@sheetxl/utils-react 0.8.0-beta.4 → 0.8.0-beta.6

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.4",
4
+ "version": "0.8.0-beta.6",
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.4",
44
+ "@sheetxl/utils": "^0.8.0-beta.6",
45
45
  "clsx": "^2.1.1",
46
46
  "detect-it": "^4.0.1",
47
47
  "prop-types": "^15.8.1",
@@ -2,7 +2,7 @@
2
2
  * Persistence key for the user's UI-language preference.
3
3
  *
4
4
  * @remarks
5
- * Owned via `usePersistenceState` against the surrounding `PersistenceStateProvider` (Studio, or a
5
+ * Owned via `usePersistentState` against the surrounding `PersistentStateProvider` (Studio, or a
6
6
  * standalone host) — the mirror of `ThemeStateKey` in `@sheetxl/react`. A host that wants to read
7
7
  * or seed it (e.g. the VS Code extension, whose store bridges to the extension host's state) does
8
8
  * so with the same key, or by supplying its own provider/store. The value is a BCP 47 tag; absent
@@ -0,0 +1,3 @@
1
+ import { PersistentStateProviderProps } from './Types';
2
+ export declare function PersistentStateProvider(props: PersistentStateProviderProps): import("react").JSX.Element;
3
+ //# sourceMappingURL=PersistentStateProvider.d.ts.map
@@ -45,7 +45,7 @@ export type PersistenceSerializer<T = any> = {
45
45
  parse: (raw: string | null) => T;
46
46
  stringify: (val: T) => string;
47
47
  };
48
- export type PersistenceStateOptions<T = any> = {
48
+ export type PersistentStateOptions<T = any> = {
49
49
  /**
50
50
  * Convert the value to/from a string for storage
51
51
  *
@@ -54,10 +54,9 @@ 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
- export type PersistenceStateSetter<T> = (next: T | ((prev: T) => T)) => void;
60
- export type PersistenceProviderProps = {
58
+ export type PersistentStateSetter<T> = (next: T | ((prev: T) => T)) => void;
59
+ export type PersistentStateProviderProps = {
61
60
  /**
62
61
  * Storage backend to use
63
62
  */
@@ -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 `usePersistentState` (without the namespace). Values are
94
+ * the typed values, not serialized strings. A value here wins over the default passed to
95
+ * `usePersistentState`; 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
  *
@@ -1,9 +1,10 @@
1
- import { PersistenceProviderProps, PersistenceSerializer } from './Types';
2
- export type Ctx = Required<Omit<PersistenceProviderProps, 'children'>> & {
1
+ import { PersistentStateProviderProps, PersistenceSerializer } from './Types';
2
+ export type Ctx = Required<Omit<PersistentStateProviderProps, 'children'>> & {
3
3
  notify(key: string, value?: string): void;
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
@@ -1,6 +1,6 @@
1
1
  export * from './Types';
2
- export * from './usePersistenceState';
3
- export * from './PersistenceStateProvider';
2
+ export * from './usePersistentState';
3
+ export * from './PersistentStateProvider';
4
4
  export * from './InMemoryStore';
5
5
  export * from './LocalStorageStore';
6
6
  //# sourceMappingURL=index.d.ts.map
@@ -1,11 +1,12 @@
1
- import { PersistenceStateOptions, PersistenceStateSetter } from './Types';
1
+ import { PersistentStateOptions, PersistentStateSetter } from './Types';
2
2
  /**
3
3
  * Persisted state hook backed by the current persistence context.
4
4
  *
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
- export declare function usePersistenceState<T = unknown>(key: string | null, defaultValue?: T | (() => T), opts?: PersistenceStateOptions<T>): [T, PersistenceStateSetter<T>, () => void];
34
- //# sourceMappingURL=usePersistenceState.d.ts.map
35
+ export declare function usePersistentState<T = unknown>(key: string | null, defaultValue?: T | (() => T), opts?: PersistentStateOptions<T>): [T, PersistentStateSetter<T>, () => void];
36
+ //# sourceMappingURL=usePersistentState.d.ts.map