@eifi1/ui-kit 0.10.0 → 0.12.0

package/src/shell/top-bar-brand.tsx

@@ -0,0 +1,76 @@
+import type { ReactNode } from "react";
+import { Link as RouterLink } from "react-router";
+import { cn } from "../lib/cn";
+import { useKitLink } from "../i18n/kit-labels";
+import { pickLinkRenderer } from "../components/text-link";
+import type { KitLinkComponent, KitLinkProps } from "../i18n/kit-labels";
+
+const routerLink: KitLinkComponent = ({ href, ...p }) => <RouterLink to={href} {...p} />;
+const plainLink: KitLinkComponent = ({ children, ...p }) => <a {...p}>{children}</a>;
+
+/** Below which width only the logo shows. The name stays in the link's accessible
+ *  name at every width. */
+const COLLAPSE = {
+  sm: "sr-only sm:not-sr-only sm:truncate",
+  md: "sr-only md:not-sr-only md:truncate",
+} as const;
+
+export interface TopBarBrandProps extends Omit<KitLinkProps, "href" | "children"> {
+  /** The brand mark — an SVG, sized by the caller or `h-6 w-auto` by default. */
+  logo: ReactNode;
+  /** The product name beside the logo, and the link's accessible name. */
+  name: ReactNode;
+  /** Where the brand links to. Default `/`. */
+  to?: string;
+  /** Hide the name below `sm` (default) or `md`; `false` always shows it. It is
+   *  visually hidden, not removed, so the link keeps its name on a phone. */
+  collapseBelow?: "sm" | "md" | false;
+  /** The app's router link for this one link. Default: the provider's
+   *  `linkComponent`, else react-router's `Link`. */
+  renderLink?: KitLinkComponent;
+}
+
+/**
+ * The top bar's home link: logo + product name, collapsing to the logo on a phone.
+ * Pass it as {@link TopBar}'s `brand`.
+ *
+ * kastlan's (top-bar.tsx:66) hid nothing and truncated the name instead — on a phone
+ * with five actions that left "Ka…" beside the logo — and needed an `aria-label`
+ * because the name could be cut. Here the name is `sr-only` below the breakpoint, so
+ * the logo is the whole visible link there and the name is still what it is called.
+ */
+export function TopBarBrand({
+  logo,
+  name,
+  to = "/",
+  collapseBelow = "sm",
+  renderLink,
+  className,
+  ...rest
+}: TopBarBrandProps) {
+  const kitLink = useKitLink();
+  return (
+    <RenderedLink
+      // The kit's one link rule (`pickLinkRenderer`): an external `to` or an in-page
+      // `#anchor` is a plain `<a>`, never the router's link.
+      render={pickLinkRenderer(renderLink, kitLink ?? routerLink, to) ?? plainLink}
+      {...rest}
+      href={to}
+      className={cn(
+        // `relative` contains the sr-only name.
+        "relative flex min-w-0 items-center gap-2 rounded-md font-semibold text-[var(--text-primary)] hover:opacity-80 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)]",
+        className,
+      )}
+    >
+      <span aria-hidden className="flex shrink-0 items-center [&_svg]:h-6 [&_svg]:w-auto">
+        {logo}
+      </span>
+      <span className={collapseBelow ? COLLAPSE[collapseBelow] : "truncate"}>{name}</span>
+    </RenderedLink>
+  );
+}
+
+/** Calls the link renderer as a component, so a router link's hooks are its own. */
+function RenderedLink({ render, ...props }: KitLinkProps & { render: KitLinkComponent }) {
+  return render(props);
+}

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

@@ -1,20 +1,118 @@
-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 { StatusDot } from "../components/status-dot";
+import type { UserAvatarBadge } from "../components/user-avatar";
+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 +120,183 @@ 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,
+  iconBadge,
+  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 status dot in the top-end corner of `icon` — keksdose's unread-support dot on the
+   * feedback trigger. Like `UserAvatar`'s `badge`, its `label` joins the trigger's name
+   * ("Send feedback 2 unread"), so the dot is not something only the eye is told about.
+   * Ignored with `trigger`: give the face its own badge there.
+   */
+  iconBadge?: UserAvatarBadge | null;
+  /**
+   * 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>
+        ) : iconBadge ? (
+          // Named by its content, like the custom-trigger branch, so the badge label is
+          // part of the name; an `aria-label` would have hidden it.
+          <button type="button" onClick={toggle} className={cn(TOPBAR_TRIGGER_CLASS, "relative", triggerClassName)}>
+            <span className="sr-only">{ariaLabel}</span>{" "}
+            <span aria-hidden className="relative inline-flex">
+              {icon}
+              <StatusDot ring tone={iconBadge.tone ?? "danger"} className="absolute -end-0.5 -top-0.5" />
+            </span>{" "}
+            <span className="sr-only">{iconBadge.label}</span>
+          </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/shell.ts

@@ -8,3 +8,5 @@ export * from "./shell/app-shell";
 export * from "./shell/option-switcher-menu";
 export * from "./shell/role-switcher";
 export * from "./shell/topbar-action-menu";
+export * from "./shell/top-bar-brand";
+export * from "./shell/auth-layout";

package/src/wizard/wizard-context.tsx

@@ -1,4 +1,4 @@
-import { createContext, useContext } from "react";
+import { createContext, useContext, useEffect, useRef } from "react";
 import type { ValidateResult } from "./types";
 
 export interface WizardContextValue {
@@ -27,3 +27,52 @@ 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);
+}
+
+/**
+ * Registers a plain validator for the mounted step — the counterpart to
+ * `useRhfWizardStep` (in `@eifi1/ui-kit/rhf`) for a step that gates on its own state
+ * (a hand-managed list of lines, a sum that has to balance) rather than a form.
+ *
+ * ```tsx
+ * useWizardStepValidate(() => ({ ok: lines.length >= 2, errors: { lines: t("…") } }));
+ * ```
+ *
+ * Next (and Finish) run it with the step's other validators; a `false` or a result
+ * with `ok: false` keeps the wizard where it is. `validate` is read through a ref, so
+ * an inline closure over the latest state registers exactly once. Throws outside a
+ * `<StepperNav>`, like {@link useWizardContext}: a validator with nothing to run it is
+ * a bug to hear about.
+ */
+export function useWizardStepValidate(
+  validate: () => ValidateResult | Promise<ValidateResult>,
+): void {
+  const { registerStepValidate } = useWizardContext();
+  const ref = useRef(validate);
+  useEffect(() => {
+    ref.current = validate;
+  });
+  useEffect(() => registerStepValidate(() => ref.current()), [registerStepValidate]);
+}
+
+/**
+ * Disables the wizard's Next and Skip while `blocked` holds (tenant shares that do not
+ * add up to 100 %). Unlike {@link useWizardStepValidate}, which answers a click, this
+ * greys the button out before one. The gate is lifted again when the step unmounts, so
+ * the next step starts unblocked.
+ */
+export function useWizardNextGate(blocked: boolean): void {
+  const { setNextBlocked } = useWizardContext();
+  useEffect(() => {
+    setNextBlocked(blocked);
+    return () => setNextBlocked(false);
+  }, [blocked, setNextBlocked]);
+}

package/src/wizard/wizard-step.tsx

@@ -1,14 +1,51 @@
 import type { ReactNode } from "react";
 import { cn } from "../lib/cn";
 
+export interface WizardStepProps {
+  children: ReactNode;
+  className?: string;
+  /**
+   * The step's heading ("Choose a unit"), drawn in the one style every step shares.
+   * kastlan's steps each hand-wrote `<h3 className="text-lg font-semibold">` (about
+   * sixteen of them: lease-picker-step, lease-unit-step, …), and a hand-written
+   * heading is one that drifts — a size here, a colour there. Omitted: no heading.
+   */
+  title?: ReactNode;
+  /** The line under the title: what the step asks for, or why. Rendered only with a
+   *  `title` or on its own when there is none. */
+  description?: ReactNode;
+  /** The heading's level. Default 3: the page has its `h1` and the wizard's own
+   *  chrome sits at `h2` (the review step, the cancel dialog), so a step is under it. */
+  headingLevel?: 2 | 3 | 4;
+}
+
+const HEADING = { 2: "h2", 3: "h3", 4: "h4" } as const;
+
 /** The vertical rhythm one wizard step's content sits on. A component rather
- *  than a class string so every step in every app spaces its fields the same. */
+ *  than a class string so every step in every app spaces its fields the same —
+ *  and, with `title` / `description`, heads them the same. */
 export function WizardStep({
   children,
   className,
-}: {
-  children: ReactNode;
-  className?: string;
-}) {
-  return <div className={cn("space-y-6", className)}>{children}</div>;
+  title,
+  description,
+  headingLevel = 3,
+}: WizardStepProps) {
+  const hasTitle = title !== undefined && title !== null && title !== false && title !== "";
+  const hasDescription =
+    description !== undefined && description !== null && description !== false && description !== "";
+  const Heading = HEADING[headingLevel];
+  return (
+    <div className={cn("space-y-6", className)}>
+      {(hasTitle || hasDescription) && (
+        <div data-slot="wizard-step-header" className="space-y-1">
+          {hasTitle && (
+            <Heading className="text-lg font-semibold text-[var(--text-primary)]">{title}</Heading>
+          )}
+          {hasDescription && <p className="text-sm text-[var(--text-muted)]">{description}</p>}
+        </div>
+      )}
+      {children}
+    </div>
+  );
 }

package/tokens.css

@@ -233,6 +233,18 @@
   --success-bg: rgba(6, 78, 59, 0.25);
 }
 
+/* ── Media ─────────────────────────────────────────────────────────────────
+   Controls drawn ON a photo or a live camera picture (the camera shutter), whose
+   background is the picture, not the page — so they must NOT follow the theme: a
+   dark-mode inverse pair would put a dark ring on a dark viewfinder. The same in both
+   themes, on purpose. */
+:root,
+.dark {
+  --media-ink: #ffffff;
+  --media-scrim: rgb(0 0 0 / 0.35);
+  --media-scrim-hover: rgb(0 0 0 / 0.5);
+}
+
 /* ── 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