@the-smithy/hearth 0.0.0-stage → 0.12.0

package/dist/next.d.ts

@@ -0,0 +1,105 @@
+import { H as HearthCore, b as CollectionPage, E as EventCollectionPage, F as FormResult, c as FormValues } from './client-DUEmHcTL.js';
+import * as _the_smithy_hearth_schema from '@the-smithy/hearth-schema';
+import { PageMeta } from '@the-smithy/hearth-schema';
+import { Metadata, MetadataRoute } from 'next';
+
+/** Holds the preview token while Next.js draft mode is on. */
+declare const PREVIEW_COOKIE = "hearth-preview";
+/** Next.js metadata from a page's or event's `meta`. */
+declare function metadataFromMeta(meta: PageMeta): Metadata;
+type HearthNextOptions = {
+    /** Base cache tag; every request is tagged with it (default "hearth"). */
+    tag?: string;
+    /**
+     * Longest time (seconds) content stays cached if a publish webhook is missed. Publishing
+     * refreshes the cache straight away through the webhook. Default 3600; false caches until then.
+     */
+    revalidate?: number | false;
+};
+/**
+ * Next.js helpers bound to a client: tagged reads (so publish webhooks refresh exactly
+ * what changed), metadata, sitemap, the revalidation route, and form submission.
+ */
+declare function createHearthNext(client: HearthCore, { tag, revalidate }?: HearthNextOptions): {
+    getSite: () => Promise<_the_smithy_hearth_schema.Site>;
+    getPages: () => Promise<_the_smithy_hearth_schema.PageSummary[]>;
+    getPage: (slug?: string | string[] | null) => Promise<_the_smithy_hearth_schema.Page | null>;
+    getEvents: (opts?: {
+        when?: "upcoming" | "past";
+        limit?: number;
+        collection?: string;
+        category?: string;
+    }) => Promise<_the_smithy_hearth_schema.HearthEvent[]>;
+    getCategories: () => Promise<_the_smithy_hearth_schema.CategoryGroup[]>;
+    getCollections: () => Promise<_the_smithy_hearth_schema.Collection[]>;
+    getCollection: (slug: string, opts?: {
+        limit?: number;
+        offset?: number;
+        tag?: string;
+        category?: string;
+        when?: "upcoming" | "past";
+    }) => Promise<CollectionPage | EventCollectionPage | null>;
+    getEvent: (slug: string) => Promise<_the_smithy_hearth_schema.HearthEventDetail | null>;
+    /** Fundraisers with progress (sites with Giving). Refreshed after every donation. */
+    getFundraisers: (opts?: {
+        status?: "active" | "completed" | "all";
+        category?: string;
+        limit?: number;
+    }) => Promise<_the_smithy_hearth_schema.Fundraiser[]>;
+    getFundraiser: (slug: string) => Promise<_the_smithy_hearth_schema.FundraiserDetail | null>;
+    /**
+     * A donation form's server action, shaped for `useActionState(action, null)`. Export it from a "use server" file:
+     *   export const donate = async (prev: FormResult | null, fd: FormData) => donateAction()(prev, fd);
+     * Fields: `amount` (dollars, or "custom" with `customAmount`), `fundraiser`, `name`, `email`, `anonymous`,
+     * `message`. On success it redirects the donor to the payment page; afterwards they return to `returnPath`.
+     */
+    donateAction: ({ returnPath }?: {
+        returnPath?: string;
+    }) => (_prev: FormResult | null, formData: FormData) => Promise<FormResult>;
+    /**
+     * An event registration form's server action (sites with Tickets), for `useActionState(action, null)`:
+     *   export const register = async (slug: string, prev: FormResult | null, fd: FormData) => registerAction(slug)(prev, fd);
+     * Fields: `ticket`, `name`, `email`, `phone`, `teamName`, `notes`, and one `attendee` per name. A free ticket
+     * resolves to { ok: true, message }; a paid one redirects to the payment page, which returns to `returnPath`.
+     */
+    registerAction: (slug: string, { returnPath }?: {
+        returnPath?: string;
+    }) => (_prev: FormResult | null, formData: FormData) => Promise<FormResult>;
+    /** Whether this request is a draft preview (to show a "Preview" banner with an exit link). */
+    isPreview: () => Promise<boolean>;
+    /**
+     * GET handler for the site's preview route (app/api/preview/route.ts):
+     *   export const GET = hearthNext.previewHandler();
+     * Hearth's "Preview on the website" button opens it with a token; it checks the token with Hearth, turns on
+     * draft mode and opens the page. Page and event reads then return saved drafts until the preview ends.
+     * Hearth's side-by-side preview adds `embed=1`, which makes the cookies work inside its editor's frame.
+     */
+    previewHandler(): (request: Request) => Promise<Response>;
+    /** GET handler that ends a preview (app/api/preview/exit/route.ts); `?path=` says where to go next. */
+    exitPreviewHandler(): (request: Request) => Promise<never>;
+    /** For `generateMetadata`: the page's title, description, canonical, robots and share tags ({} when not found). */
+    generatePageMetadata(slug?: string | string[] | null): Promise<Metadata>;
+    /** `export default sitemap` from app/sitemap.ts. */
+    sitemap(): Promise<MetadataRoute.Sitemap>;
+    /**
+     * POST handler for the site's revalidation webhook (app/api/revalidate/route.ts):
+     *   export const POST = hearthNext.revalidateHandler();
+     * Verifies the signature with HEARTH_WEBHOOK_SECRET and expires the matching tags.
+     */
+    revalidateHandler({ secret }?: {
+        secret?: string;
+    }): (request: Request) => Promise<Response>;
+    /**
+     * Submit a form from your own server action, forwarding the visitor's IP:
+     *   "use server";
+     *   export async function contact(_: unknown, formData: FormData) { return hearthNext.submitForm("contact", formData); }
+     */
+    submitForm: (formKey: string, values: FormValues) => Promise<FormResult>;
+    /**
+     * The same, shaped for `useActionState(action, null)`. Export it from a "use server" file:
+     *   export const contact = async (prev: FormResult | null, fd: FormData) => submitFormAction("contact")(prev, fd);
+     */
+    submitFormAction: (formKey: string) => (_prev: FormResult | null, formData: FormData) => Promise<FormResult>;
+};
+
+export { type HearthNextOptions, PREVIEW_COOKIE, createHearthNext, metadataFromMeta };

package/dist/next.js

@@ -0,0 +1,224 @@
+import {
+  isHearthError,
+  normalizeSlug
+} from "./chunk-7ZTQW5QR.js";
+import {
+  parseWebhook,
+  tagsForWebhook
+} from "./chunk-4VLAG4JX.js";
+
+// src/next.ts
+import { revalidateTag } from "next/cache";
+import { cookies, draftMode, headers } from "next/headers";
+import { redirect } from "next/navigation";
+var PREVIEW_COOKIE = "hearth-preview";
+var DRAFT_COOKIE = "__prerender_bypass";
+async function previewToken() {
+  if (!(await draftMode()).isEnabled) return void 0;
+  return (await cookies()).get(PREVIEW_COOKIE)?.value;
+}
+var clientIp = (h) => h.get("x-nf-client-connection-ip") ?? h.get("x-forwarded-for")?.split(",")[0]?.trim() ?? h.get("x-real-ip");
+var safePath = (path) => path && path.startsWith("/") && !path.startsWith("//") ? path : "/";
+function metadataFromMeta(meta) {
+  const description = meta.description ?? void 0;
+  return {
+    title: { absolute: meta.fullTitle },
+    description,
+    alternates: { canonical: meta.canonical },
+    robots: { index: meta.robots.index, follow: meta.robots.follow },
+    openGraph: {
+      type: meta.openGraph.type,
+      siteName: meta.openGraph.siteName,
+      locale: meta.openGraph.locale,
+      url: meta.openGraph.url,
+      title: meta.title,
+      description,
+      images: [{ url: meta.image.url, width: meta.image.width, height: meta.image.height, alt: meta.image.alt }]
+    },
+    twitter: { card: meta.twitter.card, title: meta.title, description, images: [meta.image.url], ...meta.twitter.site ? { site: meta.twitter.site } : {} }
+  };
+}
+function createHearthNext(client, { tag = "hearth", revalidate = 3600 } = {}) {
+  const tags = (...extra) => ({ cache: "force-cache", next: { revalidate, tags: [tag, ...extra] } });
+  const read = async (...extra) => {
+    const preview = await previewToken();
+    return preview ? { preview } : tags(...extra);
+  };
+  const getPage = async (slug) => client.pages.get(slug, await read(`${tag}:page:${normalizeSlug(slug)}`));
+  return {
+    getSite: () => client.site.get(tags(`${tag}:site`)),
+    getPages: () => client.pages.list(tags(`${tag}:pages`)),
+    getPage,
+    getEvents: (opts) => client.events.list(opts, tags(`${tag}:events`)),
+    getCategories: () => client.categories.list(tags(`${tag}:site`)),
+    getCollections: () => client.collections.list(tags(`${tag}:site`, `${tag}:pages`)),
+    getCollection: (slug, opts) => client.collections.get(slug, opts, tags(`${tag}:pages`, `${tag}:events`)),
+    getEvent: async (slug) => client.events.get(slug, await read(`${tag}:events`)),
+    /** Fundraisers with progress (sites with Giving). Refreshed after every donation. */
+    getFundraisers: (opts) => client.fundraisers.list(opts, tags(`${tag}:giving`)),
+    getFundraiser: async (slug) => client.fundraisers.get(slug, await read(`${tag}:giving`)),
+    /**
+     * A donation form's server action, shaped for `useActionState(action, null)`. Export it from a "use server" file:
+     *   export const donate = async (prev: FormResult | null, fd: FormData) => donateAction()(prev, fd);
+     * Fields: `amount` (dollars, or "custom" with `customAmount`), `fundraiser`, `name`, `email`, `anonymous`,
+     * `message`. On success it redirects the donor to the payment page; afterwards they return to `returnPath`.
+     */
+    donateAction: ({ returnPath = "/donate/thank-you" } = {}) => async (_prev, formData) => {
+      const h = await headers();
+      const host = h.get("x-forwarded-host") ?? h.get("host");
+      const proto = h.get("x-forwarded-proto") ?? (host?.startsWith("localhost") ? "http" : "https");
+      const raw = String(formData.get("amount") ?? "") === "custom" ? formData.get("customAmount") : formData.get("amount");
+      const dollars = Number(String(raw ?? "").replace(/[$,\s]/g, ""));
+      if (!Number.isFinite(dollars) || dollars <= 0) return { ok: false, message: "Choose or enter an amount.", fieldErrors: { amount: "Choose or enter an amount." } };
+      const text = (k) => String(formData.get(k) ?? "").trim() || void 0;
+      const result = await client.donations.checkout(
+        {
+          amountCents: Math.round(dollars * 100),
+          fundraiser: text("fundraiser"),
+          name: text("name"),
+          email: text("email"),
+          anonymous: formData.get("anonymous") === "on" || formData.get("anonymous") === "true",
+          message: text("message"),
+          returnUrl: `${proto}://${host}${safePath(returnPath)}`
+        },
+        { ip: clientIp(h) }
+      );
+      if (!result.ok) {
+        const fieldErrors = { ...result.fieldErrors };
+        if (fieldErrors.amountCents) fieldErrors.amount = fieldErrors.amountCents;
+        return { ok: false, message: result.message, fieldErrors };
+      }
+      redirect(result.checkoutUrl);
+    },
+    /**
+     * An event registration form's server action (sites with Tickets), for `useActionState(action, null)`:
+     *   export const register = async (slug: string, prev: FormResult | null, fd: FormData) => registerAction(slug)(prev, fd);
+     * Fields: `ticket`, `name`, `email`, `phone`, `teamName`, `notes`, and one `attendee` per name. A free ticket
+     * resolves to { ok: true, message }; a paid one redirects to the payment page, which returns to `returnPath`.
+     */
+    registerAction: (slug, { returnPath = "/registered" } = {}) => async (_prev, formData) => {
+      const h = await headers();
+      const host = h.get("x-forwarded-host") ?? h.get("host");
+      const proto = h.get("x-forwarded-proto") ?? (host?.startsWith("localhost") ? "http" : "https");
+      const text = (k) => String(formData.get(k) ?? "").trim() || void 0;
+      const result = await client.events.register(
+        slug,
+        {
+          ticket: text("ticket") ?? "",
+          name: text("name") ?? "",
+          email: text("email") ?? "",
+          phone: text("phone"),
+          teamName: text("teamName"),
+          notes: text("notes"),
+          attendees: formData.getAll("attendee").map((a) => String(a).trim()),
+          returnUrl: `${proto}://${host}${safePath(returnPath)}`
+        },
+        { ip: clientIp(h) }
+      );
+      if (!result.ok) return { ok: false, message: result.message, fieldErrors: result.fieldErrors };
+      if (result.status === "pending") redirect(result.checkoutUrl);
+      return { ok: true, message: "You're registered. A confirmation is on its way to your email." };
+    },
+    /** Whether this request is a draft preview (to show a "Preview" banner with an exit link). */
+    isPreview: async () => Boolean(await previewToken()),
+    /**
+     * GET handler for the site's preview route (app/api/preview/route.ts):
+     *   export const GET = hearthNext.previewHandler();
+     * Hearth's "Preview on the website" button opens it with a token; it checks the token with Hearth, turns on
+     * draft mode and opens the page. Page and event reads then return saved drafts until the preview ends.
+     * Hearth's side-by-side preview adds `embed=1`, which makes the cookies work inside its editor's frame.
+     */
+    previewHandler() {
+      return async (request) => {
+        const params = new URL(request.url).searchParams;
+        if (params.has("status")) {
+          const current = await previewToken();
+          if (!current) return new Response(null, { status: 204, headers: { "Cache-Control": "no-store" } });
+          try {
+            const { version, expiresAt } = await client.preview.verify(current);
+            return Response.json({ version, expiresAt }, { headers: { "Cache-Control": "no-store" } });
+          } catch (err) {
+            if (isHearthError(err) && err.code === "unauthorized") return new Response(null, { status: 401, headers: { "Cache-Control": "no-store" } });
+            throw err;
+          }
+        }
+        const token = params.get("token") ?? "";
+        let session;
+        try {
+          session = await client.preview.verify(token);
+        } catch (err) {
+          if (isHearthError(err) && err.code === "unauthorized") return new Response(err.message, { status: 401 });
+          throw err;
+        }
+        (await draftMode()).enable();
+        const store = await cookies();
+        const expires = new Date(session.expiresAt);
+        const embedded = params.get("embed") === "1" && process.env.NODE_ENV === "production";
+        if (embedded) {
+          const bypass = store.get(DRAFT_COOKIE)?.value;
+          if (bypass) store.set(DRAFT_COOKIE, bypass, { httpOnly: true, secure: true, sameSite: "none", partitioned: true, path: "/" });
+        }
+        store.set(PREVIEW_COOKIE, token, {
+          httpOnly: true,
+          secure: process.env.NODE_ENV === "production",
+          sameSite: embedded ? "none" : "lax",
+          ...embedded ? { partitioned: true } : {},
+          path: "/",
+          expires
+        });
+        redirect(safePath(session.path));
+      };
+    },
+    /** GET handler that ends a preview (app/api/preview/exit/route.ts); `?path=` says where to go next. */
+    exitPreviewHandler() {
+      return async (request) => {
+        (await draftMode()).disable();
+        (await cookies()).delete(PREVIEW_COOKIE);
+        redirect(safePath(new URL(request.url).searchParams.get("path")));
+      };
+    },
+    /** For `generateMetadata`: the page's title, description, canonical, robots and share tags ({} when not found). */
+    async generatePageMetadata(slug) {
+      const page = await getPage(slug);
+      return page ? metadataFromMeta(page.meta) : {};
+    },
+    /** `export default sitemap` from app/sitemap.ts. */
+    async sitemap() {
+      const entries = await client.sitemap(tags(`${tag}:pages`, `${tag}:events`));
+      return entries.map((e) => ({ url: e.url, ...e.lastModified ? { lastModified: e.lastModified } : {}, priority: e.priority }));
+    },
+    /**
+     * POST handler for the site's revalidation webhook (app/api/revalidate/route.ts):
+     *   export const POST = hearthNext.revalidateHandler();
+     * Verifies the signature with HEARTH_WEBHOOK_SECRET and expires the matching tags.
+     */
+    revalidateHandler({ secret = process.env.HEARTH_WEBHOOK_SECRET ?? "" } = {}) {
+      return async (request) => {
+        const payload = await parseWebhook(request, secret);
+        if (!payload) return new Response("Invalid signature", { status: 401 });
+        if (payload.site !== client.siteSlug) return new Response("Wrong site", { status: 400 });
+        for (const t of tagsForWebhook(payload, tag)) revalidateTag(t, { expire: 0 });
+        return Response.json({ revalidated: true });
+      };
+    },
+    /**
+     * Submit a form from your own server action, forwarding the visitor's IP:
+     *   "use server";
+     *   export async function contact(_: unknown, formData: FormData) { return hearthNext.submitForm("contact", formData); }
+     */
+    submitForm,
+    /**
+     * The same, shaped for `useActionState(action, null)`. Export it from a "use server" file:
+     *   export const contact = async (prev: FormResult | null, fd: FormData) => submitFormAction("contact")(prev, fd);
+     */
+    submitFormAction: (formKey) => async (_prev, formData) => submitForm(formKey, formData)
+  };
+  async function submitForm(formKey, values) {
+    return client.forms.submit(formKey, values, { ip: clientIp(await headers()) });
+  }
+}
+export {
+  PREVIEW_COOKIE,
+  createHearthNext,
+  metadataFromMeta
+};

package/dist/preview.d.ts

@@ -0,0 +1,36 @@
+import * as react from 'react';
+import { CSSProperties } from 'react';
+
+type HearthPreviewProps = {
+    /** The site's preview route; the SDK's `previewHandler()` answers `?status` there. Default `/api/preview`. */
+    previewRoute?: string;
+    /** The route that ends the preview (`exitPreviewHandler()`). Default `/api/preview/exit`. */
+    exitRoute?: string;
+    /** How often to check Hearth for newer drafts, in milliseconds. Default 2000. */
+    interval?: number;
+    /** Replace the default look. Without it the banner is a small dark pill at the bottom centre. */
+    className?: string;
+    style?: CSSProperties;
+};
+type Status = "live" | "updating" | "ended";
+/**
+ * The message <HearthPreview /> sends to Hearth's editor when the preview runs inside its side-by-side frame, so the
+ * editor knows the draft loaded (and can offer a new tab when a browser or an older site blocks it). No secrets.
+ */
+type HearthPreviewMessage = {
+    type: "hearth:preview";
+    status: Status;
+    path: string;
+};
+/**
+ * Live draft preview, for every site built on Hearth. Render it while previewing:
+ *
+ *   {(await hearthNext.isPreview()) ? <HearthPreview /> : null}
+ *
+ * It shows that the page is a preview, checks Hearth every couple of seconds for newer drafts (Hearth saves them as
+ * editors type) and refreshes the page in place when there are any, keeping the scroll position. Inside Hearth's
+ * side-by-side preview it reports to the editor (a `HearthPreviewMessage`) and leaves out the exit link.
+ */
+declare function HearthPreview({ previewRoute, exitRoute, interval, className, style }: HearthPreviewProps): react.JSX.Element;
+
+export { HearthPreview, type HearthPreviewMessage, type HearthPreviewProps };

package/dist/preview.js

@@ -0,0 +1,88 @@
+"use client";
+
+// src/preview.tsx
+import { useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { usePathname, useRouter } from "next/navigation";
+import { jsx, jsxs } from "react/jsx-runtime";
+var noSubscribe = () => () => {
+};
+var useInFrame = () => useSyncExternalStore(noSubscribe, () => window.parent !== window, () => false);
+var defaultStyle = {
+  position: "fixed",
+  // Bottom centre: clear of chat widgets (usually bottom right) and Next.js's dev badge (bottom left).
+  left: "50%",
+  transform: "translateX(-50%)",
+  bottom: 16,
+  zIndex: 2147483e3,
+  display: "flex",
+  alignItems: "center",
+  gap: 12,
+  padding: "8px 14px",
+  borderRadius: 999,
+  background: "#1a1a14",
+  color: "#fff",
+  font: "600 13px/1.3 system-ui, -apple-system, Segoe UI, sans-serif",
+  boxShadow: "0 4px 16px rgb(0 0 0 / 0.25)"
+};
+function HearthPreview({ previewRoute = "/api/preview", exitRoute = "/api/preview/exit", interval = 2e3, className, style }) {
+  const router = useRouter();
+  const path = usePathname();
+  const [status, setStatus] = useState("live");
+  const embedded = useInFrame();
+  const version = useRef(null);
+  useEffect(() => {
+    if (!embedded) return;
+    const message = { type: "hearth:preview", status, path: path || "/" };
+    window.parent.postMessage(message, "*");
+  }, [embedded, status, path]);
+  useEffect(() => {
+    let stopped = false;
+    let timer;
+    const check = async () => {
+      if (stopped) return;
+      if (!document.hidden) {
+        try {
+          const res = await fetch(`${previewRoute}?status=1`, { cache: "no-store", headers: { accept: "application/json" } });
+          if (res.status === 401 || res.status === 204) {
+            setStatus("ended");
+            return;
+          }
+          if (res.ok) {
+            const { version: next } = await res.json();
+            if (next && version.current && next !== version.current) {
+              setStatus("updating");
+              router.refresh();
+              setTimeout(() => !stopped && setStatus("live"), 1200);
+            }
+            if (next) version.current = next;
+          }
+        } catch {
+        }
+      }
+      timer = setTimeout(check, interval);
+    };
+    const onVisible = () => {
+      if (document.hidden) return;
+      clearTimeout(timer);
+      check();
+    };
+    document.addEventListener("visibilitychange", onVisible);
+    check();
+    return () => {
+      stopped = true;
+      clearTimeout(timer);
+      document.removeEventListener("visibilitychange", onVisible);
+    };
+  }, [previewRoute, interval, router]);
+  const exit = `${exitRoute}?path=${encodeURIComponent(path || "/")}`;
+  return /* @__PURE__ */ jsxs("div", { role: "status", "aria-live": "polite", className, style: className ? style : { ...defaultStyle, ...style }, "data-hearth-preview": status, children: [
+    /* @__PURE__ */ jsx("span", { children: status === "ended" ? "Preview ended" : status === "updating" ? "Preview \xB7 updating\u2026" : "Live preview" }),
+    embedded ? null : (
+      // A plain link, not next/link: prefetching it would end the preview.
+      /* @__PURE__ */ jsx("a", { href: exit, style: className ? void 0 : { color: "inherit", textDecoration: "underline", textUnderlineOffset: 2 }, children: status === "ended" ? "Back to the site" : "Exit" })
+    )
+  ] });
+}
+export {
+  HearthPreview
+};

package/dist/react.d.ts

@@ -0,0 +1,33 @@
+import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { KnownBlock, ResolvedBlock } from '@the-smithy/hearth-schema';
+
+type KnownType = KnownBlock["type"];
+/** One component per block type you render; each receives exactly that block. */
+type BlockComponents = {
+    [T in KnownType]?: ComponentType<{
+        block: Extract<KnownBlock, {
+            type: T;
+        }>;
+    }>;
+};
+/**
+ * Render a page's blocks with your own components, in order. Block types without a
+ * component (including types added to Hearth later) go to `fallback`, which renders
+ * nothing by default.
+ *
+ *   <HearthBlocks blocks={page.blocks} components={{ hero: Hero, richText: RichText }} />
+ */
+declare function HearthBlocks({ blocks, components, fallback, }: {
+    blocks: ResolvedBlock[];
+    components: BlockComponents;
+    fallback?: (props: {
+        block: ResolvedBlock;
+    }) => ReactNode;
+}): react.JSX.Element;
+/** schema.org structured data from `meta.jsonLd`, safely serialized. */
+declare function JsonLd({ data }: {
+    data: Record<string, unknown>[];
+}): react.JSX.Element;
+
+export { type BlockComponents, HearthBlocks, JsonLd };

package/dist/react.js

@@ -0,0 +1,24 @@
+// src/react.tsx
+import { Fragment } from "react";
+import { Fragment as Fragment2, jsx } from "react/jsx-runtime";
+function HearthBlocks({
+  blocks,
+  components,
+  fallback
+}) {
+  return /* @__PURE__ */ jsx(Fragment2, { children: blocks.map((block) => {
+    const Component = components[block.type];
+    if (Component) return /* @__PURE__ */ jsx(Component, { block }, block.id);
+    if (process.env.NODE_ENV !== "production" && !fallback) {
+      console.warn(`[hearth] No component for block type "${block.type}"; it was skipped.`);
+    }
+    return /* @__PURE__ */ jsx(Fragment, { children: fallback?.({ block }) }, block.id);
+  }) });
+}
+function JsonLd({ data }) {
+  return /* @__PURE__ */ jsx(Fragment2, { children: data.map((item, i) => /* @__PURE__ */ jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(item).replace(/</g, "\\u003c") } }, i)) });
+}
+export {
+  HearthBlocks,
+  JsonLd
+};

package/dist/testing.d.ts

@@ -0,0 +1,65 @@
+import { Site, Page, HearthEvent, HearthEventDetail, SitemapEntry, Collection, CollectionEntry, CategoryGroup, Fundraiser, FundraiserDetail, HearthForm } from '@the-smithy/hearth-schema';
+
+type MockHearthData = {
+    site?: Partial<Site>;
+    pages?: Page[];
+    events?: (HearthEvent | HearthEventDetail)[];
+    sitemap?: SitemapEntry[];
+    /** Collections, with their entries (page collections) keyed by collection slug. */
+    collections?: Collection[];
+    entries?: Record<string, CollectionEntry[]>;
+    categories?: CategoryGroup[];
+    fundraisers?: (Fundraiser | FundraiserDetail)[];
+    /** The site's forms, for `forms.get`. */
+    forms?: HearthForm[];
+    /** Handle event registrations; default confirms free tickets (`ticket: "free"`) and sends others to a fake checkout. */
+    onRegistration?(slug: string, input: Record<string, unknown>): {
+        ok: true;
+        status: "confirmed";
+    } | {
+        ok: true;
+        status: "pending";
+        checkoutUrl: string;
+    } | {
+        ok: false;
+        message: string;
+        fieldErrors: Record<string, string>;
+    };
+    /** Handle donation checkouts; default returns a fake checkout URL. */
+    onDonation?(input: Record<string, unknown>): {
+        ok: true;
+        checkoutUrl: string;
+    } | {
+        ok: false;
+        message: string;
+        fieldErrors: Record<string, string>;
+    };
+    /** A token that `preview.verify` accepts, and the path it opens. */
+    previewToken?: string;
+    previewPath?: string;
+    /** The draft version `preview.verify` reports (change it to simulate an editor saving). */
+    previewVersion?: string;
+    /** Drafts returned instead of `pages` when a request carries a preview token. */
+    draftPages?: Page[];
+    /** Handle form posts; default accepts everything. */
+    onForm?(formKey: string, values: Record<string, unknown>): {
+        ok: true;
+        message: string;
+    } | {
+        ok: false;
+        message: string;
+        fieldErrors: Record<string, string>;
+    };
+};
+/**
+ * An in-memory Hearth for tests: pass `mock.fetch` to createHearthClient.
+ *
+ *   const mock = createMockHearth({ pages: [page] });
+ *   const hearth = createHearthClient({ site: "test", apiKey: "hk_test_key_for_tests_only", fetch: mock.fetch });
+ */
+declare function createMockHearth(data?: MockHearthData): {
+    fetch: typeof globalThis.fetch;
+    requests: Request[];
+};
+
+export { type MockHearthData, createMockHearth };

package/dist/testing.js

@@ -0,0 +1,86 @@
+// src/testing.ts
+var json = (body, status = 200) => new Response(JSON.stringify(body), { status, headers: { "Content-Type": "application/json" } });
+var notFound = () => json({ error: { code: "not_found", message: "Not found" } }, 404);
+function createMockHearth(data = {}) {
+  const requests = [];
+  const fetch = async (input, init) => {
+    const req = input instanceof Request ? input : new Request(input, init);
+    requests.push(req.clone());
+    const url = new URL(req.url);
+    const m = url.pathname.match(/^\/api\/v1\/sites\/([^/]+)(\/.*)?$/);
+    if (!m) return notFound();
+    const [, slug, rest = ""] = m;
+    const registration = req.method === "POST" ? rest.match(/^\/events\/([^/]+)\/registrations$/)?.[1] : void 0;
+    if (registration) {
+      const input2 = await req.json().catch(() => ({}));
+      const result = data.onRegistration?.(decodeURIComponent(registration), input2) ?? (input2.ticket === "free" ? { ok: true, status: "confirmed" } : { ok: true, status: "pending", checkoutUrl: "https://checkout.example/pay" });
+      if (!result.ok) return json({ error: { code: "bad_request", message: result.message, details: result.fieldErrors } }, 400);
+      return json({ data: { registrationId: "00000000-0000-4000-8000-000000000002", ...result, ok: void 0 } }, 201);
+    }
+    if (req.method === "POST" && rest === "/donations/checkout") {
+      const input2 = await req.json().catch(() => ({}));
+      const result = data.onDonation?.(input2) ?? { ok: true, checkoutUrl: "https://checkout.example/pay" };
+      return result.ok ? json({ data: { donationId: "00000000-0000-4000-8000-000000000001", checkoutUrl: result.checkoutUrl } }, 201) : json({ error: { code: "bad_request", message: result.message, details: result.fieldErrors } }, 400);
+    }
+    if (req.method === "POST") {
+      const form = rest.match(/^\/forms\/([^/]+)$/)?.[1];
+      if (!form) return notFound();
+      const values = await req.json().catch(() => ({}));
+      const result = data.onForm?.(decodeURIComponent(form), values) ?? { ok: true, message: "Thanks!" };
+      return result.ok ? json({ data: { message: result.message } }, 201) : json({ error: { code: "bad_request", message: result.message, details: result.fieldErrors } }, 400);
+    }
+    if (rest === "") return json({ data: { slug, name: slug, domain: null, features: [], settings: {}, ...data.site } });
+    if (rest === "/pages") return json({ data: (data.pages ?? []).map(({ slug: slug2, path, title, seo, publishedAt }) => ({ slug: slug2, path, title, seo, noIndex: false, publishedAt })) });
+    if (rest.startsWith("/pages/")) {
+      const pool = req.headers.get("x-hearth-preview") ? [...data.draftPages ?? [], ...data.pages ?? []] : data.pages ?? [];
+      const page = pool.find((p) => p.slug === decodeURIComponent(rest.slice(7)));
+      return page ? json({ data: page }) : notFound();
+    }
+    if (rest.startsWith("/forms/")) {
+      const form = (data.forms ?? []).find((f) => f.key === decodeURIComponent(rest.slice(7)));
+      return form ? json({ data: form }) : notFound();
+    }
+    if (rest === "/events" || rest.startsWith("/events?")) return json({ data: data.events ?? [] });
+    if (rest.startsWith("/events/")) {
+      const event = (data.events ?? []).find((e) => e.slug === decodeURIComponent(rest.slice(8)));
+      return event ? json({ data: event }) : notFound();
+    }
+    if (rest === "/sitemap") return json({ data: data.sitemap ?? [] });
+    if (rest === "/fundraisers" || rest.startsWith("/fundraisers?")) {
+      const status = url.searchParams.get("status") ?? "active";
+      return json({ data: (data.fundraisers ?? []).filter((f) => status === "all" || f.status === status) });
+    }
+    if (rest.startsWith("/fundraisers/")) {
+      const fundraiser = (data.fundraisers ?? []).find((f) => f.slug === decodeURIComponent(rest.slice(13)));
+      return fundraiser ? json({ data: fundraiser }) : notFound();
+    }
+    if (rest === "/preview") {
+      const token = req.headers.get("x-hearth-preview");
+      return token && token === data.previewToken ? json({ data: { path: data.previewPath ?? "/", expiresAt: new Date(Date.now() + 36e5).toISOString(), version: data.previewVersion ?? "1" } }) : json({ error: { code: "unauthorized", message: "This preview link has expired." } }, 401);
+    }
+    if (rest === "/collections") return json({ data: data.collections ?? [] });
+    if (rest === "/categories") return json({ data: data.categories ?? [] });
+    if (rest.startsWith("/collections/")) {
+      const want = decodeURIComponent(rest.slice(13));
+      const collection = (data.collections ?? []).find((c) => c.slug === want);
+      if (!collection) return notFound();
+      if (collection.kind === "events") {
+        return json({ data: { collection, events: (data.events ?? []).filter((e) => e.collection?.id === collection.id) } });
+      }
+      const all = data.entries?.[collection.slug] ?? [];
+      const tag = url.searchParams.get("tag");
+      const category = url.searchParams.get("category");
+      const list = all.filter(
+        (e) => (!tag || e.tags.includes(tag)) && (!category || e.categories.some((c) => `${c.group.slug}/${c.slug}` === category))
+      );
+      const offset = Number(url.searchParams.get("offset") ?? 0);
+      const limit = Number(url.searchParams.get("limit") ?? 12);
+      return json({ data: { collection, total: list.length, entries: list.slice(offset, offset + limit) } });
+    }
+    return notFound();
+  };
+  return { fetch, requests };
+}
+export {
+  createMockHearth
+};