@techzyapp/ui-library 1.0.0

package/dist/components/Table/Table.d.cts

@@ -0,0 +1,248 @@
+import { type ForwardedRef, type HTMLAttributes, type ReactElement, type ReactNode } from 'react';
+import { type TableQueryConfig } from '../../theme';
+import { type TableFilter, type TableFilterState } from './tableFilter';
+export type TableAlign = 'left' | 'center' | 'right';
+export type TableSortDirection = 'asc' | 'desc';
+/** A single column definition — the simple, engine-agnostic shape a consumer writes. */
+export interface TableColumn<T> {
+    /** Field key on the row — the column id, the default cell accessor, and the local sort/search key. */
+    key: string;
+    /** Header content. */
+    header: ReactNode;
+    /** Custom cell renderer. Defaults to the row's `key` value stringified. */
+    cell?: (row: T, index: number) => ReactNode;
+    /** Enable sorting on this column (click the header to toggle asc → desc → none). Defaults to `false`. */
+    sortable?: boolean;
+    /** Fixed column width — a px `number` or any CSS width string. Opts the column out of the default cap. */
+    width?: number | string;
+    /**
+     * Cap the column's width (px `number` or CSS string) — long content **wraps** within it onto 2+ lines
+     * (the row grows) instead of stretching the table. **Implies `wrap`.** Only needed to override the
+     * default wrap cap (`280px`); otherwise plain `wrap` is enough.
+     */
+    maxWidth?: number | string;
+    /**
+     * Let this column's content **wrap** onto multiple lines (rows grow) instead of the single-line default —
+     * a long unbroken token breaks too. On its own it caps the column at a readable **`280px`** (set
+     * `maxWidth` for a different cap). Cells are single-line by default (the table scrolls horizontally); opt
+     * a long-text column (name / note / address) in with `wrap`.
+     */
+    wrap?: boolean;
+    /** Cell + header text alignment. Defaults to `left`. */
+    align?: TableAlign;
+    /**
+     * Pin the column to an edge so it stays visible while the rest scrolls horizontally (e.g. an actions
+     * column pinned `'right'`). One column per edge; a hairline separates it from the scrolling body. A
+     * pinned column with **no `width`** shrinks to its content (so an actions column fits its buttons); set
+     * `width` to override.
+     */
+    pinned?: 'left' | 'right';
+}
+/** The current sort — the column `key` + direction, or `null` when unsorted. */
+export interface TableSortState {
+    key: string;
+    direction: TableSortDirection;
+}
+/** Details of a single row-reorder drag, passed to `onReorder` alongside the reordered rows. */
+export interface TableReorderMeta {
+    /** The stable row id (from `getRowId`) of the dragged row. */
+    id: string;
+    /** The dragged row's original index in `data`. */
+    from: number;
+    /** The index the row was dropped at (its new position in the reordered array). */
+    to: number;
+}
+/** The table's live state, emitted on every change — the server-mode fetch driver. */
+export interface TableChangeState {
+    /** 1-based page number. */
+    page: number;
+    /** Rows per page. */
+    size: number;
+    /** Current search query. */
+    search: string;
+    /** Active sort, or `null`. */
+    sort: TableSortState | null;
+    /** Active filter values, keyed by filter `key` (empty when none set). */
+    filters: TableFilterState;
+    /**
+     * The **built server-request params** for this state, from the query mapping (`config.table.query`
+     * merged with the `queryMapping` prop) — ready to append to your endpoint, so you don't hand-map
+     * page/size/search/sort. E.g. `fetch(`/products?${state.query}`)`.
+     */
+    params: URLSearchParams;
+    /** `params.toString()` — e.g. `"skip=0&limit=10&q=phone&sortBy=price&order=desc"`. */
+    query: string;
+}
+/** Props shared by both table modes (everything except the mode-specific `manualPagination` / `rowCount`). */
+interface TableBaseProps<T> extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'title'> {
+    /** Column definitions — keep them simple: a `key` + `header`, plus an optional `cell` renderer. */
+    columns: TableColumn<T>[];
+    /**
+     * Row data. **Local mode** (default): the full dataset — the table searches / sorts / paginates it
+     * client-side. **Server mode** (`manualPagination`): only the current page's rows — you fetch them in
+     * `onChange` and pass `rowCount` for the total.
+     */
+    data: T[];
+    /**
+     * Stable row id from a row — used as the React key, so a row keeps its DOM identity (and any focus /
+     * in-cell state) across sort / filter / refetch. Defaults to the row **index**, which is fine for static
+     * data but reuses DOM by position when rows reorder or a server page swaps in — pass a real id (e.g.
+     * `(row) => row.id`) for any table with row interactions or changing data.
+     */
+    getRowId?: (row: T, index: number) => string;
+    /** Optional heading shown at the top-left of the toolbar. */
+    title?: ReactNode;
+    /** Extra toolbar content (e.g. future filter controls), rendered in the right group before sort/export. */
+    toolbar?: ReactNode;
+    /** Show the search box in the toolbar. Defaults to `false`. */
+    searchable?: boolean;
+    /** Placeholder for the search box. Defaults to `"Search…"`. */
+    searchPlaceholder?: string;
+    /** Initial search query. */
+    defaultSearch?: string;
+    /** Debounce (ms) before a typed search commits (local filter + `onChange`). Defaults to `300`. */
+    debounceMs?: number;
+    /** Initial page (1-based). Defaults to `1` (overridden by the URL param when `urlSync`). */
+    defaultPage?: number;
+    /** Initial rows per page. Defaults to `10` (overridden by the URL param when `urlSync`). */
+    defaultPageSize?: number;
+    /** Rows-per-page choices in the footer `Select`. Defaults to `[10, 20, 50, 100, 200]`. */
+    pageSizeOptions?: number[];
+    /**
+     * Add an **"All"** rows-per-page choice that puts every row on one page. Defaults to `true` — pass
+     * `false` to hide it (e.g. for a large server dataset where fetching everything is undesirable).
+     */
+    allowAllRows?: boolean;
+    /** Show the rows-per-page `Select` in the footer. Defaults to `true`. */
+    showPageSize?: boolean;
+    /** Show the jump-to-first-page (⏮) button in the pagination. Defaults to `false`. */
+    showFirstButton?: boolean;
+    /** Show the jump-to-last-page (⏭) button in the pagination. Defaults to `false`. */
+    showLastButton?: boolean;
+    /** Initial sort. */
+    defaultSort?: TableSortState | null;
+    /**
+     * Fires with the full `{ page, size, search, sort, params, query }` state on mount and whenever it
+     * changes — wire this to your fetch in server mode (append `state.query` to your endpoint). Search
+     * changes are debounced (`debounceMs`).
+     */
+    onChange?: (state: TableChangeState) => void;
+    /**
+     * Per-table override for how `state.params` / `state.query` are built (param names, `page` vs `offset`
+     * pagination, sort format) — merged over the app-wide `config.table.query`. Use it when one table hits a
+     * differently-shaped endpoint (e.g. `{ pageParam: 'skip', sizeParam: 'limit', searchParam: 'q', pagination: 'offset' }`).
+     */
+    queryMapping?: TableQueryConfig;
+    /**
+     * Handler for the toolbar **export** menu's built-in **"Send On Email"** item (label + icon are baked in).
+     * Set it to show the export `Dropdown`; on click it fires with the current `TableChangeState` (incl.
+     * `query`), so you just wire your endpoint — e.g. `onExportToEmail={(s) => exportCustomers(s.query)}`. Omit it
+     * to hide the export menu.
+     */
+    onExportToEmail?: (state: TableChangeState) => void;
+    /**
+     * Declarative filters — each renders a field in a toolbar **Filters** panel (a `Modal`). In **local**
+     * mode the table filters `data` client-side; in **server** mode the active values ride in `onChange`
+     * (`state.filters`). Core types: `text` / `number` / `numberRange` / `select` / `multiSelect` /
+     * `boolean` / `date` / `dateRange` (`select` / `multiSelect` take `options`).
+     */
+    filters?: TableFilter[];
+    /** Initial filter values, keyed by filter `key`. */
+    defaultFilters?: TableFilterState;
+    /** Called when a body row is clicked (makes rows interactive). */
+    onRowClick?: (row: T, index: number) => void;
+    /**
+     * Per-row actions — return the action UI (your own `IconButton`s / menu / etc.) for a row and the table
+     * renders it in a **pinned-right actions column** it adds for you (no column boilerplate). The cell is
+     * `stopPropagation`-wrapped, so clicks inside it never fire the row's `onClick` — you don't handle that.
+     */
+    actions?: (row: T, index: number) => ReactNode;
+    /**
+     * Enable **row drag-and-drop reordering** — a leading **drag-handle** column (a grip icon) is prepended,
+     * and dragging it (or keyboard: focus the handle → Space → Arrows → Space) reorders the rows, firing
+     * **`onReorder`**. **Local mode only**, and best with no active sort (a sort fights a manual order);
+     * **requires `getRowId`** (dnd needs stable row ids). Built on `@dnd-kit`. Defaults to `false`.
+     */
+    reorderable?: boolean;
+    /**
+     * Fired after a drag reorder with the **full `data` reordered** — you own `data`, so set it from this
+     * (e.g. `onReorder={setRows}`). A second **`meta`** arg carries the drag details (`{ id, from, to }` —
+     * the dragged row's id + its old/new index). Only fires while `reorderable`.
+     */
+    onReorder?: (rows: T[], meta: TableReorderMeta) => void;
+    /** Show a loading overlay over the table (e.g. while fetching a server page). Defaults to `false`. */
+    loading?: boolean;
+    /** Custom content for the empty state (replaces the default `EmptyState`). */
+    empty?: ReactNode;
+    /**
+     * Mirror page + rows-per-page + search + sort + filters to the URL query, using the **same shape as the
+     * server request** (`config.table.query` merged with `queryMapping`) — so the address bar matches
+     * `state.query` exactly (e.g. `?page=1&size=10&sortBy=rating&orderBy=desc`). Read back on mount + restored
+     * on Back/Forward. Defaults to `true`; pass `false` to opt out entirely. (Two synced tables on one page
+     * need distinct param names via their `queryMapping`, since both write the same params otherwise.)
+     */
+    urlSync?: boolean;
+    /** Controlled 1-based page (pair with `onPageChange`); omit for uncontrolled (`defaultPage`). */
+    page?: number;
+    /** Fired with the new 1-based page — on user paging, or a reset to page 1 from a size/sort/search/filter change. */
+    onPageChange?: (page: number) => void;
+    /** Controlled rows-per-page (pair with `onPageSizeChange`); omit for uncontrolled (`defaultPageSize`). */
+    pageSize?: number;
+    /** Fired with the new rows-per-page. */
+    onPageSizeChange?: (size: number) => void;
+    /** Controlled (committed, debounced) search query (pair with `onSearchChange`); omit for uncontrolled (`defaultSearch`). */
+    search?: string;
+    /** Fired with the committed (debounced) search query. */
+    onSearchChange?: (search: string) => void;
+    /** Controlled sort, or `null` (pair with `onSortChange`); omit for uncontrolled (`defaultSort`). */
+    sort?: TableSortState | null;
+    /** Fired with the new sort (or `null` when cleared). */
+    onSortChange?: (sort: TableSortState | null) => void;
+    /** Controlled filter values, keyed by filter `key` (pair with `onFiltersChange`); omit for uncontrolled (`defaultFilters`). */
+    filterValues?: TableFilterState;
+    /** Fired with the filter values on Apply / Clear. */
+    onFiltersChange?: (filters: TableFilterState) => void;
+    /** Pin the header row while the body scrolls. Defaults to `false`. */
+    stickyHeader?: boolean;
+    /** Zebra-stripe alternate rows. Defaults to `false`. */
+    striped?: boolean;
+    /** Highlight rows on hover. Defaults to `true`. */
+    hoverable?: boolean;
+}
+/**
+ * `Table` props. A discriminated union on `manualPagination` so the type enforces the server-mode contract:
+ * **local mode** (default) needs no `rowCount`; **server mode** (`manualPagination`) **requires** it (the
+ * table can't derive the total page count from a single fetched page).
+ */
+export type TableProps<T> = (TableBaseProps<T> & {
+    /** Local mode (default) — the table slices / sorts / filters `data` itself. */
+    manualPagination?: false;
+    /** Ignored in local mode (the table knows the full count from `data`). */
+    rowCount?: number;
+}) | (TableBaseProps<T> & {
+    /**
+     * **Server mode** — the table doesn't slice / sort / filter `data`; it tracks state and fires
+     * `onChange`. Pass the current page's rows in `data` and the total in `rowCount`.
+     */
+    manualPagination: true;
+    /** Total row count across all pages — **required** in server mode to compute the page count. */
+    rowCount: number;
+});
+/**
+ * A data table built on **TanStack Table** (headless — an optional peer, `external`) styled entirely with
+ * `--tz-*` tokens. Pass `columns` + `data` and it renders a sortable, paginated, searchable table. Works
+ * two ways: **local** (hand it the full `data` — it searches / sorts / paginates client-side) or **server**
+ * (`manualPagination` — pass the current page in `data` + the total in `rowCount`, and fetch in `onChange`).
+ * Composes the library's `TextField` (search), `Select` (rows per page), `Pagination`, `EmptyState`, and
+ * `Loader`; syncs page + size to the URL (`?page=1&size=10`) by default. The ref points at the root.
+ *
+ * @example
+ * <Table data={users} columns={[
+ *   { key: 'name', header: 'Name', sortable: true },
+ *   { key: 'role', header: 'Role', cell: (u) => <Chip>{u.role}</Chip> },
+ * ]} searchable />
+ */
+export declare const Table: <T>(props: TableProps<T> & {
+    ref?: ForwardedRef<HTMLDivElement>;
+}) => ReactElement;
+export {};

package/dist/components/Table/Table.d.ts

@@ -0,0 +1,248 @@
+import { type ForwardedRef, type HTMLAttributes, type ReactElement, type ReactNode } from 'react';
+import { type TableQueryConfig } from '../../theme';
+import { type TableFilter, type TableFilterState } from './tableFilter';
+export type TableAlign = 'left' | 'center' | 'right';
+export type TableSortDirection = 'asc' | 'desc';
+/** A single column definition — the simple, engine-agnostic shape a consumer writes. */
+export interface TableColumn<T> {
+    /** Field key on the row — the column id, the default cell accessor, and the local sort/search key. */
+    key: string;
+    /** Header content. */
+    header: ReactNode;
+    /** Custom cell renderer. Defaults to the row's `key` value stringified. */
+    cell?: (row: T, index: number) => ReactNode;
+    /** Enable sorting on this column (click the header to toggle asc → desc → none). Defaults to `false`. */
+    sortable?: boolean;
+    /** Fixed column width — a px `number` or any CSS width string. Opts the column out of the default cap. */
+    width?: number | string;
+    /**
+     * Cap the column's width (px `number` or CSS string) — long content **wraps** within it onto 2+ lines
+     * (the row grows) instead of stretching the table. **Implies `wrap`.** Only needed to override the
+     * default wrap cap (`280px`); otherwise plain `wrap` is enough.
+     */
+    maxWidth?: number | string;
+    /**
+     * Let this column's content **wrap** onto multiple lines (rows grow) instead of the single-line default —
+     * a long unbroken token breaks too. On its own it caps the column at a readable **`280px`** (set
+     * `maxWidth` for a different cap). Cells are single-line by default (the table scrolls horizontally); opt
+     * a long-text column (name / note / address) in with `wrap`.
+     */
+    wrap?: boolean;
+    /** Cell + header text alignment. Defaults to `left`. */
+    align?: TableAlign;
+    /**
+     * Pin the column to an edge so it stays visible while the rest scrolls horizontally (e.g. an actions
+     * column pinned `'right'`). One column per edge; a hairline separates it from the scrolling body. A
+     * pinned column with **no `width`** shrinks to its content (so an actions column fits its buttons); set
+     * `width` to override.
+     */
+    pinned?: 'left' | 'right';
+}
+/** The current sort — the column `key` + direction, or `null` when unsorted. */
+export interface TableSortState {
+    key: string;
+    direction: TableSortDirection;
+}
+/** Details of a single row-reorder drag, passed to `onReorder` alongside the reordered rows. */
+export interface TableReorderMeta {
+    /** The stable row id (from `getRowId`) of the dragged row. */
+    id: string;
+    /** The dragged row's original index in `data`. */
+    from: number;
+    /** The index the row was dropped at (its new position in the reordered array). */
+    to: number;
+}
+/** The table's live state, emitted on every change — the server-mode fetch driver. */
+export interface TableChangeState {
+    /** 1-based page number. */
+    page: number;
+    /** Rows per page. */
+    size: number;
+    /** Current search query. */
+    search: string;
+    /** Active sort, or `null`. */
+    sort: TableSortState | null;
+    /** Active filter values, keyed by filter `key` (empty when none set). */
+    filters: TableFilterState;
+    /**
+     * The **built server-request params** for this state, from the query mapping (`config.table.query`
+     * merged with the `queryMapping` prop) — ready to append to your endpoint, so you don't hand-map
+     * page/size/search/sort. E.g. `fetch(`/products?${state.query}`)`.
+     */
+    params: URLSearchParams;
+    /** `params.toString()` — e.g. `"skip=0&limit=10&q=phone&sortBy=price&order=desc"`. */
+    query: string;
+}
+/** Props shared by both table modes (everything except the mode-specific `manualPagination` / `rowCount`). */
+interface TableBaseProps<T> extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'title'> {
+    /** Column definitions — keep them simple: a `key` + `header`, plus an optional `cell` renderer. */
+    columns: TableColumn<T>[];
+    /**
+     * Row data. **Local mode** (default): the full dataset — the table searches / sorts / paginates it
+     * client-side. **Server mode** (`manualPagination`): only the current page's rows — you fetch them in
+     * `onChange` and pass `rowCount` for the total.
+     */
+    data: T[];
+    /**
+     * Stable row id from a row — used as the React key, so a row keeps its DOM identity (and any focus /
+     * in-cell state) across sort / filter / refetch. Defaults to the row **index**, which is fine for static
+     * data but reuses DOM by position when rows reorder or a server page swaps in — pass a real id (e.g.
+     * `(row) => row.id`) for any table with row interactions or changing data.
+     */
+    getRowId?: (row: T, index: number) => string;
+    /** Optional heading shown at the top-left of the toolbar. */
+    title?: ReactNode;
+    /** Extra toolbar content (e.g. future filter controls), rendered in the right group before sort/export. */
+    toolbar?: ReactNode;
+    /** Show the search box in the toolbar. Defaults to `false`. */
+    searchable?: boolean;
+    /** Placeholder for the search box. Defaults to `"Search…"`. */
+    searchPlaceholder?: string;
+    /** Initial search query. */
+    defaultSearch?: string;
+    /** Debounce (ms) before a typed search commits (local filter + `onChange`). Defaults to `300`. */
+    debounceMs?: number;
+    /** Initial page (1-based). Defaults to `1` (overridden by the URL param when `urlSync`). */
+    defaultPage?: number;
+    /** Initial rows per page. Defaults to `10` (overridden by the URL param when `urlSync`). */
+    defaultPageSize?: number;
+    /** Rows-per-page choices in the footer `Select`. Defaults to `[10, 20, 50, 100, 200]`. */
+    pageSizeOptions?: number[];
+    /**
+     * Add an **"All"** rows-per-page choice that puts every row on one page. Defaults to `true` — pass
+     * `false` to hide it (e.g. for a large server dataset where fetching everything is undesirable).
+     */
+    allowAllRows?: boolean;
+    /** Show the rows-per-page `Select` in the footer. Defaults to `true`. */
+    showPageSize?: boolean;
+    /** Show the jump-to-first-page (⏮) button in the pagination. Defaults to `false`. */
+    showFirstButton?: boolean;
+    /** Show the jump-to-last-page (⏭) button in the pagination. Defaults to `false`. */
+    showLastButton?: boolean;
+    /** Initial sort. */
+    defaultSort?: TableSortState | null;
+    /**
+     * Fires with the full `{ page, size, search, sort, params, query }` state on mount and whenever it
+     * changes — wire this to your fetch in server mode (append `state.query` to your endpoint). Search
+     * changes are debounced (`debounceMs`).
+     */
+    onChange?: (state: TableChangeState) => void;
+    /**
+     * Per-table override for how `state.params` / `state.query` are built (param names, `page` vs `offset`
+     * pagination, sort format) — merged over the app-wide `config.table.query`. Use it when one table hits a
+     * differently-shaped endpoint (e.g. `{ pageParam: 'skip', sizeParam: 'limit', searchParam: 'q', pagination: 'offset' }`).
+     */
+    queryMapping?: TableQueryConfig;
+    /**
+     * Handler for the toolbar **export** menu's built-in **"Send On Email"** item (label + icon are baked in).
+     * Set it to show the export `Dropdown`; on click it fires with the current `TableChangeState` (incl.
+     * `query`), so you just wire your endpoint — e.g. `onExportToEmail={(s) => exportCustomers(s.query)}`. Omit it
+     * to hide the export menu.
+     */
+    onExportToEmail?: (state: TableChangeState) => void;
+    /**
+     * Declarative filters — each renders a field in a toolbar **Filters** panel (a `Modal`). In **local**
+     * mode the table filters `data` client-side; in **server** mode the active values ride in `onChange`
+     * (`state.filters`). Core types: `text` / `number` / `numberRange` / `select` / `multiSelect` /
+     * `boolean` / `date` / `dateRange` (`select` / `multiSelect` take `options`).
+     */
+    filters?: TableFilter[];
+    /** Initial filter values, keyed by filter `key`. */
+    defaultFilters?: TableFilterState;
+    /** Called when a body row is clicked (makes rows interactive). */
+    onRowClick?: (row: T, index: number) => void;
+    /**
+     * Per-row actions — return the action UI (your own `IconButton`s / menu / etc.) for a row and the table
+     * renders it in a **pinned-right actions column** it adds for you (no column boilerplate). The cell is
+     * `stopPropagation`-wrapped, so clicks inside it never fire the row's `onClick` — you don't handle that.
+     */
+    actions?: (row: T, index: number) => ReactNode;
+    /**
+     * Enable **row drag-and-drop reordering** — a leading **drag-handle** column (a grip icon) is prepended,
+     * and dragging it (or keyboard: focus the handle → Space → Arrows → Space) reorders the rows, firing
+     * **`onReorder`**. **Local mode only**, and best with no active sort (a sort fights a manual order);
+     * **requires `getRowId`** (dnd needs stable row ids). Built on `@dnd-kit`. Defaults to `false`.
+     */
+    reorderable?: boolean;
+    /**
+     * Fired after a drag reorder with the **full `data` reordered** — you own `data`, so set it from this
+     * (e.g. `onReorder={setRows}`). A second **`meta`** arg carries the drag details (`{ id, from, to }` —
+     * the dragged row's id + its old/new index). Only fires while `reorderable`.
+     */
+    onReorder?: (rows: T[], meta: TableReorderMeta) => void;
+    /** Show a loading overlay over the table (e.g. while fetching a server page). Defaults to `false`. */
+    loading?: boolean;
+    /** Custom content for the empty state (replaces the default `EmptyState`). */
+    empty?: ReactNode;
+    /**
+     * Mirror page + rows-per-page + search + sort + filters to the URL query, using the **same shape as the
+     * server request** (`config.table.query` merged with `queryMapping`) — so the address bar matches
+     * `state.query` exactly (e.g. `?page=1&size=10&sortBy=rating&orderBy=desc`). Read back on mount + restored
+     * on Back/Forward. Defaults to `true`; pass `false` to opt out entirely. (Two synced tables on one page
+     * need distinct param names via their `queryMapping`, since both write the same params otherwise.)
+     */
+    urlSync?: boolean;
+    /** Controlled 1-based page (pair with `onPageChange`); omit for uncontrolled (`defaultPage`). */
+    page?: number;
+    /** Fired with the new 1-based page — on user paging, or a reset to page 1 from a size/sort/search/filter change. */
+    onPageChange?: (page: number) => void;
+    /** Controlled rows-per-page (pair with `onPageSizeChange`); omit for uncontrolled (`defaultPageSize`). */
+    pageSize?: number;
+    /** Fired with the new rows-per-page. */
+    onPageSizeChange?: (size: number) => void;
+    /** Controlled (committed, debounced) search query (pair with `onSearchChange`); omit for uncontrolled (`defaultSearch`). */
+    search?: string;
+    /** Fired with the committed (debounced) search query. */
+    onSearchChange?: (search: string) => void;
+    /** Controlled sort, or `null` (pair with `onSortChange`); omit for uncontrolled (`defaultSort`). */
+    sort?: TableSortState | null;
+    /** Fired with the new sort (or `null` when cleared). */
+    onSortChange?: (sort: TableSortState | null) => void;
+    /** Controlled filter values, keyed by filter `key` (pair with `onFiltersChange`); omit for uncontrolled (`defaultFilters`). */
+    filterValues?: TableFilterState;
+    /** Fired with the filter values on Apply / Clear. */
+    onFiltersChange?: (filters: TableFilterState) => void;
+    /** Pin the header row while the body scrolls. Defaults to `false`. */
+    stickyHeader?: boolean;
+    /** Zebra-stripe alternate rows. Defaults to `false`. */
+    striped?: boolean;
+    /** Highlight rows on hover. Defaults to `true`. */
+    hoverable?: boolean;
+}
+/**
+ * `Table` props. A discriminated union on `manualPagination` so the type enforces the server-mode contract:
+ * **local mode** (default) needs no `rowCount`; **server mode** (`manualPagination`) **requires** it (the
+ * table can't derive the total page count from a single fetched page).
+ */
+export type TableProps<T> = (TableBaseProps<T> & {
+    /** Local mode (default) — the table slices / sorts / filters `data` itself. */
+    manualPagination?: false;
+    /** Ignored in local mode (the table knows the full count from `data`). */
+    rowCount?: number;
+}) | (TableBaseProps<T> & {
+    /**
+     * **Server mode** — the table doesn't slice / sort / filter `data`; it tracks state and fires
+     * `onChange`. Pass the current page's rows in `data` and the total in `rowCount`.
+     */
+    manualPagination: true;
+    /** Total row count across all pages — **required** in server mode to compute the page count. */
+    rowCount: number;
+});
+/**
+ * A data table built on **TanStack Table** (headless — an optional peer, `external`) styled entirely with
+ * `--tz-*` tokens. Pass `columns` + `data` and it renders a sortable, paginated, searchable table. Works
+ * two ways: **local** (hand it the full `data` — it searches / sorts / paginates client-side) or **server**
+ * (`manualPagination` — pass the current page in `data` + the total in `rowCount`, and fetch in `onChange`).
+ * Composes the library's `TextField` (search), `Select` (rows per page), `Pagination`, `EmptyState`, and
+ * `Loader`; syncs page + size to the URL (`?page=1&size=10`) by default. The ref points at the root.
+ *
+ * @example
+ * <Table data={users} columns={[
+ *   { key: 'name', header: 'Name', sortable: true },
+ *   { key: 'role', header: 'Role', cell: (u) => <Chip>{u.role}</Chip> },
+ * ]} searchable />
+ */
+export declare const Table: <T>(props: TableProps<T> & {
+    ref?: ForwardedRef<HTMLDivElement>;
+}) => ReactElement;
+export {};

package/dist/components/Table/TableFilters.d.cts

@@ -0,0 +1,16 @@
+import { type TableFilter, type TableFilterState } from './tableFilter';
+export interface TableFiltersProps {
+    /** The declarative filter definitions. */
+    filters: TableFilter[];
+    /** The committed filter values. */
+    value: TableFilterState;
+    /** Commit new filter values (Apply / Clear). */
+    onChange: (value: TableFilterState) => void;
+}
+/**
+ * The Table's filter control — a toolbar **Filters** button (with a count `Badge`) that opens a right
+ * **drawer** (`Modal placement="right"`) of fields (one per `filter` def). Edits a **draft** committed only
+ * on **Apply**; **Clear** resets. A `Modal` (not a popover) so nested `Select` / `DatePicker` popovers work
+ * inside it.
+ */
+export declare function TableFilters({ filters, value, onChange }: TableFiltersProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/Table/TableFilters.d.ts

@@ -0,0 +1,16 @@
+import { type TableFilter, type TableFilterState } from './tableFilter';
+export interface TableFiltersProps {
+    /** The declarative filter definitions. */
+    filters: TableFilter[];
+    /** The committed filter values. */
+    value: TableFilterState;
+    /** Commit new filter values (Apply / Clear). */
+    onChange: (value: TableFilterState) => void;
+}
+/**
+ * The Table's filter control — a toolbar **Filters** button (with a count `Badge`) that opens a right
+ * **drawer** (`Modal placement="right"`) of fields (one per `filter` def). Edits a **draft** committed only
+ * on **Apply**; **Clear** resets. A `Modal` (not a popover) so nested `Select` / `DatePicker` popovers work
+ * inside it.
+ */
+export declare function TableFilters({ filters, value, onChange }: TableFiltersProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/Table/index.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const e=require("../../Table-BeOumGng.cjs");exports.Table=e.Table;exports.default=e.Table;
+//# sourceMappingURL=index.cjs.map

package/dist/components/Table/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/components/Table/index.d.cts

@@ -0,0 +1,3 @@
+export { Table, Table as default } from './Table';
+export type { TableProps, TableColumn, TableSortState, TableChangeState, TableReorderMeta, TableAlign, TableSortDirection, } from './Table';
+export type { TableFilter, TableFilterType, TableFilterValue, TableFilterState, } from './tableFilter';

package/dist/components/Table/index.d.ts

@@ -0,0 +1,3 @@
+export { Table, Table as default } from './Table';
+export type { TableProps, TableColumn, TableSortState, TableChangeState, TableReorderMeta, TableAlign, TableSortDirection, } from './Table';
+export type { TableFilter, TableFilterType, TableFilterValue, TableFilterState, } from './tableFilter';

package/dist/components/Table/index.js

@@ -0,0 +1,6 @@
+import { T, T as f } from "../../Table-BjPLvMbf.js";
+export {
+  T as Table,
+  f as default
+};
+//# sourceMappingURL=index.js.map

package/dist/components/Table/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/dist/components/Table/tableFilter.d.cts

@@ -0,0 +1,65 @@
+import type { TableQueryConfig } from '../../theme';
+import type { SelectOption } from '../Select';
+/** Which control + matching logic a filter uses. */
+export type TableFilterType = 'text' | 'number' | 'numberRange' | 'numberRangeSlider' | 'select' | 'multiSelect' | 'boolean' | 'date' | 'dateRange' | 'time' | 'timeRange' | 'dateTime' | 'dateTimeRange';
+/** The value a single filter holds — shape depends on its `type` (see each control). `null` / empty = off. */
+export type TableFilterValue = string | number | boolean | string[] | [number | null, number | null] | [string, string] | null;
+/** A declarative filter definition — like a column, but for the filter panel. */
+export interface TableFilter {
+    /** Field key on the row — the local accessor + the key in the emitted filter state. */
+    key: string;
+    /** Label shown in the filter panel. */
+    label: string;
+    /** The filter's control + matching logic. */
+    type: TableFilterType;
+    /** Options for `select` / `multiSelect`. */
+    options?: SelectOption[];
+    /** Placeholder for the input(s). */
+    placeholder?: string;
+    /**
+     * Param name this filter serializes to in the **server-request** query (`state.query`). Defaults to
+     * `key`. Set it to rename or bake in an operator — e.g. `'name_like'`, `'q'`, `'status'`. Range filters
+     * append the `rangeMin/MaxSuffix` to this.
+     */
+    queryKey?: string;
+    /** `numberRange` slider bounds + step (defaults `0` / `100` / `1`) — set to match the column's data range. */
+    min?: number;
+    max?: number;
+    step?: number;
+    /**
+     * Labels for a `boolean` filter's three radios (defaults `Any` / `Yes` / `No`) — e.g.
+     * `{ any: 'All', yes: 'In stock', no: 'Sold out' }`.
+     */
+    booleanLabels?: {
+        any?: string;
+        yes?: string;
+        no?: string;
+    };
+}
+/** The active filter values, keyed by filter `key`. */
+export type TableFilterState = Record<string, TableFilterValue>;
+/** Whether a filter value is "set" (should actually filter) — an empty string / array / all-null range is off. */
+export declare function isFilterActive(type: TableFilterType, value: TableFilterValue | undefined): boolean;
+/** Number of filters currently set — drives the count badge on the Filters button. */
+export declare function activeFilterCount(filters: TableFilter[], state: TableFilterState): number;
+/**
+ * Filter rows client-side against the active filter values (local mode). A row is kept only when it matches
+ * **every** active filter (AND). Filters that aren't set are skipped, so an empty state returns all rows.
+ * Pure — no React, no mutation.
+ */
+export declare function applyFilters<T>(rows: T[], filters: TableFilter[], state: TableFilterState): T[];
+/**
+ * Serialize the active filters into **server-request** params (folded into `state.query` alongside
+ * page/size/search/sort). Each filter uses its `queryKey ?? key`; scalars emit `param=value`, a
+ * `multiSelect` emits repeated / CSV / indexed params (`multiSelectFormat`), and ranges emit two params
+ * `<param><rangeMinSuffix>` / `<param><rangeMaxSuffix>` (defaults `Min`/`Max`) — only for the set bound.
+ * Config-driven via the shared `TableQueryConfig`; inactive filters are skipped.
+ */
+export declare function buildFilterQuery(filters: TableFilter[], state: TableFilterState, mapping?: TableQueryConfig): URLSearchParams;
+/**
+ * Read the active filter values back out of URL / request params — the **inverse of `buildFilterQuery`** for
+ * the same `mapping` + filter defs (each filter's `queryKey ?? key`, the `multiSelectFormat`, the range
+ * suffixes). Used by `<Table>` to restore URL-synced filters on mount / Back-Forward. Only present params
+ * produce a value; the rest stay unset.
+ */
+export declare function parseFilterQuery(filters: TableFilter[], params: URLSearchParams, mapping?: TableQueryConfig): TableFilterState;