@trackunit/react-table 2.11.8-alpha-0ef4e15e7c1.0 → 2.11.8-alpha-775ca1816d6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-table",
-  "version": "2.11.8-alpha-0ef4e15e7c1.0",
+  "version": "2.11.8-alpha-775ca1816d6.0",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -11,15 +11,15 @@
     "react-dnd": "16.0.1",
     "react-dnd-html5-backend": "16.0.1",
     "tailwind-merge": "^2.0.0",
-    "@trackunit/react-components": "3.8.2-alpha-0ef4e15e7c1.0",
-    "@trackunit/react-core-hooks": "1.25.5-alpha-0ef4e15e7c1.0",
-    "@trackunit/shared-utils": "1.19.5-alpha-0ef4e15e7c1.0",
-    "@trackunit/css-class-variance-utilities": "2.3.5-alpha-0ef4e15e7c1.0",
-    "@trackunit/ui-icons": "1.17.5-alpha-0ef4e15e7c1.0",
-    "@trackunit/react-table-base-components": "2.12.8-alpha-0ef4e15e7c1.0",
-    "@trackunit/react-form-components": "2.10.8-alpha-0ef4e15e7c1.0",
-    "@trackunit/i18n-library-translation": "2.8.5-alpha-0ef4e15e7c1.0",
-    "@trackunit/iris-app-runtime-core-api": "1.21.5-alpha-0ef4e15e7c1.0",
+    "@trackunit/react-components": "3.8.2-alpha-775ca1816d6.0",
+    "@trackunit/react-core-hooks": "1.25.5-alpha-775ca1816d6.0",
+    "@trackunit/shared-utils": "1.19.5-alpha-775ca1816d6.0",
+    "@trackunit/css-class-variance-utilities": "2.3.5-alpha-775ca1816d6.0",
+    "@trackunit/ui-icons": "1.17.5-alpha-775ca1816d6.0",
+    "@trackunit/react-table-base-components": "2.12.8-alpha-775ca1816d6.0",
+    "@trackunit/react-form-components": "2.10.8-alpha-775ca1816d6.0",
+    "@trackunit/i18n-library-translation": "2.8.5-alpha-775ca1816d6.0",
+    "@trackunit/iris-app-runtime-core-api": "1.21.5-alpha-775ca1816d6.0",
     "zod": "^3.25.76"
   },
   "peerDependencies": {

package/src/hooks/useTablePersistence/useTablePersistence.d.ts

@@ -29,29 +29,29 @@ declare const tableStateSchema: z.ZodObject<{
     expanded: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<true>, z.ZodRecord<z.ZodString, z.ZodBoolean>]>>;
 }, "strip", z.ZodTypeAny, {
     columnOrder?: string[] | undefined;
-    columnVisibility?: Record<string, boolean> | undefined;
     sorting?: {
         id: string;
         desc: boolean;
     }[] | undefined;
+    columnVisibility?: Record<string, boolean> | undefined;
+    columnSizing?: Record<string, number> | undefined;
     columnPinning?: {
         right?: string[] | undefined;
         left?: string[] | undefined;
     } | undefined;
-    columnSizing?: Record<string, number> | undefined;
     expanded?: true | Record<string, boolean> | undefined;
 }, {
     columnOrder?: string[] | undefined;
-    columnVisibility?: Record<string, boolean> | undefined;
     sorting?: {
         id: string;
         desc: boolean;
     }[] | undefined;
+    columnVisibility?: Record<string, boolean> | undefined;
+    columnSizing?: Record<string, number> | undefined;
     columnPinning?: {
         right?: string[] | undefined;
         left?: string[] | undefined;
     } | undefined;
-    columnSizing?: Record<string, number> | undefined;
     expanded?: true | Record<string, boolean> | undefined;
 }>;
 export type TableColumnOptions = z.infer<typeof tableStateSchema>;
@@ -61,58 +61,48 @@ type UseTablePersistenceResult = {
 };
 /**
  * Persists and restores table column state (order, sizing, visibility, sorting, pinning, expanded) using
- * the URL **hash fragment** and localStorage.
+ * localStorage and the URL **hash fragment**.
  *
  * Storage scope:
- * - URL hash (shareable): `columnOrder`, `columnVisibility`, `sorting`, `columnPinning`, `columnSizing`.
- * - localStorage: everything above plus `expanded`.
+ * - localStorage: everything, scoped to the current user.
+ * - URL hash (shareable): everything except `expanded`.
  *
  * The hash slot is used instead of search params because some deployments
  * route through AWS WAF, whose `SizeRestrictions_QUERYSTRING` managed rule
  * caps the query string at ~5000 bytes — easily breached by wide tables.
  * The fragment is client-only and bypasses that cap entirely (subject to a
- * 64 KiB soft limit enforced by `useHashParamSync`).
- *
- * Legacy compatibility: shared links that still use `?<persistenceKey>Tp=`
- * search params from before the hash migration are decoded on first load
- * and the search param is stripped via a `replace` navigation so old
- * bookmarks and forwarded URLs continue to restore state without polluting
- * browser history.
+ * 64 KiB soft limit enforced by the URL sync).
  *
- * On mount, state is loaded from the hash (or legacy search param as a
- * one-shot fallback) and merged with localStorage so fields omitted from
- * the URL, such as `expanded`, still survive reloads. Opening that URL
- * saves the merged layout for the account that loaded the page, so a
- * pasted link sticks without a further edit. An account that becomes
- * current later, while the same URL is still open, does not receive that
- * write — their storage changes only when they edit the table. Switching
- * back to the opener does not write the hash that is on screen then.
+ * On load the hash wins, so a link or bookmark renders the same layout for
+ * whoever opens it, and localStorage fills in what the hash omits (`expanded`).
+ * Opening a URL that carries a layout saves it for the account that loaded the
+ * page, so a pasted link sticks without a further edit. A layout that exists
+ * only in localStorage is never copied into the hash on load: doing that put
+ * the current layout into every history entry, so a later visit via history,
+ * a bookmark, or a login redirect replayed an older layout and saved it over
+ * the current one (GLU-2396).
  *
- * A layout that exists only in localStorage is not copied into the hash on
- * load. Doing that put the current layout into every history entry, so a
- * later visit via history, a bookmark, or a login redirect replayed an
- * older layout and saved it over the current one (GLU-2396). The hash is
- * written when the user changes the table, replacing the current history
- * entry, or when they open a URL that already carries one. A push per edit
- * would leave the same replayable entries behind.
+ * `onTableStateChange` takes a *partial* state and merges it into whatever was
+ * reported earlier in the session, so a consumer can report a single slice
+ * (e.g. only `expanded`) without the omitted fields falling back to their
+ * mount-time values. A field reported empty is dropped from the stored state,
+ * and once every field is empty the entry is removed altogether.
  *
- * `onTableStateChange` takes a *partial* state and merges it into whatever
- * was reported earlier in the session, so a consumer can report a single
- * slice (e.g. only `expanded`) without the omitted fields falling back to
- * their mount-time values. A field reported empty is dropped from the stored
- * state, and once every field is empty the entry is removed altogether.
+ * Each change is written to localStorage as soon as it is reported, so
+ * navigating away right after an edit cannot lose it. The hash is written
+ * after a {@link URL_WRITE_DEBOUNCE_MS} quiet period, replacing the current
+ * history entry: a drag or a run of toggles leaves one entry, not one per step.
  *
- * Reported state is scoped to the identity that reported it: when the current
- * user changes, state reported by the previous user is discarded instead of
- * being written to the new user's storage. A layout shared through the URL
- * renders for anyone. It is saved for the account that opened the page, and
- * only becomes a later account's layout once that account changes the table.
+ * Every hash write is stamped with the identity that wrote it. The stamp is
+ * read only by the login redirect, which drops a hash left behind by another
+ * account that also uses this browser, so accounts sharing a PC do not hand
+ * their layouts to each other (GLU-2396).
  *
- * The hash always wins on load so a link or bookmark renders the same layout
- * for whoever opens it. Each hash write is stamped with the identity that
- * wrote it; the stamp is read only by the login redirect, which drops a hash
- * left behind by a *different* account that also uses this browser so
- * accounts sharing a PC do not hand their layouts to each other (GLU-2396).
+ * `clientSideUserId` only moves from unresolved to resolved while this hook
+ * is mounted; switching, impersonating, or releasing an identity reloads the
+ * page or navigates away from the table. Changes reported before the id
+ * resolves are held in React state and written to the user's scoped storage
+ * once it does.
  *
  * @param persistenceKey - Unique key used to store and retrieve the table state.
  *   Must be camelCase and at most 15 characters (e.g. "userTable", "assetList").

package/src/hooks/useTablePersistence/utils/tableUrlValue.d.ts

@@ -0,0 +1,27 @@
+import type { TableColumnOptions } from "../useTablePersistence";
+/**
+ * The URL projection of table state: everything except `expanded`.
+ *
+ * Row expansion is per-session, per-user detail and would make a shared link
+ * open rows the recipient has no interest in, so it lives only in
+ * localStorage. `usePersistedState`'s `mergeWithStorageOnRead` restores it on
+ * load. The remaining fields are written as-is; the gzip step in
+ * `useCustomEncoding` handles the size, and a value that reads back to the
+ * same shape it was written from cannot drift from storage.
+ */
+export declare const toTableUrlValue: ({ expanded: _expanded, ...shareable }: TableColumnOptions) => object;
+/**
+ * Normalises a decoded URL value into the full `TableColumnOptions` shape.
+ *
+ * A value written by {@link toTableUrlValue} passes through unchanged, except
+ * that a `columnPinning` with one side missing gets the other side filled in
+ * as `[]`. Values in the legacy compact format are expanded:
+ * - short keys (`co`, `cv`, `s`, `cp`, `cs`) become full names;
+ * - a `columnVisibility` array of visible column IDs becomes a visible-only
+ *   map (see `VISIBLE_ONLY_COLUMN_VISIBILITY_KEY`);
+ * - a `columnVisibility` `{ v, h }` pair becomes explicit booleans;
+ * - `columnPinning` `{ l, r }` becomes `{ left, right }`.
+ *
+ * Non-object input is returned as-is so validation can reject it.
+ */
+export declare const fromTableUrlValue: (decoded: unknown) => unknown;

package/src/useTable.d.ts

@@ -22,6 +22,12 @@ export interface TableOptionsProps<TData extends object> extends Omit<TableOptio
  *
  * `onTableStateChange` is called with the field that changed, not the whole state, so anything
  * storing it has to merge each report into what it already holds. `useTablePersistence` does.
+ * Within that field only what differs from the column definitions is reported — visibility
+ * entries equal to `meta.hiddenByDefault`, sizes equal to `size`, an order equal to the
+ * definition order, a pinning equal to `meta.pinned` — and an emptied field is reported empty.
+ * Defaults therefore belong on the column definitions; a value in `initialState` is read as
+ * saved state, not as a default. Columns without an explicit `id` take no part in the
+ * defaults (as before), so they are always reported once they are in the state.
  *
  * @template TData - The type representing the data model associated with the table.
  * @param {TableOptionsProps<TData>} props - The props object containing configuration options.

package/src/hooks/useTablePersistence/utils/useCompactTableUrl.d.ts

@@ -1,24 +0,0 @@
-import type { TableColumnOptions } from "../useTablePersistence";
-type CompactTableUrl = Record<string, unknown>;
-type UseCompactTableUrlReturn = {
-    readonly toUrlValue: (state: TableColumnOptions) => CompactTableUrl;
-    readonly fromUrlValue: (decoded: unknown) => unknown;
-};
-/**
- * Provides transform functions for compacting table state before URL encoding
- * and expanding it back after URL decoding.
- *
- * The compaction strategy:
- * - Short property keys (columnOrder → co, columnVisibility → cv, etc.)
- * - columnVisibility stored as an array of visible column names only
- * - columnOrder stored as visible-column order when visibility is available
- * - columnSizing stored under a short key (`cs`)
- * - `expanded` is excluded from the URL and restored from localStorage via
- *   `usePersistedState`'s `mergeWithStorageOnRead`
- * - Empty pinning arrays are excluded
- *
- * These transforms are designed to plug into {@link usePersistedState}'s
- * `toUrlValue` and `fromUrlValue` options.
- */
-export declare const useCompactTableUrl: () => UseCompactTableUrlReturn;
-export {};