@vaam-apps/ui 0.1.0

package/src/components/primitives/select.tsx

@@ -0,0 +1,254 @@
+"use client";
+
+import { Listbox, ListboxButton, ListboxOption, ListboxOptions } from "@headlessui/react";
+import { Check, ChevronDown } from "lucide-react";
+import {
+  Children,
+  createContext,
+  isValidElement,
+  type ReactElement,
+  type ReactNode,
+  useContext,
+  useMemo,
+  useState,
+} from "react";
+import { cn } from "../../lib/cn";
+import { omitUndefined } from "../../lib/omit-undefined";
+
+/**
+ * D17: Radix `Select` → Headless UI `Listbox`. Flagged in the design doc as
+ * "the largest single API-shape change in the whole primitives migration" —
+ * but Radix `Select`'s own public shape (`Select value/onValueChange` →
+ * `SelectTrigger` → `SelectValue` → `SelectContent` → `SelectItem`) is kept
+ * byte-identical here, so none of this console's eleven call sites need any
+ * change. That's possible because Radix `SelectValue` and Headless UI's
+ * `Listbox` solve the "what does the trigger display" problem differently:
+ * Radix derives it internally from whichever `SelectItem` matches the
+ * current value; `Listbox` has no equivalent (`ListboxButton`'s render prop
+ * only exposes the raw `value`, not a matching option's own children/label
+ * — e.g. `routes-screen.tsx`'s provider select shows `provider.displayName`
+ * for a `value={provider.id}`, not the id itself). `findItemLabel` below
+ * replicates Radix's behaviour by walking `Select`'s own `children` tree
+ * (not the DOM — `ListboxOptions` may not be mounted while closed) to find
+ * the `SelectItem` whose `value` matches, and using *its* children as the
+ * label. Keyboard behaviour (type-ahead, `Escape`, arrow-key nav) is
+ * genuinely Headless UI's own `Listbox`, not reimplemented here — this file
+ * only adds the label-lookup Radix's `SelectValue` used to give for free.
+ */
+
+interface SelectContextValue {
+  value: string | undefined;
+  itemLabel: (value: string) => ReactNode | undefined;
+}
+const SelectContext = createContext<SelectContextValue | null>(null);
+
+function useSelectContext(component: string): SelectContextValue {
+  const ctx = useContext(SelectContext);
+  if (ctx === null) {
+    throw new Error(`<${component} /> must be rendered inside <Select>.`);
+  }
+  return ctx;
+}
+
+function findItemLabel(node: ReactNode, value: string): ReactNode | undefined {
+  let found: ReactNode | undefined;
+  Children.forEach(node, (child) => {
+    if (found !== undefined || !isValidElement(child)) return;
+    const el = child as ReactElement<{ value?: string; children?: ReactNode }>;
+    if (el.type === SelectItem) {
+      if (el.props.value === value) found = el.props.children;
+      return;
+    }
+    if (el.props?.children != null) {
+      found = findItemLabel(el.props.children, value);
+    }
+  });
+  return found;
+}
+
+/**
+ * Note the `| undefined` on the optional props below. This package
+ * compiles under `exactOptionalPropertyTypes`, where a bare `value?:
+ * string` means "you may omit this key" and NOT "you may pass
+ * `undefined`" — so the ordinary controlled pattern,
+ * `const [v, setV] = useState<string>()` followed by `value={v}`, is a
+ * type error. Found writing this component's own story, which is the
+ * first code outside the original application to use it.
+ */
+export interface SelectProps {
+  value?: string | undefined;
+  defaultValue?: string | undefined;
+  onValueChange?: ((value: string) => void) | undefined;
+  disabled?: boolean | undefined;
+  children: ReactNode;
+}
+
+export function Select({ value, defaultValue, onValueChange, disabled, children }: SelectProps) {
+  const [internalValue, setInternalValue] = useState(defaultValue);
+  const isControlled = value !== undefined;
+  const currentValue = isControlled ? value : internalValue;
+
+  function handleChange(next: string) {
+    if (!isControlled) setInternalValue(next);
+    onValueChange?.(next);
+  }
+
+  const itemLabel = useMemo(() => (v: string) => findItemLabel(children, v), [children]);
+
+  return (
+    // `as="div"` + `relative`: with `SelectContent` no longer portaled
+    // (see its own comment), the options position themselves against this
+    // element. Headless UI's `Listbox` renders a fragment by default, which
+    // would leave `absolute` resolving against whatever ancestor happened
+    // to be positioned — usually the drawer, putting the dropdown in the
+    // wrong place entirely.
+    <Listbox
+      as="div"
+      className="relative"
+      value={currentValue ?? ""}
+      onChange={handleChange}
+      {...omitUndefined({ disabled })}
+    >
+      <SelectContext.Provider value={{ value: currentValue, itemLabel }}>
+        {children}
+      </SelectContext.Provider>
+    </Listbox>
+  );
+}
+
+// Unconsumed today (grepped across `admin/`) — kept for API parity. Radix's
+// `SelectGroup` had no visual treatment of its own beyond semantic
+// grouping; Headless UI's `Listbox` has no equivalent, so this stays a
+// plain wrapper rather than reaching for `Menu`'s `MenuSection` (a
+// different component family).
+export function SelectGroup({ children }: { children: ReactNode }) {
+  return <fieldset className="contents border-0 p-0 m-0 min-w-0">{children}</fieldset>;
+}
+
+export function SelectTrigger({
+  id,
+  className,
+  children,
+}: {
+  id?: string;
+  className?: string;
+  children: ReactNode;
+}) {
+  useSelectContext("SelectTrigger");
+  return (
+    <ListboxButton
+      id={id}
+      className={cn(
+        "select select-bordered flex w-full items-center justify-between font-sans text-prose",
+        className,
+      )}
+    >
+      {children}
+      <ChevronDown
+        size={14}
+        strokeWidth={1.5}
+        className="text-muted-foreground"
+        aria-hidden="true"
+      />
+    </ListboxButton>
+  );
+}
+
+export function SelectValue({ placeholder }: { placeholder?: string }) {
+  const { value, itemLabel } = useSelectContext("SelectValue");
+  if (value === undefined || value === "") {
+    return <span className="text-subtle-foreground">{placeholder}</span>;
+  }
+  return <>{itemLabel(value) ?? value}</>;
+}
+
+export function SelectContent({
+  className,
+  children,
+}: {
+  className?: string;
+  children: ReactNode;
+}) {
+  useSelectContext("SelectContent");
+  return (
+    <ListboxOptions
+      // `portal={false}` is a correctness fix, not a preference.
+      //
+      // Headless UI's `anchor` prop portals the options into
+      // `#headlessui-portal-root`, a top-level sibling of `<body>`. Inside a
+      // `vaul` drawer that is fatal: vaul's `Content` mounts a Radix
+      // `FocusScope` with `trapped: true`, a document-level `focusin`
+      // listener that force-refocuses back into the drawer the instant
+      // focus lands outside it. The portaled listbox is outside, so its
+      // enter transition stalls mid-flight and it never becomes usable.
+      //
+      // Measured on the live console rather than inferred — opening the
+      // registration status select inside its stacked drawer gave:
+      //
+      //   parentChain     [..., DIV#headlessui-portal-root, BODY]
+      //   insideAnyDrawer false
+      //   opacity         "0"
+      //   pointerEvents   "none"
+      //   rect            [122, 10]   (collapsed, not four options tall)
+      //
+      // — byte-for-byte the signature #274 recorded for a nested Dialog.
+      // #282 fixed that class for `Dialog` and never covered `Select`, so
+      // every select inside a drawer has been silently unusable since.
+      //
+      // Rendering inline keeps the options inside the drawer's own subtree,
+      // so the focus trap contains them instead of fighting them. The cost
+      // is losing `anchor`'s collision detection; `top-full` + `w-full`
+      // below reproduces the same "directly under the trigger, matching its
+      // width" placement, which is what every call site here wants anyway.
+      portal={false}
+      // No `transition`, and no `data-closed:*` classes. Headless UI's
+      // transition machinery holds `data-closed` until it observes the
+      // enter transition finish; inside a drawer it never does. Measured
+      // after the portal fix, 1.4s after opening: `data-closed` and
+      // `data-enter` both still present, `opacity: 0`, on an element that
+      // was otherwise correct (inside the drawer, `pointer-events: auto`,
+      // full 146px height, all four options present).
+      //
+      // That is the same failure mode twice now — #274's nested Dialog was
+      // also a stalled enter transition, not a mispositioned element. A
+      // 100ms fade on a select dropdown is not worth a second component
+      // that silently does not open, so it is gone rather than debugged.
+      className={cn(
+        "absolute top-full left-0 z-50 mt-1 max-h-80 w-full min-w-[8rem] overflow-y-auto rounded-md border border-edge bg-surface-2 p-1 shadow-[var(--shadow-popover)] focus:outline-none",
+        className,
+      )}
+    >
+      {children}
+    </ListboxOptions>
+  );
+}
+
+export function SelectItem({
+  value,
+  className,
+  children,
+}: {
+  value: string;
+  className?: string;
+  children: ReactNode;
+}) {
+  return (
+    <ListboxOption
+      value={value}
+      className={cn(
+        "relative flex cursor-pointer items-center rounded-sm py-1.5 pr-2 pl-7 text-body text-foreground outline-none",
+        "data-focus:bg-surface-3",
+        className,
+      )}
+    >
+      {({ selected }) => (
+        <>
+          <span className="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
+            {selected && <Check size={14} strokeWidth={1.5} aria-hidden="true" />}
+          </span>
+          {children}
+        </>
+      )}
+    </ListboxOption>
+  );
+}

package/src/components/primitives/separator.tsx

@@ -0,0 +1,49 @@
+import { forwardRef } from "react";
+import { cn } from "../../lib/cn";
+
+// D6: `@radix-ui/react-separator` is deleted outright — the Radix primitive
+// was already a near-trivial wrapper around a styled `<div>` with a
+// `role`/`aria-orientation` toggle for the decorative/semantic distinction,
+// so nothing behavioural is lost by hand-rolling that same toggle here.
+//
+// The non-decorative branch renders a real `<hr>` rather than a `<div
+// role="separator">` — found via Biome's own a11y lint, not assumed: an
+// ARIA `separator` role on a generic element is the *interactive* (focusable,
+// resizable-pane-divider) variant per WAI-ARIA, which requires `tabIndex`
+// and `aria-valuenow`; neither is meaningful for a plain visual rule. `<hr>`
+// carries the equivalent *static* separator semantics natively, with no
+// required ARIA attributes, and is what Biome's `useSemanticElements` rule
+// itself suggests.
+export interface SeparatorProps extends React.HTMLAttributes<HTMLDivElement> {
+  orientation?: "horizontal" | "vertical";
+  /** Matches Radix's own default: `true` renders a purely visual rule with
+   * no `separator` semantics exposed to assistive tech (`role="none"` on a
+   * `<div>`); `false` renders a native `<hr>` with `aria-orientation`. */
+  decorative?: boolean;
+}
+
+export const Separator = forwardRef<HTMLDivElement, SeparatorProps>(
+  ({ className, orientation = "horizontal", decorative = true, ...props }, ref) => {
+    const sharedClassName = cn(
+      "shrink-0 border-0 bg-edge",
+      orientation === "horizontal" ? "h-px w-full" : "h-full w-px",
+      className,
+    );
+    if (decorative) {
+      return <div ref={ref} role="none" className={sharedClassName} {...props} />;
+    }
+    // No consumer forwards a ref through the non-decorative branch today
+    // (grepped across `admin/`) — the cast is a documented, zero-risk
+    // approximation rather than widening `Separator`'s public ref type to
+    // `HTMLDivElement | HTMLHRElement` for a case nothing exercises.
+    return (
+      <hr
+        ref={ref as unknown as React.Ref<HTMLHRElement>}
+        aria-orientation={orientation}
+        className={sharedClassName}
+        {...props}
+      />
+    );
+  },
+);
+Separator.displayName = "Separator";

package/src/components/primitives/side-nav.tsx

@@ -0,0 +1,253 @@
+"use client";
+
+import { Disclosure, DisclosureButton, DisclosurePanel } from "@headlessui/react";
+import { ChevronDown } from "lucide-react";
+import type { ComponentType, ReactNode } from "react";
+import { cn } from "../../lib/cn";
+
+/**
+ * The console's information architecture (console-redesign.md §4), as data.
+ * `@vaam-apps/ui` owns the shape; `frontends/apps/admin/app/nav-groups.ts` owns the actual
+ * content (routes, groupings, icons) — this file never hardcodes a route.
+ */
+export interface NavItem {
+  label: string;
+  href: string;
+  /** Any lucide-react icon component. Typed structurally so this file
+   * doesn't need to depend on `lucide-react`'s own exported icon type name. */
+  icon: ComponentType<{ size?: number; className?: string; "aria-hidden"?: boolean | "true" }>;
+}
+
+export interface NavGroup {
+  /** Small-caps section header, e.g. "Messaging" (console-redesign.md §4). */
+  label: string;
+  items: NavItem[];
+}
+
+export interface SideNavProps {
+  /** Flat, ungrouped, always first — §4 ("Dashboard"). */
+  topItem: NavItem;
+  groups: NavGroup[];
+  /** De-emphasized footer utility rows (§1.1: "administrivia, not content"). */
+  footerItems: NavItem[];
+  /** Current pathname, for active-row highlighting. Plain string, not a
+   * `next/navigation` call — this package has no dependency on Next.js, so
+   * the caller (`frontends/apps/admin/app/console-shell.tsx`) resolves it via
+   * `usePathname()` and passes it down. */
+  currentPath: string;
+  /** App-specific account/sign-out markup (§4's footer "Signed in as
+   * <email> · Sign out" row) — rendered as-is, never built here, so this
+   * component stays free of any auth-specific knowledge. */
+  accountSlot?: ReactNode;
+  className?: string;
+}
+
+function isActive(href: string, currentPath: string): boolean {
+  if (href === "/") return currentPath === "/";
+  return currentPath === href || currentPath.startsWith(`${href}/`);
+}
+
+/**
+ * One nav row.
+ *
+ * **CSS-driven, not `useMediaQuery`-driven — found live, corrected after
+ * an earlier revision of this file used `@uidotdev/usehooks`' hook here
+ * and wrapped `SideNav` in `next/dynamic({ ssr: false })` to work around
+ * its SSR crash (see `console-shell.tsx`'s own history / this file's own
+ * git log for the full finding).** That fix traded a real cost — the
+ * sidebar never appeared in the server-rendered HTML, so every full page
+ * load painted an empty slab and popped the real nav in after hydration —
+ * for a problem the breakpoint switch itself never needed JS to solve:
+ * `variant="responsive"` below expresses "full label off-canvas and at
+ * `xl`, `sr-only` at the `lg` icon-rail band" purely with `lg:sr-only
+ * xl:not-sr-only`, no hook, no client-only state, no hydration boundary.
+ *
+ * - **`"responsive"`**: the label is visible off-canvas (`<1024px`, where
+ *   this row is never reached without the group around it already being
+ *   fully expanded) and at `≥1280px`, `sr-only` in the `1024–1279px` icon
+ *   rail band — a daisyUI `.tooltip`/`data-tip` (D5) carries the label
+ *   back on hover/focus there. Used for every row that can appear in the
+ *   *persistent* sidebar: `topItem`, `footerItems`, and each group's own
+ *   "always expanded" desktop rows (`GroupSection` below).
+ * - **`"always"`**: the label is always visible, no responsive classes at
+ *   all. Used only inside the off-canvas accordion tree, which is itself
+ *   gated to `<1024px` by its own `lg:hidden` wrapper — a per-row
+ *   breakpoint switch would be redundant there, since that whole tree
+ *   never renders at any width where a switch could matter.
+ */
+function NavLink({
+  item,
+  active,
+  variant,
+  dim = false,
+}: {
+  item: NavItem;
+  active: boolean;
+  variant: "responsive" | "always";
+  dim?: boolean;
+}) {
+  const Icon = item.icon;
+  const responsive = variant === "responsive";
+  return (
+    <a
+      href={item.href}
+      aria-current={active ? "page" : undefined}
+      data-tip={item.label}
+      className={cn(
+        "flex items-center gap-3 rounded-field px-3 py-2 transition-colors",
+        dim ? "text-caption" : "text-body",
+        responsive && "tooltip tooltip-right lg:justify-center lg:px-0 xl:justify-start xl:px-3",
+        active && !dim && "bg-base-300 font-medium text-foreground",
+        active && dim && "text-foreground",
+        !active && "text-muted-foreground hover:bg-base-300/60 hover:text-foreground",
+      )}
+    >
+      <Icon size={16} className="shrink-0" aria-hidden="true" />
+      <span className={cn(responsive && "lg:sr-only xl:not-sr-only")}>{item.label}</span>
+    </a>
+  );
+}
+
+/**
+ * One group's worth of rows, rendered as **two parallel trees**, one per
+ * §6.1 regime, each visible only at its own breakpoint via a plain
+ * `hidden`/`lg:hidden` toggle — not one tree whose *content* changes based
+ * on a JS-read viewport width. The two regimes genuinely need different
+ * DOM, not just different visibility, because the off-canvas tree is
+ * interactive (a collapsible `Disclosure`) and the persistent tree is not
+ * (every group is always fully expanded there, matching §1.1's LottieFiles
+ * reference, which shows no user-collapsible groups on desktop at all) —
+ * duplicating ~4 rows per group across two trees is a irrelevant DOM cost
+ * next to the alternative (a client-only nav that never appears in the
+ * first paint).
+ *
+ * - **Off-canvas** (`lg:hidden`, so effectively `<1024px` — both the phone
+ *   band and the tablet band §6.1 explicitly keeps behind the hamburger):
+ *   a Headless UI `Disclosure`, collapsed by default, expanded only if it
+ *   contains the current route — "roughly 6–8 tappable rows on open, not
+ *   18" (§4). `defaultOpen` is computed from `currentPath`, which is
+ *   available identically on the server and the client, so this renders
+ *   correctly on first paint with no hydration mismatch.
+ * - **Persistent** (`hidden lg:flex`, so `≥1024px`): always fully
+ *   expanded. The header/rail-divider split (small-caps text at `≥1280px`,
+ *   a hairline divider instead in the `1024–1279px` icon rail band) is the
+ *   same CSS-toggle technique `NavLink`'s own `"responsive"` variant uses.
+ */
+function GroupSection({ group, currentPath }: { group: NavGroup; currentPath: string }) {
+  const hasActiveItem = group.items.some((item) => isActive(item.href, currentPath));
+
+  return (
+    <>
+      <div className="lg:hidden">
+        <Disclosure defaultOpen={hasActiveItem}>
+          {({ open }) => (
+            <div className="flex flex-col gap-0.5">
+              <DisclosureButton className="flex items-center justify-between rounded-field px-3 py-1.5 text-left text-caption text-subtle-foreground uppercase tracking-wide hover:text-foreground">
+                {group.label}
+                <ChevronDown
+                  size={14}
+                  aria-hidden="true"
+                  className={cn("transition-transform", open && "rotate-180")}
+                />
+              </DisclosureButton>
+              <DisclosurePanel className="flex flex-col gap-0.5">
+                {group.items.map((item) => (
+                  <NavLink
+                    key={item.href}
+                    item={item}
+                    active={isActive(item.href, currentPath)}
+                    variant="always"
+                  />
+                ))}
+              </DisclosurePanel>
+            </div>
+          )}
+        </Disclosure>
+      </div>
+
+      <div className="hidden lg:flex lg:flex-col lg:gap-0.5">
+        <p className="hidden px-3 py-1.5 text-caption text-subtle-foreground uppercase tracking-wide xl:block">
+          {group.label}
+        </p>
+        <div className="mx-3 my-1 border-edge-subtle border-t xl:hidden" aria-hidden="true" />
+        {group.items.map((item) => (
+          <NavLink
+            key={item.href}
+            item={item}
+            active={isActive(item.href, currentPath)}
+            variant="responsive"
+          />
+        ))}
+      </div>
+    </>
+  );
+}
+
+/**
+ * The console's side navigation (console-redesign.md §4, §6.2). A pure
+ * structural/layout component — routing, session data, and the drawer's
+ * own off-canvas/persistent CSS split all live at the call site
+ * (`frontends/apps/admin/app/console-shell.tsx`, D7): this component only ever decides
+ * "flat top item → grouped middle → de-emphasized footer" composition and
+ * the label/icon-only/accordion treatment per breakpoint.
+ *
+ * Breakpoint behaviour (§6.1 is the authoritative table here — see that
+ * section's own reasoning for why it supersedes §4's looser "Tablet
+ * (768–1024px)" prose, which pre-dates that table and was never updated to
+ * match it) — entirely CSS-driven (`lg:`/`xl:` Tailwind variants), never a
+ * JS breakpoint read:
+ *   - `<1024px` (phone and tablet alike): off-canvas, full labels,
+ *     collapsible accordion groups.
+ *   - `1024–1279px`: persistent icon-only rail, tooltip on hover/focus.
+ *   - `≥1280px`: persistent full sidebar with labels.
+ *
+ * This means the whole nav — every row, every group, every breakpoint's
+ * shape — is present in the server-rendered HTML on first paint. No
+ * `next/dynamic({ ssr: false })`, no client-only mount flash. Verify that
+ * claim directly, not by trusting this comment: `curl` a page and grep the
+ * raw HTML for a nav item's label.
+ */
+export function SideNav({
+  topItem,
+  groups,
+  footerItems,
+  currentPath,
+  accountSlot,
+  className,
+}: SideNavProps) {
+  return (
+    <nav
+      aria-label="Primary"
+      className={cn("flex h-full flex-col gap-4 overflow-y-auto bg-base-200 py-4", className)}
+    >
+      <div className="flex flex-col gap-0.5 px-2">
+        <NavLink item={topItem} active={isActive(topItem.href, currentPath)} variant="responsive" />
+      </div>
+
+      <div className="flex flex-1 flex-col gap-4 px-2">
+        {groups.map((group) => (
+          <GroupSection key={group.label} group={group} currentPath={currentPath} />
+        ))}
+      </div>
+
+      <div className="flex flex-col gap-2 border-edge-subtle border-t px-2 pt-3">
+        <div className="flex flex-col gap-0.5">
+          {footerItems.map((item) => (
+            <NavLink
+              key={item.href}
+              item={item}
+              active={isActive(item.href, currentPath)}
+              variant="responsive"
+              dim
+            />
+          ))}
+        </div>
+        {/* Hidden in the icon rail band only (no room for the account
+            block at 64px); shown off-canvas and at the full-label desktop
+            width — same `lg:hidden xl:block` toggle technique as the rest
+            of this file, not a JS breakpoint check. */}
+        {accountSlot != null && <div className="px-3 lg:hidden xl:block">{accountSlot}</div>}
+      </div>
+    </nav>
+  );
+}

package/src/components/primitives/skeleton.tsx

@@ -0,0 +1,25 @@
+import type { HTMLAttributes } from "react";
+import { cn } from "../../lib/cn";
+
+/**
+ * Static — never shimmering (design doc §3.8 rule 2: "no skeleton
+ * shimmer"; §5.2: skeleton rows must match the real row height exactly so
+ * nothing shifts on load). House rule, not negotiable — see this repo's
+ * own AGENTS.md-lineage note; do not add animation here.
+ *
+ * Deliberately hand-rolled `<div>`, not daisyUI's own `.skeleton` class:
+ * read `daisyui/components/skeleton.css` directly before deciding this —
+ * daisyUI's `.skeleton` ships a `background-position` shimmer under
+ * `animation:1.8s ease-in-out infinite skeleton` (guarded only by
+ * `prefers-reduced-motion`, which is not the same thing as "off by
+ * default"), which is exactly the animation this house rule forbids.
+ * Radius stays `rounded-sm` (now `--radius-field`, 12px, via Phase 0's
+ * token rewrite) rather than moving to `--radius-box` — this component
+ * stands in for table cells and text lines across every screen, all
+ * field-scale content, not card-scale surfaces, so the token that already
+ * existed here is also the correct D8 tier, not a value left untouched by
+ * omission.
+ */
+export function Skeleton({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn("rounded-sm bg-surface-3", className)} {...props} />;
+}

package/src/components/primitives/spinner.tsx

@@ -0,0 +1,39 @@
+import { cn } from "../../lib/cn";
+
+export interface SpinnerProps {
+  size?: "xs" | "sm" | "md" | "lg";
+  /** Announced to assistive technology. `undefined` renders the spinner
+   * `aria-hidden`, which is correct when a visible sibling already says
+   * what is loading — two announcements of the same wait is worse than
+   * one. */
+  label?: string | undefined;
+  className?: string | undefined;
+}
+
+const SIZE_CLASS = {
+  xs: "loading-xs",
+  sm: "loading-sm",
+  md: "loading-md",
+  lg: "loading-lg",
+} as const;
+
+/**
+ * An indeterminate busy indicator, for a wait whose *shape* is unknown.
+ *
+ * Prefer `Skeleton` wherever the shape of what is arriving is known —
+ * a table, a card, a detail pane. A skeleton keeps the layout from
+ * jumping when content lands and tells the reader what to expect; a
+ * spinner tells them only that something is happening. This is for the
+ * rest: a button mid-submit, a poll with no placeholder to draw.
+ */
+export function Spinner({ size = "sm", label, className }: SpinnerProps) {
+  return (
+    <span
+      className={cn("loading loading-spinner", SIZE_CLASS[size], className)}
+      role={label === undefined ? undefined : "status"}
+      aria-hidden={label === undefined ? true : undefined}
+    >
+      {label !== undefined && <span className="sr-only">{label}</span>}
+    </span>
+  );
+}