@sandboxsonny/ace-kit 0.6.0 → 0.7.0

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-T7DKI2U3.js';
 import './chunk-N5DIMG3X.js';
 import { resolve } from 'path';
 import { loadEnv } from 'vite';

package/docs/command-line.md

@@ -7,6 +7,7 @@ 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)
 ```
@@ -23,24 +24,48 @@ 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`).                             |
+| 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". |
+| `--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.
 
 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`, `--api-url` and `--dir` like `sync`.
+
 ## Signing in
 
 ```sh

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
@@ -47,9 +47,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 +121,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandboxsonny/ace-kit",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "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();

package/templates/react-router/app/routes.ts

@@ -1,4 +1,8 @@
-import { type RouteConfig, route } from "@react-router/dev/routes";
+import { type RouteConfig, index, route } from "@react-router/dev/routes";
 
-// One route draws every page: "/" is the home entry and "/{content type}/{entry}" any other.
-export default [route("*", "routes/page.tsx")] satisfies RouteConfig;
+// One route draws every page: "/" is the home entry and "/{content type}/{entry}" any other. The home page needs its own
+// `index` line: a "*" route doesn't match "/", so with only that line the home page would come out empty.
+export default [
+  index("routes/page.tsx", { id: "home" }),
+  route("*", "routes/page.tsx", { id: "page" }),
+] satisfies RouteConfig;