@trackunit/react-table 2.11.11-alpha-7afddbbe4cc.0 → 2.11.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-table",
-  "version": "2.11.11-alpha-7afddbbe4cc.0",
+  "version": "2.11.11",
   "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.4-alpha-7afddbbe4cc.0",
-    "@trackunit/react-core-hooks": "1.25.7-alpha-7afddbbe4cc.0",
-    "@trackunit/shared-utils": "1.19.7-alpha-7afddbbe4cc.0",
-    "@trackunit/css-class-variance-utilities": "2.3.7-alpha-7afddbbe4cc.0",
-    "@trackunit/ui-icons": "1.17.7-alpha-7afddbbe4cc.0",
-    "@trackunit/react-table-base-components": "2.12.11-alpha-7afddbbe4cc.0",
-    "@trackunit/react-form-components": "2.10.11-alpha-7afddbbe4cc.0",
-    "@trackunit/i18n-library-translation": "2.8.7-alpha-7afddbbe4cc.0",
-    "@trackunit/iris-app-runtime-core-api": "1.21.7-alpha-7afddbbe4cc.0",
+    "@trackunit/react-components": "3.8.4",
+    "@trackunit/react-core-hooks": "1.25.6",
+    "@trackunit/shared-utils": "1.19.6",
+    "@trackunit/css-class-variance-utilities": "2.3.6",
+    "@trackunit/ui-icons": "1.17.6",
+    "@trackunit/react-table-base-components": "2.12.11",
+    "@trackunit/react-form-components": "2.10.11",
+    "@trackunit/i18n-library-translation": "2.8.6",
+    "@trackunit/iris-app-runtime-core-api": "1.21.6",
     "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,55 +61,58 @@ type UseTablePersistenceResult = {
 };
 /**
  * Persists and restores table column state (order, sizing, visibility, sorting, pinning, expanded) using
- * localStorage and the URL **hash fragment**.
+ * the URL **hash fragment** and localStorage.
  *
  * Storage scope:
- * - localStorage: everything, scoped to the current user.
- * - URL hash (shareable): everything except `expanded`.
+ * - URL hash (shareable): `columnOrder`, `columnVisibility`, `sorting`, `columnPinning`, `columnSizing`.
+ * - localStorage: everything above plus `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 the URL sync).
+ * 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.
  *
- * 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).
+ * 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.
  *
- * `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.
+ * 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.
  *
- * 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.
+ * `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.
  *
- * 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).
+ * 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.
  *
- * Changes reported before `clientSideUserId` resolves are held in React state
- * and written to the user's scoped storage and stamped into the hash once it
- * does. The id can also change while the table is mounted: releasing an
- * impersonated identity renews the token, and the new claims are published
- * before the page navigates away. Reported state is therefore tagged with the
- * identity that produced it and persisted only while that identity is current,
- * and the layout read on load is committed to storage only for the account
- * that opened the page, so a layout never crosses from one account into
- * another's scoped storage or into their hash on its own. An identity that
- * takes over and then edits saves what it sees on screen — the opener's hash
- * over its own stored layout — under its own key, the same as editing an
- * opened link.
+ * 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).
  *
  * @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/useCompactTableUrl.d.ts

@@ -0,0 +1,24 @@
+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 {};

package/src/useTable.d.ts

@@ -22,12 +22,6 @@ 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/tableUrlValue.d.ts

@@ -1,27 +0,0 @@
-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) => Omit<TableColumnOptions, "expanded">;
-/**
- * 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;