@takazudo/zudo-doc 5.28.2 → 6.0.1

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

@@ -1,12 +1,7 @@
 "use client";
 
 /** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-// Use preact hook entrypoints directly — the "react" → "preact/compat" alias
-// lets us consume React-typed components in this Preact app.
-import { useState, useEffect, useRef } from "preact/hooks";
-// After zudolab/zudo-doc#1335 the host components pull lifecycle event names
-// from the v2 transitions module rather than hard-coding `astro:*` literals.
+import { computed, getScope, signal, type Ref } from "@takazudo/zfb/zudo-react";
 // `ensureNestedIslandPropsRefresh` is imported through the barrel (not the
 // deep `./nested-island-props-refresh.js` path) on purpose: eject rewrites
 // EVERY `../transitions/<anything>.js` import to the single specifier
@@ -15,20 +10,19 @@ import { useState, useEffect, useRef } from "preact/hooks";
 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 { SidebarNavNode, SidebarRootMenuItem, SidebarLocaleLink, SidebarNavigationContext } from "../sidebar/types.js";
 import type { ResolvedDateFormats } from "../settings.js";
 
-// This island lives INSIDE the persisted `<header>`, so a same-locale swap
-// lifts it verbatim and would re-mount it from the previous page's serialized
-// props (zudolab/zudo-doc#3525). The refresh has to outlive the island's own
-// mount/unmount cycle across a swap, so it is installed at document lifetime
-// here rather than from an effect. SSR evaluation is a safe no-op.
+// This island lives inside the persisted `<header>`. Install the shared
+// document-lifetime preparation helper eagerly and idempotently so the native
+// zfb 3.1 lifecycle can retain unchanged nested islands and recreate this one
+// when its serialized page props change. SSR evaluation is a safe no-op.
 ensureNestedIslandPropsRefresh();
 
 const cx = (...classes: Array<string | false | null | undefined>) =>
   classes.filter(Boolean).join(" ");
 
-// Icon visibility deliberately does NOT ride on Tailwind's `.hidden` utility.
+// Icon visibility deliberately does NOT ride on the `.hidden` utility.
 // `.hidden` is emitted inside `@layer utilities`, and a consumer component pack
 // that ships an UNLAYERED media reset — `img, svg, video, … { display: block }`
 // — outranks every layered rule by cascade-layer precedence, no matter the
@@ -41,16 +35,16 @@ const HIDDEN_ICON_STYLE = "display:none";
 
 // Mobile drawer hosts the SidebarTree directly (rather than receiving it as
 // JSX children) so the tree's data props ride across the SSR → hydrate
-// boundary inside the Island marker's `data-props` attribute. zfb's
-// `Island()` only serialises a child component's *own* props (excluding
-// `children`); when SidebarTree was passed as `children`, its data was
-// dropped during hydration and Preact wiped the SSR-rendered tree DOM.
+// boundary inside this island's `data-props` attribute. The island marker
+// serializes the component's own props, not a child's props hidden inside
+// `children`; passing SidebarTree that way drops its data at hydration.
 // Mirroring the desktop `<Sidebar treeComponent={SidebarTree} ...>` shape
 // keeps the data attached to the wrapping island. zudolab/zudo-doc#1355
 // wave 13.5.
 
 export interface SidebarToggleProps {
   nodes: SidebarNavNode[];
+  navigation?: SidebarNavigationContext;
   currentSlug?: string;
   rootMenuItems?: SidebarRootMenuItem[];
   backToMenuLabel?: string;
@@ -61,21 +55,18 @@ export interface SidebarToggleProps {
   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
-   * its serialized `data-props` is lifted from the previous page and refreshed
-   * wholesale by `nested-island-props-refresh` — which carries the resolved
-   * patterns along with `nodes`, at no extra cost, because that helper copies
-   * the blob rather than enumerating prop names (#4075). The patterns cannot
-   * actually differ across such a swap (the persist key is `header-${lang}`,
-   * so a locale change is never a persisted swap); what matters is that they
-   * are not LOST from the lifted island.
+   * Forwarded verbatim to the hosted `<SidebarTree>`. The same-locale header
+   * may persist across a soft navigation; zfb 3.1 keeps this island live when
+   * its effective props are unchanged and recreates it from incoming props
+   * when page data changes. The locale-keyed header persistence key prevents
+   * locale-specific props from crossing locales.
    */
   dateFormats?: ResolvedDateFormats;
 }
 
 export function SidebarToggle({
   nodes,
+  navigation,
   currentSlug,
   rootMenuItems,
   backToMenuLabel,
@@ -86,35 +77,37 @@ export function SidebarToggle({
   themeRespectSystem,
   dateFormats,
 }: SidebarToggleProps) {
-  // Initial state must match SSR (`open=false`) so the hydration DOM
-  // matches the SSG output byte-for-byte. The backdrop and toggle-icon
-  // are rendered unconditionally below so the hydration tree has the
-  // same shape regardless of `open`, preventing Preact from re-mounting
-  // the subtree (which can drop click handlers on the hamburger button).
-  const [open, setOpen] = useState(false);
-  // Focus-restore target for the Escape handler below. A `ref` does not
-  // serialise, so SSR/hydration markup is unaffected (zudolab/zudo-doc#4366).
-  const hamburgerRef = useRef<HTMLButtonElement>(null);
+  // State starts closed on the server and client so the hydration markup is
+  // byte-stable. The tree stays mounted inside this island and receives the
+  // page props directly; it is not wrapped in another Island.
+  const open = signal(false);
+  const hamburgerRef: Ref<HTMLButtonElement> = { current: null };
+  const closeIconRef: Ref<SVGSVGElement> = { current: null };
+  const menuIconRef: Ref<SVGSVGElement> = { current: null };
+  const scope = getScope();
 
-  useEffect(() => {
-    if (open) {
-      document.body.style.overflow = "hidden";
-    } else {
-      document.body.style.overflow = "";
-    }
+  // Keep the v2 body-scroll behavior and always release the lock when this
+  // scope closes or is disposed.
+  scope.effect(() => {
+    const isOpen = open.value;
+    document.body.style.overflow = isOpen ? "hidden" : "";
+    if (isOpen) closeIconRef.current?.style.removeProperty("display");
+    else closeIconRef.current?.style.setProperty("display", "none");
+    if (isOpen) menuIconRef.current?.style.setProperty("display", "none");
+    else menuIconRef.current?.style.removeProperty("display");
     return () => {
       document.body.style.overflow = "";
     };
-  }, [open]);
+  });
 
-  // Close mobile sidebar on View Transition navigation
-  useEffect(() => {
-    function handleSwap() {
-      setOpen(false);
-    }
+  // Close the mobile drawer after a client-side route swap.
+  scope.onActivate(() => {
+    const handleSwap = () => {
+      open.value = false;
+    };
     document.addEventListener(AFTER_NAVIGATE_EVENT, handleSwap);
     return () => document.removeEventListener(AFTER_NAVIGATE_EVENT, handleSwap);
-  }, []);
+  });
 
   // Escape-to-close (zudolab/zudo-doc#4366). Deliberately inlined rather than
   // reusing `connectEscapeToClose` from theme-pack-switcher/switcher-state.js
@@ -127,91 +120,101 @@ export function SidebarToggle({
   // the hamburger synchronously in the handler — the `<aside>` goes `inert`
   // on close, so without this, focus left inside the drawer would strand on
   // `<body>` and defeat the point of the fix for keyboard/AT users.
-  useEffect(() => {
-    if (!open) return;
-    function handleKeyDown(event: KeyboardEvent) {
+  scope.effect(() => {
+    if (!open.value) return;
+    function handleKeyDown(event: Event) {
+      const keyboard = event as KeyboardEvent;
       // An Escape that ends an IME composition belongs to the composition, not
       // to the drawer: cancelling a Japanese conversion in the drawer's own
       // "Filter navigation" input would otherwise dismiss the whole drawer and
       // yank focus to the hamburger. Same guard the sibling document-level
       // shortcut in `sidebar-tree-island/index.tsx` already uses.
-      if (event.isComposing) return;
+      if (keyboard.isComposing) return;
       // A nested popover (the Appearance menu, or its trigger button) that
       // owns this Escape already called preventDefault() + stopPropagation()
       // to consume it for itself — see theme-toggle/index.tsx. Respecting
       // defaultPrevented here establishes layered Escape ownership: the first
       // Escape closes only the nested layer, and only a second, unconsumed
       // Escape reaches the drawer (zudolab/zudo-doc#4393).
-      if (event.defaultPrevented) return;
-      if (event.key === "Escape") {
-        setOpen(false);
+      if (keyboard.defaultPrevented) return;
+      if (keyboard.key === "Escape") {
+        open.value = false;
         hamburgerRef.current?.focus();
       }
     }
     document.addEventListener("keydown", handleKeyDown);
     return () => document.removeEventListener("keydown", handleKeyDown);
-  }, [open]);
+  });
 
+  const isClosed = computed(() => !open.value);
+  const toggleClass = computed(() =>
+    cx(
+      "lg:hidden shrink-0 px-hsp-sm py-vsp-xs -ml-hsp-sm mr-hsp-sm text-muted hover:text-fg",
+      open.value && "relative z-modal",
+    ),
+  );
+  const backdropClass = computed(() =>
+    cx(
+      "fixed inset-0 z-modal-backdrop bg-overlay/30 lg:hidden",
+      !open.value && "hidden",
+    ),
+  );
+  const panelClass = computed(() => `
+          fixed top-[3.5rem] left-0 z-modal h-[calc(100vh_-_3.5rem)] w-[16rem] flex flex-col
+          border-r border-muted bg-bg transition-transform duration-200
+          lg:hidden
+          ${open.value ? "translate-x-0" : "-translate-x-full"}
+        `);
   return (
     <>
       {/* Hamburger button - visible only on mobile.
           Both icons are always rendered so the SSR output has the same
-          DOM shape as the post-hydration tree. The inactive one is hidden
+          DOM shape as the hydrated tree. The inactive one is hidden
           via an inline `display:none` (see HIDDEN_ICON_STYLE above), so
-          Preact's hydration walk sees byte-stable markup and keeps the
-          click handler attached. */}
+          zudo-react hydrates byte-stable markup and keeps the click handler
+          attached. */}
       <button
         ref={hamburgerRef}
         type="button"
-        onClick={() => setOpen(!open)}
-        className={cx(
-          "lg:hidden shrink-0 px-hsp-sm py-vsp-xs -ml-hsp-sm mr-hsp-sm text-muted hover:text-fg",
-          // While open, the button IS the close control (it shows the X), so it
-          // has to sit in the drawer's own tier rather than under the backdrop —
-          // `z-modal-backdrop` (50) otherwise intercepts every pointer event at
-          // the button's own centre and the X is unclickable
-          // (zudolab/zudo-doc#4369). `relative` is required: a bare `z-index`
-          // has no effect on a statically-positioned element.
-          // Conditioning on `open` is load-bearing, not cosmetic: SSR always
-          // renders `open=false`, so the closed-state markup stays
-          // byte-identical (hydration-stable, and the A2 no-stub parity hashes
-          // for this directory do not move).
-          open && "relative z-modal",
+        on:click={() => {
+          open.value = !open.value;
+        }}
+        class={toggleClass}
+        aria-label={computed(() =>
+          open.value ? "Close sidebar" : "Open sidebar",
         )}
-        aria-label={open ? "Close sidebar" : "Open sidebar"}
-        aria-expanded={open}
+        aria-expanded={computed(() => (open.value ? "true" : "false"))}
       >
         {/* X icon — visible only when open */}
         <svg
-          xmlns="http://www.w3.org/2000/svg"
-          className="h-icon-lg w-icon-lg"
-          style={open ? undefined : HIDDEN_ICON_STYLE}
+          ref={closeIconRef}
+          class="h-icon-lg w-icon-lg"
+          style={HIDDEN_ICON_STYLE}
           aria-hidden="true"
           fill="none"
           viewBox="0 0 24 24"
           stroke="currentColor"
-          strokeWidth={2}
+          stroke-width={2}
         >
           <path
-            strokeLinecap="round"
-            strokeLinejoin="round"
+            stroke-linecap="round"
+            stroke-linejoin="round"
             d="M6 18L18 6M6 6l12 12"
           />
         </svg>
         {/* Hamburger icon — visible only when closed */}
         <svg
-          xmlns="http://www.w3.org/2000/svg"
-          className="h-icon-lg w-icon-lg"
-          style={open ? HIDDEN_ICON_STYLE : undefined}
+          ref={menuIconRef}
+          class="h-icon-lg w-icon-lg"
           aria-hidden="true"
           fill="none"
           viewBox="0 0 24 24"
           stroke="currentColor"
-          strokeWidth={2}
+          stroke-width={2}
         >
           <path
-            strokeLinecap="round"
-            strokeLinejoin="round"
+            stroke-linecap="round"
+            stroke-linejoin="round"
             d="M4 6h16M4 12h16M4 18h16"
           />
         </svg>
@@ -226,14 +229,16 @@ export function SidebarToggle({
           dims the whole viewport, header included. The toggle button is the
           one exception — while open it renders the X and advertises itself as
           the close control, so it is lifted to `z-modal` (60) for exactly as
-          long as the drawer is open (see its className above). Everything else
-          in the header stays dimmed and non-interactive underneath.
-          Backdrop tapping (onClick below) remains a valid dismissal, as does
-          Escape (zudolab/zudo-doc#4366). */}
+          long as the drawer is open (see the button class above). Everything
+          else in the header stays dimmed and non-interactive underneath.
+          Backdrop tapping and Escape remain valid dismissals
+          (zudolab/zudo-doc#4366). */}
       <div
-        className={cx("fixed inset-0 z-modal-backdrop bg-overlay/30 lg:hidden", !open && "hidden")}
-        aria-hidden={!open}
-        onClick={() => setOpen(false)}
+        class={backdropClass}
+        aria-hidden={isClosed}
+        on:click={() => {
+          open.value = false;
+        }}
       />
 
       {/* Sidebar panel - mobile only (desktop sidebar is in doc-layout).
@@ -249,18 +254,14 @@ export function SidebarToggle({
           `inert` it is UNCONDITIONAL, so it is hydration-stable by
           construction: it does not vary with `open`. */}
       <aside
-        inert={!open}
+        inert={isClosed}
         data-zd-mobile-sidebar
-        className={`
-          fixed top-[3.5rem] left-0 z-modal h-[calc(100vh-3.5rem)] w-[16rem] flex flex-col
-          border-r border-muted bg-bg transition-transform duration-200
-          lg:hidden
-          ${open ? "translate-x-0" : "-translate-x-full"}
-        `}
+        class={panelClass}
       >
-        <div className="flex-1 overflow-y-auto">
+        <div class="flex-1 overflow-y-auto">
           <SidebarTree
             nodes={nodes}
+            navigation={navigation}
             currentSlug={currentSlug}
             rootMenuItems={rootMenuItems}
             backToMenuLabel={backToMenuLabel}