@xeplr/ui-table 1.0.1 → 1.0.3

package/src/tableStyles.js

@@ -0,0 +1,236 @@
+/**
+ * The table's style vocabulary, and the rule for resolving it.
+ *
+ * This is the "clear interface" the whole styling feature hangs off: one
+ * registry naming every style property a table cell can take, and one pure
+ * function that decides which layer's value wins. No React, no DOM, no
+ * persistence — a host supplies layers (theme defaults, workspace theme,
+ * widget theme, per-column/row/cell overrides) and gets back a CSS object.
+ *
+ * THREE THINGS WORTH KNOWING BEFORE CHANGING ANY OF THIS:
+ *
+ * 1. Properties are addressed by PATH, not name — 'border.top.width', not
+ *    'borderWidth'. Merging happens per leaf path, which is what stops a
+ *    column setting border.bottom.color from wiping a cell's border.top.width.
+ *
+ * 2. `border.all` is expanded into the four sides at FLATTEN time, inside its
+ *    own layer. That ordering is load-bearing. If it were expanded after
+ *    merging, a theme that set border.top.width would survive a column that
+ *    set border.all.width — the user would set the column's border to thin
+ *    and watch one edge stay thick.
+ *
+ * 3. `margin` is deliberately absent. A <td> is not a block box and discards
+ *    margin entirely; offering the control would be offering a lie. Margin
+ *    belongs to the table as a whole, which a host lays out itself.
+ */
+
+var LENGTH_UNITS = ['px', 'em', 'rem'];
+
+var FONT_FAMILY_OPTIONS = [
+  ['inherit', 'Inherit'], ['sans-serif', 'Sans'], ['serif', 'Serif'], ['monospace', 'Mono']
+];
+var FONT_WEIGHT_OPTIONS = [['400', 'Regular'], ['500', 'Medium'], ['600', 'Semibold'], ['700', 'Bold']];
+var BORDER_STYLE_OPTIONS = [
+  ['none', 'None'], ['solid', 'Solid'], ['dashed', 'Dashed'], ['dotted', 'Dotted'], ['double', 'Double']
+];
+
+var TEXT_FIELDS = [
+  { key: 'text.color', label: 'Text color', type: 'color', css: 'color' },
+  { key: 'text.fontFamily', label: 'Font', type: 'select', css: 'fontFamily', options: FONT_FAMILY_OPTIONS },
+  { key: 'text.fontSize', label: 'Size', type: 'length', css: 'fontSize', units: LENGTH_UNITS },
+  { key: 'text.fontWeight', label: 'Weight', type: 'select', css: 'fontWeight', options: FONT_WEIGHT_OPTIONS },
+  { key: 'text.fontStyle', label: 'Style', type: 'select', css: 'fontStyle', options: [['normal', 'Normal'], ['italic', 'Italic']] },
+  { key: 'text.textAlign', label: 'Align', type: 'select', css: 'textAlign', options: [['left', 'Left'], ['center', 'Center'], ['right', 'Right'], ['justify', 'Justify']] },
+  { key: 'text.verticalAlign', label: 'Vertical', type: 'select', css: 'verticalAlign', options: [['top', 'Top'], ['middle', 'Middle'], ['bottom', 'Bottom']] },
+  { key: 'text.textTransform', label: 'Case', type: 'select', css: 'textTransform', options: [['none', 'None'], ['uppercase', 'UPPER'], ['lowercase', 'lower'], ['capitalize', 'Capitalize']] },
+  { key: 'text.textDecoration', label: 'Decoration', type: 'select', css: 'textDecoration', options: [['none', 'None'], ['underline', 'Underline'], ['line-through', 'Strikethrough']] },
+  { key: 'text.lineHeight', label: 'Line height', type: 'number', css: 'lineHeight', min: 0.8, max: 3, step: 0.1 },
+  { key: 'text.letterSpacing', label: 'Letter spacing', type: 'length', css: 'letterSpacing', units: LENGTH_UNITS },
+  // Wrapping is a style choice a report designer genuinely makes per column —
+  // a code column reads better on one line even if it clips.
+  { key: 'text.whiteSpace', label: 'Wrapping', type: 'select', css: 'whiteSpace', options: [['normal', 'Wrap'], ['nowrap', 'No wrap'], ['pre-wrap', 'Preserve']] }
+];
+
+var FILL_FIELDS = [
+  { key: 'fill.background', label: 'Background', type: 'color', css: 'background' }
+];
+
+var BOX_FIELDS = [
+  { key: 'box.padding.top', label: 'Padding top', type: 'length', css: 'paddingTop', units: LENGTH_UNITS },
+  { key: 'box.padding.right', label: 'Padding right', type: 'length', css: 'paddingRight', units: LENGTH_UNITS },
+  { key: 'box.padding.bottom', label: 'Padding bottom', type: 'length', css: 'paddingBottom', units: LENGTH_UNITS },
+  { key: 'box.padding.left', label: 'Padding left', type: 'length', css: 'paddingLeft', units: LENGTH_UNITS },
+  { key: 'box.height', label: 'Height', type: 'length', css: 'height', units: LENGTH_UNITS }
+];
+
+/** 'all' is a shorthand the user edits; it never reaches CSS (see note 2). */
+export var BORDER_SIDES = ['top', 'right', 'bottom', 'left'];
+
+function borderFieldsFor(side) {
+  var prefix = 'border.' + side + '.';
+  var cap = side === 'all' ? null : side.charAt(0).toUpperCase() + side.slice(1);
+  return [
+    { key: prefix + 'width', label: 'Width', type: 'length', units: LENGTH_UNITS, css: cap && 'border' + cap + 'Width', side: side },
+    { key: prefix + 'style', label: 'Style', type: 'select', options: BORDER_STYLE_OPTIONS, css: cap && 'border' + cap + 'Style', side: side },
+    { key: prefix + 'color', label: 'Color', type: 'color', css: cap && 'border' + cap + 'Color', side: side }
+  ];
+}
+
+var BORDER_FIELDS = [{ key: 'border.radius', label: 'Radius', type: 'length', css: 'borderRadius', units: LENGTH_UNITS }]
+  .concat(borderFieldsFor('all'))
+  .concat(BORDER_SIDES.reduce(function(acc, side) { return acc.concat(borderFieldsFor(side)); }, []));
+
+/**
+ * The whole vocabulary, grouped for panel generation. A host builds its panel
+ * from this and nothing else — adding a stylable property means adding one
+ * entry here, and it appears everywhere with no other change.
+ */
+export var STYLE_GROUPS = [
+  { key: 'text', label: 'Text', fields: TEXT_FIELDS },
+  { key: 'fill', label: 'Fill', fields: FILL_FIELDS },
+  { key: 'box', label: 'Spacing & size', fields: BOX_FIELDS },
+  // Sides are collapsed behind an expander in the UI: 'all' by default, with
+  // each side openable to override just that edge.
+  { key: 'border', label: 'Border', fields: BORDER_FIELDS, expandable: BORDER_SIDES }
+];
+
+export var STYLE_FIELDS = STYLE_GROUPS.reduce(function(acc, g) { return acc.concat(g.fields); }, []);
+
+var FIELD_BY_PATH = {};
+STYLE_FIELDS.forEach(function(f) { FIELD_BY_PATH[f.key] = f; });
+
+export function styleField(path) { return FIELD_BY_PATH[path] || null; }
+
+// ── Values ────────────────────────────────────────────────────────────────
+
+/**
+ * A length is stored as { value, unit } so the unit survives a round trip and
+ * the panel can show it. Bare numbers mean px; strings pass through untouched
+ * (so a host can store 'auto' or a var() reference).
+ */
+export function cssLength(value) {
+  if (value === null || value === undefined || value === '') return null;
+  if (typeof value === 'number') return value + 'px';
+  if (typeof value === 'string') return value;
+  if (typeof value.value !== 'number' && !value.value) return null;
+  return value.value + (value.unit || 'px');
+}
+
+// ── Flatten ───────────────────────────────────────────────────────────────
+
+function walk(node, prefix, out) {
+  Object.keys(node).forEach(function(key) {
+    var value = node[key];
+    var path = prefix ? prefix + '.' + key : key;
+    // A {value, unit} pair is a leaf, not a branch to descend into.
+    var isLeaf = value === null || typeof value !== 'object' ||
+      Object.prototype.hasOwnProperty.call(value, 'value');
+    if (isLeaf) out[path] = value;
+    else walk(value, path, out);
+  });
+}
+
+/**
+ * Nested style object -> flat { path: value }, with border.all expanded into
+ * the four sides. An explicit side inside the SAME object beats 'all'; see
+ * note 2 at the top for why that expansion has to happen here.
+ */
+export function flattenStyle(style) {
+  var flat = {};
+  if (!style) return flat;
+  walk(style, '', flat);
+
+  ['width', 'style', 'color'].forEach(function(part) {
+    var all = flat['border.all.' + part];
+    if (all === undefined) return;
+    BORDER_SIDES.forEach(function(side) {
+      var path = 'border.' + side + '.' + part;
+      if (flat[path] === undefined) flat[path] = all;
+    });
+  });
+  delete flat['border.all.width'];
+  delete flat['border.all.style'];
+  delete flat['border.all.color'];
+  return flat;
+}
+
+// ── Resolve ───────────────────────────────────────────────────────────────
+
+/**
+ * Decide, per property, which layer wins.
+ *
+ * @param {Array<{id, style, rank?, at?}>} layers - Low precedence first.
+ *   `rank` defaults to array position. Layers that genuinely compete — a cell,
+ *   row and column override all landing on the same cell — share one rank and
+ *   are separated by `at` (a timestamp), so the most recent edit wins.
+ *
+ *   The timestamp is a TIEBREAK, not a winner-takes-all: it is consulted per
+ *   property. A column setting a background and a cell setting a font weight
+ *   both apply, whichever was edited last. Only when both set the SAME
+ *   property does recency decide. Whole-record precedence would mean
+ *   restyling a column silently discarded deliberate per-cell work.
+ *
+ * @returns {object} { path: { value, source, at } }
+ */
+export function resolveStyle(layers) {
+  var resolved = {};
+  (layers || []).forEach(function(layer, index) {
+    if (!layer || !layer.style) return;
+    var rank = layer.rank === undefined ? index : layer.rank;
+    var at = layer.at === undefined ? null : layer.at;
+    var flat = flattenStyle(layer.style);
+
+    Object.keys(flat).forEach(function(path) {
+      var value = flat[path];
+      if (value === null || value === undefined || value === '') return;
+      var held = resolved[path];
+      if (held) {
+        if (rank < held.rank) return;
+        if (rank === held.rank && at !== null && held.at !== null && at < held.at) return;
+        if (rank === held.rank && at === null && held.at !== null) return;
+      }
+      resolved[path] = { value: value, source: layer.id, at: at, rank: rank };
+    });
+  });
+  return resolved;
+}
+
+// ── Emit ──────────────────────────────────────────────────────────────────
+
+/**
+ * Resolved paths -> a React style object.
+ *
+ * Accepts either the output of resolveStyle or a plain { path: value } map,
+ * so a caller with a single style object can skip resolution entirely.
+ */
+export function toCssProperties(resolved) {
+  var css = {};
+  if (!resolved) return css;
+
+  Object.keys(resolved).forEach(function(path) {
+    var field = FIELD_BY_PATH[path];
+    if (!field || !field.css) return; // unknown path, or border.all — never emitted
+    var entry = resolved[path];
+    var value = entry && typeof entry === 'object' && Object.prototype.hasOwnProperty.call(entry, 'source')
+      ? entry.value : entry;
+    if (value === null || value === undefined || value === '') return;
+    css[field.css] = field.type === 'length' ? cssLength(value) : value;
+  });
+
+  // A border width with no style renders nothing at all — CSS defaults
+  // border-style to none. Someone setting "3px" and seeing no border would
+  // reasonably call that broken, so an unstated style means solid.
+  BORDER_SIDES.forEach(function(side) {
+    var cap = side.charAt(0).toUpperCase() + side.slice(1);
+    if (css['border' + cap + 'Width'] && !css['border' + cap + 'Style']) {
+      css['border' + cap + 'Style'] = 'solid';
+    }
+  });
+
+  return css;
+}
+
+/** The common case: layers in, CSS out. */
+export function resolveCellCss(layers) {
+  return toCssProperties(resolveStyle(layers));
+}

package/src/useColumnWidths.js

@@ -0,0 +1,280 @@
+import { useState, useRef, useLayoutEffect, useCallback } from 'react';
+import { measureColumnDemand, allocateColumnWidths, resolvePercentWidths } from './columnWidths.js';
+
+/**
+ * Content-based column widths — the DOM half. See columnWidths.js for the
+ * allocation rule itself; this file only supplies it with real numbers.
+ *
+ * "Use the font scale" is handled by measuring rather than configuring: the
+ * font is read off an actual rendered <td>/<th>, so if a host shrinks the type
+ * (a compact theme, say) every column narrows to match with no width setting
+ * anywhere. The same goes for cell padding — it's read from the DOM, not
+ * duplicated as a constant that would drift the first time the CSS changes.
+ */
+
+// Sentinel handed to the pure measurer in place of a font string, meaning
+// "whichever of the body's fonts renders this widest" — see measureWidest.
+var BODY_FONTS = '@@body-fonts@@';
+var MAX_BODY_FONTS = 3;
+
+var DEFAULTS = {
+  sampleRows: 200,
+  minWidth: 40,
+  maxWidth: 420,
+  maxFloor: 220
+};
+
+// Canvas measureText is exact for proportional fonts and costs microseconds.
+// One canvas is shared across every table on the page; it's never attached to
+// the document, so it holds a single backing store regardless of table count.
+var sharedCanvas = null;
+function textMeasurer() {
+  if (typeof document === 'undefined') return null;
+  if (!sharedCanvas) sharedCanvas = document.createElement('canvas');
+  var ctx = sharedCanvas.getContext('2d');
+  if (!ctx) return null;
+  var cache = new Map();
+  return function measure(text, font) {
+    if (!text) return 0;
+    var cacheKey = font + '' + text;
+    var hit = cache.get(cacheKey);
+    if (hit !== undefined) return hit;
+    ctx.font = font;
+    var width = ctx.measureText(text).width;
+    cache.set(cacheKey, width);
+    return width;
+  };
+}
+
+function fontOf(style) {
+  return (style.fontStyle && style.fontStyle !== 'normal' ? style.fontStyle + ' ' : '') +
+    (style.fontWeight || 400) + ' ' +
+    (style.fontSize || '14px') + ' ' +
+    (style.fontFamily || 'sans-serif');
+}
+
+/**
+ * Hosts routinely rebuild their column array inline on every render, so the
+ * effect below cannot use array identity to decide whether to re-measure —
+ * it would re-measure forever. This is the real question: has anything that
+ * could change a width changed?
+ *
+ * Cell FORMATTING is deliberately not part of this (the host's columnText is
+ * usually a fresh closure each render too). Hosts signal that with sizingKey.
+ */
+function signatureOf(columns, containerWidth, sizingKey, overrides) {
+  var parts = [containerWidth, columns.length];
+  for (var i = 0; i < columns.length; i++) {
+    parts.push(columns[i].accessor, columns[i].header || '');
+  }
+  parts.push(typeof sizingKey === 'object' ? JSON.stringify(sizingKey) : String(sizingKey));
+  // Overrides MUST be in here. They change widths, and this signature is the
+  // only thing deciding whether the effect below does anything at all — leave
+  // them out and setting a width is a no-op with no error and no clue.
+  // Stringified rather than identity-compared because a host will rebuild the
+  // object inline, exactly as it does the column array.
+  parts.push(overrides ? JSON.stringify(overrides) : '');
+  return parts.join('');
+}
+
+/** Widths that came out identical must not be published — that's a render loop. */
+function sameSizing(a, b) {
+  if (!a || !b || a.tableWidth !== b.tableWidth || a.widths.length !== b.widths.length) return false;
+  for (var i = 0; i < a.widths.length; i++) {
+    if (a.widths[i] !== b.widths[i]) return false;
+  }
+  return true;
+}
+
+function horizontalPadding(el) {
+  if (!el) return 0;
+  var style = window.getComputedStyle(el);
+  return parseFloat(style.paddingLeft || 0) + parseFloat(style.paddingRight || 0) +
+    parseFloat(style.borderLeftWidth || 0) + parseFloat(style.borderRightWidth || 0);
+}
+
+/**
+ * @param {object} opts
+ * @param {boolean} opts.enabled      - Off by default; hosts opt in
+ * @param {Array} opts.data           - Rows to sample. The FULL set, not the
+ *   current page: widths measured per page would jump every time you paged.
+ * @param {Array} opts.columns        - [{ accessor, header, ... }]
+ * @param {Function} [opts.columnText] - (row, column) => displayed string.
+ *   Defaults to the raw value; hosts that format their cells should pass their
+ *   formatter, or currency/date columns get measured as bare numbers.
+ * @param {*} [opts.sizingKey]        - Changing this re-measures. For font or
+ *   theme changes, which nothing else can observe.
+ * @param {object} [opts.columnWidths] - { columnIndex: percent }. Those
+ *   columns are held at that share of the available width and never measured;
+ *   everything else divides what's left. PERCENT, not px, so a pin keeps its
+ *   proportion when the container resizes. BY INDEX, not by key — see
+ *   pinnedWidth() in columnWidths.js.
+ * @param {Function} [opts.onSizing]  - Called with the full decision record.
+ * @returns {{ scrollRef, tableRef, sizing }}
+ */
+export default function useColumnWidths(opts) {
+  var enabled = !!opts.enabled;
+  var data = opts.data;
+  var columns = opts.columns;
+  var sizingKey = opts.sizingKey;
+  var onSizing = opts.onSizing;
+  var sampleRows = opts.sampleRows || DEFAULTS.sampleRows;
+  var overrides = opts.columnWidths;
+
+  var scrollRef = useRef(null);
+  var tableRef = useRef(null);
+  var lastWidthRef = useRef(0);
+  var signatureRef = useRef(null);
+  var dataRef = useRef(null);
+  var sizingRef = useRef(null);
+  var [containerWidth, setContainerWidth] = useState(0);
+  var [sizing, setSizing] = useState(null);
+
+  var columnText = opts.columnText;
+  var textOf = useCallback(function(row, column) {
+    if (columnText) return columnText(row, column);
+    var value = row ? row[column.accessor] : null;
+    return value === null || value === undefined ? '' : String(value);
+  }, [columnText]);
+
+  // ── Track the available width ──
+  // clientWidth of the scroll port, deliberately: overflow-x means a horizontal
+  // scrollbar eats height, not width, so this number can't oscillate with the
+  // scrollbar it produces.
+  useLayoutEffect(function() {
+    if (!enabled) return undefined;
+    var el = scrollRef.current;
+    if (!el || typeof ResizeObserver === 'undefined') return undefined;
+
+    function read() {
+      var width = el.clientWidth;
+      // Sub-pixel churn from zoom/fractional layout would otherwise re-run the
+      // whole measure pass on every frame during a window drag.
+      if (Math.abs(width - lastWidthRef.current) < 2) return;
+      lastWidthRef.current = width;
+      setContainerWidth(width);
+    }
+
+    read();
+    var observer = new ResizeObserver(read);
+    observer.observe(el);
+    return function() { observer.disconnect(); };
+  }, [enabled]);
+
+  // ── Measure and allocate ──
+  useLayoutEffect(function() {
+    if (!enabled || !containerWidth || !columns || !columns.length) {
+      if (sizingRef.current) { sizingRef.current = null; setSizing(null); }
+      return;
+    }
+    var measure = textMeasurer();
+    var table = tableRef.current;
+    if (!measure || !table) return;
+
+    // Cheap bail-out before the expensive part: measuring 200 rows across
+    // every column on a render that changed nothing is pure waste.
+    var signature = signatureOf(columns, containerWidth, sizingKey, overrides);
+    if (signature === signatureRef.current && data === dataRef.current && sizingRef.current) return;
+    signatureRef.current = signature;
+    dataRef.current = data;
+
+    // Fonts and padding come from real cells so this stays in step with the
+    // stylesheet automatically. Before the first row renders there's no <td>,
+    // so the header cell stands in — one pass slightly off, corrected as soon
+    // as rows arrive and the effect re-runs.
+    var bodyCell = table.querySelector('tbody .xeplr-table-td');
+    var headCell = table.querySelector('thead .xeplr-table-header-cell');
+    var headerFont = fontOf(window.getComputedStyle(headCell || bodyCell || table));
+
+    // Rows are not guaranteed to share a font. A host that styles a total row
+    // bold, or bands alternate rows differently, makes some rows wider than
+    // others at the same character count — sizing off row one alone would
+    // leave exactly those rows wrapping. So collect the distinct fonts in play
+    // and give every column enough width for the widest of them.
+    var bodyFonts = [];
+    var sampleCells = table.querySelectorAll('tbody tr .xeplr-table-td:first-child');
+    for (var s = 0; s < sampleCells.length && bodyFonts.length < MAX_BODY_FONTS; s++) {
+      var font = fontOf(window.getComputedStyle(sampleCells[s]));
+      if (bodyFonts.indexOf(font) === -1) bodyFonts.push(font);
+    }
+    if (!bodyFonts.length) bodyFonts.push(headerFont);
+
+    // measureColumnDemand deals in one font per call, which keeps it pure and
+    // trivially testable; the multi-font case is resolved here instead.
+    var measureWidest = function(text, font) {
+      if (font !== BODY_FONTS) return measure(text, font);
+      var widest = 0;
+      for (var f = 0; f < bodyFonts.length; f++) {
+        var width = measure(text, bodyFonts[f]);
+        if (width > widest) widest = width;
+      }
+      return widest;
+    };
+
+    // Header chrome: the label shares its row with the sort caret and the
+    // filter trigger, so the text needs less room than the cell does.
+    var headerPadding = horizontalPadding(headCell);
+    var trigger = table.querySelector('thead .xeplr-table-filter-trigger');
+    if (trigger) headerPadding += trigger.offsetWidth + 4;
+    else headerPadding += 16; // sort caret
+
+    // The table's own structural columns — expand arrow, select checkbox, row
+    // actions — aren't content columns and don't compete for space. Their
+    // width is reserved off the top, so the content columns divide what's
+    // actually left. Read from the DOM because two of them are sized in CSS
+    // and the third shrink-wraps whatever buttons the host supplied.
+    var extraWidths = {};
+    var reserved = 0;
+    ['expand', 'checkbox', 'actions'].forEach(function(kind) {
+      var el = table.querySelector('thead .xeplr-table-th-' + kind);
+      if (!el) return;
+      var width = Math.ceil(el.offsetWidth);
+      extraWidths[kind] = width;
+      reserved += width;
+    });
+
+    var rows = data && data.length > sampleRows ? data.slice(0, sampleRows) : (data || []);
+
+    // Percentages resolve against `available` — the container minus the
+    // structural columns — so 100 means "all the room the columns have".
+    // The conversion itself is pure and lives in columnWidths.js; this is
+    // just the only place that knows what `available` is.
+    //
+    // A percentage is also why this survives a resize: containerWidth is in
+    // the signature, so the effect re-runs and a pinned column re-resolves to
+    // the right px rather than staying at yesterday's.
+    var available = containerWidth - reserved;
+    var pxOverrides = resolvePercentWidths(overrides, available);
+
+    var demands = measureColumnDemand({
+      columns: columns,
+      rows: rows,
+      textOf: textOf,
+      headerOf: function(column) { return column.header || column.accessor; },
+      keyOf: function(column) { return column.accessor; },
+      measure: measureWidest,
+      bodyFont: BODY_FONTS,
+      headerFont: headerFont,
+      cellPadding: horizontalPadding(bodyCell) || 25,
+      headerPadding: headerPadding,
+      minWidth: opts.minColumnWidth || DEFAULTS.minWidth,
+      maxWidth: opts.maxColumnWidth || DEFAULTS.maxWidth,
+      maxFloor: opts.maxFloorWidth || DEFAULTS.maxFloor,
+      overrides: pxOverrides
+    });
+
+    var next = allocateColumnWidths(demands, containerWidth - reserved);
+    next.extraWidths = extraWidths;
+    next.tableWidth += reserved;
+
+    if (sameSizing(next, sizingRef.current)) return;
+    sizingRef.current = next;
+    setSizing(next);
+    if (onSizing) onSizing(next);
+    // State is tracked through refs above, so it is deliberately absent here.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled, containerWidth, data, columns, textOf, sampleRows, sizingKey, overrides,
+      opts.minColumnWidth, opts.maxColumnWidth, opts.maxFloorWidth]);
+
+  return { scrollRef: scrollRef, tableRef: tableRef, sizing: enabled ? sizing : null };
+}

package/src/useTableController.js

@@ -25,12 +25,27 @@ var filterFnMap = {
 
 var columnHelper = createColumnHelper();
 
+// A column def may itself be a GROUP — `{ header, columns: [...] }` instead of
+// `{ accessor, ... }` — which becomes a spanning header cell over its
+// children (a pivoted date over the measures under it), same as Excel merges
+// a date across the columns it covers. Optional and recursive: a caller that
+// never nests columns gets exactly the flat header it always got.
+function flattenLeaves(cols) {
+  var out = [];
+  for (var i = 0; i < cols.length; i++) {
+    var col = cols[i];
+    if (col.columns && col.columns.length) out = out.concat(flattenLeaves(col.columns));
+    else out.push(col);
+  }
+  return out;
+}
+
 /**
  * Hook that wires TanStack Table with auto-detected column types and smart filters.
  *
  * @param {object} options
  * @param {Array<object>}  options.data               - Row array
- * @param {Array<object>}  options.columns             - [{ accessor, header, dataType?, cell? }]
+ * @param {Array<object>}  options.columns             - [{ accessor, header, dataType?, cell? } | { header, columns: [...] }]
  * @param {number}         [options.minDetectionRows]  - Min samples for confident detection (default: 10)
  * @param {number}         [options.pageSize]           - Rows per page (default: 20)
  * @param {boolean}        [options.enableSorting]       - Default: true
@@ -65,14 +80,28 @@ export default function useTableController(options) {
     }
 
     // Run detection
-    var result = detectTypes(data, columns, minDetectionRows);
+    // Leaves only — a group column has no accessor and no data of its own to
+    // sample, it is purely a spanning header over the columns that do.
+    var result = detectTypes(data, flattenLeaves(columns), minDetectionRows);
     detectionRef.current = { types: result.types, confident: result.confident, dataRef: data };
     return result.types;
   }, [data, columns, minDetectionRows]);
 
   // ── Build TanStack column defs ──
   var tanstackColumns = useMemo(function() {
-    return columns.map(function(col) {
+    function build(col) {
+      // A group has no data of its own — column.group() renders it as a
+      // spanning header cell (TanStack's own colSpan) over whichever leaf
+      // columns are nested under it, and nothing else about those leaves
+      // changes: same filters, same sort, same cells they'd have flat.
+      if (col.columns && col.columns.length) {
+        return columnHelper.group({
+          id: col.id || col.header,
+          header: col.header,
+          columns: col.columns.map(build)
+        });
+      }
+
       var type = detectedTypes.get(col.accessor) || TYPES.STRING;
       var filterFn = filterFnMap[type] || stringFilterFn;
 
@@ -95,11 +124,34 @@ export default function useTableController(options) {
         colDef.cell = rendererFn(rendererConfig);
       }
       return columnHelper.accessor(col.accessor, colDef);
-    });
+    }
+    return columns.map(build);
   }, [columns, detectedTypes]);
 
   // ── Table state ──
-  var [sorting, setSorting] = useState([]);
+  //
+  // Sorting can be CONTROLLED by the host. Uncontrolled is the default and is
+  // what a plain data grid wants: click a header, the table reorders itself.
+  //
+  // A host takes it over when the ordering is not the table's to decide.
+  // A grouped report is the case that forces it — its rows carry subtotals
+  // that must stay with their group, and columns whose values are derived
+  // from the row above them. Re-sorting such a result in the view layer
+  // scatters the subtotals and leaves every running total describing an order
+  // that is no longer on screen. So the host supplies the order and takes the
+  // header click as an instruction, which is what `manualSorting` means to
+  // TanStack: "already sorted, do not sort it again".
+  var controlledSorting = options.sorting !== undefined;
+  var [ownSorting, setOwnSorting] = useState([]);
+  var sorting = controlledSorting ? options.sorting : ownSorting;
+  var setSorting = function (updater) {
+    var next = typeof updater === 'function' ? updater(sorting) : updater;
+    if (controlledSorting) {
+      if (options.onSortingChange) options.onSortingChange(next);
+      return;
+    }
+    setOwnSorting(next);
+  };
   var [columnFilters, setColumnFilters] = useState([]);
   var [pagination, setPagination] = useState({ pageIndex: 0, pageSize: pageSize });
 
@@ -117,7 +169,11 @@ export default function useTableController(options) {
     onPaginationChange: setPagination,
     getCoreRowModel: getCoreRowModel(),
     getFilteredRowModel: enableFiltering ? getFilteredRowModel() : undefined,
-    getSortedRowModel: enableSorting ? getSortedRowModel() : undefined,
+    // Not applied when the host controls the order — the rows arrive sorted
+    // and sorting them again is both wasted work and, for a grouped result,
+    // wrong.
+    getSortedRowModel: (enableSorting && !controlledSorting) ? getSortedRowModel() : undefined,
+    manualSorting: controlledSorting,
     getPaginationRowModel: enablePagination ? getPaginationRowModel() : undefined,
     getFacetedRowModel: getFacetedRowModel(),
     getFacetedUniqueValues: getFacetedUniqueValues(),