@elabs-ai/components-data 4.0.0 → 4.2.0

package/README.md

@@ -6,15 +6,14 @@
 > TanStack DataTable, FilterBar, SearchInput, FacetFilter, ColumnPicker.
 
 Part of **brand-ui**, a source-owned, token-driven React component system.
-These packages are **private** and are not published to any registry — they are
-consumed from this workspace. See `docs/CONSUMING.md`.
+Published to the **public npm registry** under the `@elabs-ai` scope — it
+installs like any other npm dependency, with no registry configuration and
+no token required. See `docs/CONSUMING.md`.
 
 ## Install
 
-Inside this monorepo the packages resolve as workspace dependencies:
-
-```json
-"@elabs-ai/components-data": "workspace:*"
+```bash
+pnpm add @elabs-ai/components-tokens @elabs-ai/components-data
 ```
 
 ## Set up styling (do not skip)
@@ -39,7 +38,7 @@ import { ThemeProvider } from "@elabs-ai/components-tokens";
 
 ## What's in it
 
-5 exported components — including `ColumnPicker`, `DataTable`, `FacetFilter`, `FilterBar`, `SearchInput`.
+6 exported components — including `ColumnPicker`, `DataTable`, `FacetFilter`, `FilterBar`, `FilterChip`.
 
 Don't guess the API — ask the CLI:
 
@@ -69,6 +68,6 @@ prompt for migrating an existing project: `docs/CONSUMING.md`.
 
 ## License
 
-UNLICENSED — private.
+MIT
 
 <!-- brand-ui:gen:readme:end -->

package/dist/index.d.ts

@@ -1,8 +1,30 @@
 import * as react from 'react';
 import { ReactNode, InputHTMLAttributes, ButtonHTMLAttributes, Ref, ReactElement } from 'react';
-import { ColumnDef, Table, SortingState, OnChangeFn, VisibilityState, ColumnFiltersState, PaginationState, ColumnPinningState, Row } from '@tanstack/react-table';
-export { CellContext, ColumnDef, ColumnPinningState, Row, Table } from '@tanstack/react-table';
+import { RowData, ColumnDef, Table, SortingState, OnChangeFn, VisibilityState, ColumnFiltersState, PaginationState, ColumnPinningState, ColumnSizingState, RowSelectionState, Row } from '@tanstack/react-table';
+export { CellContext, ColumnDef, ColumnMeta, ColumnPinningState, ColumnSizingState, Row, RowSelectionState, Table } from '@tanstack/react-table';
+import { FilterChipProps as FilterChipProps$1 } from '@elabs-ai/components-ui';
 
+/**
+ * `DataTable`'s `columnDef.meta` contract, read by the header/body/skeleton
+ * cell renderers. Set `numeric: true` on a column to get `tabular-nums` +
+ * end-alignment on both the `<th>` and every `<td>` (including the loading
+ * skeleton) for free.
+ */
+interface DataTableColumnMeta {
+    /** Numeric column: tabular figures + end alignment on header and cells. */
+    numeric?: boolean;
+    /**
+     * Explicit alignment override for when `numeric` isn't the right cue (or
+     * to align a non-numeric column). Independent of `numeric` — `numeric`
+     * alone still drives `tabular-nums` even when `align` overrides the
+     * alignment away from `"end"`.
+     */
+    align?: "start" | "center" | "end";
+}
+declare module "@tanstack/react-table" {
+    interface ColumnMeta<TData extends RowData, TValue> extends DataTableColumnMeta {
+    }
+}
 /** Snapshot of table slice state — used for saved-view serialise/rehydrate. */
 interface DataTableViewState {
     sorting: SortingState;
@@ -16,6 +38,17 @@ interface DataTableViewState {
      * that already constructs a `DataTableViewState` literal.
      */
     columnPinning?: ColumnPinningState;
+    /**
+     * Which rows are checked (#11), keyed by row id — see `getRowId`. OPTIONAL
+     * like `columnPinning`, for the same reason: the other members predate it.
+     */
+    rowSelection?: RowSelectionState;
+    /**
+     * Per-column widths after resizing (#12), keyed by column id. OPTIONAL like
+     * `columnPinning`/`rowSelection`, for the same reason: the other members
+     * predate it.
+     */
+    columnSizing?: ColumnSizingState;
 }
 /**
  * Argument object fired by `onServerChange` whenever a manual slice changes.
@@ -93,6 +126,81 @@ interface DataTableProps<TData, TValue> extends Omit<React.HTMLAttributes<HTMLDi
      */
     columnPinning?: ColumnPinningState;
     onColumnPinningChange?: OnChangeFn<ColumnPinningState>;
+    /**
+     * Opt in to column resizing (#12): a drag handle renders on every
+     * resizable column's trailing edge — pointer-draggable (TanStack's own
+     * `header.getResizeHandler()`) and keyboard-operable (ArrowLeft/ArrowRight
+     * on the focused handle, per the WAI-ARIA separator-as-slider practice).
+     * Default `false` so a table that doesn't opt in renders byte-identical
+     * markup to before this feature existed — no handle, no per-cell width
+     * styling.
+     */
+    enableColumnResizing?: boolean;
+    /**
+     * When `columnSizing` updates: `"onChange"` (default here — TanStack's own
+     * default is `"onEnd"`) live-updates while dragging; `"onEnd"` updates once
+     * on release. Only meaningful when `enableColumnResizing` is set.
+     */
+    columnResizeMode?: "onChange" | "onEnd";
+    /**
+     * Controlled column-widths state (#12), keyed by column id — the SAME
+     * controlled/uncontrolled shape as `columnPinning`/`rowSelection`.
+     * Uncontrolled sizing can be seeded once via `initialView.columnSizing`.
+     *
+     * A pinned column's sticky offset (`getStart("left")`/`getAfter("right")`)
+     * already sums `column.getSize()`, which folds in a `columnSizing`
+     * override automatically — so pinning and resizing compose with no extra
+     * wiring once this state reaches the table.
+     *
+     * Sizing is a LAYOUT concern, like `columnPinning`/`rowSelection` — it is
+     * client-only and never joins `DataTableServerArgs` / `onServerChange`.
+     */
+    columnSizing?: ColumnSizingState;
+    onColumnSizingChange?: OnChangeFn<ColumnSizingState>;
+    /**
+     * Controlled row-selection state (#11) — which rows are checked, keyed by
+     * row id (see `getRowId`). When provided the component is
+     * selection-controlled; otherwise it manages the slice internally and can
+     * be seeded once via `initialView.rowSelection`. Pair it with a selection
+     * column built by `createSelectionColumn` (or drive it yourself off the
+     * `table` instance handed to `toolbar`).
+     *
+     * Selection is a LAYOUT/UI concern, not a query concern — like
+     * `columnPinning`, it is client-only and never joins `DataTableServerArgs` /
+     * `onServerChange`.
+     */
+    rowSelection?: RowSelectionState;
+    onRowSelectionChange?: OnChangeFn<RowSelectionState>;
+    /**
+     * Which rows can be selected: `true`/`false` for all rows, or a predicate
+     * evaluated per row. Passed straight through to `useReactTable`. Default
+     * (TanStack's own): `true`.
+     */
+    enableRowSelection?: boolean | ((row: Row<TData>) => boolean);
+    /**
+     * Allow more than one row to be selected at once. Default (TanStack's own):
+     * `true`. Set `false` for single-select (radio-style) behaviour.
+     */
+    enableMultiRowSelection?: boolean;
+    /**
+     * Stable row id, independent of row INDEX. TanStack's default id is set
+     * ONCE per row object when the core row model is built, then reused by
+     * reference through sorting/filtering — so a client-side sort or filter
+     * does NOT disturb selection identity even without this prop. The real
+     * hazard is a `data` array replacement: when the app passes NEW object
+     * references (a re-fetch, an optimistic update), TanStack rebuilds the
+     * core row model from scratch and reassigns default (index-based) ids, so a
+     * row that kept its position but got a new object still keeps its
+     * selection — but one that MOVED position silently inherits whatever
+     * selection belonged to the id now sitting at its old index. This is
+     * unavoidable under `manualPagination`: each page IS a fresh `data` array,
+     * so the default index-based id restarts at `0` on every page and a
+     * selection made on one page can collide with a different record on the
+     * next. Supply `getRowId` whenever `data` can be replaced with new object
+     * references (including every server-paginated table) so identity survives
+     * the replacement instead of falling back to index.
+     */
+    getRowId?: (row: TData, index: number) => string;
     /**
      * One-shot rehydrate for uncontrolled slices only (ignored for any slice
      * whose corresponding controlled prop is set). Maps to `useReactTable`'s
@@ -158,6 +266,51 @@ interface DataTableProps<TData, TValue> extends Omit<React.HTMLAttributes<HTMLDi
      * (a `border-border-strong` divider between rows, no stripes).
      */
     zebra?: boolean;
+    /**
+     * Draw a quiet `--rule` hairline between columns (header and body). Off by
+     * default. Pinned cells keep their own seam and never take a divider.
+     */
+    columnDividers?: boolean;
+    /**
+     * Opt-in row drag-reorder. Off by default — an existing table renders
+     * byte-identical markup with no extra DOM per row until this is set.
+     * Fully controlled like every other slice: the component never mutates
+     * `data` itself, it only reports the move via `onRowReorder`; the caller
+     * re-orders `data` in response.
+     *
+     * Keyboard-operable out of the box (`@dnd-kit`'s default keyboard sensor):
+     * Space/Enter picks a row up, Arrow Up/Down moves it, Space/Enter drops it,
+     * Escape cancels. Every position change is announced through a live region
+     * (WCAG 4.1.3).
+     *
+     * Mutually exclusive with `enableRowVirtualization` — a windowed table
+     * can't keep dnd-kit's sortable list and a virtualizer in sync, so reorder
+     * is silently disabled (a dev warning fires) when both are set. Combining
+     * it with active `sorting` also fires a dev warning (both still work, but
+     * a sort re-orders the very rows a drag just moved, which reads as broken).
+     */
+    enableRowReorder?: boolean;
+    /**
+     * Fires when a row is dropped in a new position. `from`/`to` are indices
+     * into the **`data` array you passed in** — never into the sorted, filtered
+     * or paginated view the table renders — so they are safe to use directly
+     * with `arrayMove`/`slice`+`splice`/immer against your own `data`, unchanged
+     * by an active sort or by client-side pagination (the dragged row's true
+     * index in the full array, not its index on the current page). Under
+     * `manualPagination`, `data` IS the current page, so `from`/`to` are
+     * page-relative — reorder that page's own array with them. `row` is the
+     * moved record (`data[from]`).
+     */
+    onRowReorder?: (from: number, to: number, row: TData) => void;
+    /**
+     * Where the drag activator lives. `"cell"` (default) renders a dedicated
+     * grip-handle column so the rest of the row keeps its ordinary click/
+     * keyboard behavior untouched. `"row"` makes the whole row itself the drag
+     * activator (no extra column) — reach for this only when the row has no
+     * other primary interaction (e.g. no `onRowClick`), since a whole-row
+     * activator and a row click target the same surface.
+     */
+    rowReorderHandle?: "cell" | "row";
     /**
      * Fires when a row is activated (#337). Setting it adds ONE activation
      * target per row: a visually-hidden `<button>` rendered inside the row's
@@ -198,6 +351,19 @@ interface DataTableProps<TData, TValue> extends Omit<React.HTMLAttributes<HTMLDi
     emptyMessage?: ReactNode;
     className?: string;
 }
+/**
+ * Ready-made checkbox selection column (#11): header select-all (with a real
+ * `indeterminate` state for a partial page selection) + a per-row checkbox,
+ * both built on `@elabs-ai/components-ui`'s `Checkbox` — never hand-roll one.
+ *
+ * Add it to `columns` and pair it with `rowSelection` / `onRowSelectionChange`
+ * (or leave both uncontrolled and read `table.getSelectedRowModel()` from a
+ * `toolbar` render-prop to build a bulk-action bar).
+ *
+ * Declares an explicit `size` (40px) so it plays nicely if a caller pins it —
+ * every pinned column must declare one (#333) — without the dev warning.
+ */
+declare function createSelectionColumn<TData>(): ColumnDef<TData>;
 declare const DataTableWithRef: <TData, TValue>(props: DataTableProps<TData, TValue> & {
     ref?: React.Ref<HTMLDivElement>;
 }) => React.ReactElement | null;
@@ -205,7 +371,7 @@ declare const DataTableWithRef: <TData, TValue>(props: DataTableProps<TData, TVa
 interface SearchInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "onChange" | "value"> {
     value: string;
     onValueChange: (value: string) => void;
-    /** Visually-hidden accessible label. Defaults to "Search". */
+    /** Visually-hidden accessible label. Defaults to the localized "Search" microcopy. */
     label?: string;
     containerClassName?: string;
 }
@@ -218,7 +384,7 @@ interface SearchInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "
  * `<Input>` explicitly AND gates the clear button — while disabled the clear
  * affordance is hidden so it can't mutate the filter mid-request (#269/#8).
  */
-declare function SearchInput({ value, onValueChange, label, placeholder, className, containerClassName, disabled, ...props }: SearchInputProps): react.JSX.Element;
+declare const SearchInput: react.ForwardRefExoticComponent<SearchInputProps & react.RefAttributes<HTMLInputElement>>;
 
 interface FilterBarProps {
     /** Left cluster: search + facet filters. */
@@ -230,6 +396,34 @@ interface FilterBarProps {
 /** Horizontal toolbar that groups table filters and actions. */
 declare function FilterBar({ children, actions, className }: FilterBarProps): react.JSX.Element;
 
+interface FilterChipProps extends Omit<FilterChipProps$1, "label" | "trailing"> {
+    /**
+     * Label-in-value text — `"Status: Failed"`, never `"Status = failed"` and
+     * never a bare `"Failed"`. Same contract as the base `FilterChip`.
+     */
+    label: string;
+    /**
+     * How many records this active filter excluded (or matched) — rendered as a
+     * secondary, locale-formatted segment alongside `label`. Omit for a bare
+     * chip with no count.
+     */
+    count?: number;
+    /**
+     * The word placed before the formatted count, e.g. `"excluded"` →
+     * `"excluded 1,204"`. Omitted by default: a bare `count` renders as just the
+     * formatted number.
+     */
+    countLabel?: string;
+}
+/**
+ * A removable active-filter chip with an optional secondary count.
+ *
+ * `onRemove` stays REQUIRED (inherited from the base `FilterChip`, diverging
+ * from this item's spec draft) — the whole chip IS the remove control, so a
+ * chip with no removal affordance is a plain `Badge`, not this component.
+ */
+declare const FilterChip: react.ForwardRefExoticComponent<FilterChipProps & react.RefAttributes<HTMLButtonElement>>;
+
 interface FacetOption {
     label: string;
     value: string;
@@ -290,4 +484,4 @@ declare function toCsv<TData extends Record<string, unknown>>(rows: TData[], opt
  */
 declare function downloadCsv<TData extends Record<string, unknown>>(rows: TData[], opts?: DownloadCsvOptions<TData>): void;
 
-export { ColumnPicker, type ColumnPickerProps, type CsvColumn, DataTableWithRef as DataTable, type DataTableProps, type DataTableRowClickHandler, type DataTableServerArgs, type DataTableViewState, type DownloadCsvOptions, FacetFilter, type FacetFilterProps, type FacetOption, FilterBar, type FilterBarProps, SearchInput, type SearchInputProps, type ToCsvOptions, downloadCsv, toCsv };
+export { ColumnPicker, type ColumnPickerProps, type CsvColumn, DataTableWithRef as DataTable, type DataTableColumnMeta, type DataTableProps, type DataTableRowClickHandler, type DataTableServerArgs, type DataTableViewState, type DownloadCsvOptions, FacetFilter, type FacetFilterProps, type FacetOption, FilterBar, type FilterBarProps, FilterChip, type FilterChipProps, SearchInput, type SearchInputProps, type ToCsvOptions, createSelectionColumn, downloadCsv, toCsv };