@eifi1/ui-kit 0.50.1 → 0.51.0

package/src/shell/dev-switchers.tsx

@@ -1,179 +1,18 @@
-import { useState } from "react";
-import type { ReactNode } from "react";
-import { FlaskConical, Undo2 } from "lucide-react";
-import { DEFAULT_TOP_BAR_LABELS, useKitLabels, type LabelOverride } from "../i18n/kit-labels";
-import { TopBarActionMenu, type TopBarMenuEntry } from "./topbar-action-menu";
-import { useTopBarPartsLabels, type DevSwitchersLabels } from "./top-bar-parts-labels";
+import { DevMenu, type DevMenuProps } from "./dev-menu";
 
-/** Where the role the session started with is kept, unless the app names its own key. */
-export const DEV_ORIGINAL_ROLE_KEY = "ui-kit:dev-original-role";
+// 0.42's local-dev switchers (docs/top-bar-harmonization.md §2.7, §6.2, §6.3), since 0.51
+// a `DevMenu` with no app sections (§2.7.1). The props are the same and so is every row,
+// "Back to {role}" and its `sessionStorage` included — but it draws ONE flask where it
+// drew two: the role and the plan are groups of one menu, as in DevMenu.
 
-function readKey(key: string): string | null {
-  try {
-    return sessionStorage.getItem(key);
-  } catch {
-    return null;
-  }
-}
-
-function writeKey(key: string, value: string | null): void {
-  try {
-    if (value === null) sessionStorage.removeItem(key);
-    else sessionStorage.setItem(key, value);
-  } catch {
-    /* storage blocked: "Back to" lasts as long as this page */
-  }
-}
-
-export interface DevSwitchersProps<R extends string, P extends string> {
-  /** Draw anything at all: the app passes `import.meta.env.DEV`, so a production build
-   *  tree-shakes the switchers with the constant. */
-  enabled: boolean;
-  roles?: readonly R[];
-  /** The role the server enforces now. Named `currentRole`, not `role`, because `role` on
-   *  a JSX element is the ARIA role (as `RoleChip`'s `value`). */
-  currentRole?: R;
-  /** Apply a role — the app calls server-kit's `POST /dev/switch {role}` and re-reads
-   *  `/auth/me` (§2.7, §6.2). */
-  onRole?: (role: R) => void;
-  plans?: readonly P[];
-  /** The plan the server enforces now. Left out (not known yet — kastlan's overview is a
-   *  404 while billing is off), the plan menu still renders, with no row checked; a
-   *  `GET /dev/switch` answers it. */
-  currentPlan?: P;
-  /** Apply a plan — `POST /dev/switch {plan}`, then the overview (§6.3). */
-  onPlan?: (plan: P) => void;
-  /**
-   * The role to offer "Back to {role}" for. Left out, the kit keeps it itself: the role
-   * before the first switch of this browser session, in `sessionStorage` under
-   * `storageKey` — the server answers with the NEW role after a switch, so only the
-   * browser still knows the old one.
-   */
-  originalRole?: R;
-  /** The `sessionStorage` key for the kept role. Default {@link DEV_ORIGINAL_ROLE_KEY};
-   *  an app with several accounts on one browser may scope it per user. */
-  storageKey?: string;
-  /** Billing is off locally: the plan menu says plans change nothing, and stays usable
-   *  (§6.3). */
-  billingOff?: boolean;
-  /** A role's or a plan's words in the menu. Default: the value itself. */
-  roleLabel?: (role: R) => ReactNode;
-  planLabel?: (plan: P) => ReactNode;
-  /** Prop > `<UiKitProvider labels={{ topBarParts: { dev } }}>` > English. */
-  labels?: LabelOverride<DevSwitchersLabels>;
-}
-
-const flask = <FlaskConical className="size-5 text-warning" />;
-
-/** A label's text for a sentence, or the raw value when the label is not text. */
-const textOf = (label: ReactNode, value: string) =>
-  typeof label === "string" || typeof label === "number" ? String(label) : value;
-
-/**
- * The top bar's local-dev switchers (docs/top-bar-harmonization.md §2.7, §6.2, §6.3): the
- * role, then the plan, each a menu behind `RoleSwitcher`'s amber flask. Nothing renders
- * unless `enabled`; either menu renders only with its list and handler.
- *
- * The role menu ends in "Back to {role}" once the role differs from the one the session
- * started with: the dev route needs only a signed-in user, so a switch to a lesser role
- * can always switch back. With `billingOff` the plan menu notes that plans change nothing
- * while billing is off.
- */
-export function DevSwitchers<R extends string, P extends string>({
-  enabled,
-  roles,
-  currentRole: role,
-  onRole,
-  plans,
-  currentPlan: plan,
-  onPlan,
-  originalRole,
-  storageKey = DEV_ORIGINAL_ROLE_KEY,
-  billingOff = false,
-  roleLabel = (r) => r,
-  planLabel = (p) => p,
-  labels: labelsProp,
-}: DevSwitchersProps<R, P>) {
-  const bar = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS);
-  const words = useTopBarPartsLabels(labelsProp ? { dev: labelsProp } : undefined).dev;
-  const [kept, setKept] = useState<string | null>(() => (enabled ? readKey(storageKey) : null));
-  // 0.43 (keksdose): `enabled` may start false and turn true — an app's GET probe of the
-  // dev route — so the kept role is read again then, or "Back to {role}" is lost after a
-  // reload. Adjusted during render, React's pattern for state that follows a prop.
-  const [wasEnabled, setWasEnabled] = useState(enabled);
-  if (wasEnabled !== enabled) {
-    setWasEnabled(enabled);
-    if (enabled) setKept(readKey(storageKey));
-  }
-  if (!enabled) return null;
-
-  const original = (originalRole ?? kept ?? undefined) as R | undefined;
-
-  const pickRole = (next: R) => {
-    if (originalRole === undefined) {
-      if (next === original) {
-        // Back where the session began: nothing left to go back to.
-        writeKey(storageKey, null);
-        setKept(null);
-      } else if (kept === null && role !== undefined && next !== role) {
-        writeKey(storageKey, role);
-        setKept(role);
-      }
-    }
-    onRole?.(next);
-  };
-
-  const roleMenu =
-    roles && roles.length > 0 && role !== undefined && onRole ? (
-      <TopBarActionMenu
-        icon={flask}
-        aria-label={`${bar.switchRole} · ${bar.role(role)}`}
-        entries={[
-          { kind: "heading", key: "head-role", label: words.roleHeading },
-          ...roles.map(
-            (r): TopBarMenuEntry => ({ key: `role-${r}`, label: roleLabel(r), checked: r === role, onSelect: () => pickRole(r) }),
-          ),
-          ...(original !== undefined && original !== role
-            ? ([
-                { kind: "divider", key: "sep-back" },
-                {
-                  key: "back",
-                  icon: <Undo2 className="size-4" />,
-                  label: words.backTo(textOf(roleLabel(original), original)),
-                  onSelect: () => pickRole(original),
-                },
-              ] satisfies TopBarMenuEntry[])
-            : []),
-        ]}
-      />
-    ) : null;
+// Where it has always been imported from, until the wrapper goes in 0.52; the key and the
+// "Back to" logic it serves are DevMenu's now.
+export { DEV_ORIGINAL_ROLE_KEY } from "./dev-menu";
 
-  const planMenu =
-    plans && plans.length > 0 && onPlan ? (
-      <TopBarActionMenu
-        icon={flask}
-        aria-label={plan !== undefined ? `${words.switchPlan} · ${words.plan(plan)}` : words.switchPlan}
-        entries={[
-          { kind: "heading", key: "head-plan", label: words.planHeading },
-          ...plans.map(
-            (p): TopBarMenuEntry => ({ key: `plan-${p}`, label: planLabel(p), checked: p === plan, onSelect: () => onPlan(p) }),
-          ),
-        ]}
-      >
-        {billingOff
-          ? () => (
-              <li data-dev-billing-off="" className="mt-1 max-w-64 border-t border-subtle px-3 py-2 text-xs text-muted">
-                {words.billingOff}
-              </li>
-            )
-          : undefined}
-      </TopBarActionMenu>
-    ) : null;
+/** @deprecated 0.51 — use {@link DevMenuProps} (the same props); removed in 0.52. */
+export type DevSwitchersProps<R extends string, P extends string> = Omit<DevMenuProps<R, P>, "sections" | "active">;
 
-  return (
-    <>
-      {roleMenu}
-      {planMenu}
-    </>
-  );
+/** @deprecated 0.51 — use {@link DevMenu} (one flask; same props); removed in 0.52. */
+export function DevSwitchers<R extends string, P extends string>(props: DevSwitchersProps<R, P>) {
+  return <DevMenu {...props} />;
 }

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/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