@sandboxsonny/ace-kit 0.2.0 → 0.4.0

package/docs/dev-sites.md

@@ -0,0 +1,41 @@
+# Dev sites
+
+When your site's dev server works against a hosted CMS, it doesn't touch the live site. It works on a **dev site**: a private copy of the site that only you can see. You can change section types, try new fields and edit test content freely; the live site, and everyone editing it, never notice.
+
+## How it works
+
+On start, the dev server (the Astro integration, or the `ace()` Vite plugin on React Router):
+
+1. checks you are signed in (`npx ace-kit login`), and finds the site `ACE_SITE_DOMAIN` names;
+2. asks the CMS for your dev site of it, which the CMS makes the first time as a copy of the live site: its content types, section types, menus and the **text** of its entries, with every link between entries pointing at the copy. Images are not copied yet, so image fields start empty;
+3. points the site at it: `ACE_SITE_DOMAIN` becomes the dev site's domain for as long as the dev server runs (your `.env` is not changed), so the site reads its content from the dev site, and section sync goes there;
+4. tells the CMS where the dev server is running, so the live preview in the admin app shows your dev server.
+
+```
+[ace-kit] Made you a dev site, "Acme (dev)", as a copy of the live site (dev-3.acme.com). This dev server reads and syncs to it; the live site is not touched.
+```
+
+In the admin app the dev site appears in your Sites list with a **Dev** badge. Its Settings page has **Reset dev site**, which throws away what is in it and copies the live site again, for when you want to go back after trying something.
+
+## Who can have one
+
+Partner accounts and super admins, for sites they own. Ask for a partner account if the dev server says your account can't have a dev site.
+
+## Going to the live site
+
+A dev site is never merged into the live site. When your change is ready, deploy your site, then run `npx ace-kit sync` against the live site (`ACE_SITE_DOMAIN` set to the live domain, as in your `.env`). Deploy first: the live CMS then has the section types the deployed code expects.
+
+## Settings
+
+| Setting             | Meaning                                                                                                                                   |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `ACE_DEV_SITE`      | `false` stops the dev server using a dev site. `true` uses one even against a CMS on your own machine. Default: on for a hosted CMS only. |
+| `ACE_SYNC_SECTIONS` | See [sections](./sections.md).                                                                                                            |
+
+## 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.
+
+## Housekeeping
+
+A dev site nobody has used for 30 days (no one working in it, no website reading from it) is removed, with everything in it. It is also removed with the live site it was copied from. Dev sites don't count toward a partner's site limit.

package/docs/getting-started.md

@@ -22,7 +22,7 @@ npm install @sandboxsonny/ace-kit
 | `@sandboxsonny/ace-kit/react-router`                     | React Router 7, browser-safe: `AceRichText` (router links), `AceImage`, `AceNotice`, `createMeta`, `useAceMenu`, `useAcePreview`                                  |
 | `@sandboxsonny/ace-kit/react-router/server`              | React Router 7, server only: `createPageLoader`, `createRootLoader`, `handleRequest` (the server entry), `getEntry`, `getEntries`, `getMenuLinks`, `getAceClient` |
 | `@sandboxsonny/ace-kit/vite`                             | A Vite plugin: reads `ACE_` settings from `.env` in development and keeps one copy of React                                                                       |
-| `ace-kit` (command)                                      | `ace-kit generate`, which writes TypeScript types for your content                                                                                                |
+| `ace-kit` (command)                                      | `ace-kit generate` (TypeScript types for your content), `login`, `logout`, `whoami` (see [the command line](./command-line.md))                                   |
 
 ## The client
 

package/docs/sections.md

@@ -0,0 +1,104 @@
+# Sections
+
+A **section** is a part of a page that an editor adds, fills in and reorders in the CMS: a hero, an FAQ, a gallery. You define what each kind can hold in a small file next to the component that draws it. Ace Kit sends those definitions to the CMS while your dev server runs, and types the component's props from them.
+
+```
+src/components/sections/
+  Faq.astro
+  Faq.schema.ts      <- what an FAQ can hold
+  Hero.astro
+  Hero.schema.ts
+```
+
+## Describing a section
+
+```ts
+// Faq.schema.ts
+import { defineSection } from "@sandboxsonny/ace-kit";
+
+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" },
+      ],
+    },
+  },
+});
+```
+
+- **`handle`** is the section's kind in your code (`section.type`) and in the CMS: lowercase letters, numbers and hyphens. **`name`** is what the editor sees.
+- **`fields`** are the section's own values. Each has a `handle`, a `label` and a `type`: `text`, `textarea`, `number`, `checkbox`, `select` (also give `options: [...]`), `image`, `richtext`, `date` or `link`. Add `required: true` to make the editor fill it in.
+- **`blocks`** are the repeatable items inside a section, by handle, each with a `name` and its own `fields`. An FAQ's questions are blocks: the editor adds as many as they like and reorders them. A section without `blocks` is just fields.
+- The file's **default export** must be the result of `defineSection`. Everything else in the file is ignored.
+
+A section can't hold other sections; use blocks for a list inside one.
+
+## Drawing sections
+
+The component's props follow its schema, with nothing written twice:
+
+```astro
+---
+// Faq.astro
+import type { SectionOf } from "@sandboxsonny/ace-kit";
+import type faq from "./Faq.schema";
+
+type Props = { section: SectionOf<typeof faq> };
+const { section } = Astro.props;
+---
+
+<h2>{section.values.heading}</h2>
+{section.blocks.map((block) => (
+  <details>
+    <summary>{block.values.question}</summary>
+  </details>
+))}
+```
+
+`section.values.heading` is a `string | undefined` (it isn't required); `block.values.question` is a `string` (it is). An `image` is `AceImageData`, a `link` is `AceLinkData`, a `select` is the union of its options, and a block's `values` depend on its `type` when a section has more than one kind of block.
+
+Then draw a whole sections field with the component for each kind:
+
+```astro
+---
+import AceSections from "@sandboxsonny/ace-kit/astro/AceSections.astro";
+import Faq from "~/components/sections/Faq.astro";
+import Hero from "~/components/sections/Hero.astro";
+---
+
+<AceSections sections={entry.values.content} components={{ hero: Hero, faq: Faq }} />
+```
+
+On React and React Router the same component comes from `@sandboxsonny/ace-kit/react` and `@sandboxsonny/ace-kit/react-router`. A section whose kind has no component is left out (and noted in the dev server's log), or drawn by a `fallback` component if you give one (React). Sections are drawn in the order the editor put them.
+
+With `ace-kit generate`, a sections field is typed `AceSection[]`: a list of sections of any kind, which is what `AceSections` takes.
+
+## Syncing to the CMS
+
+While the dev server runs, Ace Kit watches for `*.schema.ts` files (in `src`) and syncs them to the CMS whenever one is added, changed or removed, and once at start. It prints one line each time:
+
+```
+10:41:07 [ace-kit] Synced 3 section types (faq, gallery, hero) to localhost (http://localhost:8080).
+```
+
+You don't run anything. You do need to be signed in once: `npx ace-kit login` (see [the command line](./command-line.md)). The sync goes to the site named by `ACE_SITE_DOMAIN` at `ACE_API_URL`, the same settings the site reads its content with, and only an owner of that site (or a super admin) can sync to it.
+
+**Your dev site, not the live one.** Against a _hosted_ CMS the dev server works on a [dev site](./dev-sites.md): your own private copy of the site, made for you the first time, so a half-written field never reaches editors or visitors of the live site. The sync goes there. Against a CMS on your own machine there is no need for one, and the sync goes to the site itself.
+
+**If there is no dev site to sync to** (you aren't signed in, or your account can't have one), automatic sync stays off against a hosted CMS, and the dev server says why. To allow it against the live site anyway, set `ACE_SYNC_SECTIONS=remote`; to turn it off, `ACE_SYNC_SECTIONS=false`. Running `npx ace-kit sync` yourself always syncs to the site `ACE_SITE_DOMAIN` names, which is how a change reaches the live site: deploy first, then run it.
+
+**Nothing is deleted, and a partial picture is never sent.** The CMS treats what is sent as the whole list. A section, block or field you take out of your code is kept there, hidden, so the content already written in it isn't lost (put it back and it returns). A field changing kind (say `text` to `number`) is refused, because its saved values are of the old kind: use a new handle. If any schema file can't be loaded, or none are found, **nothing is synced**; the error says which file and why.
+
+### On a build server
+
+`npx ace-kit sync` does the same once, in a command. With `ACE_TOKEN` set (see [the command line](./command-line.md)) it needs no browser. Schema files are TypeScript, which Node runs as it is from **Node 22.18** (use `.js` files on older versions).
+
+## What the CMS needs
+
+An API with sections (its migration 00019), command-line sign-in (00020) and, for dev sites, 00022.

package/docs/typed-content.md

@@ -45,6 +45,7 @@ cms.getEntry("pagez", "about"); // type error: no such content type
 | Rich text                        | `AceRichTextDocument`                                      |
 | Date                             | `string`, a day written `YYYY-MM-DD` (see `formatAceDate`) |
 | Link                             | `AceLinkData`: `{ href, label? }`                          |
+| Sections                         | `AceSection[]` (see [Sections](./sections.md))             |
 | a kind this version doesn't know | `unknown`                                                  |
 
 A field is optional unless it is marked required in the CMS. Before you generate, handles are plain `string` and values are `Record<string, unknown>`, so nothing breaks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandboxsonny/ace-kit",
-  "version": "0.2.0",
+  "version": "0.4.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",