@takazudo/zudo-doc 1.0.2 → 1.1.0

package/eject/site-tree-nav-island/index.tsx

@@ -0,0 +1,222 @@
+"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 } from "preact/hooks";
+import type { SidebarNavNode } from "../sidebar/types.js";
+import { INDENT, connectorLeft, ConnectorLines, CategoryLinkIcon } from "../tree-nav-shared/index.js";
+import { ChevronRight } from "../icons/index.js";
+
+// site-tree-nav uses wider padding than the narrow sidebar
+const SITE_BASE_PAD = "clamp(0.5rem, 0.8vw, 1rem)";
+
+function padLeft(depth: number): string {
+  if (depth === 0) return SITE_BASE_PAD;
+  return `calc(${depth} * ${INDENT} + 1.25rem + 5px)`;
+}
+
+function reorderTree(tree: SidebarNavNode[], order: string[]): SidebarNavNode[] {
+  const map = new Map(tree.map((node) => [node.slug, node]));
+  const ordered: SidebarNavNode[] = [];
+  for (const slug of order) {
+    const node = map.get(slug);
+    if (node) {
+      ordered.push(node);
+      map.delete(slug);
+    }
+  }
+  // append unmatched nodes at end
+  for (const node of map.values()) {
+    ordered.push(node);
+  }
+  return ordered;
+}
+
+export interface SiteTreeNavProps {
+  tree: SidebarNavNode[];
+  ariaLabel?: string;
+  categoryOrder?: string[];
+  categoryIgnore?: string[];
+}
+
+export function SiteTreeNav({
+  tree,
+  ariaLabel = "Site index",
+  categoryOrder,
+  categoryIgnore,
+}: SiteTreeNavProps) {
+  let processedTree = tree;
+  if (categoryIgnore) {
+    const ignoreSet = new Set(categoryIgnore);
+    processedTree = processedTree.filter((node) => !ignoreSet.has(node.slug));
+  }
+  if (categoryOrder) {
+    processedTree = reorderTree(processedTree, categoryOrder);
+  }
+  return (
+    <nav
+      aria-label={ariaLabel}
+      data-site-nav
+      className="grid gap-vsp-md"
+      style={{
+        gridTemplateColumns: "repeat(auto-fill, minmax(min(18rem, 100%), 1fr))",
+      }}
+    >
+      {processedTree.map((node) => (
+        <div key={node.slug} className="min-w-0 border border-muted pl-hsp-sm py-vsp-2xs">
+          {node.children.length > 0 ? (
+            <CategoryNode node={node} depth={0} isLast={true} />
+          ) : (
+            <LeafNode node={node} depth={0} isLast={true} />
+          )}
+        </div>
+      ))}
+    </nav>
+  );
+}
+SiteTreeNav.displayName = "SiteTreeNav";
+
+function NodeList({ nodes, depth }: { nodes: SidebarNavNode[]; depth: number }) {
+  return (
+    <>
+      {nodes.map((node, index) => {
+        const isLast = index === nodes.length - 1;
+        return node.children.length > 0 ? (
+          <CategoryNode
+            key={node.slug}
+            node={node}
+            depth={depth}
+            isLast={isLast}
+          />
+        ) : (
+          <LeafNode
+            key={node.slug}
+            node={node}
+            depth={depth}
+            isLast={isLast}
+          />
+        );
+      })}
+    </>
+  );
+}
+
+function CategoryNode({
+  node,
+  depth,
+  isLast,
+}: {
+  node: SidebarNavNode;
+  depth: number;
+  isLast: boolean;
+}) {
+  const [open, setOpen] = useState(true);
+  const toggle = () => setOpen((prev) => !prev);
+  const paddingLeft = padLeft(depth);
+
+  return (
+    <div className={`${depth >= 1 && !isLast ? "relative" : ""}`}>
+      {depth >= 1 && !isLast && open && (
+        <div
+          className="absolute border-l border-dashed border-muted z-local-1"
+          style={{
+            left: connectorLeft(depth),
+            top: 0,
+            bottom: 0,
+          }}
+        />
+      )}
+      <div className="relative">
+        <ConnectorLines
+          depth={depth}
+          isLast={isLast}
+          widthScale={2}
+          topPad="calc(0.15rem + var(--spacing-vsp-xs))"
+        />
+        <div
+          className="flex w-full items-center justify-between text-small font-semibold pt-[0.15rem] text-fg"
+          style={{ paddingLeft }}
+        >
+          {node.href ? (
+            <a
+              href={node.href}
+              className="flex-1 flex items-start gap-hsp-xs py-vsp-xs text-fg hover:text-accent hover:underline focus:underline"
+            >
+              {depth === 0 && (
+                <span className="flex h-[1lh] items-center">
+                  <CategoryLinkIcon className="w-[18px] 2xl:w-[24px]" />
+                </span>
+              )}
+              {node.label}
+            </a>
+          ) : (
+            <button
+              type="button"
+              onClick={toggle}
+              className="flex-1 py-vsp-xs text-left hover:text-accent hover:underline focus:underline"
+            >
+              {node.label}
+            </button>
+          )}
+          <button
+            type="button"
+            onClick={toggle}
+            className="aspect-square flex items-center justify-center w-[1.75rem] border-y border-l border-muted hover:underline focus:underline"
+            aria-expanded={open}
+            aria-label={open ? `Collapse ${node.label}` : `Expand ${node.label}`}
+          >
+            <ChevronRight className={`h-icon-xs w-icon-xs transition-transform duration-150 ${open ? "rotate-90" : ""} text-muted`} />
+          </button>
+        </div>
+      </div>
+      {open && (
+        <div>
+          <NodeList nodes={node.children} depth={depth + 1} />
+        </div>
+      )}
+    </div>
+  );
+}
+
+function LeafNode({
+  node,
+  depth,
+  isLast,
+}: {
+  node: SidebarNavNode;
+  depth: number;
+  isLast: boolean;
+}) {
+  if (!node.href) return null;
+  const isRoot = depth === 0;
+  const paddingLeft = padLeft(depth);
+
+  const topPad = isRoot
+    ? "calc(var(--spacing-vsp-xs) + 0.15rem)"
+    : "var(--spacing-vsp-2xs)";
+
+  return (
+    <div>
+      <div className="relative">
+        <ConnectorLines depth={depth} isLast={isLast} widthScale={2} topPad={topPad} />
+        <a
+          href={node.href}
+          className={isRoot
+            ? "flex items-start gap-hsp-xs py-[calc(var(--spacing-vsp-xs)+0.15rem)] text-small font-semibold text-fg hover:text-accent hover:underline focus:underline"
+            : `block py-vsp-2xs ${isLast ? "pb-vsp-xs" : ""} text-small text-fg hover:text-accent hover:underline focus:underline`
+          }
+          style={{ paddingLeft }}
+        >
+          {isRoot && (
+            <span className="flex h-[1lh] items-center">
+              <CategoryLinkIcon className="w-[18px] 2xl:w-[24px]" />
+            </span>
+          )}
+          {node.label}
+        </a>
+      </div>
+    </div>
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zudo-doc",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "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",
@@ -511,9 +511,9 @@
   ],
   "peerDependencies": {
     "preact": "^10.29.1",
-    "@takazudo/zfb": "^0.1.0-next.65",
-    "@takazudo/zfb-runtime": "^0.1.0-next.65",
-    "@takazudo/zudo-doc-history-server": "^1.0.1",
+    "@takazudo/zfb": "^0.1.0-next.67",
+    "@takazudo/zfb-runtime": "^0.1.0-next.67",
+    "@takazudo/zudo-doc-history-server": "^1.0.2",
     "@takazudo/zdtp": "^0.3.3",
     "shiki": "^4.0.2",
     "zod": "^4.3.6",
@@ -555,8 +555,8 @@
     "typescript": "^5.0.0",
     "vitest": "^4.1.0",
     "zod": "^4.3.6",
-    "@takazudo/zfb": "0.1.0-next.65",
-    "@takazudo/zfb-runtime": "0.1.0-next.65"
+    "@takazudo/zfb": "0.1.0-next.67",
+    "@takazudo/zfb-runtime": "0.1.0-next.67"
   },
   "scripts": {
     "build": "tsup && tsc -p tsconfig.build.json",

package/routes-src/_chrome.tsx

@@ -27,7 +27,7 @@
 // bindings — is A2's job (#2363). With `packageOwnedRoutes` off this module is
 // never evaluated; it only needs to typecheck and import.
 
-import type { JSX, VNode } from "preact";
+import type { JSX, VNode, ComponentChildren } from "preact";
 import {
   settings,
   defaultLocale,
@@ -92,6 +92,11 @@ import {
   getThemeDefaultMode as getThemeDefaultModeBase,
 } from "@takazudo/zudo-doc/nav-data-prep";
 import { buildSidebarForSection } from "@takazudo/zudo-doc/sidebar-utils";
+import { Details } from "@takazudo/zudo-doc/details";
+import {
+  HtmlPreviewWrapper,
+  type HtmlPreviewWrapperProps,
+} from "@takazudo/zudo-doc/html-preview-wrapper";
 
 // ---------------------------------------------------------------------------
 // Package-default host-only bindings (see module header).
@@ -371,6 +376,49 @@ const SiteTreeNavWrapper = createSiteTreeNavWrapper({
   getCategoryOrder,
 });
 
+/** HtmlPreview MDX binding (package default).
+ *
+ *  Mirrors the host stub (`pages/_mdx-components.ts`): the global preview
+ *  config is `settings.htmlPreview`, a SERIALIZABLE setting that DOES ride in
+ *  the route-context virtual module, so the package can read it directly (no
+ *  host config needed). `HtmlPreviewWrapper` wraps the bare preview in
+ *  `<Island when="visible">`, which SSR-renders the preview tree — so an
+ *  injected docs page using `<HtmlPreview html="…" />` renders correct HTML.
+ *
+ *  Hydration caveat: the interactive code-toggle hydrates only if zfb's islands
+ *  scanner reaches the `@takazudo/zfb` <Island> import inside
+ *  `HtmlPreviewWrapper`. The esbuild islands bundler does NOT walk imports of
+ *  modules whose realpath is under `node_modules` (the same gap the routes
+ *  plugin stages around — see `plugins/routes.ts`; upstream report:
+ *  Takazudo/zudo-front-builder, "islands bundler skips addVirtualModule /
+ *  import-walk for node_modules route realpaths"). SSR output is unaffected. */
+function HtmlPreviewBound(props: HtmlPreviewWrapperProps): JSX.Element {
+  return HtmlPreviewWrapper({
+    globalConfig: settings.htmlPreview ?? null,
+    ...props,
+  }) as JSX.Element;
+}
+
+/** Island MDX binding (package default) — an SSR pass-through that renders its
+ *  children, deliberately NOT the real `@takazudo/zfb` <Island>.
+ *
+ *  Why a pass-through and not `Island → @takazudo/zfb` (the sub-issue's literal
+ *  ask): the MDX corpus never uses `<Island>` as a real render tag (only inside
+ *  changelog prose), and the host stub itself uses this same pass-through. The
+ *  real zfb <Island> emits `data-zfb-island="<firstChildTagName>"` for generic
+ *  MDX children, i.e. a hydration marker pointing at a non-existent manifest
+ *  entry — and the islands scanner can't register it anyway from a package
+ *  (node_modules) import (upstream report above). A pass-through renders the
+ *  server-renderable children correctly with no bogus marker, which is the
+ *  complete and correct behaviour for the corpus. `when` is ignored at SSR
+ *  time (it only matters to the client hydration runtime). */
+function IslandPassthrough(props: {
+  when?: "load" | "idle" | "visible" | "media";
+  children?: ComponentChildren;
+}): ComponentChildren {
+  return props.children ?? null;
+}
+
 export function createMdxComponentsBound(lang: string = defaultLocale) {
   return createMdxComponents({
     settings,
@@ -380,9 +428,22 @@ export function createMdxComponentsBound(lang: string = defaultLocale) {
       CategoryTreeNav: CategoryTreeNavWrapper as never,
       SiteTreeNav: SiteTreeNavWrapper as never,
     },
-    // PresetGenerator and other showcase-only slots resolve to a package stub
-    // (render nothing) — they are project-bound and not in the package.
+    // Package-owned content components wired here so an INJECTED docs route
+    // (packageOwnedRoutes, no host `pages/` stub) renders MDX using these tags
+    // without the "MDX requires '<X>' to be passed via the 'components' prop"
+    // error (sub-issue #2390 / supersedes #2377).
+    //   - Details      → fully functional (pure <details>, no client JS).
+    //   - HtmlPreview  → SSR-renders; see HtmlPreviewBound for the hydration
+    //                    caveat tied to the node_modules islands-scanner gap.
+    //   - Island       → SSR pass-through; see IslandPassthrough.
+    // PresetGenerator stays a package stub (render nothing): it is the
+    // showcase's project-bound interactive island and downstream projects stub
+    // it. The showcase keeps its host-owned docs catch-all routes (allowlisted)
+    // so its real PresetGenerator still renders.
     extras: {
+      Details: Details as never,
+      HtmlPreview: HtmlPreviewBound as never,
+      Island: IslandPassthrough as never,
       PresetGenerator: (_props: unknown) => null,
     },
   });