@takazudo/zudo-doc 5.26.4 → 5.27.0

package/eject/header/header.tsx

@@ -294,6 +294,49 @@ export function Header(props: HeaderProps): JSX.Element {
 
   const activeNavPath = computeActiveNavPath(headerNav, matchPath);
   const rightItemDispatch = createRightItemDispatch(headerRightComponents);
+  const rightItems = headerRightItems
+    .map((item, i) => ({
+      item,
+      node: renderRightItem(
+        item,
+        i,
+        {
+          lang,
+          githubRepoUrl,
+          githubLabel,
+          themeToggle,
+          languageSwitcher,
+          versionSwitcher,
+          search,
+          colorModeEnabled,
+          hasLocales,
+        },
+        rightItemDispatch,
+      ),
+    }))
+    .filter((entry): entry is typeof entry & { node: VNode } => entry.node !== null);
+  const rightGroups: VNode[] = [];
+  let iconGroup: VNode[] = [];
+
+  const flushIconGroup = () => {
+    if (iconGroup.length === 0) return;
+    rightGroups.push(
+      <div class="flex items-center" data-header-icon-group>
+        {iconGroup}
+      </div>,
+    );
+    iconGroup = [];
+  };
+
+  for (const { item, node } of rightItems) {
+    if (isHeaderIconItem(item)) {
+      iconGroup.push(node);
+    } else {
+      flushIconGroup();
+      rightGroups.push(node);
+    }
+  }
+  flushIconGroup();
 
   return (
     <header
@@ -412,22 +455,7 @@ export function Header(props: HeaderProps): JSX.Element {
         class="ml-auto flex shrink-0 items-center gap-x-hsp-md"
         data-header-right
       >
-        {headerRightItems.map((item, i) => renderRightItem(
-          item,
-          i,
-          {
-            lang,
-            githubRepoUrl,
-            githubLabel,
-            themeToggle,
-            languageSwitcher,
-            versionSwitcher,
-            search,
-            colorModeEnabled,
-            hasLocales,
-          },
-          rightItemDispatch,
-        ))}
+        {rightGroups}
       </div>
 
       <script dangerouslySetInnerHTML={{ __html: NAV_OVERFLOW_SCRIPT }} />
@@ -592,6 +620,13 @@ function stripCurrentVersionPrefix(path: string, currentVersion?: string): strin
 
 type RightItemContext = Omit<HeaderRightComponentProps, "item" | "index">;
 
+function isHeaderIconItem(item: HeaderRightItem): boolean {
+  if (item.type === "trigger") return true;
+  if (item.type === "link") return item.icon === "github";
+  if (item.type !== "component") return false;
+  return ["github-link", "theme-toggle", "search"].includes(item.component);
+}
+
 /**
  * Shared trigger-button shell for header-right items that dispatch a
  * CustomEvent on click. The legacy template used an inline `onclick`
@@ -620,7 +655,7 @@ function TriggerButton({
       key={`right-${index}`}
       id={id}
       type="button"
-      class="flex items-center justify-center text-muted transition-colors hover:text-fg"
+      class="flex h-[40px] w-[40px] shrink-0 items-center justify-center text-muted transition-colors hover:text-fg focus-visible:outline-2 focus-visible:outline-accent focus-visible:outline-offset-2"
       aria-label={ariaLabel}
       {...inlineOnclick}
     >
@@ -730,7 +765,7 @@ const BASE_RIGHT_ITEM_DISPATCH: Readonly<Record<string, RightItemHandler>> = {
         href={ctx.githubRepoUrl}
         target="_blank"
         rel="noopener noreferrer"
-        class="flex items-center justify-center text-muted transition-colors hover:text-fg"
+        class="flex h-[40px] w-[40px] shrink-0 items-center justify-center text-muted transition-colors hover:text-fg focus-visible:outline-2 focus-visible:outline-accent focus-visible:outline-offset-2"
         aria-label={ctx.githubLabel}
         title={ctx.githubLabel}
       >
@@ -782,7 +817,9 @@ const BASE_RIGHT_ITEM_DISPATCH: Readonly<Record<string, RightItemHandler>> = {
         href={item.href}
         target={isExternal ? "_blank" : undefined}
         rel={isExternal ? "noopener noreferrer" : undefined}
-        class="flex items-center justify-center text-muted transition-colors hover:text-fg"
+        class={item.icon === "github"
+          ? "flex h-[40px] w-[40px] shrink-0 items-center justify-center text-muted transition-colors hover:text-fg focus-visible:outline-2 focus-visible:outline-accent focus-visible:outline-offset-2"
+          : "flex items-center justify-center text-muted transition-colors hover:text-fg"}
         aria-label={item.ariaLabel}
         title={label}
       >

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

@@ -14,6 +14,7 @@ import { useState, useEffect, useRef } from "preact/hooks";
 // collapse into duplicate import statements in an ejected copy.
 import { AFTER_NAVIGATE_EVENT, ensureNestedIslandPropsRefresh } from "../transitions/index.js";
 import { SidebarTree } from "../sidebar-tree-island/index.js";
+import type { ThemeToggleLabels } from "../theme-toggle/index.js";
 import type { SidebarNavNode, SidebarRootMenuItem, SidebarLocaleLink } from "../sidebar/types.js";
 import type { ResolvedDateFormats } from "../settings.js";
 
@@ -57,6 +58,8 @@ export interface SidebarToggleProps {
   locale?: string;
   localeLinks?: SidebarLocaleLink[];
   themeDefaultMode?: "light" | "dark";
+  themeLabels?: ThemeToggleLabels;
+  themeRespectSystem?: boolean;
   /**
    * Forwarded verbatim to the hosted `<SidebarTree>`. This island is the one
    * nested under the persisted `<header>`, so on a same-locale soft navigation
@@ -79,6 +82,8 @@ export function SidebarToggle({
   locale,
   localeLinks,
   themeDefaultMode,
+  themeLabels,
+  themeRespectSystem,
   dateFormats,
 }: SidebarToggleProps) {
   // Initial state must match SSR (`open=false`) so the hydration DOM
@@ -255,6 +260,8 @@ export function SidebarToggle({
             locale={locale}
             localeLinks={localeLinks}
             themeDefaultMode={themeDefaultMode}
+            themeLabels={themeLabels}
+            themeRespectSystem={themeRespectSystem}
             dateFormats={dateFormats}
           />
         </div>

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