@facetui/react 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,367 @@
+import * as react from 'react';
+import { ReactNode, CSSProperties } from 'react';
+
+type SortDirection = "asc" | "desc" | false;
+type AccessorFn<TData> = (row: TData) => unknown;
+type RowSelectionState = Record<string, boolean>;
+interface HeaderContext<TData> {
+    column: RuntimeColumn<TData>;
+    table: TableInstance<TData>;
+}
+interface CellContext<TData> {
+    row: Row<TData>;
+    column: RuntimeColumn<TData>;
+    /** Pre-extracted cell value via accessorKey / accessorFn */
+    value: unknown;
+    table: TableInstance<TData>;
+}
+interface ColumnDef<TData> {
+    /** Must be unique across all columns. Used as sort key, visibility key, etc. */
+    id: string;
+    /** Header content. Pass a string or a render function for custom headers. */
+    header: ReactNode | ((ctx: HeaderContext<TData>) => ReactNode);
+    /**
+     * Simple key-based accessor. Provide either this or `accessorFn`, not both.
+     * TypeScript will infer the value type from the key.
+     */
+    accessorKey?: keyof TData;
+    /**
+     * Function-based accessor for computed or nested values.
+     * @example accessorFn: (row) => `${row.firstName} ${row.lastName}`
+     */
+    accessorFn?: AccessorFn<TData>;
+    /**
+     * Custom cell renderer. If omitted, the raw value is rendered as a string.
+     * @example cell: ({ value }) => <Badge>{String(value)}</Badge>
+     */
+    cell?: (ctx: CellContext<TData>) => ReactNode;
+    enableSorting?: boolean;
+    enableHiding?: boolean;
+    enableResizing?: boolean;
+    /** Initial pixel width. Respected as a CSS width on the <th>/<td>. */
+    size?: number;
+    minSize?: number;
+    maxSize?: number;
+    /** Arbitrary metadata — useful for passing flags into custom renderers */
+    meta?: Record<string, unknown>;
+}
+interface Row<TData> {
+    /** Stable string identifier (from getRowId or the row's array index) */
+    id: string;
+    /** The original data item */
+    original: TData;
+    /** Position within the current page */
+    index: number;
+    getIsSelected: () => boolean;
+    /** False when `enableRowSelection` is a predicate function that rejects this row */
+    getCanSelect: () => boolean;
+    toggleSelected: (value?: boolean) => void;
+}
+interface RuntimeColumn<TData> extends ColumnDef<TData> {
+    getIsSorted: () => SortDirection;
+    toggleSort: (multiSort?: boolean) => void;
+    getIsVisible: () => boolean;
+    toggleVisibility: (value?: boolean) => void;
+    getSize: () => number;
+}
+interface PaginationState {
+    pageIndex: number;
+    pageSize: number;
+}
+interface PaginationOptions {
+    /**
+     * Set true when pagination is handled server-side.
+     * When true, the component will NOT slice `data` — it renders whatever you pass.
+     * You MUST also provide `rowCount` so the page count can be calculated.
+     */
+    manualPagination?: boolean;
+    /** Total number of rows across all pages. Required when manualPagination=true. */
+    rowCount?: number;
+    pageSizeOptions?: number[];
+    onPaginationChange?: (state: PaginationState) => void;
+}
+interface SortingState {
+    id: string;
+    desc: boolean;
+}
+interface SortingOptions {
+    /** Set true when sorting is handled server-side. */
+    manualSorting?: boolean;
+    enableMultiSort?: boolean;
+    onSortingChange?: (state: SortingState[]) => void;
+}
+interface ColumnFilter {
+    id: string;
+    value: unknown;
+}
+type ColumnFiltersState = ColumnFilter[];
+interface FilteringOptions {
+    /** Set true when filtering is handled server-side. */
+    manualFiltering?: boolean;
+    /** Controlled global filter value. Pass to sync with external state. */
+    globalFilter?: string;
+    onGlobalFilterChange?: (value: string) => void;
+    /**
+     * Controlled per-column filter values. Uncontrolled state is used when omitted.
+     * Applied as a case-insensitive substring match, ANDed across all entries.
+     */
+    columnFilters?: ColumnFiltersState;
+    onColumnFiltersChange?: (filters: ColumnFiltersState) => void;
+}
+interface RowSelectionOptions<TData> {
+    /**
+     * true/undefined → checkbox column is injected, all rows selectable
+     * false          → row selection disabled entirely (no checkbox column)
+     * fn             → checkbox column is injected; fn decides per-row eligibility
+     */
+    enableRowSelection?: boolean | ((row: Row<TData>) => boolean);
+    enableMultiRowSelection?: boolean;
+    onRowSelectionChange?: (state: RowSelectionState) => void;
+}
+interface RenderSlots<TData> {
+    /** Replaces the entire toolbar. Receives the live table instance. */
+    renderToolbar?: (table: TableInstance<TData>) => ReactNode;
+    /** Replaces the default empty state illustration. */
+    renderEmpty?: () => ReactNode;
+    /** Replaces the loading overlay. */
+    renderLoading?: () => ReactNode;
+    /**
+     * Wraps each <tr>. Useful for making rows into <Link> elements.
+     * @example renderRowWrapper={(row, children) => <Link href={`/users/${row.id}`}>{children}</Link>}
+     */
+    renderRowWrapper?: (row: Row<TData>, children: ReactNode) => ReactNode;
+}
+interface ClassNameOverrides {
+    root?: string;
+    table?: string;
+    thead?: string;
+    theadRow?: string;
+    th?: string;
+    tbody?: string;
+    tr?: string;
+    td?: string;
+    pagination?: string;
+    toolbar?: string;
+}
+interface DataTableProps<TData> extends PaginationOptions, SortingOptions, FilteringOptions, RowSelectionOptions<TData>, RenderSlots<TData> {
+    data: TData[];
+    columns: ColumnDef<TData>[];
+    /** Derive a stable row id from the row's data. Defaults to array index. */
+    getRowId?: (row: TData, index: number) => string;
+    isLoading?: boolean;
+    /** Visual density preset. Controls cell padding. */
+    density?: "compact" | "default" | "comfortable";
+    classNames?: ClassNameOverrides;
+    style?: CSSProperties;
+    "aria-label"?: string;
+    "aria-describedby"?: string;
+}
+interface TableInstance<TData> {
+    rows: Row<TData>[];
+    columns: RuntimeColumn<TData>[];
+    pagination: PaginationState;
+    sorting: SortingState[];
+    rowSelection: RowSelectionState;
+    globalFilter: string;
+    columnFilters: ColumnFiltersState;
+    pageCount: number;
+    getIsAllRowsSelected: () => boolean;
+    getIsSomeRowsSelected: () => boolean;
+    toggleAllRowsSelected: (value?: boolean) => void;
+    setSorting: (updater: SortingState[] | ((prev: SortingState[]) => SortingState[])) => void;
+    setPagination: (updater: PaginationState | ((prev: PaginationState) => PaginationState)) => void;
+    setGlobalFilter: (value: string) => void;
+    setColumnFilters: (updater: ColumnFiltersState | ((prev: ColumnFiltersState) => ColumnFiltersState)) => void;
+    /** Total row count after filtering — useful for status text */
+    filteredRowCount: number;
+}
+
+/**
+ * <DataTable> — batteries-included composed component.
+ *
+ * For full layout control, export the individual primitives and
+ * `useDataTable` from the barrel and assemble them yourself.
+ *
+ * @example
+ * <DataTable
+ *   data={users}
+ *   columns={columns}
+ *   aria-label="Users table"
+ *   enableRowSelection
+ *   pageSizeOptions={[10, 20, 50]}
+ * />
+ */
+declare function DataTable<TData>({ renderToolbar, renderEmpty, renderLoading, renderRowWrapper, isLoading, density, classNames, style, "aria-label": ariaLabel, "aria-describedby": ariaDescribedBy, ...rest }: DataTableProps<TData>): react.JSX.Element;
+
+interface DataTableHeaderProps<TData> {
+    table: TableInstance<TData>;
+    density: "compact" | "default" | "comfortable";
+    classNames?: ClassNameOverrides;
+}
+/**
+ * Renders <thead> with sortable column headers.
+ * Each sortable header uses a <button> so keyboard users can trigger sorts.
+ * A select-all checkbox is prepended when row selection is enabled.
+ */
+declare function DataTableHeader<TData>({ table, density, classNames, }: DataTableHeaderProps<TData>): react.JSX.Element;
+
+interface DataTableBodyProps<TData> {
+    table: TableInstance<TData>;
+    density: "compact" | "default" | "comfortable";
+    isLoading: boolean;
+    renderEmpty?: () => ReactNode;
+    renderRowWrapper?: (row: Row<TData>, children: ReactNode) => ReactNode;
+    classNames?: ClassNameOverrides;
+}
+/**
+ * Renders <tbody> with data rows, empty state, and per-cell value resolution.
+ * Each row's checkbox uses Radix Checkbox for full keyboard and ARIA support.
+ */
+declare function DataTableBody<TData>({ table, density, isLoading, renderEmpty, renderRowWrapper, classNames, }: DataTableBodyProps<TData>): react.JSX.Element;
+
+interface DataTableToolbarProps<TData> {
+    table: TableInstance<TData>;
+    classNames?: ClassNameOverrides;
+}
+/**
+ * Default toolbar: global search input on the left, column-toggle on the right.
+ * Replace entirely via the `renderToolbar` prop on <DataTable>.
+ */
+declare function DataTableToolbar<TData>({ table, classNames, }: DataTableToolbarProps<TData>): react.JSX.Element;
+
+interface DataTableColumnToggleProps<TData> {
+    table: TableInstance<TData>;
+}
+/**
+ * Column visibility toggle built on react-aria-components `Menu` with
+ * `selectionMode="multiple"` — each item is a `menuitemcheckbox`, fully
+ * keyboard-navigable and screen-reader annotated.
+ */
+declare function DataTableColumnToggle<TData>({ table, }: DataTableColumnToggleProps<TData>): react.JSX.Element;
+
+interface DataTablePaginationProps<TData> {
+    table: TableInstance<TData>;
+    pageSizeOptions: number[];
+    classNames?: ClassNameOverrides;
+}
+/**
+ * Pagination bar with:
+ *   - Selected-row count (when row selection is active)
+ *   - "Rows per page" selector via Radix Select
+ *   - Current page info + navigation buttons
+ *
+ * All buttons carry descriptive aria-labels and are disabled when the
+ * action is unavailable, preventing screen-reader confusion.
+ */
+declare function DataTablePagination<TData>({ table, pageSizeOptions, classNames, }: DataTablePaginationProps<TData>): react.JSX.Element;
+
+/**
+ * Core headless hook. Wraps a TanStack Table instance and adapts it to
+ * FacetUI's `TableInstance` contract, which both the composed <DataTable> and
+ * the individual primitives consume via context.
+ *
+ * TanStack Table owns the state machine and the filter → sort → paginate →
+ * select pipeline. This hook owns:
+ *   - the FacetUI-shaped public API (stable regardless of the engine)
+ *   - the auto-injected checkbox column
+ *   - the controlled-or-observable state pattern:
+ *       · internal state drives the UI by default
+ *       · an `onChange` callback makes a feature observable without handing
+ *         ownership to the caller
+ *       · passing the feature's prop (e.g. `globalFilter`) AND its `onChange`
+ *         makes it fully controlled
+ */
+declare function useDataTable<TData>(props: DataTableProps<TData>): TableInstance<TData>;
+
+/**
+ * Access the nearest DataTable's live instance from any primitive component.
+ * Throws if called outside a <DataTable> tree.
+ */
+declare function useDataTableContext<TData>(): TableInstance<TData>;
+
+interface UseColumnSortOptions {
+    enableMultiSort?: boolean;
+    onSortingChange?: (state: SortingState[]) => void;
+}
+interface UseColumnSortReturn {
+    sorting: SortingState[];
+    setSorting: (updater: SortingState[] | ((prev: SortingState[]) => SortingState[])) => void;
+    /** Cycle a single column through: none → asc → desc → none */
+    toggleSort: (columnId: string, multiSort?: boolean) => void;
+    clearSort: () => void;
+}
+/**
+ * Standalone sort state hook. Use directly when building a custom table layout
+ * that doesn't use the full <DataTable> component.
+ */
+declare function useColumnSort({ enableMultiSort, onSortingChange, }?: UseColumnSortOptions): UseColumnSortReturn;
+
+interface UsePaginationOptions {
+    initialPageSize?: number;
+    onPaginationChange?: (state: PaginationState) => void;
+}
+interface UsePaginationReturn {
+    pagination: PaginationState;
+    setPagination: (updater: PaginationState | ((prev: PaginationState) => PaginationState)) => void;
+    goToPage: (pageIndex: number) => void;
+    goToFirstPage: () => void;
+    goToLastPage: (pageCount: number) => void;
+    nextPage: () => void;
+    previousPage: () => void;
+    setPageSize: (size: number) => void;
+}
+/**
+ * Standalone pagination state hook. Safe to use outside <DataTable> when
+ * only a subset of table behaviour is needed.
+ */
+declare function usePagination({ initialPageSize, onPaginationChange, }?: UsePaginationOptions): UsePaginationReturn;
+
+interface UseRowSelectionOptions {
+    enableMultiRowSelection?: boolean;
+    onRowSelectionChange?: (state: RowSelectionState) => void;
+}
+interface UseRowSelectionReturn {
+    rowSelection: RowSelectionState;
+    setRowSelection: (state: RowSelectionState) => void;
+    toggleRow: (rowId: string, value?: boolean) => void;
+    toggleAllRows: (rows: Row<unknown>[], value?: boolean) => void;
+    clearSelection: () => void;
+    isSelected: (rowId: string) => boolean;
+    selectedCount: number;
+}
+/**
+ * Standalone row-selection hook. Use when building a custom table layout
+ * without the full <DataTable> component.
+ */
+declare function useRowSelection({ enableMultiRowSelection, onRowSelectionChange, }?: UseRowSelectionOptions): UseRowSelectionReturn;
+
+interface UseColumnVisibilityReturn {
+    columnVisibility: Record<string, boolean>;
+    isVisible: (columnId: string) => boolean;
+    toggleColumn: (columnId: string, value?: boolean) => void;
+    showAll: () => void;
+    hideAll: (hideableIds: string[]) => void;
+}
+/**
+ * Standalone column-visibility hook. Initialises all columns to visible.
+ * Respects the `enableHiding: false` guard on individual ColumnDefs — when you
+ * call hideAll, pass only the ids where enableHiding !== false.
+ */
+declare function useColumnVisibility<TData>(columns: ColumnDef<TData>[]): UseColumnVisibilityReturn;
+
+interface UseGlobalFilterOptions {
+    onGlobalFilterChange?: (value: string) => void;
+}
+interface UseGlobalFilterReturn<TData> {
+    globalFilter: string;
+    setGlobalFilter: (value: string) => void;
+    /** Apply the current filter against any dataset client-side */
+    filterData: (data: TData[]) => TData[];
+}
+/**
+ * Standalone global-filter hook. The filter is applied as a case-insensitive
+ * substring match against all accessible column values.
+ */
+declare function useGlobalFilter<TData>(columns: ColumnDef<TData>[], { onGlobalFilterChange }?: UseGlobalFilterOptions): UseGlobalFilterReturn<TData>;
+
+export { type AccessorFn, type CellContext, type ClassNameOverrides, type ColumnDef, type ColumnFilter, type ColumnFiltersState, DataTable, DataTableBody, DataTableColumnToggle, DataTableHeader, DataTablePagination, type DataTableProps, DataTableToolbar, type FilteringOptions, type HeaderContext, type PaginationOptions, type PaginationState, type RenderSlots, type Row, type RowSelectionOptions, type RowSelectionState, type RuntimeColumn, type SortDirection, type SortingOptions, type SortingState, type TableInstance, useColumnSort, useColumnVisibility, useDataTable, useDataTableContext, useGlobalFilter, usePagination, useRowSelection };