Merge pull request #2012 from TrevorBrown-dev/feat/text-direction-1830

M4: a paragraph's base direction can be forced: Text ▸ Text direction ▸ Left to right / Right to left (#1830)

crates/engine/src/automation/inspect.rs

@@ -53,6 +53,7 @@ pub const NODE_KEYS: &[&str] = &[
     "layout",
     "leadingTrim",
     "letterSpacing",
+    "lineDirections",
     "lineHeight",
     "lineIndentations",
     "lineTypes",
@@ -96,6 +97,7 @@ pub const NODE_KEYS: &[&str] = &[
     "textDecorationSkipInk",
     "textDecorationStyle",
     "textDecorationThickness",
+    "textDirection",
     "textPath",
     "textStyleRanges",
     "type",
@@ -432,6 +434,16 @@ fn text_props(t: &TextData, o: &mut serde_json::Map<String, Value>, options: &In
             insert_prop(o, options, "listStartOffsets", || t.paragraphs.iter().map(|p| json!(p.start_offset)).collect());
         }
     }
+    // The paragraphs' base direction: one for the layer when they agree, else each one's (Auto
+    // throughout says nothing).
+    let dirs: Vec<figcraft_doc::TextDirection> = t.paragraphs.iter().map(|p| p.direction).collect();
+    if let Some(first) = dirs.first().copied().filter(|d| *d != figcraft_doc::TextDirection::Auto)
+        && dirs.iter().all(|d| *d == first)
+    {
+        insert_prop(o, options, "textDirection", || json!(first));
+    } else if dirs.iter().any(|d| *d != figcraft_doc::TextDirection::Auto) {
+        insert_prop(o, options, "lineDirections", || dirs.iter().map(|d| json!(d)).collect());
+    }
     if t.list_spacing != 0.0 {
         insert_prop(o, options, "listSpacing", || json!(t.list_spacing));
     }

crates/engine/src/catalog.rs

@@ -216,6 +216,11 @@ pub static MENU: &[MenuItem] = &[
     m!("Text/Case", "Uppercase", "text.caseUpper"),
     m!("Text/Case", "Lowercase", "text.caseLower"),
     m!("Text/Case", "Title case", "text.caseTitle"),
+    // "Go to Text > Text direction. Select Left to right or Right to left." (Add right-to-left
+    // text); Auto, the way back to detection, is FigCraft's own (in `OWN`).
+    m!("Text/Text direction", "Auto", "text.directionAuto"),
+    m!("Text/Text direction", "Left to right", "text.directionLtr"),
+    m!("Text/Text direction", "Right to left", "text.directionRtl"),
     m!("Text", SEP, ""),
     m!("Text", "Missing fonts…", "text.missingFonts"),
     // Arrange
@@ -292,7 +297,7 @@ pub fn items() -> impl Iterator<Item = &'static MenuItem> {
 }
 
 /// Items of FigCraft's own that the parity count leaves out (as it does the `collab.` ones).
-const OWN: [&str; 5] = ["file.newFromTemplate", "file.newBoard", "help.gettingStarted", "text.missingFonts", "image.crop"];
+const OWN: [&str; 6] = ["file.newFromTemplate", "file.newBoard", "help.gettingStarted", "text.missingFonts", "image.crop", "text.directionAuto"];
 
 /// Coverage: (implemented, total, missing ids). `extra` lists ids implemented by the UI layer.
 pub fn parity(extra: &[&str]) -> (usize, usize, Vec<&'static str>) {

crates/engine/src/cmd/props.rs

@@ -983,6 +983,12 @@ fn apply_text(cmd: &str, doc: &mut Document, id: NodeId, props: &Map<String, Val
                 t.set_para_lists(start, end, |p| p.indent = d.clamp(0.0, f64::from(MAX_LIST_INDENT)) as u8);
             }
         }
+        "textDirection" | "direction" => {
+            let d: figcraft_doc::TextDirection = enum_of(v).ok_or_else(|| bad(cmd, "textDirection: auto|ltr|rtl"))?;
+            let t = text_mut(cmd, doc.get_mut(id)?)?;
+            let (start, end) = range_of(props, t.char_count());
+            t.set_para_lists(start, end, |p| p.direction = d);
+        }
         "listSpacing" => text_mut(cmd, doc.get_mut(id)?)?.list_spacing = f64_of(v).filter(|s| s.is_finite()).unwrap_or(0.0).clamp(0.0, 10_000.0),
         "hangingPunctuation" | "hangingList" => {
             let on = v.as_bool().ok_or_else(|| bad(cmd, format!("`{k}` must be true or false")))?;
@@ -1237,7 +1243,7 @@ pub fn override_group(k: &str) -> &'static str {
         "name" => "name",
         "characters" | "text" => "characters",
         "features" | "fontFeatures" | "openTypeFeatures" | "listStyle" | "indentation" | "listSpacing" | "maxLines" | "variationSettings"
-        | "hangingPunctuation" | "hangingList" | "wrapStyle" | "textWrap" => "textStyle",
+        | "hangingPunctuation" | "hangingList" | "wrapStyle" | "textWrap" | "textDirection" | "direction" => "textStyle",
         "cornerRadius" | "cornerSmoothing" | "topLeftRadius" | "topRightRadius" | "bottomRightRadius" | "bottomLeftRadius" => "corners",
         "width" | "height" | "w" | "h" => "size",
         "sizingH" | "sizingV" | "layoutSizingHorizontal" | "layoutSizingVertical" | "minWidth" | "maxWidth" | "minHeight" | "maxHeight" => "resizing",

crates/engine/src/cmd/text.rs

@@ -1,8 +1,8 @@
 //! Text menu and text editing commands.
 
 use figcraft_doc::{
-    LetterSpacing, LineHeight, ListStyle, NodeId, NodeKind, TextAlignH, TextAutoResize, TextCase, TextData, TextDecoration, TextPath, TextStyle,
-    VariableId,
+    LetterSpacing, LineHeight, ListStyle, NodeId, NodeKind, TextAlignH, TextAutoResize, TextCase, TextData, TextDecoration, TextDirection, TextPath,
+    TextStyle, VariableId,
 };
 use serde_json::{Map, Value, json};
 
@@ -91,6 +91,13 @@ fn set_list(s: &mut Session, p: &Value, l: ListStyle, toggle: bool) -> Result<Va
     para_range(s, p, |t, a, b| t.set_para_lists(a, b, |pl| pl.list = l))
 }
 
+/// The base direction of the targeted paragraphs: the edited ones while editing, else every
+/// paragraph of the targeted texts ("controls are available to override text direction per
+/// paragraph", Add right-to-left text, #1830).
+fn set_direction(s: &mut Session, p: &Value, d: TextDirection) -> Result<Value> {
+    para_range(s, p, |t, a, b| t.set_para_lists(a, b, |pl| pl.direction = d))
+}
+
 /// Whether every targeted char has `pred` (to decide toggle direction).
 fn all_have(s: &Session, p: &Value, pred: impl Fn(&TextStyle) -> bool) -> bool {
     let Ok(doc) = s.doc() else { return false };
@@ -319,6 +326,26 @@ pub fn specs() -> Vec<CommandSpec> {
                 para(s, p, |t| t.wrap_style = w)
             }
         ),
+        spec!(
+            "text.direction",
+            "Text direction",
+            "{direction: auto|ltr|rtl, ids?}  the base direction of the paragraphs (while editing: the selected ones): auto goes by the first letter with a direction, ltr runs them left to right and rtl right to left whatever their letters (Text ▸ Text direction)",
+            true,
+            |s, p| {
+                let d: TextDirection =
+                    get(p, "direction").and_then(super::props::enum_of).ok_or_else(|| bad("text.direction", "`direction`: auto|ltr|rtl"))?;
+                set_direction(s, p, d)
+            }
+        ),
+        spec!("text.directionAuto", "Text direction: auto", "{ids?}  while editing: the selected paragraphs", true, |s, p| {
+            set_direction(s, p, TextDirection::Auto)
+        }),
+        spec!("text.directionLtr", "Text direction: left to right", "{ids?}  while editing: the selected paragraphs", true, |s, p| {
+            set_direction(s, p, TextDirection::Ltr)
+        }),
+        spec!("text.directionRtl", "Text direction: right to left", "{ids?}  while editing: the selected paragraphs", true, |s, p| {
+            set_direction(s, p, TextDirection::Rtl)
+        }),
         spec!("text.paragraphIndent", "Paragraph indent", "{indent (px), ids?}", true, |s, p| {
             let v = finite(req_num("text.paragraphIndent", p, "indent")?).clamp(0.0, 10_000.0);
             para(s, p, |t| t.paragraph_indent = v)

crates/engine/src/dev/codegen/css.rs

@@ -307,6 +307,19 @@ fn text_decls(doc: &Document, n: &Node, tx: &figcraft_doc::TextData, t: &mut Tok
         figcraft_doc::WrapStyle::Balance => put("text-wrap", "balance".into()),
         figcraft_doc::WrapStyle::Pretty => put("text-wrap", "pretty".into()),
     }
+    // A base direction forced on every paragraph (CSS has one per element).
+    let dir = tx.paragraphs.first().map(|p| p.direction).filter(|d| tx.paragraphs.iter().all(|p| p.direction == *d));
+    match dir {
+        Some(figcraft_doc::TextDirection::Ltr) => put("direction", "ltr".into()),
+        Some(figcraft_doc::TextDirection::Rtl) => {
+            put("direction", "rtl".into());
+            // Left alignment is absolute on the canvas; `start` would be the right edge here.
+            if tx.align_h == TextAlignH::Left {
+                put("text-align", "left".into());
+            }
+        }
+        _ => {}
+    }
     match s.case {
         TextCase::Original => {}
         TextCase::Upper => put("text-transform", "uppercase".into()),

crates/engine/src/text_behaviour_tests.rs

@@ -371,6 +371,64 @@ fn max_lines_on_auto_height_text_hugs_that_many_lines() {
     assert_eq!(resize_mode(&s, fixed), TextAutoResize::Truncate);
 }
 
+#[test]
+fn text_direction_is_forced_per_paragraph() {
+    // Add right-to-left text: "By default, Figma automatically handles text direction based on
+    // language detection. However, controls are available to override text direction per
+    // paragraph" ("Go to Text > Text direction. Select Left to right or Right to left.").
+    let font = test_mono_font();
+    let mut s = Session::new();
+    let t = text(&mut s, "abc def\nghi\njkl", json!({"fontFamily": font, "fontSize": 16, "lineHeight": 24}));
+    let rtl = |s: &Session| -> Vec<bool> {
+        let (l, _) = figcraft_text::layout_node(s.doc().unwrap().node(t).unwrap()).unwrap();
+        l.lines.iter().map(|l| l.rtl).collect()
+    };
+    let inspect = |s: &Session| crate::inspect::node_json(s.doc().unwrap(), t, 0);
+    assert_eq!(rtl(&s), [false, false, false], "Latin letters read left to right");
+    assert!(inspect(&s).get("textDirection").is_none() && inspect(&s).get("lineDirections").is_none());
+    // The layer's paragraphs at once, by the command or `node.set`; inspect reports the one
+    // direction they share, and Dev Mode's CSS has it.
+    s.execute("text.direction", &json!({"ids": [t], "direction": "rtl"})).unwrap();
+    assert_eq!(rtl(&s), [true, true, true], "forced right to left whatever the letters");
+    assert_eq!(inspect(&s)["textDirection"], json!("rtl"));
+    let css = |s: &mut Session| s.execute("inspect.code", &json!({"id": t})).unwrap()["code"].as_str().unwrap().to_string();
+    assert!(css(&mut s).contains("direction: rtl;"), "{}", css(&mut s));
+    assert!(css(&mut s).contains("text-align: left;"), "Left stays the left edge, which `start` would not be: {}", css(&mut s));
+    s.execute("node.set", &json!({"id": t, "props": {"textDirection": "ltr"}})).unwrap();
+    assert_eq!(rtl(&s), [false, false, false]);
+    assert_eq!(inspect(&s)["textDirection"], json!("ltr"));
+    assert!(css(&mut s).contains("direction: ltr;"));
+    s.execute("text.directionAuto", &json!({"ids": [t]})).unwrap();
+    assert!(inspect(&s).get("textDirection").is_none(), "auto throughout says nothing");
+    assert!(!css(&mut s).contains("direction:"));
+    // While editing, the caret's paragraph alone (the menu's Right to left); inspect lists each
+    // paragraph's direction when they differ, and the CSS stays quiet.
+    s.execute("text.edit.begin", &json!({"id": t, "caret": 9})).unwrap();
+    s.execute("text.directionRtl", &json!({})).unwrap();
+    s.execute("text.edit.end", &json!({})).unwrap();
+    assert_eq!(rtl(&s), [false, true, false], "the second paragraph only");
+    assert_eq!(inspect(&s)["lineDirections"], json!(["auto", "rtl", "auto"]));
+    assert!(!css(&mut s).contains("direction:"));
+    // Enter inside a forced paragraph keeps the direction for the new one, as list settings carry.
+    s.execute("text.edit.begin", &json!({"id": t, "caret": 10})).unwrap();
+    s.execute("text.edit.insert", &json!({"text": "\n"})).unwrap();
+    s.execute("text.edit.end", &json!({})).unwrap();
+    assert_eq!(rtl(&s), [false, true, true, false]);
+    // An empty last paragraph (after a final newline) keeps the direction forced on it.
+    s.execute("node.set", &json!({"id": t, "props": {"characters": "abc\n", "textDirection": "auto"}})).unwrap();
+    s.execute("text.edit.begin", &json!({"id": t, "caret": 4})).unwrap();
+    s.execute("text.directionRtl", &json!({})).unwrap();
+    s.execute("text.edit.end", &json!({})).unwrap();
+    assert_eq!(rtl(&s), [false, true], "the empty last line runs right to left");
+    // A direction the document has words for; junk is refused.
+    s.execute("node.set", &json!({"id": t, "props": {"characters": "\u{05E9}\u{05DC}\u{05D5}\u{05DD} abc", "textDirection": "auto"}})).unwrap();
+    assert_eq!(rtl(&s), [true], "Hebrew first: right to left by detection");
+    s.execute("node.set", &json!({"id": t, "props": {"textDirection": "ltr"}})).unwrap();
+    assert_eq!(rtl(&s), [false], "forced left to right");
+    assert!(s.execute("node.set", &json!({"id": t, "props": {"textDirection": "sideways"}})).is_err());
+    assert!(s.execute("text.direction", &json!({"ids": [t], "direction": "up"})).is_err());
+}
+
 #[test]
 fn balance_and_pretty_wrap_styles_break_lines_as_documented() {
     // Explore text properties: "Auto: Figma fits as many words as possible on each line before

crates/engine/src/text_tail_tests.rs

@@ -64,7 +64,7 @@ fn a_list_with_a_start_number_toggles_off() {
     let mut s = Session::new();
     let t = text(&mut s, "two\nthree\nfour");
     if let figcraft_doc::NodeKind::Text(td) = &mut s.doc_mut().unwrap().get_mut(t).unwrap().kind {
-        let n = |start_offset| ParaList { list: N, indent: 0, start_offset };
+        let n = |start_offset| ParaList { list: N, indent: 0, start_offset, ..ParaList::default() };
         td.paragraphs = vec![n(1), n(0), n(0)];
     }
     let j = crate::inspect::node_json(s.doc().unwrap(), t, 0);
@@ -157,7 +157,8 @@ fn list_keys_at_list_items() {
     for (chars, before, caret, k, shift, after, want, why) in cases {
         let mut s = Session::new();
         let t = text(&mut s, chars);
-        let ps: Vec<ParaList> = before.iter().map(|(list, indent)| ParaList { list: *list, indent: *indent, start_offset: 0 }).collect();
+        let ps: Vec<ParaList> =
+            before.iter().map(|(list, indent)| ParaList { list: *list, indent: *indent, start_offset: 0, ..ParaList::default() }).collect();
         if let figcraft_doc::NodeKind::Text(td) = &mut s.doc_mut().unwrap().get_mut(t).unwrap().kind {
             td.paragraphs = ps;
         }
@@ -181,7 +182,11 @@ fn paragraph_lists_follow_edits() {
     // A paragraph's list stays with it as text is typed, pasted and deleted: new paragraphs copy
     // the one they split from; joined paragraphs keep the first one's.
     let mut t = TextData::new("ab\ncd\nef");
-    t.paragraphs = vec![ParaList { list: B, indent: 1, start_offset: 0 }, ParaList::default(), ParaList { list: N, indent: 0, start_offset: 0 }];
+    t.paragraphs = vec![
+        ParaList { list: B, indent: 1, start_offset: 0, ..ParaList::default() },
+        ParaList::default(),
+        ParaList { list: N, indent: 0, start_offset: 0, ..ParaList::default() },
+    ];
     let get = |t: &TextData| (0..t.paragraph_count()).map(|p| (t.para_list(p).list, t.para_list(p).indent)).collect::<Vec<_>>();
     t.replace_range(1, 1, "x\ny");
     assert_eq!(get(&t), [(B, 1), (B, 1), (P, 0), (N, 0)], "a pasted newline: a new item like it");
@@ -196,7 +201,7 @@ fn paragraph_lists_follow_edits() {
         (seed >> 33) as usize % n.max(1)
     };
     let mut t = TextData::new("a\nb\nc\nd");
-    t.paragraphs = vec![ParaList { list: B, indent: 2, start_offset: 0 }; 4];
+    t.paragraphs = vec![ParaList { list: B, indent: 2, start_offset: 0, ..ParaList::default() }; 4];
     for _ in 0..500 {
         let n = t.char_count();
         let (a, b) = (rnd(n + 2), rnd(n + 2));