@akshar-technosoft/ui 1.0.24 → 1.1.0

package/dist/index.d.ts

@@ -1,29 +1,818 @@
-export { DataTable } from './components/data/data-table/data-table.js';
-export { DataTableActionBar, DataTableActionBarAction, DataTableActionBarSelection } from './components/data/data-table/data-table-action-bar.js';
-export { DataTableProps, GroupColumnDef } from './components/data/data-table/data-table-types.js';
-export { DataTemplate } from './components/data/data-template/data-template.js';
-export { DataTemplateProps } from './components/data/data-template/data-template-types.js';
-export { DataTemplateActionBar, DataTemplateActionBarAction, DataTemplateActionBarSelection } from './components/data/data-template/data-template-action-bar.js';
-export { AppMetaProvider, createTypedAppMetaContext } from './context/app-meta/context.js';
-export { createPageTemplateHook } from './context/app-meta/hooks.js';
-export { AppMeta } from './context/app-meta/types.js';
-export { createLayoutComponents } from './components/layouts/factories.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Table, ColumnDef, Row } from '@tanstack/react-table';
+import { LucideIcon } from 'lucide-react';
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import * as React$1 from 'react';
+import React__default, { ReactNode } from 'react';
+import { VariantProps } from 'class-variance-authority';
+import { motion } from 'framer-motion';
+import { RegisteredRoutes } from '@akshar-technosoft/router';
 export { GeneralHelper } from './components/general.js';
-export { ErrorComponent } from './components/core/error.js';
-export { CurrencyTransfer } from './components/core/event-success.js';
-export { Loader } from './components/core/loader.js';
-export { NotFound } from './components/core/notfound.js';
-export { OfflineUI } from './components/core/offline-content.js';
-export { Unauthorized } from './components/core/unauthorized.js';
-import 'react/jsx-runtime';
-import './components/ui/button.js';
-import 'class-variance-authority/types';
-import 'react';
-import 'class-variance-authority';
-import '@tanstack/react-table';
-import 'framer-motion';
-import 'lucide-react';
-import './components/layouts/app-container.js';
-import './components/layouts/app-header.js';
-import './components/layouts/app-content.js';
-import './components/layouts/app-footer.js';
+
+/**
+ * Storage for the DataTable `persist` feature: filter values, global search text, external
+ * (server) filter values and pagination survive unmount/back-navigation — in-memory by default,
+ * optionally localStorage (`local: true`).
+ *
+ * Values are stored per FILTER IDENTITY (`key`/`id`), not as raw TanStack state — that's what
+ * lets a `shared` slot apply across pages even when the pages use different filter keys or one
+ * side is an `externalSearch` filter.
+ */
+/**
+ * Augment this interface ONCE in the app to get autocomplete + typo checking for `group` and
+ * `shared` (without it both are plain strings):
+ * ```ts
+ * // src/types/table-persist.d.ts
+ * declare module "@akshar-technosoft/ui" {
+ *   interface PersistGroupRegistry { inhouse: "party" | "material"; sales: "party" }
+ * }
+ * ```
+ */
+interface PersistGroupRegistry {
+}
+type PersistGroupId = keyof PersistGroupRegistry extends never ? string : keyof PersistGroupRegistry & string;
+type PersistSlotId = keyof PersistGroupRegistry extends never ? string : PersistGroupRegistry[keyof PersistGroupRegistry] & string;
+type PersistConfig = {
+    /**
+     * Unique id for this table ACROSS THE WHOLE APP (it's the storage map key, and the
+     * localStorage key when `local: true`). Two tables with the same key share one saved state —
+     * that's a bug unless you meant it. One page with two tables needs two keys.
+     */
+    key: string;
+    /**
+     * Namespace for `shared` filter slots — ONLY tables with the same group exchange those values
+     * (a "party" slot in group "inhouse" never leaks into group "sales"). Required for `shared`
+     * to do anything; a `shared` filter on a table without a group is inert (dev warning).
+     */
+    group?: PersistGroupId;
+    /**
+     * Also write to localStorage so state survives refresh/re-login.
+     * NOTE: unlike zustand's `persist` middleware, the default here is IN-MEMORY (back-navigation
+     * only); localStorage is the opt-in. Multi-client caveat: localStorage is per-browser, not
+     * per-login — a client switch on the same machine sees the previous client's saved filters.
+     * @default false
+     */
+    local?: boolean;
+    /** Set false to persist filters only, not page index/size. @default true */
+    pagination?: boolean;
+};
+/**
+ * Persisted external (server) filter values for a table key — use in the PAGE's query-params
+ * initializer so the very first request already carries the restored filters (otherwise the
+ * default request fires once and is immediately superseded by the replayed one):
+ * ```ts
+ * const [params, setParams] = useState(() => ({ Status: "Completed", ...mapToParams(readPersistedExternal("qc-completed")) }))
+ * ```
+ */
+declare function readPersistedExternal(key: string): Record<string, unknown>;
+
+type TableExportColumn = {
+    /** The column's id (accessorKey for accessor columns). */
+    id: string;
+    /** Header text: `exportHeader` if given, else the string `header`, else the id. */
+    header: string;
+};
+/**
+ * A plain, file-format-agnostic snapshot of what the table is currently showing: the visible
+ * columns in display order and every row that survives the active filters and sorting (all pages,
+ * not just the one on screen). Hand it to an app-side writer (Excel, CSV, print) — the table never
+ * touches file generation itself, so the component stays free of heavy spreadsheet dependencies.
+ */
+type TableExportView<TData = unknown> = {
+    columns: TableExportColumn[];
+    /** One array per row, cell values in `columns` order. Values keep their native type (number,
+     *  Date, boolean…) so the writer can apply proper cell formatting instead of dumping strings. */
+    rows: unknown[][];
+    /** The filtered + sorted row originals, same order as `rows`, for writers that want raw data. */
+    originals: TData[];
+};
+/**
+ * Build a {@link TableExportView} from the table's CURRENT state, exactly as the user shaped it:
+ * hidden columns are skipped, column order (including pinning) is respected, and rows come from the
+ * pre-pagination model, so they are filtered and sorted but not cut to the visible page.
+ *
+ * Which columns make it in: a visible column is exported when it has an accessor (accessorKey or
+ * accessorFn) or a `exportValue` on its def. Display-only columns (actions, JSX-composed cells
+ * without an accessor) are skipped unless they provide `exportValue`. A JSX `header` falls back to
+ * the column id unless `exportHeader` names it.
+ *
+ * Call it anywhere you hold the table instance (from `onTableReady` or the `children` render prop);
+ * the toolbar's Export button calls it for you and passes the result to `onExport`.
+ */
+declare function getTableExportView<TData>(table: Table<TData>): TableExportView<TData>;
+
+type Paths<T, Prefix extends string = ''> = T extends object ? {
+    [K in keyof T]: K extends string ? T[K] extends object ? Paths<T[K], `${Prefix}${K}.`> | `${Prefix}${K}` : `${Prefix}${K}` : never;
+}[keyof T] : never;
+type NumericKeys<T> = {
+    [K in keyof T]: T[K] extends number ? K : never;
+}[keyof T];
+type AggregationConfigMap<TData> = {
+    [K in NumericKeys<TData>]?: AggregationConfig<TData>;
+} & {
+    [key: string]: AggregationConfig<TData> | undefined;
+};
+type AggregationFunction = 'sum' | 'average' | 'min' | 'max' | 'count' | 'unique' | 'median';
+type AggregationConfig<TData> = {
+    enabled: boolean;
+    functions?: AggregationFunction[];
+    format?: (value: any, func: AggregationFunction) => string;
+    accessor?: (row: TData) => number | null;
+};
+/** Fields shared by every filter control, independent of how it locates its value. */
+type FilterControlConfig = {
+    /** Input placeholder and the filter's display label (also used on chips and the grouped picker). */
+    placeholder: string;
+    /**
+     * Which control to render and how the value is entered. Set it to match the field's shape so the
+     * user gets the right input:
+     *   `'text'` (the default) is a free text box, matched as a case insensitive contains.
+     *   `'select'` is a dropdown of fixed choices; it requires `options`, and the picked value is
+     *   matched as given (use it for status, yes/no, category style fields).
+     *   `'date'` is a single date picker; `'daterange'` is a from/to range picker. Both accept `dateFormat`.
+     *   `'number'` is a numeric input.
+     * @default "text"
+     */
+    type?: "text" | "select" | "date" | "daterange" | "number";
+    /** Choices for `type: "select"`. Each `value` is what the filter matches; `label` is what the
+     *  user sees. Required when `type` is `"select"`; ignored otherwise. */
+    options?: {
+        label: string;
+        value: string;
+    }[];
+    /** Tailwind width class for the control wrapper (e.g. `"max-w-[150px]"`). */
+    width?: string;
+    /** Leading icon inside the control. */
+    icon?: LucideIcon;
+    /**
+     * Run this filter on the server instead of the local data. When set, the filter's value is NOT
+     * applied to the in-memory rows; instead it is collected and handed to `onExternalSearch(values)`
+     * so the parent can re-query the API. The call fires automatically at the control's natural commit
+     * point: a `select` on pick, a `date`/`daterange` on Apply, and a `text` box after a short debounce.
+     */
+    externalSearch?: boolean;
+    /** date-fns format string for displaying the selected date(s), e.g. "dd MMM yyyy". */
+    dateFormat?: string;
+    /**
+     * Where this filter's control is placed inside the toolbar. Both variants require
+     * `settings.showToolbar: true`, because every filter lives in the toolbar; with the toolbar off no
+     * filter renders at all, whatever its placement.
+     *
+     * `'bar'` (the default) sits inline on the toolbar's left row and is always visible. Use it for the
+     * few primary filters you combine constantly (for example product and category), so they stay side
+     * by side.
+     *
+     * `'menu'` keeps the control off the bar: it becomes an option in the global search's field
+     * picker (which appears automatically when `enableGlobalFilter` is on and any `'menu'` filter
+     * exists), and while it holds a value it shows as a removable chip on the bar. Use it so many
+     * filters don't fill the toolbar with boxes.
+     *
+     * @default 'bar'
+     */
+    placement?: "bar" | "menu";
+    /**
+     * Share this filter's VALUE across every page whose table has the same `persist.group`, under
+     * this slot name (e.g. `shared: "party"` — search a party on one page, the next page in the
+     * group opens already filtered to it). The slot stores only the value, so pages can bind it to
+     * different filter keys, or even to an `externalSearch` filter. Requires `persist.group`.
+     */
+    shared?: PersistSlotId;
+    /**
+     * Set false to exclude this one filter from persistence (scan boxes, one-shot searches) while
+     * the rest of the table persists. Inert without the table-level `persist` prop. @default true
+     */
+    persist?: boolean;
+};
+/**
+ * A filter bound to a real data field by its path. Use this form (the common one) whenever the value
+ * you filter on is a plain field on the row, flat or nested.
+ *
+ * `key` is a dot path into the row, validated against `T`, and doubles as the filter's identity. How
+ * it filters depends on whether a column already owns that path:
+ *   If a visible column has the same `accessorKey`, the filter drives that column with TanStack's
+ *   built in case insensitive contains match. This is the normal, zero setup case.
+ *   If no column owns the path (the field is only shown inside another cell, for example a "SKU and
+ *   Category" cell that prints three fields), the table auto generates a hidden, filter only column
+ *   for it so the same contains match still works. You do not touch the `columns` array.
+ *
+ * Reach for {@link CustomFilterConfig} instead only when the match is not a plain contains on one
+ * field, for example matching inside an array of objects or across several fields at once.
+ */
+type PathFilterConfig<T> = FilterControlConfig & {
+    /** Dot path into the row (validated against `T`). Serves as both the value source and the id. */
+    key: Paths<T>;
+    id?: never;
+    filterFn?: never;
+};
+/**
+ * A filter that owns its matching logic. Use this form when the value is not a plain field, for
+ * example a cell holding an array of objects, or when one control should match across several fields.
+ *
+ * You provide `filterFn(row, value)`, which receives the whole row (so it can read any field or
+ * array) and returns whether the row passes. The table wires it to an auto generated hidden, filter
+ * only column, so it runs inside TanStack's normal filtering and AND combines with every other
+ * filter; you never touch the `columns` array. `id` is any unique string that identifies this filter
+ * (it does not need to be a real field, because `filterFn` reads the row itself).
+ *
+ * @example
+ * // Match if ANY lot in the row's array has a matching number, and (separately) if any is urgent.
+ * const filters = [
+ *   { id: "lotNo", type: "text", placeholder: "Lot No",
+ *     filterFn: (row, v) => row.lots.some(l => String(l.lotNo).toLowerCase().includes(String(v).toLowerCase())) },
+ *   { id: "urgentOnly", type: "select", placeholder: "Urgent", options: [{ label: "Urgent", value: "1" }],
+ *     filterFn: (row, v) => !v || row.lots.some(l => l.isUrgent) },
+ * ];
+ */
+type CustomFilterConfig<T> = FilterControlConfig & {
+    /** Any unique string identifying this filter. Not required to be a real field, since `filterFn`
+     *  reads the row directly. */
+    id: string;
+    /** Predicate deciding whether a row passes. Receives the full row and the current filter value. */
+    filterFn: (row: T, value: any) => boolean;
+    key?: never;
+};
+/**
+ * One toolbar filter control. Pick the form by how the value is located:
+ *   {@link PathFilterConfig} — pass `key` (a real dot path). The common case: flat or nested fields.
+ *   {@link CustomFilterConfig} — pass `id` + `filterFn`. For arrays of objects or multi field matches.
+ * Either way the filtering runs through TanStack's model and AND combines; you never edit `columns`.
+ */
+type FilterConfig<T> = PathFilterConfig<T> | CustomFilterConfig<T>;
+type PaginationConfig = {
+    /** Rows per page initially. @default 10 */
+    pageSize?: number;
+    /** Options in the "Rows" selector. `-1` renders "All". Pass `[]` to hide the selector.
+     *  @default [10, 25, 50, 100, -1] */
+    pageSizeOptions?: number[];
+    /** Show the "Showing X to Y of Z" range text. @default true */
+    showInfo?: boolean;
+    /** Show numbered page buttons (with ellipsis window); otherwise just prev/next. @default false */
+    showPageNumbers?: boolean;
+};
+/**
+ * Feature and presentation toggles for the table. Every field is optional and its default is noted.
+ * Many flags are inert unless a "master" flag is also on, and that coupling is the usual reason a
+ * setting appears to do nothing. The master relationships:
+ *
+ *   `showToolbar` owns everything drawn in the toolbar row (global search, the whole `filters` UI, the
+ *   Columns menu, the Aggregations menu, Export, Refresh, the bulk pin actions). The per column sort
+ *   and pin menus are drawn in the header instead, so they keep working when `showToolbar` is off.
+ *
+ *   `enableFiltering` owns the filter engine. `enableGlobalFilter` can still render its box but will
+ *   not remove any rows while `enableFiltering` is off.
+ *
+ *   `enableRowSelection` owns the select column. `selectionMode`, `showCheckbox`,
+ *   `enableHeaderCheckbox` and `fixedCheckboxColumn` are all inert without it.
+ *
+ *   `enableColumnPinning` owns pinning, which `fixedCheckboxColumn` depends on.
+ *
+ *   The global search's field picker appears automatically when `enableGlobalFilter` is on and
+ *   any filter has `placement: 'menu'` — there is no separate flag for it.
+ */
+type TableSettings = {
+    /**
+     * Render the column header row. Turning it off also removes sorting, the pin menu and resize
+     * handles (they live in the header) even when their flags are on. Suited to compact read-only
+     * lists.
+     * @default true
+     */
+    showHeader?: boolean;
+    /**
+     * Allow sorting. Clicking a sortable header cycles asc → desc → clear, and each header cell's "⋯"
+     * menu offers the same actions explicitly; an arrow at the header's right edge shows the active
+     * direction. Clicks on interactive elements inside custom JSX headers do not sort. The serial
+     * "No." column sorts on its display index, so sorting it is rarely meaningful.
+     * @default true
+     */
+    enableSorting?: boolean;
+    /**
+     * Render the toolbar row above the table. This is the largest master switch: with it off you lose
+     * the global search, the entire `filters` UI (both bar filters and the "Filters" menu), the Columns
+     * menu, the Aggregations menu, Export, Refresh and the bulk pin actions, because all of them are
+     * hosted here. The header's own per column menus are unaffected. Enable it for data heavy screens; leave it off for display-only tables.
+     * @default false
+     */
+    showToolbar?: boolean;
+    /**
+     * Placement of the toolbar relative to the card. `'default'` renders it outside and above the card.
+     * `'above-header'` and `'below-header'` render it inside the card as a sticky band that stacks with
+     * the optional `header` prop; the component measures these bands at runtime to compute the header's
+     * sticky offset. Only relevant while `toolbar` is on.
+     * @default 'default'
+     */
+    toolbarPosition?: 'above-header' | 'below-header' | 'default';
+    /**
+     * Install the filter row model. This is the engine both column filters and the global search run
+     * on, so it is the real on and off for filtering: with it off a search box can render but no rows
+     * are removed. Aggregations compute over the filtered rows, so they see the full data set when this
+     * is off.
+     * @default true
+     */
+    enableFiltering?: boolean;
+    /**
+     * Show the global search box. It matches a row's accessor columns only, with a case insensitive
+     * contains test, so a column rendered purely through `cell` with no `accessorKey` or `accessorFn`
+     * is invisible to it; give such a column an `accessorFn` to make it searchable. Needs `showToolbar` to
+     * appear and `enableFiltering` to actually narrow rows.
+     * @default true
+     */
+    enableGlobalFilter?: boolean;
+    /**
+     * Show the "Columns" menu that toggles column visibility. Columns marked `enableHiding: false` (the
+     * serial and select helpers) never appear in it, and grouped columns are listed under their group
+     * heading. It is part of the toolbar, so it needs `showToolbar` to be visible.
+     * @default true
+     */
+    enableColumnVisibility?: boolean;
+    /**
+     * Add the leading selection column and turn on row selection. Selection is enforced at the table
+     * level against `isRowSelectable`, so those rows cannot be caught even by select all, and
+     * `onRowSelectionChange` reports only genuinely selectable rows. Master for the whole
+     * selection group below.
+     * @default true
+     */
+    enableRowSelection?: boolean;
+    /**
+     * Allow the user to drag column widths. Resizing runs live and the handles sit on the right edge of
+     * each header cell, so `showHeader: false` removes the ability to resize. A pinned column is locked
+     * to its size, so if you also pin, resize the column first and pin afterwards.
+     * @default false
+     */
+    enableColumnResizing?: boolean;
+    /**
+     * Master switch for sticky pinned columns. The serial and select columns are always pinned left and
+     * re-pinned on every change so they cannot drift. Users pin one column from the header's "⋯" menu
+     * (works without the toolbar) or in bulk from the toolbar's settings menu. A pinned column is
+     * clamped to its rendered width so its content cannot push it wider and break the sticky offsets.
+     * @default true
+     */
+    enableColumnPinning?: boolean;
+    /**
+     * The header's select-all checkbox. Set false to grey it out while keeping per-row checkboxes
+     * usable (select-all too costly/dangerous, manual multi-select still wanted). Only meaningful
+     * in `'multiple'` mode.
+     * @default true
+     */
+    enableHeaderCheckbox?: boolean;
+    /**
+     * Lock the select column in place by hiding its pin menu so users cannot move or unpin it. Needs
+     * `enableRowSelection` and `enableColumnPinning`.
+     * @remarks Half wired today: `onColumnPinningChange` re-pins the select column to the left on every
+     * change regardless of this flag, so setting it `false` only exposes a pin menu whose Unpin has no
+     * effect.
+     * @default true
+     */
+    fixedCheckboxColumn?: boolean;
+    /**
+     * Show the leading "No." column. It prints the row's position in the current view (`index + 1`), so
+     * it renumbers as you sort, filter or page and is not a stable record id. When any aggregation is
+     * enabled its footer cell shows the total row count.
+     * @default true
+     */
+    showSerialNumbers?: boolean;
+    /**
+     * Zebra stripe alternate rows for readability. The stripe follows a row's position on the current
+     * page, so the pattern stays consistent as you page through the data.
+     * @default true
+     */
+    striped?: boolean;
+    /**
+     * Highlight the row under the cursor. Selected rows keep a stronger background of their own, so the
+     * hover and selected states stay distinguishable.
+     * @default true
+     */
+    hoverable?: boolean;
+    /**
+     * Compact density. Tightens the vertical padding across header, body and footer cells so more rows
+     * fit on screen. Turn it off for a roomier, more touch friendly layout.
+     * @default true
+     */
+    compact?: boolean;
+    /**
+     * Draw cell separators. Interior columns get a right border, while the last column and the last
+     * unpinned column before a right pinned group intentionally drop theirs, so the border never doubles
+     * against a pinned column's sticky separator.
+     * @default true
+     */
+    bordered?: boolean;
+    /**
+     * Let the table card flex to fill its parent's height, which only takes effect inside a parent that
+     * has a bounded height. Pair it with `maxHeight` so the body scrolls while the header and footer
+     * stay sticky. Use it for full page tables.
+     * @default false
+     */
+    fullHeight?: boolean;
+    /**
+     * Selection style. `'multiple'` shows checkboxes plus a select all header checkbox. `'single'` shows
+     * a radio, makes the whole row clickable, and selecting a row clears any previous selection. Needs
+     * `enableRowSelection`.
+     * @default "multiple"
+     */
+    selectionMode?: "single" | "multiple";
+    /**
+     * In `'single'` mode, whether to draw the radio control at all. With it `false` the radio is hidden
+     * but the row stays clickable, which suits designs that select by clicking the row itself. No effect
+     * in `'multiple'` mode.
+     * @default true
+     */
+    showCheckbox?: boolean;
+    /**
+     * Show removable chips on the toolbar for applied `placement: 'menu'` filters, so collapsed
+     * filters stay visible while active. Turn off if the bar gets cluttered — active menu filters
+     * are then only visible through their control in the search field picker.
+     * @default true
+     */
+    showFilterChips?: boolean;
+    /**
+     * Label on the global search's field picker while "all fields" is selected. The picker itself
+     * appears automatically when `enableGlobalFilter` is on and at least one filter has
+     * `placement: 'menu'`. @default "Global"
+     */
+    groupedFilterLabel?: string;
+};
+type ColumnFooter<TData> = {
+    content?: React.ReactNode | ((table: Table<TData>) => React.ReactNode);
+    align?: 'left' | 'center' | 'right';
+    className?: string;
+};
+type TableHeaderProps = {
+    content: React.ReactNode;
+    align?: 'left' | 'center' | 'right';
+    className?: string;
+    showOnEmpty?: boolean;
+};
+type GroupColumnDef<TData> = ColumnDef<TData> & {
+    columns?: GroupColumnDef<TData>[];
+    enablePinning?: boolean;
+    headerAlign?: 'left' | 'center' | 'right';
+    customFooter?: ColumnFooter<TData>;
+    /**
+     * Value this column contributes to an export (see `getTableExportView`). Without it the export
+     * uses the column's accessor value, which covers plain columns; provide it when the cell renders
+     * a JSX composite (several fields in one cell) so the export gets a flat printable value instead
+     * of losing the column, and on display-only columns (no accessor) that should still export.
+     * Return native types (number, Date…) so the writer can format cells properly.
+     * @example exportValue: (row) => `${row.RefNo} (${row.RefDate})`
+     */
+    exportValue?: (row: TData) => unknown;
+    /**
+     * Header text used in exports when `header` is JSX and therefore unprintable. A plain string
+     * `header` is used as-is and does not need this.
+     */
+    exportHeader?: string;
+};
+type DataTableProps<TData> = {
+    /** Row data. Rendered client-side (filter/sort/paginate all in-memory unless server-driven). */
+    data: TData[];
+    /** Column definitions. TanStack `ColumnDef` plus a few extras; see {@link GroupColumnDef}. */
+    columns: GroupColumnDef<TData>[];
+    /** Toolbar filter controls (see {@link FilterConfig}); place each on the bar or behind the global
+     *  search's field picker via `FilterConfig.placement`. Debug: filters live in the toolbar, so none
+     *  render unless `settings.showToolbar: true`. */
+    filters?: FilterConfig<TData>[];
+    /** Pagination config — its presence enables pagination. Omit to render all rows. */
+    pagination?: PaginationConfig;
+    /** Feature and presentation toggles; see {@link TableSettings} for the full dependency map. */
+    settings?: TableSettings;
+    /** Title/header area above the table. Plain node, or {@link TableHeaderProps} for alignment control. */
+    header?: React.ReactNode | TableHeaderProps;
+    /** Sticky footer content (spans full width). */
+    footer?: React.ReactNode;
+    /** Extra class on the outer wrapper. */
+    className?: string;
+    /** Max height of the scroll container (enables sticky header/footer). @default "100%" */
+    maxHeight?: string;
+    /** Show the loading overlay. @default false */
+    loading?: boolean;
+    /** Error message. When set it replaces the table with an error card, which also offers Try Again
+     *  when `onRefresh` is given. */
+    error?: string;
+    /** Text shown when there are no rows. @default "No data available" */
+    emptyMessage?: string;
+    /** Fires with the selected row originals whenever selection changes. Requires `enableRowSelection`.
+     *  @remarks Unselectable rows (see `isRowSelectable`) are filtered out. */
+    onRowSelectionChange?: (selectedRows: TData[]) => void;
+    /**
+     * Called by the toolbar Export button. `data` is the filtered + sorted row originals (all pages,
+     * not just the visible one) and `view` is the ready-to-write snapshot of the visible columns and
+     * cell values (see `getTableExportView` — call it yourself via `onTableReady` for export buttons
+     * that live outside the toolbar). Feed `view` to the app's Excel/CSV writer.
+     */
+    onExport?: (data: TData[], view: TableExportView<TData>) => void;
+    /** Called by the toolbar Refresh button (and the error card's Try Again). */
+    onRefresh?: () => void;
+    /** Escape hatch that hands you the TanStack `table` instance for imperative control. */
+    onTableReady?: (table: Table<TData>) => void;
+    /** Render-prop for an action bar etc.; receives the `table` instance. */
+    children?: (table: Table<TData>) => React.ReactNode;
+    /** Return false to make a row unselectable: its checkbox greys out, select-all skips it and
+     *  `onRowSelectionChange` never reports it. The row itself stays fully visible and interactive. */
+    isRowSelectable?: (row: TData) => boolean;
+    /**
+     * Returns a **stable, unique id for a row**, derived from your own data. Forwarded straight to
+     * TanStack's `getRowId`. You are not assigning an id — you point at the field(s) that already
+     * uniquely identify the record, and TanStack calls this to read it.
+     *
+     * **Why it matters:** without it, selection (and expansion/pinning) is keyed by the row's *index in
+     * the `data` array*. That is fine as long as the array never changes, but the moment `data` is
+     * replaced or reordered — a refetch, a tab switch to a different list, an insert/delete that shifts
+     * everything after it — index `2` now points at a different record, so the wrong rows appear
+     * selected. With `getRowId`, selection is keyed by the record itself and survives all of that.
+     *
+     * (Client-side sort / filter / pagination alone do **not** need this — they don't mutate the `data`
+     * array, so index-based ids stay correct. It's specifically array replacement/reordering that breaks.)
+     *
+     * **When to pass it:** any table that has row selection *and* whose `data` can be refetched,
+     * reordered, or have rows added/removed. Also **required** for `defaultSelectedRows` to target rows
+     * reliably. Display-only or never-refetched tables can omit it.
+     *
+     * Pick field(s) guaranteed unique per row; combine with `-` when no single field is unique.
+     * @example getRowId={(row) => String(row.id)}
+     * @example getRowId={(row) => `${row.Code}-${row.Type}`}  // unique only as a pair
+     */
+    getRowId?: (row: TData, index: number) => string;
+    /**
+     * **Uncontrolled prefill.** Return `true` for rows that should start already selected. The table
+     * keeps owning selection state afterwards — this only seeds the initial value (same idea as
+     * `<input defaultChecked>`), so you do not have to manage a controlled selection yourself.
+     *
+     * **Timing:** seeded exactly once, after the first non-empty `data` load (so it works even when data
+     * arrives async). It is *not* re-run on later data changes — that would wipe the user's own
+     * selections on every refetch. To deliberately re-seed for a new dataset (e.g. switching tabs),
+     * remount the table with a React `key`.
+     *
+     * **Safety:** only rows the table considers selectable are seeded — a row failing `isRowSelectable`
+     * is skipped, so prefill can never select an unselectable row. Setting selection here
+     * flows through the normal path, so `onRowSelectionChange`, the action bar, and any
+     * "disable others once one is selected" logic react exactly as they do for a real user click.
+     *
+     * **Pair with `getRowId`** so the seeded rows are matched by record, not by array position.
+     * @example defaultSelectedRows={(row) => row.WasPreviouslyPicked}
+     */
+    defaultSelectedRows?: (row: TData) => boolean;
+    /** Server side search callback. Receives the staged external filter values when the Search button
+     *  is pressed; run your query here. */
+    onExternalSearch?: (filters: Record<string, any>) => void;
+    /** Column aggregations (footer sums / averages / counts …), parent-controlled. The footer row
+     *  appears whenever any column's config is `enabled`. Debug: the toolbar's Aggregations menu (to
+     *  toggle them from the UI) additionally needs `onAggregationChange` + `settings.showToolbar` + at
+     *  least one numeric column. @see AggregationConfigMap */
+    aggregations?: AggregationConfigMap<TData>;
+    /** Fires when the user toggles an aggregation in the toolbar menu; persist it into your
+     *  `aggregations` state (the component does not own it). Without this the toggle menu is hidden. */
+    onAggregationChange?: (columnId: string, config: AggregationConfig<TData>) => void;
+    /** Per-row className (e.g. status-based row colouring). */
+    rowClassName?: (row: Row<TData>) => string;
+    /**
+     * Persist this table's filters, global search, external filter values and pagination across
+     * unmount/back-navigation. In-memory by default (refresh = fresh); `local: true` adds
+     * localStorage. String shorthand = `{ key }`. Absent = no persistence (today's behaviour).
+     * Restore is synchronous (seeded before first render — no unfiltered flash); external filters
+     * are replayed through `onExternalSearch` on mount (see `readPersistedExternal` to seed the
+     * page's own query instead). Selection is never persisted. See {@link PersistConfig}.
+     * @example persist="qc-completed"
+     * @example persist={{ key: "qc-completed", group: "inhouse", local: true }}
+     */
+    persist?: string | PersistConfig;
+};
+
+declare function DataTable<T>({ data, columns: initialColumns, filters, pagination, settings, header, footer, className, maxHeight, loading, error, emptyMessage, onRowSelectionChange, onExport, onRefresh, onTableReady, children, isRowSelectable, getRowId, defaultSelectedRows, onExternalSearch, aggregations, onAggregationChange, rowClassName, persist: persistProp, }: DataTableProps<T>): react_jsx_runtime.JSX.Element;
+
+declare const buttonVariants: (props?: ({
+    variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | null | undefined;
+    size?: "default" | "sm" | "lg" | "icon" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+declare function Button({ className, variant, size, asChild, ...props }: React$1.ComponentProps<"button"> & VariantProps<typeof buttonVariants> & {
+    asChild?: boolean;
+}): react_jsx_runtime.JSX.Element;
+
+interface DataTableActionBarProps<TData> extends React$1.ComponentProps<typeof motion.div> {
+    table: Table<TData> | null;
+    visible?: boolean;
+    container?: Element | DocumentFragment | null;
+    children: React$1.ReactNode;
+}
+declare function DataTableActionBar<TData>({ table, visible: visibleProp, container: containerProp, children, className, ...props }: DataTableActionBarProps<TData>): React$1.ReactPortal | null;
+interface DataTableActionBarActionProps extends React$1.ComponentProps<typeof Button> {
+    tooltip?: string;
+    isPending?: boolean;
+}
+declare function DataTableActionBarAction({ size, tooltip, isPending, disabled, className, children, ...props }: DataTableActionBarActionProps): react_jsx_runtime.JSX.Element;
+interface DataTableActionBarSelectionProps<TData> {
+    table: Table<TData> | null;
+}
+declare function DataTableActionBarSelection<TData>({ table }: DataTableActionBarSelectionProps<TData>): react_jsx_runtime.JSX.Element | null;
+
+type DataTemplateField<T> = {
+    key: keyof T;
+    label: string;
+    type?: "text" | "number" | "date" | "boolean";
+    sortable?: boolean;
+    filterable?: boolean;
+    searchable?: boolean;
+};
+type DataTemplateFilter<T> = {
+    key: keyof T;
+    label: string;
+    type: "text" | "select" | "date" | "number" | "boolean";
+    options?: {
+        label: string;
+        value: string;
+    }[];
+    placeholder?: string;
+    icon?: LucideIcon;
+};
+type DataTemplatePagination = {
+    pageSize?: number;
+    pageSizeOptions?: number[];
+    showInfo?: boolean;
+    showPageNumbers?: boolean;
+};
+type DataTemplateSettings = {
+    enableSorting?: boolean;
+    enableFiltering?: boolean;
+    enableGlobalSearch?: boolean;
+    enableSelection?: boolean;
+    enableExport?: boolean;
+    showToolbar?: boolean;
+    selectionMode?: "single" | "multiple";
+    gridCols?: {
+        default: number;
+        sm?: number;
+        md?: number;
+        lg?: number;
+        xl?: number;
+        "2xl"?: number;
+    };
+    gap?: number;
+    aspectRatio?: "square" | "video" | "auto" | string;
+    minCardWidth?: number;
+    maxCardWidth?: number;
+};
+type DataTemplateType<T> = (item: T, index: number, isSelected: boolean, onToggleSelect: () => void) => ReactNode;
+type DataTemplateProps<T> = {
+    data: T[];
+    template: DataTemplateType<T>;
+    fields: DataTemplateField<T>[];
+    filters?: DataTemplateFilter<T>[];
+    pagination?: DataTemplatePagination;
+    settings?: DataTemplateSettings;
+    header?: ReactNode;
+    footer?: ReactNode;
+    className?: string;
+    loading?: boolean;
+    error?: string;
+    emptyMessage?: string;
+    emptyIcon?: ReactNode;
+    onSelectionChange?: (selectedItems: T[]) => void;
+    onExport?: (data: T[]) => void;
+    onRefresh?: () => void;
+    onTemplateReady?: (controller: DataTemplateController<T>) => void;
+    children?: (controller: DataTemplateController<T>) => ReactNode;
+};
+type DataTemplateController<T> = {
+    getSelectedItems: () => T[];
+    clearSelection: () => void;
+    selectAll: () => void;
+    getFilteredData: () => T[];
+    getTotalCount: () => number;
+    getVisibleCount: () => number;
+    refresh: () => void;
+    exportData: () => void;
+};
+type DataTemplateActionBarProps<T> = {
+    controller: DataTemplateController<T>;
+    visible?: boolean;
+    container?: Element | DocumentFragment | null;
+    children: React__default.ReactNode;
+    className?: string;
+};
+type DataTemplateActionBarActionProps = {
+    tooltip?: string;
+    isPending?: boolean;
+    size?: "sm" | "icon";
+    variant?: "default" | "secondary" | "outline" | "ghost";
+    disabled?: boolean;
+    className?: string;
+    children: React__default.ReactNode;
+    onClick?: () => void;
+};
+
+declare function DataTemplate<T extends Record<string, any>>({ data, template, fields, filters, pagination, settings, header, footer, className, loading, error, emptyMessage, emptyIcon, onSelectionChange, onExport, onRefresh, onTemplateReady, children, }: DataTemplateProps<T>): react_jsx_runtime.JSX.Element;
+
+declare function DataTemplateActionBar<T>({ controller, visible: visibleProp, container: containerProp, children, className, ...props }: DataTemplateActionBarProps<T> & React$1.ComponentProps<typeof motion.div>): React$1.ReactPortal | null;
+declare function DataTemplateActionBarAction({ size, variant, tooltip, isPending, disabled, className, children, onClick, ...props }: DataTemplateActionBarActionProps): react_jsx_runtime.JSX.Element;
+interface DataTemplateActionBarSelectionProps<T> {
+    controller: DataTemplateController<T>;
+}
+declare function DataTemplateActionBarSelection<T>({ controller }: DataTemplateActionBarSelectionProps<T>): react_jsx_runtime.JSX.Element | null;
+
+type AppContainerProps = {
+    children: ReactNode;
+    className?: string;
+};
+/** Page shell: full-height column, small gap between header/content/footer. */
+declare const AppContainer: ({ children, className }: AppContainerProps) => react_jsx_runtime.JSX.Element;
+
+type AppHeaderProps = {
+    className?: string;
+    title?: ReactNode;
+    description?: string;
+    /** Back arrow button left of the title: navigate via `href` (typed route) or `onClick`. */
+    backAction?: {
+        onClick?: () => void;
+        href?: RegisteredRoutes;
+    };
+    /** Small label/value pairs rendered under the title. */
+    metadata?: {
+        label: string;
+        value: ReactNode;
+    }[];
+    /**
+     * Everything right of the title block. Rendered inside a `flex flex-1
+     * items-center justify-end h-full` row, so content lands at the right edge
+     * vertically centered — no wrapper needed. For a different layout add your
+     * own flex utilities via `childrenClassName` (twMerge, later wins) or a
+     * `<div className="flex-1" />` spacer / `mr-auto` on a child.
+     */
+    children?: ReactNode;
+    /** Extra classes for the children row (e.g. `justify-between gap-2`). */
+    childrenClassName?: string;
+};
+declare const AppHeader: ({ className, title, description, backAction, metadata, children, childrenClassName, }: AppHeaderProps) => react_jsx_runtime.JSX.Element;
+
+type BandProps = {
+    children: React__default.ReactNode;
+    className?: string;
+};
+/**
+ * Pinned band above AppContent's scroll region (border-b, shares the parent's
+ * padding). Must be a DIRECT child of AppContent — it is a marker: AppContent
+ * extracts it and renders the band itself; anything else inside scrolls as body.
+ */
+declare const AppContentHeader: (_props: BandProps) => null;
+/** Pinned band below the scroll region. Same contract as AppContentHeader. */
+declare const AppContentFooter: (_props: BandProps) => null;
+type AppSheetProps = {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** Sheet edge. Default right. */
+    side?: "left" | "right";
+    /** Default true: sheet slides OVER the dimmed body (click outside closes).
+     *  `overlay={false}` = push mode: sheet takes its width, body shrinks.
+     *  Below 1024px push falls back to overlay automatically — a fixed-width
+     *  panel would leave the main content unusably cramped. */
+    overlay?: boolean;
+    /** Merged onto the panel's default `w-[420px] max-w-full` (fixed width, clamps to
+     *  full width on small screens) — override the width (`w-1/3`, `w-[600px]`) or
+     *  add styling (`p-0`). Panel content has an intrinsic comfortable width; the
+     *  MAIN content is the responsive part, not the sheet. */
+    className?: string;
+    children: React__default.ReactNode;
+};
+/**
+ * Side panel of an AppContent. Must be a DIRECT child of AppContent (marker,
+ * same contract as the bands) — one sheet per AppContent. Controlled only.
+ */
+declare const AppSheet: (_props: AppSheetProps) => null;
+type AppContentProps = {
+    children: React__default.ReactNode;
+    className?: string;
+    /** Extra classes for the inner content wrapper (default has `p-2` — pass `p-0` to drop it). */
+    contentClassName?: string;
+};
+/**
+ * Page content region. Fills the remaining space of its flex parent
+ * (`flex-auto min-h-0`) — the standard slot under AppContainer/AppHeader.
+ * For a content-sized block override via className (`flex-none`) or pair with
+ * an explicit height (`h-full`). Children scroll; AppContentHeader/Footer and
+ * AppSheet direct children are extracted and rendered as pinned band / side panel.
+ */
+declare const AppContent: ({ children: rawChildren, className, contentClassName, }: AppContentProps) => react_jsx_runtime.JSX.Element;
+
+type AppFooterProps = {
+    className?: string;
+    /**
+     * Footer content, rendered into a padded flex row. The LAST child is pushed
+     * to the right edge (`[&>*:last-child]:ml-auto`) — actions go last, any
+     * leading children (status text, form fields) sit left with a `gap-4`.
+     * Override per page via className (twMerge, later wins). Renders nothing
+     * without children.
+     */
+    children?: ReactNode;
+};
+declare const AppFooter: ({ className, children }: AppFooterProps) => react_jsx_runtime.JSX.Element | null;
+
+declare const ErrorComponent: () => react_jsx_runtime.JSX.Element;
+
+declare function CurrencyTransfer(): react_jsx_runtime.JSX.Element;
+
+declare const Loader: () => react_jsx_runtime.JSX.Element;
+
+declare const NotFound: () => react_jsx_runtime.JSX.Element;
+
+declare const OfflineUI: () => react_jsx_runtime.JSX.Element;
+
+declare const Unauthorized: () => react_jsx_runtime.JSX.Element;
+
+export { AppContainer, type AppContainerProps, AppContent, AppContentFooter, AppContentHeader, type AppContentProps, AppFooter, type AppFooterProps, AppHeader, type AppHeaderProps, AppSheet, type AppSheetProps, CurrencyTransfer, DataTable, DataTableActionBar, DataTableActionBarAction, DataTableActionBarSelection, type DataTableProps, DataTemplate, DataTemplateActionBar, DataTemplateActionBarAction, DataTemplateActionBarSelection, type DataTemplateProps, ErrorComponent, type GroupColumnDef, Loader, NotFound, OfflineUI, type PersistConfig, type PersistGroupRegistry, type TableExportColumn, type TableExportView, Unauthorized, getTableExportView, readPersistedExternal };