@takazudo/zfb 0.1.0-next.10

package/dist/content.d.ts

@@ -0,0 +1,240 @@
+import { parseFrontmatter } from "./frontmatter.js";
+import type { ParsedFrontmatter } from "./frontmatter.js";
+import type { VNode } from "./jsx-types.js";
+export { parseFrontmatter };
+export type { ParsedFrontmatter };
+/**
+ * One entry in an embedded content snapshot. Mirrors
+ * `crates/zfb-content/src/content_bridge.rs::EntrySnapshot`. Re-exported
+ * by `@takazudo/zfb-runtime/snapshot` for the runtime-side bundle. See
+ * that module for field-by-field documentation.
+ */
+export interface SnapshotEntry {
+    readonly slug: string;
+    readonly frontmatter: unknown;
+    readonly body: string;
+    readonly module_specifier: string;
+    readonly rel_path: string;
+}
+/**
+ * Point-in-time snapshot of every configured collection. Mirrors
+ * `crates/zfb-content/src/content_bridge.rs::ContentSnapshot`.
+ */
+export interface Snapshot {
+    readonly collections: Readonly<Record<string, readonly SnapshotEntry[]>>;
+}
+/**
+ * Register a [`Snapshot`] so [`getCollection`] resolves from memory.
+ *
+ * Pass `undefined` to clear (used by tests that need to restore the v0
+ * filesystem path between runs). Idempotent: the latest call wins.
+ *
+ * Stored on `globalThis.__zfb.contentSnapshot` rather than a
+ * module-level `let` so a worker bundle that ends up with two
+ * `zfb/content` module instances still sees a single shared snapshot —
+ * see the [`SnapshotBridgeNamespace`] doc above for the full
+ * pnpm-symlink rationale.
+ */
+export declare function setContentSnapshot(snapshot: Snapshot | undefined): void;
+/**
+ * Read the currently-installed [`Snapshot`], or `undefined` if none is
+ * registered. Exposed mostly for tests; production callers should not
+ * need to introspect the bridge state.
+ *
+ * Reads from `globalThis.__zfb.contentSnapshot`; see
+ * [`setContentSnapshot`] for why the slot lives on `globalThis`.
+ */
+export declare function getContentSnapshot(): Snapshot | undefined;
+/**
+ * Props accepted by an entry's [`CollectionEntry.Content`] component.
+ *
+ * `components` mirrors Astro's `<Content components={...}>` contract:
+ * a flat record of element-name → override component (e.g. `{ h1: MyH1 }`).
+ * The default-components convention ships from `zfb`'s root export
+ * (`defaultComponents`, lands in Sub 6) and users compose with their own
+ * via `{ ...defaultComponents, ...mine }`.
+ */
+export interface ContentProps {
+    /** Element-name → override component map. Optional. */
+    components?: Record<string, unknown>;
+}
+/**
+ * Public JSX-element shape returned by [`CollectionEntry.Content`].
+ *
+ * Matches the structural shape that both Preact's and React's `jsx-runtime`
+ * accept on either side of the boundary, mirroring the Island wrapper's
+ * approach. Consumers should treat this as opaque — its only contract is
+ * "renderable JSX value".
+ *
+ * Aliased as `JSX.Element` in the field signature: the JS runtime is
+ * type-erased and the actual VNode shape is supplied by the framework
+ * adapter at evaluation time.
+ */
+export type ContentElement = {
+    readonly type: string | ((...args: unknown[]) => unknown);
+    readonly props: Readonly<Record<string, unknown>>;
+    readonly key: unknown;
+};
+/**
+ * Generic shape returned for one entry in a content collection. The `data`
+ * field carries parsed frontmatter, typed by the caller via the generic
+ * parameter.
+ */
+export type CollectionEntry<T = Record<string, unknown>> = {
+    /** Filename without `.md` extension. Stable across runs. */
+    slug: string;
+    /** Parsed frontmatter. */
+    data: T;
+    /** Raw markdown body (frontmatter stripped). */
+    body: string;
+    /**
+     * Stable module specifier used as the bridge lookup key. Format:
+     * `mdx://<collection>/<slug>` (no hash component — the JS stub does
+     * not compile MDX, so it has no body hash to attach; the production
+     * Rust-side `zfb-content::collection::Entry::module_specifier` adds a
+     * `#<hash>` suffix and the bridge is responsible for matching either
+     * form against its registered components).
+     *
+     * This field is part of the v0+ JS surface so the bridge has something
+     * deterministic to key on without consulting per-call state.
+     */
+    module_specifier: string;
+    /**
+     * Renderable component for this entry.
+     *
+     * **Bridge contract.** At call time, `Content` consults
+     * `globalThis.__zfb?.content?.get(entry.module_specifier)`. If the
+     * bridge is present and returns a function, that function is invoked
+     * with `props` and its result returned verbatim.
+     *
+     * **Fallback.** Outside the renderer (unit tests, dev sandboxes, or any
+     * environment where `globalThis.__zfb.content.get` is absent or returns
+     * `undefined`), `Content` returns a JSX-shaped element rendering the
+     * raw markdown body inside a `<pre data-zfb-content-fallback>` block,
+     * with a leading `[zfb fallback render]` marker line so the visual
+     * distinction survives unstyled environments. The marker is also a
+     * grep target for "did the production renderer not run?" diagnostics.
+     *
+     * **Typed signature.** Returns `ContentElement` (a structural alias for
+     * `JSX.Element`) so consumers can drop `<entry.Content components={...} />`
+     * into both React and Preact JSX without per-framework type setup.
+     *
+     * @example
+     *   const post = (await getCollection("blog"))[0];
+     *   return <post.Content components={{ ...defaultComponents, h1: MyH1 }} />;
+     */
+    Content: (props: ContentProps) => ContentElement;
+};
+/**
+ * Load every `*.md` file in the named collection. Files starting with `.`
+ * or that lack a `.md` extension are ignored.
+ *
+ * **ADR-004 contract: this function is synchronous.** TSX page modules
+ * call it from anywhere — top-level, inside a render body, inside a
+ * `useMemo` — and SSR completes in a single pass without yielding. The
+ * snapshot path returns from memory; the filesystem fallback uses sync
+ * `node:fs` APIs so the surface stays unified. (The legacy async
+ * implementation was an oversight — the ADR predates it; SSG paths
+ * always saw a Promise where ADR-004 says they should see an array,
+ * which is why migrations from Astro tripped on `getCollection().filter
+ * is not a function`.)
+ *
+ * @example
+ *   const posts = getCollection<{ title: string; date: string }>("blog");
+ */
+export declare function getCollection<T = Record<string, unknown>>(name: string): CollectionEntry<T>[];
+/**
+ * @internal
+ *
+ * Convert a `path.relative()` result into a forward-slash-separated
+ * slug with the trailing `.md` extension stripped.
+ *
+ * Slugs are URL-flavored identifiers, not filesystem paths — they
+ * MUST use `/` regardless of the host OS so a nested entry like
+ * `2024/hello.md` produces the slug `2024/hello` on both POSIX and
+ * Windows. Without this normalisation, Windows callers would see
+ * `2024\hello`, which then leaks through to `module_specifier` and
+ * any URL the consumer derives from the slug.
+ *
+ * Exported solely so the unit test suite can pin the Windows
+ * behaviour without needing an actual Windows host. Do not depend on
+ * this from application code — name and signature may change.
+ */
+export declare function _relPathToSlug(relPath: string): string;
+/**
+ * Public JSX-element shape returned by every override in [`defaultComponents`].
+ *
+ * Mirrors [`ContentElement`] and [`IslandElement`]: a structural alias for
+ * `JSX.Element` so consumers can drop these overrides into both React and
+ * Preact JSX without per-framework type setup.
+ */
+export type ContentComponentElement = {
+    readonly type: string;
+    readonly props: Readonly<Record<string, unknown>>;
+    readonly key: unknown;
+};
+/**
+ * Props accepted by every default override. `children` and any extra
+ * attributes (`className`, `id`, `href`, …) are passed through verbatim
+ * to the underlying HTML element.
+ */
+export interface ContentComponentProps {
+    children?: VNode;
+    [key: string]: unknown;
+}
+/**
+ * `<h2>` passthrough override. Ported from zudo-doc's `HeadingH2`, stripped
+ * of styling — v0 ships pass-through behaviour; visual treatment is layered
+ * on by the consumer (or by a follow-up enhancement pass).
+ */
+export declare function ContentH2(props: ContentComponentProps): ContentComponentElement;
+/** `<h3>` passthrough override. See [`ContentH2`] for the contract. */
+export declare function ContentH3(props: ContentComponentProps): ContentComponentElement;
+/** `<h4>` passthrough override. See [`ContentH2`] for the contract. */
+export declare function ContentH4(props: ContentComponentProps): ContentComponentElement;
+/** `<p>` passthrough override. Mirrors zudo-doc's `ContentParagraph`. */
+export declare function ContentParagraph(props: ContentComponentProps): ContentComponentElement;
+/** `<a>` passthrough override. Mirrors zudo-doc's `ContentLink`. */
+export declare function ContentLink(props: ContentComponentProps): ContentComponentElement;
+/** `<strong>` passthrough override. Mirrors zudo-doc's `ContentStrong`. */
+export declare function ContentStrong(props: ContentComponentProps): ContentComponentElement;
+/** `<blockquote>` passthrough override. Mirrors zudo-doc's `ContentBlockquote`. */
+export declare function ContentBlockquote(props: ContentComponentProps): ContentComponentElement;
+/** `<ul>` passthrough override. Mirrors zudo-doc's `ContentUl`. */
+export declare function ContentUl(props: ContentComponentProps): ContentComponentElement;
+/** `<ol>` passthrough override. Mirrors zudo-doc's `ContentOl`. */
+export declare function ContentOl(props: ContentComponentProps): ContentComponentElement;
+/** `<table>` passthrough override. Mirrors zudo-doc's `ContentTable`. */
+export declare function ContentTable(props: ContentComponentProps): ContentComponentElement;
+/** `<code>` passthrough override. Mirrors zudo-doc's `ContentCode`. */
+export declare function ContentCode(props: ContentComponentProps): ContentComponentElement;
+/**
+ * Default per-element override map — eleven entries covering the markdown
+ * tags the zudo-doc convention overrides (`h2`, `h3`, `h4`, `p`, `a`,
+ * `strong`, `blockquote`, `ul`, `ol`, `table`, `code`).
+ *
+ * `h1` is intentionally absent: page titles render from frontmatter, per
+ * the zudo-doc convention.
+ *
+ * Spread into a `components` prop to compose with custom overrides:
+ *
+ * ```tsx
+ * import { defaultComponents } from "zfb";
+ *
+ * <entry.Content components={{ ...defaultComponents, h2: MyFancyH2 }} />
+ * ```
+ */
+export declare const defaultComponents: {
+    readonly h2: typeof ContentH2;
+    readonly h3: typeof ContentH3;
+    readonly h4: typeof ContentH4;
+    readonly p: typeof ContentParagraph;
+    readonly a: typeof ContentLink;
+    readonly strong: typeof ContentStrong;
+    readonly blockquote: typeof ContentBlockquote;
+    readonly ul: typeof ContentUl;
+    readonly ol: typeof ContentOl;
+    readonly table: typeof ContentTable;
+    readonly code: typeof ContentCode;
+};
+//# sourceMappingURL=content.d.ts.map

package/dist/content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"AAiDA,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAO5C,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAC5B,YAAY,EAAE,iBAAiB,EAAE,CAAC;AAwBlC;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC,CAAC,CAAC;CAC1E;AA6CD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAAG,IAAI,CAKvE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,IAAI,QAAQ,GAAG,SAAS,CAEzD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,CAAC;IAC1D,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAClD,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;CACvB,CAAC;AA6BF;;;;GAIG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IACzD,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,IAAI,EAAE,CAAC,CAAC;IACR,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;;;OAUG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,cAAc,CAAC;CAClD,CAAC;AAmKF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC,EAAE,CA2D7F;AA0ED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAOtD;AAgCD;;;;;;GAMG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAClD,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,KAAK,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAeD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,qBAAqB,GAAG,uBAAuB,CAE/E;AAED,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,KAAK,EAAE,qBAAqB,GAAG,uBAAuB,CAE/E;AAED,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,KAAK,EAAE,qBAAqB,GAAG,uBAAuB,CAE/E;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,uBAAuB,CAEtF;AAED,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,KAAK,EAAE,qBAAqB,GAAG,uBAAuB,CAEjF;AAED,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,KAAK,EAAE,qBAAqB,GAAG,uBAAuB,CAEnF;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,qBAAqB,GAAG,uBAAuB,CAEvF;AAED,mEAAmE;AACnE,wBAAgB,SAAS,CAAC,KAAK,EAAE,qBAAqB,GAAG,uBAAuB,CAE/E;AAED,mEAAmE;AACnE,wBAAgB,SAAS,CAAC,KAAK,EAAE,qBAAqB,GAAG,uBAAuB,CAE/E;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,KAAK,EAAE,qBAAqB,GAAG,uBAAuB,CAElF;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,KAAK,EAAE,qBAAqB,GAAG,uBAAuB,CAEjF;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;CAYpB,CAAC"}