@akshar-technosoft/ui 1.2.1 → 1.3.0

package/README.md

@@ -15,7 +15,7 @@ Colors ride the app's theme CSS variables (`--sidebar`, `--border`, `--backgroun
 | `DataTable`, `DataTableProps`, `GroupColumnDef` | The data table and its types |
 | `DataTableActionBar`, `DataTableActionBarAction`, `DataTableActionBarSelection` | Floating bulk-action bar for selected rows |
 | `getTableExportView`, `TableExportView`, `TableExportColumn` | Export snapshot builder (see [Export](#export)) |
-| `readPersistedExternal`, `PersistConfig`, `PersistGroupRegistry` | Persist helpers (see [Persist](#persist)) |
+| `readPersistedExternal`, `useTableFilterParam`, `FilterKeys`, `PersistConfig`, `PersistGroupRegistry`, `PersistGroupId`, `PersistSlotId`, `PersistSlotFor` | Persist + URL-sync helpers (see [Persist](#persist)) |
 | `DataTemplate`, `DataTemplateProps` + action-bar components | Card/grid sibling of DataTable |
 | `AppContainer`, `AppHeader`, `AppContent`, `AppContentHeader`, `AppContentFooter`, `AppSheet`, `AppFooter` | Page layout system |
 | `GeneralHelper` | Static utils: `formatDate`, `formatINR`, `toProperCase`, `copyToClipboard`, `CopyToClipboard`, `StatusBadge` |
@@ -238,7 +238,7 @@ The toolbar's **Aggregations menu** (user-facing toggles, per-column function su
 
 ## Persist
 
-Opt-in state persistence across unmount/back-navigation:
+Opt-in state persistence across unmount/back-navigation, **and** the URL query string:
 
 ```tsx
 persist="qc-completed"                                        // shorthand for { key }
@@ -247,13 +247,32 @@ persist={{ key: "qc-completed", group: "inhouse", local: true }}
 
 **Persists:** column filter values, global search text, the field-picker selection, external (server) filter values, pagination (`pagination: false` to skip page state). **Never persists:** selection, sorting, visibility, pinning, sizing.
 
-**How it works:** values are stored per **filter identity** (`key`/`id`), not as raw table state, in an in-memory map — a refresh starts clean. `local: true` mirrors to localStorage (`atsui:tbl:v1:*`), surviving refresh; note it's per-browser, not per-login. Restore is synchronous, seeded before first render — no flash of unfiltered data. Dates are revived from ISO strings. Per-filter opt-out: `persist: false` on that filter.
+**Three legs, one consistency rule:** in-memory (always, whenever `persist` is set) + the URL query string (always) + localStorage (opt-in via `local: true`). While a persist-enabled table is mounted, **mem and the URL always mirror each other** — mem is the primary; `local: true` folds localStorage into the same guarantee. This is what makes each of the following work without you wiring anything:
 
-**`key` must be app-unique.** Two mounted tables on one key overwrite each other's state (dev warning). One page with two tables = two keys.
+- Filter something, navigate away (even a bare nav-link click to the same route, no remount), come back — filter AND url both restored, always in sync.
+- Filter something, hit refresh — the URL alone survives it, no `local` needed.
+- Share/bookmark a URL with `?LotNo=X` — deep-links straight into a pre-filtered table.
+- `local: true` additionally survives a full close/reopen of the browser (URL alone doesn't).
+
+**The one protocol you should know if you're driving the URL yourself** (`useTableFilterParam`, a manual `setSearchParams`, a `<TypedLink>` with a query): an **absent** param is never treated as a delete — a bare navigation naturally drops the query string without the table's state changing, so on remount/re-render a missing param gets **restored** into the URL from mem, not treated as "user cleared it." To actually clear a filter from outside the table, write the param **present but empty** (`?LotNo=`) — `useTableFilterParam`'s setter already does this for you.
+
+**How it works otherwise:** values are stored per **filter identity** (`key`/`id`), not as raw table state, in an in-memory map — a refresh with no `local` starts clean except for whatever the URL still carries. `local: true` mirrors to localStorage (`atsui:tbl:v1:*`); note it's per-browser, not per-login, and not live across tabs (another already-open tab picks up a change on its next mount/navigation, not instantly). Restore is synchronous, seeded before first render — no flash of unfiltered data. Dates serialize as one URL param, ISO, comma-separated for a range (`?Date=2026-07-01,2026-07-09`). Per-filter opt-out: `persist: false` on that filter (excluded from mem, localStorage, AND the URL).
+
+**`key` must be app-unique.** Two mounted tables on one key overwrite each other's state (dev warning). One page with two tables = two keys. Two DIFFERENT tables sharing a filter id (or both using the global search) on the SAME route will cross-talk through the URL, since query params are one flat namespace per page — usually not a real scenario since that'd mean two tables on one screen filtering the same field.
+
+### Reading/writing a table's filter from OUTSIDE it
+
+`useTableFilterParam(filters, key)` gives you a live, typed `[value, setValue]` for one filter — typed straight off the same `filters` array you already pass to `<DataTable>`, no separate registry to keep in sync. Works because of the URL-mirror guarantee above: reading the URL param IS reading the filter's live value.
+
+```tsx
+const [lotNo, setLotNo] = useTableFilterParam(lotReportFilters, "LotNo")
+// lotNo: string | undefined — live, updates as the table's own filter changes
+// setLotNo(undefined) clears it (writes the present-but-empty param, not a delete)
+```
 
 ### Shared slots — one value across pages
 
-`shared: "party"` on a filter publishes its VALUE into a named slot; every table in the same `persist.group` with a filter bound to that slot picks it up — even when the pages use different filter `key`s, or one side is an `externalSearch` filter (values are stored by identity, which is what makes this possible). Search a party on one page; the next page in the group opens already filtered to it. Two tables mounted at once live-sync through the slot.
+`shared: "party"` on a filter publishes its VALUE into a named slot; every table in the same `persist.group` with a filter bound to that slot picks it up — even when the pages use different filter `key`s, or one side is an `externalSearch` filter (values are stored by identity, which is what makes this possible). Search a party on one page; the next page in the group opens already filtered to it. Two tables mounted at once live-sync through the slot. Shared filters also go through the URL leg (a redirect from OUTSIDE the group has no other way to reach a `shared` filter), so the same absent-vs-empty protocol above applies to them too.
 
 `shared` REQUIRES `persist.group`. Slots never cross groups — "party" in group `inhouse` is not "party" in `sales`. A `shared` filter on a group-less table is inert and warns.
 
@@ -271,7 +290,29 @@ declare module "@akshar-technosoft/ui" {
 }
 ```
 
-After this `group: "inhose"` is a compile error and `shared` autocompletes.
+After this `group: "inhose"` is a compile error, and `shared` autocompletes/type-checks against **only that one table's own group's slots** — not the app-wide union of every group's slots. That narrowing is automatic when `filters` is written inline in JSX alongside `persist`:
+
+```tsx
+<DataTable
+  persist={{ key: "qc-completed", group: "inhouse" }}
+  filters={[
+    { key: "PartyCode", placeholder: "Party", shared: "party" },   // ✓ autocompletes "party" | "material"
+  ]}
+/>
+```
+
+It does **NOT** auto-narrow when `filters` is a separately declared `const` — the common pattern in this codebase — because that array gets its type at its own declaration, independent of a `persist` prop written later in the same component. Pass the group as `DataTableProps`'s **second** type parameter there:
+
+```tsx
+// QualityCheckPending.tsx — table's persist.group is "QC"
+const filters: DataTableProps<ORPReportQualityCheckType, "QC">["filters"] = [
+  { key: "Code", placeholder: "Taka No.", type: "text" },
+  { key: "RefNo", placeholder: "Ref No", type: "text", shared: "taka" },   // ← now autocompletes/checks against ONLY group "QC"'s slots ("taka"), not every group's
+  // ...
+]
+```
+
+Without the `, "QC"` the array still compiles (falls back to the broad union of every group's slots, same as before this existed) — the second type param is what turns that into a real, group-scoped check.
 
 ### The double API call, and how to fix it
 
@@ -413,8 +454,8 @@ Every prop `DataTable` accepts — this is the whole surface, nothing else exist
 | `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 |
+| `shared` | no | Group-wide value slot (needs `persist.group`); typed against `DataTableProps`'s 2nd type param, see [Persist](#persist) |
+| `persist` | no (`true`) | `false` = exclude from persistence (mem, localStorage, AND the URL) |
 
 `GroupColumnDef` extras beyond TanStack: `headerAlign`, `columns`, `enablePinning`, `enableColumnVisibility`, `enableHeaderMenu`, `reserveMenuSpace`, `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)).
 
@@ -426,6 +467,8 @@ Action bar: `DataTableActionBar` takes `table`, `visible` (default: auto — sho
 - **Global search can't find a value that's visibly on screen** → that column has no accessor; add `accessorFn`.
 - **A `key` filter does nothing** → the path doesn't match the data shape (it's a data path, not a column id).
 - **Wrong rows selected after a refetch** → pass `getRowId`.
+- **Filter cleared from outside (`useTableFilterParam`, manual `setSearchParams`) comes right back** → you deleted the param instead of setting it to `""`. Absent = restore-from-mem, present-but-empty = clear. `useTableFilterParam`'s setter already does this correctly.
+- **`shared` autocompletes every group's slots, not just this table's** → `filters` is a separately declared `const`; add the group as `DataTableProps`'s 2nd type param: `DataTableProps<Row, "QC">["filters"]`. See [Persist](#persist).
 - **`shared` does nothing** → no `persist.group` on the table (warns).
 - **Two tables fight over saved state** → same `persist.key` (warns).
 - **Field picker missing** → needs `enableGlobalFilter` on AND at least one `placement: 'menu'` filter.