@spatika/react 1.0.0

package/src/lib/cover-pattern.ts

@@ -0,0 +1,242 @@
+/**
+ * Seeded cover scenes for profile / story heroes.
+ * Compact kit set — journalD ships a larger catalog; kinds here keep the same
+ * contract (palette, headerInk, chromeInk, layered SVG geometry).
+ */
+
+export const COVER_PATTERN_KINDS = [
+  "mountains",
+  "aurora",
+  "ocean",
+  "meadow",
+  "dusk",
+  "lake",
+] as const;
+
+export type CoverPatternKind = (typeof COVER_PATTERN_KINDS)[number];
+
+export type CoverPatternInput = {
+  seed: string;
+  hue: number;
+  secondaryHue?: number;
+  tertiaryHue?: number;
+  dark?: boolean;
+  warm?: boolean;
+  kind?: CoverPatternKind | null;
+};
+
+export type CoverNaturePalette = {
+  skyTop: string;
+  skyBottom: string;
+  far: string;
+  mid: string;
+  near: string;
+  accent: string;
+  water: string;
+  highlight: string;
+  star: string;
+};
+
+export type CoverCircle = {
+  cx: number;
+  cy: number;
+  r: number;
+  fill: string;
+  opacity?: number;
+};
+
+export type CoverEllipse = {
+  cx: number;
+  cy: number;
+  rx: number;
+  ry: number;
+  fill?: string;
+  opacity?: number;
+};
+
+export type CoverPath = {
+  d: string;
+  fill?: string;
+  opacity?: number;
+};
+
+export type CoverPolygon = {
+  points: string;
+  fill: string;
+  opacity?: number;
+};
+
+/** `light` = white-ish text on a dark scene; `dark` = near-black text on a pale scene. */
+export type CoverHeaderInk = "light" | "dark";
+
+export type CoverScene = {
+  kind: CoverPatternKind;
+  palette: CoverNaturePalette;
+  uid: string;
+  skyStyle: { backgroundColor: string; backgroundImage: string };
+  headerInk: CoverHeaderInk;
+  chromeInk: CoverHeaderInk;
+  polygons: CoverPolygon[];
+  paths: CoverPath[];
+  ellipses: CoverEllipse[];
+  circles: CoverCircle[];
+};
+
+export type CoverPattern = CoverScene;
+
+const VW = 1600;
+const VH = 420;
+
+function hashSeed(value: string): number {
+  let hash = 2166136261;
+  const source = value || "User";
+  for (let i = 0; i < source.length; i++) {
+    hash ^= source.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+
+function wrapHue(hue: number): number {
+  return ((hue % 360) + 360) % 360;
+}
+
+function pick(hash: number, salt: number, modulo: number): number {
+  return (hash + salt * 2654435761) % modulo;
+}
+
+function hsl(h: number, s: number, l: number): string {
+  return `hsl(${Math.round(wrapHue(h))} ${Math.round(s)}% ${Math.round(l)}%)`;
+}
+
+function parseHslL(color: string): number | null {
+  const match = color.match(/hsl\(\s*[\d.]+\s+[\d.]+%\s+([\d.]+)%\s*\)/i);
+  return match ? Number(match[1]) : null;
+}
+
+export function isCoverPatternKind(value: string | null | undefined): value is CoverPatternKind {
+  return Boolean(value && (COVER_PATTERN_KINDS as readonly string[]).includes(value));
+}
+
+function buildPalette(
+  kind: CoverPatternKind,
+  hue: number,
+  secondary: number,
+  dark: boolean,
+): CoverNaturePalette {
+  const skyL = dark ? 14 : kind === "dusk" || kind === "aurora" ? 28 : 78;
+  const landL = dark ? 18 : 42;
+  const shift = kind === "ocean" || kind === "lake" ? 18 : 0;
+  return {
+    skyTop: hsl(hue + (kind === "aurora" ? 40 : 8), dark ? 38 : 52, skyL + (dark ? 0 : 8)),
+    skyBottom: hsl(hue + shift, dark ? 32 : 48, skyL - 8),
+    far: hsl(secondary, 28, landL + 12),
+    mid: hsl(hue + 12, 34, landL),
+    near: hsl(hue - 8, 38, landL - 8),
+    accent: hsl(hue + 48, 62, dark ? 58 : 52),
+    water: hsl(hue + 18 + shift, 42, dark ? 28 : 48),
+    highlight: hsl(hue + 20, 70, dark ? 72 : 88),
+    star: hsl(hue, 20, 96),
+  };
+}
+
+function getCoverHeaderInk(palette: CoverNaturePalette): CoverHeaderInk {
+  const samples = [palette.near, palette.mid, palette.skyBottom];
+  const luma =
+    samples.reduce((sum, color) => sum + (parseHslL(color) ?? 50), 0) / samples.length;
+  return luma < 36 ? "light" : "dark";
+}
+
+function getCoverChromeInk(palette: CoverNaturePalette): CoverHeaderInk {
+  const luma = parseHslL(palette.skyTop);
+  return (luma ?? 50) < 42 ? "light" : "dark";
+}
+
+function ridge(y: number, amp: number, phase: number, fill: string): CoverPath {
+  const steps = 8;
+  let d = `M0 ${VH} L0 ${y}`;
+  for (let i = 1; i <= steps; i++) {
+    const x = (VW / steps) * i;
+    const wave = Math.sin((i + phase) * 0.9) * amp;
+    d += ` L${x} ${y + wave}`;
+  }
+  d += ` L${VW} ${VH} Z`;
+  return { d, fill };
+}
+
+function buildScene(
+  kind: CoverPatternKind,
+  hash: number,
+  palette: CoverNaturePalette,
+): Pick<CoverScene, "polygons" | "paths" | "ellipses" | "circles"> {
+  const sunX = 220 + pick(hash, 3, 1100);
+  const sunY = kind === "dusk" ? 90 : 70;
+  const sunR = kind === "aurora" ? 28 : 46;
+  const paths: CoverPath[] = [
+    ridge(250, 28, pick(hash, 5, 6), palette.far),
+    ridge(290, 36, pick(hash, 7, 6), palette.mid),
+    ridge(340, 22, pick(hash, 9, 6), palette.near),
+  ];
+  const circles: CoverCircle[] = [
+    { cx: sunX, cy: sunY, r: sunR, fill: palette.highlight, opacity: 0.9 },
+  ];
+  const ellipses: CoverEllipse[] = [];
+
+  if (kind === "ocean" || kind === "lake") {
+    paths.push({
+      d: `M0 310 Q400 280 800 320 T${VW} 300 L${VW} ${VH} L0 ${VH} Z`,
+      fill: palette.water,
+      opacity: 0.85,
+    });
+  }
+  if (kind === "aurora") {
+    ellipses.push(
+      { cx: 480, cy: 90, rx: 340, ry: 48, fill: palette.accent, opacity: 0.35 },
+      { cx: 980, cy: 70, rx: 280, ry: 36, fill: palette.highlight, opacity: 0.28 },
+    );
+  }
+  if (kind === "meadow") {
+    circles.push(
+      { cx: 180, cy: 360, r: 14, fill: palette.accent, opacity: 0.7 },
+      { cx: 420, cy: 380, r: 10, fill: palette.highlight, opacity: 0.65 },
+      { cx: 1280, cy: 350, r: 12, fill: palette.accent, opacity: 0.6 },
+    );
+  }
+
+  return { polygons: [], paths, ellipses, circles };
+}
+
+export function getCoverPattern(input: CoverPatternInput): CoverScene {
+  const seed = input.seed || "User";
+  const hash = hashSeed(seed);
+  const kind = isCoverPatternKind(input.kind)
+    ? input.kind
+    : COVER_PATTERN_KINDS[pick(hash, 1, COVER_PATTERN_KINDS.length)];
+  const dark = Boolean(input.dark);
+  const warmth = input.warm ? 8 : 0;
+  const hue = wrapHue(input.hue + warmth);
+  const secondary = wrapHue((input.secondaryHue ?? input.hue + 28) + warmth);
+  const palette = buildPalette(kind, hue, secondary, dark);
+  const drawn = buildScene(kind, hash, palette);
+
+  return {
+    kind,
+    palette,
+    uid: `n${hash.toString(36)}-${kind}`,
+    headerInk: getCoverHeaderInk(palette),
+    chromeInk: getCoverChromeInk(palette),
+    skyStyle: {
+      backgroundColor: palette.skyBottom,
+      backgroundImage: `linear-gradient(180deg, ${palette.skyTop} 0%, ${palette.skyBottom} 72%)`,
+    },
+    ...drawn,
+  };
+}
+
+export function getCoverPatternStyle(input: CoverPatternInput): CoverScene["skyStyle"] {
+  return getCoverPattern(input).skyStyle;
+}
+
+export function getCoverPatternKind(input: CoverPatternInput): CoverPatternKind {
+  return getCoverPattern(input).kind;
+}

package/src/lib/overlay-stack.ts

@@ -0,0 +1,44 @@
+import type * as React from "react";
+
+/**
+ * Stacking layers for portaled UI.
+ *
+ * App shells (e.g. journalD fullscreen story editor) often use z-index ~9999.
+ * Floating menus sit just above that; modal dialogs sit above menus.
+ */
+export const OVERLAY_Z_INDEX = {
+  /** Popovers / selects that are not competing with fullscreen editors. */
+  popover: 90,
+  /** Dropdown menus (including menus opened inside fullscreen editors). */
+  menu: 10000,
+  /** Modal overlays + dialog/sheet/alert content. */
+  modal: 11000,
+} as const;
+
+/** Inline styles that beat consumer `.glass { position: relative }` rules. */
+export function fixedLayerStyle(
+  zIndex: number,
+  extra?: React.CSSProperties,
+): React.CSSProperties {
+  return {
+    position: "fixed",
+    zIndex,
+    ...extra,
+  };
+}
+
+/**
+ * Radix-compatible synthetic event for menu `onSelect`.
+ * Callers use `event.preventDefault()` to keep the menu open.
+ */
+export function createSelectEvent(): Event {
+  let prevented = false;
+  return {
+    preventDefault() {
+      prevented = true;
+    },
+    get defaultPrevented() {
+      return prevented;
+    },
+  } as Event;
+}

package/src/lib/portal.tsx

@@ -0,0 +1,21 @@
+import * as React from "react";
+import { createPortal } from "react-dom";
+
+export type PortalProps = {
+  children: React.ReactNode;
+  container?: HTMLElement | null;
+};
+
+/**
+ * Renders children into `document.body` (or a provided container) via React portal.
+ * Mounts synchronously on the client so floating content can be measured in the
+ * same layout pass (avoids width=0 positioning flashes).
+ */
+export function Portal({ children, container }: PortalProps) {
+  const target =
+    container ?? (typeof document !== "undefined" ? document.body : null);
+
+  if (!target) return null;
+
+  return createPortal(children, target);
+}

package/src/lib/slot.tsx

@@ -0,0 +1,69 @@
+import * as React from "react";
+import { composeRefs } from "./compose-refs";
+
+type AnyProps = Record<string, unknown>;
+
+/**
+ * Merges two prop objects, composing event handlers and classNames,
+ * and merging style objects. Used by Slot for asChild composition.
+ */
+function mergeProps(slotProps: AnyProps, childProps: AnyProps): AnyProps {
+  const override: AnyProps = { ...childProps };
+
+  for (const propName of Object.keys(slotProps)) {
+    const slotValue = slotProps[propName];
+    const childValue = childProps[propName];
+
+    const isHandler = /^on[A-Z]/.test(propName);
+    if (isHandler) {
+      if (slotValue && childValue) {
+        override[propName] = (...args: unknown[]) => {
+          (childValue as (...a: unknown[]) => void)(...args);
+          (slotValue as (...a: unknown[]) => void)(...args);
+        };
+      } else if (slotValue) {
+        override[propName] = slotValue;
+      }
+    } else if (propName === "style") {
+      override[propName] = {
+        ...((slotValue as React.CSSProperties) || {}),
+        ...((childValue as React.CSSProperties) || {}),
+      };
+    } else if (propName === "className") {
+      override[propName] = [slotValue, childValue].filter(Boolean).join(" ");
+    } else if (childValue === undefined) {
+      override[propName] = slotValue;
+    }
+  }
+
+  return override;
+}
+
+export type SlotProps = React.HTMLAttributes<HTMLElement> & {
+  children?: React.ReactNode;
+};
+
+/**
+ * Renders as its single React element child, merging Slot props onto that child.
+ * Used for `asChild` composition on Button, Badge, and overlay triggers.
+ */
+export const Slot = React.forwardRef<HTMLElement, SlotProps>(
+  ({ children, ...props }, forwardedRef) => {
+    if (!React.isValidElement(children)) {
+      return null;
+    }
+
+    const child = children as React.ReactElement & {
+      ref?: React.Ref<HTMLElement>;
+    };
+
+    const childProps = (child.props ?? {}) as AnyProps;
+    const merged = mergeProps(props as AnyProps, childProps);
+
+    return React.cloneElement(child, {
+      ...merged,
+      ref: composeRefs(forwardedRef, child.ref),
+    } as AnyProps);
+  },
+);
+Slot.displayName = "Slot";

package/src/lib/surfaces.ts

@@ -0,0 +1,57 @@
+/**
+ * Surface / card hierarchy class recipes.
+ * Use with GlassCard or SurfaceCard rather than copying Tailwind strings.
+ */
+import { cn } from "./cn";
+
+export const surfaceRadiusCard = "rounded-[var(--radius-card)]";
+export const surfaceRadiusControl = "rounded-[var(--radius-control)]";
+export const surfaceRadiusPill = "rounded-[var(--radius-pill)]";
+
+/** Soft profile-style card radius (squarish). */
+export const surfaceRadiusProfile = "rounded-lg";
+
+/** Primary elevated card (About / hero panels). */
+export const surfacePrimaryClass = cn(
+  "relative h-full overflow-hidden",
+  surfaceRadiusProfile,
+  "border border-border/20",
+  "bg-gradient-to-br from-card via-card to-primary/[0.06] dark:from-card/95 dark:via-card/90 dark:to-primary/[0.08]",
+  "p-3.5 sm:p-5 lg:p-6",
+  "shadow-[0_18px_40px_-24px_rgba(0,0,0,0.35)] dark:shadow-[0_22px_48px_-20px_rgba(0,0,0,0.65)]",
+  "ring-1 ring-inset ring-white/25 dark:ring-white/8",
+  "backdrop-blur-xl",
+);
+
+/** Quieter secondary card. */
+export const surfaceSecondaryClass = cn(
+  "relative h-full overflow-hidden",
+  surfaceRadiusProfile,
+  "border border-border/20",
+  "bg-muted/25 dark:bg-muted/15",
+  "p-3 sm:p-3.5 lg:p-4",
+  "shadow-none",
+  "backdrop-blur-md",
+);
+
+/** Detail glass card with soft elevation. */
+export const surfaceDetailClass = cn(
+  "relative h-full overflow-hidden",
+  surfaceRadiusProfile,
+  "border border-border/25",
+  "bg-card/95 dark:bg-card/80",
+  "p-3 sm:p-4 lg:p-5",
+  "shadow-[0_10px_28px_-18px_rgba(0,0,0,0.28)] dark:shadow-[0_14px_32px_-16px_rgba(0,0,0,0.55)]",
+  "ring-1 ring-inset ring-white/40 dark:ring-white/8",
+  "backdrop-blur-xl",
+);
+
+/** Minimal dashed supporting strip. */
+export const surfaceTertiaryClass = cn(
+  "relative overflow-hidden",
+  surfaceRadiusProfile,
+  "border border-dashed border-border/30",
+  "bg-transparent dark:bg-muted/5",
+  "p-3 sm:p-3.5",
+  "shadow-none",
+);

package/src/lib/themes.test.ts

@@ -0,0 +1,73 @@
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  applyTheme,
+  DEFAULT_THEME,
+  isDarkTheme,
+  isThemeId,
+  SPATIKA_THEME_STORAGE_KEY,
+  readStoredTheme,
+  THEME_IDS,
+  THEME_LABELS,
+  writeStoredTheme,
+} from "./themes";
+
+function resetRoot() {
+  document.documentElement.className = "";
+  document.documentElement.removeAttribute("data-spk-theme");
+  document.documentElement.style.colorScheme = "";
+}
+
+describe("themes", () => {
+  afterEach(() => {
+    resetRoot();
+    localStorage.removeItem(SPATIKA_THEME_STORAGE_KEY);
+  });
+
+  it("lists four named theme ids", () => {
+    expect(THEME_IDS).toEqual(["mukta", "neelam", "usha", "sandhya"]);
+    expect(DEFAULT_THEME).toBe("mukta");
+  });
+
+  it("provides human labels for each theme", () => {
+    for (const id of THEME_IDS) {
+      expect(THEME_LABELS[id]).toBeTruthy();
+    }
+  });
+
+  it("narrows theme ids", () => {
+    expect(isThemeId("neelam")).toBe(true);
+    expect(isThemeId("dark")).toBe(false);
+    expect(isDarkTheme("neelam")).toBe(true);
+    expect(isDarkTheme("usha")).toBe(false);
+  });
+
+  it("applies neelam theme class and data attribute", () => {
+    applyTheme("neelam");
+    expect(document.documentElement.classList.contains("neelam")).toBe(true);
+    expect(document.documentElement.getAttribute("data-spk-theme")).toBe("neelam");
+    expect(document.documentElement.style.colorScheme).toBe("dark");
+  });
+
+  it("clears theme classes for mukta", () => {
+    applyTheme("neelam");
+    applyTheme("mukta");
+    expect(document.documentElement.classList.contains("neelam")).toBe(false);
+    expect(document.documentElement.getAttribute("data-spk-theme")).toBe("mukta");
+    expect(document.documentElement.style.colorScheme).toBe("light");
+  });
+
+  it("applies usha and sandhya without leaving stale classes", () => {
+    applyTheme("usha");
+    applyTheme("sandhya");
+    expect(document.documentElement.classList.contains("usha")).toBe(false);
+    expect(document.documentElement.classList.contains("sandhya")).toBe(true);
+  });
+
+  it("reads and writes stored themes", () => {
+    expect(readStoredTheme(SPATIKA_THEME_STORAGE_KEY)).toBeNull();
+    writeStoredTheme(SPATIKA_THEME_STORAGE_KEY, "sandhya");
+    expect(readStoredTheme(SPATIKA_THEME_STORAGE_KEY)).toBe("sandhya");
+    writeStoredTheme(false, "neelam");
+    expect(readStoredTheme(SPATIKA_THEME_STORAGE_KEY)).toBe("sandhya");
+  });
+});

package/src/lib/themes.ts

@@ -0,0 +1,59 @@
+/** Supported theme identifiers applied as classes on a root element. */
+export const THEME_IDS = ["mukta", "neelam", "usha", "sandhya"] as const;
+
+export type ThemeId = (typeof THEME_IDS)[number];
+
+export const DEFAULT_THEME: ThemeId = "mukta";
+
+/** Default `localStorage` key used by the docs site and `SpatikaThemeProvider`. */
+export const SPATIKA_THEME_STORAGE_KEY = "spk-theme";
+
+export const THEME_LABELS: Record<ThemeId, string> = {
+  mukta: "Mukta",
+  neelam: "Neelam",
+  usha: "Usha",
+  sandhya: "Sandhya",
+};
+
+const THEME_CLASS_LIST = ["neelam", "usha", "sandhya"] as const;
+
+export function isThemeId(value: unknown): value is ThemeId {
+  return typeof value === "string" && (THEME_IDS as readonly string[]).includes(value);
+}
+
+export function isDarkTheme(theme: ThemeId): boolean {
+  return theme === "neelam" || theme === "sandhya";
+}
+
+/** Read a persisted theme. Returns `null` when missing or invalid. */
+export function readStoredTheme(storageKey?: string | false): ThemeId | null {
+  if (!storageKey || typeof window === "undefined") return null;
+  try {
+    const value = window.localStorage.getItem(storageKey);
+    return isThemeId(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Persist a theme. No-op when `storageKey` is unset. */
+export function writeStoredTheme(storageKey: string | false | undefined, theme: ThemeId): void {
+  if (!storageKey || typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(storageKey, theme);
+  } catch {
+    // Private mode / quota — keep the in-memory theme.
+  }
+}
+
+/** Apply a theme class to an element (defaults to `<html>`). */
+export function applyTheme(theme: ThemeId, target?: HTMLElement | null) {
+  if (typeof document === "undefined") return;
+  const root = target ?? document.documentElement;
+  root.classList.remove(...THEME_CLASS_LIST);
+  if (theme !== DEFAULT_THEME) {
+    root.classList.add(theme);
+  }
+  root.setAttribute("data-spk-theme", theme);
+  root.style.colorScheme = isDarkTheme(theme) ? "dark" : "light";
+}

package/src/lib/tokens.test.ts

@@ -0,0 +1,52 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const tokensRoot = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "../../../tokens/src",
+);
+
+describe("@spatika/tokens", () => {
+  it("defines four theme roots", () => {
+    const css = readFileSync(join(tokensRoot, "tokens.css"), "utf8");
+    expect(css).toContain(":root");
+    expect(css).toContain(".neelam");
+    expect(css).toContain(".usha");
+    expect(css).toContain(".sandhya");
+    expect(css).toContain("--glass-bg");
+    expect(css).toContain("--primary");
+  });
+
+  it("ships glass utilities and a11y helpers", () => {
+    const css = readFileSync(join(tokensRoot, "glass.css"), "utf8");
+    expect(css).toContain(".glass");
+    expect(css).toContain(".glass-panel");
+    expect(css).toContain(".spk-focus-ring");
+    expect(css).toContain(".spk-touch-target");
+    expect(css).toContain("prefers-reduced-motion");
+    expect(css).toContain(".glass-tabbar");
+    expect(css).toContain(".glass-page-toolbar");
+  });
+
+  it("ships app chrome, cover bleed, and page-header type", () => {
+    const chrome = readFileSync(join(tokensRoot, "chrome.css"), "utf8");
+    expect(chrome).toContain(".app-chrome-header");
+    expect(chrome).toContain("data-cover-chrome-bleed");
+    expect(chrome).toContain(".story-identity");
+    expect(chrome).toContain(".profile-identity");
+    expect(chrome).toContain(".glass-page-toolbar");
+    expect(chrome).toContain(".app-page-chrome");
+    const tokens = readFileSync(join(tokensRoot, "tokens.css"), "utf8");
+    expect(tokens).toContain("--app-tabbar-height");
+    expect(tokens).toContain("--app-chrome-offset");
+    const surfaces = readFileSync(join(tokensRoot, "surfaces.css"), "utf8");
+    expect(surfaces).toContain(".page-header-title");
+  });
+
+  it("respects reduced motion in base styles", () => {
+    const css = readFileSync(join(tokensRoot, "base.css"), "utf8");
+    expect(css).toContain("prefers-reduced-motion");
+  });
+});

package/src/lib/typography.ts

@@ -0,0 +1,27 @@
+/**
+ * Named typography roles for the Spatika design language.
+ * Prefer these over ad-hoc text-[10px] font-black uppercase strings.
+ */
+
+/** Uppercase micro-label (section kickers, chip group titles). */
+export const typographyEyebrow =
+  "text-[10px] font-black uppercase tracking-widest text-muted-foreground/70";
+
+/** Slightly stronger eyebrow for page bands. */
+export const typographyBandEyebrow =
+  "text-[10px] font-black uppercase tracking-[0.2em] text-muted-foreground/55";
+
+/** Compact card / filter section title. */
+export const typographySectionLabel =
+  "text-[10px] font-black uppercase tracking-widest text-muted-foreground";
+
+/** Primary page title treatment (pairs with .app-title CSS when preferred). */
+export const typographyPageTitle =
+  "text-2xl font-black tracking-tight text-foreground sm:text-3xl";
+
+/** Supporting copy under titles. */
+export const typographyPageSubtitle =
+  "text-sm font-medium leading-relaxed text-muted-foreground";
+
+/** Dense body used in admin / settings panels. */
+export const typographyBodyDense = "text-sm font-medium leading-snug text-foreground";

package/src/lib/use-controllable-state.ts

@@ -0,0 +1,38 @@
+import * as React from "react";
+
+type UseControllableStateParams<T> = {
+  prop?: T;
+  defaultProp?: T;
+  onChange?: (value: T) => void;
+};
+
+/**
+ * Controlled/uncontrolled state helper (Radix-style).
+ * When `prop` is provided the state is controlled; otherwise it uses local state.
+ */
+export function useControllableState<T>({
+  prop,
+  defaultProp,
+  onChange,
+}: UseControllableStateParams<T>): [T | undefined, (value: T | ((prev: T | undefined) => T)) => void] {
+  const [uncontrolled, setUncontrolled] = React.useState(defaultProp);
+  const isControlled = prop !== undefined;
+  const value = isControlled ? prop : uncontrolled;
+
+  const setValue = React.useCallback(
+    (next: T | ((prev: T | undefined) => T)) => {
+      const resolved =
+        typeof next === "function"
+          ? (next as (prev: T | undefined) => T)(value)
+          : next;
+
+      if (!isControlled) {
+        setUncontrolled(resolved);
+      }
+      onChange?.(resolved);
+    },
+    [isControlled, onChange, value],
+  );
+
+  return [value, setValue];
+}