@the-smithy/create-hearth-site 0.28.0 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-smithy/create-hearth-site",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Start a new client website powered by Hearth: pnpm create @the-smithy/hearth-site",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -30,7 +30,7 @@
   ],
   "devDependencies": {
     "vitest": "^5.0.3",
-    "@the-smithy/hearth-schema": "^0.28.0"
+    "@the-smithy/hearth-schema": "^0.29.0"
   },
   "scripts": {
     "test": "node --test \"test/**/*.test.js\" && vitest run test/blocks.test.ts test/overrides.test.ts",

package/template/AGENTS.md

@@ -12,6 +12,7 @@ Before grepping or reading whole files, use [Drift](https://github.com/The-Smith
 - `drift query <symbol>` or `drift find <words>`: where something is defined
 - `drift show <symbol>` or `drift sig <symbol>`: its source, or just its signature
 - `drift outline <file>`: a file's definitions and imports
+- `drift docs <words>`: the section of the docs that covers something. Read it with `drift show <path:start-end>`
 - `drift refs <symbol>`, `drift importers <file>`, `drift tests --for <file>`: what uses it
 - `drift context <symbol or file>`: all of the above before changing something
 - `drift map`: orientation in a new repo
@@ -86,10 +87,10 @@ Work in this order, and stop at the first step that gets the result:
    don't reach it, so it falls behind Hearth. Use one only when everything above can't get there, build it from
    `src/hearth/ui.tsx` and the theme, and say why in `SITE.md`.
 
-To style blocks without setting up pages for them, open `/hearth/blocks` while `pnpm dev` is running: every block with
+To style blocks without setting up pages for them, open `/hearth/blocks` while `pnpm dev` is running: each block with
 its options and states, in sample content, drawn with this site's theme, so a change in `src/theme` shows at once.
-`/hearth/blocks?block=hero` shows one block. Its **Unstyled** switch (`/hearth/blocks/unstyled`) shows them with no design
-and each element's slot name. Neither is served in production. Global blocks and the site's custom blocks aren't in it.
+It shows one block at a time: `/hearth/blocks?block=hero` goes to one, and `?block=all` shows the whole list. Its
+**Unstyled** switch (`/hearth/blocks/unstyled`) shows them with no design and each element's slot name. Neither is served in production. Global blocks and the site's custom blocks aren't in it.
 Without a browser, the unstyled page is `node_modules/@the-smithy/hearth/block-reference.html`, but it's large: for slots,
 use `src/hearth/theme/defaults.ts`.
 

package/template/README.md

@@ -98,7 +98,7 @@ Keep the API key out of chat: the agent never needs to see it, only `.env.local`
 | `src/theme/theme.css` | Brand tokens (colors, fonts, content width) and the site's own CSS. **Start here** |
 | `src/theme/index.ts` | The Tailwind classes of any part of any block, page, form, header or footer, by slot |
 | `src/hearth/theme/defaults.ts` | Every slot and its default classes: read it to find the slot to change |
-| `/hearth/blocks` | Not a file: while `pnpm dev` runs, this address shows every block on one page with your theme, without setting up pages for them. `?block=hero` shows one. Its **Unstyled** switch shows them with no design, and each element's slot name |
+| `/hearth/blocks` | Not a file: while `pnpm dev` runs, this address shows each block with your theme, one at a time, without setting up pages for them. `?block=hero` goes to one, and `?block=all` shows the whole list. Its **Unstyled** switch shows them with no design, and each element's slot name |
 | `src/theme/fonts.ts` | Web fonts (next/font) |
 | `src/theme/custom-blocks.tsx` | Components for the site's own block types (Settings → Custom blocks in Hearth) |
 | `src/theme/overrides.tsx` | Last resort: replace a whole block's component, the logo, the footer, the event or fundraiser page, their cards or the donation form (see `AGENTS.md`) |

package/template/src/app/hearth/blocks/unstyled/route.ts

@@ -1,10 +1,11 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 
-const SWITCH = `<span class="view-switch"><span class="view-current">Unstyled</span><a href="/hearth/blocks" onclick="this.href='/hearth/blocks'+location.hash">This site's theme</a></span>`;
+// Stays on the same block, or on the whole list: #block-hero here is ?block=hero there.
+const SWITCH = `<span class="view-switch"><span class="view-current">Unstyled</span><a href="/hearth/blocks" onclick="var id=location.hash.slice(1);if(id&&id!=='top')this.href='/hearth/blocks?block='+id.replace('block-','')">This site's theme</a></span>`;
 
 /**
- * Every block unstyled, with its options, states and slot names, to build against while developing. Only under
+ * Each block unstyled, with its options, states and slot names, to build against while developing. Only under
  * `pnpm dev`: the page comes from the SDK, so it matches this site's release, and visitors never see it.
  */
 export function GET() {

package/template/src/hearth/block-library/controls.tsx

@@ -24,15 +24,6 @@ export function SampleGuard() {
   return null;
 }
 
-/** A link to the block library's other view, staying on the same block. */
-export function ViewLink({ href, children }: { href: string; children: ReactNode }) {
-  return (
-    <a href={href} className="hearth-library-view" onClick={(e) => (e.currentTarget.href = href + window.location.hash)}>
-      {children}
-    </a>
-  );
-}
-
 /** One sample failing (a site without Giving has no fundraisers to offer) leaves the rest of the page working. */
 export class SampleBoundary extends Component<{ children: ReactNode }, { message?: string }> {
   state: { message?: string } = {};

package/template/src/hearth/block-library/page.tsx

@@ -1,14 +1,19 @@
 import type { Metadata } from "next";
+import Link from "next/link";
 import { notFound } from "next/navigation";
 import { Fragment, Suspense, type ReactNode } from "react";
 import { Blocks } from "../blocks";
-import { SampleBoundary, SampleGuard, ViewLink } from "./controls";
+import { SampleBoundary, SampleGuard } from "./controls";
 import { FormStates, Ground, GROUND_NAMES } from "./pieces";
 import { blockSamples, libraryGroups } from "./samples";
 
 export const metadata: Metadata = { title: "Block library", robots: { index: false, follow: false } };
 
 const TONES = ["default", "muted", "inverse", "accent"] as const;
+const START_HERE = [
+  { type: "grounds", label: "Grounds and buttons" },
+  { type: "form-states", label: "Form states" },
+];
 
 // Its own plain styles, so that nothing in a site's theme changes the tools around the samples.
 const CSS = `
@@ -19,6 +24,9 @@ const CSS = `
 .hearth-library-switch > * { padding: 4px 12px; }
 .hearth-library-switch > * + * { border-left: 1px solid #d8d8d4; }
 .hearth-library-current { background: #1f4fd8; color: #fff; }
+.hearth-library-steps { display: inline-flex; gap: 8px; }
+.hearth-library-steps > * { padding: 4px 12px; border: 1px solid #d8d8d4; border-radius: 6px; }
+.hearth-library-steps > span { color: #5c5c58; }
 .hearth-library-jump { position: relative; }
 .hearth-library-jump summary { cursor: pointer; padding: 4px 12px; border: 1px solid #d8d8d4; border-radius: 6px; list-style: none; }
 .hearth-library-jump summary::after { content: " ▾"; }
@@ -52,18 +60,26 @@ function Sample({ id, name, label, action, children }: { id?: string; name: stri
 }
 
 /**
- * Every block on one page, drawn by the real components with this site's theme and overrides, so that a change in
- * src/theme shows here at once. For `pnpm dev` only. Its samples stand in for a site's content, so nothing depends on
- * which pages exist, and nothing here is saved. ?block=hero shows one block's samples.
+ * The blocks, drawn by the real components with this site's theme and overrides, so that a change in src/theme shows
+ * here at once. For `pnpm dev` only. Its samples stand in for a site's content, so nothing depends on which pages
+ * exist, and nothing here is saved. It shows one block at a time, from ?block=hero; ?block=all shows the whole list.
  */
 export default async function BlockLibrary({ searchParams }: { searchParams: Promise<{ block?: string | string[] }> }) {
   if (process.env.NODE_ENV !== "development") notFound();
   const { block } = await searchParams;
   const samples = blockSamples(new Date());
-  const all = libraryGroups.flatMap((g) => g.blocks);
-  const only = all.find((b) => b.type === block);
-  const unstyled = `/hearth/blocks/unstyled${only ? `#block-${only.type}` : ""}`;
-  const showing = only ? [only] : all;
+  const blocks = libraryGroups.flatMap((g) => g.blocks);
+  const items: { type: string; label: string }[] = [...START_HERE, ...blocks];
+  const everything = block === "all";
+  const index = Math.max(
+    items.findIndex((item) => item.type === block),
+    0,
+  );
+  const current = items[index];
+  const anchor = START_HERE.includes(current) ? current.type : `block-${current.type}`;
+  const unstyled = `/hearth/blocks/unstyled#${everything ? "all" : anchor}`;
+  const only = (type: string) => (everything ? <Link href={`/hearth/blocks?block=${type}`}>Only this block</Link> : undefined);
+  const showing = everything ? blocks : blocks.filter((b) => b.type === current.type);
   return (
     <>
       <style>{CSS}</style>
@@ -71,42 +87,51 @@ export default async function BlockLibrary({ searchParams }: { searchParams: Pro
       <div className="hearth-library-bar">
         <b>Block library</b>
         <span className="hearth-library-switch">
-          <ViewLink href={unstyled}>Unstyled</ViewLink>
+          <a href={unstyled}>Unstyled</a>
           <span className="hearth-library-current">This site&apos;s theme</span>
         </span>
-        <details className="hearth-library-jump">
-          <summary>{only ? only.label : "All blocks"}</summary>
+        <span className="hearth-library-switch">
+          {everything ? <Link href="/hearth/blocks">One block</Link> : <span className="hearth-library-current">One block</span>}
+          {everything ? <span className="hearth-library-current">All blocks</span> : <Link href={`/hearth/blocks?block=all#${anchor}`}>All blocks</Link>}
+        </span>
+        <details key={everything ? "all" : current.type} className="hearth-library-jump">
+          <summary>{everything ? "Choose a block" : current.label}</summary>
           <nav aria-label="Blocks">
-            <a href="/hearth/blocks">Every block on one page</a>
-            {libraryGroups.map((g) => (
+            {[{ group: "Start here", blocks: START_HERE }, ...libraryGroups].map((g) => (
               <Fragment key={g.group}>
                 <p>{g.group}</p>
                 {g.blocks.map((b) => (
-                  <a key={b.type} href={`/hearth/blocks?block=${b.type}`}>
+                  <Link key={b.type} href={`/hearth/blocks?block=${b.type}`}>
                     {b.label}
-                  </a>
+                  </Link>
                 ))}
               </Fragment>
             ))}
           </nav>
         </details>
+        {everything ? null : (
+          <span className="hearth-library-steps">
+            {index > 0 ? <Link href={`/hearth/blocks?block=${items[index - 1].type}`}>← Previous</Link> : <span>← Previous</span>}
+            {index < items.length - 1 ? <Link href={`/hearth/blocks?block=${items[index + 1].type}`}>Next →</Link> : <span>Next →</span>}
+          </span>
+        )}
         <span className="hearth-library-note">Sample content. Links and forms here do nothing.</span>
       </div>
-      {only
-        ? null
-        : TONES.map((tone) => (
-            <Sample key={tone} id={tone === "default" ? "grounds" : undefined} name="Grounds" label={`${GROUND_NAMES[tone]} ground`}>
+      {everything || current.type === "grounds"
+        ? TONES.map((tone) => (
+            <Sample key={tone} id={tone === "default" ? "grounds" : undefined} name="Grounds" label={`${GROUND_NAMES[tone]} ground`} action={only("grounds")}>
               <Ground tone={tone} />
             </Sample>
-          ))}
-      {only ? null : (
-        <Sample id="form-states" name="Form states" label="Errors, filled-in fields, options and the success message">
+          ))
+        : null}
+      {everything || current.type === "form-states" ? (
+        <Sample id="form-states" name="Form states" label="Errors, filled-in fields, options and the success message" action={only("form-states")}>
           <FormStates />
         </Sample>
-      )}
+      ) : null}
       {showing.map((b) =>
         samples[b.type].map((s, i) => (
-          <Sample key={s.block.id} id={i ? undefined : `block-${b.type}`} name={b.label} label={s.label} action={only ? <a href="/hearth/blocks">Show every block</a> : <a href={`/hearth/blocks?block=${b.type}`}>Only this block</a>}>
+          <Sample key={s.block.id} id={i ? undefined : `block-${b.type}`} name={b.label} label={s.label} action={only(b.type)}>
             <Blocks blocks={[s.block]} />
           </Sample>
         )),