@eifi1/ui-kit 0.41.0 → 0.42.0

package/src/shell/dev-switchers.tsx

@@ -0,0 +1,171 @@
+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";
+
+/** 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";
+
+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));
+  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;
+
+  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;
+
+  return (
+    <>
+      {roleMenu}
+      {planMenu}
+    </>
+  );
+}

package/src/shell/sync-status-indicator.tsx

@@ -0,0 +1,301 @@
+import { useEffect, useRef, useState } from "react";
+import type { ComponentType } from "react";
+import { Check, Cloud, CloudAlert, CloudOff, RefreshCw, UploadCloud } from "lucide-react";
+import type { LucideProps } from "lucide-react";
+import { cn } from "../lib/cn";
+import { IconButton } from "../components/icon-button";
+import { Tooltip } from "../components/tooltip";
+import { useBillingLabels } from "../billing/billing-labels";
+import { useKitLocale, type LabelOverride } from "../i18n/kit-labels";
+import { useTopBarPartsLabels, type SyncStatusLabels } from "./top-bar-parts-labels";
+
+/**
+ * What the indicator shows, fed by the app's sync engine (docs/top-bar-harmonization.md
+ * §2.6). Small on purpose: keksdose's sync-status store, kastlan's handover controller and
+ * Kurvenschmiede's online state + `useIsMutating` all fill it.
+ */
+export interface SyncStatus {
+  /** What the engine is doing. `offline` is the engine's own verdict; `online: false` is
+   *  the browser's — either shows the offline state. */
+  phase: "idle" | "syncing" | "offline" | "error";
+  /** The browser's `navigator.onLine` (or the app's better guess). */
+  online: boolean;
+  /** Writes kept on this device and not yet sent. */
+  pending: number;
+  /** Writes this device cannot send at all (keksdose: no key for the budget). Ranked first. */
+  blocked?: number;
+  /** Writes the server refused as read-only and keeps until a plan (billing §12.5). */
+  waitingForPlan?: number;
+  /** When the last good round ended — epoch ms, an ISO string or a `Date`. */
+  lastSyncedAt?: number | string | Date | null;
+}
+
+/** The seven states, in their ranking: the first that holds wins. */
+export type SyncState = "blocked" | "waitingForPlan" | "offline" | "error" | "syncing" | "pending" | "synced";
+
+/**
+ * Which of the seven states a {@link SyncStatus} is in — keksdose's ranking
+ * (sync-status-indicator.tsx): a write that cannot be sent at all ranks above everything,
+ * because waiting cannot help it; then one waiting for a plan; then offline; then a refused
+ * round; then a round under way; then writes waiting; else in sync. `syncing` also holds
+ * while a tap's own round runs (`refreshing`), before the engine publishes its phase.
+ */
+export function syncState(status: SyncStatus, refreshing = false): SyncState {
+  if ((status.blocked ?? 0) > 0) return "blocked";
+  if ((status.waitingForPlan ?? 0) > 0) return "waitingForPlan";
+  if (!status.online || status.phase === "offline") return "offline";
+  if (status.phase === "error") return "error";
+  if (status.phase === "syncing" || refreshing) return "syncing";
+  if (status.pending > 0) return "pending";
+  return "synced";
+}
+
+type Tone = "danger" | "warning" | "info" | "success";
+
+const LOOK: Record<SyncState, { Icon: ComponentType<LucideProps>; tone: Tone }> = {
+  // The one the user must act on: the kit's danger, where keksdose had rose.
+  blocked: { Icon: CloudAlert, tone: "danger" },
+  // Safe, and a payment sends them: amber, the kit's warning.
+  waitingForPlan: { Icon: CloudAlert, tone: "warning" },
+  offline: { Icon: CloudOff, tone: "warning" },
+  // Usually resolves by itself (a deploy, a read-only view): amber, not danger.
+  error: { Icon: CloudAlert, tone: "warning" },
+  syncing: { Icon: RefreshCw, tone: "info" },
+  pending: { Icon: UploadCloud, tone: "warning" },
+  synced: { Icon: Cloud, tone: "success" },
+};
+
+const TEXT_TONE: Record<Tone, string> = {
+  danger: "text-danger",
+  warning: "text-warning",
+  info: "text-info",
+  success: "text-success",
+};
+
+/** The scope words of an indicator that covers only part of the app (§6.10). */
+export interface SyncStatusScope {
+  /** Put before every state in the tooltip: "Handovers on this device" →
+   *  "Handovers on this device: 3 changes waiting to sync". */
+  name: string;
+  /** The whole offline sentence instead of the kit's, when offline means something
+   *  narrower: "Offline: handovers keep working on this device; everything else needs a
+   *  connection". */
+  offline?: string;
+}
+
+export interface SyncStatusIndicatorProps {
+  status: SyncStatus;
+  /**
+   * Run a round now (push, then pull, then re-read what is on screen). With it the
+   * indicator is a "sync now" button, disabled offline and mid-round but keeping its
+   * colour; a returned promise keeps the spin until it settles. Without it, a status only
+   * (§6.9).
+   */
+  onSync?: () => void | Promise<unknown>;
+  /** Render nothing while in sync — kastlan and Kurvenschmiede show it only while offline,
+   *  syncing or with changes waiting, held or refused (§2.6). */
+  hideWhenIdle?: boolean;
+  /** The app's words for its part of the app (§6.10). */
+  scope?: SyncStatusScope;
+  /**
+   * Where the app keeps a change before the server has it. `"device"` (the default): an
+   * offline-first app (keksdose, kastlan's handovers) — offline means "kept here, sent
+   * later". `"none"`: an online-only app that keeps nothing on the device (Kurvenschmiede,
+   * build review B1) — offline reads "changes can't be saved until you reconnect", a
+   * round reads "Saving…", and `pending`, `blocked` and `waitingForPlan` are ignored,
+   * since there is nowhere for a change to wait. "Up to date" when settled.
+   */
+  storage?: "device" | "none";
+  /** Short words beside the cloud ("Offline", "Syncing…", "3 waiting") while not in sync. */
+  showLabel?: boolean;
+  /** Prop > `<UiKitProvider labels={{ topBarParts: { sync } }}>` > English. */
+  labels?: LabelOverride<SyncStatusLabels>;
+  /** The clock's language for "Synced at 14:05". Default: the provider's locale. */
+  locale?: string;
+  className?: string;
+  /** `data-*` attributes go on the trigger — a tour's anchor (`data-tour="sync-status"`). */
+  [key: `data-${string}`]: string | number | boolean | undefined;
+}
+
+/** The `data-*` attributes of a rest object, for a trigger. */
+function dataAttributes(rest: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(rest).filter(([k]) => k.startsWith("data-")));
+}
+
+/**
+ * The top bar's sync status (docs/top-bar-harmonization.md §2.6), lifted from keksdose's
+ * `SyncStatusIndicator`: the seven states and their ranking ({@link syncState}), one cloud
+ * per state, a ✓ badge when in sync and a spin while syncing. With `onSync` it is also the
+ * "sync now" button, and its name says both what it is and what a tap does.
+ *
+ * Colours are the kit's roles — danger for a write that cannot be sent, warning for
+ * anything waiting, info while syncing, success when in sync — where keksdose had raw
+ * rose/amber/sky/emerald pairs.
+ */
+export function SyncStatusIndicator({
+  status,
+  onSync,
+  hideWhenIdle = false,
+  scope,
+  showLabel = false,
+  labels: labelsProp,
+  locale: localeProp,
+  className,
+  storage = "device",
+  ...rest
+}: SyncStatusIndicatorProps) {
+  const words = useTopBarPartsLabels(labelsProp ? { sync: labelsProp } : undefined).sync;
+  const billing = useBillingLabels();
+  const locale = useKitLocale(localeProp);
+  // The tap's own round, local rather than in the app's store: the store's phase belongs
+  // to the sync engine, and a second writer would race the round itself.
+  const [refreshing, setRefreshing] = useState(false);
+  const mounted = useRef(true);
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+
+  const onlineOnly = storage === "none";
+  // Online-only: nothing waits on the device, so only offline, error, saving and settled.
+  const state = syncState(
+    onlineOnly ? { ...status, pending: 0, blocked: 0, waitingForPlan: 0 } : status,
+    refreshing,
+  );
+  const data = dataAttributes(rest);
+  if (hideWhenIdle && state === "synced") return null;
+
+  const { Icon, tone } = LOOK[state];
+  const spin = state === "syncing";
+  let text: string;
+  switch (state) {
+    case "blocked":
+      text = words.blocked(status.blocked ?? 0);
+      break;
+    case "waitingForPlan":
+      text = billing.waitingChanges(status.waitingForPlan ?? 0);
+      break;
+    case "offline":
+      text = onlineOnly ? words.offlineUnsaved : words.offline;
+      break;
+    case "error":
+      text = words.refused;
+      break;
+    case "syncing":
+      text = onlineOnly ? words.saving : words.syncing;
+      break;
+    case "pending":
+      text = words.pending(status.pending);
+      break;
+    default:
+      text = !onlineOnly && status.lastSyncedAt
+        ? words.syncedAt(
+            // A clock time in the UI's language, never the browser's (keksdose live #246).
+            new Date(status.lastSyncedAt).toLocaleTimeString(locale, { hour: "2-digit", minute: "2-digit" }),
+          )
+        : words.idle;
+  }
+  if (scope) {
+    text = state === "offline" && scope.offline ? scope.offline : words.scoped(scope.name, text);
+  }
+
+  const short =
+    state === "offline"
+      ? words.offlineShort
+      : state === "syncing"
+        ? onlineOnly
+          ? words.saving
+          : words.syncingShort
+        : state === "error"
+          ? words.refusedShort
+          : state === "pending" || state === "blocked" || state === "waitingForPlan"
+            ? words.waitingShort(
+                state === "pending"
+                  ? status.pending
+                  : state === "blocked"
+                    ? (status.blocked ?? 0)
+                    : (status.waitingForPlan ?? 0),
+              )
+            : null;
+
+  const offline = state === "offline";
+  const canSync = !!onSync && status.online && status.phase !== "offline" && !spin;
+  const name = onSync
+    ? canSync
+      ? words.withHint(text, words.syncHint)
+      : offline
+        ? words.withHint(text, words.offlineHint)
+        : text
+    : text;
+  const badge = state === "synced" ? <Check className="stroke-[3]" /> : undefined;
+  const glyph = <Icon aria-hidden className={spin ? "animate-spin" : undefined} />;
+
+  const sync = async () => {
+    if (!canSync || !onSync) return;
+    setRefreshing(true);
+    try {
+      await onSync();
+    } finally {
+      if (mounted.current) setRefreshing(false);
+    }
+  };
+
+  const control = onSync ? (
+    <IconButton
+      {...data}
+      data-sync-state={state}
+      size="2xs"
+      glyphSize={20}
+      shape="round"
+      // A status that is also an action: disabled (offline, mid-round) is exactly when
+      // the state matters most, so it keeps its colour.
+      disabledStyle="keep"
+      tone={tone}
+      quiet={false}
+      label={name}
+      labelVisible={false}
+      // Below: the bar is at the top edge, where a bubble above has no room.
+      tooltipSide="bottom"
+      onClick={() => void sync()}
+      disabled={!canSync}
+      // It announces itself as a status: a reader hears the state change.
+      aria-live="polite"
+      badge={badge}
+    >
+      {glyph}
+    </IconButton>
+  ) : (
+    <Tooltip label={name} side="bottom">
+      <span
+        {...data}
+        role="status"
+        data-sync-state={state}
+        className={cn("relative inline-flex size-9 shrink-0 items-center justify-center [&>svg]:size-5", TEXT_TONE[tone])}
+      >
+        {glyph}
+        <span className="sr-only">{name}</span>
+        {badge && (
+          <span
+            aria-hidden
+            className="pointer-events-none absolute bottom-1.5 end-1.5 inline-flex rounded-full bg-surface [&_svg]:size-3"
+          >
+            {badge}
+          </span>
+        )}
+      </span>
+    </Tooltip>
+  );
+
+  if (!showLabel || !short) return className ? <span className={cn("inline-flex", className)}>{control}</span> : control;
+  return (
+    <span className={cn("inline-flex items-center gap-1", className)}>
+      {control}
+      {/* The eye's short words; the name above already says it in full. */}
+      <span aria-hidden className={cn("whitespace-nowrap text-xs font-medium", TEXT_TONE[tone])}>
+        {short}
+      </span>
+    </span>
+  );
+}

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

@@ -0,0 +1,79 @@
+import { Fragment } from "react";
+import type { ReactNode } from "react";
+
+/**
+ * The top bar's items by name (docs/top-bar-harmonization.md §2.1, §6.6). Each is the
+ * app's own node — a kit part or its own — and any may be left out.
+ */
+export interface TopBarActionsProps {
+  /** kastlan's `CompanySwitcher`: the context, first. */
+  companySwitcher?: ReactNode;
+  /** `GlobalSearch` (⌘K). */
+  search?: ReactNode;
+  /** `ThemeToggle`. */
+  theme?: ReactNode;
+  /** `FeedbackMenu`. */
+  feedback?: ReactNode;
+  /** `TourMenu`. */
+  tours?: ReactNode;
+  /** kastlan's assistant, beside the tours while it is on. */
+  assistant?: ReactNode;
+  /** `SyncStatusIndicator`. */
+  sync?: ReactNode;
+  /** `DevSwitchers` (role, then plan). */
+  dev?: ReactNode;
+  /** kastlan's platform button. */
+  platform?: ReactNode;
+  /** The account menu. When it is set the signed-out slots are not drawn. */
+  account?: ReactNode;
+  /** Signed out (§6.6): the bar's `LanguageMenu`, since there is no account menu to hold
+   *  the language. Drawn only without `account`. */
+  language?: ReactNode;
+  /** Signed out (§6.6): the "Sign in" button, where the account menu would be. Drawn only
+   *  without `account`. */
+  signIn?: ReactNode;
+}
+
+/** §2.1's order, then the signed-out pair in the account menu's place. */
+export const TOP_BAR_ACTION_ORDER = [
+  "companySwitcher",
+  "search",
+  "theme",
+  "feedback",
+  "tours",
+  "assistant",
+  "sync",
+  "dev",
+  "platform",
+  "account",
+  "language",
+  "signIn",
+] as const satisfies readonly (keyof TopBarActionsProps)[];
+
+const present = (node: ReactNode) => node !== undefined && node !== null && node !== false && node !== "";
+
+/**
+ * The top bar's actions in the one order every app shares (§2.1): company switcher ·
+ * Search · Theme · Feedback · Tours (· Assistant) · Sync · dev role · dev plan · platform ·
+ * account menu — and, signed out, Language · Sign in where the account menu goes (§6.6).
+ * The app fills the slots it has; an empty slot is skipped, so it leaves no gap.
+ *
+ * It draws a fragment, no box of its own: hand it to `TopBar`'s `actions`, whose row
+ * spaces the items.
+ *
+ * ```tsx
+ * <TopBar brand={…} actions={<TopBarActions search={…} theme={…} tours={…} account={…} />} />
+ * ```
+ */
+export function TopBarActions(props: TopBarActionsProps) {
+  const signedOut = !present(props.account);
+  return (
+    <>
+      {TOP_BAR_ACTION_ORDER.map((slot) => {
+        if ((slot === "language" || slot === "signIn") && !signedOut) return null;
+        const node = props[slot];
+        return present(node) ? <Fragment key={slot}>{node}</Fragment> : null;
+      })}
+    </>
+  );
+}

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

@@ -0,0 +1,133 @@
+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
+ * 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.
+ */
+
+/** `TourMenu`'s words (§2.4). */
+export interface TourMenuLabels {
+  /** The compass's name, and the menu's. */
+  menu: string;
+  /** The NEW dot on the compass, for a reader: it joins the trigger's name. */
+  newDot: string;
+  /** The heading over the tours that start on the open page. */
+  thisPage: string;
+  /** The heading over the untaken new tours. */
+  newTours: string;
+  /** The last row, the way to the app's tours page (only with `href`). */
+  allTours: string;
+  /** The chip on a new tour's row. */
+  badgeNew: string;
+  /** What the ✓ on a taken tour's row says to a reader. */
+  completed: string;
+}
+
+/** `SyncStatusIndicator`'s words (§2.6). The "waiting for a plan" state is
+ *  `billing.waitingChanges`, the kit's words for it since billing §12.5. */
+export interface SyncStatusLabels {
+  /** Writes this device cannot send (keksdose: no key for the budget). Ranked first. */
+  blocked: (count: number) => string;
+  offline: string;
+  /** The server refused the last round. */
+  refused: string;
+  syncing: string;
+  pending: (count: number) => string;
+  /** Settled, with the time of the last good round (already formatted). */
+  syncedAt: (time: string) => string;
+  /** Settled, before the first round. */
+  idle: string;
+  /** Joined to the state when a tap syncs: what the tap does. */
+  syncHint: string;
+  /** Joined to the state while offline, when a tap can do nothing. */
+  offlineHint: string;
+  /** The state and what a tap does, as one tooltip: "Offline — nothing to sync…". */
+  withHint: (state: string, hint: string) => string;
+  /** The state with the app's `scope` words before it: "Handovers on this device: …". */
+  scoped: (scope: string, state: string) => string;
+  /** The short words beside the cloud (`showLabel`): offline. */
+  offlineShort: string;
+  /** The short words while syncing. */
+  syncingShort: string;
+  /** The short words while changes wait (pending, held for a plan, or blocked). */
+  waitingShort: (count: number) => string;
+  /** The short words after a refused round. */
+  refusedShort: string;
+  /** Offline in an online-only app (`storage="none"`): nothing is kept on the device. */
+  offlineUnsaved: string;
+  /** A round under way in an online-only app — it saves, it doesn't sync. Also its short
+   *  words beside the cloud. */
+  saving: string;
+}
+
+/** `DevSwitchers`' words (§2.7, §6.2, §6.3). */
+export interface DevSwitchersLabels {
+  /** The heading of the role menu. */
+  roleHeading: string;
+  /** The plan switcher's name. */
+  switchPlan: string;
+  /** The plan switcher's tooltip, given the active plan. */
+  plan: (value: string) => string;
+  /** The heading of the plan menu. */
+  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. */
+  billingOff: string;
+}
+
+export interface TopBarPartsLabels {
+  tours: TourMenuLabels;
+  sync: SyncStatusLabels;
+  dev: DevSwitchersLabels;
+}
+
+export const DEFAULT_TOP_BAR_PARTS_LABELS: TopBarPartsLabels = {
+  tours: {
+    menu: "Guided tours",
+    newDot: "New tours",
+    thisPage: "On this page",
+    newTours: "New tours",
+    allTours: "All tours…",
+    badgeNew: "New",
+    completed: "Completed",
+  },
+  sync: {
+    blocked: (count) =>
+      count === 1
+        ? "1 change cannot be sent from this device"
+        : `${count} changes cannot be sent from this device`,
+    offline: "Offline — changes are saved on this device and will sync when you reconnect",
+    refused: "The server refused the last sync",
+    syncing: "Syncing…",
+    pending: (count) => (count === 1 ? "1 change waiting to sync" : `${count} changes waiting to sync`),
+    syncedAt: (time) => `Synced at ${time}`,
+    idle: "Up to date",
+    syncHint: "Tap to sync now",
+    offlineHint: "nothing to sync while offline",
+    withHint: (state, hint) => `${state} — ${hint}`,
+    scoped: (scope, state) => `${scope}: ${state}`,
+    offlineShort: "Offline",
+    syncingShort: "Syncing…",
+    waitingShort: (count) => `${count} waiting`,
+    refusedShort: "Not synced",
+    offlineUnsaved: "Offline — changes can't be saved until you reconnect",
+    saving: "Saving…",
+  },
+  dev: {
+    roleHeading: "Dev · role",
+    switchPlan: "Switch plan",
+    plan: (value) => `Plan: ${value}`,
+    planHeading: "Dev · plan",
+    backTo: (role) => `Back to ${role}`,
+    billingOff: "Billing is off locally: plans change nothing",
+  },
+};
+
+/** The `topBarParts` namespace, resolved — English, then the provider, then `labels`. */
+export function useTopBarPartsLabels(labels?: LabelOverride<TopBarPartsLabels>): TopBarPartsLabels {
+  return useKitLabels("topBarParts", DEFAULT_TOP_BAR_PARTS_LABELS, labels);
+}