@the-smithy/hearth 0.13.0 → 0.14.0

package/README.md

@@ -9,12 +9,15 @@ nothing without a Hearth account. Developer access is by invitation: request it
 
 ## Getting started
 
-Most sites start from the starter template, which has this package set up already:
+Most sites start from the starter template, which has this package set up already. For example, for a site
+whose address in Hearth is `acme` (the part after `/admin/sites/` in Hearth's address bar):
 
 ```sh
-pnpm create @the-smithy/hearth-site my-site --site <your-site>
+pnpm create @the-smithy/hearth-site@latest acme-website --site acme
 ```
 
+`acme-website` is the folder it creates. Keep `@latest`: pnpm otherwise skips a release in its first day.
+
 To add it to an existing project instead:
 
 ```sh
@@ -22,9 +25,9 @@ pnpm add @the-smithy/hearth
 ```
 
 ```dotenv
-# .env.local
-HEARTH_SITE=<your-site>
-HEARTH_API_KEY=<a key from the site's Settings → Developers in Hearth>
+# .env.local (never committed)
+HEARTH_SITE=acme
+HEARTH_API_KEY=hk_…   # Hearth → the site → API & webhooks → API keys
 ```
 
 ```ts
@@ -37,6 +40,18 @@ export const hearth = createHearthClient({
 });
 ```
 
+## With an AI coding assistant
+
+The package ships `llms.md`, a short reference written for coding agents: point yours at
+`node_modules/@the-smithy/hearth/llms.md`. Once the key is in `.env.local`, the full API guide can be saved for
+the agent too (sites made from the starter have `pnpm hearth:docs` for this):
+
+```sh
+curl -H "Authorization: Bearer $HEARTH_API_KEY" https://hearth.thesmithy.io/admin/docs/api.md -o hearth-api.md
+```
+
+Keep `hearth-api.md` out of git, and the key out of chat: the agent only needs it in `.env.local`.
+
 ## Documentation
 
 Once you have developer access, the full documentation (every method, Next.js helpers, rendering blocks,

package/dist/react.d.ts

@@ -1,7 +1,60 @@
 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;
+};
+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"];
+/**
+ * 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 +95,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 };

package/dist/react.js

@@ -1,26 +1,161 @@
 // 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 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: { ...grid("16rem"), alignItems: "start", gap: "1.25rem" }, children: [
+          /* @__PURE__ */ jsxs("div", { style: { ...stack("0.75rem"), order: d.imagePosition === "left" ? 2 : 1 }, children: [
+            heading(d.heading),
+            md(d.markdown),
+            d.cta ? /* @__PURE__ */ jsx("p", { children: link(d.cta) }) : null
+          ] }),
+          image ? /* @__PURE__ */ jsx("figure", { style: { margin: 0, order: d.imagePosition === "left" ? 1 : 2 }, children: img(image) }) : 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);
+    return out ? /* @__PURE__ */ jsx("section", { 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,6 +171,8 @@ function HearthEmbed({ block, className }) {
   );
 }
 export {
+  GUIDE_BLOCK_TYPES,
+  GuideBlocks,
   HearthBlocks,
   HearthEmbed,
   JsonLd

package/llms.md

@@ -11,6 +11,21 @@ client components: the API key is secret.
   `export const hearth = createHearthClient({ site: process.env.HEARTH_SITE!, apiKey: process.env.HEARTH_API_KEY! })`
   `export const hearthNext = createHearthNext(hearth)` (from `@the-smithy/hearth/next`)
 
+## Working with the developer (read first)
+- Start by confirming the setup, and say what you found. In a site made from the starter: `pnpm hearth:check`
+  (connection, published pages, block types in use and any without a component). Elsewhere: call
+  `hearth.site.get()` and `hearth.pages.list()` from a server-side script.
+- Full guide (every block's fields, events, forms, previews, SEO): `pnpm hearth:docs` in the starter, or
+  `GET https://hearth.thesmithy.io/admin/docs/api.md` with `Authorization: Bearer $HEARTH_API_KEY`. Save it to
+  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 → 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
+  component per block type.
+
 ## Client (`@the-smithy/hearth`)
 - `site.get(): Site`
 - `pages.list(): PageSummary[]`
@@ -71,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.0",
+  "version": "0.14.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.0"
+    "@the-smithy/hearth-schema": "^0.14.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",