@takazudo/zudo-doc 5.26.3 → 5.26.4

package/CHANGELOG.md

@@ -8,6 +8,13 @@ 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

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

@@ -1,6 +1,6 @@
 "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();
@@ -17,6 +17,7 @@ function SidebarToggle({
   dateFormats
 }) {
   const [open, setOpen] = useState(false);
+  const hamburgerRef = useRef(null);
   useEffect(() => {
     if (open) {
       document.body.style.overflow = "hidden";
@@ -34,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: [

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
@@ -87,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) {
@@ -108,6 +111,35 @@ 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.
@@ -117,9 +149,23 @@ export function SidebarToggle({
           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}
       >
@@ -165,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.3",
+  "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",
@@ -771,7 +771,7 @@
     "typescript": "^5.0.0",
     "vitest": "^4.1.0",
     "zod": "^4.3.6",
-    "@takazudo/zudo-doc-history-server": "5.26.3"
+    "@takazudo/zudo-doc-history-server": "5.26.4"
   },
   "scripts": {
     "gen:search-widget-script": "node scripts/gen-search-widget-script.mjs",