@iloveagents/foundry-web-ui 0.16.0 → 0.17.0

package/README.md

@@ -38,6 +38,29 @@ components are generated:
 @source "../node_modules/@iloveagents/foundry-web-ui/dist";
 ```
 
+## Lists
+
+Every list renders through one `DataTable` family (TanStack Table underneath):
+AND-of-tokens search, faceted filters with live counts (OR within a facet, AND
+across facets, array cells count per element, empty cells as "None"), sortable
+headers, column visibility, row selection, optional paging, optional grouping,
+and a URL codec that keeps `q` / `sort` / `f_<column>` / `hide` / `page` / `size`.
+
+```tsx
+const table = useDataTable({ data: rows, columns, getRowId: (row) => row.id, pageSize: 20 });
+
+<DataTableToolbar table={table} facets={[{ columnId: "status" }, { columnId: "priority" }]} />
+<DataTable table={table} onRowClick={(row) => open(row.original)} />
+<DataTablePagination table={table} />
+```
+
+Give a column `filterFn: facetFilterFn` (or the string `"facet"` in untyped
+code) to use it as a facet; `meta.facetLabels` names
+its values, `meta.label` names the column in the View menu, and
+`DataTableColumnHeader` makes a header sortable. Pass `state` + `onStateChange`
+(with `parseDataTableState` / `mergeDataTableUrlState`) to keep the whole list
+state in the URL.
+
 ## 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-column-header.d.ts

@@ -0,0 +1,8 @@
+/** Sortable column header with an asc / desc / hide menu. */
+import type { Column } from "@tanstack/react-table";
+export interface DataTableColumnHeaderProps<T> {
+    column: Column<T, unknown>;
+    title: string;
+    className?: string;
+}
+export declare function DataTableColumnHeader<T>({ column, title, className, }: DataTableColumnHeaderProps<T>): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,12 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { ArrowDown, ArrowUp, ChevronsUpDown, EyeOff } from "lucide-react";
+import { Button, cn } from "@iloveagents/foundry-web-primitives";
+import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger, } from "../../ui/dropdown-menu.js";
+export function DataTableColumnHeader({ column, title, className, }) {
+    if (!column.getCanSort()) {
+        return _jsx("div", { className: cn("font-medium", className), children: title });
+    }
+    const sorted = column.getIsSorted();
+    const align = column.columnDef.meta?.align;
+    return (_jsx("div", { className: cn("flex items-center", align === "right" && "justify-end", className), children: _jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsxs(Button, { type: "button", variant: "ghost", size: "sm", "aria-label": `${title}: ${sorted === "asc" ? "sorted ascending" : sorted === "desc" ? "sorted descending" : "not sorted"}`, "data-sorted": sorted || undefined, className: "-ml-3 h-8 gap-1.5 rounded-lg px-2 text-xs font-medium text-muted-foreground data-[state=open]:bg-accent data-[sorted]:text-foreground", children: [_jsx("span", { children: title }), sorted === "desc" ? (_jsx(ArrowDown, { className: "size-3.5" })) : sorted === "asc" ? (_jsx(ArrowUp, { className: "size-3.5" })) : (_jsx(ChevronsUpDown, { className: "size-3.5 opacity-60" }))] }) }), _jsxs(DropdownMenuContent, { align: "start", className: "rounded-xl border-border/45 bg-popover/95 shadow-lg", children: [_jsxs(DropdownMenuItem, { onClick: () => column.toggleSorting(false), children: [_jsx(ArrowUp, { className: "size-3.5 text-muted-foreground" }), "Asc"] }), _jsxs(DropdownMenuItem, { onClick: () => column.toggleSorting(true), children: [_jsx(ArrowDown, { className: "size-3.5 text-muted-foreground" }), "Desc"] }), sorted ? (_jsxs(DropdownMenuItem, { onClick: () => column.clearSorting(), children: [_jsx(ChevronsUpDown, { className: "size-3.5 text-muted-foreground" }), "Unsorted"] })) : null, column.getCanHide() ? (_jsxs(_Fragment, { children: [_jsx(DropdownMenuSeparator, {}), _jsxs(DropdownMenuItem, { onClick: () => column.toggleVisibility(false), children: [_jsx(EyeOff, { className: "size-3.5 text-muted-foreground" }), "Hide"] })] })) : null] })] }) }));
+}

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

@@ -0,0 +1,16 @@
+/**
+ * One facet: a dashed "+ Title" button that opens a checklist of options
+ * with live counts. Picking several options ORs them; the table ANDs the
+ * facets. Options come from the data unless declared.
+ */
+import type { Column } from "@tanstack/react-table";
+import { type DataTableFacetOption } from "./facets.js";
+export interface DataTableFacetedFilterProps<T> {
+    column: Column<T, unknown>;
+    title?: string;
+    options?: DataTableFacetOption[];
+    /** Show a search box inside the list once there are more options than this (default 7). */
+    searchableFrom?: number;
+    className?: string;
+}
+export declare function DataTableFacetedFilter<T>({ column, title, options: declared, searchableFrom, className, }: DataTableFacetedFilterProps<T>): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Check, PlusCircle } from "lucide-react";
+import { useMemo, useState } from "react";
+import { Button, cn } from "@iloveagents/foundry-web-primitives";
+import { Popover, PopoverContent, PopoverTrigger } from "../../ui/popover.js";
+import { columnLabel, facetOptions, normalizeFacetValue, } from "./facets.js";
+export function DataTableFacetedFilter({ column, title, options: declared, searchableFrom = 7, className, }) {
+    const [query, setQuery] = useState("");
+    const label = title ?? columnLabel(column);
+    const selected = normalizeFacetValue(column.getFilterValue());
+    const selectedSet = new Set(selected);
+    const options = facetOptions(column, declared);
+    const shown = useMemo(() => {
+        const needle = query.trim().toLowerCase();
+        return needle ? options.filter((o) => o.label.toLowerCase().includes(needle)) : options;
+    }, [options, query]);
+    const toggle = (value) => {
+        const next = selectedSet.has(value)
+            ? selected.filter((item) => item !== value)
+            : [...selected, value];
+        column.setFilterValue(next.length ? next : undefined);
+    };
+    return (_jsxs(Popover, { onOpenChange: (open) => !open && setQuery(""), children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Button, { type: "button", variant: "outline", size: "sm", "data-facet": column.id, "data-active": selected.length ? "" : undefined, className: cn("h-8 rounded-xl border-dashed border-border/60 bg-background/65 shadow-none hover:bg-muted/26", selected.length && "border-solid border-primary/30", className), children: [_jsx(PlusCircle, { className: "size-4" }), label, selected.length > 0 ? (_jsxs(_Fragment, { children: [_jsx("span", { className: "mx-0.5 h-4 w-px bg-border/60", "aria-hidden": "true" }), _jsx("span", { className: "rounded-md bg-muted px-1.5 py-0.5 text-xs font-normal lg:hidden", children: selected.length }), _jsx("span", { className: "hidden gap-1 lg:flex", children: selected.length > 2 ? (_jsxs("span", { className: "rounded-md bg-muted px-1.5 py-0.5 text-xs font-normal", children: [selected.length, " selected"] })) : (options
+                                        .filter((option) => selectedSet.has(option.value))
+                                        .map((option) => (_jsx("span", { className: "rounded-md bg-muted px-1.5 py-0.5 text-xs font-normal", children: option.label }, option.value)))) })] })) : null] }) }), _jsxs(PopoverContent, { align: "start", className: "w-56 p-1.5", children: [options.length >= searchableFrom ? (_jsx("input", { value: query, onChange: (event) => setQuery(event.target.value), placeholder: label, "aria-label": `Search ${label} options`, className: "mb-1 h-8 w-full rounded-lg border border-border/45 bg-background/72 px-2 text-sm outline-none focus:border-primary/30" })) : null, _jsx("div", { role: "group", "aria-label": `${label} filter`, className: "max-h-72 space-y-0.5 overflow-y-auto", children: shown.length === 0 ? (_jsx("div", { className: "px-2 py-4 text-center text-xs text-muted-foreground", children: "No options." })) : (shown.map((option) => {
+                            const checked = selectedSet.has(option.value);
+                            const Icon = option.icon;
+                            return (_jsxs("button", { type: "button", role: "checkbox", "aria-checked": checked, onClick: () => toggle(option.value), className: cn("flex w-full items-center gap-2 rounded-lg px-2 py-1.5 text-left text-sm transition-colors hover:bg-accent", option.count === 0 && !checked && "text-muted-foreground"), children: [_jsx("span", { className: cn("flex size-4 shrink-0 items-center justify-center rounded border border-border", checked
+                                            ? "border-primary bg-primary text-primary-foreground"
+                                            : "opacity-60 [&_svg]:invisible"), children: _jsx(Check, { className: "size-3.5" }) }), Icon ? _jsx(Icon, { className: "size-4 text-muted-foreground" }) : null, _jsx("span", { className: "min-w-0 flex-1 truncate", children: option.label }), _jsx("span", { className: "ml-auto font-mono text-xs tabular-nums text-muted-foreground", children: option.count })] }, option.value));
+                        })) }), selected.length > 0 ? (_jsxs(_Fragment, { children: [_jsx("div", { className: "my-1 h-px bg-border/45" }), _jsx("button", { type: "button", onClick: () => column.setFilterValue(undefined), className: "w-full rounded-lg px-2 py-1.5 text-center text-sm hover:bg-accent", children: "Clear filter" })] })) : null] })] }));
+}

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

@@ -0,0 +1,8 @@
+/** Selection summary, rows-per-page, page x of y, first/prev/next/last. */
+import type { Table } from "@tanstack/react-table";
+export interface DataTablePaginationProps<T> {
+    table: Table<T>;
+    pageSizeOptions?: number[];
+    className?: string;
+}
+export declare function DataTablePagination<T>({ table, pageSizeOptions, className, }: DataTablePaginationProps<T>): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronLeft, ChevronRight, ChevronsLeft, ChevronsRight } from "lucide-react";
+import { Button, cn } from "@iloveagents/foundry-web-primitives";
+import { Select } from "../../ui/select.js";
+export function DataTablePagination({ table, pageSizeOptions = [10, 20, 50, 100], className, }) {
+    const total = table.getFilteredRowModel().rows.length;
+    const selected = table.getFilteredSelectedRowModel().rows.length;
+    const { pageIndex, pageSize } = table.getState().pagination;
+    const pageCount = Math.max(1, table.getPageCount());
+    const sizes = pageSizeOptions.includes(pageSize)
+        ? pageSizeOptions
+        : [...pageSizeOptions, pageSize].sort((a, b) => a - b);
+    const iconButton = "size-8 rounded-lg border-border/45 bg-background/65 p-0 shadow-none hover:bg-muted/26";
+    return (_jsxs("div", { className: cn("flex flex-wrap items-center gap-x-6 gap-y-2 text-sm", className), children: [_jsx("div", { className: "flex-1 text-muted-foreground", "aria-live": "polite", children: selected > 0 ? `${selected} of ${total} row(s) selected.` : `${total} row(s)` }), _jsxs("label", { className: "flex items-center gap-2", children: [_jsx("span", { className: "font-medium", children: "Rows per page" }), _jsx(Select, { value: pageSize, onChange: (event) => table.setPageSize(Number(event.target.value)), className: "h-8 w-[4.5rem] rounded-lg px-2 py-0", children: sizes.map((size) => (_jsx("option", { value: size, children: size }, size))) })] }), _jsxs("div", { className: "font-medium", children: ["Page ", pageIndex + 1, " of ", pageCount] }), _jsxs("div", { className: "flex items-center gap-1.5", children: [_jsxs(Button, { type: "button", variant: "outline", className: cn(iconButton, "hidden lg:inline-flex"), onClick: () => table.setPageIndex(0), disabled: !table.getCanPreviousPage(), children: [_jsx("span", { className: "sr-only", children: "Go to first page" }), _jsx(ChevronsLeft, { className: "size-4" })] }), _jsxs(Button, { type: "button", variant: "outline", className: iconButton, onClick: () => table.previousPage(), disabled: !table.getCanPreviousPage(), children: [_jsx("span", { className: "sr-only", children: "Go to previous page" }), _jsx(ChevronLeft, { className: "size-4" })] }), _jsxs(Button, { type: "button", variant: "outline", className: iconButton, onClick: () => table.nextPage(), disabled: !table.getCanNextPage(), children: [_jsx("span", { className: "sr-only", children: "Go to next page" }), _jsx(ChevronRight, { className: "size-4" })] }), _jsxs(Button, { type: "button", variant: "outline", className: cn(iconButton, "hidden lg:inline-flex"), onClick: () => table.setPageIndex(pageCount - 1), disabled: !table.getCanNextPage(), children: [_jsx("span", { className: "sr-only", children: "Go to last page" }), _jsx(ChevronsRight, { className: "size-4" })] })] })] }));
+}

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

@@ -0,0 +1,16 @@
+import type { ComponentType } from "react";
+export interface DataTableRowAction {
+    label: string;
+    onSelect: () => void;
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    destructive?: boolean;
+    disabled?: boolean;
+}
+export interface DataTableRowActionsProps {
+    actions: Array<DataTableRowAction | "separator">;
+    label?: string;
+    className?: string;
+}
+export declare function DataTableRowActions({ actions, label, className, }: DataTableRowActionsProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** The "…" menu at the end of a row. Items are data, so agents and tests can read them. */
+import { MoreHorizontal } from "lucide-react";
+import { Button, cn } from "@iloveagents/foundry-web-primitives";
+import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger, } from "../../ui/dropdown-menu.js";
+export function DataTableRowActions({ actions, label = "Open menu", className, }) {
+    return (_jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsxs(Button, { type: "button", variant: "ghost", size: "sm", "data-no-row-click": "", className: cn("size-8 rounded-lg p-0 data-[state=open]:bg-accent", className), children: [_jsx(MoreHorizontal, { className: "size-4" }), _jsx("span", { className: "sr-only", children: label })] }) }), _jsx(DropdownMenuContent, { align: "end", className: "w-44 rounded-xl border-border/45 bg-popover/95 shadow-lg", children: actions.map((action, index) => action === "separator" ? (_jsx(DropdownMenuSeparator, {}, `sep-${index}`)) : (_jsxs(DropdownMenuItem, { disabled: action.disabled, onClick: (event) => {
+                        event.stopPropagation();
+                        action.onSelect();
+                    }, className: cn(action.destructive && "text-destructive focus:text-destructive"), children: [action.icon ? _jsx(action.icon, { className: "size-4 text-muted-foreground" }) : null, action.label] }, action.label))) })] }));
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Search + facets + Reset on the left, actions + View menu on the right.
+ * Facets are declared by column id; everything else is read off the table.
+ */
+import type { Table } from "@tanstack/react-table";
+import type { ReactNode } from "react";
+import type { DataTableFacetOption } from "./facets.js";
+export interface DataTableFacet {
+    columnId: string;
+    title?: string;
+    options?: DataTableFacetOption[];
+}
+export interface DataTableToolbarProps<T> {
+    table: Table<T>;
+    facets?: DataTableFacet[];
+    searchPlaceholder?: string;
+    /** Hide the search box. */
+    search?: boolean;
+    /** Hide the View (column visibility) menu. */
+    viewOptions?: boolean;
+    /** Extra controls rendered next to the facets (left side). */
+    children?: ReactNode;
+    /** Controls rendered on the right, before the View menu. */
+    actions?: ReactNode;
+    className?: string;
+}
+export declare function DataTableToolbar<T>({ table, facets, searchPlaceholder, search, viewOptions, children, actions, className, }: DataTableToolbarProps<T>): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,18 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Search, X } from "lucide-react";
+import { Button, Input, cn } from "@iloveagents/foundry-web-primitives";
+import { DataTableFacetedFilter } from "./data-table-faceted-filter.js";
+import { DataTableViewOptions } from "./data-table-view-options.js";
+export function DataTableToolbar({ table, facets = [], searchPlaceholder = "Search…", search = true, viewOptions = true, children, actions, className, }) {
+    const state = table.getState();
+    const isFiltered = state.columnFilters.length > 0 || Boolean(state.globalFilter);
+    return (_jsxs("div", { className: cn("flex flex-wrap items-center gap-2", className), children: [search ? (_jsxs("div", { className: "relative", children: [_jsx(Search, { className: "pointer-events-none absolute left-2.5 top-1/2 size-4 -translate-y-1/2 text-muted-foreground" }), _jsx(Input, { type: "search", value: state.globalFilter ?? "", onChange: (event) => table.setGlobalFilter(event.target.value), placeholder: searchPlaceholder, "aria-label": searchPlaceholder, className: "h-8 w-[160px] rounded-xl border-border/45 bg-background/72 pl-8 text-sm shadow-none lg:w-[250px]" })] })) : null, facets.map((facet) => {
+                const column = table.getColumn(facet.columnId);
+                if (!column)
+                    return null;
+                return (_jsx(DataTableFacetedFilter, { column: column, title: facet.title, options: facet.options }, facet.columnId));
+            }), children, isFiltered ? (_jsxs(Button, { type: "button", variant: "ghost", size: "sm", onClick: () => {
+                    table.resetColumnFilters();
+                    table.setGlobalFilter("");
+                }, className: "h-8 rounded-xl px-2.5", children: ["Reset", _jsx(X, { className: "size-4" })] })) : null, actions || viewOptions ? (_jsxs("div", { className: "ml-auto flex items-center gap-2", children: [actions, viewOptions ? _jsx(DataTableViewOptions, { table: table }) : null] })) : null] }));
+}

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

@@ -0,0 +1,7 @@
+/** The "View" menu: toggle column visibility. */
+import type { Table } from "@tanstack/react-table";
+export interface DataTableViewOptionsProps<T> {
+    table: Table<T>;
+    className?: string;
+}
+export declare function DataTableViewOptions<T>({ table, className }: DataTableViewOptionsProps<T>): import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Settings2 } from "lucide-react";
+import { Button, cn } from "@iloveagents/foundry-web-primitives";
+import { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger, } from "../../ui/dropdown-menu.js";
+import { columnLabel } from "./facets.js";
+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)))] })] }));
+}

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

@@ -0,0 +1,25 @@
+/**
+ * The grid. Renders whatever a `useDataTable` instance says: header groups,
+ * flat rows, or group header rows with their expanded children. Row clicks
+ * ignore interactive descendants so a selection checkbox or a row menu
+ * never doubles as "open".
+ */
+import { type Row, type Table } from "@tanstack/react-table";
+import type { KeyboardEvent, MouseEvent, ReactNode } from "react";
+export interface DataTableProps<T> {
+    table: Table<T>;
+    onRowClick?: (row: Row<T>, event: MouseEvent | KeyboardEvent) => void;
+    /** The row whose details are open elsewhere (drawer, panel) — highlighted, `aria-current`. */
+    activeRowId?: string | null;
+    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;
+    stickyHeader?: boolean;
+    dense?: boolean;
+    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;

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

@@ -0,0 +1,65 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The grid. Renders whatever a `useDataTable` instance says: header groups,
+ * flat rows, or group header rows with their expanded children. Row clicks
+ * ignore interactive descendants so a selection checkbox or a row menu
+ * never doubles as "open".
+ */
+import { flexRender } from "@tanstack/react-table";
+import { ChevronDown, ChevronRight } from "lucide-react";
+import { cn } from "@iloveagents/foundry-web-primitives";
+const INTERACTIVE = "a, button, input, select, textarea, [role='menuitem'], [data-no-row-click]";
+function orderedRows(table, groupOrder) {
+    const rows = table.getRowModel().rows;
+    if (!table.getState().grouping.length)
+        return rows;
+    const top = rows.filter((row) => row.depth === 0);
+    const rank = new Map((groupOrder ?? []).map((key, index) => [key, index]));
+    const sorted = groupOrder
+        ? [...top].sort((a, b) => {
+            const ra = rank.get(String(a.groupingValue ?? "")) ?? Number.MAX_SAFE_INTEGER;
+            const rb = rank.get(String(b.groupingValue ?? "")) ?? Number.MAX_SAFE_INTEGER;
+            return ra - rb;
+        })
+        : 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, }) {
+    const rows = orderedRows(table, groupOrder);
+    const columnCount = table.getVisibleLeafColumns().length;
+    const cellPad = dense ? "px-3 py-1.5" : "px-3 py-2.5";
+    const activate = (row, event) => {
+        if (!onRowClick)
+            return;
+        const target = event.target;
+        if (target?.closest(INTERACTIVE))
+            return;
+        onRowClick(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", 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 === " ") {
+                                    if (event.target.closest(INTERACTIVE))
+                                        return;
+                                    event.preventDefault();
+                                    activate(row, event);
+                                }
+                            }, 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", meta?.className), children: flexRender(cell.column.columnDef.cell, cell.getContext()) }, cell.id));
+                            }) }, row.id)))) })] }) }) }));
+}
+function DefaultGroupLabel({ row }) {
+    const grouping = row
+        .getAllCells()
+        .map((cell) => cell.column)
+        .find((column) => column.getIsGrouped());
+    const key = String(row.groupingValue ?? "");
+    const label = grouping ? (grouping.columnDef.meta?.facetLabels?.[key] ?? key) : key;
+    return (_jsxs("span", { children: [label || "None", " ", _jsxs("span", { className: "font-normal text-muted-foreground", children: ["(", row.subRows.length, ")"] })] }));
+}

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

@@ -0,0 +1,82 @@
+/**
+ * Facet semantics shared by every DataTable: how a cell value turns into
+ * facet keys, how a facet filter matches (OR within one facet — the table
+ * ANDs facets together), and how option counts are derived from the rows
+ * that every *other* filter lets through (TanStack's faceted row model), so
+ * a count always reads "rows you'd see if you added this option".
+ */
+import type { Column, FilterFn, Row, RowData } from "@tanstack/react-table";
+import type { ComponentType } from "react";
+declare module "@tanstack/react-table" {
+    interface ColumnMeta<TData extends RowData, TValue> {
+        /** Label for the View menu, facet titles and agent descriptions (defaults to a string header, then the id). */
+        label?: string;
+        /** Class for body cells of this column. */
+        className?: string;
+        /** Class for the header cell of this column. */
+        headerClassName?: string;
+        /** Horizontal alignment of header and cells. */
+        align?: "left" | "center" | "right";
+        /** Text the global search sees for this column instead of the cell value. */
+        searchText?: (row: TData) => string;
+        /** Labels for facet keys and group headers (`value → label`). */
+        facetLabels?: Record<string, string>;
+        /** 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;
+    }
+}
+/** Facet key for empty cells (`null`, `undefined`, `""`, `[]`). */
+export declare const FACET_EMPTY = "__none__";
+export interface DataTableFacetOption {
+    value: string;
+    label: string;
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+}
+export interface DataTableFacetCount extends DataTableFacetOption {
+    count: number;
+}
+/**
+ * Keys a cell value contributes to a facet — arrays contribute one key per
+ * 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 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[];
+/**
+ * OR within a facet: a row passes when any of its keys is selected. Typed
+ * loosely so `filterFn: facetFilterFn` fits any row type; `useDataTable`
+ * also registers it as the string `"facet"` for untyped (JSX) columns.
+ */
+export declare const facetFilterFn: FilterFn<any>;
+/** Rows per facet key, counted over the rows every OTHER filter lets through. */
+export declare function facetCounts<T>(column: Column<T, unknown>): Map<string, number>;
+export interface FacetOptionsOptions {
+    /** Label for keys that are neither declared nor in `meta.facetLabels`. */
+    labelFor?: (key: string) => string;
+    /** Label for the empty-cell option (default "None"). */
+    emptyLabel?: string;
+}
+/**
+ * Declared options first (in declared order, kept even at count 0), then
+ * every undeclared key seen in the data, then the empty option when some
+ * rows have no value.
+ */
+export declare function facetOptions<T>(column: Column<T, unknown>, declared?: DataTableFacetOption[], options?: FacetOptionsOptions): DataTableFacetCount[];
+/** Plain-text projection of a cell value for search and agent read-outs. */
+export declare function cellText(value: unknown): string;
+/**
+ * Lower-cased text of every searchable cell of a row. Cached per row object
+ * and invalidated when the row's cells change identity (new columns or a
+ * changed `meta.searchText`), since TanStack keeps row objects across
+ * column changes.
+ */
+export declare function rowSearchText<T>(row: Row<T>): string;
+/** Every whitespace-separated token must appear somewhere in the row (AND across tokens). */
+export declare const tokenSearchFilterFn: FilterFn<any>;
+/** Human label of a column: `meta.label`, then a string header, then the id. */
+export declare function columnLabel<T>(column: Column<T, unknown>): string;

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

@@ -0,0 +1,156 @@
+/** Facet key for empty cells (`null`, `undefined`, `""`, `[]`). */
+export const FACET_EMPTY = "__none__";
+/**
+ * Keys a cell value contributes to a facet — arrays contribute one key per
+ * element. A real value that spells the empty sentinel is escaped with a
+ * leading backslash so it never masquerades as "no value".
+ */
+export function facetKeys(value) {
+    if (value == null || value === "")
+        return [FACET_EMPTY];
+    if (value === FACET_EMPTY)
+        return [`\\${FACET_EMPTY}`];
+    if (Array.isArray(value)) {
+        const keys = value.flatMap((item) => facetKeys(item)).filter((key) => key !== FACET_EMPTY);
+        return keys.length ? Array.from(new Set(keys)) : [FACET_EMPTY];
+    }
+    if (typeof value === "object") {
+        const record = value;
+        const key = record.id ?? record.value ?? record.name;
+        return key == null || key === "" ? [FACET_EMPTY] : [String(key)];
+    }
+    return [String(value)];
+}
+/** A facet filter value is a list of selected keys; anything else means "no filter". */
+export function normalizeFacetValue(filterValue) {
+    if (Array.isArray(filterValue))
+        return filterValue.map(String).filter(Boolean);
+    if (filterValue == null || filterValue === "")
+        return [];
+    return [String(filterValue)];
+}
+/**
+ * OR within a facet: a row passes when any of its keys is selected. Typed
+ * loosely so `filterFn: facetFilterFn` fits any row type; `useDataTable`
+ * also registers it as the string `"facet"` for untyped (JSX) columns.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const facetFilterFn = (row, columnId, filterValue) => {
+    const wanted = normalizeFacetValue(filterValue);
+    if (!wanted.length)
+        return true;
+    return facetKeys(row.getValue(columnId)).some((key) => wanted.includes(key));
+};
+facetFilterFn.autoRemove = (value) => normalizeFacetValue(value).length === 0;
+/** Rows per facet key, counted over the rows every OTHER filter lets through. */
+export function facetCounts(column) {
+    const counts = new Map();
+    for (const row of column.getFacetedRowModel().flatRows) {
+        for (const key of facetKeys(row.getValue(column.id))) {
+            counts.set(key, (counts.get(key) ?? 0) + 1);
+        }
+    }
+    return counts;
+}
+/**
+ * Declared options first (in declared order, kept even at count 0), then
+ * every undeclared key seen in the data, then the empty option when some
+ * rows have no value.
+ */
+export function facetOptions(column, declared, options) {
+    const counts = facetCounts(column);
+    const labels = column.columnDef.meta?.facetLabels ?? {};
+    const labelFor = (key) => labels[key] ?? options?.labelFor?.(key) ?? key;
+    const seen = new Set();
+    const out = [];
+    for (const option of declared ?? []) {
+        seen.add(option.value);
+        out.push({ ...option, count: counts.get(option.value) ?? 0 });
+    }
+    const rest = Array.from(counts.keys())
+        .filter((key) => !seen.has(key) && key !== FACET_EMPTY)
+        .sort((a, b) => labelFor(a).localeCompare(labelFor(b)));
+    for (const key of rest)
+        out.push({ value: key, label: labelFor(key), count: counts.get(key) ?? 0 });
+    if (counts.has(FACET_EMPTY) && !seen.has(FACET_EMPTY)) {
+        out.push({
+            value: FACET_EMPTY,
+            label: labels[FACET_EMPTY] ?? options?.emptyLabel ?? "None",
+            count: counts.get(FACET_EMPTY) ?? 0,
+        });
+    }
+    return out;
+}
+/** Plain-text projection of a cell value for search and agent read-outs. */
+export function cellText(value) {
+    if (value == null)
+        return "";
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "bigint")
+        return String(value);
+    if (typeof value === "boolean")
+        return value ? "yes" : "no";
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return value.map(cellText).filter(Boolean).join(" ");
+    if (typeof value === "object") {
+        const record = value;
+        if (typeof record.name === "string")
+            return record.name;
+        if (typeof record.label === "string")
+            return record.label;
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return "";
+        }
+    }
+    return String(value);
+}
+const searchTextCache = new WeakMap();
+/**
+ * Lower-cased text of every searchable cell of a row. Cached per row object
+ * and invalidated when the row's cells change identity (new columns or a
+ * changed `meta.searchText`), since TanStack keeps row objects across
+ * column changes.
+ */
+export function rowSearchText(row) {
+    const cells = row.getAllCells();
+    const cached = searchTextCache.get(row);
+    if (cached && cached.cells === cells)
+        return cached.text;
+    const text = cells
+        .filter((cell) => cell.column.getCanGlobalFilter())
+        .map((cell) => {
+        const custom = cell.column.columnDef.meta?.searchText;
+        return custom ? custom(row.original) : cellText(cell.getValue());
+    })
+        .join(" ")
+        .toLowerCase();
+    searchTextCache.set(row, { cells, text });
+    return text;
+}
+/** Every whitespace-separated token must appear somewhere in the row (AND across tokens). */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const tokenSearchFilterFn = (row, _columnId, filterValue) => {
+    const tokens = String(filterValue ?? "")
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean);
+    if (!tokens.length)
+        return true;
+    const hay = rowSearchText(row);
+    return tokens.every((token) => hay.includes(token));
+};
+tokenSearchFilterFn.autoRemove = (value) => !String(value ?? "").trim();
+/** Human label of a column: `meta.label`, then a string header, then the id. */
+export function columnLabel(column) {
+    const meta = column.columnDef.meta;
+    if (meta?.label)
+        return meta.label;
+    const header = column.columnDef.header;
+    return typeof header === "string" ? header : column.id;
+}

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

@@ -0,0 +1,4 @@
+/** A leading checkbox column: header selects the page, cells select the row. */
+import type { ColumnDef } from "@tanstack/react-table";
+export declare const SELECTION_COLUMN_ID = "__select";
+export declare function selectionColumn<T>(): ColumnDef<T, unknown>;

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

@@ -0,0 +1,19 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Checkbox } from "@iloveagents/foundry-web-primitives";
+export const SELECTION_COLUMN_ID = "__select";
+export function selectionColumn() {
+    return {
+        id: SELECTION_COLUMN_ID,
+        size: 36,
+        enableSorting: false,
+        enableHiding: false,
+        enableGlobalFilter: false,
+        header: ({ table }) => (_jsx(Checkbox, { checked: table.getIsAllPageRowsSelected()
+                ? true
+                : table.getIsSomePageRowsSelected()
+                    ? "indeterminate"
+                    : false, onCheckedChange: (value) => table.toggleAllPageRowsSelected(Boolean(value)), "aria-label": "Select all", className: "translate-y-0.5" })),
+        cell: ({ row }) => (_jsx(Checkbox, { checked: row.getIsSelected(), disabled: !row.getCanSelect(), onCheckedChange: (value) => row.toggleSelected(Boolean(value)), "aria-label": "Select row", className: "translate-y-0.5" })),
+        meta: { label: "Select", headerClassName: "w-9", className: "w-9" },
+    };
+}

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

@@ -0,0 +1,41 @@
+/**
+ * The whole user-facing state of a DataTable as one value, plus a URL codec.
+ *
+ * URL keys are shared with the older collection pages (`q`, `sort`, `f_<id>`)
+ * so a link that worked before keeps working; `hide`, `page` and `size` are
+ * new. Selection and expansion are never put in the URL. A present-but-empty
+ * key (`f_status=`, `sort=`, `hide=`, `q=`) means "cleared", so a default the
+ * host configured can be switched off by the user and survive a reload.
+ */
+import type { ColumnFiltersState, ExpandedState, PaginationState, RowSelectionState, SortingState, VisibilityState } from "@tanstack/react-table";
+export interface DataTableState {
+    globalFilter: string;
+    columnFilters: ColumnFiltersState;
+    sorting: SortingState;
+    columnVisibility: VisibilityState;
+    rowSelection: RowSelectionState;
+    pagination: PaginationState;
+    expanded: ExpandedState;
+}
+export declare const DEFAULT_PAGE_SIZE = 20;
+export declare const EMPTY_DATA_TABLE_STATE: DataTableState;
+export declare function isDataTableUrlKey(key: string): boolean;
+export interface DataTableUrlOptions {
+    /** Page size that is implied when `size` is absent (default 20). */
+    defaultPageSize?: number;
+    /**
+     * State implied when the URL says nothing. Serializing writes an explicit
+     * empty key when the user cleared a value the defaults would bring back.
+     */
+    defaults?: Partial<DataTableState>;
+}
+/**
+ * Serialize the URL-worthy part of the state. A key whose value equals the
+ * default is omitted; a key the user cleared while a default exists is
+ * written empty; a key absent from a partial `state` is omitted.
+ */
+export declare function serializeDataTableState(state: Partial<DataTableState>, options?: DataTableUrlOptions): URLSearchParams;
+/** Parse a URL into a full state; `defaults` fill what the URL doesn't say. */
+export declare function parseDataTableState(params: URLSearchParams, options?: DataTableUrlOptions): DataTableState;
+/** Replace this table's keys in `params`, leaving every other key untouched. */
+export declare function mergeDataTableUrlState(params: URLSearchParams, state: Partial<DataTableState>, options?: DataTableUrlOptions): URLSearchParams;

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

@@ -0,0 +1,148 @@
+export const DEFAULT_PAGE_SIZE = 20;
+export const EMPTY_DATA_TABLE_STATE = {
+    globalFilter: "",
+    columnFilters: [],
+    sorting: [],
+    columnVisibility: {},
+    rowSelection: {},
+    pagination: { pageIndex: 0, pageSize: DEFAULT_PAGE_SIZE },
+    expanded: true,
+};
+const FILTER_PREFIX = "f_";
+const OWN_KEYS = new Set(["q", "sort", "hide", "page", "size"]);
+export function isDataTableUrlKey(key) {
+    return OWN_KEYS.has(key) || key.startsWith(FILTER_PREFIX);
+}
+function encodePart(value) {
+    return value.replace(/%/g, "%25").replace(/,/g, "%2C");
+}
+function decodePart(value) {
+    return value.replace(/%2C/gi, ",").replace(/%2D/gi, "-").replace(/%25/g, "%");
+}
+/** Sort ids may contain commas or start with "-"; both are escaped. */
+function encodeSortId(id) {
+    const encoded = encodePart(id);
+    return encoded.startsWith("-") ? `%2D${encoded.slice(1)}` : encoded;
+}
+function filterValues(value) {
+    if (Array.isArray(value))
+        return value.map(String).filter(Boolean);
+    return value == null || value === "" ? [] : [String(value)];
+}
+function sortKey(sorting) {
+    return (sorting ?? [])
+        .map((s) => (s.desc ? `-${encodeSortId(s.id)}` : encodeSortId(s.id)))
+        .join(",");
+}
+function hiddenKey(visibility) {
+    return Object.entries(visibility ?? {})
+        .filter(([, visible]) => visible === false)
+        .map(([id]) => encodePart(id))
+        .sort()
+        .join(",");
+}
+/**
+ * Serialize the URL-worthy part of the state. A key whose value equals the
+ * default is omitted; a key the user cleared while a default exists is
+ * written empty; a key absent from a partial `state` is omitted.
+ */
+export function serializeDataTableState(state, options) {
+    const defaults = options?.defaults ?? {};
+    const params = new URLSearchParams();
+    if (state.globalFilter !== undefined && state.globalFilter !== (defaults.globalFilter ?? "")) {
+        params.set("q", state.globalFilter);
+    }
+    if (state.sorting !== undefined && sortKey(state.sorting) !== sortKey(defaults.sorting)) {
+        params.set("sort", sortKey(state.sorting));
+    }
+    if (state.columnFilters !== undefined) {
+        const current = new Map(state.columnFilters.map((f) => [f.id, filterValues(f.value).map(encodePart).join(",")]));
+        const base = new Map((defaults.columnFilters ?? []).map((f) => [
+            f.id,
+            filterValues(f.value).map(encodePart).join(","),
+        ]));
+        for (const id of new Set([...current.keys(), ...base.keys()])) {
+            const value = current.get(id) ?? "";
+            if (value !== (base.get(id) ?? ""))
+                params.set(`${FILTER_PREFIX}${id}`, value);
+        }
+    }
+    if (state.columnVisibility !== undefined &&
+        hiddenKey(state.columnVisibility) !== hiddenKey(defaults.columnVisibility)) {
+        params.set("hide", hiddenKey(state.columnVisibility));
+    }
+    const pagination = state.pagination;
+    if (pagination) {
+        const defaultIndex = defaults.pagination?.pageIndex ?? 0;
+        if (pagination.pageIndex !== defaultIndex)
+            params.set("page", String(pagination.pageIndex + 1));
+        const defaultSize = options?.defaultPageSize ?? defaults.pagination?.pageSize ?? DEFAULT_PAGE_SIZE;
+        if (pagination.pageSize !== defaultSize)
+            params.set("size", String(pagination.pageSize));
+    }
+    return params;
+}
+/** Parse a URL into a full state; `defaults` fill what the URL doesn't say. */
+export function parseDataTableState(params, options) {
+    const defaults = { ...EMPTY_DATA_TABLE_STATE, ...options?.defaults };
+    const defaultSize = options?.defaultPageSize ?? defaults.pagination.pageSize;
+    const sortRaw = params.get("sort");
+    const sorting = sortRaw == null
+        ? defaults.sorting
+        : sortRaw
+            .split(",")
+            .filter(Boolean)
+            .map((part) => part.startsWith("-")
+            ? { id: decodePart(part.slice(1)), desc: true }
+            : { id: decodePart(part), desc: false });
+    const filtersById = new Map(defaults.columnFilters.map((filter) => [filter.id, filter]));
+    for (const [key, raw] of params.entries()) {
+        if (!key.startsWith(FILTER_PREFIX))
+            continue;
+        const id = key.slice(FILTER_PREFIX.length);
+        const values = raw.split(",").filter(Boolean).map(decodePart);
+        if (values.length)
+            filtersById.set(id, { id, value: values });
+        else
+            filtersById.delete(id);
+    }
+    const columnFilters = Array.from(filtersById.values());
+    const columnVisibility = { ...defaults.columnVisibility };
+    const hideRaw = params.get("hide");
+    if (hideRaw != null) {
+        for (const id of Object.keys(columnVisibility)) {
+            if (columnVisibility[id] === false)
+                delete columnVisibility[id];
+        }
+        for (const id of hideRaw.split(",").filter(Boolean).map(decodePart))
+            columnVisibility[id] = false;
+    }
+    const pageRaw = params.get("page");
+    const page = Number.parseInt(pageRaw ?? "", 10);
+    const size = Number.parseInt(params.get("size") ?? "", 10);
+    return {
+        ...defaults,
+        globalFilter: params.has("q") ? (params.get("q") ?? "") : defaults.globalFilter,
+        sorting,
+        columnFilters,
+        columnVisibility,
+        pagination: {
+            pageIndex: pageRaw == null
+                ? defaults.pagination.pageIndex
+                : Number.isFinite(page) && page > 1
+                    ? page - 1
+                    : 0,
+            pageSize: Number.isFinite(size) && size > 0 ? size : defaultSize,
+        },
+    };
+}
+/** Replace this table's keys in `params`, leaving every other key untouched. */
+export function mergeDataTableUrlState(params, state, options) {
+    const next = new URLSearchParams();
+    for (const [key, value] of params.entries())
+        if (!isDataTableUrlKey(key))
+            next.append(key, value);
+    for (const [key, value] of serializeDataTableState(state, options).entries())
+        next.set(key, value);
+    return next;
+}

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

@@ -0,0 +1,22 @@
+import { type ColumnDef, type FilterFn, type Row, type Table } from "@tanstack/react-table";
+import { type DataTableState } from "./state.js";
+export interface UseDataTableOptions<T> {
+    data: T[];
+    columns: ColumnDef<T, any>[];
+    /** Stable row id (defaults to the row index). Required for selection that survives re-sorting. */
+    getRowId?: (row: T, index: number, parent?: Row<T>) => string;
+    /** Controlled state — pair with `onStateChange` (e.g. URL-bound). */
+    state?: Partial<DataTableState>;
+    onStateChange?: (next: DataTableState) => void;
+    /** Uncontrolled start state. */
+    initialState?: Partial<DataTableState>;
+    /** Rows per page; omit (or `false`) for an unpaginated table. Ignored while grouped. */
+    pageSize?: number | false;
+    /** Column id to group rows by (one level). */
+    groupBy?: string | null;
+    enableRowSelection?: boolean | ((row: Row<T>) => boolean);
+    enableMultiRowSelection?: boolean;
+    /** Replace the default AND-of-tokens search. */
+    globalFilterFn?: FilterFn<T>;
+}
+export declare function useDataTable<T>(options: UseDataTableOptions<T>): Table<T>;

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

@@ -0,0 +1,102 @@
+/**
+ * One hook that turns rows + columns into a fully wired TanStack table:
+ * token search, faceted filters, sorting, column visibility, selection,
+ * optional pagination and optional single-level grouping — with the whole
+ * state as ONE value so it can live in component state or in the URL.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { getCoreRowModel, getExpandedRowModel, getFacetedRowModel, getFacetedUniqueValues, getFilteredRowModel, getGroupedRowModel, getPaginationRowModel, getSortedRowModel, useReactTable, } from "@tanstack/react-table";
+import { facetFilterFn, tokenSearchFilterFn } from "./facets.js";
+import { DEFAULT_PAGE_SIZE, EMPTY_DATA_TABLE_STATE } from "./state.js";
+const PAGE_RESET_KEYS = new Set(["globalFilter", "columnFilters", "sorting"]);
+export function useDataTable(options) {
+    const { data, columns, getRowId, state: controlledState, onStateChange, initialState, pageSize, groupBy, enableRowSelection = false, enableMultiRowSelection = true, globalFilterFn, } = options;
+    const controlled = controlledState !== undefined && onStateChange !== undefined;
+    const basePageSize = pageSize || DEFAULT_PAGE_SIZE;
+    const [innerState, setInnerState] = useState(() => ({
+        ...EMPTY_DATA_TABLE_STATE,
+        ...initialState,
+        pagination: { pageIndex: 0, pageSize: basePageSize, ...initialState?.pagination },
+    }));
+    const state = useMemo(() => controlled
+        ? {
+            ...EMPTY_DATA_TABLE_STATE,
+            ...controlledState,
+            pagination: { pageIndex: 0, pageSize: basePageSize, ...controlledState.pagination },
+        }
+        : innerState, [basePageSize, controlled, controlledState, innerState]);
+    const stateRef = useRef(state);
+    stateRef.current = state;
+    const tableRef = useRef(null);
+    const update = useCallback((key, updater) => {
+        const current = stateRef.current;
+        const value = typeof updater === "function"
+            ? updater(current[key])
+            : updater;
+        if (Object.is(value, current[key]))
+            return;
+        const next = { ...current, [key]: value };
+        if (PAGE_RESET_KEYS.has(key) && next.pagination.pageIndex !== 0) {
+            next.pagination = { ...next.pagination, pageIndex: 0 };
+        }
+        stateRef.current = next;
+        // Apply to the instance now, not on the next render: a caller that
+        // reads row models right after a mutation (agent tools, tests) sees
+        // the new state even while the host owns it (URL, store).
+        tableRef.current?.setOptions((prev) => ({
+            ...prev,
+            state: { ...prev.state, [key]: value, pagination: next.pagination },
+        }));
+        if (controlled)
+            onStateChange(next);
+        else
+            setInnerState(next);
+    }, [controlled, onStateChange]);
+    const grouped = Boolean(groupBy);
+    const tableOptions = {
+        data,
+        columns,
+        getRowId,
+        state: { ...state, grouping: groupBy ? [groupBy] : [] },
+        onGlobalFilterChange: (updater) => update("globalFilter", updater),
+        onColumnFiltersChange: (updater) => update("columnFilters", updater),
+        onSortingChange: (updater) => update("sorting", updater),
+        onColumnVisibilityChange: (updater) => update("columnVisibility", updater),
+        onRowSelectionChange: (updater) => update("rowSelection", updater),
+        onPaginationChange: (updater) => update("pagination", updater),
+        onExpandedChange: (updater) => update("expanded", updater),
+        // String alias for untyped column defs (JSX renderers): `filterFn: "facet"`.
+        filterFns: { facet: facetFilterFn },
+        globalFilterFn: globalFilterFn ?? tokenSearchFilterFn,
+        getColumnCanGlobalFilter: (column) => column.columnDef.enableGlobalFilter ?? column.accessorFn != null,
+        enableRowSelection,
+        enableMultiRowSelection,
+        groupedColumnMode: false,
+        autoResetPageIndex: false,
+        autoResetExpanded: false,
+        getCoreRowModel: getCoreRowModel(),
+        getFilteredRowModel: getFilteredRowModel(),
+        getSortedRowModel: getSortedRowModel(),
+        getFacetedRowModel: getFacetedRowModel(),
+        getFacetedUniqueValues: getFacetedUniqueValues(),
+    };
+    if (grouped) {
+        tableOptions.getGroupedRowModel = getGroupedRowModel();
+        tableOptions.getExpandedRowModel = getExpandedRowModel();
+    }
+    else if (pageSize) {
+        tableOptions.getPaginationRowModel = getPaginationRowModel();
+    }
+    const table = useReactTable(tableOptions);
+    tableRef.current = table;
+    // A shrinking data set (or a tighter filter) can strand a later page.
+    useEffect(() => {
+        if (grouped || !pageSize)
+            return;
+        const index = table.getState().pagination.pageIndex;
+        const count = table.getPageCount();
+        if (index > 0 && index >= count)
+            table.setPageIndex(Math.max(0, count - 1));
+    });
+    return table;
+}

package/dist/index.d.ts

@@ -33,6 +33,18 @@ export { CollectionEmptyState } from "./components/collection-empty-state.js";
 export { CollectionSkeleton } from "./components/collection-skeleton.js";
 export { InfiniteScrollSentinel } from "./components/infinite-scroll-sentinel.js";
 export { CollectionSurface } from "./components/collection-surface.js";
+export { DataTable, type DataTableProps } from "./components/data-table/data-table.js";
+export { DataTableToolbar, type DataTableFacet, type DataTableToolbarProps, } from "./components/data-table/data-table-toolbar.js";
+export { DataTableFacetedFilter, type DataTableFacetedFilterProps, } from "./components/data-table/data-table-faceted-filter.js";
+export { DataTableViewOptions, type DataTableViewOptionsProps, } from "./components/data-table/data-table-view-options.js";
+export { DataTableColumnHeader, type DataTableColumnHeaderProps, } from "./components/data-table/data-table-column-header.js";
+export { DataTablePagination, type DataTablePaginationProps, } from "./components/data-table/data-table-pagination.js";
+export { DataTableRowActions, type DataTableRowAction, type DataTableRowActionsProps, } from "./components/data-table/data-table-row-actions.js";
+export { selectionColumn, SELECTION_COLUMN_ID } from "./components/data-table/selection-column.js";
+export { useDataTable, type UseDataTableOptions } from "./components/data-table/use-data-table.js";
+export { DEFAULT_PAGE_SIZE, EMPTY_DATA_TABLE_STATE, isDataTableUrlKey, mergeDataTableUrlState, parseDataTableState, serializeDataTableState, type DataTableState, type DataTableUrlOptions, } from "./components/data-table/state.js";
+export { FACET_EMPTY, cellText, columnLabel, facetCounts, facetFilterFn, facetKeys, facetOptions, normalizeFacetValue, rowSearchText, tokenSearchFilterFn, type DataTableFacetCount, type DataTableFacetOption, } from "./components/data-table/facets.js";
+export { createColumnHelper, flexRender, type Column, type ColumnDef, type ColumnFiltersState, type Row, type RowSelectionState, type SortingState, type Table, type VisibilityState, } from "@tanstack/react-table";
 export { ThemeRuntimeProvider, ThemeScope, ThemeDocumentMetadata, useThemeRuntime, } from "./components/theme-runtime-provider.js";
 export { JsonViewer } from "./components/json-viewer.js";
 export { UserMenu } from "./components/user-menu.js";
@@ -42,7 +54,7 @@ export { NameDialog } from "./components/name-dialog.js";
 export { SurfaceCard, surfaceCardVariants } from "./components/surface-card.js";
 export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from "./ui/tooltip.js";
 export { Collapsible, CollapsibleTrigger, CollapsibleContent } from "./ui/collapsible.js";
-export { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuLabel, } from "./ui/dropdown-menu.js";
+export { DropdownMenu, DropdownMenuTrigger, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuLabel, } from "./ui/dropdown-menu.js";
 export { Dialog, DialogPortal, DialogOverlay, DialogTrigger, DialogClose, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription, } from "./ui/dialog.js";
 export { Popover, PopoverTrigger, PopoverAnchor, PopoverContent } from "./ui/popover.js";
 export { Select, selectClassName } from "./ui/select.js";
@@ -66,7 +78,7 @@ export { usePageTools } from "./lib/use-page-tools.js";
 export { useNewConversation } from "./lib/use-new-conversation.js";
 export { AGUIAdapterSDK } from "./lib/ag-ui-adapter.js";
 export { FileAttachmentAdapter, resolveMimeType } from "./lib/attachment-adapter.js";
-export { registerAttachmentAdapter, useAttachmentAdapterStore, } from "./lib/attachment-registry.js";
+export { registerAttachmentAdapter, useAttachmentAdapterStore } from "./lib/attachment-registry.js";
 export { ReasoningPart, ReasoningMessagePartComponent } from "./components/reasoning-part.js";
 export { ReasoningEffortPicker } from "./components/reasoning-effort-picker.js";
 export { AuthProvider } from "./lib/auth-provider.js";

package/dist/index.js

@@ -31,6 +31,18 @@ export { CollectionEmptyState } from "./components/collection-empty-state.js";
 export { CollectionSkeleton } from "./components/collection-skeleton.js";
 export { InfiniteScrollSentinel } from "./components/infinite-scroll-sentinel.js";
 export { CollectionSurface } from "./components/collection-surface.js";
+export { DataTable } from "./components/data-table/data-table.js";
+export { DataTableToolbar, } from "./components/data-table/data-table-toolbar.js";
+export { DataTableFacetedFilter, } from "./components/data-table/data-table-faceted-filter.js";
+export { DataTableViewOptions, } from "./components/data-table/data-table-view-options.js";
+export { DataTableColumnHeader, } from "./components/data-table/data-table-column-header.js";
+export { DataTablePagination, } from "./components/data-table/data-table-pagination.js";
+export { DataTableRowActions, } from "./components/data-table/data-table-row-actions.js";
+export { selectionColumn, SELECTION_COLUMN_ID } from "./components/data-table/selection-column.js";
+export { useDataTable } from "./components/data-table/use-data-table.js";
+export { DEFAULT_PAGE_SIZE, EMPTY_DATA_TABLE_STATE, isDataTableUrlKey, mergeDataTableUrlState, parseDataTableState, serializeDataTableState, } from "./components/data-table/state.js";
+export { FACET_EMPTY, cellText, columnLabel, facetCounts, facetFilterFn, facetKeys, facetOptions, normalizeFacetValue, rowSearchText, tokenSearchFilterFn, } from "./components/data-table/facets.js";
+export { createColumnHelper, flexRender, } from "@tanstack/react-table";
 export { ThemeRuntimeProvider, ThemeScope, ThemeDocumentMetadata, useThemeRuntime, } from "./components/theme-runtime-provider.js";
 export { JsonViewer } from "./components/json-viewer.js";
 export { UserMenu } from "./components/user-menu.js";
@@ -46,7 +58,7 @@ export { SurfaceCard, surfaceCardVariants } from "./components/surface-card.js";
 // package. Tracked for a follow-up under #95/#96.
 export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from "./ui/tooltip.js";
 export { Collapsible, CollapsibleTrigger, CollapsibleContent } from "./ui/collapsible.js";
-export { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuLabel, } from "./ui/dropdown-menu.js";
+export { DropdownMenu, DropdownMenuTrigger, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuLabel, } from "./ui/dropdown-menu.js";
 export { Dialog, DialogPortal, DialogOverlay, DialogTrigger, DialogClose, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription, } from "./ui/dialog.js";
 export { Popover, PopoverTrigger, PopoverAnchor, PopoverContent } from "./ui/popover.js";
 export { Select, selectClassName } from "./ui/select.js";
@@ -74,7 +86,7 @@ export { useNewConversation } from "./lib/use-new-conversation.js";
 // --- Adapters ---
 export { AGUIAdapterSDK } from "./lib/ag-ui-adapter.js";
 export { FileAttachmentAdapter, resolveMimeType } from "./lib/attachment-adapter.js";
-export { registerAttachmentAdapter, useAttachmentAdapterStore, } from "./lib/attachment-registry.js";
+export { registerAttachmentAdapter, useAttachmentAdapterStore } from "./lib/attachment-registry.js";
 export { ReasoningPart, ReasoningMessagePartComponent } from "./components/reasoning-part.js";
 export { ReasoningEffortPicker } from "./components/reasoning-effort-picker.js";
 // --- Auth ---

package/dist/ui/dropdown-menu.d.ts

@@ -5,3 +5,4 @@ export declare const DropdownMenuContent: import("react").ForwardRefExoticCompon
 export declare const DropdownMenuItem: import("react").ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuItemProps & import("react").RefAttributes<HTMLDivElement>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
 export declare const DropdownMenuSeparator: import("react").ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuSeparatorProps & import("react").RefAttributes<HTMLDivElement>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
 export declare const DropdownMenuLabel: import("react").ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuLabelProps & import("react").RefAttributes<HTMLDivElement>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+export declare const DropdownMenuCheckboxItem: import("react").ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuCheckboxItemProps & import("react").RefAttributes<HTMLDivElement>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;

package/dist/ui/dropdown-menu.js

@@ -1,6 +1,7 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu";
 import { forwardRef } from "react";
+import { Check } from "lucide-react";
 import { cn } from "@iloveagents/foundry-web-primitives";
 export const DropdownMenu = DropdownMenuPrimitive.Root;
 export const DropdownMenuTrigger = DropdownMenuPrimitive.Trigger;
@@ -17,3 +18,5 @@ export const DropdownMenuSeparator = forwardRef(({ className, ...props }, ref) =
 DropdownMenuSeparator.displayName = "DropdownMenuSeparator";
 export const DropdownMenuLabel = forwardRef(({ className, ...props }, ref) => (_jsx(DropdownMenuPrimitive.Label, { ref: ref, className: cn("px-2 py-1.5 text-sm font-semibold", className), ...props })));
 DropdownMenuLabel.displayName = "DropdownMenuLabel";
+export const DropdownMenuCheckboxItem = forwardRef(({ className, children, checked, ...props }, ref) => (_jsxs(DropdownMenuPrimitive.CheckboxItem, { ref: ref, checked: checked, className: cn("relative flex cursor-default select-none items-center gap-2 rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none", "transition-colors focus:bg-accent focus:text-accent-foreground", "data-[disabled]:pointer-events-none data-[disabled]:opacity-50", className), ...props, children: [_jsx("span", { className: "absolute left-2 flex size-4 items-center justify-center", children: _jsx(DropdownMenuPrimitive.ItemIndicator, { children: _jsx(Check, { className: "size-4" }) }) }), children] })));
+DropdownMenuCheckboxItem.displayName = "DropdownMenuCheckboxItem";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iloveagents/foundry-web-ui",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "license": "MIT",
   "description": "React agent UI core for Foundry UI — chat, composer, AG-UI adapter for assistant-ui, tool cards, panels, sidebar, theme runtime, and UI stores.",
   "keywords": [
@@ -65,13 +65,14 @@
     "@radix-ui/react-popover": "^1.1.15",
     "@radix-ui/react-slot": "^1.2.0",
     "@radix-ui/react-tooltip": "^1.2.0",
+    "@tanstack/react-table": "^8.21.3",
     "class-variance-authority": "^0.7.0",
     "clsx": "^2.1.0",
-    "tailwind-merge": "^3.5.0",
     "react-markdown": "^10.0.0",
     "remark-gfm": "^4.0.0",
-    "@iloveagents/foundry-agent": "^0.16.0",
-    "@iloveagents/foundry-web-primitives": "^0.16.0"
+    "tailwind-merge": "^3.5.0",
+    "@iloveagents/foundry-agent": "^0.17.0",
+    "@iloveagents/foundry-web-primitives": "^0.17.0"
   },
   "devDependencies": {
     "@ag-ui/client": "^0.0.52",