@eifi1/ui-kit 0.30.0 → 0.31.0

package/src/account/sessions-setting.tsx

@@ -12,7 +12,8 @@ import { hasMessage } from "../components/choice-parts";
 import { DangerConfirm } from "../components/danger-confirm";
 import { Skeleton } from "../components/skeleton";
 import { Button, Card } from "../components/ui";
-import { CARD_DESCRIPTION_CLASS, CARD_TITLE_CLASS, settle, useMounted } from "./account-parts";
+import { CARD_DESCRIPTION_CLASS, settle, useMounted } from "./account-parts";
+import { SettingsCardTitle } from "../settings/settings-heading";
 
 /* ── Labels ──────────────────────────────────────────────────────────────── */
 
@@ -206,7 +207,7 @@ export function SessionsSetting<Id extends SessionId = SessionId>({
   return (
     <Card {...rest} className={cn("p-4 space-y-3", className)}>
       <div>
-        <div className={CARD_TITLE_CLASS}>{labels.title}</div>
+        <SettingsCardTitle>{labels.title}</SettingsCardTitle>
         <div className={CARD_DESCRIPTION_CLASS}>{labels.description}</div>
       </div>
       {showList &&

package/src/admin/invitations-panel.tsx

@@ -196,8 +196,10 @@ export interface InvitationsPanelProps<R extends string = string> {
   onInvite?: (draft: InvitationDraft<R>) => MaybePromise<InvitationSentAnswer | void>;
   /** Mints a new link and mails it. Left out: no resend button. */
   onResend?: (invitation: InvitationRow<R>) => MaybePromise<InvitationSentAnswer | void>;
-  /** Revokes an open invitation (level `none`, §4.2: re-inviting undoes it). Left out:
-   *  no revoke button. */
+  /** Revokes an open or an expired invitation (level `none`, §4.2: re-inviting undoes
+   *  it). An expired row can be resent, and since 0.31 also removed: in an app that
+   *  keeps the rows it would otherwise stay listed for good (Kurvenschmiede's 0.30
+   *  adoption). Left out: no revoke button. */
   onRevoke?: (invitation: InvitationRow<R>) => MaybePromise;
   /** The list is being fetched. */
   loading?: boolean;
@@ -205,6 +207,10 @@ export interface InvitationsPanelProps<R extends string = string> {
   describeError?: (error: unknown) => ReactNode | undefined;
   /** Over the form: who can be invited and what happens, in the app's words. */
   intro?: ReactNode;
+  /** The list's visible heading. Default: the `listTitle` label. `null` leaves it out,
+   *  for a page whose card is already headed "Invitations" (Kurvenschmiede's 0.30
+   *  adoption); the list keeps the label as its accessible name either way. */
+  listTitle?: ReactNode | null;
   className?: string;
   labels?: Partial<InvitationsLabels>;
 }
@@ -233,6 +239,7 @@ export function InvitationsPanel<R extends string = string>({
   loading = false,
   describeError,
   intro,
+  listTitle,
   className,
   labels: labelsProp,
 }: InvitationsPanelProps<R>) {
@@ -418,7 +425,7 @@ export function InvitationsPanel<R extends string = string>({
       )}
 
       <div className="space-y-2">
-        <SectionLabel as="h4">{labels.listTitle}</SectionLabel>
+        {listTitle !== null && <SectionLabel as="h4">{listTitle ?? labels.listTitle}</SectionLabel>}
         {loading && invitations.length === 0 ? (
           <div className="flex justify-center py-3">
             <Spinner label={labels.loading} />
@@ -432,7 +439,7 @@ export function InvitationsPanel<R extends string = string>({
               const link = invitation.link ?? links[key];
               const open = invitation.status === "open";
               const resendable = onResend && (open || invitation.status === "expired");
-              const revocable = onRevoke && open;
+              const revocable = onRevoke && (open || invitation.status === "expired");
               const scopeText = scopeLabel(invitation.scope);
               const by =
                 typeof invitation.invited_by === "string" ? invitation.invited_by : nameOf(invitation.invited_by);

package/src/auth/auth-errors.ts

@@ -64,8 +64,31 @@ export type AccountErrorCode =
   | "confirmation_mismatch"
   | "password_incorrect";
 
-/** Every code the kit reads: the sign-in refusals and the account ones (0.30.0). */
-export type KitErrorCode = AuthErrorCode | AccountErrorCode;
+/**
+ * 0.31.0: the demo's coded refusals (docs/landing-demo-harmonization.md §6.2) —
+ * server-kit 0.5's `DemoErrorCode`, value for value, answered as `{detail, code}` like
+ * the others and read by the same {@link authErrorCode}.
+ *
+ * - `demo_disabled` — `404`: the demo switch is off (it is "not there", not forbidden).
+ * - `demo_rate_limited` — `429` with `Retry-After`: the per-IP window of demo starts.
+ * - `demo_capacity` — `429`, no `Retry-After`: the cap of live demo users.
+ * - `demo_not_ready` — `503`: the demo data has not been seeded yet.
+ * - `demo_read_only` — `403`, model R: any write by a demo user. The app's write lock
+ *   already explains it, so it shows no toast (§5.4).
+ * - `demo_refused` — `403`, both models: an action a demo never may — a way in or out,
+ *   mail, uploads, the account export (§6.4).
+ */
+export type DemoErrorCode =
+  | "demo_disabled"
+  | "demo_rate_limited"
+  | "demo_capacity"
+  | "demo_not_ready"
+  | "demo_read_only"
+  | "demo_refused";
+
+/** Every code the kit reads: the sign-in refusals, the account ones (0.30.0) and the
+ *  demo's (0.31.0). */
+export type KitErrorCode = AuthErrorCode | AccountErrorCode | DemoErrorCode;
 
 const CODES: ReadonlySet<string> = new Set<KitErrorCode>([
   "invalid_credentials",
@@ -83,6 +106,12 @@ const CODES: ReadonlySet<string> = new Set<KitErrorCode>([
   "confirmation_required",
   "confirmation_mismatch",
   "password_incorrect",
+  "demo_disabled",
+  "demo_rate_limited",
+  "demo_capacity",
+  "demo_not_ready",
+  "demo_read_only",
+  "demo_refused",
 ]);
 
 type Bag = Record<string, unknown>;
@@ -102,8 +131,9 @@ function codeOfBody(body: unknown): KitErrorCode | undefined {
 }
 
 /**
- * The code an error carries — an {@link AuthErrorCode}, or since 0.30.0 an
- * {@link AccountErrorCode} — or `undefined` when it carries none.
+ * The code an error carries — an {@link AuthErrorCode}, since 0.30.0 an
+ * {@link AccountErrorCode}, since 0.31.0 a {@link DemoErrorCode} — or `undefined` when it
+ * carries none.
  *
  * Reads the parsed response body wherever the apps' HTTP clients put it, without
  * depending on any of them:
@@ -142,7 +172,8 @@ export function authErrorCode(err: unknown): KitErrorCode | undefined {
  * The kit's `SignInForm` and `RegisterForm` call it on what their callbacks reject
  * with, so an app's `onSubmit` can simply let its client's error through. See
  * {@link authErrorCode} for the shapes it reads. Since 0.30.0 it knows the account codes
- * too: `isAuthError(err, "last_admin")`.
+ * too: `isAuthError(err, "last_admin")`; since 0.31.0 the demo's:
+ * `isAuthError(err, "demo_read_only")`.
  */
 export function isAuthError(err: unknown, code?: KitErrorCode): boolean {
   const found = authErrorCode(err);

package/src/auth/sign-in-form.tsx

@@ -10,6 +10,9 @@ import { CurrentPasswordInput } from "../components/danger-confirm";
 import { OneTimeCodeInput } from "../components/one-time-code-input";
 import { TextLink } from "../components/text-link";
 import { Button, Input } from "../components/ui";
+import { accessAction } from "../landing/access";
+import type { AccessChoice } from "../landing/access";
+import { useLandingLabels } from "../landing/landing-labels";
 import { authErrorCode, englishRateLimited, isRateLimited, retryAfterSeconds } from "./auth-errors";
 import type { KitErrorCode } from "./auth-errors";
 import { taggedEmail } from "./email-tag";
@@ -171,6 +174,9 @@ export interface SignInLabels {
    *  wait its `Retry-After` asks for, in seconds ({@link retryAfterSeconds}), or
    *  `undefined` (or `0`) without one. */
   rateLimited?: (seconds?: number) => string;
+  /** 0.31.0: the link after `noAccount` for an invitation-only app (`access` of kind
+   *  `request`) — a mail to support, in place of `register`. */
+  requestAccess?: string;
 }
 
 /** `Required`: every key, the 0.30 ones included, has its English here. */
@@ -208,6 +214,7 @@ export const DEFAULT_SIGN_IN_LABELS: Required<SignInLabels> = {
   recoveryCodeHint: (length) => `${length} letters and digits. Dashes and spaces don’t matter.`,
   recoveryCodeInvalid: "This backup code is not valid, or it has been used already.",
   rateLimited: englishRateLimited,
+  requestAccess: "Request access",
 };
 
 /* ── Props ───────────────────────────────────────────────────────────────── */
@@ -252,6 +259,15 @@ export interface SignInFormProps extends Omit<ComponentPropsWithoutRef<"div">, "
   forgotHref?: string;
   /** "No account yet? Create account" goes here — `/register`. Left out, no line. */
   registerHref?: string;
+  /**
+   * 0.31.0 (docs/landing-demo-harmonization.md §4.2): how a visitor gets an account —
+   * the same value the landing's `PublicHeader` and `Hero` take. `{kind: "request",
+   * email}` turns the line into "No account yet? Request access", a mail to support with
+   * the subject and body of `accessAction` (every app is invitation-only); `{kind:
+   * "register", href}` keeps "Create account", to `href`. Wins over `registerHref`; left
+   * out, `registerHref` works as before.
+   */
+  access?: AccessChoice;
   /** The email field's start value — the reset page ends on "Sign in" with the address
    *  filled in (§6.3). */
   defaultEmail?: string;
@@ -408,6 +424,7 @@ export function SignInForm({
   passkeyAutofill,
   forgotHref,
   registerHref,
+  access,
   defaultEmail = "",
   emailTag,
   deactivatedContact,
@@ -424,6 +441,20 @@ export function SignInForm({
   ...rest
 }: SignInFormProps) {
   const labels = useKitLabels("signIn", DEFAULT_SIGN_IN_LABELS, labelsProp);
+  // The mail's subject and body are the landing's words (`landing` namespace), so the
+  // request reads the same from every page that offers it.
+  const landing = useLandingLabels();
+  const accountLink =
+    access === undefined
+      ? registerHref === undefined
+        ? null
+        : { href: registerHref, label: labels.register }
+      : access.kind === "register"
+        ? { href: access.href, label: labels.register }
+        : {
+            href: accessAction(access, landing).href,
+            label: labels.requestAccess ?? DEFAULT_SIGN_IN_LABELS.requestAccess,
+          };
   const [step, setStep] = useState<SignInStep>("credentials");
   const [email, setEmail] = useState(defaultEmail);
   const [password, setPassword] = useState("");
@@ -834,11 +865,11 @@ export function SignInForm({
           </TextLink>
         </p>
       )}
-      {registerHref !== undefined && (
+      {accountLink !== null && (
         <p className="text-center text-sm text-[var(--text-secondary)]">
           {labels.noAccount}{" "}
-          <TextLink href={registerHref} tone="primary">
-            {labels.register}
+          <TextLink href={accountLink.href} tone="primary">
+            {accountLink.label}
           </TextLink>
         </p>
       )}

package/src/components/account-settings-labels.ts

@@ -46,6 +46,12 @@ export interface PasswordSettingLabels {
 }
 
 export interface TwoFactorSettingLabels {
+  /**
+   * Before 0.31 the card's one line, "<status>: On". Since 0.31 the setting's name is the
+   * card's {@link title} and the state stands beside it, so this is read only where no
+   * `title` is given at the same level — an app that translated `status` keeps its word
+   * as the title.
+   */
   status: string;
   enabledText: string;
   disabledText: string;
@@ -70,6 +76,12 @@ export interface TwoFactorSettingLabels {
   secretHint?: string;
   /** The copy button beside that key. */
   copySecret?: string;
+  /**
+   * 0.31.0 (docs/settings-harmonization.md §3.7): the card's title, a heading inside a
+   * `SettingsLayout`. OPTIONAL for the reason `qrAlt` is. Unset, the same source's
+   * `status` stands in for it, then English.
+   */
+  title?: string;
 }
 
 export interface PasskeysSettingLabels {
@@ -160,6 +172,7 @@ export const DEFAULT_ACCOUNT_SETTINGS_LABELS: AccountSettingsLabels = {
     qrAlt: "QR code",
     secretHint: "Can’t scan it? Enter this key in the app instead:",
     copySecret: "Copy key",
+    title: "Two-factor authentication",
   },
   passkeys: {
     title: "Passkeys",

package/src/components/account-settings.tsx

@@ -13,8 +13,10 @@ import {
   PasswordStrengthMeter,
 } from "./password-strength";
 import type { PasswordStrengthMeterProps } from "./password-strength";
-import { DEFAULT_COMMON_LABELS, useKitLabels } from "../i18n/kit-labels";
+import { useKitLabelOverrides, useKitLabels } from "../i18n/kit-labels";
+import { Chip } from "./chip";
 import { useAccountSettingsLabels } from "./account-settings-labels";
+import { SettingsCardTitle } from "../settings/settings-heading";
 import type {
   PasswordSettingLabels,
   ProfileSettingLabels,
@@ -59,6 +61,8 @@ interface ProfileSettingCommonProps {
   saving?: boolean;
   /** Prop > `<UiKitProvider labels={{ accountSettings: { profile } }}>` > English. */
   labels?: Partial<ProfileSettingLabels>;
+  /** The card's DOM id — a settings catalogue `anchor`, so `?focus=` can ring it (0.31). */
+  id?: string;
 }
 
 /**
@@ -114,11 +118,11 @@ export type ProfileSettingProps = ProfileSettingDisplayNameProps | ProfileSettin
  * blank, and is a `commit` (a {@link WriteLockProvider} locks it, keksdose's demo).
  */
 export function ProfileSetting(props: ProfileSettingProps) {
-  const { name, email, role, memberSince, labels: labelsProp } = props;
+  const { name, email, role, memberSince, labels: labelsProp, id } = props;
   const labels = useAccountSettingsLabels("profile", labelsProp);
   const names = props.firstName !== undefined || props.lastName !== undefined;
   return (
-    <Card className="p-4 space-y-3">
+    <Card id={id} className="p-4 space-y-3">
       <div className="flex items-center gap-3">
         <UserAvatar
           name={name}
@@ -127,7 +131,9 @@ export function ProfileSetting(props: ProfileSettingProps) {
           size="lg"
         />
         <div className="min-w-0">
-          <div className="text-sm font-medium">{labels.title}</div>
+          {/* A heading inside a SettingsLayout (0.31, docs/settings-harmonization.md
+              §3.7), the plain div it always was outside one. */}
+          <SettingsCardTitle>{labels.title}</SettingsCardTitle>
           <div className="truncate font-mono text-xs text-[var(--text-muted)]">
             {/* `email` was a required key that nothing rendered; it names the address
                 for a screen reader, which otherwise hears a bare string under a title. */}
@@ -293,6 +299,7 @@ export function PasswordSetting({
   strength,
   maxBytes,
   labels: labelsProp,
+  id,
 }: {
   /** Called with the validated (current, new) pair; return a promise to auto-clear on success. */
   onSubmit: (currentPassword: string, newPassword: string) => void | Promise<unknown>;
@@ -323,6 +330,8 @@ export function PasswordSetting({
   maxBytes?: number;
   /** Prop > `<UiKitProvider labels={{ accountSettings: { password } }}>` > English. */
   labels?: Partial<PasswordSettingLabels>;
+  /** The card's DOM id — a settings catalogue `anchor`, so `?focus=` can ring it (0.31). */
+  id?: string;
 }) {
   const labels = useAccountSettingsLabels("password", labelsProp);
   const strengthOptions = typeof strength === "object" ? strength : undefined;
@@ -365,8 +374,8 @@ export function PasswordSetting({
   );
 
   return (
-    <Card className="p-4 space-y-3">
-      <div className="text-sm font-medium">{labels.title}</div>
+    <Card id={id} className="p-4 space-y-3">
+      <SettingsCardTitle>{labels.title}</SettingsCardTitle>
       <Input type="password" autoComplete="current-password" label={labels.current} value={current} onChange={(e) => setCurrent(e.target.value)} />
       {strength ? (
         // One box for the field and its meter, so the card's `space-y-3` spaces the pair
@@ -433,6 +442,7 @@ export function TwoFactorSetting({
   busy,
   renderQr,
   labels: labelsProp,
+  id,
 }: {
   enabled: boolean;
   /** What the app's setup call returned; null before setup starts. */
@@ -446,8 +456,16 @@ export function TwoFactorSetting({
   renderQr?: (otpauthUri: string) => ReactNode;
   /** Prop > `<UiKitProvider labels={{ accountSettings: { twoFactor } }}>` > English. */
   labels?: Partial<TwoFactorSettingLabels>;
+  /** The card's DOM id — a settings catalogue `anchor`, so `?focus=` can ring it (0.31). */
+  id?: string;
 }) {
   const labels = useAccountSettingsLabels("twoFactor", labelsProp);
+  // The title (0.31, docs/settings-harmonization.md §3.7) is new, and an app that
+  // translated this card before it named the setting in `status` — "2FA",
+  // "Zwei-Faktor-Authentifizierung". Each source's `title` first, then its `status`, so
+  // that app keeps its own word instead of meeting the English title.
+  const overrides = useKitLabelOverrides("accountSettings")?.twoFactor;
+  const title = labelsProp?.title ?? overrides?.title ?? labelsProp?.status ?? overrides?.status ?? labels.title;
   const [code, setCode] = useState("");
   const [password, setPassword] = useState("");
   // Both code fields are a OneTimeCodeInput (0.22.0) — the field this card wrote by hand
@@ -461,17 +479,20 @@ export function TwoFactorSetting({
   //    pasted from an authenticator that groups its digits used to reach `onEnable`
   //    with the space in it.
   //  - one `code` state for both, as before.
-  // Only for the "Status: Enabled" composition — the punctuation between a field's
-  // name and its value is the language's (see `CommonLabels.fieldValue`).
-  const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
   const secret = setup
     ? (setup.secret ?? ("otpauthUri" in setup ? otpauthSecret(setup.otpauthUri) : null))
     : null;
 
   return (
-    <Card className="p-4 space-y-3">
-      <div className="text-sm">
-        {common.fieldValue(labels.status, enabled ? labels.enabledText : labels.disabledText)}
+    <Card id={id} className="p-4 space-y-3">
+      {/* The card had only "Two-factor authentication: Off". A settings page outlines its
+          cards by their titles (§3.7), so the setting's name is the title now, and the
+          state stands beside it as a chip instead of repeating the name. */}
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <SettingsCardTitle>{title}</SettingsCardTitle>
+        <Chip size="sm" tone={enabled ? "success" : "neutral"}>
+          {enabled ? labels.enabledText : labels.disabledText}
+        </Chip>
       </div>
 
       {!enabled && !setup && (

package/src/components/data-table.tsx

@@ -1725,6 +1725,14 @@ export function DataTable<T>({
       // flip stays instant.
       interactive &&
         "cursor-pointer transition-transform duration-100 active:scale-[0.995] active:bg-[var(--bg-active)] motion-reduce:transition-none motion-reduce:active:scale-100",
+      // The keyboard's frame drawn INSIDE the card, as the desktop row's is (keksdose live
+      // #394): the browser's own ring and tap highlight sit on the card's outer edge, and
+      // three ancestors clip it — SwipeableRow's `overflow-hidden`, the card list, and
+      // AppShell main's `overflow-x-clip` — so the frame went missing on one side. A press
+      // keeps the fill and the squeeze above; an outline on every tap of a long list would
+      // be louder than the acknowledgement it replaces.
+      interactive &&
+        "[-webkit-tap-highlight-color:transparent] focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-[var(--brand)]",
     );
     // The card's content is written once and worn by either tag below. Note that
     // the primary cell is rendered RAW here, never through `linkColumn` — the card

package/src/components/date-picker.tsx

@@ -588,9 +588,6 @@ function StepButton({
           // px-3 would make it wider than it needs to be. twMerge lets these win.
           "relative flex h-full w-10 shrink-0 items-center justify-center px-0 text-[var(--text-muted)]",
           "hover:bg-[var(--bg-hover)] hover:text-[var(--text-secondary)]",
-          // Raised while hovered or focused, so the shared border and the focus ring are
-          // drawn on top of the neighbour they overlap by a pixel.
-          "hover:z-10 focus-visible:z-10",
           // Dimmed ICON, not a dimmed box: at 40% opacity the whole button — border
           // included — faded out of the group and read as a broken, detached control.
           "disabled:cursor-not-allowed disabled:text-[var(--text-placeholder)] disabled:opacity-60 disabled:hover:bg-[var(--bg-surface)]",
@@ -1164,7 +1161,15 @@ export function DatePicker(props: DatePickerProps) {
         "flex items-stretch [&>*:not(:first-child)]:-ms-px",
         step && "[&_[role=combobox]]:rounded-s-none",
         (step || today) && "[&_[role=combobox]]:rounded-e-none",
-        "[&_[role=combobox]:focus-visible]:relative [&_[role=combobox]:focus-visible]:z-10",
+        // The PART that is focused, pressed or invalid is raised over the neighbour it
+        // overlaps by a pixel, so its blue (or red) border shows on all four sides
+        // (keksdose live #394). `:focus-within`, not `:focus-visible`: a tap focuses
+        // without it, as does the sheet handing focus back, and the next part — later in
+        // the DOM — painted its grey left edge over the tapped one's right. Raising the
+        // whole part (each is `relative`) keeps the floating label and the icon above
+        // the trigger, which raising the trigger alone covered. Hover raises nothing: it
+        // changes no border, and would let a hovered › cover a focused field's edge.
+        "[&>*:focus-within]:z-20 [&>*:active]:z-20 [&>*:has([aria-invalid=true])]:z-10",
         className,
       )}
     >

package/src/components/passkeys-setting.tsx

@@ -6,6 +6,7 @@ import { useKitLocale } from "../i18n/kit-labels";
 import { Button, Card, EmptyState, Input } from "./ui";
 import { Skeleton } from "./skeleton";
 import { useAccountSettingsLabels } from "./account-settings-labels";
+import { SettingsCardTitle } from "../settings/settings-heading";
 import type { PasskeysSettingLabels } from "./account-settings-labels";
 
 /** What a passkey's `id` may be: the app's own key type, string or numeric. */
@@ -243,7 +244,7 @@ export function PasskeysSetting<Id extends PasskeyId = PasskeyId>({
     // `rest` is only `id` and `data-*`: everything else the props name is destructured.
     <Card {...rest} className={cn("p-4 space-y-3", className)}>
       <div>
-        <div className="text-sm font-medium">{labels.title}</div>
+        <SettingsCardTitle>{labels.title}</SettingsCardTitle>
         <div className="text-xs text-[var(--text-muted)]">
           {mode === "alongside"
             ? labels.descriptionAlongside

package/src/components/settings-fields.tsx

@@ -1,6 +1,8 @@
 import type { ReactNode } from "react";
 import { Select } from "./ui";
 import type { SelectProps } from "./ui";
+import { ToggleGroup } from "./toggle-group";
+import type { ToggleGroupBaseProps } from "./toggle-group";
 import type { ThemePreference } from "../theme/theme-store";
 
 /**
@@ -20,6 +22,8 @@ import type { ThemePreference } from "../theme/theme-store";
  */
 export interface ThemeSettingProps
   extends Omit<SelectProps, "value" | "onChange" | "children"> {
+  /** The `Select` (default). See {@link ThemeSettingToggleProps} for `"toggle"`. */
+  variant?: "select";
   value: ThemePreference;
   onChange: (value: ThemePreference) => void;
   label: ReactNode;
@@ -28,7 +32,52 @@ export interface ThemeSettingProps
   id?: string;
 }
 
-export function ThemeSetting({ value, onChange, label, optionLabels, id, ...rest }: ThemeSettingProps) {
+/**
+ * `variant="toggle"` (0.31.0, docs/settings-harmonization.md §2.8): the three choices as
+ * one segmented control instead of a select — system, light and dark side by side, the
+ * choice visible without opening anything, in every app (keksdose offered light and dark
+ * only; its store already knew "system"). A {@link ToggleGroup}'s props pass through —
+ * `labelPlacement`, `disabledReason`, `commit`, `size` — minus the options and the value,
+ * which this owns.
+ *
+ * Bind it to the PREFERENCE (`"system"` included), never to the resolved mode: on a
+ * system-dark device a control bound to the mode shows "dark" and cannot say "follow the
+ * system" (keksdose's control, §8).
+ */
+export interface ThemeSettingToggleProps
+  extends Omit<ToggleGroupBaseProps<ThemePreference>, "options" | "label" | "ariaLabel"> {
+  variant: "toggle";
+  value: ThemePreference;
+  onChange: (value: ThemePreference) => void;
+  /**
+   * Names the group: the field's label, or the label above it (`labelPlacement`). Leave
+   * it out inside a card already titled "Theme" and name the group with `aria-label` or
+   * `aria-labelledby` instead, so the card does not say "Theme" twice.
+   */
+  label?: ReactNode;
+  /** Translated option labels. */
+  optionLabels: { system: string; light: string; dark: string };
+  id?: string;
+}
+
+export function ThemeSetting(props: ThemeSettingProps | ThemeSettingToggleProps) {
+  if (props.variant === "toggle") {
+    const { variant: _variant, value, onChange, label, optionLabels, ...rest } = props;
+    return (
+      <ToggleGroup<ThemePreference>
+        {...rest}
+        label={label}
+        value={value}
+        onChange={onChange}
+        options={[
+          { value: "system", label: optionLabels.system },
+          { value: "light", label: optionLabels.light },
+          { value: "dark", label: optionLabels.dark },
+        ]}
+      />
+    );
+  }
+  const { variant: _variant, value, onChange, label, optionLabels, id, ...rest } = props;
   return (
     <Select
       {...rest}