@react-x11/components 0.1.0 → 0.2.1

package/src/html/layout/table.ts

@@ -0,0 +1,380 @@
+// Table layout.
+//
+// Tables earn a formatting context of their own here rather than being
+// approximated with flex, because the thing a table does that nothing else
+// does is **size a column from every cell in it** — a constraint that runs
+// across the grain of the box tree, and the reason a table cannot be
+// expressed as nested rows of boxes without measuring twice and guessing.
+//
+// The documents this component exists for are full of them: exported
+// reports, mail, anything generated by a template. So the auto algorithm is
+// implemented rather than stubbed, and `table-layout: fixed` is implemented
+// beside it because that is the one an author reaches for when the auto
+// algorithm is too slow — which, on a table with a thousand rows, it is.
+import { AUTO, isPct, resolveOrNull } from '../css/values.js';
+import type { Len } from '../css/values.js';
+import { Box } from './boxes.js';
+import { measureIntrinsicWidth, moveTo, resolveEdges } from './block.js';
+import type { LayoutContext } from './block.js';
+
+interface Cell {
+  box: Box;
+  row: number;
+  column: number;
+  colSpan: number;
+  rowSpan: number;
+}
+
+/** Lay out a table's insides. Returns the content height. */
+export function layoutTable(
+  table: Box,
+  ctx: LayoutContext,
+  contentWidth: number,
+): number {
+  const rows: Box[] = [];
+  const captions: Box[] = [];
+  for (const child of table.children) {
+    if (child.kind === 'table-caption') captions.push(child);
+    else if (child.kind === 'table-row-group') {
+      for (const row of child.children) {
+        if (row.kind === 'table-row') rows.push(row);
+      }
+    } else if (child.kind === 'table-row') rows.push(child);
+  }
+
+  const { cells, columnCount } = gridOf(rows);
+  if (!columnCount)
+    return layoutCaptionsOnly(captions, ctx, table, contentWidth);
+
+  const style = table.style;
+  const spacing = style.borderCollapse === 'collapse' ? 0 : style.borderSpacing;
+  const gaps = spacing * (columnCount + 1);
+  const available = Math.max(0, contentWidth - gaps);
+
+  for (const cell of cells) resolveEdges(cell.box, contentWidth);
+
+  const widths =
+    style.tableLayout === 'fixed'
+      ? fixedColumns(table, cells, columnCount, available)
+      : autoColumns(cells, columnCount, available, ctx, contentWidth);
+
+  // --- place ---------------------------------------------------------------
+  let y = table.contentY;
+  for (const caption of captions) {
+    resolveEdges(caption, contentWidth);
+    ctx.layoutSubtree(caption, contentWidth);
+    moveTo(caption, table.contentX, y);
+    y += caption.height;
+  }
+
+  const columnX: number[] = new Array<number>(columnCount);
+  let x = table.contentX + spacing;
+  for (let c = 0; c < columnCount; c += 1) {
+    columnX[c] = x;
+    x += widths[c] + spacing;
+  }
+  // A table with `width: auto` is as wide as its columns need, not as wide as
+  // its container — it shrinks to fit, which is what makes a two-column table
+  // in a wide document a small table rather than a pair of columns stranded
+  // at the left of a full-width box. The columns were sized against the space
+  // on offer, so this only ever narrows.
+  const used = Math.min(x - table.contentX, contentWidth);
+  const tableContentWidth = style.width === AUTO ? used : contentWidth;
+  if (style.width === AUTO)
+    table.width = tableContentWidth + table.horizontalExtra;
+
+  const rowTop: number[] = new Array<number>(rows.length);
+  const rowHeight: number[] = new Array<number>(rows.length).fill(0);
+  y += spacing;
+
+  // Size every cell at its column width first, so a row's height is the
+  // tallest cell in it rather than the first one that was measured.
+  for (const cell of cells) {
+    const width = spannedWidth(widths, cell, spacing);
+    ctx.layoutSubtree(cell.box, width);
+    const specified = resolveOrNull(cell.box.style.height, NaN);
+    if (specified !== null) {
+      cell.box.height = Math.max(
+        cell.box.height,
+        specified + cell.box.verticalExtra,
+      );
+    }
+  }
+  for (const cell of cells) {
+    if (cell.rowSpan > 1) continue;
+    rowHeight[cell.row] = Math.max(rowHeight[cell.row], cell.box.height);
+  }
+  for (let r = 0; r < rows.length; r += 1) {
+    const specified = resolveOrNull(rows[r].style.height, NaN);
+    if (specified !== null) rowHeight[r] = Math.max(rowHeight[r], specified);
+  }
+  // A row-spanning cell only forces height when the rows it covers do not
+  // already provide it — otherwise a `rowspan="3"` cell would make each of
+  // its three rows as tall as all of it.
+  for (const cell of cells) {
+    if (cell.rowSpan <= 1) continue;
+    const last = Math.min(rows.length - 1, cell.row + cell.rowSpan - 1);
+    let covered = 0;
+    for (let r = cell.row; r <= last; r += 1) covered += rowHeight[r];
+    covered += spacing * (last - cell.row);
+    const missing = cell.box.height - covered;
+    if (missing > 0) rowHeight[last] += missing;
+  }
+
+  for (let r = 0; r < rows.length; r += 1) {
+    rowTop[r] = y;
+    y += rowHeight[r] + spacing;
+  }
+
+  for (const cell of cells) {
+    const last = Math.min(rows.length - 1, cell.row + cell.rowSpan - 1);
+    let height = 0;
+    for (let r = cell.row; r <= last; r += 1) height += rowHeight[r];
+    height += spacing * (last - cell.row);
+    const width = spannedWidth(widths, cell, spacing);
+    const inner = cell.box.height;
+    // `vertical-align` inside a cell moves the *content*, not the box: the
+    // box fills the row, and the content sits top, middle or bottom in it.
+    let offset = 0;
+    const va = cell.box.style.verticalAlign;
+    if (va === 'middle') offset = Math.max(0, (height - inner) / 2);
+    else if (va === 'bottom') offset = Math.max(0, height - inner);
+    moveTo(cell.box, columnX[cell.column], rowTop[cell.row] + offset);
+    cell.box.width = width;
+    cell.box.height = Math.max(inner, height - offset);
+  }
+
+  for (let r = 0; r < rows.length; r += 1) {
+    const row = rows[r];
+    row.x = table.contentX;
+    row.y = rowTop[r];
+    row.width = tableContentWidth;
+    row.height = rowHeight[r];
+  }
+  for (const child of table.children) {
+    if (child.kind !== 'table-row-group') continue;
+    const groupRows = child.children.filter((row) => row.kind === 'table-row');
+    if (!groupRows.length) continue;
+    child.x = table.contentX;
+    child.y = groupRows[0].y;
+    child.width = tableContentWidth;
+    child.height =
+      groupRows[groupRows.length - 1].y +
+      groupRows[groupRows.length - 1].height -
+      child.y;
+  }
+
+  return y - table.contentY;
+}
+
+function layoutCaptionsOnly(
+  captions: Box[],
+  ctx: LayoutContext,
+  table: Box,
+  contentWidth: number,
+): number {
+  let y = table.contentY;
+  for (const caption of captions) {
+    resolveEdges(caption, contentWidth);
+    ctx.layoutSubtree(caption, contentWidth);
+    moveTo(caption, table.contentX, y);
+    y += caption.height;
+  }
+  return y - table.contentY;
+}
+
+function spannedWidth(widths: number[], cell: Cell, spacing: number): number {
+  let width = 0;
+  const last = Math.min(widths.length - 1, cell.column + cell.colSpan - 1);
+  for (let c = cell.column; c <= last; c += 1) width += widths[c];
+  return width + spacing * (last - cell.column);
+}
+
+/**
+ * Assign every cell a row and a column, honouring `colspan` and `rowspan`.
+ * The occupancy grid is what makes a `rowspan` in an earlier row push a
+ * later row's cells to the right, which is the bug every naive table
+ * renderer ships with.
+ */
+function gridOf(rows: Box[]): { cells: Cell[]; columnCount: number } {
+  const cells: Cell[] = [];
+  const occupied: boolean[][] = [];
+  let columnCount = 0;
+
+  const mark = (r: number, c: number): void => {
+    (occupied[r] ??= [])[c] = true;
+  };
+  const taken = (r: number, c: number): boolean => occupied[r]?.[c] === true;
+
+  for (let r = 0; r < rows.length; r += 1) {
+    let c = 0;
+    for (const box of rows[r].children) {
+      if (box.kind !== 'table-cell') continue;
+      while (taken(r, c)) c += 1;
+      const colSpan = Math.max(1, spanAttr(box, 'colspan'));
+      const rowSpan = Math.max(1, spanAttr(box, 'rowspan'));
+      cells.push({ box, row: r, column: c, colSpan, rowSpan });
+      for (let dr = 0; dr < rowSpan; dr += 1) {
+        for (let dc = 0; dc < colSpan; dc += 1) mark(r + dr, c + dc);
+      }
+      c += colSpan;
+      columnCount = Math.max(columnCount, c);
+    }
+  }
+  return { cells, columnCount };
+}
+
+function spanAttr(box: Box, name: string): number {
+  const raw = box.el?.attribs?.[name];
+  if (!raw) return 1;
+  const n = parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? Math.min(n, 1000) : 1;
+}
+
+/** `table-layout: fixed` — the first row and any `width` decide, and the
+ *  rest of the table is not measured at all. That is the whole point of it. */
+function fixedColumns(
+  table: Box,
+  cells: Cell[],
+  columnCount: number,
+  available: number,
+): number[] {
+  const widths: number[] = new Array<number>(columnCount).fill(0);
+  const fixed: boolean[] = new Array<boolean>(columnCount).fill(false);
+  for (const cell of cells) {
+    if (cell.row > 0) break;
+    const len = cell.box.style.width;
+    if (len === AUTO) continue;
+    const px = lengthAgainst(len, available);
+    if (px === null) continue;
+    const per = px / cell.colSpan;
+    for (
+      let c = cell.column;
+      c < cell.column + cell.colSpan && c < columnCount;
+      c += 1
+    ) {
+      widths[c] = per;
+      fixed[c] = true;
+    }
+  }
+  const used = widths.reduce((a, b) => a + b, 0);
+  const remaining = Math.max(0, available - used);
+  const autoCount = fixed.filter((f) => !f).length;
+  const each = autoCount ? remaining / autoCount : 0;
+  for (let c = 0; c < columnCount; c += 1) if (!fixed[c]) widths[c] = each;
+  // A table narrower than its container keeps the width it asked for; one
+  // wider than it is left wide and overflows, which is what a browser does
+  // and what makes an oversized table scrollable rather than crushed.
+  const total = widths.reduce((a, b) => a + b, 0);
+  if (total < available && table.style.width !== AUTO) {
+    const scale = available / (total || 1);
+    for (let c = 0; c < columnCount; c += 1) widths[c] *= scale;
+  }
+  return widths;
+}
+
+/**
+ * The auto algorithm: measure every cell's max-content and min-content
+ * width, then distribute.
+ *
+ * The distribution is the part worth stating. When the max-content widths
+ * fit, they are used — a small table is exactly as wide as its contents.
+ * When they do not, the surplus over each column's minimum is scaled down in
+ * proportion, so a column of long prose gives up more than a column of
+ * dates. A column with an explicit `width` is honoured before either.
+ */
+function autoColumns(
+  cells: Cell[],
+  columnCount: number,
+  available: number,
+  ctx: LayoutContext,
+  containingWidth: number,
+): number[] {
+  const max: number[] = new Array<number>(columnCount).fill(0);
+  const min: number[] = new Array<number>(columnCount).fill(0);
+  const explicit: (number | null)[] = new Array<number | null>(
+    columnCount,
+  ).fill(null);
+
+  for (const cell of cells) {
+    // Two probe layouts per cell: unconstrained for max-content, and at a
+    // width of 1 for min-content — which the line breaker answers by
+    // breaking at every opportunity, so the widest line is the longest
+    // unbreakable word.
+    //
+    // Cached on the box, because intrinsic widths are width-independent by
+    // definition — measuring them per layout pass made a *resize* of a
+    // 500-row table cost as much as its first layout (223ms of re-probing
+    // measured against 10ms with the cache). The cache's invalidation rule
+    // is the box's lifetime: any DOM or style change rebuilds the tree.
+    if (cell.box.intrinsicMaxContent < 0) {
+      cell.box.intrinsicMaxContent = measureIntrinsicWidth(
+        cell.box,
+        ctx,
+        Infinity,
+      );
+      cell.box.intrinsicMinContent = measureIntrinsicWidth(cell.box, ctx, 1);
+    }
+    const cellMax = cell.box.intrinsicMaxContent;
+    const cellMin = cell.box.intrinsicMinContent;
+
+    const len = cell.box.style.width;
+    const width = len === AUTO ? null : lengthAgainst(len, containingWidth);
+    if (cell.colSpan === 1) {
+      max[cell.column] = Math.max(max[cell.column], cellMax);
+      min[cell.column] = Math.max(min[cell.column], cellMin);
+      if (width !== null) {
+        explicit[cell.column] = Math.max(
+          explicit[cell.column] ?? 0,
+          width + cell.box.horizontalExtra,
+        );
+      }
+    } else {
+      // A spanning cell contributes to its columns only when they cannot
+      // already hold it, spread evenly — which is the spec's rule reduced to
+      // the part that matters visually.
+      const last = Math.min(columnCount - 1, cell.column + cell.colSpan - 1);
+      let currentMax = 0;
+      let currentMin = 0;
+      for (let c = cell.column; c <= last; c += 1) {
+        currentMax += max[c];
+        currentMin += min[c];
+      }
+      const spread = last - cell.column + 1;
+      if (cellMax > currentMax) {
+        const each = (cellMax - currentMax) / spread;
+        for (let c = cell.column; c <= last; c += 1) max[c] += each;
+      }
+      if (cellMin > currentMin) {
+        const each = (cellMin - currentMin) / spread;
+        for (let c = cell.column; c <= last; c += 1) min[c] += each;
+      }
+    }
+  }
+
+  for (let c = 0; c < columnCount; c += 1) {
+    if (explicit[c] !== null) {
+      max[c] = Math.max(max[c], explicit[c] as number);
+      min[c] = Math.max(min[c], Math.min(explicit[c] as number, max[c]));
+    }
+    min[c] = Math.min(min[c], max[c]);
+  }
+
+  const totalMax = max.reduce((a, b) => a + b, 0);
+  if (totalMax <= available) {
+    // Everything fits. A table with an explicit width still fills it, by
+    // growing the columns in proportion to what they asked for.
+    return max;
+  }
+  const totalMin = min.reduce((a, b) => a + b, 0);
+  if (totalMin >= available) return min;
+  const slack = available - totalMin;
+  const surplus = totalMax - totalMin;
+  return max.map((m, c) => min[c] + ((m - min[c]) / surplus) * slack);
+}
+
+function lengthAgainst(len: Len, base: number): number | null {
+  if (len === AUTO) return null;
+  if (isPct(len)) return Number.isFinite(base) ? (len.pct / 100) * base : null;
+  return len;
+}