@takazudo/zudo-doc 5.26.5 → 5.27.0

package/eject/sidebar-tree-island/index.tsx

@@ -12,7 +12,7 @@ import { INDENT, BASE_PAD, connectorLeft, ConnectorLines, CategoryLinkIcon } fro
 import { ChevronRight, ChevronLeft, Search } from "../icons/index.js";
 // BARE ThemeToggle — renders inside the SidebarToggle island, so it must
 // NOT bring its own island wrapper.
-import { ThemeToggle } from "../theme-toggle/index.js";
+import { ThemeToggle, type ThemeToggleLabels } from "../theme-toggle/index.js";
 import { smartBreakToHtml } from "../smart-break/index.js";
 // After zudolab/zudo-doc#1335 the host components also pull lifecycle event
 // names from the v2 transitions module rather than hard-coding literals.
@@ -184,6 +184,8 @@ export interface SidebarTreeProps {
   locale?: string;
   localeLinks?: SidebarLocaleLink[];
   themeDefaultMode?: "light" | "dark";
+  themeLabels?: ThemeToggleLabels;
+  themeRespectSystem?: boolean;
   /**
    * Per-role date patterns already resolved for this page's locale, serialized
    * into the island's `data-props` by the SSR wrappers (`sidebar-with-defaults`
@@ -197,13 +199,13 @@ export interface SidebarTreeProps {
   dateFormats?: ResolvedDateFormats;
 }
 
-function SidebarFooter({ links, themeDefaultMode }: { links?: SidebarLocaleLink[]; themeDefaultMode?: "light" | "dark" }) {
+function SidebarFooter({ links, themeDefaultMode, themeLabels, themeRespectSystem }: { links?: SidebarLocaleLink[]; themeDefaultMode?: "light" | "dark"; themeLabels?: ThemeToggleLabels; themeRespectSystem?: boolean }) {
   if (!links && !themeDefaultMode) return null;
   return (
     // pb-[50vh] provides scroll room so the footer doesn't sit at the very bottom of the viewport
     <div className="lg:hidden flex items-center gap-hsp-md border-t border-muted px-hsp-sm py-vsp-xs pb-[50vh] text-small">
       {themeDefaultMode && (
-        <ThemeToggle defaultMode={themeDefaultMode} pendingUntilHydrated={true} />
+        <ThemeToggle defaultMode={themeDefaultMode} labels={themeLabels} respectPrefersColorScheme={themeRespectSystem} pendingUntilHydrated={true} />
       )}
       {links && links.map((link, i) => (
         <span key={link.href} className="flex items-center gap-hsp-xs">
@@ -221,7 +223,7 @@ function SidebarFooter({ links, themeDefaultMode }: { links?: SidebarLocaleLink[
   );
 }
 
-export function SidebarTree({ nodes, currentSlug, currentPath, rootMenuItems, backToMenuLabel, locale: localeProp, localeLinks, themeDefaultMode, dateFormats }: SidebarTreeProps) {
+export function SidebarTree({ nodes, currentSlug, currentPath, rootMenuItems, backToMenuLabel, locale: localeProp, localeLinks, themeDefaultMode, themeLabels, themeRespectSystem, dateFormats }: SidebarTreeProps) {
   const activeSlug = useActiveSlug(nodes, currentSlug, currentPath);
   const [query, setQuery] = useState("");
   const [showingRootMenu, setShowingRootMenu] = useState(false);
@@ -257,8 +259,8 @@ export function SidebarTree({ nodes, currentSlug, currentPath, rootMenuItems, ba
   );
 
   const footer = useMemo(
-    () => (localeLinks || themeDefaultMode) ? <SidebarFooter links={localeLinks} themeDefaultMode={themeDefaultMode} /> : null,
-    [localeLinks, themeDefaultMode],
+    () => (localeLinks || themeDefaultMode) ? <SidebarFooter links={localeLinks} themeDefaultMode={themeDefaultMode} themeLabels={themeLabels} themeRespectSystem={themeRespectSystem} /> : null,
+    [localeLinks, themeDefaultMode, themeLabels, themeRespectSystem],
   );
 
   const noteTrayRoot = nodes.length === 1 && nodes[0]?.shape === "note-tray" ? nodes[0] : undefined;

package/eject/theme-toggle/color-scheme-sync.ts

@@ -1,81 +1,126 @@
-// Shared color-scheme state helpers for ThemeToggle (#2012 E3).
-//
-// Two ThemeToggle instances can be mounted at once (header + mobile
-// sidebar footer). Each instance holds its own `mode` state, so a
-// toggle in one used to leave the other's icon stale — the instances
-// only read the DOM at mount. These helpers centralise the write path
-// (`applyColorScheme`) and give every instance a subscription point
-// (`subscribeColorSchemeChanged`) keyed on the `color-scheme-changed`
-// window event, which `applyColorScheme` dispatches after mutating the
-// DOM. The same event is already consumed by the zdtp design-token
-// panel, so the event name is a cross-package contract — do not rename.
-//
-// This module is intentionally NOT marked "use client": zfb's island
-// scanner registers every exported binding of a "use client" file as an
-// island, and these helpers are plain functions, not components. They
-// run in the browser only (called from the ThemeToggle island and
-// unit tests).
-
+// Browser color-scheme state shared by the pre-paint bootstrap and client islands.
+// The selected preference is distinct from the effective light/dark appearance.
 export type ColorSchemeMode = "light" | "dark";
+export type ThemePreference = ColorSchemeMode | "system";
 
 export const COLOR_SCHEME_CHANGED_EVENT = "color-scheme-changed";
+export const THEME_PREFERENCE_CHANGED_EVENT = "theme-preference-changed";
+export const COLOR_SCHEME_RUNTIME_GLOBAL = "__zudoDocColorScheme";
+export const COLOR_SCHEME_STORAGE_KEY = "zudo-doc-theme";
 
-const STORAGE_KEY = "zudo-doc-theme";
+export interface ColorSchemeRuntime {
+  // null means no valid persisted or live explicit choice.
+  choice: ThemePreference | null;
+  defaultMode: ColorSchemeMode;
+  respectPrefersColorScheme: boolean;
+  lastMode?: ColorSchemeMode;
+  cleanup?: () => void;
+}
 
-/**
- * Read the active color scheme from `<html data-theme>`. Falls back to
- * `defaultMode` when the attribute is missing or holds an unexpected
- * value (e.g. before the ColorSchemeProvider bootstrap script ran).
- */
-export function readColorSchemeFromDom(
+// Keep these pure functions self-contained: the provider serializes their JS
+// bodies into the inline pre-paint script, so both paths use identical rules.
+export function normalizeThemePreference(value: unknown): ThemePreference | null {
+  return value === "light" || value === "dark" || value === "system"
+    ? value
+    : null;
+}
+
+export function resolveThemePreference(
+  choice: ThemePreference | null,
   defaultMode: ColorSchemeMode,
+  respectPrefersColorScheme: boolean,
+): ThemePreference {
+  return choice ?? (respectPrefersColorScheme ? "system" : defaultMode);
+}
+
+export function resolveColorScheme(
+  preference: ThemePreference,
+  systemIsDark: boolean,
 ): ColorSchemeMode {
+  return preference === "system" ? (systemIsDark ? "dark" : "light") : preference;
+}
+
+function runtime(): ColorSchemeRuntime | null {
+  return ((window as unknown as Record<string, unknown>)[COLOR_SCHEME_RUNTIME_GLOBAL] ??
+    null) as ColorSchemeRuntime | null;
+}
+
+function readStorage(): ThemePreference | null {
+  try {
+    return normalizeThemePreference(localStorage.getItem(COLOR_SCHEME_STORAGE_KEY));
+  } catch {
+    return null;
+  }
+}
+
+function getRuntime(): ColorSchemeRuntime {
+  const existing = runtime();
+  if (existing) return existing;
+  const initial: ColorSchemeRuntime = {
+    choice: readStorage(),
+    defaultMode: "dark",
+    respectPrefersColorScheme: true,
+  };
+  (window as unknown as Record<string, unknown>)[COLOR_SCHEME_RUNTIME_GLOBAL] = initial;
+  return initial;
+}
+
+export function readThemePreference(
+  defaultMode: ColorSchemeMode = "dark",
+  respectPrefersColorScheme = true,
+): ThemePreference {
+  const state = runtime();
+  return resolveThemePreference(
+    state ? state.choice : readStorage(),
+    state?.defaultMode ?? defaultMode,
+    state?.respectPrefersColorScheme ?? respectPrefersColorScheme,
+  );
+}
+
+export function readColorSchemeFromDom(defaultMode: ColorSchemeMode): ColorSchemeMode {
   const actual = document.documentElement.getAttribute("data-theme");
   return actual === "light" || actual === "dark" ? actual : defaultMode;
 }
 
-/**
- * Apply `next` as the active color scheme: mutate the DOM, persist the
- * preference, and notify every subscriber (including other mounted
- * ThemeToggle instances and the zdtp design-token panel) via the
- * `color-scheme-changed` window event.
- *
- * Tweak-state reconciliation is intentionally NOT done here (#2037). The zdtp
- * panel owns its own storage lifecycle and current persisted-state contract;
- * its own `color-scheme-changed` listener clears applied inline
- * styles and re-seeds the color slice from the newly active scheme. An
- * earlier version of this function deleted `zudo-doc-tweak-state` + `-v2` on
- * every toggle, which (a) targeted stale keys after zdtp moved to v3 — so it
- * no longer did anything — and (b) when it did fire, wiped the whole envelope
- * including scheme-independent spacing/typography/size tweaks, contradicting
- * the documented carry-over guarantee. So the host no longer touches zdtp's
- * private storage keys.
- *
- * The design-token-panel bootstrap ALSO listens for this event and, on toggle,
- * destroys + reconfigures the panel with the new mode's mode-scoped semantic
- * DEFAULTS (see `design-token-panel-bootstrap.ts` + the host's
- * `buildDesignTokenPanelConfig`, #2610). That keeps the panel's per-mode
- * defaults faithful. Saved Color overrides are scheme- and mode-scoped:
- * the package-default builder declares separate Default Light / Default Dark
- * identities in panelSettings.colorMode, so an edit made in one mode does not
- * replace the other mode's default or saved mapping. Returning to a mode
- * restores that identity's saved choice. Palette, Spacing, Font, and Size
- * overrides remain shared across light/dark within the active theme pack.
- * The browser contract lives in e2e/theme-panel-persistence.spec.ts (#3980).
- * See zudo-doc#2037 / #2610.
- */
+/** Select a preference. Storage is best effort; the live choice survives errors. */
+export function applyThemePreference(next: ThemePreference): void {
+  const state = getRuntime();
+  const previousPreference = resolveThemePreference(
+    state.choice,
+    state.defaultMode,
+    state.respectPrefersColorScheme,
+  );
+  const previousMode = state.lastMode ?? document.documentElement.getAttribute("data-theme");
+  state.choice = next;
+  try {
+    localStorage.setItem(COLOR_SCHEME_STORAGE_KEY, next);
+  } catch {
+    // Private browsing or disabled storage must not block theme changes.
+  }
+  const systemIsDark = window.matchMedia?.("(prefers-color-scheme: dark)").matches ?? false;
+  const mode = resolveColorScheme(next, systemIsDark);
+  document.documentElement.setAttribute("data-theme", mode);
+  document.documentElement.style.colorScheme = mode;
+  state.lastMode = mode;
+  if (previousMode !== mode) {
+    window.dispatchEvent(new CustomEvent(COLOR_SCHEME_CHANGED_EVENT));
+  }
+  if (previousPreference !== next) {
+    window.dispatchEvent(new CustomEvent(THEME_PREFERENCE_CHANGED_EVENT));
+  }
+}
+
+/** Existing light/dark callers explicitly select the corresponding preference. */
 export function applyColorScheme(next: ColorSchemeMode): void {
-  document.documentElement.setAttribute("data-theme", next);
-  document.documentElement.style.colorScheme = next;
-  localStorage.setItem(STORAGE_KEY, next);
-  window.dispatchEvent(new CustomEvent(COLOR_SCHEME_CHANGED_EVENT));
+  applyThemePreference(next);
 }
 
-/**
- * Subscribe to color-scheme changes. Returns an unsubscribe function
- * (suitable as a `useEffect` cleanup).
- */
 export function subscribeColorSchemeChanged(listener: () => void): () => void {
   window.addEventListener(COLOR_SCHEME_CHANGED_EVENT, listener);
   return () => window.removeEventListener(COLOR_SCHEME_CHANGED_EVENT, listener);
 }
+
+export function subscribeThemePreferenceChanged(listener: () => void): () => void {
+  window.addEventListener(THEME_PREFERENCE_CHANGED_EVENT, listener);
+  return () => window.removeEventListener(THEME_PREFERENCE_CHANGED_EVENT, listener);
+}

package/eject/theme-toggle/index.tsx

@@ -2,127 +2,242 @@
 
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-// BARE (non-island-wrapped) theme toggle — the single ThemeToggle
-// implementation (#2012 E2). Published as the dedicated
-// `@takazudo/zudo-doc/theme-toggle` subpath so hosts can compose it
-// into their own `<Island>` wrappers (or nest it inside another island,
-// e.g. the mobile sidebar footer) without inheriting an extra island
-// layer. The island-wrapped variant for the `./theme` barrel lives in
-// `../theme/theme-toggle.tsx`, which wraps this component.
-//
-// Use the preact hook entrypoints directly — zfb's esbuild step does
-// not alias "react" to "preact/compat", so importing from "react" here
-// would fail to resolve.
-import { useState, useEffect } from "preact/hooks";
+import { useState, useEffect, useRef } from "preact/hooks";
+import { createPortal } from "preact/compat";
 import { useHydrationPending } from "./hydration-pending.js";
+import { AFTER_NAVIGATE_EVENT } from "../transitions/index.js";
 import {
-  applyColorScheme,
+  applyThemePreference,
   readColorSchemeFromDom,
+  readThemePreference,
   subscribeColorSchemeChanged,
+  subscribeThemePreferenceChanged,
   type ColorSchemeMode,
+  type ThemePreference,
 } from "./color-scheme-sync.js";
 
-function SunIcon() {
+const preferences: ThemePreference[] = ["light", "dark", "system"];
+let menuSequence = 0;
+
+function PreferenceIcon({ preference }: { preference: ThemePreference }) {
   return (
-    <svg
-      aria-hidden="true"
-      xmlns="http://www.w3.org/2000/svg"
-      width="20"
-      height="20"
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth="2"
-      strokeLinecap="round"
-      strokeLinejoin="round"
-    >
-      <circle cx="12" cy="12" r="5" />
-      <line x1="12" y1="1" x2="12" y2="3" />
-      <line x1="12" y1="21" x2="12" y2="23" />
-      <line x1="4.22" y1="4.22" x2="5.64" y2="5.64" />
-      <line x1="18.36" y1="18.36" x2="19.78" y2="19.78" />
-      <line x1="1" y1="12" x2="3" y2="12" />
-      <line x1="21" y1="12" x2="23" y2="12" />
-      <line x1="4.22" y1="19.78" x2="5.64" y2="18.36" />
-      <line x1="18.36" y1="5.64" x2="19.78" y2="4.22" />
+    <svg aria-hidden="true" xmlns="http://www.w3.org/2000/svg" width="20" height="20"
+      viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.2"
+      strokeLinecap="square" strokeLinejoin="miter">
+      {preference === "light" ? (
+        <><circle cx="12" cy="12" r="3.6" /><path d="M12 2.5V6M12 18V21.5M2.5 12H6M18 12H21.5M5.3 5.3L7.8 7.8M16.2 16.2L18.7 18.7M5.3 18.7L7.8 16.2M16.2 7.8L18.7 5.3" /></>
+      ) : preference === "dark" ? (
+        <path d="M10.2 2.9C5.7 3.9 2.6 7.9 3 12.6C3.4 17.7 7.9 21.5 13 21.1C16.9 20.7 20.1 17.9 21 14.1C18.6 15.7 15.6 15.8 13.2 14.3C9.3 12 8 6.8 10.2 2.9Z" />
+      ) : (
+        <path d="M2.5 3.5H21.5V16.5H2.5ZM12 16.5V20.5M7.5 20.5H16.5" />
+      )}
     </svg>
   );
 }
 
-function MoonIcon() {
-  return (
-    <svg
-      aria-hidden="true"
-      xmlns="http://www.w3.org/2000/svg"
-      width="20"
-      height="20"
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth="2"
-      strokeLinecap="round"
-      strokeLinejoin="round"
-    >
-      <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
-    </svg>
-  );
+export interface ThemeToggleLabels {
+  appearance: string;
+  light: string;
+  dark: string;
+  system: string;
+  systemHelper: string;
 }
 
+const englishLabels: ThemeToggleLabels = {
+  appearance: "Appearance",
+  light: "Light",
+  dark: "Dark",
+  system: "System",
+  systemHelper: "Follows device · currently {mode}",
+};
+
 export interface ThemeToggleProps {
   defaultMode?: ColorSchemeMode;
+  respectPrefersColorScheme?: boolean;
+  labels?: ThemeToggleLabels;
   /** Keep activation pending until the first successful mount. @default true */
   pendingUntilHydrated?: boolean;
 }
 
-// NAMED export (not default) on purpose: tsup compiles a default export
-// to `export { ThemeToggle as default }`, an alias shape zfb's island
-// scanner does not recognize — the island then never registers and the
-// header toggle ships dead (zero hydration). Named exports compile to
-// `export { ThemeToggle }`, which the scanner handles (same pattern as
-// the package's MobileToc island).
+// Keep the named export: zfb's island scanner keys on the ThemeToggle name.
 export function ThemeToggle({
   defaultMode = "dark",
+  respectPrefersColorScheme = true,
+  labels = englishLabels,
   pendingUntilHydrated = true,
 }: ThemeToggleProps) {
   const pending = useHydrationPending(pendingUntilHydrated);
-  // Initial state must match server render to avoid hydration mismatch.
-  // Actual theme is synced from DOM in useEffect below.
-  const [mode, setMode] = useState<ColorSchemeMode>(defaultMode);
+  // The menu exists only after a client interaction; allocate across island roots.
+  const menuId = useRef("");
+  const ensureMenuId = () => {
+    if (!menuId.current) menuId.current = `zd-appearance-${++menuSequence}`;
+  };
+  const rootRef = useRef<HTMLDivElement>(null);
+  const menuRef = useRef<HTMLDivElement>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const itemRefs = useRef<Array<HTMLButtonElement | null>>([]);
+  const restoreFocusRef = useRef(false);
+  const [preference, setPreference] = useState<ThemePreference>(
+    respectPrefersColorScheme ? "system" : defaultMode,
+  );
+  const [resolved, setResolved] = useState<ColorSchemeMode>(defaultMode);
+  const [open, setOpen] = useState(false);
+  const [activeIndex, setActiveIndex] = useState(0);
+  const [placement, setPlacement] = useState<{ left: number; top: number; width: number; maxHeight: number } | null>(null);
 
   useEffect(() => {
-    const sync = () => setMode(readColorSchemeFromDom(defaultMode));
+    const sync = () => {
+      setPreference(readThemePreference(defaultMode, respectPrefersColorScheme));
+      setResolved(readColorSchemeFromDom(defaultMode));
+    };
     sync();
-    // Cross-instance sync (#2012 E3): every mounted toggle re-reads the
-    // DOM whenever any instance (or the zdtp panel) applies a scheme,
-    // so the header toggle and the sidebar-footer toggle never disagree.
-    return subscribeColorSchemeChanged(sync);
-  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+    const unsubscribePreference = subscribeThemePreferenceChanged(() => {
+      sync();
+      setOpen(false);
+    });
+    const unsubscribeScheme = subscribeColorSchemeChanged(sync);
+    return () => {
+      unsubscribePreference();
+      unsubscribeScheme();
+    };
+  }, [defaultMode, respectPrefersColorScheme]);
 
-  function toggle() {
-    if (pending) return;
-    const next = mode === "dark" ? "light" : "dark";
-    setMode(next);
-    applyColorScheme(next);
-  }
+  useEffect(() => {
+    if (!open) return;
+    // A portaled menu still sits below the third-party token panel's very high
+    // stacking tier. The native popover top layer keeps it actionable while
+    // that panel is open, without competing with the host's z-index scale.
+    const menu = menuRef.current;
+    menu?.showPopover?.();
+    const position = () => {
+      const rect = triggerRef.current?.getBoundingClientRect();
+      if (!rect) return;
+      const gap = 8;
+      const width = Math.min(260, window.innerWidth - gap * 2);
+      // Measure after the popover enters the top layer. A fixed guess clips
+      // the System helper once the option rows meet the 44px touch target.
+      const desiredHeight = menu?.scrollHeight ?? 280;
+      const roomBelow = window.innerHeight - rect.bottom - gap * 2;
+      const roomAbove = rect.top - gap * 2;
+      const above = roomBelow < desiredHeight && roomAbove > roomBelow;
+      const maxHeight = Math.max(80, Math.min(desiredHeight, above ? roomAbove : roomBelow));
+      setPlacement({
+        left: Math.max(gap, Math.min(rect.right - width, window.innerWidth - width - gap)),
+        top: above ? Math.max(gap, rect.top - gap - maxHeight) : rect.bottom + gap,
+        width,
+        maxHeight,
+      });
+    };
+    const onPointerDown = (event: PointerEvent) => {
+      if (
+        !rootRef.current?.contains(event.target as Node) &&
+        !menuRef.current?.contains(event.target as Node)
+      ) setOpen(false);
+    };
+    const onNavigate = () => setOpen(false);
+    position();
+    document.addEventListener("pointerdown", onPointerDown);
+    window.addEventListener("resize", position);
+    window.addEventListener("scroll", position, true);
+    document.addEventListener(AFTER_NAVIGATE_EVENT, onNavigate);
+    return () => {
+      if (menu?.hidePopover && menu.matches(":popover-open")) menu.hidePopover();
+      document.removeEventListener("pointerdown", onPointerDown);
+      window.removeEventListener("resize", position);
+      window.removeEventListener("scroll", position, true);
+      document.removeEventListener(AFTER_NAVIGATE_EVENT, onNavigate);
+    };
+  }, [open]); // activeIndex is set before opening; arrow movement focuses directly.
+
+  useEffect(() => {
+    if (open && placement) itemRefs.current[activeIndex]?.focus();
+  }, [open, placement]); // Focus once the portaled menu is visible.
+
+  useEffect(() => {
+    if (open || !restoreFocusRef.current) return;
+    restoreFocusRef.current = false;
+    requestAnimationFrame(() => triggerRef.current?.focus());
+  }, [open]);
 
-  const nextMode = mode === "dark" ? "light" : "dark";
+  const close = (restoreFocus = false) => {
+    restoreFocusRef.current = restoreFocus;
+    setOpen(false);
+  };
+  const select = (next: ThemePreference) => {
+    close(true);
+    applyThemePreference(next);
+    setPreference(next);
+    setResolved(readColorSchemeFromDom(defaultMode));
+  };
+  const move = (index: number) => {
+    const next = (index + preferences.length) % preferences.length;
+    setActiveIndex(next);
+    itemRefs.current[next]?.focus();
+  };
+  const onMenuKeyDown = (event: KeyboardEvent) => {
+    if (event.key === "Escape") {
+      event.preventDefault();
+      close(true);
+    } else if (event.key === "Tab") {
+      // Let the browser move focus before unmounting the focused menu item.
+      window.setTimeout(() => close(), 0);
+    } else if (event.key === "ArrowDown") {
+      event.preventDefault();
+      move(activeIndex + 1);
+    } else if (event.key === "ArrowUp") {
+      event.preventDefault();
+      move(activeIndex - 1);
+    } else if (event.key === "Home") {
+      event.preventDefault();
+      move(0);
+    } else if (event.key === "End") {
+      event.preventDefault();
+      move(2);
+    }
+  };
 
   return (
-    <button
-      onClick={toggle}
-      aria-label={`Switch to ${nextMode} mode`}
-      aria-disabled={pending ? "true" : undefined}
-      data-zd-pending={pending ? "" : undefined}
-      className="text-muted hover:text-fg transition-colors p-hsp-sm focus-visible:outline-2 focus-visible:outline-accent focus-visible:outline-offset-2"
-    >
-      {mode === "dark" ? <SunIcon /> : <MoonIcon />}
-    </button>
+    <div ref={rootRef} className="relative inline-flex" data-zd-theme-menu="">
+      <button ref={triggerRef} type="button" aria-haspopup="menu" aria-expanded={open}
+        aria-controls={open ? menuId.current : undefined}
+        aria-label={`${labels.appearance}: ${labels[preference]}`}
+        aria-disabled={pending ? "true" : undefined}
+        data-zd-pending={pending ? "" : undefined}
+        onClick={() => {
+          if (pending) return;
+          if (open) close(true);
+          else { setPlacement(null); ensureMenuId(); setActiveIndex(preferences.indexOf(preference)); setOpen(true); }
+        }}
+        onKeyDown={(event) => {
+          if (pending) { if (event.key === "Enter" || event.key === " ") event.preventDefault(); return; }
+          if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+            event.preventDefault(); setPlacement(null); ensureMenuId(); setActiveIndex(event.key === "ArrowDown" ? 0 : 2); setOpen(true);
+          } else if (event.key === "Escape" && open) { event.preventDefault(); close(true); }
+        }}
+        className="inline-flex h-[40px] w-[40px] shrink-0 items-center justify-center text-muted hover:text-fg focus-visible:outline-2 focus-visible:outline-accent focus-visible:outline-offset-2"
+      ><PreferenceIcon preference={preference} /></button>
+      {open && createPortal(<div ref={menuRef} id={menuId.current} role="menu" aria-label={labels.appearance}
+        popover={typeof HTMLElement !== "undefined" && "showPopover" in HTMLElement.prototype ? "manual" : undefined}
+        onKeyDown={onMenuKeyDown}
+        className="fixed z-tooltip overflow-y-auto rounded-lg border border-muted bg-surface p-hsp-xs text-fg shadow-lg"
+        style={placement ? { left: placement.left, top: placement.top, right: "auto", bottom: "auto", margin: 0, width: placement.width, maxHeight: placement.maxHeight } : { visibility: "hidden", left: 0, top: 0, right: "auto", bottom: "auto", margin: 0, width: Math.min(260, window.innerWidth - 16) }}>
+        <div className="px-hsp-sm py-vsp-xs text-small font-semibold" aria-hidden="true">{labels.appearance}</div>
+        {preferences.map((option, index) => (
+          <button key={option} ref={(node) => { itemRefs.current[index] = node; }} type="button"
+            role="menuitemradio" aria-checked={preference === option}
+            onFocus={() => setActiveIndex(index)} onClick={() => select(option)}
+            className={`flex min-h-[44px] w-full items-center gap-hsp-sm rounded px-hsp-sm text-left text-small ${preference === option ? "bg-accent/10" : ""} hover:bg-accent/10 focus-visible:bg-accent/10 focus-visible:outline-2 focus-visible:outline-accent`}
+          >
+            <PreferenceIcon preference={option} />
+            <span className="flex-1">{labels[option]}</span>
+            <span aria-hidden="true" className="text-accent">{preference === option ? "✓" : ""}</span>
+          </button>
+        ))}
+        <div className="px-hsp-sm py-vsp-xs text-small text-muted">
+          {labels.systemHelper.replace("{mode}", labels[resolved])}
+        </div>
+      </div>, document.body)}
+    </div>
   );
 }
-// Pin the island marker name to "ThemeToggle" regardless of bundler
-// identifier mangling: zfb's Island() derives the SSR marker via
-// `displayName ?? name`, and esbuild may rename the function when
-// another binding shares the name in the same bundle. Setting
-// displayName explicitly keeps the emitted marker aligned with the
-// island-manifest entry. zudolab/zudo-doc#1446.
 ThemeToggle.displayName = "ThemeToggle";

package/eject/theme-toggle/labels.ts

@@ -0,0 +1,15 @@
+import type { ThemeToggleLabels } from "./index.js";
+
+/** Resolve labels before island serialization so host translation overrides apply. */
+export function themeToggleLabels(
+  t: (key: string, locale: string) => string,
+  locale: string,
+): ThemeToggleLabels {
+  return {
+    appearance: t("appearance.title", locale),
+    light: t("appearance.light", locale),
+    dark: t("appearance.dark", locale),
+    system: t("appearance.system", locale),
+    systemHelper: t("appearance.systemHelper", locale),
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zudo-doc",
-  "version": "5.26.5",
+  "version": "5.27.0",
   "type": "module",
   "description": "zudo-doc framework primitives layer that sits on top of zfb's engine — sidebar, theme, TOC, breadcrumb, layouts, head injection, View Transitions, SSR-skip wrappers (per ADR-003).",
   "license": "MIT",
@@ -717,9 +717,9 @@
   ],
   "peerDependencies": {
     "@takazudo/zdtp": "^0.5.2 || ^0.6.0 || ^0.7.0 || ^0.8.0",
-    "@takazudo/zfb": "^2.20.1",
-    "@takazudo/zfb-md-wasm": "^2.20.1",
-    "@takazudo/zfb-runtime": "^2.20.1",
+    "@takazudo/zfb": "^2.20.2",
+    "@takazudo/zfb-md-wasm": "^2.20.2",
+    "@takazudo/zfb-runtime": "^2.20.2",
     "@takazudo/zudo-doc-history-server": "^5.17.2",
     "diff": "^8.0.0",
     "katex": "^0.16.0",
@@ -757,9 +757,9 @@
   },
   "devDependencies": {
     "@takazudo/mdx-formatter": "1.3.0-next.4",
-    "@takazudo/zfb": "2.20.1",
-    "@takazudo/zfb-md-wasm": "2.20.1",
-    "@takazudo/zfb-runtime": "2.20.1",
+    "@takazudo/zfb": "2.20.2",
+    "@takazudo/zfb-md-wasm": "2.20.2",
+    "@takazudo/zfb-runtime": "2.20.2",
     "@types/fs-extra": "^11.0.4",
     "@types/minimist": "^1.2.5",
     "@types/node": "^25.3.5",
@@ -771,7 +771,7 @@
     "typescript": "^5.0.0",
     "vitest": "^4.1.0",
     "zod": "^4.3.6",
-    "@takazudo/zudo-doc-history-server": "5.26.5"
+    "@takazudo/zudo-doc-history-server": "5.27.0"
   },
   "scripts": {
     "gen:search-widget-script": "node scripts/gen-search-widget-script.mjs",