@takazudo/zudo-doc 0.2.22 → 1.0.1

package/eject/breadcrumb/breadcrumb.tsx

@@ -0,0 +1,194 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+
+import type { ComponentChildren, VNode } from "preact";
+import { findPath } from "./find-path.js";
+import type { BreadcrumbItem, SidebarNode } from "./types.js";
+import { ChevronRight } from "../icons/index.js";
+
+/**
+ * Convert a sidebar tree + the current page's id into the ordered list
+ * of crumbs the renderer walks. The first crumb is the home rung
+ * (icon-only, label is the empty string), followed by each ancestor in
+ * the tree, ending with the current page (no `href` so the renderer
+ * paints it as plain text).
+ *
+ * Mirrors the legacy buildBreadcrumbs() behaviour from
+ * src/utils/docs.ts so the rendered output stays parity-equivalent
+ * with the original Astro breadcrumb component.
+ */
+export function buildBreadcrumbItems(
+  tree: SidebarNode[],
+  currentId: string,
+  homeHref: string,
+): BreadcrumbItem[] {
+  const items: BreadcrumbItem[] = [{ label: "", href: homeHref }];
+  const path = findPath(tree, currentId);
+  for (let i = 0; i < path.length; i++) {
+    const node = path[i];
+    if (!node) continue;
+    const isLast = i === path.length - 1;
+    items.push({
+      label: node.label,
+      href: isLast ? undefined : node.href,
+    });
+  }
+  return items;
+}
+
+interface SmartLabelProps {
+  label: string;
+}
+
+/**
+ * Inline replacement for the Astro template's `set:html` /
+ * smartBreakToHtml call. Keeps the breadcrumb self-contained inside the
+ * 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
+ * looks "path-like" (URLs, slash-separated paths, etc.). Prose labels
+ * pass through unchanged.
+ */
+function SmartLabel({ label }: SmartLabelProps): VNode | string {
+  if (!isPathLike(label)) return label;
+  const parts = label.split(DELIM_SPLIT);
+  const nodes: (string | VNode)[] = [];
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    if (!part) continue;
+    nodes.push(part);
+    if (i % 2 === 1) nodes.push(<wbr key={`wbr-${i}`} />);
+  }
+  return <>{nodes}</>;
+}
+
+const DELIM_SPLIT = /([/\\\-_.:?#&=])/;
+
+/** Heuristic copied from src/utils/smart-break.tsx — kept inline so v2
+ *  has no upward dependency. Returns true when delimiter-aware
+ *  line-break hints are useful (paths, URLs), false for prose. */
+function isPathLike(text: string): boolean {
+  if (!text) return false;
+  if (text.includes("://")) return true;
+  if (/^\.{0,2}\//.test(text)) return true;
+  if (/^[A-Za-z]:[\\/]/.test(text)) return true;
+  const forwardMatches = text.match(/[A-Za-z0-9]\/[A-Za-z0-9]/g);
+  if (forwardMatches && forwardMatches.length >= 2) return true;
+  const backMatches = text.match(/[A-Za-z0-9]\\[A-Za-z0-9]/g);
+  if (backMatches && backMatches.length >= 2) return true;
+  const hasDomainDot = /[A-Za-z0-9]\.[A-Za-z0-9]/.test(text);
+  const hasSlash = /[\\/]/.test(text);
+  if (hasDomainDot && hasSlash) return true;
+  return false;
+}
+
+function ChevronIcon(): VNode {
+  return <ChevronRight className="h-icon-xs w-icon-xs text-muted shrink-0" />;
+}
+
+function HomeIcon(): VNode {
+  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"
+      stroke="currentColor"
+      stroke-width="2"
+      aria-hidden="true"
+    >
+      <path
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        d="M3 12l2-2m0 0l7-7 7 7M5 10v10a1 1 0 001 1h3m10-11l2 2m-2-2v10a1 1 0 01-1 1h-3m-4 0a1 1 0 01-1-1v-4a1 1 0 011-1h2a1 1 0 011 1v4a1 1 0 01-1 1h-2z"
+      />
+    </svg>
+  );
+}
+
+export interface BreadcrumbProps {
+  /** Pre-built items, or omit and pass `tree` + `currentId` instead. */
+  items?: BreadcrumbItem[];
+  /** Sidebar tree to derive the trail from. Required when `items` is omitted. */
+  tree?: SidebarNode[];
+  /** Id of the current page (matches SidebarNode.id). Required when `items` is omitted. */
+  currentId?: string;
+  /** Href for the leading home rung. Defaults to "/". */
+  homeHref?: string;
+  /**
+   * Optional slot rendered at the right end of the breadcrumb row.
+   * When provided, the breadcrumb nav and this slot are wrapped in a
+   * flex row that matches the original Astro doc-layout's combined
+   * 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"
+   *
+   * The `[&_nav]:mb-0` 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;
+}
+
+/**
+ * Breadcrumb trail component.
+ *
+ * Two usage shapes:
+ *   1. Pass pre-built `items` (existing call-sites that already
+ *      compute crumbs upstream).
+ *   2. Pass `tree` + `currentId` and the component derives the trail.
+ *
+ * Returns null when no items resolve, matching the documented
+ * `items.length > 0 &&` guard.
+ */
+export function Breadcrumb(props: BreadcrumbProps): VNode | null {
+  const items =
+    props.items ??
+    (props.tree && props.currentId !== undefined
+      ? buildBreadcrumbItems(props.tree, props.currentId, props.homeHref ?? "/")
+      : []);
+
+  if (items.length === 0) return null;
+
+  const nav = (
+    <nav class="mb-vsp-md text-small" aria-label="Breadcrumb">
+      <ol class="flex flex-wrap items-center gap-x-hsp-xs">
+        {items.map((item, i) => (
+          <li key={`crumb-${i}`} class="flex items-center gap-x-hsp-xs">
+            {i > 0 && <ChevronIcon />}
+            {item.href ? (
+              <a
+                href={item.href}
+                class="text-muted underline hover:text-fg flex items-center gap-x-hsp-2xs"
+              >
+                {i === 0 && <HomeIcon />}
+                <SmartLabel label={item.label} />
+              </a>
+            ) : (
+              <span class="text-fg">
+                <SmartLabel label={item.label} />
+              </span>
+            )}
+          </li>
+        ))}
+      </ol>
+    </nav>
+  );
+
+  if (props.rightSlot === undefined) return nav;
+
+  // 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
+  // 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">
+      {nav}
+      {props.rightSlot}
+    </div>
+  );
+}

package/eject/breadcrumb/find-path.ts

@@ -0,0 +1,26 @@
+import type { BreadcrumbNode, SidebarNode } from "./types.js";
+
+/**
+ * Walk the sidebar tree and return the chain of nodes from the root
+ * level down to (and including) the node whose `id` matches `targetId`.
+ *
+ * Returns an empty array when no node matches. Pure: never mutates the
+ * input tree, never reads anything outside of it.
+ *
+ * Used by the breadcrumb component to derive the current page's
+ * ancestry. The home/root crumb is the renderer's responsibility — this
+ * helper deals strictly with the tree itself.
+ */
+export function findPath<T extends BreadcrumbNode = SidebarNode>(
+  nodes: readonly T[],
+  targetId: string,
+): T[] {
+  for (const node of nodes) {
+    if (node.id === targetId) return [node];
+    if (node.children && node.children.length > 0) {
+      const sub = findPath(node.children as readonly T[], targetId);
+      if (sub.length > 0) return [node, ...sub];
+    }
+  }
+  return [];
+}

package/eject/breadcrumb/index.ts

@@ -0,0 +1,4 @@
+export { Breadcrumb, buildBreadcrumbItems } from "./breadcrumb.js";
+export type { BreadcrumbProps } from "./breadcrumb.js";
+export { findPath } from "./find-path.js";
+export type { BreadcrumbItem, SidebarNode } from "./types.js";

package/eject/breadcrumb/types.ts

@@ -0,0 +1,32 @@
+/**
+ * Type contract for the breadcrumb component.
+ *
+ * Breadcrumb only walks the tree to find an ancestor chain — it does not
+ * need the full SidebarNode shape from sidebar-tree. We declare a minimal
+ * structural interface here. The canonical SidebarNode (from sidebar-tree)
+ * is structurally assignable to this, so callers can pass either shape
+ * unchanged.
+ */
+export interface BreadcrumbNode {
+  type: "doc" | "category";
+  id: string;
+  label: string;
+  href?: string;
+  sidebar_position?: number;
+  children?: readonly BreadcrumbNode[];
+}
+
+/**
+ * Backward-compatible alias retained for callers that previously imported
+ * `SidebarNode` from this subpath.
+ */
+export type SidebarNode = BreadcrumbNode;
+
+/**
+ * One rung of the breadcrumb trail. `href` is omitted on the final
+ * (current-page) item so the renderer can present it as plain text.
+ */
+export interface BreadcrumbItem {
+  label: string;
+  href?: string;
+}

package/eject/code-group/index.tsx

@@ -0,0 +1,78 @@
+/** @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).
+//
+// zfb emits:
+//   <CodeGroup tabs={["label1", "label2", ...]}>
+//     <pre data-lang="ts">{RAW code text}</pre>
+//     <pre data-lang="js">{RAW code text}</pre>
+//   </CodeGroup>
+//
+// The existing <Tabs>/<TabItem> UI uses a children-based API, so this
+// component zips the `tabs` label array with the `<pre data-lang>` children
+// by index, wrapping each in a <TabItem> with the matching label.
+//
+// Code inside each <pre> is raw text (NOT syntect-highlighted — the Rust
+// pipeline does not run highlight inside code-group fences). We render
+// the <pre> inside a <TabItem> with explicit styling via Tailwind tokens
+// so it looks like a code block visually.
+//
+// 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 { Tabs } from "../code-syntax/index.js";
+import { TabItem } from "../tab-item/index.js";
+
+type Props = {
+  tabs?: string[];
+  children?: ComponentChildren;
+  [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);
+
+  // Zip tabs labels with pre children by index. Extra children beyond the
+  // tabs array (shouldn't happen in normal zfb output) are ignored.
+  const items = tabs.map((label, i) => {
+    const child = childArray[i];
+    return { label, child };
+  });
+
+  if (items.length === 0) {
+    // Degenerate: no tabs — render children as-is.
+    return <>{children}</>;
+  }
+
+  // zfb forwards `:::code-group{name="x"}` as the `name` prop; Tabs persists
+  // the active tab per group via `groupId`.
+  const groupId = typeof name === "string" ? name : undefined;
+
+  return (
+    <Tabs groupId={groupId}>
+      {items.map(({ label, child }, i) => (
+        // value is suffixed with the index so two fences sharing a label
+        // (e.g. both titled "ts") get distinct stable tab identities; the
+        // label stays the visible text.
+        <TabItem
+          key={`${label}-${i}`}
+          label={label}
+          value={`${label}-${i}`}
+          default={i === 0 ? true : undefined}
+        >
+          {/* Raw-code <pre> from zfb: apply code-block visual treatment via tokens */}
+          <div class="code-group-panel">{child}</div>
+        </TabItem>
+      ))}
+    </Tabs>
+  );
+}

package/eject/content-admonition/index.tsx

@@ -0,0 +1,50 @@
+/** @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>">
+//     <p class="admonition-title">…</p>
+//     <div class="admonition-body">…</div>
+//   </div>
+// is the hook both the design-system CSS (`.admonition-<variant>` rules in
+// 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";
+
+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;
+}
+
+/**
+ * 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 function makeAdmonition(variant: AdmonitionVariant) {
+  const defaultTitle = variant.charAt(0).toUpperCase() + variant.slice(1);
+  return function Admonition({ title, children }: AdmonitionProps): VNode {
+    const heading = title && title.length > 0 ? title : defaultTitle;
+    return (
+      <div data-admonition={variant} class={`admonition admonition-${variant}`}>
+        <p class="admonition-title">{heading}</p>
+        <div class="admonition-body">{children}</div>
+      </div>
+    );
+  };
+}

package/eject/details/details.tsx

@@ -0,0 +1,34 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+
+import type { ComponentChildren, VNode } from "preact";
+
+export interface DetailsProps {
+  /**
+   * Summary / toggle label shown in the `<summary>` element.
+   * Defaults to `"Details"` — the same fallback used by the legacy
+   * `src/components/details`.
+   */
+  title?: string;
+  /** Slot content rendered inside the collapsed body. */
+  children?: ComponentChildren;
+}
+
+/**
+ * Collapsible `<details>` / `<summary>` block — JSX port of
+ * `src/components/details`.
+ *
+ * Keeps layout and token classes identical to the original template.
+ * The legacy component used Astro's `<slot />`; v2 accepts standard
+ * Preact `children`.
+ */
+export function Details({ title = "Details", children }: DetailsProps): VNode {
+  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">
+        {title}
+      </summary>
+      <div class="px-hsp-lg py-vsp-sm zd-content">{children}</div>
+    </details>
+  );
+}

package/eject/details/index.ts

@@ -0,0 +1,4 @@
+// Barrel for the details topic — JSX port of
+// `src/components/details`.
+export { Details } from "./details.js";
+export type { DetailsProps } from "./details.js";

package/eject/doc-pager/index.tsx

@@ -0,0 +1,91 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// doc-pager — factory for the shared prev/next pager <nav> (epic #2344, S7).
+//
+// The host's `pages/lib/_doc-pager.tsx` previously read the `t` function
+// from `@/config/i18n` at module scope. This factory receives `t` as an
+// injected dependency so the logic lives in the package while the host stub
+// keeps the singleton imports.
+
+import type { JSX } from "preact";
+import { ChevronLeft, ChevronRight } from "../icons/index.js";
+
+// NavNode is a superset; we only need the fields the pager uses.
+interface PagerNode {
+  href?: string;
+  label: string;
+}
+
+export interface DocPagerProps {
+  /** Previous page node (null = no previous page → renders placeholder). */
+  prev: PagerNode | null;
+  /** Next page node (null = no next page → renders placeholder). */
+  next: PagerNode | null;
+  /** Active locale for translated "Previous" / "Next" labels. */
+  locale: string;
+}
+
+/** Dependencies injected by the host stub. */
+export interface DocPagerDeps {
+  /** Translate a UI string key for a locale. */
+  t: (key: string, locale: string) => string;
+}
+
+/**
+ * Create a `DocPager` component bound to the host's injected `t` translator.
+ */
+export function createDocPager(
+  deps: DocPagerDeps,
+): (props: DocPagerProps) => JSX.Element {
+  const { t } = deps;
+
+  /**
+   * Prev/next pagination nav shared by all four doc-route page components.
+   *
+   * Renders a two-column grid: prev card on the left, next card on the right.
+   * When a node is absent its slot is filled with an empty `<div>` to maintain
+   * the two-column layout. Placement: immediately after MDX content, before
+   * `DocHistoryArea` (Astro reference order — content → pager → utilities,
+   * per #1535).
+   */
+  function DocPager({ prev, next, locale }: DocPagerProps): JSX.Element {
+    return (
+      <nav class="mt-vsp-2xl grid grid-cols-2 gap-hsp-xl">
+        {prev ? (
+          <a
+            href={prev.href}
+            class="group border border-muted rounded-lg p-hsp-lg hover:border-accent"
+          >
+            <div class="flex items-center gap-hsp-xs text-caption text-muted mb-vsp-2xs">
+              <ChevronLeft className="h-[1.125rem] w-[1.125rem]" />
+              <span class="no-underline">{t("nav.previous", locale)}</span>
+            </div>
+            <p class="text-small font-semibold underline group-hover:text-accent">
+              {prev.label}
+            </p>
+          </a>
+        ) : (
+          <div />
+        )}
+        {next ? (
+          <a
+            href={next.href}
+            class="group border border-muted rounded-lg p-hsp-lg hover:border-accent text-right"
+          >
+            <div class="flex items-center justify-end gap-hsp-xs text-caption text-muted mb-vsp-2xs">
+              <span class="no-underline">{t("nav.next", locale)}</span>
+              <ChevronRight className="h-[1.125rem] w-[1.125rem]" />
+            </div>
+            <p class="text-small font-semibold underline group-hover:text-accent">
+              {next.label}
+            </p>
+          </a>
+        ) : (
+          <div />
+        )}
+      </nav>
+    );
+  }
+
+  return DocPager;
+}