From 6e3a749bda6fbdc6eed0bf829e60af76c72bfb46 Mon Sep 17 00:00:00 2001 From: DemchaAV Date: Fri, 11 Sep 2026 14:22:27 +0100 Subject: [PATCH] docs(recipes): say that a table cell takes a direction too The text-direction recipe still told readers that text in a table cell carries no direction, so Hebrew comes out of a cell reversed and Arabic unjoined, and that right-to-left text belongs in paragraphs instead. That was true when the page was written, with #536, and stopped being true two days later, when #558 gave DocumentTableStyle a direction of its own. The README and the backend capability matrix already say so; this page was the one place still saying the opposite. The stale paragraph under Where direction stops gives way to a Tables section that describes what the code does today: - the style builder's `direction(...)` takes `LTR`, `RTL` and `AUTO` and follows the cell-style cascade: `defaultCellStyle`, `columnStyle`, `rowStyle`, then the cell's own `withStyle`; - a composed-paragraph cell takes its direction from the paragraph; - `AUTO` is read per cell, over the whole cell; - a right-to-left cell sits at its right edge unless a `textAnchor` anywhere in its cascade says otherwise, a table-wide `TOP_LEFT` included; Word output is the exception, since the DOCX backend writes no alignment for a plain-text cell; - auto-width columns are measured on the joined Arabic forms, and a cell that declares nothing still draws Hebrew and Arabic the right way round. What still stops is stated where the old paragraph stood: only paragraphs and table cells declare a direction; a list carries none, so each item is a left-to-right paragraph and `align(TextAlign.RIGHT)` moves it to the right margin while its bullet stays at the item's left end; and column order is not mirrored. The new snippet carries a doc-example marker, so DocumentationSnippetCompileTest compiles it from now on. --- docs/recipes/text-direction.md | 52 ++++++++++++++++++++++++++++++---- 1 file changed, 47 insertions(+), 5 deletions(-) diff --git a/docs/recipes/text-direction.md b/docs/recipes/text-direction.md index 9a656a5df..de9e618fe 100644 --- a/docs/recipes/text-direction.md +++ b/docs/recipes/text-direction.md @@ -91,13 +91,55 @@ is not. Shaping covers the base Arabic block (U+0621–U+064A) — the Persian a Urdu extensions render unjoined for now. Vowel points and direction marks sit between letters without breaking the join. +## Tables + +A table cell says it the same way, through its style: + + +```java +import com.demcha.compose.document.table.DocumentTableStyle; + +DocumentTableStyle.builder() + .direction(TextDirection.AUTO) + .build(); +``` + +The builder's `direction(...)` takes the same `LTR`, `RTL` and `AUTO`, and +follows the same cascade as the rest of a cell style — the table's +`defaultCellStyle`, then `columnStyle(i, …)`, then `rowStyle(i, …)`, then the +cell's own `withStyle(…)` — so one call on the table's default sets it for every +cell. Give those cells a `textStyle` whose font covers the script, as a +paragraph needs (see [Fonts](#fonts)). A cell whose content is a composed +paragraph (`DocumentTableCell.node(...)`) is laid out as that paragraph, and +takes its direction from the paragraph instead. + +The cell is the unit `AUTO` reads. Two cells side by side under one `AUTO` +answer it separately, and a cell's second line does not run the other way from +its first because it happens to open on Latin. + +A right-to-left cell sits at its right edge unless a `textAnchor` set anywhere +in its cascade says where to put it — the rule alignment already follows in a +paragraph. An anchor sets the horizontal side along with the vertical one, so a +table-wide `TOP_LEFT` chosen only to top-align the cells also pins right-to-left +ones to the left; give them `TOP_RIGHT`. Word output is the exception: the DOCX +backend writes no alignment for a cell written as plain text, so Word places it +by its own default — the right edge, for right-to-left text — and an explicit +`textAnchor` does not reach it. An auto-width column is measured on the joined +Arabic forms, so it is sized to the text that is drawn. + +A cell that declares nothing still draws its Hebrew and Arabic the right way +round: a declaration settles which direction a line is *embedded* in, while a +script runs the way it runs inside that. + ## Where direction stops -Direction is a property of a **paragraph**. Text inside a table cell goes through the -table's own layout, which does not carry direction, so the same Hebrew string draws -correctly in `addParagraph` and reversed in a cell, and Arabic in a cell is unjoined. Set -right-to-left text as a paragraph where you can; inside a table the text is drawn in the -order it is written. +Only paragraphs and table cells declare a direction. A list carries none of its +own: each item is laid out as a left-to-right paragraph, so +`align(TextAlign.RIGHT)` sets the items against the right margin, but each +bullet stays at the left end of its item. + +Column order is not mirrored. The first column of a right-to-left table is still +the leftmost one — write the columns in the order they should appear. ## See also