@eifi1/ui-kit 0.12.0 → 0.13.0

package/src/components/field-sync.tsx

@@ -146,35 +146,40 @@ export function useFieldSync<T>({
     };
   }, []);
 
-  const flush = useCallback(async () => {
-    if (inFlightRef.current) return; // the settle path below picks the new draft up
-    const next = draftRef.current;
-    if (equalsRef.current(next, savedRef.current)) return;
-
-    inFlightRef.current = true;
-    setState("pending");
-    setError(null);
-    try {
-      await onSaveRef.current(next);
-      savedRef.current = next;
-      inFlightRef.current = false;
-      if (!mountedRef.current) return;
-      // The draft may have moved while this was in the air. Compare against what is
-      // on screen NOW, not against what was sent.
-      if (equalsRef.current(draftRef.current, next)) {
-        setState("synced");
-      } else {
-        setState("edited");
-        void flush();
+  // A named inner function so the settle path can start the next round by calling it
+  // again; a `useCallback` cannot refer to its own binding while it is being built.
+  const flush = useCallback(() => {
+    const run = async (): Promise<void> => {
+      if (inFlightRef.current) return; // the settle path below picks the new draft up
+      const next = draftRef.current;
+      if (equalsRef.current(next, savedRef.current)) return;
+
+      inFlightRef.current = true;
+      setState("pending");
+      setError(null);
+      try {
+        await onSaveRef.current(next);
+        savedRef.current = next;
+        inFlightRef.current = false;
+        if (!mountedRef.current) return;
+        // The draft may have moved while this was in the air. Compare against what is
+        // on screen NOW, not against what was sent.
+        if (equalsRef.current(draftRef.current, next)) {
+          setState("synced");
+        } else {
+          setState("edited");
+          void run();
+        }
+      } catch (cause) {
+        inFlightRef.current = false;
+        const err = toError(cause);
+        onErrorRef.current?.(err);
+        if (!mountedRef.current) return;
+        setState("error");
+        setError(err);
       }
-    } catch (cause) {
-      inFlightRef.current = false;
-      const err = toError(cause);
-      onErrorRef.current?.(err);
-      if (!mountedRef.current) return;
-      setState("error");
-      setError(err);
-    }
+    };
+    return run();
   }, []);
 
   const setValue = useCallback(
@@ -396,23 +401,26 @@ export function FieldSyncRow<T>({
   const retry = onRetry ?? sync.retry;
 
   // The saved confirmation: on only for the moment after a save lands. Keyed on the
-  // TRANSITION pending → synced, so a field that starts synced shows nothing.
-  const previous = useRef(state);
+  // TRANSITION pending → synced, so a field that starts synced shows nothing. The
+  // transition is seen while rendering, against the previous state; the effect only
+  // owns the timer that turns it off again.
+  const [previous, setPrevious] = useState(state);
   const [justSaved, setJustSaved] = useState(false);
+  if (state !== previous) {
+    setPrevious(state);
+    setJustSaved(state === "synced" && previous === "pending");
+  }
   useEffect(() => {
-    const was = previous.current;
-    previous.current = state;
-    if (state === "synced" && was === "pending") {
-      // eslint-disable-next-line react-hooks/set-state-in-effect -- reacts to the save landing
-      setJustSaved(true);
-      const t = setTimeout(() => setJustSaved(false), savedMs);
-      return () => clearTimeout(t);
-    }
-    if (state !== "synced") setJustSaved(false);
-  }, [state, savedMs]);
+    if (!justSaved) return;
+    const t = setTimeout(() => setJustSaved(false), savedMs);
+    return () => clearTimeout(t);
+  }, [justSaved, savedMs]);
   const shown: FieldSyncState | null = state === "synced" ? (justSaved ? "synced" : null) : state;
 
   return (
+    /* eslint-disable-next-line jsx-a11y/no-static-element-interactions -- not an interaction:
+       `onBlur` listens for focus leaving the row's own controls (which are the
+       interactive elements) to save; the wrapper itself is never focused. */
     <div
       data-field-sync={state}
       className={cn(

package/src/components/full-bleed-dialog.tsx

@@ -169,6 +169,10 @@ export function FullBleedDialog({
   if (!open || typeof document === "undefined") return null;
 
   return createPortal(
+    /* eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- the dialog
+       container, per the APG dialog pattern: `onKeyDown` is Escape-to-close for whatever
+       inside it holds focus, and the mouse handlers are the backdrop press (Escape and the
+       close button are its keyboard path). */
     <div
       // `animate-overlay` on the backdrop and `animate-sheet` on the panel (live #320):
       // the backdrop fades, the panel rises from the bottom edge it is anchored to.

package/src/components/hover-menu.tsx

@@ -103,22 +103,24 @@ export function HoverMenu({
   // close what was just opened (feedback #19). Toggling closed on click stays
   // for keyboard/touch activation, which reaches "open" without going through
   // the hover path.
-  const openedByHoverRef = useRef(false);
+  //
+  // State rather than a ref: `close` is handed to the caller's render prop, and a
+  // function that writes a ref must not be reachable from render.
+  const [openedByHover, setOpenedByHover] = useState(false);
 
   const close = useCallback(() => {
-    openedByHoverRef.current = false;
+    setOpenedByHover(false);
     setPhase("closed");
   }, []);
 
-  const toggle = useCallback(
-    () =>
-      setPhase((p) => {
-        if (p === "open" || p === "closing") return openedByHoverRef.current ? p : "closed";
-        openedByHoverRef.current = false;
-        return "open";
-      }),
-    [],
-  );
+  const toggle = useCallback(() => {
+    if (open) {
+      if (!openedByHover) setPhase("closed");
+      return;
+    }
+    setOpenedByHover(false);
+    setPhase("open");
+  }, [open, openedByHover]);
 
   const handleMouseEnter = useCallback(
     () => setPhase((p) => (p === "closing" ? "open" : p === "closed" ? "opening" : p)),
@@ -134,7 +136,7 @@ export function HoverMenu({
   useEffect(() => {
     if (phase === "opening") {
       const id = setTimeout(() => {
-        openedByHoverRef.current = true;
+        setOpenedByHover(true);
         setPhase("open");
       }, OPEN_DELAY_MS);
       return () => clearTimeout(id);
@@ -217,7 +219,7 @@ export function HoverMenu({
           (edge === "last" ? list[list.length - 1] : list[0])?.focus();
         } else {
           focusOnOpenRef.current = edge;
-          openedByHoverRef.current = false;
+          setOpenedByHover(false);
           setPhase("open");
         }
       }
@@ -247,11 +249,14 @@ export function HoverMenu({
   // subtracted first so the measurement is against the natural position.
   const panelRef = useRef<HTMLDivElement>(null);
   const [shiftX, setShiftX] = useState(0);
+  // Back to 0 on close, adjusted while rendering against the previous `open`.
+  const [wasOpen, setWasOpen] = useState(open);
+  if (open !== wasOpen) {
+    setWasOpen(open);
+    if (!open) setShiftX(0);
+  }
   useLayoutEffect(() => {
-    if (!open) {
-      setShiftX(0);
-      return;
-    }
+    if (!open) return;
     const el = panelRef.current;
     if (!el) return;
     const rect = el.getBoundingClientRect();
@@ -267,6 +272,10 @@ export function HoverMenu({
   }, [open]);
 
   return (
+    /* eslint-disable-next-line jsx-a11y/no-static-element-interactions -- never focused
+       itself: the mouse handlers are the hover-to-open convenience, and `onKeyDown`
+       catches keys bubbling from the caller's trigger button and the menuitems, which
+       are the keyboard path (Enter/Space/arrows open, arrows move, Escape closes). */
     <div
       // `...rest` first: the hover handlers below are the whole component, and a caller
       // passing one of its own must not silently replace them.

package/src/components/list.tsx

@@ -106,8 +106,20 @@ const TARGET_RING =
   "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-[var(--brand)]";
 
 interface ListItemBaseProps {
-  /** The row's name: one line, truncated. */
+  /** The row's name: one line, truncated — unless {@link titleLines} says otherwise. */
   title: ReactNode;
+  /**
+   * How many lines the title may take. `1` (default) truncates with an ellipsis, which
+   * is right for a name the app chose — a unit number, a user, a file — where the
+   * cut-off end is still recognisable and every row keeps one height.
+   *
+   * `2` clamps at two lines; `"all"` shows every line, breaking inside a long word
+   * rather than overflowing. For rows whose only name is free text a person typed
+   * (kastlan 44): a defect or a note titled by its description, where the first 30
+   * characters on a phone say nothing and there is no other field to tell two rows
+   * apart. Pair it with `align="start"` so the icon stays by the first line.
+   */
+  titleLines?: 1 | 2 | "all";
   /** The line under it: one line, truncated — or two, with `subtitleLines={2}`. */
   subtitle?: ReactNode;
   /** `2` for a line that is a body rather than a label (keksdose's notification text). */
@@ -256,7 +268,7 @@ export type ListItemProps = ListItemBaseProps &
 
 /**
  * One row of a {@link List}: leading icon or avatar, title and subtitle (both
- * truncating), a trailing slot, and — beside the row, not inside it — its actions.
+ * truncating by default), a trailing slot, and — beside the row, not inside it — its actions.
  *
  * All three apps draw this row by hand, a dozen times: kastlan's units
  * (building-detail-page.tsx:402), open tickets (group-overview-page.tsx:160), activity
@@ -269,6 +281,7 @@ export type ListItemProps = ListItemBaseProps &
 export const ListItem = forwardRef<HTMLElement, ListItemProps>(function ListItem(
   {
     title,
+    titleLines = 1,
     subtitle,
     subtitleLines = 1,
     meta,
@@ -329,7 +342,8 @@ export const ListItem = forwardRef<HTMLElement, ListItemProps>(function ListItem
           // Names the body's group; harmless without one.
           id={hasBody ? titleId : undefined}
           className={cn(
-            "block truncate text-sm text-[var(--text-primary)]",
+            "block text-sm text-[var(--text-primary)]",
+            titleLines === 1 ? "truncate" : titleLines === 2 ? "line-clamp-2 break-words" : "break-words",
             unread ? "font-semibold" : "font-medium",
           )}
         >

package/src/components/modal.tsx

@@ -370,6 +370,10 @@ function ModalPanel({
       )}
       {...backdropClose}
     >
+      {/* eslint-disable-next-line jsx-a11y/no-static-element-interactions -- always
+          role="dialog" or "alertdialog" (the ternary hides that from the rule): `onKeyDown`
+          is Escape-to-close per the APG dialog pattern, and the drag handlers are
+          swipe-to-dismiss, whose keyboard path is that same Escape. */}
       <div
         // `...rest` FIRST, everything the dialog needs to be a dialog after it. A
         // wrapper that spreads its own props through to this one cannot then take away

package/src/components/multi-entity-combobox.tsx

@@ -127,7 +127,7 @@ export function MultiEntityCombobox<V extends string | number>({
     create: createLabel,
   });
   const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
-  const { open, results, resolve, setOpen } = core;
+  const { open, results, resolve, setOpen, query, triggerRef } = core;
   // One id per instance, generated here rather than in the core: `aria-controls` on
   // the trigger has to name the list while the list is still closed, so the id
   // belongs to whoever renders both ends of it.
@@ -154,13 +154,13 @@ export function MultiEntityCombobox<V extends string | number>({
       : labels.selectedCount(value.length);
   })();
 
-  const q = core.query.trim();
+  const q = query.trim();
   const showCreate =
     Boolean(onCreate) && q.length > 0 && !results.some((o) => o.label.toLowerCase() === q.toLowerCase());
   const showClear = Boolean(clearable && value.length > 0 && !disabled);
 
   const toggle = (o: ComboOption<V>) => {
-    core.cacheRef.current.set(o.value, o);
+    core.rememberOption(o);
     if (valueSet.has(o.value)) onChange(value.filter((v) => v !== o.value));
     else onChange([...value, o.value]);
     // Stay open — multi-select keeps adding.
@@ -174,7 +174,7 @@ export function MultiEntityCombobox<V extends string | number>({
     <div {...rest} className={cn("relative", className)}>
       {label !== undefined && <FieldLabel>{label}</FieldLabel>}
       <button
-        ref={core.triggerRef}
+        ref={triggerRef}
         id={id}
         type="button"
         // A combobox, not a button. The distinction is not pedantry: this control
@@ -234,6 +234,10 @@ export function MultiEntityCombobox<V extends string | number>({
           {summary}
         </span>
         {showClear ? (
+          /* eslint-disable-next-line jsx-a11y/click-events-have-key-events -- tabIndex -1 inside
+              the trigger <button>, so it never holds focus and a key handler here could
+              never fire. A pointer shortcut; the keyboard path is unticking the options
+              in the open list. */
           <span
             role="button"
             tabIndex={-1}

package/src/components/number-input.tsx

@@ -232,6 +232,7 @@ export function NumberInput({
         // keeps focus/caret); desktop keeps the native decimal keypad.
         inputMode={isMobile ? "none" : "decimal"}
         autoComplete="off"
+        // eslint-disable-next-line jsx-a11y/no-autofocus -- a documented prop the caller opts into (off by default); the field never takes focus on its own.
         autoFocus={autoFocus}
         disabled={disabled}
         // Display mode has no floating label to feed the blank-placeholder trick,

package/src/components/numpad-sheet.tsx

@@ -99,11 +99,16 @@ export function NumberPadSheet({
   onDone,
   label,
   labels,
+  decimalMark = ".",
 }: {
   value: string;
   /** Fired with the raw (sanitised) field text on every key — same contract as
    * the host field's own `onChange`. */
   onChange: (value: string) => void;
+  /** The glyph on the decimal key — "," where the host shows a comma (AmountInput
+   *  in fr-CH, kastlan 40). The key still inserts a dot; the host's text is dot-form
+   *  underneath and `sanitizeLive` reads either. */
+  decimalMark?: "." | ",";
   /** Fired on "Done": the host blurs the input, which commits (evaluates) and
    * unmounts the sheet via its existing blur handler. */
   onDone: () => void;
@@ -231,7 +236,7 @@ export function NumberPadSheet({
               onClick={() => insert(key.ins)}
               className={cn(PAD_BTN, key.accent ? PAD_ACCENT : PAD_DIGIT)}
             >
-              {key.label}
+              {key.kind === "ins" && key.name === "decimal" ? decimalMark : key.label}
             </button>
           ),
         )}

package/src/components/page-header.tsx

@@ -2,21 +2,44 @@ import type { ComponentPropsWithoutRef, ElementType, ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { SECTION_LABEL_CLASS } from "./text";
 
-/** `md` (default) is kastlan's `text-2xl` page title from `sm` up, a step smaller on a
- *  phone; `sm` is lenkbank's `text-lg` title on a dense tool page (projects-page.tsx). */
-export type PageHeaderSize = "sm" | "md";
+/**
+ * `md` (default) is kastlan's `text-2xl` page title from `sm` up, a step smaller on a
+ * phone; `sm` is lenkbank's `text-lg` title on a dense tool page (projects-page.tsx).
+ *
+ * `compact` (0.13) is keksdose's page title (keksdose F4): `text-xl font-semibold` at
+ * EVERY width — budgets, rules, accounts, transactions and budget pages all write
+ * exactly that `<h1>` by hand. It is `md`'s phone size without `md`'s step up to
+ * `text-2xl` on a wider screen, and without its `tracking-tight`, which keksdose's
+ * titles never had. A word and not a letter for the reason `ProgressBar`'s `slim` is
+ * one: the letters are taken in order, and there is none between `sm` and `md` — an
+ * `lg` or `xl` at `text-xl` would read as LARGER than `md`, which from `sm` up it is
+ * not.
+ */
+export type PageHeaderSize = "sm" | "compact" | "md";
 
 const TITLE: Record<PageHeaderSize, string> = {
   sm: "text-lg font-semibold",
+  compact: "text-xl font-semibold",
   md: "text-xl font-semibold tracking-tight sm:text-2xl",
 };
 
+/**
+ * How the title block and the actions sit below the `sm` breakpoint. From `sm` up both
+ * layouts are one row: title block at the start, actions at the end.
+ */
+export type PageHeaderMobileLayout = "stacked" | "inline";
+
+const ROW: Record<PageHeaderMobileLayout, string> = {
+  stacked: "flex-col gap-3 sm:flex-row sm:items-start sm:justify-between sm:gap-4",
+  inline: "flex-row items-center justify-between gap-2 sm:gap-4",
+};
+
 export interface PageHeaderProps extends Omit<ComponentPropsWithoutRef<"div">, "title"> {
   title: ReactNode;
   /** A sentence under the title. */
   description?: ReactNode;
   /** Buttons for the page — "New", "Export". At the title's end from `sm` up; under it,
-   *  wrapping, on a phone. */
+   *  wrapping, on a phone — unless {@link mobileLayout} is `inline`. */
   actions?: ReactNode;
   /** A `Breadcrumbs` trail, drawn above everything else. */
   breadcrumbs?: ReactNode;
@@ -27,6 +50,19 @@ export interface PageHeaderProps extends Omit<ComponentPropsWithoutRef<"div">, "
    *  header inside a page that already has its `h1` (a tab's own header). */
   as?: "h1" | "h2" | "h3";
   size?: PageHeaderSize;
+  /**
+   * `stacked` (default): on a phone the actions drop under the title and wrap, so a
+   * row of three buttons never pushes the title off the screen.
+   *
+   * `inline`: the actions stay beside the title on a phone too, vertically centred on
+   * it — keksdose's headers (transactions-page.tsx:515, `flex items-center
+   * justify-between gap-2`), which carry one or two icon-sized controls and were tuned
+   * for the phone in live #263. Adopting `PageHeader` must not undo that tuning, so the
+   * row stays a row (keksdose F4). The actions do NOT wrap or shrink here: `inline` is
+   * for a header whose actions are known to fit beside a phone-width title (an icon
+   * button, a month picker); a long title wraps to make room for them instead.
+   */
+  mobileLayout?: PageHeaderMobileLayout;
 }
 
 /**
@@ -48,6 +84,7 @@ export function PageHeader({
   eyebrow,
   as = "h1",
   size = "md",
+  mobileLayout = "stacked",
   className,
   ...rest
 }: PageHeaderProps) {
@@ -55,7 +92,7 @@ export function PageHeader({
   return (
     <div {...rest} className={cn("flex min-w-0 flex-col gap-2", className)}>
       {breadcrumbs}
-      <div className="flex min-w-0 flex-col gap-3 sm:flex-row sm:items-start sm:justify-between sm:gap-4">
+      <div className={cn("flex min-w-0", ROW[mobileLayout])}>
         <div className="min-w-0 flex-1">
           {eyebrow != null && <p className={cn(SECTION_LABEL_CLASS.xs, "mb-1")}>{eyebrow}</p>}
           <Heading className={cn("break-words text-[var(--text-primary)]", TITLE[size])}>{title}</Heading>

package/src/components/picker-sheet.tsx

@@ -154,6 +154,9 @@ export function PickerSheet({
 
   if (!open || typeof document === "undefined") return null;
   return createPortal(
+    /* eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- the dialog
+       container, per the APG dialog pattern: `onKeyDown` is Escape-to-close for whatever
+       inside it holds focus, and `onMouseDown` only stops propagation (live #328). */
     <div
       // Spread FIRST, and every attribute below it deliberately wins: `style`,
       // `onMouseDown` and `onKeyDown` here are not styling choices, they are live

package/src/components/popover.tsx

@@ -169,6 +169,9 @@ export function Popover({
       {trigger({ open, toggle, ref: triggerRef })}
       {open && pos &&
         createPortal(
+          /* eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- the
+             dialog container, per the APG dialog pattern: `onKeyDown` is Escape-to-close for
+             whatever inside it holds focus. */
           <div
             // `...rest` first: the role, the id the trigger's `aria-controls` points at,
             // the `tabIndex` the trap needs and the measured position are what make this

package/src/components/signed-amount.tsx

@@ -223,7 +223,8 @@ export interface DeltaProps extends SignedFormatProps, Omit<ComponentPropsWithou
   goodDirection?: GoodDirection;
   /** What it is measured against, after it: "vs last month". */
   label?: ReactNode;
-  /** Hide the arrow (shown by default, as on a StatTile). */
+  /** Hide the arrow (shown by default, as on a StatTile). At zero the arrow is a flat
+   *  dash BESIDE the figure ("– 0.00 %"), never in place of it. */
   arrow?: boolean;
   sensitive?: boolean;
   /** The `statTile` namespace's direction words — a delta says the same as a tile's. */
@@ -276,8 +277,16 @@ export function Delta({
     >
       <span data-private={sensitive ? "" : undefined} className={cn("inline-flex items-center gap-0.5 font-medium", tone)}>
         {arrow && <Icon className="size-[1em] shrink-0" aria-hidden />}
-        {/* Flat with an arrow is the dash alone, as on a tile; without one, the zero. */}
-        <span aria-hidden>{dir === "flat" && arrow ? null : amount}</span>
+        {/* The figure at zero too, beside the flat dash (kastlan feedback #48). Before
+            this a flat delta with an arrow drew the dash ALONE, as a StatTile does — so
+            a rent-change column that printed "0.00 %" for an unchanged lease showed a
+            bare "–" in its place, and a bare dash is what a table prints for a MISSING
+            value: "unchanged" and "not known" looked the same. The Minus icon is the
+            neutral indicator, the muted tone the neutral colour, and the figure says
+            how much (none) in the column's own digits. A value that is missing never
+            reaches here — a non-finite one renders nothing, above. Visible change for
+            every `<Delta value={0}>` with the default arrow: "–" became "– 0 %". */}
+        <span aria-hidden>{amount}</span>
         <span className="sr-only">{spoken}</span>
       </span>
       {label != null && <span className="text-[var(--text-muted)]">{label}</span>}

package/src/components/stat-tile.tsx

@@ -379,7 +379,9 @@ export function StatTile({
       <div className="relative mt-1 flex flex-wrap items-center gap-x-1.5 text-xs tabular-nums">
         <span id={deltaId} data-private={priv} className={cn("inline-flex items-center gap-0.5 font-medium", deltaTone)}>
           <Icon className="size-3 shrink-0" aria-hidden />
-          <span aria-hidden>{dir === "flat" ? null : amount}</span>
+          {/* The figure at zero too, like Delta (kastlan 48): "0 %" says the change was
+              measured; a bare dash reads like a missing value. */}
+          <span aria-hidden>{amount}</span>
           <span className="sr-only">{spoken}</span>
         </span>
         {d.label != null && <span className="text-[var(--text-muted)]">{d.label}</span>}

package/src/components/swipeable-row.tsx

@@ -164,13 +164,13 @@ export function SwipeableRow({
   // painted the RIGHT action's colour into the gap. With no left action at all that
   // colour was the only thing the gesture ever showed.
   //
-  // Written during render rather than in an effect: an effect would repaint a frame
-  // later (visibly, at 150ms) and `setState` in an effect body is an eslint error in
-  // the consuming app. The value is derived from this render's own dx, so a
-  // concurrent re-render recomputes it identically.
-  const lastSide = useRef<"left" | "right">("right");
-  if (dx !== 0) lastSide.current = dx < 0 ? "left" : "right";
-  const draggingLeft = dx !== 0 ? dx < 0 : lastSide.current === "left";
+  // Adjusted during render rather than in an effect: an effect would repaint a frame
+  // later (visibly, at 150ms). State set while rendering re-renders this component
+  // before anything is committed, so the released frame already has the right side.
+  const [lastSide, setLastSide] = useState<"left" | "right">("right");
+  const side = dx === 0 ? null : dx < 0 ? "left" : "right";
+  if (side && side !== lastSide) setLastSide(side);
+  const draggingLeft = side ? side === "left" : lastSide === "left";
   const shown = draggingLeft
     ? leftActions[Math.max(0, swipe.armedLeftIndex)]
     : rightActions[Math.max(0, swipe.armedRightIndex)];