@the-smithy/hearth 0.13.1 → 0.15.0

package/README.md

@@ -27,7 +27,7 @@ pnpm add @the-smithy/hearth
 ```dotenv
 # .env.local (never committed)
 HEARTH_SITE=acme
-HEARTH_API_KEY=hk_…   # Hearth → the site → Settings → Developers → API keys
+HEARTH_API_KEY=hk_…   # Hearth → the site → API & webhooks → API keys
 ```
 
 ```ts

package/dist/react.d.ts

@@ -1,7 +1,73 @@
 import * as react from 'react';
-import { ComponentType, ReactNode } from 'react';
+import { ReactNode, ComponentType } from 'react';
 import { KnownBlock, ResolvedBlock } from '@the-smithy/hearth-schema';
 
+/** Class names for each part of a guide. Leave any out to render that part unstyled. */
+type GuideTheme = {
+    /** Wraps the blocks (spacing between them). */
+    root?: string;
+    /** A block's heading (h2). */
+    heading?: string;
+    /** Intros, captions, small print. */
+    muted?: string;
+    /** Wraps rendered Markdown. */
+    prose?: string;
+    /** Surfaces: steps, cards, the question list, numbers. */
+    card?: string;
+    /** The number on a step. */
+    stepNumber?: string;
+    /** A step's or card's title. */
+    itemTitle?: string;
+    /** Text links. */
+    link?: string;
+    /** The main button in a call to action. */
+    button?: string;
+    /** The call-to-action box. */
+    callout?: string;
+    /** A quote. */
+    quote?: string;
+    /** Images and video frames. */
+    media?: string;
+    /** The "+" on an expandable question. */
+    accent?: string;
+    /** A step's label ("Step 1": the text-and-image block's eyebrow). */
+    eyebrow?: string;
+    /** A step's screenshot (the text-and-image block's image, shown full width under the step). */
+    screenshot?: string;
+};
+type GuideLinkProps = {
+    href: string;
+    className?: string;
+    children: ReactNode;
+};
+type GuideBlocksProps = {
+    /** The guide page's blocks, as the API returns them. Types a guide doesn't use are skipped. */
+    blocks: readonly unknown[];
+    theme?: GuideTheme;
+    /** Render Markdown (e.g. with react-markdown). Without it, paragraphs are shown as plain text. */
+    renderMarkdown?: (markdown: string) => ReactNode;
+    /** Your router's link (e.g. next/link) for links within the product. External links always use <a>. */
+    linkComponent?: ComponentType<GuideLinkProps>;
+};
+/** Block types a guide can use; anything else is skipped. */
+declare const GUIDE_BLOCK_TYPES: readonly ["hero", "richText", "mediaText", "schedule", "cardGrid", "faq", "gallery", "video", "quote", "stats", "cta"];
+/**
+ * The guide's sections that have a heading, in order, with the anchor each one gets: for an "In this guide" list.
+ *
+ *   guideOutline(page.blocks).map((s) => <a href={`#${s.id}`}>{s.title}</a>)
+ */
+declare function guideOutline(blocks: readonly unknown[]): {
+    id: string;
+    title: string;
+}[];
+/**
+ * Render a guide's blocks with your product's styles.
+ *
+ *   <GuideBlocks blocks={page.blocks} theme={{ card: "rounded-xl bg-white ring-1 ring-ash", link: "underline" }}
+ *     renderMarkdown={(md) => <ReactMarkdown>{md}</ReactMarkdown>} linkComponent={Link} />
+ */
+declare function GuideBlocks({ blocks, theme, renderMarkdown, linkComponent: InternalLink }: GuideBlocksProps): react.JSX.Element;
+
 type KnownType = KnownBlock["type"];
 /** One component per block type you render; each receives exactly that block. */
 type BlockComponents = {
@@ -42,4 +108,4 @@ declare function HearthEmbed({ block, className }: {
     className?: string;
 }): react.JSX.Element;
 
-export { type BlockComponents, HearthBlocks, HearthEmbed, JsonLd };
+export { type BlockComponents, GUIDE_BLOCK_TYPES, GuideBlocks, type GuideBlocksProps, type GuideLinkProps, type GuideTheme, HearthBlocks, HearthEmbed, JsonLd, guideOutline };

package/dist/react.js

@@ -1,26 +1,171 @@
 // src/react.tsx
 import { Fragment } from "react";
 import { EMBED_ALLOW, EMBED_SANDBOX, embedDocument } from "@the-smithy/hearth-schema";
-import { Fragment as Fragment2, jsx } from "react/jsx-runtime";
+
+// src/guide.tsx
+import { videoEmbedUrl } from "@the-smithy/hearth-schema";
+import { jsx, jsxs } from "react/jsx-runtime";
+var GUIDE_BLOCK_TYPES = ["hero", "richText", "mediaText", "schedule", "cardGrid", "faq", "gallery", "video", "quote", "stats", "cta"];
+var anchor = (text) => text.toLowerCase().replace(/\*/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+var headingOf = (b) => typeof b.data?.heading === "string" && b.data.heading.trim() ? b.data.heading.trim() : null;
+function guideOutline(blocks) {
+  return blocks.flatMap((b) => {
+    const title = GUIDE_BLOCK_TYPES.includes(b.type) && b.type !== "cta" ? headingOf(b) : null;
+    return title ? [{ id: anchor(title), title: title.replace(/\*/g, "") }] : [];
+  });
+}
+var stack = (gap) => ({ display: "flex", flexDirection: "column", gap });
+var grid = (min) => ({ display: "grid", gap: "0.75rem", gridTemplateColumns: `repeat(auto-fit, minmax(min(100%, ${min}), 1fr))` });
+var fill = { display: "block", width: "100%", height: "auto" };
+var str = (v) => typeof v === "string" && v ? v : null;
+function plainMarkdown(markdown) {
+  return markdown.split(/\n{2,}/).map((p, i) => /* @__PURE__ */ jsx("p", { style: { whiteSpace: "pre-line" }, children: p }, i));
+}
+function GuideBlocks({ blocks, theme = {}, renderMarkdown = plainMarkdown, linkComponent: InternalLink }) {
+  const t = theme;
+  const md = (markdown) => /* @__PURE__ */ jsx("div", { className: t.prose, children: renderMarkdown(String(markdown ?? "")) });
+  const heading = (v) => str(v) ? /* @__PURE__ */ jsx("h2", { className: t.heading, children: str(v) }) : null;
+  const intro = (v) => str(v) ? /* @__PURE__ */ jsx("p", { className: t.muted, children: str(v) }) : null;
+  const link = (l, className = t.link) => /^https?:\/\//.test(l.href) || !InternalLink ? /* @__PURE__ */ jsx("a", { href: l.href, className, .../^https?:\/\//.test(l.href) ? { target: "_blank", rel: "noopener noreferrer" } : {}, children: l.label }) : /* @__PURE__ */ jsx(InternalLink, { href: l.href, className, children: l.label });
+  const img = (i, className = t.media) => /* @__PURE__ */ jsx("img", { src: i.src, alt: i.alt ?? "", className, style: fill, loading: "lazy" });
+  function render(block) {
+    const d = block.data ?? {};
+    switch (block.type) {
+      case "hero":
+        return /* @__PURE__ */ jsxs("div", { style: stack("0.5rem"), children: [
+          heading(d.heading),
+          str(d.body) ? md(d.body) : null
+        ] });
+      case "richText":
+        return md(d.markdown);
+      case "mediaText": {
+        const image = d.image;
+        return /* @__PURE__ */ jsxs("div", { style: stack("0.75rem"), children: [
+          /* @__PURE__ */ jsxs("div", { style: stack("0.375rem"), children: [
+            str(d.eyebrow) ? /* @__PURE__ */ jsx("p", { className: t.eyebrow, children: str(d.eyebrow) }) : null,
+            heading(d.heading),
+            str(d.markdown) ? md(d.markdown) : null,
+            d.cta ? /* @__PURE__ */ jsx("p", { children: link(d.cta) }) : null
+          ] }),
+          image ? /* @__PURE__ */ jsx("figure", { style: { margin: 0 }, children: img(image, t.screenshot ?? t.media) }) : null
+        ] });
+      }
+      case "schedule": {
+        const items = d.items ?? [];
+        return /* @__PURE__ */ jsxs("div", { style: stack("0.75rem"), children: [
+          heading(d.heading),
+          intro(d.intro),
+          /* @__PURE__ */ jsx("ol", { style: { ...stack("0.75rem"), listStyle: "none", margin: 0, padding: 0 }, children: items.map((s, i) => /* @__PURE__ */ jsxs("li", { className: t.card, style: { display: "flex", gap: "1rem", alignItems: "flex-start" }, children: [
+            /* @__PURE__ */ jsx("span", { className: t.stepNumber, style: { flexShrink: 0 }, children: s.time }),
+            /* @__PURE__ */ jsxs("span", { style: { minWidth: 0 }, children: [
+              /* @__PURE__ */ jsx("span", { className: t.itemTitle, style: { display: "block" }, children: s.title }),
+              s.details ? /* @__PURE__ */ jsx("span", { className: t.muted, style: { display: "block", whiteSpace: "pre-line" }, children: s.details }) : null
+            ] })
+          ] }, i)) })
+        ] });
+      }
+      case "cardGrid": {
+        const items = d.items ?? [];
+        return /* @__PURE__ */ jsxs("div", { style: stack("0.75rem"), children: [
+          heading(d.heading),
+          intro(d.intro),
+          /* @__PURE__ */ jsx("div", { style: grid("14rem"), children: items.map((c, i) => /* @__PURE__ */ jsxs("div", { className: t.card, style: stack("0.375rem"), children: [
+            c.image ? img(c.image) : null,
+            /* @__PURE__ */ jsx("p", { className: t.itemTitle, children: c.title }),
+            c.body ? /* @__PURE__ */ jsx("p", { className: t.muted, style: { whiteSpace: "pre-line" }, children: c.body }) : null,
+            c.link ? /* @__PURE__ */ jsx("p", { children: link(c.link) }) : null
+          ] }, i)) })
+        ] });
+      }
+      case "faq": {
+        const items = d.items ?? [];
+        return /* @__PURE__ */ jsxs("div", { style: stack("0.75rem"), children: [
+          heading(d.heading),
+          /* @__PURE__ */ jsx("div", { style: stack("0.5rem"), children: items.map((q, i) => /* @__PURE__ */ jsxs("details", { className: t.card, children: [
+            /* @__PURE__ */ jsxs("summary", { style: { display: "flex", justifyContent: "space-between", gap: "1rem", cursor: "pointer", listStyle: "none" }, className: t.itemTitle, children: [
+              q.question,
+              /* @__PURE__ */ jsx("span", { "aria-hidden": true, className: t.accent, children: "+" })
+            ] }),
+            /* @__PURE__ */ jsx("div", { style: { marginTop: "0.5rem" }, children: md(q.answer) })
+          ] }, i)) })
+        ] });
+      }
+      case "gallery": {
+        const images = d.images ?? [];
+        return /* @__PURE__ */ jsxs("div", { style: stack("0.75rem"), children: [
+          heading(d.heading),
+          intro(d.intro),
+          /* @__PURE__ */ jsx("div", { style: grid("14rem"), children: images.map((g, i) => /* @__PURE__ */ jsxs("figure", { style: { margin: 0 }, children: [
+            img(g.image),
+            g.caption ? /* @__PURE__ */ jsx("figcaption", { className: t.muted, style: { marginTop: "0.25rem" }, children: g.caption }) : null
+          ] }, i)) })
+        ] });
+      }
+      case "video": {
+        const src = typeof d.url === "string" ? videoEmbedUrl(d.url) : null;
+        if (!src) return null;
+        return /* @__PURE__ */ jsxs("figure", { style: { ...stack("0.5rem"), margin: 0 }, children: [
+          heading(d.heading),
+          /* @__PURE__ */ jsx("div", { className: t.media, style: { aspectRatio: "16 / 9", overflow: "hidden" }, children: /* @__PURE__ */ jsx("iframe", { src, title: String(d.title ?? "Video"), style: { width: "100%", height: "100%", border: 0 }, allow: "autoplay; fullscreen; picture-in-picture", allowFullScreen: true, loading: "lazy" }) }),
+          str(d.caption) ? /* @__PURE__ */ jsx("figcaption", { className: t.muted, children: str(d.caption) }) : null
+        ] });
+      }
+      case "quote":
+        return /* @__PURE__ */ jsxs("blockquote", { className: t.quote, style: { margin: 0 }, children: [
+          /* @__PURE__ */ jsx("p", { children: String(d.quote ?? "") }),
+          str(d.name) ? /* @__PURE__ */ jsx("footer", { className: t.muted, children: [d.name, d.role].filter(Boolean).join(", ") }) : null
+        ] });
+      case "stats": {
+        const items = d.items ?? [];
+        return /* @__PURE__ */ jsxs("div", { style: stack("0.75rem"), children: [
+          heading(d.heading),
+          /* @__PURE__ */ jsx("dl", { style: { ...grid("10rem"), margin: 0 }, children: items.map((s, i) => /* @__PURE__ */ jsxs("div", { className: t.card, children: [
+            /* @__PURE__ */ jsx("dt", { className: t.muted, children: s.label }),
+            /* @__PURE__ */ jsx("dd", { className: t.itemTitle, style: { margin: 0 }, children: s.value })
+          ] }, i)) })
+        ] });
+      }
+      case "cta":
+        return /* @__PURE__ */ jsxs("div", { className: t.callout, style: stack("0.5rem"), children: [
+          /* @__PURE__ */ jsx("p", { className: t.itemTitle, children: String(d.heading ?? "") }),
+          str(d.body) ? /* @__PURE__ */ jsx("p", { className: t.muted, children: str(d.body) }) : null,
+          d.primary || d.secondary ? /* @__PURE__ */ jsxs("div", { style: { display: "flex", flexWrap: "wrap", alignItems: "center", gap: "1rem", marginTop: "0.25rem" }, children: [
+            d.primary ? link(d.primary, t.button) : null,
+            d.secondary ? link(d.secondary) : null
+          ] }) : null
+        ] });
+      default:
+        return null;
+    }
+  }
+  return /* @__PURE__ */ jsx("div", { className: t.root, style: t.root ? void 0 : stack("2rem"), children: blocks.map((b, i) => {
+    const out = render(b);
+    const title = b.type !== "cta" ? headingOf(b) : null;
+    return out ? /* @__PURE__ */ jsx("section", { id: title ? anchor(title) : void 0, style: title ? { scrollMarginTop: "1.5rem" } : void 0, children: out }, b.id ?? i) : null;
+  }) });
+}
+
+// src/react.tsx
+import { Fragment as Fragment2, jsx as jsx2 } from "react/jsx-runtime";
 function HearthBlocks({
   blocks,
   components,
   fallback
 }) {
-  return /* @__PURE__ */ jsx(Fragment2, { children: blocks.map((block) => {
+  return /* @__PURE__ */ jsx2(Fragment2, { children: blocks.map((block) => {
     const Component = components[block.type];
-    if (Component) return /* @__PURE__ */ jsx(Component, { block }, block.id);
+    if (Component) return /* @__PURE__ */ jsx2(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);
+    return /* @__PURE__ */ jsx2(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)) });
+  return /* @__PURE__ */ jsx2(Fragment2, { children: data.map((item, i) => /* @__PURE__ */ jsx2("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(item).replace(/</g, "\\u003c") } }, i)) });
 }
 function HearthEmbed({ block, className }) {
-  return /* @__PURE__ */ jsx(
+  return /* @__PURE__ */ jsx2(
     "iframe",
     {
       srcDoc: embedDocument(block.data.html),
@@ -36,7 +181,10 @@ function HearthEmbed({ block, className }) {
   );
 }
 export {
+  GUIDE_BLOCK_TYPES,
+  GuideBlocks,
   HearthBlocks,
   HearthEmbed,
-  JsonLd
+  JsonLd,
+  guideOutline
 };

package/llms.md

@@ -20,7 +20,7 @@ client components: the API key is secret.
   a gitignored file and read the parts you need.
 - Never print, log or commit the API key, and don't ask the developer to paste it into chat. Read it only from
   env. If it's missing or rejected (`HearthError` code `unauthorized`), ask them to create one in Hearth → the
-  site → Settings → Developers → API keys and put it in `.env.local`.
+  site → API & webhooks → API keys and put it in `.env.local`.
 - Only published content comes back. A new site whose pages are drafts returns no pages, so every route 404s:
   that's expected. Tell the developer to publish in Hearth; never add placeholder content to the code.
 - Content (text, menus, contact details, SEO) is edited in Hearth. The code owns design: tokens, layout and one
@@ -86,6 +86,9 @@ client components: the API key is secret.
 - `<HearthEmbed block={block} />`: renders an Embed block's `html` in a sandboxed iframe. Never inject `html` into the page.
 - Custom blocks: `{ type: "custom", data: { block: "<key>", values } }`, the site's own block types; map keys to components, skip unknown ones. `customBlocks.list()` / `hearthNext.getCustomBlocks()` describe their fields.
 - `<JsonLd data={page.meta.jsonLd} />`
+- `<GuideBlocks blocks={page.blocks} theme={{ card, heading, link, ... }} renderMarkdown={(md) => ...} linkComponent={Link} />`:
+  how-to guides (a "guides" collection) read inside The Smithy's products. Same blocks and structure everywhere;
+  each product passes its own class names (`GuideTheme`) and Markdown renderer. No CSS ships with it.
 
 ## Other entry points
 - `@the-smithy/hearth/webhooks`: `verifyWebhook(raw, header, secret)`, `parseWebhook(request, secret)`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-smithy/hearth",
-  "version": "0.13.1",
+  "version": "0.15.0",
   "description": "Typed client for the Hearth Delivery API: content, SEO, forms and publish webhooks.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -45,7 +45,7 @@
     "llms.md"
   ],
   "dependencies": {
-    "@the-smithy/hearth-schema": "^0.13.1"
+    "@the-smithy/hearth-schema": "^0.15.0"
   },
   "peerDependencies": {
     "next": ">=15",
@@ -62,6 +62,7 @@
   "devDependencies": {
     "@types/node": "^22.20.5",
     "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "next": "16.3.8",
     "react": "19.2.8",
     "react-dom": "19.2.8",