@eifi1/ui-kit 0.10.0 → 0.11.0

package/src/lib/dates.ts

@@ -149,6 +149,43 @@ export function addDaysIso(iso: string, days: number): string {
   return toLocalIso(d);
 }
 
+/**
+ * `d` moved by whole months, keeping the day of the month where the target has one.
+ * `setMonth` alone ROLLS OVER — 31 January + 1 month is 3 March — which would skip
+ * February entirely for anyone paging through the year with PageDown. Returns a new
+ * Date; `d` is not touched.
+ */
+export function addMonthsClamped(d: Date, months: number): Date {
+  const day = d.getDate();
+  const out = new Date(d.getFullYear(), d.getMonth() + months, 1);
+  const lastOfTarget = new Date(out.getFullYear(), out.getMonth() + 1, 0).getDate();
+  out.setDate(Math.min(day, lastOfTarget));
+  return out;
+}
+
+/**
+ * The first day of the week in `locale`, as a `Date#getDay` index (0 = Sunday).
+ *
+ * `Intl.Locale#getWeekInfo()` is the standard spelling; V8 shipped it first as the
+ * `weekInfo` accessor, and Firefox has neither yet — hence both reads and a Monday
+ * fallback, which is ISO 8601. Its `firstDay` counts 1 = Monday … 7 = Sunday, so `% 7`
+ * maps it onto `getDay`. `undefined` asks for the runtime's default locale.
+ */
+export function localeWeekStart(locale: string | undefined): 0 | 1 | 2 | 3 | 4 | 5 | 6 {
+  try {
+    const tag = locale ?? new Intl.DateTimeFormat().resolvedOptions().locale;
+    const loc = new Intl.Locale(tag) as Intl.Locale & {
+      getWeekInfo?: () => { firstDay: number };
+      weekInfo?: { firstDay: number };
+    };
+    const firstDay = (loc.getWeekInfo?.() ?? loc.weekInfo)?.firstDay;
+    if (typeof firstDay === "number") return (firstDay % 7) as 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  } catch {
+    // A malformed tag throws from `Intl.Locale`; a calendar still has to render.
+  }
+  return 1;
+}
+
 /** Whether two Dates fall on the same local calendar day. */
 export function sameYmd(a: Date, b: Date): boolean {
   return (

package/src/rhf/use-rhf-wizard-step.ts

@@ -0,0 +1,113 @@
+/**
+ * The bridge between a react-hook-form step and the wizard's Next gate.
+ * `@eifi1/ui-kit/rhf`.
+ *
+ * ```tsx
+ * function AddressStep({ onUpdate }: { onUpdate: (v: Address) => void }) {
+ *   const form = useForm<Address>({ defaultValues });
+ *   useRhfWizardStep(form, { onValid: onUpdate });
+ *   return <Form {...form}>…</Form>;
+ * }
+ * ```
+ *
+ * Inside a `<StepperNav>` the hook registers the step's validator with the wizard, so
+ * Next (and Finish on a form-bearing last step) runs it: on success the values go to
+ * `onValid` and the wizard advances; on failure react-hook-form shows its own inline
+ * `<FormMessage>`s, focuses the first field in error, and the wizard stays put — and,
+ * since the result carries no per-field errors, says its "fill in the required
+ * fields" line so the button did not seem to do nothing. It also RETURNS the
+ * validator, for a nav of your own outside `<StepperNav>` (where there is no wizard
+ * context to register with, so nothing is registered).
+ *
+ * Two modes:
+ *
+ *  - **The whole form** (no `fields`): `form.handleSubmit`, exactly as kastlan's
+ *    `use-rhf-wizard-step.ts` — every rule and the resolver run, `onValid` receives
+ *    the TRANSFORMED values (a zod `.transform()` included), and focus follows the
+ *    form's own `shouldFocusError` (on by default).
+ *  - **Some fields** (`fields: ["iban", "bic"]`): `form.trigger(fields)`, for a wizard
+ *    that keeps one form across several steps, each of which validates only what it
+ *    shows. The first of those fields in error is focused (`shouldFocus`; the control
+ *    has to take `field.ref`), errors on fields of later steps are not raised, and
+ *    `onValid` receives `form.getValues()` — the untransformed values, because a
+ *    resolver's output is only produced for the whole form.
+ *
+ * Both callbacks are read through refs, so the validator is registered once per form
+ * however the caller writes them (an inline `(v) => onUpdate(v)` is the usual case).
+ *
+ * The positional `useRhfWizardStep(form, onValid)` of the hook kastlan kept is the
+ * whole-form mode, and still accepted.
+ *
+ * Why it lives here and not in `@eifi1/ui-kit/wizard`: it imports react-hook-form,
+ * which only this entry may (see packaging-contract).
+ */
+import { useCallback, useEffect, useRef } from "react";
+import type { FieldPath, FieldValues, UseFormReturn } from "react-hook-form";
+import { useOptionalWizardContext } from "../wizard/wizard-context";
+
+export type RhfWizardStepOptions<
+  TFieldValues extends FieldValues,
+  TTransformed = TFieldValues,
+> =
+  | {
+      /** Validate only these fields — the step's share of a form that spans steps. */
+      fields: readonly FieldPath<TFieldValues>[];
+      /** Called with `form.getValues()` when the fields pass, before the wizard
+       *  advances. */
+      onValid?: (values: TFieldValues) => void;
+    }
+  | {
+      /** Omitted: validate the whole form through `handleSubmit`. */
+      fields?: undefined;
+      /** Called with the form's (transformed) values when it passes, before the
+       *  wizard advances. */
+      onValid?: (values: TTransformed) => void;
+    };
+
+/**
+ * Connects `form` to the wizard's step validation and returns the step's validator.
+ * See the module note for the two modes.
+ */
+export function useRhfWizardStep<
+  TFieldValues extends FieldValues,
+  TContext = unknown,
+  TTransformed = TFieldValues,
+>(
+  form: UseFormReturn<TFieldValues, TContext, TTransformed>,
+  options?:
+    | RhfWizardStepOptions<TFieldValues, TTransformed>
+    | ((values: TTransformed) => void),
+): () => Promise<boolean> {
+  const opts = typeof options === "function" ? { onValid: options } : (options ?? {});
+  const optsRef = useRef(opts);
+  useEffect(() => {
+    optsRef.current = opts;
+  });
+
+  const validate = useCallback(async (): Promise<boolean> => {
+    const current = optsRef.current;
+    if (current.fields) {
+      const ok = await form.trigger([...current.fields], { shouldFocus: true });
+      if (ok) current.onValid?.(form.getValues());
+      return ok;
+    }
+    const onValid = current.onValid as ((values: TTransformed) => void) | undefined;
+    let ok = false;
+    await form.handleSubmit(
+      (values) => {
+        ok = true;
+        onValid?.(values);
+      },
+      () => {
+        ok = false;
+      },
+    )();
+    return ok;
+  }, [form]);
+
+  const wizard = useOptionalWizardContext();
+  const register = wizard?.registerStepValidate;
+  useEffect(() => register?.(validate), [register, validate]);
+
+  return validate;
+}

package/src/rhf.ts

@@ -7,3 +7,5 @@
 // the barrel dropped its last react-hook-form import (see the wizard section of
 // src/index.ts). The packaging contract test holds that line.
 export * from "./rhf/form";
+// The react-hook-form bridge to the wizard's Next gate (useWizard lives in /wizard).
+export * from "./rhf/use-rhf-wizard-step";

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/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);
+}