@takazudo/zudo-doc 5.8.0 → 5.10.0

package/dist/mdx-components/index.d.ts

@@ -2,7 +2,7 @@ import type { Settings } from "../settings.js";
 /** Any Preact-renderable component (function returning a VNode/children). */
 type AnyComponent = (props: Record<string, unknown>) => unknown;
 /**
- * The 4 host-supplied, locale-aware nav wrappers. Each accepts a `lang` prop;
+ * The host-supplied, locale-aware nav wrappers. Each accepts a `lang` prop;
  * the factory injects the active `locale` so the wrapper queries the correct
  * collection. `SiteTreeNav` is reused for both the `SiteTreeNav` and
  * `SiteTreeNavDemo` MDX tags (matching the showcase mapping).
@@ -11,6 +11,7 @@ export interface MdxNavData {
     CategoryNav: AnyComponent;
     CategoryTreeNav: AnyComponent;
     SiteTreeNav: AnyComponent;
+    NoteTrayIndex: AnyComponent;
 }
 export interface CreateMdxComponentsOptions {
     /**
@@ -35,6 +36,8 @@ export interface CreateMdxComponentsOptions {
      * which wrapper `navData` holds.
      */
     currentVersion?: string;
+    /** Canonical slug of the page being rendered, used to infer its containing note tray. */
+    currentSlug: string;
     /** Host-supplied locale-aware nav wrappers. */
     navData: MdxNavData;
     /**

package/dist/mdx-components/index.js

@@ -109,7 +109,7 @@ function makeEnlargeableParagraph(imageEnlarge, ContentImg) {
   };
 }
 function createMdxComponents(options) {
-  const { settings, locale, currentVersion, navData, extras } = options;
+  const { settings, locale, currentVersion, currentSlug, navData, extras } = options;
   const ContentImg = makeContentImg(settings.base);
   const EnlargeableParagraph = makeEnlargeableParagraph(
     settings.imageEnlarge,
@@ -118,6 +118,7 @@ function createMdxComponents(options) {
   const CategoryNavBound = (props) => navData.CategoryNav({ ...props, lang: locale, currentVersion });
   const CategoryTreeNavBound = (props) => navData.CategoryTreeNav({ ...props, lang: locale, currentVersion });
   const SiteTreeNavBound = (props) => navData.SiteTreeNav({ ...props, lang: locale, currentVersion });
+  const NoteTrayIndexBound = (props) => navData.NoteTrayIndex({ ...props, lang: locale, currentVersion, currentSlug });
   return {
     ...defaultComponents,
     // img override: rewrites root-relative src to include settings.base.
@@ -151,6 +152,7 @@ function createMdxComponents(options) {
     CategoryTreeNav: CategoryTreeNavBound,
     SiteTreeNav: SiteTreeNavBound,
     SiteTreeNavDemo: SiteTreeNavBound,
+    NoteTrayIndex: NoteTrayIndexBound,
     // Host extras win over any same-named default above (Details, HtmlPreview,
     // Island, PresetGenerator, showcase stubs, etc.).
     ...extras ?? {}

package/dist/nav-indexing/index.d.ts

@@ -34,4 +34,6 @@ export { DocCardGrid } from "./doc-card-grid.js";
 export type { DocCardGridProps, DocCardItem } from "./doc-card-grid.js";
 export { VersionsPageContent } from "./versions-page-content.js";
 export type { VersionsPageContentProps } from "./versions-page-content.js";
+export { NoteTrayIndex } from "./note-tray-index.js";
+export type { NoteTrayIndexItem, NoteTrayIndexProps, NoteTrayIndexStyle, } from "./note-tray-index.js";
 export type { NavNode, TagItem, TagLink, TagNavLabels, VersionPageEntry, VersionsPageLabels, } from "./types.js";

package/dist/nav-indexing/index.js

@@ -6,12 +6,14 @@ import { DocsSitemap } from "./docs-sitemap.js";
 import { NavCardGrid } from "./nav-card-grid.js";
 import { DocCardGrid } from "./doc-card-grid.js";
 import { VersionsPageContent } from "./versions-page-content.js";
+import { NoteTrayIndex } from "./note-tray-index.js";
 export {
   CategoryNav,
   CategoryTreeNav,
   DocCardGrid,
   DocsSitemap,
   NavCardGrid,
+  NoteTrayIndex,
   SiteTreeNavDemo,
   TagNav,
   VersionsPageContent

package/dist/nav-indexing/note-tray-index.d.ts

@@ -0,0 +1,29 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { JSX } from "preact";
+import { type NoteTrayOrder } from "../note-tray-model/index.js";
+import type { TagLink, TagNavLabels } from "./types.js";
+export type NoteTrayIndexStyle = "index" | "cards" | "timeline";
+export interface NoteTrayIndexItem {
+    slug: string;
+    label: string;
+    description?: string;
+    href?: string;
+    hasPage?: boolean;
+    children: NoteTrayIndexItem[];
+    rank?: number;
+    date?: string;
+    updated?: string;
+    tagLinks?: TagLink[];
+}
+export interface NoteTrayIndexProps {
+    items: NoteTrayIndexItem[];
+    style?: NoteTrayIndexStyle;
+    showDate?: boolean;
+    locale: string;
+    updatedLabel: string;
+    dated: boolean;
+    order?: NoteTrayOrder;
+    tagLabels?: TagNavLabels;
+}
+export declare function NoteTrayIndex(props: NoteTrayIndexProps): JSX.Element | null;

package/dist/nav-indexing/note-tray-index.js

@@ -0,0 +1,120 @@
+import { jsx, jsxs } from "preact/jsx-runtime";
+import {
+  formatDate,
+  formatYearMonthLabel,
+  groupItems,
+  rankWidth
+} from "../note-tray-model/index.js";
+import { TagNav } from "./tag-nav.js";
+function DateLine({
+  item,
+  locale,
+  updatedLabel
+}) {
+  if (!item.date && !item.updated) return null;
+  return /* @__PURE__ */ jsxs("span", { class: "tabular-nums text-caption text-muted", children: [
+    item.date && /* @__PURE__ */ jsx("time", { datetime: item.date, children: formatDate(item.date, locale) }),
+    item.date && item.updated && /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: " \xB7 " }),
+    item.updated && /* @__PURE__ */ jsxs("span", { children: [
+      updatedLabel,
+      " ",
+      /* @__PURE__ */ jsx("time", { datetime: item.updated, children: formatDate(item.updated, locale) })
+    ] })
+  ] });
+}
+function ItemTags({ item, labels }) {
+  if (!labels || !item.tagLinks?.length) return null;
+  return /* @__PURE__ */ jsx(TagNav, { variant: "page", tagLinks: item.tagLinks, labels });
+}
+function IndexList(props) {
+  const width = rankWidth(props.items);
+  return /* @__PURE__ */ jsx("ol", { class: "border-t border-muted", children: props.items.map((item) => /* @__PURE__ */ jsxs(
+    "li",
+    {
+      class: "grid grid-cols-[auto_1fr] gap-x-hsp-lg border-b border-muted py-vsp-md",
+      children: [
+        /* @__PURE__ */ jsx(
+          "span",
+          {
+            class: "tabular-nums text-heading leading-none text-muted",
+            style: { width: `${width}ch` },
+            children: item.rank === void 0 ? "" : String(item.rank).padStart(width, "0")
+          }
+        ),
+        /* @__PURE__ */ jsxs("div", { class: "min-w-0", children: [
+          item.href ? /* @__PURE__ */ jsx(
+            "a",
+            {
+              class: "font-medium text-fg hover:text-accent hover:underline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent",
+              href: item.href,
+              children: item.label
+            }
+          ) : /* @__PURE__ */ jsx("span", { class: "font-medium text-fg", children: item.label }),
+          item.description && /* @__PURE__ */ jsx("p", { class: "mt-vsp-2xs text-small text-muted", children: item.description }),
+          props.showDate && /* @__PURE__ */ jsx("span", { class: "mt-vsp-2xs block", children: /* @__PURE__ */ jsx(DateLine, { item, locale: props.locale, updatedLabel: props.updatedLabel }) })
+        ] })
+      ]
+    },
+    item.slug
+  )) });
+}
+function CardList(props) {
+  return /* @__PURE__ */ jsx("div", { class: "grid grid-cols-1 gap-vsp-md", children: props.items.map((item) => /* @__PURE__ */ jsxs("article", { class: "rounded border border-muted bg-surface px-hsp-xl py-vsp-lg", children: [
+    props.showDate && /* @__PURE__ */ jsx("div", { class: "mb-vsp-xs", children: /* @__PURE__ */ jsx(DateLine, { item, locale: props.locale, updatedLabel: props.updatedLabel }) }),
+    /* @__PURE__ */ jsx("h2", { class: "text-title font-medium", children: item.href ? /* @__PURE__ */ jsx(
+      "a",
+      {
+        class: "text-fg hover:text-accent hover:underline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent",
+        href: item.href,
+        children: item.label
+      }
+    ) : item.label }),
+    item.description && /* @__PURE__ */ jsx("p", { class: "mt-vsp-xs text-muted", children: item.description }),
+    item.tagLinks?.length ? /* @__PURE__ */ jsx("div", { class: "mt-vsp-md", children: /* @__PURE__ */ jsx(ItemTags, { item, labels: props.tagLabels }) }) : null
+  ] }, item.slug)) });
+}
+function Timeline(props) {
+  const groups = groupItems(props.items, "month", props.order ?? "asc");
+  return /* @__PURE__ */ jsx("div", { class: "space-y-vsp-lg", children: groups.map((group) => /* @__PURE__ */ jsxs("section", { children: [
+    /* @__PURE__ */ jsx("h2", { class: "mb-vsp-sm text-small font-medium text-fg", children: formatYearMonthLabel(group.key, props.locale) }),
+    /* @__PURE__ */ jsx("ol", { class: "ml-hsp-xs border-l border-muted", children: group.items.map((item) => /* @__PURE__ */ jsxs("li", { class: "relative grid gap-vsp-2xs pb-vsp-lg pl-hsp-lg last:pb-0", children: [
+      /* @__PURE__ */ jsx(
+        "span",
+        {
+          class: "absolute -left-hsp-xs top-vsp-2xs size-icon-xs rounded-full border border-bg bg-muted",
+          "aria-hidden": "true"
+        }
+      ),
+      /* @__PURE__ */ jsxs("div", { class: "flex flex-wrap items-baseline gap-x-hsp-sm gap-y-vsp-2xs", children: [
+        /* @__PURE__ */ jsx(DateLine, { item, locale: props.locale, updatedLabel: props.updatedLabel }),
+        item.href ? /* @__PURE__ */ jsx(
+          "a",
+          {
+            class: "font-medium text-fg hover:text-accent hover:underline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent",
+            href: item.href,
+            children: item.label
+          }
+        ) : /* @__PURE__ */ jsx("span", { class: "font-medium text-fg", children: item.label })
+      ] }),
+      item.description && /* @__PURE__ */ jsx("p", { class: "text-small text-muted", children: item.description }),
+      /* @__PURE__ */ jsx(ItemTags, { item, labels: props.tagLabels })
+    ] }, item.slug)) })
+  ] }, group.key)) });
+}
+function NoteTrayIndex(props) {
+  if (props.items.length === 0) return null;
+  if (props.style === "timeline" && !props.dated) {
+    throw new Error('[zudo-doc] <NoteTrayIndex style="timeline"> requires a dated note tray.');
+  }
+  switch (props.style ?? "index") {
+    case "cards":
+      return /* @__PURE__ */ jsx(CardList, { ...props });
+    case "timeline":
+      return /* @__PURE__ */ jsx(Timeline, { ...props });
+    default:
+      return /* @__PURE__ */ jsx(IndexList, { ...props });
+  }
+}
+export {
+  NoteTrayIndex
+};

package/dist/note-tray-index/index.d.ts

@@ -0,0 +1,45 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { JSX } from "preact";
+import { type NoteTrayIndexItem, type NoteTrayIndexStyle } from "../nav-indexing/index.js";
+export interface NoteTrayIndexNode extends NoteTrayIndexItem {
+    shape?: "note-tray";
+    sortOrder?: "asc" | "desc";
+    noteTrayDated?: boolean;
+    children: NoteTrayIndexNode[];
+}
+export interface NoteTrayIndexDoc {
+    slug: string;
+    data: {
+        slug?: string;
+        tags?: string[];
+    };
+}
+export interface NoteTrayIndexSource {
+    navDocs: NoteTrayIndexDoc[];
+    categoryMeta: Map<string, unknown>;
+}
+export interface NoteTrayIndexWrapperProps {
+    style?: NoteTrayIndexStyle;
+    showDate?: boolean;
+    category?: string;
+    lang?: string;
+    currentVersion?: string;
+    currentSlug?: string;
+}
+export interface NoteTrayIndexDeps {
+    defaultLocale: string;
+    docTags: boolean;
+    resolveNavSource: (lang: string, currentVersion: string | undefined, options?: {
+        applyDefaultLocaleOnlyFilter?: boolean;
+        keepUnlisted?: boolean;
+    }) => NoteTrayIndexSource;
+    buildNavTree: (docs: NoteTrayIndexDoc[], locale: string, categoryMeta: Map<string, unknown>) => NoteTrayIndexNode[];
+    findNode: (tree: NoteTrayIndexNode[], slug: string) => NoteTrayIndexNode | undefined;
+    toRouteSlug: (slug: string) => string;
+    resolveTag: (raw: string) => string;
+    tagHref: (tag: string, locale: string) => string;
+    t: (key: string, locale: string) => string;
+    versionedDocsUrl: (slug: string, versionSlug: string, lang: string) => string;
+}
+export declare function createNoteTrayIndexWrapper(deps: NoteTrayIndexDeps): (props: NoteTrayIndexWrapperProps) => JSX.Element | null;

package/dist/note-tray-index/index.js

@@ -0,0 +1,52 @@
+import { jsx } from "preact/jsx-runtime";
+import { remapVersionedHrefs } from "../nav-data-prep/index.js";
+import {
+  NoteTrayIndex
+} from "../nav-indexing/index.js";
+import { findContainingNoteTray, getNoteTrayItems } from "../note-tray-model/index.js";
+function createNoteTrayIndexWrapper(deps) {
+  return function NoteTrayIndexWrapper({
+    style = "index",
+    showDate = false,
+    category,
+    lang = deps.defaultLocale,
+    currentVersion,
+    currentSlug
+  }) {
+    const source = deps.resolveNavSource(lang, currentVersion, { keepUnlisted: true });
+    const rawTree = deps.buildNavTree(source.navDocs, lang, source.categoryMeta);
+    const tree = currentVersion ? remapVersionedHrefs(rawTree, currentVersion, lang, deps.versionedDocsUrl) : rawTree;
+    const tray = category ? deps.findNode(tree, category) : currentSlug ? findContainingNoteTray(tree, currentSlug) : void 0;
+    if (!tray || tray.shape !== "note-tray") return null;
+    const docsBySlug = new Map(
+      source.navDocs.map((doc) => [doc.data.slug ?? deps.toRouteSlug(doc.slug), doc])
+    );
+    const items = getNoteTrayItems(tray).map((item) => {
+      const rawTags = docsBySlug.get(item.slug)?.data.tags ?? [];
+      const tags = [...new Set(rawTags.map(deps.resolveTag))];
+      return {
+        ...item,
+        tagLinks: deps.docTags ? tags.map((tag) => ({ tag, href: deps.tagHref(tag, lang) })) : void 0
+      };
+    });
+    return /* @__PURE__ */ jsx(
+      NoteTrayIndex,
+      {
+        items,
+        style,
+        showDate,
+        locale: lang,
+        updatedLabel: deps.t("doc.updated", lang),
+        dated: tray.noteTrayDated === true,
+        order: tray.sortOrder ?? "asc",
+        tagLabels: {
+          tags: deps.t("doc.tags", lang),
+          taggedWith: deps.t("doc.taggedWith", lang)
+        }
+      }
+    );
+  };
+}
+export {
+  createNoteTrayIndexWrapper
+};

package/dist/note-tray-model/index.d.ts

@@ -0,0 +1,31 @@
+import { formatDate, parseIsoDate, type IsoDateParts } from "../format-date/index.js";
+export { formatDate, parseIsoDate };
+export type { IsoDateParts };
+export type NoteTrayOrder = "asc" | "desc";
+export type NoteTrayGrouping = "year" | "month";
+/** Minimal structural node accepted by every note-tray consumer. */
+export interface NoteTrayNode {
+    slug: string;
+    shape?: "note-tray";
+    hasPage?: boolean;
+    sortOrder?: NoteTrayOrder;
+    rank?: number;
+    date?: string;
+    children: NoteTrayNode[];
+}
+export interface NoteTrayGroup<T extends NoteTrayNode = NoteTrayNode> {
+    key: string;
+    items: T[];
+}
+export declare function findNoteTray<T extends NoteTrayNode>(tree: readonly T[], slug: string): T | undefined;
+/** Find the tray whose slug is the longest prefix of a page slug. */
+export declare function findContainingNoteTray<T extends NoteTrayNode>(tree: readonly T[], pageSlug: string): T | undefined;
+/** Direct routed children are the items in a valid (flat) tray. */
+export declare function getNoteTrayItems<T extends NoteTrayNode>(tray: T): T[];
+/** Rank labels use at least two digits: 01..99, then widen with item count. */
+export declare function rankWidth(itemsOrCount: readonly unknown[] | number): number;
+export declare function yearKey(iso: string): string;
+export declare function yearMonthKey(iso: string): string;
+export declare function formatYearMonthLabel(isoOrKey: string, locale: string): string;
+/** Group dated items chronologically and keep rank order within each group. */
+export declare function groupItems<T extends NoteTrayNode>(items: readonly T[], grouping: NoteTrayGrouping, order: NoteTrayOrder): NoteTrayGroup<T>[];

package/dist/note-tray-model/index.js

@@ -0,0 +1,74 @@
+import {
+  formatDate,
+  formatYearMonth,
+  parseIsoDate
+} from "../format-date/index.js";
+function findNoteTray(tree, slug) {
+  for (const node of tree) {
+    if (node.slug === slug && node.shape === "note-tray") return node;
+    const found = findNoteTray(node.children, slug);
+    if (found) return found;
+  }
+  return void 0;
+}
+function findContainingNoteTray(tree, pageSlug) {
+  let found;
+  const visit = (nodes) => {
+    for (const node of nodes) {
+      if (node.shape === "note-tray" && (pageSlug === node.slug || pageSlug.startsWith(`${node.slug}/`)) && (!found || node.slug.length > found.slug.length)) {
+        found = node;
+      }
+      visit(node.children);
+    }
+  };
+  visit(tree);
+  return found;
+}
+function getNoteTrayItems(tray) {
+  return tray.children.filter((item) => item.hasPage !== false);
+}
+function rankWidth(itemsOrCount) {
+  const count = typeof itemsOrCount === "number" ? itemsOrCount : itemsOrCount.length;
+  return Math.max(2, String(Math.max(0, count)).length);
+}
+function yearKey(iso) {
+  const parts = parseIsoDate(iso);
+  return parts ? String(parts.year).padStart(4, "0") : "";
+}
+function yearMonthKey(iso) {
+  const parts = parseIsoDate(iso);
+  return parts ? `${String(parts.year).padStart(4, "0")}-${String(parts.month).padStart(2, "0")}` : "";
+}
+function formatYearMonthLabel(isoOrKey, locale) {
+  return formatYearMonth(isoOrKey, locale);
+}
+function groupItems(items, grouping, order) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    if (!item.date) continue;
+    const key = grouping === "year" ? yearKey(item.date) : yearMonthKey(item.date);
+    if (!key) continue;
+    const group = groups.get(key) ?? [];
+    group.push(item);
+    groups.set(key, group);
+  }
+  const direction = order === "desc" ? -1 : 1;
+  return [...groups.entries()].sort(([a], [b]) => direction * a.localeCompare(b)).map(([key, group]) => ({
+    key,
+    items: group.sort(
+      (a, b) => direction * ((a.rank ?? Number.MAX_SAFE_INTEGER) - (b.rank ?? Number.MAX_SAFE_INTEGER))
+    )
+  }));
+}
+export {
+  findContainingNoteTray,
+  findNoteTray,
+  formatDate,
+  formatYearMonthLabel,
+  getNoteTrayItems,
+  groupItems,
+  parseIsoDate,
+  rankWidth,
+  yearKey,
+  yearMonthKey
+};

package/dist/plugins/codex-resources.d.ts

@@ -0,0 +1,4 @@
+import type { ZfbPlugin } from "@takazudo/zfb/plugins";
+export { runCodexResourcesPreStep } from "./internal/codex-resources/index.js";
+declare const plugin: ZfbPlugin;
+export default plugin;

package/dist/plugins/codex-resources.js

@@ -0,0 +1,31 @@
+import { runCodexResourcesPreStep } from "./internal/codex-resources/index.js";
+import { runCodexResourcesPreStep as runCodexResourcesPreStep2 } from "./internal/codex-resources/index.js";
+const PLUGIN_NAME = "@takazudo/zudo-doc-codex-resources";
+const plugin = {
+  name: PLUGIN_NAME,
+  async preBuild(ctx) {
+    const codexDir = ctx.options["codexDir"];
+    if (typeof codexDir !== "string" || codexDir.length === 0) {
+      throw new Error(
+        `[${PLUGIN_NAME}] preBuild: options.codexDir must be a non-empty string (got ${JSON.stringify(codexDir)})`
+      );
+    }
+    const projectRootOpt = ctx.options["projectRoot"];
+    const scanRootOpt = ctx.options["scanRoot"];
+    const docsDirOpt = ctx.options["docsDir"];
+    const result = runCodexResourcesPreStep({
+      codexDir,
+      projectRoot: typeof projectRootOpt === "string" ? projectRootOpt : ctx.projectRoot,
+      scanRoot: typeof scanRootOpt === "string" ? scanRootOpt : void 0,
+      docsDir: typeof docsDirOpt === "string" ? docsDirOpt : "src/content/docs"
+    });
+    ctx.logger.info(
+      `codex-resources: ${result.agentsMd} AGENTS.md, ${result.config} config, ${result.agents} agents, ${result.hooks} hooks, ${result.rules} rules, ${result.skills} skills`
+    );
+  }
+};
+var codex_resources_default = plugin;
+export {
+  codex_resources_default as default,
+  runCodexResourcesPreStep2 as runCodexResourcesPreStep
+};