@instruments/materia-ui 0.1.0

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

@@ -0,0 +1,33 @@
+import type { DataGridColumn as Column } from "@instruments/materia-ui/utils/data-grid-table";
+import type { LucideIcon } from "lucide-react";
+import type * as React from "react";
+interface ColumnFilterOption {
+    /** Label text */
+    label: string;
+    /** Current value */
+    value: string;
+    /** Optional leading icon (Lucide or any SVG component), rendered via `Icon`. */
+    icon?: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>;
+}
+interface DataGridColumnFilterProps<TData extends object, TValue> {
+    /** TanStack Table column to filter; supplies facet counts and reads/writes its filter value. */
+    column?: Column<TData, TValue>;
+    /** Selectable values shown in the filter list. */
+    options: ColumnFilterOption[];
+    /** Label for the trigger button and the search input placeholder. */
+    title?: string;
+}
+/**
+ * Faceted multi-select filter for a DataGrid column, built on Base UI Combobox
+ * in `multiple` mode with the search field inside the popup.
+ * The trigger summarises the selection; the popup lists options with live facet counts and a clear action.
+ *
+ * @bestPractice For a DataGrid, prefer marking the column `meta: { filter: true }` and building the table with `useDataGridTable`: its header and `PageToolbarTableFilters` then filter it from one state. Use this only for a standalone filter outside that route.
+ * @bestPractice Pass the TanStack `column` instance (not a column id) - counts come from `column.getFacetedUniqueValues()`, so wire `getFacetedUniqueValues`/`getFacetedRowModel` into the table for live facet counts.
+ * @bestPractice Supply `options` (label/value/icon) explicitly; the filter renders those choices, it does not derive them from the data - omitted values won't be filterable.
+ * @bestPractice Use this for a discrete multi-select facet; it stores an array filter value, so pair it with a column filter fn that matches array membership.
+ * @bestPractice The typed search survives each pick, so several matches can be ticked from one query; it resets when the popup closes.
+ * @category data
+ */
+declare const DataGridColumnFilter: <TData extends object, TValue>({ column, title, options, }: DataGridColumnFilterProps<TData, TValue>) => React.JSX.Element;
+export { DataGridColumnFilter, type DataGridColumnFilterProps };

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

@@ -0,0 +1,62 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Combobox as ComboboxPrimitive } from "@base-ui/react/combobox";
+import { Badge } from "@instruments/materia-ui/components/badge";
+import { Button } from "@instruments/materia-ui/components/button";
+import { Center } from "@instruments/materia-ui/components/center";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { Icon } from "@instruments/materia-ui/components/icon";
+import { Separator } from "@instruments/materia-ui/components/separator";
+import { focusRing } from "@instruments/materia-ui/tokens/focus-ring";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Check, CirclePlus, Search } from "lucide-react";
+import { POPOVER_CONTENT_ANIMATION, POPOVER_SURFACE, } from "../../tokens/overlay-styles.js";
+/** The selected-value summary shown inside the trigger button. */
+const FilterTriggerBadges = ({ options, selectedValues, }) => {
+    if (selectedValues.size === 0) {
+        return null;
+    }
+    return (_jsxs(_Fragment, { children: [_jsx(Separator, { className: "mx-2 h-4", orientation: "vertical" }), _jsx(Badge, { className: "rounded-sm px-1 font-normal lg:hidden", tone: "neutral", emphasis: "soft", children: selectedValues.size }), _jsx("div", { className: "hidden space-x-1 lg:flex", children: selectedValues.size > 2 ? (_jsxs(Badge, { className: "rounded-sm px-1 font-normal", tone: "neutral", emphasis: "soft", children: [selectedValues.size, " selected"] })) : (options.flatMap((option) => selectedValues.has(option.value)
+                    ? [
+                        _jsx(Badge, { className: "rounded-sm px-1 font-normal", tone: "neutral", emphasis: "soft", children: option.label }, option.value),
+                    ]
+                    : [])) })] }));
+};
+/** A single selectable option row in the filter list. */
+const FilterOptionItem = ({ count, isSelected, option, }) => (_jsxs(ComboboxPrimitive.Item, { className: cn("text-paragraph-sm relative flex w-full cursor-default items-center gap-2 rounded-sm px-2.5 py-1.5 outline-none select-none", "hover:bg-accent hover:text-accent-foreground", "data-highlighted:bg-accent data-highlighted:text-accent-foreground", "[&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0"), "data-slot": "data-grid-column-filter-option", value: option, children: [_jsx(Center, { className: cn("border-primary me-2 size-4 rounded-sm border", isSelected
+                ? "bg-primary text-primary-foreground"
+                : "opacity-50 [&_svg]:invisible"), children: _jsx(Icon, { icon: Check, size: "xs" }) }), option.icon === undefined ? null : (_jsx(Icon, { className: "text-muted-foreground mr-2", icon: option.icon, size: "xs" })), _jsx("span", { children: option.label }), count > 0 && (_jsx(Center, { as: "span", className: "text-caption ms-auto size-4 font-mono", children: count }))] }));
+const optionToLabel = (option) => option.label;
+const optionToValue = (option) => option.value;
+const isSameOption = (option, value) => option.value === value.value;
+/**
+ * Faceted multi-select filter for a DataGrid column, built on Base UI Combobox
+ * in `multiple` mode with the search field inside the popup.
+ * The trigger summarises the selection; the popup lists options with live facet counts and a clear action.
+ *
+ * @bestPractice For a DataGrid, prefer marking the column `meta: { filter: true }` and building the table with `useDataGridTable`: its header and `PageToolbarTableFilters` then filter it from one state. Use this only for a standalone filter outside that route.
+ * @bestPractice Pass the TanStack `column` instance (not a column id) - counts come from `column.getFacetedUniqueValues()`, so wire `getFacetedUniqueValues`/`getFacetedRowModel` into the table for live facet counts.
+ * @bestPractice Supply `options` (label/value/icon) explicitly; the filter renders those choices, it does not derive them from the data - omitted values won't be filterable.
+ * @bestPractice Use this for a discrete multi-select facet; it stores an array filter value, so pair it with a column filter fn that matches array membership.
+ * @bestPractice The typed search survives each pick, so several matches can be ticked from one query; it resets when the popup closes.
+ * @category data
+ */
+const DataGridColumnFilter = ({ column, title, options, }) => {
+    const facets = column?.getFacetedUniqueValues();
+    const filterValue = column?.getFilterValue();
+    const selectedValues = new Set(Array.isArray(filterValue) ? filterValue : []);
+    const selectedOptions = options.filter((option) => selectedValues.has(option.value));
+    return (_jsxs(ComboboxPrimitive.Root, { autoHighlight: true, isItemEqualToValue: isSameOption, itemToStringLabel: optionToLabel, itemToStringValue: optionToValue, items: options, multiple: true, onInputValueChange: (_value, eventDetails) => {
+            // Keep the typed filter while ticking several matches.
+            if (eventDetails.isItemPress === true) {
+                eventDetails.cancel();
+            }
+        }, onValueChange: (next) => {
+            column?.setFilterValue(next.length > 0 ? next.map((option) => option.value) : undefined);
+        }, value: selectedOptions, children: [_jsxs(ComboboxPrimitive.Trigger
+            // It renders the kit's Button, a native <button>.
+            , { 
+                // It renders the kit's Button, a native <button>.
+                nativeButton: true, "aria-label": title, render: _jsx(Button, { tone: "neutral", emphasis: "outline", "data-component": "data-grid-column-filter", pressed: false, size: "sm" }), children: [_jsx(Icon, { icon: CirclePlus, size: "xs" }), title, _jsx(FilterTriggerBadges, { options: options, selectedValues: selectedValues })] }), _jsx(ComboboxPrimitive.Portal, { children: _jsx(ComboboxPrimitive.Positioner, { align: "start", className: "z-50", sideOffset: 4, children: _jsx(ComboboxPrimitive.Popup, { "aria-label": title, className: `${POPOVER_CONTENT_ANIMATION} ${POPOVER_SURFACE} w-50 origin-(--transform-origin) rounded-3xl`, "data-slot": "data-grid-column-filter-content", children: _jsxs(Flex, { className: "bg-popover text-popover-foreground size-full overflow-hidden rounded-lg border shadow-xs", direction: "column", children: [_jsxs(Flex, { align: "center", className: "h-9 border-b px-3", gap: "xs", children: [_jsx(Icon, { className: "shrink-0 opacity-50", icon: Search, size: "xs" }), _jsx(ComboboxPrimitive.Input, { className: "placeholder:text-muted-foreground text-paragraph-sm flex h-10 w-full bg-transparent py-3 outline-hidden", placeholder: title })] }), _jsx(ComboboxPrimitive.Empty, { className: "text-paragraph-sm py-6 text-center empty:p-0", children: "No results found." }), _jsx(ComboboxPrimitive.List, { className: "max-h-75 scroll-py-1 overflow-x-hidden overflow-y-auto overscroll-contain p-1 empty:hidden", children: (option) => (_jsx(FilterOptionItem, { count: facets?.get(option.value) ?? 0, isSelected: selectedValues.has(option.value), option: option }, option.value)) }), selectedValues.size > 0 && (_jsx("div", { className: "border-t p-1", children: _jsx("button", { className: cn(focusRing(), "hover:bg-accent hover:text-accent-foreground text-paragraph-sm flex w-full cursor-default items-center justify-center rounded-sm px-2.5 py-1.5 select-none"), onClick: () => column?.setFilterValue(undefined), type: "button", children: "Clear filters" }) }))] }) }) }) })] }));
+};
+export { DataGridColumnFilter };

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

@@ -0,0 +1,2 @@
+export type { DataGridColumnFilterProps } from "./data-grid-column-filter/data-grid-column-filter-root.js";
+export { DataGridColumnFilter } from "./data-grid-column-filter/data-grid-column-filter-root.js";

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

@@ -0,0 +1 @@
+export { DataGridColumnFilter } from "./data-grid-column-filter/data-grid-column-filter-root.js";

package/dist/compositions/data-grid-column-header/data-grid-column-header-menu-items.d.ts

@@ -0,0 +1,22 @@
+import type { DataGridColumn as Column } from "@instruments/materia-ui/utils/data-grid-table";
+import type { getVisibilityColumnOptions } from "./data-grid-column-header-utils.js";
+type VisibilityColumnOption = ReturnType<typeof getVisibilityColumnOptions>[number];
+/** Ascending and descending sort; choosing the active direction clears it. */
+export declare const SortMenuItems: <TData extends object, TValue>({ column, }: {
+    column: Column<TData, TValue>;
+}) => import("react").JSX.Element;
+/** Pin to either edge; choosing the active edge unpins. */
+export declare const PinMenuItems: <TData extends object, TValue>({ column, }: {
+    column: Column<TData, TValue>;
+}) => import("react").JSX.Element;
+/** Move one place left or right; disabled at an edge or while pinned. */
+export declare const MoveMenuItems: <TData extends object, TValue>({ canMove, column, moveColumn, }: {
+    canMove: (direction: "left" | "right") => boolean;
+    column: Column<TData, TValue>;
+    moveColumn: (direction: "left" | "right") => void;
+}) => import("react").JSX.Element;
+/** Submenu of checkbox items that show and hide columns, staying open on toggle. */
+export declare const VisibilityMenu: ({ visibilityColumns, }: {
+    visibilityColumns: VisibilityColumnOption[];
+}) => import("react").JSX.Element;
+export {};

package/dist/compositions/data-grid-column-header/data-grid-column-header-menu-items.js

@@ -0,0 +1,40 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { DropdownMenuCheckboxItem, DropdownMenuItem, DropdownMenuPortal, DropdownMenuSeparator, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, } from "@instruments/materia-ui/components/dropdown-menu";
+import { ArrowDown, ArrowLeft, ArrowLeftToLine, ArrowRight, ArrowRightToLine, ArrowUp, Check, Settings2, } from "lucide-react";
+import { Icon } from "../../components/icon.js";
+/** A menu item that toggles one column state and shows a check while it is on. */
+const ToggleMenuItem = ({ active, children, disabled = false, icon, onToggle, }) => (_jsx(DropdownMenuItem, { disabled: disabled, icon: icon, onClick: onToggle, suffix: active ? _jsx(Icon, { className: "text-primary", icon: Check, size: "xs" }) : null, children: children }));
+/** Ascending and descending sort; choosing the active direction clears it. */
+export const SortMenuItems = ({ column, }) => (_jsxs(_Fragment, { children: [_jsx(ToggleMenuItem, { active: column.getIsSorted() === "asc", disabled: !column.getCanSort(), icon: ArrowUp, onToggle: () => {
+                if (column.getIsSorted() === "asc") {
+                    column.clearSorting();
+                }
+                else {
+                    column.toggleSorting(false);
+                }
+            }, children: "Asc" }), _jsx(ToggleMenuItem, { active: column.getIsSorted() === "desc", disabled: !column.getCanSort(), icon: ArrowDown, onToggle: () => {
+                if (column.getIsSorted() === "desc") {
+                    column.clearSorting();
+                }
+                else {
+                    column.toggleSorting(true);
+                }
+            }, children: "Desc" })] }));
+/** Pin to either edge; choosing the active edge unpins. */
+export const PinMenuItems = ({ column, }) => (_jsxs(_Fragment, { children: [_jsx(ToggleMenuItem, { active: column.getIsPinned() === "start", icon: ArrowLeftToLine, onToggle: () => {
+                column.pin(column.getIsPinned() === "start" ? false : "start");
+            }, children: "Pin to left" }), _jsx(ToggleMenuItem, { active: column.getIsPinned() === "end", icon: ArrowRightToLine, onToggle: () => {
+                column.pin(column.getIsPinned() === "end" ? false : "end");
+            }, children: "Pin to right" })] }));
+/** Move one place left or right; disabled at an edge or while pinned. */
+export const MoveMenuItems = ({ canMove, column, moveColumn, }) => (_jsxs(_Fragment, { children: [_jsx(DropdownMenuSeparator, {}), _jsx(DropdownMenuItem, { disabled: !canMove("left") || column.getIsPinned() !== false, icon: ArrowLeft, onClick: () => {
+                moveColumn("left");
+            }, children: "Move to Left" }), _jsx(DropdownMenuItem, { disabled: !canMove("right") || column.getIsPinned() !== false, icon: ArrowRight, onClick: () => {
+                moveColumn("right");
+            }, children: "Move to Right" })] }));
+/** Submenu of checkbox items that show and hide columns, staying open on toggle. */
+export const VisibilityMenu = ({ visibilityColumns, }) => (_jsxs(DropdownMenuSub, { children: [_jsx(DropdownMenuSubTrigger, { icon: Settings2, children: "Columns" }), _jsx(DropdownMenuPortal, { children: _jsx(DropdownMenuSubContent, { children: visibilityColumns.map((col) => (_jsx(DropdownMenuCheckboxItem, { checked: col.isVisible, className: "capitalize", onCheckedChange: (value) => {
+                        col.toggleVisibility(value);
+                    }, onSelect: (event) => {
+                        event.preventDefault();
+                    }, children: col.label }, col.id))) }) })] }));

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

@@ -0,0 +1,29 @@
+import type { DataGridColumn as Column } from "@instruments/materia-ui/utils/data-grid-table";
+import type { HTMLAttributes, ReactNode } from "react";
+interface DataGridColumnHeaderProps<TData extends object, TValue> extends HTMLAttributes<HTMLDivElement> {
+    /** The TanStack Table column this header sorts, pins, moves, and toggles. */
+    column: Column<TData, TValue>;
+    /** Filter control rendered at the top of the header dropdown menu. */
+    filter?: ReactNode;
+    icon?: ReactNode;
+    pinnable?: boolean;
+    /** Header label text. */
+    title?: string;
+    /**
+     * Expose the column-visibility submenu in the header dropdown.
+     * @default false
+     */
+    visibility?: boolean;
+}
+/**
+ * Interactive column header for a `DataGrid`: click to cycle sorting, or open the
+ * dropdown to sort, pin, move, and toggle column visibility. Reads DataGrid
+ * context, so it must render inside a `DataGrid` provider.
+ *
+ * @bestPractice Render inside a `DataGrid` - it calls `useDataGrid()` and throws outside the provider; use it as a column def's `header`, not standalone.
+ * @bestPractice The pin/move/visibility controls only appear when the matching `tableLayout` flags (`columnsPinnable`/`columnsMovable`/`columnsVisibility`) are enabled on `DataGrid` - a missing menu item usually means the flag is off, not a bug.
+ * @bestPractice Pass a human `title` (and optional `icon`); it is the accessible label for the sort/menu trigger and the moved-column announcement.
+ * @category data
+ */
+declare const DataGridColumnHeader: <TData extends object, TValue>({ column, title, icon, className, filter, visibility, }: DataGridColumnHeaderProps<TData, TValue>) => import("react").JSX.Element;
+export { DataGridColumnHeader, type DataGridColumnHeaderProps };

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

@@ -0,0 +1,72 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button } from "@instruments/materia-ui/components/button";
+import { DropdownMenu, DropdownMenuContent, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger, } from "@instruments/materia-ui/components/dropdown-menu";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { Icon } from "@instruments/materia-ui/components/icon";
+import { useDataGrid } from "@instruments/materia-ui/compositions/data-grid";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { ArrowDown, ArrowUp, ChevronsUpDown, PinOff } from "lucide-react";
+import { MoveMenuItems, PinMenuItems, SortMenuItems, VisibilityMenu, } from "../data-grid-column-header/data-grid-column-header-menu-items.js";
+import { canMoveColumn, getHeaderControlsState, getVisibilityColumnOptions, moveColumnOrder, } from "../data-grid-column-header/data-grid-column-header-utils.js";
+const renderSortIndicator = (sortDirection) => {
+    if (sortDirection === "desc") {
+        return _jsx(Icon, { className: "mt-px", icon: ArrowDown, size: "2xs" });
+    }
+    if (sortDirection === "asc") {
+        return _jsx(Icon, { className: "mt-px", icon: ArrowUp, size: "2xs" });
+    }
+    return _jsx(Icon, { className: "mt-px", icon: ChevronsUpDown, size: "2xs" });
+};
+const HeaderLabel = ({ className, icon, title, }) => (_jsxs(Flex, { align: "center", className: cn("text-secondary-foreground/80 text-grid-header h-full gap-1.5 font-normal [&_svg]:size-3.5 [&_svg]:opacity-60", className), "data-component": "data-grid-column-header", inline: true, children: [icon, title] }));
+const HeaderButton = ({ className, column, icon, loading, recordCount, title, }) => (_jsxs(Button, { emphasis: "ghost", className: cn("text-secondary-foreground/80 hover:bg-secondary hover:text-foreground data-popup-open:bg-secondary data-popup-open:text-foreground -ms-2 h-7 rounded-md px-2 font-normal", className), "data-component": "data-grid-column-header", disabled: loading === true || recordCount === 0, onClick: () => {
+        const isSorted = column.getIsSorted();
+        if (isSorted === "asc") {
+            column.toggleSorting(true);
+        }
+        else if (isSorted === "desc") {
+            column.clearSorting();
+        }
+        else {
+            column.toggleSorting(false);
+        }
+    }, pressed: false, children: [icon, title, column.getCanSort() && renderSortIndicator(column.getIsSorted())] }));
+const HeaderPin = ({ column, title, }) => (_jsx(Button, { emphasis: "ghost", "aria-label": `Unpin ${title} column`, className: "-me-1 rounded-md", icon: PinOff, iconClassName: "opacity-50", onClick: () => {
+        column.pin(false);
+    }, pressed: false, size: "icon-xs", square: true, title: `Unpin ${title} column` }));
+const HeaderControls = ({ canMove, className, column, controlsState, filter, icon, loading, moveColumn, recordCount, title, visibilityColumns, }) => (_jsxs(Flex, { align: "center", className: "h-full gap-1.5", "data-component": "data-grid-column-header", justify: "space-between", children: [_jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { render: _jsx(HeaderButton, { className: className, column: column, icon: icon, loading: loading, recordCount: recordCount, title: title }) }), _jsxs(DropdownMenuContent, { align: "start", className: "w-40", children: [filter !== undefined && filter !== null && (_jsx(DropdownMenuLabel, { children: filter })), controlsState.showFilterSeparator && _jsx(DropdownMenuSeparator, {}), column.getCanSort() && _jsx(SortMenuItems, { column: column }), controlsState.showControlsSeparator && _jsx(DropdownMenuSeparator, {}), controlsState.canShowPinMenu && _jsx(PinMenuItems, { column: column }), controlsState.showMoveMenu && (_jsx(MoveMenuItems, { canMove: canMove, column: column, moveColumn: moveColumn })), controlsState.showVisibilitySeparator && _jsx(DropdownMenuSeparator, {}), controlsState.canShowVisibilityMenu && (_jsx(VisibilityMenu, { visibilityColumns: visibilityColumns }))] })] }), controlsState.canShowPinMenu && column.getIsPinned() !== false && (_jsx(HeaderPin, { column: column, title: title }))] }));
+/**
+ * Interactive column header for a `DataGrid`: click to cycle sorting, or open the
+ * dropdown to sort, pin, move, and toggle column visibility. Reads DataGrid
+ * context, so it must render inside a `DataGrid` provider.
+ *
+ * @bestPractice Render inside a `DataGrid` - it calls `useDataGrid()` and throws outside the provider; use it as a column def's `header`, not standalone.
+ * @bestPractice The pin/move/visibility controls only appear when the matching `tableLayout` flags (`columnsPinnable`/`columnsMovable`/`columnsVisibility`) are enabled on `DataGrid` - a missing menu item usually means the flag is off, not a bug.
+ * @bestPractice Pass a human `title` (and optional `icon`); it is the accessible label for the sort/menu trigger and the moved-column announcement.
+ * @category data
+ */
+const DataGridColumnHeader = ({ column, title = "", icon, className, filter, visibility = false, }) => {
+    const { loading, table, props, recordCount } = useDataGrid();
+    const controlsState = getHeaderControlsState({
+        canPin: column.getCanPin(),
+        canSort: column.getCanSort(),
+        columnsMovable: Boolean(props.tableLayout?.columnsMovable),
+        columnsPinnable: Boolean(props.tableLayout?.columnsPinnable),
+        columnsVisibility: Boolean(props.tableLayout?.columnsVisibility),
+        hasFilter: Boolean(filter),
+        visibility,
+    });
+    const visibilityColumns = getVisibilityColumnOptions(table.getAllColumns());
+    const moveColumn = (direction) => {
+        table.setColumnOrder(moveColumnOrder(column.id, table.state.columnOrder, direction));
+    };
+    const canMove = (direction) => canMoveColumn(column.id, table.state.columnOrder, direction);
+    if (controlsState.showHeaderControls) {
+        return (_jsx(HeaderControls, { canMove: canMove, className: className, column: column, controlsState: controlsState, filter: filter, icon: icon, loading: loading, moveColumn: moveColumn, recordCount: recordCount, title: title, visibilityColumns: visibilityColumns }));
+    }
+    if (controlsState.showHeaderButton ||
+        (props.tableLayout?.columnsResizable === true && column.getCanResize())) {
+        return (_jsx(Flex, { align: "center", className: "h-full", "data-component": "data-grid-column-header", children: _jsx(HeaderButton, { className: className, column: column, icon: icon, loading: loading, recordCount: recordCount, title: title }) }));
+    }
+    return _jsx(HeaderLabel, { className: className, icon: icon, title: title });
+};
+export { DataGridColumnHeader };

package/dist/compositions/data-grid-column-header/data-grid-column-header-utils.d.ts

@@ -0,0 +1,42 @@
+interface HeaderControlsStateOptions {
+    canPin: boolean;
+    canSort: boolean;
+    columnsMovable: boolean;
+    columnsPinnable: boolean;
+    columnsVisibility: boolean;
+    hasFilter: boolean;
+    visibility: boolean;
+}
+interface HeaderControlsState {
+    canShowPinMenu: boolean;
+    canShowVisibilityMenu: boolean;
+    showControlsSeparator: boolean;
+    showFilterSeparator: boolean;
+    showHeaderButton: boolean;
+    showHeaderControls: boolean;
+    showMoveMenu: boolean;
+    showVisibilitySeparator: boolean;
+}
+interface VisibilityColumnOption {
+    id: string;
+    isVisible: boolean;
+    label: string;
+    toggleVisibility: (visible: boolean) => void;
+}
+interface VisibilityColumnDefinition {
+    accessorFn?: unknown;
+    columnDef: {
+        meta?: {
+            headerTitle?: string;
+        };
+    };
+    getCanHide: () => boolean;
+    getIsVisible: () => boolean;
+    id: string;
+    toggleVisibility: (visible: boolean) => void;
+}
+declare const canMoveColumn: (columnId: string, columnOrder: string[], direction: "left" | "right") => boolean;
+declare const moveColumnOrder: (columnId: string, columnOrder: string[], direction: "left" | "right") => string[];
+declare const getHeaderControlsState: (options: HeaderControlsStateOptions) => HeaderControlsState;
+declare const getVisibilityColumnOptions: (columns: VisibilityColumnDefinition[]) => VisibilityColumnOption[];
+export { canMoveColumn, getHeaderControlsState, getVisibilityColumnOptions, type HeaderControlsState, type HeaderControlsStateOptions, moveColumnOrder, type VisibilityColumnDefinition, type VisibilityColumnOption, };

package/dist/compositions/data-grid-column-header/data-grid-column-header-utils.js

@@ -0,0 +1,74 @@
+const canMoveColumn = (columnId, columnOrder, direction) => {
+    const currentIndex = columnOrder.indexOf(columnId);
+    if (direction === "left") {
+        return currentIndex > 0;
+    }
+    return currentIndex !== -1 && currentIndex < columnOrder.length - 1;
+};
+const moveColumnOrder = (columnId, columnOrder, direction) => {
+    const currentIndex = columnOrder.indexOf(columnId);
+    const targetIndex = direction === "left" ? currentIndex - 1 : currentIndex + 1;
+    if (currentIndex === -1 ||
+        targetIndex < 0 ||
+        targetIndex >= columnOrder.length) {
+        return columnOrder;
+    }
+    const nextOrder = [...columnOrder];
+    const [movedColumn] = nextOrder.splice(currentIndex, 1);
+    if (movedColumn === undefined || movedColumn === null || movedColumn === "") {
+        return columnOrder;
+    }
+    nextOrder.splice(targetIndex, 0, movedColumn);
+    return nextOrder;
+};
+const deriveHeaderButton = (d) => d.canSort ||
+    (d.canShowPinMenu && !d.columnsMovable) ||
+    d.hasFilter ||
+    d.canShowVisibilityMenu;
+const deriveHeaderControls = (d) => d.columnsMovable ||
+    d.canShowVisibilityMenu ||
+    d.canShowPinMenu ||
+    d.hasFilter;
+const deriveVisibilitySeparator = (d) => d.canShowVisibilityMenu && (d.canSort || d.canPin || d.hasFilter);
+const getHeaderControlsState = (options) => {
+    const { canPin, canSort, columnsMovable, columnsPinnable, columnsVisibility, hasFilter, visibility, } = options;
+    const canShowPinMenu = columnsPinnable && canPin;
+    const canShowVisibilityMenu = columnsVisibility && visibility;
+    const hasInteractiveControls = canSort || canShowPinMenu || canShowVisibilityMenu;
+    const derived = {
+        canPin,
+        canShowPinMenu,
+        canShowVisibilityMenu,
+        canSort,
+        columnsMovable,
+        hasFilter,
+        hasInteractiveControls,
+    };
+    return {
+        canShowPinMenu,
+        canShowVisibilityMenu,
+        showControlsSeparator: (hasFilter || canSort) && hasInteractiveControls,
+        showFilterSeparator: hasFilter && hasInteractiveControls,
+        showHeaderButton: deriveHeaderButton(derived),
+        showHeaderControls: deriveHeaderControls(derived),
+        showMoveMenu: columnsMovable,
+        showVisibilitySeparator: deriveVisibilitySeparator(derived),
+    };
+};
+const getVisibilityColumnOptions = (columns) => {
+    const options = [];
+    for (const column of columns) {
+        if (column.accessorFn !== undefined && column.getCanHide()) {
+            options.push({
+                id: column.id,
+                isVisible: column.getIsVisible(),
+                label: column.columnDef.meta?.headerTitle ?? column.id,
+                toggleVisibility: (visible) => {
+                    column.toggleVisibility(visible);
+                },
+            });
+        }
+    }
+    return options;
+};
+export { canMoveColumn, getHeaderControlsState, getVisibilityColumnOptions, moveColumnOrder, };

package/dist/compositions/data-grid-column-header.d.ts

@@ -0,0 +1,2 @@
+export type { DataGridColumnHeaderProps } from "./data-grid-column-header/data-grid-column-header-root.js";
+export { DataGridColumnHeader } from "./data-grid-column-header/data-grid-column-header-root.js";

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

@@ -0,0 +1 @@
+export { DataGridColumnHeader } from "./data-grid-column-header/data-grid-column-header-root.js";

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

@@ -0,0 +1,22 @@
+import type { DataGridTable as Table } from "@instruments/materia-ui/utils/data-grid-table";
+import type { ReactElement } from "react";
+/**
+ * Dropdown of checkbox items that show/hide the hideable columns of a TanStack
+ * Table.
+ *
+ * Only lists columns with an accessor that report `getCanHide()`, labelling
+ * each from `columnDef.meta.headerTitle` (falling back to the column id).
+ * Toggling a column keeps the menu open so several can be flipped at once.
+ *
+ * @bestPractice Pass the TanStack `table` instance directly (this part does NOT read DataGrid context) plus a `trigger` element rendered via `render` - supply your own `Button`, it renders none.
+ * @bestPractice Only accessor columns reporting `getCanHide()` appear; set `enableHiding: false` on a column def to keep it always-visible and out of this menu.
+ * @bestPractice Label each column via `columnDef.meta.headerTitle` - the menu falls back to the raw column `id` when it's missing.
+ * @category data
+ */
+declare const DataGridColumnVisibility: <TData extends object>({ table, trigger, }: {
+    /** The TanStack table instance whose column visibility is controlled. */
+    table: Table<TData>;
+    /** Element that opens the menu. */
+    trigger: ReactElement;
+}) => import("react").JSX.Element;
+export { DataGridColumnVisibility };

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

@@ -0,0 +1,25 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuLabel, DropdownMenuTrigger, } from "@instruments/materia-ui/components/dropdown-menu";
+/**
+ * Dropdown of checkbox items that show/hide the hideable columns of a TanStack
+ * Table.
+ *
+ * Only lists columns with an accessor that report `getCanHide()`, labelling
+ * each from `columnDef.meta.headerTitle` (falling back to the column id).
+ * Toggling a column keeps the menu open so several can be flipped at once.
+ *
+ * @bestPractice Pass the TanStack `table` instance directly (this part does NOT read DataGrid context) plus a `trigger` element rendered via `render` - supply your own `Button`, it renders none.
+ * @bestPractice Only accessor columns reporting `getCanHide()` appear; set `enableHiding: false` on a column def to keep it always-visible and out of this menu.
+ * @bestPractice Label each column via `columnDef.meta.headerTitle` - the menu falls back to the raw column `id` when it's missing.
+ * @category data
+ */
+const DataGridColumnVisibility = ({ table, trigger, }) => (_jsxs(DropdownMenu, { "data-component": "data-grid-column-visibility", children: [_jsx(DropdownMenuTrigger, { render: trigger }), _jsxs(DropdownMenuContent, { align: "end", className: "min-w-37.5", children: [_jsx(DropdownMenuLabel, { className: "font-medium", children: "Toggle Columns" }), table.getAllColumns().flatMap((column) => column.accessorFn !== undefined && column.getCanHide()
+                    ? [
+                        _jsx(DropdownMenuCheckboxItem, { checked: column.getIsVisible(), className: "capitalize", onCheckedChange: (value) => {
+                                column.toggleVisibility(value);
+                            }, onSelect: (event) => {
+                                event.preventDefault();
+                            }, children: column.columnDef.meta?.headerTitle ?? column.id }, column.id),
+                    ]
+                    : [])] })] }));
+export { DataGridColumnVisibility };

package/dist/compositions/data-grid-column-visibility.d.ts

@@ -0,0 +1 @@
+export { DataGridColumnVisibility } from "./data-grid-column-visibility/data-grid-column-visibility-root.js";

package/dist/compositions/data-grid-column-visibility.js

@@ -0,0 +1 @@
+export { DataGridColumnVisibility } from "./data-grid-column-visibility/data-grid-column-visibility-root.js";

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

@@ -0,0 +1,62 @@
+import type { ReactNode } from "react";
+interface DataGridPaginationProps {
+    className?: string;
+    /**
+     * Label for the button that jumps past a collapsed page group.
+     * @default "..."
+     */
+    ellipsisText?: string;
+    /**
+     * Range-summary template; `{from}`, `{to}`, and `{count}` are substituted.
+     * @default "{from} - {to} of {count}"
+     */
+    info?: string;
+    /** Placeholder rendered in place of the range summary while loading. */
+    infoSkeleton?: ReactNode;
+    more?: boolean;
+    /**
+     * Number of page buttons shown before collapsing to an ellipsis.
+     * @default 5
+     */
+    moreLimit?: number;
+    /**
+     * Accessible label for the next-page arrow button.
+     * @default "Go to next page"
+     */
+    nextPageLabel?: string;
+    /**
+     * Accessible label for the previous-page arrow button.
+     * @default "Go to previous page"
+     */
+    previousPageLabel?: string;
+    /**
+     * Label preceding the rows-per-page select.
+     * @default "Rows per page"
+     */
+    rowsPerPageLabel?: string;
+    /**
+     * Page-size options offered by the rows-per-page select.
+     * @default [5, 10, 25, 50, 100]
+     */
+    sizes?: number[];
+    /** @default "per page" */
+    sizesDescription?: string;
+    sizesInfo?: string;
+    /** @default "Show" */
+    sizesLabel?: string;
+    /** Placeholder rendered in place of the rows-per-page select while loading. */
+    sizesSkeleton?: ReactNode;
+}
+/**
+ * Pagination footer for a DataGrid: a rows-per-page select, a range summary,
+ * and page navigation. Reads pagination state from the surrounding DataGrid
+ * context, so it must be rendered inside a DataGrid provider whose table has a
+ * pagination row model.
+ *
+ * @bestPractice Render inside a `DataGrid` whose `table` has `paginatedRowModel: createPaginatedRowModel()` wired - it reads `table.state.pagination` from context and throws outside the provider.
+ * @bestPractice For server-side paging, drive the table with `manualPagination` + `pageCount` and a controlled `pagination` state; the range summary uses `recordCount`, so pass the true total, not the page length.
+ * @bestPractice Configure page-size choices via `sizes` (not by restyling the select), and localise the range text through the `info` template.
+ * @category data
+ */
+declare const DataGridPagination: (props: DataGridPaginationProps) => import("react").JSX.Element;
+export { DataGridPagination, type DataGridPaginationProps };

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

@@ -0,0 +1,96 @@
+import { Fragment as _Fragment, 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 { Select, SelectContent, SelectItem, SelectTrigger, SelectValue, } from "@instruments/materia-ui/components/select";
+import { Skeleton } from "@instruments/materia-ui/components/skeleton";
+import { useDataGrid } from "@instruments/materia-ui/compositions/data-grid";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { ChevronLeftIcon, ChevronRightIcon } from "lucide-react";
+const defaultProps = {
+    /** Ellipsis text */
+    ellipsisText: "...",
+    info: "{from} - {to} of {count}",
+    /** Info skeleton */
+    infoSkeleton: _jsx(Skeleton, { className: "h-8 w-60" }),
+    more: false,
+    /** More limit */
+    moreLimit: 5,
+    /** Next page label */
+    nextPageLabel: "Go to next page",
+    /** Previous page label */
+    previousPageLabel: "Go to previous page",
+    /** Rows per page label */
+    rowsPerPageLabel: "Rows per page",
+    /** Component size */
+    sizes: [5, 10, 25, 50, 100],
+    /** Component size */
+    sizesDescription: "per page",
+    /** Component size */
+    sizesLabel: "Show",
+    /** Component size */
+    sizesSkeleton: _jsx(Skeleton, { className: "h-8 w-44" }),
+};
+const BTN_BASE_CLASSES = "size-7 p-0 text-paragraph-sm";
+const BTN_ARROW_CLASSES = `${BTN_BASE_CLASSES} rtl:transform rtl:rotate-180`;
+/** Replace the {from}/{to}/{count} placeholders in the info template. */
+const formatPaginationInfo = (template, from, to, count) => template !== undefined && template !== ""
+    ? template
+        .replace("{from}", from.toString())
+        .replace("{to}", to.toString())
+        .replace("{count}", count.toString())
+    : `${from} - ${to} of ${count}`;
+const RowsPerPageSelect = ({ rowsPerPageLabel, sizes, table, }) => {
+    const { pageSize } = table.state.pagination;
+    return (_jsxs(_Fragment, { children: [_jsx("div", { className: "text-muted-foreground text-paragraph-sm", children: rowsPerPageLabel }), _jsxs(Select, { onValueChange: (value) => {
+                    const newPageSize = Number(value);
+                    table.setPageSize(newPageSize);
+                }, value: `${pageSize}`, children: [_jsx(SelectTrigger, { className: "w-fit", size: "sm", children: _jsx(SelectValue, { placeholder: `${pageSize}` }) }), _jsx(SelectContent, { className: "min-w-12.5", side: "top", children: sizes?.map((size) => (_jsx(SelectItem, { value: `${size}`, children: size }, size))) })] })] }));
+};
+const PaginationNav = ({ ellipsisText, moreLimit, nextPageLabel, previousPageLabel, table, }) => {
+    const { pageIndex } = table.state.pagination;
+    const pageCount = table.getPageCount();
+    if (pageCount <= 1) {
+        return null;
+    }
+    // Determine the start and end of the pagination group
+    const currentGroupStart = Math.floor(pageIndex / moreLimit) * moreLimit;
+    const currentGroupEnd = Math.min(currentGroupStart + moreLimit, pageCount);
+    // Page indices for the current group
+    const pageIndices = Array.from({ length: Math.max(0, currentGroupEnd - currentGroupStart) }, (_, idx) => currentGroupStart + idx);
+    return (_jsxs(Flex, { align: "center", className: "order-1 space-x-1 sm:order-2", children: [_jsx(Button, { "aria-label": previousPageLabel, emphasis: "ghost", className: BTN_ARROW_CLASSES, disabled: !table.getCanPreviousPage(), icon: ChevronLeftIcon, onClick: () => {
+                    table.previousPage();
+                }, size: "icon-sm" }), currentGroupStart > 0 && (_jsx(Button, { emphasis: "ghost", className: BTN_BASE_CLASSES, onClick: () => {
+                    table.setPageIndex(currentGroupStart - 1);
+                }, size: "sm", children: ellipsisText })), pageIndices.map((i) => (_jsx(Button, { emphasis: "ghost", className: cn(BTN_BASE_CLASSES, "text-muted-foreground", {
+                    "bg-accent text-accent-foreground": pageIndex === i,
+                }), onClick: () => {
+                    if (pageIndex !== i) {
+                        table.setPageIndex(i);
+                    }
+                }, size: "sm", children: i + 1 }, `page-${i + 1}`))), currentGroupEnd < pageCount && (_jsx(Button, { emphasis: "ghost", className: BTN_BASE_CLASSES, onClick: () => {
+                    table.setPageIndex(currentGroupEnd);
+                }, size: "sm", children: ellipsisText })), _jsx(Button, { "aria-label": nextPageLabel, emphasis: "ghost", className: BTN_ARROW_CLASSES, disabled: !table.getCanNextPage(), icon: ChevronRightIcon, onClick: () => {
+                    table.nextPage();
+                }, size: "icon-sm" })] }));
+};
+/**
+ * Pagination footer for a DataGrid: a rows-per-page select, a range summary,
+ * and page navigation. Reads pagination state from the surrounding DataGrid
+ * context, so it must be rendered inside a DataGrid provider whose table has a
+ * pagination row model.
+ *
+ * @bestPractice Render inside a `DataGrid` whose `table` has `paginatedRowModel: createPaginatedRowModel()` wired - it reads `table.state.pagination` from context and throws outside the provider.
+ * @bestPractice For server-side paging, drive the table with `manualPagination` + `pageCount` and a controlled `pagination` state; the range summary uses `recordCount`, so pass the true total, not the page length.
+ * @bestPractice Configure page-size choices via `sizes` (not by restyling the select), and localise the range text through the `info` template.
+ * @category data
+ */
+const DataGridPagination = (props) => {
+    const { table, recordCount, loading } = useDataGrid();
+    const mergedProps = { ...defaultProps, ...props };
+    const { pageIndex, pageSize } = table.state.pagination;
+    const from = pageIndex * pageSize + 1;
+    const to = Math.min((pageIndex + 1) * pageSize, recordCount);
+    const paginationInfo = formatPaginationInfo(mergedProps.info, from, to, recordCount);
+    return (_jsxs(Flex, { align: "center", className: cn("grow gap-2.5 py-2.5 sm:flex-row sm:py-0", mergedProps?.className), "data-component": "data-grid-pagination", "data-slot": "data-grid-pagination", direction: "column", justify: "space-between", wrap: "wrap", children: [_jsx(Flex, { align: "center", className: "order-2 space-x-2.5 pb-2.5 sm:order-1 sm:pb-0", wrap: "wrap", children: loading === true ? (mergedProps?.sizesSkeleton) : (_jsx(RowsPerPageSelect, { rowsPerPageLabel: mergedProps.rowsPerPageLabel, sizes: mergedProps.sizes, table: table })) }), _jsx(Flex, { align: "center", className: "order-1 gap-2.5 pt-2.5 sm:order-2 sm:flex-row sm:justify-end sm:pt-0", direction: "column", justify: "center", children: loading === true ? (mergedProps?.infoSkeleton) : (_jsxs(_Fragment, { children: [_jsx("div", { className: "text-muted-foreground text-paragraph-sm order-2 text-nowrap sm:order-1", children: paginationInfo }), _jsx(PaginationNav, { ellipsisText: mergedProps.ellipsisText, moreLimit: mergedProps?.moreLimit ?? 5, nextPageLabel: mergedProps.nextPageLabel, previousPageLabel: mergedProps.previousPageLabel, table: table })] })) })] }));
+};
+export { DataGridPagination };

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

@@ -0,0 +1,2 @@
+export type { DataGridPaginationProps } from "./data-grid-pagination/data-grid-pagination-root.js";
+export { DataGridPagination } from "./data-grid-pagination/data-grid-pagination-root.js";