@takazudo/zudo-doc 5.26.5 → 5.27.0

package/dist/theme-toggle/color-scheme-sync.d.ts

@@ -1,44 +1,24 @@
 export type ColorSchemeMode = "light" | "dark";
+export type ThemePreference = ColorSchemeMode | "system";
 export declare const COLOR_SCHEME_CHANGED_EVENT = "color-scheme-changed";
-/**
- * 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 declare const THEME_PREFERENCE_CHANGED_EVENT = "theme-preference-changed";
+export declare const COLOR_SCHEME_RUNTIME_GLOBAL = "__zudoDocColorScheme";
+export declare const COLOR_SCHEME_STORAGE_KEY = "zudo-doc-theme";
+export interface ColorSchemeRuntime {
+    choice: ThemePreference | null;
+    defaultMode: ColorSchemeMode;
+    respectPrefersColorScheme: boolean;
+    lastMode?: ColorSchemeMode;
+    cleanup?: () => void;
+}
+export declare function normalizeThemePreference(value: unknown): ThemePreference | null;
+export declare function resolveThemePreference(choice: ThemePreference | null, defaultMode: ColorSchemeMode, respectPrefersColorScheme: boolean): ThemePreference;
+export declare function resolveColorScheme(preference: ThemePreference, systemIsDark: boolean): ColorSchemeMode;
+export declare function readThemePreference(defaultMode?: ColorSchemeMode, respectPrefersColorScheme?: boolean): ThemePreference;
 export declare function readColorSchemeFromDom(defaultMode: ColorSchemeMode): ColorSchemeMode;
-/**
- * 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 declare function applyThemePreference(next: ThemePreference): void;
+/** Existing light/dark callers explicitly select the corresponding preference. */
 export declare function applyColorScheme(next: ColorSchemeMode): void;
-/**
- * Subscribe to color-scheme changes. Returns an unsubscribe function
- * (suitable as a `useEffect` cleanup).
- */
 export declare function subscribeColorSchemeChanged(listener: () => void): () => void;
+export declare function subscribeThemePreferenceChanged(listener: () => void): () => void;

package/dist/theme-toggle/color-scheme-sync.js

@@ -1,22 +1,97 @@
 const COLOR_SCHEME_CHANGED_EVENT = "color-scheme-changed";
-const STORAGE_KEY = "zudo-doc-theme";
+const THEME_PREFERENCE_CHANGED_EVENT = "theme-preference-changed";
+const COLOR_SCHEME_RUNTIME_GLOBAL = "__zudoDocColorScheme";
+const COLOR_SCHEME_STORAGE_KEY = "zudo-doc-theme";
+function normalizeThemePreference(value) {
+  return value === "light" || value === "dark" || value === "system" ? value : null;
+}
+function resolveThemePreference(choice, defaultMode, respectPrefersColorScheme) {
+  return choice ?? (respectPrefersColorScheme ? "system" : defaultMode);
+}
+function resolveColorScheme(preference, systemIsDark) {
+  return preference === "system" ? systemIsDark ? "dark" : "light" : preference;
+}
+function runtime() {
+  return window[COLOR_SCHEME_RUNTIME_GLOBAL] ?? null;
+}
+function readStorage() {
+  try {
+    return normalizeThemePreference(localStorage.getItem(COLOR_SCHEME_STORAGE_KEY));
+  } catch {
+    return null;
+  }
+}
+function getRuntime() {
+  const existing = runtime();
+  if (existing) return existing;
+  const initial = {
+    choice: readStorage(),
+    defaultMode: "dark",
+    respectPrefersColorScheme: true
+  };
+  window[COLOR_SCHEME_RUNTIME_GLOBAL] = initial;
+  return initial;
+}
+function readThemePreference(defaultMode = "dark", respectPrefersColorScheme = true) {
+  const state = runtime();
+  return resolveThemePreference(
+    state ? state.choice : readStorage(),
+    state?.defaultMode ?? defaultMode,
+    state?.respectPrefersColorScheme ?? respectPrefersColorScheme
+  );
+}
 function readColorSchemeFromDom(defaultMode) {
   const actual = document.documentElement.getAttribute("data-theme");
   return actual === "light" || actual === "dark" ? actual : defaultMode;
 }
+function applyThemePreference(next) {
+  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 {
+  }
+  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));
+  }
+}
 function applyColorScheme(next) {
-  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);
 }
 function subscribeColorSchemeChanged(listener) {
   window.addEventListener(COLOR_SCHEME_CHANGED_EVENT, listener);
   return () => window.removeEventListener(COLOR_SCHEME_CHANGED_EVENT, listener);
 }
+function subscribeThemePreferenceChanged(listener) {
+  window.addEventListener(THEME_PREFERENCE_CHANGED_EVENT, listener);
+  return () => window.removeEventListener(THEME_PREFERENCE_CHANGED_EVENT, listener);
+}
 export {
   COLOR_SCHEME_CHANGED_EVENT,
+  COLOR_SCHEME_RUNTIME_GLOBAL,
+  COLOR_SCHEME_STORAGE_KEY,
+  THEME_PREFERENCE_CHANGED_EVENT,
   applyColorScheme,
+  applyThemePreference,
+  normalizeThemePreference,
   readColorSchemeFromDom,
-  subscribeColorSchemeChanged
+  readThemePreference,
+  resolveColorScheme,
+  resolveThemePreference,
+  subscribeColorSchemeChanged,
+  subscribeThemePreferenceChanged
 };

package/dist/theme-toggle/index.d.ts

@@ -1,10 +1,19 @@
 import { type ColorSchemeMode } from "./color-scheme-sync.js";
+export interface ThemeToggleLabels {
+    appearance: string;
+    light: string;
+    dark: string;
+    system: string;
+    systemHelper: string;
+}
 export interface ThemeToggleProps {
     defaultMode?: ColorSchemeMode;
+    respectPrefersColorScheme?: boolean;
+    labels?: ThemeToggleLabels;
     /** Keep activation pending until the first successful mount. @default true */
     pendingUntilHydrated?: boolean;
 }
-export declare function ThemeToggle({ defaultMode, pendingUntilHydrated, }: ThemeToggleProps): import("preact").JSX.Element;
+export declare function ThemeToggle({ defaultMode, respectPrefersColorScheme, labels, pendingUntilHydrated, }: ThemeToggleProps): import("preact").JSX.Element;
 export declare namespace ThemeToggle {
     var displayName: string;
 }

package/dist/theme-toggle/index.js

@@ -1,41 +1,19 @@
 "use client";
-import { jsx, jsxs } from "preact/jsx-runtime";
-import { useState, useEffect } from "preact/hooks";
+import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
+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,
-  subscribeColorSchemeChanged
+  readThemePreference,
+  subscribeColorSchemeChanged,
+  subscribeThemePreferenceChanged
 } from "./color-scheme-sync.js";
-function SunIcon() {
-  return /* @__PURE__ */ jsxs(
-    "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",
-      children: [
-        /* @__PURE__ */ jsx("circle", { cx: "12", cy: "12", r: "5" }),
-        /* @__PURE__ */ jsx("line", { x1: "12", y1: "1", x2: "12", y2: "3" }),
-        /* @__PURE__ */ jsx("line", { x1: "12", y1: "21", x2: "12", y2: "23" }),
-        /* @__PURE__ */ jsx("line", { x1: "4.22", y1: "4.22", x2: "5.64", y2: "5.64" }),
-        /* @__PURE__ */ jsx("line", { x1: "18.36", y1: "18.36", x2: "19.78", y2: "19.78" }),
-        /* @__PURE__ */ jsx("line", { x1: "1", y1: "12", x2: "3", y2: "12" }),
-        /* @__PURE__ */ jsx("line", { x1: "21", y1: "12", x2: "23", y2: "12" }),
-        /* @__PURE__ */ jsx("line", { x1: "4.22", y1: "19.78", x2: "5.64", y2: "18.36" }),
-        /* @__PURE__ */ jsx("line", { x1: "18.36", y1: "5.64", x2: "19.78", y2: "4.22" })
-      ]
-    }
-  );
-}
-function MoonIcon() {
+const preferences = ["light", "dark", "system"];
+let menuSequence = 0;
+function PreferenceIcon({ preference }) {
   return /* @__PURE__ */ jsx(
     "svg",
     {
@@ -46,42 +24,223 @@ function MoonIcon() {
       viewBox: "0 0 24 24",
       fill: "none",
       stroke: "currentColor",
-      strokeWidth: "2",
-      strokeLinecap: "round",
-      strokeLinejoin: "round",
-      children: /* @__PURE__ */ jsx("path", { d: "M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" })
+      strokeWidth: "1.2",
+      strokeLinecap: "square",
+      strokeLinejoin: "miter",
+      children: preference === "light" ? /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx("circle", { cx: "12", cy: "12", r: "3.6" }),
+        /* @__PURE__ */ jsx("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" ? /* @__PURE__ */ jsx("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" }) : /* @__PURE__ */ jsx("path", { d: "M2.5 3.5H21.5V16.5H2.5ZM12 16.5V20.5M7.5 20.5H16.5" })
     }
   );
 }
+const englishLabels = {
+  appearance: "Appearance",
+  light: "Light",
+  dark: "Dark",
+  system: "System",
+  systemHelper: "Follows device \xB7 currently {mode}"
+};
 function ThemeToggle({
   defaultMode = "dark",
+  respectPrefersColorScheme = true,
+  labels = englishLabels,
   pendingUntilHydrated = true
 }) {
   const pending = useHydrationPending(pendingUntilHydrated);
-  const [mode, setMode] = useState(defaultMode);
+  const menuId = useRef("");
+  const ensureMenuId = () => {
+    if (!menuId.current) menuId.current = `zd-appearance-${++menuSequence}`;
+  };
+  const rootRef = useRef(null);
+  const menuRef = useRef(null);
+  const triggerRef = useRef(null);
+  const itemRefs = useRef([]);
+  const restoreFocusRef = useRef(false);
+  const [preference, setPreference] = useState(
+    respectPrefersColorScheme ? "system" : defaultMode
+  );
+  const [resolved, setResolved] = useState(defaultMode);
+  const [open, setOpen] = useState(false);
+  const [activeIndex, setActiveIndex] = useState(0);
+  const [placement, setPlacement] = useState(null);
   useEffect(() => {
-    const sync = () => setMode(readColorSchemeFromDom(defaultMode));
+    const sync = () => {
+      setPreference(readThemePreference(defaultMode, respectPrefersColorScheme));
+      setResolved(readColorSchemeFromDom(defaultMode));
+    };
     sync();
-    return subscribeColorSchemeChanged(sync);
-  }, []);
-  function toggle() {
-    if (pending) return;
-    const next = mode === "dark" ? "light" : "dark";
-    setMode(next);
-    applyColorScheme(next);
-  }
-  const nextMode = mode === "dark" ? "light" : "dark";
-  return /* @__PURE__ */ jsx(
-    "button",
-    {
-      onClick: toggle,
-      "aria-label": `Switch to ${nextMode} mode`,
-      "aria-disabled": pending ? "true" : void 0,
-      "data-zd-pending": pending ? "" : void 0,
-      className: "text-muted hover:text-fg transition-colors p-hsp-sm focus-visible:outline-2 focus-visible:outline-accent focus-visible:outline-offset-2",
-      children: mode === "dark" ? /* @__PURE__ */ jsx(SunIcon, {}) : /* @__PURE__ */ jsx(MoonIcon, {})
+    const unsubscribePreference = subscribeThemePreferenceChanged(() => {
+      sync();
+      setOpen(false);
+    });
+    const unsubscribeScheme = subscribeColorSchemeChanged(sync);
+    return () => {
+      unsubscribePreference();
+      unsubscribeScheme();
+    };
+  }, [defaultMode, respectPrefersColorScheme]);
+  useEffect(() => {
+    if (!open) return;
+    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);
+      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) => {
+      if (!rootRef.current?.contains(event.target) && !menuRef.current?.contains(event.target)) 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]);
+  useEffect(() => {
+    if (open && placement) itemRefs.current[activeIndex]?.focus();
+  }, [open, placement]);
+  useEffect(() => {
+    if (open || !restoreFocusRef.current) return;
+    restoreFocusRef.current = false;
+    requestAnimationFrame(() => triggerRef.current?.focus());
+  }, [open]);
+  const close = (restoreFocus = false) => {
+    restoreFocusRef.current = restoreFocus;
+    setOpen(false);
+  };
+  const select = (next) => {
+    close(true);
+    applyThemePreference(next);
+    setPreference(next);
+    setResolved(readColorSchemeFromDom(defaultMode));
+  };
+  const move = (index) => {
+    const next = (index + preferences.length) % preferences.length;
+    setActiveIndex(next);
+    itemRefs.current[next]?.focus();
+  };
+  const onMenuKeyDown = (event) => {
+    if (event.key === "Escape") {
+      event.preventDefault();
+      close(true);
+    } else if (event.key === "Tab") {
+      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 /* @__PURE__ */ jsxs("div", { ref: rootRef, className: "relative inline-flex", "data-zd-theme-menu": "", children: [
+    /* @__PURE__ */ jsx(
+      "button",
+      {
+        ref: triggerRef,
+        type: "button",
+        "aria-haspopup": "menu",
+        "aria-expanded": open,
+        "aria-controls": open ? menuId.current : void 0,
+        "aria-label": `${labels.appearance}: ${labels[preference]}`,
+        "aria-disabled": pending ? "true" : void 0,
+        "data-zd-pending": pending ? "" : void 0,
+        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",
+        children: /* @__PURE__ */ jsx(PreferenceIcon, { preference })
+      }
+    ),
+    open && createPortal(/* @__PURE__ */ jsxs(
+      "div",
+      {
+        ref: menuRef,
+        id: menuId.current,
+        role: "menu",
+        "aria-label": labels.appearance,
+        popover: typeof HTMLElement !== "undefined" && "showPopover" in HTMLElement.prototype ? "manual" : void 0,
+        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) },
+        children: [
+          /* @__PURE__ */ jsx("div", { className: "px-hsp-sm py-vsp-xs text-small font-semibold", "aria-hidden": "true", children: labels.appearance }),
+          preferences.map((option, index) => /* @__PURE__ */ jsxs(
+            "button",
+            {
+              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`,
+              children: [
+                /* @__PURE__ */ jsx(PreferenceIcon, { preference: option }),
+                /* @__PURE__ */ jsx("span", { className: "flex-1", children: labels[option] }),
+                /* @__PURE__ */ jsx("span", { "aria-hidden": "true", className: "text-accent", children: preference === option ? "\u2713" : "" })
+              ]
+            },
+            option
+          )),
+          /* @__PURE__ */ jsx("div", { className: "px-hsp-sm py-vsp-xs text-small text-muted", children: labels.systemHelper.replace("{mode}", labels[resolved]) })
+        ]
+      }
+    ), document.body)
+  ] });
 }
 ThemeToggle.displayName = "ThemeToggle";
 export {

package/dist/theme-toggle/labels.d.ts

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

package/dist/theme-toggle/labels.js

@@ -0,0 +1,12 @@
+function themeToggleLabels(t, locale) {
+  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)
+  };
+}
+export {
+  themeToggleLabels
+};

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>