Skip to main content

text_typeset/shaping/
shaper.rs

1use harfrust::{Buffer, Direction, Feature, ShapeOptions, ShaperFont, Tag};
2
3use crate::font::registry::FontRegistry;
4use crate::font::resolve::ResolvedFont;
5use crate::shaping::run::{ShapedGlyph, ShapedRun};
6use crate::types::FontFeature;
7
8/// Convert public [`FontFeature`] toggles into harfrust [`Feature`]s,
9/// applied across the whole shaped string (global range). Script-mandated
10/// features apply regardless; these are the discretionary toggles.
11pub fn to_harfrust_features(features: &[FontFeature]) -> Vec<Feature> {
12    features
13        .iter()
14        .map(|f| Feature::new(Tag::new(&f.tag), f.value, ..))
15        .collect()
16}
17
18/// Read units-per-em for a font face.
19///
20/// `harfrust::FontRef` is a thin wrapper over read-fonts and exposes
21/// the `head` table only through the `read_fonts::TableProvider` trait,
22/// which harfrust doesn't re-export. Since we already depend on swash
23/// for `font_metrics_px` further down, we reuse swash's `Metrics` to
24/// pull UPEM — one less dependency surface to maintain.
25fn units_per_em(bytes: &[u8], face_index: u32) -> Option<u16> {
26    let font_ref = swash::FontRef::from_index(bytes, face_index as usize)?;
27    let upem = font_ref.metrics(&[]).units_per_em;
28    if upem == 0 { None } else { Some(upem) }
29}
30
31/// Text direction for shaping.
32#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
33pub enum TextDirection {
34    /// Auto-detect from text content (default).
35    #[default]
36    Auto,
37    LeftToRight,
38    RightToLeft,
39}
40
41/// Shape a text string with the given resolved font.
42///
43/// Returns a ShapedRun with glyph IDs and pixel-space positions.
44/// The `text_offset` is the byte offset of this text within the block
45/// (used for cluster mapping back to document positions).
46/// Shape a text string with automatic glyph fallback.
47///
48/// After shaping with the primary font, any .notdef glyphs (glyph_id==0)
49/// are detected and re-shaped with fallback fonts. If no fallback font
50/// covers a character, it remains as .notdef (renders as blank space
51/// with correct advance).
52pub fn shape_text(
53    registry: &FontRegistry,
54    resolved: &ResolvedFont,
55    text: &str,
56    text_offset: usize,
57) -> Option<ShapedRun> {
58    shape_text_with_fallback(
59        registry,
60        resolved,
61        text,
62        text_offset,
63        TextDirection::Auto,
64        &[],
65    )
66}
67
68/// Shape text with an explicit direction and glyph fallback.
69///
70/// Like `shape_text`, but caller supplies the direction instead of letting
71/// rustybuzz guess. Used by the bidi-aware layout path, which splits text
72/// into directional runs before shaping.
73pub fn shape_text_with_fallback(
74    registry: &FontRegistry,
75    resolved: &ResolvedFont,
76    text: &str,
77    text_offset: usize,
78    direction: TextDirection,
79    features: &[Feature],
80) -> Option<ShapedRun> {
81    let mut run = shape_text_directed(registry, resolved, text, text_offset, direction, features)?;
82
83    // Check for .notdef glyphs and attempt fallback
84    if run.glyphs.iter().any(|g| g.glyph_id == 0) && !text.is_empty() {
85        apply_glyph_fallback(registry, resolved, text, text_offset, features, &mut run);
86    }
87
88    Some(run)
89}
90
91/// Re-shape .notdef glyphs using fallback fonts.
92///
93/// Works on **spans** of consecutive .notdef glyphs, not on glyphs one at a
94/// time: each span is mapped back to the character range that produced it and
95/// that whole range is re-shaped in the fallback font, then spliced in.
96///
97/// Shaping a span as a unit is what makes complex scripts survive fallback.
98/// Re-shaping character by character — which this used to do — cannot join
99/// Arabic, because a letter shaped alone has no neighbours and can only take
100/// its isolated form. It also kept only the *first* glyph of each result, so
101/// any letter whose isolated form is a base plus a mark lost the mark. An
102/// Arabic word set in a font without Arabic came out as disconnected,
103/// dotless stumps.
104///
105/// A span is re-shaped with the run's own direction rather than `Auto`, so
106/// the substituted glyphs come back in the same visual order as the ones
107/// around them.
108fn apply_glyph_fallback(
109    registry: &FontRegistry,
110    primary: &ResolvedFont,
111    text: &str,
112    text_offset: usize,
113    features: &[Feature],
114    run: &mut ShapedRun,
115) {
116    use crate::font::resolve::find_fallback_font;
117
118    // Maximal spans of consecutive .notdef glyphs, as index ranges.
119    let mut spans: Vec<std::ops::Range<usize>> = Vec::new();
120    let mut i = 0;
121    while i < run.glyphs.len() {
122        if run.glyphs[i].glyph_id == 0 {
123            let start = i;
124            while i < run.glyphs.len() && run.glyphs[i].glyph_id == 0 {
125                i += 1;
126            }
127            spans.push(start..i);
128        } else {
129            i += 1;
130        }
131    }
132    if spans.is_empty() {
133        return;
134    }
135
136    // Splice from the back so earlier ranges stay valid as lengths change.
137    for span in spans.into_iter().rev() {
138        let Some((byte_start, byte_end)) = notdef_char_range(&run.glyphs, &span, text) else {
139            continue;
140        };
141        let Some(slice) = text.get(byte_start..byte_end) else {
142            continue;
143        };
144        let Some(first_char) = slice.chars().next() else {
145            continue;
146        };
147
148        let Some(fallback_id) = find_fallback_font(registry, first_char, primary.font_face_id)
149        else {
150            continue; // no fallback available — leave the span as .notdef
151        };
152        let Some(fallback_entry) = registry.get(fallback_id) else {
153            continue;
154        };
155
156        let fallback_resolved = ResolvedFont {
157            font_face_id: fallback_id,
158            size_px: primary.size_px,
159            face_index: fallback_entry.face_index,
160            swash_cache_key: fallback_entry.swash_cache_key,
161            scale_factor: primary.scale_factor,
162            weight: primary.weight,
163        };
164
165        let Some(fallback_run) = shape_text_directed(
166            registry,
167            &fallback_resolved,
168            slice,
169            text_offset + byte_start,
170            run.direction,
171            features,
172        ) else {
173            continue;
174        };
175        if fallback_run.glyphs.is_empty() {
176            continue;
177        }
178
179        // Clusters come back local to `slice`; lift them into `text` space,
180        // which is what the rest of the pipeline expects of this run.
181        let replacement: Vec<ShapedGlyph> = fallback_run
182            .glyphs
183            .into_iter()
184            .map(|mut g| {
185                g.cluster += byte_start as u32;
186                g.font_face_id = fallback_id;
187                g
188            })
189            .collect();
190
191        run.glyphs.splice(span, replacement);
192    }
193
194    run.advance_width = run.glyphs.iter().map(|g| g.x_advance).sum();
195}
196
197/// The byte range of `text` that a span of consecutive .notdef glyphs covers.
198///
199/// Glyphs sit in visual order, so clusters ascend across an LTR run and
200/// descend across an RTL one. Taking the min and max over the span rather
201/// than its first and last glyph keeps this direction-agnostic.
202///
203/// The span's end is the nearest cluster *after* it among the glyphs outside
204/// it — the start of whatever the primary font did manage to shape — or the
205/// end of the text when the span runs to the edge.
206fn notdef_char_range(
207    glyphs: &[ShapedGlyph],
208    span: &std::ops::Range<usize>,
209    text: &str,
210) -> Option<(usize, usize)> {
211    let inside = glyphs.get(span.clone())?;
212    let start = inside.iter().map(|g| g.cluster as usize).min()?;
213    let last = inside.iter().map(|g| g.cluster as usize).max()?;
214
215    let end = glyphs
216        .iter()
217        .enumerate()
218        .filter(|(i, _)| !span.contains(i))
219        .map(|(_, g)| g.cluster as usize)
220        .filter(|&c| c > last)
221        .min()
222        .unwrap_or(text.len());
223
224    if start >= end || !text.is_char_boundary(start) || !text.is_char_boundary(end) {
225        return None;
226    }
227    Some((start, end))
228}
229
230/// Shape text with an explicit direction.
231pub fn shape_text_directed(
232    registry: &FontRegistry,
233    resolved: &ResolvedFont,
234    text: &str,
235    text_offset: usize,
236    direction: TextDirection,
237    features: &[Feature],
238) -> Option<ShapedRun> {
239    let entry = registry.get(resolved.font_face_id)?;
240    let font = entry.shaping_font()?;
241
242    let upem = units_per_em(entry.bytes(), entry.face_index).unwrap_or(0) as f32;
243    if upem == 0.0 {
244        return None;
245    }
246    // Shape at physical ppem, then divide results by scale_factor so
247    // downstream layout stays in logical pixels. See ResolvedFont.
248    let sf = resolved.scale_factor.max(f32::MIN_POSITIVE);
249    let physical_size = resolved.size_px * sf;
250    let physical_scale = physical_size / upem;
251    let inv_sf = 1.0 / sf;
252
253    let mut buffer = Buffer::new();
254    buffer.push_str(text);
255    match direction {
256        TextDirection::LeftToRight => buffer.set_direction(Direction::LeftToRight),
257        TextDirection::RightToLeft => buffer.set_direction(Direction::RightToLeft),
258        TextDirection::Auto => {}
259    }
260    // Always guess, including after an explicit set_direction. The guess
261    // only fills in what is still unset — it assigns `script` when it is
262    // `None` and `direction` when it is `Invalid` — so the caller's
263    // direction survives untouched and the script gets populated.
264    //
265    // That script is what picks the shaper: with `script: None` harfrust
266    // falls back to DEFAULT_SHAPER, which never requests init/medi/fina/
267    // isol, and Arabic comes out in disconnected isolated forms. Setting
268    // it selects ARABIC_SHAPER and the letters join. It also keeps
269    // harfrust from panicking on a still-Invalid direction in the Auto
270    // case, which is why this call used to live in that branch alone.
271    buffer.guess_segment_properties();
272
273    // Resolve the concrete direction (Auto is now decided by the buffer).
274    // Stored on the run so hit-testing knows RTL glyph order.
275    let resolved_direction = if buffer.direction() == Direction::RightToLeft {
276        TextDirection::RightToLeft
277    } else {
278        TextDirection::LeftToRight
279    };
280
281    // The font is opened once per face and cached on the FontEntry, and
282    // it keeps its preprocessed tables, so repeated shape calls (every
283    // relayout/keystroke) reuse them; the ShaperFont over it is cheap.
284    harfrust::shape(
285        &ShaperFont::new(font),
286        &mut buffer,
287        ShapeOptions::new().features(features),
288    )
289    .ok()?;
290
291    let infos = buffer.glyph_infos();
292    let positions = buffer.glyph_positions();
293
294    let mut glyphs = Vec::with_capacity(infos.len());
295    let mut total_advance = 0.0f32;
296
297    for (info, pos) in infos.iter().zip(positions.iter()) {
298        let x_advance = pos.x_advance as f32 * physical_scale * inv_sf;
299        let y_advance = pos.y_advance as f32 * physical_scale * inv_sf;
300        let x_offset = pos.x_offset as f32 * physical_scale * inv_sf;
301        let y_offset = pos.y_offset as f32 * physical_scale * inv_sf;
302
303        glyphs.push(ShapedGlyph {
304            glyph_id: info.glyph_id as u16,
305            cluster: info.cluster,
306            x_advance,
307            y_advance,
308            x_offset,
309            y_offset,
310            font_face_id: resolved.font_face_id,
311        });
312
313        total_advance += x_advance;
314    }
315
316    Some(ShapedRun {
317        font_face_id: resolved.font_face_id,
318        size_px: resolved.size_px,
319        weight: resolved.weight,
320        glyphs,
321        advance_width: total_advance,
322        text_range: text_offset..text_offset + text.len(),
323        direction: resolved_direction,
324        bidi_level: if resolved_direction == TextDirection::RightToLeft {
325            1
326        } else {
327            0
328        },
329        underline_style: crate::types::UnderlineStyle::None,
330        overline: false,
331        strikeout: false,
332        is_link: false,
333        foreground_color: None,
334        underline_color: None,
335        background_color: None,
336        anchor_href: None,
337        tooltip: None,
338        vertical_alignment: crate::types::VerticalAlignment::Normal,
339        image_name: None,
340        image_height: 0.0,
341    })
342}
343
344/// Shape a text string, reusing a harfrust `Buffer` to avoid allocations.
345pub fn shape_text_with_buffer(
346    registry: &FontRegistry,
347    resolved: &ResolvedFont,
348    text: &str,
349    text_offset: usize,
350    buffer: Buffer,
351    features: &[Feature],
352) -> Option<(ShapedRun, Buffer)> {
353    let entry = registry.get(resolved.font_face_id)?;
354    let font = entry.shaping_font()?;
355
356    let upem = units_per_em(entry.bytes(), entry.face_index).unwrap_or(0) as f32;
357    if upem == 0.0 {
358        return None;
359    }
360    let sf = resolved.scale_factor.max(f32::MIN_POSITIVE);
361    let physical_size = resolved.size_px * sf;
362    let physical_scale = physical_size / upem;
363    let inv_sf = 1.0 / sf;
364
365    let mut buffer = buffer;
366    buffer.push_str(text);
367    // Recycled buffers come back without segment properties; explicitly
368    // guess them so harfrust doesn't panic on Direction::Invalid.
369    buffer.guess_segment_properties();
370
371    let resolved_direction = if buffer.direction() == Direction::RightToLeft {
372        TextDirection::RightToLeft
373    } else {
374        TextDirection::LeftToRight
375    };
376
377    harfrust::shape(
378        &ShaperFont::new(font),
379        &mut buffer,
380        ShapeOptions::new().features(features),
381    )
382    .ok()?;
383
384    let infos = buffer.glyph_infos();
385    let positions = buffer.glyph_positions();
386
387    let mut glyphs = Vec::with_capacity(infos.len());
388    let mut total_advance = 0.0f32;
389
390    for (info, pos) in infos.iter().zip(positions.iter()) {
391        let x_advance = pos.x_advance as f32 * physical_scale * inv_sf;
392        let y_advance = pos.y_advance as f32 * physical_scale * inv_sf;
393        let x_offset = pos.x_offset as f32 * physical_scale * inv_sf;
394        let y_offset = pos.y_offset as f32 * physical_scale * inv_sf;
395
396        glyphs.push(ShapedGlyph {
397            glyph_id: info.glyph_id as u16,
398            cluster: info.cluster,
399            x_advance,
400            y_advance,
401            x_offset,
402            y_offset,
403            font_face_id: resolved.font_face_id,
404        });
405
406        total_advance += x_advance;
407    }
408
409    let run = ShapedRun {
410        font_face_id: resolved.font_face_id,
411        size_px: resolved.size_px,
412        weight: resolved.weight,
413        glyphs,
414        advance_width: total_advance,
415        text_range: text_offset..text_offset + text.len(),
416        direction: resolved_direction,
417        bidi_level: if resolved_direction == TextDirection::RightToLeft {
418            1
419        } else {
420            0
421        },
422        underline_style: crate::types::UnderlineStyle::None,
423        overline: false,
424        strikeout: false,
425        is_link: false,
426        foreground_color: None,
427        underline_color: None,
428        background_color: None,
429        anchor_href: None,
430        tooltip: None,
431        vertical_alignment: crate::types::VerticalAlignment::Normal,
432        image_name: None,
433        image_height: 0.0,
434    };
435
436    // Reclaim the buffer for reuse: clearing keeps the allocation and
437    // drops the contents and segment properties.
438    buffer.clear();
439    Some((run, buffer))
440}
441
442pub struct FontMetricsPx {
443    pub ascent: f32,
444    pub descent: f32,
445    pub leading: f32,
446    pub underline_offset: f32,
447    pub strikeout_offset: f32,
448    pub stroke_size: f32,
449}
450
451/// Get font metrics (ascent, descent, leading) scaled to logical pixels.
452///
453/// Scales at `size_px * scale_factor` (physical) and divides by
454/// `scale_factor`, so callers always see logical-pixel metrics.
455pub fn font_metrics_px(registry: &FontRegistry, resolved: &ResolvedFont) -> Option<FontMetricsPx> {
456    let entry = registry.get(resolved.font_face_id)?;
457    let font_ref = swash::FontRef::from_index(entry.bytes(), entry.face_index as usize)?;
458    let sf = resolved.scale_factor.max(f32::MIN_POSITIVE);
459    let physical_size = resolved.size_px * sf;
460    let metrics = font_ref.metrics(&[]).scale(physical_size);
461    let inv_sf = 1.0 / sf;
462
463    Some(FontMetricsPx {
464        ascent: metrics.ascent * inv_sf,
465        descent: metrics.descent * inv_sf,
466        leading: metrics.leading * inv_sf,
467        underline_offset: metrics.underline_offset * inv_sf,
468        strikeout_offset: metrics.strikeout_offset * inv_sf,
469        stroke_size: metrics.stroke_size * inv_sf,
470    })
471}
472
473/// A bidi run: a contiguous range of text with the same direction.
474pub struct BidiRun {
475    pub byte_range: std::ops::Range<usize>,
476    pub direction: TextDirection,
477    /// Visual order index (for reordering after line breaking).
478    pub visual_order: usize,
479    /// UAX #9 embedding level: even is LTR, odd is RTL.
480    ///
481    /// Rule L2 reorders by level, not by direction, and the two are not
482    /// interchangeable: a Latin phrase quoted inside Arabic inside an
483    /// English paragraph sits at level 2, and reordering it as though it
484    /// were level 0 puts it on the wrong side of the Arabic. `direction`
485    /// cannot tell those apart — `level` can.
486    pub level: u8,
487}
488
489/// A paragraph's bidi structure in **logical** order.
490///
491/// [`bidi_runs`] returns runs already reordered for display, which suits
492/// a single-line label that is shaped and painted in one go. The
493/// multi-line editor cannot use that: line breaking is a logical
494/// operation, so runs have to stay in logical order until the breaker has
495/// decided where the lines fall, and only then get reordered *per line*.
496/// Reordering the paragraph up front and breaking afterwards would
497/// scramble any paragraph that wraps.
498pub struct BidiParagraph {
499    /// Runs of uniform embedding level, in logical order.
500    pub runs: Vec<BidiRun>,
501    /// The paragraph embedding level actually used — the explicit base
502    /// direction when one was given, else the rule P2/P3 auto-detection.
503    pub para_level: u8,
504}
505
506impl BidiParagraph {
507    /// The paragraph's base direction, as resolved.
508    pub fn base_direction(&self) -> TextDirection {
509        if self.para_level % 2 == 1 {
510            TextDirection::RightToLeft
511        } else {
512            TextDirection::LeftToRight
513        }
514    }
515}
516
517/// The unicode-bidi paragraph level that expresses `base`.
518///
519/// `None` asks unicode-bidi to auto-detect (rules P2/P3: the first strong
520/// character wins, defaulting to LTR when the text has none). An explicit
521/// level overrides that — which is the point of honouring a stored
522/// paragraph direction, since P2/P3 incorrectly classifies any RTL
523/// paragraph that happens to open with a digit, a Latin acronym or an
524/// opening quote.
525fn base_para_level(base: TextDirection) -> Option<unicode_bidi::Level> {
526    match base {
527        TextDirection::Auto => None,
528        TextDirection::LeftToRight => Some(unicode_bidi::Level::ltr()),
529        TextDirection::RightToLeft => Some(unicode_bidi::Level::rtl()),
530    }
531}
532
533/// Resolve `text`'s bidi structure under an explicit or auto base direction.
534///
535/// Runs come back in logical order, each tagged with its embedding level.
536/// Callers shape each run with its own direction and later reorder the
537/// runs of each line with [`visual_order`].
538pub fn analyze_paragraph(text: &str, base: TextDirection) -> BidiParagraph {
539    use unicode_bidi::BidiInfo;
540
541    if text.is_empty() {
542        return BidiParagraph {
543            runs: Vec::new(),
544            para_level: base_para_level(base).map_or(0, |l| l.number()),
545        };
546    }
547
548    let bidi_info = BidiInfo::new(text, base_para_level(base));
549
550    // A block is one paragraph as far as layout is concerned; if the text
551    // somehow carries a hard break, the first paragraph's level is the
552    // one that governs alignment.
553    let para_level = bidi_info
554        .paragraphs
555        .first()
556        .map(|p| p.level.number())
557        .or_else(|| base_para_level(base).map(|l| l.number()))
558        .unwrap_or(0);
559
560    // Group consecutive characters of equal level. Iterating by
561    // `char_indices` rather than by byte keeps a run boundary from ever
562    // landing inside a multi-byte character.
563    let mut starts: Vec<(usize, u8)> = Vec::new();
564    for (idx, _) in text.char_indices() {
565        let level = bidi_info.levels[idx].number();
566        if starts.last().map(|&(_, l)| l) != Some(level) {
567            starts.push((idx, level));
568        }
569    }
570
571    // Each run ends where the next begins; the last ends with the text.
572    let ends = starts
573        .iter()
574        .skip(1)
575        .map(|&(start, _)| start)
576        .chain(std::iter::once(text.len()));
577
578    let runs: Vec<BidiRun> = starts
579        .iter()
580        .zip(ends)
581        .map(|(&(start, level), end)| BidiRun {
582            byte_range: start..end,
583            direction: if level % 2 == 1 {
584                TextDirection::RightToLeft
585            } else {
586                TextDirection::LeftToRight
587            },
588            // Always 0 here: these runs are in *logical* order and the
589            // block path reorders per line after breaking, so a
590            // paragraph-wide visual index would be both unused and
591            // misleading. `bidi_runs` fills it in for the single-line
592            // path, which does lay a paragraph out in one go.
593            visual_order: 0,
594            level,
595        })
596        .collect();
597
598    BidiParagraph { runs, para_level }
599}
600
601/// Reorder items from logical into visual order per UAX #9 rule L2.
602///
603/// Returns indices into `levels`: `result[0]` is the item to paint
604/// leftmost. L2 reads "from the highest level down to the lowest odd
605/// level, reverse any contiguous sequence of items at that level or
606/// higher", which is what the loop below does literally.
607pub fn visual_order(levels: &[u8]) -> Vec<usize> {
608    let mut order: Vec<usize> = (0..levels.len()).collect();
609    let Some(&max) = levels.iter().max() else {
610        return order;
611    };
612    // With no odd level nothing is RTL, so logical order is already visual.
613    let Some(min_odd) = levels.iter().copied().filter(|l| l % 2 == 1).min() else {
614        return order;
615    };
616
617    let mut level = max;
618    while level >= min_odd {
619        let mut i = 0;
620        while i < order.len() {
621            if levels[order[i]] >= level {
622                let start = i;
623                while i < order.len() && levels[order[i]] >= level {
624                    i += 1;
625                }
626                order[start..i].reverse();
627            } else {
628                i += 1;
629            }
630        }
631        // min_odd is odd, hence >= 1, so this cannot wrap past zero.
632        level -= 1;
633    }
634    order
635}
636
637/// Analyze text for bidirectional content and return directional runs
638/// in **visual order** per UAX #9 (Unicode Bidirectional Algorithm, rule L2).
639///
640/// The returned runs can be shaped independently and concatenated left-to-right
641/// to produce correctly-ordered mixed-script text (e.g. Latin embedded in
642/// Arabic). For pure-LTR text, returns a single LTR run. For pure-RTL text,
643/// returns a single RTL run.
644pub fn bidi_runs(text: &str) -> Vec<BidiRun> {
645    use unicode_bidi::BidiInfo;
646
647    if text.is_empty() {
648        return Vec::new();
649    }
650
651    let bidi_info = BidiInfo::new(text, None);
652    let mut runs = Vec::new();
653
654    for para in &bidi_info.paragraphs {
655        let (levels, level_runs) = bidi_info.visual_runs(para, para.range.clone());
656        for level_run in level_runs {
657            if level_run.is_empty() {
658                continue;
659            }
660            let level = levels[level_run.start];
661            let direction = if level.is_rtl() {
662                TextDirection::RightToLeft
663            } else {
664                TextDirection::LeftToRight
665            };
666            let visual_order = runs.len();
667            runs.push(BidiRun {
668                byte_range: level_run,
669                direction,
670                visual_order,
671                level: level.number(),
672            });
673        }
674    }
675
676    if runs.is_empty() {
677        runs.push(BidiRun {
678            byte_range: 0..text.len(),
679            direction: TextDirection::LeftToRight,
680            visual_order: 0,
681            level: 0,
682        });
683    }
684
685    runs
686}
687
688#[cfg(test)]
689mod bidi_tests {
690    use super::*;
691
692    const ARABIC: &str = "\u{0643}\u{062A}\u{0628}"; // كتب
693    const HEBREW: &str = "\u{05E9}\u{05DC}\u{05D5}\u{05DD}"; // שלום
694
695    #[test]
696    fn rule_l2_leaves_all_ltr_text_alone() {
697        assert_eq!(visual_order(&[0, 0, 0]), vec![0, 1, 2]);
698        assert_eq!(visual_order(&[]), Vec::<usize>::new());
699    }
700
701    #[test]
702    fn rule_l2_reverses_a_run_of_rtl() {
703        // level 0 "a", level 1 RTL, level 0 "b" -> the RTL span reverses
704        // in place but stays between its neighbours.
705        assert_eq!(visual_order(&[0, 1, 1, 0]), vec![0, 2, 1, 3]);
706    }
707
708    #[test]
709    fn rule_l2_nests_an_ltr_island_inside_rtl() {
710        // An English phrase (level 2) quoted inside Arabic (level 1)
711        // inside an English paragraph (level 0). The level-2 island must
712        // keep its own left-to-right order while the level-1 material
713        // around it reverses — the case `direction` alone cannot express.
714        let levels = [0, 1, 2, 2, 1, 0];
715        assert_eq!(visual_order(&levels), vec![0, 4, 2, 3, 1, 5]);
716    }
717
718    #[test]
719    fn rule_l2_reverses_the_whole_line_in_an_rtl_paragraph() {
720        // Level 1 throughout with a level-2 Latin word: the paragraph
721        // reads right-to-left, so logical item 0 paints rightmost.
722        assert_eq!(visual_order(&[1, 2, 1]), vec![2, 1, 0]);
723    }
724
725    #[test]
726    fn a_leading_digit_does_not_fool_auto_detection() {
727        // Worth pinning, because it is easy to assume otherwise: digits
728        // are type EN, not strong, so rule P2 skips them and finds the
729        // Arabic. An Arabic paragraph opening with a number needs no
730        // explicit direction.
731        let text = "123 \u{0643}\u{062A}\u{0628}";
732        assert_eq!(analyze_paragraph(text, TextDirection::Auto).para_level, 1);
733    }
734
735    #[test]
736    fn an_explicit_base_direction_overrides_first_strong_detection() {
737        // A Latin acronym *is* strong (type L), so rule P2 stops at the
738        // "NASA" and calls this Arabic paragraph left-to-right — the
739        // real false detection, and the reason a stored paragraph
740        // direction has to win over guessing.
741        let text = "NASA \u{0623}\u{0639}\u{0644}\u{0646}\u{062A}";
742        assert_eq!(
743            analyze_paragraph(text, TextDirection::Auto).para_level,
744            0,
745            "auto-detection is expected to get this one wrong"
746        );
747
748        let forced = analyze_paragraph(text, TextDirection::RightToLeft);
749        assert_eq!(forced.para_level, 1);
750        assert_eq!(forced.base_direction(), TextDirection::RightToLeft);
751
752        // And the override genuinely changes the layout, not just the
753        // recorded level: the Arabic now leads visually. Runs come back
754        // in logical order, so ask rule L2 which one paints leftmost —
755        // the same thing a caller laying the paragraph out would do.
756        let auto = analyze_paragraph(text, TextDirection::Auto);
757        let first_visual = |p: &BidiParagraph| {
758            let levels: Vec<u8> = p.runs.iter().map(|r| r.level).collect();
759            visual_order(&levels).first().map(|&i| p.runs[i].direction)
760        };
761        assert_eq!(first_visual(&auto), Some(TextDirection::LeftToRight));
762        assert_eq!(first_visual(&forced), Some(TextDirection::RightToLeft));
763    }
764
765    #[test]
766    fn pure_arabic_auto_detects_as_rtl() {
767        let para = analyze_paragraph(ARABIC, TextDirection::Auto);
768        assert_eq!(para.base_direction(), TextDirection::RightToLeft);
769        assert_eq!(para.runs.len(), 1);
770        assert_eq!(para.runs[0].direction, TextDirection::RightToLeft);
771        assert_eq!(para.runs[0].byte_range, 0..ARABIC.len());
772    }
773
774    #[test]
775    fn runs_come_back_in_logical_order_and_cover_the_text() {
776        // "hello <hebrew> world" — three runs, contiguous, logical order.
777        let text = format!("hello {HEBREW} world");
778        let para = analyze_paragraph(&text, TextDirection::Auto);
779
780        assert!(para.runs.len() >= 2, "expected a directional split");
781        assert_eq!(para.runs[0].byte_range.start, 0);
782        assert_eq!(para.runs.last().unwrap().byte_range.end, text.len());
783        for pair in para.runs.windows(2) {
784            assert_eq!(
785                pair[0].byte_range.end, pair[1].byte_range.start,
786                "runs must tile the text with no gap or overlap"
787            );
788            assert!(
789                pair[0].byte_range.start < pair[1].byte_range.start,
790                "runs must be in logical order"
791            );
792        }
793        assert!(
794            para.runs
795                .iter()
796                .any(|r| r.direction == TextDirection::RightToLeft),
797            "the Hebrew span should have produced an RTL run"
798        );
799    }
800
801    #[test]
802    fn run_boundaries_never_split_a_multibyte_character() {
803        let text = format!("a{ARABIC}b{HEBREW}c");
804        for run in analyze_paragraph(&text, TextDirection::Auto).runs {
805            assert!(
806                text.is_char_boundary(run.byte_range.start)
807                    && text.is_char_boundary(run.byte_range.end),
808                "run {:?} splits a character in {text:?}",
809                run.byte_range
810            );
811        }
812    }
813
814    #[test]
815    fn rule_l2_over_a_real_paragraph_is_a_permutation() {
816        let text = format!("hello {HEBREW} world {ARABIC} end");
817        let para = analyze_paragraph(&text, TextDirection::Auto);
818        let levels: Vec<u8> = para.runs.iter().map(|r| r.level).collect();
819
820        let mut seen = visual_order(&levels);
821        seen.sort_unstable();
822        assert_eq!(
823            seen,
824            (0..para.runs.len()).collect::<Vec<_>>(),
825            "every run must appear exactly once in the visual order"
826        );
827    }
828
829    #[test]
830    fn empty_text_analyzes_without_panicking() {
831        let para = analyze_paragraph("", TextDirection::RightToLeft);
832        assert!(para.runs.is_empty());
833        assert_eq!(para.para_level, 1);
834    }
835}