@djangocfg/ui-core 2.1.225 → 2.1.227

package/package.json

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

package/src/components/accordion.tsx

@@ -5,9 +5,90 @@ import * as React from 'react';
 import * as AccordionPrimitive from '@radix-ui/react-accordion';
 import { ChevronDownIcon } from '@radix-ui/react-icons';
 
+import { useStoredValue, type StorageType, type UseStoredValueOptions } from '../hooks/useStoredValue';
 import { cn } from '../lib/utils';
 
-const Accordion = AccordionPrimitive.Root
+type AccordionSingleProps = React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Root> & {
+  type: 'single'
+  storageKey?: string
+  storageType?: StorageType
+  storageTtl?: number
+}
+
+type AccordionMultipleProps = React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Root> & {
+  type: 'multiple'
+  storageKey?: string
+  storageType?: StorageType
+  storageTtl?: number
+}
+
+export type AccordionProps = AccordionSingleProps | AccordionMultipleProps
+
+const Accordion = React.forwardRef<
+  React.ElementRef<typeof AccordionPrimitive.Root>,
+  AccordionProps
+>(({ storageKey, storageType, storageTtl, ...props }, ref) => {
+  const storageOptions: UseStoredValueOptions | undefined =
+    storageKey ? { storage: storageType ?? 'local', ttl: storageTtl } : undefined;
+
+  const isSingle = props.type === 'single';
+
+  // For single: persist string; for multiple: persist string[]
+  const initialSingle = (props as AccordionSingleProps).defaultValue ?? ((props as AccordionSingleProps).value as string | undefined) ?? '';
+  const initialMultiple = (props as AccordionMultipleProps).defaultValue ?? ((props as AccordionMultipleProps).value as string[] | undefined) ?? [];
+
+  const [storedSingle, setStoredSingle] = useStoredValue<string>(
+    isSingle ? storageKey : undefined,
+    initialSingle,
+    storageOptions,
+  );
+  const [storedMultiple, setStoredMultiple] = useStoredValue<string[]>(
+    !isSingle ? storageKey : undefined,
+    initialMultiple,
+    storageOptions,
+  );
+
+  if (isSingle) {
+    const { onValueChange, value, defaultValue, ...rest } = props as AccordionSingleProps & { onValueChange?: (v: string) => void };
+    const handleValueChange = storageKey
+      ? (newValue: string) => { setStoredSingle(newValue); onValueChange?.(newValue); }
+      : onValueChange;
+    const extraProps = storageKey && value === undefined && storedSingle
+      ? { defaultValue: storedSingle }
+      : defaultValue !== undefined ? { defaultValue } : {};
+
+    return (
+      <AccordionPrimitive.Root
+        ref={ref}
+        type="single"
+        value={value}
+        onValueChange={handleValueChange}
+        {...extraProps}
+        {...rest}
+      />
+    );
+  }
+
+  const { onValueChange, value, defaultValue, ...rest } = props as AccordionMultipleProps & { onValueChange?: (v: string[]) => void };
+  const handleValueChange = storageKey
+    ? (newValue: string[]) => { setStoredMultiple(newValue); onValueChange?.(newValue); }
+    : onValueChange;
+  const extraProps = storageKey && value === undefined && storedMultiple.length > 0
+    ? { defaultValue: storedMultiple }
+    : defaultValue !== undefined ? { defaultValue } : {};
+
+  return (
+    <AccordionPrimitive.Root
+      ref={ref}
+      type="multiple"
+      value={value}
+      onValueChange={handleValueChange}
+      {...extraProps}
+      {...rest}
+    />
+  );
+})
+Accordion.displayName = "Accordion"
 
 const AccordionItem = React.forwardRef<
   React.ElementRef<typeof AccordionPrimitive.Item>,

package/src/components/combobox.tsx

@@ -4,6 +4,7 @@ import { Check, ChevronsUpDown } from 'lucide-react';
 import * as React from 'react';
 
 import { useTypedT, type I18nTranslations } from '@djangocfg/i18n';
+import { useStoredValue, type StorageType, type UseStoredValueOptions } from '../hooks/useStoredValue';
 import { cn } from '../lib/utils';
 import { Button } from './button';
 import {
@@ -31,11 +32,38 @@ export interface ComboboxProps {
   renderValue?: (option: ComboboxOption | undefined) => React.ReactNode
   /** Custom filter function. If provided, replaces default filtering logic. */
   filterFunction?: (option: ComboboxOption, search: string) => boolean
+  /**
+   * When provided, the selected value is persisted under this key.
+   *
+   * On mount: if the stored value exists in the current options list,
+   * it becomes the initial selection. If options are not yet loaded
+   * (empty array), the component waits — it applies the stored value
+   * once options become non-empty (see autoSelectFromOptions).
+   *
+   * @example storageKey="selected-queue"
+   */
+  storageKey?: string
+  /** @default 'local' */
+  storageType?: StorageType
+  /** TTL in ms */
+  storageTtl?: number
+  /**
+   * When true AND storageKey is set: after options load/change, if the
+   * stored value is present in the new options list it is auto-selected
+   * (calls onValueChange). If the stored value is no longer in the list
+   * the selection is cleared to "".
+   *
+   * When false (default): stored value only seeds the initial value on
+   * first render — subsequent option changes don't auto-correct the value.
+   *
+   * @default false
+   */
+  autoSelectFromOptions?: boolean
 }
 
 export function Combobox({
   options,
-  value,
+  value: controlledValue,
   onValueChange,
   placeholder,
   searchPlaceholder,
@@ -45,12 +73,77 @@ export function Combobox({
   renderOption,
   renderValue,
   filterFunction,
+  storageKey,
+  storageType,
+  storageTtl,
+  autoSelectFromOptions = false,
 }: ComboboxProps) {
   const t = useTypedT<I18nTranslations>()
   const [open, setOpen] = React.useState(false)
   const [search, setSearch] = React.useState("")
   const scrollRef = React.useRef<HTMLDivElement>(null)
 
+  const storageOptions: UseStoredValueOptions | undefined =
+    storageKey ? { storage: storageType ?? 'local', ttl: storageTtl } : undefined;
+
+  const [storedValue, setStoredValue] = useStoredValue<string>(
+    storageKey,
+    controlledValue ?? '',
+    storageOptions,
+  );
+
+  // Internal selection state — used only when parent doesn't control `value`.
+  // Seeded from storedValue (which is initialValue / '' on SSR, real value post-hydration).
+  const [internalValue, setInternalValue] = React.useState<string>(
+    controlledValue !== undefined ? controlledValue : storedValue,
+  );
+
+  // The effective selected value: prefer controlled, fall back to internal
+  const value = controlledValue !== undefined ? controlledValue : internalValue;
+
+  // autoSelectFromOptions: when options become available, validate stored value.
+  // Runs whenever options change (async loads, filters, etc.)
+  // Only acts when: storageKey is set, autoSelectFromOptions=true, options non-empty.
+  // Guards:
+  //   - don't override a value the user explicitly set to "" (intentional clear)
+  //   - don't run while options are still loading (length === 0)
+  const autoSelectApplied = React.useRef(false);
+
+  React.useEffect(() => {
+    if (!storageKey || !autoSelectFromOptions || options.length === 0) return;
+
+    // Only auto-apply once per storageKey lifetime to avoid fighting user selections.
+    // Reset when storageKey changes (handled by the key dependency below).
+    if (autoSelectApplied.current) return;
+    autoSelectApplied.current = true;
+
+    const savedValue = storedValue;
+    if (!savedValue) return; // nothing saved
+
+    const existsInOptions = options.some((o) => o.value === savedValue && !o.disabled);
+
+    if (existsInOptions) {
+      // Restore saved selection
+      if (controlledValue === undefined) {
+        setInternalValue(savedValue);
+      }
+      onValueChange?.(savedValue);
+    } else {
+      // Saved value no longer valid — clear it
+      setStoredValue('');
+      if (controlledValue === undefined) {
+        setInternalValue('');
+      }
+      onValueChange?.('');
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [options, storageKey, autoSelectFromOptions]);
+
+  // Reset autoSelectApplied when storageKey changes
+  React.useEffect(() => {
+    autoSelectApplied.current = false;
+  }, [storageKey]);
+
   // Resolve translations
   const resolvedPlaceholder = placeholder ?? t('ui.select.placeholder')
   const resolvedSearchPlaceholder = searchPlaceholder ?? t('ui.select.search')
@@ -58,7 +151,6 @@ export function Combobox({
 
   React.useEffect(() => {
     if (scrollRef.current && open) {
-      // Force scrollable styles with !important
       const el = scrollRef.current
       el.style.cssText = `
         max-height: 300px !important;
@@ -78,12 +170,10 @@ export function Combobox({
   const filteredOptions = React.useMemo(() => {
     if (!search) return options
 
-    // Use custom filter function if provided
     if (filterFunction) {
       return options.filter((option) => filterFunction(option, search))
     }
 
-    // Default filtering: simple includes
     const searchLower = search.toLowerCase()
     return options.filter(
       (option) =>
@@ -93,6 +183,17 @@ export function Combobox({
     )
   }, [options, search, filterFunction])
 
+  const handleSelect = React.useCallback(
+    (currentValue: string) => {
+      const next = currentValue === value ? "" : currentValue;
+      if (storageKey) setStoredValue(next);
+      if (controlledValue === undefined) setInternalValue(next);
+      onValueChange?.(next);
+      setOpen(false);
+    },
+    [value, storageKey, setStoredValue, controlledValue, onValueChange],
+  );
+
   return (
     <Popover
       open={open}
@@ -154,8 +255,7 @@ export function Combobox({
                     value={option.value}
                     onSelect={(currentValue) => {
                       if (!option.disabled) {
-                        onValueChange?.(currentValue === value ? "" : currentValue)
-                        setOpen(false)
+                        handleSelect(currentValue)
                       }
                     }}
                     disabled={option.disabled}

package/src/components/input.tsx

@@ -1,9 +1,83 @@
 import * as React from 'react';
 
+import { useStoredValue, type StorageType, type UseStoredValueOptions } from '../hooks/useStoredValue';
 import { cn } from '../lib/utils';
 
-const Input = React.forwardRef<HTMLInputElement, React.ComponentProps<"input">>(
-  ({ className, type, ...props }, ref) => {
+export interface InputProps extends React.ComponentProps<"input"> {
+  /**
+   * When provided, the input value is persisted to storage under this key.
+   *
+   * Rules:
+   * - If the parent passes `value` (controlled), storage is used for initial
+   *   hydration only on first mount (defaultValue path is not applicable), but
+   *   writes are still saved so the next mount can restore the value.
+   *   In fully controlled mode the parent owns the value — storage just seeds
+   *   the `defaultValue` on next fresh mount if the parent doesn't supply one.
+   * - If the parent passes `defaultValue` or neither, the component is
+   *   uncontrolled — storage provides the default and tracks changes via
+   *   an onChange wrapper.
+   *
+   * @example storageKey="search-filter"
+   */
+  storageKey?: string;
+  /**
+   * Which storage backend to use.
+   * @default 'local'
+   */
+  storageType?: StorageType;
+  /**
+   * TTL in ms. Stored value expires after this duration.
+   */
+  storageTtl?: number;
+}
+
+const Input = React.forwardRef<HTMLInputElement, InputProps>(
+  ({ className, type, storageKey, storageType, storageTtl, onChange, defaultValue, value, ...props }, ref) => {
+    const storageOptions: UseStoredValueOptions | undefined =
+      storageKey ? { storage: storageType ?? 'local', ttl: storageTtl } : undefined;
+
+    const [storedValue, setStoredValue] = useStoredValue<string>(
+      storageKey,
+      // seed: use provided defaultValue or controlled value as fallback seed
+      (defaultValue as string | undefined) ?? (value as string | undefined) ?? '',
+      storageOptions,
+    );
+
+    // Wrap onChange to persist to storage on every change.
+    // Only active when storageKey is provided.
+    const handleChange = React.useCallback(
+      (e: React.ChangeEvent<HTMLInputElement>) => {
+        if (storageKey) {
+          setStoredValue(e.target.value);
+        }
+        onChange?.(e);
+      },
+      [storageKey, setStoredValue, onChange],
+    );
+
+    // If parent passes explicit `value` — fully controlled, we don't inject
+    // defaultValue (React would warn about switching modes). We still write
+    // to storage on change via handleChange.
+    if (value !== undefined) {
+      return (
+        <input
+          type={type}
+          className={cn(
+            "flex h-10 w-full rounded-md border border-input 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",
+            className
+          )}
+          ref={ref}
+          value={value}
+          onChange={storageKey ? handleChange : onChange}
+          {...props}
+        />
+      );
+    }
+
+    // Uncontrolled: inject stored value as defaultValue (if no defaultValue given).
+    // React requires defaultValue to be stable on first render — storedValue from
+    // useLocalStorage is initialValue on SSR and the real value after hydration.
+    // This is fine: defaultValue only seeds the initial DOM value.
     return (
       <input
         type={type}
@@ -12,11 +86,13 @@ const Input = React.forwardRef<HTMLInputElement, React.ComponentProps<"input">>(
           className
         )}
         ref={ref}
+        defaultValue={storageKey && storedValue ? storedValue : defaultValue}
+        onChange={storageKey ? handleChange : onChange}
         {...props}
       />
-    )
-  }
-)
+    );
+  },
+);
 Input.displayName = "Input"
 
 export { Input }

package/src/components/multi-select.tsx

@@ -4,6 +4,7 @@ import { Check, ChevronsUpDown, X } from 'lucide-react';
 import * as React from 'react';
 
 import { useTypedT, type I18nTranslations } from '@djangocfg/i18n';
+import { useStoredValue, type StorageType, type UseStoredValueOptions } from '../hooks/useStoredValue';
 import { cn } from '../lib/utils';
 import { Badge } from './badge';
 import { Button } from './button';
@@ -29,11 +30,39 @@ export interface MultiSelectProps {
   className?: string
   disabled?: boolean
   maxDisplay?: number
+  /**
+   * When provided, the selected values array is persisted under this key.
+   *
+   * On mount: stored values that are present in the current options are
+   * restored. Values that no longer exist in options are silently dropped
+   * (safe against stale data from removed options).
+   *
+   * @example storageKey="selected-tags"
+   */
+  storageKey?: string
+  /** @default 'local' */
+  storageType?: StorageType
+  /** TTL in ms */
+  storageTtl?: number
+  /**
+   * When true AND storageKey is set: after options load/change, the stored
+   * selection is filtered to only include values present in the current
+   * options. Values not in options are removed from the selection and
+   * from storage.
+   *
+   * When false (default): stored values are only used to seed the initial
+   * selection. Subsequent option changes don't re-filter.
+   *
+   * @default false
+   */
+  autoSelectFromOptions?: boolean
 }
 
+const EMPTY_ARRAY: string[] = [];
+
 export function MultiSelect({
   options,
-  value = [],
+  value: controlledValue,
   onChange,
   placeholder,
   searchPlaceholder,
@@ -41,17 +70,73 @@ export function MultiSelect({
   className,
   disabled = false,
   maxDisplay = 3,
+  storageKey,
+  storageType,
+  storageTtl,
+  autoSelectFromOptions = false,
 }: MultiSelectProps) {
   const t = useTypedT<I18nTranslations>()
   const [open, setOpen] = React.useState(false)
   const [search, setSearch] = React.useState("")
   const scrollRef = React.useRef<HTMLDivElement>(null)
 
+  const storageOptions: UseStoredValueOptions | undefined =
+    storageKey ? { storage: storageType ?? 'local', ttl: storageTtl } : undefined;
+
+  const [storedValue, setStoredValue] = useStoredValue<string[]>(
+    storageKey,
+    controlledValue ?? EMPTY_ARRAY,
+    storageOptions,
+  );
+
+  // Internal selection state for uncontrolled mode
+  const [internalValue, setInternalValue] = React.useState<string[]>(
+    controlledValue !== undefined ? controlledValue : storedValue,
+  );
+
+  const value = controlledValue !== undefined ? controlledValue : internalValue;
+
   // Resolve translations
   const resolvedPlaceholder = placeholder ?? t('ui.select.placeholder')
   const resolvedSearchPlaceholder = searchPlaceholder ?? t('ui.select.search')
   const resolvedEmptyText = emptyText ?? t('ui.select.noResults')
 
+  // autoSelectFromOptions: filter stored selection to valid options only
+  const autoSelectApplied = React.useRef(false);
+
+  React.useEffect(() => {
+    if (!storageKey || !autoSelectFromOptions || options.length === 0) return;
+    if (autoSelectApplied.current) return;
+    autoSelectApplied.current = true;
+
+    const saved = storedValue;
+    if (!saved || saved.length === 0) return;
+
+    const validOptionValues = new Set(
+      options.filter((o) => !o.disabled).map((o) => o.value)
+    );
+    const filtered = saved.filter((v) => validOptionValues.has(v));
+
+    // Only update if something actually changed
+    const changed = filtered.length !== saved.length ||
+      filtered.some((v, i) => v !== saved[i]);
+
+    if (changed) {
+      setStoredValue(filtered);
+      if (controlledValue === undefined) setInternalValue(filtered);
+      onChange?.(filtered);
+    } else if (filtered.length > 0) {
+      // Restore valid selection to parent
+      if (controlledValue === undefined) setInternalValue(filtered);
+      onChange?.(filtered);
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [options, storageKey, autoSelectFromOptions]);
+
+  React.useEffect(() => {
+    autoSelectApplied.current = false;
+  }, [storageKey]);
+
   React.useEffect(() => {
     if (scrollRef.current && open) {
       const el = scrollRef.current
@@ -81,17 +166,22 @@ export function MultiSelect({
     )
   }, [options, search])
 
-  const handleSelect = (optionValue: string) => {
+  const handleSelect = React.useCallback((optionValue: string) => {
     const newValue = value.includes(optionValue)
       ? value.filter((v) => v !== optionValue)
-      : [...value, optionValue]
-    onChange?.(newValue)
-  }
+      : [...value, optionValue];
+    if (storageKey) setStoredValue(newValue);
+    if (controlledValue === undefined) setInternalValue(newValue);
+    onChange?.(newValue);
+  }, [value, storageKey, setStoredValue, controlledValue, onChange]);
 
-  const handleRemove = (optionValue: string, e: React.MouseEvent) => {
-    e.stopPropagation()
-    onChange?.(value.filter((v) => v !== optionValue))
-  }
+  const handleRemove = React.useCallback((optionValue: string, e: React.MouseEvent) => {
+    e.stopPropagation();
+    const newValue = value.filter((v) => v !== optionValue);
+    if (storageKey) setStoredValue(newValue);
+    if (controlledValue === undefined) setInternalValue(newValue);
+    onChange?.(newValue);
+  }, [value, storageKey, setStoredValue, controlledValue, onChange]);
 
   const displayValue = React.useMemo(() => {
     if (selectedOptions.length === 0) {
@@ -127,7 +217,7 @@ export function MultiSelect({
         )}
       </div>
     )
-  }, [selectedOptions, maxDisplay, resolvedPlaceholder, disabled, t])
+  }, [selectedOptions, maxDisplay, resolvedPlaceholder, disabled, t, handleRemove])
 
   return (
     <Popover

package/src/components/slider.tsx

@@ -4,13 +4,54 @@ import * as React from 'react';
 
 import * as SliderPrimitive from '@radix-ui/react-slider';
 
+import { useStoredValue, type StorageType, type UseStoredValueOptions } from '../hooks/useStoredValue';
 import { cn } from '../lib/utils';
 
+export interface SliderProps extends React.ComponentPropsWithoutRef<typeof SliderPrimitive.Root> {
+  /**
+   * When provided, the slider value is persisted under this key.
+   * Works with both controlled (`value`) and uncontrolled (`defaultValue`) modes.
+   * @example storageKey="volume-level"
+   */
+  storageKey?: string
+  /** @default 'local' */
+  storageType?: StorageType
+  /** TTL in ms */
+  storageTtl?: number
+}
+
 const Slider = React.forwardRef<
   React.ElementRef<typeof SliderPrimitive.Root>,
-  React.ComponentPropsWithoutRef<typeof SliderPrimitive.Root>
->(({ className, orientation = 'horizontal', ...props }, ref) => {
+  SliderProps
+>(({ className, orientation = 'horizontal', storageKey, storageType, storageTtl, onValueChange, ...props }, ref) => {
   const isVertical = orientation === 'vertical';
+
+  const storageOptions: UseStoredValueOptions | undefined =
+    storageKey ? { storage: storageType ?? 'local', ttl: storageTtl } : undefined;
+
+  const [storedValue, setStoredValue] = useStoredValue<number[]>(
+    storageKey,
+    (props.defaultValue as number[] | undefined) ?? (props.value as number[] | undefined) ?? [],
+    storageOptions,
+  );
+
+  const handleValueChange = React.useCallback(
+    (newValue: number[]) => {
+      if (storageKey) setStoredValue(newValue);
+      onValueChange?.(newValue);
+    },
+    [storageKey, setStoredValue, onValueChange],
+  );
+
+  const sliderProps = {
+    ...props,
+    onValueChange: storageKey ? handleValueChange : onValueChange,
+    // Inject stored defaultValue only in uncontrolled mode
+    ...(storageKey && props.value === undefined && storedValue.length > 0
+      ? { defaultValue: storedValue }
+      : {}),
+  };
+
   return (
     <SliderPrimitive.Root
       ref={ref}
@@ -22,7 +63,7 @@ const Slider = React.forwardRef<
           : "flex-row items-center w-full",
         className
       )}
-      {...props}
+      {...sliderProps}
     >
       <SliderPrimitive.Track
         className={cn(

package/src/components/tabs.tsx

@@ -6,6 +6,7 @@ import * as React from 'react';
 import * as TabsPrimitive from '@radix-ui/react-tabs';
 
 import { useIsMobile } from '../hooks';
+import { useStoredValue, type StorageType } from '../hooks/useStoredValue';
 import { useTypedT, type I18nTranslations } from '@djangocfg/i18n';
 import { cn } from '../lib/utils';
 import { Button } from './button';
@@ -36,17 +37,54 @@ export interface TabsProps extends React.ComponentPropsWithoutRef<typeof TabsPri
    * @default false
    */
   sticky?: boolean
+  /**
+   * When provided, the active tab value is persisted under this key.
+   * On mount the last active tab is restored automatically.
+   * Works with both controlled (`value`) and uncontrolled (`defaultValue`) modes.
+   * In controlled mode the stored value is passed to `defaultValue` on first
+   * render; the parent stays in charge after that.
+   * @example storageKey="admin-tab"
+   */
+  storageKey?: string
+  /** @default 'local' */
+  storageType?: StorageType
 }
 
 const Tabs = React.forwardRef<
   React.ElementRef<typeof TabsPrimitive.Root>,
   TabsProps
->(({ mobileSheet = false, mobileSheetTitle, mobileTitleText, sticky = false, children, ...props }, ref) => {
+>(({ mobileSheet = false, mobileSheetTitle, mobileTitleText, sticky = false, storageKey, storageType, children, ...props }, ref) => {
   const t = useTypedT<I18nTranslations>()
   const resolvedMobileSheetTitle = mobileSheetTitle ?? t('ui.navigation.title')
   const isMobile = useIsMobile()
   const [open, setOpen] = React.useState(false)
 
+  const [storedTab, setStoredTab] = useStoredValue<string>(
+    storageKey,
+    // seed: prefer defaultValue prop, then controlled value, then empty
+    (props.defaultValue as string | undefined) ?? (props.value as string | undefined) ?? '',
+    storageKey ? { storage: storageType ?? 'local' } : undefined,
+  );
+
+  // Wrap onValueChange to persist tab changes
+  const handleValueChange = React.useCallback(
+    (newValue: string) => {
+      if (storageKey) setStoredTab(newValue);
+      props.onValueChange?.(newValue);
+    },
+    [storageKey, setStoredTab, props.onValueChange],
+  );
+
+  // Build enhanced props: inject stored defaultValue when no value/defaultValue given
+  const tabsProps = {
+    ...props,
+    onValueChange: storageKey ? handleValueChange : props.onValueChange,
+    // Only inject defaultValue when: storageKey set, no controlled value, storedTab non-empty
+    ...(storageKey && props.value === undefined && storedTab
+      ? { defaultValue: storedTab }
+      : {}),
+  };
+
   // If mobile sheet mode is disabled, render normal tabs
   if (!mobileSheet || !isMobile) {
     // If sticky is enabled for desktop, wrap TabsList in sticky container
@@ -60,7 +98,7 @@ const Tabs = React.forwardRef<
       )
 
       return (
-        <TabsPrimitive.Root ref={ref} {...props}>
+        <TabsPrimitive.Root ref={ref} {...tabsProps}>
           <div className="sticky top-0 z-40 w-full border-b bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60 mb-4">
             {tabsList}
           </div>
@@ -70,7 +108,7 @@ const Tabs = React.forwardRef<
     }
 
     return (
-      <TabsPrimitive.Root ref={ref} {...props}>
+      <TabsPrimitive.Root ref={ref} {...tabsProps}>
         {children}
       </TabsPrimitive.Root>
     )
@@ -92,7 +130,7 @@ const Tabs = React.forwardRef<
 
   // Mobile Sheet Navigation
   return (
-    <TabsPrimitive.Root ref={ref} {...props}>
+    <TabsPrimitive.Root ref={ref} {...tabsProps}>
       <div className={cn(
         "w-full border-b bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60 mb-4",
         sticky && "sticky top-0 z-40"

package/src/components/textarea.tsx

@@ -1,22 +1,71 @@
 import * as React from 'react';
 
+import { useStoredValue, type StorageType, type UseStoredValueOptions } from '../hooks/useStoredValue';
 import { cn } from '../lib/utils';
 
-const Textarea = React.forwardRef<
-  HTMLTextAreaElement,
-  React.ComponentProps<"textarea">
->(({ className, ...props }, ref) => {
-  return (
-    <textarea
-      className={cn(
-        "flex min-h-[60px] w-full rounded-md border border-input bg-transparent px-3 py-2 text-sm shadow-sm placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50",
-        className
-      )}
-      ref={ref}
-      {...props}
-    />
-  )
-})
+export interface TextareaProps extends React.ComponentProps<"textarea"> {
+  /**
+   * When provided, the textarea value is persisted to storage under this key.
+   * Same controlled/uncontrolled rules as Input.
+   * @example storageKey="draft-message"
+   */
+  storageKey?: string;
+  /** @default 'local' */
+  storageType?: StorageType;
+  /** TTL in ms */
+  storageTtl?: number;
+}
+
+const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
+  ({ className, storageKey, storageType, storageTtl, onChange, defaultValue, value, ...props }, ref) => {
+    const storageOptions: UseStoredValueOptions | undefined =
+      storageKey ? { storage: storageType ?? 'local', ttl: storageTtl } : undefined;
+
+    const [storedValue, setStoredValue] = useStoredValue<string>(
+      storageKey,
+      (defaultValue as string | undefined) ?? (value as string | undefined) ?? '',
+      storageOptions,
+    );
+
+    const handleChange = React.useCallback(
+      (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+        if (storageKey) {
+          setStoredValue(e.target.value);
+        }
+        onChange?.(e);
+      },
+      [storageKey, setStoredValue, onChange],
+    );
+
+    if (value !== undefined) {
+      return (
+        <textarea
+          className={cn(
+            "flex min-h-[60px] w-full rounded-md border border-input bg-transparent px-3 py-2 text-sm shadow-sm placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50",
+            className
+          )}
+          ref={ref}
+          value={value}
+          onChange={storageKey ? handleChange : onChange}
+          {...props}
+        />
+      );
+    }
+
+    return (
+      <textarea
+        className={cn(
+          "flex min-h-[60px] w-full rounded-md border border-input bg-transparent px-3 py-2 text-sm shadow-sm placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50",
+          className
+        )}
+        ref={ref}
+        defaultValue={storageKey && storedValue ? storedValue : defaultValue}
+        onChange={storageKey ? handleChange : onChange}
+        {...props}
+      />
+    );
+  },
+);
 Textarea.displayName = "Textarea"
 
 export { Textarea }

package/src/hooks/index.ts

@@ -19,6 +19,8 @@ export { useResolvedTheme } from './useResolvedTheme';
 export type { ResolvedTheme } from './useResolvedTheme';
 export { useLocalStorage } from './useLocalStorage';
 export { useSessionStorage } from './useSessionStorage';
+export { useStoredValue } from './useStoredValue';
+export type { UseStoredValueOptions, StorageType } from './useStoredValue';
 export { useHotkey, useHotkeysContext, HotkeysProvider, isHotkeyPressed } from './useHotkey';
 export type { UseHotkeyOptions, HotkeyCallback, Keys, HotkeyRefType } from './useHotkey';
 export { useBrowserDetect } from './useBrowserDetect';

package/src/hooks/useStoredValue.ts

@@ -0,0 +1,72 @@
+'use client';
+
+import { useCallback } from 'react';
+
+import { useLocalStorage } from './useLocalStorage';
+import { useSessionStorage } from './useSessionStorage';
+
+export type StorageType = 'local' | 'session';
+
+export interface UseStoredValueOptions {
+  /**
+   * 'local' — persists across browser sessions (localStorage)
+   * 'session' — cleared when tab is closed (sessionStorage)
+   * @default 'local'
+   */
+  storage?: StorageType;
+  /**
+   * Time-to-live in milliseconds. After expiry, initialValue is returned.
+   * @example ttl: 24 * 60 * 60 * 1000 // 24 hours
+   */
+  ttl?: number;
+}
+
+/**
+ * Unified storage hook that delegates to useLocalStorage or useSessionStorage.
+ *
+ * Used by components (Input, Combobox, MultiSelect, Tabs, etc.) to add
+ * optional persistence via a single `storageKey` prop.
+ *
+ * When storageKey is undefined the hook is a no-op:
+ *   - returns initialValue as current value
+ *   - setValue / removeValue are no-ops
+ * This means adding storageKey to a component has zero overhead when unused.
+ *
+ * @example
+ * const [value, setValue, removeValue] = useStoredValue('my-key', '', { storage: 'session' });
+ */
+export function useStoredValue<T>(
+  storageKey: string | undefined,
+  initialValue: T,
+  options?: UseStoredValueOptions,
+): readonly [T, (value: T | ((prev: T) => T)) => void, () => void] {
+  const storageType = options?.storage ?? 'local';
+  const ttlOption = options?.ttl ? { ttl: options.ttl } : undefined;
+
+  // 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 localResult = useLocalStorage<T>(
+    storageType === 'local' && storageKey ? storageKey : dummyKey,
+    initialValue,
+    ttlOption,
+  );
+
+  const sessionResult = useSessionStorage<T>(
+    storageType === 'session' && storageKey ? storageKey : dummyKey,
+    initialValue,
+    ttlOption,
+  );
+
+  const noopSetValue = useCallback((_value: T | ((prev: T) => T)) => {}, []);
+  const noopRemove = useCallback(() => {}, []);
+
+  // No storageKey — pure no-op, no storage reads/writes
+  if (!storageKey) {
+    return [initialValue, noopSetValue, noopRemove] as const;
+  }
+
+  return storageType === 'local' ? localResult : sessionResult;
+}

package/src/snippets/index.ts

@@ -7,4 +7,4 @@ export {
   createLazyNamedComponent,
 } from './LazyComponent';
 export type { LazyWrapperProps } from './LazyComponent';
-../utils/runtime-errors
+export { emitRuntimeError, RUNTIME_ERROR_EVENT } from '../utils/runtime-errors';