Skip to content

docs(recipes): say that a table cell takes a direction too - #679

Merged
DemchaAV merged 1 commit into
developfrom
docs/rtl-table-cells
Sep 11, 2026
Merged

docs(recipes): say that a table cell takes a direction too#679
DemchaAV merged 1 commit into
developfrom
docs/rtl-table-cells

Conversation

@DemchaAV

Copy link
Copy Markdown
Owner

Why

docs/recipes/text-direction.md still says that text in a table cell carries no direction: the same Hebrew string draws reversed in a cell, Arabic comes out unjoined, and right-to-left text belongs in paragraphs. That stopped being true with #558, which gave DocumentTableStyle a direction(...) of its own. The README and the backend capability matrix already describe table-cell direction; this page was the one place contradicting them.

What changed

  • The stale paragraph under Where direction stops gives way to a Tables section: DocumentTableStyle.Builder.direction(...) with LTR / RTL / AUTO, following the cell-style cascade defaultCellStylecolumnStylerowStyle → the cell's own withStyle.
  • It states the behaviour a reader trips on: AUTO is resolved per cell and over the whole cell; a right-to-left cell takes its right edge only when no textAnchor is set anywhere in its cascade, so a table-wide TOP_LEFT pins it left; the DOCX backend writes no alignment for a plain-text cell; auto columns are measured on the joined Arabic forms; an undeclared cell still draws Hebrew and Arabic in order; a composed-paragraph cell takes the paragraph's direction.
  • Where direction stops now lists what still holds: only paragraphs and table cells declare a direction; list items are left-to-right paragraphs, so align(TextAlign.RIGHT) moves them to the right margin but leaves each bullet at the item's left end; column order is not mirrored.
  • The new snippet carries a doc-example marker, so DocumentationSnippetCompileTest compiles it.

Verification

Each statement is tied to code and an existing test; no code changed.

  • RTL table-cell suites, all green: RtlTableCellTest 8, PptxTableCellDirectionTest 7, DocxTableCellDirectionTest 6, qa RtlAcrossBackendsTest + RtlScenariosVisualTest 15.
  • Documentation guards: core com.demcha.documentation.* plus EnginePdfBoundaryTest (links and anchors, recipe catalogue, canonical surface, coverage) 115 green; qa DocumentationSnippetCompileTest 6 + DocumentationExamplesTest 12 green. Breaking the new snippet on purpose turns DocumentationSnippetCompileTest red and names text-direction-table-cell, so the guard really covers it.
  • node knowledge/tools/claims/check-claims.mjs --check and node knowledge/tools/routing/check-routes.mjs green; git diff --check clean.
  • Not run locally: the full reactor gate, since no code changed; CI runs it on this PR.

Lane: canonical — docs only (docs/recipes/text-direction.md).

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.
@DemchaAV
DemchaAV merged commit bc8c053 into develop Sep 11, 2026
10 checks passed
@DemchaAV
DemchaAV deleted the docs/rtl-table-cells branch September 11, 2026 13:46
DemchaAV added a commit that referenced this pull request Sep 12, 2026
Brings the 2.4.0 engine work onto the promotion branch: native letter
spacing (#676), opt-in list hanging indent (#674), the resolved timeline
rail (#671-#673), the row-child margin fix, the RTL documentation
corrections (#679, #680) and the templates japicmp gate (#681).

Eight files conflicted. CHANGELOG.md is a union of both v2.4.0 sections,
with the branch-local "### Deprecated" folded into the house heading
"### Deprecations" and the sections ordered the way released entries are.
The other seven are generated and were regenerated from the merged source
rather than resolved by side: knowledge/api/templates.json and .md through
extract-api --from-reactor, and the five cv preview PDFs by re-rendering
their example classes.

Five qa baselines moved, all from f75def6, which stops a row child's
horizontal margin being taken off twice. Each of the four layout snapshots
changes by exactly one node's own horizontal margin - HeadingRule_EXPERIENCE
+9.0, EducationHeadingRule +11.285, FooterDueIcon -3.479 (a negative margin)
and FooterSite +1.693 (a right margin) - with startPage and endPage
unchanged, so no page ownership moved. cobalt_rota keeps its geometry
snapshot and moves only in pixels, inside composed table cells, which emit
fragments rather than PlacedNodes and so cannot appear in a layout snapshot;
the changed region is the day-header and note cells. One of 126 pixel
baselines changed, verified by checksum before and after.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant