@iloveagents/foundry-web-ui 0.19.0 → 0.20.0

package/dist/components/data-table/data-table.js

@@ -7,17 +7,51 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  */
 import { flexRender } from "@tanstack/react-table";
 import { ChevronDown, ChevronRight } from "lucide-react";
+import { useCallback, useEffect, useRef, useState, } from "react";
+import { DATA_TABLE_MIN_WIDTH } from "./facets.js";
+import { useDataTableFrame } from "./data-table-frame.js";
+import { usePinnedOffsets } from "./use-pinned-offsets.js";
+import { useElementWidth } from "./use-element-width.js";
 import { cn } from "@iloveagents/foundry-web-primitives";
-const INTERACTIVE = "a, button, input, select, textarea, [role='menuitem'], [data-no-row-click]";
-/** Literal classes so Tailwind generates them: hide the column below the breakpoint. */
-const BREAKPOINT_CLASS = {
-    sm: "max-sm:hidden",
-    md: "max-md:hidden",
-    lg: "max-lg:hidden",
-    xl: "max-xl:hidden",
-    "2xl": "max-2xl:hidden",
-};
-const breakpointClass = (breakpoint) => breakpoint ? BREAKPOINT_CLASS[breakpoint] : undefined;
+// Native controls, the ARIA widgets that own the same keys (a slider or a
+// listbox answers to arrows; a checkbox to space), and anything a host marks.
+// A row's keyboard handling must never take a key out from under one of them.
+const INTERACTIVE = [
+    "a",
+    "button",
+    "input",
+    "select",
+    "textarea",
+    "[contenteditable]:not([contenteditable='false'])",
+    "[role='menuitem']",
+    "[role='menuitemcheckbox']",
+    "[role='menuitemradio']",
+    "[role='checkbox']",
+    "[role='radio']",
+    "[role='switch']",
+    "[role='slider']",
+    "[role='spinbutton']",
+    "[role='textbox']",
+    "[role='combobox']",
+    "[role='listbox']",
+    "[role='option']",
+    "[role='tab']",
+    // Arrow-owning composites: a tree or a grid inside a cell navigates with
+    // exactly the keys this table wants.
+    "[role='tree']",
+    "[role='treeitem']",
+    "[role='grid']",
+    "[role='gridcell']",
+    "[role='menu']",
+    "[role='menubar']",
+    "[role='radiogroup']",
+    // The plain ones: a div acting as a button or a link is still a control,
+    // and its click must not also open the row behind it.
+    "[role='button']",
+    "[role='link']",
+    "[data-no-row-click]",
+].join(", ");
+/** Group header rows and their expanded children, in declared group order. */
 function orderedRows(table, groupOrder) {
     const rows = table.getRowModel().rows;
     if (!table.getState().grouping.length)
@@ -33,35 +67,237 @@ function orderedRows(table, groupOrder) {
         : top;
     return sorted.flatMap((row) => row.getIsGrouped() && row.getIsExpanded() ? [row, ...row.subRows] : [row]);
 }
-export function DataTable({ table, onRowClick, activeRowId, rowClassName, renderGroup, groupOrder, emptyState = "No results.", stickyHeader = false, dense = false, className, "aria-label": ariaLabel, }) {
+export function DataTable({ table, onRowClick, onRowOpen, activeRowId, onActiveRowChange, rowClassName, renderGroup, groupOrder, emptyState = "No results.", spacer = true, stickyHeader = false, fill, maxHeight, dense = false, onRenderedColumnsChange, className, "aria-label": ariaLabel, }) {
+    const frame = useDataTableFrame();
+    // In focus mode the layer is a fixed flex column: the table takes the
+    // remaining height (`min-h-0` lets a flex item shrink below its content)
+    // and scrolls in both directions, so the toolbar above stays put.
+    const filling = fill ?? frame?.focused ?? false;
+    const bounded = !filling && maxHeight !== undefined;
+    // A header only sticks inside a scroll container — which is exactly what
+    // `fill` and `maxHeight` create.
+    const sticky = stickyHeader || filling || bounded;
     const rows = orderedRows(table, groupOrder);
-    const columnCount = table.getVisibleLeafColumns().length;
+    const dataRows = rows.filter((row) => !row.getIsGrouped());
+    const rootRef = useRef(null);
+    const scrollerRef = useRef(null);
+    const [scrolledX, setScrolledX] = useState(false);
+    const width = useElementWidth(rootRef);
+    // A column has to earn its place twice: the mode it is meant for, and the
+    // width the list actually has.
+    const fits = (meta) => {
+        // Focus mode is the question, not `fill`: `fill` is a scroll-layout prop
+        // a host may set on an ordinary page, and it would otherwise reveal
+        // columns meant for the fullscreen layer (and hide them inside it when
+        // a host passed `fill={false}`).
+        if (meta?.showIn === "focus" && !(frame?.focused ?? false))
+            return false;
+        const breakpoint = meta?.breakpoint;
+        return !breakpoint || width === undefined || width >= DATA_TABLE_MIN_WIDTH[breakpoint];
+    };
+    // What the table actually draws: TanStack visibility, then the width and
+    // mode gates. Everything downstream — the pinned run, the empty-row colspan,
+    // what the host is told — is derived from this one list, so none of them can
+    // name a column that is not on screen.
+    const renderedColumns = table
+        .getVisibleLeafColumns()
+        .filter((column) => fits(column.columnDef.meta));
+    // Width of the leaves that survive the gates; `undefined` when none of them
+    // declares one, so the column keeps its natural width.
+    const fittingLeafWidth = (header) => {
+        // Walk `subHeaders` rather than `getLeafHeaders()`: the latter includes
+        // this header's own entry, whose size already sums the descendants, and
+        // the total would count everything twice.
+        const collect = (node) => node.subHeaders.length
+            ? node.subHeaders.flatMap(collect)
+            : fits(node.column.columnDef.meta)
+                ? [node]
+                : [];
+        const sizes = collect(header).map((leaf) => leaf.getSize());
+        if (!sizes.length)
+            return undefined;
+        return sizes.every((size) => size === 150) ? undefined : sizes.reduce((a, b) => a + b, 0);
+    };
+    const fittingLeafCount = (header) => header.subHeaders.length === 0
+        ? fits(header.column.columnDef.meta)
+            ? 1
+            : 0
+        : header.subHeaders.reduce((total, sub) => total + fittingLeafCount(sub), 0);
+    // Pinned columns: frozen against the left edge so a row keeps its identity
+    // while the rest of a wide table scrolls sideways.
+    // Freezing is a run from the left edge: everything up to the last pinned
+    // column comes along, so a leading checkbox never slides out from under the
+    // rows it belongs to. A pinned column the width gate dropped is not in the
+    // run at all — otherwise the seam would mark a column nobody can see.
+    const lastPinnedIndex = renderedColumns.reduce((last, column, index) => (column.columnDef.meta?.pinned === "left" ? index : last), -1);
+    const pinnedIds = renderedColumns.slice(0, lastPinnedIndex + 1).map((column) => column.id);
+    const { offsets, lastPinned, measure } = usePinnedOffsets(pinnedIds);
+    // A pinned cell is opaque — the other columns slide underneath it — and it
+    // restates the row's hover / selected / active tints. Those rules live in
+    // this package's `styles.css`, keyed off the attributes below, so a host
+    // needs no CSS wiring of its own.
+    const pinnedProps = (columnId, tone) => offsets[columnId] === undefined
+        ? {}
+        : {
+            "data-pinned": tone,
+            "data-pinned-edge": columnId === lastPinned ? "" : undefined,
+        };
+    const pinnedStyle = (columnId) => offsets[columnId] === undefined ? undefined : { left: offsets[columnId] };
+    // Keyboard: the active row moves with the arrows and stays in view, so a
+    // long list can be walked without touching the mouse.
+    const bodyRef = useRef(null);
+    const moveActive = useCallback((delta) => {
+        if (!onActiveRowChange || dataRows.length === 0)
+            return;
+        const index = dataRows.findIndex((row) => row.id === activeRowId);
+        const next = delta === "first"
+            ? 0
+            : delta === "last"
+                ? dataRows.length - 1
+                : index < 0
+                    ? delta > 0
+                        ? 0
+                        : dataRows.length - 1
+                    : Math.min(dataRows.length - 1, Math.max(0, index + delta));
+        const row = dataRows[next];
+        if (row)
+            onActiveRowChange(row);
+    }, [activeRowId, dataRows, onActiveRowChange]);
+    // Sorting, filtering or a late-arriving page moves the active row without
+    // changing its id, and an id restored before the rows load points at nothing
+    // yet — so the position is part of what this watches.
+    const activeIndex = dataRows.findIndex((row) => row.id === activeRowId);
+    useEffect(() => {
+        if (!activeRowId || activeIndex < 0)
+            return;
+        const element = Array.from(bodyRef.current?.querySelectorAll("tr[data-row-id]") ?? []).find((row) => row.dataset.rowId === activeRowId);
+        element?.scrollIntoView?.({ block: "nearest" });
+        // Take the keyboard along, but only when it is on a ROW: arrows move the
+        // active row, and leaving focus on the row it left means the next Enter
+        // opens the wrong one. Focus inside a cell's own control stays there —
+        // moving it would eject someone mid-edit when a re-sort happens to shift
+        // the row — and focus elsewhere on the page is never stolen.
+        const active = typeof document === "undefined" ? null : document.activeElement;
+        const onARow = active instanceof HTMLElement &&
+            active.matches("tr[data-row-id]") &&
+            bodyRef.current?.contains(active);
+        if (element && onARow && active !== element) {
+            element.focus?.({ preventScroll: true });
+        }
+    }, [activeRowId, activeIndex]);
+    const columnCount = renderedColumns.length + (spacer ? 1 : 0);
+    const renderedIds = renderedColumns.map((column) => column.id);
+    // JSON, not a comma-joined string: a column id may contain a comma, and
+    // splitting one back apart would report columns that do not exist (and let
+    // two different sets share a key, so the host is never told).
+    const renderedKey = JSON.stringify(renderedIds);
+    const renderedRef = useRef(onRenderedColumnsChange);
+    renderedRef.current = onRenderedColumnsChange;
+    const renderedIdsRef = useRef(renderedIds);
+    renderedIdsRef.current = renderedIds;
+    useEffect(() => {
+        renderedRef.current?.(renderedIdsRef.current);
+    }, [renderedKey]);
     const cellPad = dense ? "px-3 py-1.5" : "px-3 py-2.5";
-    const activate = (row, event) => {
-        if (!onRowClick)
+    const activate = (row, event, handler) => {
+        if (!handler)
             return;
         const target = event.target;
         if (target?.closest(INTERACTIVE))
             return;
-        onRowClick(row, event);
+        handler(row, event);
     };
-    return (_jsx("div", { className: cn("overflow-hidden rounded-2xl border border-border/45 bg-card/60", className), children: _jsx("div", { className: "overflow-x-auto", children: _jsxs("table", { className: "w-full caption-bottom text-sm", "aria-label": ariaLabel, children: [_jsx("thead", { className: cn(stickyHeader && "sticky top-0 z-10 bg-card"), children: table.getHeaderGroups().map((headerGroup) => (_jsx("tr", { className: "border-b border-border/45", children: headerGroup.headers.map((header) => {
-                                const meta = header.column.columnDef.meta;
-                                return (_jsx("th", { colSpan: header.colSpan, scope: "col", style: header.getSize() !== 150 ? { width: header.getSize() } : undefined, className: cn("h-10 px-3 text-left align-middle text-xs font-medium text-muted-foreground", meta?.align === "right" && "text-right", meta?.align === "center" && "text-center", breakpointClass(meta?.breakpoint), meta?.headerClassName), children: header.isPlaceholder
-                                        ? null
-                                        : flexRender(header.column.columnDef.header, header.getContext()) }, header.id));
-                            }) }, headerGroup.id))) }), _jsx("tbody", { children: rows.length === 0 ? (_jsx("tr", { children: _jsx("td", { colSpan: columnCount, className: "h-24 text-center text-sm text-muted-foreground", children: emptyState }) })) : (rows.map((row) => row.getIsGrouped() ? (_jsx("tr", { "data-group-row": "", className: "border-t border-border/45 bg-muted/35 text-sm font-medium", children: _jsx("td", { colSpan: columnCount, className: "px-3 py-1.5", children: _jsxs("div", { className: "flex items-center gap-2", children: [_jsx("button", { type: "button", onClick: row.getToggleExpandedHandler(), "aria-expanded": row.getIsExpanded(), "aria-label": row.getIsExpanded() ? "Collapse group" : "Expand group", className: "rounded-md p-0.5 text-muted-foreground hover:bg-accent hover:text-foreground", children: row.getIsExpanded() ? (_jsx(ChevronDown, { className: "size-4" })) : (_jsx(ChevronRight, { className: "size-4" })) }), _jsx("div", { className: "min-w-0 flex-1", children: renderGroup ? renderGroup(row) : _jsx(DefaultGroupLabel, { row: row }) })] }) }) }, row.id)) : (_jsx("tr", { "data-row-id": row.id, "data-state": row.getIsSelected() ? "selected" : undefined, "data-active": activeRowId != null && row.id === activeRowId ? "" : undefined, "aria-current": activeRowId != null && row.id === activeRowId ? "true" : undefined, "aria-selected": row.getIsSelected() || undefined, tabIndex: onRowClick ? 0 : undefined, onClick: (event) => activate(row, event), onKeyDown: (event) => {
-                                if (event.key === "Enter" || event.key === " ") {
+    return (_jsx("div", { ref: rootRef, "data-scrolled-x": scrolledX ? "" : undefined, className: cn("overflow-hidden rounded-2xl border border-border/45 bg-card/60", filling && "flex min-h-0 flex-1 flex-col", className), children: _jsx("div", { ref: scrollerRef, onScroll: (event) => {
+                const next = event.currentTarget.scrollLeft > 0;
+                setScrolledX((current) => (current === next ? current : next));
+            }, "data-list-scroller": "", style: bounded ? { maxHeight } : undefined, className: cn(filling ? "min-h-0 flex-1 overflow-auto" : bounded ? "overflow-auto" : "overflow-x-auto"), children: _jsxs("table", { className: "w-full caption-bottom text-sm", "aria-label": ariaLabel, onKeyDown: onActiveRowChange
+                    ? (event) => {
+                        // Let a control that owns these keys keep them.
+                        if (event.target.closest(INTERACTIVE))
+                            return;
+                        if (event.key === "ArrowDown")
+                            moveActive(1);
+                        else if (event.key === "ArrowUp")
+                            moveActive(-1);
+                        else if (event.key === "Home")
+                            moveActive("first");
+                        else if (event.key === "End")
+                            moveActive("last");
+                        else if (event.key === "Escape") {
+                            // Only when there IS a row to let go of. One Escape, one
+                            // effect: it clears the active row without also leaving
+                            // focus mode — but with no active row it belongs to the
+                            // frame, so it is left alone to bubble there.
+                            if (!activeRowId)
+                                return;
+                            onActiveRowChange(null);
+                            event.stopPropagation();
+                            event.nativeEvent.stopImmediatePropagation();
+                        }
+                        else
+                            return;
+                        event.preventDefault();
+                    }
+                    : undefined, children: [_jsx("thead", { className: cn(sticky && "sticky top-0 z-10 bg-card"), children: table.getHeaderGroups().map((headerGroup) => (_jsxs("tr", { className: "border-b border-border/45", children: [headerGroup.headers.map((header) => {
+                                    const meta = header.column.columnDef.meta;
+                                    // A grouping header spans its leaves; when the width gate
+                                    // drops some of them it has to narrow, and when it drops all
+                                    // of them the group header goes too.
+                                    const span = fittingLeafCount(header);
+                                    if (span === 0)
+                                        return null;
+                                    // `getSize()` sums EVERY descendant, including the ones the
+                                    // width gate just dropped, so a half-gated group would hold
+                                    // space for a column that is not there and push the table
+                                    // wider than its own columns.
+                                    const sized = header.subHeaders.length
+                                        ? fittingLeafWidth(header)
+                                        : header.getSize();
+                                    return (_jsx("th", { colSpan: span, scope: "col", 
+                                        // Every column in the run, not only the marked ones: the
+                                        // run can start with an unmarked leader (a selection
+                                        // checkbox), and an unmeasured leader leaves the column
+                                        // after it stacked at zero, overlapping it.
+                                        ref: pinnedIds.includes(header.column.id) ? measure(header.column.id) : undefined, ...pinnedProps(header.column.id, "header"), style: {
+                                            ...(sized !== undefined && sized !== 150 ? { width: sized } : {}),
+                                            ...pinnedStyle(header.column.id),
+                                        }, className: cn("h-10 px-3 text-left align-middle text-xs font-medium text-muted-foreground", meta?.align === "right" && "text-right", meta?.align === "center" && "text-center", meta?.headerClassName), children: header.isPlaceholder
+                                            ? null
+                                            : flexRender(header.column.columnDef.header, header.getContext()) }, header.id));
+                                }), spacer ? _jsx("th", { "aria-hidden": "true", className: "w-full p-0" }) : null] }, headerGroup.id))) }), _jsx("tbody", { ref: bodyRef, children: rows.length === 0 ? (_jsx("tr", { children: _jsx("td", { colSpan: columnCount, className: "h-24 text-center text-sm text-muted-foreground", children: emptyState }) })) : (rows.map((row) => row.getIsGrouped() ? (_jsx("tr", { "data-group-row": "", className: "border-t border-border/45 bg-muted/35 text-sm font-medium", children: _jsx("td", { colSpan: columnCount, className: "p-0", children: _jsxs("div", { "data-group-content": "", style: width ? { width } : undefined, className: "flex items-center gap-2 px-3 py-1.5", children: [_jsx("button", { type: "button", onClick: row.getToggleExpandedHandler(), "aria-expanded": row.getIsExpanded(), "aria-label": row.getIsExpanded() ? "Collapse group" : "Expand group", className: "rounded-md p-0.5 text-muted-foreground hover:bg-accent hover:text-foreground", children: row.getIsExpanded() ? (_jsx(ChevronDown, { className: "size-4" })) : (_jsx(ChevronRight, { className: "size-4" })) }), _jsx("div", { className: "min-w-0 flex-1", children: renderGroup ? renderGroup(row) : _jsx(DefaultGroupLabel, { row: row }) })] }) }) }, row.id)) : (_jsxs("tr", { "data-row-id": row.id, "data-state": row.getIsSelected() ? "selected" : undefined, "data-active": activeRowId != null && row.id === activeRowId ? "" : undefined, "aria-current": activeRowId != null && row.id === activeRowId ? "true" : undefined, "aria-selected": row.getIsSelected() || undefined, "data-clickable": onRowClick || onRowOpen ? "" : undefined, "data-focusable": onRowClick || onRowOpen || onActiveRowChange ? "" : undefined, tabIndex: onRowClick || onRowOpen || onActiveRowChange ? 0 : undefined, 
+                            // `detail` counts the clicks in the sequence: the second
+                            // one belongs to the double-click that follows, and
+                            // letting it through would toggle a selection off again
+                            // right before the row opens.
+                            onClick: (event) => {
+                                if (event.detail > 1)
+                                    return;
+                                activate(row, event, onRowClick);
+                            }, onDoubleClick: (event) => activate(row, event, onRowOpen), onKeyDown: (event) => {
+                                if (event.key === "Enter") {
+                                    if (event.target.closest(INTERACTIVE))
+                                        return;
+                                    event.preventDefault();
+                                    activate(row, event, onRowOpen ?? onRowClick);
+                                }
+                                else if (event.key === " ") {
                                     if (event.target.closest(INTERACTIVE))
                                         return;
                                     event.preventDefault();
-                                    activate(row, event);
+                                    activate(row, event, onRowClick);
                                 }
-                            }, className: cn("border-t border-border/35 transition-colors", onRowClick &&
-                                "cursor-pointer hover:bg-muted/30 focus-visible:bg-muted/30 focus-visible:outline-none", "data-[state=selected]:bg-primary/6 data-[active]:bg-primary/8", rowClassName?.(row)), children: row.getVisibleCells().map((cell) => {
-                                const meta = cell.column.columnDef.meta;
-                                return (_jsx("td", { className: cn(cellPad, "align-middle", meta?.align === "right" && "text-right", meta?.align === "center" && "text-center", breakpointClass(meta?.breakpoint), meta?.className), children: flexRender(cell.column.columnDef.cell, cell.getContext()) }, cell.id));
-                            }) }, row.id)))) })] }) }) }));
+                            }, className: cn("group/row border-t border-border/35 transition-colors", (onRowClick || onRowOpen) && "cursor-pointer hover:bg-muted/30", 
+                            // Anything focusable has to SHOW where the keyboard is —
+                            // a list navigated with the arrows is focusable without
+                            // being clickable, and silent focus leaves a keyboard
+                            // user guessing which row the next key belongs to.
+                            (onRowClick || onRowOpen || onActiveRowChange) &&
+                                "focus-visible:bg-muted/30 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-inset focus-visible:ring-ring", "data-[state=selected]:bg-primary/6 data-[active]:bg-primary/8", rowClassName?.(row)), children: [row.getVisibleCells().map((cell) => {
+                                    const meta = cell.column.columnDef.meta;
+                                    if (!fits(meta))
+                                        return null;
+                                    return (_jsx("td", { ...pinnedProps(cell.column.id, "cell"), style: pinnedStyle(cell.column.id), className: cn(cellPad, "align-middle", meta?.align === "right" && "text-right", meta?.align === "center" && "text-center", meta?.className), children: flexRender(cell.column.columnDef.cell, cell.getContext()) }, cell.id));
+                                }), spacer ? _jsx("td", { "aria-hidden": "true", className: "w-full p-0" }) : null] }, row.id)))) })] }) }) }));
 }
 function DefaultGroupLabel({ row }) {
     const grouping = row

package/dist/components/data-table/date-buckets.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Dates as things you can tick. A timestamp is never a facet value — nobody
+ * filters by "2026-08-14T09:12:03Z" — so these turn one into the words a
+ * person actually means: how old it is, and whether it is late. Pair them
+ * with `meta.facetBuckets`, which is what the rest of the machinery counts,
+ * ORs, ANDs and puts in the URL.
+ *
+ * Every list with a date wants this, which is why it lives here rather than
+ * being written again in each one.
+ */
+export interface DateBucketOptions {
+    /** The moment to measure against (default: now). Pass it to keep a test still. */
+    now?: number;
+}
+export declare function parseDateish(value: unknown): number | null;
+export type AgeBucket = "today" | "week" | "month" | "older" | "never";
+/** The narrowest bucket something falls in — the one to LABEL it with. */
+export declare function ageBucket(value: unknown, options?: DateBucketOptions): AgeBucket;
+/**
+ * Every bucket something belongs to — what a FILTER needs.
+ *
+ * "Last 7 days" includes today. Saying it does not is technically defensible
+ * and reads as broken: a register where everything had just been touched
+ * showed "Today 11, Last 7 days 8, Last 30 days 0", three numbers that
+ * cannot all be true of the same rows. Ranges nest, so the keys nest, and
+ * the counts come out as totals a person can check by eye.
+ *
+ * The tail ("older than 30 days") and "never" are states rather than
+ * ranges, so they stand alone.
+ */
+export declare function ageBuckets(value: unknown, options?: DateBucketOptions): AgeBucket[];
+export interface DueStateOptions extends DateBucketOptions {
+    /** How near counts as "soon" (default 30 days). */
+    soonDays?: number;
+}
+export type DueState = "overdue" | "soon" | "later" | "undated";
+/**
+ * Where a deadline stands. `undated` is its own answer, not a guess: plenty
+ * of real deadlines are written as "Contract signature (May)", and calling
+ * those neither late nor on time is the honest reading.
+ */
+export declare function dueState(value: unknown, options?: DueStateOptions): DueState;
+/** "today" · "yesterday" · "6 d ago" · the date once that stops being useful. */
+export declare function relativeAge(value: unknown, options?: DateBucketOptions): string;

package/dist/components/data-table/date-buckets.js

@@ -0,0 +1,178 @@
+/**
+ * Dates as things you can tick. A timestamp is never a facet value — nobody
+ * filters by "2026-08-14T09:12:03Z" — so these turn one into the words a
+ * person actually means: how old it is, and whether it is late. Pair them
+ * with `meta.facetBuckets`, which is what the rest of the machinery counts,
+ * ORs, ANDs and puts in the URL.
+ *
+ * Every list with a date wants this, which is why it lives here rather than
+ * being written again in each one.
+ */
+const DAY = 86400000;
+/**
+ * Milliseconds for a value that carries a date, `null` for one that does not.
+ *
+ * Only shapes whose meaning is not in doubt are read: ISO (`2026-08-22`, with
+ * an optional time and zone), the dotted European `d.m.yyyy`, and year-first
+ * `yyyy/m/d`. Everything else is `null` — including `03/04/2026` and
+ * `03-04-2026`, which are March in one country and April in another.
+ *
+ * The alternative, handing the leftovers to `Date.parse`, is what makes that
+ * guess quietly: it reads `03-04-2026` as March 4th and even turns `"1"` into
+ * a date. A field where people legitimately write "Contract signature (May)"
+ * needs a parser that says no.
+ */
+const ISO = /^(\d{4})-(\d{2})-(\d{2})(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?\s*(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+const DOTTED = /^(\d{1,2})\.(\d{1,2})\.(\d{4})$/;
+const YEAR_FIRST = /^(\d{4})\/(\d{1,2})\/(\d{1,2})$/;
+/**
+ * Midnight at the start of that date, in the reader's own zone — and `null`
+ * if the date does not exist (2026-02-31 is a typo).
+ *
+ * Local, not UTC: a date somebody typed into a form means that day where
+ * they are. Reading it as UTC makes "22 August" start at 17:00 on the 21st
+ * for a reader in UTC−7, which then puts the row in the wrong bucket and
+ * marks a deadline overdue most of a day early.
+ */
+function localDay(year, month, day) {
+    if (month < 1 || month > 12 || day < 1 || day > 31)
+        return null;
+    const at = new Date(year, month - 1, day).getTime();
+    const check = new Date(at);
+    return check.getFullYear() === year && check.getMonth() === month - 1 && check.getDate() === day
+        ? at
+        : null;
+}
+/** Midnight of the local calendar day an instant falls in. */
+function startOfDay(at) {
+    const date = new Date(at);
+    return new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime();
+}
+/**
+ * The last millisecond of that local day — built from the NEXT day's calendar
+ * fields, never by adding 24 hours. On a daylight-saving change the day is 23
+ * or 25 hours long, and a fixed offset would end it an hour early in autumn
+ * and an hour into tomorrow in spring.
+ */
+function endOfDay(at) {
+    const date = new Date(at);
+    return new Date(date.getFullYear(), date.getMonth(), date.getDate() + 1).getTime() - 1;
+}
+/**
+ * Whole calendar days between two instants — 23:30 and 00:30 the next
+ * morning are ONE day apart even though barely an hour passed. Everything
+ * a person calls "today" or "yesterday" is a calendar question, so counting
+ * elapsed milliseconds gets it wrong twice a night.
+ */
+function calendarDaysBetween(from, to) {
+    return Math.round((startOfDay(to) - startOfDay(from)) / DAY);
+}
+function parseParts(value) {
+    if (value == null || value === "")
+        return null;
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? null : { at: value.getTime(), dateOnly: false };
+    if (typeof value === "number")
+        return Number.isFinite(value) ? { at: value, dateOnly: false } : null;
+    const text = String(value).trim();
+    if (!text)
+        return null;
+    const iso = ISO.exec(text);
+    if (iso) {
+        // The calendar day has to be real; the clock and zone are `Date.parse`'s
+        // job, and it handles ISO without guessing.
+        const day = localDay(Number(iso[1]), Number(iso[2]), Number(iso[3]));
+        if (day === null)
+            return null;
+        // A bare date is that day where the reader is; one carrying a clock (and
+        // possibly a zone) is the instant it names.
+        if (text.length === 10)
+            return { at: day, dateOnly: true };
+        const parsed = Date.parse(text);
+        return Number.isNaN(parsed) ? null : { at: parsed, dateOnly: false };
+    }
+    const dotted = DOTTED.exec(text);
+    if (dotted) {
+        const at = localDay(Number(dotted[3]), Number(dotted[2]), Number(dotted[1]));
+        return at === null ? null : { at, dateOnly: true };
+    }
+    const yearFirst = YEAR_FIRST.exec(text);
+    if (yearFirst) {
+        const at = localDay(Number(yearFirst[1]), Number(yearFirst[2]), Number(yearFirst[3]));
+        return at === null ? null : { at, dateOnly: true };
+    }
+    return null;
+}
+export function parseDateish(value) {
+    return parseParts(value)?.at ?? null;
+}
+/** The narrowest bucket something falls in — the one to LABEL it with. */
+export function ageBucket(value, options = {}) {
+    const at = parseDateish(value);
+    if (at === null)
+        return "never";
+    const days = calendarDaysBetween(at, options.now ?? Date.now());
+    if (days <= 0)
+        return "today";
+    if (days < 7)
+        return "week";
+    if (days < 30)
+        return "month";
+    return "older";
+}
+/**
+ * Every bucket something belongs to — what a FILTER needs.
+ *
+ * "Last 7 days" includes today. Saying it does not is technically defensible
+ * and reads as broken: a register where everything had just been touched
+ * showed "Today 11, Last 7 days 8, Last 30 days 0", three numbers that
+ * cannot all be true of the same rows. Ranges nest, so the keys nest, and
+ * the counts come out as totals a person can check by eye.
+ *
+ * The tail ("older than 30 days") and "never" are states rather than
+ * ranges, so they stand alone.
+ */
+export function ageBuckets(value, options = {}) {
+    const narrowest = ageBucket(value, options);
+    if (narrowest === "today")
+        return ["today", "week", "month"];
+    if (narrowest === "week")
+        return ["week", "month"];
+    if (narrowest === "month")
+        return ["month"];
+    return [narrowest];
+}
+/**
+ * Where a deadline stands. `undated` is its own answer, not a guess: plenty
+ * of real deadlines are written as "Contract signature (May)", and calling
+ * those neither late nor on time is the honest reading.
+ */
+export function dueState(value, options = {}) {
+    const parts = parseParts(value);
+    if (parts === null)
+        return "undated";
+    const now = options.now ?? Date.now();
+    // A date with no clock is a whole day, and someone with until Friday is not
+    // late on Friday morning — so it runs out at the end of that day where
+    // they are. A real timestamp is compared as the instant it is.
+    const deadline = parts.dateOnly ? endOfDay(parts.at) : parts.at;
+    if (deadline < now)
+        return "overdue";
+    return deadline - now <= (options.soonDays ?? 30) * DAY ? "soon" : "later";
+}
+/** "today" · "yesterday" · "6 d ago" · the date once that stops being useful. */
+export function relativeAge(value, options = {}) {
+    const at = parseDateish(value);
+    if (at === null)
+        return "—";
+    const days = calendarDaysBetween(at, options.now ?? Date.now());
+    if (days <= 0)
+        return "today";
+    if (days === 1)
+        return "yesterday";
+    if (days < 30)
+        return `${days} d ago`;
+    const date = new Date(at);
+    const pad = (part) => String(part).padStart(2, "0");
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}

package/dist/components/data-table/facets.d.ts

@@ -21,16 +21,47 @@ declare module "@tanstack/react-table" {
         searchText?: (row: TData) => string;
         /** Labels for facet keys and group headers (`value → label`). */
         facetLabels?: Record<string, string>;
-        /** Smallest viewport the column is shown at; below it the column is hidden (the View menu can still force it). */
+        /** Narrowest list width the column is shown at; below it the column hides (the Columns menu still lists it). */
         breakpoint?: DataTableBreakpoint;
+        /**
+         * Which mode the column earns its place in. `"always"` (default) means
+         * wherever it fits; `"focus"` keeps it for when the list has the screen
+         * to itself, so a page-embedded list stays scannable and going
+         * fullscreen actually shows you more.
+         */
+        showIn?: "always" | "focus";
+        /** Start hidden: available in the Columns menu, off until asked for. */
+        defaultHidden?: boolean;
+        /**
+         * Turn a raw value into the facet keys it belongs to — how a number or a
+         * date becomes something you can tick: "≥ 50 %", "overdue", "this week".
+         * The rest of the machinery (counts, OR within, AND across, the URL, the
+         * agent tools) works on those keys unchanged.
+         */
+        facetBuckets?: (value: unknown) => string[];
+        /** Freeze the column against the left edge while the table scrolls sideways. */
+        pinned?: "left";
         /** Keep unused type parameter referenced for declaration merging. */
         __cellValue?: TValue;
         /** Hosts may carry their own keys in `meta` (e.g. a server sort key). */
         [key: string]: unknown;
     }
 }
-/** Tailwind breakpoints a column can be gated on. */
+/**
+ * How much room a column needs. Measured against the *list's* own width, not
+ * the window — so a list beside an open detail pane sheds columns and gets
+ * them back in focus mode, with no work from the host.
+ *
+ * `sm` 448px · `md` 672px · `lg` 896px · `xl` 1024px · `2xl` 1280px.
+ */
 export type DataTableBreakpoint = "sm" | "md" | "lg" | "xl" | "2xl";
+/**
+ * The list width at which each band starts earning its columns. Measured on
+ * the list itself, not the viewport — a list in a side pane is narrow even on
+ * a wide screen. Exported so a host that derives breakpoints from a schema
+ * measures against the same numbers the table renders by.
+ */
+export declare const DATA_TABLE_MIN_WIDTH: Record<DataTableBreakpoint, number>;
 /** Facet key for empty cells (`null`, `undefined`, `""`, `[]`). */
 export declare const FACET_EMPTY = "__none__";
 export interface DataTableFacetOption {
@@ -48,6 +79,7 @@ export interface DataTableFacetCount extends DataTableFacetOption {
  * element. A real value that spells the empty sentinel is escaped with a
  * leading backslash so it never masquerades as "no value".
  */
+export declare function columnFacetKeys<T>(column: Column<T, unknown>, value: unknown): string[];
 export declare function facetKeys(value: unknown): string[];
 /** A facet filter value is a list of selected keys; anything else means "no filter". */
 export declare function normalizeFacetValue(filterValue: unknown): string[];