@eifi1/ui-kit 0.35.0 → 0.36.0

package/dist/theme/theme-store.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/theme/theme-store.ts"],"sourcesContent":["import { useEffect } from \"react\";\nimport { create } from \"zustand\";\nimport { persist } from \"zustand/middleware\";\nimport { logger } from \"../lib/logger\";\n\nexport type ThemeMode = \"light\" | \"dark\";\n/** What the user chose; \"system\" tracks the OS `prefers-color-scheme`. */\nexport type ThemePreference = \"light\" | \"dark\" | \"system\";\n\nexport interface ThemeState {\n  /** The user's choice (persisted). */\n  preference: ThemePreference;\n  /** The RESOLVED light/dark actually in effect (system → OS). Read this for\n   *  anything that needs the concrete theme (e.g. token selection, toasts). */\n  mode: ThemeMode;\n  setPreference: (preference: ThemePreference) => void;\n  /** Set an explicit light/dark choice (preference follows). */\n  setMode: (mode: ThemeMode) => void;\n  /** Flip the effective theme to the opposite explicit choice. */\n  toggle: () => void;\n}\n\nfunction systemPreference(): ThemeMode {\n  try {\n    return window.matchMedia(\"(prefers-color-scheme: dark)\").matches ? \"dark\" : \"light\";\n  } catch {\n    return \"light\";\n  }\n}\n\nfunction resolve(preference: ThemePreference): ThemeMode {\n  return preference === \"system\" ? systemPreference() : preference;\n}\n\n/** Normalize a persisted theme-state blob to a valid preference. Older blobs\n *  persisted the concrete `mode` (light/dark); carry that over as an explicit\n *  preference so the choice survives. Shared by the store's `migrate` and the\n *  pre-hydration {@link applyPersistedTheme}. */\nfunction preferenceFromState(\n  s: { mode?: string; preference?: string } | null | undefined,\n): ThemePreference {\n  if (s?.preference === \"light\" || s?.preference === \"dark\" || s?.preference === \"system\") {\n    return s.preference;\n  }\n  if (s?.mode === \"light\" || s?.mode === \"dark\") return s.mode;\n  return \"system\";\n}\n\n/** Toggle the `.dark` class on <html> for a resolved light/dark mode. */\nfunction applyThemeClass(mode: ThemeMode): void {\n  const root = document.documentElement;\n  if (mode === \"dark\") root.classList.add(\"dark\");\n  else root.classList.remove(\"dark\");\n}\n\n/**\n * Pre-hydration: read the theme PREFERENCE persisted under `storageKey` straight\n * from localStorage, resolve it to a concrete light/dark mode, and toggle the\n * `.dark` class on <html> — BEFORE React and the store mount, so the first paint\n * already has the right theme (no flash). Returns the resolved mode so the caller\n * can chain {@link applyPersistedPalette}. Encapsulates the zustand-persist\n * envelope + the legacy `mode`→`preference` fallback so apps never re-type the\n * storage shape in their entrypoint.\n */\nexport function applyPersistedTheme(storageKey: string): ThemeMode {\n  let preference: ThemePreference = \"system\";\n  try {\n    const blob = JSON.parse(localStorage.getItem(storageKey) ?? \"{}\") as {\n      state?: { mode?: string; preference?: string };\n    };\n    preference = preferenceFromState(blob.state);\n  } catch {\n    /* malformed storage → system */\n  }\n  const mode = resolve(preference);\n  applyThemeClass(mode);\n  return mode;\n}\n\n/**\n * Build a theme store bound to a consumer-supplied localStorage key. Tracks a\n * light/dark/system PREFERENCE (feedback #330) and exposes the resolved `mode`.\n * Returns the `useTheme` hook plus a `useApplyTheme` effect that toggles the\n * `.dark` class on <html> and, while on \"system\", follows OS theme changes live.\n */\nexport function createThemeStore(storageKey: string) {\n  const useTheme = create<ThemeState>()(\n    logger(\n      persist(\n        (set, get) => ({\n          preference: \"system\" as ThemePreference,\n          mode: systemPreference(),\n          setPreference: (preference) => set({ preference, mode: resolve(preference) }),\n          setMode: (mode) => set({ preference: mode, mode }),\n          toggle: () => {\n            const next: ThemeMode = get().mode === \"dark\" ? \"light\" : \"dark\";\n            set({ preference: next, mode: next });\n          },\n        }),\n        {\n          name: storageKey,\n          version: 2,\n          // Only the preference is persisted; `mode` is derived on load.\n          partialize: (s) => ({ preference: s.preference }),\n          migrate: (persistedState): { preference: ThemePreference } => ({\n            preference: preferenceFromState(\n              persistedState as { mode?: string; preference?: string } | null,\n            ),\n          }),\n          onRehydrateStorage: () => (state) => {\n            // The persisted preference decides the concrete mode at load.\n            if (state) state.mode = resolve(state.preference);\n          },\n        },\n      ),\n      \"theme\",\n    ),\n  );\n\n  function useApplyTheme(): void {\n    const mode = useTheme((s) => s.mode);\n    const preference = useTheme((s) => s.preference);\n    useEffect(() => {\n      applyThemeClass(mode);\n    }, [mode]);\n    // While tracking the system, follow OS theme changes live.\n    useEffect(() => {\n      if (preference !== \"system\") return;\n      let mq: MediaQueryList;\n      try {\n        mq = window.matchMedia(\"(prefers-color-scheme: dark)\");\n      } catch {\n        return;\n      }\n      const onChange = () => useTheme.setState({ mode: mq.matches ? \"dark\" : \"light\" });\n      onChange();\n      mq.addEventListener?.(\"change\", onChange);\n      return () => mq.removeEventListener?.(\"change\", onChange);\n    }, [preference]);\n  }\n\n  return { useTheme, useApplyTheme };\n}\n\nexport type ThemeStore = ReturnType<typeof createThemeStore>;\n"],"mappings":";AAAA,SAAS,iBAAiB;AAC1B,SAAS,cAAc;AACvB,SAAS,eAAe;AACxB,SAAS,cAAc;AAmBvB,SAAS,mBAA8B;AACrC,MAAI;AACF,WAAO,OAAO,WAAW,8BAA8B,EAAE,UAAU,SAAS;AAAA,EAC9E,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEA,SAAS,QAAQ,YAAwC;AACvD,SAAO,eAAe,WAAW,iBAAiB,IAAI;AACxD;AAMA,SAAS,oBACP,GACiB;AACjB,MAAI,GAAG,eAAe,WAAW,GAAG,eAAe,UAAU,GAAG,eAAe,UAAU;AACvF,WAAO,EAAE;AAAA,EACX;AACA,MAAI,GAAG,SAAS,WAAW,GAAG,SAAS,OAAQ,QAAO,EAAE;AACxD,SAAO;AACT;AAGA,SAAS,gBAAgB,MAAuB;AAC9C,QAAM,OAAO,SAAS;AACtB,MAAI,SAAS,OAAQ,MAAK,UAAU,IAAI,MAAM;AAAA,MACzC,MAAK,UAAU,OAAO,MAAM;AACnC;AAWO,SAAS,oBAAoB,YAA+B;AACjE,MAAI,aAA8B;AAClC,MAAI;AACF,UAAM,OAAO,KAAK,MAAM,aAAa,QAAQ,UAAU,KAAK,IAAI;AAGhE,iBAAa,oBAAoB,KAAK,KAAK;AAAA,EAC7C,QAAQ;AAAA,EAER;AACA,QAAM,OAAO,QAAQ,UAAU;AAC/B,kBAAgB,IAAI;AACpB,SAAO;AACT;AAQO,SAAS,iBAAiB,YAAoB;AACnD,QAAM,WAAW,OAAmB;AAAA,IAClC;AAAA,MACE;AAAA,QACE,CAAC,KAAK,SAAS;AAAA,UACb,YAAY;AAAA,UACZ,MAAM,iBAAiB;AAAA,UACvB,eAAe,CAAC,eAAe,IAAI,EAAE,YAAY,MAAM,QAAQ,UAAU,EAAE,CAAC;AAAA,UAC5E,SAAS,CAAC,SAAS,IAAI,EAAE,YAAY,MAAM,KAAK,CAAC;AAAA,UACjD,QAAQ,MAAM;AACZ,kBAAM,OAAkB,IAAI,EAAE,SAAS,SAAS,UAAU;AAC1D,gBAAI,EAAE,YAAY,MAAM,MAAM,KAAK,CAAC;AAAA,UACtC;AAAA,QACF;AAAA,QACA;AAAA,UACE,MAAM;AAAA,UACN,SAAS;AAAA;AAAA,UAET,YAAY,CAAC,OAAO,EAAE,YAAY,EAAE,WAAW;AAAA,UAC/C,SAAS,CAAC,oBAAqD;AAAA,YAC7D,YAAY;AAAA,cACV;AAAA,YACF;AAAA,UACF;AAAA,UACA,oBAAoB,MAAM,CAAC,UAAU;AAEnC,gBAAI,MAAO,OAAM,OAAO,QAAQ,MAAM,UAAU;AAAA,UAClD;AAAA,QACF;AAAA,MACF;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAEA,WAAS,gBAAsB;AAC7B,UAAM,OAAO,SAAS,CAAC,MAAM,EAAE,IAAI;AACnC,UAAM,aAAa,SAAS,CAAC,MAAM,EAAE,UAAU;AAC/C,cAAU,MAAM;AACd,sBAAgB,IAAI;AAAA,IACtB,GAAG,CAAC,IAAI,CAAC;AAET,cAAU,MAAM;AACd,UAAI,eAAe,SAAU;AAC7B,UAAI;AACJ,UAAI;AACF,aAAK,OAAO,WAAW,8BAA8B;AAAA,MACvD,QAAQ;AACN;AAAA,MACF;AACA,YAAM,WAAW,MAAM,SAAS,SAAS,EAAE,MAAM,GAAG,UAAU,SAAS,QAAQ,CAAC;AAChF,eAAS;AACT,SAAG,mBAAmB,UAAU,QAAQ;AACxC,aAAO,MAAM,GAAG,sBAAsB,UAAU,QAAQ;AAAA,IAC1D,GAAG,CAAC,UAAU,CAAC;AAAA,EACjB;AAEA,SAAO,EAAE,UAAU,cAAc;AACnC;","names":[]}
+{"version":3,"sources":["../../src/theme/theme-store.ts"],"sourcesContent":["import { useEffect } from \"react\";\nimport { create } from \"zustand\";\nimport { persist } from \"zustand/middleware\";\nimport { logger } from \"../lib/logger\";\nimport { registerDeviceSetting } from \"../lib/device-settings\";\n\nexport type ThemeMode = \"light\" | \"dark\";\n/** What the user chose; \"system\" tracks the OS `prefers-color-scheme`. */\nexport type ThemePreference = \"light\" | \"dark\" | \"system\";\n\nexport interface ThemeState {\n  /** The user's choice (persisted). */\n  preference: ThemePreference;\n  /** The RESOLVED light/dark actually in effect (system → OS). Read this for\n   *  anything that needs the concrete theme (e.g. token selection, toasts). */\n  mode: ThemeMode;\n  setPreference: (preference: ThemePreference) => void;\n  /** Set an explicit light/dark choice (preference follows). */\n  setMode: (mode: ThemeMode) => void;\n  /** Flip the effective theme to the opposite explicit choice. */\n  toggle: () => void;\n}\n\nfunction systemPreference(): ThemeMode {\n  try {\n    return window.matchMedia(\"(prefers-color-scheme: dark)\").matches ? \"dark\" : \"light\";\n  } catch {\n    return \"light\";\n  }\n}\n\nfunction resolve(preference: ThemePreference): ThemeMode {\n  return preference === \"system\" ? systemPreference() : preference;\n}\n\n/** Normalize a persisted theme-state blob to a valid preference. Older blobs\n *  persisted the concrete `mode` (light/dark); carry that over as an explicit\n *  preference so the choice survives. Shared by the store's `migrate` and the\n *  pre-hydration {@link applyPersistedTheme}. */\nfunction preferenceFromState(\n  s: { mode?: string; preference?: string } | null | undefined,\n): ThemePreference {\n  if (s?.preference === \"light\" || s?.preference === \"dark\" || s?.preference === \"system\") {\n    return s.preference;\n  }\n  if (s?.mode === \"light\" || s?.mode === \"dark\") return s.mode;\n  return \"system\";\n}\n\n/** Toggle the `.dark` class on <html> for a resolved light/dark mode. */\nfunction applyThemeClass(mode: ThemeMode): void {\n  const root = document.documentElement;\n  if (mode === \"dark\") root.classList.add(\"dark\");\n  else root.classList.remove(\"dark\");\n}\n\n/**\n * Pre-hydration: read the theme PREFERENCE persisted under `storageKey` straight\n * from localStorage, resolve it to a concrete light/dark mode, and toggle the\n * `.dark` class on <html> — BEFORE React and the store mount, so the first paint\n * already has the right theme (no flash). Returns the resolved mode so the caller\n * can chain {@link applyPersistedPalette}. Encapsulates the zustand-persist\n * envelope + the legacy `mode`→`preference` fallback so apps never re-type the\n * storage shape in their entrypoint.\n */\nexport function applyPersistedTheme(storageKey: string): ThemeMode {\n  let preference: ThemePreference = \"system\";\n  try {\n    const blob = JSON.parse(localStorage.getItem(storageKey) ?? \"{}\") as {\n      state?: { mode?: string; preference?: string };\n    };\n    preference = preferenceFromState(blob.state);\n  } catch {\n    /* malformed storage → system */\n  }\n  const mode = resolve(preference);\n  applyThemeClass(mode);\n  return mode;\n}\n\n/**\n * Build a theme store bound to a consumer-supplied localStorage key. Tracks a\n * light/dark/system PREFERENCE (feedback #330) and exposes the resolved `mode`.\n * Returns the `useTheme` hook plus a `useApplyTheme` effect that toggles the\n * `.dark` class on <html> and, while on \"system\", follows OS theme changes live.\n */\nexport function createThemeStore(storageKey: string) {\n  const useTheme = create<ThemeState>()(\n    logger(\n      persist(\n        (set, get) => ({\n          preference: \"system\" as ThemePreference,\n          mode: systemPreference(),\n          setPreference: (preference) => set({ preference, mode: resolve(preference) }),\n          setMode: (mode) => set({ preference: mode, mode }),\n          toggle: () => {\n            const next: ThemeMode = get().mode === \"dark\" ? \"light\" : \"dark\";\n            set({ preference: next, mode: next });\n          },\n        }),\n        {\n          name: storageKey,\n          version: 2,\n          // Only the preference is persisted; `mode` is derived on load.\n          partialize: (s) => ({ preference: s.preference }),\n          migrate: (persistedState): { preference: ThemePreference } => ({\n            preference: preferenceFromState(\n              persistedState as { mode?: string; preference?: string } | null,\n            ),\n          }),\n          onRehydrateStorage: () => (state) => {\n            // The persisted preference decides the concrete mode at load.\n            if (state) state.mode = resolve(state.preference);\n          },\n        },\n      ),\n      \"theme\",\n    ),\n  );\n  // Reset this device's settings (docs/settings-harmonization.md §11.4): back to\n  // \"System\" through the setter, which re-resolves `mode`; `useApplyTheme` puts the\n  // class back and follows the OS again, and the persisted blob is what the pre-paint\n  // `applyPersistedTheme` reads next load.\n  registerDeviceSetting({\n    key: storageKey,\n    kind: \"appearance\",\n    reset: () => useTheme.getState().setPreference(\"system\"),\n  });\n\n  function useApplyTheme(): void {\n    const mode = useTheme((s) => s.mode);\n    const preference = useTheme((s) => s.preference);\n    useEffect(() => {\n      applyThemeClass(mode);\n    }, [mode]);\n    // While tracking the system, follow OS theme changes live.\n    useEffect(() => {\n      if (preference !== \"system\") return;\n      let mq: MediaQueryList;\n      try {\n        mq = window.matchMedia(\"(prefers-color-scheme: dark)\");\n      } catch {\n        return;\n      }\n      const onChange = () => useTheme.setState({ mode: mq.matches ? \"dark\" : \"light\" });\n      onChange();\n      mq.addEventListener?.(\"change\", onChange);\n      return () => mq.removeEventListener?.(\"change\", onChange);\n    }, [preference]);\n  }\n\n  return { useTheme, useApplyTheme };\n}\n\nexport type ThemeStore = ReturnType<typeof createThemeStore>;\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eifi1/ui-kit",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "type": "module",
   "description": "App-agnostic shared design system: domain-free React components, theme and tokens.",
   "_sideEffects": "The barrel (src/index.ts) re-exports EVERY component, including components/chart, which statically imports recharts. Without this field a bundler must assume each of those modules has side effects, so it cannot drop the unused ones: importing a Button from '@eifi1/ui-kit' dragged all 433KB of recharts into the consumer's ENTRY chunk, and Keksdose was preloading it on every page load, login included. Nothing in src/ imports for side effects (no bare imports, no CSS imports from JS, no module-level global writes) — the token stylesheet is its own './tokens.css' export — so this is safe. CSS is still listed so any future stylesheet survives. Re-checked when `flag-icons` left `dependencies` and tsup started emitting a `\"use client\"` banner: neither touches this. The flag stylesheet was never imported from JS in the first place (that was the finding), and a directive prologue is a string literal every bundler lifts out before it decides whether a module is inert.",

package/src/admin/role-select.tsx

@@ -7,6 +7,7 @@ import type { CheckboxGroupOption } from "../components/checkbox-group";
 import { Select } from "../components/select";
 import type { SelectProps } from "../components/select";
 import type { CommitScope } from "../components/write-lock";
+import type { FieldHelpProps } from "../components/field-parts";
 import { DEFAULT_ROLE_SELECT_LABELS } from "./role-select-labels";
 
 /**
@@ -185,7 +186,7 @@ export function RoleSelect<R extends string = string>({
 
 /* ── RolesEditor ────────────────────────────────────────────────────────────── */
 
-export interface RolesEditorProps<R extends string = string> {
+export interface RolesEditorProps<R extends string = string> extends FieldHelpProps {
   /** The roles ticked — the draft the app holds while its dialog is open. */
   value: readonly R[];
   roles: RoleVocabulary<R>;
@@ -236,6 +237,7 @@ export function RolesEditor<R extends string = string>({
   legendVisibility,
   required,
   hint,
+  help,
   error,
   columns,
   commit,
@@ -267,6 +269,7 @@ export function RolesEditor<R extends string = string>({
       onChange={onChange}
       required={required}
       hint={hint}
+      help={help}
       error={error}
       columns={columns}
       commit={commit}

package/src/components/amount-input.tsx

@@ -36,6 +36,7 @@ import {
   LockedReason,
   mergeRefs,
   type DisabledReasonDisplay,
+  type FieldHelpProps,
   type LockReason,
 } from "./field-parts";
 import { useEndWidth, useNumericField } from "./numeric-field";
@@ -43,7 +44,7 @@ import type { CommitScope } from "./write-lock";
 
 /** {@link AmountInput}'s props — exported since 0.34 (refactor audit 2026-10, API-9): a
  *  wrapper typed itself off `ComponentProps<typeof AmountInput>` until then. */
-export interface AmountInputProps {
+export interface AmountInputProps extends FieldHelpProps {
   value: string;
   onChange: (value: string) => void;
   currency?: string;

package/src/components/autocomplete.tsx

@@ -32,6 +32,7 @@ import {
   useFieldHint,
   useLockReason,
   type DisabledReasonDisplay,
+  type FieldHelpProps,
 } from "./field-parts";
 import type { CommitScope } from "./write-lock";
 
@@ -44,7 +45,8 @@ export interface AutocompleteProps<V extends string | number = string>
   extends Omit<
     ComponentPropsWithoutRef<"input">,
     "value" | "defaultValue" | "onChange" | "onSelect" | "children" | "type" | "size"
-  > {
+  >,
+    FieldHelpProps {
   /** What is in the field. Controlled, and never reset by the component: opening,
    *  closing and a failed lookup all leave it exactly as typed. */
   value: string;
@@ -220,6 +222,7 @@ export function Autocomplete<V extends string | number = string>(props: Autocomp
     invalid,
     error,
     hint,
+    help,
     status,
     emptyLabel,
     loadErrorLabel,
@@ -252,7 +255,7 @@ export function Autocomplete<V extends string | number = string>(props: Autocomp
     noResults: emptyLabel,
     loadError: loadErrorLabel,
   });
-  const hintParts = useFieldHint(hint, ariaDescribedBy);
+  const hintParts = useFieldHint(hint, ariaDescribedBy, { help, name: label ?? ariaLabel });
   // A form library's `aria-invalid` paints as well as announces (DUP-8: it only
   // announced, through the spread below).
   const field = useFieldError(error, invalid, hintParts.describedBy, rest["aria-invalid"]);

package/src/components/button-look.ts

@@ -100,8 +100,13 @@ export const buttonVariantClasses: Record<ButtonVariant, string> = {
   // the base's focus ring stays: those copies had `outline-none` and no ring, so
   // a keyboard user tabbing onto them saw nothing at all. `rounded-sm` keeps that
   // ring hugging the word instead of drawing a pill round it.
+  //
+  // Under More contrast the word reads `--brand-muted`, the brand AS TEXT (0.36,
+  // colour-roles §13.3 decision 8): `--brand` is solved as a mark (3:1), and on More
+  // contrast's darker light well Moss's read 3.68:1; the derived dark brands sit at 3.0
+  // as text too. Both modes, since `contrast:` does not split them.
   link:
-    "rounded-sm p-0 bg-transparent text-brand underline-offset-4 hover:underline focus-visible:ring-brand",
+    "rounded-sm p-0 bg-transparent text-brand underline-offset-4 hover:underline focus-visible:ring-brand contrast:text-brand-muted",
 };
 
 /**
@@ -132,11 +137,14 @@ export const buttonVariantClasses: Record<ButtonVariant, string> = {
  */
 export type ButtonTone = "default" | "muted" | "danger";
 
+// `contrast:text-secondary` restates the tone's own colour under the `contrast:` variant,
+// so tailwind-merge drops the link's `contrast:text-brand-muted` (0.36): a quiet link
+// stays quiet under More contrast. On `ghost` it reads the same either way.
 const BUTTON_TONES: Record<Exclude<ButtonTone, "default">, string> = {
   muted:
-    "text-secondary hover:text-primary disabled:hover:text-secondary",
+    "text-secondary hover:text-primary disabled:hover:text-secondary contrast:text-secondary",
   danger:
-    "text-secondary hover:text-danger focus-visible:ring-danger-strong disabled:hover:text-secondary",
+    "text-secondary hover:text-danger focus-visible:ring-danger-strong disabled:hover:text-secondary contrast:text-secondary",
 };
 
 /** Only the two transparent variants take every tone; see {@link ButtonTone}. */
@@ -158,9 +166,11 @@ const BUTTON_BOXED_DANGER: Partial<Record<ButtonVariant, string>> = {
 
 // `pressed` on a `link`: the brand colour and a heavier weight, which is exactly what
 // lenkbank's "All speeds" toggle paints by hand (gear/hysteresis-charts.tsx:482). After
-// the tone, so a pressed muted link is brand, and an unpressed one is quiet grey.
+// the tone, so a pressed muted link is brand, and an unpressed one is quiet grey. Under
+// More contrast the brand as text, `--brand-muted`, at rest and hovered (0.36, as the
+// `link` variant), whatever the tone.
 export const BUTTON_LINK_PRESSED =
-  "font-medium text-brand hover:text-brand disabled:hover:text-brand";
+  "font-medium text-brand hover:text-brand disabled:hover:text-brand contrast:text-brand-muted contrast:hover:text-brand-muted contrast:disabled:hover:text-brand-muted";
 
 /** The second argument of {@link buttonClasses} in its options form. */
 export interface ButtonClassesOptions {

package/src/components/checkbox-group.tsx

@@ -4,7 +4,14 @@ import { cn } from "../lib/cn";
 import { Checkbox } from "./checkbox";
 import { hasContent } from "../lib/presence";
 import { useCommitReason, type CommitScope } from "./write-lock";
-import { FIELD_ERROR_CLASS, mergeDescribedBy, RequiredStarOnLegend, useInlineHint } from "./field-parts";
+import {
+  FIELD_ERROR_CLASS,
+  fieldHelpMark,
+  mergeDescribedBy,
+  RequiredStarOnLegend,
+  useInlineHint,
+  type FieldHelpProps,
+} from "./field-parts";
 
 /** One box of a {@link CheckboxGroup}. */
 export interface CheckboxGroupOption<T extends string = string> {
@@ -22,7 +29,7 @@ export interface CheckboxGroupOption<T extends string = string> {
  *  reader where the dialog's title already says it to the eye. */
 export type CheckboxGroupLegendVisibility = "visible" | "sr-only";
 
-export interface CheckboxGroupProps<T extends string = string> {
+export interface CheckboxGroupProps<T extends string = string> extends FieldHelpProps {
   /** The question the boxes answer — the fieldset's `<legend>`, which names the group.
    *  Without one, pass `aria-label`. */
   legend?: ReactNode;
@@ -64,6 +71,8 @@ export interface CheckboxGroupProps<T extends string = string> {
   /**
    * Standing advice for the group, under the boxes, attached to the fieldset with
    * `aria-describedby` before the error — the field anatomy every kit field keeps.
+   * A `help` beside it (0.36) is a "?" after the legend — with a visible legend only —
+   * and names nothing: the fieldset is then named by the legend's words alone.
    */
   hint?: ReactNode;
   /** What is wrong with the set, in the caller's words. Under the boxes, on the
@@ -128,6 +137,7 @@ export function CheckboxGroup<T extends string = string>({
   disabled,
   required,
   hint,
+  help,
   error,
   invalid,
   commit,
@@ -142,7 +152,11 @@ export function CheckboxGroup<T extends string = string>({
   const errorId = `${generated}-error`;
   // §4: a FieldHint under the group is its words at Large and on a touch screen, not a
   // lone "?" (DUP-2, refactor audit 2026-10). A HelpPopover stays a "?".
-  const shownHint = useInlineHint(hint);
+  // A `help` "?" after a VISIBLE legend (0.36): the label line a group has. Its FieldHint
+  // hint is then its words at every size, as everywhere a help stands beside one.
+  const helpMark = fieldHelpMark(legend !== undefined && legendVisibility === "visible" ? help : undefined, legend);
+  const legendTextId = `${generated}-legend`;
+  const shownHint = useInlineHint(hint, helpMark !== undefined);
   const showHint = hasContent(shownHint);
   const showError = hasContent(error);
   const isInvalid = Boolean(invalid) || showError;
@@ -169,6 +183,9 @@ export function CheckboxGroup<T extends string = string>({
     <fieldset
       id={id}
       aria-label={ariaLabel}
+      // With a help "?" inside the legend, the legend's WORDS name the group: a legend
+      // names its fieldset by its whole content, the "?"'s "About …" included.
+      aria-labelledby={helpMark !== undefined && ariaLabel === undefined ? legendTextId : undefined}
       aria-describedby={mergeDescribedBy(ariaDescribedBy, showHint && hintId, showError && errorId)}
       disabled={disabled && !locked}
       // `relative` holds an `sr-only` legend (sr-only-containment.test); `min-w-0`
@@ -184,12 +201,13 @@ export function CheckboxGroup<T extends string = string>({
               : cn("mb-2 p-0 text-sm font-medium text-primary", (disabled || locked) && "opacity-60")
           }
         >
-          {legend}
+          {helpMark === undefined ? legend : <span id={legendTextId}>{legend}</span>}
           {required && (
             <span aria-hidden className="ms-0.5 text-danger">
               *
             </span>
           )}
+          {helpMark !== undefined && <span className="ms-1 inline-flex align-middle font-normal">{helpMark}</span>}
         </legend>
       )}
       <RequiredStarOnLegend.Provider value={true}>

package/src/components/column-mapper.tsx

@@ -31,6 +31,7 @@ import {
   TableHeaderCell,
   TableRow,
 } from "./table";
+import type { FieldHelpProps } from "./field-parts";
 import { Select } from "./select";
 import { Textarea } from "./textarea";
 import { DEFAULT_COLUMN_MAPPER_LABELS, markedShort } from "./column-mapper-labels";
@@ -425,7 +426,7 @@ export function ColumnRoleTable<
 
 // ── ColumnMapper ──────────────────────────────────────────────────────────────
 
-export interface ColumnMapperProps<R extends string> {
+export interface ColumnMapperProps<R extends string> extends FieldHelpProps {
   /** The parts the columns play — translated labels, which are required, which must
    *  be numbers. See {@link ColumnRole}. */
   roles: readonly ColumnRole<R>[];
@@ -440,7 +441,8 @@ export interface ColumnMapperProps<R extends string> {
   onChange: (result: ColumnMapperResult<R> | null) => void;
   /** The paste box's label. Default: `labels.paste`. */
   label?: ReactNode;
-  /** The caption under the paste box. Default: `labels.pasteHint`. */
+  /** The caption under the paste box. Default: `labels.pasteHint`. The paste box's
+   *  `help` (0.36) is `help`. */
   hint?: ReactNode;
   /** What the file dialog offers, and what a drop is checked against. Default:
    *  `.csv,.tsv,.txt,.dat,.asc`. */
@@ -503,6 +505,7 @@ export function ColumnMapper<R extends string>({
   onChange,
   label,
   hint,
+  help,
   accept = DEFAULT_ACCEPT,
   maxSize,
   defaultText = "",
@@ -605,6 +608,7 @@ export function ColumnMapper<R extends string>({
       <Textarea
         label={label ?? labels.paste}
         hint={hint ?? labels.pasteHint}
+        help={help}
         rows={5}
         wrap="off"
         spellCheck={false}

package/src/components/combobox.tsx

@@ -22,6 +22,7 @@ import {
   useFieldHint,
   useLockReason,
   type DisabledReasonDisplay,
+  type FieldHelpProps,
 } from "./field-parts";
 import type { CommitScope } from "./write-lock";
 import { lockedKeyDown, rowClass, SuggestionList, usePrimaryPressOnly } from "./combobox-suggestions";
@@ -38,7 +39,8 @@ export type { InlineEntityComboboxProps } from "./inline-entity-combobox";
  * the DOM events of the wrapper. Everything else a wrapper needs reaches the root.
  */
 export interface ComboboxProps
-  extends Omit<ComponentPropsWithoutRef<"div">, "id" | "onChange" | "onBlur" | "onSubmit"> {
+  extends Omit<ComponentPropsWithoutRef<"div">, "id" | "onChange" | "onBlur" | "onSubmit">,
+    FieldHelpProps {
   value: string;
   onChange: (v: string) => void;
   /** Suggestion pool (e.g. existing payee names). */
@@ -186,6 +188,7 @@ export function Combobox(props: ComboboxProps) {
     invalid,
     error,
     hint,
+    help,
     disabled,
     disabledReason,
     disabledReasonDisplay,
@@ -204,7 +207,7 @@ export function Combobox(props: ComboboxProps) {
     "aria-required": ariaRequired,
     ...rest
   } = props;
-  const hintParts = useFieldHint(hint, ariaDescribedBy);
+  const hintParts = useFieldHint(hint, ariaDescribedBy, { help, name: label ?? ariaLabel });
   const field = useFieldError(error, invalid, hintParts.describedBy, ariaInvalid);
   const generated = useId();
   const fieldId = id ?? generated;

package/src/components/country-select.tsx

@@ -19,6 +19,7 @@ import {
   useFieldMessages,
   useLockReason,
   type DisabledReasonDisplay,
+  type FieldHelpProps,
 } from "./field-parts";
 import { CurrencyFlag } from "./currency-select";
 import { ComboboxPanel, useComboboxCore, type ComboOption } from "./combobox-core";
@@ -66,7 +67,8 @@ export { DEFAULT_COUNTRY_SELECT_LABELS };
  * `null` of a clear cannot reach a handler that was never told about it.
  */
 export interface CountrySelectProps<Clearable extends boolean = false>
-  extends Omit<ComponentPropsWithoutRef<"div">, "onChange" | "defaultValue"> {
+  extends Omit<ComponentPropsWithoutRef<"div">, "onChange" | "defaultValue">,
+    FieldHelpProps {
   /** The chosen country as an ISO 3166-1 alpha-2 code ("CH"), in either case;
    *  `null`, `undefined` or `""` when none is. A code outside the list still shows
    *  its name — the list restricts what can be PICKED, not what can be shown. */
@@ -249,6 +251,7 @@ export function CountrySelect<Clearable extends boolean = false>({
   flags = false,
   label,
   hint,
+  help,
   error,
   invalid,
   placeholder,
@@ -359,6 +362,8 @@ export function CountrySelect<Clearable extends boolean = false>({
   // the error — Select's order. Through useFieldMessages since 0.34 (DUP-2, DUP-8).
   const field = useFieldMessages({
     hint,
+    help,
+    name: label ?? ariaLabel,
     error,
     invalid,
     describedBy: ariaDescribedBy,

package/src/components/currency-select.tsx

@@ -2,7 +2,7 @@ import { useCallback, useId } from "react";
 import type { ComponentPropsWithoutRef, ReactNode, Ref } from "react";
 import { FieldChevron, FIELD_TRIGGER, FIELD_INVALID, FIELD_FLOATING_PAD } from "./field-base";
 import { FieldLabel } from "./field-parts";
-import { assignRef, EndHintRow, useFieldMessages } from "./field-parts";
+import { assignRef, EndHintRow, useFieldMessages, type FieldHelpProps } from "./field-parts";
 import { cn } from "../lib/cn";
 import { useComboboxCore } from "./combobox-core";
 import {
@@ -29,7 +29,7 @@ export type { CurrencyFlagProps, CurrencyOption };
 
 /** `onChange` is the kit's — "a currency was picked", carrying the code — rather
  *  than the div's form event. */
-export interface CurrencySelectProps extends Omit<ComponentPropsWithoutRef<"div">, "onChange"> {
+export interface CurrencySelectProps extends Omit<ComponentPropsWithoutRef<"div">, "onChange">, FieldHelpProps {
   value: string;
   onChange: (code: string) => void;
   placeholder?: string;
@@ -106,6 +106,7 @@ export function CurrencySelect({
   invalid,
   error,
   hint,
+  help,
   labels,
   currencyNames,
   "aria-label": ariaLabel,
@@ -143,7 +144,15 @@ export function CurrencySelect({
   // on the wrapper `<div>` through the spread, where nothing reads it. The caller's ids
   // first, then the caption, then the error — Select's order, through useFieldMessages
   // since 0.34 (DUP-2, DUP-8).
-  const field = useFieldMessages({ hint, error, invalid, describedBy: ariaDescribedBy, ariaInvalid });
+  const field = useFieldMessages({
+    hint,
+    help,
+    name: label ?? ariaLabel,
+    error,
+    invalid,
+    describedBy: ariaDescribedBy,
+    ariaInvalid,
+  });
   const { labelHint, describedBy, isInvalid } = field;
 
   // The trigger's NAME. A combobox does not take its name from its content, and the

package/src/components/date-field.tsx

@@ -19,7 +19,7 @@ import {
 import { splitTriggerAria } from "./trigger-aria";
 import type { TriggerAria } from "./trigger-aria";
 import { FIELD_TRIGGER, FIELD_FLOATING_PAD, FIELD_INVALID } from "./field-base";
-import { assignRef, FieldLabelLine, LABEL_ABOVE_BOX } from "./field-parts";
+import { assignRef, FieldLabelLine, LABEL_ABOVE_BOX, type FieldHelpProps } from "./field-parts";
 import { FullBleedDialog } from "./full-bleed-dialog";
 import type { RemLength } from "../hooks/use-breakpoint";
 import type { MiniCalendarProps } from "./mini-calendar";
@@ -34,7 +34,7 @@ import { Popover } from "./popover";
  * `FormEvent`, while both pickers answer with ISO date strings. Each declares its own
  * (date-picker.tsx, date-range-picker.tsx).
  */
-export interface DatePickerBaseProps extends Omit<ComponentPropsWithoutRef<"div">, "onChange"> {
+export interface DatePickerBaseProps extends Omit<ComponentPropsWithoutRef<"div">, "onChange">, FieldHelpProps {
   /** BCP 47 tag for the trigger's date and the calendar. Falls back to
    *  `<UiKitProvider locale>`, then to the runtime's default. */
   locale?: string;

package/src/components/date-picker.tsx

@@ -170,6 +170,7 @@ export function DatePicker(props: DatePickerProps) {
     disabled,
     invalid,
     hint,
+    help,
     error,
     // Named so it reaches the field (and so its trigger) when a step/today row is the
     // root and takes the rest of the caller's props.
@@ -185,6 +186,8 @@ export function DatePicker(props: DatePickerProps) {
   // (the element a screen reader is on) after any description of the caller's own.
   const messages = useFieldMessages({
     hint,
+    help,
+    name: label ?? rest["aria-label"],
     error,
     invalid,
     describedBy: rest["aria-describedby"],

package/src/components/date-range-picker.tsx

@@ -394,6 +394,7 @@ export function DateRangePicker(props: DateRangePickerProps) {
     disabled,
     invalid,
     hint,
+    help,
     error,
     // The trigger's (API-3).
     ref,
@@ -404,6 +405,8 @@ export function DateRangePicker(props: DateRangePickerProps) {
   const render = useTriggerFormat("dateRangePicker", locale, formatOptions, formatValue);
   const messages = useFieldMessages({
     hint,
+    help,
+    name: label ?? rest["aria-label"],
     error,
     invalid,
     describedBy: rest["aria-describedby"],

package/src/components/entity-combobox.tsx

@@ -25,6 +25,7 @@ import {
   useFieldHint,
   useLockReason,
   type DisabledReasonDisplay,
+  type FieldHelpProps,
 } from "./field-parts";
 import { useCommitReason, type CommitScope } from "./write-lock";
 
@@ -33,7 +34,8 @@ export type { ComboClearValue, ComboOption } from "./combobox-core";
 /** `onChange` is the kit's — "a selection was made", carrying values — rather
  *  than the div's form event, so the DOM's spelling of it is omitted. */
 export interface EntityComboboxProps<V extends string | number, C extends ComboClearValue = null>
-  extends Omit<ComponentPropsWithoutRef<"div">, "onChange"> {
+  extends Omit<ComponentPropsWithoutRef<"div">, "onChange">,
+    FieldHelpProps {
   /** Selected id; `null`, `undefined` or `clearValue` when nothing is selected. */
   value: V | C | null | undefined;
   /** Selecting an option emits its value; the clear button emits `clearValue`. */
@@ -182,6 +184,7 @@ export function EntityCombobox<V extends string | number, C extends ComboClearVa
     invalid,
     error,
     hint,
+    help,
     filter,
     minChars,
     debounceMs,
@@ -206,7 +209,7 @@ export function EntityCombobox<V extends string | number, C extends ComboClearVa
     minChars,
     debounceMs,
   });
-  const hintParts = useFieldHint(hint, ariaDescribedBy);
+  const hintParts = useFieldHint(hint, ariaDescribedBy, { help, name: label ?? ariaLabel });
   const field = useFieldError(error, invalid, hintParts.describedBy, ariaInvalid);
   // The props are the per-instance overrides, the provider the app-wide ones; a
   // prop left `undefined` falls through to the provider rather than masking it.