@djangocfg/ui-core 2.1.602 → 2.1.604

package/README.md

@@ -51,7 +51,7 @@ import { UiProviders, Button, Card } from '@djangocfg/ui-core';
 | Group | Examples |
 |---|---|
 | `components/data/` | Avatar · AvatarGroup · Badge · BadgeOverflow · Card · Table · BalancedText · Skeleton · Stat · Status · Progress · CircularProgress · Carousel · Calendar · Toggle · ToggleGroup · RelativeTimeCard (`timeZone` prop) · Chart (subpath `/chart`) |
-| `components/forms/` | Button · DownloadButton · ButtonGroup · Input · InputGroup · InputAffix · InputOTP · OTPInput · PhoneInput · MaskInput · SegmentedInput · TagsInput · Textarea · Switch · Checkbox · CheckboxGroup · RadioGroup · Slider · Form · Field · Editable · SettingRow / SettingsBlock · DateField · TimeField · DateTimeField · MoneyField · FilterButton · FilterMenu · PopoverActionButton · TimePicker (legacy) |
+| `components/forms/` | Button · CONTROL_SIZE · DownloadButton · ButtonGroup · Input · InputGroup · InputAffix · InputOTP · OTPInput · PhoneInput · MaskInput · SegmentedInput · TagsInput · Textarea · Switch · Checkbox · CheckboxGroup · RadioGroup · Slider · Form · Field · Editable · SettingRow / SettingsBlock · DateField · TimeField · DateTimeField · MoneyField · FilterButton · FilterMenu · PopoverActionButton · TimePicker (legacy) |
 | `components/select/` | Select · Combobox · ComboboxAsync · MultiSelect · MultiSelectPro · CountrySelect · LanguageSelect · TimezoneSelect |
 | `components/feedback/` | Alert · Toast (sonner) · Banner · Empty · Preloader · Spinner |
 | `components/overlay/` | Dialog · AlertDialog · Drawer · Sheet · ResponsiveSheet · SidePanel · Popover · Tooltip · HoverCard |
@@ -61,6 +61,29 @@ import { UiProviders, Button, Card } from '@djangocfg/ui-core';
 | `components/specialized/` | CopyButton · CopyField · Kbd · Flag · ImageWithFallback · Item · TokenIcon · Portal · Presence · Primitive · VisuallyHidden |
 | `components/boundary/` | Boundary (error boundary, mounted by `UiProviders`) |
 
+### Control sizes
+
+`Button` and every field-like control read one height ladder,
+`CONTROL_SIZE` (`forms/control-size.ts`), so a row of them lines up at every
+size. Never write `h-9` / `h-10` on a control: read the map, or pass the size.
+
+| Size | Height | Button `size` | `Input` / `InputGroup` / `DateField` `inputSize` | `SelectTrigger` `size` |
+|---|---|---|---|---|
+| `xs` | 28px (`h-7`) | yes | yes | yes |
+| `sm` | 32px (`h-8`) | yes | yes | yes |
+| `default` | 36px (`h-9`) | yes | yes | yes |
+| `lg` | 44px (`h-11`) | yes | yes | yes |
+| `huge` | 56px (`h-14`) | yes | no | no |
+
+`Button` also has `icon` (36px square). Triggers built on `Button`
+(`Combobox`, `LanguageSelect`, `DatePicker`) take their height from the Button
+size; the multi-select triggers use `minHeight` so chips can wrap but never
+sit under the fixed control. Not on the ladder, on purpose: `FilterButton`
+(its `FilterBar` sets the height), OTP / segmented cells (square code cells),
+and `Textarea` (multi-line).
+`control-size.test.tsx` fails if `Button`, `Input` or `SelectTrigger` stop
+agreeing; the Storybook story `Controls / Alignment` draws the guide lines.
+
 ### MenuBuilder
 
 Declarative menus: pass `MenuItem[]` and a trigger, it renders through the
@@ -94,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.602",
+  "version": "2.1.604",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -120,19 +120,21 @@
     "dist",
     "src",
     "!src/**/*.stories.tsx",
+    "!src/**/*.test.{ts,tsx}",
     "!src/components/_gallery.tsx",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "lint": "eslint .",
+    "test": "vitest run",
     "check": "tsc --noEmit && node scripts/check-preset-contrast.mjs && node scripts/check-docs.mjs",
     "check:contrast": "node scripts/check-preset-contrast.mjs",
     "check:docs": "node scripts/check-docs.mjs"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.602",
-    "@djangocfg/i18n": "^2.1.602",
+    "@djangocfg/api": "^2.1.604",
+    "@djangocfg/i18n": "^2.1.604",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -208,10 +210,10 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/api": "^2.1.602",
-    "@djangocfg/eslint-config": "^2.1.602",
-    "@djangocfg/i18n": "^2.1.602",
-    "@djangocfg/typescript-config": "^2.1.602",
+    "@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",
@@ -219,7 +221,8 @@
     "lucide-react": "^0.545.0",
     "next": "^16.2.10",
     "storybook": "^10.5.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
   },
   "publishConfig": {
     "access": "public"

package/src/components/data/toggle/index.tsx

@@ -6,6 +6,7 @@ import * as React from 'react';
 import * as TogglePrimitive from '@radix-ui/react-toggle';
 
 import { cn } from '../../../lib/utils';
+import { CONTROL_SIZE } from '../../forms/control-size';
 
 const toggleVariants = cva(
   "inline-flex items-center justify-center gap-2 rounded-[var(--radius)] text-sm font-medium transition-colors hover:bg-muted hover:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
@@ -17,9 +18,9 @@ const toggleVariants = cva(
           "border border-border bg-transparent shadow-sm hover:bg-accent hover:text-accent-foreground",
       },
       size: {
-        default: "h-9 px-2 min-w-9",
-        sm: "h-8 px-1.5 min-w-8",
-        lg: "h-10 px-2.5 min-w-10",
+        default: cn(CONTROL_SIZE.default.height, "px-2 min-w-9"),
+        sm: cn(CONTROL_SIZE.sm.height, "px-1.5 min-w-8"),
+        lg: cn(CONTROL_SIZE.lg.height, "px-2.5 min-w-11"),
       },
     },
     defaultVariants: {

package/src/components/forms/button/index.tsx

@@ -8,6 +8,7 @@ import { Slot } from '@radix-ui/react-slot';
 
 import { cn } from '../../../lib/utils';
 import { Link } from '../../navigation/link';
+import { buttonSizeClass, CONTROL_SIZE } from '../control-size';
 
 const buttonVariants = cva(
   "inline-flex cursor-pointer items-center justify-center gap-2 whitespace-nowrap rounded-[var(--radius)] text-sm font-semibold transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
@@ -30,13 +31,16 @@ const buttonVariants = cva(
         ghost: "hover:bg-accent hover:text-accent-foreground",
         link: "text-primary underline-offset-4 hover:underline",
       },
+      // Height comes from the shared control ladder, so a Button at any size
+      // lines up with the Input / Select trigger of the same size. Only the
+      // corner radius is decided here.
       size: {
-        default: "h-9 px-4 py-2",
-        sm: "h-8 rounded-[var(--radius)] px-3 text-sm",
-        xs: "h-7 rounded-[var(--radius-sm)] px-2 py-1 text-xs",
-        lg: "h-11 rounded-[var(--radius)] px-8",
-        huge: "h-14 rounded-[var(--radius)] px-10 text-lg",
-        icon: "h-9 w-9",
+        default: buttonSizeClass('default'),
+        sm: cn(buttonSizeClass('sm'), "rounded-[var(--radius)]"),
+        xs: cn(buttonSizeClass('xs'), "rounded-[var(--radius-sm)]"),
+        lg: cn(buttonSizeClass('lg'), "rounded-[var(--radius)]"),
+        huge: cn(buttonSizeClass('huge'), "rounded-[var(--radius)]"),
+        icon: cn(CONTROL_SIZE.default.height, "w-9"),
       },
       // Most variants ship a baked-in `shadow`/`shadow-sm` for a lifted look.
       // `elevated={false}` flattens that (e.g. controls grouped inside a card —

package/src/components/forms/control-size.ts

@@ -0,0 +1,67 @@
+import { cn } from '../../lib/utils';
+
+/**
+ * The one height ladder every field-like control and `Button` reads.
+ *
+ * A row of `<Input/> <Select/> <Button/>` only lines up if each of them gets
+ * its height for the same size name from the same place. Two ladders drifting
+ * apart is invisible per component and obvious the moment they share a row, so
+ * a control never spells `h-9` / `h-10` itself — it reads this map.
+ *
+ * Tailwind reads complete class tokens only, so every entry is a literal
+ * string; never build one by interpolation.
+ *
+ * - `height` / `minHeight`: the shared token. `minHeight` is for triggers that
+ *   grow with their content (chips, tags) and must still never be shorter than
+ *   the fixed control of the same size.
+ * - `button`: horizontal padding and type size of a `Button` at this size.
+ * - `field`: horizontal and vertical padding and type size of a text field.
+ *   `default` keeps `text-base md:text-sm` so a phone does not zoom on focus.
+ *
+ * `huge` exists for `Button` only; no field has one.
+ */
+export const CONTROL_SIZE = {
+  xs: {
+    height: 'h-7',
+    minHeight: 'min-h-7',
+    button: 'px-2 py-1 text-xs',
+    field: 'px-2 py-0.5 text-xs',
+  },
+  sm: {
+    height: 'h-8',
+    minHeight: 'min-h-8',
+    button: 'px-3 text-sm',
+    field: 'px-2.5 py-1 text-sm',
+  },
+  default: {
+    height: 'h-9',
+    minHeight: 'min-h-9',
+    button: 'px-4 py-2',
+    field: 'px-3 py-1 text-base md:text-sm',
+  },
+  lg: {
+    height: 'h-11',
+    minHeight: 'min-h-11',
+    button: 'px-8',
+    field: 'px-4 py-2 text-base',
+  },
+  huge: {
+    height: 'h-14',
+    minHeight: 'min-h-14',
+    button: 'px-10 text-lg',
+  },
+} as const;
+
+/** Every size name on the ladder. */
+export type ControlSize = keyof typeof CONTROL_SIZE;
+
+/** The sizes a text field offers — the ladder without `huge`. */
+export type FieldControlSize = Exclude<ControlSize, 'huge'>;
+
+/** Height, padding and type size of a fixed-height field at `size`. */
+export const fieldSizeClass = (size: FieldControlSize = 'default'): string =>
+  cn(CONTROL_SIZE[size].height, CONTROL_SIZE[size].field);
+
+/** Height, padding and type size of a `Button` at `size`. */
+export const buttonSizeClass = (size: ControlSize = 'default'): string =>
+  cn(CONTROL_SIZE[size].height, CONTROL_SIZE[size].button);

package/src/components/forms/datetime-field/date-field.tsx

@@ -15,6 +15,7 @@ import { useIsTouch } from '../../../hooks/media';
 import { Popover, PopoverContent, PopoverTrigger } from '../../overlay/popover';
 import { Calendar } from '../../data/calendar/calendar';
 import { formatDateString, parseDateString } from './date-time-utils';
+import type { FieldControlSize } from '../control-size';
 import { NativeFieldShell, NATIVE_FIELD_INPUT_CLASS } from './native-field-shell';
 import { IconTrigger, PopoverChevron } from './popover-chevron';
 
@@ -49,6 +50,8 @@ export interface DateFieldProps {
    */
   id?: string;
 
+  /** Height from the shared control ladder — same names as `Input`'s `inputSize`. */
+  inputSize?: FieldControlSize;
   className?: string;
   align?: 'start' | 'center' | 'end';
   'aria-label'?: string;
@@ -67,6 +70,7 @@ export const DateField = React.forwardRef<HTMLInputElement, DateFieldProps>(
       showPopover,
       name,
       id,
+      inputSize,
       className,
       align = 'start',
       'aria-label': ariaLabel,
@@ -112,6 +116,7 @@ export const DateField = React.forwardRef<HTMLInputElement, DateFieldProps>(
           iconOpensPopover={withPopover}
           invalid={invalid}
           disabled={disabled}
+          inputSize={inputSize}
           className={className}
           popoverTrigger={
             withPopover ? (

package/src/components/forms/datetime-field/date-time-field.tsx

@@ -14,6 +14,7 @@ import { CalendarClock, Clock } from 'lucide-react';
 import * as React from 'react';
 
 import { cn } from '../../../lib/utils';
+import { CONTROL_SIZE, type FieldControlSize } from '../control-size';
 import { useIsTouch } from '../../../hooks/media';
 import { Popover, PopoverContent, PopoverTrigger } from '../../overlay/popover';
 import { Calendar } from '../../data/calendar/calendar';
@@ -58,6 +59,8 @@ export interface DateTimeFieldProps {
    */
   id?: string;
 
+  /** Height from the shared control ladder — same names as `Input`'s `inputSize`. */
+  inputSize?: FieldControlSize;
   className?: string;
   align?: 'start' | 'center' | 'end';
   'aria-label'?: string;
@@ -76,6 +79,7 @@ export const DateTimeField = React.forwardRef<HTMLInputElement, DateTimeFieldPro
       showPopover,
       name,
       id,
+      inputSize,
       className,
       align = 'start',
       'aria-label': ariaLabel,
@@ -120,6 +124,7 @@ export const DateTimeField = React.forwardRef<HTMLInputElement, DateTimeFieldPro
           iconOpensPopover={withPopover}
           invalid={invalid}
           disabled={disabled}
+          inputSize={inputSize}
           className={className}
           popoverTrigger={
             withPopover ? (
@@ -179,7 +184,7 @@ export const DateTimeField = React.forwardRef<HTMLInputElement, DateTimeFieldPro
             />
             {/* Time row: a full, comfortable field — not a cramped chip. The
               * label + clock icon sit left; the native time input fills the
-              * rest at the same height as the main field (h-10) so it's an easy
+              * rest at the default control height so it's an easy
               * tap/click target and reads as a real input. */}
             <div className="flex items-center gap-2 border-t p-3">
               <Clock className="size-4 shrink-0 text-muted-foreground" aria-hidden />
@@ -195,7 +200,8 @@ export const DateTimeField = React.forwardRef<HTMLInputElement, DateTimeFieldPro
                 className={cn(
                   // `--center` variant centers the native segments (see
                   // datetime-field.css); it sets its own display/justify.
-                  'native-datetime-input native-datetime-input--center ml-auto h-10 rounded-[var(--radius)]',
+                  'native-datetime-input native-datetime-input--center ml-auto rounded-[var(--radius)]',
+                  CONTROL_SIZE.default.height,
                   'border border-border bg-input px-4 text-base tabular-nums text-foreground shadow-sm md:text-sm',
                   'focus-visible:border-ring focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
                   'disabled:cursor-not-allowed disabled:opacity-50',

package/src/components/forms/datetime-field/native-field-shell.tsx

@@ -22,6 +22,7 @@
 import * as React from 'react';
 
 import { cn } from '../../../lib/utils';
+import { CONTROL_SIZE, type FieldControlSize } from '../control-size';
 
 export interface NativeFieldShellProps {
   /** Leading icon (lucide element). */
@@ -38,6 +39,8 @@ export interface NativeFieldShellProps {
    *  driven by the surrounding `Field` / `Form` layer. */
   invalid?: boolean;
   disabled?: boolean;
+  /** Height from the shared control ladder — same names as `Input`'s `inputSize`. */
+  inputSize?: FieldControlSize;
   className?: string;
   /** The native `<input>` element, already typed and wired by the field. */
   children: React.ReactNode;
@@ -71,7 +74,7 @@ export const NATIVE_FIELD_INPUT_CLASS = cn(
  * sharp Vercel/Linear look rather than a blurry halo.
  */
 export const NativeFieldShell = React.forwardRef<HTMLDivElement, NativeFieldShellProps>(
-  ({ icon, iconOpensPopover, invalid, disabled, className, children, popoverTrigger }, ref) => {
+  ({ icon, iconOpensPopover, invalid, disabled, inputSize = 'default', className, children, popoverTrigger }, ref) => {
     return (
       <div
         ref={ref}
@@ -79,7 +82,8 @@ export const NativeFieldShell = React.forwardRef<HTMLDivElement, NativeFieldShel
         data-disabled={disabled ? '' : undefined}
         aria-invalid={invalid || undefined}
         className={cn(
-          'flex h-10 w-full items-center gap-2 rounded-[var(--radius)] border bg-input px-3 shadow-sm',
+          CONTROL_SIZE[inputSize].height,
+          'flex w-full items-center gap-2 rounded-[var(--radius)] border bg-input px-3 shadow-sm',
           'transition-[color,background-color,border-color,box-shadow]',
           'border-border',
           // Crisp focus edge on the whole shell (border + 1px ring = ~2px clean

package/src/components/forms/datetime-field/time-field.tsx

@@ -14,6 +14,7 @@
 import { Clock } from 'lucide-react';
 import * as React from 'react';
 
+import type { FieldControlSize } from '../control-size';
 import { NativeFieldShell, NATIVE_FIELD_INPUT_CLASS } from './native-field-shell';
 
 export interface TimeFieldProps {
@@ -40,6 +41,8 @@ export interface TimeFieldProps {
    * the field a user actually focuses.
    */
   id?: string;
+  /** Height from the shared control ladder — same names as `Input`'s `inputSize`. */
+  inputSize?: FieldControlSize;
   className?: string;
   'aria-label'?: string;
 }
@@ -57,6 +60,7 @@ export const TimeField = React.forwardRef<HTMLInputElement, TimeFieldProps>(
       step,
       name,
       id,
+      inputSize,
       className,
       'aria-label': ariaLabel,
     },
@@ -79,6 +83,7 @@ export const TimeField = React.forwardRef<HTMLInputElement, TimeFieldProps>(
         icon={<Clock aria-hidden />}
         invalid={invalid}
         disabled={disabled}
+        inputSize={inputSize}
         className={className}
       >
         <input

package/src/components/forms/editable/index.tsx

@@ -3,6 +3,7 @@
 import * as React from "react";
 
 import { cn } from "../../../lib/utils";
+import type { FieldControlSize } from "../control-size";
 import { inputClass, TEXTAREA_CLASS } from "../input";
 
 // =============================================================================
@@ -45,7 +46,7 @@ export type EditablePreviewProps = React.ComponentPropsWithoutRef<"span">;
 
 export interface EditableInputProps extends Omit<React.ComponentPropsWithoutRef<"input">, "value" | "defaultValue"> {
   /** Density — matches the standalone Input's `inputSize`. Default: 'default'. */
-  inputSize?: 'default' | 'sm';
+  inputSize?: FieldControlSize;
 }
 
 export type EditableTextareaProps = Omit<React.ComponentPropsWithoutRef<"textarea">, "value" | "defaultValue">;

package/src/components/forms/input/index.tsx

@@ -2,6 +2,7 @@ import * as React from 'react';
 
 import { useStoredValue, type StorageType, type UseStoredValueOptions } from '../../../hooks';
 import { cn } from '../../../lib/utils';
+import { fieldSizeClass, type FieldControlSize } from '../control-size';
 
 export interface InputProps extends React.ComponentProps<"input"> {
   /**
@@ -30,11 +31,14 @@ export interface InputProps extends React.ComponentProps<"input"> {
    */
   storageTtl?: number;
   /**
-   * Control height/density.
-   * - `default` — 40px (forms, standalone fields).
-   * - `sm` — 36px, smaller text (inline edits, dense rows, settings chips).
+   * Control height, from the shared ladder in `forms/control-size.ts` — the
+   * same name gives a `Button` and a `SelectTrigger` the same height.
+   * - `xs` — 28px.
+   * - `sm` — 32px.
+   * - `default` — 36px.
+   * - `lg` — 44px.
    */
-  inputSize?: 'default' | 'sm';
+  inputSize?: FieldControlSize;
   /**
    * Drop the field chrome — border, surface, rounding, focus ring — for an
    * input that sits inside a control that draws them itself (`InputGroup`).
@@ -76,8 +80,10 @@ const INPUT_CHROME =
 const INPUT_BASE = cn(INPUT_CORE, INPUT_CHROME);
 
 const INPUT_SIZE: Record<NonNullable<InputProps['inputSize']>, string> = {
-  default: "h-10 px-3 py-2 text-base md:text-sm",
-  sm: "h-9 px-2.5 py-1.5 text-sm",
+  xs: fieldSizeClass('xs'),
+  sm: fieldSizeClass('sm'),
+  default: fieldSizeClass('default'),
+  lg: fieldSizeClass('lg'),
 };
 
 /** Resolve the full input class for a given size. */
@@ -146,7 +152,7 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(
     return (
       <input
         type={type}
-        className={cn(INPUT_CLASS, className)}
+        className={resolvedClass}
         ref={ref}
         defaultValue={storageKey && storedValue ? storedValue : defaultValue}
         onChange={storageKey ? handleChange : onChange}

package/src/components/forms/input-affix/index.tsx

@@ -3,6 +3,7 @@
 import * as React from 'react';
 
 import { cn } from '../../../lib/utils';
+import type { FieldControlSize } from '../control-size';
 import {
   InputGroup,
   InputGroupAddon,
@@ -41,11 +42,13 @@ export interface InputAffixProps
   suffix?: React.ReactNode;
   /** Applied to the group, so callers can size the whole control. */
   groupClassName?: string;
+  /** Height from the shared control ladder — same names as `Input`'s `inputSize`. */
+  inputSize?: FieldControlSize;
 }
 
 const InputAffix = React.forwardRef<HTMLInputElement, InputAffixProps>(
-  ({ prefix, suffix, className, groupClassName, ...props }, ref) => (
-    <InputGroup className={groupClassName}>
+  ({ prefix, suffix, className, groupClassName, inputSize, ...props }, ref) => (
+    <InputGroup className={groupClassName} inputSize={inputSize}>
       {prefix ? (
         <InputGroupAddon align="inline-start" aria-hidden="true">
           {prefix}

package/src/components/forms/input-group/index.tsx

@@ -5,10 +5,18 @@ import * as React from 'react';
 
 import { cn } from '../../../lib/utils';
 import { Button } from '../../forms/button';
+import { CONTROL_SIZE, type FieldControlSize } from '../control-size';
 import { Input } from '../../forms/input';
 import { Textarea } from '../../forms/textarea';
 
-function InputGroup({ className, ...props }: React.ComponentProps<"div">) {
+function InputGroup({
+  className,
+  inputSize = "default",
+  ...props
+}: React.ComponentProps<"div"> & {
+  /** Height from the shared control ladder — the same name as `Input`'s `inputSize`. */
+  inputSize?: FieldControlSize
+}) {
   return (
     <div
       data-slot="input-group"
@@ -20,18 +28,12 @@ function InputGroup({ className, ...props }: React.ComponentProps<"div">) {
         // nearly invisible next to a plain field's, and a focused money input
         // showed a crisp inner rectangle inside a ghost of an outer one.
         "group/input-group border-border bg-input shadow-xs relative flex w-full items-center rounded-[var(--radius)] border outline-none transition-[color,background-color,border-color,box-shadow]",
-        // Matches `Input`'s default size (h-10), not its `sm` one.
-        //
-        // This was `h-9`, which made a grouped input a row shorter than a bare
-        // `Input` or a `SelectTrigger` beside it — visible the moment a form
-        // puts a prefixed money field next to a plain select, and not
-        // attributable to either component from the outside. A wrapper that
-        // changes a control's height is a wrapper that cannot be dropped into
-        // an existing row.
-        //
-        // Use `className="h-9"` at the call site for the compact size, the
-        // same way `inputSize="sm"` is opted into rather than inherited.
-        "h-10 has-[>textarea]:h-auto",
+        // Height comes from the shared control ladder, the same map `Input` and
+        // `SelectTrigger` read, so a grouped input is never a row shorter or
+        // taller than a bare one beside it. A wrapper that changes a control's
+        // height cannot be dropped into an existing row.
+        CONTROL_SIZE[inputSize].height,
+        "has-[>textarea]:h-auto",
 
         // Variants based on alignment.
         //

package/src/components/forms/mask-input/index.tsx

@@ -3,6 +3,7 @@
 import * as React from "react";
 
 import { cn } from "../../../lib/utils";
+import { CONTROL_SIZE } from "../control-size";
 
 // =============================================================================
 // Types
@@ -458,7 +459,8 @@ const MaskInput = React.forwardRef<HTMLInputElement, MaskInputProps>(
         ref={composedRef}
         value={displayValue}
         className={cn(
-          "flex h-10 w-full rounded-[var(--radius)] border border-border bg-transparent px-3 py-2 text-base shadow-sm transition-colors file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+          CONTROL_SIZE.default.height,
+          "flex w-full rounded-[var(--radius)] border border-border bg-transparent px-3 py-1 text-base shadow-sm transition-colors file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
           className
         )}
         onChange={handleChange}

package/src/components/forms/phone-input/index.tsx

@@ -209,8 +209,7 @@ const PhoneInput = React.forwardRef<HTMLInputElement, PhoneInputProps>(
           <DropdownMenuTrigger asChild>
             <Button
               variant="outline"
-              size="sm"
-              className="h-10 px-3 rounded-r-none border-r-0 flex items-center gap-2"
+              className="px-3 rounded-r-none border-r-0 flex items-center gap-2"
               disabled={disabled}
             >
               <Flag countryCode={currentCountry.code} rounded className="h-3 w-4" />
@@ -227,7 +226,8 @@ const PhoneInput = React.forwardRef<HTMLInputElement, PhoneInputProps>(
                   placeholder={translations.searchCountries}
                   value={searchQuery}
                   onChange={(e) => setSearchQuery(e.target.value)}
-                  className="pl-8 h-8"
+                  inputSize="sm"
+                  className="pl-8"
                   autoFocus
                 />
               </div>

package/src/components/index.ts

@@ -12,6 +12,8 @@ export type { TouchSafeInputProps, TouchSafeTextareaProps, TouchSafeSelectProps
 export { Button, ButtonLink, buttonVariants } from './forms/button';
 export type { ButtonProps, ButtonLinkProps } from './forms/button';
 export { Input } from './forms/input';
+export { CONTROL_SIZE } from './forms/control-size';
+export type { ControlSize, FieldControlSize } from './forms/control-size';
 export { Textarea } from './forms/textarea';
 export { Label } from './forms/label';
 export { Checkbox } from './forms/checkbox';

package/src/components/select/language-select.tsx

@@ -10,6 +10,7 @@ import { LanguageFlag } from '../specialized/flag';
 import { Badge } from '../data/badge';
 import { Button } from '../forms/button';
 import { Checkbox } from '../forms/checkbox';
+import { CONTROL_SIZE } from '../forms/control-size';
 import {
   Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList
 } from '../navigation/command';
@@ -363,6 +364,14 @@ export function LanguageSelect({
   }
 
   // Dropdown variant (displayValue is memoized above, before the inline guard)
+  const triggerSize = size === 'sm' ? 'sm' : 'default';
+  // Single-select: a fixed-height pill (the Button size sets height).
+  // Multiple: allow growth so wrapped badges aren't clipped, never shorter than
+  // the fixed control of the same size.
+  const triggerSizeClass = multiple
+    ? cn('h-auto', CONTROL_SIZE[triggerSize].minHeight, size === 'sm' ? 'py-1' : 'py-2')
+    : size === 'sm' && 'text-xs';
+
   return (
     <Popover
       open={open}
@@ -376,19 +385,10 @@ export function LanguageSelect({
       <PopoverTrigger asChild>
         <Button
           variant="outline"
-          size={size === 'sm' ? 'sm' : 'default'}
+          size={triggerSize}
           role="combobox"
           aria-expanded={open}
-          className={cn(
-            SELECT_TRIGGER_CLASS,
-            // Single-select: a fixed-height pill (the Button size sets height).
-            // Multiple: allow growth so wrapped badges aren't clipped — keep the
-            // auto-height min behaviour, scaled to the chosen size.
-            multiple
-              ? (size === 'sm' ? "min-h-8 h-auto py-1" : "min-h-10 h-auto py-2")
-              : (size === 'sm' ? "text-xs" : "h-10"),
-            className
-          )}
+          className={cn(SELECT_TRIGGER_CLASS, triggerSizeClass, className)}
           disabled={disabled}
         >
           <div className="flex-1 text-left overflow-hidden">

package/src/components/select/select.tsx

@@ -7,6 +7,7 @@ import * as SelectPrimitive from '@radix-ui/react-select';
 
 import { cn } from '../../lib/utils';
 import { Badge } from '../data/badge';
+import { CONTROL_SIZE, type FieldControlSize } from '../forms/control-size';
 
 /**
  * Radix `<Select.Item value="" />` is reserved (it's how Radix represents
@@ -59,14 +60,23 @@ const SelectTrigger = React.forwardRef<
      * status bar or toolbar where the trigger should read like a plain button.
      */
     variant?: "default" | "ghost";
+    /**
+     * Height from the shared control ladder (`forms/control-size.ts`): the same
+     * name as a `Button` or `Input` gives the same height. Ignored by `ghost`,
+     * which has no fixed height.
+     */
+    size?: FieldControlSize;
   }
->(({ className, children, icon: Icon, variant = "default", ...props }, ref) => (
+>(({ className, children, icon: Icon, variant = "default", size = "default", ...props }, ref) => (
   <SelectPrimitive.Trigger
     ref={ref}
     className={cn(
       "flex items-center justify-between whitespace-nowrap text-sm ring-offset-background data-[placeholder]:text-muted-foreground focus:outline-none disabled:cursor-not-allowed disabled:opacity-50",
       variant === "default" &&
-        "h-10 w-full rounded-[var(--radius)] border border-border bg-transparent px-3 py-2 shadow-sm focus:ring-1 focus:ring-ring",
+        cn(
+          CONTROL_SIZE[size].height,
+          "w-full rounded-[var(--radius)] border border-border bg-transparent px-3 shadow-sm focus:ring-1 focus:ring-ring",
+        ),
       variant === "ghost" &&
         "rounded-md px-2 py-0.5 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground data-[state=open]:bg-muted data-[state=open]:text-foreground",
       className

package/src/components/select/trigger.ts

@@ -1,3 +1,6 @@
+import { cn } from '../../lib/utils';
+import { CONTROL_SIZE } from '../forms/control-size';
+
 /**
  * The shared class list for a select-like trigger.
  *
@@ -19,5 +22,7 @@ export const SELECT_TRIGGER_CLASS = "w-full justify-between font-normal";
  * The same, for pickers whose trigger grows with its content (chips, tags,
  * multiple rows) instead of keeping a fixed control height.
  */
-export const SELECT_TRIGGER_MULTI_CLASS =
-  "w-full justify-between font-normal min-h-10 h-auto py-2";
+export const SELECT_TRIGGER_MULTI_CLASS = cn(
+  "w-full justify-between font-normal h-auto py-2",
+  CONTROL_SIZE.default.minHeight,
+);

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,