@eifi1/ui-kit 0.50.0 → 0.51.0

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

@@ -20,7 +20,10 @@ export interface TopBarActionsProps {
   assistant?: ReactNode;
   /** `SyncStatusIndicator`. */
   sync?: ReactNode;
-  /** `DevSwitchers` (role, then plan). */
+  /** `DevMenu` (0.51, docs/top-bar-harmonization.md §2.7.1): the one flask — the role,
+   *  the plan, then the app's own dev sections. Fill it only behind
+   *  `import.meta.env.DEV`, so a production build drops the branch. (0.42's
+   *  `DevSwitchers`, deprecated, is a DevMenu with no sections.) */
   dev?: ReactNode;
   /** kastlan's platform button. */
   platform?: ReactNode;

package/src/shell/top-bar-parts-labels.ts

@@ -2,10 +2,11 @@ import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
 
 /**
  * The `topBarParts` namespace (0.42, docs/top-bar-harmonization.md §3.1): the words of the
- * top bar's shared parts — `TourMenu`, `SyncStatusIndicator` and `DevSwitchers`. A module
+ * top bar's shared parts — `TourMenu`, `SyncStatusIndicator` and `DevMenu` (0.42's
+ * `DevSwitchers`, whose words these still are, §2.7.1). A module
  * of words with no component code, like every `*-labels.ts` (0.34, KS U8). The language
- * sub-list (`AccountMenuLanguage`) names itself with `topBar.language`, and the dev role
- * switcher's name and tooltip are `topBar.switchRole` / `topBar.role`, as `RoleSwitcher`'s.
+ * sub-list (`AccountMenuLanguage`) names itself with `topBar.language`, and the role in the
+ * dev flask's name is `topBar.role`, as `RoleSwitcher`'s tooltip.
  */
 
 /** `TourMenu`'s words (§2.4). */
@@ -69,19 +70,27 @@ export interface SyncStatusLabels {
   saving: string;
 }
 
-/** `DevSwitchers`' words (§2.7, §6.2, §6.3). */
+/**
+ * `DevMenu`'s words (§2.7, §2.7.1, §6.2, §6.3). Still named for 0.42's `DevSwitchers`: the
+ * namespace is the same `topBarParts.dev`, and an app's label tree keeps compiling.
+ */
 export interface DevSwitchersLabels {
-  /** The heading of the role menu. */
+  /** 0.51: the flask's name, and the menu's — the role and the plan follow it. */
+  menu: string;
+  /** 0.51: what the dot on the flask means while `active`, joined to its name — an
+   *  override the developer could forget is on (a "today", a slow server). */
+  overridesOn: string;
+  /** The heading of the role group. */
   roleHeading: string;
-  /** The plan switcher's name. */
+  /** @deprecated 0.51 — DevMenu's one flask is named by `menu`; removed in 0.52. */
   switchPlan: string;
-  /** The plan switcher's tooltip, given the active plan. */
+  /** The plan in the flask's name, given the active plan. */
   plan: (value: string) => string;
-  /** The heading of the plan menu. */
+  /** The heading of the plan group. */
   planHeading: string;
   /** The row back to the role the session started with. */
   backTo: (role: string) => string;
-  /** The plan menu's note while billing is off locally. */
+  /** The plan group's note while billing is off locally. */
   billingOff: string;
 }
 
@@ -127,6 +136,8 @@ export const DEFAULT_TOP_BAR_PARTS_LABELS: TopBarPartsLabels = {
     saving: "Saving…",
   },
   dev: {
+    menu: "Dev tools",
+    overridesOn: "Overrides on",
     roleHeading: "Dev · role",
     switchPlan: "Switch plan",
     plan: (value) => `Plan: ${value}`,

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

@@ -135,6 +135,16 @@ export interface TopBarMenuHeader {
 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]';
 
+/**
+ * `scrollable`'s cap (0.51, DevMenu): the glass under the bar. Under `TopBar` the panel
+ * starts about 50px down — the `size-9` trigger centred in the `h-12` bar ends at 42px,
+ * and `HoverMenu` hangs the panel `pt-2` below it — so 4rem (64px) leaves some 14px clear
+ * under the last row. `dvh`, not `vh`: on a phone `100vh` is the viewport with the
+ * browser's toolbars put away, taller than the glass while they show.
+ * `overscroll-contain`, so a fling past the last row does not scroll the page behind.
+ */
+const SCROLLABLE_PANEL = "max-h-[calc(100dvh-4rem)] overflow-y-auto overscroll-contain";
+
 /**
  * A header or footer inside the menu panel.
  *
@@ -195,7 +205,8 @@ function keepTabInsidePanel(e: ReactKeyboardEvent<HTMLUListElement>) {
  * A long menu is grouped by topic with `{ kind: "heading" }` entries (0.23) — see
  * {@link TopBarMenuEntry}. There is no separate phone layout: the panel is the same
  * hover panel at 390px, kept inside the viewport by `HoverMenu`, and a heading wraps
- * rather than widening it.
+ * rather than widening it. A menu that can grow taller than a phone's glass passes
+ * `scrollable` (0.51), since that clamp is sideways only.
  */
 export function TopBarActionMenu({
   icon,
@@ -213,6 +224,7 @@ export function TopBarActionMenu({
   footerLabel,
   align,
   panelClassName,
+  scrollable = false,
   triggerAttributes,
 }: {
   /** The trigger's face for the usual icon button. Ignored when `trigger` is given. */
@@ -282,6 +294,20 @@ export function TopBarActionMenu({
    *  direction (see `HoverMenu`, whose type this is). Default `end`. */
   align?: HoverMenuProps["align"];
   panelClassName?: string;
+  /**
+   * Cap the panel at the glass under the top bar and scroll the rows inside it (0.51,
+   * `DevMenu`). `HoverMenu` keeps a panel inside the viewport sideways only, so a tall
+   * one ran off the bottom of the screen: DevMenu's ~25 rows on a 390×844 phone, with
+   * the last ones out of reach — the page cannot scroll them up, the panel hangs from
+   * the sticky bar.
+   *
+   * Off by default: a menu that fits keeps its natural height and has no scroll
+   * container (`TourMenu` keeps its own `max-h-[70vh]`). The keyboard needs nothing
+   * extra: `HoverMenu`'s roving focus is a plain `focus()`, which the browser follows by
+   * scrolling the panel to the row, so ↓, ↑, Home and End reach a row below the cap. The
+   * header and the footer are inside the list and scroll with the rows.
+   */
+  scrollable?: boolean;
   /** `data-*` attributes for the trigger itself — a tour's anchor (`data-tour`), a test
    *  hook. The parts built on this menu (`TourMenu`) pass theirs through here. */
   triggerAttributes?: { [key: `data-${string}`]: string | number | boolean | undefined };
@@ -389,7 +415,7 @@ export function TopBarActionMenu({
         );
         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}>
+          <ul className={cn("py-1", scrollable && SCROLLABLE_PANEL, panelClassName)} onKeyDown={keepTabInsidePanel}>
             {header && (
               <MenuSection className="mb-1 border-b border-subtle px-3 py-2">
                 <div className="truncate text-sm font-medium text-primary">{header.title}</div>

package/src/shell.ts

@@ -89,7 +89,11 @@ export { TourMenu } from "./shell/tour-menu";
 export type { TourMenuProps, TourMenuTour } from "./shell/tour-menu";
 export { SyncStatusIndicator, syncState } from "./shell/sync-status-indicator";
 export type { SyncStatus, SyncState, SyncStatusScope, SyncStatusIndicatorProps } from "./shell/sync-status-indicator";
-export { DevSwitchers, DEV_ORIGINAL_ROLE_KEY } from "./shell/dev-switchers";
+// 0.51 (§2.7.1, keksdose): one flask, the kit's Account section and the app's own dev
+// sections; `DevSwitchers` is a deprecated wrapper over it until 0.52.
+export { DevMenu, DEV_ORIGINAL_ROLE_KEY } from "./shell/dev-menu";
+export type { DevMenuProps, DevMenuSection } from "./shell/dev-menu";
+export { DevSwitchers } from "./shell/dev-switchers";
 export type { DevSwitchersProps } from "./shell/dev-switchers";
 export { DEFAULT_TOP_BAR_PARTS_LABELS, useTopBarPartsLabels } from "./shell/top-bar-parts-labels";
 export type {

package/src/testing/index.ts

@@ -24,3 +24,11 @@ export {
   type StubbedBoxSize,
   type ViewportOptions,
 } from "./viewport";
+// 0.50.1 (keksdose N4): a valid `TourStepContext` for a test that calls a step's
+// `beforeStep` or `when` itself — `beforeStep!(tourStepContext())`.
+export {
+  tourStepContext,
+  type TestTourStepContext,
+  type TourStepContextOptions,
+  type TourStepVia,
+} from "./tour";

package/src/testing/tour.ts

@@ -0,0 +1,41 @@
+/**
+ * 0.50.1 (keksdose N4): a `TourStepContext` for a test that calls a step's `beforeStep` or
+ * `when` itself. 0.50 gave both the context, so `beforeStep!()` is a type error;
+ * `beforeStep!(tourStepContext())` is the drop-in.
+ *
+ * Spelled out here rather than imported from the tour module, so `@eifi1/ui-kit/testing`
+ * still reaches no package (the tour module reaches React); the kit's own test pins that it
+ * is assignable to `TourStepContext`.
+ */
+
+/** How a step is entered: `TourStepContext["via"]`. */
+export type TourStepVia = "start" | "at" | "next" | "back" | "goto";
+
+/** The shape of `TourStepContext` (`@eifi1/ui-kit/tour`). */
+export interface TestTourStepContext {
+  gate(key: string): boolean | undefined;
+  via: TourStepVia;
+}
+
+export interface TourStepContextOptions {
+  /** How the step is entered. Default `"start"`. */
+  via?: TourStepVia;
+  /**
+   * The published gates, as the form would publish them: `{ "txn.transfer": true }`. A key
+   * left out answers `undefined` (nobody publishes it). Default: none.
+   */
+  gates?: Readonly<Record<string, boolean | undefined>>;
+}
+
+/**
+ * A valid step context: `via: "start"` and no gates published, unless `options` say
+ * otherwise. `step.beforeStep!(tourStepContext())`, `step.when!(tourStepContext({ gates:
+ * { "txn.transfer": true } }))`, `tourStepContext({ via: "at" })` for a "Guide me" entry.
+ */
+export function tourStepContext(options: TourStepContextOptions = {}): TestTourStepContext {
+  const gates = options.gates ?? {};
+  return {
+    gate: (key) => (Object.prototype.hasOwnProperty.call(gates, key) ? gates[key] : undefined),
+    via: options.via ?? "start",
+  };
+}

package/src/theme/palette-presets.ts

@@ -211,10 +211,6 @@ export const PAUL_TOL_PRESET: PalettePreset = {
   },
 };
 
-/** @deprecated 0.49 — use `DEFAULT_PRESET` (Imprint IS the default now); removed in 0.51.
- *  A persisted `"imprint"` id resolves to it through `presetById`'s fallback. */
-export const IMPRINT_PRESET: PalettePreset = DEFAULT_PRESET;
-
 // The full-theme switcher from #307 stayed retired (feedback #328) — the default
 // is still the single source of truth for surfaces, brand and money (its five
 // alternatives are gone, see the header). What IS selectable is

package/src/tour/tour-engine.ts

@@ -0,0 +1,41 @@
+/**
+ * 0.50.1 (keksdose N1): the tour engine a launcher is handed as its fourth argument — one
+ * object for the life of the provider (or of `useTourUrlSync`) whose fields always read the
+ * engine's LATEST render: `engine.active`, `engine.index` after an `await` are current, and
+ * `engine.stop()` mid-run stops the run that is up now. Internal: the type is `TourEngine`.
+ *
+ * `set` is called from a layout effect with each render's engine; `engine` reads it.
+ */
+export function liveEngine<T extends object>(
+  keys: readonly (keyof T & string)[],
+  initial: T | null = null,
+): { engine: T; set: (current: T) => void } {
+  let current = initial;
+  const read = () => {
+    if (!current)
+      throw new Error(
+        "[ui-kit] The tour engine was read before its provider rendered.",
+      );
+    return current;
+  };
+  const engine = {} as T;
+  for (const key of keys) {
+    Object.defineProperty(engine, key, {
+      enumerable: true,
+      get: () => {
+        const value = read()[key];
+        // A method is looked up when it is CALLED, so a kept `engine.stop` is the latest too.
+        return typeof value === "function"
+          ? (...args: unknown[]) =>
+              (read()[key] as (...a: unknown[]) => unknown)(...args)
+          : value;
+      },
+    });
+  }
+  return {
+    engine,
+    set: (next) => {
+      current = next;
+    },
+  };
+}

package/src/tour/tour.tsx

@@ -20,11 +20,13 @@ import { useDismissLayer } from "../hooks/use-dismiss";
 import { sameRect } from "../hooks/use-anchored-rect";
 import { dirOf, horizontalStep } from "../lib/direction";
 import { isComposing } from "../lib/ime";
+import { focusQuietly } from "../lib/quiet-focus";
 import type { Direction } from "../lib/direction";
 import { DEFAULT_TOUR_LABELS } from "./tour-labels";
 import type { TourInfo } from "./tour-info";
 import { completeStored, rememberAccount, rememberMigrate, type UseTourProgressOptions } from "./use-tour-progress";
 import { createGateRegistry, devWarnings, TourInternalContext, type GateRegistry } from "./tour-gates";
+import { liveEngine } from "./tour-engine";
 import { DOCK_MAX_WIDTH, dockEdge, dockStyle, readBand, scrollIntoFreeHalf, type DockEdge } from "./tour-dock";
 
 export { useTourGate, useTourGateRelease } from "./tour-gates";
@@ -193,15 +195,42 @@ export type TourStart = TourContextValue["start"];
  * `useTourUrlSync`.
  *
  * `start` is the provider's own `start` (keksdose N4), so the launcher needs no ref to a
- * component below the provider and may be defined above it. `useTourUrlSync` passes it too
- * (under a provider). A two-argument launcher that reaches `start` its own way still works.
+ * component below the provider and may be defined above it. `engine` (0.50.1, keksdose N1)
+ * is the rest of the engine — `stop`, `next`, `active`, … — read live, see {@link TourEngine}.
+ * `useTourUrlSync` passes both (under a provider). A launcher taking fewer arguments still
+ * works.
  */
 export type TourLauncher = (
   id: string,
   opts: { startIndex?: number; at?: TourAt },
   start: TourStart,
+  engine: TourEngine,
 ) => void | Promise<unknown>;
 
+/**
+ * 0.50.1 (keksdose N1): the whole engine `useTour()` returns, handed to a launcher as its
+ * FOURTH argument by `TourProvider` and `useTourUrlSync`, so a tour built above the provider
+ * can also `stop`, `next` or read `active` with no `useTour()` registered from below. One
+ * object per provider whose fields read the latest render (`engine.active` after an
+ * `await` is current); its methods are the provider's own. `start` (the third argument) is
+ * `engine.start`.
+ */
+export type TourEngine = TourContextValue;
+
+const ENGINE_KEYS = [
+  "active",
+  "activeId",
+  "start",
+  "stop",
+  "next",
+  "prev",
+  "goToStep",
+  "index",
+  "total",
+  "position",
+  "count",
+] as const satisfies readonly (keyof TourContextValue)[];
+
 interface StartOptions {
   /** Stable id of the tour, surfaced as `activeId` so the app can mirror it to
    *  the URL (deep-link / evaluation tracking) and record completion. Defaults to
@@ -463,8 +492,11 @@ export function TourProvider({
     },
     [arrive, forward, backward],
   );
-  // The provider's own `start`, handed to `launch` as its third argument (keksdose N4).
+  // The provider's own `start` and the live engine, handed to `launch` as its third and
+  // fourth arguments (keksdose N4, N1).
   const ownStartRef = useRef<TourContextValue["start"] | null>(null);
+  const [live] = useState(() => liveEngine<TourEngine>(ENGINE_KEYS));
+  const engine = live.engine;
   const start = useCallback(
     (what: TourStep[] | string, opts?: StartOptions | { at?: TourAt }) => {
       if (typeof what !== "string") {
@@ -476,11 +508,11 @@ export function TourProvider({
         if (devWarnings()) console.warn(`[ui-kit] start("${what}") needs TourProvider's \`launch\` prop.`);
         return;
       }
-      void Promise.resolve(run(what, { at: opts?.at }, ownStartRef.current!)).catch((error: unknown) =>
+      void Promise.resolve(run(what, { at: opts?.at }, ownStartRef.current!, engine)).catch((error: unknown) =>
         console.error(error),
       );
     },
-    [startSteps],
+    [startSteps, engine],
   ) as TourContextValue["start"];
   useLayoutEffect(() => {
     ownStartRef.current = start;
@@ -573,23 +605,27 @@ export function TourProvider({
     });
   }, [active, gates, arrive, forward, finish]);
 
+  const value: TourContextValue = {
+    active,
+    activeId,
+    start,
+    stop,
+    next,
+    prev,
+    goToStep,
+    index,
+    total,
+    position: active ? nav.position : 0,
+    count: active ? nav.count : 0,
+  };
+  // Read by the live engine (`launch`'s fourth argument) after this render commits.
+  useLayoutEffect(() => {
+    live.set(value);
+  });
+
   return (
     <TourInternalContext.Provider value={internals}>
-      <TourContext.Provider
-        value={{
-          active,
-          activeId,
-          start,
-          stop,
-          next,
-          prev,
-          goToStep,
-          index,
-          total,
-          position: active ? nav.position : 0,
-          count: active ? nav.count : 0,
-        }}
-      >
+      <TourContext.Provider value={value}>
         {children}
         {active && (
           <TourOverlay
@@ -1104,11 +1140,14 @@ function TourOverlay({
     if (!ready || !guided || !step.target) return;
     const el = queryVisibleTarget(step.target);
     const control = el ? firstFocusable(el) : null;
+    // Described BEFORE it is focused, so a screen reader reads the step with the field's
+    // name. Focused quietly (0.50.1, keksdose B1): a picker that opens on focus stays
+    // closed, or its list would cover the card; ArrowDown, typing or a click opens it.
+    const previous = control ? control.getAttribute("aria-describedby") : null;
+    if (control) control.setAttribute("aria-describedby", previous ? `${previous} ${bodyId}` : bodyId);
     if (coarsePointer() || !control) cardRef.current?.focus();
-    else if (!el!.contains(document.activeElement)) control.focus();
+    else if (!el!.contains(document.activeElement)) focusQuietly(control);
     if (!control) return;
-    const previous = control.getAttribute("aria-describedby");
-    control.setAttribute("aria-describedby", previous ? `${previous} ${bodyId}` : bodyId);
     return () => {
       if (previous === null) control.removeAttribute("aria-describedby");
       else control.setAttribute("aria-describedby", previous);
@@ -1238,7 +1277,8 @@ function TourOverlay({
   const lockedNext = useCallback(() => {
     const el = step.target ? queryVisibleTarget(step.target) : null;
     const control = el ? firstFocusable(el) : null;
-    control?.focus();
+    // Quietly, as on arrival: the hint is read with the card in view, not under a list.
+    if (control) focusQuietly(control);
     announce(gateHint);
   }, [step.target, announce, gateHint]);
   const tryNext = awaitsRelease ? NOOP : locked ? lockedNext : onNext;

package/src/tour/use-tour-url-sync.ts

@@ -2,7 +2,8 @@ import { createContext, useContext, useEffect, useLayoutEffect, useRef, useState
 import * as ReactRouter from "react-router";
 import { useLocation, useNavigate, type Navigator } from "react-router";
 import { useSearchParamsState } from "../hooks/use-search-param-state";
-import { useTourOptional, type TourStart } from "./tour";
+import { useTourOptional, type TourEngine, type TourStart } from "./tour";
+import { liveEngine } from "./tour-engine";
 import { devWarnings } from "./tour-gates";
 
 /* ── useTourUrlSync ─────────────────────────────────────────────────────────── */
@@ -14,9 +15,16 @@ export interface UseTourUrlSyncOptions {
    * toast) to `useTour().start`. An unknown id should do nothing. May return a promise:
    * the parameters are kept until it settles. Under a `TourProvider` the third argument is
    * that provider's `start` (0.50, as `TourProvider launch` gets it), so one launcher serves
-   * both. Without a provider it is a `start` that does nothing (a development build warns).
+   * both; the fourth is its whole engine, read live (0.50.1, `TourEngine`: `stop`, `next`,
+   * `active`, …). Without a provider `start` and the engine's methods do nothing (a
+   * development build warns) and the engine reads as idle.
    */
-  launch: (id: string, options: { startIndex: number }, start: TourStart) => void | Promise<unknown>;
+  launch: (
+    id: string,
+    options: { startIndex: number },
+    start: TourStart,
+    engine: TourEngine,
+  ) => void | Promise<unknown>;
   /**
    * Are the facts a tour's steps are built from loaded yet (keksdose's `ready`: the
    * caches a branching tour reads)? A deep link waits for it, keeping its parameters, so
@@ -124,10 +132,12 @@ export function useTourUrlSync({ launch, ready = true, stepAliases = [] }: UseTo
 
   const launchRef = useRef(launch);
   const startRef = useRef<TourStart>(engine?.start ?? noProviderStart);
+  const [live] = useState(() => liveEngine<TourEngine>(ENGINE_KEYS, NO_PROVIDER_ENGINE));
   const activeIdRef = useRef(activeId);
   useLayoutEffect(() => {
     launchRef.current = launch;
     startRef.current = engine?.start ?? noProviderStart;
+    live.set(engine ?? NO_PROVIDER_ENGINE);
     activeIdRef.current = active ? activeId : null;
   });
   /** The `tour` value last seen in the URL: a tour starts when it CHANGES to an id. */
@@ -153,7 +163,7 @@ export function useTourUrlSync({ launch, ready = true, stepAliases = [] }: UseTo
     pendingRef.current = null;
     launchingRef.current = true;
     void Promise.resolve()
-      .then(() => launchRef.current(pending.id, { startIndex: pending.startIndex }, startRef.current))
+      .then(() => launchRef.current(pending.id, { startIndex: pending.startIndex }, startRef.current, live.engine))
       .catch(() => undefined)
       .finally(() => {
         launchingRef.current = false;
@@ -193,6 +203,25 @@ const noProviderStart: TourStart = () => {
   if (devWarnings()) console.warn("[ui-kit] useTourUrlSync: the launcher's start needs a TourProvider above it.");
 };
 
+const noProviderCall = () => {
+  if (devWarnings()) console.warn("[ui-kit] useTourUrlSync: the launcher's engine needs a TourProvider above it.");
+};
+/** The engine for a launcher run with no `TourProvider` above `useTourUrlSync`: idle. */
+const NO_PROVIDER_ENGINE: TourEngine = {
+  active: false,
+  activeId: null,
+  start: noProviderStart,
+  stop: noProviderCall,
+  next: noProviderCall,
+  prev: noProviderCall,
+  goToStep: noProviderCall,
+  index: 0,
+  total: 0,
+  position: 0,
+  count: 0,
+};
+const ENGINE_KEYS = Object.keys(NO_PROVIDER_ENGINE) as (keyof TourEngine)[];
+
 /* ── useTourCatalogueUrlState ───────────────────────────────────────────────── */
 
 /** The catalogue's state filter. */