@eifi1/ui-kit 0.21.0 → 0.23.0

package/src/components/sign-chip.tsx

@@ -0,0 +1,103 @@
+import { ArrowUpDown, Minus, Plus } from "lucide-react";
+import { Chip } from "./chip";
+import { Tooltip } from "./tooltip";
+import { cn } from "../lib/cn";
+import { useKitLabels } from "../i18n/kit-labels";
+
+// ── Labels ────────────────────────────────────────────────────────────────────
+
+/** The words a {@link SignChip} says — the `signChip` namespace of
+ *  `<UiKitProvider labels>`, and per chip through its `labels` prop. */
+export interface SignChipLabels {
+  /** The chip's text while the figure is negative — money going out. */
+  outflow: string;
+  /** The chip's text while the figure is positive — money coming in. */
+  inflow: string;
+  /** The chip's accessible name and its tooltip: the state it is in, and what a press
+   *  turns it into — `current` and `next` are the two words above. The other option is
+   *  nowhere on screen to be read, so the name has to say both. */
+  direction: (current: string, next: string) => string;
+}
+
+export const DEFAULT_SIGN_CHIP_LABELS: SignChipLabels = {
+  outflow: "Outflow",
+  inflow: "Inflow",
+  direction: (current, next) => `Direction: ${current} — switch to ${next}`,
+};
+
+export interface SignChipProps {
+  /** The figure is negative (an outflow) — the same flag {@link AmountInput}'s
+   *  `negative` is, so one state feeds both: `<AmountInput negative={neg}
+   *  onNegativeChange={setNeg} />` and `<SignChip negative={neg}
+   *  onNegativeChange={setNeg} />`. */
+  negative: boolean;
+  /** A press: the other direction. */
+  onNegativeChange: (negative: boolean) => void;
+  disabled?: boolean;
+  /** Per-chip overrides of the `signChip` namespace. */
+  labels?: Partial<SignChipLabels>;
+  /** On the chip. Place it in its row from here — keksdose's form passes `self-end`
+   *  to sit it on the display figure's baseline strip. */
+  className?: string;
+}
+
+/**
+ * The SIGN of an amount, as one chip that shows only the state it is in — keksdose
+ * K15, its `DirectionToggle` (feedback #417, #430, #431, dev#434) made a kit piece,
+ * so the figure and its direction come from one package and wear one palette.
+ *
+ * WHY A CHIP, NOT A SEGMENTED CONTROL. A two-option toggle spends half its width
+ * telling you what the figure is NOT, and at a phone's width it was the widest thing on
+ * the form after the figure itself (#417). This sits beside the amount and reads as one
+ * phrase with it — "−42,50 Outflow" — and a press flips it. Hiding the alternative costs
+ * discoverability, so two things pay it back: the ± glyph and the swap arrows say "this
+ * is a control", not a badge; and the name and tooltip spell out both the current state
+ * and what a press will do.
+ *
+ * NOT A PRESSED/UNPRESSED TOGGLE. A {@link Chip} toggle has a FIXED label naming its
+ * on-state, with `aria-pressed` carrying the state. Here the word IS the state, so it
+ * is an action button with no `aria-pressed`: "Direction: Inflow, not pressed" would
+ * name no on-state for "not pressed" to be the absence of. The name changing under
+ * focus is the echo.
+ *
+ * THE COLOUR is the money pairing — the chip's `expense` / `income` tones, the same
+ * `--money-expense` / `--money-income` that {@link AmountInput}'s `tone` paints the
+ * figure with (dev#434): only the text and the border carry the tint, on a neutral
+ * surface, because a filled pill next to a tinted figure reads as one smear.
+ *
+ * SIZE. `lg` on a phone — the 44px touch target beside a display figure that has no
+ * field height to match — and from `md` up exactly a labelled field's 42px, so it never
+ * stands taller than the fields in its grid row (#431).
+ *
+ * An exported chip rather than an `AmountInput signControl` slot: the slot would have
+ * to own the row the two share, and every form lays that row out differently (beside
+ * the figure on a phone, in a grid column on a desktop). The chip is the part that was
+ * being re-written; the row stays the form's.
+ */
+export function SignChip({ negative, onNegativeChange, disabled, labels: labelsProp, className }: SignChipProps) {
+  const labels = useKitLabels("signChip", DEFAULT_SIGN_CHIP_LABELS, labelsProp);
+  const current = negative ? labels.outflow : labels.inflow;
+  const next = negative ? labels.inflow : labels.outflow;
+  const name = labels.direction(current, next);
+  return (
+    <Tooltip label={name} lazy>
+      <Chip
+        size="lg"
+        tone={negative ? "expense" : "income"}
+        icon={negative ? Minus : Plus}
+        onClick={() => onNegativeChange(!negative)}
+        disabled={disabled}
+        aria-label={name}
+        // `gap-1.5 px-3`: the chip's narrower body, because on a 375px screen every
+        // pixel of it is taken from the figure beside it (#430). `md:py-2.5` with the
+        // hairline border is the 42px a labelled field measures (#431).
+        className={cn("shrink-0 gap-1.5 whitespace-nowrap px-3 font-medium md:min-h-0 md:py-2.5", className)}
+      >
+        {current}
+        {/* The swap arrows after the word, in the label's own row: decoration (the
+            name already says what a press does), set a little apart from the word. */}
+        <ArrowUpDown className="ms-1.5 inline size-3.5 align-[-0.2em] opacity-60" aria-hidden />
+      </Chip>
+    </Tooltip>
+  );
+}

package/src/components/swatch-picker.tsx

@@ -1,9 +1,12 @@
 import { useId, useMemo } from "react";
-import type { ComponentPropsWithoutRef } from "react";
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { useKitLabels } from "../i18n/kit-labels";
 import { TILE_SIZE, TileRadioGroup } from "./tile-radio";
 import type { TileItem, TileSize } from "./tile-radio";
+import { Tooltip } from "./tooltip";
+import { useCommitReason } from "./write-lock";
+import { hasContent, LabelStrip } from "./field-parts";
 
 export interface SwatchPickerLabels {
   /** The "no colour" tile's name, when `allowNone` is set. */
@@ -35,7 +38,23 @@ export interface SwatchOption<T extends string> {
   /** A remark read after the name and shown under it in the bubble ("used by
    *  Groceries"). The tile wears a dot while it has one. */
   note?: string;
+  /** Out of the choice and out of reach — skipped by the arrow keys and Tab. With a
+   *  `disabledReason` the tile stays reachable instead and says why. */
   disabled?: boolean;
+  /**
+   * Why THIS colour cannot be chosen right now — the whole picker's `disabledReason`,
+   * one tile at a time (the kit's later list after keksdose K3: a colour another
+   * category already wears, a flag only an owner may set). {@link Button}'s rule: a tile
+   * that is merely `disabled` is a dead square a keyboard never lands on, so nobody
+   * learns why it is dimmed.
+   *
+   * The tile looks disabled but is `aria-disabled`, not `disabled`: Tab and the arrow
+   * keys still reach it, its bubble shows the reason under its name, and the reason
+   * describes it. Choosing it — a click, Space or Enter, or an arrow under automatic
+   * activation — does nothing: the focus moves onto it and the checked colour stays
+   * where it was, as under the whole-picker lock. Wins over `disabled`.
+   */
+  disabledReason?: ReactNode;
 }
 
 /**
@@ -72,6 +91,31 @@ export interface SwatchPickerProps<T extends string>
   tileClassName?: string;
   disabled?: boolean;
   labels?: Partial<SwatchPickerLabels>;
+  /**
+   * An 11px static label in a strip over the swatches, named by it (keksdose K2): the
+   * transaction row's flag picker stands between labelled fields and hand-builds this
+   * (`FieldLabel` + `pt-5`, transaction-flags.tsx:155) because the picker had no label.
+   * The label sits on the same line as a field's own (`top-1`, `inset-x-3`); the
+   * swatches start 20px down, below its whole line box — see `LABEL_STRIP_PAD`. With a
+   * label, `className` styles the wrapper, as on a labelled {@link ToggleGroup}; an
+   * explicit `aria-label` / `aria-labelledby` still names the group instead.
+   */
+  label?: ReactNode;
+  /** A {@link FieldHint} beside the label. Only with `label`. */
+  hint?: ReactNode;
+  /**
+   * Why the colour cannot be changed right now — {@link Button}'s `disabledReason`, for
+   * a picker that saves itself on change (keksdose K3, the flag picker in a row a
+   * read-only viewer may see). The swatches stay reachable and the arrow keys still
+   * walk them, but nothing reaches `onChange`; the reason is shown in the kit
+   * {@link Tooltip} under the row (each swatch's own name bubble sits above it) and
+   * describes the group. Wins over `disabled`.
+   */
+  disabledReason?: ReactNode;
+  /** This picker COMMITS — choosing a colour saves it. Under a locked
+   *  {@link WriteLockProvider} it takes the `disabledReason` path with the lock's
+   *  reason, as {@link Button}'s `commit` does. */
+  commit?: boolean;
 }
 
 /**
@@ -97,51 +141,113 @@ export function SwatchPicker<T extends string>({
   tileClassName,
   disabled = false,
   labels,
+  label,
+  hint,
+  disabledReason: ownDisabledReason,
+  commit,
   className,
   ...rest
 }: SwatchPickerProps<T>) {
   const text = useKitLabels("swatchPicker", DEFAULT_SWATCH_PICKER_LABELS, labels);
   const mixedId = useId();
+  const labelId = useId();
+  const reasonId = useId();
+  const disabledReason = useCommitReason(commit, ownDisabledReason);
+  const locked = hasContent(disabledReason);
+  const labelled = hasContent(label);
   const byValue = useMemo(() => new Map(options.map((o) => [o.value, o])), [options]);
   const items: TileItem<T>[] = [
     ...(allowNone ? [{ key: null, label: text.none }] : []),
-    ...options.map((o) => ({ key: o.value, label: o.label, note: o.note, disabled: o.disabled })),
+    ...options.map((o) => ({
+      key: o.value,
+      label: o.label,
+      note: o.note,
+      disabled: o.disabled,
+      disabledReason: o.disabledReason,
+    })),
   ];
-  return (
+  const tiles = (
+    <TileRadioGroup
+      items={items}
+      checked={mixed ? undefined : value}
+      // A locked picker saves on change, so the change is swallowed — the arrow keys
+      // still move the focus (and, automatic, would choose), and nothing is chosen. A
+      // locked TILE is refused by the tiles themselves; asked again here so a reason
+      // can never become a change, whatever the tiles do.
+      onSelect={(next) => {
+        if (!locked && !hasContent(next === null ? undefined : byValue.get(next)?.disabledReason)) onChange(next);
+      }}
+      activation={activation}
+      // A reason wins over `disabled`: the tiles stay in the tab order.
+      disabled={disabled && !locked}
+      size={size}
+      tileClassName={
+        tileClassName || locked
+          ? (_item, selected) =>
+              cn(
+                // The disabled tile's look, without its `disabled`: dimmed, a
+                // not-allowed cursor, and no hover offer on a tile that cannot be
+                // chosen. Not on the selected tile, whose frame IS its state.
+                locked && "cursor-not-allowed opacity-50",
+                locked && !selected && "hover:border-[var(--border)] hover:bg-[var(--bg-surface)]",
+                tileClassName,
+              )
+          : undefined
+      }
+      renderTile={(item) => {
+        const opt = item.key === null ? undefined : byValue.get(item.key);
+        return (
+          <span
+            aria-hidden
+            // A hairline round the dot, drawn over whatever colour it is: a pale
+            // yellow swatch on a white surface is otherwise a hole in the row.
+            className={cn(
+              "rounded-full ring-1 ring-inset ring-black/10 dark:ring-white/15",
+              TILE_SIZE[size].swatch,
+              opt?.swatchClassName,
+            )}
+            style={{ background: opt?.color }}
+          />
+        );
+      }}
+    />
+  );
+  const group = (
     <div
       {...rest}
       role="radiogroup"
-      aria-disabled={disabled || undefined}
+      aria-labelledby={
+        labelled && rest["aria-label"] === undefined && rest["aria-labelledby"] === undefined
+          ? labelId
+          : rest["aria-labelledby"]
+      }
+      aria-disabled={disabled || locked || undefined}
       aria-describedby={
-        [rest["aria-describedby"], mixed && mixedId].filter(Boolean).join(" ") || undefined
+        [rest["aria-describedby"], mixed && mixedId, locked && reasonId].filter(Boolean).join(" ") ||
+        undefined
       }
-      className={cn("flex flex-wrap items-center gap-1.5", className)}
+      className={cn("flex flex-wrap items-center gap-1.5", !labelled && className)}
     >
-      <TileRadioGroup
-        items={items}
-        checked={mixed ? undefined : value}
-        onSelect={onChange}
-        activation={activation}
-        disabled={disabled}
-        size={size}
-        tileClassName={tileClassName ? () => tileClassName : undefined}
-        renderTile={(item) => {
-          const opt = item.key === null ? undefined : byValue.get(item.key);
-          return (
-            <span
-              aria-hidden
-              // A hairline round the dot, drawn over whatever colour it is: a pale
-              // yellow swatch on a white surface is otherwise a hole in the row.
-              className={cn(
-                "rounded-full ring-1 ring-inset ring-black/10 dark:ring-white/15",
-                TILE_SIZE[size].swatch,
-                opt?.swatchClassName,
-              )}
-              style={{ background: opt?.color }}
-            />
-          );
-        }}
-      />
+      {locked ? (
+        // Inside the group, round the tiles — not round the group, whose box is the
+        // caller's row item. This row inherits the group's gap, wrap and alignment, so
+        // the tiles sit exactly where they sit unlocked. Below the row: each tile's own
+        // bubble (its colour's name) is above it.
+        <Tooltip
+          label={disabledReason}
+          side="bottom"
+          className="flex min-w-0 flex-1 gap-[inherit] [align-items:inherit] [flex-wrap:inherit] [justify-content:inherit]"
+        >
+          <>
+            {tiles}
+            <span id={reasonId} hidden>
+              {disabledReason}
+            </span>
+          </>
+        </Tooltip>
+      ) : (
+        tiles
+      )}
       {/* `hidden`, not `sr-only`: a description is read from hidden text, and this
           way it takes no room in the row. */}
       {mixed && (
@@ -151,4 +257,10 @@ export function SwatchPicker<T extends string>({
       )}
     </div>
   );
+  if (!labelled) return group;
+  return (
+    <LabelStrip labelId={labelId} label={label} hint={hint} disabled={disabled || locked} pad="clear" className={className}>
+      {group}
+    </LabelStrip>
+  );
 }

package/src/components/switch.tsx

@@ -2,6 +2,7 @@ import { forwardRef, useId } from "react";
 import type { ChangeEvent, InputHTMLAttributes, ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { hasMessage, mergeDescribedBy } from "./choice-parts";
+import { LockedReason, useLockReason } from "./field-parts";
 
 /**
  * An on/off switch that is still `<input type="checkbox">`, with `role="switch"`.
@@ -79,6 +80,25 @@ export interface SwitchProps extends Omit<InputHTMLAttributes<HTMLInputElement>,
    * label WITHOUT a literal "*". No mark without a label.
    */
   required?: boolean;
+  /**
+   * Why the switch cannot be flipped — {@link Button}'s `disabledReason`. A switch is
+   * the control that "takes effect the moment it is flipped", so it is the first one
+   * keksdose K3 names: its settings rows sat behind a `SaveGuard` that forced a native
+   * `disabled`, out of the tab order, so the reason never reached a keyboard.
+   *
+   * With a reason the switch is `aria-disabled` instead: still focusable, a click or
+   * Space flips nothing and fires no `onChange` / `onCheckedChange`, the reason is in
+   * the kit {@link Tooltip} on the track and on its `aria-describedby`, and the row
+   * fades as a disabled one does. It wins over `disabled`. Changing the lock mounts the
+   * switch anew (it moves in or out of the Tooltip), as a locked Button is.
+   */
+  disabledReason?: ReactNode;
+  /**
+   * This switch COMMITS — flipping it saves. Under a locked {@link WriteLockProvider} it
+   * is locked the `disabledReason` way with the lock's reason (which wins over its
+   * own). No provider, or an unlocked one: no effect. Button's `commit`, for K3.
+   */
+  commit?: boolean;
 }
 
 /**
@@ -101,39 +121,70 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(function Switch(
     id,
     disabled,
     required,
+    disabledReason,
+    commit,
+    onClick,
     ...rest
   },
   ref,
 ) {
   const generated = useId();
   const inputId = id ?? generated;
+  const lock = useLockReason(commit, disabledReason);
+  const locked = lock.locked;
+  // Locked is disabled the focusable way — the row fades and the words stop inviting a
+  // click, as for `disabled`.
+  const looksDisabled = Boolean(disabled) || locked;
   const descriptionId = `${inputId}-description`;
   const showDescription = hasMessage(description);
   const bare = label === undefined && !showDescription;
   const geometry = SIZES[size];
 
-  const control = (
-    <span className={cn("relative inline-flex shrink-0", bare && className)}>
+  const track = (
+    <span className={cn("relative inline-flex shrink-0", bare && !locked && className)}>
       <input
         ref={ref}
         id={bare ? id : inputId}
-        disabled={disabled}
+        // A reason wins over `disabled`, as on Button: the switch stays reachable.
+        disabled={locked ? undefined : disabled}
         required={required}
         {...rest}
         // After the spread: a caller's props object must not be able to turn this
         // back into a plain checkbox, or into a text field.
         type="checkbox"
         role="switch"
-        aria-describedby={mergeDescribedBy(rest["aria-describedby"], showDescription && descriptionId)}
+        aria-disabled={locked || rest["aria-disabled"] || undefined}
+        aria-describedby={mergeDescribedBy(
+          rest["aria-describedby"],
+          showDescription && descriptionId,
+          locked && lock.reasonId,
+        )}
+        // A locked switch's click is swallowed, as a locked Button's is.
+        onClick={locked ? undefined : onClick}
         onChange={(e: ChangeEvent<HTMLInputElement>) => {
+          if (locked) {
+            // Put the thumb back and report nothing — see Checkbox for why here and not
+            // by cancelling the click. Label clicks and Space arrive as clicks too.
+            e.currentTarget.checked = !e.currentTarget.checked;
+            return;
+          }
           onChange?.(e);
           onCheckedChange?.(e.target.checked);
         }}
-        className={cn(TRACK, geometry.track, inputClassName)}
+        className={cn(TRACK, geometry.track, locked && "cursor-not-allowed", inputClassName)}
       />
       <span aria-hidden className={cn(THUMB, geometry.thumb)} />
     </span>
   );
+  // The Tooltip goes round the track, not the row — the row is the caller's layout. A
+  // bare switch hands its `className` to the wrapper, then the outermost element.
+  const control = locked ? (
+    <LockedReason lock={lock} className={cn("shrink-0", bare && className)}>
+      {track}
+    </LockedReason>
+  ) : (
+    track
+  );
 
   if (bare) return control;
 
@@ -148,7 +199,7 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(function Switch(
           htmlFor={inputId}
           className={cn(
             "block text-sm leading-5 text-[var(--text-primary)]",
-            disabled ? "cursor-not-allowed" : "cursor-pointer select-none",
+            looksDisabled ? "cursor-not-allowed" : "cursor-pointer select-none",
           )}
         >
           {label}
@@ -168,7 +219,7 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(function Switch(
   );
 
   return (
-    <div className={cn("flex items-start gap-3", disabled && "opacity-60", className)}>
+    <div className={cn("flex items-start gap-3", looksDisabled && "opacity-60", className)}>
       {switchPosition === "end" ? (
         <>
           {words}