@eifi1/ui-kit 0.11.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/field.tsx

@@ -55,6 +55,40 @@ export interface FieldControlProps {
   "aria-required": true | undefined;
 }
 
+/**
+ * The second argument of a `Field`'s render-prop children: what a GROUP needs that
+ * a single control does not. `htmlFor` names an `<input>`, but a `<label>` pointing
+ * at a `role="radiogroup"` div names nothing — so a group (a {@link ToggleGroup})
+ * takes `aria-labelledby={labelId}` instead. Kept out of {@link FieldControlProps}
+ * so the spread every existing control takes is unchanged.
+ */
+export interface FieldRenderMeta {
+  /** The label element's id, or `undefined` when the field has no label. */
+  labelId: string | undefined;
+}
+
+/**
+ * Where the label is visible. `"visible"` (default); `"sr-only"`: never drawn, still
+ * the control's name; `"below-sm"` / `"below-md"` / `"below-lg"`: drawn only under
+ * that breakpoint and screen-reader-only from it up.
+ *
+ * For table-like editors — kastlan's journal entry lines
+ * (accounting/components/wizard/journal-entry-lines-step.tsx) — where a desktop
+ * row sits under column headers that already say "Account" and "Amount", but the
+ * phone layout stacks each line as a card and needs the labels back. The name stays
+ * on the control at every width; only the ink changes.
+ */
+export type FieldLabelVisibility = "visible" | "sr-only" | "below-sm" | "below-md" | "below-lg";
+
+// Literal class strings so Tailwind's scanner sees each one.
+const LABEL_VISIBILITY: Record<FieldLabelVisibility, string | undefined> = {
+  visible: undefined,
+  "sr-only": "sr-only",
+  "below-sm": "sm:sr-only",
+  "below-md": "md:sr-only",
+  "below-lg": "lg:sr-only",
+};
+
 export interface FieldProps {
   /** The label above the control. Omit it for a group whose control is labelled
    *  some other way; the hint and error still render. */
@@ -74,10 +108,13 @@ export interface FieldProps {
   disabled?: boolean;
   /** The label's size: `sm` for a dense row, `md` otherwise. */
   labelSize?: "sm" | "md";
+  /** See {@link FieldLabelVisibility}. */
+  labelVisibility?: FieldLabelVisibility;
   /** Wrapper className. */
   className?: string;
-  /** The control. A function receives {@link FieldControlProps} to spread on it. */
-  children: ReactNode | ((control: FieldControlProps) => ReactNode);
+  /** The control. A function receives {@link FieldControlProps} to spread on it, and
+   *  {@link FieldRenderMeta} (the label's id, for a group). */
+  children: ReactNode | ((control: FieldControlProps, meta: FieldRenderMeta) => ReactNode);
 }
 
 const isShown = (node: ReactNode) =>
@@ -91,6 +128,7 @@ export function Field({
   htmlFor,
   disabled,
   labelSize,
+  labelVisibility = "visible",
   className,
   children,
 }: FieldProps) {
@@ -98,6 +136,7 @@ export function Field({
   const id = htmlFor ?? `${generated}-control`;
   const hintId = `${generated}-hint`;
   const errorId = `${generated}-error`;
+  const labelId = `${generated}-label`;
   const hasHint = isShown(hint);
   const hasError = isShown(error);
   const describedBy = [hasHint && hintId, hasError && errorId].filter(Boolean).join(" ");
@@ -108,20 +147,32 @@ export function Field({
     "aria-required": required || undefined,
   };
   return (
-    <div data-slot="field" className={cn("grid gap-1.5", className)}>
+    <div
+      data-slot="field"
+      className={cn(
+        "grid gap-1.5",
+        // A hidden label is `position: absolute`; `relative` keeps its containing
+        // block here rather than the page's (see sr-only-containment.test).
+        labelVisibility !== "visible" && "relative",
+        className,
+      )}
+    >
       {label !== undefined && (
         <Label
+          id={labelId}
           htmlFor={id}
           required={required}
           disabled={disabled}
           size={labelSize}
           data-error={hasError || undefined}
-          className="data-[error=true]:text-[var(--danger)]"
+          className={cn("data-[error=true]:text-[var(--danger)]", LABEL_VISIBILITY[labelVisibility])}
         >
           {label}
         </Label>
       )}
-      {typeof children === "function" ? children(control) : children}
+      {typeof children === "function"
+        ? children(control, { labelId: label !== undefined ? labelId : undefined })
+        : children}
       {hasHint && (
         <p id={hintId} className="text-[11px] leading-tight text-[var(--text-muted)]">
           {hint}

package/src/components/floating-panel.tsx

@@ -15,7 +15,8 @@ import { X } from "lucide-react";
 
 import { cn } from "../lib/cn";
 import { dirOf, type Direction } from "../lib/direction";
-import { useKitLabels } from "../i18n/kit-labels";
+import { useKitLabels, useKitLink } from "../i18n/kit-labels";
+import { pickLinkRenderer } from "./text-link";
 import { Tooltip, type TooltipSide } from "./tooltip";
 
 export interface FloatingPanelLabels {
@@ -588,8 +589,17 @@ export interface FloatingActionProps extends Omit<ButtonHTMLAttributes<HTMLButto
   label: string;
   icon: ReactNode;
   /** Make it a toggle: `aria-pressed` and the brand "on" look (the brand glyph on the
-   *  quiet brand fill), as {@link FloatingActionButtonProps.pressed}. Ignored on a link. */
+   *  quiet brand fill), as {@link FloatingActionButtonProps.pressed}. Ignored on a link.
+   *  For the state without the tint, see {@link pressedStyle}. */
   pressed?: boolean;
+  /**
+   * How `pressed` looks. `tint` (default): the brand "on" look. `plain`: the member
+   * keeps its quiet look in both states and only `aria-pressed` changes — for a toggle
+   * whose icon already says which state it is in (keksdose's /transactions "Upcoming"
+   * swaps two icons; a tint on top said it twice). The same as passing `aria-pressed`
+   * without `pressed`, which also rides through untinted.
+   */
+  pressedStyle?: "tint" | "plain";
   /**
    * `primary`: the brand-filled member, for the group's main action (the /transactions
    * "+"). Default: the quiet one.
@@ -611,8 +621,8 @@ export interface FloatingActionProps extends Omit<ButtonHTMLAttributes<HTMLButto
   tooltip?: boolean;
   /** Where the tooltip opens. Default `top` — the group sits at the bottom of the screen. */
   tooltipSide?: TooltipSide;
-  /** Make it a link — the /transactions invoices member. A plain `<a>` unless
-   *  `renderLink` hands it to your router. */
+  /** Make it a link — the /transactions invoices member. Drawn by `renderLink`, else
+   *  the `<UiKitProvider linkComponent>` (an in-app `href`), else a plain `<a>`. */
   href?: string;
   /** Render the link through your router's `Link` — see {@link FloatingActionLinkProps}. */
   renderLink?: (props: FloatingActionLinkProps) => ReactElement;
@@ -637,6 +647,7 @@ export function FloatingAction({
   label,
   icon,
   pressed,
+  pressedStyle = "tint",
   variant = "default",
   badge,
   badgeLabel,
@@ -652,6 +663,7 @@ export function FloatingAction({
   ...rest
 }: FloatingActionProps) {
   const labels = useKitLabels("floatingPanel", DEFAULT_FLOATING_PANEL_LABELS);
+  const kitLink = useKitLink();
   const counted = badge !== undefined && badge > 0;
   const name = counted ? `${label}, ${badgeLabel ?? labels.badge(badge)}` : label;
   const isLink = href !== undefined;
@@ -661,7 +673,7 @@ export function FloatingAction({
     "disabled:cursor-not-allowed disabled:opacity-50 [&_svg]:size-5",
     variant === "primary"
       ? "bg-[var(--brand)] text-[var(--brand-contrast)] hover:bg-[var(--brand-hover)]"
-      : pressed && !isLink
+      : pressed && !isLink && pressedStyle === "tint"
         ? "bg-[var(--brand-bg)] text-[var(--brand)] hover:bg-[var(--brand-bg-hover)]"
         : "text-[var(--text-secondary)] hover:bg-[var(--bg-hover)] hover:text-[var(--text-primary)]",
     className,
@@ -697,8 +709,9 @@ export function FloatingAction({
       children: body,
     };
     const { children: content, ...anchor } = linkProps;
-    member = renderLink ? (
-      <RenderedFloatingLink render={renderLink} {...linkProps} />
+    const render = pickLinkRenderer(renderLink, kitLink, href);
+    member = render ? (
+      <RenderedFloatingLink render={render} {...linkProps} />
     ) : (
       <a {...anchor}>{content}</a>
     );

package/src/components/form-actions.tsx

@@ -0,0 +1,191 @@
+import { isValidElement } from "react";
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { useKitLabels } from "../i18n/kit-labels";
+import { Button, Spinner, type ButtonVariant } from "./ui";
+
+/** The words {@link FormActions} renders on its own behalf — the `form` namespace. */
+export interface FormActionsLabels {
+  save: string;
+  cancel: string;
+}
+
+export const DEFAULT_FORM_ACTIONS_LABELS: FormActionsLabels = {
+  save: "Save",
+  cancel: "Cancel",
+};
+
+export type FormActionsAlign = "start" | "center" | "end" | "between";
+
+/**
+ * Where the row sits:
+ *  - `inline` (default): under the form's last field, `pt-4` above it.
+ *  - `sticky`: stuck to the bottom of the scrolling page or pane, on the surface
+ *    colour with a rule above, clear of the phone's home indicator — for a long form
+ *    whose Save should not be a scroll away.
+ *  - `dialog`: no spacing of its own, for a dialog's footer slot (DialogFrame,
+ *    FullBleedDialog's `footer`), which already pads and rules it.
+ */
+export type FormActionsPlacement = "inline" | "sticky" | "dialog";
+
+/** The start-side action of {@link FormActionsProps.destructive}, as data. */
+export interface FormActionsDestructive {
+  label: ReactNode;
+  onClick: () => void;
+  disabled?: boolean;
+  /** See Button's `disabledReason`. */
+  disabledReason?: ReactNode;
+}
+
+const ALIGN_CLASS: Record<FormActionsAlign, string> = {
+  start: "justify-start",
+  center: "justify-center",
+  end: "justify-end",
+  between: "justify-between",
+};
+
+const PLACEMENT_CLASS: Record<FormActionsPlacement, string> = {
+  inline: "pt-4",
+  sticky: "sticky bottom-0 z-10 border-t border-[var(--border)] bg-[var(--bg-surface)] pt-3",
+  dialog: "",
+};
+
+export interface FormActionsProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+  /** Called by Cancel. Omitted: no Cancel button (a form that only saves). */
+  onCancel?: () => void;
+  /**
+   * Given: the save button is `type="button"` and calls this — for a dialog or a row
+   * that saves from a handler. Omitted: it is `type="submit"` and submits the
+   * enclosing `<form>` (or the one named by {@link form}).
+   */
+  onSubmit?: () => void;
+  /** The save button's text. Default `form.save` from the provider, else "Save". */
+  submitLabel?: ReactNode;
+  /** The cancel button's text. Default `form.cancel` from the provider, else "Cancel". */
+  cancelLabel?: ReactNode;
+  /** The save button's text while `pending` ("Saving…"). Default: `submitLabel`. */
+  pendingLabel?: ReactNode;
+  /**
+   * The save is running: a spinner in the save button, `aria-busy` on it, and the
+   * button disabled, so a second click cannot send the form twice. Cancel stays
+   * usable.
+   */
+  pending?: boolean;
+  /** Disable save for a reason of the form's own (an unbalanced entry). */
+  submitDisabled?: boolean;
+  /** Why save is disabled — see Button's `disabledReason`. Keeps it focusable. */
+  submitDisabledReason?: ReactNode;
+  /** The save button's variant. Default `brand`; `danger` for a save that destroys
+   *  (kastlan's `destructive` flag on its own FormActions). */
+  submitVariant?: ButtonVariant;
+  /**
+   * A destructive action at the START of the row, apart from Save and Cancel — the
+   * "Delete" of an edit dialog. Pass `{ label, onClick }` for the kit's quiet danger
+   * button, or an element of your own (a {@link DangerConfirm}, say). With it the row
+   * is `between`-aligned unless `align` says otherwise.
+   */
+  destructive?: ReactNode | FormActionsDestructive;
+  /** Horizontal alignment. Default `end` (`between` with a `destructive` action). */
+  align?: FormActionsAlign;
+  /** See {@link FormActionsPlacement}. Default `inline`. */
+  placement?: FormActionsPlacement;
+  /** The `id` of the `<form>` the save button submits, when the row is rendered
+   *  outside it (a dialog's footer slot). */
+  form?: string;
+  /** Extra actions, placed before Cancel. */
+  children?: ReactNode;
+}
+
+function isDestructiveData(value: unknown): value is FormActionsDestructive {
+  return typeof value === "object" && value !== null && !isValidElement(value) && "onClick" in value;
+}
+
+/**
+ * The Save / Cancel row every form, wizard-step form and dialog ends in — kastlan's
+ * `FormActions`, with the labels from the provider, a pending state and a place for
+ * the destructive action.
+ *
+ * ```tsx
+ * <form onSubmit={form.handleSubmit(save)}>
+ *   …
+ *   <FormActions onCancel={close} pending={mutation.isPending} />
+ * </form>
+ * ```
+ *
+ * The spinner is the kit's {@link Spinner}, drawn inside the button with `label={null}`
+ * so the button's name stays its text; `aria-busy` is what says it is working.
+ */
+export function FormActions({
+  onCancel,
+  onSubmit,
+  submitLabel,
+  cancelLabel,
+  pendingLabel,
+  pending = false,
+  submitDisabled = false,
+  submitDisabledReason,
+  submitVariant = "brand",
+  destructive,
+  align,
+  placement = "inline",
+  form,
+  children,
+  className,
+  style,
+  ...rest
+}: FormActionsProps) {
+  const labels = useKitLabels("form", DEFAULT_FORM_ACTIONS_LABELS);
+  const hasDestructive = destructive !== undefined && destructive !== null && destructive !== false;
+  const justify = align ?? (hasDestructive ? "between" : "end");
+  const start = !hasDestructive ? null : isDestructiveData(destructive) ? (
+    <Button
+      type="button"
+      variant="ghost"
+      tone="danger"
+      onClick={destructive.onClick}
+      disabled={destructive.disabled}
+      disabledReason={destructive.disabledReason}
+    >
+      {destructive.label}
+    </Button>
+  ) : (
+    destructive
+  );
+  const saveLabel = submitLabel ?? labels.save;
+
+  return (
+    <div
+      data-slot="form-actions"
+      data-placement={placement}
+      {...rest}
+      style={
+        placement === "sticky"
+          ? { paddingBottom: "max(0.75rem, env(safe-area-inset-bottom))", ...style }
+          : style
+      }
+      className={cn("flex flex-wrap items-center gap-2", ALIGN_CLASS[justify], PLACEMENT_CLASS[placement], className)}
+    >
+      {start && <div className="me-auto flex items-center gap-2">{start}</div>}
+      <div className="flex flex-wrap items-center gap-2">
+        {children}
+        {onCancel && (
+          <Button type="button" variant="secondary" onClick={onCancel}>
+            {cancelLabel ?? labels.cancel}
+          </Button>
+        )}
+        <Button
+          type={onSubmit ? "button" : "submit"}
+          form={form}
+          onClick={onSubmit}
+          variant={submitVariant}
+          disabled={pending || submitDisabled}
+          disabledReason={pending ? undefined : submitDisabledReason}
+          aria-busy={pending || undefined}
+        >
+          {pending && <Spinner label={null} className="size-4" />}
+          {pending && pendingLabel !== undefined ? pendingLabel : saveLabel}
+        </Button>
+      </div>
+    </div>
+  );
+}

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.