@sheetxl/utils-react 0.8.0-beta.3 → 0.8.0-beta.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@sheetxl/utils-react",
3
3
  "description": "Utils React - Utilities for React capabilities needed for all SheetXL components.",
4
- "version": "0.8.0-beta.3",
4
+ "version": "0.8.0-beta.5",
5
5
  "license": "SEE LICENSE IN <LICENSE>",
6
6
  "type": "module",
7
7
  "exports": {
@@ -41,7 +41,7 @@
41
41
  ],
42
42
  "dependencies": {
43
43
  "@floating-ui/react-dom": "^2.1.9",
44
- "@sheetxl/utils": "^0.8.0-beta.3",
44
+ "@sheetxl/utils": "^0.8.0-beta.5",
45
45
  "clsx": "^2.1.1",
46
46
  "detect-it": "^4.0.1",
47
47
  "prop-types": "^15.8.1",
@@ -54,7 +54,6 @@ export type PersistenceStateOptions<T = any> = {
54
54
  serializer?: PersistenceSerializer<T>;
55
55
  version?: number;
56
56
  migrate?: (oldValue: unknown, oldVersion: number | undefined) => T;
57
- lazy?: boolean;
58
57
  };
59
58
  export type PersistenceStateSetter<T> = (next: T | ((prev: T) => T)) => void;
60
59
  export type PersistenceProviderProps = {
@@ -84,6 +83,21 @@ export type PersistenceProviderProps = {
84
83
  * @defaultValue `150`
85
84
  */
86
85
  debounceMs?: number;
86
+ /**
87
+ * Default values by key, used for any key with no stored value.
88
+ *
89
+ * @remarks
90
+ * Lets a host change the starting value of user-adjustable state without taking the choice away from
91
+ * the user — for example, enabling the dark grid by default while the user can still turn it off.
92
+ *
93
+ * Keys are the same logical keys passed to `usePersistenceState` (without the namespace). Values are
94
+ * the typed values, not serialized strings. A value here wins over the default passed to
95
+ * `usePersistenceState`; a stored value wins over both. Defaults are never written to the store, so
96
+ * changing one later applies to every user who has not made a choice.
97
+ *
98
+ * @defaultValue none
99
+ */
100
+ defaultValues?: Readonly<Record<string, unknown>>;
87
101
  /**
88
102
  * Children elements that will have access to the persistence context.
89
103
  *
@@ -4,6 +4,7 @@ export type Ctx = Required<Omit<PersistenceProviderProps, 'children'>> & {
4
4
  subscribeKey(key: string, fn: (value?: string) => void): () => void;
5
5
  };
6
6
  export declare const PersistenceContext: import('react').Context<Ctx | null>;
7
+ export declare const EmptyDefaultValues: Readonly<Record<string, unknown>>;
7
8
  export declare const DefaultSerializer: PersistenceSerializer;
8
9
  export declare function usePersistenceContext(): Ctx;
9
10
  //# sourceMappingURL=_Context.d.ts.map
@@ -5,7 +5,8 @@ import { PersistenceStateOptions, PersistenceStateSetter } from './Types';
5
5
  * This works like `useState`, but:
6
6
  *
7
7
  * - The value is persisted under `namespace:key` using the current store.
8
- * - On first render, it initializes from `defaultValue`.
8
+ * - With no stored value, it uses the provider's `defaultValues[key]` if present, otherwise `defaultValue`.
9
+ * Defaults are never written to the store; only values passed to `setState` are.
9
10
  * - Then it **hydrates asynchronously** from the configured store
10
11
  * (memory, localStorage, IndexedDB, remote, etc.). Hydration is *seeding*: a value written with
11
12
  * `setState` while the read is still in flight is newer, so it wins and the read is discarded.
@@ -19,16 +20,17 @@ import { PersistenceStateOptions, PersistenceStateSetter } from './Types';
19
20
  *
20
21
  * - No reads or writes go to the persistence store.
21
22
  * - No cross-tab / cross-hook subscription is set up.
22
- * - `clear()` simply resets back to the default value (or `undefined`).
23
+ * - `clear()` simply resets back to `defaultValue` (or `undefined`).
23
24
  *
24
25
  * @typeParam T - Type of the stored value.
25
26
  * @param key - Logical storage key; use `null` to disable persistence entirely.
26
- * @param defaultValue - Initial value or lazy initializer function.
27
- * @param opts - Options controlling serialization, versioning, migration, and laziness.
27
+ * @param defaultValue - Value used when nothing is stored and the provider has no default for `key`; a
28
+ * function is called lazily to produce it.
29
+ * @param opts - Options controlling serialization, versioning, and migration.
28
30
  * @returns A tuple of `[state, setState, clear]`:
29
31
  * - `state` – The current value.
30
32
  * - `setState(next)` – Updates the value and persists it (unless `key === null`).
31
- * - `clear()` – Removes the persisted value and resets to `defaultValue`.
33
+ * - `clear()` – Removes the persisted value and resets to the default.
32
34
  */
33
35
  export declare function usePersistenceState<T = unknown>(key: string | null, defaultValue?: T | (() => T), opts?: PersistenceStateOptions<T>): [T, PersistenceStateSetter<T>, () => void];
34
36
  //# sourceMappingURL=usePersistenceState.d.ts.map