@eifi1/ui-kit 0.21.0 → 0.23.0

package/src/components/tile-radio.tsx

@@ -6,51 +6,119 @@ import { horizontalStep } from "../lib/direction";
 import { Tooltip } from "./tooltip";
 
 /**
- * The machinery {@link SwatchPicker} and {@link IconPicker} share: a row of square
- * tiles that behaves as ONE radio group. Private to the package — not re-exported
- * from the barrel.
+ * A row of square tiles that behaves as ONE radio group — the machinery
+ * {@link SwatchPicker} and {@link IconPicker} are built on, public since 0.22.0 for the
+ * one-of-n pickers those two do not cover (kastlan's input audit: a choice whose tiles
+ * show something of the app's own — a mark, a pattern, a symbol set the kit does not
+ * ship).
  *
  * Keksdose had three of these (the category colours, the category symbols, the
  * transaction flags) and all three were rows of `aria-pressed` buttons: a separate
  * tab stop per tile, and "pressed" on a choice that is really one-of-n. The APG radio
  * group is the shape a screen reader expects for that ("Red, radio, 2 of 7, checked")
  * and the one a keyboard expects too — a single tab stop, arrows to move.
+ *
+ * ## The container is yours
+ *
+ * It renders the TILES only — no wrapper — so it can sit in a layout the caller owns
+ * (a wrapping row, a grid, a row beside a search box). That element must carry the
+ * group's semantics, as SwatchPicker's does:
+ *
+ * ```tsx
+ * <div role="radiogroup" aria-labelledby={headingId} className="flex flex-wrap gap-1.5">
+ *   <TileRadioGroup
+ *     items={[{ key: "dots", label: "Dots" }, { key: "lines", label: "Lines" }]}
+ *     checked={pattern}
+ *     onSelect={(key) => key && setPattern(key)}
+ *     renderTile={(item) => <PatternGlyph pattern={item.key} className={TILE_SIZE.md.glyph} />}
+ *   />
+ * </div>
+ * ```
+ *
+ * `role="radiogroup"` and a name (`aria-label` or `aria-labelledby`) — without them a
+ * screen reader hears radios that belong to nothing, and no "2 of 7". Set
+ * `aria-disabled` on it as well when the whole group is `disabled`.
+ *
+ * ## What a tile is
+ *
+ * A square (28 / 32 / 44px, {@link TILE_SIZE}) holding `renderTile`'s content, NAMED by
+ * the item's `label` (`aria-label`, so what is drawn inside is decoration) and showing
+ * that label in a bubble on hover and focus — a row of unlabelled squares is the
+ * complaint that put the bubble there. It is for choices that are SEEN: a colour, a
+ * glyph, a pattern. A choice that has to be READ — a plan with a price and three lines
+ * of features, an option with a sentence of explanation — is a {@link ChoiceCardGroup}
+ * (`type="radio"`): a card names its option by its title and describes it by its text,
+ * where a tile would hide the text behind a bubble and repeat it.
+ *
+ * No strings of its own: every name is an item's `label`, the "none" tile's included.
+ *
+ * ## A tile that cannot be chosen
+ *
+ * `disabled` takes a tile out of the choice AND out of reach: the arrow keys skip it
+ * and Tab never lands on it, so a dimmed square says nothing about why. Give it a
+ * `disabledReason` instead and it stays reachable, `aria-disabled`, with the reason in
+ * its bubble and its description — and choosing it does nothing (0.23, the kit's later
+ * list after keksdose K3; {@link Button}'s `disabledReason`, one tile at a time).
  */
 
+/** A tile's size: 28 / 32 / 44px — see {@link TILE_SIZE}. */
 export type TileSize = "sm" | "md" | "lg";
 
-/** 28 / 32 / 44px. `lg` is the touch target a phone surface wants (`min-h-11`). */
+/** 28 / 32 / 44px. `lg` is the touch target a phone surface wants (`min-h-11`). `glyph`
+ *  and `swatch` are the content sizes the kit's own pickers draw inside each — use them
+ *  in `renderTile` so a tile of the app's own matches theirs. */
 export const TILE_SIZE: Record<TileSize, { tile: string; glyph: string; swatch: string }> = {
   sm: { tile: "size-7", glyph: "size-3.5", swatch: "size-4" },
   md: { tile: "size-8", glyph: "size-4", swatch: "size-5" },
   lg: { tile: "size-11", glyph: "size-5", swatch: "size-6" },
 };
 
-/** One tile, whatever it shows. `key` is `null` for the "none" entry. */
+/** One tile, whatever it shows. `key` is `null` for the "none" entry — a tile of its
+ *  own that leads back to nothing, since clicking a checked tile does not uncheck it. */
 export interface TileItem<T extends string> {
   key: T | null;
   label: string;
   /** Said after the name, and shown in the bubble under it. Marks the tile with a
    *  dot, so the note is visible without hovering every tile to find it. */
   note?: string;
+  /** Out of the choice and out of reach: natively disabled, skipped by the arrow keys,
+   *  never the tab stop. */
   disabled?: boolean;
+  /**
+   * Why this tile cannot be chosen right now — a colour another category already wears,
+   * a symbol only an owner may set. The tile LOOKS disabled but is `aria-disabled`, not
+   * `disabled`: Tab and the arrow keys still reach it, the reason shows in its bubble
+   * under its name (and its `note`) and describes it, and a click, Space / Enter or an
+   * arrow under automatic activation chooses nothing — the focus moves, the checked
+   * tile stays. Wins over `disabled`, as on {@link Button}; the whole group's
+   * `disabled` still wins over it.
+   */
+  disabledReason?: ReactNode;
 }
 
 export interface TileRadioGroupProps<T extends string> {
+  /** The tiles, in reading order. Render them inside a `role="radiogroup"` element
+   *  with a name — see the module note. */
   items: TileItem<T>[];
   /** The checked key, or `undefined` for "nothing is checked" (the mixed state, or
    *  a value that is not among the options). */
   checked: T | null | undefined;
   onSelect: (key: T | null) => void;
-  /** "automatic": an arrow key moves AND checks, the APG default. "manual": arrows
-   *  move focus only, Space or Enter checks — for a picker whose change is expensive
-   *  (a bulk edit that saves on every change). */
-  activation: "automatic" | "manual";
-  disabled: boolean;
-  size: TileSize;
-  /** What goes inside a tile. The frame, the tick and the note's dot are drawn here. */
+  /** "automatic" (default): an arrow key moves AND checks, the APG default. "manual":
+   *  arrows move focus only, Space or Enter checks — for a picker whose change is
+   *  expensive (a bulk edit that saves on every change). */
+  activation?: "automatic" | "manual";
+  /** Every tile disabled. Mark the container `aria-disabled` too. Default `false`. */
+  disabled?: boolean;
+  /** 28 / 32 / 44px tiles ({@link TILE_SIZE}). Default "md"; "lg" is the touch-target
+   *  size a phone surface wants. */
+  size?: TileSize;
+  /** What goes inside a tile — `aria-hidden` decoration, since the tile is named by
+   *  `label`. Not called for the `null` ("none") item, which shows the kit's "no"
+   *  glyph. The frame, the tick and the note's dot are drawn around it. */
   renderTile: (item: TileItem<T>, selected: boolean) => ReactNode;
-  /** Extra classes for a tile, per item. */
+  /** Extra classes for a tile, per item, merged after the kit's — so a `size-*` here
+   *  beats `size`'s (a tile that grows in a narrow card). */
   tileClassName?: (item: TileItem<T>, selected: boolean) => string | undefined;
 }
 
@@ -71,28 +139,53 @@ const TILE_IDLE =
   "border-[var(--border)] bg-[var(--bg-surface)] hover:border-[var(--border-strong)] hover:bg-[var(--bg-hover)]";
 const TILE_SELECTED =
   "border-[var(--text-primary)] bg-[var(--bg-surface)] ring-1 ring-[var(--text-primary)]";
+/** A locked tile: the disabled look without `disabled` — dimmed, a not-allowed cursor. */
+const TILE_LOCKED = "cursor-not-allowed opacity-50";
+/** …and no hover offer on an idle one, which cannot be chosen. Not on the selected
+ *  tile, whose frame IS its state. */
+const TILE_LOCKED_IDLE = "hover:border-[var(--border)] hover:bg-[var(--bg-surface)]";
+
+/** `undefined`, `null`, `false` and `""` are no reason — what `cond && "…"` gives. */
+function isLocked(item: TileItem<string>): boolean {
+  const r = item.disabledReason;
+  return r !== undefined && r !== null && r !== false && r !== "";
+}
+
+/** Out of reach: natively disabled. A reason keeps a `disabled` tile reachable. */
+function isOff(item: TileItem<string>): boolean {
+  return Boolean(item.disabled) && !isLocked(item);
+}
 
+/**
+ * The tiles of one radio group, without the group element — render them inside a
+ * `role="radiogroup"` with a name (the module note above has the example). One tab stop
+ * (the checked tile, else the first that can be chosen), arrows to move — left and
+ * right follow the page's direction — Home and End to the ends, and by default the
+ * arrows choose as they go.
+ */
 export function TileRadioGroup<T extends string>({
   items,
   checked,
   onSelect,
-  activation,
-  disabled,
-  size,
+  activation = "automatic",
+  disabled = false,
+  size = "md",
   renderTile,
   tileClassName,
 }: TileRadioGroupProps<T>) {
   const refs = useRef<Array<HTMLButtonElement | null>>([]);
   const noteId = useId();
+  const reasonId = useId();
   const s = TILE_SIZE[size];
   const checkedIndex =
     checked === undefined ? -1 : items.findIndex((it) => it.key === checked);
-  // The ONE tab stop: the checked tile, else the first that can be chosen — the APG
-  // rule, so Tab into a group with nothing checked still lands somewhere.
+  // The ONE tab stop: the checked tile, else the first that can be reached — the APG
+  // rule, so Tab into a group with nothing checked still lands somewhere. A locked
+  // tile is reachable: landing on it is how its reason is read.
   const tabStop =
-    checkedIndex >= 0 && !items[checkedIndex].disabled
+    checkedIndex >= 0 && !isOff(items[checkedIndex])
       ? checkedIndex
-      : items.findIndex((it) => !it.disabled);
+      : items.findIndex((it) => !isOff(it));
 
   const onKeyDown = (e: KeyboardEvent<HTMLButtonElement>, index: number) => {
     // Left and right are VISUAL directions: in a right-to-left page the row runs the
@@ -120,7 +213,8 @@ export function TileRadioGroup<T extends string>({
         return;
     }
     e.preventDefault();
-    const enabled = items.map((it, i) => (it.disabled ? -1 : i)).filter((i) => i >= 0);
+    // Locked tiles are in the walk; natively disabled ones are not.
+    const enabled = items.map((it, i) => (isOff(it) ? -1 : i)).filter((i) => i >= 0);
     if (!enabled.length) return;
     const at = enabled.indexOf(index);
     let target: number;
@@ -129,13 +223,17 @@ export function TileRadioGroup<T extends string>({
     // Wrapping, as a native radio group does: the last tile's "next" is the first.
     else target = enabled[(at + step + enabled.length) % enabled.length];
     refs.current[target]?.focus();
-    if (activation === "automatic") onSelect(items[target].key);
+    // Onto a locked tile the focus moves and the choice does not: the checked tile
+    // stays checked, and the next arrow walks on from here.
+    if (activation === "automatic" && !isLocked(items[target])) onSelect(items[target].key);
   };
 
   return (
     <>
       {items.map((item, i) => {
         const selected = i === checkedIndex;
+        const locked = isLocked(item);
+        const describedBy = [item.note && `${noteId}-${i}`, locked && `${reasonId}-${i}`].filter(Boolean).join(" ");
         const button = (
           <button
             ref={(el) => {
@@ -146,18 +244,25 @@ export function TileRadioGroup<T extends string>({
             aria-checked={selected}
             aria-label={item.label}
             // The note is a DESCRIPTION, read after the name and the state, not glued
-            // into the name — the punctuation between the two would be English's.
-            aria-describedby={item.note ? `${noteId}-${i}` : undefined}
+            // into the name — the punctuation between the two would be English's. So
+            // is a lock's reason, after the note.
+            aria-describedby={describedBy || undefined}
             tabIndex={i === tabStop ? 0 : -1}
-            disabled={disabled || item.disabled}
+            // A reason wins over the tile's own `disabled` (as on Button): reachable,
+            // and refusing. The whole group's `disabled` still wins over both.
+            disabled={disabled || isOff(item)}
+            aria-disabled={(locked && !disabled) || undefined}
             // Clicking the checked tile again does nothing: a radio is not a toggle.
-            // "None" is the way back to nothing, and it is a tile of its own.
-            onClick={() => !selected && onSelect(item.key)}
+            // "None" is the way back to nothing, and it is a tile of its own. A locked
+            // tile is never chosen.
+            onClick={() => !selected && !locked && onSelect(item.key)}
             onKeyDown={(e) => onKeyDown(e, i)}
             className={cn(
               TILE_BASE,
               s.tile,
               selected ? TILE_SELECTED : TILE_IDLE,
+              locked && TILE_LOCKED,
+              locked && !selected && TILE_LOCKED_IDLE,
               tileClassName?.(item, selected),
             )}
           >
@@ -181,6 +286,14 @@ export function TileRadioGroup<T extends string>({
                 </span>
               </>
             )}
+            {/* The reason's description is a `hidden` copy, as on a locked Button: the
+                bubble exists only while hovered or focused once portalled, and a
+                description that comes and goes is read inconsistently. */}
+            {locked && (
+              <span id={`${reasonId}-${i}`} hidden>
+                {item.disabledReason}
+              </span>
+            )}
             {selected && <SelectedTick />}
           </button>
         );
@@ -193,10 +306,13 @@ export function TileRadioGroup<T extends string>({
           <Tooltip
             key={item.key ?? "\u0000none"}
             label={
-              item.note ? (
+              item.note || locked ? (
                 <>
                   <span className="block">{item.label}</span>
-                  <span className="block font-normal text-[var(--text-muted)]">{item.note}</span>
+                  {item.note && <span className="block font-normal text-[var(--text-muted)]">{item.note}</span>}
+                  {/* The reason in the body colour: it is the news, the note is
+                      standing context. */}
+                  {locked && <span className="block font-normal">{item.disabledReason}</span>}
                 </>
               ) : (
                 item.label

package/src/components/time-input.tsx

@@ -31,9 +31,16 @@ import { cn } from "../lib/cn";
  *    {@link FIELD_INVALID} and `aria-invalid`. A reversed window (`min="22:00"
  *    max="06:00"`, a night shift, quiet hours) is read the way the HTML spec reads it:
  *    as wrapping past midnight.
+ *
+ * `hint` is Input's too (keksdose K4): text is a caption under the field ("Local time
+ * at the site"), a {@link FieldHint} rides the label line. `showCount` is typed out — a
+ * time has no length worth counting.
  */
 export interface TimeInputProps
-  extends Omit<InputProps, "type" | "value" | "defaultValue" | "min" | "max" | "step" | "variant"> {
+  extends Omit<
+    InputProps,
+    "type" | "value" | "defaultValue" | "min" | "max" | "step" | "variant" | "showCount" | "countLabels"
+  > {
   /** `"HH:mm"` (or `"HH:mm:ss"` with a sub-minute `step`); `""` is "no time". */
   value: string;
   /** The normalised value on every change the browser reports — which for a time