@sandboxsonny/ace-kit 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -13,7 +13,7 @@ type AceClientOptions = {
 type AceFieldSchema = {
   handle: string;
   label: string;
-  /** `text`, `textarea`, `select`, `number`, `checkbox`, `image`, `richtext`, `date` or `link`. */
+  /** `text`, `textarea`, `select`, `number`, `checkbox`, `image`, `richtext`, `date`, `link` or `sections`. */
   component_key: string;
   config: { required?: boolean; options?: string[] } | null;
 };
@@ -178,6 +178,164 @@ type AceImageAttributes = {
 /** What to put on an `<img>`: a web-sized `src`, `srcset` when there are copies, and the size so the page doesn't jump. */
 declare function imageAttributes(image: AceImageData, { sizes, lazy }: AceImageOptions): AceImageAttributes;
 
+/**
+ * What a link field holds in an entry's values, as visitors get it: where it goes, already worked out (a link to a
+ * page of the site is its address, such as "/pages/about"), and the words it is shown with, if the editor gave any.
+ */
+type AceLinkData = {
+  href: string;
+  label?: string;
+};
+
+/** A mark on a piece of text. A link's address is already worked out: an entry link comes as its path. */
+type AceRichTextMark = { type: "bold" } | { type: "italic" } | { type: "link"; attrs: { href: string } };
+
+/**
+ * One node of a rich text document: `paragraph`, `heading` (`attrs.level` 2 to 4), `bulletList`, `orderedList`
+ * (`attrs.start`), `listItem`, `blockquote`, `hardBreak`, `text`, or `image` (`attrs.image` is the picture).
+ */
+type AceRichTextNode = {
+  type: string;
+  attrs?: { level?: number; start?: number; assetId?: number; image?: AceImageData };
+  content?: AceRichTextNode[];
+  text?: string;
+  marks?: AceRichTextMark[];
+};
+
+/** The value of a rich text field. */
+type AceRichTextDocument = { type: "doc"; content?: AceRichTextNode[] };
+
+/** The kinds of field a section or block can hold. */
+type SectionFieldType = "text" | "textarea" | "number" | "checkbox" | "select" | "image" | "richtext" | "date" | "link";
+type FieldBase = {
+    /** What the field is called in the section's values: lowercase letters, numbers and hyphens. */
+    handle: string;
+    /** What the editor sees it called. */
+    label: string;
+    /** If true, the editor has to fill it in. */
+    required?: boolean;
+};
+/** One field of a section or block. A `select` field also lists its `options`. */
+type SectionFieldDefinition = (FieldBase & {
+    type: Exclude<SectionFieldType, "select">;
+}) | (FieldBase & {
+    type: "select";
+    options: readonly string[];
+});
+/** A kind of block a section can hold: one item of a list inside the section, such as one question of an FAQ. */
+type BlockDefinition = {
+    name: string;
+    fields?: readonly SectionFieldDefinition[];
+};
+/** What `defineSection` takes: a kind of section a site's code defines. */
+type SectionDefinition = {
+    /** What the section is called in the CMS and in code (`type`): lowercase letters, numbers and hyphens. */
+    handle: string;
+    /** What the editor sees it called. */
+    name: string;
+    fields?: readonly SectionFieldDefinition[];
+    /** The kinds of block it can hold, by handle. */
+    blocks?: Readonly<Record<string, BlockDefinition>>;
+};
+/**
+ * Describes a kind of section: its fields, and the blocks it can hold. Put one in a `*.schema.ts` file next to the
+ * component that draws it, as its default export. Ace Kit syncs them to the CMS while the dev server runs (and with
+ * `ace-kit sync`), and the component's props can be typed from it with `SectionOf`.
+ *
+ *     // Faq.schema.ts
+ *     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 }] } },
+ *     });
+ *
+ * It returns the definition unchanged: its job is to check it as you write it, and to keep the exact handles and
+ * types that `SectionOf` reads.
+ */
+declare function defineSection<const Definition extends SectionDefinition>(definition: Definition): Definition;
+type ValueOfField<Field> = Field extends {
+    type: "text" | "textarea" | "date";
+} ? string : Field extends {
+    type: "number";
+} ? number : Field extends {
+    type: "checkbox";
+} ? boolean : Field extends {
+    type: "select";
+    options: readonly (infer Option)[];
+} ? Option : Field extends {
+    type: "image";
+} ? AceImageData : Field extends {
+    type: "richtext";
+} ? AceRichTextDocument : Field extends {
+    type: "link";
+} ? AceLinkData : unknown;
+type FieldsOf<Fields> = Fields extends readonly (infer Field extends SectionFieldDefinition)[] ? Field : never;
+/** The values of a list of fields: a required field is always there, any other may be missing. */
+type ValuesOfFields<Fields> = {
+    [Field in FieldsOf<Fields> as Field extends {
+        required: true;
+    } ? Field["handle"] : never]: ValueOfField<Field>;
+} & {
+    [Field in FieldsOf<Fields> as Field extends {
+        required: true;
+    } ? never : Field["handle"]]?: ValueOfField<Field>;
+};
+type BlocksOf<Definition> = Definition extends {
+    blocks: infer Blocks extends Readonly<Record<string, BlockDefinition>>;
+} ? {
+    [Handle in keyof Blocks & string]: {
+        id: string;
+        type: Handle;
+        values: ValuesOfFields<Blocks[Handle]["fields"]>;
+    };
+}[keyof Blocks & string][] : never[];
+/**
+ * A section of this kind, as a website gets it from the CMS, worked out from its definition: type the props of the
+ * component that draws it with this.
+ *
+ *     import type { SectionOf } from "@sandboxsonny/ace-kit";
+ *     import type faq from "./Faq.schema";
+ *     type Props = { section: SectionOf<typeof faq> };
+ */
+type SectionOf<Definition extends SectionDefinition> = {
+    id: string;
+    type: Definition["handle"];
+    values: ValuesOfFields<Definition["fields"]>;
+    blocks: BlocksOf<Definition>;
+};
+
+/**
+ * Checks a section definition and returns what is wrong with it, written for the person who wrote it (an empty list
+ * means it is fine). The CMS checks everything again; this is so the mistake is reported against the file, at once,
+ * before anything is sent.
+ */
+declare function checkSectionDefinition(definition: unknown, where?: string): string[];
+type ApiField = {
+    handle: string;
+    label: string;
+    component_key: string;
+    config: {
+        required?: boolean;
+        options?: string[];
+    };
+};
+/** The body of `PUT /sites/{id}/section-types`: every section type the site's code defines. */
+type SectionTypesPayload = {
+    sections: {
+        handle: string;
+        name: string;
+        fields: ApiField[];
+        blocks: {
+            handle: string;
+            name: string;
+            fields: ApiField[];
+        }[];
+    }[];
+};
+/** Turns section definitions (already checked) into what the CMS takes. */
+declare function sectionTypesPayload(definitions: readonly SectionDefinition[]): SectionTypesPayload;
+
 type AceDateFormat = Intl.DateTimeFormatOptions & {
     /** A language such as "en-GB". The default is the one the server or browser runs in. */
     locale?: string;
@@ -188,15 +346,6 @@ type AceDateFormat = Intl.DateTimeFormatOptions & {
  */
 declare function formatAceDate(date: string, format?: AceDateFormat): string | null;
 
-/**
- * What a link field holds in an entry's values, as visitors get it: where it goes, already worked out (a link to a
- * page of the site is its address, such as "/pages/about"), and the words it is shown with, if the editor gave any.
- */
-type AceLinkData = {
-  href: string;
-  label?: string;
-};
-
 /**
  * Where a link in rich text goes, or null if it can't be trusted. The CMS only allows paths, web addresses,
  * mailto: and tel:; this checks again so the page stays safe even if something else ever gets into the text.
@@ -307,24 +456,6 @@ declare function renderTextArea(text: string | undefined, { multiline }?: {
     multiline?: boolean;
 }): string;
 
-/** A mark on a piece of text. A link's address is already worked out: an entry link comes as its path. */
-type AceRichTextMark = { type: "bold" } | { type: "italic" } | { type: "link"; attrs: { href: string } };
-
-/**
- * One node of a rich text document: `paragraph`, `heading` (`attrs.level` 2 to 4), `bulletList`, `orderedList`
- * (`attrs.start`), `listItem`, `blockquote`, `hardBreak`, `text`, or `image` (`attrs.image` is the picture).
- */
-type AceRichTextNode = {
-  type: string;
-  attrs?: { level?: number; start?: number; assetId?: number; image?: AceImageData };
-  content?: AceRichTextNode[];
-  text?: string;
-  marks?: AceRichTextMark[];
-};
-
-/** The value of a rich text field. */
-type AceRichTextDocument = { type: "doc"; content?: AceRichTextNode[] };
-
 /** How wide an image in the text is shown, so the browser picks a suitable copy from srcset. */
 declare const richTextImageSizes = "(min-width: 42rem) 42rem, 100vw";
 /** The heading level to draw: 2 to 4, whatever the document says. */
@@ -337,4 +468,24 @@ declare const listStart: (node: AceRichTextNode) => number | undefined;
  */
 declare function renderRichText(document: AceRichTextDocument): string;
 
-export { type AceAddress, type AceClient, type AceClientOptions, type AceContentTypeHandle, type AceContentTypeSchema, type AceContentTypes, type AceDateFormat, type AceEntry, type AceFieldSchema, type AceImageAttributes, type AceImageData, type AceImageOptions, type AceLinkAttributes, type AceLinkData, type AceMenu, type AceMenuItem, type AceNavigationLink, type AcePage, AcePreviewExpiredError, type AceRichTextDocument, type AceRichTextMark, type AceRichTextNode, AceUnavailableError, type AceValuesOf, addFramingPolicy, addressFromPath, createAceClient, formatAceDate, framingPolicy, headingLevel, homeAddress, imageAttributes, isCurrentPage, isHomeAddress, isInternalPath, isRefreshRequest, linkAddress, linkAttributes, linksFromMenu, listStart, listenForPreviewRefresh, loadMenuLinks, loadPage, originOf, pageNotices, pathOfAddress, previewHeaders, previewParameter, previewTokenFrom, refreshMessageType, refreshPageContent, renderRichText, renderTextArea, richTextImageSizes, swapPageContent, visitablePath };
+/** One block of a section, as a website gets it from the CMS, without knowing which kind it is. */
+type AceSectionBlock = {
+  id: string;
+  type: string;
+  values: Record<string, unknown>;
+};
+
+/**
+ * One section of an entry's sections field, as a website gets it from the CMS, without knowing which kind it is.
+ * A component that draws one kind of section types its prop with `SectionOf<typeof schema>` instead.
+ */
+type AceSection = {
+  /** Steady for as long as the section exists, so a list can be keyed by it. */
+  id: string;
+  /** Which kind of section: the `handle` of its definition. */
+  type: string;
+  values: Record<string, unknown>;
+  blocks: AceSectionBlock[];
+};
+
+export { type AceAddress, type AceClient, type AceClientOptions, type AceContentTypeHandle, type AceContentTypeSchema, type AceContentTypes, type AceDateFormat, type AceEntry, type AceFieldSchema, type AceImageAttributes, type AceImageData, type AceImageOptions, type AceLinkAttributes, type AceLinkData, type AceMenu, type AceMenuItem, type AceNavigationLink, type AcePage, AcePreviewExpiredError, type AceRichTextDocument, type AceRichTextMark, type AceRichTextNode, type AceSection, type AceSectionBlock, AceUnavailableError, type AceValuesOf, type BlockDefinition, type SectionDefinition, type SectionFieldDefinition, type SectionFieldType, type SectionOf, type SectionTypesPayload, type ValuesOfFields, addFramingPolicy, addressFromPath, checkSectionDefinition, createAceClient, defineSection, formatAceDate, framingPolicy, headingLevel, homeAddress, imageAttributes, isCurrentPage, isHomeAddress, isInternalPath, isRefreshRequest, linkAddress, linkAttributes, linksFromMenu, listStart, listenForPreviewRefresh, loadMenuLinks, loadPage, originOf, pageNotices, pathOfAddress, previewHeaders, previewParameter, previewTokenFrom, refreshMessageType, refreshPageContent, renderRichText, renderTextArea, richTextImageSizes, sectionTypesPayload, swapPageContent, visitablePath };

package/dist/index.js

@@ -5,6 +5,118 @@ export { AcePreviewExpiredError, AceUnavailableError, createAceClient, isCurrent
 export { addressFromPath, homeAddress, isHomeAddress, pathOfAddress, visitablePath } from './chunk-M5WR5TCR.js';
 export { addFramingPolicy, framingPolicy, isRefreshRequest, originOf, previewHeaders, previewParameter, previewTokenFrom, refreshMessageType, swapPageContent } from './chunk-YLO6IAXF.js';
 
+// src/sections/define-section.ts
+function defineSection(definition) {
+  return definition;
+}
+
+// src/sections/payload.ts
+var handlePattern = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+var maximumHandleLength = 64;
+var maximumNameLength = 200;
+var fieldTypes = [
+  "text",
+  "textarea",
+  "number",
+  "checkbox",
+  "select",
+  "image",
+  "richtext",
+  "date",
+  "link"
+];
+var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isHandle = (value) => typeof value === "string" && value.length <= maximumHandleLength && handlePattern.test(value);
+var handleRule = 'lowercase letters, numbers and hyphens (such as "call-to-action")';
+function checkFields(fields, where, problems) {
+  if (fields === void 0) return;
+  if (!Array.isArray(fields)) {
+    problems.push(`${where}: fields must be a list.`);
+    return;
+  }
+  const seen = /* @__PURE__ */ new Set();
+  fields.forEach((field, index) => {
+    if (!isObject(field)) {
+      problems.push(`${where}: field ${index + 1} must be an object with a handle, a label and a type.`);
+      return;
+    }
+    const name = isHandle(field.handle) ? `field "${field.handle}"` : `field ${index + 1}`;
+    if (!isHandle(field.handle)) problems.push(`${where}: ${name} needs a handle of ${handleRule}.`);
+    else if (seen.has(field.handle)) problems.push(`${where}: ${name} is defined twice.`);
+    else seen.add(field.handle);
+    if (typeof field.label !== "string" || field.label.trim() === "" || field.label.length > maximumNameLength) {
+      problems.push(`${where}: ${name} needs a label.`);
+    }
+    if (typeof field.type !== "string" || !fieldTypes.includes(field.type)) {
+      const given = typeof field.type === "string" ? ` "${field.type}"` : "";
+      problems.push(`${where}: ${name} has a type${given} that isn't one of ${fieldTypes.join(", ")}.`);
+    } else if (field.type === "select") {
+      const { options } = field;
+      if (!Array.isArray(options) || options.length === 0 || options.some((option) => typeof option !== "string" || option === "")) {
+        problems.push(`${where}: ${name} is a select, so it needs options: a list of the choices, as text.`);
+      }
+    }
+    if (field.required !== void 0 && typeof field.required !== "boolean") {
+      problems.push(`${where}: ${name} has a required that isn't true or false.`);
+    }
+  });
+}
+function checkSectionDefinition(definition, where = "this section") {
+  const problems = [];
+  if (!isObject(definition)) {
+    return [`${where}: the default export must be the result of defineSection({ ... }).`];
+  }
+  if (!isHandle(definition.handle)) {
+    problems.push(`${where}: needs a handle of ${handleRule}.`);
+  }
+  if (typeof definition.name !== "string" || definition.name.trim() === "" || definition.name.length > maximumNameLength) {
+    problems.push(`${where}: needs a name.`);
+  }
+  checkFields(definition.fields, where, problems);
+  if (definition.blocks !== void 0) {
+    if (!isObject(definition.blocks)) {
+      problems.push(`${where}: blocks must be an object of the kinds of block, by handle.`);
+    } else {
+      for (const [handle, block] of Object.entries(definition.blocks)) {
+        const blockWhere = `${where}, block "${handle}"`;
+        if (!isHandle(handle)) problems.push(`${blockWhere}: the handle must be ${handleRule}.`);
+        if (!isObject(block)) {
+          problems.push(`${blockWhere}: must be an object with a name and fields.`);
+          continue;
+        }
+        if (typeof block.name !== "string" || block.name.trim() === "") problems.push(`${blockWhere}: needs a name.`);
+        checkFields(block.fields, blockWhere, problems);
+      }
+    }
+  }
+  return problems;
+}
+function apiFields(fields) {
+  return (fields ?? []).map((field) => ({
+    handle: field.handle,
+    label: field.label,
+    component_key: field.type,
+    config: {
+      ...field.required ? { required: true } : {},
+      ...field.type === "select" ? { options: [...field.options] } : {}
+    }
+  }));
+}
+function sectionTypesPayload(definitions) {
+  return {
+    sections: definitions.map((definition) => ({
+      handle: definition.handle,
+      name: definition.name,
+      fields: apiFields(definition.fields),
+      blocks: Object.entries(definition.blocks ?? {}).map(([handle, block]) => ({
+        handle,
+        name: block.name,
+        fields: apiFields(block.fields)
+      }))
+    }))
+  };
+}
+
 // src/helpers/dates.ts
 var defaultFormat = { dateStyle: "long" };
 function formatAceDate(date, format = {}) {
@@ -21,4 +133,4 @@ function formatAceDate(date, format = {}) {
   }).format(moment);
 }
 
-export { formatAceDate };
+export { checkSectionDefinition, defineSection, formatAceDate, sectionTypesPayload };

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

@@ -75,7 +75,7 @@ type AceClientOptions = {
 type AceFieldSchema = {
   handle: string;
   label: string;
-  /** `text`, `textarea`, `select`, `number`, `checkbox`, `image`, `richtext`, `date` or `link`. */
+  /** `text`, `textarea`, `select`, `number`, `checkbox`, `image`, `richtext`, `date`, `link` or `sections`. */
   component_key: string;
   config: { required?: boolean; options?: string[] } | null;
 };

package/dist/react-router.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ImgHTMLAttributes } from 'react';
+import { ImgHTMLAttributes, ComponentType } from 'react';
 
 /** An image as the CMS Ace public API returns it. Use `src` and `srcset` in an `<img>`. */
 type AceImageData = {
@@ -122,6 +122,51 @@ declare function AceRichText({ document }: {
     document: AceRichTextDocument;
 }): react.JSX.Element;
 
+/** One block of a section, as a website gets it from the CMS, without knowing which kind it is. */
+type AceSectionBlock = {
+  id: string;
+  type: string;
+  values: Record<string, unknown>;
+};
+
+/**
+ * One section of an entry's sections field, as a website gets it from the CMS, without knowing which kind it is.
+ * A component that draws one kind of section types its prop with `SectionOf<typeof schema>` instead.
+ */
+type AceSection = {
+  /** Steady for as long as the section exists, so a list can be keyed by it. */
+  id: string;
+  /** Which kind of section: the `handle` of its definition. */
+  type: string;
+  values: Record<string, unknown>;
+  blocks: AceSectionBlock[];
+};
+
+type AceSectionsProps = {
+    /** An entry's sections field, as the CMS gives it: a list of sections, or nothing. */
+    sections: readonly AceSection[] | null | undefined;
+    /**
+     * The component that draws each kind of section, by the section's `type` (the handle in its schema). Each one is
+     * given the section as its `section` prop. A kind with no component is left out.
+     */
+    components: Readonly<Record<string, ComponentType<{
+        section: never;
+    }>>>;
+    /** Drawn for a section whose kind has no component, instead of leaving it out. */
+    fallback?: ComponentType<{
+        section: AceSection;
+    }>;
+};
+/**
+ * Draws an entry's sections field: each section by the component for its kind, in the order the editor put them.
+ *
+ *     <AceSections sections={entry.values.content} components={{ hero: Hero, faq: Faq }} />
+ *
+ * `Hero` is typed from its own schema (`SectionOf<typeof heroSchema>`), and that is kept: the map only has to
+ * say which component goes with which `type`.
+ */
+declare function AceSections({ sections, components, fallback: Fallback }: AceSectionsProps): react.JSX.Element | null;
+
 type MetaDescriptor = {
     title: string;
 } | {
@@ -171,4 +216,4 @@ type AceRootData = {
   };
 };
 
-export { AceImage, AceLink, AceNotice, AceRichText, type AceRootData, AceTextArea, createMeta, meta, useAceMenu, useAcePreview };
+export { AceImage, AceLink, AceNotice, AceRichText, type AceRootData, AceSections, AceTextArea, createMeta, meta, useAceMenu, useAcePreview };

package/dist/react-router.js

@@ -1,6 +1,6 @@
 import { pageNotices } from './chunk-XPZY5R5A.js';
-import { AceLink, AceRichText, usePreviewRefresh } from './chunk-2MXND4HG.js';
-export { AceImage, AceTextArea } from './chunk-2MXND4HG.js';
+import { AceLink, AceRichText, usePreviewRefresh } from './chunk-XS6Z7BMM.js';
+export { AceImage, AceSections, AceTextArea } from './chunk-XS6Z7BMM.js';
 import { isInternalPath } from './chunk-FVR55GIU.js';
 import './chunk-YN7LJWGI.js';
 import './chunk-M5WR5TCR.js';

package/dist/react.d.ts

@@ -85,6 +85,51 @@ type AceLinkProps = {
 /** A link field, drawn as a link. Nothing is drawn if the address can't be trusted. */
 declare function AceLink({ link, children, className, as: Link }: AceLinkProps): react.JSX.Element | null;
 
+/** One block of a section, as a website gets it from the CMS, without knowing which kind it is. */
+type AceSectionBlock = {
+  id: string;
+  type: string;
+  values: Record<string, unknown>;
+};
+
+/**
+ * One section of an entry's sections field, as a website gets it from the CMS, without knowing which kind it is.
+ * A component that draws one kind of section types its prop with `SectionOf<typeof schema>` instead.
+ */
+type AceSection = {
+  /** Steady for as long as the section exists, so a list can be keyed by it. */
+  id: string;
+  /** Which kind of section: the `handle` of its definition. */
+  type: string;
+  values: Record<string, unknown>;
+  blocks: AceSectionBlock[];
+};
+
+type AceSectionsProps = {
+    /** An entry's sections field, as the CMS gives it: a list of sections, or nothing. */
+    sections: readonly AceSection[] | null | undefined;
+    /**
+     * The component that draws each kind of section, by the section's `type` (the handle in its schema). Each one is
+     * given the section as its `section` prop. A kind with no component is left out.
+     */
+    components: Readonly<Record<string, ComponentType<{
+        section: never;
+    }>>>;
+    /** Drawn for a section whose kind has no component, instead of leaving it out. */
+    fallback?: ComponentType<{
+        section: AceSection;
+    }>;
+};
+/**
+ * Draws an entry's sections field: each section by the component for its kind, in the order the editor put them.
+ *
+ *     <AceSections sections={entry.values.content} components={{ hero: Hero, faq: Faq }} />
+ *
+ * `Hero` is typed from its own schema (`SectionOf<typeof heroSchema>`), and that is kept: the map only has to
+ * say which component goes with which `type`.
+ */
+declare function AceSections({ sections, components, fallback: Fallback }: AceSectionsProps): react.JSX.Element | null;
+
 type AceTextAreaProps = {
     /** The text area field's value. Missing or blank draws nothing. */
     value: string | undefined;
@@ -107,4 +152,4 @@ declare function AceTextArea({ value, multiline }: AceTextAreaProps): react.JSX.
  */
 declare function usePreviewRefresh(adminOrigin: string | null | undefined, refresh?: () => Promise<void>): void;
 
-export { AceImage, AceLink, AceRichText, type AceRichTextLink, AceTextArea, usePreviewRefresh };
+export { AceImage, AceLink, AceRichText, type AceRichTextLink, AceSections, AceTextArea, usePreviewRefresh };

package/dist/react.js

@@ -1,4 +1,4 @@
-export { AceImage, AceLink, AceRichText, AceTextArea, usePreviewRefresh } from './chunk-2MXND4HG.js';
+export { AceImage, AceLink, AceRichText, AceSections, AceTextArea, usePreviewRefresh } from './chunk-XS6Z7BMM.js';
 import './chunk-FVR55GIU.js';
 import './chunk-YN7LJWGI.js';
 import './chunk-M5WR5TCR.js';

package/dist/vite.d.ts

@@ -7,7 +7,8 @@ import { Plugin } from 'vite';
  * development. This reads the `ACE_` variables from `.env` files into `process.env`, never replacing one that is
  * already set, and never exposing them to the browser. In production the host's environment is used as it is.
  * It also makes sure the site uses a single copy of React and React Router, in the app and in its tests: add it to
- * `vitest.config.ts` too if the site tests components that use the kit.
+ * `vitest.config.ts` too if the site tests components that use the kit. And while the dev server runs it syncs the
+ * site's section types (its `*.schema.ts` files) to the CMS whenever they change; see `ace-kit sync`.
  *
  *     // vite.config.ts
  *     export default defineConfig({ plugins: [ace(), reactRouter()] });

package/dist/vite.js

@@ -1,8 +1,7 @@
+import { startDevSite, startSectionSync } from './chunk-O3NAJNUN.js';
 import { resolve } from 'path';
 import { loadEnv } from 'vite';
 
-// src/vite/plugin.ts
-
 // src/helpers/package-name.ts
 var packageName = "@sandboxsonny/ace-kit";
 
@@ -10,6 +9,26 @@ var packageName = "@sandboxsonny/ace-kit";
 function ace() {
   return {
     name: "ace-kit",
+    async configureServer(server) {
+      const logger = server.config.logger;
+      const devSite = await startDevSite({
+        root: server.config.root,
+        mode: server.config.mode,
+        log: {
+          info: (text) => logger.info(`[ace-kit] ${text}`, { timestamp: true }),
+          warn: (text) => logger.warn(`[ace-kit] ${text}`, { timestamp: true })
+        }
+      });
+      if (devSite) {
+        const tellCms = () => {
+          const address = server.httpServer?.address();
+          if (address && typeof address === "object") void devSite.setPreviewUrl(`http://localhost:${address.port}`);
+        };
+        if (server.httpServer && !server.httpServer.listening) server.httpServer.once("listening", tellCms);
+        else tellCms();
+      }
+      startSectionSync(server);
+    },
     config(config, { mode }) {
       const root = config.root ? resolve(config.root) : process.cwd();
       const fromFiles = loadEnv(mode, root, "ACE_");

package/docs/api-reference.md

@@ -36,6 +36,17 @@ Everything below is exported from `@sandboxsonny/ace-kit` unless a path is given
 | `linkAttributes(link)`         | What to draw for a link field: `{ href, label }` (`label` is `null` when the editor gave no words), or `null` if the address can't be trusted.                                                                                                                                    |
 | `formatAceDate(date, format?)` | A date field's day (`"2026-10-13"`) as words, in the language asked for (`{ locale: "en-GB" }`), or `null` if it isn't a real day. Takes the options of `Intl.DateTimeFormat`; the default is `dateStyle: "long"`. A day has no time of day, so it never shifts with a time zone. |
 
+## Sections
+
+|                                                     |                                                                                                                             |
+| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `defineSection({ handle, name, fields?, blocks? })` | Describes a kind of section in a `*.schema.ts` file (see [Sections](./sections.md)). Returns it unchanged, for `SectionOf`. |
+| `SectionOf<typeof schema>`                          | The type of a section of that kind, as a website gets it: use it for the props of the component that draws it.              |
+| `checkSectionDefinition(definition, where?)`        | What is wrong with a definition, as a list of messages (empty if fine).                                                     |
+| `sectionTypesPayload(definitions)`                  | The body `PUT /sites/{id}/section-types` takes.                                                                             |
+
+Types: `AceSection`, `AceSectionBlock`, `SectionDefinition`, `SectionFieldDefinition`, `SectionFieldType`, `BlockDefinition`, `ValuesOfFields`. Components: `AceSections.astro`, and `AceSections` from `/react` and `/react-router`.
+
 ## Menus
 
 |                                            |                                                                            |
@@ -83,7 +94,7 @@ Everything below is exported from `@sandboxsonny/ace-kit` unless a path is given
 | `applyPage(response, page)`                                                               | Puts a page's status and headers on a response.                                                                                                           |
 | `ace`                                                                                     | The client these use.                                                                                                                                     |
 
-Components, by file: `AceImage.astro`, `AceLink.astro`, `AceRichText.astro`, `AceTextArea.astro`, `AceMenu.astro`, `AceNotice.astro`, `AcePreviewRefresh.astro`.
+Components, by file: `AceImage.astro`, `AceLink.astro`, `AceSections.astro`, `AceRichText.astro`, `AceTextArea.astro`, `AceMenu.astro`, `AceNotice.astro`, `AcePreviewRefresh.astro`.
 
 ## React Router 7
 
@@ -109,4 +120,4 @@ Components, by file: `AceImage.astro`, `AceLink.astro`, `AceRichText.astro`, `Ac
 
 ## React (`@sandboxsonny/ace-kit/react`)
 
-`AceImage`, `AceLink` (with `as`), `AceRichText` (with `link`), `usePreviewRefresh(adminOrigin, refresh?)`.
+`AceImage`, `AceLink` (with `as`), `AceSections` (with `fallback`), `AceRichText` (with `link`), `usePreviewRefresh(adminOrigin, refresh?)`.

package/docs/command-line.md

@@ -7,6 +7,7 @@ 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 generate   # write TypeScript types (see Typed content)
+npx ace-kit sync       # send your section types to the CMS (see Sections)
 ```
 
 Every command takes `--api-url`, or reads `ACE_API_URL` from the environment or a `.env` file in the folder you run it in. Failing both, it uses the address you last signed in to (kept in a small file beside your logins), so after `ace-kit login --api-url …` you can simply run `ace-kit whoami` from anywhere.

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.