@takazudo/zudo-doc 5.28.2 → 6.0.1

package/dist/z-index-defaults/index.d.ts

@@ -4,7 +4,7 @@
  * Ported from the `create-zudo-doc` base template's
  * `src/config/z-index-tokens.ts` `Z_INDEX_TIERS` export (epic
  * zudolab/zudo-doc#2651, S4 #2654). Consumed by the theme-CSS default
- * (#2655) for the shipped `@theme` z-index block; a project's own
+ * (#2655) for the shipped `:root` z-index block; a project's own
  * `gen-z-index` codegen (from `@takazudo/zudo-doc`'s `gen-z-index` bin)
  * becomes opt-in customization on top of this default rather than the only
  * source.
@@ -16,9 +16,9 @@
  * Strategy (from zudolab/zudo-css-wisdom z-index-strategy): semantic single-
  * namespace tokens — names describe ROLES, never magnitudes. One flat ordered
  * list. Values are deliberately gapped but otherwise arbitrary: renaming and
- * reordering is cheap, which is the whole point. Tailwind v4 reads the
- * `--z-index-<name>` theme key and generates a `z-<name>` utility, so e.g.
- * `@theme { --z-index-toolbar: 20 }` produces `.z-toolbar { z-index: 20 }`.
+ * reordering is cheap, which is the whole point. zudo-wind reads the
+ * `--z-index-<name>` token and generates a `z-<name>` utility, so e.g.
+ * `:root { --z-index-toolbar: 20 }` produces `.z-toolbar { z-index: 20 }`.
  *
  * `local-1`/`local-2`/`local-3` ("local" kind in the template) are anonymous
  * reusable helpers for promoting a child WITHIN a parent stacking context

package/dist/zdtp-loader.d.ts

@@ -1 +1,8 @@
+import type { PanelConfig, PanelInstanceHandle } from "@takazudo/zdtp";
 export * from "@takazudo/zdtp";
+/**
+ * Mount zdtp's opaque Preact root only while the activating island still owns
+ * the pending import. Once configured, zdtp keeps its document-lifetime root
+ * and its existing navigation cleanup semantics.
+ */
+export declare function configurePanelIfActive(signal: AbortSignal | undefined, config: PanelConfig): PanelInstanceHandle | null;

package/dist/zdtp-loader.js

@@ -1 +1,9 @@
+import { configurePanel } from "@takazudo/zdtp";
 export * from "@takazudo/zdtp";
+function configurePanelIfActive(signal, config) {
+  if (signal?.aborted) return null;
+  return configurePanel(config);
+}
+export {
+  configurePanelIfActive
+};

package/eject/asset-components/asset-card.tsx

@@ -1,7 +1,5 @@
 /** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-
-import type { JSX } from "preact";
+import type { JSX } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import { assetRawHref, assetViewerHref } from "../asset-path/index.js";
 import {
   AssetFileIcon,
@@ -59,27 +57,27 @@ export function createAssetCard(context: AssetComponentContext) {
     const finalDescription = description ?? entry.description;
 
     return (
-      <article className="rounded-lg border border-muted bg-surface px-hsp-lg py-vsp-sm">
-        <div className="flex items-start gap-x-hsp-md">
-          <span className="flex h-icon-lg w-icon-lg shrink-0 items-center justify-center text-muted">
-            <AssetFileIcon className="h-icon-lg w-icon-lg" />
+      <article class="rounded-lg border border-muted bg-surface px-hsp-lg py-vsp-sm">
+        <div class="flex items-start gap-x-hsp-md">
+          <span class="flex h-icon-lg w-icon-lg shrink-0 items-center justify-center text-muted">
+            <AssetFileIcon class="h-icon-lg w-icon-lg" />
           </span>
-          <div className="min-w-0 flex-1">
-            <div className="font-mono text-small text-fg">
-              {entry.dir ? <span className="text-muted">{entry.dir}/</span> : null}
+          <div class="min-w-0 flex-1">
+            <div class="font-mono text-small text-fg">
+              {entry.dir ? <span class="text-muted">{entry.dir}/</span> : null}
               <strong>{title ?? entry.name}</strong>
             </div>
-            <div className="mt-vsp-3xs text-caption text-muted">
+            <div class="mt-vsp-3xs text-caption text-muted">
               {details.join(" · ")}
             </div>
             {finalDescription ? (
-              <p className="mt-vsp-xs text-small text-muted">
+              <p class="mt-vsp-xs text-small text-muted">
                 {finalDescription}
               </p>
             ) : null}
-            <div className="mt-vsp-xs flex gap-x-hsp-lg text-caption">
+            <div class="mt-vsp-xs flex gap-x-hsp-lg text-caption">
               <a
-                className="text-fg hover:text-accent focus-visible:text-accent hover:underline focus-visible:underline"
+                class="text-fg hover:text-accent focus-visible:text-accent hover:underline focus-visible:underline"
                 href={viewerHref}
               >
                 {assetComponentText(
@@ -89,9 +87,9 @@ export function createAssetCard(context: AssetComponentContext) {
                 )} →
               </a>
               <a
-                className="text-fg hover:text-accent focus-visible:text-accent hover:underline focus-visible:underline"
+                class="text-fg hover:text-accent focus-visible:text-accent hover:underline focus-visible:underline"
                 href={rawHref}
-                download
+                download=""
               >
                 {assetComponentText(
                   context,

package/eject/asset-components/asset-code.tsx

@@ -1,7 +1,5 @@
 /** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-
-import type { JSX } from "preact";
+import type { JSX } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import { assetViewerHref } from "../asset-path/index.js";
 import {
   AssetFileIcon,
@@ -91,19 +89,19 @@ export function createAssetCode(context: AssetComponentContext) {
           : `lines ${requested.start}–${requested.end}`;
 
     return (
-      <section className="overflow-hidden rounded-lg border border-muted bg-surface">
-        <header className="flex items-center justify-between gap-x-hsp-md border-b border-muted px-hsp-lg py-vsp-2xs text-caption">
-          <span className="flex min-w-0 items-center gap-x-hsp-xs font-mono text-fg">
-            <AssetFileIcon className="h-icon-sm w-icon-sm shrink-0" />
+      <section class="overflow-hidden rounded-lg border border-muted bg-surface">
+        <header class="flex items-center justify-between gap-x-hsp-md border-b border-muted px-hsp-lg py-vsp-2xs text-caption">
+          <span class="flex min-w-0 items-center gap-x-hsp-xs font-mono text-fg">
+            <AssetFileIcon class="h-icon-sm w-icon-sm shrink-0" />
             <span>{title ?? resolved.path}</span>
           </span>
-          <span className="shrink-0 text-muted">{rangeLabel}</span>
+          <span class="shrink-0 text-muted">{rangeLabel}</span>
         </header>
         <div
-          className="overflow-x-auto bg-code-bg text-code-fg text-caption"
-          dangerouslySetInnerHTML={{ __html: excerpt.html }}
+          class="overflow-x-auto bg-code-bg text-code-fg text-caption"
+          rawHtml={excerpt.html}
         />
-        <footer className="flex flex-wrap items-center justify-between gap-x-hsp-md gap-y-vsp-3xs border-t border-muted px-hsp-lg py-vsp-2xs text-caption text-muted">
+        <footer class="flex flex-wrap items-center justify-between gap-x-hsp-md gap-y-vsp-3xs border-t border-muted px-hsp-lg py-vsp-2xs text-caption text-muted">
           <span>
             {assetComponentText(
               context,
@@ -113,7 +111,7 @@ export function createAssetCode(context: AssetComponentContext) {
             )}
           </span>
           <a
-            className="text-fg hover:text-accent focus-visible:text-accent hover:underline focus-visible:underline"
+            class="text-fg hover:text-accent focus-visible:text-accent hover:underline focus-visible:underline"
             href={viewerHref}
           >
             {assetComponentText(

package/eject/asset-components/shared.tsx

@@ -1,7 +1,5 @@
 /** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-
-import type { JSX } from "preact";
+import type { JSX } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import { decodeAuthoredHref } from "../asset-path/index.js";
 import type {
   AssetIndexEntry,
@@ -92,13 +90,13 @@ export function formatAssetLanguage(language: string | undefined): string {
 }
 
 export function AssetFileIcon({
-  className,
+  class: className,
 }: {
-  className?: string;
+  class?: string;
 }): JSX.Element {
   return (
     <svg
-      className={className}
+      class={className}
       viewBox="0 0 24 24"
       fill="none"
       stroke="currentColor"
@@ -120,7 +118,7 @@ export function MissingAssetWarning({
 }): JSX.Element {
   return (
     <div
-      className="rounded border border-warning/30 bg-warning/5 px-hsp-lg py-vsp-xs text-small text-warning"
+      class="rounded border border-warning/30 bg-warning/5 px-hsp-lg py-vsp-xs text-small text-warning"
       role="status"
     >
       {children}

package/eject/breadcrumb/breadcrumb.tsx

@@ -1,7 +1,5 @@
 /** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-
-import type { ComponentChildren, VNode } from "preact";
+import type { Child, Description } from "@takazudo/zfb/zudo-react";
 import { findPath } from "./find-path.js";
 import type { BreadcrumbItem, BreadcrumbNode } from "./types.js";
 import { ChevronRight } from "../icons/index.js";
@@ -46,14 +44,14 @@ interface SmartLabelProps {
  * v2 package — the legacy smart-break util lives in the host project's
  * src/utils/, which v2 must not reach into.
  *
- * Inserts a Preact <wbr/> after each delimiter character when the label
+ * Inserts a zudo-react <wbr/> after each delimiter character when the label
  * looks "path-like" (URLs, slash-separated paths, etc.). Prose labels
  * pass through unchanged.
  */
-function SmartLabel({ label }: SmartLabelProps): VNode | string {
+function SmartLabel({ label }: SmartLabelProps): Child {
   if (!isPathLike(label)) return label;
   const parts = label.split(DELIM_SPLIT);
-  const nodes: (string | VNode)[] = [];
+  const nodes: Child[] = [];
   for (let i = 0; i < parts.length; i++) {
     const part = parts[i];
     if (!part) continue;
@@ -83,14 +81,13 @@ function isPathLike(text: string): boolean {
   return false;
 }
 
-function ChevronIcon(): VNode {
-  return <ChevronRight className="h-icon-xs w-icon-xs text-muted shrink-0" />;
+function ChevronIcon(): Child {
+  return <ChevronRight class="h-icon-xs w-icon-xs text-muted shrink-0" />;
 }
 
-function HomeIcon(): VNode {
+function HomeIcon(): Child {
   return (
     <svg
-      xmlns="http://www.w3.org/2000/svg"
       class="h-[1.575rem] w-[1.575rem] shrink-0"
       fill="none"
       viewBox="0 0 24 24"
@@ -123,14 +120,15 @@ export interface BreadcrumbProps {
    * breadcrumb + version-switcher row:
    *
    *   class="mb-vsp-sm flex flex-col items-start gap-vsp-xs
-   *          sm:flex-row sm:items-center sm:justify-between [&_nav]:mb-0"
+   *          sm:flex-row sm:items-center sm:justify-between zd-breadcrumb-nav-no-margin"
    *
-   * The `[&_nav]:mb-0` rule strips the nav's own `mb-vsp-md` so the
+   * The `zd-breadcrumb-nav-no-margin` rule strips the nav's own
+   * `mb-vsp-md` so the
    * wrapper margin controls spacing instead. Use this to place the
    * VersionSwitcher pill inline at the right of the breadcrumb row,
    * matching the reference site's layout on category index pages.
    */
-  rightSlot?: ComponentChildren;
+  rightSlot?: Child;
 }
 
 /**
@@ -144,7 +142,7 @@ export interface BreadcrumbProps {
  * Returns null when no items resolve, matching the documented
  * `items.length > 0 &&` guard.
  */
-export function Breadcrumb(props: BreadcrumbProps): VNode | null {
+export function Breadcrumb(props: BreadcrumbProps): Child {
   const items =
     props.items ??
     (props.tree && props.currentId !== undefined
@@ -187,11 +185,12 @@ export function Breadcrumb(props: BreadcrumbProps): VNode | null {
 
   // When a rightSlot is provided, wrap both elements in a flex row that
   // matches the original Astro doc-layout's breadcrumb + version-switcher
-  // row. The `[&_nav]:mb-0` rule cancels the nav's own bottom margin so
+  // row. The `zd-breadcrumb-nav-no-margin` rule cancels the nav's own bottom
+  // margin so
   // the wrapper margin controls spacing instead (matching the Astro
   // reference which used `mb-vsp-sm` on the outer div).
   return (
-    <div class="mb-vsp-sm flex flex-col items-start gap-vsp-xs sm:flex-row sm:items-center sm:justify-between [&_nav]:mb-0">
+    <div class="mb-vsp-sm flex flex-col items-start gap-vsp-xs sm:flex-row sm:items-center sm:justify-between zd-breadcrumb-nav-no-margin">
       {nav}
       {props.rightSlot}
     </div>

package/eject/code-group/index.tsx

@@ -1,5 +1,4 @@
 /** @jsxRuntime automatic */
-/** @jsxImportSource preact */
 // CodeGroup — adapter for zfb's `:::code-group` directive (codeTabs Option A).
 // Moved from the showcase's `src/components/content/code-group.tsx` into the
 // shared package as part of the package-first migration (epic #2321, S4 #2327).
@@ -22,24 +21,19 @@
 // TabsInit (the companion init script) is expected to be present in the
 // consumer's layout — we do not duplicate it here.
 
-import type { ComponentChildren } from "preact";
+import { flattenChildren } from "@takazudo/zfb/zudo-react";
+import type { Child } from "@takazudo/zfb/zudo-react";
 import { Tabs } from "../code-syntax/index.js";
 import { TabItem } from "../tab-item/index.js";
 
 type Props = {
   tabs?: string[];
-  children?: ComponentChildren;
+  children?: Child;
   [key: string]: unknown;
 };
 
-function toArray(children: ComponentChildren): ComponentChildren[] {
-  if (!children) return [];
-  if (Array.isArray(children)) return children;
-  return [children];
-}
-
 export function CodeGroup({ tabs = [], children, name }: Props) {
-  const childArray = toArray(children);
+  const childArray = flattenChildren(children);
 
   // Zip tabs labels with pre children by index. Extra children beyond the
   // tabs array (shouldn't happen in normal zfb output) are ignored.

package/eject/content-admonition/index.tsx

@@ -1,12 +1,11 @@
 /** @jsxRuntime automatic */
-/** @jsxImportSource preact */
 // Admonition factory for MDX callout variants (Note/Tip/Info/Warning/
 // Danger/Caution/Important). Moved from the showcase's
 // `src/components/content/content-admonition.tsx` into the shared package
 // as part of the package-first migration (epic #2321, S4 #2327).
 //
 // Markup contract — KEEP STABLE. The structure:
-//   <div data-admonition="<variant>" class="admonition admonition-<variant>">
+//   <div data-admonition="<variant>" class="admonition-<variant>">
 //     <p class="admonition-title">…</p>
 //     <div class="admonition-body">…</div>
 //   </div>
@@ -14,7 +13,7 @@
 // the consumer's global.css) and e2e smoke specs target. Per-variant
 // color + icon live in CSS keyed off `data-admonition`, so this component
 // stays presentation-agnostic.
-import type { ComponentChildren, VNode } from "preact";
+import type { Child } from "@takazudo/zfb/zudo-react";
 
 export type AdmonitionVariant =
   | "note"
@@ -28,7 +27,7 @@ export type AdmonitionVariant =
 export interface AdmonitionProps {
   /** Custom title; falls back to the capitalized variant name (e.g. "Note"). */
   title?: string;
-  children?: ComponentChildren;
+  children?: Child;
 }
 
 /**
@@ -38,10 +37,10 @@ export interface AdmonitionProps {
  */
 export function makeAdmonition(variant: AdmonitionVariant) {
   const defaultTitle = variant.charAt(0).toUpperCase() + variant.slice(1);
-  return function Admonition({ title, children }: AdmonitionProps): VNode {
+  return function Admonition({ title, children }: AdmonitionProps): Child {
     const heading = title && title.length > 0 ? title : defaultTitle;
     return (
-      <div data-admonition={variant} class={`admonition admonition-${variant}`}>
+      <div data-admonition={variant} class={`admonition-${variant}`}>
         <p class="admonition-title">{heading}</p>
         <div class="admonition-body">{children}</div>
       </div>

package/eject/desktop-sidebar-toggle-island/index.ts

@@ -0,0 +1,4 @@
+// Keep storage helpers available to existing package consumers from this
+// ordinary facade. The zudo-react island entry exports only its component.
+export { DesktopSidebarToggle } from "./island.js";
+export { SIDEBAR_STORAGE_KEY, readState, setDataAttribute } from "./storage.js";

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

@@ -0,0 +1,50 @@
+"use client";
+
+/** @jsxRuntime automatic */
+import { computed, getScope, Show, signal } from "@takazudo/zfb/zudo-react";
+import { ChevronLeft, ChevronRight } from "../icons/index.js";
+import { AFTER_NAVIGATE_EVENT } from "../transitions/index.js";
+import { readState, setDataAttribute, writeState } from "./storage.js";
+
+export function DesktopSidebarToggle() {
+  // Keep SSR and the initial client render visible. The activation callback
+  // reads storage only after hydration, when browser APIs are available.
+  const visible = signal(true);
+  const scope = getScope();
+
+  scope.onActivate(() => {
+    const initialVisibility = readState();
+    visible.value = initialVisibility;
+    setDataAttribute(initialVisibility);
+
+    const restoreDocumentAttribute = () => setDataAttribute(readState());
+    document.addEventListener(AFTER_NAVIGATE_EVENT, restoreDocumentAttribute);
+    return () => document.removeEventListener(AFTER_NAVIGATE_EVENT, restoreDocumentAttribute);
+  });
+
+  const toggle = () => {
+    const next = !visible.value;
+    visible.value = next;
+    writeState(next);
+    setDataAttribute(next);
+  };
+
+  return (
+    <button
+      type="button"
+      on:click={toggle}
+      class="zd-desktop-sidebar-toggle hidden lg:flex fixed bottom-vsp-xl z-sidebar items-center justify-center w-[1.5rem] h-[3rem] bg-surface border border-muted border-l-0 text-muted cursor-pointer transition-[left,color] duration-200 hover:text-fg"
+      style="border-radius:0 var(--radius-DEFAULT) var(--radius-DEFAULT) 0"
+      aria-label={computed(() => visible.value ? "Hide sidebar" : "Show sidebar")}
+      aria-pressed={visible}
+    >
+      <Show when={computed(() => visible.value)}>
+        {() => <ChevronLeft class="h-icon-sm w-icon-sm" />}
+      </Show>
+      <Show when={computed(() => !visible.value)}>
+        {() => <ChevronRight class="h-icon-sm w-icon-sm" />}
+      </Show>
+    </button>
+  );
+}
+DesktopSidebarToggle.displayName = "DesktopSidebarToggle";

package/eject/desktop-sidebar-toggle-island/storage.ts

@@ -0,0 +1,27 @@
+export const SIDEBAR_STORAGE_KEY = "zudo-doc-sidebar-visible";
+
+export function readState(): boolean {
+  if (typeof window === "undefined") return true;
+  try {
+    return localStorage.getItem(SIDEBAR_STORAGE_KEY) !== "false";
+  } catch {
+    return true;
+  }
+}
+
+export function writeState(isVisible: boolean): void {
+  try {
+    localStorage.setItem(SIDEBAR_STORAGE_KEY, String(isVisible));
+  } catch {
+    // Private browsing and disabled storage must not block the toggle.
+  }
+}
+
+export function setDataAttribute(isVisible: boolean): void {
+  if (typeof document === "undefined") return;
+  if (isVisible) {
+    document.documentElement.removeAttribute("data-sidebar-hidden");
+  } else {
+    document.documentElement.setAttribute("data-sidebar-hidden", "");
+  }
+}

package/eject/details/details.tsx

@@ -1,7 +1,5 @@
 /** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-
-import type { ComponentChildren, VNode } from "preact";
+import type { Child } from "@takazudo/zfb/zudo-react";
 
 export interface DetailsProps {
   /**
@@ -11,7 +9,7 @@ export interface DetailsProps {
    */
   title?: string;
   /** Slot content rendered inside the collapsed body. */
-  children?: ComponentChildren;
+  children?: Child;
 }
 
 /**
@@ -22,7 +20,7 @@ export interface DetailsProps {
  * The legacy component used Astro's `<slot />`; v2 accepts standard
  * Preact `children`.
  */
-export function Details({ title = "Details", children }: DetailsProps): VNode {
+export function Details({ title = "Details", children }: DetailsProps): Child {
   return (
     <details class="my-vsp-md border border-muted rounded-lg overflow-hidden">
       <summary class="cursor-pointer px-hsp-lg py-vsp-sm bg-surface font-medium text-fg select-none hover:text-accent">