@instruments/materia-ui 0.1.0

package/dist/compositions/data-grid/data-grid-filterable-header.js

@@ -0,0 +1,71 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button } from "@instruments/materia-ui/components/button";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { Icon } from "@instruments/materia-ui/components/icon";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { ArrowDown, ArrowUp, ChevronDown, ChevronsUpDown } from "lucide-react";
+import { isNumber } from "../../utils/type-guards.js";
+import { FilterDropdown } from "./data-grid-filter-dropdown.js";
+/** Single-arrow sort indicator icons keyed by sort direction. */
+const SORT_ICON_MAP = { asc: ArrowUp, desc: ArrowDown };
+/**
+ * Sort indicator: on a sort-only column a faint double arrow until sorted;
+ * on a filtering column only the arrow of the order in force, so the header
+ * always says which column the rows are sorted by.
+ */
+const SortOnlyIndicator = ({ canFilter, canSort, sorted, }) => {
+    if (!canSort || (canFilter === true && sorted === false)) {
+        return null;
+    }
+    return (_jsx(Icon, { className: cn("transition-opacity", sorted === false ? "opacity-30 group-hover:opacity-50" : "opacity-100"), icon: sorted === false ? ChevronsUpDown : SORT_ICON_MAP[sorted], size: "2xs" }));
+};
+/** Chevron and the number of values chosen, shown when a column is filterable. */
+const MenuIndicator = ({ canFilter, hasActiveFilter, selectedCount, }) => {
+    if (canFilter !== true) {
+        return null;
+    }
+    return (_jsxs(Flex, { align: "center", as: "span", className: "gap-1", children: [_jsx(Icon, { className: "text-muted-foreground group-hover:text-foreground transition-colors", icon: ChevronDown, size: "2xs" }), hasActiveFilter && (_jsx("span", { className: "text-muted-foreground tabular-nums", children: selectedCount }))] }));
+};
+/**
+ * Unified column header for DataGrid columns.
+ * Combines sorting, filtering, search, and tag pills in a single popover.
+ *
+ * - Sort-only columns render a plain button with sort toggle.
+ * - Filter columns open a popover with optional search, facet checkboxes, and sort commands.
+ * - Tag columns add dismissible pills above the facet list via `showSelectedTags`.
+ *
+ * A column whose `header` is plain text gets this automatically: sortable
+ * columns sort from it, and `meta.filter` columns filter from it. Render it
+ * yourself only from a custom `header` function.
+ *
+ * @bestPractice Prefer a plain-text `header` plus `meta.filter` over rendering this by hand; the table then wires it, and `PageToolbarTableFilters` shows the same choices as chips.
+ */
+export const DataGridFilterableHeader = ({ column, children, options, showSelectedTags, showSearch, className, }) => {
+    const canSort = column.getCanSort();
+    const canFilter = column.getCanFilter() && options && options.length > 0;
+    const sorted = column.getIsSorted();
+    const facets = column.getFacetedUniqueValues();
+    const sortKind = isNumber(facets.keys().next().value) ? "number" : "text";
+    const filterValue = column.getFilterValue();
+    const selectedValues = new Set(Array.isArray(filterValue) ? filterValue : []);
+    const hasActiveFilter = selectedValues.size > 0;
+    const searchVisible = showSearch === true ||
+        (showSearch !== false && canFilter === true && options.length > 5);
+    const setSelected = (values) => {
+        column.setFilterValue(values.length > 0 ? values : undefined);
+    };
+    const headerContent = (_jsxs(Flex, { align: "center", as: "span", className: "gap-2", children: [children, _jsx(SortOnlyIndicator, { canFilter: canFilter, canSort: canSort, sorted: sorted }), _jsx(MenuIndicator, { canFilter: canFilter, hasActiveFilter: hasActiveFilter, selectedCount: selectedValues.size })] }));
+    // No filter - render button (sortable or static)
+    if (canFilter !== true) {
+        return (_jsx(Button, { className: cn("-ml-1 font-normal", canSort && "cursor-pointer", className), onClick: canSort ? column.getToggleSortingHandler() : undefined, radius: "full", size: "xs", tone: "neutral", emphasis: "ghost", children: headerContent }));
+    }
+    // With filter dropdown
+    return (_jsx(FilterDropdown, { canSort: canSort, ...(className === undefined ? {} : { className }), facets: facets, hasActiveFilter: hasActiveFilter, headerContent: headerContent, onClearFilter: () => {
+            column.setFilterValue(undefined);
+        }, onClearSort: () => {
+            column.clearSorting();
+        }, onSort: (desc) => {
+            column.toggleSorting(desc);
+        }, onChange: setSelected, options: options, searchVisible: searchVisible, selectedValues: selectedValues, ...(showSelectedTags === undefined ? {} : { showSelectedTags }), sortKind: sortKind, sorted: sorted }));
+};

package/dist/compositions/data-grid/data-grid-root.d.ts

@@ -0,0 +1,18 @@
+import type { DataGridProps } from "./data-grid-types.js";
+/**
+ * Root of the DataGrid compound: merges caller layout/loading props over
+ * sensible defaults and provides the context consumed by the table parts.
+ *
+ * Requires a TanStack `table` instance (throws without one). Applies
+ * `initialColumnPinning` once on mount and auto-enables column pinning for it.
+ *
+ * @bestPractice Reach for `DataGrid` (not `Table`) when you need sorting, filtering, column pinning/visibility, or pagination - `Table` is a plain styled HTML table with no data model.
+ * @bestPractice Pass a `useTable` instance as `table` - `DataGrid` throws "requires the `table` prop" without one; column defs and row model live on that instance, not on `DataGrid` props.
+ * @bestPractice Render the satellite parts (`DataGridTable`, `DataGridPagination`, `DataGridColumnHeader/Filter/Visibility`) inside `DataGrid` - they read the table + layout from its context and break outside it.
+ * @bestPractice Enable features through `tableLayout` (`columnsPinnable`, `columnsResizable`, `columnsVisibility`, …) rather than styling rows manually; set `initialColumnPinning` to pin on mount.
+ * @category data
+ */
+declare const DataGrid: <TData extends object>({ children, table, initialColumnPinning, ...props }: DataGridProps<TData>) => import("react").JSX.Element;
+export { DataGrid };
+export { DataGridProvider, useDataGrid } from "./data-grid-context.js";
+export { DataGridShell } from "./data-grid-shell.js";

package/dist/compositions/data-grid/data-grid-root.js

@@ -0,0 +1,119 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef } from "react";
+import { DataGridProvider } from "./data-grid-context.js";
+/**
+ * Root of the DataGrid compound: merges caller layout/loading props over
+ * sensible defaults and provides the context consumed by the table parts.
+ *
+ * Requires a TanStack `table` instance (throws without one). Applies
+ * `initialColumnPinning` once on mount and auto-enables column pinning for it.
+ *
+ * @bestPractice Reach for `DataGrid` (not `Table`) when you need sorting, filtering, column pinning/visibility, or pagination - `Table` is a plain styled HTML table with no data model.
+ * @bestPractice Pass a `useTable` instance as `table` - `DataGrid` throws "requires the `table` prop" without one; column defs and row model live on that instance, not on `DataGrid` props.
+ * @bestPractice Render the satellite parts (`DataGridTable`, `DataGridPagination`, `DataGridColumnHeader/Filter/Visibility`) inside `DataGrid` - they read the table + layout from its context and break outside it.
+ * @bestPractice Enable features through `tableLayout` (`columnsPinnable`, `columnsResizable`, `columnsVisibility`, …) rather than styling rows manually; set `initialColumnPinning` to pin on mount.
+ * @category data
+ */
+const DataGrid = ({ children, table, initialColumnPinning, ...props }) => {
+    const hasAppliedInitialPinning = useRef(false);
+    const mergedProps = useMemo(() => {
+        const defaultProps = {
+            /** Loading state */
+            loadingMode: "skeleton",
+            /** Table class names */
+            tableClassNames: {
+                base: "",
+                body: "",
+                /** Body row */
+                bodyRow: "",
+                /**
+                 * Edge cell: the outer columns keep the content clear of the
+                 * shell's rounded corners, which the cells' own padding does not.
+                 */
+                edgeCell: "first:ps-5 last:pe-5",
+                footer: "",
+                header: "",
+                /** Header row */
+                headerRow: "",
+                /** Header sticky */
+                headerSticky: "sticky top-0 z-10 bg-card",
+            },
+            /** Table layout */
+            tableLayout: {
+                /** Cell border */
+                cellBorder: false,
+                /** Columns draggable */
+                columnsDraggable: false,
+                /** Columns movable */
+                columnsMovable: false,
+                /** Columns pinnable */
+                columnsPinnable: Boolean(initialColumnPinning),
+                /** Columns resizable */
+                columnsResizable: false,
+                /** Columns visibility */
+                columnsVisibility: false,
+                dense: false,
+                /** Header background */
+                headerBackground: true,
+                /** Header border */
+                headerBorder: true,
+                /** Header sticky */
+                headerSticky: true,
+                /** Row border */
+                rowBorder: true,
+                /** Row height */
+                rowHeight: 72,
+                /** Row rounded */
+                rowRounded: false,
+                /** Rows draggable */
+                rowsDraggable: false,
+                striped: false,
+                width: "fixed",
+            },
+        };
+        return {
+            ...defaultProps,
+            ...props,
+            /** Table class names */
+            tableClassNames: {
+                ...defaultProps.tableClassNames,
+                ...props.tableClassNames,
+            },
+            /** Table layout */
+            tableLayout: {
+                ...defaultProps.tableLayout,
+                ...props.tableLayout,
+            },
+        };
+    }, [props, initialColumnPinning]);
+    // Ensure table is provided
+    if (!table) {
+        throw new Error("DataGrid requires the `table` prop.");
+    }
+    const columnsPinnable = mergedProps.tableLayout?.columnsPinnable === true;
+    useEffect(() => {
+        if (!columnsPinnable) {
+            return;
+        }
+        // oxlint-disable-next-line react-doctor/no-pass-data-to-parent -- not parent state: this is TanStack Table's imperative setOptions API mutating the consumer-owned table instance to enable column pinning; there is no parent setter being called.
+        table.setOptions((prev) => ({
+            ...prev,
+            enableColumnPinning: true,
+        }));
+    }, [columnsPinnable, table]);
+    useEffect(() => {
+        if (hasAppliedInitialPinning.current || !initialColumnPinning) {
+            return;
+        }
+        hasAppliedInitialPinning.current = true;
+        table.setColumnPinning({
+            start: initialColumnPinning.left ?? [],
+            end: initialColumnPinning.right ?? [],
+        });
+    }, [initialColumnPinning, table]);
+    return (_jsx(DataGridProvider, { table: table, ...mergedProps, children: children }));
+};
+export { DataGrid };
+export { DataGridProvider, useDataGrid } from "./data-grid-context.js";
+export { DataGridShell } from "./data-grid-shell.js";

package/dist/compositions/data-grid/data-grid-shell.d.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from "react";
+import type { BorderStyle } from "../../tokens/border.js";
+/** Rounded, bordered container that frames the grid; wrap `DataGridTable` in it. */
+declare const DataGridShell: ({ children, className, border, ref, }: {
+    /** Child elements */
+    children: ReactNode;
+    /** CSS class name */
+    className?: string;
+    /** Border style. Options: "solid" (default), "none", "dashed". */
+    border?: BorderStyle;
+    /** Ref to the container element */
+    ref?: React.Ref<HTMLDivElement>;
+}) => import("react").JSX.Element;
+export { DataGridShell };

package/dist/compositions/data-grid/data-grid-shell.js

@@ -0,0 +1,8 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Grid } from "@instruments/materia-ui/components/grid";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { borderStyleClasses } from "../../tokens/border.js";
+/** Rounded, bordered container that frames the grid; wrap `DataGridTable` in it. */
+const DataGridShell = ({ children, className, border = "solid", ref, }) => (_jsx(Grid, { className: cn("bg-card w-full overflow-hidden rounded-3xl", borderStyleClasses(border), className), columns: "none", "data-component": "data-grid", "data-slot": "data-grid", gap: "none", ref: ref, children: children }));
+export { DataGridShell };

package/dist/compositions/data-grid/data-grid-sort-filter.d.ts

@@ -0,0 +1,114 @@
+import type { DataGridColumn as Column, DataGridFeatures, DataGridTable as Table } from "@instruments/materia-ui/utils/data-grid-table";
+import type { FilterFn, TableOptions } from "@tanstack/react-table";
+import type { DataGridColumnFilterMeta, FilterOption } from "./data-grid-types.js";
+/**
+ * Keeps a row when its value is one of the chosen values. Values are compared
+ * as text, so a numeric column filters by the same strings its options show.
+ */
+export declare const filterFnInValues: <TData extends object>() => FilterFn<DataGridFeatures, TData>;
+/** The column's filter declaration, or undefined when it does not filter. */
+export declare const getColumnFilterMeta: <TData extends object>(column: Column<TData>) => DataGridColumnFilterMeta | undefined;
+/** The column's header when it is plain text; undefined when it renders itself. */
+export declare const getColumnHeaderText: <TData extends object>(column: Column<TData>) => string | undefined;
+/** What to call the column in the toolbar: its title, else its plain-text header, else its id. */
+export declare const getColumnTitle: <TData extends object>(column: Column<TData>) => string;
+/**
+ * The values a filterable column offers: its declared options, else every
+ * value in its rows, in order. A server-filtered table only holds a page of
+ * rows, so it must declare them.
+ */
+export declare const getColumnFilterOptions: <TData extends object>(column: Column<TData>, table: Table<TData>) => FilterOption[];
+/** The values chosen in a column's filter. */
+export declare const getColumnFilterValues: <TData extends object>(column: Column<TData>) => string[];
+/** Sets a column's chosen values, removing the filter when none are left. */
+export declare const setColumnFilterValues: <TData extends object>(column: Column<TData>, values: readonly string[]) => void;
+/** The table's filterable columns, in column order. */
+export declare const getFilterableColumns: <TData extends object>(table: Table<TData>) => Column<TData>[];
+/** The table's sortable columns, in column order. */
+export declare const getSortableColumns: <TData extends object>(table: Table<TData>) => Column<TData>[];
+export interface DataGridAppliedFilter<TData extends object> {
+    column: Column<TData>;
+    /** The value's display label. */
+    label: string;
+    value: string;
+}
+/** Every chosen value across the table's filters, column by column. */
+export declare const getAppliedFilters: <TData extends object>(table: Table<TData>) => DataGridAppliedFilter<TData>[];
+/**
+ * `useTable` for a DataGrid: the one route to a sortable, filterable table.
+ * Columns marked `meta.filter` filter by the values chosen in their header
+ * or the page toolbar, and one column sorts at a time, so the header arrows
+ * and the toolbar's sort menu always agree.
+ *
+ * @example
+ * const table = useDataGridTable({
+ *   columns,
+ *   data,
+ *   features: dataGridFeatures,
+ *   getRowId: (row) => row.id,
+ * });
+ */
+export declare const useDataGridTable: <TData extends object>(options: TableOptions<DataGridFeatures, TData>) => import("@tanstack/react-table").ReactTable<{
+    cellSelectionFeature: import("@tanstack/react-table").TableFeature;
+    cellSpanningFeature: import("@tanstack/react-table").TableFeature;
+    columnFacetingFeature: import("@tanstack/react-table").TableFeature;
+    columnFilteringFeature: import("@tanstack/react-table").TableFeature;
+    columnGroupingFeature: import("@tanstack/react-table").TableFeature;
+    columnOrderingFeature: import("@tanstack/react-table").TableFeature;
+    columnPinningFeature: import("@tanstack/react-table").TableFeature;
+    columnResizingFeature: import("@tanstack/react-table").TableFeature;
+    columnSizingFeature: import("@tanstack/react-table").TableFeature;
+    columnVisibilityFeature: import("@tanstack/react-table").TableFeature;
+    globalFilteringFeature: import("@tanstack/react-table").TableFeature;
+    rowAggregationFeature: import("@tanstack/react-table").TableFeature;
+    rowExpandingFeature: import("@tanstack/react-table").TableFeature;
+    rowPaginationFeature: import("@tanstack/react-table").TableFeature;
+    rowPinningFeature: import("@tanstack/react-table").TableFeature;
+    rowSelectionFeature: import("@tanstack/react-table").TableFeature;
+    rowSortingFeature: import("@tanstack/react-table").TableFeature;
+    aggregationFns: {
+        sum: import("@tanstack/react-table").AggregationFnDef<any, any, unknown, number>;
+        min: import("@tanstack/react-table").AggregationFnDef<any, any, unknown, (number | Date) | undefined>;
+        max: import("@tanstack/react-table").AggregationFnDef<any, any, unknown, (number | Date) | undefined>;
+        extent: import("@tanstack/react-table").AggregationFnDef<any, any, unknown, [(number | Date) | undefined, (number | Date) | undefined]>;
+        mean: import("@tanstack/react-table").AggregationFnDef<any, any, unknown, number | undefined>;
+        median: import("@tanstack/react-table").AggregationFnDef<any, any, unknown, number | undefined>;
+        unique: import("@tanstack/react-table").AggregationFnDef<any, any, unknown, unknown[]>;
+        uniqueCount: import("@tanstack/react-table").AggregationFnDef<any, any, unknown, number>;
+        count: import("@tanstack/react-table").AggregationFnDef<any, any, unknown, number>;
+        first: import("@tanstack/react-table").AggregationFnDef<any, any, unknown, unknown>;
+        last: import("@tanstack/react-table").AggregationFnDef<any, any, unknown, unknown>;
+    };
+    facetedRowModel: (table: import("@tanstack/react-table").Table<any, any>, columnId: string) => () => import("@tanstack/react-table").RowModel<any, any>;
+    facetedUniqueValues: (table: import("@tanstack/react-table").Table<import("@tanstack/react-table").TableFeatures, any>, columnId: string) => () => Map<any, number>;
+    filterFns: {
+        arrIncludes: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+        arrIncludesAll: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+        arrHas: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+        arrIncludesSome: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+        between: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+        betweenInclusive: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+        empty: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+        endsWith: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+        equals: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+        equalsString: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+        equalsStringSensitive: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+        inDateRange: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+        inNumberRange: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+        includesString: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+        includesStringSensitive: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+        notEmpty: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+        startsWith: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+        weakEquals: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+    };
+    filteredRowModel: (table: import("@tanstack/react-table").Table<any, any>) => () => import("@tanstack/react-table").RowModel<any, any>;
+    sortFns: {
+        alphanumeric: import("@tanstack/react-table").CreatedSortFn<any, any>;
+        alphanumericCaseSensitive: import("@tanstack/react-table").CreatedSortFn<any, any>;
+        basic: import("@tanstack/react-table").CreatedSortFn<any, any>;
+        datetime: import("@tanstack/react-table").CreatedSortFn<any, any>;
+        text: import("@tanstack/react-table").CreatedSortFn<any, any>;
+        textCaseSensitive: import("@tanstack/react-table").CreatedSortFn<any, any>;
+    };
+    sortedRowModel: (table: import("@tanstack/react-table").Table<any, any>) => () => import("@tanstack/react-table").RowModel<any, any>;
+}, TData, import("@tanstack/react-table").TableState_CellSelection & import("@tanstack/react-table").TableState_ColumnFiltering & import("@tanstack/react-table").TableState_ColumnGrouping & import("@tanstack/react-table").TableState_ColumnOrdering & import("@tanstack/react-table").TableState_ColumnPinning & import("@tanstack/react-table").TableState_ColumnResizing & import("@tanstack/react-table").TableState_ColumnSizing & import("@tanstack/react-table").TableState_ColumnVisibility & import("@tanstack/react-table").TableState_GlobalFiltering & import("@tanstack/react-table").TableState_RowExpanding & import("@tanstack/react-table").TableState_RowPagination & import("@tanstack/react-table").TableState_RowPinning & import("@tanstack/react-table").TableState_RowSelection & import("@tanstack/react-table").TableState_RowSorting>;

package/dist/compositions/data-grid/data-grid-sort-filter.js

@@ -0,0 +1,98 @@
+"use client";
+import { useTable } from "@tanstack/react-table";
+import { isString } from "../../utils/type-guards.js";
+/**
+ * Keeps a row when its value is one of the chosen values. Values are compared
+ * as text, so a numeric column filters by the same strings its options show.
+ */
+export const filterFnInValues = () => (row, columnId, values) => values === undefined ||
+    values.length === 0 ||
+    values.includes(String(row.getValue(columnId)));
+/** The column's filter declaration, or undefined when it does not filter. */
+export const getColumnFilterMeta = (column) => {
+    const filter = column.columnDef.meta?.filter;
+    if (filter === undefined) {
+        return undefined;
+    }
+    return filter === true ? {} : filter;
+};
+/** The column's header when it is plain text; undefined when it renders itself. */
+export const getColumnHeaderText = (column) => {
+    const { header } = column.columnDef;
+    return isString(header) ? header : undefined;
+};
+/** What to call the column in the toolbar: its title, else its plain-text header, else its id. */
+export const getColumnTitle = (column) => column.columnDef.meta?.title ?? getColumnHeaderText(column) ?? column.id;
+/**
+ * The values a filterable column offers: its declared options, else every
+ * value in its rows, in order. A server-filtered table only holds a page of
+ * rows, so it must declare them.
+ */
+export const getColumnFilterOptions = (column, table) => {
+    const options = getColumnFilterMeta(column)?.options;
+    if (options !== undefined) {
+        return options;
+    }
+    if (table.options.manualFiltering === true) {
+        throw new Error(`DataGrid column "${column.id}" filters on the server, so its meta.filter needs options.`);
+    }
+    return [...column.getFacetedUniqueValues().keys()]
+        .flatMap((value) => value === undefined || value === null || value === ""
+        ? []
+        : [String(value)])
+        .toSorted((a, b) => a.localeCompare(b, undefined, { numeric: true }))
+        .map((value) => ({ label: value, value }));
+};
+/** The values chosen in a column's filter. */
+export const getColumnFilterValues = (column) => {
+    const value = column.getFilterValue();
+    return Array.isArray(value) ? value.map(String) : [];
+};
+/** Sets a column's chosen values, removing the filter when none are left. */
+export const setColumnFilterValues = (column, values) => {
+    column.setFilterValue(values.length > 0 ? [...values] : undefined);
+};
+/** The table's filterable columns, in column order. */
+export const getFilterableColumns = (table) => table
+    .getAllLeafColumns()
+    .filter((column) => getColumnFilterMeta(column) !== undefined && column.getCanFilter());
+/** The table's sortable columns, in column order. */
+export const getSortableColumns = (table) => table.getAllLeafColumns().filter((column) => column.getCanSort());
+/** Every chosen value across the table's filters, column by column. */
+export const getAppliedFilters = (table) => getFilterableColumns(table).flatMap((column) => {
+    const options = getColumnFilterMeta(column)?.options;
+    return getColumnFilterValues(column).map((value) => ({
+        column,
+        label: options?.find((option) => option.value === value)?.label ?? value,
+        value,
+    }));
+});
+/** Gives each filterable column the set-membership filter unless it names its own. */
+const withFilterFns = (columns) => columns.map((column) => {
+    const nested = "columns" in column && column.columns !== undefined
+        ? { columns: withFilterFns(column.columns) }
+        : {};
+    const filterFn = column.meta?.filter !== undefined && column.filterFn === undefined
+        ? { filterFn: filterFnInValues() }
+        : {};
+    return { ...column, ...nested, ...filterFn };
+});
+/**
+ * `useTable` for a DataGrid: the one route to a sortable, filterable table.
+ * Columns marked `meta.filter` filter by the values chosen in their header
+ * or the page toolbar, and one column sorts at a time, so the header arrows
+ * and the toolbar's sort menu always agree.
+ *
+ * @example
+ * const table = useDataGridTable({
+ *   columns,
+ *   data,
+ *   features: dataGridFeatures,
+ *   getRowId: (row) => row.id,
+ * });
+ */
+export const useDataGridTable = (options) => useTable({
+    enableMultiSort: false,
+    ...options,
+    columns: withFilterFns(options.columns),
+});

package/dist/compositions/data-grid/data-grid-toolbar.d.ts

@@ -0,0 +1,16 @@
+import type React from "react";
+export interface DataGridToolbarProps extends React.ComponentProps<"div"> {
+    /**
+     * Content aligned to the left side of the toolbar
+     */
+    left?: React.ReactNode;
+    /**
+     * Content aligned to the right side of the toolbar
+     */
+    right?: React.ReactNode;
+}
+/**
+ * Header bar above a DataGrid for actions, search, and filters. Renders `left`
+ * and `right` in a space-between row; falls back to `children` when neither is set.
+ */
+export declare const DataGridToolbar: ({ className, left, right, children, ...props }: DataGridToolbarProps) => React.JSX.Element;

package/dist/compositions/data-grid/data-grid-toolbar.js

@@ -0,0 +1,13 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * Header bar above a DataGrid for actions, search, and filters. Renders `left`
+ * and `right` in a space-between row; falls back to `children` when neither is set.
+ */
+export const DataGridToolbar = ({ className, left, right, children, ...props }) => {
+    const hasLeft = left !== undefined && left !== null;
+    const hasRight = right !== undefined && right !== null;
+    return (_jsx("div", { className: cn("shrink-0 pb-6", className), "data-component": "data-grid-toolbar", "data-slot": "data-grid-toolbar", ...props, children: _jsxs(Flex, { align: "center", className: "h-full", justify: "space-between", children: [hasLeft && (_jsx(Flex, { align: "center", "data-slot": "toolbar-left", gap: "sm", children: left })), hasRight && (_jsx(Flex, { align: "center", "data-slot": "toolbar-right", gap: "sm", children: right })), !hasLeft && !hasRight && children] }) }));
+};

package/dist/compositions/data-grid/data-grid-types.d.ts

@@ -0,0 +1,150 @@
+import type { DataGridTable as Table } from "@instruments/materia-ui/utils/data-grid-table";
+import type { CellData, TableFeatures, ColumnFiltersState, RowData, SortingState } from "@tanstack/react-table";
+import type { ReactNode } from "react";
+/**
+ * Extends TanStack Table's per-column `meta` with DataGrid rendering hooks;
+ * set these on a column definition's `meta` field.
+ */
+declare module "@tanstack/react-table" {
+    interface ColumnMeta<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData> {
+        /** Extra class(es) applied to every body cell in this column. */
+        cellClassName?: string;
+        /** Renders the expanded-row panel for a row; its presence marks the row expandable. */
+        expandedContent?: (row: TData) => ReactNode;
+        /** Extra class(es) applied to this column's header cell. */
+        headerClassName?: string;
+        /** Tooltip/accessible title for the header when the visible label is abbreviated. */
+        headerTitle?: string;
+        /** Placeholder rendered in this cell while loading in `"skeleton"` mode. */
+        skeleton?: ReactNode;
+        /**
+         * Makes the column filterable from its header and the page toolbar.
+         * `true` lists the column's own values; pass `options` to name them, or
+         * when the server filters and the rows on hand are not all of them.
+         * The column's `filterFn` defaults to set membership via
+         * `useDataGridTable`.
+         */
+        filter?: true | DataGridColumnFilterMeta;
+        /**
+         * The column's name where its `header` is not plain text, used by the
+         * toolbar's sort menu and filter chips.
+         */
+        title?: string;
+    }
+}
+/** How a filterable column offers its values. */
+export interface DataGridColumnFilterMeta {
+    /** The values to offer, in order. Defaults to the column's own values. */
+    options?: FilterOption[];
+    /** Show a search field above the values: true, false, or automatic (over five). */
+    search?: boolean;
+}
+/** Query params a server-side data source receives when DataGrid drives paging, sorting, and filtering. */
+/** A selectable facet in a filterable column header: the stored filter `value` and its display `label`. */
+export interface FilterOption {
+    label: string;
+    value: string;
+}
+export interface DataGridApiFetchParams {
+    filters?: ColumnFiltersState;
+    pageIndex: number;
+    pageSize: number;
+    searchQuery?: string;
+    sorting?: SortingState;
+}
+/** Response a data source returns to DataGrid: the current page's rows plus total-count pagination. */
+export interface DataGridApiResponse<T> {
+    data: T[];
+    /** True when the query matched no rows; drives the empty state. */
+    empty: boolean;
+    pagination: {
+        total: number;
+        page: number;
+    };
+}
+/** Value exposed by `useDataGrid`: the table instance alongside the resolved props, loading flag, and count. */
+export interface DataGridContextProps<TData extends object> {
+    loading?: boolean;
+    props: DataGridProps<TData>;
+    recordCount: number;
+    table: Table<TData>;
+}
+/**
+ * Params for a manual/imperative fetch. Like {@link DataGridApiFetchParams} but
+ * keyed by `columnFilters` and without a free-text `searchQuery`.
+ */
+export interface DataGridRequestParams {
+    columnFilters?: ColumnFiltersState;
+    pageIndex: number;
+    pageSize: number;
+    sorting?: SortingState;
+}
+/** Props for the `DataGrid` provider that wraps a TanStack table with layout, loading, and interaction config. */
+export interface DataGridProps<TData extends object> {
+    children?: ReactNode;
+    className?: string;
+    /** Content shown in place of rows when the table is empty. */
+    emptyMessage?: ReactNode | string;
+    /** Initial pinned columns (applied once). */
+    initialColumnPinning?: {
+        left?: string[];
+        right?: string[];
+    };
+    loading?: boolean;
+    loadingMessage?: ReactNode | string;
+    /**
+     * How the loading state renders.
+     * @default "skeleton"
+     */
+    loadingMode?: "skeleton" | "spinner";
+    /** Invoked when a body row is clicked; providing it makes rows interactive. */
+    onRowClick?: (row: TData) => void;
+    /** Total row count across all pages; drives pagination and the empty state. */
+    recordCount: number;
+    /** TanStack table instance to render. Required by `DataGrid`; optional here so context can be shared. */
+    table?: Table<TData>;
+    /** Per-slot class overrides for the table's structural elements. */
+    tableClassNames?: {
+        base?: string;
+        header?: string;
+        headerRow?: string;
+        headerSticky?: string;
+        body?: string;
+        bodyRow?: string;
+        footer?: string;
+        edgeCell?: string;
+    };
+    /** Presentational toggles for density, borders, sticky/pinnable columns, and row sizing. */
+    tableLayout?: {
+        dense?: boolean;
+        cellBorder?: boolean;
+        rowBorder?: boolean;
+        rowRounded?: boolean;
+        striped?: boolean;
+        headerBackground?: boolean;
+        headerBorder?: boolean;
+        headerSticky?: boolean;
+        /** Column sizing strategy: `"fixed"` respects column sizes, `"auto"` lets content size them. */
+        width?: "auto" | "fixed";
+        columnsVisibility?: boolean;
+        columnsResizable?: boolean;
+        /** Enable column pinning. Auto-enabled when `initialColumnPinning` is set. */
+        columnsPinnable?: boolean;
+        columnsMovable?: boolean;
+        columnsDraggable?: boolean;
+        rowsDraggable?: boolean;
+        /** Body row height in pixels. */
+        rowHeight?: number;
+        /** Height in pixels of an expanded row's content area. */
+        expandedRowHeight?: number;
+    };
+    /** Row virtualisation for large datasets. */
+    virtualization?: {
+        /** Window the rows. On by default; set `false` to render every row. */
+        enabled?: boolean;
+        /** Estimated row height in pixels, used to size the virtual scroll area. */
+        estimateSize?: number;
+        /** Rows rendered beyond the visible window on each side. */
+        overscan?: number;
+    };
+}

package/dist/compositions/data-grid/data-grid-types.js

@@ -0,0 +1 @@
+export {};