@cl-light-ds/ui 0.1.0 → 0.3.0

package/src/lib/table-controller.ts

@@ -0,0 +1,1090 @@
+/**
+ * Behaviour for `<Table interactive>`.
+ *
+ * The controller never sorts, pages or persists data. It manages UI state
+ * (sort indicators, selection, edit lifecycle, tree visibility, column layout,
+ * keyboard focus) and reports intent through bubbling `table:*` events on the
+ * `[data-slot="table-root"]` element. The app responds by re-rendering rows;
+ * a MutationObserver re-applies layout and selection state to the new rows.
+ *
+ * Outbound events (all bubble, all cancelable unless noted):
+ * - `table:sort`       `{ column, direction: "asc" | "desc" | null }`
+ * - `table:edit`       `{ rowId, column, value, previous, respond(promise) }`
+ *                      Call `respond` with a promise; reject it (Error or string)
+ *                      to show the error state. `preventDefault()` rejects the edit.
+ * - `table:selection`  `{ rowIds, allResults }` (not cancelable)
+ * - `table:page`       `{ page, pageSize }`
+ * - `table:toggle-row` `{ rowId, expanded }`
+ * - `table:columns`    `{ widths, hidden }` (not cancelable)
+ *
+ * Inbound event:
+ * - `table:set` `{ loading?: boolean, totalCount?: number, page?: number }`
+ */
+
+type SortState = "asc" | "desc" | "none";
+type EditValue = string | string[];
+
+export interface TableEditDetail {
+  rowId: string | null;
+  column: string;
+  value: EditValue;
+  previous: EditValue;
+  respond: (result: unknown) => void;
+}
+
+export interface TableSortDetail {
+  column: string;
+  direction: "asc" | "desc" | null;
+}
+
+export interface TableSetDetail {
+  loading?: boolean;
+  totalCount?: number;
+  page?: number;
+}
+
+const bound = new WeakSet<HTMLElement>();
+const MIN_COLUMN_WIDTH = 64;
+const ERROR_TIMEOUT = 4000;
+
+export function initTables(scope: ParentNode = document) {
+  scope
+    .querySelectorAll<HTMLElement>('[data-slot="table-root"][data-interactive]')
+    .forEach((root) => {
+      if (bound.has(root)) return;
+      bound.add(root);
+      createTable(root);
+    });
+}
+
+function errorMessage(error: unknown, fallback: string): string {
+  if (typeof error === "string" && error) return error;
+  if (error instanceof Error && error.message) return error.message;
+  return fallback;
+}
+
+function parseValue(td: HTMLElement): EditValue {
+  const raw = td.dataset.value ?? "";
+  if (td.dataset.editor !== "multiselect") return raw;
+  try {
+    const parsed: unknown = JSON.parse(raw || "[]");
+    return Array.isArray(parsed) ? parsed.map(String) : [];
+  } catch {
+    return [];
+  }
+}
+
+function serializeValue(td: HTMLElement, value: EditValue): string {
+  return td.dataset.editor === "multiselect" ? JSON.stringify(value) : String(value);
+}
+
+function sameValue(a: EditValue, b: EditValue): boolean {
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((v) => b.includes(v));
+  }
+  return a === b;
+}
+
+function isTextEntry(el: Element | null): boolean {
+  return !!el && (el.matches("input:not([type=checkbox]), textarea, select") || !!el.closest('[data-slot="table-cell-editor"]'));
+}
+
+function createTable(root: HTMLElement) {
+  const tableElement = root.querySelector<HTMLTableElement>('table[data-slot="table"]');
+  if (!tableElement) return;
+  const table: HTMLTableElement = tableElement;
+
+  const live = root.querySelector<HTMLElement>('[data-slot="table-live"]');
+  const pagination = root.querySelector<HTMLElement>('[data-slot="table-pagination"]');
+  const banner = root.querySelector<HTMLElement>('[data-slot="table-select-all-banner"]');
+  const columnMenu = root.querySelector<HTMLElement>("[data-table-column-menu]");
+  const pinCount = Number(root.dataset.pinnedColumns ?? 0) || 0;
+
+  let allResults = false;
+  let activeText: HTMLTableCellElement | null = null;
+  let current: HTMLTableCellElement | null = null;
+  const hiddenColumns = new Set<string>();
+  const visibleErrors = new Set<HTMLTableCellElement>();
+  const errorTimers = new WeakMap<HTMLElement, number>();
+  const boundWidgets = new WeakSet<Element>();
+
+  table.setAttribute("role", "grid");
+
+  // ---------------------------------------------------------------- helpers
+
+  const emit = <T,>(name: string, detail: T, cancelable = true) =>
+    root.dispatchEvent(new CustomEvent<T>(name, { bubbles: true, cancelable, detail }));
+
+  const announce = (message: string) => {
+    if (!live) return;
+    live.textContent = "";
+    window.setTimeout(() => {
+      live.textContent = message;
+    }, 50);
+  };
+
+  const headerRow = () => table.tHead?.rows[table.tHead.rows.length - 1] ?? null;
+
+  const bodyRows = () =>
+    Array.from(table.tBodies).flatMap((tbody) =>
+      Array.from(tbody.rows).filter((r) => r.dataset.slot === "table-row"),
+    );
+
+  const allRows = () => Array.from(table.rows);
+
+  const cellLabel = (td: HTMLElement) => td.dataset.label ?? td.dataset.column ?? "value";
+
+  const hasTree = () => !!table.querySelector("tbody tr[data-folder]");
+
+  const totalCount = () => {
+    const value = Number(root.dataset.totalCount ?? pagination?.dataset.totalCount);
+    return Number.isFinite(value) && value > 0 ? value : null;
+  };
+
+  // ---------------------------------------------------------------- sorting
+
+  const syncSortAvailability = () => {
+    const tree = hasTree();
+    table.querySelectorAll<HTMLButtonElement>('[data-slot="table-sort-button"]').forEach((button) => {
+      button.disabled = tree;
+      button.title = tree ? "Sorting is not available in tree tables" : "";
+    });
+  };
+
+  const setSortState = (th: HTMLElement, state: SortState) => {
+    th.dataset.sort = state;
+    th.setAttribute("aria-sort", state === "asc" ? "ascending" : state === "desc" ? "descending" : "none");
+  };
+
+  const cycleSort = (th: HTMLTableCellElement) => {
+    if (hasTree()) return;
+    const column = th.dataset.column;
+    if (!column) return;
+    const sortable = Array.from(table.querySelectorAll<HTMLTableCellElement>("th[data-sortable]"));
+    const previous = sortable.map((h) => [h, (h.dataset.sort as SortState) ?? "none"] as const);
+    const now = (th.dataset.sort as SortState) ?? "none";
+    const next: SortState = now === "asc" ? "desc" : now === "desc" ? "none" : "asc";
+
+    sortable.forEach((h) => setSortState(h, h === th ? next : "none"));
+
+    const accepted = emit<TableSortDetail>("table:sort", {
+      column,
+      direction: next === "none" ? null : next,
+    });
+    if (!accepted) {
+      previous.forEach(([h, state]) => setSortState(h, state));
+      return;
+    }
+    const name = th.textContent?.trim() || column;
+    announce(next === "none" ? "Sorting cleared" : `Sorted by ${name}, ${next === "asc" ? "ascending" : "descending"}`);
+  };
+
+  // -------------------------------------------------------------- selection
+
+  const rowCheckbox = (tr: HTMLTableRowElement) =>
+    tr.querySelector<HTMLInputElement>('input[data-table-select="row"]');
+
+  const headerCheckbox = () => table.querySelector<HTMLInputElement>('input[data-table-select="all"]');
+
+  const selectionRows = () => bodyRows().filter((tr) => rowCheckbox(tr));
+
+  const descendantsOf = (tr: HTMLTableRowElement) => {
+    const id = tr.dataset.rowId;
+    if (!id) return [];
+    const ids = new Set([id]);
+    const result: HTMLTableRowElement[] = [];
+    for (const row of bodyRows()) {
+      const parent = row.dataset.parentId;
+      if (parent && ids.has(parent)) {
+        result.push(row);
+        if (row.dataset.rowId) ids.add(row.dataset.rowId);
+      }
+    }
+    return result;
+  };
+
+  const setText = (selector: string, text: string, scope: ParentNode = root) =>
+    scope.querySelectorAll(selector).forEach((el) => {
+      el.textContent = text;
+    });
+
+  const syncSelection = () => {
+    const rows = selectionRows();
+    const boxes = rows.map((tr) => rowCheckbox(tr)!).filter((b) => !b.disabled);
+    let checkedCount = 0;
+
+    rows.forEach((tr) => {
+      const checked = rowCheckbox(tr)!.checked;
+      if (checked) {
+        checkedCount += 1;
+        tr.dataset.state = "selected";
+        tr.setAttribute("aria-selected", "true");
+      } else {
+        if (tr.dataset.state === "selected") delete tr.dataset.state;
+        tr.setAttribute("aria-selected", "false");
+      }
+    });
+
+    const everyChecked = boxes.length > 0 && boxes.every((b) => b.checked);
+    const header = headerCheckbox();
+    if (header) {
+      header.checked = everyChecked;
+      header.indeterminate = checkedCount > 0 && !everyChecked;
+    }
+    if (!everyChecked) allResults = false;
+
+    const total = totalCount();
+    const count = allResults && total ? total : checkedCount;
+    root.toggleAttribute("data-has-selection", checkedCount > 0);
+    setText('[data-slot="table-selection-count"]', String(count));
+
+    if (banner) {
+      const show = everyChecked && total !== null && total > boxes.length;
+      banner.hidden = !show;
+      setText('[data-slot="table-page-count"]', String(boxes.length), banner);
+      setText('[data-slot="table-total-count"]', String(total ?? 0), banner);
+      banner.querySelectorAll<HTMLElement>("[data-banner-page]").forEach((el) => (el.hidden = allResults));
+      banner.querySelectorAll<HTMLElement>("[data-banner-all]").forEach((el) => (el.hidden = !allResults));
+    }
+    return { rows, checkedCount, count };
+  };
+
+  const selectionChanged = () => {
+    const { rows, count } = syncSelection();
+    const rowIds = rows
+      .filter((tr) => rowCheckbox(tr)!.checked)
+      .map((tr) => tr.dataset.rowId)
+      .filter((id): id is string => !!id);
+    emit("table:selection", { rowIds, allResults }, false);
+    announce(count === 0 ? "No rows selected" : `${count} selected`);
+  };
+
+  const clearSelection = () => {
+    allResults = false;
+    selectionRows().forEach((tr) => (rowCheckbox(tr)!.checked = false));
+    selectionChanged();
+  };
+
+  // ------------------------------------------------------------------- tree
+
+  const applyTree = () => {
+    const hiddenParents = new Set<string>();
+    for (const tr of bodyRows()) {
+      const parent = tr.dataset.parentId;
+      const hiddenByParent = !!parent && hiddenParents.has(parent);
+      tr.hidden = hiddenByParent;
+      const id = tr.dataset.rowId;
+      const folder = tr.hasAttribute("data-folder");
+      const expanded = tr.hasAttribute("data-expanded");
+      if (id && (hiddenByParent || (folder && !expanded))) hiddenParents.add(id);
+      if (folder) {
+        tr.setAttribute("aria-expanded", String(expanded));
+        const toggle = tr.querySelector<HTMLElement>('[data-slot="table-row-toggle"]');
+        toggle?.setAttribute("aria-label", expanded ? "Collapse row" : "Expand row");
+        toggle?.setAttribute("aria-expanded", String(expanded));
+      }
+    }
+  };
+
+  const setExpanded = (tr: HTMLTableRowElement, expanded: boolean) => {
+    if (!tr.hasAttribute("data-folder") || tr.hasAttribute("data-expanded") === expanded) return;
+    tr.toggleAttribute("data-expanded", expanded);
+    applyTree();
+    emit("table:toggle-row", { rowId: tr.dataset.rowId ?? null, expanded });
+    const name = tr.querySelector("[data-folder-cell]")?.textContent?.trim() ?? "Row";
+    announce(`${name} ${expanded ? "expanded" : "collapsed"}`);
+  };
+
+  // ---------------------------------------------------------------- columns
+
+  const columnCells = (index: number, column: string | undefined, headerLength: number) =>
+    allRows().flatMap((tr) => {
+      if (tr.cells.length === headerLength) return tr.cells[index] ? [tr.cells[index]] : [];
+      if (!column) return [];
+      return Array.from(tr.cells).filter((c) => c.dataset.column === column);
+    });
+
+  const applyColumns = () => {
+    const header = headerRow();
+    if (!header) return;
+    Array.from(header.cells).forEach((th, index) => {
+      const column = th.dataset.column;
+      const hide = !!column && hiddenColumns.has(column);
+      columnCells(index, column, header.cells.length).forEach((cell) => (cell.hidden = hide));
+    });
+  };
+
+  const applyPinned = () => {
+    const header = headerRow();
+    if (!header || pinCount <= 0) return;
+    const ths = Array.from(header.cells);
+    const pinned = ths.map((_, i) => i).filter((i) => !ths[i]!.hidden).slice(0, pinCount);
+    const offsets = new Map<number, number>();
+    let left = 0;
+    pinned.forEach((i) => {
+      offsets.set(i, left);
+      left += ths[i]!.getBoundingClientRect().width;
+    });
+    const last = pinned[pinned.length - 1];
+    ths.forEach((th, index) => {
+      columnCells(index, th.dataset.column, ths.length).forEach((cell) => {
+        const offset = offsets.get(index);
+        if (offset === undefined) {
+          delete cell.dataset.pinned;
+          delete cell.dataset.pinnedLast;
+          cell.style.left = "";
+          return;
+        }
+        cell.dataset.pinned = "";
+        cell.toggleAttribute("data-pinned-last", index === last);
+        cell.style.left = `${offset}px`;
+      });
+    });
+  };
+
+  const emitColumns = () => {
+    const widths: Record<string, number> = {};
+    headerRow()
+      ?.querySelectorAll<HTMLElement>("th[data-column]")
+      .forEach((th) => {
+        if (th.style.width) widths[th.dataset.column!] = Math.round(parseFloat(th.style.width));
+      });
+    emit("table:columns", { widths, hidden: Array.from(hiddenColumns) }, false);
+  };
+
+  const setColumnWidth = (th: HTMLElement, width: number) => {
+    const px = `${Math.max(MIN_COLUMN_WIDTH, Math.round(width))}px`;
+    th.style.width = px;
+    th.style.minWidth = px;
+    applyPinned();
+  };
+
+  const bindResize = (handle: HTMLElement) => {
+    handle.addEventListener("pointerdown", (event) => {
+      const th = handle.closest("th");
+      if (!th) return;
+      event.preventDefault();
+      event.stopPropagation();
+      const startX = event.clientX;
+      const startWidth = th.getBoundingClientRect().width;
+      handle.setPointerCapture(event.pointerId);
+      root.dataset.resizing = "";
+      const move = (e: PointerEvent) => setColumnWidth(th, startWidth + e.clientX - startX);
+      const up = () => {
+        handle.removeEventListener("pointermove", move);
+        handle.removeEventListener("pointerup", up);
+        handle.removeEventListener("pointercancel", up);
+        delete root.dataset.resizing;
+        emitColumns();
+      };
+      handle.addEventListener("pointermove", move);
+      handle.addEventListener("pointerup", up);
+      handle.addEventListener("pointercancel", up);
+    });
+    // A click on the handle must not toggle the sort button underneath.
+    handle.addEventListener("click", (e) => e.stopPropagation());
+  };
+
+  if (columnMenu) {
+    let columns: string[] = [];
+    let visible: string[] = [];
+    try {
+      columns = JSON.parse(columnMenu.dataset.columns ?? "[]");
+      visible = JSON.parse(columnMenu.dataset.defaultValues ?? "[]");
+    } catch {
+      /* malformed attributes: treat every column as visible */
+    }
+    columns.filter((c) => !visible.includes(c)).forEach((c) => hiddenColumns.add(c));
+    columnMenu.addEventListener("dropdown-menu:values-change", (event) => {
+      const { values } = (event as CustomEvent<{ values: string[] }>).detail;
+      hiddenColumns.clear();
+      columns.filter((c) => !values.includes(c)).forEach((c) => hiddenColumns.add(c));
+      applyColumns();
+      applyPinned();
+      ensureTabStop();
+      emitColumns();
+    });
+  }
+
+  // ----------------------------------------------------------------- errors
+
+  // Bubbles are moved to <body> on first use: pinned (sticky, z-indexed) cells
+  // form stacking contexts that would paint later rows over the bubble.
+  const errorElements = new WeakMap<HTMLElement, HTMLElement>();
+  const errorElement = (td: HTMLElement) => {
+    let el = errorElements.get(td) ?? null;
+    if (!el) {
+      el = td.querySelector<HTMLElement>('[data-slot="table-cell-error"]');
+      if (!el) return null;
+      errorElements.set(td, el);
+      document.body.append(el);
+    }
+    return el;
+  };
+
+  const positionError = (td: HTMLTableCellElement) => {
+    const el = errorElement(td);
+    if (!el) return;
+    const rect = td.getBoundingClientRect();
+    el.style.left = `${rect.left + 8}px`;
+    el.style.top = `${rect.bottom + 4}px`;
+  };
+
+  const showError = (td: HTMLTableCellElement, message: string, autoHide = false) => {
+    const el = errorElement(td);
+    if (!el) return;
+    el.textContent = message;
+    el.id ||= `table-error-${Math.random().toString(36).slice(2)}`;
+    el.hidden = false;
+    td.querySelector("[data-table-input]")?.setAttribute("aria-describedby", el.id);
+    visibleErrors.add(td);
+    positionError(td);
+    window.clearTimeout(errorTimers.get(td));
+    if (autoHide) errorTimers.set(td, window.setTimeout(() => hideError(td), ERROR_TIMEOUT));
+  };
+
+  const hideError = (td: HTMLTableCellElement) => {
+    const el = errorElement(td);
+    if (el) el.hidden = true;
+    td.querySelector("[data-table-input]")?.removeAttribute("aria-describedby");
+    visibleErrors.delete(td);
+  };
+
+  const repositionErrors = () =>
+    visibleErrors.forEach((td) => (td.isConnected ? positionError(td) : hideError(td)));
+  root.querySelector('[data-slot="table-container"]')?.addEventListener("scroll", repositionErrors, { passive: true });
+  window.addEventListener("scroll", repositionErrors, { passive: true, capture: true });
+  window.addEventListener("resize", () => {
+    repositionErrors();
+    applyPinned();
+  });
+
+  // ---------------------------------------------------------------- editing
+
+  const requestEdit = (td: HTMLTableCellElement, value: EditValue, previous: EditValue): Promise<unknown> => {
+    let pending: Promise<unknown> | undefined;
+    const accepted = emit<TableEditDetail>("table:edit", {
+      rowId: td.closest("tr")?.dataset.rowId ?? null,
+      column: td.dataset.column ?? "",
+      value,
+      previous,
+      respond: (result) => {
+        pending = Promise.resolve(result);
+      },
+    });
+    if (!accepted) return Promise.reject(new Error("This change was not accepted."));
+    return pending ?? Promise.resolve(undefined);
+  };
+
+  const textInput = (td: HTMLElement) => td.querySelector<HTMLInputElement>("input[data-table-input]");
+  const confirmButton = (td: HTMLElement) => td.querySelector<HTMLButtonElement>('[data-table-action="confirm"]');
+
+  const validateText = (td: HTMLTableCellElement, showMessage: boolean) => {
+    const input = textInput(td);
+    if (!input) return true;
+    const valid = input.checkValidity();
+    const confirm = confirmButton(td);
+    if (confirm) confirm.disabled = !valid;
+    if (valid) {
+      input.removeAttribute("aria-invalid");
+      hideError(td);
+    } else if (showMessage) {
+      input.setAttribute("aria-invalid", "true");
+      showError(td, input.validationMessage);
+    }
+    return valid;
+  };
+
+  const renderTextValue = (td: HTMLElement, value: string) => {
+    const target = td.querySelector<HTMLElement>('[data-slot="table-cell-value"]');
+    if (!target) return;
+    target.textContent = value || td.dataset.placeholder || "";
+    target.classList.toggle("text-muted-foreground", !value);
+    target.classList.toggle("font-normal", !value);
+  };
+
+  const cancelText = (td: HTMLTableCellElement, refocus = true) => {
+    const input = textInput(td);
+    td.dataset.state = "idle";
+    input?.removeAttribute("aria-invalid");
+    hideError(td);
+    if (activeText === td) activeText = null;
+    if (refocus) focusCell(td);
+  };
+
+  const startText = (td: HTMLTableCellElement) => {
+    const input = textInput(td);
+    if (!input || td.dataset.state === "saving") return;
+    if (activeText && activeText !== td) {
+      const other = activeText;
+      if (textInput(other)?.value !== (other.dataset.value ?? "")) {
+        textInput(other)?.focus();
+        announce(`Save or cancel the ${cellLabel(other)} edit first`);
+        return;
+      }
+      cancelText(other, false);
+    }
+    activeText = td;
+    input.value = td.dataset.value ?? "";
+    td.dataset.state = "editing";
+    validateText(td, false);
+    input.focus();
+    input.select();
+  };
+
+  const commitText = async (td: HTMLTableCellElement) => {
+    const input = textInput(td);
+    if (!input || td.dataset.state === "saving") return;
+    if (!validateText(td, true)) {
+      input.focus();
+      return;
+    }
+    const previous = td.dataset.value ?? "";
+    const value = input.value;
+    if (value === previous) {
+      cancelText(td);
+      return;
+    }
+    td.dataset.state = "saving";
+    td.setAttribute("aria-busy", "true");
+    input.readOnly = true;
+    try {
+      const result = await requestEdit(td, value, previous);
+      const saved = typeof result === "string" ? result : value;
+      td.dataset.value = saved;
+      renderTextValue(td, saved);
+      td.dataset.state = "idle";
+      activeText = null;
+      hideError(td);
+      focusCell(td);
+      announce(`${cellLabel(td)} saved`);
+    } catch (error) {
+      td.dataset.state = "error";
+      input.setAttribute("aria-invalid", "true");
+      const message = errorMessage(error, "Could not save the change.");
+      showError(td, message);
+      input.focus();
+      announce(`${cellLabel(td)} not saved. ${message}`);
+    } finally {
+      input.readOnly = false;
+      td.removeAttribute("aria-busy");
+    }
+  };
+
+  // -------------------------------------------------------- choice editors
+
+  const renderChoice = (td: HTMLTableCellElement, value: EditValue) => {
+    const target = td.querySelector<HTMLElement>('[data-slot="table-cell-value"]');
+    const template = td.querySelector<HTMLTemplateElement>('template[data-slot="table-cell-templates"]');
+    if (!target || !template) return;
+    const values = Array.isArray(value) ? value : value ? [value] : [];
+    const option = (v: string) =>
+      template.content.querySelector<HTMLElement>(`[data-option="${CSS.escape(v)}"]`);
+
+    if (td.dataset.editor === "combobox") {
+      const text = values.map((v) => option(v)?.textContent?.trim() ?? v).join(", ");
+      renderTextValue(td, text);
+      return;
+    }
+
+    const max = Number(td.dataset.maxVisible ?? 2) || 2;
+    const nodes: Node[] = values.slice(0, max).map((v) => {
+      const node = option(v)?.cloneNode(true) as HTMLElement | undefined;
+      if (node) {
+        node.removeAttribute("data-option");
+        return node;
+      }
+      return document.createTextNode(v);
+    });
+    if (values.length > max) {
+      const more = template.content.querySelector("[data-option-overflow]")?.cloneNode(true) as HTMLElement | undefined;
+      if (more) {
+        more.removeAttribute("data-option-overflow");
+        more.textContent = `+${values.length - max}`;
+        nodes.push(more);
+      }
+    }
+    if (nodes.length === 0) {
+      const empty = document.createElement("span");
+      empty.className = "text-muted-foreground font-normal";
+      empty.textContent = td.dataset.placeholder ?? "";
+      nodes.push(empty);
+    }
+    target.replaceChildren(...nodes);
+  };
+
+  const commitChoice = async (
+    td: HTMLTableCellElement,
+    value: EditValue,
+    previous: EditValue,
+    revert: (value: EditValue) => void,
+  ) => {
+    if (sameValue(value, previous)) return;
+    td.dataset.value = serializeValue(td, value);
+    renderChoice(td, value);
+    td.dataset.state = "saving";
+    td.setAttribute("aria-busy", "true");
+    hideError(td);
+    try {
+      await requestEdit(td, value, previous);
+      announce(`${cellLabel(td)} saved`);
+    } catch (error) {
+      td.dataset.value = serializeValue(td, previous);
+      renderChoice(td, previous);
+      revert(previous);
+      const message = errorMessage(error, "Could not save the change.");
+      showError(td, message, true);
+      announce(`${cellLabel(td)} not saved. ${message}`);
+    } finally {
+      td.dataset.state = "idle";
+      td.removeAttribute("aria-busy");
+    }
+  };
+
+  const bindMenuCell = (menu: HTMLElement) => {
+    const td = menu.closest<HTMLTableCellElement>("td[data-editable]");
+    if (!td) return;
+    const restore = (value: EditValue) =>
+      menu.dispatchEvent(
+        new CustomEvent("dropdown-menu:set", {
+          detail: Array.isArray(value) ? { values: value, source: "restore" } : { value, source: "restore" },
+        }),
+      );
+
+    if (td.dataset.editor === "select") {
+      menu.addEventListener("dropdown-menu:value-change", (event) => {
+        const { value, previousValue, source } = (
+          event as CustomEvent<{ value: string | null; previousValue: string | null; source: string }>
+        ).detail;
+        if (source === "programmatic" || source === "restore") return;
+        void commitChoice(td, value ?? "", previousValue ?? "", restore);
+      });
+      return;
+    }
+
+    // Multiselect: preview while open, commit once when the menu closes.
+    let snapshot: string[] | null = null;
+    let working: string[] = [];
+    menu.addEventListener("dropdown-menu:open-change", (event) => {
+      const { open } = (event as CustomEvent<{ open: boolean }>).detail;
+      if (open) {
+        snapshot = parseValue(td) as string[];
+        working = [...snapshot];
+        return;
+      }
+      if (!snapshot) return;
+      const before = snapshot;
+      snapshot = null;
+      if (sameValue(working, before)) {
+        renderChoice(td, before);
+        return;
+      }
+      void commitChoice(td, working, before, restore);
+    });
+    menu.addEventListener("dropdown-menu:values-change", (event) => {
+      const { values, source } = (event as CustomEvent<{ values: string[]; source: string }>).detail;
+      if (source === "programmatic" || source === "restore" || !snapshot) return;
+      working = values;
+      renderChoice(td, values);
+    });
+  };
+
+  const comboboxOf = (td: HTMLElement) => td.querySelector<HTMLElement>("[data-table-combobox]");
+
+  const startCombobox = (td: HTMLTableCellElement) => {
+    const combobox = comboboxOf(td);
+    if (!combobox || td.dataset.state === "saving") return;
+    td.dataset.state = "editing";
+    const input = combobox.querySelector<HTMLInputElement>('[data-slot="combobox-input"]');
+    input?.focus();
+    combobox.dispatchEvent(new CustomEvent("combobox:set", { detail: { open: true } }));
+  };
+
+  const bindCombobox = (combobox: HTMLElement) => {
+    const td = combobox.closest<HTMLTableCellElement>("td[data-editable]");
+    if (!td) return;
+    const restore = (value: EditValue) =>
+      combobox.dispatchEvent(new CustomEvent("combobox:set", { detail: { value: String(value) || null } }));
+    const close = () => {
+      if (td.dataset.state !== "editing") return;
+      td.dataset.state = "idle";
+      restore(td.dataset.value ?? "");
+      focusCell(td);
+    };
+
+    combobox.addEventListener("combobox:change", (event) => {
+      if (td.dataset.state !== "editing") return;
+      const { value } = (event as CustomEvent<{ value: string | null }>).detail;
+      const previous = td.dataset.value ?? "";
+      td.dataset.state = "idle";
+      focusCell(td);
+      if (value !== null && value !== previous) void commitChoice(td, value, previous, restore);
+    });
+    combobox.addEventListener("combobox:open-change", (event) => {
+      if ((event as CustomEvent<{ open: boolean }>).detail.open) return;
+      // Let a pending `combobox:change` land first.
+      window.setTimeout(close, 0);
+    });
+    combobox.addEventListener("focusout", (event) => {
+      const next = (event as FocusEvent).relatedTarget as Node | null;
+      if (next && combobox.contains(next)) return;
+      window.setTimeout(() => {
+        if (!combobox.contains(document.activeElement)) close();
+      }, 0);
+    });
+  };
+
+  // --------------------------------------------------------------- keyboard
+
+  const visibleCells = (tr: HTMLTableRowElement) => Array.from(tr.cells).filter((c) => !c.hidden);
+  const gridRows = () => allRows().filter((tr) => !tr.hidden && visibleCells(tr).length > 0);
+
+  function focusCell(cell: HTMLTableCellElement) {
+    if (current && current !== cell) current.tabIndex = -1;
+    current = cell;
+    cell.tabIndex = 0;
+    cell.focus();
+  }
+
+  function ensureTabStop() {
+    const cells = Array.from(table.querySelectorAll<HTMLTableCellElement>("th, td"));
+    cells.forEach((cell) => {
+      if (cell !== current) cell.tabIndex = -1;
+    });
+    // Inner controls are reached with Enter/Space, not Tab (ARIA grid pattern).
+    table
+      .querySelectorAll<HTMLElement>("th button, th input, td button, td input[type=checkbox], td a[href]")
+      .forEach((el) => {
+        if (!el.closest('[data-slot="table-cell-editor"]')) el.tabIndex = -1;
+      });
+    if (!current || !table.contains(current) || current.hidden || current.closest("tr")?.hidden) {
+      current = gridRows()[0] ? visibleCells(gridRows()[0]!)[0] ?? null : null;
+    }
+    if (current) current.tabIndex = 0;
+  }
+
+  const moveFocus = (cell: HTMLTableCellElement, key: string, ctrl: boolean) => {
+    const rows = gridRows();
+    const tr = cell.closest("tr");
+    let rowIndex = tr ? rows.indexOf(tr) : -1;
+    if (rowIndex < 0) return;
+    let colIndex = visibleCells(tr!).indexOf(cell);
+    const lastRow = rows.length - 1;
+    switch (key) {
+      case "ArrowUp":
+        rowIndex = Math.max(0, rowIndex - 1);
+        break;
+      case "ArrowDown":
+        rowIndex = Math.min(lastRow, rowIndex + 1);
+        break;
+      case "ArrowLeft":
+        colIndex = Math.max(0, colIndex - 1);
+        break;
+      case "ArrowRight":
+        colIndex += 1;
+        break;
+      case "Home":
+        colIndex = 0;
+        if (ctrl) rowIndex = 0;
+        break;
+      case "End":
+        colIndex = Number.MAX_SAFE_INTEGER;
+        if (ctrl) rowIndex = lastRow;
+        break;
+      case "PageUp":
+        rowIndex = Math.max(0, rowIndex - 10);
+        break;
+      case "PageDown":
+        rowIndex = Math.min(lastRow, rowIndex + 10);
+        break;
+    }
+    const target = visibleCells(rows[rowIndex]!);
+    const next = target[Math.min(colIndex, target.length - 1)];
+    if (next) focusCell(next);
+  };
+
+  const activate = (cell: HTMLTableCellElement) => {
+    if (cell.matches('td[data-editable][data-editor="text"]')) return startText(cell);
+    if (cell.matches('td[data-editable][data-editor="combobox"]')) return startCombobox(cell);
+    const control = cell.querySelector<HTMLElement>(
+      '[data-slot="table-cell-display"], [data-slot="table-sort-button"], [data-slot="table-row-toggle"], input[type=checkbox], button, a[href]',
+    );
+    if (!control || control.closest('[data-slot="table-cell-editor"]')) return;
+    // Checkboxes toggle in place; menus and buttons take focus so it returns to them.
+    if (!control.matches("input[type=checkbox]")) control.focus();
+    control.click();
+  };
+
+  const NAV_KEYS = new Set(["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Home", "End", "PageUp", "PageDown"]);
+
+  // Capture phase so arrow keys on a focused trigger navigate the grid
+  // instead of opening its menu.
+  table.addEventListener(
+    "keydown",
+    (event) => {
+      const target = event.target as HTMLElement;
+      if (isTextEntry(target)) return;
+      const cell = target.closest<HTMLTableCellElement>("th, td");
+      if (!cell || cell.closest("table") !== table || !NAV_KEYS.has(event.key)) return;
+
+      const tr = cell.closest("tr");
+      if (tr?.hasAttribute("data-folder") && cell.hasAttribute("data-folder-cell")) {
+        const expanded = tr.hasAttribute("data-expanded");
+        if (event.key === "ArrowRight" && !expanded) {
+          event.preventDefault();
+          event.stopPropagation();
+          return setExpanded(tr, true);
+        }
+        if (event.key === "ArrowLeft" && expanded) {
+          event.preventDefault();
+          event.stopPropagation();
+          return setExpanded(tr, false);
+        }
+      }
+      if (event.altKey && cell.tagName === "TH" && cell.querySelector('[data-slot="table-resize-handle"]')) {
+        if (event.key === "ArrowLeft" || event.key === "ArrowRight") {
+          event.preventDefault();
+          event.stopPropagation();
+          setColumnWidth(cell, cell.getBoundingClientRect().width + (event.key === "ArrowRight" ? 16 : -16));
+          emitColumns();
+          return;
+        }
+      }
+      event.preventDefault();
+      event.stopPropagation();
+      moveFocus(cell, event.key, event.ctrlKey || event.metaKey);
+    },
+    true,
+  );
+
+  table.addEventListener("keydown", (event) => {
+    const target = event.target as HTMLElement;
+    const cell = target.closest<HTMLTableCellElement>("th, td");
+    if (!cell || cell.closest("table") !== table) return;
+
+    // Text editor keys.
+    if (target.matches("input[data-table-input]")) {
+      if (event.key === "Enter") {
+        event.preventDefault();
+        void commitText(cell);
+      } else if (event.key === "Escape") {
+        event.preventDefault();
+        event.stopPropagation();
+        cancelText(cell);
+      }
+      return;
+    }
+    if (isTextEntry(target)) return;
+    if (target !== cell) return; // inner controls handle their own Enter/Space
+
+    if (event.key === "Enter" || event.key === "F2") {
+      event.preventDefault();
+      activate(cell);
+    } else if (event.key === " ") {
+      const checkbox = cell.querySelector<HTMLInputElement>("input[type=checkbox]");
+      if (checkbox) {
+        event.preventDefault();
+        checkbox.click();
+      }
+    }
+  });
+
+  table.addEventListener("focusin", (event) => {
+    const cell = (event.target as HTMLElement).closest<HTMLTableCellElement>("th, td");
+    if (!cell || cell.closest("table") !== table || cell === current) return;
+    if (current) current.tabIndex = -1;
+    current = cell;
+    cell.tabIndex = 0;
+  });
+
+  // ----------------------------------------------------------------- clicks
+
+  root.addEventListener("click", (event) => {
+    const target = event.target as HTMLElement;
+
+    const action = target.closest<HTMLElement>("[data-table-action]");
+    if (action && root.contains(action)) {
+      const td = action.closest<HTMLTableCellElement>("td");
+      switch (action.dataset.tableAction) {
+        case "confirm":
+          if (td) void commitText(td);
+          return;
+        case "cancel":
+          if (td) cancelText(td);
+          return;
+        case "clear-selection":
+          clearSelection();
+          return;
+        case "select-all-results":
+          allResults = true;
+          selectionChanged();
+          return;
+      }
+    }
+
+    const sort = target.closest<HTMLButtonElement>('[data-slot="table-sort-button"]');
+    if (sort && table.contains(sort)) {
+      const th = sort.closest("th");
+      if (th) cycleSort(th);
+      return;
+    }
+
+    const toggle = target.closest<HTMLElement>('[data-slot="table-row-toggle"]');
+    if (toggle && table.contains(toggle)) {
+      const tr = toggle.closest("tr");
+      if (tr) setExpanded(tr, !tr.hasAttribute("data-expanded"));
+      return;
+    }
+
+    const display = target.closest<HTMLElement>('[data-slot="table-cell-display"]');
+    const td = display?.closest<HTMLTableCellElement>("td[data-editable]");
+    if (display && td && table.contains(td)) {
+      if (td.dataset.editor === "text") startText(td);
+      else if (td.dataset.editor === "combobox") startCombobox(td);
+      // select/multiselect: the dropdown trigger opens itself.
+    }
+
+    const page = target.closest<HTMLButtonElement>("[data-table-page]");
+    if (page && pagination?.contains(page)) goToPage(page.dataset.tablePage ?? "");
+  });
+
+  table.addEventListener("input", (event) => {
+    const input = event.target as HTMLElement;
+    if (!input.matches("input[data-table-input]")) return;
+    const td = input.closest<HTMLTableCellElement>("td");
+    if (!td) return;
+    if (td.dataset.state === "error") td.dataset.state = "editing";
+    validateText(td, true);
+  });
+
+  table.addEventListener("change", (event) => {
+    const input = event.target as HTMLInputElement;
+    const kind = input.dataset?.tableSelect;
+    if (!kind) return;
+    if (kind === "all") {
+      allResults = false;
+      selectionRows().forEach((tr) => {
+        const box = rowCheckbox(tr)!;
+        if (!box.disabled) box.checked = input.checked;
+      });
+    } else {
+      const tr = input.closest("tr");
+      if (!input.checked) allResults = false;
+      if (tr?.hasAttribute("data-folder")) {
+        descendantsOf(tr).forEach((row) => {
+          const box = rowCheckbox(row);
+          if (box && !box.disabled) box.checked = input.checked;
+        });
+      }
+    }
+    selectionChanged();
+  });
+
+  // ------------------------------------------------------------- pagination
+
+  const paginationState = () => {
+    const page = Number(pagination?.dataset.page ?? 1) || 1;
+    const pageSize = Number(pagination?.dataset.pageSize ?? 10) || 10;
+    const total = Number(pagination?.dataset.totalCount ?? 0) || 0;
+    return { page, pageSize, total, pageCount: Math.max(1, Math.ceil(total / pageSize)) };
+  };
+
+  const renderPagination = () => {
+    if (!pagination) return;
+    const { page, pageSize, total, pageCount } = paginationState();
+    const from = total === 0 ? 0 : (page - 1) * pageSize + 1;
+    const to = Math.min(page * pageSize, total);
+    setText('[data-slot="table-pagination-summary"]', `Showing ${from}–${to} of ${total}`, pagination);
+    setText('[data-slot="table-pagination-status"]', `Page ${page} of ${pageCount}`, pagination);
+    pagination.querySelectorAll<HTMLButtonElement>("[data-table-page]").forEach((button) => {
+      const dir = button.dataset.tablePage;
+      button.disabled = dir === "first" || dir === "prev" ? page <= 1 : page >= pageCount;
+    });
+  };
+
+  const setPage = (page: number, pageSize: number) => {
+    if (!pagination) return;
+    const accepted = emit("table:page", { page, pageSize });
+    if (!accepted) return;
+    pagination.dataset.page = String(page);
+    pagination.dataset.pageSize = String(pageSize);
+    allResults = false;
+    renderPagination();
+    announce(`Page ${page}`);
+  };
+
+  function goToPage(direction: string) {
+    const { page, pageSize, pageCount } = paginationState();
+    const next =
+      direction === "first" ? 1 : direction === "prev" ? page - 1 : direction === "next" ? page + 1 : pageCount;
+    const clamped = Math.min(pageCount, Math.max(1, next));
+    if (clamped !== page) setPage(clamped, pageSize);
+  }
+
+  pagination?.addEventListener("change", (event) => {
+    const select = event.target as HTMLSelectElement;
+    if (!select.matches("[data-table-page-size]")) return;
+    setPage(1, Number(select.value) || 10);
+  });
+
+  // ---------------------------------------------------------------- inbound
+
+  root.addEventListener("table:set", (event) => {
+    const detail = (event as CustomEvent<TableSetDetail>).detail ?? {};
+    if (detail.loading !== undefined) {
+      root.toggleAttribute("data-loading", detail.loading);
+      table.setAttribute("aria-busy", String(detail.loading));
+    }
+    if (detail.totalCount !== undefined) {
+      root.dataset.totalCount = String(detail.totalCount);
+      if (pagination) pagination.dataset.totalCount = String(detail.totalCount);
+    }
+    if (detail.page !== undefined && pagination) pagination.dataset.page = String(detail.page);
+    renderPagination();
+    syncSelection();
+  });
+
+  // ------------------------------------------------------------------- sync
+
+  const bindWidgets = () => {
+    table.querySelectorAll<HTMLElement>("[data-table-menu]").forEach((menu) => {
+      if (boundWidgets.has(menu)) return;
+      boundWidgets.add(menu);
+      bindMenuCell(menu);
+    });
+    table.querySelectorAll<HTMLElement>("[data-table-combobox]").forEach((combobox) => {
+      if (boundWidgets.has(combobox)) return;
+      boundWidgets.add(combobox);
+      bindCombobox(combobox);
+    });
+    table.querySelectorAll<HTMLElement>('[data-slot="table-resize-handle"]').forEach((handle) => {
+      if (boundWidgets.has(handle)) return;
+      boundWidgets.add(handle);
+      bindResize(handle);
+    });
+  };
+
+  const sync = () => {
+    repositionErrors();
+    bindWidgets();
+    applyTree();
+    applyColumns();
+    applyPinned();
+    syncSortAvailability();
+    syncSelection();
+    ensureTabStop();
+  };
+
+  let scheduled = false;
+  new MutationObserver(() => {
+    if (scheduled) return;
+    scheduled = true;
+    requestAnimationFrame(() => {
+      scheduled = false;
+      sync();
+    });
+  }).observe(table, { childList: true, subtree: true });
+
+  sync();
+  renderPagination();
+}