@eifi1/ui-kit 0.11.0 → 0.13.0

package/src/rhf/line-items.tsx

@@ -0,0 +1,130 @@
+/**
+ * {@link LineItems} over react-hook-form's `useFieldArray`. `@eifi1/ui-kit/rhf`.
+ *
+ * ```tsx
+ * <RhfLineItems
+ *   name="components"
+ *   newItem={() => ({ type: "net_rent", amount: null, validFrom: "" })}
+ *   minItems={1}
+ *   columns={[
+ *     { key: "type", header: "Type", render: ({ name, label }) => (
+ *       <RhfSelect name={`${name}.type`} options={TYPES} aria-label={label} />
+ *     ) },
+ *     { key: "amount", header: "Amount", width: "8rem", align: "end", render: ({ name, label }) => (
+ *       <RhfMoneyField name={`${name}.amount`} ariaLabel={label} />
+ *     ) },
+ *   ]}
+ *   totals={{ amount: formatMoney(total) }}
+ * />
+ * ```
+ *
+ * The rows are the array's `fields` (keyed by their `id`, as react-hook-form asks),
+ * Add appends `newItem()`, remove is `remove(index)`, and an error on the array
+ * itself — the `rules` here, or a resolver's `lines: "At least two lines"` — is the
+ * list's `error`. Each cell's `render` gets `name`, the row's path
+ * (`"components.2"`), to bind its field to.
+ */
+import type { ReactNode } from "react";
+import {
+  useFieldArray,
+  useFormState,
+  type FieldArray,
+  type FieldArrayPath,
+  type FieldArrayWithId,
+  type FieldValues,
+  type UseFieldArrayProps,
+} from "react-hook-form";
+import {
+  LineItems,
+  type LineItemCellContext,
+  type LineItemsColumn,
+  type LineItemsProps,
+} from "../components/line-items";
+
+/** A cell's context, with the row's path in the form. */
+export interface RhfLineItemCellContext<TItem, TArrayName extends string>
+  extends LineItemCellContext<TItem> {
+  /** The row's path: `${name}.${index}` — bind the cell's field to
+   *  `` `${name}.amount` ``. */
+  name: `${TArrayName}.${number}`;
+}
+
+export interface RhfLineItemsColumn<TItem, TArrayName extends string>
+  extends Omit<LineItemsColumn<TItem>, "render"> {
+  render: (ctx: RhfLineItemCellContext<TItem, TArrayName>) => ReactNode;
+}
+
+export interface RhfLineItemsProps<
+  TFieldValues extends FieldValues = FieldValues,
+  TArrayName extends FieldArrayPath<TFieldValues> = FieldArrayPath<TFieldValues>,
+  TTransformed = TFieldValues,
+> extends Omit<
+    LineItemsProps<FieldArrayWithId<TFieldValues, TArrayName, "id">>,
+    "items" | "columns" | "onAdd" | "onRemove" | "getKey"
+  > {
+  name: TArrayName;
+  /** `form.control`. Optional under `<Form {...form}>`. */
+  control?: UseFieldArrayProps<TFieldValues, TArrayName, "id", TTransformed>["control"];
+  /** `useFieldArray`'s `rules` (`minLength`, `validate` …); its message is the list's
+   *  error. */
+  rules?: UseFieldArrayProps<TFieldValues, TArrayName, "id", TTransformed>["rules"];
+  columns: readonly RhfLineItemsColumn<FieldArrayWithId<TFieldValues, TArrayName, "id">, TArrayName>[];
+  /** A new row's values. Omitted: no add button. */
+  newItem?: () => FieldArray<TFieldValues, TArrayName>;
+  /** `false`: no remove buttons. Default `true`. */
+  removable?: boolean;
+}
+
+/** The message of an error at `path` in react-hook-form's errors tree: the array's
+ *  own (`root`, from `rules`) or one a resolver put on the array. */
+function arrayError(errors: unknown, path: string): string | undefined {
+  let node: unknown = errors;
+  for (const key of path.split(".")) {
+    if (node === null || typeof node !== "object") return undefined;
+    node = (node as Record<string, unknown>)[key];
+  }
+  if (node === null || typeof node !== "object") return undefined;
+  const { root, message } = node as { root?: { message?: unknown }; message?: unknown };
+  const text = root?.message ?? message;
+  return typeof text === "string" && text !== "" ? text : undefined;
+}
+
+/** {@link LineItems} bound to a field array. See the module note. */
+export function RhfLineItems<
+  TFieldValues extends FieldValues = FieldValues,
+  TArrayName extends FieldArrayPath<TFieldValues> = FieldArrayPath<TFieldValues>,
+  TTransformed = TFieldValues,
+>({
+  name,
+  control,
+  rules,
+  columns,
+  newItem,
+  removable = true,
+  error,
+  ...rest
+}: RhfLineItemsProps<TFieldValues, TArrayName, TTransformed>) {
+  const { fields, append, remove } = useFieldArray<TFieldValues, TArrayName, "id", TTransformed>({
+    control,
+    name,
+    rules,
+  });
+  const { errors } = useFormState({ control, name: name as never });
+  const bound: LineItemsColumn<FieldArrayWithId<TFieldValues, TArrayName, "id">>[] = columns.map(
+    ({ render, ...column }) => ({
+      ...column,
+      render: (ctx) => render({ ...ctx, name: `${name}.${ctx.index}` as `${TArrayName}.${number}` }),
+    }),
+  );
+  return (
+    <LineItems
+      {...rest}
+      items={fields}
+      columns={bound}
+      getKey={(field) => field.id}
+      onAdd={newItem ? () => append(newItem()) : undefined}
+      onRemove={removable ? (index) => remove(index) : undefined}
+      error={error ?? arrayError(errors, name)}
+    />
+  );
+}

package/src/rhf.ts

@@ -9,3 +9,9 @@
 export * from "./rhf/form";
 // The react-hook-form bridge to the wizard's Next gate (useWizard lives in /wizard).
 export * from "./rhf/use-rhf-wizard-step";
+// Bound fields — one line per field (RhfTextField, RhfNumberField, RhfIntegerField, RhfMoneyField,
+// RhfDateField, RhfTextarea, RhfSelect, RhfCheckbox, RhfCombobox, RhfTextCombobox)
+// and RhfField, the shell they are built on.
+export * from "./rhf/fields";
+// LineItems over useFieldArray.
+export * from "./rhf/line-items";

package/src/search/command-palette.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useId, useMemo, useRef, useState } from "react";
+import { useEffect, useEffectEvent, useId, useMemo, useRef, useState } from "react";
 import type { ReactNode } from "react";
 import { createPortal } from "react-dom";
 import { CornerDownLeft, Search, X } from "lucide-react";
@@ -54,9 +54,12 @@ function groupItems(items: CommandItem[]) {
     }
     byGroup.get(item.group)!.push(item);
   }
+  const flat = order.flatMap((g) => byGroup.get(g)!).filter((item) => item.kind !== "status");
   return {
     groups: order.map((g) => ({ group: g, items: byGroup.get(g)! })),
-    flat: order.flatMap((g) => byGroup.get(g)!).filter((item) => item.kind !== "status"),
+    flat,
+    /** Each selectable item's position in `flat` — its `data-index` and keyboard slot. */
+    flatIndex: new Map(flat.map((item, index) => [item, index])),
   };
 }
 
@@ -279,8 +282,9 @@ export function CommandPalette({
   const dialogRef = useRef<HTMLDivElement>(null);
   const inputRef = useRef<HTMLInputElement>(null);
   const listRef = useRef<HTMLUListElement>(null);
-  const searchRef = useRef(search);
-  searchRef.current = search;
+  // The latest `search`, callable from the debounced effect without being one of its
+  // dependencies — `revision` is what re-runs it (see the prop's docstring).
+  const runSearch = useEffectEvent((q: string) => search(q));
   const reqId = useRef(0);
   /** What the provider's last answer was: a promise (`false`), an array (`true`), or
    *  not known yet. Only a provider known to be async shows "Searching…" while the
@@ -305,17 +309,24 @@ export function CommandPalette({
   useBodyScrollLock(open);
 
   // Reset when opened — the palette's OWN text only; a controlled query belongs to
-  // its owner (see the prop).
+  // its owner (see the prop). Adjusted during render on the closed-to-open transition
+  // (starting from "closed", so a palette mounted open resets too). `controlled` is
+  // read at the open, not watched: a caller switching modes while the palette is open
+  // is not a reason to wipe what is typed.
+  const [wasOpen, setWasOpen] = useState(false);
+  if (open !== wasOpen) {
+    setWasOpen(open);
+    if (open) {
+      if (!controlled) setOwnQuery("");
+      // An uncommitted draft does not outlive the open it was typed in.
+      setDraft(controlled ? query : "");
+      setActive(0);
+    }
+  }
+  // The ref half of that reset: results from a previous open do not carry a
+  // highlight into this one.
   useEffect(() => {
-    if (!open) return;
-    if (!controlled) setOwnQuery("");
-    // An uncommitted draft does not outlive the open it was typed in.
-    setDraft(controlled ? query : "");
-    setActive(0);
-    shownQuery.current = null;
-    // `controlled` is read at the open, not watched: a caller switching modes while
-    // the palette is open is not a reason to wipe what is typed.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
+    if (open) shownQuery.current = null;
   }, [open]);
 
   // Debounced, race-safe search.
@@ -325,7 +336,7 @@ export function CommandPalette({
     if (syncRef.current === false) setLoading(true);
     const run = async () => {
       try {
-        const answer = searchRef.current(query);
+        const answer = runSearch(query);
         syncRef.current = !isThenable(answer);
         if (!syncRef.current) setLoading(true);
         const r = await answer;
@@ -359,7 +370,7 @@ export function CommandPalette({
   }, [query, open, revision]);
 
   // Group results, preserving first-seen group order; keep a flat list for nav.
-  const { groups, flat } = useMemo(() => groupItems(results), [results]);
+  const { groups, flat, flatIndex } = useMemo(() => groupItems(results), [results]);
   useEffect(() => {
     activeIdRef.current = flat[active]?.id;
   });
@@ -404,8 +415,8 @@ export function CommandPalette({
   if (!open) return null;
 
   const comfortable = density === "comfortable";
-  let flatIndex = -1;
   return createPortal(
+    // eslint-disable-next-line jsx-a11y/no-static-element-interactions -- pointer-only backdrop dismiss; Escape is the keyboard path
     <div
       className={cn(
         "fixed inset-0 z-[70] flex items-start justify-center bg-black/40",
@@ -546,8 +557,7 @@ export function CommandPalette({
                       </li>
                     );
                   }
-                  flatIndex += 1;
-                  const idx = flatIndex;
+                  const idx = flatIndex.get(item) ?? -1;
                   const isActive = idx === active;
                   const redact = item.redact ?? redactLabels;
                   // Written once and worn by either tag below, so the anchor and the

package/src/shell/app-shell.tsx

@@ -1,17 +1,19 @@
 import { createContext, useCallback, useContext, useEffect, useId, useRef, useState } from "react";
 import type { ComponentPropsWithoutRef, ReactNode } from "react";
 import { createPortal } from "react-dom";
-import { NavLink, matchPath, useLocation } from "react-router";
+import { Link, NavLink, matchPath, useLocation } from "react-router";
 import { ChevronRight, PanelLeftClose, PanelLeftOpen } from "lucide-react";
 import type { LucideIcon } from "lucide-react";
 import { cn } from "../lib/cn";
 import { dirOf, type Direction } from "../lib/direction";
 import { readStored, writeStored } from "../lib/safe-storage";
 import { Tooltip } from "../components/tooltip";
+import { pickLinkRenderer } from "../components/text-link";
 import { useAnchoredRect } from "../hooks/use-anchored-rect";
 import { useEscapeKey } from "../hooks/use-dismiss";
 import { useMediaQuery } from "../hooks/use-media-query";
-import { DEFAULT_APP_SHELL_LABELS, useKitLabels } from "../i18n/kit-labels";
+import { DEFAULT_APP_SHELL_LABELS, useKitLabels, useKitLink } from "../i18n/kit-labels";
+import type { KitLinkComponent, KitLinkProps } from "../i18n/kit-labels";
 
 export interface AppShellSubItem {
   to: string;
@@ -48,6 +50,44 @@ export interface AppShellNavItem {
   items?: AppShellSubItem[];
 }
 
+/**
+ * One entry of the sidebar's bottom area ({@link AppShellProps.sidebarFooterItems}) —
+ * the version link and the legal links kastlan hand-built in `sidebarFooter`.
+ *
+ * - `link` (default): one link. Expanded it shows `icon` + `text` (default `label`),
+ *   with `hint` as a tooltip if given; collapsed it is the icon alone, named and
+ *   tooltipped by `label`.
+ * - `links`: a small group — the legal links. Expanded, a `<nav>` named `label` holding
+ *   the links as a wrapping row of small text; collapsed, ONE icon link to `to` (default
+ *   the first link's), named and tooltipped by `label`, since a column of icons for
+ *   "Imprint", "Privacy" and "Terms" would say nothing an icon can.
+ */
+export type AppShellSidebarFooterItem =
+  | {
+      kind?: "link";
+      key: string;
+      to: string;
+      icon: LucideIcon;
+      /** The link's name, and the tooltip when collapsed ("What's new · v1.4.0"). */
+      label: string;
+      /** Visible text when expanded ("Kastlan v1.4.0"). Default `label`. */
+      text?: ReactNode;
+      /** A tooltip on the expanded link ("What's new"). */
+      hint?: string;
+      /** Leaves the app: a plain `<a target="_blank" rel="noopener noreferrer">`. */
+      external?: boolean;
+    }
+  | {
+      kind: "links";
+      key: string;
+      icon: LucideIcon;
+      /** The group's name — its `<nav>` label, and the collapsed icon's name ("Legal"). */
+      label: string;
+      /** The collapsed icon's target. Default the first link's `to`. */
+      to?: string;
+      links: { to: string; label: string; external?: boolean }[];
+    };
+
 /**
  * Exported and `<div>`-shaped. This is the outermost element of every consuming app, so
  * there is nothing above it to hang an id, a landmark label or a `data-tour` anchor on —
@@ -66,6 +106,13 @@ export interface AppShellProps extends ComponentPropsWithoutRef<"div"> {
   /** Extra sidebar content above the collapse toggle (e.g. a version link).
    *  Receives the collapsed state so it can render compact vs. full. */
   sidebarFooter?: (collapsed: boolean) => ReactNode;
+  /** The sidebar's bottom area as data — a version link, the legal links — drawn full
+   *  when expanded and as icon + tooltip when collapsed. Rendered above
+   *  `sidebarFooter`, which stays for anything the data cannot describe. */
+  sidebarFooterItems?: AppShellSidebarFooterItem[];
+  /** The router link for `sidebarFooterItems`. Default: the provider's
+   *  `linkComponent`, else react-router's `Link`. */
+  renderLink?: KitLinkComponent;
   /** localStorage key for the persisted collapse state. */
   collapseStorageKey?: string;
   /** Default: `appShell.collapse` from the {@link UiKitProvider}, else English. */
@@ -201,6 +248,8 @@ export function AppShell({
   children,
   footer,
   sidebarFooter,
+  sidebarFooterItems,
+  renderLink,
   collapseStorageKey: collapseStorageKeyProp,
   collapseLabel,
   expandLabel,
@@ -296,6 +345,9 @@ export function AppShell({
                 ))}
               </div>
             </nav>
+            {!!sidebarFooterItems?.length && (
+              <SidebarFooterItems items={sidebarFooterItems} collapsed={collapsed} renderLink={renderLink} />
+            )}
             {sidebarFooter?.(collapsed)}
             <div className="border-t border-[var(--border)] p-2">
               {collapsed ? (
@@ -397,6 +449,99 @@ export function AppShell({
   );
 }
 
+const routerLink: KitLinkComponent = ({ href, ...p }) => <Link to={href} {...p} />;
+const plainLink: KitLinkComponent = ({ children, ...p }) => <a {...p}>{children}</a>;
+
+const FOOTER_ICON_LINK =
+  "flex min-h-8 items-center justify-center rounded-md text-[var(--text-muted)] hover:bg-[var(--bg-hover)] hover:text-[var(--text-secondary)]";
+
+/** Calls the link renderer as a component, so a router link's hooks are its own. */
+function RenderedLink({ render, ...props }: KitLinkProps & { render: KitLinkComponent }) {
+  return render(props);
+}
+
+/** The sidebar's bottom area, from {@link AppShellSidebarFooterItem}s. */
+function SidebarFooterItems({
+  items,
+  collapsed,
+  renderLink,
+}: {
+  items: AppShellSidebarFooterItem[];
+  collapsed: boolean;
+  renderLink?: KitLinkComponent;
+}) {
+  const kitLink = useKitLink();
+  const linkTo = (to: string, external: boolean | undefined, { children, ...props }: Omit<KitLinkProps, "href">) => {
+    // The kit's one link rule (`pickLinkRenderer`): an external `to` or an in-page
+    // `#anchor` is a plain `<a>` even without `external`; only `external` opens a tab.
+    const InApp = pickLinkRenderer(renderLink, kitLink ?? routerLink, to) ?? plainLink;
+    return external ? (
+      <a href={to} target="_blank" rel="noopener noreferrer" {...props}>
+        {children}
+      </a>
+    ) : (
+      <RenderedLink render={InApp} href={to} {...props}>
+        {children}
+      </RenderedLink>
+    );
+  };
+
+  return (
+    <div data-slot="sidebar-footer-items" className={cn("px-2 py-1", collapsed ? "space-y-1" : "space-y-1.5")}>
+      {items.map((item) => {
+        if (collapsed) {
+          const to = item.kind === "links" ? (item.to ?? item.links[0]?.to) : item.to;
+          if (!to) return null;
+          const external = item.kind === "links" ? item.links.find((l) => l.to === to)?.external : item.external;
+          return (
+            <Tooltip key={item.key} label={item.label} side="end" portal className="block">
+              {linkTo(to, external, {
+                "aria-label": item.label,
+                className: FOOTER_ICON_LINK,
+                children: <item.icon className="size-4" aria-hidden />,
+              })}
+            </Tooltip>
+          );
+        }
+        if (item.kind === "links") {
+          return (
+            <nav
+              key={item.key}
+              aria-label={item.label}
+              className="flex flex-wrap justify-center gap-x-3 gap-y-0.5 text-[11px] text-[var(--text-muted)]"
+            >
+              {item.links.map((l) => (
+                <span key={l.to}>
+                  {linkTo(l.to, l.external, {
+                    className: "rounded-sm hover:text-[var(--text-secondary)] hover:underline",
+                    children: l.label,
+                  })}
+                </span>
+              ))}
+            </nav>
+          );
+        }
+        const link = linkTo(item.to, item.external, {
+          className: cn(FOOTER_ICON_LINK, "gap-1.5 text-xs font-medium"),
+          children: (
+            <>
+              <item.icon className="size-3.5 shrink-0" aria-hidden />
+              <span className="min-w-0 truncate">{item.text ?? item.label}</span>
+            </>
+          ),
+        });
+        return item.hint ? (
+          <Tooltip key={item.key} label={item.hint} side="top" portal className="block">
+            {link}
+          </Tooltip>
+        ) : (
+          <div key={item.key}>{link}</div>
+        );
+      })}
+    </div>
+  );
+}
+
 /** One cell of the phone's group bar. Marked while the group's own page OR any of its
  *  pages is current — NavLink alone only knows its own `to`, which left the bar with
  *  nothing marked on every sub-page (the same defect the sidebar had). */
@@ -620,7 +765,6 @@ function SidebarGroup({
   // group UNFOLDS into view on load rather than appearing already open.
   const here = subActive || onOwnPage;
   useEffect(() => {
-    // eslint-disable-next-line react-hooks/set-state-in-effect -- follows the route, see above
     if (here) setOpenGroup(item.to);
   }, [here, item.to, setOpenGroup]);
   const expanded = inline && open;
@@ -786,6 +930,9 @@ function SidebarFlyout({ item, children }: { item: AppShellNavItem; children: Re
   );
 
   return (
+    // Not a control: hover and focus-within on the nav link inside. Focus (the
+    // keyboard path) opens it exactly as hover does, Escape closes it.
+    // eslint-disable-next-line jsx-a11y/no-static-element-interactions -- hover/focus-within wrapper around a real link
     <div
       ref={wrapperRef}
       className="relative"
@@ -798,6 +945,9 @@ function SidebarFlyout({ item, children }: { item: AppShellNavItem; children: Re
       {open &&
         pos &&
         createPortal(
+          // Keeps the flyout open while the pointer crosses into it; keyboard users
+          // reach it by focus, which the wrapper above already handles.
+          // eslint-disable-next-line jsx-a11y/no-static-element-interactions -- pointer-only hover bridge
           <div
             dir={dir}
             style={{ position: "fixed", ...pos }}

package/src/shell/auth-layout.tsx

@@ -0,0 +1,190 @@
+import type { ComponentPropsWithoutRef, CSSProperties, ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { Card } from "../components/ui";
+
+/**
+ * `extends ComponentPropsWithoutRef<"div">` because this is the page's outermost element
+ * — the one that owns `min-h-dvh` and the safe-area padding — so there is nothing a
+ * consumer could wrap it in to add an id or a `data-*` hook without breaking that.
+ */
+export interface AuthLayoutProps extends Omit<ComponentPropsWithoutRef<"div">, "title"> {
+  /** The brand mark (an SVG), drawn in a brand-coloured tile above the title. */
+  logo?: ReactNode;
+  /** `false` draws `logo` as it is, without the tile — for a full-colour logo image. */
+  logoTile?: boolean;
+  /** The page's `<h1>` (see `headingAs`): the product name on sign-in, "Verify email",
+   *  "Imprint". */
+  title?: ReactNode;
+  /** The muted line under the title. */
+  description?: ReactNode;
+  /** The card's content — the form, the status, the legal text. */
+  children: ReactNode;
+  /**
+   * Above the header, outside the card — the legal pages' "← Back to sign in" link, or
+   * a notice banner. Start-aligned in both widths.
+   */
+  back?: ReactNode;
+  /** The top-end corner: a `LanguageMenu`. */
+  languageMenu?: ReactNode;
+  /** The top-end corner, before the language menu: a `ThemeToggle`. */
+  themeToggle?: ReactNode;
+  /** Below the card, centred — the legal links. */
+  footer?: ReactNode;
+  /** Wraps the footer in a `<nav>` with this name ("Legal"). Without it, a plain block. */
+  footerLabel?: string;
+  /**
+   * - `"narrow"` (default) — a `max-w-sm` card centred on the page, header centred:
+   *   sign-in, register, verify email, two-factor.
+   * - `"wide"` — a `max-w-3xl` column from the top of the page, header start-aligned:
+   *   running text (imprint, privacy, terms), which reads badly centred.
+   */
+  width?: "narrow" | "wide";
+  /** `false` lays the header and content on the page itself, without the card's
+   *  surface and border — the legal pages. Default true. */
+  card?: boolean;
+  /** Extra classes for the card (or, with `card={false}`, the content column). */
+  cardClassName?: string;
+  /**
+   * `false` draws the content column and the footer as plain `<div>`s instead of
+   * `<main>` and `<footer>` — for an AuthLayout embedded in a page that already has its
+   * landmarks (a preview, a docs page, a dialog), where a second `<main>` would nest
+   * one inside the other. Default `true`: on its own route it IS the page.
+   */
+  landmark?: boolean;
+  /** The title's element. Default `h1` — the page's heading; an embedded layout takes
+   *  the level of where it sits (`h2`, `h3`). */
+  headingAs?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+}
+
+/** Keeps the page clear of a notch, the rounded corners and the home indicator on a
+ *  phone in `viewport-fit=cover`; 1rem where the platform reports no inset. Physical
+ *  left/right, because that is what `env()` reports. */
+const SAFE_AREA: CSSProperties = {
+  paddingTop: "max(1rem, env(safe-area-inset-top, 0px))",
+  paddingBottom: "max(1rem, env(safe-area-inset-bottom, 0px))",
+  paddingLeft: "max(1rem, env(safe-area-inset-left, 0px))",
+  paddingRight: "max(1rem, env(safe-area-inset-right, 0px))",
+};
+
+const FOOTER_CLASS =
+  "flex flex-wrap justify-center gap-x-4 gap-y-1 text-xs text-[var(--text-muted)] [&_a:hover]:text-[var(--text-primary)] [&_a:hover]:underline [&_a]:rounded-sm [&_a:focus-visible]:outline-none [&_a:focus-visible]:ring-2 [&_a:focus-visible]:ring-[var(--brand)]";
+
+/**
+ * The public page frame outside the app shell: sign-in, registration, email
+ * verification, two-factor — and, `width="wide"`, the legal pages.
+ *
+ * kastlan's login, register, verify-email and two-factor pages each repeat the same
+ * `min-h-screen` centring, the absolutely placed language switcher, the brand tile, the
+ * centred title + subtitle and an absolutely placed legal footer. Absolutely placed,
+ * the footer and the switcher sat ON the card on a short phone screen (a tall register
+ * form, or the software keyboard up); here they are rows of a column that grows with
+ * its content, so the page scrolls instead of overlapping.
+ *
+ * The corner controls, the `<main>` and the footer are in reading order: a screen
+ * reader meets the language switch first, which is where someone who cannot read the
+ * page's language needs it.
+ */
+export function AuthLayout({
+  logo,
+  logoTile = true,
+  title,
+  description,
+  children,
+  back,
+  languageMenu,
+  themeToggle,
+  footer,
+  footerLabel,
+  width = "narrow",
+  card = true,
+  cardClassName,
+  landmark = true,
+  headingAs: Heading = "h1",
+  className,
+  style,
+  ...rest
+}: AuthLayoutProps) {
+  const Main = landmark ? "main" : "div";
+  const Footer = landmark ? "footer" : "div";
+  const wide = width === "wide";
+  const hasCorner = languageMenu != null || themeToggle != null;
+  const hasHeader = logo != null || title != null || description != null;
+
+  const header = hasHeader && (
+    <div
+      data-slot="auth-layout-header"
+      className={cn("flex flex-col gap-1.5", wide ? "items-start text-start" : "items-center text-center")}
+    >
+      {logo != null &&
+        (logoTile ? (
+          <div className="mb-2 flex size-12 items-center justify-center rounded-lg bg-[var(--brand)] text-[var(--brand-contrast)] [&_svg]:size-6">
+            {logo}
+          </div>
+        ) : (
+          <div className="mb-2">{logo}</div>
+        ))}
+      {title != null && (
+        <Heading
+          className={cn(
+            "font-semibold leading-tight text-[var(--text-primary)]",
+            wide ? "text-2xl md:text-3xl" : "text-2xl",
+          )}
+        >
+          {title}
+        </Heading>
+      )}
+      {description != null && <p className="text-sm text-[var(--text-muted)]">{description}</p>}
+    </div>
+  );
+
+  const body = (
+    <>
+      {header}
+      <div className={cn(hasHeader && (wide ? "mt-6" : "mt-5"))}>{children}</div>
+    </>
+  );
+
+  return (
+    <div
+      {...rest}
+      data-auth-layout={width}
+      style={{ ...SAFE_AREA, ...style }}
+      className={cn("flex min-h-dvh flex-col bg-[var(--bg-page)] text-[var(--text-primary)]", className)}
+    >
+      {hasCorner && (
+        <div data-slot="auth-layout-corner" className="flex items-center justify-end gap-1">
+          {themeToggle}
+          {languageMenu}
+        </div>
+      )}
+      <Main
+        data-slot="auth-layout-main"
+        className={cn(
+          // `relative` contains any `sr-only` child (see AppShell's <main>).
+          "relative flex w-full flex-1 flex-col",
+          wide ? "py-6 md:py-10" : "items-center justify-center py-8",
+        )}
+      >
+        <div className={cn("mx-auto w-full", wide ? "max-w-3xl" : "max-w-sm")}>
+          {back != null && <div className="mb-4">{back}</div>}
+          {card ? (
+            <Card className={cn(wide ? "p-6 md:p-8" : "p-6", cardClassName)}>{body}</Card>
+          ) : (
+            <div className={cardClassName}>{body}</div>
+          )}
+        </div>
+      </Main>
+      {footer != null && footer !== false && (
+        <Footer data-slot="auth-layout-footer" className="pt-4">
+          {footerLabel ? (
+            <nav aria-label={footerLabel} className={FOOTER_CLASS}>
+              {footer}
+            </nav>
+          ) : (
+            <div className={FOOTER_CLASS}>{footer}</div>
+          )}
+        </Footer>
+      )}
+    </div>
+  );
+}