@djangocfg/ui-core 2.1.603 → 2.1.604

package/README.md

@@ -117,6 +117,39 @@ fields (`DateField` / `TimeField` / `DateTimeField`) have their own reference in
 | `time/` | `useNow` · `useInterval` · `useTimeout` |
 | `router/` | `useLink` · `useRouter` (router-adapter consumer) |
 
+### Storage keys and namespaces (`hooks/state`)
+
+`useLocalStorage`, `useSessionStorage` and `useStoredValue` (every component
+`storageKey` prop) write under one scheme, `<owner>.<area>.<name>`, e.g.
+`cfg.ui.sidebar_width`, `kino.player.volume`. Full rules for agents:
+`@djangocfg/api` → `@docs/STORAGE_KEYS.md`.
+
+- A key that already follows the scheme is used as is.
+- A bare name (`'search-filter'`) is folded to `snake_case` and put under the
+  active owner: `cfg.ui.search_filter`. The owner is the hook's `namespace`
+  option, else the nearest `<StorageNamespaceProvider owner="kino">`, else the
+  framework default `cfg`.
+- Quota recovery drops only non-personal keys of our scheme, never tokens,
+  drafts, the profile or third-party keys (`NEXT_LOCALE`).
+
+```tsx
+// app root, once
+<StorageNamespaceProvider owner="kino">…</StorageNamespaceProvider>
+
+// lib/storage.ts, fixed keys declared once
+export const kino = createStorageNamespace('kino');
+export const VOLUME = kino.key('player', 'volume'); // kino.player.volume
+
+const [volume, setVolume] = useLocalStorage(VOLUME, 1);
+kino.keys();                       // every kino.* key in localStorage
+kino.clear();                      // "reset preferences" (personal cfg keys survive)
+```
+
+Helpers: `resolveStorageKey`, `isSchemeKey`, `listStorageKeys(owner, area)`,
+`clearStorageNamespace(owner, { area, includePersonal })`,
+`createStorageNamespace(owner)` (`key`, `storage` = guarded read/write/onChange, `keys`, `clear`).
+Do not write `localStorage` literals or ad-hoc keys in components.
+
 ## Lib utilities (`/lib`)
 
 - `cn(...)` — `clsx` + `tailwind-merge` shortcut

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.603",
+  "version": "2.1.604",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -133,8 +133,8 @@
     "check:docs": "node scripts/check-docs.mjs"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.603",
-    "@djangocfg/i18n": "^2.1.603",
+    "@djangocfg/api": "^2.1.604",
+    "@djangocfg/i18n": "^2.1.604",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -210,10 +210,10 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/api": "^2.1.603",
-    "@djangocfg/eslint-config": "^2.1.603",
-    "@djangocfg/i18n": "^2.1.603",
-    "@djangocfg/typescript-config": "^2.1.603",
+    "@djangocfg/api": "^2.1.604",
+    "@djangocfg/eslint-config": "^2.1.604",
+    "@djangocfg/i18n": "^2.1.604",
+    "@djangocfg/typescript-config": "^2.1.604",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^24.13.3",
     "@types/react": "19.2.15",

package/src/hooks/state/index.ts

@@ -19,3 +19,19 @@ export { useStateMachine } from './useStateMachine';
 export type { StateMachineConfig } from './useStateMachine';
 export { useCallbackRef } from './useCallbackRef';
 export { usePrevious } from './usePrevious';
+export {
+  DEFAULT_STORAGE_NAMESPACE,
+  StorageNamespaceProvider,
+  useStorageNamespace,
+  resolveStorageKey,
+  isSchemeKey,
+  listStorageKeys,
+  clearStorageNamespace,
+  createStorageNamespace,
+} from './storage-namespace';
+export type {
+  StorageNamespace,
+  StorageNamespaceProviderProps,
+  StorageArea,
+  ClearStorageOptions,
+} from './storage-namespace';

package/src/hooks/state/storage-namespace.ts

@@ -0,0 +1,215 @@
+'use client';
+
+/**
+ * Storage namespaces for the state hooks.
+ *
+ * Every key we write to the browser follows one scheme (full rules:
+ * `@djangocfg/api` → `@docs/STORAGE_KEYS.md`):
+ *
+ *   `<owner>.<area>.<name>[.<id>]`   e.g. `cfg.ui.sidebar_width`, `kino.player.volume`
+ *
+ * The hooks (`useLocalStorage`, `useSessionStorage`, `useStoredValue`) enforce
+ * it by resolving the key you pass:
+ *
+ *   1. A key that already follows the scheme (`kino.player.volume`) is used as is.
+ *   2. A bare name (`sidebar-width`, `Last Volume`) is folded to `snake_case` and
+ *      placed under the active namespace: `<owner>.ui.sidebar_width`.
+ *
+ * The active owner is, in order: the hook's `namespace` option, the nearest
+ * `<StorageNamespaceProvider owner="…">`, then `cfg` (the framework default).
+ * An app sets its owner once at the root and forgets about it.
+ */
+
+import { createContext, createElement, useContext, type ReactNode } from 'react';
+import {
+  CFG_FAMILIES,
+  CFG_KEYS,
+  createStorage,
+  normalizeSegment,
+  type GuardedStorage,
+} from '@djangocfg/api/storage';
+
+/** The framework's owner. Used when nothing else is declared. */
+export const DEFAULT_STORAGE_NAMESPACE = 'cfg';
+
+/** Area given to a bare key. Hook-level state is UI state unless the caller names the area. */
+export const DEFAULT_STORAGE_AREA = 'ui';
+
+const OWNER_RE = /^[a-z][a-z0-9_]*$/;
+const SCHEME_RE = /^[a-z][a-z0-9_]*(\.[a-z0-9_]+)+$/;
+
+const NamespaceContext = createContext<string>(DEFAULT_STORAGE_NAMESPACE);
+
+export interface StorageNamespaceProviderProps {
+  /** Short lower-case owner for every key written below: `kino`, `mls`, `crm`. */
+  owner: string;
+  children?: ReactNode;
+}
+
+/**
+ * Declares the owner of every bare storage key in the subtree.
+ * Place it once, near the root of an app.
+ */
+export function StorageNamespaceProvider({ owner, children }: StorageNamespaceProviderProps) {
+  if (!OWNER_RE.test(owner)) {
+    throw new TypeError(`StorageNamespaceProvider: owner "${owner}" must match ${OWNER_RE}`);
+  }
+  return createElement(NamespaceContext.Provider, { value: owner }, children);
+}
+
+/** The owner the hooks use here (the provider's, or `cfg`). */
+export function useStorageNamespace(): string {
+  return useContext(NamespaceContext);
+}
+
+/** True when `key` already follows `<owner>.<area>.<name>`. */
+export function isSchemeKey(key: string): boolean {
+  return SCHEME_RE.test(key);
+}
+
+/**
+ * Pure resolver behind the hooks: scheme keys pass through, bare names are
+ * folded and prefixed with `<owner>.ui.`. Throws when nothing usable is left.
+ */
+export function resolveStorageKey(key: string, owner: string = DEFAULT_STORAGE_NAMESPACE): string {
+  if (isSchemeKey(key)) return key;
+  const name = normalizeSegment(key);
+  if (!name) throw new TypeError(`storage key "${key}" is empty after normalisation`);
+  return `${owner}.${DEFAULT_STORAGE_AREA}.${name}`;
+}
+
+/** Hook form: owner = option → provider → `cfg`. */
+export function useResolvedStorageKey(key: string, namespace?: string): string {
+  const fromContext = useStorageNamespace();
+  return resolveStorageKey(key, namespace ?? fromContext);
+}
+
+// ---- eviction (shared by the quota-recovery paths of the hooks) -------------
+
+const PERSONAL_KEYS = new Set(
+  Object.values(CFG_KEYS)
+    .filter((spec) => spec.personal)
+    .map((spec) => spec.key),
+);
+const PERSONAL_PREFIXES = Object.values(CFG_FAMILIES)
+  .filter((spec) => spec.personal)
+  .map((spec) => spec.prefix);
+
+/**
+ * May the quota-recovery code drop this key? Only keys that follow our scheme
+ * and are not personal (tokens, profile, drafts). Third-party keys such as
+ * `NEXT_LOCALE` and everything signed-in-user related are never evicted.
+ */
+export function isEvictableKey(key: string): boolean {
+  if (!isSchemeKey(key)) return false;
+  if (key.startsWith('cfg.auth.') || PERSONAL_KEYS.has(key)) return false;
+  return !PERSONAL_PREFIXES.some((prefix) => key.startsWith(prefix));
+}
+
+/** Names in `storage` that the quota recovery is allowed to remove. */
+export function evictableKeys(storage: Storage): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < storage.length; i += 1) {
+    const name = storage.key(i);
+    if (name && isEvictableKey(name)) out.push(name);
+  }
+  return out;
+}
+
+// ---- inspection / reset ------------------------------------------------------
+
+export type StorageArea = 'local' | 'session';
+
+function nativeArea(area: StorageArea): Storage | null {
+  if (typeof window === 'undefined') return null;
+  try {
+    return area === 'session' ? window.sessionStorage : window.localStorage;
+  } catch {
+    return null;
+  }
+}
+
+/** Every key an owner holds in one store (`cfg` by default). */
+export function listStorageKeys(owner: string = DEFAULT_STORAGE_NAMESPACE, area: StorageArea = 'local'): string[] {
+  const native = nativeArea(area);
+  if (!native) return [];
+  const prefix = `${owner}.`;
+  const out: string[] = [];
+  for (let i = 0; i < native.length; i += 1) {
+    const name = native.key(i);
+    if (name?.startsWith(prefix)) out.push(name);
+  }
+  return out.sort();
+}
+
+export interface ClearStorageOptions {
+  /** Store to clear. Default: both. */
+  area?: StorageArea;
+  /** Also remove personal keys (tokens, profile, drafts). Default false: preferences only. */
+  includePersonal?: boolean;
+}
+
+/**
+ * Removes the keys of one owner. By default personal keys survive, so a
+ * "reset preferences" button never signs the user out.
+ * Hooks mounted on a removed key keep their in-memory value until they write.
+ */
+export function clearStorageNamespace(
+  owner: string = DEFAULT_STORAGE_NAMESPACE,
+  { area, includePersonal = false }: ClearStorageOptions = {},
+): string[] {
+  const areas: StorageArea[] = area ? [area] : ['local', 'session'];
+  const removed: string[] = [];
+  for (const a of areas) {
+    const native = nativeArea(a);
+    if (!native) continue;
+    for (const name of listStorageKeys(owner, a)) {
+      if (!includePersonal && owner === DEFAULT_STORAGE_NAMESPACE && !isEvictableKey(name)) continue;
+      try {
+        native.removeItem(name);
+        removed.push(name);
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  return removed;
+}
+
+// ---- an app's namespace -------------------------------------------------------
+
+export interface StorageNamespace {
+  readonly owner: string;
+  /** `kino.player.volume` from `('player', 'volume')`; parts are folded to snake_case. */
+  key(...parts: string[]): string;
+  /** Guarded non-React access (`read`, `write`, `readJSON`, `onChange`, `clearAll`…). */
+  readonly storage: GuardedStorage;
+  keys(area?: StorageArea): string[];
+  clear(options?: ClearStorageOptions): string[];
+}
+
+/**
+ * Declares an app's namespace in one place:
+ *
+ * ```ts
+ * // lib/storage.ts
+ * export const kinoStorage = createStorageNamespace('kino');
+ * export const PLAYER_VOLUME = kinoStorage.key('player', 'volume'); // kino.player.volume
+ *
+ * // component
+ * const [volume, setVolume] = useLocalStorage(PLAYER_VOLUME, 1);
+ * ```
+ *
+ * and wraps the app root in `<StorageNamespaceProvider owner="kino">` so bare
+ * `storageKey` props on ui-core components land under `kino.ui.*`.
+ */
+export function createStorageNamespace(owner: string): StorageNamespace {
+  const storage = createStorage(owner);
+  return {
+    owner,
+    key: (...parts) => storage.key(...parts),
+    storage,
+    keys: (area = 'local') => listStorageKeys(owner, area),
+    clear: (options) => clearStorageNamespace(owner, options),
+  };
+}

package/src/hooks/state/useLocalStorage.ts

@@ -3,6 +3,7 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 
 import { isQuotaExceededError } from './storage-quota';
+import { evictableKeys, useResolvedStorageKey } from './storage-namespace';
 
 /**
  * Storage wrapper format with metadata
@@ -27,6 +28,12 @@ export interface UseLocalStorageOptions {
    * @example 24 * 60 * 60 * 1000 // 24 hours
    */
   ttl?: number;
+  /**
+   * Owner for a bare key (`'sidebar-width'` → `<owner>.ui.sidebar_width`).
+   * Default: the nearest `StorageNamespaceProvider`, else `cfg`.
+   * A key that already follows `<owner>.<area>.<name>` is used as is.
+   */
+  namespace?: string;
 }
 
 /**
@@ -152,10 +159,11 @@ function broadcastKey(
  * patch({ b: 3 }); // merges → { a: 1, b: 3 }, only writes if it changed
  */
 export function useLocalStorage<T>(
-  key: string,
+  keyInput: string,
   initialValue: T,
   options?: UseLocalStorageOptions
 ): UseLocalStorageReturn<T> {
+  const key = useResolvedStorageKey(keyInput, options?.namespace);
   const ttl = options?.ttl;
   // Always start with initialValue to match SSR
   const [storedValue, setStoredValue] = useState<T>(initialValue);
@@ -276,43 +284,25 @@ export function useLocalStorage<T>(
   };
 
   // Clear old data when localStorage is full
-  const clearOldData = () => {
+  // Drop evictable keys (our scheme, non-personal) when the quota is full.
+  // Tokens, drafts and third-party keys are never touched.
+  const evict = (fraction: number) => {
     try {
-      const keys = Object.keys(localStorage).filter(key => key && typeof key === 'string');
-      // Remove oldest items if we have more than 50 items
-      if (keys.length > 50) {
-        const itemsToRemove = Math.ceil(keys.length * 0.2);
-        for (let i = 0; i < itemsToRemove; i++) {
-          try {
-            const key = keys[i];
-            if (key) {
-              localStorage.removeItem(key);
-            }
-          } catch {
-            // Ignore errors when removing items
-          }
-        }
-      }
-    } catch (error) {
-      console.error('Error clearing old localStorage data:', error);
-    }
-  };
-
-  // Force clear all data if quota is exceeded
-  const forceClearAll = () => {
-    try {
-      const keys = Object.keys(localStorage);
-      for (const key of keys) {
+      const names = evictableKeys(window.localStorage).filter((name) => name !== key);
+      const count = fraction >= 1 ? names.length : Math.ceil(names.length * fraction);
+      for (const name of names.slice(0, count)) {
         try {
-          localStorage.removeItem(key);
+          window.localStorage.removeItem(name);
         } catch {
           // Ignore errors when removing items
         }
       }
     } catch (error) {
-      console.error('Error force clearing localStorage:', error);
+      console.error('Error clearing old localStorage data:', error);
     }
   };
+  const clearOldData = () => evict(0.2);
+  const forceClearAll = () => evict(1);
 
   // Prepare data for storage (with or without TTL wrapper)
   const prepareForStorage = (value: T): string => {

package/src/hooks/state/useSessionStorage.ts

@@ -3,6 +3,7 @@
 import { useState } from 'react';
 
 import { isQuotaExceededError } from './storage-quota';
+import { evictableKeys, useResolvedStorageKey } from './storage-namespace';
 
 /**
  * Storage wrapper format with metadata
@@ -27,6 +28,12 @@ export interface UseSessionStorageOptions {
    * @example 24 * 60 * 60 * 1000 // 24 hours
    */
   ttl?: number;
+  /**
+   * Owner for a bare key (`'wizard-step'` → `<owner>.ui.wizard_step`).
+   * Default: the nearest `StorageNamespaceProvider`, else `cfg`.
+   * A key that already follows `<owner>.<area>.<name>` is used as is.
+   */
+  namespace?: string;
 }
 
 /**
@@ -89,10 +96,11 @@ function isExpired<T>(wrapped: StorageWrapper<T>): boolean {
  * });
  */
 export function useSessionStorage<T>(
-  key: string,
+  keyInput: string,
   initialValue: T,
   options?: UseSessionStorageOptions
 ): UseSessionStorageReturn<T> {
+  const key = useResolvedStorageKey(keyInput, options?.namespace);
   const ttl = options?.ttl;
 
   // Get initial value from sessionStorage or use provided initialValue
@@ -152,44 +160,25 @@ export function useSessionStorage<T>(
     }
   };
 
-  // Clear old data when sessionStorage is full
-  const clearOldData = () => {
+  // Drop evictable keys (our scheme, non-personal) when the quota is full.
+  // Tokens, drafts and third-party keys are never touched.
+  const evict = (fraction: number) => {
     try {
-      const keys = Object.keys(sessionStorage).filter(k => k && typeof k === 'string');
-      // Remove oldest items if we have more than 50 items
-      if (keys.length > 50) {
-        const itemsToRemove = Math.ceil(keys.length * 0.2);
-        for (let i = 0; i < itemsToRemove; i++) {
-          try {
-            const k = keys[i];
-            if (k) {
-              sessionStorage.removeItem(k);
-            }
-          } catch {
-            // Ignore errors when removing items
-          }
-        }
-      }
-    } catch (error) {
-      console.error('Error clearing old sessionStorage data:', error);
-    }
-  };
-
-  // Force clear all data if quota is exceeded
-  const forceClearAll = () => {
-    try {
-      const keys = Object.keys(sessionStorage);
-      for (const k of keys) {
+      const names = evictableKeys(window.sessionStorage).filter((name) => name !== key);
+      const count = fraction >= 1 ? names.length : Math.ceil(names.length * fraction);
+      for (const name of names.slice(0, count)) {
         try {
-          sessionStorage.removeItem(k);
+          window.sessionStorage.removeItem(name);
         } catch {
           // Ignore errors when removing items
         }
       }
     } catch (error) {
-      console.error('Error force clearing sessionStorage:', error);
+      console.error('Error clearing old sessionStorage data:', error);
     }
   };
+  const clearOldData = () => evict(0.2);
+  const forceClearAll = () => evict(1);
 
   // Prepare data for storage (with or without TTL wrapper)
   const prepareForStorage = (value: T): string => {

package/src/hooks/state/useStoredValue.ts

@@ -19,6 +19,11 @@ export interface UseStoredValueOptions {
    * @example ttl: 24 * 60 * 60 * 1000 // 24 hours
    */
   ttl?: number;
+  /**
+   * Owner for a bare `storageKey`. Default: nearest `StorageNamespaceProvider`, else `cfg`.
+   * @see resolveStorageKey
+   */
+  namespace?: string;
 }
 
 /**
@@ -41,6 +46,9 @@ export type UseStoredValueReturn<T> = readonly [
  * Used by components (Input, Combobox, MultiSelect, Tabs, etc.) to add
  * optional persistence via a single `storageKey` prop.
  *
+ * `storageKey` follows the storage-key scheme (see `./storage-namespace`): a full
+ * `owner.area.name` key is used as is, a bare name lands under `<owner>.ui.<name>`.
+ *
  * When storageKey is undefined the hook is a no-op:
  *   - returns initialValue as current value
  *   - setValue / removeValue / patch are no-ops
@@ -55,12 +63,12 @@ export function useStoredValue<T>(
   options?: UseStoredValueOptions,
 ): UseStoredValueReturn<T> {
   const storageType = options?.storage ?? 'local';
-  const ttlOption = options?.ttl ? { ttl: options.ttl } : undefined;
+  const ttlOption = { ttl: options?.ttl, namespace: options?.namespace };
 
   // Both hooks are always called (rules of hooks — no conditional calls).
   // Only one of them is actually used depending on storageType.
   // When storageKey is undefined we pass a dummy key; the result is discarded.
-  const dummyKey = '__useStoredValue_noop__';
+  const dummyKey = 'cfg.ui.noop';
 
   const localResult = useLocalStorage<T>(
     storageType === 'local' && storageKey ? storageKey : dummyKey,