lurq 0.65.1

A Rust UI toolkit with typed components, retained state, reactive signals, GPU rendering, and DevTools.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
use std::sync::Arc;

use crate::{
  layout::Alignment,
  node::{TextColor, color::Color},
};

mod font_features;
mod generic_family;
pub use font_features::{FontFeature, FontFeatures};
pub use generic_family::GenericFamily;
pub(crate) use generic_family::{alias_name, cosmic_family};

const DEFAULT_FONT_SIZE: f32 = 16.0;
const DEFAULT_LINE_HEIGHT: f32 = 1.2;
/// The color of `TextStyle::default()`. A typography style that keeps it names no color: its text is drawn in
/// the theme's foreground (`ThemePalette::foreground`).
pub(crate) const DEFAULT_TEXT_COLOR: Color = Color::new(0, 0, 0, 255);
#[cfg(target_os = "windows")]
const DEFAULT_FONT_FAMILY_WINDOWS: &str = "Segoe UI";
#[cfg(not(target_os = "windows"))]
const DEFAULT_FONT_FAMILY_FALLBACK: &str = "";

#[derive(Clone, PartialEq)]
pub struct TextStyle {
  /// The font family: a family name, an alias registered with
  /// `App::register_font` (resolved first), or a CSS generic family
  /// (`"serif"`, `"sans-serif"`, `"monospace"`, `"cursive"`, `"fantasy"`, in
  /// any ASCII case), drawn with the platform's font for it. See
  /// [`GenericFamily`] for the fonts each platform uses and for drawing one in
  /// a bundled font.
  pub font_family: Arc<str>,
  pub font_size: f32,
  pub line_height: f32,
  pub weight: FontWeight,
  pub style: FontStyle,
  pub text_align: TextAlign,
  /// Vertical placement of the glyph run within its box (the line-height box
  /// for a single line, or the node's box when it is taller). Alignment is
  /// based on the actual glyph ink bounds so text is optically centered rather
  /// than metric-centered (which leaves most fonts sitting visibly high).
  pub vertical_align: VerticalAlign,
  /// CSS `text-box-trim`-style leading trim. When set, `line_height` only adds
  /// leading BETWEEN wrapped lines: the measured box of a single line collapses
  /// to the em box (`font_size`) instead of `font_size * line_height`, and a
  /// multi-line run's box drops the half-leading above the first line and below
  /// the last. Glyph placement is unaffected — the render path already centers
  /// the optical box within the (now trimmed) box — so a single line looks
  /// identical to `line_height: 1.0` while wrapped lines keep their full leading.
  /// Lets a caller pick one readable `line_height` for both single- and
  /// multi-line text without inflating single-line vertical rhythm.
  pub trim_line_box: bool,
  /// Extra space added after every glyph, in logical pixels, like CSS
  /// `letter-spacing` (including after the last glyph of a line). Negative values
  /// tighten text. It scales with the display scale factor like `font_size`, and
  /// measurement, wrapping, painting, carets and hit testing all use the spaced
  /// advances. Non-finite values are treated as `0.0`.
  pub letter_spacing: f32,
  /// How far a span of a rich text is drawn above the line's baseline, in logical pixels, like CSS
  /// `vertical-align: <length>`: a footnote's number, a superscript. Negative draws it below. Only where its glyphs
  /// are drawn moves: the line's height, the wrapping, the carets and what a selection covers stay those of the
  /// baseline. `0.0` by default; a plain text and a text input do not shift.
  pub baseline_shift: f32,
  /// OpenType feature settings for shaping, like CSS `font-feature-settings`.
  /// Empty by default, which keeps the shaper's default features — including
  /// ligatures and contextual alternates. Programming ligatures can misrender
  /// commands and code (Geist Mono shapes `--` into one cell-wide glyph drawn
  /// over the preceding space, so ` --flag` reads as `--flag`); turn them off with
  /// `FontFeatures::new([FontFeature::disable(*b"liga"), FontFeature::disable(*b"calt")])`.
  pub font_features: FontFeatures,
  pub color: Color,
  pub caret_color: Option<TextColor>,
  pub shadow: Option<TextShadow>,
  /// A line under the text, like CSS `text-decoration-line: underline`.
  /// `None` by default. It is drawn under every laid-out line the text
  /// covers, wrapped lines included, and changes neither measurement nor
  /// wrapping.
  pub underline: Option<TextUnderline>,
  /// A line through the text, like CSS `text-decoration-line: line-through`.
  /// `None` by default. Drawn as the underline is, over the glyphs.
  pub strikethrough: Option<TextStrikethrough>,
  /// The case the text is drawn in, like CSS `text-transform`: as it is
  /// written (the default), in capitals, or in small letters. Only what is
  /// drawn changes: the text itself, what is copied of it, what tooling reads
  /// and where a caret stands are the text as written. A letter whose capital
  /// is more than one letter or is written in more bytes (`ß`, some ligatures)
  /// stays as it is written.
  pub case: TextCase,
}

/// The case a text is drawn in: see [`TextStyle::case`].
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
pub enum TextCase {
  /// As it is written.
  #[default]
  AsWritten,
  /// In capitals, as a small heading over a group is drawn.
  Upper,
  /// In small letters.
  Lower,
}

impl TextCase {
  /// `text` in this case. Each letter is replaced where its other case is one
  /// letter of as many bytes, so every byte offset into the text is an offset
  /// into what is drawn too.
  pub fn apply(self, text: &str) -> std::borrow::Cow<'_, str> {
    let change = |c: char| -> char {
      let mut other = match self {
        Self::AsWritten => return c,
        Self::Upper => CaseIter::Upper(c.to_uppercase()),
        Self::Lower => CaseIter::Lower(c.to_lowercase()),
      };
      match (other.next(), other.next()) {
        (Some(one), None) if one.len_utf8() == c.len_utf8() => one,
        _ => c,
      }
    };
    if self == Self::AsWritten || text.chars().all(|c| change(c) == c) {
      return std::borrow::Cow::Borrowed(text);
    }
    std::borrow::Cow::Owned(text.chars().map(change).collect())
  }
}

enum CaseIter {
  Upper(std::char::ToUppercase),
  Lower(std::char::ToLowercase),
}

impl Iterator for CaseIter {
  type Item = char;

  fn next(&mut self) -> Option<char> {
    match self {
      Self::Upper(chars) => chars.next(),
      Self::Lower(chars) => chars.next(),
    }
  }
}

impl Default for TextStyle {
  fn default() -> Self {
    Self {
      font_family: default_font_family(),
      font_size: DEFAULT_FONT_SIZE,
      line_height: DEFAULT_LINE_HEIGHT,
      weight: FontWeight::Normal,
      style: FontStyle::Normal,
      text_align: TextAlign::Left,
      vertical_align: VerticalAlign::default(),
      trim_line_box: false,
      letter_spacing: 0.0,
      baseline_shift: 0.0,
      font_features: FontFeatures::default(),
      color: DEFAULT_TEXT_COLOR,
      caret_color: None,
      shadow: None,
      underline: None,
      strikethrough: None,
      case: TextCase::AsWritten,
    }
  }
}

impl TextStyle {
  /// Scales the pixel metrics (font size and letter spacing) for shaping at
  /// `factor` device pixels per logical pixel.
  pub(crate) fn scale_pixels(&mut self, factor: f32) {
    self.font_size *= factor;
    self.letter_spacing *= factor;
    self.baseline_shift *= factor;
  }
}

/// An underline, like CSS `text-decoration: underline` with
/// `text-decoration-color`, `text-decoration-thickness` and
/// `text-underline-offset`. Each unset value follows the text: the text's
/// color, and the thickness and position the font gives its underline.
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub struct TextUnderline {
  /// The line's color; `None` is the text's color.
  pub color: Option<Color>,
  /// The line's thickness in logical pixels; `None` is the font's underline
  /// thickness. Non-finite or negative values count as unset.
  pub thickness: Option<f32>,
  /// How far below the baseline the line's top edge sits, in logical pixels;
  /// `None` is the font's underline position. Non-finite values count as
  /// unset.
  pub offset: Option<f32>,
}

impl TextUnderline {
  /// An underline in the text's color, at the font's thickness and position.
  pub fn new() -> Self {
    Self::default()
  }

  pub fn color(mut self, color: Color) -> Self {
    self.color = Some(color);
    self
  }

  pub fn thickness(mut self, thickness: f32) -> Self {
    self.thickness = Some(thickness);
    self
  }

  pub fn offset(mut self, offset: f32) -> Self {
    self.offset = Some(offset);
    self
  }
}

/// A line through the text, like CSS `text-decoration: line-through` with
/// `text-decoration-color` and `text-decoration-thickness`. Each unset value
/// follows the text: the text's color, and the thickness the font gives its
/// strikeout. The line sits where the font puts its strikeout.
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub struct TextStrikethrough {
  /// The line's color; `None` is the text's color.
  pub color: Option<Color>,
  /// The line's thickness in logical pixels; `None` is the font's strikeout
  /// thickness. Non-finite or negative values count as unset.
  pub thickness: Option<f32>,
}

impl TextStrikethrough {
  /// A line through the text in its color, at the font's thickness.
  pub fn new() -> Self {
    Self::default()
  }

  pub fn color(mut self, color: Color) -> Self {
    self.color = Some(color);
    self
  }

  pub fn thickness(mut self, thickness: f32) -> Self {
    self.thickness = Some(thickness);
    self
  }
}

/// CSS-like text shadow: offsets and blur radius are in logical pixels, the
/// blur radius maps to a Gaussian with `sigma = blur_radius / 2`.
#[derive(Clone, Copy, PartialEq)]
pub struct TextShadow {
  pub offset_x: f32,
  pub offset_y: f32,
  pub blur_radius: f32,
  pub color: Color,
}

impl TextShadow {
  pub fn new(offset_x: f32, offset_y: f32, blur_radius: f32, color: Color) -> Self {
    Self {
      offset_x,
      offset_y,
      blur_radius: blur_radius.max(0.0),
      color,
    }
  }

  pub(crate) fn is_visible(&self) -> bool {
    self.color.a() > 0 && (self.offset_x != 0.0 || self.offset_y != 0.0 || self.blur_radius > 0.0)
  }
}

fn default_font_family() -> Arc<str> {
  #[cfg(target_os = "windows")]
  {
    Arc::from(DEFAULT_FONT_FAMILY_WINDOWS)
  }
  #[cfg(not(target_os = "windows"))]
  {
    Arc::from(DEFAULT_FONT_FAMILY_FALLBACK)
  }
}

/// CSS font weight. The named variants carry the CSS keyword values (`Thin` =
/// 100 … `Black` = 900); `Numeric` accepts any other weight and is clamped to
/// CSS's `1..=1000` range. Weights compare, hash and cache by numeric value, so
/// `FontWeight::Numeric(600) == FontWeight::SemiBold`.
///
/// Text is drawn with the loaded face of the requested family chosen by CSS
/// font matching (as implemented by fontdb): an exact weight first; for a
/// request of 400–449, then 500; for 450–500, then 400; otherwise the nearest
/// lighter face for requests up to 500 and the nearest heavier face above 500,
/// then the nearest face on the other side. Faces are never synthesized, so
/// `SemiBold` renders with the Bold face when the family has no 600 face.
#[derive(Clone, Copy, Debug, Default)]
pub enum FontWeight {
  Thin,
  ExtraLight,
  Light,
  #[default]
  Normal,
  Medium,
  SemiBold,
  Bold,
  ExtraBold,
  Black,
  Numeric(u16),
}

impl FontWeight {
  pub const MIN_VALUE: u16 = 1;
  pub const MAX_VALUE: u16 = 1000;

  /// The CSS numeric weight, clamped to `1..=1000`.
  pub const fn value(self) -> u16 {
    match self {
      Self::Thin => 100,
      Self::ExtraLight => 200,
      Self::Light => 300,
      Self::Normal => 400,
      Self::Medium => 500,
      Self::SemiBold => 600,
      Self::Bold => 700,
      Self::ExtraBold => 800,
      Self::Black => 900,
      Self::Numeric(value) => {
        if value < Self::MIN_VALUE {
          Self::MIN_VALUE
        } else if value > Self::MAX_VALUE {
          Self::MAX_VALUE
        } else {
          value
        }
      }
    }
  }

  /// The requested weight. Layout passes the weight of the nearest loaded face
  /// instead, because cosmic-text only selects faces of exactly this weight.
  pub fn to_cosmic(&self) -> cosmic_text::Weight {
    cosmic_text::Weight(self.value())
  }
}

impl PartialEq for FontWeight {
  fn eq(&self, other: &Self) -> bool {
    self.value() == other.value()
  }
}

impl Eq for FontWeight {}

impl std::hash::Hash for FontWeight {
  fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
    self.value().hash(state);
  }
}

impl From<u16> for FontWeight {
  fn from(value: u16) -> Self {
    Self::Numeric(value)
  }
}

#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
pub enum FontStyle {
  #[default]
  Normal,
  Italic,
}

impl FontStyle {
  pub fn to_cosmic(&self) -> cosmic_text::Style {
    match self {
      Self::Normal => cosmic_text::Style::Normal,
      Self::Italic => cosmic_text::Style::Italic,
    }
  }
}

#[derive(Clone, Copy, Default, PartialEq, Eq)]
pub enum TextAlign {
  #[default]
  Left,
  Center,
  Right,
  Justified,
  End,
}

impl TextAlign {
  pub(crate) fn to_cosmic(self) -> cosmic_text::Align {
    match self {
      Self::Left => cosmic_text::Align::Left,
      Self::Center => cosmic_text::Align::Center,
      Self::Right => cosmic_text::Align::Right,
      Self::Justified => cosmic_text::Align::Justified,
      Self::End => cosmic_text::Align::End,
    }
  }
}

/// Vertical alignment of a text run's glyph ink within its box, mirroring
/// browser `vertical-align` semantics against the line-height box:
/// - `Top`: the top of the glyph ink meets the top of the box.
/// - `Bottom`: the bottom of the glyph ink meets the bottom of the box.
/// - `Center`: the ink is centered — `offset = (box_height - ink_height) / 2`.
/// - `LineBox`: no ink at all: the first line box starts at the top of the box, and each line's glyphs sit on the
///   baseline the font's ascent, descent and the line height give it, like CSS text. The run keeps its position when
///   its glyphs change, and carets and selections line up with it. Text inputs place their lines this way.
#[derive(Clone, Copy, Default, PartialEq, Eq)]
pub enum VerticalAlign {
  Top,
  #[default]
  Center,
  Bottom,
  LineBox,
}

impl From<Alignment> for TextAlign {
  fn from(alignment: Alignment) -> Self {
    match alignment {
      Alignment::Start | Alignment::Stretch => Self::Left,
      Alignment::Center => Self::Center,
      Alignment::End => Self::Right,
    }
  }
}