@takazudo/zudo-doc 0.2.21 → 1.0.0

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;
+}

package/eject/footer/footer.tsx

@@ -0,0 +1,167 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+
+// Footer presentational shell for the documentation layout.
+//
+// The original template mixed data-prep (settings + getDocsCollection
+// + tag-vocabulary lookups + locale overrides) with the presentational
+// footer markup. Because v2 must stay decoupled from host-only helpers,
+// only the presentational shell lives here: callers prepare the
+// already-localized, already-resolved data upstream and feed it in via
+// `linkColumns` / `tagColumns` / `copyright` props.
+//
+// Behaviour parity notes:
+//
+//  - The `<footer>` shell is always rendered — even when all three slots
+//    are empty — so the contentinfo ARIA landmark is present on every
+//    page regardless of whether link columns or copyright are configured.
+//    (The original Astro template returned early when `!footer`; that
+//    guard lives in the host-side `FooterWithDefaults` wrapper in
+//    `pages/lib/footer-with-defaults.tsx` now.)
+//
+//  - The link/tag column grid is only emitted when at least one column is
+//    present (mirrors the Astro `hasColumns &&` guard).
+//
+//  - The copyright block is rendered as-is via `dangerouslySetInnerHTML`
+//    because the original template used `<Fragment set:html={copyright} />`
+//    to allow inline anchors. Callers are responsible for sanitising
+//    the string (the Astro version did the same — it trusted
+//    `settings.footer.copyright`).
+//
+//  - When both columns and copyright exist, the copyright block is
+//    visually separated by a top border + spacing, identical to the
+//    `mt-vsp-lg border-t border-muted pt-vsp-md` that the Astro template
+//    applied via `class:list` conditional.
+
+import type { VNode } from "preact";
+
+import type { FooterLinkColumn, FooterTagColumn } from "./types.js";
+
+export interface FooterProps {
+  /**
+   * Already-localized link columns. Each item's href should be
+   * base-prefixed and locale-aware; `isExternal` controls the
+   * target/rel attributes.
+   */
+  linkColumns?: FooterLinkColumn[];
+  /**
+   * Already-resolved tag columns. Empty array (or omitted) hides the
+   * taglist entirely. Each tag's href should already be base-prefixed.
+   */
+  tagColumns?: FooterTagColumn[];
+  /**
+   * Copyright HTML. Rendered via `dangerouslySetInnerHTML` so embedded
+   * anchors work. The caller is responsible for the contents.
+   */
+  copyright?: string;
+  /**
+   * When provided, adds `data-zfb-transition-persist` to the `<footer>`
+   * element. Use a locale-keyed value (e.g. `footer-en`, `footer-ja`) so
+   * cross-locale swaps discard the stale footer while same-locale swaps
+   * preserve DOM-node identity. See zudolab/zudo-doc#1546.
+   */
+  persistKey?: string;
+}
+
+/**
+ * Footer shell for the documentation layout.
+ *
+ * Always renders the `<footer>` shell so the contentinfo ARIA landmark
+ * is present on every page — even when no columns or copyright are
+ * configured. The inner content (link grid, copyright) is only emitted
+ * when the respective slots carry data.
+ */
+export function Footer(props: FooterProps): VNode {
+  const linkColumns = props.linkColumns ?? [];
+  const tagColumns = props.tagColumns ?? [];
+  const copyright = props.copyright ?? "";
+  const persistKey = props.persistKey;
+
+  const hasColumns = linkColumns.length > 0 || tagColumns.length > 0;
+  const hasCopyright = copyright.length > 0;
+
+  const copyrightClass = hasColumns
+    ? "text-center text-caption text-muted [&_a]:text-accent [&_a]:underline mt-vsp-lg border-t border-muted pt-vsp-md"
+    : "text-center text-caption text-muted [&_a]:text-accent [&_a]:underline";
+
+  return (
+    <footer
+      class="border-t border-muted bg-surface"
+      // Strategy B: locale-keyed persist (zudolab/zudo-doc#1546).
+      // The footer's locale-aware bits (link labels, copyright) are SSR'd
+      // per locale; a locale-keyed persist key (`footer-en`, `footer-ja`)
+      // guarantees cross-locale swaps re-render the footer while
+      // same-locale swaps preserve DOM-node identity (safe — footer
+      // content is invariant page-to-page within a locale).
+      {...(persistKey
+        ? { "data-zfb-transition-persist": persistKey }
+        : {})}
+    >
+      <div class="mx-auto max-w-[clamp(50rem,75vw,90rem)] px-hsp-xl py-vsp-xl lg:px-hsp-2xl lg:py-vsp-2xl">
+        {hasColumns && (
+          <div class="grid grid-cols-1 gap-vsp-lg sm:grid-cols-2 lg:grid-cols-[repeat(auto-fit,minmax(12rem,1fr))]">
+            {linkColumns.map((column, i) => (
+              <div key={`link-${i}-${column.title}`}>
+                <p class="text-small font-semibold text-fg mb-vsp-xs">
+                  {column.title}
+                </p>
+                <ul class="list-none p-0">
+                  {column.items.map((item, j) => (
+                    <li
+                      key={`item-${i}-${j}-${item.href}`}
+                      class="mb-vsp-2xs"
+                    >
+                      <a
+                        href={item.href}
+                        class="text-caption text-muted hover:text-accent hover:underline focus-visible:underline"
+                        {...(item.isExternal
+                          ? {
+                              target: "_blank",
+                              rel: "noopener noreferrer",
+                            }
+                          : {})}
+                      >
+                        {item.label}
+                      </a>
+                    </li>
+                  ))}
+                </ul>
+              </div>
+            ))}
+            {tagColumns.map((column, i) => (
+              <div
+                key={`tag-${i}-${column.group}`}
+                data-taglist-group={column.group}
+              >
+                <h2 class="text-small font-semibold text-fg mb-vsp-xs">
+                  {column.title}
+                </h2>
+                <ul class="list-none p-0">
+                  {column.tags.map(({ tag, count, href }) => (
+                    <li key={`tag-item-${tag}`} class="mb-vsp-2xs">
+                      <a
+                        href={href}
+                        class="text-caption text-muted hover:text-accent hover:underline focus-visible:underline"
+                      >
+                        #{tag}
+                        <span class="opacity-60" aria-hidden="true">
+                          &nbsp;({count})
+                        </span>
+                      </a>
+                    </li>
+                  ))}
+                </ul>
+              </div>
+            ))}
+          </div>
+        )}
+        {hasCopyright && (
+          <div
+            class={copyrightClass}
+            dangerouslySetInnerHTML={{ __html: copyright }}
+          />
+        )}
+      </div>
+    </footer>
+  );
+}

package/eject/footer/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Public entry for the framework-agnostic footer shell.
+ *
+ * Consumers import from `@takazudo/zudo-doc/footer`:
+ *
+ *   import { Footer, type FooterProps } from "@takazudo/zudo-doc/footer";
+ *
+ * The shell is purely presentational — see `./types.ts` for the data
+ * shapes the host project assembles upstream.
+ */
+
+export { Footer } from "./footer.js";
+export type { FooterProps } from "./footer.js";
+export type {
+  FooterLinkColumn,
+  FooterLinkItem,
+  FooterTagColumn,
+  FooterTagItem,
+} from "./types.js";

package/eject/footer/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Public types for the framework-agnostic footer shell.
+ *
+ * The original footer template mixed three concerns:
+ *   1. Reading `settings.footer` and applying locale overrides.
+ *   2. Loading the docs collection + tag vocabulary to build the
+ *      optional taglist columns.
+ *   3. Rendering the footer markup.
+ *
+ * Concerns (1) and (2) depend on host-side helpers (`@/config/settings`,
+ * `@/utils/get-docs-collection`, `tag-vocabulary`, etc.) that v2 must
+ * not reach into. So this package only ports concern (3): the
+ * presentational shell. Callers prepare the columns upstream and pass
+ * already-localized, already-resolved hrefs in.
+ */
+
+/** A single link rendered inside a {@link FooterLinkColumn}. */
+export interface FooterLinkItem {
+  /** Visible label (already locale-resolved by the caller). */
+  label: string;
+  /** Resolved href (already base-prefixed and locale-aware). */
+  href: string;
+  /**
+   * When true, the rendered anchor adds `target="_blank"` and
+   * `rel="noopener noreferrer"`. Callers compute this from their own
+   * external-href detector.
+   */
+  isExternal?: boolean;
+}
+
+/** One column in the footer's link grid. */
+export interface FooterLinkColumn {
+  /** Visible heading for the column (already locale-resolved). */
+  title: string;
+  items: FooterLinkItem[];
+}
+
+/** A single tag rendered inside a {@link FooterTagColumn}. */
+export interface FooterTagItem {
+  /** Canonical tag id (rendered as `#<tag>`). */
+  tag: string;
+  /** Document count shown next to the tag. */
+  count: number;
+  /** Resolved href to the tag's index page. */
+  href: string;
+}
+
+/** One column in the footer's tag grid. */
+export interface FooterTagColumn {
+  /**
+   * Group identifier — usually a vocabulary group name like `"topic"`,
+   * or the literal `"__flat__"` sentinel for the ungrouped/flat column.
+   * Surfaced as `data-taglist-group` on the rendered column wrapper so
+   * downstream tests / e2e selectors keep working.
+   */
+  group: string;
+  /** Visible heading for the column (already locale-resolved). */
+  title: string;
+  tags: FooterTagItem[];
+}