@sandboxsonny/ace-kit 0.6.0 → 0.7.1

package/dist/react-router-server.d.ts

@@ -142,7 +142,7 @@ declare const getMenuLinks: (handle: string, options?: {
     fallback?: AceNavigationLink[];
 }) => Promise<AceNavigationLink[]>;
 /**
- * The loader for the route that draws every page. The route is a catch-all (`route("*", "routes/page.tsx")`):
+ * The loader for the route that draws every page. The route is a catch-all, plus an index line because "*" does not match "/" (`index("routes/page.tsx", { id: "home" })` and `route("*", "routes/page.tsx", { id: "page" })`):
  *
  *     export const loader = createPageLoader<PageValues>();
  *     export { headers } from "@sandboxsonny/ace-kit/react-router/server";

package/dist/vite.js

@@ -1,4 +1,4 @@
-import { startDevSite, startSectionSync } from './chunk-G5FGBOFT.js';
+import { startDevSite, startSectionSync } from './chunk-2W2NWDKV.js';
 import './chunk-N5DIMG3X.js';
 import { resolve } from 'path';
 import { loadEnv } from 'vite';

package/docs/astro.md

@@ -15,21 +15,19 @@ export default defineConfig({
 });
 ```
 
-The integration declares three settings, adds the middleware that lets the CMS's admin app (and only it) frame the site for [live preview](./live-preview.md), and makes Vite process the kit. The settings are read when the server starts, not baked into the build, so one build runs anywhere:
+The integration declares the site's settings, adds the middleware that lets the CMS's admin app (and only it) frame the site for [live preview](./live-preview.md), and makes Vite process the kit. The settings are read when the server starts, not baked into the build, so one build runs anywhere:
 
-| Setting                    | Default                                              | Meaning                                                   |
-| -------------------------- | ---------------------------------------------------- | --------------------------------------------------------- |
-| `ACE_API_URL`              | `https://api.ace-cms.co.uk`                          | where the CMS Ace API lives                               |
-| `ACE_SITE_DOMAIN`          | the host of Astro's `site` setting, else `localhost` | the domain this site has in the CMS (the port is ignored) |
-| `ACE_PREVIEW_ADMIN_ORIGIN` | `https://app.ace-cms.co.uk`                          | where the CMS admin app runs                              |
+| Setting           | Default                                              | Meaning                                                   |
+| ----------------- | ---------------------------------------------------- | --------------------------------------------------------- |
+| `ACE_SITE_DOMAIN` | the host of Astro's `site` setting, else `localhost` | the domain this site has in the CMS (the port is ignored) |
 
-CMS Ace is a hosted platform, so a site normally sets none of these except its domain, and it does that with Astro's own `site` setting, which Astro needs for canonical addresses anyway:
+A site connects to CMS Ace by itself and only needs to say which site it is, which it does with Astro's own `site` setting, which Astro needs for canonical addresses anyway:
 
 ```js
 export default defineConfig({ site: "https://www.example.com", integrations: [ace()] });
 ```
 
-To try a site without editing the config, `npm run dev -- --site https://www.example.com` does the same. `ACE_SITE_DOMAIN`, when set, wins. Set `ACE_API_URL` and `ACE_PREVIEW_ADMIN_ORIGIN` (in `.env`) only to use a CMS running on your own machine, for example `http://localhost:8080` and `http://localhost:5173`.
+To try a site without editing the config, `npm run dev -- --site https://www.example.com` does the same. `ACE_SITE_DOMAIN`, when set, wins.
 
 ## Pages
 

package/docs/command-line.md

@@ -7,11 +7,12 @@ npx @sandboxsonny/ace-kit create my-site --site my-site.com   # make a new site
 npx ace-kit login      # sign in
 npx ace-kit whoami     # who am I signed in as?
 npx ace-kit logout     # sign out
+npx ace-kit doctor     # check this site is set up properly (see Checking a site)
 npx ace-kit generate   # write TypeScript types (see Typed content)
 npx ace-kit sync       # send your section types to the CMS (see Sections)
 ```
 
-Commands talk to the hosted CMS Ace unless told otherwise. Only for a CMS on your own machine, give `--api-url`, or set `ACE_API_URL` in the environment or a `.env` file in the folder you run it in. Failing both, a command uses the address you last signed in to (kept in a small file beside your logins), and failing that the hosted one, so `ace-kit login` and `ace-kit whoami` need no flags at all. Commands about a site (`sync`, `generate`) take `--site example.com`, or read `ACE_SITE_DOMAIN`.
+Commands connect to CMS Ace for you, so `ace-kit login` and `ace-kit whoami` need no flags at all. Commands about a site (`sync`, `generate`, `doctor`) take `--site example.com`, or read `ACE_SITE_DOMAIN`.
 
 ## Making a site
 
@@ -23,24 +24,45 @@ One command makes everything a new site needs:
 
 1. **Checks** the folder, the domain and the name, before anything is made.
 2. **Signs you in** if you aren't already (your browser opens; type the code from the terminal, as in [Signing in](#signing-in)).
-3. **Makes the site in CMS Ace** and gives it a starter: a `pages` content type, Home, About and Contact entries, a main menu and, for the Astro starter, the three example section types (hero, FAQ, gallery).
+3. **Makes the site in CMS Ace** and gives it a starter: a `pages` content type, Home, About and Contact entries, a main menu and the three example section types (hero, FAQ, gallery).
 4. **Copies a starter site** into `my-site/` with its name, domain and package name filled in.
 
 If a site with that domain already exists in CMS Ace, it is **left alone** (nothing is added to it, in case it has real content), a warning says so, and only the folder is made. If the CMS refuses to make the site (for instance, you have made as many as your account allows) nothing is made at all.
 
 Your account must be a **partner or super admin** (only they can make sites). The login `create` uses can set up the site it just made, for an hour, and no other site: it can't write content anywhere else.
 
-| Option                            | Meaning                                                                                |
-| --------------------------------- | -------------------------------------------------------------------------------------- |
-| `<domain>` (or `--site <domain>`) | The domain the site has in CMS Ace. Required.                                          |
-| `--framework astro\|react-router` | `astro` (the default) or `react-router`. The React Router starter has no sections yet. |
-| `--name <name>`                   | The name shown to visitors. Default: made from the folder, so `my-site` is "My Site".  |
-| `--api-url <address>`             | Only for a CMS on your own machine (or set `ACE_API_URL`).                             |
-
-Against a CMS on your own machine (`--api-url` or `ACE_API_URL` set to `http://localhost:8080`), it also writes a `.env` in the new folder with `ACE_API_URL` and `ACE_PREVIEW_ADMIN_ORIGIN=http://localhost:5173`, and sets the site's Preview address to the local dev server (`http://localhost:4321`, or 4322 for React Router), so the site and live preview work with no more setup. Against the hosted CMS Ace none of that is needed.
+| Option                            | Meaning                                                                               |
+| --------------------------------- | ------------------------------------------------------------------------------------- |
+| `<domain>` (or `--site <domain>`) | The domain the site has in CMS Ace. Required.                                         |
+| `--framework astro\|react-router` | `astro` (the default) or `react-router`. Both have the same three example sections.   |
+| `--name <name>`                   | The name shown to visitors. Default: made from the folder, so `my-site` is "My Site". |
 
 The folder must not exist yet (or must be empty). The starter is a small server-rendered site with a header, footer, rich text, live preview and Prettier, ESLint, tests and a CI workflow. When it finishes: `cd my-site`, `npm install`, `npm run dev`.
 
+## Checking a site
+
+```sh
+npx ace-kit doctor
+```
+
+Run it in your site's folder when something isn't working. It changes nothing, never prints your login, and says what to do about each problem:
+
+```
+  ✓ Node 24.14.0
+  ✓ An Astro site
+  ✓ Ace Kit 0.6.0 is installed
+  ✓ CMS: https://api.ace-cms.co.uk (the hosted CMS Ace)
+  ✓ Site: shop.example.com
+  ✓ The CMS answers
+  ✓ The CMS knows the site: "Shop"
+  ✓ Pages has 3 published entries, including home
+  ✓ Signed in as sam@example.com
+  ✓ 3 section types in your code (faq, gallery, hero)
+  ✓ The CMS has all of them
+```
+
+It checks your Node version, that Ace Kit is installed, which CMS and site your settings point at, that the CMS can be reached and knows the site, that the site has its Pages content, that you are signed in, the site's preview address, and that the section types in your code match the CMS. `✗` is a problem (the command exits with 1), `!` is a warning, `-` is a note. It takes `--site` and `--dir` like `sync`.
+
 ## Signing in
 
 ```sh

package/docs/dev-sites.md

@@ -34,7 +34,7 @@ A dev site is never merged into the live site. When your change is ready, deploy
 
 ## If something stops it
 
-The dev server says so once, and carries on showing the **live site**, read-only, with section sync off: you aren't signed in (run `npx ace-kit login --api-url <address>`), your account can't have a dev site, the site isn't one you can see, or the CMS can't be reached.
+The dev server says so once, and carries on showing the **live site**, read-only, with section sync off: you aren't signed in (run `npx ace-kit login`), your account can't have a dev site, the site isn't one you can see, or the CMS can't be reached.
 
 ## Housekeeping
 

package/docs/react-router.md

@@ -4,7 +4,7 @@ Ace Kit has a React Router adapter, so a site only writes its design. It needs `
 
 ```
 app/
-  routes.ts            route("*", "routes/page.tsx")            one route draws every page
+  routes.ts            index + route("*") for routes/page.tsx  one route draws every page
   entry.server.tsx     one line
   root.tsx             createRootLoader + your layout and header
   routes/page.tsx      createPageLoader + your page
@@ -26,13 +26,11 @@ export default defineConfig({ plugins: [ace(), reactRouter()] });
 
 The settings are environment variables, read when the server starts, so one build runs anywhere. Put them in `.env` for development and in the host's environment for production:
 
-| Variable                   | Default                     | Meaning                                                   |
-| -------------------------- | --------------------------- | --------------------------------------------------------- |
-| `ACE_API_URL`              | `https://api.ace-cms.co.uk` | where the CMS Ace API lives                               |
-| `ACE_SITE_DOMAIN`          | `localhost`                 | the domain this site has in the CMS (the port is ignored) |
-| `ACE_PREVIEW_ADMIN_ORIGIN` | `https://app.ace-cms.co.uk` | where the CMS admin app runs                              |
+| Variable          | Default     | Meaning                                                   |
+| ----------------- | ----------- | --------------------------------------------------------- |
+| `ACE_SITE_DOMAIN` | `localhost` | the domain this site has in the CMS (the port is ignored) |
 
-CMS Ace is a hosted platform, so a site normally sets only `ACE_SITE_DOMAIN`. Set the other two only to use a CMS on your own machine (`http://localhost:8080` and `http://localhost:5173`).
+A site connects to CMS Ace by itself and only needs to say which site it is, with `ACE_SITE_DOMAIN`.
 
 **2. The server entry**, which renders pages and lets the CMS's admin app (and only it) frame the site for [live preview](./live-preview.md):
 
@@ -47,9 +45,13 @@ It waits until a page is completely ready before answering (every page is fully
 
 ```ts
 // app/routes.ts
-import { type RouteConfig, route } from "@react-router/dev/routes";
+import { type RouteConfig, index, route } from "@react-router/dev/routes";
 
-export default [route("*", "routes/page.tsx")] satisfies RouteConfig;
+// "/" is the home entry. A "*" route doesn't match "/", so the home page needs its own `index` line.
+export default [
+  index("routes/page.tsx", { id: "home" }),
+  route("*", "routes/page.tsx", { id: "page" }),
+] satisfies RouteConfig;
 ```
 
 ```tsx
@@ -117,3 +119,28 @@ export async function loader() {
 ## Without the adapter
 
 Everything the adapter does is built from the framework-free [core](./getting-started.md): `loadPage`, `loadMenuLinks`, `previewTokenFrom`, `addFramingPolicy`, the [React components](./react.md) and `usePreviewRefresh`. The adapter is about 150 lines; read it if you need to do something it doesn't.
+
+## Sections
+
+A sections field is drawn with `AceSections`, which gives each section to the component for its kind. Each kind is a component with a `*.schema.ts` file beside it saying what an editor can fill in (see [Sections](./sections.md)):
+
+```tsx
+// app/components/page-content.tsx
+import { AceSections } from "@sandboxsonny/ace-kit/react-router";
+
+import { Hero } from "~/components/sections/hero";
+
+<AceSections sections={entry.values.content} components={{ hero: Hero }} />;
+```
+
+```tsx
+// app/components/sections/hero.tsx, typed from hero.schema.ts
+import type { SectionOf } from "@sandboxsonny/ace-kit";
+import type hero from "./hero.schema";
+
+export function Hero({ section }: { section: SectionOf<typeof hero> }) {
+  return <h2>{section.values.heading}</h2>;
+}
+```
+
+Schema files in `app/` (or `src/`) are found by `ace-kit sync`, and while `npm run dev` runs, saving one syncs it to the CMS. A new site from `npx @sandboxsonny/ace-kit create --framework react-router` comes with a hero, an FAQ and a gallery.

package/docs/react.md

@@ -74,8 +74,11 @@ Pass `adminOrigin` only for a page shown with a preview token (`previewTokenFrom
 ## A route in React Router 7
 
 ```tsx
-// app/routes.ts: one route draws every page
-export default [route("*", "routes/page.tsx")] satisfies RouteConfig;
+// app/routes.ts: one route draws every page ("/" needs its own index line: a "*" route does not match it)
+export default [
+  index("routes/page.tsx", { id: "home" }),
+  route("*", "routes/page.tsx", { id: "page" }),
+] satisfies RouteConfig;
 
 // app/routes/page.tsx
 export async function loader({ request, params }: Route.LoaderArgs) {

package/docs/typed-content.md

@@ -12,7 +12,7 @@ or with the settings in the environment:
 ACE_SITE_DOMAIN=www.example.com npx ace-kit generate
 ```
 
-Add `--api-url http://localhost:8080` (or `ACE_API_URL`) only for a CMS on your own machine. It reads `GET /public/content-types` (no login: it describes field names and kinds, never entries) and writes `src/ace-kit.generated.d.ts` (change it with `--out`). Make sure the file is inside your `tsconfig` `include`. Commit it, and run the command again whenever content types change (a good moment is a CI step, or a `generate` script next to `dev`).
+It reads `GET /public/content-types` (no login: it describes field names and kinds, never entries) and writes `src/ace-kit.generated.d.ts` (change it with `--out`). Make sure the file is inside your `tsconfig` `include`. Commit it, and run the command again whenever content types change (a good moment is a CI step, or a `generate` script next to `dev`).
 
 ```ts
 // ace-kit.generated.d.ts (generated)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandboxsonny/ace-kit",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Everything a website needs to use CMS Ace: a typed client, addressing, images, menus, rich text, live preview, and Astro and React adapters.",
   "keywords": [
     "cms",

package/templates/react-router/app/ace-kit.generated.d.ts

@@ -1,5 +1,5 @@
 // Generated by ace-kit from localhost. Do not edit: run `ace-kit generate` to update it.
-import type { AceImageData, AceRichTextDocument } from "@sandboxsonny/ace-kit";
+import type { AceImageData, AceLinkData, AceRichTextDocument, AceSection } from "@sandboxsonny/ace-kit";
 
 declare module "@sandboxsonny/ace-kit" {
   interface AceContentTypes {
@@ -11,6 +11,12 @@ declare module "@sandboxsonny/ace-kit" {
       "body"?: AceRichTextDocument;
       /** Hero image */
       "hero"?: AceImageData;
+      /** Published */
+      "published"?: string;
+      /** Button */
+      "button"?: AceLinkData;
+      /** Content */
+      "content"?: AceSection[];
     };
   }
 }

package/templates/react-router/app/app.css

@@ -170,3 +170,88 @@ a {
   padding-left: 1rem;
   font-style: italic;
 }
+.published {
+  color: var(--colour-muted);
+  font-size: 0.9rem;
+}
+.actions {
+  margin-top: 2rem;
+}
+
+/* Sections: a hero, an FAQ and a gallery (see components/sections) */
+.hero {
+  padding-block: 3rem;
+}
+.hero__inner {
+  display: grid;
+  gap: 2rem;
+  align-items: center;
+}
+@media (min-width: 48rem) {
+  .hero__inner--with-picture {
+    grid-template-columns: 1fr 1fr;
+  }
+}
+.hero h2 {
+  margin: 0 0 0.75rem;
+  font-size: 2.25rem;
+  line-height: 1.15;
+}
+.hero__subheading {
+  margin: 0 0 1.5rem;
+  color: var(--colour-muted);
+  font-size: 1.15rem;
+}
+.hero__picture img {
+  border-radius: 0.5rem;
+}
+
+.faq {
+  max-width: 42rem;
+}
+.faq h2 {
+  margin: 0 0 1rem;
+  font-size: 1.75rem;
+}
+.faq details {
+  border-bottom: 1px solid var(--colour-surface);
+  padding-block: 0.75rem;
+}
+.faq summary {
+  cursor: pointer;
+  font-weight: 600;
+}
+.faq__answer {
+  margin-top: 0.5rem;
+  color: var(--colour-muted);
+}
+.faq__answer > * + * {
+  margin-top: 0.75rem;
+}
+
+.gallery__note {
+  margin: 0 0 1rem;
+  color: var(--colour-muted);
+  font-size: 0.9rem;
+}
+.gallery__photos {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(14rem, 1fr));
+  gap: 1rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+.gallery__photos figure {
+  margin: 0;
+}
+.gallery__photos img {
+  border-radius: 0.5rem;
+  width: 100%;
+  object-fit: cover;
+}
+.gallery__photos figcaption {
+  margin-top: 0.4rem;
+  color: var(--colour-muted);
+  font-size: 0.9rem;
+}

package/templates/react-router/app/components/page-content.tsx

@@ -1,32 +1,55 @@
+import { formatAceDate } from "@sandboxsonny/ace-kit";
 import type { AceEntry } from "@sandboxsonny/ace-kit";
-import { AceImage, AceRichText, AceTextArea } from "@sandboxsonny/ace-kit/react-router";
+import { AceImage, AceLink, AceRichText, AceSections, AceTextArea } from "@sandboxsonny/ace-kit/react-router";
 
+import { Faq } from "~/components/sections/faq";
+import { Gallery } from "~/components/sections/gallery";
+import { Hero } from "~/components/sections/hero";
 import type { PageValues } from "~/types/page";
 
-/** An entry of the "Pages" content type: its title (or headline), description, hero image and body. */
+/** An entry of the "Pages" content type: its title (or headline), description, hero image, body, button and sections. */
 export function PageContent({ entry }: { entry: AceEntry<PageValues> }) {
-  const { headline, body, hero } = entry.values;
+  const { headline, body, hero, published, button, content } = entry.values;
   return (
-    <section className="section">
-      <div className="container prose">
-        <h1>{headline || entry.title}</h1>
-        {entry.description ? <p className="intro">{entry.description}</p> : null}
-        {hero ? (
-          <figure>
-            <AceImage image={hero} sizes="(min-width: 64rem) 64rem, 100vw" lazy={false} />
-          </figure>
-        ) : null}
-        {
-          // A site made before its Body field was rich text still has plain text, with blank lines between paragraphs.
-          typeof body === "string" ? (
-            <AceTextArea value={body} />
-          ) : body ? (
-            <div className="rich-text">
-              <AceRichText document={body} />
-            </div>
-          ) : null
-        }
-      </div>
-    </section>
+    <>
+      <section className="section">
+        <div className="container prose">
+          <h1>{headline || entry.title}</h1>
+          {entry.description ? <p className="intro">{entry.description}</p> : null}
+          {
+            // A date field is a day with no time of day, so it is the same day wherever the server runs.
+            published ? (
+              <p className="published">
+                Published <time dateTime={published}>{formatAceDate(published, { locale: "en-GB" }) ?? published}</time>
+              </p>
+            ) : null
+          }
+          {hero ? (
+            <figure>
+              <AceImage image={hero} sizes="(min-width: 64rem) 64rem, 100vw" lazy={false} />
+            </figure>
+          ) : null}
+          {
+            // A site made before its Body field was rich text still has plain text, with blank lines between paragraphs.
+            typeof body === "string" ? (
+              <AceTextArea value={body} />
+            ) : body ? (
+              <div className="rich-text">
+                <AceRichText document={body} />
+              </div>
+            ) : null
+          }
+          {
+            // A link field: the editor's words and where it goes, already worked out by the CMS.
+            button ? (
+              <p className="actions">
+                <AceLink link={button} className="button" />
+              </p>
+            ) : null
+          }
+        </div>
+      </section>
+      <AceSections sections={content} components={{ hero: Hero, faq: Faq, gallery: Gallery }} />
+    </>
   );
 }

package/templates/react-router/app/components/sections/faq.schema.ts

@@ -0,0 +1,17 @@
+import { defineSection } from "@sandboxsonny/ace-kit";
+
+// An FAQ is a heading and a list of questions. The questions are blocks: the editor adds as many as they like.
+export default defineSection({
+  handle: "faq",
+  name: "FAQ",
+  fields: [{ handle: "heading", label: "Heading", type: "text" }],
+  blocks: {
+    question: {
+      name: "Question",
+      fields: [
+        { handle: "question", label: "Question", type: "text", required: true },
+        { handle: "answer", label: "Answer", type: "richtext" },
+      ],
+    },
+  },
+});

package/templates/react-router/app/components/sections/faq.tsx

@@ -0,0 +1,26 @@
+import type { SectionOf } from "@sandboxsonny/ace-kit";
+import { AceRichText } from "@sandboxsonny/ace-kit/react-router";
+
+import type faq from "./faq.schema";
+
+/** An FAQ: a heading and a list of questions, each a block. Its fields and blocks are in faq.schema.ts. */
+export function Faq({ section }: { section: SectionOf<typeof faq> }) {
+  const { heading } = section.values;
+  return (
+    <section className="section" data-section={section.type}>
+      <div className="container faq">
+        {heading ? <h2>{heading}</h2> : null}
+        {section.blocks.map((block) => (
+          <details key={block.id}>
+            <summary>{block.values.question}</summary>
+            {block.values.answer ? (
+              <div className="faq__answer">
+                <AceRichText document={block.values.answer} />
+              </div>
+            ) : null}
+          </details>
+        ))}
+      </div>
+    </section>
+  );
+}

package/templates/react-router/app/components/sections/gallery.schema.ts

@@ -0,0 +1,20 @@
+import { defineSection } from "@sandboxsonny/ace-kit";
+
+// A gallery is a heading, a date and a list of photos. The photos are blocks.
+export default defineSection({
+  handle: "gallery",
+  name: "Gallery",
+  fields: [
+    { handle: "heading", label: "Heading", type: "text" },
+    { handle: "published", label: "Published", type: "date" },
+  ],
+  blocks: {
+    photo: {
+      name: "Photo",
+      fields: [
+        { handle: "image", label: "Image", type: "image" },
+        { handle: "caption", label: "Caption", type: "text" },
+      ],
+    },
+  },
+});

package/templates/react-router/app/components/sections/gallery.tsx

@@ -0,0 +1,39 @@
+import { formatAceDate } from "@sandboxsonny/ace-kit";
+import type { SectionOf } from "@sandboxsonny/ace-kit";
+import { AceImage } from "@sandboxsonny/ace-kit/react-router";
+
+import type gallery from "./gallery.schema";
+
+/** A gallery: a heading, a date and a list of photos, each a block. Its fields and blocks are in gallery.schema.ts. */
+export function Gallery({ section }: { section: SectionOf<typeof gallery> }) {
+  const { heading, published } = section.values;
+  const photos = section.blocks.filter((block) => block.values.image || block.values.caption);
+  return (
+    <section className="section" data-section={section.type}>
+      <div className="container">
+        {heading ? <h2>{heading}</h2> : null}
+        {published ? (
+          <p className="gallery__note">
+            <time dateTime={published}>{formatAceDate(published, { locale: "en-GB" }) ?? published}</time>
+          </p>
+        ) : null}
+        {photos.length > 0 ? (
+          <ul className="gallery__photos">
+            {photos.map((photo) => (
+              <li key={photo.id}>
+                <figure>
+                  {photo.values.image ? (
+                    <AceImage image={photo.values.image} sizes="(min-width: 48rem) 20rem, 100vw" />
+                  ) : null}
+                  {photo.values.caption ? <figcaption>{photo.values.caption}</figcaption> : null}
+                </figure>
+              </li>
+            ))}
+          </ul>
+        ) : (
+          <p className="gallery__note">No photos yet.</p>
+        )}
+      </div>
+    </section>
+  );
+}

package/templates/react-router/app/components/sections/hero.schema.ts

@@ -0,0 +1,14 @@
+import { defineSection } from "@sandboxsonny/ace-kit";
+
+// What a hero can hold. The CMS learns it from this file (the dev server syncs it when it changes), and Hero.astro's
+// props are typed from it.
+export default defineSection({
+  handle: "hero",
+  name: "Hero",
+  fields: [
+    { handle: "heading", label: "Heading", type: "text", required: true },
+    { handle: "subheading", label: "Subheading", type: "textarea" },
+    { handle: "picture", label: "Picture", type: "image" },
+    { handle: "button", label: "Button", type: "link" },
+  ],
+});

package/templates/react-router/app/components/sections/hero.tsx

@@ -0,0 +1,25 @@
+import type { SectionOf } from "@sandboxsonny/ace-kit";
+import { AceImage, AceLink } from "@sandboxsonny/ace-kit/react-router";
+
+import type hero from "./hero.schema";
+
+/** A hero: a heading, an optional subheading and button, and an optional picture. Its fields are in hero.schema.ts. */
+export function Hero({ section }: { section: SectionOf<typeof hero> }) {
+  const { heading, subheading, picture, button } = section.values;
+  return (
+    <section className="hero section--surface" data-section={section.type}>
+      <div className={picture ? "container hero__inner hero__inner--with-picture" : "container hero__inner"}>
+        <div>
+          <h2>{heading}</h2>
+          {subheading ? <p className="hero__subheading">{subheading}</p> : null}
+          {button ? <AceLink link={button} className="button" /> : null}
+        </div>
+        {picture ? (
+          <div className="hero__picture">
+            <AceImage image={picture} sizes="(min-width: 64rem) 32rem, 100vw" lazy={false} />
+          </div>
+        ) : null}
+      </div>
+    </section>
+  );
+}

package/templates/react-router/app/routes/page.test.tsx

@@ -47,6 +47,60 @@ describe("the page", () => {
     expect(screen.getByRole("link", { name: "more" }).getAttribute("href")).toBe("/pages/contact");
   });
 
+  it("shows the published date and the button", () => {
+    show({
+      kind: "entry",
+      status: 200,
+      entry: {
+        ...entry,
+        values: { ...entry.values, published: "2026-10-13", button: { href: "/pages/contact", label: "Get in touch" } },
+      },
+      headers: {},
+    });
+    expect(screen.getByText("13 October 2026")).toBeTruthy();
+    expect(screen.getByRole("link", { name: "Get in touch" }).getAttribute("href")).toBe("/pages/contact");
+  });
+
+  it("draws each section with the component for its kind, in order, and leaves out a kind it has none for", () => {
+    const richText = (text: string) => ({
+      type: "doc",
+      content: [{ type: "paragraph", content: [{ type: "text", text }] }],
+    });
+    show({
+      kind: "entry",
+      status: 200,
+      entry: {
+        ...entry,
+        values: {
+          ...entry.values,
+          content: [
+            { id: "a", type: "hero", values: { heading: "Big news", subheading: "Read on" }, blocks: [] },
+            {
+              id: "b",
+              type: "faq",
+              values: { heading: "Questions" },
+              blocks: [
+                { id: "b1", type: "question", values: { question: "Why?", answer: richText("Because.") } },
+                { id: "b2", type: "question", values: { question: "How?" } },
+              ],
+            },
+            { id: "c", type: "gallery", values: { heading: "Photos" }, blocks: [] },
+            { id: "d", type: "mystery", values: {}, blocks: [] },
+          ],
+        },
+      },
+      headers: {},
+    });
+    expect(screen.getByRole("heading", { name: "Big news" })).toBeTruthy();
+    expect(screen.getByText("Read on")).toBeTruthy();
+    expect(screen.getByText("Why?")).toBeTruthy();
+    expect(screen.getByText("Because.")).toBeTruthy();
+    expect(screen.getByText("How?")).toBeTruthy();
+    expect(screen.getByText("No photos yet.")).toBeTruthy();
+    const kinds = [...document.querySelectorAll("[data-section]")].map((node) => node.getAttribute("data-section"));
+    expect(kinds).toEqual(["hero", "faq", "gallery"]);
+  });
+
   it("shows plain text bodies, from before the field was rich text, as paragraphs", () => {
     show({ kind: "entry", status: 200, entry: { ...entry, values: { body: "One\n\nTwo" } }, headers: {} });
     expect(screen.getByText("One")).toBeTruthy();