@elabs-ai/components-data 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manuel Reimitz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+<!-- brand-ui:gen:readme:start -->
+<!-- Generated by scripts/gen-package-readmes.mjs — do not edit inside these markers. -->
+
+# `@elabs-ai/components-data`
+
+> 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`.
+
+## Install
+
+Inside this monorepo the packages resolve as workspace dependencies:
+
+```json
+"@elabs-ai/components-data": "workspace:*"
+```
+
+## Set up styling (do not skip)
+
+Components are Tailwind v4 classes backed by semantic tokens. Two lines in
+your CSS entry, or **everything renders unstyled** — the single most common
+mistake:
+
+```css
+@import "@elabs-ai/components-tokens/styles.css";
+@source "../node_modules/@elabs-ai/components-data/dist";
+```
+
+The `@source` line is required because Tailwind ignores `node_modules`. Add
+one per brand-ui package you render. Then wrap your app once:
+
+```tsx
+import { ThemeProvider } from "@elabs-ai/components-tokens";
+
+<ThemeProvider defaultTheme="light">{children}</ThemeProvider>;
+```
+
+## What's in it
+
+5 exported components — including `ColumnPicker`, `DataTable`, `FacetFilter`, `FilterBar`, `SearchInput`.
+
+Don't guess the API — ask the CLI:
+
+```bash
+pnpm add -D @elabs-ai/components-cli
+pnpm exec brand-ui search <query>   # find a component
+pnpm exec brand-ui docs <Name>      # its real props, from source
+```
+
+## Using an AI coding agent?
+
+For Claude Code, install the plugin from this repo's checkout:
+
+```
+/plugin marketplace add .
+/plugin install brand-ui
+```
+
+`brand-ui docs <Name>` returns intent, composition, state→token mappings and
+anti-patterns — tell your agent to run it instead of guessing a prop. The CLI
+also runs as an MCP server (`brand-ui mcp`).
+
+## Full guide
+
+Tailwind and Next.js wiring, per-package extras, agent enablement and a
+prompt for migrating an existing project: `docs/CONSUMING.md`.
+
+## License
+
+UNLICENSED — private.
+
+<!-- brand-ui:gen:readme:end -->

package/dist/index.d.ts

@@ -0,0 +1,293 @@
+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';
+
+/** Snapshot of table slice state — used for saved-view serialise/rehydrate. */
+interface DataTableViewState {
+    sorting: SortingState;
+    columnVisibility: VisibilityState;
+    columnFilters: ColumnFiltersState;
+    globalFilter?: string;
+    pagination?: PaginationState;
+    /**
+     * Which columns are frozen to the left/right edge (#333). OPTIONAL on purpose:
+     * the other members predate it, and a required key would break every consumer
+     * that already constructs a `DataTableViewState` literal.
+     */
+    columnPinning?: ColumnPinningState;
+}
+/**
+ * Argument object fired by `onServerChange` whenever a manual slice changes.
+ * The consuming app should re-fetch with these params and update `data`.
+ */
+interface DataTableServerArgs {
+    pagination: PaginationState;
+    sorting: SortingState;
+    columnFilters: ColumnFiltersState;
+    globalFilter: string;
+}
+/**
+ * Fires when a row is activated (#337).
+ *
+ * Both activation paths deliver a `click`: a pointer click on the row body, and
+ * a keyboard Enter/Space on the row's hidden activation `<button>` (which the
+ * browser dispatches as a click). So the handler takes ONE event type — there is
+ * nothing for the caller to branch on.
+ */
+type DataTableRowClickHandler<TData> = (row: Row<TData>, event: React.MouseEvent<HTMLElement>) => void;
+interface DataTableProps<TData, TValue> extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+    columns: ColumnDef<TData, TValue>[];
+    data: TData[];
+    /** Render a toolbar above the table; receives the table instance. */
+    toolbar?: (table: Table<TData>) => ReactNode;
+    /** Enable client-side pagination. */
+    enablePagination?: boolean;
+    pageSize?: number;
+    /**
+     * Hide the pager once there's genuinely only one page
+     * (`table.getPageCount() <= 1`). Default `true`. When `manualPagination` is
+     * set without `rowCount`/`pageCount`, the page count isn't knowable (TanStack
+     * falls back to the current page's row count) — in that ambiguous case the
+     * pager still renders regardless of this flag, so the existing dev warning
+     * (#227) stays the diagnostic instead of a silently-hidden pager. Set to
+     * `false` to always show the pager (e.g. while a server total is still
+     * loading and you'd rather show a disabled pager than none).
+     */
+    hidePaginationWhenSingle?: boolean;
+    /**
+     * Controlled global filter value. When provided, the table reflects this
+     * value and the component manages no internal filter state. Keep the source
+     * of truth in the app and pass it down — never mutate the filter during
+     * render (e.g. `table.setGlobalFilter()` in `toolbar`), which loops.
+     */
+    globalFilter?: string;
+    /** Fires when the table requests a global-filter change (e.g. from typeahead). */
+    onGlobalFilterChange?: (value: string) => void;
+    /** Controlled sorting state. When provided the component is sorted-controlled. */
+    sorting?: SortingState;
+    onSortingChange?: OnChangeFn<SortingState>;
+    /** Controlled column-visibility state. */
+    columnVisibility?: VisibilityState;
+    onColumnVisibilityChange?: OnChangeFn<VisibilityState>;
+    /** Controlled column-filters state. */
+    columnFilters?: ColumnFiltersState;
+    onColumnFiltersChange?: OnChangeFn<ColumnFiltersState>;
+    /** Controlled pagination state. */
+    pagination?: PaginationState;
+    onPaginationChange?: OnChangeFn<PaginationState>;
+    /**
+     * Controlled column-pinning state (#333) — the columns frozen against the
+     * left and/or right edge while the rest of the table scrolls horizontally.
+     * When provided the component is pinning-controlled; otherwise it manages the
+     * slice internally and can be seeded once via `initialView.columnPinning`.
+     *
+     * A pinned column MUST declare an explicit `size` in its `ColumnDef`: the
+     * sticky offset is computed from TanStack's `column.getStart("left")` /
+     * `getAfter("right")`, which sum the DECLARED sizes, so an auto-width column
+     * would render at a width that doesn't match its own offset. A dev-only
+     * warning fires for a pinned column with no `size`.
+     *
+     * Pinning is a LAYOUT concern, not a query concern — it is client-only and
+     * never joins `DataTableServerArgs` / `onServerChange`.
+     */
+    columnPinning?: ColumnPinningState;
+    onColumnPinningChange?: OnChangeFn<ColumnPinningState>;
+    /**
+     * One-shot rehydrate for uncontrolled slices only (ignored for any slice
+     * whose corresponding controlled prop is set). Maps to `useReactTable`'s
+     * `initialState`.
+     */
+    initialView?: Partial<DataTableViewState>;
+    /**
+     * When true, sorting is handled by the server. Pass `sorting` (controlled)
+     * and handle `onServerChange` to re-fetch with the new sort params.
+     * NOTE: controlled ≠ manual — a controlled `sorting` with `manualSorting:false`
+     * still sorts locally.
+     */
+    manualSorting?: boolean;
+    /**
+     * When true, filtering is handled by the server.
+     * NOTE: a controlled `columnFilters` with `manualFiltering:false` still
+     * filters locally.
+     */
+    manualFiltering?: boolean;
+    /** When true, pagination is handled by the server. */
+    manualPagination?: boolean;
+    /**
+     * Total row count — used by the server model so TanStack can derive
+     * page count. Required when `manualPagination` is true and `pageCount` is
+     * not provided.
+     */
+    rowCount?: number;
+    /**
+     * Total page count — alternative to `rowCount` for server pagination. When
+     * both are provided, `pageCount` wins.
+     */
+    pageCount?: number;
+    /**
+     * Fired after any manual-slice change with the current {pagination, sorting,
+     * columnFilters, globalFilter}. The component never fetches; the app must
+     * re-fetch and update `data`.
+     */
+    onServerChange?: (args: DataTableServerArgs) => void;
+    /** When true: overlay spinner; on empty+loading show skeleton rows instead of empty message. */
+    loading?: boolean;
+    /**
+     * Opt-in to row virtualization (for very large lists). Mutually exclusive
+     * with enablePagination in practice — if both are set, virtualization wins
+     * and pagination is silently ignored.
+     */
+    enableRowVirtualization?: boolean;
+    /** Estimated row height in px (used by the virtualizer). Default: 40. */
+    estimateRowHeight?: number;
+    /** Virtualizer overscan (rows rendered above/below the visible window). Default: 8. */
+    overscan?: number;
+    /** CSS max-height of the scroll container in virtualized mode. Default: "32rem". */
+    maxBodyHeight?: string;
+    /**
+     * Number of skeleton placeholder rows to render while loading.
+     * Defaults to `pageSize` (non-virtualized) or `min(10, pageSize)` (virtualized).
+     */
+    loadingRows?: number;
+    /**
+     * Gentle alternating row stripes ("zebra") as the row-separation cue, instead
+     * of a hairline divider between every row. Default `true` — the stripe is the
+     * single separation gesture, so rows carry no divider (a divider on a striped
+     * row would be a redundant boundary). Set `false` for the classic line model
+     * (a `border-border-strong` divider between rows, no stripes).
+     */
+    zebra?: boolean;
+    /**
+     * Fires when a row is activated (#337). Setting it adds ONE activation
+     * target per row: a visually-hidden `<button>` rendered inside the row's
+     * first cell. That button is the row's keyboard tab stop and its accessible
+     * name; a pointer click anywhere else in the row resolves to the same
+     * handler, so mouse and keyboard converge on one control instead of two
+     * competing ones (a focusable `<tr>` cannot carry an activation role without
+     * destroying `row` table semantics).
+     *
+     * Guarded: a click that originates on a nested interactive control
+     * (button/link/input/checkbox/…) or is the tail end of a text-selection drag
+     * does NOT fire it. Optional; omitting it renders rows exactly as before.
+     */
+    onRowClick?: DataTableRowClickHandler<TData>;
+    /**
+     * Accessible name for the row's hidden activation button (#337). Only read
+     * when `onRowClick` is set. Defaults to the row's first visible cell value
+     * when that is a string/number (the row's primary identifier — the same
+     * naming a link in that cell would get), else the localized
+     * `data.table.rowAction` fallback. Supply it whenever the first cell isn't a
+     * good name for the row.
+     */
+    rowActionLabel?: (row: Row<TData>) => string;
+    /**
+     * Per-row className, merged alongside the existing zebra/line/hover/selected
+     * classes via `cn()` (so it can't accidentally clobber them) (#337).
+     */
+    rowClassName?: (row: Row<TData>) => string;
+    /**
+     * Accessible name for the table, rendered as a visually-hidden (`sr-only`)
+     * `<caption>` — the first child of `<table>`. Screen readers announce it as
+     * the table's name and it makes column-header navigation meaningful.
+     * Optional; omit it only when the surrounding page already labels the table
+     * unambiguously (e.g. an adjacent heading) (#338).
+     */
+    caption?: ReactNode;
+    /** Message shown when there are no rows and not loading. */
+    emptyMessage?: ReactNode;
+    className?: string;
+}
+declare const DataTableWithRef: <TData, TValue>(props: DataTableProps<TData, TValue> & {
+    ref?: React.Ref<HTMLDivElement>;
+}) => React.ReactElement | null;
+
+interface SearchInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "onChange" | "value"> {
+    value: string;
+    onValueChange: (value: string) => void;
+    /** Visually-hidden accessible label. Defaults to "Search". */
+    label?: string;
+    containerClassName?: string;
+}
+/**
+ * Search field with a leading icon and a clear button. Controlled.
+ *
+ * `disabled` (available via the extended `InputHTMLAttributes`) is how a
+ * consumer signals a pending fetch (D5 — the app owns fetch state, this
+ * control just reflects it; see loading-states.md). It is forwarded to the
+ * `<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;
+
+interface FilterBarProps {
+    /** Left cluster: search + facet filters. */
+    children: ReactNode;
+    /** Right cluster: column picker, export, primary actions. */
+    actions?: ReactNode;
+    className?: string;
+}
+/** Horizontal toolbar that groups table filters and actions. */
+declare function FilterBar({ children, actions, className }: FilterBarProps): react.JSX.Element;
+
+interface FacetOption {
+    label: string;
+    value: string;
+}
+interface FacetFilterProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "title"> {
+    title: string;
+    options: FacetOption[];
+    /** Currently selected values (controlled). */
+    selected: string[];
+    onSelectedChange: (values: string[]) => void;
+}
+/**
+ * Multi-select faceted filter rendered as a dropdown of toggles.
+ *
+ * `disabled` (forwarded to the trigger `Button`) is how a consumer signals a
+ * pending fetch (D5 — the app owns fetch state, this control just reflects
+ * it; see loading-states.md).
+ *
+ * The trigger takes `Button`'s DEFAULT size (`h-9`), not `sm` (#346): a facet
+ * filter lives in a toolbar beside `Select` / `Input` / `DatePicker`, all of
+ * which land on `h-9` (Select's own default rung, Input hardcoded, DatePicker
+ * via this same Button default). An `sm` trigger was the lone `h-8` outlier in
+ * that row, so the top and bottom edges of a filter bar didn't line up.
+ */
+declare const FacetFilter: react.ForwardRefExoticComponent<FacetFilterProps & react.RefAttributes<HTMLButtonElement>>;
+
+interface ColumnPickerProps<TData> extends ButtonHTMLAttributes<HTMLButtonElement> {
+    table: Table<TData>;
+    /** Trigger label. Defaults to "Columns". */
+    label?: string;
+}
+declare const ColumnPicker: <TData>(props: ColumnPickerProps<TData> & {
+    ref?: Ref<HTMLButtonElement>;
+}) => ReactElement | null;
+
+type CsvColumn<TData> = {
+    key: keyof TData & string;
+    header?: string;
+};
+interface ToCsvOptions<TData> {
+    /** Subset/reorder of columns. Omitted → all keys from rows[0]. */
+    columns?: CsvColumn<TData>[];
+    /** Emit header row. Default true. */
+    header?: boolean;
+    /** Field delimiter. Default ",". */
+    delimiter?: string;
+}
+interface DownloadCsvOptions<TData> extends ToCsvOptions<TData> {
+    /** File name without extension. Default "download". */
+    filename?: string;
+}
+/**
+ * Serialize rows to a CSV string (no DOM access — safe for SSR / jsdom).
+ */
+declare function toCsv<TData extends Record<string, unknown>>(rows: TData[], opts?: ToCsvOptions<TData>): string;
+/**
+ * Trigger a CSV file download in the browser. No-op in SSR environments.
+ */
+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 };