@sandboxsonny/ace-kit 0.2.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

@@ -0,0 +1,52 @@
+# The command line
+
+`ace-kit` is also a command. It signs you in to CMS Ace from your terminal, and writes types for your content.
+
+```sh
+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.
+
+## Signing in
+
+```sh
+npx ace-kit login --api-url http://localhost:8080
+```
+
+```
+Signing in to http://localhost:8080
+
+  1. Go to   http://localhost:5173/device
+  2. Type    BCDF-GHJK
+
+Check the code on that page matches. Waiting for you to approve it (Ctrl-C to cancel)...
+```
+
+Your browser opens the CMS admin app's approval page. **Type the code from your terminal** into it (it is deliberately not in the link), check that the tool and the address it shows are yours, and choose **Approve**. The terminal then says who you are signed in as. This is the OAuth device flow, the same shape as `gh auth login`: no password is ever typed into the terminal, and nothing secret is written in a file inside your project.
+
+Only approve a login you started just now, from your own terminal. If the code on the page doesn't match the one in your terminal, or you didn't ask for a login, choose **Turn it down**.
+
+## Where the login is kept
+
+- **On a Mac:** the macOS Keychain, as an item named `ace-kit` whose account is the API address. You can see it in Keychain Access. Ace Kit uses the `security` program that comes with macOS, so nothing native is installed, and the login is handed to it on standard input, never as an argument other users of the machine could read.
+- **Anywhere else:** a file only you can read, `~/.config/ace-kit/credentials.json` (mode `0600`, in a folder of mode `0700`; `%APPDATA%\ace-kit` on Windows). Set `XDG_CONFIG_HOME` to move it.
+- Set `ACE_KIT_CREDENTIALS=file` to use the file even on a Mac.
+
+One login is kept per API address, so you can be signed in to a local CMS and a hosted one at once.
+
+## What a command-line login can do
+
+Much less than you can in the browser. It can see which sites you can reach, read their content types, and read and sync their section types (the last only on a site where you are an owner, or a super admin). It cannot manage members, passwords or other logins, read or change entries and images, or approve another command-line login. It lasts 90 days at most and ends after 30 days unused. A super admin sees it on the Sessions screen, named after your machine, and can end it from there.
+
+## Build servers
+
+A build server has nobody to approve a login in a browser. Set `ACE_TOKEN` to a token instead and Ace Kit uses it in place of a stored login. (Tokens for this are not made yet; for now sign in on the machine that needs it.)
+
+## Signing out
+
+`npx ace-kit logout` ends the login at the CMS and forgets it on this machine. If the CMS can't be reached it still forgets it here, and says so.