@eifi1/ui-kit 0.40.1 → 0.42.0

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);
+}

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

@@ -206,11 +206,13 @@ export function TopBarActionMenu({
   heading,
   header,
   entries,
+  leading,
   children,
   footer,
   footerLabel,
   align,
   panelClassName,
+  triggerAttributes,
 }: {
   /** The trigger's face for the usual icon button. Ignored when `trigger` is given. */
   icon?: ReactNode;
@@ -260,6 +262,13 @@ export function TopBarActionMenu({
    * `close` shuts the menu.
    */
   children?: (close: () => void) => ReactNode;
+  /**
+   * Rows like {@link children}, but BEFORE `entries`, under the header — the account
+   * menu's `AccountMenuLanguage`, which goes first after the app's context rows (§6.5)
+   * in a menu whose other rows are all entries (kastlan, build review B1). Render `<li>`s;
+   * `close` shuts the menu.
+   */
+  leading?: (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
@@ -272,6 +281,9 @@ export function TopBarActionMenu({
    *  direction (see `HoverMenu`, whose type this is). Default `end`. */
   align?: HoverMenuProps["align"];
   panelClassName?: string;
+  /** `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 };
 }) {
   // Names the groups' headings for `aria-labelledby`. Positional rather than from the
   // entry's `key`, which is the caller's text and may hold a space — and a space in
@@ -286,11 +298,11 @@ export function TopBarActionMenu({
         // kit's button. Same classes and face either way.
         const control = (className: string, children: ReactNode, label?: string) =>
           href ? (
-            <Link to={href} onClick={close} aria-label={label} className={className}>
+            <Link {...triggerAttributes} to={href} onClick={close} aria-label={label} className={className}>
               {children}
             </Link>
           ) : (
-            <button type="button" onClick={toggle} aria-label={label} className={className}>
+            <button {...triggerAttributes} type="button" onClick={toggle} aria-label={label} className={className}>
               {children}
             </button>
           );
@@ -380,6 +392,7 @@ export function TopBarActionMenu({
                 {heading}
               </li>
             )}
+            {leading?.(close)}
             {toBlocks(entries).map((block, i, blocks) => {
               if (block.kind === "loose") {
                 const entry = block.entry;

package/src/shell/topbar-controls.tsx

@@ -25,16 +25,30 @@ function MenuHeading({ children }: { children: string }) {
   );
 }
 
-/** Sun/Moon toggle for the light/dark theme. Controlled: the app owns the mode. */
+/**
+ * Sun/Moon toggle for the light/dark theme. Controlled: the app owns the mode, and the
+ * toggle keeps no storage key of its own (docs/top-bar-harmonization.md §6.4).
+ *
+ * `mode` is the theme ON SCREEN — the resolved one, so with a "system" preference it is
+ * whatever the OS gives. A tap asks for the opposite of that: `onChange("light")` while
+ * dark is shown, `onChange("dark")` while light is. The app writes it as its theme
+ * preference (an explicit light or dark), where Settings → Appearance keeps the three-way
+ * choice. `onToggle` is the older way to hear the tap, without the next mode; both fire.
+ */
 export function ThemeToggle({
   mode,
   onToggle,
+  onChange,
   "aria-label": ariaLabel,
   title,
   className,
 }: {
+  /** The resolved light/dark on screen (`useThemeStore`'s `mode`, not its preference). */
   mode: ThemeMode;
-  onToggle: () => void;
+  /** Hears a tap. Kept for 0.41's callers; `onChange` says what to switch to. */
+  onToggle?: () => void;
+  /** 0.42: the mode to switch to — always the opposite of `mode`. */
+  onChange?: (next: ThemeMode) => void;
   /** Default: `topBar.theme` from the {@link UiKitProvider}, else English. */
   "aria-label"?: string;
   title?: string;
@@ -48,7 +62,10 @@ export function ThemeToggle({
     <Tooltip label={title} portal>
       <button
         type="button"
-        onClick={onToggle}
+        onClick={() => {
+          onChange?.(mode === "dark" ? "light" : "dark");
+          onToggle?.();
+        }}
         aria-label={labels.theme}
         className={cn(TOPBAR_TRIGGER_CLASS, className)}
       >