@djangocfg/ui-core 2.1.310 → 2.1.312

package/README.md

@@ -87,7 +87,7 @@ import { Button, Dialog, Table } from '@djangocfg/ui-core';
 </SidePanel>
 ```
 
-**`Drawer`** — modal vaul panel sliding from any edge (`top` / `right` / `bottom` / `left`). Sizes: `sm` `md` `lg` `xl` `full`, default `md`; or pass an explicit `width` / `height`. Pass `resizable` to drag the inner edge — auto-disabled on mobile (< 768px) unless `resizableOnDesktopOnly={false}`. Tune with `minSize` / `maxSize` (px) and observe via `onResizeChange`. Pass `persistKey` to save the resized size in `localStorage` and restore it on next open. The store is exported as `useDrawerSizeStore` (with `clearSize` / `clearAll`).
+**`Drawer`** — modal vaul panel sliding from any edge (`top` / `right` / `bottom` / `left`). Sizes: `sm` `md` `lg` `xl` `full`, default `md`; or pass an explicit `width` / `height`. Pass `resizable` to drag the inner edge — auto-disabled on mobile (< 768px) unless `resizableOnDesktopOnly={false}`. Tune with `minSize` / `maxSize` (px). Resize is controlled via `resizedSize` + `onSizeChange` (uncontrolled if omitted). For built-in `localStorage` persistence use the `useDrawerSize(key, { axis, min, max })` hook — it returns `{ size, setSize, reset }` you wire into the same props. Backed by the centralized `useUIPersistedState` / `useUIPersistStore` (see below).
 
 ```tsx
 <Drawer direction="right">
@@ -424,6 +424,58 @@ import '@djangocfg/ui-core/styles/globals';
 | `@djangocfg/ui-core/styles` | CSS |
 | `@djangocfg/ui-core/styles/palette` | Theme palette hooks & utilities |
 
+## Persisted UI State
+
+Centralized localStorage-backed store for component preferences. One zustand+persist store under `djangocfg.ui.state`, scoped by category. Single migration surface, single «reset all» button.
+
+### Per-component hooks
+
+```tsx
+// Drawer size
+const drawer = useDrawerSize('settings', { min: 320, max: 900 });
+<DrawerContent resizable resizedSize={drawer.size} onSizeChange={drawer.setSize} />
+
+// Tabs
+const { tab, setTab } = useTabsState('settings-page', 'general', {
+  allowed: ['general', 'appearance', 'advanced'],
+});
+<Tabs value={tab} onValueChange={setTab}>...</Tabs>
+
+// Accordion
+const { value, setValue } = useAccordionMultipleState('sidebar', ['general']);
+<Accordion type="multiple" value={value} onValueChange={setValue}>...</Accordion>
+```
+
+Need persist for something not on this list (table prefs, sidebar state, etc.)? Use the generic `useUIPersistedState` directly — it's the same API every per-component hook is built on top of.
+
+### Generic API
+
+```tsx
+import {
+  useUIPersistedState,
+  useUIPersistedStateThrottled,
+  useUIPersistStore,
+} from '@djangocfg/ui-core';
+
+// Build your own per-component hook
+const { value, setValue, reset, hydrated } = useUIPersistedState(
+  'my-scope', 'instance-key', defaultValue,
+  { sanitize: (raw) => /* clamp / validate / migrate */ raw },
+);
+
+// Throttled writes for high-frequency updates (live splitter, etc.)
+useUIPersistedStateThrottled('splitter', 'main', 50, 200 /* ms */);
+```
+
+### Inspection / DevTools
+
+```tsx
+useUIPersistStore.getState().getAll();        // snapshot of all scopes
+useUIPersistStore.getState().listScopes();    // ['drawer-size:width', 'tabs', ...]
+useUIPersistStore.getState().clearScope('tabs');
+useUIPersistStore.getState().clearAll();      // reset all UI preferences
+```
+
 ## Runtime Error Emitter
 
 Emit runtime errors as events (caught by ErrorTrackingProvider in layouts):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.310",
+  "version": "2.1.312",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -91,7 +91,7 @@
     "playground": "playground dev"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.310",
+    "@djangocfg/i18n": "^2.1.312",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -160,9 +160,9 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.310",
+    "@djangocfg/i18n": "^2.1.312",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.310",
+    "@djangocfg/typescript-config": "^2.1.312",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",

package/src/components/index.ts

@@ -41,7 +41,7 @@ export { Dialog, DialogTrigger, DialogClose, DialogContent, DialogHeader, Dialog
 export { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogTitle, AlertDialogTrigger, AlertDialogPortal, AlertDialogOverlay } from './overlay/alert-dialog';
 export { Popover, PopoverContent, PopoverTrigger, PopoverAnchor, PopoverArrow } from './overlay/popover';
 export { Sheet, SheetTrigger, SheetClose, SheetContent, SheetHeader, SheetFooter, SheetTitle, SheetDescription, SheetPortal, SheetOverlay } from './overlay/sheet';
-export { Drawer, DrawerTrigger, DrawerClose, DrawerContent, DrawerHeader, DrawerFooter, DrawerTitle, DrawerDescription, DrawerPortal, DrawerOverlay, useDrawerSizeStore } from './overlay/drawer';
+export { Drawer, DrawerTrigger, DrawerClose, DrawerContent, DrawerHeader, DrawerFooter, DrawerTitle, DrawerDescription, DrawerPortal, DrawerOverlay, useDrawerSize } from './overlay/drawer';
 export { ResponsiveSheet, ResponsiveSheetContent, ResponsiveSheetHeader, ResponsiveSheetTitle, ResponsiveSheetDescription, ResponsiveSheetFooter } from './overlay/responsive-sheet';
 export { SidePanel, SidePanelContent, SidePanelHeader, SidePanelTitle, SidePanelDescription, SidePanelBody, SidePanelFooter, SidePanelClose } from './overlay/side-panel';
 export type { SidePanelProps, SidePanelContentProps, SidePanelCloseProps } from './overlay/side-panel';
@@ -57,7 +57,11 @@ export { Menubar, MenubarMenu, MenubarTrigger, MenubarContent, MenubarItem, Menu
 export { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuGroup, DropdownMenuPortal, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuRadioGroup } from './navigation/dropdown-menu';
 export { ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuItem, ContextMenuLabel, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger } from './navigation/context-menu';
 export { Tabs, TabsContent, TabsList, TabsTrigger } from './navigation/tabs';
+export { useTabsState } from './navigation/tabs/useTabsState';
+export type { UseTabsStateOptions, UseTabsStateResult } from './navigation/tabs/useTabsState';
 export { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from './navigation/accordion';
+export { useAccordionSingleState, useAccordionMultipleState } from './navigation/accordion/useAccordionState';
+export type { UseAccordionSingleResult, UseAccordionMultipleResult } from './navigation/accordion/useAccordionState';
 export { Collapsible, CollapsibleContent, CollapsibleTrigger } from './navigation/collapsible';
 export { Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut } from './navigation/command';
 export { Link, LinkProvider, LinkComponentContext, useLinkComponent } from './navigation/link';

package/src/components/navigation/accordion/useAccordionState.ts

@@ -0,0 +1,69 @@
+'use client';
+
+import * as React from 'react';
+
+import { useUIPersistedState } from '../../../lib/persist';
+
+const SCOPE_SINGLE = 'accordion:single';
+const SCOPE_MULTIPLE = 'accordion:multiple';
+
+export interface UseAccordionSingleResult {
+  /** Currently open item id, or empty string if all closed. */
+  value: string;
+  setValue: (next: string) => void;
+  reset: () => void;
+}
+
+export interface UseAccordionMultipleResult {
+  /** List of open item ids. */
+  value: string[];
+  setValue: (next: string[]) => void;
+  reset: () => void;
+}
+
+/**
+ * Persist a single-mode Accordion's open item.
+ *
+ * @example
+ * const { value, setValue } = useAccordionSingleState('sidebar-groups');
+ * <Accordion type="single" value={value} onValueChange={setValue}>...</Accordion>
+ */
+export function useAccordionSingleState(
+  key: string,
+  defaultValue = '',
+): UseAccordionSingleResult {
+  const sanitize = React.useCallback(
+    (raw: string) => (typeof raw === 'string' ? raw : undefined),
+    [],
+  );
+  const persisted = useUIPersistedState<string>(SCOPE_SINGLE, key, defaultValue, { sanitize });
+  return {
+    value: persisted.value,
+    setValue: persisted.setValue,
+    reset: persisted.reset,
+  };
+}
+
+/**
+ * Persist a multiple-mode Accordion's open items.
+ *
+ * @example
+ * const { value, setValue } = useAccordionMultipleState('sidebar-groups', ['general']);
+ * <Accordion type="multiple" value={value} onValueChange={setValue}>...</Accordion>
+ */
+export function useAccordionMultipleState(
+  key: string,
+  defaultValue: string[] = [],
+): UseAccordionMultipleResult {
+  const sanitize = React.useCallback(
+    (raw: string[]) =>
+      Array.isArray(raw) && raw.every((v) => typeof v === 'string') ? raw : undefined,
+    [],
+  );
+  const persisted = useUIPersistedState<string[]>(SCOPE_MULTIPLE, key, defaultValue, { sanitize });
+  return {
+    value: persisted.value,
+    setValue: persisted.setValue,
+    reset: persisted.reset,
+  };
+}

package/src/components/navigation/tabs/useTabsState.ts

@@ -0,0 +1,57 @@
+'use client';
+
+import * as React from 'react';
+
+import { useUIPersistedState } from '../../../lib/persist';
+
+const SCOPE = 'tabs';
+
+export interface UseTabsStateOptions<T extends string = string> {
+  /**
+   * Whitelist of allowed tab values. If the persisted value is not in
+   * this list, falls back to default. Pass when you don't want a stale
+   * value (e.g. tab renamed/removed) to leak through.
+   */
+  allowed?: readonly T[];
+}
+
+export interface UseTabsStateResult<T extends string = string> {
+  /** Current tab value (default until hydrated, or if stored value is no longer allowed). */
+  tab: T;
+  /** Persist new tab value. Wire to `<Tabs onValueChange={...}>`. */
+  setTab: (next: T) => void;
+  /** Remove the persisted entry. */
+  reset: () => void;
+}
+
+/**
+ * Persist Tabs `value` between sessions.
+ *
+ * @example
+ * const { tab, setTab } = useTabsState('settings-page', 'general', { allowed: ['general', 'appearance', 'advanced'] });
+ * <Tabs value={tab} onValueChange={setTab}>...</Tabs>
+ */
+export function useTabsState<T extends string = string>(
+  key: string,
+  defaultTab: T,
+  options: UseTabsStateOptions<T> = {},
+): UseTabsStateResult<T> {
+  const { allowed } = options;
+  const sanitize = React.useCallback(
+    (raw: T) => {
+      if (typeof raw !== 'string') return undefined;
+      if (allowed && !allowed.includes(raw)) return undefined;
+      return raw;
+    },
+    [allowed],
+  );
+
+  const { value, setValue, reset } = useUIPersistedState<T>(
+    SCOPE,
+    key,
+    defaultTab,
+    { sanitize },
+  );
+
+  return { tab: value, setTab: setValue, reset };
+}

package/src/components/overlay/drawer/drawer.story.tsx

@@ -9,6 +9,7 @@ import {
   DrawerTitle,
   DrawerDescription,
   DrawerClose,
+  useDrawerSize,
   type DrawerSize,
 } from '.';
 import { Button } from '../../forms/button';
@@ -257,7 +258,7 @@ export const Resizable = () => {
           resizable
           minSize={320}
           maxSize={900}
-          onResizeChange={setSize}
+          onSizeChange={setSize}
         >
           <DrawerHeader>
             <DrawerTitle>Resizable</DrawerTitle>
@@ -277,42 +278,49 @@ export const Resizable = () => {
   );
 };
 
-export const ResizablePersisted = () => (
-  <div className="space-y-3">
-    <p className="text-sm text-muted-foreground">
-      Same as <code>Resizable</code>, but the size is persisted in
-      <code> localStorage</code> under <code>persistKey="story-demo"</code> —
-      reload the page and reopen, the last width is restored.
-    </p>
-    <Drawer direction="right">
-      <DrawerTrigger asChild>
-        <Button variant="outline">Open persisted drawer</Button>
-      </DrawerTrigger>
-      <DrawerContent
-        direction="right"
-        size="md"
-        resizable
-        persistKey="story-demo"
-        minSize={320}
-        maxSize={900}
-      >
-        <DrawerHeader>
-          <DrawerTitle>Resizable + persisted</DrawerTitle>
-          <DrawerDescription>
-            Width survives reloads. Open DevTools → Application → Local Storage
-            and look for <code>djangocfg.ui.drawer-sizes</code>.
-          </DrawerDescription>
-        </DrawerHeader>
-        <div className="p-4 text-sm">Drag the left edge to resize.</div>
-        <DrawerFooter>
-          <DrawerClose asChild>
-            <Button variant="outline">Close</Button>
-          </DrawerClose>
-        </DrawerFooter>
-      </DrawerContent>
-    </Drawer>
-  </div>
-);
+export const ResizablePersisted = () => {
+  const drawer = useDrawerSize('story-demo', { axis: 'width', min: 320, max: 900 });
+  return (
+    <div className="space-y-3">
+      <p className="text-sm text-muted-foreground">
+        Persistence is wired via the <code>useDrawerSize(key)</code> hook —
+        the drawer itself is just a controlled component. Reload the page and
+        reopen, the last width is restored from <code>localStorage</code>.
+      </p>
+      <div className="flex gap-2">
+        <Drawer direction="right">
+          <DrawerTrigger asChild>
+            <Button variant="outline">Open persisted drawer</Button>
+          </DrawerTrigger>
+          <DrawerContent
+            direction="right"
+            size="md"
+            resizable
+            minSize={320}
+            maxSize={900}
+            resizedSize={drawer.size}
+            onSizeChange={drawer.setSize}
+          >
+            <DrawerHeader>
+              <DrawerTitle>Resizable + persisted</DrawerTitle>
+              <DrawerDescription>
+                Stored in <code>djangocfg.ui.state</code>. Current:{' '}
+                {drawer.size != null ? `${Math.round(drawer.size)}px` : 'preset (480px)'}
+              </DrawerDescription>
+            </DrawerHeader>
+            <div className="p-4 text-sm">Drag the left edge to resize.</div>
+            <DrawerFooter>
+              <DrawerClose asChild>
+                <Button variant="outline">Close</Button>
+              </DrawerClose>
+            </DrawerFooter>
+          </DrawerContent>
+        </Drawer>
+        <Button variant="ghost" onClick={drawer.reset}>Reset stored size</Button>
+      </div>
+    </div>
+  );
+};
 
 export const NarrowViewport = () => (
   <div className="space-y-3">

package/src/components/overlay/drawer/index.tsx

@@ -5,7 +5,6 @@ import { Drawer as DrawerPrimitive } from 'vaul';
 
 import { cn } from '../../../lib/utils';
 import { useIsMobile } from '../../../hooks/media/useMobile';
-import { useDrawerSizeStore } from './store';
 
 const Drawer = ({
   shouldScaleBackground = true,
@@ -78,11 +77,6 @@ const verticalSizePx: Record<DrawerSize, number> = {
   full: 900,
 };
 
-// Anchor + border + radius only — no width/height bake-in. Length is
-// applied via inline `style` from props so vaul's first
-// `getBoundingClientRect()` measurement matches the final layout
-// (avoids the inset.left=mismatch bug when className-based defaults
-// leak into the first paint).
 const directionStyles = {
   bottom: "inset-x-0 bottom-0 mt-24 rounded-t-lg border-t",
   top: "inset-x-0 top-0 mb-24 rounded-b-lg border-b",
@@ -124,14 +118,14 @@ export interface DrawerContentProps
   minSize?: number;
   /** Max size in px when `resizable`. Width for horizontal, height for vertical. */
   maxSize?: number;
-  /** Called with the new size in px on every resize step. */
-  onResizeChange?: (size: number) => void;
   /**
-   * Persist resized size in localStorage under this key. Without it,
-   * resize is session-only. Width and height are stored separately,
-   * so the same key can be reused across directions.
+   * Controlled current size in px. Pair with `onSizeChange` for external
+   * persistence (see `useDrawerSize` hook). When `undefined`, the drawer
+   * is uncontrolled and size lives in local state.
    */
-  persistKey?: string;
+  resizedSize?: number;
+  /** Called once on pointer-up with the final resized size in px. */
+  onSizeChange?: (size: number) => void;
 }
 
 const DrawerContent = React.forwardRef<
@@ -149,8 +143,8 @@ const DrawerContent = React.forwardRef<
   resizableOnDesktopOnly = true,
   minSize,
   maxSize,
-  onResizeChange,
-  persistKey,
+  resizedSize,
+  onSizeChange,
   ...props
 }, ref) => {
   const isVertical = direction === 'bottom' || direction === 'top';
@@ -162,41 +156,25 @@ const DrawerContent = React.forwardRef<
   const minPx = minSize ?? defaultMin;
   const maxPx = maxSize ?? defaultMax;
 
-  const initialPx = isVertical
+  const presetPx = isVertical
     ? parseInitialPx(height, verticalSizePx[size])
     : parseInitialPx(width, horizontalSizePx[size]);
 
-  const [resizedPx, setResizedPx] = React.useState<number | null>(null);
-  const axis: 'width' | 'height' = isVertical ? 'height' : 'width';
+  // Uncontrolled: track size locally. Controlled: caller owns it via `resizedSize`.
+  const isControlled = resizedSize !== undefined;
+  const [internalPx, setInternalPx] = React.useState<number | null>(null);
+  const currentPx = isControlled ? clamp(resizedSize!, minPx, maxPx) : internalPx;
 
-  // Hydrate persist store on mount (skipHydration in middleware) and
-  // pull stored size for this key+axis. Clamp to current min/max so a
-  // value persisted under looser bounds doesn't escape.
+  // Reset uncontrolled state if direction or enabled flag flips, so we
+  // don't carry a horizontal width into a vertical drawer.
   React.useEffect(() => {
-    if (!resizeEnabled || !persistKey) return;
-    let cancelled = false;
-    const applyStored = () => {
-      if (cancelled) return;
-      const stored = useDrawerSizeStore.getState().getSize(persistKey, axis);
-      if (stored != null) {
-        setResizedPx(clamp(stored, minPx, maxPx));
-      }
-    };
-    Promise.resolve(useDrawerSizeStore.persist.rehydrate()).then(applyStored);
-    return () => {
-      cancelled = true;
-    };
-  }, [resizeEnabled, persistKey, axis, minPx, maxPx]);
-
-  // Reset resized state if direction or enabled flag flips, so we don't
-  // carry a horizontal width into a vertical drawer.
-  React.useEffect(() => {
-    setResizedPx(null);
-  }, [direction, resizeEnabled]);
+    if (!isControlled) setInternalPx(null);
+  }, [direction, resizeEnabled, isControlled]);
 
   const dragStateRef = React.useRef<{
     startCoord: number;
     startSize: number;
+    lastSize: number;
   } | null>(null);
 
   const handlePointerDown = React.useCallback((e: React.PointerEvent<HTMLDivElement>) => {
@@ -204,11 +182,13 @@ const DrawerContent = React.forwardRef<
     e.preventDefault();
     e.stopPropagation();
     (e.currentTarget as HTMLElement).setPointerCapture?.(e.pointerId);
+    const startSize = currentPx ?? presetPx;
     dragStateRef.current = {
       startCoord: isVertical ? e.clientY : e.clientX,
-      startSize: resizedPx ?? initialPx,
+      startSize,
+      lastSize: startSize,
     };
-  }, [resizeEnabled, isVertical, resizedPx, initialPx]);
+  }, [resizeEnabled, isVertical, currentPx, presetPx]);
 
   const handlePointerMove = React.useCallback((e: React.PointerEvent<HTMLDivElement>) => {
     const drag = dragStateRef.current;
@@ -216,30 +196,39 @@ const DrawerContent = React.forwardRef<
     e.preventDefault();
     const current = isVertical ? e.clientY : e.clientX;
     const delta = current - drag.startCoord;
-    // Direction sign: handle is on the side facing into the viewport, so
-    // dragging away from the anchor grows the drawer.
-    const sign =
-      direction === 'right' || direction === 'bottom' ? -1 : 1;
+    const sign = direction === 'right' || direction === 'bottom' ? -1 : 1;
     const next = clamp(drag.startSize + sign * delta, minPx, maxPx);
-    setResizedPx(next);
-    onResizeChange?.(next);
-  }, [direction, isVertical, minPx, maxPx, onResizeChange]);
+    drag.lastSize = next;
+    if (!isControlled) setInternalPx(next);
+    // Note: onSizeChange fires on pointer-up only — avoids hammering
+    // localStorage / external stores during drag. For live feedback
+    // during drag, render from `currentPx` (uncontrolled) or from your
+    // own state synced separately.
+  }, [direction, isVertical, minPx, maxPx, isControlled]);
 
   const handlePointerUp = React.useCallback((e: React.PointerEvent<HTMLDivElement>) => {
-    if (!dragStateRef.current) return;
+    const drag = dragStateRef.current;
+    if (!drag) return;
     (e.currentTarget as HTMLElement).releasePointerCapture?.(e.pointerId);
     dragStateRef.current = null;
-    if (persistKey && resizedPx != null) {
-      useDrawerSizeStore.getState().setSize(persistKey, axis, resizedPx);
-    }
-  }, [persistKey, axis, resizedPx]);
-
-  const resolvedWidth = !isVertical
-    ? (resizedPx != null ? `${resizedPx}px` : (toCssLength(width) ?? horizontalSizePresets[size]))
+    onSizeChange?.(drag.lastSize);
+  }, [onSizeChange]);
+
+  // Viewport clamp — keeps the drawer inside the window on narrow screens.
+  // Without this, a fixed `width: 720px` on a 600px-wide window paints the
+  // drawer 120px past the right edge (off-screen for `direction="right"`).
+  // Applied to BOTH the resized px value and the initial preset so user-
+  // dragged widths can't overflow either. CSS `min()` is cheap and the
+  // browser re-evaluates on every viewport change, so window resize works
+  // for free.
+  const rawWidth = !isVertical
+    ? (currentPx != null ? `${currentPx}px` : (toCssLength(width) ?? horizontalSizePresets[size]))
     : undefined;
-  const resolvedHeight = isVertical
-    ? (resizedPx != null ? `${resizedPx}px` : (toCssLength(height) ?? verticalSizePresets[size]))
+  const rawHeight = isVertical
+    ? (currentPx != null ? `${currentPx}px` : (toCssLength(height) ?? verticalSizePresets[size]))
     : undefined;
+  const resolvedWidth = rawWidth ? `min(100vw, ${rawWidth})` : undefined;
+  const resolvedHeight = rawHeight ? `min(100vh, ${rawHeight})` : undefined;
 
   const handlePosition: Record<typeof direction, string> = {
     right: 'left-0 top-0 h-full w-1.5 -translate-x-1/2 cursor-ew-resize',
@@ -352,4 +341,5 @@ export {
   DrawerDescription,
 }
 
-export { useDrawerSizeStore } from './store';
+export { useDrawerSize } from './useDrawerSize';
+export type { UseDrawerSizeOptions, UseDrawerSizeResult } from './useDrawerSize';

package/src/components/overlay/drawer/useDrawerSize.ts

@@ -0,0 +1,71 @@
+'use client';
+
+import * as React from 'react';
+
+import { useUIPersistedState } from '../../../lib/persist';
+
+const SCOPE_WIDTH = 'drawer-size:width';
+const SCOPE_HEIGHT = 'drawer-size:height';
+
+export interface UseDrawerSizeOptions {
+  /** Which axis to read/write. `'width'` for left/right, `'height'` for top/bottom. */
+  axis?: 'width' | 'height';
+  /** Clamp loaded value into these bounds (recommended). */
+  min?: number;
+  max?: number;
+}
+
+export interface UseDrawerSizeResult {
+  /** Persisted size in px, or `undefined` if nothing stored / not yet hydrated. */
+  size: number | undefined;
+  /** Persist a new size. */
+  setSize: (size: number) => void;
+  /** Remove the persisted entry for this key. */
+  reset: () => void;
+}
+
+/**
+ * Hook that wires a Drawer to centralized persisted UI state.
+ *
+ * Width and height live in separate scopes, so the same `key` can be
+ * reused across directions without one axis overwriting the other.
+ *
+ * @example
+ * const drawer = useDrawerSize('settings', { min: 320, max: 900 });
+ * <DrawerContent
+ *   resizable
+ *   resizedSize={drawer.size}
+ *   onSizeChange={drawer.setSize}
+ * />
+ */
+export function useDrawerSize(
+  key: string,
+  options: UseDrawerSizeOptions = {},
+): UseDrawerSizeResult {
+  const { axis = 'width', min, max } = options;
+  const scope = axis === 'height' ? SCOPE_HEIGHT : SCOPE_WIDTH;
+
+  const sanitize = React.useCallback(
+    (raw: number) => {
+      if (typeof raw !== 'number' || !Number.isFinite(raw)) return undefined;
+      let v = raw;
+      if (min != null) v = Math.max(v, min);
+      if (max != null) v = Math.min(v, max);
+      return v;
+    },
+    [min, max],
+  );
+
+  const persisted = useUIPersistedState<number | undefined>(
+    scope,
+    key,
+    undefined,
+    { sanitize: (raw) => (raw == null ? undefined : sanitize(raw)) },
+  );
+
+  return {
+    size: persisted.value,
+    setSize: persisted.setValue,
+    reset: persisted.reset,
+  };
+}

package/src/lib/index.ts

@@ -2,3 +2,4 @@ export * from "./utils";
 export * from "./logger";
 export * from "./dialog-service";
 export * from "./env";
+export * from "./persist";

package/src/lib/persist/index.ts

@@ -0,0 +1,11 @@
+'use client';
+
+export { useUIPersistStore } from './store';
+export {
+  useUIPersistedState,
+  useUIPersistedStateThrottled,
+} from './useUIPersistedState';
+export type {
+  UseUIPersistedStateOptions,
+  UseUIPersistedStateResult,
+} from './useUIPersistedState';

package/src/lib/persist/store.ts

@@ -0,0 +1,80 @@
+'use client';
+
+import { create } from 'zustand';
+import { persist, createJSONStorage } from 'zustand/middleware';
+
+/**
+ * Centralized UI-state persistence for ui-core components.
+ *
+ * Layout: `state[scope][key] = value`. Scopes namespace different
+ * categories (e.g. `'drawer-size'`, `'tabs'`, `'accordion'`) so keys
+ * never collide across components.
+ *
+ * One localStorage entry serves all components — single migration
+ * surface, single «reset all UI preferences» button.
+ */
+type ScopeMap = Record<string, Record<string, unknown>>;
+
+interface UIPersistStore {
+  state: ScopeMap;
+  set: (scope: string, key: string, value: unknown) => void;
+  get: <T>(scope: string, key: string) => T | undefined;
+  remove: (scope: string, key: string) => void;
+  clearScope: (scope: string) => void;
+  clearAll: () => void;
+  /** DevTools/inspection: snapshot of all scopes. */
+  getAll: () => ScopeMap;
+  /** DevTools/inspection: list scope names. */
+  listScopes: () => string[];
+}
+
+const noopStorage = {
+  getItem: () => null,
+  setItem: () => undefined,
+  removeItem: () => undefined,
+};
+
+export const useUIPersistStore = create<UIPersistStore>()(
+  persist(
+    (set, get) => ({
+      state: {},
+      set: (scope, key, value) => {
+        set((s) => ({
+          state: {
+            ...s.state,
+            [scope]: { ...s.state[scope], [key]: value },
+          },
+        }));
+      },
+      get: <T,>(scope: string, key: string) =>
+        get().state[scope]?.[key] as T | undefined,
+      remove: (scope, key) => {
+        set((s) => {
+          const scoped = s.state[scope];
+          if (!scoped || !(key in scoped)) return s;
+          const { [key]: _removed, ...rest } = scoped;
+          return { state: { ...s.state, [scope]: rest } };
+        });
+      },
+      clearScope: (scope) => {
+        set((s) => {
+          if (!(scope in s.state)) return s;
+          const { [scope]: _removed, ...rest } = s.state;
+          return { state: rest };
+        });
+      },
+      clearAll: () => set({ state: {} }),
+      getAll: () => get().state,
+      listScopes: () => Object.keys(get().state),
+    }),
+    {
+      name: 'djangocfg.ui.state',
+      version: 1,
+      storage: createJSONStorage(() =>
+        typeof window !== 'undefined' ? window.localStorage : noopStorage,
+      ),
+      // Components hydrate explicitly on mount via `useUIPersistedState`.
+      skipHydration: true,
+    },
+  ),
+);

package/src/lib/persist/useUIPersistedState.ts

@@ -0,0 +1,123 @@
+'use client';
+
+import * as React from 'react';
+
+import { useUIPersistStore } from './store';
+
+export interface UseUIPersistedStateOptions<T> {
+  /**
+   * Optional sanitizer applied to the stored value on load. Use it to
+   * clamp numbers into bounds, drop unknown enum values, or migrate
+   * shape. Return `undefined` to fall back to default.
+   */
+  sanitize?: (raw: T) => T | undefined;
+}
+
+export interface UseUIPersistedStateResult<T> {
+  /** Current value: persisted (post-sanitize) if available, otherwise the default. */
+  value: T;
+  /** Persist a new value. */
+  setValue: (next: T) => void;
+  /** Remove the persisted entry. `value` reverts to default on next render. */
+  reset: () => void;
+  /** True once the persist middleware has rehydrated from storage. */
+  hydrated: boolean;
+}
+
+/**
+ * Read/write a piece of UI state in the centralized persisted store.
+ *
+ * @param scope  Namespace (e.g. `'drawer-size'`, `'tabs'`). Pick a
+ *               stable string per component family.
+ * @param key    Per-instance identifier within the scope.
+ * @param defaultValue  Used until hydration completes or when no value is stored.
+ *
+ * @example
+ * const { value, setValue, reset } = useUIPersistedState('tabs', 'settings', 'general');
+ */
+export function useUIPersistedState<T>(
+  scope: string,
+  key: string,
+  defaultValue: T,
+  options: UseUIPersistedStateOptions<T> = {},
+): UseUIPersistedStateResult<T> {
+  const { sanitize } = options;
+  const [hydrated, setHydrated] = React.useState(false);
+
+  React.useEffect(() => {
+    let cancelled = false;
+    Promise.resolve(useUIPersistStore.persist.rehydrate()).then(() => {
+      if (!cancelled) setHydrated(true);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const stored = useUIPersistStore(
+    (s) => s.state[scope]?.[key] as T | undefined,
+  );
+
+  const value = React.useMemo(() => {
+    if (!hydrated || stored === undefined) return defaultValue;
+    if (sanitize) {
+      const sanitized = sanitize(stored);
+      return sanitized === undefined ? defaultValue : sanitized;
+    }
+    return stored;
+  }, [hydrated, stored, defaultValue, sanitize]);
+
+  const setValue = React.useCallback(
+    (next: T) => {
+      useUIPersistStore.getState().set(scope, key, next);
+    },
+    [scope, key],
+  );
+
+  const reset = React.useCallback(() => {
+    useUIPersistStore.getState().remove(scope, key);
+  }, [scope, key]);
+
+  return { value, setValue, reset, hydrated };
+}
+
+/**
+ * Same as `useUIPersistedState` but trailing-edge throttles writes by
+ * `delayMs`. Use for high-frequency updates (live splitter drag, scroll
+ * position) where you don't want to hammer storage.
+ */
+export function useUIPersistedStateThrottled<T>(
+  scope: string,
+  key: string,
+  defaultValue: T,
+  delayMs: number,
+  options: UseUIPersistedStateOptions<T> = {},
+): UseUIPersistedStateResult<T> {
+  const base = useUIPersistedState(scope, key, defaultValue, options);
+  const timerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+  const pendingRef = React.useRef<T | null>(null);
+
+  const setValue = React.useCallback(
+    (next: T) => {
+      pendingRef.current = next;
+      if (timerRef.current != null) return;
+      timerRef.current = setTimeout(() => {
+        timerRef.current = null;
+        if (pendingRef.current !== null) {
+          base.setValue(pendingRef.current);
+          pendingRef.current = null;
+        }
+      }, delayMs);
+    },
+    [base, delayMs],
+  );
+
+  React.useEffect(
+    () => () => {
+      if (timerRef.current != null) clearTimeout(timerRef.current);
+    },
+    [],
+  );
+
+  return { ...base, setValue };
+}

package/src/components/overlay/drawer/store.ts

@@ -1,64 +0,0 @@
-'use client';
-
-import { create } from 'zustand';
-import { persist, createJSONStorage } from 'zustand/middleware';
-
-/**
- * Persisted drawer sizes keyed by `persistKey`.
- *
- * Stores width (left/right drawers) and height (top/bottom drawers)
- * separately under the same key, so a single key can drive both axes
- * if the drawer is reused with different directions.
- */
-interface DrawerSizeEntry {
-  width?: number;
-  height?: number;
-}
-
-interface DrawerSizeStore {
-  sizes: Record<string, DrawerSizeEntry>;
-  setSize: (key: string, axis: 'width' | 'height', size: number) => void;
-  getSize: (key: string, axis: 'width' | 'height') => number | undefined;
-  clearSize: (key: string) => void;
-  clearAll: () => void;
-}
-
-const noopStorage = {
-  getItem: () => null,
-  setItem: () => undefined,
-  removeItem: () => undefined,
-};
-
-export const useDrawerSizeStore = create<DrawerSizeStore>()(
-  persist(
-    (set, get) => ({
-      sizes: {},
-      setSize: (key, axis, size) => {
-        set((state) => ({
-          sizes: {
-            ...state.sizes,
-            [key]: { ...state.sizes[key], [axis]: size },
-          },
-        }));
-      },
-      getSize: (key, axis) => get().sizes[key]?.[axis],
-      clearSize: (key) => {
-        set((state) => {
-          const { [key]: _removed, ...rest } = state.sizes;
-          return { sizes: rest };
-        });
-      },
-      clearAll: () => set({ sizes: {} }),
-    }),
-    {
-      name: 'djangocfg.ui.drawer-sizes',
-      version: 1,
-      storage: createJSONStorage(() =>
-        typeof window !== 'undefined' ? window.localStorage : noopStorage,
-      ),
-      // Skip auto-hydrate so SSR markup doesn't differ from first client paint.
-      // Components hydrate explicitly on mount via `useEffect`.
-      skipHydration: true,
-    },
-  ),
-);