feat(painter-dom): implement w:bidiVisual RTL table rendering (SD-2278) (#2556)

* feat(painter-dom): implement w:bidiVisual RTL table rendering (ECMA-376 §17.4.1)

Detect `tableProperties.rightToLeft` from `w:bidiVisual` and render
tables with visually reversed column order:

- Set `dir="rtl"` + `direction: rtl` on table fragment container
- Mirror cell X positions so first logical column appears on the right
- Swap resolved border left↔right in CSS output for correct visual edges
- Swap cell padding left↔right per Part 4 §14.3.3–14.3.8
- Handle cell spacing and colspan in mirrored layout
- Mirror ghost cell positions for cross-page rowspan continuations

Fixes SD-2278

* test(painter-dom): add unit tests for RTL table border swap and cell mirroring

- border-utils: tests for swapTableBordersLR and swapCellBordersLR
- renderTableRow: tests for RTL x-position mirroring with asymmetric widths,
  isRtl passthrough to renderTableCell, and border left↔right swap

* fix(painter-dom): address RTL table review feedback

- Remove dir="rtl" from table container — w:bidiVisual only affects cell
  layout order, not paragraph text direction. Cell reversal is handled
  by X mirroring already. Setting dir on the container would flip bidi
  behavior for LTR/neutral content inside cells.
- Fix ghost cell spacing mismatch — ghostX was computed without cell
  spacing but totalWidth included it, causing misaligned continuation
  cells in RTL tables with non-zero cellSpacing.

* fix(painter-dom): swap container L/R borders for RTL separate-border tables

For tables with borderCollapse=separate and cellSpacing, the container
paints outer table borders directly. Swap left↔right for RTL tables
so the container border matches the mirrored cell layout.

* test(painter-dom): add missing RTL table test coverage

- renderTableCell: RTL padding swap with asymmetric left/right values
- renderTableRow: RTL mirroring with non-zero cellSpacing + colspan
- renderTableFragment: ghost cell RTL x-position mirroring for rowspan
  continuations, isRtl propagation to body rows

Author: caio-pizzol

packages/layout-engine/painters/dom/src/table/border-utils.test.ts

@@ -20,6 +20,8 @@ import {
   resolveTableCellBorders,
   createTableBorderOverlay,
   hasExplicitCellBorders,
+  swapTableBordersLR,
+  swapCellBordersLR,
 } from './border-utils.js';
 
 describe('applyBorder', () => {
@@ -469,3 +471,54 @@ describe('createTableBorderOverlay', () => {
     expect(overlay?.style.borderBottom).toMatch(/2px solid (#0000FF|rgb\(0,\s*0,\s*255\))/i);
   });
 });
+
+describe('swapTableBordersLR', () => {
+  it('swaps left and right borders', () => {
+    const borders: TableBorders = {
+      top: { style: 'single', width: 1, color: '#000000' },
+      bottom: { style: 'single', width: 1, color: '#000000' },
+      left: { style: 'thick', width: 3, color: '#0000FF' },
+      right: { style: 'single', width: 0.5, color: '#FF0000' },
+      insideH: { style: 'single', width: 1, color: '#111111' },
+      insideV: { style: 'single', width: 1, color: '#222222' },
+    };
+    const swapped = swapTableBordersLR(borders)!;
+    expect(swapped.left).toEqual(borders.right);
+    expect(swapped.right).toEqual(borders.left);
+    expect(swapped.top).toEqual(borders.top);
+    expect(swapped.bottom).toEqual(borders.bottom);
+    expect(swapped.insideH).toEqual(borders.insideH);
+    expect(swapped.insideV).toEqual(borders.insideV);
+  });
+
+  it('returns undefined for undefined input', () => {
+    expect(swapTableBordersLR(undefined)).toBeUndefined();
+  });
+
+  it('handles missing left or right', () => {
+    const borders: TableBorders = { top: { style: 'single', width: 1, color: '#000' } };
+    const swapped = swapTableBordersLR(borders)!;
+    expect(swapped.left).toBeUndefined();
+    expect(swapped.right).toBeUndefined();
+  });
+});
+
+describe('swapCellBordersLR', () => {
+  it('swaps left and right borders', () => {
+    const borders: CellBorders = {
+      top: { style: 'single', width: 1, color: '#000000' },
+      bottom: { style: 'single', width: 1, color: '#000000' },
+      left: { style: 'thick', width: 3, color: '#0000FF' },
+      right: { style: 'single', width: 0.5, color: '#FF0000' },
+    };
+    const swapped = swapCellBordersLR(borders)!;
+    expect(swapped.left).toEqual(borders.right);
+    expect(swapped.right).toEqual(borders.left);
+    expect(swapped.top).toEqual(borders.top);
+    expect(swapped.bottom).toEqual(borders.bottom);
+  });
+
+  it('returns undefined for undefined input', () => {
+    expect(swapCellBordersLR(undefined)).toBeUndefined();
+  });
+});

packages/layout-engine/painters/dom/src/table/border-utils.ts

@@ -309,3 +309,28 @@ export const resolveTableCellBorders = (
     right: borderValueToSpec(cellBounds.touchesRightEdge ? tableBorders?.right : null),
   };
 };
+
+/**
+ * Swap left↔right on table borders for RTL tables (ECMA-376 Part 4 §14.3.2, §14.3.6).
+ * insideH/insideV and top/bottom are not affected by direction.
+ */
+export const swapTableBordersLR = (borders: TableBorders | undefined): TableBorders | undefined => {
+  if (!borders) return undefined;
+  return {
+    ...borders,
+    left: borders.right,
+    right: borders.left,
+  };
+};
+
+/**
+ * Swap left↔right on cell borders for RTL tables (ECMA-376 Part 4 §14.3.1, §14.3.5).
+ */
+export const swapCellBordersLR = (borders: CellBorders | undefined): CellBorders | undefined => {
+  if (!borders) return undefined;
+  return {
+    ...borders,
+    left: borders.right,
+    right: borders.left,
+  };
+};

packages/layout-engine/painters/dom/src/table/renderTableCell.test.ts

@@ -3936,3 +3936,75 @@ describe('segment count sync: renderer vs layout engine', () => {
     expect(getCellSegmentCount(cell)).toBe(2);
   });
 });
+
+describe('RTL cell padding swap', () => {
+  let doc: Document;
+
+  beforeEach(() => {
+    doc = document.implementation.createHTMLDocument('table-cell-rtl');
+  });
+
+  const createBaseDeps = () => ({
+    doc,
+    x: 0,
+    y: 0,
+    rowHeight: 40,
+    borders: undefined,
+    useDefaultBorder: false,
+    context: { sectionIndex: 0, pageIndex: 0, columnIndex: 0 },
+    renderLine: () => doc.createElement('div'),
+    applySdtDataset: () => {},
+  });
+
+  const cellMeasure: TableCellMeasure = {
+    blocks: [
+      {
+        kind: 'paragraph' as const,
+        lines: [{ fromRun: 0, fromChar: 0, toRun: 0, toChar: 1, width: 10, ascent: 12, descent: 4, lineHeight: 20 }],
+        totalHeight: 20,
+      },
+    ],
+    width: 100,
+    height: 20,
+    gridColumnStart: 0,
+    colSpan: 1,
+    rowSpan: 1,
+  };
+
+  it('swaps asymmetric padding left↔right when isRtl is true', () => {
+    const cell: TableCell = {
+      id: 'rtl-cell' as unknown as import('@superdoc/contracts').BlockId,
+      blocks: [{ kind: 'paragraph', id: 'p1', runs: [{ text: 'x', fontFamily: 'Arial', fontSize: 12 }] }],
+      attrs: { padding: { top: 2, left: 3, right: 8, bottom: 2 } },
+    };
+
+    const { cellElement } = renderTableCell({
+      ...createBaseDeps(),
+      cellMeasure,
+      cell,
+      isRtl: true,
+    });
+
+    expect(cellElement.style.paddingLeft).toBe('8px');
+    expect(cellElement.style.paddingRight).toBe('3px');
+    expect(cellElement.style.paddingTop).toBe('2px');
+    expect(cellElement.style.paddingBottom).toBe('2px');
+  });
+
+  it('does not swap padding when isRtl is false', () => {
+    const cell: TableCell = {
+      id: 'ltr-cell' as unknown as import('@superdoc/contracts').BlockId,
+      blocks: [{ kind: 'paragraph', id: 'p1', runs: [{ text: 'x', fontFamily: 'Arial', fontSize: 12 }] }],
+      attrs: { padding: { top: 2, left: 3, right: 8, bottom: 2 } },
+    };
+
+    const { cellElement } = renderTableCell({
+      ...createBaseDeps(),
+      cellMeasure,
+      cell,
+    });
+
+    expect(cellElement.style.paddingLeft).toBe('3px');
+    expect(cellElement.style.paddingRight).toBe('8px');
+  });
+});

packages/layout-engine/painters/dom/src/table/renderTableCell.ts

@@ -904,6 +904,8 @@ type TableCellRenderDependencies = {
   tableSdt?: SdtMetadata | null;
   /** Table indent in pixels (applied to table fragment positioning) */
   tableIndent?: number;
+  /** Whether the table is visually right-to-left (w:bidiVisual, ECMA-376 §17.4.1) */
+  isRtl?: boolean;
   /** Computed cell width from rescaled columnWidths (overrides cellMeasure.width when present) */
   cellWidth?: number;
   /** Starting line index for partial row rendering (inclusive) */
@@ -992,16 +994,18 @@ export const renderTableCell = (deps: TableCellRenderDependencies): TableCellRen
     applySdtDataset,
     tableSdt,
     tableIndent,
+    isRtl,
     cellWidth,
     fromLine,
     toLine,
   } = deps;
 
   const attrs = cell?.attrs;
   const padding = attrs?.padding || { top: 0, left: 4, right: 4, bottom: 0 };
-  const paddingLeft = padding.left ?? 4;
+  // RTL: swap left↔right cell margins (ECMA-376 Part 4 §14.3.3–14.3.4, §14.3.7–14.3.8)
+  const paddingLeft = isRtl ? (padding.right ?? 4) : (padding.left ?? 4);
   const paddingTop = padding.top ?? 0;
-  const paddingRight = padding.right ?? 4;
+  const paddingRight = isRtl ? (padding.left ?? 4) : (padding.right ?? 4);
   const paddingBottom = padding.bottom ?? 0;
 
   const cellEl = doc.createElement('div');

packages/layout-engine/painters/dom/src/table/renderTableFragment.test.ts

@@ -1695,4 +1695,162 @@ describe('renderTableFragment', () => {
       expect(parsed2.segments[1][0].y).toBe(0);
     });
   });
+
+  describe('RTL table (bidiVisual)', () => {
+    it('mirrors ghost cell x positions for RTL tables with rowspan continuations', () => {
+      // 2-column RTL table where col 0 has rowSpan=2.
+      // Fragment 2 continues from fragment 1, so col 0 becomes a ghost cell.
+      const block: TableBlock = {
+        kind: 'table',
+        id: 'rtl-ghost-table' as BlockId,
+        attrs: {
+          tableProperties: { rightToLeft: true },
+          borders: {
+            top: { style: 'single', width: 1, color: '#000' },
+            bottom: { style: 'single', width: 1, color: '#000' },
+            insideH: { style: 'single', width: 1, color: '#000' },
+            insideV: { style: 'single', width: 1, color: '#000' },
+          },
+        },
+        rows: [
+          {
+            id: 'row-1' as BlockId,
+            cells: [
+              { id: 'c-1-1' as BlockId, paragraph: { kind: 'paragraph', id: 'p-1-1' as BlockId, runs: [] } },
+              { id: 'c-1-2' as BlockId, paragraph: { kind: 'paragraph', id: 'p-1-2' as BlockId, runs: [] } },
+            ],
+          },
+          {
+            id: 'row-2' as BlockId,
+            cells: [
+              { id: 'c-2-1' as BlockId, paragraph: { kind: 'paragraph', id: 'p-2-1' as BlockId, runs: [] } },
+              { id: 'c-2-2' as BlockId, paragraph: { kind: 'paragraph', id: 'p-2-2' as BlockId, runs: [] } },
+            ],
+          },
+        ],
+      };
+
+      const measure: TableMeasure = {
+        kind: 'table',
+        rows: [
+          {
+            cells: [
+              { width: 100, height: 20, gridColumnStart: 0, colSpan: 1, rowSpan: 2 },
+              { width: 200, height: 20, gridColumnStart: 1, colSpan: 1, rowSpan: 1 },
+            ],
+            height: 20,
+          },
+          {
+            cells: [{ width: 200, height: 20, gridColumnStart: 1, colSpan: 1, rowSpan: 1 }],
+            height: 20,
+          },
+        ],
+        columnWidths: [100, 200],
+        totalWidth: 300,
+        totalHeight: 40,
+      };
+
+      // Fragment 2: continuation from row 1 (only row 1 body, ghost for col 0)
+      const fragment: TableFragment = {
+        kind: 'table',
+        blockId: 'rtl-ghost-table' as BlockId,
+        fromRow: 1,
+        toRow: 2,
+        continuesFromPrev: true,
+        x: 0,
+        y: 0,
+        width: 300,
+        height: 20,
+      };
+
+      blockLookup.set('rtl-ghost-table', { block, measure });
+
+      const el = renderTableFragment({
+        doc,
+        fragment,
+        context,
+        blockLookup,
+        renderLine: () => doc.createElement('div'),
+        applyStyles: (e, s) => Object.assign(e.style, s),
+        applyFragmentFrame: () => {},
+        applySdtDataset: () => {},
+      });
+
+      // Ghost cell for col 0 (rowSpan=2, width=100) should be mirrored.
+      // In LTR: ghostX=0. In RTL: ghostX = 300 - 0 - 100 = 200.
+      const ghostCells = Array.from(el.querySelectorAll('div')).filter(
+        (d) => d.style.position === 'absolute' && d.style.overflow === 'hidden' && d.childElementCount === 0,
+      );
+
+      expect(ghostCells.length).toBeGreaterThanOrEqual(1);
+      const ghostLeft = parseFloat(ghostCells[0].style.left);
+      // Ghost should be on the right side (x=200), not left (x=0)
+      expect(ghostLeft).toBe(200);
+    });
+
+    it('passes isRtl to renderTableRow for body rows', () => {
+      const block: TableBlock = {
+        kind: 'table',
+        id: 'rtl-pass-table' as BlockId,
+        attrs: { tableProperties: { rightToLeft: true } },
+        rows: [
+          {
+            id: 'row-1' as BlockId,
+            cells: [
+              { id: 'c-1' as BlockId, paragraph: { kind: 'paragraph', id: 'p-1' as BlockId, runs: [] } },
+              { id: 'c-2' as BlockId, paragraph: { kind: 'paragraph', id: 'p-2' as BlockId, runs: [] } },
+            ],
+          },
+        ],
+      };
+
+      const measure: TableMeasure = {
+        kind: 'table',
+        rows: [
+          {
+            cells: [
+              { width: 100, height: 20, gridColumnStart: 0, colSpan: 1, rowSpan: 1 },
+              { width: 100, height: 20, gridColumnStart: 1, colSpan: 1, rowSpan: 1 },
+            ],
+            height: 20,
+          },
+        ],
+        columnWidths: [100, 100],
+        totalWidth: 200,
+        totalHeight: 20,
+      };
+
+      const fragment: TableFragment = {
+        kind: 'table',
+        blockId: 'rtl-pass-table' as BlockId,
+        fromRow: 0,
+        toRow: 1,
+        x: 0,
+        y: 0,
+        width: 200,
+        height: 20,
+      };
+
+      blockLookup.set('rtl-pass-table', { block, measure });
+
+      const el = renderTableFragment({
+        doc,
+        fragment,
+        context,
+        blockLookup,
+        renderLine: () => doc.createElement('div'),
+        applyStyles: (e, s) => Object.assign(e.style, s),
+        applyFragmentFrame: () => {},
+        applySdtDataset: () => {},
+      });
+
+      // Cells should be mirrored: col 0 at x=100, col 1 at x=0
+      const cells = Array.from(el.querySelectorAll('div')).filter(
+        (d) => d.style.position === 'absolute' && d.style.width === '100px',
+      );
+
+      const positions = cells.map((c) => parseFloat(c.style.left)).sort((a, b) => a - b);
+      expect(positions).toEqual([0, 100]);
+    });
+  });
 });