@akshar-technosoft/ui 1.1.0 → 1.1.1

package/README.md

@@ -146,6 +146,8 @@ Required: `placeholder`, plus either `key` (path filter) or `id` + `filterFn` (c
 onExternalSearch={(values) => setSearchFilters(values)}   // feed your query params
 ```
 
+**Why one table-level callback and not per-filter?** A server query is ONE request carrying all params. Every commit hands you the **complete staged map** — with two external filters (say `Date` and `PartyName`), picking a date fires `{ Date: {...} }`, then typing a party fires `{ Date: {...}, PartyName: "xy" }`: both values together, every time. The page builds params in one place and runs one query; any number of external filters just adds keys to the same map. Clearing fires `{}`.
+
 Local and external filters mix freely on one table: external narrows what you fetch, local narrows the fetched rows.
 
 ### Global search & the field picker
@@ -295,7 +297,26 @@ onExport={(data, view) => buildQcExcel(view)}   // Settings menu > Export (item
 const view = getTableExportView(table);
 ```
 
-`TableExportView` = `columns` (visible, display+pin order, select/serial excluded) + `rows` (cell values in column order, native types preserved so writers can format real numbers/dates) + `originals` (filtered+sorted row objects). Rows come from the pre-pagination model: filtered and sorted, ALL pages.
+**What the two arguments are:**
+
+- `data: T[]` — the filtered + sorted **row originals** (your objects, all pages, not just the visible one). It is literally `view.originals` — kept as the first arg so simple handlers can ignore `view`.
+- `view: TableExportView<T>` — the ready-to-write snapshot:
+
+```ts
+{
+  columns: [                       // VISIBLE columns only, in display + pin order,
+    { id: "FullCPOSrNo", header: "Order No." },   // select/serialNumber excluded;
+    { id: "Qty",         header: "Qty" },         // header = exportHeader ?? string header ?? id
+  ],
+  rows: [                          // one array per row, values in `columns` order,
+    ["CPO-101", 250],              // native types kept (number/Date/boolean — real
+    ["CPO-102", 480],              // Excel cells, not strings)
+  ],
+  originals: [ {...}, {...} ],     // same rows as objects, same order as `rows`
+}
+```
+
+Rows come from the pre-pagination model: filtered and sorted, ALL pages. Typical writer: header row from `view.columns.map(c => c.header)`, data rows straight from `view.rows`; reach into `view.originals` when the sheet needs fields that aren't visible columns.
 
 A column is included when it has an accessor or `exportValue`. Display-only columns are skipped unless `exportValue` supplies a flat value — also the tool for JSX composite cells:
 
@@ -338,7 +359,56 @@ Taxonomy: `show*` = a UI element/region is visible · `enable*` = a capability i
 | `toolbarPosition` | `'default'` | `'above-header'` / `'below-header'` |
 | `groupedFilterLabel` | `"Global"` | Field picker "all" label |
 
-Remaining props: `header` (node or `{ content, align, className, showOnEmpty }` — a sticky title band inside the card), `footer` (sticky full-width bottom band), `maxHeight` (scroll container, default `"100%"`), `loading` (overlay), `error` + `onRefresh` (error card with Try Again), `emptyMessage`, `rowClassName={(row) => class}` (status-based row colouring), `onTableReady={(table) => …}` (imperative escape hatch — fires once per table instance), `children={(table) => …}` (render-prop, e.g. the action bar).
+## Complete props reference
+
+Every prop `DataTable` accepts — this is the whole surface, nothing else exists:
+
+| Prop | Type | Default | What it does |
+|---|---|---|---|
+| `data` | `T[]` | required | Row data, rendered client-side |
+| `columns` | `GroupColumnDef<T>[]` | required | Column defs ([Columns](#columns)) |
+| `filters` | `FilterConfig<T>[]` | — | Toolbar filter controls ([Filters](#filters--the-full-story)) |
+| `pagination` | `PaginationConfig` | — | Presence enables paging ([Pagination](#pagination)) |
+| `settings` | `TableSettings` | `{}` | Feature/presentation toggles (table above) |
+| `header` | node or `{ content, align, className, showOnEmpty }` | — | Sticky title band inside the card; `showOnEmpty` (default true) keeps it on empty data |
+| `footer` | `ReactNode` | — | Sticky full-width bottom band |
+| `className` | `string` | — | Outer wrapper classes |
+| `maxHeight` | `string` | `"100%"` | Scroll container cap — what makes header/footer sticky |
+| `loading` | `boolean` | `false` | Spinner overlay over the card |
+| `error` | `string` | — | Replaces the table with an error card (+ Try Again when `onRefresh` given) |
+| `emptyMessage` | `string` | `"No data available"` | Empty-state text |
+| `onRowSelectionChange` | `(rows: T[]) => void` | — | Selected originals on every change ([Selection](#selection)) |
+| `onExport` | `(data, view) => void` | — | Enables the Settings-menu Export item ([Export](#export)) |
+| `onRefresh` | `() => void` | — | Toolbar Refresh button + error-card Try Again |
+| `onTableReady` | `(table) => void` | — | TanStack instance escape hatch; fires once per instance |
+| `children` | `(table) => ReactNode` | — | Render-prop (action bar etc.) |
+| `isRowSelectable` | `(row: T) => boolean` | — | Row-level selection gate |
+| `getRowId` | `(row, index) => string` | — | Stable row identity ([Selection](#selection)) |
+| `defaultSelectedRows` | `(row: T) => boolean` | — | Uncontrolled selection prefill, seeded once |
+| `onExternalSearch` | `(values) => void` | — | Server-filter commit callback ([External filters](#external-server-filters)) |
+| `aggregations` | `AggregationConfigMap<T>` | `{}` | Footer computations ([Aggregations](#aggregations)) |
+| `onAggregationChange` | `(columnId, config) => void` | — | Enables the toolbar Aggregations menu |
+| `rowClassName` | `(row: Row<T>) => string` | — | Per-row classes (status colouring) |
+| `persist` | `string \| PersistConfig` | — | State persistence ([Persist](#persist)) |
+
+`FilterConfig` fields (per filter):
+
+| Field | Required | Notes |
+|---|---|---|
+| `placeholder` | yes | Label everywhere: control, chip, field picker |
+| `key` | one of | Data dot-path (path filter) |
+| `id` + `filterFn(row, value)` | one of | Custom predicate filter |
+| `type` | no (`"text"`) | `text` / `select` / `date` / `daterange` / `number` |
+| `options` | with `select` | `{ label, value }[]` |
+| `placement` | no (`"bar"`) | `"menu"` = behind the field picker + chip |
+| `externalSearch` | no (`false`) | Server-side |
+| `width`, `icon`, `dateFormat` | no | Cosmetic |
+| `shared` | no | Group-wide value slot (needs `persist.group`) |
+| `persist` | no (`true`) | `false` = exclude from persistence |
+
+`GroupColumnDef` extras beyond TanStack: `headerAlign`, `columns`, `enablePinning`, `customFooter`, `exportValue`, `exportHeader` ([Columns](#columns)). `PersistConfig`: `key` (required), `group`, `local`, `pagination` ([Persist](#persist)). `AggregationConfig`: `enabled`, `functions`, `format`, `accessor` ([Aggregations](#aggregations)). `PaginationConfig`: `pageSize`, `pageSizeOptions`, `showInfo`, `showPageNumbers` ([Pagination](#pagination)).
+
+Action bar: `DataTableActionBar` takes `table`, `visible` (default: auto — shown while anything selected), `container` (portal target, default `document.body`) plus `motion.div` props; `DataTableActionBarAction` takes Button props plus `tooltip` and `isPending`; `DataTableActionBarSelection` takes `table`.
 
 ## Troubleshooting
 
@@ -369,7 +439,9 @@ DataTable's sibling for card/grid layouts: same toolbar/search/filter/pagination
 />
 ```
 
-`onTemplateReady` / `children` receive a controller (`getSelectedItems`, `selectAll`, `clearSelection`, `getFilteredData`, `refresh`, `exportData`…), and it has its own `DataTemplateActionBar` family.
+`onTemplateReady` / `children` receive a controller (`getSelectedItems`, `selectAll`, `clearSelection`, `getFilteredData`, `getTotalCount`, `getVisibleCount`, `refresh`, `exportData`), and it has its own `DataTemplateActionBar` family.
+
+Full surface — props: `data`, `template`, `fields` (`{ key, label, type?, sortable?, filterable?, searchable? }`), `filters` (`{ key, label, type, options?, placeholder?, icon? }`), `pagination`, `settings`, `header`, `footer`, `className`, `loading`, `error`, `emptyMessage`, `emptyIcon`, `onSelectionChange`, `onExport(data)`, `onRefresh`, `onTemplateReady`, `children`. Settings: `enableSorting`, `enableFiltering`, `enableGlobalSearch`, `enableSelection` (default OFF), `enableExport`, `showToolbar` (default ON), `selectionMode`, `gridCols`, `gap`, `aspectRatio`, `minCardWidth`, `maxCardWidth`.
 
 ---