feat: rtl for tables

[artem-harbour]

Linear: SD-2810

Phase 5 (RTL Table Stability) is now completed for RTL table interaction and roundtrip reliability.

This PR does not introduce RTL tables from scratch; core support was already in place.
The main work here was stabilization and regression coverage:

• Confirmed full bidiVisual pipeline behavior (<w:bidiVisual/> ↔ tableProperties.rightToLeft)
• Validated RTL table rendering order and border behavior in the current layout pipeline
• Verified click-to-position behavior for RTL tables, including empty/padding areas
• Verified Tab and Shift+Tab table navigation behavior against Word
• Confirmed export roundtrip preserves RTL table semantics without border-side corruption
• Fixed RTL resize/drag boundary mapping issues, including handle-to-column targeting and post-resize hover indicator consistency
• Added regression tests for RTL and LTR table resize/hover flows
• Added focused behavior and import/export tests using real DOCX fixtures

Overall result: RTL tables are now covered by explicit tests across rendering, interaction, and export paths, with resize/drag behavior stabilized and regression-protected.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[linear]

SD-2810

[caio-pizzol]

hey @artem-harbour - the resize handle metadata + RTL drag flip math are clean, and the click-fallback / Tab tests pin the interaction surface well :)

Important

looks right for the resize/click/nav surface this PR scopes. 4 pre-existing rendering bugs surfaced when i instrumented the new fixtures against Word; they're out of scope here but block the "RTL tables done" claim.

bugs: bidiVisual tables default left-aligned (Word right-aligns), outer L/R table borders never render, cell padding ignores start/end margins, cell-level <w:tcBorders><w:start>/<w:end> dropped entirely. test coverage is the bigger gap (arrow keys in RTL cells, Tab/Shift+Tab boundary cases, resize positive-width assertions, layout/visual baselines for the new fixtures).

i pushed a follow-up commit scoping right-edge resize affectedColumns to one column (avoids rewriting column 1 cell tcW), plus 5 ECMA §17.4 fixtures in R2 as rendering/sd-2810-rtl-table-*.docx.

screenshot: Word vs SuperDoc side-by-side on rtl-table-tcborders-startend.docx (Word renders red start border on visual right + blue end border on visual left; SuperDoc renders neither).

agent context

{
  "schema": "review_handoff_v1",
  "review_id": "pr-3227",
  "findings": [
    {
      "id": "rtl-table-position",
      "severity": "important",
      "anchors": [{"file": "packages/layout-engine/layout-engine/src/layout-table.ts", "line": 184, "quote": "const justification = typeof attrs?.justification === 'string' ? attrs.justification : undefined;"}],
      "claim": "resolveTableFrame ignores rightToLeft when justification is absent, so bidiVisual tables with no explicit w:jc default to left-aligned. Word defaults to right-aligned (start-aligned in RTL).",
      "failure_mode": "User opens a bidiVisual table; SuperDoc places it on the left of the page, Word places it on the right.",
      "verification": [{"command": "pnpm dev (port 9095) + load rendering/sd-2810-rtl-table-tblind.docx + measure fragment leftGap/rightGap vs page", "result_summary": "leftGap=193px, rightGap=383px (table closer to left); Word screenshot shows table on right with rightGap smaller than leftGap.", "status": "executed"}],
      "ruled_out": [{"hypothesis": "Section-level w:bidi cascades to table alignment", "why_ruled_out": "Fixture has no section bidi; spec §17.6.1 says section bidi only affects section-level properties, not paragraph or table alignment."}],
      "handoff": {"recommended_start": "layout-table.ts:177 resolveTableFrame", "suggested_fix": "After reading justification, derive effective = justification ?? (rightToLeft ? 'end' : undefined) and use that for the right-aligned branch.", "expected_files": ["packages/layout-engine/layout-engine/src/layout-table.ts", "packages/layout-engine/layout-engine/src/layout-table.test.ts"], "avoid_files": ["packages/layout-engine/painters/dom/src/table/renderTableFragment.ts"], "do_not_repeat": []},
      "verification_after_fix": [{"command": "playwright test tables/rtl-table-spec-coverage.spec.ts", "expected": "new assertion: tableRect.right is within ~96px of pageRect.right on rtl-table-tblind.docx"}]
    },
    {
      "id": "rtl-table-outer-borders",
      "severity": "important",
      "anchors": [{"file": "packages/layout-engine/painters/dom/src/table/renderTableFragment.ts", "line": 343, "quote": "applyBorder(container, 'Right', borderValueToSpec(isRtl ? tableBorders.left : tableBorders.right));"}],
      "claim": "Outer left/right table borders never render on bidiVisual tables. The swap reads tableBorders.left/right but the importer may store start/end keys, leaving the swap pulling undefined.",
      "failure_mode": "User opens a bidiVisual table with full tblBorders; SuperDoc shows only top/bottom + inner borders, Word renders all four outer sides.",
      "verification": [{"command": "pnpm dev + load rendering/sd-2810-rtl-table-vmerge.docx + visual compare to Word", "result_summary": "Word renders left and right outer borders; SuperDoc does not.", "status": "executed"}],
      "ruled_out": [{"hypothesis": "Cell-level borders are masking the table-level borders", "why_ruled_out": "Cells have no per-side borders defined; the comment at line 178 notes 'cells handle all borders' but cell-render is not applying them either."}],
      "handoff": {"recommended_start": "super-converter/v3/handlers/w/tblBorders and the tableBorders key normalization", "suggested_fix": "Either normalize importer output to left/right physical keys, or change the swap to read tableBorders.start/end.", "expected_files": ["packages/layout-engine/painters/dom/src/table/renderTableFragment.ts", "packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/tblBorders"], "avoid_files": [], "do_not_repeat": []},
      "verification_after_fix": [{"command": "playwright test tables/rtl-table-spec-coverage.spec.ts", "expected": "new assertion: container has non-zero borderLeftWidth and borderRightWidth on rtl-table-vmerge.docx"}]
    },
    {
      "id": "rtl-cell-padding",
      "severity": "important",
      "anchors": [{"file": "packages/layout-engine/style-engine/src/ooxml/index.ts", "line": 0, "quote": "cellMargins.marginStart / marginEnd resolution"}],
      "claim": "Cells in bidiVisual tables render with less padding than Word. cellMargins.marginStart/marginEnd are not mapped to physical padding for RTL.",
      "failure_mode": "User opens a bidiVisual table; SuperDoc cells look cramped vs Word's padded cells.",
      "verification": [{"command": "visual compare rtl-table-col1-tcw-divergent.docx in SuperDoc vs Word", "result_summary": "Word shows ~8px padding all sides; SuperDoc shows minimal padding.", "status": "executed"}],
      "ruled_out": [],
      "handoff": {"recommended_start": "style-engine cellMargins resolver + painter cell padding application", "suggested_fix": "Map marginStart/marginEnd to marginLeft/marginRight based on table rightToLeft.", "expected_files": ["packages/layout-engine/style-engine/src/ooxml/index.ts", "packages/layout-engine/painters/dom/src/table/renderTableCell.ts"], "avoid_files": [], "do_not_repeat": []},
      "verification_after_fix": [{"command": "playwright test tables/rtl-table-spec-coverage.spec.ts", "expected": "computed cell padding-left/padding-right match marginEnd/marginStart values respectively on bidiVisual tables"}]
    },
    {
      "id": "rtl-tcborders-startend-dropped",
      "severity": "important",
      "anchors": [{"file": "packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/tcBorders/tcBorders-translator.js", "line": 0, "quote": "tcBorders w:start / w:end parsing"}],
      "claim": "Cell-level <w:tcBorders><w:start> and <w:end> render as no borders on bidiVisual tables. Fixture has start=#FF0000 24sz, end=#0000FF 24sz; SuperDoc paints neither.",
      "failure_mode": "User opens a bidiVisual table cell with start/end borders; Word shows them on the correct visual sides (start=right, end=left in RTL), SuperDoc shows none.",
      "verification": [{"command": "pnpm dev + load rendering/sd-2810-rtl-table-tcborders-startend.docx + getComputedStyle on cell + walk ancestors for any colored border", "result_summary": "No element in the cell subtree has border-left-color or border-right-color matching #FF0000 or #0000FF; Word screenshot shows both clearly.", "status": "executed"}],
      "ruled_out": [{"hypothesis": "Painter renders borders as absolutely-positioned overlay divs", "why_ruled_out": "queried all div descendants with position:absolute + non-default background-color inside the fragment; result was empty array."}],
      "handoff": {"recommended_start": "tcBorders-translator.js + renderTableCell.ts border application", "suggested_fix": "Confirm start/end are preserved through the parser, then map them to visual edges using table rightToLeft in the painter.", "expected_files": ["packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/tcBorders/tcBorders-translator.js", "packages/layout-engine/painters/dom/src/table/renderTableCell.ts"], "avoid_files": ["packages/layout-engine/painters/dom/src/table/renderTableFragment.ts"], "do_not_repeat": []},
      "verification_after_fix": [{"command": "un-fixme tables/rtl-table-spec-coverage.spec.ts cell-borders test", "expected": "cell on visual right has border-right-color rgb(255,0,0); cell on visual left has border-left-color rgb(0,0,255)"}]
    },
    {
      "id": "test-coverage-corner-cases",
      "severity": "nit",
      "anchors": [{"file": "tests/behavior/tests/tables", "line": 0, "quote": "table interaction suite"}],
      "claim": "Corner cases of table interaction in RTL are unverified: arrow-key navigation between cells, Tab/Shift+Tab from last-visual-cell boundary, positive width assertion after right-edge drag.",
      "failure_mode": "Regressions in RTL interaction won't be caught by the existing suite.",
      "verification": [{"command": "grep tests/behavior/tests/tables for ArrowLeft/ArrowRight/ArrowUp/ArrowDown", "result_summary": "No specs exercise arrow-key navigation in tables under RTL context.", "status": "executed"}],
      "ruled_out": [],
      "handoff": {"recommended_start": "tests/behavior/tests/tables - new specs against the 5 R2 fixtures", "suggested_fix": "Add specs for ArrowLeft/Right cell navigation in RTL, Tab from last visual cell, resize positive-width assertion. Land layout-compare + visual baselines for the 5 new corpus entries.", "expected_files": ["tests/behavior/tests/tables", "tests/visual/tests/rendering", "tests/layout"], "avoid_files": [], "do_not_repeat": []},
      "verification_after_fix": [{"command": "playwright test tables", "expected": "new specs pass against current bidiVisual rendering after the 4 rendering bugs above are addressed"}]
    }
  ]
}

[caio-pizzol]

hey @artem-harbour! the RTL table work is in good shape :) - verified the new fixtures against dev.

i pushed follow-ups: dropped the double-mirror in pm-adapter (painter is now the sole RTL swap), restored a missing legacy border-style normalizer, and added asymmetric fixtures + TableResizeOverlay RTL tests.

the tcMar fixme exposes a real importer gap (style-engine projection drops marginStart/marginEnd) - tracked under SD-2771.

lgtm.

[superdoc-bot]

🎉 This PR is included in vscode-ext v2.3.0-next.132

[superdoc-bot]

🎉 This PR is included in @superdoc-dev/mcp v0.3.0-next.87

The release is available on GitHub release

[superdoc-bot]

🎉 This PR is included in @superdoc-dev/react v1.2.0-next.130

The release is available on GitHub release

[superdoc-bot]

🎉 This PR is included in superdoc-cli v0.8.0-next.102

The release is available on GitHub release

[superdoc-bot]

🎉 This PR is included in superdoc-sdk v1.8.0-next.86

[superdoc-bot]

🎉 This PR is included in superdoc v1.30.0-next.84

The release is available on GitHub release