@takazudo/zudo-doc 5.28.1 → 6.0.0

package/dist/content/heading-h4.d.ts

@@ -1,6 +1,5 @@
 /** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-import type { JSX } from "preact";
+import type { JSX } from "@takazudo/zfb/zudo-react/jsx-runtime";
 type Props = JSX.IntrinsicElements["h4"];
-export declare function HeadingH4({ id, children, className, ...rest }: Props): JSX.Element;
+export declare function HeadingH4({ id, children, class: klass, ...rest }: Props): import("@takazudo/zfb").Description;
 export {};

package/dist/content/heading-h4.js

@@ -1,12 +1,12 @@
-import { jsx } from "preact/jsx-runtime";
-function HeadingH4({ id, children, className, ...rest }) {
+import { jsx } from "@takazudo/zfb/zudo-react/jsx-runtime";
+function HeadingH4({ id, children, class: klass, ...rest }) {
   return /* @__PURE__ */ jsx(
     "h4",
     {
       id,
-      className: `text-body font-semibold leading-snug pt-vsp-xs border-t border-transparent${className ? ` ${className}` : ""}`,
+      class: `text-body font-semibold leading-snug pt-vsp-xs border-t border-transparent${klass ? ` ${klass}` : ""}`,
       style: {
-        borderImage: "linear-gradient(to right, var(--color-muted), transparent) 1"
+        "border-image": "linear-gradient(to right, var(--color-muted), transparent) 1"
       },
       ...rest,
       children

package/dist/content-admonition/index.d.ts

@@ -1,15 +1,14 @@
 /** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-import type { ComponentChildren, VNode } from "preact";
+import type { Child } from "@takazudo/zfb/zudo-react";
 export type AdmonitionVariant = "note" | "tip" | "info" | "warning" | "danger" | "caution" | "important";
 export interface AdmonitionProps {
     /** Custom title; falls back to the capitalized variant name (e.g. "Note"). */
     title?: string;
-    children?: ComponentChildren;
+    children?: Child;
 }
 /**
  * Build the admonition component for a single variant. The title row is always
  * rendered — defaulting to the capitalized variant name when the author gives
  * no `title` — matching the Astro reference where every callout shows a title.
  */
-export declare function makeAdmonition(variant: AdmonitionVariant): ({ title, children }: AdmonitionProps) => VNode;
+export declare function makeAdmonition(variant: AdmonitionVariant): ({ title, children }: AdmonitionProps) => Child;

package/dist/content-admonition/index.js

@@ -1,9 +1,9 @@
-import { jsx, jsxs } from "preact/jsx-runtime";
+import { jsx, jsxs } from "@takazudo/zfb/zudo-react/jsx-runtime";
 function makeAdmonition(variant) {
   const defaultTitle = variant.charAt(0).toUpperCase() + variant.slice(1);
   return function Admonition({ title, children }) {
     const heading = title && title.length > 0 ? title : defaultTitle;
-    return /* @__PURE__ */ jsxs("div", { "data-admonition": variant, class: `admonition admonition-${variant}`, children: [
+    return /* @__PURE__ */ jsxs("div", { "data-admonition": variant, class: `admonition-${variant}`, children: [
       /* @__PURE__ */ jsx("p", { class: "admonition-title", children: heading }),
       /* @__PURE__ */ jsx("div", { class: "admonition-body", children })
     ] });

package/dist/content.css

@@ -10,32 +10,34 @@
  * drift). See zudolab/zudo-doc#2188.
  *
  * Component-first split: the major elements (h2–h4, p, a, strong, blockquote,
- * ul, ol, table) get their VISUALS from the package's `defaultComponents` Preact
- * components (Tailwind classes + inline styles), whose utilities ship in
- * `dist/safelist.css`. This file owns only what those components do NOT emit:
- * the flow-space vertical rhythm, heading `--flow-space` + tightening, the
- * minor/structural elements (li, code, pre, th/td, hr, img, h5/h6, dt/dd,
- * hash-links), and the admonitions + mermaid layout.
+ * ul, ol, table) get their VISUALS from the package's `defaultComponents`
+ * zudo-react components, whose utilities are generated by zudo-wind from the
+ * public `@takazudo/zudo-doc/wind.json` manifest. This file owns only what
+ * those components do NOT emit: the flow-space vertical rhythm, heading
+ * `--flow-space` + tightening, the minor/structural elements (li, code, pre,
+ * th/td, hr, img, h5/h6, dt/dd, hash-links), and the admonitions + mermaid
+ * layout.
  *
  * ── Consumer contract ──────────────────────────────────────────────────────
- * 1. LAYER ORDER — the consumer's stylesheet MUST declare, before importing:
- *        @layer zd-preflight, zd-flow;
- *        @import "tailwindcss/preflight" layer(zd-preflight);
- *        @import "tailwindcss/utilities";            (unlayered)
- *    The flow-space owl rule below lives in `@layer zd-flow` so unlayered
- *    `mt-*` utilities win over it while it still beats preflight's
- *    `* { margin: 0 }`. See zudolab/zudo-doc#2082 / #2109.
- * 2. DESIGN TOKENS — the consumer's `@theme` MUST define every custom property
- *    consumed below:
+ * 1. LAYER ORDER — the consumer's stylesheet declares, before importing:
+ *        @layer zw-reset, zd-flow;
+ *    `zw-reset` is the zudo-wind reset layer (`reset: "owned-v1"`, supplied by
+ *    `zudoDoc()`); `zd-flow` is the layer used below for the flow-space owl
+ *    rule, so unlayered utilities (e.g. `mt-*`) win over it while it still
+ *    beats the reset's `* { margin: 0 }`. Only that flow rule is layered.
+ *    See zudolab/zudo-doc#2082 / #2109.
+ * 2. DESIGN TOKENS — no consumer `@theme`, Tailwind import or safelist is
+ *    needed. `zudoDoc()` supplies var-backed token defaults, and the custom
+ *    properties consumed below are authored as plain `:root` variables
+ *    (default values from `@takazudo/zudo-doc/theme.css`; override them in a
+ *    `:root` rule after the imports):
  *      --color-{fg,bg,muted,accent,accent-hover,code-bg,code-fg,info,success,
  *               warning,danger}
  *      --spacing-{vsp-2xs,vsp-xs,vsp-sm,vsp-md,vsp-lg,vsp-xl,vsp-2xl,
  *                 hsp-2xs,hsp-xs,hsp-sm,hsp-md,hsp-lg,hsp-xl}
  *      --text-{body,small}   --font-mono   --font-weight-{medium,semibold}
  *      --leading-{relaxed,snug}   --radius-DEFAULT
- * 3. SAFELIST — the consumer MUST also `@import "@takazudo/zudo-doc/safelist.css"`
- *    so the component-emitted utility classes (text-title, border-t-[3px],
- *    text-accent, …) are generated.
+ *    See packages/zudo-doc/CLAUDE.md, "Shipped CSS artifacts and Wind manifest".
  * ========================================================================== */
 
 /* ========================================
@@ -55,13 +57,13 @@
 /* ── Flow spacing (vertical rhythm) ── */
 
 /* In the `zd-flow` cascade layer (declared by the consumer at the top of its
- * stylesheet) so the unlayered `tailwindcss/utilities` import wins over it:
+ * stylesheet) so unlayered utilities win over it:
  * unlayered declarations always beat layered ones regardless of specificity or
  * source order. Both this rule and a `mt-*` utility have specificity (0,1,0);
  * without the layer this rule comes later in source order and silently kills
  * every `mt-*` on a `.zd-content` direct child (e.g. body-foot-util-area's
- * `mt-vsp-xl`). zd-flow sits ABOVE zd-preflight so this rule still beats
- * preflight's `* { margin: 0 }` reset and the .zd-content rhythm is preserved
+ * `mt-vsp-xl`). zd-flow is declared AFTER zw-reset so this rule still beats
+ * the reset's `* { margin: 0 }` reset and the .zd-content rhythm is preserved
  * for plain content blocks. The layer is scoped to ONLY this flow rule — every
  * other `.zd-content` author rule (links, code, lists, headings, the
  * `:first-child` reset, etc.) stays unlayered so utilities do NOT flip those.
@@ -119,24 +121,20 @@
 
 /* ── Heading auto-links ── */
 
+/* Native heading links are empty, as in v2. Preserve their ordinary link
+   styling without adding a visible glyph or changing heading geometry. */
 .zd-content :where(h2, h3, h4, h5, h6) .hash-link {
-  text-decoration: none;
-  margin-left: var(--spacing-hsp-sm);
-  opacity: 0;
-  transition: opacity var(--default-transition-duration);
-}
-
-.zd-content :where(h2, h3, h4, h5, h6) .hash-link::after {
-  content: "#";
   color: var(--color-accent);
+  text-decoration: underline;
 }
 
-.zd-content :where(h2, h3, h4, h5, h6):hover .hash-link {
-  opacity: 1;
+@media (hover: hover) {
+  .zd-content :where(h2, h3, h4, h5, h6) .hash-link:hover {
+    color: var(--color-accent-hover);
+  }
 }
 
 .zd-content :where(h2, h3, h4, h5, h6) .hash-link:focus-visible {
-  opacity: 1;
   outline: 2px solid var(--color-accent);
   outline-offset: 2px;
 }
@@ -215,6 +213,10 @@
 }
 
 .zd-content :where(pre code) {
+  /* Preserve the measured v2 code-element stack independently of the pre
+     container and inline-code tokens; its fallback metrics set line boxes. */
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas,
+    "Liberation Mono", "Courier New", monospace;
   background: transparent;
   padding: 0;
   border: none;
@@ -324,7 +326,7 @@
  * nested blocks here had no inter-element gap (zudolab/zudo-doc#2417). The
  * admonition is a narrower scope than the page flow, so a shorter gap
  * (vsp-sm < the page's vsp-md) reads as natural. Layered in `zd-flow` for the
- * same reason as the page owl: it must beat preflight's `* { margin: 0 }` but
+ * same reason as the page owl: it must beat the reset's `* { margin: 0 }` but
  * lose to an unlayered `mt-*` utility on a nested block. */
 @layer zd-flow {
   .admonition-body > :where(* + *) {

package/dist/design-token-panel-bootstrap-controller.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Design-token panel (zdtp) WIRING MECHANISM (#2658, epic Minimal Scaffold
+ * #2651). zdtp itself is LAZY-LOADED (#3282, epic
+ * #3261): this module carries NO top-level value import of `@takazudo/zdtp`
+ * whatsoever. It used to eagerly import the side-effect-free `/constants` leaf;
+ * since #4018 those constants come from the in-package mirror
+ * `./design-token-panel-constants.js`, because that one static edge made an
+ * OPTIONAL peer a hard build-time requirement for every chrome consumer
+ * (#4009 — see that module's header).
+ * On activation, the controller binds handlers and probes persisted state. The
+ * root package is `import()`ed on the first dispatch on either resolved
+ * toggle channel (the shared `toggle-design-token-panel`, or this instance's own —
+ * see the public 0.5 {@link resolveToggleEventName}), or eagerly when the
+ * persisted-state probe finds saved tweaks / a previously-open panel, so zdtp's bundle stays
+ * out of the initial page load.
+ *
+ * `bootstrapDesignTokenPanel` is a callable that configures zdtp's panel and
+ * wires its lifecycle hooks to zfb's navigation events via
+ * `setLifecycleAdapter()`. It receives a mode-scoped PanelConfig builder —
+ * either a project override or the package default from
+ * `@takazudo/zudo-doc/design-token-panel-config`. The package island imports
+ * that builder statically; it is zdtp-runtime-free (type-only zdtp imports),
+ * so the probe can compute the active storage prefix before zdtp exists.
+ *
+ * The current call shape is a mode-scoped builder. It rebuilds the panel per
+ * light/dark mode on every `color-scheme-changed` toggle:
+ *
+ *   import { bootstrapDesignTokenPanel } from "@takazudo/zudo-doc/design-token-panel-bootstrap";
+ *   import { buildDesignTokenPanelConfig } from "@/config/design-token-panel-config";
+ *   bootstrapDesignTokenPanel(buildDesignTokenPanelConfig);
+ *
+ * `design-token-panel-bootstrap-island.tsx` owns the PACKAGE-OWNED island
+ * component that wires the mode-scoped builder for every `createChrome`
+ * consumer with no host config file — the #2658 "Approach (a)" package default. Since #3396 it
+ * binds the package-default builder DIRECTLY
+ * (`./design-token-panel-config/index.js`), not the routes plugin's
+ * `virtual:zudo-doc-design-token-panel-config` module.
+ * `packages/zudo-doc/src/chrome/derive.tsx` statically imports it through the
+ * public facade so zfb's island scanner walks route → chrome → derive → facade
+ * → island entry (mirrors the DocHistory #2480 static-import contract). A host
+ * that ejects entirely can call
+ * `bootstrapDesignTokenPanel` with its own builder. Package-owned INJECTED
+ * routes do not render this component — they render the configured wrapper
+ * described below — but every other `createChrome` caller does.
+ *
+ * COUPLING REMOVED (#3396, epic #3394): this module no longer imports any
+ * `virtual:` specifier, so `@takazudo/zudo-doc/chrome` (which reaches here via
+ * `chrome/derive.tsx`) bundles OUTSIDE a zfb build with zero shims, and a
+ * `packageOwnedRoutes: false` host needs no alias for the config specifier.
+ *
+ * WHERE THE HOST OVERRIDE ENTERS NOW: `settings.designTokenPanelConfigModule`
+ * still travels through `virtual:zudo-doc-design-token-panel-config`, but the
+ * ONLY module that imports that specifier is the routes-only wrapper
+ * `routes/_design-token-panel-bootstrap.tsx`. It calls
+ * {@link runDesignTokenPanelBootstrapOnce} with the resolved builder and is
+ * threaded into `hostBindings.DesignTokenPanelBootstrap` by `routes/_chrome.tsx`,
+ * so `deriveBodyEndIslands` renders it instead of the package default on
+ * injected routes. The wrapper is a component-level seam INSIDE the client
+ * island bundle — deliberately NOT a module-level setter: the route/SSR graph
+ * and the hydrated island bundle are separate module graphs, so a setter called
+ * during route evaluation would configure only the server instance while the
+ * client re-evaluated this module and kept the default.
+ *
+ * SELF-CONTAINED `pages/` STUBS (was a KNOWN GAP in #3396; closed by #3414).
+ * A host that renders docs through a self-contained `pages/` stub (the
+ * locked-manifest shape, #2653 — it calls `createChrome` directly rather than
+ * going through `routes/_chrome.tsx`) reaches the package default here, so
+ * `designTokenPanelConfigModule` does not apply to those pages. Because
+ * {@link runDesignTokenPanelBootstrapOnce}'s latch is per SESSION, not per
+ * page, that used to make the whole SPA session's panel config depend on which
+ * page was hard-loaded first (#3406). Two things now bound it:
+ *
+ * - `chrome/derive.tsx` SKIPS this package default as the slot default when
+ *   `settings.designTokenPanelConfigModule` is set and the host supplied no
+ *   explicit `chromeBindings.DesignTokenPanelBootstrap` (and
+ *   `packageOwnedRoutes` is on). Stub-rendered pages then mount NO panel island
+ *   at all, so they can no longer win the latch with the wrong builder — the
+ *   configured island is the genuine first caller whatever the entry page. The
+ *   absence on stub pages is deliberate; such a host threads its own builder
+ *   via `chromeBindings.DesignTokenPanelBootstrap` to get a panel there too.
+ * - Any residual default-then-configured race that skip does not close warns at
+ *   runtime, naming both the setting and that workaround — see
+ *   {@link runDesignTokenPanelBootstrapOnce}.
+ *
+ * Package-first wiring landed in S9a zudolab/zudo-doc#2333; mode-scoped rebuild
+ * wiring was added in zudolab/zudo-doc#2610 and the package-default island in
+ * #2658.
+ *
+ * CSS is pulled via `@import "@takazudo/zdtp/styles.css"` in the project's
+ * `src/styles/global.css` so the panel chrome lands in the main page CSS
+ * bundle (not a deferred chunk). Vite library mode strips the source CSS
+ * import from the emitted JS, so the explicit CSS-side import is the
+ * required pull point. See @takazudo/zdtp PORTABLE-CONTRACT.md §7.
+ */
+import type { PanelConfig } from "@takazudo/zdtp";
+/** Active color-scheme mode, read from `<html data-theme>`. */
+type ColorSchemeMode = "light" | "dark";
+/**
+ * A per-mode PanelConfig factory. The package default and host overrides use
+ * this same shape so panel defaults follow the live light/dark mode.
+ */
+export type PanelConfigBuilder = (mode: ColorSchemeMode) => PanelConfig;
+/**
+ * Theme-pack storage-prefix rule (ADR theme-packs.md Decision 4), enforced
+ * CENTRALLY here — never per-builder, so host builders supplied via
+ * `designTokenPanelConfigModule` cannot cross-contaminate namespaces even if
+ * unaware of packs:
+ *
+ * - active pack `default` → the builder's `storagePrefix` stays BYTE-UNCHANGED
+ *   (the existing-user carry-over guarantee: `zudo-doc-tweak` keys keep
+ *   working on the stock look).
+ * - any other pack → `${storagePrefix}--<slug>` (double hyphen avoids
+ *   colliding with zdtp's own `-open`/version suffixes). zdtp derives every
+ *   key — including the `${prefix}-open` open-state mirror — from the prefix,
+ *   so tweaks saved under pack A are invisible under pack B and restored
+ *   verbatim on switch-back.
+ *
+ * The `PanelConfigBuilder` signature stays `(mode) => PanelConfig` — this is a
+ * post-process of the RETURNED config, not a builder-contract change.
+ */
+export declare function withPackScopedStoragePrefix(config: PanelConfig, activePack: string): PanelConfig;
+/**
+ * Bootstrap zdtp for a project — LAZILY (#3282). On activation this registers the
+ * interim toggle listener on both resolved channels (#3315), drains the
+ * pre-hydration click queue, and probes localStorage for persisted panel
+ * state; the actual
+ * `import("@takazudo/zudo-doc/zdtp-loader")` (zdtp's package-owned
+ * re-export, #4201) + configure happen on the first toggle (or
+ * immediately on a probe hit). The configure body then wires everything the
+ * pre-lazy version wired eagerly: `configurePanel` with the pack-scoped
+ * mode-config, the `color-scheme-changed` / `theme-pack-changed` rebuild
+ * listeners, `reapplyPersistedOverrides`, and the zfb lifecycle adapter via
+ * `setLifecycleAdapter`.
+ *
+ * @param buildConfig - The project's `(mode) => PanelConfig` builder for
+ *   mode-scoped rebuilds.
+ */
+export declare function bootstrapDesignTokenPanel(buildConfig: PanelConfigBuilder): void;
+/**
+ * Which island won the once-latch below (#3414).
+ *
+ * - `"default"` — the package-default island, bound
+ *   to the package-default builder.
+ * - `"configured"` — the routes-only wrapper
+ *   (`routes/_design-token-panel-bootstrap.tsx`), bound to whatever
+ *   `virtual:zudo-doc-design-token-panel-config` resolved to (a host's
+ *   `settings.designTokenPanelConfigModule` when set, the package default
+ *   otherwise).
+ */
+export type DesignTokenPanelBootstrapOrigin = "default" | "configured";
+/**
+ * Run {@link bootstrapDesignTokenPanel} at most once per module instance, with
+ * whichever mode-scoped builder the caller supplies.
+ *
+ * Exists so the routes-only configured wrapper
+ * (`routes/_design-token-panel-bootstrap.tsx`, #3396) gets the same one-shot
+ * semantics as {@link DesignTokenPanelBootstrap} while supplying the
+ * host-overridable builder from `virtual:zudo-doc-design-token-panel-config`.
+ * The guard is deliberately shared across both callers: `deriveBodyEndIslands`
+ * renders exactly ONE of them, and if a host ever mounted both, configuring the
+ * panel twice would re-mount it rather than layer the two configs.
+ *
+ * `origin` tags WHICH island is calling (#3414). It is optional, defaulting to
+ * `"default"`, because this function is reachable from the frozen
+ * `./design-token-panel-bootstrap` subpath (API.md) — an added required
+ * parameter would break an ejected host that calls it. Both in-package callers
+ * pass it explicitly.
+ *
+ * `activationSignal` is the optional owner scope's disposal signal. Disposal
+ * before configuration releases the pending once-claim; successful
+ * configuration detaches that scope and keeps the document-lifetime adapter.
+ *
+ * This is a CALL, not a module-level setter — the builder is passed by the
+ * island that activates in the client bundle, so it never has to cross the
+ * route-graph → island-bundle boundary.
+ */
+export declare function runDesignTokenPanelBootstrapOnce(build: PanelConfigBuilder, origin?: DesignTokenPanelBootstrapOrigin, activationSignal?: AbortSignal): void;
+export {};