@eifi1/ui-kit 0.9.0 → 0.11.0

package/src/shell/topbar-action-menu.tsx

@@ -1,20 +1,116 @@
-import type { ReactNode } from "react";
+import { useLayoutEffect, useRef } from "react";
+import type { KeyboardEvent as ReactKeyboardEvent, ReactNode } from "react";
 import { Link } from "react-router";
 import { cn } from "../lib/cn";
 import { HoverMenu } from "../components/hover-menu";
-import { TOPBAR_MENU_ITEM_CLASS, TOPBAR_TRIGGER_CLASS } from "./topbar-controls";
+import { MenuItem } from "../components/menu-item";
+import type { MenuItemTone } from "../components/menu-item";
+import { TOPBAR_TRIGGER_CLASS } from "./topbar-controls";
 
 /**
  * One row of a {@link TopBarActionMenu}. An `action` (default) runs `onSelect`, a
  * `link` navigates via react-router, and a `divider` draws a rule. Non-divider
  * rows close the menu automatically when chosen. `kind` may be omitted for
  * actions, keeping the common case terse.
+ *
+ * The rows are {@link MenuItem}s, so they take its options: `tone: "danger"` for the
+ * log-out row, `checked` (+ `checkable`) for a choice, `current` for the link to the
+ * page already open, `disabled`.
  */
 export type TopBarMenuEntry =
-  | { kind?: "action"; key: string; icon?: ReactNode; label: ReactNode; trailing?: ReactNode; onSelect: () => void }
-  | { kind: "link"; key: string; icon?: ReactNode; label: ReactNode; trailing?: ReactNode; to: string }
+  | {
+      kind?: "action";
+      key: string;
+      icon?: ReactNode;
+      label: ReactNode;
+      trailing?: ReactNode;
+      onSelect: () => void;
+      tone?: MenuItemTone;
+      /** Makes the row a choice (`menuitemradio`, or `menuitemcheckbox` with
+       *  `checkable: "checkbox"`) and says whether it is chosen. */
+      checked?: boolean;
+      checkable?: "radio" | "checkbox";
+      disabled?: boolean;
+    }
+  | {
+      kind: "link";
+      key: string;
+      icon?: ReactNode;
+      label: ReactNode;
+      trailing?: ReactNode;
+      to: string;
+      tone?: MenuItemTone;
+      /** The link to the page already open: `aria-current="page"` and a check mark. */
+      current?: boolean;
+      disabled?: boolean;
+    }
   | { kind: "divider"; key: string };
 
+/**
+ * The non-interactive identity block at the top of an account menu — kastlan's name +
+ * role, keksdose's display name + email + role chip. It is text, not a `menuitem`: the
+ * arrow keys pass over it.
+ */
+export interface TopBarMenuHeader {
+  /** The first line — the user's name. */
+  title: ReactNode;
+  /** The muted second line — an email, a role. */
+  subtitle?: ReactNode;
+  /** Anything below — a role chip. A link or button here stays out of the arrow keys
+   *  and in the Tab order, like the footer's. */
+  extra?: ReactNode;
+}
+
+/** What a control is, as far as `HoverMenu` is concerned, when it lives in the header
+ *  or the footer: not a menu row. */
+const SECTION_CONTROLS = "a[href]:not([role]),button:not([role])";
+const TABBABLE = 'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]';
+
+/**
+ * A header or footer inside the menu panel.
+ *
+ * `HoverMenu` promotes EVERY role-less button and link in its panel to a `menuitem` out
+ * of the Tab order, and turns every list into `role="none"` — right for the rows, wrong
+ * for a footer of legal links, which would join the arrow-key cycle and drop out of Tab.
+ * So before it looks (a child's layout effect runs before its parent's), the controls
+ * in here get their own role spelled out, which `HoverMenu` leaves alone, and any list
+ * keeps its list semantics.
+ */
+function MenuSection({ className, children }: { className: string; children: ReactNode }) {
+  const ref = useRef<HTMLLIElement>(null);
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    for (const c of el.querySelectorAll<HTMLElement>(SECTION_CONTROLS)) {
+      c.setAttribute("role", c.tagName === "A" ? "link" : "button");
+    }
+    for (const l of el.querySelectorAll<HTMLElement>("ul:not([role]),ol:not([role])")) l.setAttribute("role", "list");
+    for (const l of el.querySelectorAll<HTMLElement>("li:not([role])")) l.setAttribute("role", "listitem");
+  });
+  return (
+    <li ref={ref} role="none" className={className}>
+      {children}
+    </li>
+  );
+}
+
+/**
+ * `HoverMenu` closes on any Tab inside the panel — right when Tab leaves it, wrong when
+ * Tab is on its way from a row to a footer link, or from one footer link to the next:
+ * the panel would unmount under the focus. So a Tab whose next stop is still inside the
+ * panel stops here and the browser moves focus; one that leaves reaches `HoverMenu`,
+ * which closes.
+ */
+function keepTabInsidePanel(e: ReactKeyboardEvent<HTMLUListElement>) {
+  if (e.key !== "Tab") return;
+  const from = e.target as HTMLElement;
+  const stops = Array.from(e.currentTarget.querySelectorAll<HTMLElement>(TABBABLE)).filter(
+    (el) => el.getAttribute("tabindex") !== "-1",
+  );
+  const way = e.shiftKey ? Node.DOCUMENT_POSITION_PRECEDING : Node.DOCUMENT_POSITION_FOLLOWING;
+  if (stops.some((el) => el !== from && from.compareDocumentPosition(el) & way)) e.stopPropagation();
+}
+
 /**
  * A top-bar icon button that opens a {@link HoverMenu} of actions and/or links,
  * with an optional uppercase heading and divider rules. Generic glue over the
@@ -22,70 +118,164 @@ export type TopBarMenuEntry =
  * so those call sites describe their rows as data instead of rebuilding the
  * trigger + list markup. For a checkmarked value-switcher use
  * {@link OptionSwitcherMenu} instead.
+ *
+ * It is also the ACCOUNT menu kastlan and keksdose each hand-build on `HoverMenu`: a
+ * custom `trigger` (the avatar), a `header` (name + role / email), the rows, and a
+ * free-content `footer` (the legal links).
  */
 export function TopBarActionMenu({
   icon,
+  trigger,
+  triggerClassName,
   ariaLabel,
   heading,
+  header,
   entries,
+  children,
+  footer,
+  footerLabel,
+  align,
   panelClassName,
 }: {
-  icon: ReactNode;
+  /** The trigger's face for the usual icon button. Ignored when `trigger` is given. */
+  icon?: ReactNode;
+  /**
+   * A face of your own for the trigger — the account menu's `UserAvatar`. It is drawn
+   * INSIDE the kit's button, which keeps the wiring: `aria-haspopup`, `aria-expanded`,
+   * the toggle, the keyboard. `open` is there for a chevron that turns.
+   *
+   * The button is named by `ariaLabel` followed by any readable text in the face — a
+   * `UserAvatar` `badge` label reaches a screen reader that way ("Account menu 3
+   * unread"), where an `aria-label` on the button would have hidden it. A
+   * `UserAvatar`'s initials are `aria-hidden`, so the person's name is only in the
+   * name if `ariaLabel` carries it ("Marcel Eifert, account menu").
+   */
+  trigger?: (state: { open: boolean }) => ReactNode;
+  /** Extra classes for the trigger button — `rounded-full` round an avatar. */
+  triggerClassName?: string;
+  /** Names the trigger and the menu. */
   ariaLabel: string;
   heading?: string;
+  /** A non-interactive identity block above the rows. */
+  header?: TopBarMenuHeader;
   entries: TopBarMenuEntry[];
+  /**
+   * Rows the entry data cannot describe (a `Disclosure` sub-list, an app's own
+   * section), after `entries`. Render `<li>`s holding `MenuItem`s or plain controls;
+   * `close` shuts the menu.
+   */
+  children?: (close: () => void) => ReactNode;
+  /**
+   * Free content below the rows, behind a rule — the legal links. Its links and
+   * buttons are NOT menu rows: the arrow keys skip them and Tab reaches them. Pass a
+   * function to get `close` for the links' `onClick`.
+   */
+  footer?: ReactNode | ((close: () => void) => ReactNode);
+  /** Wraps the footer in a `<nav>` with this name ("Legal"). Without it, a plain block. */
+  footerLabel?: string;
+  /** Which edge of the trigger the panel lines up with (see `HoverMenu`). Default `end`. */
+  align?: "start" | "end" | "left" | "right";
   panelClassName?: string;
 }) {
   return (
     <HoverMenu
       ariaLabel={ariaLabel}
-      trigger={({ toggle }) => (
-        <button type="button" onClick={toggle} aria-label={ariaLabel} className={TOPBAR_TRIGGER_CLASS}>
-          {icon}
-        </button>
-      )}
+      align={align}
+      trigger={({ open, toggle }) =>
+        trigger ? (
+          <button type="button" onClick={toggle} className={cn(TOPBAR_TRIGGER_CLASS, "relative", triggerClassName)}>
+            <span className="sr-only">{ariaLabel}</span>
+            {/* The space keeps the name from running into the face's text ("Account
+                menu3 unread"); as a flex item it takes no room. */}
+            {" "}
+            {trigger({ open })}
+          </button>
+        ) : (
+          <button
+            type="button"
+            onClick={toggle}
+            aria-label={ariaLabel}
+            className={cn(TOPBAR_TRIGGER_CLASS, triggerClassName)}
+          >
+            {icon}
+          </button>
+        )
+      }
     >
-      {(close) => (
-        <ul className={cn("py-1", panelClassName)}>
-          {heading && (
-            <li className="px-3 py-1 text-[10px] font-semibold uppercase tracking-wide text-[var(--text-placeholder)]">
-              {heading}
-            </li>
-          )}
-          {entries.map((entry) => {
-            if (entry.kind === "divider") {
-              return <li key={entry.key} className="my-1 border-t border-[var(--border)]" />;
-            }
-            const content = (
-              <span className="flex w-full items-center gap-2">
-                {entry.icon}
-                {entry.label}
-                {entry.trailing && <span className="ms-auto ps-2">{entry.trailing}</span>}
-              </span>
-            );
-            return (
-              <li key={entry.key}>
-                {entry.kind === "link" ? (
-                  <Link to={entry.to} onClick={close} className={TOPBAR_MENU_ITEM_CLASS}>
-                    {content}
-                  </Link>
-                ) : (
-                  <button
-                    type="button"
-                    onClick={() => {
-                      entry.onSelect();
-                      close();
-                    }}
-                    className={TOPBAR_MENU_ITEM_CLASS}
-                  >
-                    {content}
-                  </button>
+      {(close) => {
+        const footerBody = typeof footer === "function" ? footer(close) : footer;
+        const footerClass =
+          "flex flex-wrap gap-x-3 gap-y-1 text-xs text-[var(--text-muted)] [&_a:hover]:text-[var(--text-primary)] [&_a]:rounded-sm [&_a:focus-visible]:outline-none [&_a:focus-visible]:ring-2 [&_a:focus-visible]:ring-[var(--brand)]";
+        return (
+          // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- a Tab bubbling up from a row or footer link, see keepTabInsidePanel
+          <ul className={cn("py-1", panelClassName)} onKeyDown={keepTabInsidePanel}>
+            {header && (
+              <MenuSection className="mb-1 border-b border-[var(--border)] px-3 py-2">
+                <div className="truncate text-sm font-medium text-[var(--text-primary)]">{header.title}</div>
+                {header.subtitle != null && (
+                  <div className="truncate text-xs text-[var(--text-muted)]">{header.subtitle}</div>
                 )}
+                {header.extra != null && <div className="mt-1">{header.extra}</div>}
+              </MenuSection>
+            )}
+            {heading && (
+              <li className="px-3 py-1 text-[10px] font-semibold uppercase tracking-wide text-[var(--text-placeholder)]">
+                {heading}
               </li>
-            );
-          })}
-        </ul>
-      )}
+            )}
+            {entries.map((entry) => {
+              if (entry.kind === "divider") {
+                return <li key={entry.key} className="my-1 border-t border-[var(--border)]" />;
+              }
+              return (
+                <li key={entry.key}>
+                  {entry.kind === "link" ? (
+                    <MenuItem
+                      href={entry.to}
+                      renderLink={({ href, ...p }) => <Link to={href} {...p} />}
+                      onClick={close}
+                      leading={entry.icon}
+                      trailing={entry.trailing}
+                      tone={entry.tone}
+                      current={entry.current}
+                      disabled={entry.disabled}
+                    >
+                      {entry.label}
+                    </MenuItem>
+                  ) : (
+                    <MenuItem
+                      onClick={() => {
+                        entry.onSelect();
+                        close();
+                      }}
+                      leading={entry.icon}
+                      trailing={entry.trailing}
+                      tone={entry.tone}
+                      checked={entry.checked}
+                      checkable={entry.checkable}
+                      disabled={entry.disabled}
+                    >
+                      {entry.label}
+                    </MenuItem>
+                  )}
+                </li>
+              );
+            })}
+            {children?.(close)}
+            {footerBody != null && footerBody !== false && (
+              <MenuSection className="mt-1 border-t border-[var(--border)] px-3 py-2">
+                {footerLabel ? (
+                  <nav aria-label={footerLabel} className={footerClass}>
+                    {footerBody}
+                  </nav>
+                ) : (
+                  <div className={footerClass}>{footerBody}</div>
+                )}
+              </MenuSection>
+            )}
+          </ul>
+        );
+      }}
     </HoverMenu>
   );
 }

package/src/wizard/stepper-nav.tsx

@@ -107,7 +107,8 @@ export function StepperNav<TData extends Record<string, unknown>>({
   const pending = wizard.isValidating;
   const stepNextLabel = wizard.currentStep.nextLabel;
 
-  let forwardButton: ReactNode = null;
+  // Every branch below assigns it; no initial value to overwrite.
+  let forwardButton: ReactNode;
   if (wizard.isCommitStep) {
     const finishButton = (
       <Button

package/src/wizard/types.ts

@@ -109,8 +109,8 @@ export interface UseWizardOptions<TData extends Record<string, unknown>> {
    */
   missingRequiredMessage?: string;
   /**
-   * How to surface {@link missingRequiredMessage}. Defaults to a `sonner` toast
-   * (an optional peer, imported only when this actually fires). Pass your own to
+   * How to surface {@link missingRequiredMessage}. Defaults to the kit's `toast.error`
+   * (sonner, an optional peer, is loaded only when a toast is shown). Pass your own to
    * route it somewhere else, or to a no-op to silence it.
    */
   onValidationFailed?: (message: string) => void;

package/src/wizard/use-wizard.ts

@@ -18,6 +18,7 @@ import { useCallback, useEffect, useReducer, useRef, useState } from "react";
 import { useSearchParams } from "react-router";
 import { useKitLabels } from "../i18n/kit-labels";
 import { DEFAULT_WIZARD_LABELS } from "./types";
+import { toast } from "../components/toast";
 import type {
   FieldErrors,
   StepStatus,
@@ -312,9 +313,8 @@ export function useWizard<TData extends Record<string, unknown>>(
         if (onValidationFailed) {
           onValidationFailed(message);
         } else {
-          // sonner is an optional peer: imported here, on the failure path only,
-          // so an app that never trips this never has to install it.
-          const { toast } = await import("sonner");
+          // The kit's `toast` loads sonner (an optional peer) lazily, so an app
+          // that never trips this never has to install it.
           toast.error(message);
         }
       }

package/src/wizard/wizard-context.tsx

@@ -27,3 +27,12 @@ export function useWizardContext(): WizardContextValue {
   }
   return ctx;
 }
+
+/**
+ * The wizard context, or `null` outside a `<StepperNav>`. For a hook that registers
+ * with the wizard when there is one and works without it — `useRhfWizardStep` in
+ * `@eifi1/ui-kit/rhf`, whose returned `validate` a custom nav can call itself.
+ */
+export function useOptionalWizardContext(): WizardContextValue | null {
+  return useContext(WizardContext);
+}

package/src/wizard/wizard-summary.tsx

@@ -1,5 +1,6 @@
 import { Pencil } from "lucide-react";
 import { Card, CardAction, CardContent, CardHeader, CardTitle, IconButton } from "../components/ui";
+import { Tooltip } from "../components/tooltip";
 import type { SummarySection, WizardLabels } from "./types";
 import { DEFAULT_WIZARD_LABELS } from "./types";
 import { useKitLabels } from "../i18n/kit-labels";
@@ -44,16 +45,19 @@ export function WizardSummary({
             <CardTitle className="text-base">{section.label}</CardTitle>
             {section.stepIndex !== undefined && onEditStep && (
               <CardAction>
-                <IconButton
-                  size="sm"
-                  variant="ghost"
-                  aria-label={l.edit}
-                  title={l.edit}
-                  disabled={disabled}
-                  onClick={() => onEditStep(section.stepIndex as number)}
-                >
-                  <Pencil />
-                </IconButton>
+                {/* The kit Tooltip, not a native `title`: it shows on keyboard focus too,
+                    and an app with a one-tooltip rule (keksdose dev#523) sees one. */}
+                <Tooltip label={l.edit}>
+                  <IconButton
+                    size="sm"
+                    variant="ghost"
+                    aria-label={l.edit}
+                    disabled={disabled}
+                    onClick={() => onEditStep(section.stepIndex as number)}
+                  >
+                    <Pencil />
+                  </IconButton>
+                </Tooltip>
               </CardAction>
             )}
           </CardHeader>

package/tokens.css

@@ -233,6 +233,103 @@
   --success-bg: rgba(6, 78, 59, 0.25);
 }
 
+/* ── Toasts ─────────────────────────────────────────────────────────────────
+   The kit `<Toaster>` (components/toast.tsx) paints sonner with the AlertBanner
+   tones. These are ALIASES, not new colours, and they exist for one reason: sonner
+   declares its own `--success-bg` / `--success-border` (and info, warning) on the
+   toaster element, so that element cannot read the kit's value under the same name
+   — `--success-bg: var(--success-bg)` is a cycle. Declared here, they are computed
+   on `<html>` and inherited down under a name sonner does not touch.
+
+   The background is the tone's wash layered on the surface, as AlertBanner's
+   `elevated` frame does: the dark washes are translucent, and a toast floats over
+   content. `--z-toast` is above every kit overlay (modal and sheets z-50, tour
+   z-60/61, command palette z-70) and above whatever an app stacks on top of those —
+   a toast confirming a dialog's action must not land under the dialog. */
+:root,
+.dark {
+  --z-toast: 2147483647;
+  --toast-success-bg: linear-gradient(var(--success-bg), var(--success-bg)) var(--bg-surface);
+  --toast-success-border: var(--success-border);
+  --toast-info-bg: linear-gradient(var(--info-bg), var(--info-bg)) var(--bg-surface);
+  --toast-info-border: var(--info-border);
+  --toast-warning-bg: linear-gradient(var(--warning-bg), var(--warning-bg)) var(--bg-surface);
+  --toast-warning-border: var(--warning-border);
+  --toast-danger-bg: linear-gradient(var(--danger-bg), var(--danger-bg)) var(--bg-surface);
+  --toast-danger-border: var(--danger-border);
+}
+
+/* The description of an untoned toast in the secondary text colour (sonner hard-codes
+   #3f3f3f, unreadable in the dark theme); a toned toast's inherits its tone. */
+.kit-toaster [data-sonner-toast][data-styled="true"]:not([data-type="success"], [data-type="info"], [data-type="warning"], [data-type="error"]) [data-description] {
+  color: var(--text-secondary);
+}
+/* The action button in the tone's own colour rather than sonner's black pill. */
+.kit-toaster [data-sonner-toast][data-styled="true"] [data-button]:not([data-cancel]) {
+  background: var(--toast-action-bg, var(--text-primary));
+  color: var(--bg-surface);
+}
+.kit-toaster [data-sonner-toast][data-type="success"] { --toast-action-bg: var(--success); }
+.kit-toaster [data-sonner-toast][data-type="info"] { --toast-action-bg: var(--info); }
+.kit-toaster [data-sonner-toast][data-type="warning"] { --toast-action-bg: var(--warning); }
+.kit-toaster [data-sonner-toast][data-type="error"] { --toast-action-bg: var(--danger); }
+/* The kit's focus ring on the toast's buttons — sonner's is a black shadow that
+   vanishes on the dark theme. */
+.kit-toaster [data-sonner-toast][data-styled="true"] :is([data-button], [data-close-button]):focus-visible {
+  outline: 2px solid var(--brand);
+  outline-offset: 2px;
+}
+
+/* ── Categorical hues ───────────────────────────────────────────────────────
+   Colours that MEAN nothing but "this is a different value": kastlan's status
+   enums (status-badge.tsx over enum-meta.ts), where ~15 enums map to 9 Tailwind
+   hues. Four of those are semantic and already have tokens — green = --success,
+   yellow = --warning, red = --danger, gray = the neutral chip — so only the five
+   below are new: blue (open / sent / rented), purple (assigned / accepted),
+   orange (terminated / high urgency), teal (invoiced) and indigo (a meeting
+   stage). The smallest set that covers every enum; deliberately not a ramp.
+
+   Same triple and same shades as the status family (700 text / 300 border /
+   100 surface in light, 300 text / translucent 700 border / 900 wash in dark),
+   so a categorical chip sits beside a semantic one at the same weight. Not in
+   `TokenSet`: like `--danger`, a hue is a specific colour, not a tint of the
+   palette preset, so it lives here and nowhere else. */
+:root {
+  --hue-blue: #1d4ed8;            /* blue-700 */
+  --hue-blue-border: #93c5fd;     /* blue-300 */
+  --hue-blue-bg: #dbeafe;         /* blue-100 */
+  --hue-indigo: #4338ca;          /* indigo-700 */
+  --hue-indigo-border: #a5b4fc;   /* indigo-300 */
+  --hue-indigo-bg: #e0e7ff;       /* indigo-100 */
+  --hue-purple: #7e22ce;          /* purple-700 */
+  --hue-purple-border: #d8b4fe;   /* purple-300 */
+  --hue-purple-bg: #f3e8ff;       /* purple-100 */
+  --hue-teal: #0f766e;            /* teal-700 */
+  --hue-teal-border: #5eead4;     /* teal-300 */
+  --hue-teal-bg: #ccfbf1;         /* teal-100 */
+  --hue-orange: #c2410c;          /* orange-700 */
+  --hue-orange-border: #fdba74;   /* orange-300 */
+  --hue-orange-bg: #ffedd5;       /* orange-100 */
+}
+
+.dark {
+  --hue-blue: #93c5fd;            /* blue-300 */
+  --hue-blue-border: rgba(29, 78, 216, 0.6);
+  --hue-blue-bg: rgba(30, 58, 138, 0.25);
+  --hue-indigo: #a5b4fc;          /* indigo-300 */
+  --hue-indigo-border: rgba(67, 56, 202, 0.6);
+  --hue-indigo-bg: rgba(49, 46, 129, 0.25);
+  --hue-purple: #d8b4fe;          /* purple-300 */
+  --hue-purple-border: rgba(126, 34, 206, 0.6);
+  --hue-purple-bg: rgba(88, 28, 135, 0.25);
+  --hue-teal: #5eead4;            /* teal-300 */
+  --hue-teal-border: rgba(15, 118, 110, 0.6);
+  --hue-teal-bg: rgba(19, 78, 74, 0.25);
+  --hue-orange: #fdba74;          /* orange-300 */
+  --hue-orange-border: rgba(194, 65, 12, 0.6);
+  --hue-orange-bg: rgba(124, 45, 18, 0.25);
+}
+
 /* Semantic colour utilities backed by the tokens above. Unlayered so they win
    over Tailwind's layered colour utilities, and theme-aware for free (the var
    flips under .dark) — no dark: variant needed at the call site. */