@iloveagents/foundry-web-ui 0.19.0 → 0.20.1

package/README.md

@@ -61,6 +61,86 @@ its values, `meta.label` names the column in the View menu, and
 (with `parseDataTableState` / `mergeDataTableUrlState`) to keep the whole list
 state in the URL.
 
+### A column says where it earns its place
+
+```tsx
+const column: ColumnDef<Risk> = {
+  id: "worst_case",
+  accessorKey: "worst_case",
+  meta: {
+    breakpoint: "lg", // the narrowest LIST width it needs (not the window)
+    showIn: "focus", // only when the list has the screen to itself
+    pinned: "left", // frozen against the left edge while the rest scrolls
+    defaultHidden: true, // in the Columns menu, off until asked for*
+    align: "right",
+  },
+};
+```
+
+Widths are measured on the table itself, so a list beside an open detail pane
+sheds exactly the columns a narrow window would and focus mode brings them
+back — no media queries in the host. `DATA_TABLE_MIN_WIDTH` publishes the
+bands (`sm` 448 · `md` 672 · `lg` 896 · `xl` 1024 · `2xl` 1280) for a host that
+derives them from a schema.
+
+\* `useDataTable` applies `defaultHidden` to its own initial state. A list
+whose state lives elsewhere (the URL) passes `defaultHiddenColumns(columns)`
+into that layer's `defaults` instead — a hidden-only URL records nothing when
+a column is _shown_, so re-applying the default on every render would undo the
+user the moment they bring one out.
+
+Freezing is a run from the left edge: every column up to the last `pinned` one
+comes along, so a leading checkbox never slides out from under its rows.
+
+That gating is render-time and deliberately **not** TanStack `columnVisibility`
+(which belongs to the user and rides in the URL), so anything that must agree
+with what is on screen reads `onRenderedColumnsChange` rather than
+`column.getIsVisible()`.
+
+### Numbers and dates you can tick
+
+`meta.facetBuckets` turns a raw value into the keys a person actually filters
+by; counts, OR-within, AND-across, the URL and the agent tools work on those
+keys unchanged.
+
+```tsx
+const probability: ColumnDef<Risk> = {
+  id: "probability",
+  accessorKey: "probability",
+  filterFn: facetFilterFn,
+  meta: {
+    facetBuckets: (value) => [Number(value) >= 0.5 ? "high" : "low"],
+    facetLabels: { high: "50 % or more", low: "under 50 %" },
+  },
+};
+```
+
+Dates get the buckets every list wants: `ageBucket` (`today` · `week` ·
+`month` · `older` · `never`), `dueState` (`overdue` · `soon` · `later` ·
+`undated`) and `relativeAge` for the cell. `parseDateish` underneath reads ISO
+and the dotted European form and refuses `03/04/2026` — March in one country,
+April in another — rather than guessing.
+
+### Selecting, opening, and the keyboard
+
+A click selects (`onRowClick`), Enter or a double click opens (`onRowOpen`) —
+the desktop-list split, so brushing a row never opens a pane by surprise.
+`selectionColumn()` adds the tick boxes; `DataTableSelectionBar` is the one
+place bulk actions live (and the selection a chat agent reads).
+`onActiveRowChange` + `activeRowId` walk the list with ↑/↓/Home/End, Escape
+clears, and the active row stays scrolled into view.
+
+`useAppStore.setContextItem(key, item | null)` keeps one context chip per key,
+so a list can keep the chat in step with its selection instead of piling up
+stale chips.
+
+### Room to scroll
+
+`DataTable` takes `maxHeight` to give a list its own viewport (sticky header,
+both axes) instead of running down the page; inside a focused `DataTableFrame`
+it fills the layer. `spacer` (default) keeps columns at their natural width
+with the slack at the end, the way a spreadsheet looks.
+
 ## Extension Points
 
 Feature modules (like SPACES) plug into `@iloveagents/foundry-web-ui` via registries — no direct imports needed:

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

@@ -14,11 +14,18 @@ export function DataTableFacetedFilter({ column, title, options: declared, searc
         const needle = query.trim().toLowerCase();
         return needle ? options.filter((o) => o.label.toLowerCase().includes(needle)) : options;
     }, [options, query]);
+    // A functional update, not one derived from this render's `selected`: with
+    // URL-backed state the re-render lands a tick later, so two quick clicks
+    // would otherwise both start from the same value and the first would be
+    // lost.
     const toggle = (value) => {
-        const next = selectedSet.has(value)
-            ? selected.filter((item) => item !== value)
-            : [...selected, value];
-        column.setFilterValue(next.length ? next : undefined);
+        column.setFilterValue((current) => {
+            const values = normalizeFacetValue(current);
+            const next = values.includes(value)
+                ? values.filter((item) => item !== value)
+                : [...values, value];
+            return next.length ? next : undefined;
+        });
     };
     return (_jsxs(Popover, { onOpenChange: (open) => {
             if (open)

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

@@ -3,6 +3,19 @@
  * fullscreen layer (Escape leaves it). `DataTableToolbar` shows the focus
  * button whenever it renders inside a frame — users with wide lists get a
  * way out of a cramped page without the host doing anything.
+ *
+ * The focus layer stays where it is in the tree — only its classes change —
+ * so entering and leaving focus never remounts the list (its rows, drawer,
+ * selection and in-flight edits survive) and it keeps inheriting the host's
+ * theme scope. It never scrolls itself: it is a fixed flex column whose
+ * growing child — the table — owns the scrolling, which keeps the toolbar in
+ * place while the rows move under a sticky header (see `DataTable`, which
+ * reads this context).
+ *
+ * A `position: fixed` layer is relative to the viewport unless an ancestor
+ * establishes a containing block (`transform`, `filter`, `perspective`,
+ * `contain: paint`); a host that does that on a list's ancestor has to opt
+ * out of focus mode.
  */
 import { type HTMLAttributes, type ReactNode } from "react";
 export interface DataTableFrameContextValue {
@@ -16,5 +29,7 @@ export interface DataTableFrameProps extends Omit<HTMLAttributes<HTMLDivElement>
     /** Classes applied in focus mode on top of the fullscreen layer. */
     focusClassName?: string;
     defaultFocused?: boolean;
+    /** Told when focus mode turns on or off — a host with room to spare can show more. */
+    onFocusChange?: (focused: boolean) => void;
 }
-export declare function DataTableFrame({ children, className, focusClassName, defaultFocused, ...rest }: DataTableFrameProps): import("react/jsx-runtime").JSX.Element;
+export declare const DataTableFrame: import("react").ForwardRefExoticComponent<DataTableFrameProps & import("react").RefAttributes<HTMLDivElement>>;

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

@@ -4,22 +4,41 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * fullscreen layer (Escape leaves it). `DataTableToolbar` shows the focus
  * button whenever it renders inside a frame — users with wide lists get a
  * way out of a cramped page without the host doing anything.
+ *
+ * The focus layer stays where it is in the tree — only its classes change —
+ * so entering and leaving focus never remounts the list (its rows, drawer,
+ * selection and in-flight edits survive) and it keeps inheriting the host's
+ * theme scope. It never scrolls itself: it is a fixed flex column whose
+ * growing child — the table — owns the scrolling, which keeps the toolbar in
+ * place while the rows move under a sticky header (see `DataTable`, which
+ * reads this context).
+ *
+ * A `position: fixed` layer is relative to the viewport unless an ancestor
+ * establishes a containing block (`transform`, `filter`, `perspective`,
+ * `contain: paint`); a host that does that on a list's ancestor has to opt
+ * out of focus mode.
  */
-import { createContext, useContext, useEffect, useMemo, useState, } from "react";
+import { createContext, forwardRef, useContext, useEffect, useMemo, useRef, useState, } from "react";
 import { cn } from "@iloveagents/foundry-web-primitives";
 const DataTableFrameContext = createContext(null);
 /** The enclosing frame's focus state, or `null` outside a frame. */
 export function useDataTableFrame() {
     return useContext(DataTableFrameContext);
 }
-export function DataTableFrame({ children, className, focusClassName, defaultFocused = false, ...rest }) {
+export const DataTableFrame = forwardRef(function DataTableFrame({ children, className, focusClassName, defaultFocused = false, onFocusChange, ...rest }, ref) {
     const [focused, setFocused] = useState(defaultFocused);
+    const changeRef = useRef(onFocusChange);
+    changeRef.current = onFocusChange;
     useEffect(() => {
         if (!focused)
             return;
         const onKeyDown = (event) => {
-            if (event.key === "Escape")
+            // Through the same door as the button: a host told about focus mode
+            // must hear about it however it ended.
+            if (event.key === "Escape") {
                 setFocused(false);
+                changeRef.current?.(false);
+            }
         };
         document.addEventListener("keydown", onKeyDown);
         const previousOverflow = document.body.style.overflow;
@@ -29,8 +48,14 @@ export function DataTableFrame({ children, className, focusClassName, defaultFoc
             document.body.style.overflow = previousOverflow;
         };
     }, [focused]);
-    const value = useMemo(() => ({ focused, setFocused }), [focused]);
-    return (_jsx(DataTableFrameContext.Provider, { value: value, children: _jsx("div", { ...rest, "data-focused": focused ? "" : undefined, className: focused
-                ? cn("fixed inset-0 z-50 flex flex-col gap-3 overflow-auto bg-background p-4 sm:p-6", focusClassName)
+    const value = useMemo(() => ({
+        focused,
+        setFocused: (next) => {
+            setFocused(next);
+            changeRef.current?.(next);
+        },
+    }), [focused]);
+    return (_jsx(DataTableFrameContext.Provider, { value: value, children: _jsx("div", { ...rest, ref: ref, "data-focused": focused ? "" : undefined, className: focused
+                ? cn("fixed inset-0 z-50 flex flex-col gap-3 overflow-hidden bg-background p-4 sm:p-6", focusClassName)
                 : className, children: children }) }));
-}
+});

package/dist/components/data-table/data-table-selection-bar.d.ts

@@ -0,0 +1,18 @@
+/**
+ * What you can do with the rows you ticked. Appears only while something is
+ * selected, states the count in words, and hosts drop their bulk actions in —
+ * the same place in every list, so "select some rows, then do a thing" is one
+ * habit across the platform (and the same set the chat agent reads).
+ */
+import type { Row, Table } from "@tanstack/react-table";
+import type { ReactNode } from "react";
+export interface DataTableSelectionBarProps<T> {
+    table: Table<T>;
+    /** Bulk actions for the selected rows. */
+    children?: ReactNode | ((rows: Row<T>[]) => ReactNode);
+    /** What one row is called ("risk"); the plural is derived, or give `plural`. */
+    label?: string;
+    plural?: string;
+    className?: string;
+}
+export declare function DataTableSelectionBar<T>({ table, children, label, plural, className, }: DataTableSelectionBarProps<T>): import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,15 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { X } from "lucide-react";
+import { Button, cn } from "@iloveagents/foundry-web-primitives";
+export function DataTableSelectionBar({ table, children, label = "row", plural, className, }) {
+    // Every selected row, not only the ones the current filter shows: a
+    // selection the user cannot see is still a selection, and hiding the bar
+    // would take away the only way to clear it.
+    const rows = table.getSelectedRowModel().rows;
+    if (rows.length === 0)
+        return null;
+    return (_jsxs("div", { "data-selection-bar": "", role: "status", className: cn("flex min-h-8 flex-wrap items-center gap-2 rounded-xl bg-primary/5 px-3 text-sm", className), children: [_jsxs("span", { className: "font-medium", children: [rows.length, " ", rows.length === 1 ? label : (plural ?? `${label}s`), " selected"] }), _jsx("div", { className: "flex flex-wrap items-center gap-2", children: typeof children === "function" ? children(rows) : children }), _jsxs(Button, { type: "button", variant: "ghost", size: "sm", 
+                // `true` = the blank state, not the caller's `initialState`, which
+                // would make "Clear" resurrect rows.
+                onClick: () => table.resetRowSelection(true), className: "ml-auto h-8 rounded-lg px-2.5", children: ["Clear", _jsx(X, { className: "size-4" })] })] }));
+}

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

@@ -2,7 +2,7 @@
  * Two bands, so a list with many filters still reads as ordered rather than
  * as a ragged wrap:
  *
- *   row 1   search …………………………………… Filters (n) · actions · View · ⤢
+ *   row 1   search ……………………………… Filters (n) · actions · Columns · ⤢
  *   row 2   facet · facet · facet · + Filter · Reset
  *
  * Row one never wraps (its right group is fixed); filters live on their own
@@ -37,12 +37,15 @@ export interface DataTableToolbarProps<T> {
     collapsibleFilters?: boolean;
     /** Whether the filter row starts open (default `true`; when closed the toggle still shows the active count). */
     defaultFiltersOpen?: boolean;
-    /** Facets always visible when none declares `pinned` (default 3; `Infinity` shows all). */
+    /**
+     * Facets always visible when none declares `pinned` (default 3; `Infinity`
+     * shows all). Focus mode shows every facet unless a number is given.
+     */
     pinnedFacets?: number;
     searchPlaceholder?: string;
     /** Hide the search box. */
     search?: boolean;
-    /** Hide the View (column visibility) menu. */
+    /** Hide the Columns (column visibility) menu. */
     viewOptions?: boolean;
     /** Hide the focus (fullscreen) button that appears inside a `DataTableFrame`. */
     focus?: boolean;
@@ -50,6 +53,12 @@ export interface DataTableToolbarProps<T> {
     children?: ReactNode;
     /** Controls rendered on the right, before the View menu. */
     actions?: ReactNode;
+    /**
+     * Shown *in place of* the filter row while rows are ticked — the mail-app
+     * move, so the list never jumps when a selection appears. Receives nothing;
+     * compose `DataTableSelectionBar` or your own summary.
+     */
+    selectionBar?: ReactNode;
     className?: string;
 }
 /** Which facets render as buttons: pinned ones, revealed ones, and any with a value. */
@@ -57,4 +66,4 @@ export declare function visibleFacets<T>(table: Table<T>, facets: DataTableFacet
     shown: DataTableFacet[];
     hidden: DataTableFacet[];
 };
-export declare function DataTableToolbar<T>({ table, facets, layout, collapsibleFilters, defaultFiltersOpen, pinnedFacets, searchPlaceholder, search, viewOptions, focus, children, actions, className, }: DataTableToolbarProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare function DataTableToolbar<T>({ table, facets, layout, collapsibleFilters, defaultFiltersOpen, pinnedFacets, searchPlaceholder, search, viewOptions, focus, children, actions, selectionBar, className, }: DataTableToolbarProps<T>): import("react/jsx-runtime").JSX.Element;

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

@@ -9,6 +9,12 @@ import { DataTableViewOptions } from "./data-table-view-options.js";
 import { columnLabel, normalizeFacetValue } from "./facets.js";
 /** Which facets render as buttons: pinned ones, revealed ones, and any with a value. */
 export function visibleFacets(table, facets, revealed, pinnedFacets) {
+    // "Show everything" beats a per-facet `pinned: false`: focus mode has the
+    // room, and the promise is that nothing stays behind the menu there.
+    if (pinnedFacets === Number.POSITIVE_INFINITY) {
+        const shown = facets.filter((facet) => table.getColumn(facet.columnId));
+        return { shown, hidden: [] };
+    }
     const explicit = facets.some((facet) => facet.pinned !== undefined);
     const shown = [];
     const hidden = [];
@@ -22,14 +28,21 @@ export function visibleFacets(table, facets, revealed, pinnedFacets) {
     });
     return { shown, hidden };
 }
-export function DataTableToolbar({ table, facets = [], layout = "auto", collapsibleFilters, defaultFiltersOpen = true, pinnedFacets = 3, searchPlaceholder = "Search…", search = true, viewOptions = true, focus = true, children, actions, className, }) {
+export function DataTableToolbar({ table, facets = [], layout = "auto", collapsibleFilters, defaultFiltersOpen = true, pinnedFacets, searchPlaceholder = "Search…", search = true, viewOptions = true, focus = true, children, actions, selectionBar, className, }) {
     const [revealed, setRevealed] = useState(() => new Set());
     const [filtersOpen, setFiltersOpen] = useState(defaultFiltersOpen);
     const frame = useDataTableFrame();
     const focusButton = focus && frame ? (_jsx(Button, { type: "button", variant: "outline", size: "sm", "aria-pressed": frame.focused, "aria-label": frame.focused ? "Leave focus mode" : "Focus on the list", title: frame.focused ? "Leave focus mode (Esc)" : "Focus on the list", onClick: () => frame.setFocused(!frame.focused), className: "size-8 rounded-xl border-border/45 bg-background/65 p-0 shadow-none hover:bg-muted/26", children: frame.focused ? _jsx(Minimize2, { className: "size-4" }) : _jsx(Maximize2, { className: "size-4" }) })) : null;
     const state = table.getState();
+    // `DataTableSelectionBar` renders null with nothing selected, so the
+    // element being present says nothing. Ask the table instead — otherwise
+    // the filter row disappears behind an empty selection row.
+    const hasSelection = table.getSelectedRowModel().rows.length > 0;
+    const showSelectionBar = Boolean(selectionBar) && hasSelection;
     const isFiltered = state.columnFilters.length > 0 || Boolean(state.globalFilter) || revealed.size > 0;
-    const { shown, hidden } = visibleFacets(table, facets, revealed, pinnedFacets);
+    // Focus mode has the screen to itself: show every facet unless told otherwise.
+    const pinnedCount = pinnedFacets ?? (frame?.focused ? Number.POSITIVE_INFINITY : 3);
+    const { shown, hidden } = visibleFacets(table, facets, revealed, pinnedCount);
     // `children` alone (extra controls, no facets) is not a reason to open a
     // second band — it rides in the filter row only when there is one.
     const stacked = layout === "stacked" || (layout === "auto" && facets.length > 0);
@@ -62,7 +75,7 @@ export function DataTableToolbar({ table, facets = [], layout = "auto", collapsi
     const filtersToggle = canCollapse ? (_jsxs(Button, { type: "button", variant: "outline", size: "sm", "data-filters-toggle": "", "aria-expanded": showFilters, onClick: () => setFiltersOpen((current) => !current), className: cn("h-8 rounded-xl border-border/45 bg-background/65 shadow-none hover:bg-muted/26", activeFilters > 0 && "border-primary/30"), children: [_jsx(SlidersHorizontal, { className: "size-4" }), "Filters", activeFilters > 0 ? (_jsxs("span", { className: "rounded-md bg-muted px-1.5 py-0.5 text-xs font-normal tabular-nums", children: [_jsx("span", { "aria-hidden": "true", children: activeFilters }), _jsxs("span", { className: "sr-only", children: [activeFilters, " active"] })] })) : null] })) : null;
     const rightGroup = actions || viewOptions || focusButton || filtersToggle ? (_jsxs("div", { className: "flex shrink-0 items-center gap-2", children: [filtersToggle, actions, viewOptions ? _jsx(DataTableViewOptions, { table: table }) : null, focusButton] })) : null;
     if (!stacked) {
-        return (_jsxs("div", { className: cn("flex items-start gap-2", className), children: [_jsxs("div", { className: "flex min-w-0 flex-1 flex-wrap items-center gap-2", children: [searchNode, facetNodes, addFilterNode, children, resetNode] }), rightGroup ? _jsx("div", { className: "ml-auto", children: rightGroup }) : null] }));
+        return (_jsxs("div", { className: cn("flex flex-col gap-2", className), children: [_jsxs("div", { className: "flex items-start gap-2", children: [_jsxs("div", { className: "flex min-w-0 flex-1 flex-wrap items-center gap-2", children: [searchNode, facetNodes, addFilterNode, children, resetNode] }), rightGroup ? _jsx("div", { className: "ml-auto", children: rightGroup }) : null] }), showSelectionBar ? _jsx("div", { "data-selection-row": "", children: selectionBar }) : null] }));
     }
-    return (_jsxs("div", { className: cn("flex flex-col gap-2", className), children: [_jsxs("div", { className: "flex items-center gap-2", children: [searchNode, rightGroup ? _jsx("div", { className: "ml-auto", children: rightGroup }) : null] }), showFilters ? (_jsxs("div", { "data-filter-row": "", className: "flex flex-wrap items-center gap-2", children: [facetNodes, addFilterNode, children, resetNode] })) : null] }));
+    return (_jsxs("div", { className: cn("flex flex-col gap-2", className), children: [_jsxs("div", { className: "flex items-center gap-2", children: [searchNode, rightGroup ? _jsx("div", { className: "ml-auto", children: rightGroup }) : null] }), showSelectionBar ? (_jsx("div", { "data-selection-row": "", children: selectionBar })) : showFilters ? (_jsxs("div", { "data-filter-row": "", className: "flex flex-wrap items-center gap-2", children: [facetNodes, addFilterNode, children, resetNode] })) : null] }));
 }

package/dist/components/data-table/data-table-view-options.d.ts

@@ -1,4 +1,4 @@
-/** The "View" menu: toggle column visibility. */
+/** The "Columns" menu: toggle column visibility. */
 import type { Table } from "@tanstack/react-table";
 export interface DataTableViewOptionsProps<T> {
     table: Table<T>;

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

@@ -7,5 +7,5 @@ export function DataTableViewOptions({ table, className }) {
     const columns = table.getAllLeafColumns().filter((column) => column.getCanHide());
     if (!columns.length)
         return null;
-    return (_jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsxs(Button, { type: "button", variant: "outline", size: "sm", className: cn("h-8 rounded-xl border-border/45 bg-background/65 shadow-none hover:bg-muted/26", className), children: [_jsx(Settings2, { className: "size-4" }), "View"] }) }), _jsxs(DropdownMenuContent, { align: "end", className: "w-48 rounded-xl border-border/45 bg-popover/95 shadow-lg", children: [_jsx(DropdownMenuLabel, { children: "Toggle columns" }), _jsx(DropdownMenuSeparator, {}), columns.map((column) => (_jsx(DropdownMenuCheckboxItem, { checked: column.getIsVisible(), onCheckedChange: (checked) => column.toggleVisibility(Boolean(checked)), onSelect: (event) => event.preventDefault(), className: "capitalize", children: columnLabel(column) }, column.id)))] })] }));
+    return (_jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsxs(Button, { type: "button", variant: "outline", size: "sm", className: cn("h-8 rounded-xl border-border/45 bg-background/65 shadow-none hover:bg-muted/26", className), children: [_jsx(Settings2, { className: "size-4" }), "Columns"] }) }), _jsxs(DropdownMenuContent, { align: "end", className: "w-48 rounded-xl border-border/45 bg-popover/95 shadow-lg", children: [_jsx(DropdownMenuLabel, { children: "Show columns" }), _jsx(DropdownMenuSeparator, {}), columns.map((column) => (_jsx(DropdownMenuCheckboxItem, { checked: column.getIsVisible(), onCheckedChange: (checked) => column.toggleVisibility(Boolean(checked)), onSelect: (event) => event.preventDefault(), children: columnLabel(column) }, column.id)))] })] }));
 }

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

@@ -5,21 +5,62 @@
  * never doubles as "open".
  */
 import { type Row, type Table } from "@tanstack/react-table";
-import type { KeyboardEvent, MouseEvent, ReactNode } from "react";
+import { type KeyboardEvent, type MouseEvent, type ReactNode } from "react";
 export interface DataTableProps<T> {
     table: Table<T>;
+    /** Single click on a row — selecting it, in the desktop sense. */
     onRowClick?: (row: Row<T>, event: MouseEvent | KeyboardEvent) => void;
+    /**
+     * Opening a row: Enter or a double click, the way a file list behaves. Keep
+     * it separate from `onRowClick` so brushing or clicking a row (to scroll,
+     * to select) never opens a detail pane by surprise.
+     */
+    onRowOpen?: (row: Row<T>, event: MouseEvent | KeyboardEvent) => void;
     /** The row whose details are open elsewhere (drawer, panel) — highlighted, `aria-current`. */
     activeRowId?: string | null;
+    /**
+     * Move the active row with ↑/↓ (Home/End for the ends) and clear it with
+     * Escape, scrolling it into view — the keyboard flow people expect from a
+     * master list beside a detail pane. Needs `activeRowId`.
+     */
+    onActiveRowChange?: (row: Row<T> | null) => void;
     rowClassName?: (row: Row<T>) => string | undefined;
     /** Content of a group header row (default: label and count). */
     renderGroup?: (row: Row<T>) => ReactNode;
     /** Declared order of group keys; unknown keys follow in data order. */
     groupOrder?: string[];
     emptyState?: ReactNode;
+    /**
+     * Keep the columns at their natural width and let the leftover room sit at
+     * the end, the way a spreadsheet looks, instead of stretching a text column
+     * across the gap. Set `false` for a table whose last column should fill.
+     */
+    spacer?: boolean;
+    /** Keep the header in place while the rows scroll (always on in focus mode). */
     stickyHeader?: boolean;
+    /**
+     * Make the table the scroll region of its flex-column parent, on both
+     * axes, instead of growing the page. Defaults to true inside a focused
+     * `DataTableFrame`.
+     */
+    fill?: boolean;
+    /**
+     * Give the list its own viewport of at most this height (e.g. `"70vh"`),
+     * so the rows scroll under a sticky header instead of running down the
+     * page — the way a spreadsheet-like list is expected to behave. Ignored
+     * while `fill` is on, which already bounds the height.
+     */
+    maxHeight?: string | number;
     dense?: boolean;
+    /**
+     * The columns the table actually drew, whenever that set changes. Width and
+     * focus gating happen at render time and are deliberately NOT TanStack
+     * visibility (that belongs to the user and rides in the URL) — so anything
+     * that must agree with what is on screen, above all the chat agent's view
+     * of the list, learns it here.
+     */
+    onRenderedColumnsChange?: (columnIds: string[]) => void;
     className?: string;
     "aria-label"?: string;
 }
-export declare function DataTable<T>({ table, onRowClick, activeRowId, rowClassName, renderGroup, groupOrder, emptyState, stickyHeader, dense, className, "aria-label": ariaLabel, }: DataTableProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare function DataTable<T>({ table, onRowClick, onRowOpen, activeRowId, onActiveRowChange, rowClassName, renderGroup, groupOrder, emptyState, spacer, stickyHeader, fill, maxHeight, dense, onRenderedColumnsChange, className, "aria-label": ariaLabel, }: DataTableProps<T>): import("react/jsx-runtime").JSX.Element;