feat: support wide tables rendering outside of margins (#2823)

* feat: support wide tables rendering outside of margins

* fix: fix for multi-column layout

* fix: added missing tests and removed duplicated code

* test: add coverage for wide-table helpers (SD-2544 / SD-2545)

- direct unit tests for resolveTableWidthAttr (contracts) - the new public
  helper had no test of its own; covers width/value field, type passthrough,
  zero/negative/non-finite/null rejection.
- direct unit tests for resolveTableFrame and resolveRenderedTableWidth
  (layout-engine) - these are now exported and used by incrementalLayout, so
  worth testing in isolation: pct calculation, px/dxa fallback to measured,
  negative x for centered/right wide tables, indent + wide.
- pin the quiet behavior change for tableLayout: 'fixed' without an explicit
  tableWidth (measuring/dom) - grid widths wider than the column now pass
  through; previously they were scaled to fit.
- two click-to-position cases: legacy fragments without columnIndex fall back
  to visual x via determineColumn, and a fragment claiming a columnIndex past
  the document column count is clamped to the last valid column.

* chore: add/update comments

Author: VladaHarbour

packages/layout-engine/contracts/src/engines/__tests__/tables.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest';
+import { OOXML_PCT_DIVISOR, resolveTableWidthAttr } from '../tables.js';
+
+describe('OOXML_PCT_DIVISOR', () => {
+  it('equals 5000 (1/50th of a percent)', () => {
+    expect(OOXML_PCT_DIVISOR).toBe(5000);
+  });
+});
+
+describe('resolveTableWidthAttr', () => {
+  it('reads the width field with its type', () => {
+    expect(resolveTableWidthAttr({ width: 600, type: 'px' })).toEqual({ width: 600, type: 'px' });
+  });
+
+  it('reads the value field when width is not present', () => {
+    expect(resolveTableWidthAttr({ value: 2500, type: 'pct' })).toEqual({ width: 2500, type: 'pct' });
+  });
+
+  it('prefers width over value when both are present', () => {
+    expect(resolveTableWidthAttr({ width: 100, value: 200, type: 'px' })).toEqual({ width: 100, type: 'px' });
+  });
+
+  it('preserves type for dxa', () => {
+    expect(resolveTableWidthAttr({ width: 1440, type: 'dxa' })).toEqual({ width: 1440, type: 'dxa' });
+  });
+
+  it('returns width with undefined type when type is omitted', () => {
+    const result = resolveTableWidthAttr({ width: 300 });
+    expect(result).toEqual({ width: 300, type: undefined });
+  });
+
+  it('rejects null', () => {
+    expect(resolveTableWidthAttr(null)).toBeNull();
+  });
+
+  it('rejects undefined', () => {
+    expect(resolveTableWidthAttr(undefined)).toBeNull();
+  });
+
+  it('rejects primitives', () => {
+    expect(resolveTableWidthAttr(600)).toBeNull();
+    expect(resolveTableWidthAttr('600')).toBeNull();
+    expect(resolveTableWidthAttr(true)).toBeNull();
+  });
+
+  it('rejects objects with no width or value', () => {
+    expect(resolveTableWidthAttr({ type: 'px' })).toBeNull();
+    expect(resolveTableWidthAttr({})).toBeNull();
+  });
+
+  it('rejects non-numeric width', () => {
+    expect(resolveTableWidthAttr({ width: '600' as unknown as number, type: 'px' })).toBeNull();
+    expect(resolveTableWidthAttr({ value: null as unknown as number, type: 'pct' })).toBeNull();
+  });
+
+  it('rejects NaN', () => {
+    expect(resolveTableWidthAttr({ width: NaN, type: 'pct' })).toBeNull();
+  });
+
+  it('rejects Infinity', () => {
+    expect(resolveTableWidthAttr({ width: Infinity, type: 'pct' })).toBeNull();
+    expect(resolveTableWidthAttr({ width: -Infinity, type: 'pct' })).toBeNull();
+  });
+
+  it('rejects zero', () => {
+    expect(resolveTableWidthAttr({ width: 0, type: 'pct' })).toBeNull();
+    expect(resolveTableWidthAttr({ value: 0, type: 'pct' })).toBeNull();
+  });
+
+  it('rejects negative widths', () => {
+    expect(resolveTableWidthAttr({ width: -100, type: 'px' })).toBeNull();
+    expect(resolveTableWidthAttr({ value: -2500, type: 'pct' })).toBeNull();
+  });
+});

packages/layout-engine/contracts/src/engines/tables.ts

@@ -36,6 +36,29 @@ export interface TableWidthAttr {
   type?: 'pct' | 'px' | 'pixel' | string;
 }
 
+/**
+ * Extract a validated numeric width from a table width attribute object.
+ *
+ * Supports either `width` or `value` fields and rejects non-finite or non-positive
+ * values so callers can safely use the result in layout calculations.
+ */
+export function resolveTableWidthAttr(value: unknown): { width: number; type?: TableWidthAttr['type'] } | null {
+  if (!value || typeof value !== 'object') {
+    return null;
+  }
+
+  const measurement = value as TableWidthAttr;
+  const width = measurement.width ?? measurement.value;
+  if (typeof width !== 'number' || !Number.isFinite(width) || width <= 0) {
+    return null;
+  }
+
+  return {
+    width,
+    type: measurement.type,
+  };
+}
+
 export interface TableColumnSpec {
   type: 'auto' | 'fixed' | 'pct';
   width?: number; // pt or percentage (0-100)

packages/layout-engine/contracts/src/index.ts

@@ -5,7 +5,12 @@ export { computeTabStops, layoutWithTabs, calculateTabWidth } from './engines/ta
 export type { TabStop };
 
 // Export table contracts
-export { OOXML_PCT_DIVISOR, type TableWidthAttr, type TableColumnSpec } from './engines/tables.js';
+export {
+  OOXML_PCT_DIVISOR,
+  resolveTableWidthAttr,
+  type TableWidthAttr,
+  type TableColumnSpec,
+} from './engines/tables.js';
 
 export { effectiveTableCellSpacing } from './table-cell-spacing.js';
 
@@ -1885,6 +1890,8 @@ export type PartialRowInfo = {
 export type TableFragment = {
   kind: 'table';
   blockId: BlockId;
+  /** Flow column that owns this fragment, distinct from visual x when overflow crosses margins. */
+  columnIndex?: number;
   fromRow: number;
   toRow: number;
   x: number;

packages/layout-engine/layout-bridge/src/incrementalLayout.ts

@@ -9,7 +9,7 @@ import type {
   SectionBreakBlock,
   NormalizedColumnLayout,
 } from '@superdoc/contracts';
-import { cloneColumnLayout, normalizeColumnLayout } from '@superdoc/contracts';
+import { cloneColumnLayout, normalizeColumnLayout, rescaleColumnWidths } from '@superdoc/contracts';
 import {
   layoutDocument,
   layoutHeaderFooter,
@@ -20,6 +20,7 @@ import {
   type NumberingContext,
   SEMANTIC_PAGE_HEIGHT_PX,
   SINGLE_COLUMN_DEFAULT,
+  resolveTableFrame,
 } from '@superdoc/layout-engine';
 import { remeasureParagraph } from './remeasure';
 import { computeDirtyRegions } from './diff';
@@ -228,7 +229,9 @@ const assignFootnotesToColumns = (
 
     if (columns && columns.count > 1 && page) {
       const fragment = findFragmentForPos(page, ref.pos);
-      if (fragment && typeof fragment.x === 'number') {
+      if (fragment?.kind === 'table' && typeof fragment.columnIndex === 'number') {
+        columnIndex = Math.max(0, Math.min(columns.count - 1, fragment.columnIndex));
+      } else if (fragment && typeof fragment.x === 'number') {
         const widths = Array.isArray(columns.widths) && columns.widths.length > 0 ? columns.widths : undefined;
         if (widths) {
           let cursorX = columns.left;
@@ -1728,46 +1731,27 @@ export async function incrementalLayout(
                   const block = blockById.get(range.blockId);
                   if (!measure || measure.kind !== 'table') return;
                   if (!block || block.kind !== 'table') return;
-                  const tableWidthRaw = Math.max(0, measure.totalWidth ?? 0);
-                  let tableWidth = Math.min(contentWidth, tableWidthRaw);
-                  let tableX = columnX;
-                  const justification =
-                    typeof block.attrs?.justification === 'string' ? block.attrs.justification : undefined;
-                  if (justification === 'center') {
-                    tableX = columnX + Math.max(0, (contentWidth - tableWidth) / 2);
-                  } else if (justification === 'right' || justification === 'end') {
-                    tableX = columnX + Math.max(0, contentWidth - tableWidth);
-                  } else {
-                    const indentValue = (block.attrs?.tableIndent as { width?: unknown } | undefined)?.width;
-                    const indent = typeof indentValue === 'number' && Number.isFinite(indentValue) ? indentValue : 0;
-                    tableX += indent;
-                    tableWidth = Math.max(0, tableWidth - indent);
-                  }
-                  // Rescale column widths when table was clamped to section width.
-                  // This happens in mixed-orientation docs where measurement uses the
-                  // widest section but rendering is per-section (SD-1859).
-                  let fragmentColumnWidths: number[] | undefined;
-                  if (
-                    tableWidthRaw > tableWidth &&
-                    measure.columnWidths &&
-                    measure.columnWidths.length > 0 &&
-                    tableWidthRaw > 0
-                  ) {
-                    const scale = tableWidth / tableWidthRaw;
-                    fragmentColumnWidths = measure.columnWidths.map((w: number) => Math.max(1, Math.round(w * scale)));
-                    const scaledSum = fragmentColumnWidths.reduce((a: number, b: number) => a + b, 0);
-                    const target = Math.round(tableWidth);
-                    if (scaledSum !== target && fragmentColumnWidths.length > 0) {
-                      fragmentColumnWidths[fragmentColumnWidths.length - 1] = Math.max(
-                        1,
-                        fragmentColumnWidths[fragmentColumnWidths.length - 1] + (target - scaledSum),
-                      );
-                    }
-                  }
+                  const tableWidthRaw = Math.max(0, measure.totalWidth ?? contentWidth);
+                  const { x: tableX, width: tableWidth } = resolveTableFrame(
+                    columnX,
+                    contentWidth,
+                    tableWidthRaw,
+                    block.attrs,
+                  );
+                  // Rescale column widths only when the resolved fragment width is narrower
+                  // than the measured table width. Today that primarily happens for
+                  // percentage-width tables rendered in a narrower section (SD-1859),
+                  // while non-percent wide tables keep their measured overflow width.
+                  const fragmentColumnWidths = rescaleColumnWidths(
+                    measure.columnWidths,
+                    measure.totalWidth,
+                    tableWidth,
+                  );
 
                   page.fragments.push({
                     kind: 'table',
                     blockId: range.blockId,
+                    columnIndex,
                     fromRow: 0,
                     toRow: block.rows.length,
                     x: tableX,

packages/layout-engine/layout-bridge/src/position-hit.ts

@@ -143,6 +143,14 @@ export const determineColumn = (layout: Layout, fragmentX: number): number => {
   return Math.max(0, Math.min(columns.count - 1, raw));
 };
 
+const determineTableColumn = (layout: Layout, fragment: TableFragment): number => {
+  if (typeof fragment.columnIndex === 'number') {
+    const count = layout.columns?.count ?? 1;
+    return Math.max(0, Math.min(Math.max(0, count - 1), fragment.columnIndex));
+  }
+  return determineColumn(layout, fragment.x);
+};
+
 // ---------------------------------------------------------------------------
 // Line / position helpers
 // ---------------------------------------------------------------------------
@@ -935,7 +943,7 @@ export function clickToPositionGeometry(
           layoutEpoch,
           blockId: tableHit.fragment.blockId,
           pageIndex,
-          column: determineColumn(layout, tableHit.fragment.x),
+          column: determineTableColumn(layout, tableHit.fragment),
           lineIndex,
         };
       }
@@ -949,7 +957,7 @@ export function clickToPositionGeometry(
         layoutEpoch,
         blockId: tableHit.fragment.blockId,
         pageIndex,
-        column: determineColumn(layout, tableHit.fragment.x),
+        column: determineTableColumn(layout, tableHit.fragment),
         lineIndex: 0,
       };
     }