@takazudo/zudo-doc 5.26.2 → 5.26.4

package/CHANGELOG.md

@@ -8,6 +8,23 @@ The format is based on Keep a Changelog, and release notes are generated from th
 
 No unreleased changes.
 
+## [5.26.4] - 2026-09-22
+
+### Bug Fixes
+
+- The mobile sidebar drawer now closes when Escape is pressed, and focus returns to the toggle button. The drawer is a modal-style surface — it renders above a full-viewport backdrop, locks body scroll while open, and is `inert` while closed — so Escape is the dismissal that keyboard-only and assistive-technology users reach for first, and it previously did nothing at all: the `SidebarToggle` island registered no key handler. The listener is now attached to `document` only while the drawer is open, so a closed drawer never swallows an Escape meant for another surface such as the language switcher or the theme-pack flyout. Focus is restored to the toggle as the drawer closes; because the panel becomes `inert` again, focus left inside it would otherwise strand on `<body>`. The handler ignores an Escape that ends an IME composition, so cancelling a Japanese conversion in the drawer's own filter field no longer dismisses the drawer. (10036db43, 4445f1972)
+- The toggle's X now closes the drawer when clicked. While the drawer was open the toggle rendered the close icon but sat underneath the backdrop — `z-modal-backdrop` (50) covers the header's `z-toolbar` (20), so `document.elementFromPoint()` at the button's own centre returned the backdrop element and every real pointer event was intercepted. The toggle now joins the drawer's own tier (`relative z-modal`, 60) for exactly as long as the drawer is open, so the X dismisses the drawer as its icon implies; the rest of the header stays dimmed and non-interactive underneath, and the closed-state markup is unchanged. Together with the Escape fix above, this restores both the keyboard and the pointer dismissal — before the two, clicking the backdrop was the only working way out of an open drawer, and nothing in the interface advertised it. (ffe0f728b)
+
+## [5.26.3] - 2026-09-21
+
+### Bug Fixes
+
+- The mobile sidebar toggle no longer renders both of its icons at once in a project whose global CSS contains an unlayered media reset such as `img, svg, video, canvas, audio, iframe, embed, object { display: block }`. The inactive icon used to be hidden with Tailwind's `.hidden` utility, which ships inside `@layer utilities` — an unlayered author rule outranks every layered rule by cascade-layer precedence regardless of source order, so both icons computed to `display: block`, stacked vertically, and made the toggle a 48px control showing the X and the hamburger together. The inactive icon is now hidden with an inline declaration, which no consumer stylesheet can outrank. (30d6625e8)
+
+### Other Changes
+
+- The `@takazudo/zfb`, `@takazudo/zfb-runtime`, and `@takazudo/zfb-md-wasm` peer dependency floors are now `^2.20.1`. The 2.20.1 release is lockstep metadata only — no upstream package reports a package-specific change, and the published-tarball delta is limited to each package's own version field plus its platform-binary pins. No zudo-doc config migration is required. (07d700356)
+
 ## [5.26.2] - 2026-09-20
 
 ### Bug Fixes

package/dist/sidebar-toggle-island/index.js

@@ -1,10 +1,11 @@
 "use client";
 import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
-import { useState, useEffect } from "preact/hooks";
+import { useState, useEffect, useRef } from "preact/hooks";
 import { AFTER_NAVIGATE_EVENT, ensureNestedIslandPropsRefresh } from "../transitions/index.js";
 import { SidebarTree } from "../sidebar-tree-island/index.js";
 ensureNestedIslandPropsRefresh();
 const cx = (...classes) => classes.filter(Boolean).join(" ");
+const HIDDEN_ICON_STYLE = "display:none";
 function SidebarToggle({
   nodes,
   currentSlug,
@@ -16,6 +17,7 @@ function SidebarToggle({
   dateFormats
 }) {
   const [open, setOpen] = useState(false);
+  const hamburgerRef = useRef(null);
   useEffect(() => {
     if (open) {
       document.body.style.overflow = "hidden";
@@ -33,13 +35,39 @@ function SidebarToggle({
     document.addEventListener(AFTER_NAVIGATE_EVENT, handleSwap);
     return () => document.removeEventListener(AFTER_NAVIGATE_EVENT, handleSwap);
   }, []);
+  useEffect(() => {
+    if (!open) return;
+    function handleKeyDown(event) {
+      if (event.isComposing) return;
+      if (event.key === "Escape") {
+        setOpen(false);
+        hamburgerRef.current?.focus();
+      }
+    }
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [open]);
   return /* @__PURE__ */ jsxs(Fragment, { children: [
     /* @__PURE__ */ jsxs(
       "button",
       {
+        ref: hamburgerRef,
         type: "button",
         onClick: () => setOpen(!open),
-        className: "lg:hidden shrink-0 px-hsp-sm py-vsp-xs -ml-hsp-sm mr-hsp-sm text-muted hover:text-fg",
+        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"
+        ),
         "aria-label": open ? "Close sidebar" : "Open sidebar",
         "aria-expanded": open,
         children: [
@@ -47,7 +75,8 @@ function SidebarToggle({
             "svg",
             {
               xmlns: "http://www.w3.org/2000/svg",
-              className: cx("h-icon-lg w-icon-lg", !open && "hidden"),
+              className: "h-icon-lg w-icon-lg",
+              style: open ? void 0 : HIDDEN_ICON_STYLE,
               "aria-hidden": "true",
               fill: "none",
               viewBox: "0 0 24 24",
@@ -67,7 +96,8 @@ function SidebarToggle({
             "svg",
             {
               xmlns: "http://www.w3.org/2000/svg",
-              className: cx("h-icon-lg w-icon-lg", open && "hidden"),
+              className: "h-icon-lg w-icon-lg",
+              style: open ? HIDDEN_ICON_STYLE : void 0,
               "aria-hidden": "true",
               fill: "none",
               viewBox: "0 0 24 24",

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

@@ -4,7 +4,7 @@
 /** @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 } from "preact/hooks";
+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.
 // `ensureNestedIslandPropsRefresh` is imported through the barrel (not the
@@ -27,6 +27,17 @@ ensureNestedIslandPropsRefresh();
 const cx = (...classes: Array<string | false | null | undefined>) =>
   classes.filter(Boolean).join(" ");
 
+// Icon visibility deliberately does NOT ride on Tailwind's `.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
+// source order. Both icons then computed to `display: block`, stacked, and made
+// the mobile toggle 48px tall (zudolab/zudo-doc#4355). An inline declaration
+// sits above all author rules, layered or not, so the state holds against any
+// consumer stylesheet. It is a plain string so SSR and the initial client
+// render serialise byte-identically for hydration.
+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
@@ -76,6 +87,9 @@ export function SidebarToggle({
   // 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);
 
   useEffect(() => {
     if (open) {
@@ -97,25 +111,69 @@ export function SidebarToggle({
     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
+  // — this island is ejectable and eject's `rewireImports` would rewrite that
+  // relative import to `@takazudo/zudo-doc/theme-pack-switcher`, a subpath
+  // absent from the package's `exports` map, shipping a broken ejected copy.
+  // The listener is registered only while `open` is true: a closed drawer
+  // must never swallow an Escape meant for another document-level listener
+  // (language switcher, find bar, theme-pack flyout). Focus is restored to
+  // 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) {
+      // 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 (event.key === "Escape") {
+        setOpen(false);
+        hamburgerRef.current?.focus();
+      }
+    }
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [open]);
+
   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 closed-state icon is
-          hidden via `hidden` when open=true, and vice versa, so Preact's
-          hydration walk sees byte-stable markup and keeps the click
-          handler attached. */}
+          DOM shape as the post-hydration 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. */}
       <button
+        ref={hamburgerRef}
         type="button"
         onClick={() => setOpen(!open)}
-        className="lg:hidden shrink-0 px-hsp-sm py-vsp-xs -ml-hsp-sm mr-hsp-sm text-muted hover:text-fg"
+        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",
+        )}
         aria-label={open ? "Close sidebar" : "Open sidebar"}
         aria-expanded={open}
       >
         {/* X icon — visible only when open */}
         <svg
           xmlns="http://www.w3.org/2000/svg"
-          className={cx("h-icon-lg w-icon-lg", !open && "hidden")}
+          className="h-icon-lg w-icon-lg"
+          style={open ? undefined : HIDDEN_ICON_STYLE}
           aria-hidden="true"
           fill="none"
           viewBox="0 0 24 24"
@@ -131,7 +189,8 @@ export function SidebarToggle({
         {/* Hamburger icon — visible only when closed */}
         <svg
           xmlns="http://www.w3.org/2000/svg"
-          className={cx("h-icon-lg w-icon-lg", open && "hidden")}
+          className="h-icon-lg w-icon-lg"
+          style={open ? HIDDEN_ICON_STYLE : undefined}
           aria-hidden="true"
           fill="none"
           viewBox="0 0 24 24"
@@ -152,9 +211,13 @@ export function SidebarToggle({
           mount/unmount across the hydration boundary).
           `z-modal-backdrop` (50) intentionally sits ABOVE the header
           (`z-toolbar`, 20): the open mobile drawer is a modal surface that
-          dims the whole viewport, header included. Closing is via tapping the
-          backdrop (onClick below), so the header hamburger being dimmed under
-          it is fine. */}
+          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). */}
       <div
         className={cx("fixed inset-0 z-modal-backdrop bg-overlay/30 lg:hidden", !open && "hidden")}
         aria-hidden={!open}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zudo-doc",
-  "version": "5.26.2",
+  "version": "5.26.4",
   "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.0",
-    "@takazudo/zfb-md-wasm": "^2.20.0",
-    "@takazudo/zfb-runtime": "^2.20.0",
+    "@takazudo/zfb": "^2.20.1",
+    "@takazudo/zfb-md-wasm": "^2.20.1",
+    "@takazudo/zfb-runtime": "^2.20.1",
     "@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.0",
-    "@takazudo/zfb-md-wasm": "2.20.0",
-    "@takazudo/zfb-runtime": "2.20.0",
+    "@takazudo/zfb": "2.20.1",
+    "@takazudo/zfb-md-wasm": "2.20.1",
+    "@takazudo/zfb-runtime": "2.20.1",
     "@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.2"
+    "@takazudo/zudo-doc-history-server": "5.26.4"
   },
   "scripts": {
     "gen:search-widget-script": "node scripts/gen-search-widget-script.mjs",