@eifi1/ui-kit 0.11.0 → 0.13.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

@@ -5,6 +5,8 @@ import { cn } from "../lib/cn";
 import { HoverMenu } from "../components/hover-menu";
 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";
 
 /**
@@ -56,9 +58,15 @@ export interface TopBarMenuHeader {
   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;
+  /**
+   * 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.
+   *
+   * Pass a function to get `close`, as `footer` does — keksdose F7: its admin role
+   * chip links to the admin area, and a router link does not unmount the menu, so
+   * without `close` the panel stayed open over the page it had just navigated to.
+   */
+  extra?: ReactNode | ((close: () => void) => ReactNode);
 }
 
 /** What a control is, as far as `HoverMenu` is concerned, when it lives in the header
@@ -125,6 +133,7 @@ function keepTabInsidePanel(e: ReactKeyboardEvent<HTMLUListElement>) {
  */
 export function TopBarActionMenu({
   icon,
+  iconBadge,
   trigger,
   triggerClassName,
   ariaLabel,
@@ -139,6 +148,13 @@ export function TopBarActionMenu({
 }: {
   /** 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`,
@@ -190,6 +206,17 @@ export function TopBarActionMenu({
             {" "}
             {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"
@@ -204,6 +231,7 @@ export function TopBarActionMenu({
     >
       {(close) => {
         const footerBody = typeof footer === "function" ? footer(close) : footer;
+        const headerExtra = typeof header?.extra === "function" ? header.extra(close) : header?.extra;
         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 (
@@ -215,7 +243,7 @@ export function TopBarActionMenu({
                 {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>}
+                {headerExtra != null && headerExtra !== false && <div className="mt-1">{headerExtra}</div>}
               </MenuSection>
             )}
             {heading && (

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/tour/tour.tsx

@@ -157,11 +157,15 @@ export function TourProvider({
   const [activeId, setActiveId] = useState<string | null>(null);
   const optsRef = useRef<StartOptions>({});
   // Live mirrors so the step-control callbacks can stay stable (identity-safe for
-  // consumers) while still reading the current steps/index.
+  // consumers) while still reading the current steps/index. Synced in a layout
+  // effect — after the commit, before paint and before any passive effect or event
+  // can call them — rather than written during render.
   const stepsRef = useRef<TourStep[] | null>(null);
-  stepsRef.current = steps;
   const indexRef = useRef(0);
-  indexRef.current = index;
+  useLayoutEffect(() => {
+    stepsRef.current = steps;
+    indexRef.current = index;
+  }, [steps, index]);
   const active = !!steps && steps.length > 0;
   const total = steps?.length ?? 0;
 
@@ -277,6 +281,15 @@ function TourOverlay({
   const isLast = index === steps.length - 1;
   const [rect, setRect] = useState<Rect | null>(null);
   const [ready, setReady] = useState(false);
+  // A new step starts unlocated: reset during render when the step changes, so the
+  // previous step's spotlight never paints over the new one. The effect below then
+  // locates it.
+  const [locating, setLocating] = useState({ index, step });
+  if (locating.index !== index || locating.step !== step) {
+    setLocating({ index, step });
+    setReady(false);
+    setRect(null);
+  }
   // The overlay is portalled to <body>, out of whatever `dir` subtree the app set, so it
   // takes the direction of the element it spotlights (the document's for a centered
   // step). Arrow keys and start/end placement read it.
@@ -287,8 +300,6 @@ function TourOverlay({
   useEffect(() => {
     let cancelled = false;
     let raf = 0;
-    setReady(false);
-    setRect(null);
     void (async () => {
       await step.beforeStep?.();
       if (cancelled) return;

package/src/wizard/use-wizard.ts

@@ -14,7 +14,7 @@
  * The committing step is the last one unless a step says `commits: true`; the
  * steps after that one are post-commit steps (see `WizardStepConfig.commits`).
  */
-import { useCallback, useEffect, useReducer, useRef, useState } from "react";
+import { useCallback, useEffect, useLayoutEffect, useReducer, useRef, useState } from "react";
 import { useSearchParams } from "react-router";
 import { useKitLabels } from "../i18n/kit-labels";
 import { DEFAULT_WIZARD_LABELS } from "./types";
@@ -163,8 +163,12 @@ export function useWizard<TData extends Record<string, unknown>>(
     missingRequiredMessage,
     onValidationFailed,
   } = options;
+  // The latest `steps`, for the stable callbacks below. Synced after commit (before
+  // paint, and before any handler can run) rather than written during render.
   const stepsRef = useRef<WizardStepConfig[]>(steps);
-  stepsRef.current = steps;
+  useLayoutEffect(() => {
+    stepsRef.current = steps;
+  }, [steps]);
   // A hook, not a component, but it produces two sentences of its own — the
   // "fill in the required fields" toast and the fallback submit error — and both
   // reach the user. So it reads the provider like any component does; only the two
@@ -239,8 +243,8 @@ export function useWizard<TData extends Record<string, unknown>>(
   // it back.
   const clearStepUrl = useStepUrl(urlParam, state.currentStepIndex);
 
-  // `steps`, not `stepsRef.current`: during render the two are the same array, and
-  // reading a ref in render is what the hooks linter (rightly) objects to.
+  // `steps`, not `stepsRef.current`: reading a ref in render is what the hooks
+  // linter (rightly) objects to, and the ref only catches up after the commit.
   const currentStep = steps[state.currentStepIndex];
   const isFirstStep = state.currentStepIndex === 0;
   const isLastStep = state.currentStepIndex === steps.length - 1;

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 {
@@ -36,3 +36,43 @@ export function useWizardContext(): WizardContextValue {
 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,83 @@
 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;
+  /**
+   * Controls for the step as a whole, at the end of the header row beside the title —
+   * kastlan 43: the buildings step's "Add building" had nowhere to go but UNDER the
+   * list it adds to, where it falls below the fold once there are three buildings.
+   * A header action is where every other kit surface (`PageHeader`, `Card`) puts it.
+   *
+   * Wraps under the title on a narrow screen rather than squeezing it. Renders the
+   * header on its own if there is no `title` either.
+   */
+  actions?: 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,
+  actions,
+}: WizardStepProps) {
+  const hasTitle = title !== undefined && title !== null && title !== false && title !== "";
+  const hasDescription =
+    description !== undefined && description !== null && description !== false && description !== "";
+  const hasActions = actions !== undefined && actions !== null && actions !== false && actions !== "";
+  const Heading = HEADING[headingLevel];
+  const heading = (
+    <>
+      {hasTitle && <Heading className="text-lg font-semibold text-[var(--text-primary)]">{title}</Heading>}
+      {hasDescription && <p className="text-sm text-[var(--text-muted)]">{description}</p>}
+    </>
+  );
+  return (
+    <div className={cn("space-y-6", className)}>
+      {hasActions ? (
+        // One row: the text takes the room, the actions keep their width at the end
+        // and wrap below it when there is not enough — `basis-64` is the width the
+        // title asks for before that happens (a zero basis would never wrap and
+        // squeeze the title to a word a line instead). `items-start` so a two-line
+        // description does not pull the button down to its middle; `ms-auto` keeps
+        // the actions at the end with no title, and when they wrap.
+        <div data-slot="wizard-step-header" className="flex flex-wrap items-start justify-between gap-x-4 gap-y-2">
+          {(hasTitle || hasDescription) && <div className="min-w-0 grow basis-64 space-y-1">{heading}</div>}
+          <div data-slot="wizard-step-actions" className="ms-auto flex shrink-0 flex-wrap items-center gap-2">
+            {actions}
+          </div>
+        </div>
+      ) : (
+        // Without actions the header is exactly what it was, so a step that passes
+        // none renders as before.
+        (hasTitle || hasDescription) && (
+          <div data-slot="wizard-step-header" className="space-y-1">
+            {heading}
+          </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