@eifi1/ui-kit 0.21.0 → 0.23.0

package/src/components/toggle-group.tsx

@@ -3,6 +3,9 @@ import type { ComponentPropsWithoutRef, KeyboardEvent, ReactElement, ReactNode }
 import { cn } from "../lib/cn";
 import { horizontalStep } from "../lib/direction";
 import { FIELD_INVALID, FloatingField, Label } from "./ui";
+import { Tooltip } from "./tooltip";
+import { useCommitReason } from "./write-lock";
+import { hasContent, LabelStrip } from "./field-parts";
 
 export interface ToggleOption<T extends string> {
   value: T;
@@ -59,6 +62,9 @@ export interface ToggleGroupBaseProps<T extends string>
    * `sm`: 12px options with `px-2 py-1` — the compact group keksdose's rule editor
    * (rule-editor:204) writes as `optionClassName="px-2 py-1 text-xs"` beside a small
    * caption. `md` (default) is the size every other group has.
+   *
+   * Honoured inside the field chrome and the strip too (keksdose K1): the 12px type
+   * stays, and the field is still 42px — see `CHROME_PAD`.
    */
   size?: "sm" | "md";
   /**
@@ -84,11 +90,32 @@ export interface ToggleGroupBaseProps<T extends string>
    * cap pair sits in a `Field` column between two labelled-above inputs, where the
    * chrome's inner label would be the only one of its kind).
    *
+   * `"strip"`: the 11px static label (and `hint`) in a strip OVER the bare group, for a
+   * group that stands in a row of fields but is not one (keksdose K2 — the transaction
+   * row's cleared-status picker, live #288 / #431 / dev#468). No field border: the group
+   * keeps its own box, and its segments drop their vertical padding so a 16px strip
+   * plus the 26px group is exactly a labelled {@link Input}'s 42px, the label on the
+   * same line as theirs. `error` and `caption` go under the group, as in the other two.
+   *
    * Inside a `Field`, pass no `label` at all and spread the render-prop instead —
    * `{(ids, { labelId }) => <ToggleGroup {...ids} aria-labelledby={labelId} … />}` —
    * so the Field's label names the group and its hint and error describe it.
    */
-  labelPlacement?: "field" | "above";
+  labelPlacement?: "field" | "above" | "strip";
+  /**
+   * Classes for the field chrome's own box — the bordered, padded box round the
+   * segments — merged last, so they win. `className` styles the wrapper the chrome sits
+   * in; this reaches the box itself. Only with `label` in the `"field"` placement.
+   *
+   * For a field JOINED flush to a neighbour (keksdose K1): reports-filters.tsx joins its
+   * "group by" field to the range select on its start edge from `md` up, and squares the
+   * shared corners by hand chrome today — here that is
+   * `chromeClassName="md:rounded-s-none"` with `className="md:-ms-px"` (the wrapper
+   * overlaps the neighbour by the one border they share). A class rather than a
+   * `joined="start"` because every such join keksdose has is responsive: on a phone the
+   * two stack and both keep their corners.
+   */
+  chromeClassName?: string;
   /** A {@link FieldHint} on the label line, as on a labelled {@link Select}. Only with
    *  `label`. */
   hint?: ReactNode;
@@ -96,8 +123,60 @@ export interface ToggleGroupBaseProps<T extends string>
    *  `--danger`, marks the group `aria-invalid` and describes it with the message, as
    *  {@link Select}'s `error` does. Only with `label`. */
   error?: ReactNode;
+  /**
+   * Why the group cannot be changed right now — {@link Button}'s `disabledReason`, for
+   * a group that saves itself on change (keksdose K3: the last `SaveGuard` sites are
+   * self-committing controls like this one, and SaveGuard's native `disabled` took
+   * them out of the tab order so the reason never reached a keyboard).
+   *
+   * The group stays reachable — its segments are `aria-disabled`, not `disabled`, and
+   * a radio group's arrow keys still walk them — but nothing reaches `onChange`, and
+   * the reason shows in the kit {@link Tooltip} over the segments on hover or focus and
+   * describes each segment. The chosen option keeps its fill, as under `disabled`.
+   * Wins over `disabled`, as on Button: passing both keeps the group reachable.
+   */
+  disabledReason?: ReactNode;
+  /**
+   * This group COMMITS — choosing an option saves it. Under a locked
+   * {@link WriteLockProvider} it takes the `disabledReason` path with the lock's
+   * reason (which wins over a `disabledReason` of its own): *"everything renders; only
+   * the commit is locked"* (keksdose dev#496/#497), and a control that is its own commit
+   * must render refused, never live-and-discarding. No provider, or an unlocked one:
+   * no effect.
+   */
+  commit?: boolean;
 }
 
+/**
+ * The field chrome's vertical geometry — keksdose K1, the kit reintroducing feedback
+ * #117 that keksdose's hand-built chrome had fixed.
+ *
+ * The label is the field's static label: `top-1` and 11px in a `leading-tight` line, so
+ * its line box runs from 4px to 17.75px. Until 0.22 the chrome was `pt-4` over a 20px
+ * (`leading-5`) segment, so the ACTIVE segment's fill — painted from the top of the
+ * segment — started at 17px (1px border + 16px), 0.75px INSIDE the label's line box:
+ * the highlight touched the word above it, exactly what #117's rework had measured and
+ * cured with `pt-5`.
+ *
+ * Now the strip is `pt-5` and the fill starts at 21px, 3.25px clear, and the segment
+ * gives the 4px back so the field stays a labelled Select's 42px: `md` sets its 14px
+ * text in an 18px line with a 2px moat under it (the bare group's own `p-0.5` moat),
+ * `sm` sets 12px text in a 16px line over `pb-1` — keksdose's measured chrome
+ * (price-level-picker, reports-filters: `pt-5 pb-1`, `text-xs md:py-0`), byte for byte.
+ * Before, `size="sm"` inside the chrome was overridden to the md 20px line.
+ *
+ *     md: 1 + 20 + 18 + 2 + 1 = 42        sm: 1 + 20 + 16 + 4 + 1 = 42
+ */
+const CHROME_PAD: Record<"sm" | "md", string> = { md: "pt-5 pb-0.5", sm: "pt-5 pb-1" };
+const CHROME_SEGMENT: Record<"sm" | "md", string> = { md: "py-0 leading-[18px]", sm: "py-0 leading-4" };
+
+/**
+ * The strip placement's segments: a 26px group (1 + 2 + 20 + 2 + 1) under the 16px
+ * strip — `md`'s 20px text-sm line with no padding, `sm`'s 16px line with 2px either
+ * side. See `LABEL_STRIP_PAD` for why 16.
+ */
+const STRIP_SEGMENT: Record<"sm" | "md", string> = { md: "py-0", sm: "py-0.5" };
+
 /**
  * A line under the group saying what the CHOSEN option means — lenkbank's ToggleField
  * `hint` (features/gear/common.tsx:97): not help behind a "?" but a caption, and one
@@ -189,18 +268,30 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
     size = "md",
     label,
     labelPlacement = "field",
+    chromeClassName,
     hint,
     error,
+    disabledReason: ownDisabledReason,
+    commit,
     "aria-label": ariaLabelAttr,
     ...restWithMode
   } = props;
   const labelId = useId();
   const errorId = useId();
-  const labelled = label !== undefined && label !== null && label !== false && label !== "";
-  // `field` is the chrome; a label placed above keeps the bare group's own box.
+  const reasonId = useId();
+  // The lock's reason under a locked provider (with `commit`), else the group's own.
+  const disabledReason = useCommitReason(commit, ownDisabledReason);
+  const locked = hasContent(disabledReason);
+  // Locked looks disabled — the dimmed group, the not-allowed cursor, no hover offer —
+  // but stays focusable; `disabled` alone also takes the segments out of the tab order.
+  const dimmed = disabled || locked;
+  const labelled = hasContent(label);
+  // `field` is the chrome; a label placed above or in a strip keeps the bare group's
+  // own box.
   const field = labelled && labelPlacement === "field";
   const above = labelled && labelPlacement === "above";
-  const hasError = labelled && error !== undefined && error !== null && error !== false && error !== "";
+  const strip = labelled && labelPlacement === "strip";
+  const hasError = labelled && hasContent(error);
   // Taken off the rest so neither reaches the DOM; `props` keeps them paired, which is
   // what lets the `onChange` below be called with `null` only in the mode that allows it.
   const { allowEmpty: _allowEmpty, onChange: _onChange, caption, semantics: _semantics, ...rest } = restWithMode;
@@ -210,8 +301,11 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
   const captionId = useId();
   const captionIsLive = typeof caption === "function";
   const captionNode = captionIsLive ? (caption as (v: T | null) => ReactNode)(value) : caption;
-  const hasCaption = captionNode !== undefined && captionNode !== null && captionNode !== false && captionNode !== "";
+  const hasCaption = hasContent(captionNode);
   const choose = (next: T) => {
+    // A locked group swallows the change: it saves on change, and a lock that let the
+    // value move and then discarded it would show a state that was never stored.
+    if (locked) return;
     if (props.allowEmpty) props.onChange(next === value ? null : next);
     else props.onChange(next);
   };
@@ -236,10 +330,79 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
     if (next === null) return;
     e.preventDefault();
     next = next < 0 ? last : next > last ? 0 : next;
+    // The segments' own parent: the group, or under a lock the tooltip's row inside it.
     const buttons = e.currentTarget.parentElement?.querySelectorAll<HTMLButtonElement>(":scope > button");
     buttons?.[next]?.focus();
+    // Locked: the focus walks (each segment says why on arrival), the choice does not.
     choose(options[next].value);
   };
+  const segments = options.map((opt, index) => {
+    const active = opt.value === value;
+    return (
+      <button
+        key={opt.value}
+        type="button"
+        role={pressed ? undefined : "radio"}
+        aria-checked={pressed ? undefined : active}
+        aria-pressed={pressed ? active : undefined}
+        // A reason wins over `disabled` (as on Button): reachable, and refusing.
+        disabled={disabled && !locked}
+        aria-disabled={locked || undefined}
+        // On each segment rather than the group: the segment is what takes focus, and
+        // a group's description is not read reliably when focus lands inside it.
+        aria-describedby={locked ? reasonId : undefined}
+        tabIndex={pressed ? undefined : opt.value === tabStop ? 0 : -1}
+        onKeyDown={pressed ? undefined : (e) => onRadioKey(e, index)}
+        onClick={() => choose(opt.value)}
+        className={cn(
+          // `truncate` (which carries whitespace-nowrap) rather than letting a
+          // label wrap: a segmented control sizes its whole row to the tallest
+          // option, so one two-word option — Keksdose feedback #147's "Where I
+          // am" — silently doubles the height of every segment beside it.
+          //
+          // `basis-auto` is what keeps that ellipsis a LAST resort rather than
+          // the normal state (Keksdose dev#475). With flex-1's `basis-0`, a
+          // shrink-to-fit group (`w-auto`) still resolves to the sum of the
+          // labels' widths — and then splits it EQUALLY, so the short option
+          // got 66px it did not need and "Where I am" got 66 of the 81 it did:
+          // truncated at 1778px of free screen. Basing each segment on its own
+          // content and sharing only the LEFTOVER space keeps a full-width
+          // group's segments near-equal and an auto-width group's exact.
+          //
+          // `focus-visible` + `ring-inset`, not `focus` + an outset ring. A ring
+          // is a box-shadow that spreads OUTWARD, so on a flush group it painted
+          // 2px of ring over both neighbours and over the container's own border
+          // — and on a phone it appeared on every TAP, because a tap focuses the
+          // button. That is the other half of what live #268's rework saw
+          // overlaying the selected segment's boundary. Inset keeps the ring
+          // inside the segment it belongs to; focus-visible keeps it for the
+          // keyboard, which is the only input that needs it.
+          overflow === "wrap" ? "whitespace-nowrap" : "min-w-0 truncate",
+          "flex-1 basis-auto rounded px-3 py-1.5 text-sm font-medium transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-[var(--border-strong)]",
+          size === "sm" && "px-2 py-1 text-xs",
+          // In the field chrome: no vertical padding, and the line that makes the
+          // field 42px under a strip that clears the label — see CHROME_PAD. `sm`
+          // keeps its 12px type here (it used to be overridden to the md line).
+          field && CHROME_SEGMENT[size],
+          // In the strip placement: a 26px group under a 16px strip — STRIP_SEGMENT.
+          strip && STRIP_SEGMENT[size],
+          active
+            ? "bg-[var(--bg-inverse)] text-[var(--text-inverse)]"
+            : "text-[var(--text-secondary)] hover:bg-[var(--bg-hover)]",
+          // No hover fill on a group that cannot be changed — a segment that
+          // lights up under the pointer is an offer, and there is none here. Not on
+          // the chosen segment: its fill IS its state, and its inverse text would
+          // vanish on a transparent hover.
+          dimmed && "cursor-not-allowed",
+          dimmed && !active && "hover:bg-transparent dark:hover:bg-transparent",
+          optionClassName,
+          opt.className,
+        )}
+      >
+        {opt.label}
+      </button>
+    );
+  });
   const group = (
     <div
       // The audit's named example of a closed prop list (§"Public API design"): the
@@ -262,10 +425,10 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
       aria-describedby={
         [rest["aria-describedby"], hasCaption && captionId, hasError && errorId].filter(Boolean).join(" ") || undefined
       }
-      // `aria-disabled` on the group as well as `disabled` on each button: a radio
-      // group is what the user is being refused, and a screen reader announcing
+      // `aria-disabled` on the group as well as on (or `disabled` on) each button: a
+      // radio group is what the user is being refused, and a screen reader announcing
       // three separately-disabled radios does not say that.
-      aria-disabled={disabled || undefined}
+      aria-disabled={dimmed || undefined}
       className={cn(
         // `gap-0.5` — the same 2px as the container's own padding, so EVERY segment
         // sits in a uniform 2px moat and no two fills ever touch. Flush segments were
@@ -284,75 +447,34 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
         // The whole group fades, the way every other disabled control in this
         // package does; `cursor-not-allowed` is on the buttons, which is what a
         // pointer is actually over.
-        disabled && "opacity-60",
+        dimmed && "opacity-60",
         // The bare group (no chrome to paint) wears the invalid border itself.
-        !field && (outsideInvalid || (above && hasError)) && FIELD_INVALID,
+        !field && (outsideInvalid || ((above || strip) && hasError)) && FIELD_INVALID,
         // Inside the field's chrome the group is only a row of segments: no border, no
         // surface, no padding of its own, and the field (not the group) is what dims.
         field && "border-0 bg-transparent p-0 shadow-none opacity-100",
         !labelled && className,
       )}
     >
-      {options.map((opt, index) => {
-        const active = opt.value === value;
-        return (
-          <button
-            key={opt.value}
-            type="button"
-            role={pressed ? undefined : "radio"}
-            aria-checked={pressed ? undefined : active}
-            aria-pressed={pressed ? active : undefined}
-            disabled={disabled}
-            tabIndex={pressed ? undefined : opt.value === tabStop ? 0 : -1}
-            onKeyDown={pressed ? undefined : (e) => onRadioKey(e, index)}
-            onClick={() => choose(opt.value)}
-            className={cn(
-              // `truncate` (which carries whitespace-nowrap) rather than letting a
-              // label wrap: a segmented control sizes its whole row to the tallest
-              // option, so one two-word option — Keksdose feedback #147's "Where I
-              // am" — silently doubles the height of every segment beside it.
-              //
-              // `basis-auto` is what keeps that ellipsis a LAST resort rather than
-              // the normal state (Keksdose dev#475). With flex-1's `basis-0`, a
-              // shrink-to-fit group (`w-auto`) still resolves to the sum of the
-              // labels' widths — and then splits it EQUALLY, so the short option
-              // got 66px it did not need and "Where I am" got 66 of the 81 it did:
-              // truncated at 1778px of free screen. Basing each segment on its own
-              // content and sharing only the LEFTOVER space keeps a full-width
-              // group's segments near-equal and an auto-width group's exact.
-              //
-              // `focus-visible` + `ring-inset`, not `focus` + an outset ring. A ring
-              // is a box-shadow that spreads OUTWARD, so on a flush group it painted
-              // 2px of ring over both neighbours and over the container's own border
-              // — and on a phone it appeared on every TAP, because a tap focuses the
-              // button. That is the other half of what live #268's rework saw
-              // overlaying the selected segment's boundary. Inset keeps the ring
-              // inside the segment it belongs to; focus-visible keeps it for the
-              // keyboard, which is the only input that needs it.
-              overflow === "wrap" ? "whitespace-nowrap" : "min-w-0 truncate",
-              "flex-1 basis-auto rounded px-3 py-1.5 text-sm font-medium transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-[var(--border-strong)]",
-              size === "sm" && "px-2 py-1 text-xs",
-              // In a field: no vertical padding and a 20px line — a `text-sm` line, the
-              // same line a labelled Select holds under its label strip — so the field's
-              // own `pt-4 pb-1` decides the height, as it does for the select.
-              field && "py-0 leading-5",
-              active
-                ? "bg-[var(--bg-inverse)] text-[var(--text-inverse)]"
-                : "text-[var(--text-secondary)] hover:bg-[var(--bg-hover)]",
-              // No hover fill on a group that cannot be changed — a segment that
-              // lights up under the pointer is an offer, and there is none here. Not on
-              // the chosen segment: its fill IS its state, and its inverse text would
-              // vanish on a transparent hover.
-              disabled && "cursor-not-allowed",
-              disabled && !active && "hover:bg-transparent dark:hover:bg-transparent",
-              optionClassName,
-              opt.className,
-            )}
-          >
-            {opt.label}
-          </button>
-        );
-      })}
+      {locked ? (
+        // The reason's bubble wraps the SEGMENTS, inside the group, not the group: a
+        // wrapper outside it would become the flex or grid item in the caller's row in
+        // the group's place, and a `w-full` / `md:w-auto` on the group would size the
+        // wrong box. This row inherits the group's gap and wrap, so the segments lay out
+        // exactly as they do unlocked, and `:scope > button` above still finds them. A
+        // fragment child, so the Tooltip describes nothing itself — each segment points
+        // at the hidden copy, the way a locked Button does.
+        <Tooltip label={disabledReason} className="flex min-w-0 flex-1 gap-[inherit] [flex-wrap:inherit]">
+          <>
+            {segments}
+            <span id={reasonId} hidden>
+              {disabledReason}
+            </span>
+          </>
+        </Tooltip>
+      ) : (
+        segments
+      )}
     </div>
   );
   // Rendered whenever the caption is — `aria-live` must be on the element BEFORE its
@@ -384,7 +506,7 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
               by `aria-labelledby` on the group; the element keeps the Field look. */}
           <Label
             id={labelId}
-            disabled={disabled}
+            disabled={dimmed}
             data-error={hasError || undefined}
             className="data-[error=true]:text-[var(--danger)]"
           >
@@ -400,6 +522,15 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
       </div>
     );
   }
+  if (strip) {
+    return (
+      <LabelStrip labelId={labelId} label={label} hint={hint} disabled={dimmed} pad="field" className={className}>
+        {group}
+        {captionEl}
+        {errorEl}
+      </LabelStrip>
+    );
+  }
   if (!field) {
     if (!captionEl) return group;
     // The group keeps its `className`, as without a caption; the wrapper only stacks.
@@ -422,9 +553,11 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
       >
         <div
           className={cn(
-            "flex flex-1 flex-col justify-center rounded-md border border-[var(--border)] bg-[var(--bg-surface)] px-1 pt-4 pb-1 shadow-sm",
-            disabled && "bg-[var(--bg-surface-2)] opacity-60",
+            "flex flex-1 flex-col justify-center rounded-md border border-[var(--border)] bg-[var(--bg-surface)] px-1 shadow-sm",
+            CHROME_PAD[size],
+            dimmed && "bg-[var(--bg-surface-2)] opacity-60",
             hasError && FIELD_INVALID,
+            chromeClassName,
           )}
         >
           {group}

package/src/components/trigger-aria.ts

@@ -14,6 +14,9 @@ export interface TriggerAria {
   "aria-labelledby"?: string;
   "aria-describedby"?: string;
   "aria-invalid"?: boolean | "true" | "false" | "grammar" | "spelling";
+  /** 0.23.0: a form library's `required` (RhfMonthPicker) is announced on the trigger,
+   *  not lost on the wrapper. */
+  "aria-required"?: boolean | "true" | "false";
 }
 
 /** Split a field's props into what its trigger takes and what its wrapper takes. */
@@ -26,6 +29,7 @@ export function splitTriggerAria<T extends TriggerAria>(
     "aria-labelledby": labelledBy,
     "aria-describedby": describedBy,
     "aria-invalid": invalid,
+    "aria-required": required,
     ...rest
   } = props;
   return [
@@ -35,6 +39,7 @@ export function splitTriggerAria<T extends TriggerAria>(
       "aria-labelledby": labelledBy,
       "aria-describedby": describedBy,
       "aria-invalid": invalid,
+      "aria-required": required,
     },
     rest,
   ];