@exegia/corpora-ui 0.5.0

package/src/components/ui/otp-field.tsx

@@ -0,0 +1,88 @@
+"use client";
+
+import { OTPField as OTPFieldPrimitive } from "@base-ui/react/otp-field";
+import * as React from "react";
+import { cn } from "@/lib/utils";
+import { playCue } from "@/lib/sound";
+import { Separator } from "@/components/ui/separator";
+
+export function OTPField({
+  className,
+  size = "default",
+  sound = true,
+  onValueChange,
+  ...props
+}: React.ComponentProps<typeof OTPFieldPrimitive.Root> & {
+  size?: "default" | "lg";
+  /** Play a tick cue per entered character. Inert until bindSounds(). */
+  sound?: boolean;
+}): React.ReactElement {
+  // Typing is keyboard-driven, so the cue is imperative (playCue is gated on
+  // the app having called bindSounds). Tick only when characters are added.
+  const lastLength = React.useRef(
+    String(props.value ?? props.defaultValue ?? "").length,
+  );
+
+  const handleValueChange: NonNullable<typeof onValueChange> = (
+    value,
+    ...rest
+  ) => {
+    if (sound && value.length > lastLength.current) {
+      playCue("tick");
+    }
+    lastLength.current = value.length;
+    onValueChange?.(value, ...rest);
+  };
+
+  return (
+    <OTPFieldPrimitive.Root
+      className={cn(
+        "flex items-center gap-2 has-disabled:opacity-64 has-disabled:**:data-[slot=otp-field-input]:shadow-none has-disabled:**:data-[slot=otp-field-input]:before:shadow-none!",
+        className,
+      )}
+      data-size={size}
+      data-slot="otp-field"
+      onValueChange={handleValueChange}
+      {...props}
+    />
+  );
+}
+
+export function OTPFieldInput({
+  className,
+  ...props
+}: React.ComponentProps<typeof OTPFieldPrimitive.Input>): React.ReactElement {
+  return (
+    <OTPFieldPrimitive.Input
+      className={cn(
+        "relative in-[[data-slot=otp-field][data-size=lg]]:size-10 size-9 min-w-0 rounded-lg border border-input bg-background not-dark:bg-clip-padding text-center in-[[data-slot=otp-field][data-size=lg]]:text-lg text-base text-foreground in-[[data-slot=otp-field][data-size=lg]]:leading-10 leading-9 shadow-xs/5 outline-none ring-ring/24 transition-shadow before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-lg)-1px)] not-focus-visible:not-aria-invalid:before:shadow-[0_1px_--theme(--color-black/4%)] focus-visible:z-10 focus-visible:border-ring focus-visible:shadow-none focus-visible:ring-[3px] focus-visible:ring-ring/24 aria-invalid:border-destructive/36 aria-invalid:shadow-none aria-invalid:focus-visible:border-destructive/64 aria-invalid:focus-visible:ring-destructive/16 sm:in-[[data-slot=otp-field][data-size=lg]]:size-9 sm:size-8 sm:in-[[data-slot=otp-field][data-size=lg]]:text-base sm:text-sm sm:in-[[data-slot=otp-field][data-size=lg]]:leading-9 sm:leading-8 dark:bg-input/32 dark:aria-invalid:focus-visible:ring-destructive/24 dark:not-focus-visible:not-aria-invalid:before:shadow-[0_-1px_--theme(--color-white/6%)]",
+        className,
+      )}
+      data-slot="otp-field-input"
+      spellCheck={false}
+      {...props}
+    />
+  );
+}
+
+export function OTPFieldSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof Separator>): React.ReactElement {
+  return (
+    <OTPFieldPrimitive.Separator
+      render={
+        <Separator
+          className={cn(
+            "rounded-full bg-input data-[orientation=horizontal]:h-0.5 data-[orientation=horizontal]:w-3",
+            className,
+          )}
+          orientation="horizontal"
+          {...props}
+        />
+      }
+    />
+  );
+}
+
+export { OTPFieldPrimitive };

package/src/components/ui/separator.tsx

@@ -0,0 +1,23 @@
+import { Separator as SeparatorPrimitive } from "@base-ui/react/separator";
+import type React from "react";
+import { cn } from "@/lib/utils";
+
+export function Separator({
+  className,
+  orientation = "horizontal",
+  ...props
+}: SeparatorPrimitive.Props): React.ReactElement {
+  return (
+    <SeparatorPrimitive
+      className={cn(
+        "shrink-0 bg-border data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-full data-[orientation=vertical]:w-px data-[orientation=vertical]:not-[[class^='h-']]:not-[[class*='_h-']]:self-stretch",
+        className,
+      )}
+      data-slot="separator"
+      orientation={orientation}
+      {...props}
+    />
+  );
+}
+
+export { SeparatorPrimitive };

package/src/components/ui/spinner.tsx

@@ -0,0 +1,17 @@
+import { Loader2Icon } from "lucide-react";
+import type React from "react";
+import { cn } from "@/lib/utils";
+
+export function Spinner({
+  className,
+  ...props
+}: React.ComponentProps<typeof Loader2Icon>): React.ReactElement {
+  return (
+    <Loader2Icon
+      aria-label="Loading"
+      className={cn("animate-spin", className)}
+      role="status"
+      {...props}
+    />
+  );
+}

package/src/components/ui/textarea.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import { Field as FieldPrimitive } from "@base-ui/react/field";
+import { mergeProps } from "@base-ui/react/merge-props";
+import type * as React from "react";
+import { cn } from "@/lib/utils";
+
+export type TextareaProps = React.ComponentPropsWithoutRef<"textarea"> &
+  React.RefAttributes<HTMLTextAreaElement> & {
+    size?: "sm" | "default" | "lg" | number;
+    unstyled?: boolean;
+  };
+
+export function Textarea({
+  className,
+  size = "default",
+  unstyled = false,
+  ref,
+  ...props
+}: TextareaProps): React.ReactElement {
+  return (
+    <span
+      className={
+        cn(
+          !unstyled &&
+            "relative inline-flex w-full rounded-lg border border-input bg-background not-dark:bg-clip-padding text-base text-foreground shadow-xs/5 ring-ring/24 transition-shadow before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-lg)-1px)] has-focus-visible:has-aria-invalid:border-destructive/64 has-focus-visible:has-aria-invalid:ring-destructive/16 has-aria-invalid:border-destructive/36 has-focus-visible:border-ring has-disabled:opacity-64 has-[:disabled,:focus-visible,[aria-invalid]]:shadow-none has-focus-visible:ring-[3px] not-has-disabled:has-not-focus-visible:not-has-aria-invalid:before:shadow-[0_1px_--theme(--color-black/4%)] sm:text-sm dark:bg-input/32 dark:has-aria-invalid:ring-destructive/24 dark:not-has-disabled:has-not-focus-visible:not-has-aria-invalid:before:shadow-[0_-1px_--theme(--color-white/6%)]",
+          className,
+        ) || undefined
+      }
+      data-size={size}
+      data-slot="textarea-control"
+    >
+      <FieldPrimitive.Control
+        ref={ref}
+        value={props.value}
+        defaultValue={props.defaultValue}
+        disabled={props.disabled}
+        id={props.id}
+        name={props.name}
+        render={(defaultProps: React.ComponentProps<"textarea">) => (
+          <textarea
+            className={cn(
+              "field-sizing-content min-h-17.5 w-full rounded-[inherit] px-[calc(--spacing(3)-1px)] py-[calc(--spacing(1.5)-1px)] outline-none max-sm:min-h-20.5",
+              size === "sm" &&
+                "min-h-16.5 px-[calc(--spacing(2.5)-1px)] py-[calc(--spacing(1)-1px)] max-sm:min-h-19.5",
+              size === "lg" &&
+                "min-h-18.5 py-[calc(--spacing(2)-1px)] max-sm:min-h-21.5",
+            )}
+            data-slot="textarea"
+            {...mergeProps(defaultProps, props)}
+          />
+        )}
+      />
+    </span>
+  );
+}
+
+export { FieldPrimitive };

package/src/index.css

@@ -0,0 +1,171 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "shadcn/tailwind.css";
+@import "@fontsource-variable/inter";
+@import "@fontsource-variable/figtree";
+
+@custom-variant dark (&:is(.dark *));
+
+:root {
+    /* Let width/height tween between auto and fixed values (e.g. a button
+       toggling to an icon-only size). Progressive enhancement: browsers
+       without support keep the instant jump. */
+    interpolate-size: allow-keywords;
+    --background: oklch(1 0 0);
+    --foreground: oklch(0.145 0 0);
+    --card: oklch(1 0 0);
+    --card-foreground: oklch(0.145 0 0);
+    --popover: oklch(1 0 0);
+    --popover-foreground: oklch(0.145 0 0);
+    --primary: oklch(0.457 0.24 277.023);
+    --primary-foreground: oklch(0.962 0.018 272.314);
+    --secondary: oklch(0.967 0.001 286.375);
+    --secondary-foreground: oklch(0.21 0.006 285.885);
+    --muted: oklch(0.97 0 0);
+    --muted-foreground: oklch(0.556 0 0);
+    --accent: oklch(0.97 0 0);
+    --accent-foreground: oklch(0.205 0 0);
+    --destructive: oklch(0.577 0.245 27.325);
+    --border: oklch(0.922 0 0);
+    --input: oklch(0.922 0 0);
+    --ring: oklch(0.708 0 0);
+    --chart-1: oklch(0.811 0.111 293.571);
+    --chart-2: oklch(0.606 0.25 292.717);
+    --chart-3: oklch(0.541 0.281 293.009);
+    --chart-4: oklch(0.491 0.27 292.581);
+    --chart-5: oklch(0.432 0.232 292.759);
+    --radius: 0.875rem;
+    --sidebar: oklch(0.985 0 0);
+    --sidebar-foreground: oklch(0.145 0 0);
+    --sidebar-primary: oklch(0.511 0.262 276.966);
+    --sidebar-primary-foreground: oklch(0.962 0.018 272.314);
+    --sidebar-accent: oklch(0.97 0 0);
+    --sidebar-accent-foreground: oklch(0.205 0 0);
+    --sidebar-border: oklch(0.922 0 0);
+    --sidebar-ring: oklch(0.708 0 0);
+    --destructive-foreground: var(--color-red-700);
+}
+
+.dark {
+    --background: oklch(0.145 0 0);
+    --foreground: oklch(0.985 0 0);
+    --card: oklch(0.205 0 0);
+    --card-foreground: oklch(0.985 0 0);
+    --popover: oklch(0.205 0 0);
+    --popover-foreground: oklch(0.985 0 0);
+    --primary: oklch(0.398 0.195 277.366);
+    --primary-foreground: oklch(0.962 0.018 272.314);
+    --secondary: oklch(0.274 0.006 286.033);
+    --secondary-foreground: oklch(0.985 0 0);
+    --muted: oklch(0.269 0 0);
+    --muted-foreground: oklch(0.708 0 0);
+    --accent: oklch(0.269 0 0);
+    --accent-foreground: oklch(0.985 0 0);
+    --destructive: oklch(0.704 0.191 22.216);
+    --border: oklch(1 0 0 / 10%);
+    --input: oklch(1 0 0 / 15%);
+    --ring: oklch(0.556 0 0);
+    --chart-1: oklch(0.811 0.111 293.571);
+    --chart-2: oklch(0.606 0.25 292.717);
+    --chart-3: oklch(0.541 0.281 293.009);
+    --chart-4: oklch(0.491 0.27 292.581);
+    --chart-5: oklch(0.432 0.232 292.759);
+    --sidebar: oklch(0.205 0 0);
+    --sidebar-foreground: oklch(0.985 0 0);
+    --sidebar-primary: oklch(0.585 0.233 277.117);
+    --sidebar-primary-foreground: oklch(0.962 0.018 272.314);
+    --sidebar-accent: oklch(0.269 0 0);
+    --sidebar-accent-foreground: oklch(0.985 0 0);
+    --sidebar-border: oklch(1 0 0 / 10%);
+    --sidebar-ring: oklch(0.556 0 0);
+    --destructive-foreground: var(--color-red-400);
+}
+
+@theme inline {
+    /* motion tokens (transitions.dev scale) */
+    --ease-smooth-out: cubic-bezier(0.22, 1, 0.36, 1);
+    --font-sans: 'Inter Variable', sans-serif;
+    --font-heading: 'Figtree Variable', sans-serif;
+    --color-sidebar-ring: var(--sidebar-ring);
+    --color-sidebar-border: var(--sidebar-border);
+    --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+    --color-sidebar-accent: var(--sidebar-accent);
+    --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+    --color-sidebar-primary: var(--sidebar-primary);
+    --color-sidebar-foreground: var(--sidebar-foreground);
+    --color-sidebar: var(--sidebar);
+    --color-chart-5: var(--chart-5);
+    --color-chart-4: var(--chart-4);
+    --color-chart-3: var(--chart-3);
+    --color-chart-2: var(--chart-2);
+    --color-chart-1: var(--chart-1);
+    --color-ring: var(--ring);
+    --color-input: var(--input);
+    --color-border: var(--border);
+    --color-destructive: var(--destructive);
+    --color-accent-foreground: var(--accent-foreground);
+    --color-accent: var(--accent);
+    --color-muted-foreground: var(--muted-foreground);
+    --color-muted: var(--muted);
+    --color-secondary-foreground: var(--secondary-foreground);
+    --color-secondary: var(--secondary);
+    --color-primary-foreground: var(--primary-foreground);
+    --color-primary: var(--primary);
+    --color-popover-foreground: var(--popover-foreground);
+    --color-popover: var(--popover);
+    --color-card-foreground: var(--card-foreground);
+    --color-card: var(--card);
+    --color-foreground: var(--foreground);
+    --color-background: var(--background);
+    --radius-sm: calc(var(--radius) * 0.6);
+    --radius-md: calc(var(--radius) * 0.8);
+    --radius-lg: var(--radius);
+    --radius-xl: calc(var(--radius) * 1.4);
+    --radius-2xl: calc(var(--radius) * 1.8);
+    --radius-3xl: calc(var(--radius) * 2.2);
+    --radius-4xl: calc(var(--radius) * 2.6);
+    --color-destructive-foreground: var(--destructive-foreground);
+  @keyframes liquid-drift {
+  0% {
+    background-position: 0% 0%, 100% 100%, 0% 0%;
+        }
+  50% {
+    background-position: 30% 20%, 70% 80%, 0% 0%;
+        }
+  100% {
+    background-position: 0% 0%, 100% 100%, 0% 0%;
+        }
+    }
+  --animate-caret-blink: 1s ease-out infinite caret-blink
+;
+  --animate-input-shake: input-shake 0.4s ease-in-out;
+  @keyframes input-shake {
+    0%, 100% { translate: 0; }
+    20% { translate: -6px 0; }
+    40% { translate: 6px 0; }
+    60% { translate: -4px 0; }
+    80% { translate: 4px 0; }
+  }
+  @keyframes caret-blink {
+  0%, 70%, to {
+    opacity: 1;
+        }
+  20%, 50% {
+    opacity: 0;
+        }
+    }}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+    }
+  body {
+    @apply bg-background text-foreground;
+    }
+  button:not(:disabled), [role="button"]:not(:disabled) {
+    cursor: pointer;
+    }
+  html {
+    @apply font-sans;
+    }
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * npm library entry point (`@corpora/ui`).
+ *
+ * Export every published component here — atoms from `components/ui`,
+ * compositions from `components/composed`, blocks from `components/blocks`.
+ * The docs site (main.tsx + routes.tsx + pages/) is NOT part of the package.
+ */
+
+// atoms
+export * from "./components/ui/button"
+export * from "./components/ui/card"
+export * from "./components/ui/checkbox"
+export * from "./components/ui/field"
+export * from "./components/ui/frame"
+export * from "./components/ui/input"
+export * from "./components/ui/input-group"
+export * from "./components/ui/label"
+export * from "./components/ui/otp-field"
+export * from "./components/ui/separator"
+export * from "./components/ui/spinner"
+export * from "./components/ui/textarea"
+
+// components
+export * from "./components/composed/password-input"
+export * from "./components/composed/social-providers"
+
+// blocks
+export * from "./components/blocks/auth/auth-shell"
+export * from "./components/blocks/auth/code-auth-block"
+export * from "./components/blocks/auth/forgot-password-block"
+export * from "./components/blocks/auth/login-block"
+export * from "./components/blocks/auth/signup-block"
+
+// lib
+export * from "./lib/auth-accent"
+export * from "./lib/sound"
+export * from "./lib/utils"

package/src/lib/auth-accent.ts

@@ -0,0 +1,49 @@
+/**
+ * Brand accents for the auth blocks.
+ *
+ * An accent is a set of custom properties set on the AuthCard root plus one
+ * class string applied to the card's primary action. Splitting it this way
+ * keeps the accent inheritable — anything else inside the card can opt into
+ * `var(--auth-accent)` without the shell knowing about it.
+ */
+
+/** Brand accents available to the auth blocks. */
+export type AuthAccent = "corpora" | "exegia";
+
+/**
+ * Custom properties an accent contributes, set on the AuthCard root.
+ *
+ * The gradient lives in `--auth-accent-image` because `background-color` can't
+ * hold one; `--auth-accent` sits underneath as the solid that paints wherever
+ * the image is `none`. Foregrounds are fixed rather than themed — the accent
+ * itself is a constant, so its contrast pair has to be too (white on the
+ * corpora yellow fails badly).
+ */
+export const authAccentVars: Record<AuthAccent, Record<string, string>> = {
+  corpora: {
+    "--auth-accent": "#E8B124",
+    "--auth-accent-image": "none",
+    "--auth-accent-foreground": "oklch(0.145 0 0)",
+  },
+  exegia: {
+    "--auth-accent": "#3B0080",
+    "--auth-accent-image":
+      "linear-gradient(44deg in oklab, rgba(29,0,202,0.66) 3%, #3B0080 37%, rgba(36,0,72,0.86) 98%)",
+    "--auth-accent-foreground": "oklch(0.985 0 0)",
+  },
+};
+
+/**
+ * Applied to the primary action inside an accented AuthCard, after the button
+ * cva output so tailwind-merge lets it win over `bg-primary`. The hover and
+ * pressed background entries are required: `hover:bg-primary/90` lives in a
+ * different modifier group from `bg-*` and would otherwise survive and repaint
+ * the button on hover.
+ *
+ * Hover uses `brightness` rather than a background tween because the button's
+ * `transition-property` list is shared with its press/size animations — adding
+ * `filter` to it means restating the whole list and its per-property
+ * durations. The trade is an instant hover change instead of a 150ms one.
+ */
+export const authAccentActionStyles =
+  "border-transparent bg-[var(--auth-accent)] bg-[image:var(--auth-accent-image)] text-[var(--auth-accent-foreground)] shadow-none hover:bg-[var(--auth-accent)] hover:brightness-110 data-pressed:bg-[var(--auth-accent)] data-pressed:brightness-110 *:data-[slot=button-loading-indicator]:text-[var(--auth-accent-foreground)]";

package/src/lib/glass-variants.ts

@@ -0,0 +1,57 @@
+export type FrostGlassVariant = "clear" | "frosted" | "subtle" | "liquid" | "liquid-refract";
+export type FrostGlassVariantProp = { glassVariant?: FrostGlassVariant };
+
+export const liquidRefractStyles = "bg-transparent border-0 shadow-none";
+
+export const glassVariantStyles: Record<FrostGlassVariant, string> = {
+  clear: [
+    "backdrop-blur-[2px] backdrop-saturate-[1.9]",
+    "bg-white/[0.25] dark:bg-black/[0.25]",
+    "border border-white/[0.5] dark:border-white/[0.12]",
+    "shadow-[0_1px_12px_rgba(0,0,0,0.05)] dark:shadow-[0_1px_12px_rgba(0,0,0,0.2)]",
+  ].join(" "),
+  frosted: [
+    "backdrop-blur-[16px] backdrop-saturate-[1.6]",
+    "bg-white/[0.55] dark:bg-black/[0.35]",
+    "border border-white/[0.4] dark:border-white/10",
+    "shadow-[0_2px_20px_rgba(0,0,0,0.06)] dark:shadow-[0_2px_20px_rgba(0,0,0,0.3)]",
+  ].join(" "),
+  subtle: [
+    "backdrop-blur-[4px] backdrop-saturate-[1.5]",
+    "bg-white/[0.3] dark:bg-white/[0.06]",
+    "border border-black/[0.05] dark:border-white/[0.08]",
+    "shadow-sm",
+  ].join(" "),
+  liquid: [
+    // 1) Refractive backdrop — lighter than frosted so the background reads
+    //    clearly through the lens; saturation + brightness lift makes it bloom.
+    "backdrop-blur-[12px] backdrop-saturate-[1.8] backdrop-brightness-[1.05]",
+    "dark:backdrop-saturate-[1.6] dark:backdrop-brightness-[0.95]",
+
+    // 2) Base translucent fill (acts as the panel's "tint").
+    "bg-white/[0.10] dark:bg-white/[0.04]",
+
+    // 3) Layered radial-gradient sheen + warm bottom tint + vertical wash.
+    //    Underscores represent spaces inside Tailwind arbitrary values.
+    "[background-image:radial-gradient(120%_85%_at_15%_8%,rgba(255,255,255,0.55)_0%,rgba(255,255,255,0.18)_38%,rgba(255,255,255,0)_70%),radial-gradient(110%_80%_at_85%_100%,rgba(255,210,230,0.22)_0%,rgba(255,255,255,0)_60%),linear-gradient(180deg,rgba(255,255,255,0.28)_0%,rgba(255,255,255,0.12)_100%)]",
+    "dark:[background-image:radial-gradient(120%_85%_at_15%_8%,rgba(255,255,255,0.18)_0%,rgba(255,255,255,0.05)_40%,rgba(255,255,255,0)_70%),radial-gradient(110%_80%_at_85%_100%,rgba(120,170,255,0.12)_0%,rgba(0,0,0,0)_60%),linear-gradient(180deg,rgba(255,255,255,0.06)_0%,rgba(0,0,0,0.18)_100%)]",
+    "[background-size:200%_200%,180%_180%,100%_100%]",
+    "[background-repeat:no-repeat]",
+
+    // 4) Multi-layer bevel:
+    //    - inset top hairline highlight (light-from-above)
+    //    - inset fish-eye glow at the bottom (lensing artifact)
+    //    - thin inset side rails
+    //    - outer contact shadow + broader halo (panel feels floating)
+    "shadow-[inset_0_1px_0_0_rgba(255,255,255,0.65),inset_0_-12px_24px_-10px_rgba(255,255,255,0.45),inset_1px_0_0_0_rgba(255,255,255,0.22),inset_-1px_0_0_0_rgba(255,255,255,0.18),0_24px_60px_-18px_rgba(15,23,42,0.30),0_8px_24px_-8px_rgba(15,23,42,0.18)]",
+    "dark:shadow-[inset_0_1px_0_0_rgba(255,255,255,0.30),inset_0_-14px_28px_-10px_rgba(180,210,255,0.18),inset_1px_0_0_0_rgba(255,255,255,0.10),inset_-1px_0_0_0_rgba(255,255,255,0.08),0_28px_70px_-18px_rgba(0,0,0,0.55),0_10px_28px_-10px_rgba(0,0,0,0.40)]",
+
+    // 5) Hairline border for the chamfer's outer edge.
+    "border border-white/[0.45] dark:border-white/[0.10]",
+
+    // 6) Slow ambient drift; respects prefers-reduced-motion.
+    "animate-[liquid-drift_18s_ease-in-out_infinite] motion-reduce:animate-none",
+    "[will-change:background-position]",
+  ].join(" "),
+  "liquid-refract": "",
+};

package/src/lib/sound.ts

@@ -0,0 +1,39 @@
+/**
+ * Interaction sound for the library, powered by cuelume (Web Audio synthesis,
+ * zero runtime deps, SSR-safe).
+ *
+ * Components only emit inert `data-cuelume-*` attributes — nothing plays
+ * until the consuming app opts in once:
+ *
+ *   import { bindSounds } from "@corpora/ui"
+ *   bindSounds()
+ *
+ * The app owns preferences via setSoundEnabled / setSoundVolume.
+ */
+import { bind, play } from "cuelume";
+import type { SoundName } from "cuelume";
+
+let bound = false;
+
+/** Opt into interaction sound. Delegated and idempotent (see cuelume bind). */
+export function bindSounds(root?: ParentNode): void {
+  bound = true;
+  bind(root);
+}
+
+/**
+ * Imperative cue used by library components for keyboard-driven interactions
+ * the data attributes can't cover (OTP typing, visibility toggles, …).
+ * No-op until the app has opted in via bindSounds().
+ */
+export function playCue(name: SoundName, options?: { volume?: number }): void {
+  if (bound) play(name, options);
+}
+
+export {
+  play as playSound,
+  setEnabled as setSoundEnabled,
+  setVolume as setSoundVolume,
+  sounds,
+} from "cuelume";
+export type { SoundName };

package/src/lib/utils.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from "bun:test"
+
+import { glassVariantStyles } from "./glass-variants"
+import { cn } from "./utils"
+
+describe("cn", () => {
+  test("merges conflicting tailwind classes", () => {
+    expect(cn("p-2", "p-4")).toBe("p-4")
+  })
+
+  test("drops falsy values", () => {
+    expect(cn("a", undefined, null, "c")).toBe("a c")
+  })
+})
+
+describe("glassVariantStyles", () => {
+  test("has a style entry for every glass finish", () => {
+    expect(Object.keys(glassVariantStyles).sort()).toEqual(
+      ["clear", "frosted", "liquid", "liquid-refract", "subtle"].sort(),
+    )
+  })
+})

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}