@eifi1/ui-kit 0.9.0 → 0.11.0

package/src/components/description-list.tsx

@@ -3,16 +3,62 @@ import type { ComponentPropsWithoutRef, CSSProperties, ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { FieldHint } from "./ui";
 
-export type DescriptionListLayout = "rows" | "cards";
-export type DescriptionListDensity = "comfortable" | "compact";
+export type DescriptionListLayout = "rows" | "cards" | "stacked";
+export type DescriptionListDensity = "comfortable" | "compact" | "tight";
+/** How many columns a `stacked` or `cards` list may use. */
+export type DescriptionListColumns = 1 | 2 | 3 | 4 | 5 | 6;
 
 interface ListContextValue {
   layout: DescriptionListLayout;
   numeric: boolean;
+  prose: boolean;
   density: DescriptionListDensity;
+  columns: DescriptionListColumns;
 }
 
-const ListContext = createContext<ListContextValue>({ layout: "rows", numeric: false, density: "comfortable" });
+const ListContext = createContext<ListContextValue>({
+  layout: "rows",
+  numeric: false,
+  prose: false,
+  density: "comfortable",
+  columns: 2,
+});
+
+/**
+ * `stacked` columns, by the width of the LIST (a container query on a wrapper — the
+ * `<dl>` is the grid and cannot query itself). One column on a phone-narrow pane, two
+ * from 20rem, then one more column each time every column would still get ~12rem.
+ * The same shape as kastlan's DetailGrid (1 → 2 at `sm` → n at `md`), measured on the
+ * pane rather than the viewport, so the four preview dialogs and a full-width detail
+ * page can share one list. Literal strings, because Tailwind only emits what it reads.
+ */
+const STACKED_COLS: Record<DescriptionListColumns, string> = {
+  1: "grid-cols-1",
+  2: "grid-cols-1 @xs:grid-cols-2",
+  3: "grid-cols-1 @xs:grid-cols-2 @xl:grid-cols-3",
+  4: "grid-cols-1 @xs:grid-cols-2 @xl:grid-cols-3 @3xl:grid-cols-4",
+  5: "grid-cols-1 @xs:grid-cols-2 @xl:grid-cols-3 @3xl:grid-cols-4 @5xl:grid-cols-5",
+  6: "grid-cols-1 @xs:grid-cols-2 @xl:grid-cols-3 @3xl:grid-cols-4 @5xl:grid-cols-5 @6xl:grid-cols-6",
+};
+
+/** An item's span at each of those thresholds, never more columns than exist there —
+ *  so a span can never open an implicit column and push the grid past its pane. */
+const STACKED_SPAN: Record<DescriptionListColumns, string> = {
+  1: "",
+  2: "@xs:col-span-2",
+  3: "@xs:col-span-2 @xl:col-span-3",
+  4: "@xs:col-span-2 @xl:col-span-3 @3xl:col-span-4",
+  5: "@xs:col-span-2 @xl:col-span-3 @3xl:col-span-4 @5xl:col-span-5",
+  6: "@xs:col-span-2 @xl:col-span-3 @3xl:col-span-4 @5xl:col-span-5 @6xl:col-span-6",
+};
+
+/** The cards grid's gap per density, as a class and as the length the column formula
+ *  subtracts — one table so the two cannot disagree. */
+const CARD_GAP: Record<DescriptionListDensity, { cls: string; len: string }> = {
+  comfortable: { cls: "gap-3", len: "0.75rem" },
+  compact: { cls: "gap-2", len: "0.5rem" },
+  tight: { cls: "gap-1", len: "0.25rem" },
+};
 
 export interface DescriptionListProps extends ComponentPropsWithoutRef<"dl"> {
   /**
@@ -21,6 +67,10 @@ export interface DescriptionListProps extends ComponentPropsWithoutRef<"dl"> {
    * beside a sidebar stacks where it is actually cramped, not where the viewport is.
    * `cards`: a grid of small bordered cards, term above body — keksdose's overview
    * figures, lenkbank's account facts.
+   * `stacked` (0.10.0): a borderless grid, term ABOVE detail, {@link columns} wide —
+   * kastlan's DetailField/DetailGrid and the label-over-value grids of its lease,
+   * invoice, contact and unit preview dialogs. Items can {@link DescriptionItemProps.span}
+   * several columns (a notes field across the whole row).
    */
   layout?: DescriptionListLayout;
   /** Every detail is a figure: tabular digits, end-aligned. A `numeric` list of
@@ -28,10 +78,31 @@ export interface DescriptionListProps extends ComponentPropsWithoutRef<"dl"> {
    *  term would double the list's height to gain no width. Per item: see
    *  {@link DescriptionItemProps.numeric}. */
   numeric?: boolean;
-  /** `compact` tightens the rhythm for a dense side panel. */
+  /** `compact` tightens the rhythm for a dense side panel. `tight` (0.10.0) is 11px
+   *  type on a 2px rhythm with no rules between rows — keksdose's admin metrics
+   *  breakdowns (metrics-panel's label-left, count-right lists), which are read as a
+   *  block of small print, not scanned row by row. */
   density?: DescriptionListDensity;
   /** `cards` only: the narrowest a card may get before the grid drops a column. */
   minCardWidth?: string;
+  /**
+   * `stacked`: how many columns the grid grows to on a wide pane (default 2), see
+   * {@link STACKED_COLS}. `cards` (0.10.0): the MOST cards per row; the grid still
+   * drops columns below {@link minCardWidth}. keksdose's category editor faked "two
+   * side by side" with `minCardWidth="calc(50% - 0.5rem)"`, which is `columns={2}
+   * minCardWidth="0"` now, without knowing the gap. Ignored by `rows`.
+   */
+  columns?: DescriptionListColumns;
+  /**
+   * The details are sentences, not values: regular weight in the secondary ink.
+   * lenkbank's control explainer cards each carry a paragraph, and at the card's
+   * `font-medium` primary ink a grid of paragraphs reads as a wall of headings — it
+   * spelled `font-normal text-slate-700` into every item. A flag rather than a new
+   * default because every other card list in the apps holds values (dates, figures,
+   * counts) that are not flagged `numeric` and ARE meant to stand out; lightening them
+   * all would not be an improvement. Per item: {@link DescriptionItemProps.prose}.
+   */
+  prose?: boolean;
 }
 
 /**
@@ -54,27 +125,66 @@ export interface DescriptionListProps extends ComponentPropsWithoutRef<"dl"> {
 export function DescriptionList({
   layout = "rows",
   numeric = false,
+  prose = false,
   density = "comfortable",
   minCardWidth = "10rem",
+  columns,
   className,
   style,
   ...rest
 }: DescriptionListProps) {
   const cards = layout === "cards";
+  const stacked = layout === "stacked";
+  const gap = CARD_GAP[density];
+  // Cards: auto-fill at `minCardWidth`, and with `columns` a floor on the track of one
+  // n-th of the row (less the gaps) — so auto-fill can never fit more than n. The
+  // outer `min(100%, …)` keeps a single card from overflowing a pane narrower than
+  // its minimum.
+  const track =
+    columns !== undefined
+      ? `max(${minCardWidth}, (100% - ${columns - 1} * ${gap.len}) / ${columns})`
+      : minCardWidth;
   const grid: CSSProperties | undefined = cards
-    ? { gridTemplateColumns: `repeat(auto-fill, minmax(min(100%, ${minCardWidth}), 1fr))` }
+    ? { gridTemplateColumns: `repeat(auto-fill, minmax(min(100%, ${track}), 1fr))` }
     : undefined;
+  const ctx: ListContextValue = { layout, numeric, prose, density, columns: columns ?? 2 };
+  const text = density === "tight" ? "text-[11px] leading-4" : density === "compact" ? "text-xs" : "text-sm";
+
+  if (stacked) {
+    return (
+      <ListContext.Provider value={ctx}>
+        {/* The container the columns are measured on — see STACKED_COLS. */}
+        <div className="@container">
+          <dl
+            {...rest}
+            data-layout={layout}
+            style={style}
+            className={cn(
+              "grid",
+              STACKED_COLS[ctx.columns],
+              density === "tight" ? "gap-x-3 gap-y-1" : density === "compact" ? "gap-x-4 gap-y-2" : "gap-x-6 gap-y-4",
+              text,
+              className,
+            )}
+          />
+        </div>
+      </ListContext.Provider>
+    );
+  }
+
   return (
-    <ListContext.Provider value={{ layout, numeric, density }}>
+    <ListContext.Provider value={ctx}>
       <dl
         {...rest}
         data-layout={layout}
         style={grid ? { ...grid, ...style } : style}
         className={cn(
           cards
-            ? cn("grid", density === "compact" ? "gap-2" : "gap-3")
-            : "@container divide-y divide-[var(--border)]",
-          density === "compact" ? "text-xs" : "text-sm",
+            ? cn("grid", gap.cls)
+            : // Tight rows carry no rules: at a 2px rhythm a line under every row
+              // turns a block of small print into a ruled table.
+              cn("@container", density !== "tight" && "divide-y divide-[var(--border)]"),
+          text,
           className,
         )}
       />
@@ -95,10 +205,28 @@ export interface DescriptionItemProps extends Omit<ComponentPropsWithoutRef<"div
   numeric?: boolean;
   /** Classes for the `<dd>`. */
   detailClassName?: string;
+  /** This detail is prose (see {@link DescriptionListProps.prose}); overrides the
+   *  list's setting either way. */
+  prose?: boolean;
+  /**
+   * `stacked`: how many columns this item spans, clamped to the list's `columns` and
+   * to however many the pane has room for; `"full"` is the whole row. kastlan's
+   * DetailField `span={2}` for notes and descriptions. `cards`: only `"full"` applies,
+   * because a card grid's column count is not known to CSS ahead of layout.
+   */
+  span?: number | "full";
 }
 
-const ROW_PAD: Record<DescriptionListDensity, string> = { comfortable: "py-2.5", compact: "py-1.5" };
-const CARD_PAD: Record<DescriptionListDensity, string> = { comfortable: "px-3 py-2.5", compact: "px-2.5 py-1.5" };
+const ROW_PAD: Record<DescriptionListDensity, string> = {
+  comfortable: "py-2.5",
+  compact: "py-1.5",
+  tight: "py-px",
+};
+const CARD_PAD: Record<DescriptionListDensity, string> = {
+  comfortable: "px-3 py-2.5",
+  compact: "px-2.5 py-1.5",
+  tight: "px-2 py-1",
+};
 
 /** One term and its detail inside a {@link DescriptionList}. */
 export function DescriptionItem({
@@ -106,19 +234,32 @@ export function DescriptionItem({
   children,
   hint,
   numeric: numericProp,
+  prose: proseProp,
+  span,
   detailClassName,
   className,
   ...rest
 }: DescriptionItemProps) {
-  const { layout, numeric: listNumeric, density } = useContext(ListContext);
+  const { layout, numeric: listNumeric, prose: listProse, density, columns } = useContext(ListContext);
   const numeric = numericProp ?? listNumeric;
+  const prose = proseProp ?? listProse;
   const cards = layout === "cards";
+  const stacked = layout === "stacked";
+  const spanClass =
+    span === "full"
+      ? "col-span-full"
+      : stacked && span !== undefined && span > 1
+        ? STACKED_SPAN[Math.min(Math.floor(span), columns) as DescriptionListColumns]
+        : undefined;
 
   const termNode = (
     <dt
       className={cn(
         "flex min-w-0 items-center gap-1 text-[var(--text-muted)]",
-        cards && "text-xs uppercase tracking-wide",
+        cards && (density === "tight" ? "text-[10px] uppercase tracking-wide" : "text-xs uppercase tracking-wide"),
+        // Stacked terms are a step smaller than the detail, as kastlan's dialogs set
+        // them; in a list that is already small they stay the list's own size.
+        stacked && density === "comfortable" && "text-xs",
       )}
     >
       <span className="min-w-0 break-words">{term}</span>
@@ -129,8 +270,10 @@ export function DescriptionItem({
     <dd
       className={cn(
         "min-w-0 break-words text-[var(--text-primary)]",
-        numeric && "tabular-nums text-end",
-        cards && "mt-0.5 font-medium",
+        // A stacked figure sits under its term, so it keeps the term's start edge.
+        numeric && (stacked ? "tabular-nums" : "tabular-nums text-end"),
+        (cards || stacked) && "mt-0.5 font-medium",
+        prose && "font-normal text-[var(--text-secondary)]",
         detailClassName,
       )}
     >
@@ -145,6 +288,7 @@ export function DescriptionItem({
         className={cn(
           "min-w-0 rounded-md border border-[var(--border)] bg-[var(--bg-surface)]",
           CARD_PAD[density],
+          spanClass,
           className,
         )}
       >
@@ -154,6 +298,15 @@ export function DescriptionItem({
     );
   }
 
+  if (stacked) {
+    return (
+      <div {...rest} className={cn("min-w-0", spanClass, className)}>
+        {termNode}
+        {detail}
+      </div>
+    );
+  }
+
   return (
     <div
       {...rest}

package/src/components/dialog-frame.tsx

@@ -103,6 +103,13 @@ export interface DialogFrameProps extends Omit<ModalProps, "labelledBy" | "child
  * tailwind-merged last), which is how a full-screen phone sheet is spelt:
  * `fullBleed className="h-[100dvh] max-w-full rounded-none md:h-auto md:rounded-lg"`.
  *
+ * ## Kept mounted
+ *
+ * `open` reaches the `Modal` like every other prop, so `<DialogFrame open={open} …>`
+ * replaces the `{open && <DialogFrame …/>}` gate (kastlan's `FormModal` was only
+ * that gate) and gains the exit a caller-driven close otherwise skips. See
+ * {@link ModalProps.open}.
+ *
  * ## What it is not
  *
  * Not `FullBleedDialog`: that is the phone's full-screen editor with its own `open`,

package/src/components/disclosure.tsx

@@ -3,22 +3,14 @@ import type { ComponentPropsWithoutRef, ReactNode } from "react";
 import { ChevronDown } from "lucide-react";
 
 import { cn } from "../lib/cn";
+// Read at the moment of closing, as `useCloseTransition` does: the setting can change
+// under a long-lived page.
+import { prefersReducedMotion } from "../hooks/use-close-transition";
 
 /** How long the fold takes, in ms. The same number as the `duration-200` below and as
  *  the unmount timer, because they are the same movement. */
 const COLLAPSE_MS = 200;
 
-/** Read at the moment of closing, like `useCloseTransition` does: the setting can
- *  change under a long-lived page, and jsdom/SSR have no `matchMedia` — where "no
- *  animation" is also the only correct answer, since nothing is painting. */
-function prefersReducedMotion(): boolean {
-  return (
-    typeof window === "undefined" ||
-    typeof window.matchMedia !== "function" ||
-    window.matchMedia("(prefers-reduced-motion: reduce)").matches
-  );
-}
-
 /**
  * `extends` the div's props so an `id` (what a trigger's `aria-controls` points at), a
  * `data-tour` anchor or a test id reaches the element that folds.
@@ -163,8 +155,14 @@ export interface DisclosureProps extends Omit<ComponentPropsWithoutRef<"div">, "
    * after the flag, like every other menu row with a sub-list. With `trailing`, the
    * chevron follows it, as on a card. A `card` always has it at the end, so this is
    * ignored there. A `menu` defaults to `end`, like the menu rows around it.
+   *
+   * `after-title` sits it right after the title's text, pointing down and turning up —
+   * "Net profit ⌄ ······ 1,234.50", Lenkbank's result rows, where the far end of the
+   * row belongs to a figure (see {@link trailingInTrigger}) and a leading chevron
+   * would push every label off the column the non-expandable rows' labels start on.
+   * Not a card's: its chevron keeps the end.
    */
-  chevronPosition?: "start" | "end";
+  chevronPosition?: "start" | "end" | "after-title";
   /**
    * Wrap the header button in a heading of this level. The WAI-ARIA disclosure pattern
    * puts the button INSIDE the heading when the disclosure titles a section, so the
@@ -203,8 +201,26 @@ export interface DisclosureProps extends Omit<ComponentPropsWithoutRef<"div">, "
    * the row under it (a stretched hit area), so clicking the empty space or the
    * card's chevron still toggles, while whatever sits in `trailing` gets its own
    * clicks. With `trailing`, the card's chevron moves after it, to the row's end.
+   *
+   * Unless {@link trailingInTrigger} is set, which moves it INTO the button.
    */
   trailing?: ReactNode;
+  /**
+   * Render {@link trailing} inside the header button instead of beside it, so the
+   * whole row — figure included — is one click target and the figure is part of the
+   * button's accessible name: "Net profit 1,234.50, collapsed" rather than a button
+   * called "Net profit" next to an unexplained number.
+   *
+   * Lenkbank's result rows (features/steering/results-panel.tsx) are the case: label,
+   * chevron, and the value at the far end, all one `<button>`, because a result row
+   * has nothing else it could mean.
+   *
+   * ⚠️ Only for NON-interactive content — a count, a figure, a status chip. A button
+   * may not contain another interactive element; an action belongs in the default,
+   * sibling `trailing`. The content is rendered in a `<span>`, so keep it phrasing
+   * content too (no `div`s).
+   */
+  trailingInTrigger?: boolean;
   /**
    * Trigger-only mode: the id of an element the CALLER renders elsewhere — the hidden
    * rows of a table, a panel in another column — which this header shows and hides.
@@ -212,6 +228,37 @@ export interface DisclosureProps extends Omit<ComponentPropsWithoutRef<"div">, "
    * its own (`children`, `bodyClassName` and `keepMounted` are ignored). Pair it with
    * `open` / `onOpenChange`: the caller owns the state, since the caller renders what
    * it governs.
+   *
+   * It is an IDREF LIST, as `aria-controls` is: several space-separated ids when what
+   * folds is several elements — a budget group's category rows, each its own `<li>`,
+   * siblings of this header (keksdose's budget-mobile-list joins their ids with
+   * `" "`). It may be the EMPTY string: trigger-only mode with nothing to point at yet
+   * (a group whose rows are all filtered away, rows that are not rendered while shut).
+   * The header then carries no `aria-controls` at all rather than an empty one, and
+   * still toggles.
+   *
+   * A table's leading row — keksdose's "Upcoming" toggle over the scheduled rows of
+   * its transactions table — is this mode too: the rows it folds are the TABLE's, so
+   * the disclosure is only the header, and the table renders or drops them from the
+   * same state.
+   *
+   * ```tsx
+   * <DataTable
+   *   rows={showFuture ? [...scheduled, ...posted] : posted}
+   *   leadingRow={
+   *     <Disclosure
+   *       variant="bare"
+   *       title={upcomingLabel}
+   *       open={showFuture}
+   *       onOpenChange={setShowFuture}
+   *       // The scheduled rows' ids while they are rendered; "" while they are not.
+   *       controls={showFuture ? scheduled.map((tx) => `row-s${tx.id}`).join(" ") : ""}
+   *       headerClassName="px-3 py-2"
+   *     />
+   *   }
+   *   …
+   * />
+   * ```
    */
   controls?: string;
   /** The body. Not rendered in trigger-only mode ({@link DisclosureProps.controls}). */
@@ -247,6 +294,7 @@ export function Disclosure({
   triggerProps,
   bodyClassName,
   trailing,
+  trailingInTrigger = false,
   controls,
   className,
   children,
@@ -259,11 +307,17 @@ export function Disclosure({
   const menu = variant === "menu";
   // The card's chevron trails always; a menu row's unless asked otherwise; a bare
   // one only when asked to.
-  const chevronAtEnd = card || (chevronPosition ?? (menu ? "end" : "start")) === "end";
+  const chevronAt = card ? "end" : (chevronPosition ?? (menu ? "end" : "start"));
+  const chevronAtEnd = chevronAt === "end";
+  const chevronAfterTitle = chevronAt === "after-title";
   const triggerOnly = controls !== undefined;
   // The card's header squares its lower corners only when a body opens under it.
   const joined = open && !triggerOnly;
   const hasTrailing = trailing !== undefined && trailing !== null && trailing !== false;
+  // `trailing` beside the button, which then stretches under it; inside the button,
+  // the row is simply the button.
+  const trailingInside = hasTrailing && trailingInTrigger;
+  const trailingBeside = hasTrailing && !trailingInTrigger;
 
   const toggle = () => {
     const next = !open;
@@ -278,13 +332,14 @@ export function Disclosure({
       {...extraTriggerProps}
       type="button"
       aria-expanded={open}
-      aria-controls={triggerOnly ? controls : bodyId}
+      // `||`: an empty `controls` is trigger-only with nothing to name, not `aria-controls=""`.
+      aria-controls={triggerOnly ? controls || undefined : bodyId}
       disabled={disabled}
       onClick={toggle}
       data-disclosure-trigger=""
       className={cn(
         "flex w-full gap-2 text-start outline-none disabled:cursor-not-allowed disabled:opacity-50",
-        hasTrailing
+        trailingBeside
           ? // Stretched over the whole header row (the row is `relative`), so the space
             // round `trailing` and the card's chevron still toggle; the ring and the
             // card's hover paint on the stretched area / the row, not the text box.
@@ -297,7 +352,7 @@ export function Disclosure({
         card
           ? cn(
               "items-center justify-between rounded-lg p-4",
-              hasTrailing ? "pe-0" : "hover:bg-[var(--bg-hover)] focus-visible:ring-inset",
+              trailingBeside ? "pe-0" : "hover:bg-[var(--bg-hover)] focus-visible:ring-inset",
               joined && "rounded-b-none",
             )
           : menu
@@ -309,29 +364,46 @@ export function Disclosure({
         headerClassName,
       )}
     >
-      {!chevronAtEnd && <Chevron open={open} leading />}
+      {chevronAt === "start" && <Chevron open={open} leading />}
       {/* `flex-1`: the title takes the row, so whatever a caller puts at its end sits
           at the header's far edge. */}
       <span className="min-w-0 flex-1">
-        <span className={cn("block", card && "text-sm font-semibold text-[var(--text-primary)]")}>{title}</span>
+        {chevronAfterTitle ? (
+          // The chevron hugs the text, however long the translation: the text wraps
+          // before the chevron is pushed away from it.
+          <span className="flex items-center gap-1">
+            <span className="min-w-0">{title}</span>
+            <Chevron open={open} small />
+          </span>
+        ) : (
+          <span className={cn("block", card && "text-sm font-semibold text-[var(--text-primary)]")}>{title}</span>
+        )}
         {hint !== undefined && (
           <span className="mt-0.5 block text-xs font-normal text-[var(--text-muted)]">{hint}</span>
         )}
       </span>
-      {chevronAtEnd && !hasTrailing && <Chevron open={open} small={!card} />}
+      {/* The space is for the accessible name — "Net profit 1,234.50", not
+          "Net profit1,234.50"; between flex items it renders as nothing. */}
+      {trailingInside && " "}
+      {trailingInside && (
+        <span data-disclosure-trailing="" className="flex shrink-0 items-center gap-2">
+          {trailing}
+        </span>
+      )}
+      {chevronAtEnd && !trailingBeside && <Chevron open={open} small={!card} />}
     </button>
   );
 
   // Preflight already makes h1–h6 inherit size and weight, so the heading adds
   // structure and nothing visible.
-  const header = Heading ? <Heading className={hasTrailing ? "min-w-0 flex-1" : undefined}>{button}</Heading> : button;
+  const header = Heading ? <Heading className={trailingBeside ? "min-w-0 flex-1" : undefined}>{button}</Heading> : button;
 
   return (
     <div
       {...rest}
       className={cn(card && "rounded-lg border border-[var(--border)] bg-[var(--bg-surface)] shadow-sm", className)}
     >
-      {hasTrailing ? (
+      {trailingBeside ? (
         <div
           className={cn(
             "relative flex items-center gap-2",

package/src/components/field.tsx

@@ -0,0 +1,137 @@
+/**
+ * A field group with its label ABOVE the control: label, control, hint, error.
+ *
+ * ```tsx
+ * <Field label="IBAN" required hint="22 characters" error={errors.iban}>
+ *   {(ids) => <Input {...ids} value={iban} onChange={…} />}
+ * </Field>
+ * ```
+ *
+ * The kit's `Input` and `Select` float their label inside the field, and the pickers
+ * draw theirs the same way. That is the wrong shape for a control the kit did not
+ * render, a radio group, a range slider, or a form that sets its labels above the
+ * fields throughout — which is what kastlan's wizards are, and why it kept its own
+ * `WizardField` after the kit dropped the one it had never rendered. This is that
+ * group, with the wiring the old one left to the caller: the label names the control
+ * through `htmlFor`, and the control is described by the hint and the error that are
+ * actually on screen.
+ *
+ * ## Wiring
+ *
+ * Pass a function as `children` and it receives {@link FieldControlProps} — `id`,
+ * `aria-describedby`, `aria-invalid` and `aria-required` — to spread on the control.
+ * Plain children render as they are, for a control that wires itself (a checkbox that
+ * carries its own label, a group with `aria-labelledby`); `htmlFor` then points the
+ * label at the control's own id, and the hint and error are on screen but describe
+ * nothing — the same as the `WizardField` this replaces.
+ *
+ * ## Decoupled
+ *
+ * Deliberately knows neither the wizard nor react-hook-form: `error` is a plain
+ * value. Pass `wizard.fieldErrors.iban`, a step-local error, or
+ * `fieldState.error?.message` from a `FormField` render — the markup is the same
+ * whichever of them gates the step, so a step can move between them without its
+ * fields changing. (Inside a react-hook-form form, `FormItem` + `FormLabel` from
+ * `@eifi1/ui-kit/rhf` do the same job with the ids taken from the form.)
+ *
+ * The error is NOT `role="alert"`, for the reason the kit's `error` prop gives (see
+ * `useFieldError` in components/ui.tsx): it is read when focus reaches the control.
+ */
+import { useId, type ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { Label } from "./ui";
+
+/** What a `Field` hands its render-prop children, to spread on the control. */
+export interface FieldControlProps {
+  /** The id the label's `htmlFor` points at. */
+  id: string;
+  /** The ids of the hint and the error that are rendered, or `undefined` when
+   *  neither is. */
+  "aria-describedby": string | undefined;
+  /** `true` while the field has an error, `undefined` otherwise. */
+  "aria-invalid": true | undefined;
+  /** `true` when the field is `required`. The label's star is `aria-hidden`; this
+   *  is what a screen reader hears instead. */
+  "aria-required": true | undefined;
+}
+
+export interface FieldProps {
+  /** The label above the control. Omit it for a group whose control is labelled
+   *  some other way; the hint and error still render. */
+  label?: ReactNode;
+  /** Draws the kit's required mark after the label, and sets `aria-required` on the
+   *  render-prop control. */
+  required?: boolean;
+  /** Muted helper text below the control. */
+  hint?: ReactNode;
+  /** The error below the control. `null`, `false` and `""` are no error — what a
+   *  `touched && errors.x` evaluates to on the happy path. */
+  error?: ReactNode;
+  /** The control's id. Defaults to a generated one; set it when the control carries
+   *  its own id (plain children). */
+  htmlFor?: string;
+  /** Dims the label with its control. */
+  disabled?: boolean;
+  /** The label's size: `sm` for a dense row, `md` otherwise. */
+  labelSize?: "sm" | "md";
+  /** Wrapper className. */
+  className?: string;
+  /** The control. A function receives {@link FieldControlProps} to spread on it. */
+  children: ReactNode | ((control: FieldControlProps) => ReactNode);
+}
+
+const isShown = (node: ReactNode) =>
+  node !== undefined && node !== null && node !== false && node !== "";
+
+export function Field({
+  label,
+  required,
+  hint,
+  error,
+  htmlFor,
+  disabled,
+  labelSize,
+  className,
+  children,
+}: FieldProps) {
+  const generated = useId();
+  const id = htmlFor ?? `${generated}-control`;
+  const hintId = `${generated}-hint`;
+  const errorId = `${generated}-error`;
+  const hasHint = isShown(hint);
+  const hasError = isShown(error);
+  const describedBy = [hasHint && hintId, hasError && errorId].filter(Boolean).join(" ");
+  const control: FieldControlProps = {
+    id,
+    "aria-describedby": describedBy || undefined,
+    "aria-invalid": hasError || undefined,
+    "aria-required": required || undefined,
+  };
+  return (
+    <div data-slot="field" className={cn("grid gap-1.5", className)}>
+      {label !== undefined && (
+        <Label
+          htmlFor={id}
+          required={required}
+          disabled={disabled}
+          size={labelSize}
+          data-error={hasError || undefined}
+          className="data-[error=true]:text-[var(--danger)]"
+        >
+          {label}
+        </Label>
+      )}
+      {typeof children === "function" ? children(control) : children}
+      {hasHint && (
+        <p id={hintId} className="text-[11px] leading-tight text-[var(--text-muted)]">
+          {hint}
+        </p>
+      )}
+      {hasError && (
+        <p id={errorId} className="text-[11px] leading-tight text-[var(--danger)]">
+          {error}
+        </p>
+      )}
+    </div>
+  );
+}