@vaam-apps/ui 0.1.0

package/src/components/primitives/drawer.tsx

@@ -0,0 +1,326 @@
+"use client";
+
+import { X } from "lucide-react";
+import { forwardRef, type ReactNode } from "react";
+import { Drawer as DrawerPrimitive } from "vaul";
+import { cn } from "../../lib/cn";
+
+// vaul is standalone. Direction defaults to "right" — a side drawer reads
+// as the console's Sheet-equivalent (design doc T15: "extend, don't fork");
+// pass `direction="bottom"` for the mobile/narrow-viewport case.
+//
+// This generic composition (`Drawer`/`DrawerTrigger`/`DrawerClose`/
+// `DrawerContent`) is unchanged by console-redesign.md §6.4/D14 — it is
+// still the right tool for a one-off drawer with no quick-vs-more
+// distinction to encode (see the gallery's own "Open drawer" example).
+// `QuickDetailDrawer`/`MoreDetailDrawer` below are a *second*, self-
+// contained API for the specific §3 distinction; they do not replace this
+// one.
+export const Drawer = DrawerPrimitive.Root;
+export const DrawerTrigger = DrawerPrimitive.Trigger;
+export const DrawerClose = DrawerPrimitive.Close;
+export const DrawerPortal = DrawerPrimitive.Portal;
+
+export const DrawerOverlay = forwardRef<
+  React.ElementRef<typeof DrawerPrimitive.Overlay>,
+  React.ComponentPropsWithoutRef<typeof DrawerPrimitive.Overlay>
+>(({ className, ...props }, ref) => (
+  <DrawerPrimitive.Overlay
+    ref={ref}
+    className={cn("fixed inset-0 z-50 bg-black/50", className)}
+    {...props}
+  />
+));
+DrawerOverlay.displayName = "DrawerOverlay";
+
+export const DrawerContent = forwardRef<
+  React.ElementRef<typeof DrawerPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof DrawerPrimitive.Content>
+>(({ className, children, ...props }, ref) => (
+  <DrawerPortal>
+    <DrawerOverlay />
+    <DrawerPrimitive.Content
+      ref={ref}
+      className={cn(
+        "fixed inset-y-0 right-0 z-50 flex h-full w-full max-w-[560px] flex-col",
+        "border-edge border-l bg-surface-2 shadow-[var(--shadow-dialog)]",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </DrawerPrimitive.Content>
+  </DrawerPortal>
+));
+DrawerContent.displayName = "DrawerContent";
+
+/** Not previously exported — `vaul`'s `Content` renders Radix Dialog's
+ * `Content` underneath (`vaul/dist/index.js` imports `@radix-ui/react-
+ * dialog` directly and forwards its `Content`/`Title`/`Description`), so
+ * Radix's own "DialogContent requires a DialogTitle" dev warning applies
+ * here exactly as it does to `primitives/dialog.tsx`. `QuickDetailDrawer`/
+ * `MoreDetailDrawer` below always render one; exported separately too for
+ * any future one-off use of the generic `DrawerContent` above. */
+export const DrawerTitle = forwardRef<
+  React.ElementRef<typeof DrawerPrimitive.Title>,
+  React.ComponentPropsWithoutRef<typeof DrawerPrimitive.Title>
+>(({ className, ...props }, ref) => (
+  <DrawerPrimitive.Title
+    ref={ref}
+    className={cn("font-medium text-foreground text-title-sm", className)}
+    {...props}
+  />
+));
+DrawerTitle.displayName = "DrawerTitle";
+
+/** See `DrawerTitle` — same "not previously exported, Radix warns without
+ * one" reasoning, for `aria-describedby` instead of the accessible name. */
+export const DrawerDescription = forwardRef<
+  React.ElementRef<typeof DrawerPrimitive.Description>,
+  React.ComponentPropsWithoutRef<typeof DrawerPrimitive.Description>
+>(({ className, ...props }, ref) => (
+  <DrawerPrimitive.Description
+    ref={ref}
+    className={cn("text-muted-foreground text-prose", className)}
+    {...props}
+  />
+));
+DrawerDescription.displayName = "DrawerDescription";
+
+// ---------------------------------------------------------------------
+// QuickDetailDrawer / MoreDetailDrawer (console-redesign.md §3, D14, §5)
+// ---------------------------------------------------------------------
+//
+// The design doc's own §6.4 sketch of this file was explicitly flagged as
+// unverified ("the mechanism is now known and worth checking before this
+// sketch is trusted verbatim") for two independent reasons, both checked
+// directly against `vaul@1.1.2`'s compiled source
+// (`node_modules/vaul/dist/index.js`) before writing this, not assumed:
+//
+// 1. **The `useMediaQuery` call the sketch used is gone (D12).** No JS
+//    viewport read of any kind happens in this file — every breakpoint
+//    switch below is a plain Tailwind `md:` variant, so both variants
+//    render identically on the server and on the client's first paint.
+//
+// 2. **A single `vaul` `Drawer.Root` cannot itself be "bottom on phone,
+//    right on desktop" — its `direction` prop is not a CSS concern.** It
+//    drives real per-instance state: which axis (`translate3d(0,y,0)` vs
+//    `(x,0,0)`) the built-in open/close keyframes and the live drag-follow
+//    math use (`isVertical(direction)`, `getTranslate(el, direction)`,
+//    throughout `dist/index.js`). The sketch never set `direction` at all
+//    (it left every caller to supply it on a separately-rendered `<Drawer>`
+//    Root, which — combined with `direction`'s own default of `"bottom"` —
+//    means the sketch's "more details" `Content` would in practice always
+//    have inherited `"bottom"` regardless of viewport anyway). Rather than
+//    read the viewport to pick a direction (banned, and also the same
+//    hydration-mismatch shape D12 already fixed once — a deep-linked
+//    `?panel=<id>` drawer can be `open` on the very first server render,
+//    per D14, so the first paint has to be right, not just eventually
+//    correct after an effect), both drawers below **fix `direction` to
+//    `"bottom"` unconditionally** and let plain `md:` classes handle
+//    *position* — matching this file's own established, precedented
+//    pattern for a responsive split that can't be one reactive value
+//    (`side-nav.tsx`'s `GroupSection`: "two parallel trees... not one tree
+//    whose content changes based on a JS-read viewport width").
+//
+//    The one real, accepted cost of fixing `direction`: `vaul`'s own
+//    open/close animation (`slideFromBottom`/`slideToBottom`, a vertical
+//    `translate3d`) plays at every breakpoint, including the `md:` right-
+//    panel position — so the panel's *entrance motion* is vertical even
+//    though its *resting position* is a right-hand edge. This was
+//    deliberately not "fixed" by layering a second, horizontal CSS
+//    `transition` on top keyed off `data-[state=]`: `vaul`'s animation is
+//    a real `@keyframes` `animation`, which (unlike a plain `transition`)
+//    correctly plays on a freshly-inserted node — Radix's `Content` isn't
+//    in the DOM at all until `open`, so a competing `transition`-based
+//    replacement would very likely not animate on *open* at all (no prior
+//    DOM node to transition *from*) while still fighting the real
+//    animation for the `transform` property. Keeping `vaul`'s own,
+//    already-correct mechanism and accepting a vertical entrance for the
+//    desktop panel is the smaller, more honest compromise, and it costs no
+//    extra CSS (constraint 7). If this reads as wrong once seen live,
+//    revisit by disabling it explicitly (`data-vaul-animate="false"` is
+//    force-overridable via a prop — `Content`'s `...rest` spreads *after*
+//    vaul's own default in `dist/index.js`) and shipping a real
+//    `@keyframes`-based replacement, not a `transition`.
+//
+//    Fixing `direction` also fixes the *drag* gesture to the vertical
+//    axis everywhere. Left alone, that would make a click-drag inside the
+//    desktop panel (e.g. selecting text) register as a vertical swipe
+//    attempt. Closed with `handleOnly` on the `Root` (drag can only start
+//    from a `Drawer.Handle`) plus rendering that handle only below `md:` —
+//    so desktop has no drag surface at all (pointer/click/Escape/overlay
+//    close it instead), and phone keeps a real, correctly-axised drag
+//    handle, which is also what §3's own mobile paragraph asks for ("...
+//    with a drag handle").
+//
+// Both variants are otherwise identical in mechanism and differ only in
+// the two things §3/D14 make load-bearing: `dimmed` (renders an
+// `Overlay` and sets `vaul`'s own `modal` prop — verified live in
+// `dist/index.js` that `modal` is what actually gates both the
+// background `pointer-events`/scroll-lock behaviour *and*, independently,
+// whether an `Overlay` should render at all; Radix's own focus trap and
+// `aria-modal="true"` are unconditional either way — `vaul` never forwards
+// its `modal` prop down to `@radix-ui/react-dialog`'s `Root`, which keeps
+// its own default of `true` regardless. So "quick details" is visually and
+// interactively lighter — no dim, background stays scrollable/clickable —
+// but is exactly as keyboard-trapped and exactly as announced to a screen
+// reader as "more details" is; that's a real, verified limitation of
+// `vaul@1.1.2`, not a gap left open on purpose) and `contentClassName`
+// (width/inset/radius/border, per D14's own two size ranges).
+interface DetailDrawerProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** Rendered as the drawer's accessible name (`Drawer.Title`) — required,
+   * not optional, because both variants always render one and Radix warns
+   * loudly in dev without it. */
+  title: ReactNode;
+  /** Rendered as the drawer's accessible description (`Drawer.Description`).
+   * Optional for the *caller* — when omitted, a screen-reader-only
+   * fallback is still rendered so `aria-describedby` is always wired,
+   * matching `primitives/dialog.tsx`'s own precedent of never shipping a
+   * `Content` with no description at all. */
+  description?: ReactNode;
+  /** The scrollable body — a summary of fields, an edit form, whatever the
+   * calling screen owns. This file has no opinion on it. */
+  children: ReactNode;
+  /** Optional sticky action row (§1.5's Polar reference: "a fixed bottom
+   * action row... stays visible without the form needing to scroll"). */
+  footer?: ReactNode;
+  className?: string;
+}
+
+function DetailDrawerContent({
+  open,
+  onOpenChange,
+  title,
+  description,
+  children,
+  footer,
+  className,
+  dimmed,
+  contentClassName,
+}: DetailDrawerProps & { dimmed: boolean; contentClassName: string }) {
+  return (
+    <DrawerPrimitive.Root
+      open={open}
+      onOpenChange={onOpenChange}
+      direction="bottom"
+      modal={dimmed}
+      dismissible
+      handleOnly
+      // vaul defaults this to `false` (`onOpenAutoFocus` is pre-vented
+      // unless the caller opts in) — verified in `dist/index.js`'s `Root`
+      // default parameters. Without it, opening either drawer would leave
+      // keyboard focus sitting on whatever triggered it instead of moving
+      // into the panel, which is a real, checkable regression from plain
+      // Radix `Dialog` behaviour (its own default *does* auto-focus
+      // `Content`) — set explicitly so focus genuinely lands inside the
+      // drawer the moment it opens, not just gets trapped there once the
+      // user starts tabbing.
+      autoFocus
+    >
+      <DrawerPrimitive.Portal>
+        {dimmed && <DrawerPrimitive.Overlay className="fixed inset-0 z-50 bg-black/50" />}
+        <DrawerPrimitive.Content
+          className={cn(
+            "fixed z-50 flex flex-col bg-surface-2 shadow-[var(--shadow-dialog)] outline-none",
+            // Phone: bottom sheet.
+            "inset-x-0 bottom-0 rounded-t-box border-edge border-t",
+            // `md`+: right-hand panel — every sheet-only property above is
+            // reset explicitly (inset, rounding, border side, max-height),
+            // not just overridden by a wider max-width, per this file's
+            // own D12-correction note above.
+            "md:inset-x-auto md:inset-y-0 md:right-0 md:h-full md:max-h-none",
+            "md:w-full md:rounded-t-none md:rounded-l-box md:border-t-0 md:border-l",
+            contentClassName,
+            className,
+          )}
+        >
+          {/* Drag surface (D14's mobile "with a drag handle"), phone only —
+              `handleOnly` on Root means dragging is only possible starting
+              from this element, and it's hidden at `md:`, so desktop has
+              no drag surface at all (see this file's own header comment
+              for why: `direction` is fixed to "bottom", so a desktop drag
+              would otherwise compute against the wrong axis).
+              **`!` (Tailwind v4 important) is load-bearing here, not
+              decorative — found live, not assumed:** `vaul` injects
+              `[data-vaul-handle]{display:block; ...}` into a `<style>` tag
+              it appends to `<head>` itself (`dist/index.js`'s own
+              `__insertCSS`), at the same specificity as a plain `md:hidden`
+              utility and *after* Tailwind's build-time stylesheet in
+              cascade order — so a bare `md:hidden` lost the tie and the
+              handle stayed visible at desktop width, confirmed by
+              inspecting `getComputedStyle(...).display` in a real browser
+              at 1280px before this fix, and confirmed gone after it. */}
+          <DrawerPrimitive.Handle className="mt-2 shrink-0 bg-edge-strong md:hidden!" />
+
+          <div className="flex items-start justify-between gap-3 border-edge border-b px-5 py-4">
+            <div className="min-w-0">
+              <DrawerTitle className="truncate">{title}</DrawerTitle>
+              <DrawerDescription className={description == null ? "sr-only" : "mt-1"}>
+                {description ?? "Details panel."}
+              </DrawerDescription>
+            </div>
+            <DrawerPrimitive.Close
+              aria-label="Close"
+              className="shrink-0 text-subtle-foreground hover:text-foreground"
+            >
+              <X size={16} strokeWidth={1.5} />
+            </DrawerPrimitive.Close>
+          </div>
+
+          <div className="flex-1 overflow-y-auto px-5 py-4">{children}</div>
+
+          {footer != null && (
+            <div className="flex shrink-0 items-center justify-end gap-2 border-edge border-t px-5 py-4">
+              {footer}
+            </div>
+          )}
+        </DrawerPrimitive.Content>
+      </DrawerPrimitive.Portal>
+    </DrawerPrimitive.Root>
+  );
+}
+
+/**
+ * **Quick details** (§3, D14) — a peek at one row's state without leaving
+ * the list. Narrow (`420–480px` at `md`+), undimmed (background stays
+ * legible and, per `vaul`'s own `modal={false}` behaviour verified above,
+ * scrollable/clickable — matching the Mercury reference, §1.4), no route
+ * ownership: the caller owns `open`/`onOpenChange` from local state (e.g.
+ * "which row id is selected"), and losing it on refresh is expected and
+ * fine (reopening is one click on the same row).
+ *
+ * Not a `Dialog`, and not for anything destructive — §1.7/§3 reserve that
+ * for the centered `Dialog` primitive. This is a read-mostly summary with
+ * 1–2 actions, e.g. a "View full details" link that upgrades to
+ * `MoreDetailDrawer`.
+ */
+export function QuickDetailDrawer(props: DetailDrawerProps) {
+  return (
+    <DetailDrawerContent
+      {...props}
+      dimmed={false}
+      contentClassName="max-h-[70vh] md:max-w-[440px]"
+    />
+  );
+}
+
+/**
+ * **More details** (§3, D14) — the full record: every field, an edit
+ * form, destructive actions, short nested history. Wide (`640–720px` at
+ * `md`+), dimmed (modal-weight, matching the Polar reference, §1.5). The
+ * *caller* is expected to own a shallow `?panel=<recordId>` route so this
+ * survives refresh and is linkable (D14) — this component only owns the
+ * visual/behavioural weight, never routing; pass `open` derived from that
+ * query param and `onOpenChange` wired to update it.
+ *
+ * A destructive-confirmation step opened *from inside* this drawer (e.g.
+ * webhook-secret rotation) stays a nested `Dialog` (§3's own footnote) —
+ * that dialog needs a z-index at or above this drawer's `z-50`; setting
+ * that is `primitives/dialog.tsx`'s job (§8 risk list), not this file's.
+ */
+export function MoreDetailDrawer(props: DetailDrawerProps) {
+  return <DetailDrawerContent {...props} dimmed contentClassName="max-h-[92vh] md:max-w-[680px]" />;
+}

package/src/components/primitives/dropdown-menu.tsx

@@ -0,0 +1,128 @@
+"use client";
+
+import {
+  Menu,
+  MenuButton,
+  MenuItem,
+  MenuItems,
+  MenuSection,
+  MenuSeparator,
+} from "@headlessui/react";
+import { Check } from "lucide-react";
+import type { ComponentPropsWithoutRef } from "react";
+import { cn } from "../../lib/cn";
+import { omitUndefined } from "../../lib/omit-undefined";
+
+// D3: Radix `DropdownMenu` → Headless UI `Menu`/`MenuButton`/`MenuItems`/`MenuItem`.
+export const DropdownMenu = Menu;
+
+// `MenuButton` is natively polymorphic (`as`), replacing Radix's `asChild`
+// pattern (D4's same call, applied to a trigger rather than `Button`
+// itself): `<DropdownMenuTrigger as={Button} variant="secondary">…`.
+export const DropdownMenuTrigger = MenuButton;
+
+// `DropdownMenuGroup`/`DropdownMenuCheckboxItem` have zero call sites in
+// this codebase today (grepped across `admin/` and `packages/ui`) — kept
+// for API parity rather than dropped silently, mapped onto Headless UI's
+// closest equivalents.
+export const DropdownMenuGroup = MenuSection;
+
+export function DropdownMenuSeparator({
+  className,
+  ...props
+}: ComponentPropsWithoutRef<typeof MenuSeparator>) {
+  return <MenuSeparator className={cn("my-1 h-px bg-edge", className)} {...props} />;
+}
+
+export function DropdownMenuContent({
+  className,
+  ...props
+}: ComponentPropsWithoutRef<typeof MenuItems>) {
+  return (
+    <MenuItems
+      anchor="bottom start"
+      transition
+      className={cn(
+        "z-50 min-w-[180px] rounded-md border border-edge bg-surface-2 p-1 shadow-[var(--shadow-popover)] [--anchor-gap:4px] focus:outline-none",
+        "origin-top transition duration-100 ease-out data-closed:scale-95 data-closed:opacity-0",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function DropdownMenuItem({
+  className,
+  ...props
+}: Omit<ComponentPropsWithoutRef<"button">, "type">) {
+  return (
+    <MenuItem
+      as="button"
+      type="button"
+      className={cn(
+        "flex w-full cursor-pointer items-center gap-2 rounded-sm px-2 py-1.5 text-left text-body text-foreground outline-none",
+        "data-focus:bg-surface-3",
+        "data-disabled:pointer-events-none data-disabled:opacity-50",
+        className,
+      )}
+      {...omitUndefined(props)}
+    />
+  );
+}
+
+/** Unconsumed today (see module doc above) — caller controls `checked`
+ * itself, since Headless UI's `Menu` has no built-in checkbox-item state
+ * the way Radix's `DropdownMenuCheckboxItem` did. */
+export function DropdownMenuCheckboxItem({
+  className,
+  checked = false,
+  children,
+  ...props
+}: Omit<ComponentPropsWithoutRef<"button">, "type"> & { checked?: boolean }) {
+  return (
+    <MenuItem
+      as="button"
+      type="button"
+      role="menuitemcheckbox"
+      aria-checked={checked}
+      className={cn(
+        "flex w-full cursor-pointer items-center gap-2 rounded-sm px-2 py-1.5 text-left text-body text-foreground outline-none",
+        "data-focus:bg-surface-3",
+        className,
+      )}
+      {...omitUndefined(props)}
+    >
+      <span className="flex h-3.5 w-3.5 items-center justify-center">
+        {checked && <Check size={14} strokeWidth={1.5} aria-hidden="true" />}
+      </span>
+      {children}
+    </MenuItem>
+  );
+}
+
+/**
+ * **Found live, not assumed**: Headless UI's own `MenuHeading` throws the
+ * identical "not inside a relevant parent" error `label.tsx`'s own module
+ * doc already found for the standalone `Label` — `MenuHeading` needs a
+ * `MenuSection` ancestor to supply that context (`MenuSection`'s own
+ * implementation calls `useLabels()` to *create* the provider; `MenuHeading`
+ * calls `useLabelContext()` to *consume* it), and every call site here
+ * (matching the original Radix `DropdownMenuLabel`'s own shape) renders a
+ * standalone label with no surrounding group. Radix's own `Label` was a
+ * plain, non-interactive `<div>` with no roving-focus/ARIA-grouping
+ * behaviour beyond being read as ordinary text inside the menu's
+ * accessible tree — so a plain `<div>` here loses nothing real and avoids
+ * a dependency this element doesn't actually need. Reproduced live: a real
+ * "Uncaught Error: You used a <Label /> component, but it is not inside a
+ * relevant parent" client-side exception, thrown the instant the gallery's
+ * demo menu opened, before this fix.
+ */
+export function DropdownMenuLabel({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn("px-2 py-1.5 text-micro text-muted-foreground tracking-[0.03em]", className)}
+      {...props}
+    />
+  );
+}

package/src/components/primitives/form-field.tsx

@@ -0,0 +1,136 @@
+import type { ReactNode } from "react";
+import { cn } from "../../lib/cn";
+import { Label } from "./label";
+
+/**
+ * A labelled form control with an optional validation error beneath it.
+ *
+ * This replaces the console's two most-duplicated class strings after the
+ * table-column ones:
+ *
+ * - `"flex flex-col gap-1.5"` — **80 occurrences**, every one of them
+ *   wrapping exactly `<Label htmlFor>` + one control (+ sometimes an
+ *   error paragraph).
+ * - `"text-caption text-state-danger-fg"` — **35 occurrences**, almost all
+ *   of them that error paragraph.
+ *
+ * The shape was identical at every site, checked before this component was
+ * designed rather than assumed:
+ *
+ * ```tsx
+ * <div className="flex flex-col gap-1.5">
+ *   <Label htmlFor="record-msisdn">MSISDN</Label>
+ *   <Input id="record-msisdn" {...form.register("msisdn")} />
+ *   <p className="text-caption text-state-danger-fg">{errors.msisdn.message}</p>
+ * </div>
+ * ```
+ *
+ * becomes
+ *
+ * ```tsx
+ * <FormField label="MSISDN" htmlFor="record-msisdn" error={errors.msisdn?.message}>
+ *   <Input id="record-msisdn" {...form.register("msisdn")} />
+ * </FormField>
+ * ```
+ *
+ * **Why a semantic component and not a generic `<Stack gap="1.5">`.** A
+ * layout primitive parameterised by its own CSS is a `<div>` with extra
+ * steps — it moves the class from the call site into a prop at the call
+ * site, which is not factorisation. `FormField` instead names the *thing*
+ * (a labelled control with an error slot), so the spacing, the label
+ * treatment and the error treatment are one decision in one place, and a
+ * caller cannot get the error styling wrong by writing the `<p>` itself.
+ *
+ * `htmlFor` is required rather than optional. Several of the 80 sites had
+ * a `<Label>` with no `htmlFor` at all, which silently breaks
+ * click-to-focus and screen-reader association; making it required turns
+ * that into a compile error instead of an accessibility bug nobody
+ * notices.
+ */
+export interface FormFieldProps {
+  label: ReactNode;
+  /** The `id` of the control this labels. Required — see the module doc. */
+  htmlFor: string;
+  /** Validation message. `undefined` renders no error element at all. */
+  error?: string | undefined;
+  /** Help text rendered between the label and the control. */
+  hint?: ReactNode;
+  /**
+   * `"field"` (default) labels a single form control by `htmlFor`.
+   *
+   * `"group"` is for a `RadioGroup`/`ChipSelect`, where the control is a
+   * `role="radiogroup"`/`role="group"` wrapper rather than a labelable
+   * element. HTML's `for` only associates with labelable form controls, so
+   * pointing it at a `<div>` is invalid *and* dangling — which is exactly
+   * what the enum migration shipped: four `<Label for="…">` with no
+   * element carrying that id anywhere, found in review.
+   *
+   * In group mode no `for` is emitted; the label carries
+   * [`groupLabelId(htmlFor)`] instead, and the caller wires the group with
+   * `aria-labelledby={groupLabelId(htmlFor)}`. Both sides derive the id
+   * from the same function so they cannot drift.
+   */
+  control?: "field" | "group";
+  children: ReactNode;
+  className?: string | undefined;
+}
+
+/** The id a `control="group"` FormField puts on its label, and the value a
+ * grouped control must pass as `aria-labelledby`. One function so the two
+ * sides cannot disagree. */
+export function groupLabelId(htmlFor: string): string {
+  return `${htmlFor}-label`;
+}
+
+export function FormField({
+  label,
+  htmlFor,
+  error,
+  hint,
+  children,
+  className,
+  control = "field",
+}: FormFieldProps) {
+  return (
+    <div className={cn("flex flex-col gap-1.5", className)}>
+      {control === "group" ? (
+        // Not a <Label>: with no `for` it would associate with nothing, and
+        // a label wrapping no control is worse than a plain element with an
+        // id the group points back at.
+        <span id={groupLabelId(htmlFor)} className="font-medium text-body text-foreground">
+          {label}
+        </span>
+      ) : (
+        <Label htmlFor={htmlFor}>{label}</Label>
+      )}
+      {hint !== undefined && <p className="text-caption text-muted-foreground">{hint}</p>}
+      {children}
+      {error !== undefined && <FieldError>{error}</FieldError>}
+    </div>
+  );
+}
+
+/**
+ * A validation message.
+ *
+ * Exported separately because a handful of the 35 sites are not inside a
+ * `FormField` — a form-level error above the submit button, or an error
+ * attached to a control group rather than one input. Those should still
+ * use the same treatment rather than re-inlining the class.
+ *
+ * `role="alert"` so the message is announced when it appears, which none
+ * of the 35 hand-rolled `<p>` elements did.
+ */
+export function FieldError({
+  children,
+  className,
+}: {
+  children: ReactNode;
+  className?: string | undefined;
+}) {
+  return (
+    <p role="alert" className={cn("text-caption text-state-danger-fg", className)}>
+      {children}
+    </p>
+  );
+}