oxframe_text/
lib.rs

1//! Text for oxframe: layout with `parley`, glyph outlines with `skrifa`.
2//!
3//! > **Status:** oxframe is under very active development. The API is not stable yet and
4//! > may change from version to version. Pin the exact version in your Cargo.toml and check
5//! > the [changelog](https://github.com/oxygenframe/oxframe-sdk/blob/main/CHANGELOG.md)
6//! > before upgrading.
7//!
8//! Text becomes a [`BezPath`], so it renders identically on every backend
9//! and can be morphed and trimmed like any other path.
10//!
11//! Determinism: only embedded fonts are used — Inter and JetBrains Mono
12//! (SIL OFL 1.1, see `fonts/`) plus fonts registered with
13//! [`register_font`]. System fonts are never consulted.
14
15#![warn(missing_docs)]
16
17mod code;
18mod diff;
19
20pub use code::{Lang, Token, highlight};
21pub use diff::{
22    CodeDiff, EditError, LineEdit, Loc, Piece, PieceEdit, code_lines, diff_code, insert_at,
23    line_pieces, map_focus, remove_range, replace_range,
24};
25
26use std::cell::RefCell;
27use std::hash::{Hash, Hasher};
28use std::rc::Rc;
29
30use kurbo::{Affine, BezPath, Rect};
31use parley::fontique::{Blob, FontInfoOverride};
32use parley::{
33    Alignment, AlignmentOptions, FontContext, FontFamily, FontWeight, Layout, LayoutContext,
34    LineHeight, PositionedLayoutItem, StyleProperty,
35};
36use skrifa::instance::{LocationRef, Size};
37use skrifa::outline::{DrawSettings, OutlinePen};
38use skrifa::{FontRef, GlyphId, MetadataProvider};
39
40const INTER: &[u8] = include_bytes!("../fonts/Inter.ttf");
41const JETBRAINS_MONO: &[u8] = include_bytes!("../fonts/JetBrainsMono.ttf");
42
43/// Built-in sans-serif family (Inter).
44pub const SANS: &str = "Inter";
45/// Built-in monospace family (JetBrains Mono).
46pub const MONO: &str = "JetBrains Mono";
47
48/// Horizontal alignment of lines.
49#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
50pub enum Align {
51    #[default]
52    /// Left.
53    Start,
54    /// Centered.
55    Center,
56    /// Right.
57    End,
58}
59
60/// How text is laid out.
61#[derive(Debug, Clone, PartialEq)]
62pub struct TextStyle {
63    /// Font family name: [`SANS`], [`MONO`] or a registered family.
64    pub family: String,
65    /// Font size in pixels.
66    pub size: f64,
67    /// 100..=900.
68    pub weight: f64,
69    /// Italic style.
70    pub italic: bool,
71    /// Multiple of the font size.
72    pub line_height: f64,
73    /// Extra space between letters, in pixels.
74    pub letter_spacing: f64,
75    /// Alignment of lines.
76    pub align: Align,
77    /// Wrap width; `None` means no wrapping.
78    pub max_width: Option<f64>,
79}
80
81impl Default for TextStyle {
82    fn default() -> Self {
83        Self {
84            family: SANS.to_owned(),
85            size: 48.0,
86            weight: 400.0,
87            italic: false,
88            line_height: 1.2,
89            letter_spacing: 0.0,
90            align: Align::Start,
91            max_width: None,
92        }
93    }
94}
95
96impl Hash for TextStyle {
97    fn hash<H: Hasher>(&self, h: &mut H) {
98        self.family.hash(h);
99        for v in [
100            self.size,
101            self.weight,
102            self.line_height,
103            self.letter_spacing,
104        ] {
105            v.to_bits().hash(h);
106        }
107        self.italic.hash(h);
108        self.align.hash(h);
109        self.max_width.map(f64::to_bits).hash(h);
110    }
111}
112
113/// A run of text with its own style; unset fields inherit the base style.
114#[derive(Debug, Clone, PartialEq, Default)]
115pub struct TextSpan {
116    /// The text.
117    pub text: String,
118    /// Font family.
119    pub family: Option<String>,
120    /// Font size in pixels.
121    pub size: Option<f64>,
122    /// Weight, 100..=900.
123    pub weight: Option<f64>,
124    /// Italic style.
125    pub italic: Option<bool>,
126}
127
128impl Hash for TextSpan {
129    fn hash<H: Hasher>(&self, h: &mut H) {
130        self.text.hash(h);
131        self.family.hash(h);
132        self.size.map(f64::to_bits).hash(h);
133        self.weight.map(f64::to_bits).hash(h);
134        self.italic.hash(h);
135    }
136}
137
138/// Where a glyph came from.
139#[derive(Debug, Clone, Copy, PartialEq)]
140pub struct GlyphInfo {
141    /// Index of the span (0 for plain text).
142    pub span: u16,
143    /// First character of the glyph's cluster.
144    pub ch: char,
145    /// Pen position of the glyph (baseline origin).
146    pub origin: kurbo::Point,
147}
148
149/// Laid-out text. Coordinates: origin at the top-left of the layout box,
150/// y pointing down.
151#[derive(Debug, Clone)]
152pub struct TextLayout {
153    /// All glyph outlines.
154    pub path: BezPath,
155    /// One path per glyph, in visual order — for per-letter animation.
156    pub glyphs: Vec<BezPath>,
157    /// Parallel to `glyphs`.
158    pub info: Vec<GlyphInfo>,
159    /// Width of the layout box.
160    pub width: f64,
161    /// Height of the layout box.
162    pub height: f64,
163}
164
165impl TextLayout {
166    /// The layout box as a rectangle.
167    pub fn bounds(&self) -> Rect {
168        Rect::new(0.0, 0.0, self.width, self.height)
169    }
170}
171
172struct Fonts {
173    font_cx: FontContext,
174    layout_cx: LayoutContext<u16>,
175    cache: Vec<(u64, Rc<TextLayout>)>,
176}
177
178const CACHE_SIZE: usize = 256;
179
180thread_local! {
181    static FONTS: RefCell<Fonts> = RefCell::new(Fonts::new());
182}
183
184impl Fonts {
185    fn new() -> Self {
186        let mut font_cx = FontContext::new();
187        for data in [INTER, JETBRAINS_MONO] {
188            font_cx
189                .collection
190                .register_fonts(Blob::new(std::sync::Arc::new(data)), None);
191        }
192        Self {
193            font_cx,
194            layout_cx: LayoutContext::new(),
195            cache: Vec::new(),
196        }
197    }
198}
199
200/// Registers a font (TTF/OTF/TTC bytes, e.g. from `include_bytes!`).
201/// Returns the family names it provides.
202pub fn register_font(data: &'static [u8]) -> Vec<String> {
203    FONTS.with(|f| {
204        let mut f = f.borrow_mut();
205        f.cache.clear();
206        let collection = &mut f.font_cx.collection;
207        let families = collection.register_fonts(
208            Blob::new(std::sync::Arc::new(data)),
209            None::<FontInfoOverride<'_>>,
210        );
211        families
212            .into_iter()
213            .filter_map(|(id, _)| collection.family_name(id).map(str::to_owned))
214            .collect()
215    })
216}
217
218/// Lays out `text` (cached by text and style).
219pub fn layout(text: &str, style: &TextStyle) -> Rc<TextLayout> {
220    layout_rich(
221        &[TextSpan {
222            text: text.to_owned(),
223            ..Default::default()
224        }],
225        style,
226    )
227}
228
229/// Lays out styled spans as one paragraph (cached).
230pub fn layout_rich(spans: &[TextSpan], style: &TextStyle) -> Rc<TextLayout> {
231    let mut h = std::hash::DefaultHasher::new();
232    spans.hash(&mut h);
233    style.hash(&mut h);
234    let key = h.finish();
235    FONTS.with(|f| {
236        let mut f = f.borrow_mut();
237        if let Some(pos) = f.cache.iter().position(|(k, _)| *k == key) {
238            let entry = f.cache.remove(pos);
239            let value = entry.1.clone();
240            f.cache.push(entry);
241            return value;
242        }
243        let value = Rc::new(build(&mut f, spans, style));
244        if f.cache.len() >= CACHE_SIZE {
245            f.cache.remove(0);
246        }
247        f.cache.push((key, value.clone()));
248        value
249    })
250}
251
252fn build(f: &mut Fonts, spans: &[TextSpan], style: &TextStyle) -> TextLayout {
253    let Fonts {
254        font_cx, layout_cx, ..
255    } = f;
256    let text: String = spans.iter().map(|s| s.text.as_str()).collect();
257    let text = text.as_str();
258    let mut b = layout_cx.ranged_builder(font_cx, text, 1.0, true);
259    b.push_default(StyleProperty::FontFamily(FontFamily::named(&style.family)));
260    b.push_default(StyleProperty::FontSize(style.size as f32));
261    b.push_default(StyleProperty::FontWeight(FontWeight::new(
262        style.weight as f32,
263    )));
264    if style.italic {
265        b.push_default(StyleProperty::FontStyle(parley::FontStyle::Italic));
266    }
267    b.push_default(StyleProperty::LineHeight(LineHeight::FontSizeRelative(
268        style.line_height as f32,
269    )));
270    b.push_default(StyleProperty::LetterSpacing(style.letter_spacing as f32));
271    b.push_default(StyleProperty::Brush(0u16));
272    let mut at = 0;
273    for (i, span) in spans.iter().enumerate() {
274        let r = at..at + span.text.len();
275        at = r.end;
276        if r.is_empty() {
277            continue;
278        }
279        b.push(StyleProperty::Brush(i as u16), r.clone());
280        if let Some(f) = &span.family {
281            b.push(StyleProperty::FontFamily(FontFamily::named(f)), r.clone());
282        }
283        if let Some(sz) = span.size {
284            b.push(StyleProperty::FontSize(sz as f32), r.clone());
285        }
286        if let Some(w) = span.weight {
287            b.push(
288                StyleProperty::FontWeight(FontWeight::new(w as f32)),
289                r.clone(),
290            );
291        }
292        if let Some(it) = span.italic {
293            let st = if it {
294                parley::FontStyle::Italic
295            } else {
296                parley::FontStyle::Normal
297            };
298            b.push(StyleProperty::FontStyle(st), r.clone());
299        }
300    }
301    let mut layout: Layout<u16> = b.build(text);
302    layout.break_all_lines(style.max_width.map(|w| w as f32));
303    let align = match style.align {
304        Align::Start => Alignment::Start,
305        Align::Center => Alignment::Center,
306        Align::End => Alignment::End,
307    };
308    layout.align(align, AlignmentOptions::default());
309
310    let mut path = BezPath::new();
311    let mut glyphs = Vec::new();
312    let mut info = Vec::new();
313    for line in layout.lines() {
314        for item in line.items() {
315            let PositionedLayoutItem::GlyphRun(run) = item else {
316                continue;
317            };
318            let r = run.run();
319            let span = run.style().brush;
320            // The source character of every glyph, in visual order.
321            let chars: Vec<char> = r
322                .visual_clusters()
323                .flat_map(|c| {
324                    let ch = text[c.text_range()].chars().next().unwrap_or('\0');
325                    std::iter::repeat_n(ch, c.glyphs().count())
326                })
327                .collect();
328            let font = r.font();
329            let Ok(font_ref) = FontRef::from_index(font.data.as_ref(), font.index) else {
330                continue;
331            };
332            let outlines = font_ref.outline_glyphs();
333            let coords = r.normalized_coords();
334            let size = Size::new(r.font_size());
335            let coords: Vec<skrifa::instance::NormalizedCoord> = coords
336                .iter()
337                .map(|c| skrifa::raw::types::F2Dot14::from_bits(c.to_bits()))
338                .collect();
339            let location = LocationRef::new(&coords);
340            // Synthetic italic when the family has no italic face.
341            let skew = r
342                .synthesis()
343                .skew()
344                .map_or(0.0, |deg| f64::from(deg).to_radians().tan());
345            for (gi, g) in run.positioned_glyphs().enumerate() {
346                let Some(outline) = outlines.get(GlyphId::new(g.id)) else {
347                    continue;
348                };
349                let mut pen = Pen(BezPath::new());
350                if outline
351                    .draw(DrawSettings::unhinted(size, location), &mut pen)
352                    .is_err()
353                {
354                    continue;
355                }
356                // Font units are y-up; flip and move to the pen position.
357                let tf = Affine::translate((f64::from(g.x), f64::from(g.y)))
358                    * Affine::scale_non_uniform(1.0, -1.0)
359                    * Affine::skew(skew, 0.0);
360                let glyph = tf * pen.0;
361                if !glyph.elements().is_empty() {
362                    path.extend(glyph.elements().iter().copied());
363                    glyphs.push(glyph);
364                    info.push(GlyphInfo {
365                        span,
366                        ch: chars.get(gi).copied().unwrap_or('\0'),
367                        origin: kurbo::Point::new(f64::from(g.x), f64::from(g.y)),
368                    });
369                }
370            }
371        }
372    }
373    TextLayout {
374        path,
375        glyphs,
376        info,
377        width: f64::from(layout.width()),
378        height: f64::from(layout.height()),
379    }
380}
381
382struct Pen(BezPath);
383
384impl OutlinePen for Pen {
385    fn move_to(&mut self, x: f32, y: f32) {
386        self.0.move_to((f64::from(x), f64::from(y)));
387    }
388    fn line_to(&mut self, x: f32, y: f32) {
389        self.0.line_to((f64::from(x), f64::from(y)));
390    }
391    fn quad_to(&mut self, cx0: f32, cy0: f32, x: f32, y: f32) {
392        self.0.quad_to(
393            (f64::from(cx0), f64::from(cy0)),
394            (f64::from(x), f64::from(y)),
395        );
396    }
397    fn curve_to(&mut self, cx0: f32, cy0: f32, cx1: f32, cy1: f32, x: f32, y: f32) {
398        self.0.curve_to(
399            (f64::from(cx0), f64::from(cy0)),
400            (f64::from(cx1), f64::from(cy1)),
401            (f64::from(x), f64::from(y)),
402        );
403    }
404    fn close(&mut self) {
405        self.0.close_path();
406    }
407}
408
409#[cfg(test)]
410mod tests {
411    use kurbo::Shape;
412
413    use super::*;
414
415    #[test]
416    fn lays_out_text_with_embedded_font() {
417        let l = layout("Hello", &TextStyle::default());
418        assert_eq!(l.glyphs.len(), 5);
419        assert!(l.width > 100.0 && l.width < 160.0, "width {}", l.width);
420        let bb = l.path.bounding_box();
421        assert!(bb.y0 >= 0.0 && bb.y1 <= l.height, "{bb:?} h={}", l.height);
422    }
423
424    #[test]
425    fn mono_and_weight_change_shapes() {
426        let s = TextStyle::default();
427        let regular = layout("iii", &s);
428        let mono = layout(
429            "iii",
430            &TextStyle {
431                family: MONO.into(),
432                ..s.clone()
433            },
434        );
435        let bold = layout("iii", &TextStyle { weight: 800.0, ..s });
436        assert!(mono.width > regular.width);
437        assert_ne!(bold.path, regular.path);
438    }
439
440    #[test]
441    fn wraps_and_centers() {
442        let s = TextStyle {
443            max_width: Some(120.0),
444            align: Align::Center,
445            ..Default::default()
446        };
447        let l = layout("one two three four", &s);
448        assert!(l.height > 2.0 * 48.0);
449    }
450
451    #[test]
452    fn rich_spans_carry_index_and_chars() {
453        let spans = [
454            TextSpan {
455                text: "ab ".into(),
456                ..Default::default()
457            },
458            TextSpan {
459                text: "cd".into(),
460                weight: Some(800.0),
461                ..Default::default()
462            },
463        ];
464        let l = layout_rich(&spans, &TextStyle::default());
465        let got: Vec<(u16, char)> = l.info.iter().map(|i| (i.span, i.ch)).collect();
466        assert_eq!(got, vec![(0, 'a'), (0, 'b'), (1, 'c'), (1, 'd')]);
467        assert!(l.info[1].origin.x > l.info[0].origin.x);
468    }
469
470    #[test]
471    fn cyrillic_is_supported() {
472        let l = layout("Привет", &TextStyle::default());
473        assert_eq!(l.glyphs.len(), 6);
474    }
475}
oxframe_text/lib.rs

oxframe_text/
lib.rs
