@djangocfg/ui-core 2.1.309 → 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`.
+**`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.309",
+  "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.309",
+    "@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.309",
+    "@djangocfg/i18n": "^2.1.312",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.309",
+    "@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 } 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';
@@ -238,6 +239,89 @@ export const CustomWidth = () => (
   </Drawer>
 );
 
+export const Resizable = () => {
+  const [size, setSize] = React.useState<number | null>(null);
+  return (
+    <div className="space-y-3">
+      <p className="text-sm text-muted-foreground">
+        Drag the inner edge to resize. Disabled on mobile (&lt; 768px) by
+        default — pass <code>resizableOnDesktopOnly={'{false}'}</code> to allow
+        on touch.
+      </p>
+      <Drawer direction="right">
+        <DrawerTrigger asChild>
+          <Button variant="outline">Open resizable drawer</Button>
+        </DrawerTrigger>
+        <DrawerContent
+          direction="right"
+          size="md"
+          resizable
+          minSize={320}
+          maxSize={900}
+          onSizeChange={setSize}
+        >
+          <DrawerHeader>
+            <DrawerTitle>Resizable</DrawerTitle>
+            <DrawerDescription>
+              Current width: {size != null ? `${Math.round(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>
+    </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">
     <p className="text-sm text-muted-foreground">

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

@@ -4,6 +4,7 @@ import * as React from 'react';
 import { Drawer as DrawerPrimitive } from 'vaul';
 
 import { cn } from '../../../lib/utils';
+import { useIsMobile } from '../../../hooks/media/useMobile';
 
 const Drawer = ({
   shouldScaleBackground = true,
@@ -56,11 +57,26 @@ const verticalSizePresets: Record<DrawerSize, string> = {
   full: '100vh',
 };
 
-// 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).
+// Numeric fallbacks used as initial size when resize starts and the
+// user has not provided an explicit width/height. We can't read the
+// CSS `min(100vw, …px)` value reliably before the first paint, so we
+// take the px portion as a baseline.
+const horizontalSizePx: Record<DrawerSize, number> = {
+  sm: 360,
+  md: 480,
+  lg: 640,
+  xl: 800,
+  full: 1200,
+};
+
+const verticalSizePx: Record<DrawerSize, number> = {
+  sm: 240,
+  md: 360,
+  lg: 480,
+  xl: 640,
+  full: 900,
+};
+
 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",
@@ -73,6 +89,18 @@ const toCssLength = (value: string | number | undefined): string | undefined =>
   return typeof value === 'number' ? `${value}px` : value;
 };
 
+const parseInitialPx = (value: string | number | undefined, fallback: number): number => {
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string') {
+    const match = value.match(/(-?\d+(?:\.\d+)?)/);
+    if (match) return Number(match[1]);
+  }
+  return fallback;
+};
+
+const clamp = (value: number, min: number, max: number) =>
+  Math.min(Math.max(value, min), max);
+
 export interface DrawerContentProps
   extends React.ComponentPropsWithoutRef<typeof DrawerPrimitive.Content> {
   direction?: 'bottom' | 'right' | 'left' | 'top';
@@ -82,20 +110,132 @@ export interface DrawerContentProps
   width?: string | number;
   /** CSS length for height — applies to top/bottom drawers. Overrides `size`. */
   height?: string | number;
+  /** Allow user to resize the drawer by dragging its inner edge. */
+  resizable?: boolean;
+  /** Disable resize on mobile viewports (< 768px). Default `true`. */
+  resizableOnDesktopOnly?: boolean;
+  /** Min size in px when `resizable`. Width for horizontal, height for vertical. */
+  minSize?: number;
+  /** Max size in px when `resizable`. Width for horizontal, height for vertical. */
+  maxSize?: number;
+  /**
+   * 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.
+   */
+  resizedSize?: number;
+  /** Called once on pointer-up with the final resized size in px. */
+  onSizeChange?: (size: number) => void;
 }
 
 const DrawerContent = React.forwardRef<
   React.ElementRef<typeof DrawerPrimitive.Content>,
   DrawerContentProps
->(({ className, children, direction = 'bottom', size = 'md', width, height, style, ...props }, ref) => {
+>(({
+  className,
+  children,
+  direction = 'bottom',
+  size = 'md',
+  width,
+  height,
+  style,
+  resizable = false,
+  resizableOnDesktopOnly = true,
+  minSize,
+  maxSize,
+  resizedSize,
+  onSizeChange,
+  ...props
+}, ref) => {
   const isVertical = direction === 'bottom' || direction === 'top';
+  const isMobile = useIsMobile();
+  const resizeEnabled = resizable && (!resizableOnDesktopOnly || !isMobile);
+
+  const defaultMin = isVertical ? 200 : 280;
+  const defaultMax = isVertical ? 800 : 960;
+  const minPx = minSize ?? defaultMin;
+  const maxPx = maxSize ?? defaultMax;
 
-  const resolvedWidth = !isVertical
-    ? (toCssLength(width) ?? horizontalSizePresets[size])
+  const presetPx = isVertical
+    ? parseInitialPx(height, verticalSizePx[size])
+    : parseInitialPx(width, horizontalSizePx[size]);
+
+  // 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;
+
+  // Reset uncontrolled state if direction or enabled flag flips, so we
+  // don't carry a horizontal width into a vertical drawer.
+  React.useEffect(() => {
+    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>) => {
+    if (!resizeEnabled) return;
+    e.preventDefault();
+    e.stopPropagation();
+    (e.currentTarget as HTMLElement).setPointerCapture?.(e.pointerId);
+    const startSize = currentPx ?? presetPx;
+    dragStateRef.current = {
+      startCoord: isVertical ? e.clientY : e.clientX,
+      startSize,
+      lastSize: startSize,
+    };
+  }, [resizeEnabled, isVertical, currentPx, presetPx]);
+
+  const handlePointerMove = React.useCallback((e: React.PointerEvent<HTMLDivElement>) => {
+    const drag = dragStateRef.current;
+    if (!drag) return;
+    e.preventDefault();
+    const current = isVertical ? e.clientY : e.clientX;
+    const delta = current - drag.startCoord;
+    const sign = direction === 'right' || direction === 'bottom' ? -1 : 1;
+    const next = clamp(drag.startSize + sign * delta, minPx, maxPx);
+    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>) => {
+    const drag = dragStateRef.current;
+    if (!drag) return;
+    (e.currentTarget as HTMLElement).releasePointerCapture?.(e.pointerId);
+    dragStateRef.current = null;
+    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
-    ? (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',
+    left: 'right-0 top-0 h-full w-1.5 translate-x-1/2 cursor-ew-resize',
+    bottom: 'top-0 left-0 w-full h-1.5 -translate-y-1/2 cursor-ns-resize',
+    top: 'bottom-0 left-0 w-full h-1.5 translate-y-1/2 cursor-ns-resize',
+  };
 
   return (
     <DrawerPortal>
@@ -108,13 +248,29 @@ const DrawerContent = React.forwardRef<
           className
         )}
         style={{
-          transition: 'transform 300ms cubic-bezier(0.32, 0.72, 0, 1)',
+          transition: dragStateRef.current
+            ? 'none'
+            : 'transform 300ms cubic-bezier(0.32, 0.72, 0, 1)',
           ...(resolvedWidth ? { width: resolvedWidth } : {}),
           ...(resolvedHeight ? { height: resolvedHeight } : {}),
           ...style,
         }}
         {...props}
       >
+        {resizeEnabled && (
+          <div
+            role="separator"
+            aria-orientation={isVertical ? 'horizontal' : 'vertical'}
+            onPointerDown={handlePointerDown}
+            onPointerMove={handlePointerMove}
+            onPointerUp={handlePointerUp}
+            onPointerCancel={handlePointerUp}
+            className={cn(
+              "absolute z-10 select-none touch-none bg-transparent hover:bg-border/60 transition-colors",
+              handlePosition[direction]
+            )}
+          />
+        )}
         {isVertical && <div className="mx-auto mt-4 h-2 w-[100px] rounded-full bg-muted" />}
         {children}
       </DrawerPrimitive.Content>
@@ -184,3 +340,6 @@ export {
   DrawerTitle,
   DrawerDescription,
 }
+
+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 };
+}