@sandboxsonny/ace-kit 0.0.0-stage → 0.1.1

package/dist/react-router.d.ts

@@ -0,0 +1,155 @@
+import * as react from 'react';
+import { ImgHTMLAttributes } from 'react';
+
+/** An image as the CMS Ace public API returns it. Use `src` and `srcset` in an `<img>`. */
+type AceImageData = {
+  id: number;
+  /** The untouched original. */
+  url: string;
+  /** A web-sized copy, for browsers that ignore `srcset`. */
+  src: string;
+  /** Copies at several widths; empty when the image is too small to need them. */
+  srcset: string;
+  width: number | null;
+  height: number | null;
+  alt_text: string;
+  content_type: string;
+};
+
+type AceImageOptions = {
+    /** How wide the image is shown, e.g. "(min-width: 64rem) 64rem, 100vw". The browser uses it to pick a copy from srcset. */
+    sizes: string;
+    /** Leave on for images below the first screen; turn off for the one at the top of the page. */
+    lazy?: boolean;
+};
+
+type AceImageProps = AceImageOptions & {
+    image: AceImageData;
+} & Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "srcSet" | "sizes" | "width" | "height" | "alt" | "loading">;
+/** An image from the CMS as an `<img>` with a web-sized `src`, `srcset`, its size and its alt text. */
+declare function AceImage({ image, sizes, lazy, ...rest }: AceImageProps): react.JSX.Element;
+
+type AceTextAreaProps = {
+    /** The text area field's value. Missing or blank draws nothing. */
+    value: string | undefined;
+    /** True (the default): blank lines start new paragraphs and a single new line is a line break. False: one line of text. */
+    multiline?: boolean;
+};
+/**
+ * A text area field's text. Multi-line text becomes `<p>` paragraphs (a new line inside one is a `<br>`); with
+ * `multiline={false}` it is a single line of text with no element around it, to put inside your own. React escapes
+ * the text, so it is safe as it is.
+ */
+declare function AceTextArea({ value, multiline }: AceTextAreaProps): react.JSX.Element;
+
+/** A live entry from the public API. `Values` is the shape of its content type's fields. */
+type AceEntry<Values = Record<string, unknown>> = {
+  id: number;
+  content_type_id: number;
+  /** The content type's handle, which is the first part of the entry's address. */
+  content_type_handle: string;
+  title: string;
+  handle: string;
+  description: string;
+  values: Values;
+  created_at: string;
+  updated_at: string;
+  /** Only on a preview: true when the entry has a draft and this is it. */
+  is_draft?: boolean;
+};
+
+/** What to do with a request for a page: show an entry, redirect, or explain. */
+type AcePage<Values = Record<string, unknown>> =
+  | { kind: "entry"; status: 200; entry: AceEntry<Values>; headers: Record<string, string> }
+  | { kind: "redirect"; status: 301 | 302; location: string; headers: Record<string, string> }
+  | { kind: "not-found"; status: 404; headers: Record<string, string> }
+  | { kind: "unavailable"; status: 503; headers: Record<string, string> }
+  | { kind: "preview-expired"; status: 403; headers: Record<string, string> };
+
+/**
+ * What to show for a page that isn't an entry (`page.kind` is `not-found`, `unavailable` or `preview-expired`): a heading
+ * and a message, and a link home unless the preview has expired. Unstyled; give it a `className`.
+ */
+declare function AceNotice({ page, className }: {
+    page: Exclude<AcePage, {
+        kind: "entry";
+    }>;
+    className?: string;
+}): react.JSX.Element;
+
+/** 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[] };
+
+/**
+ * A rich text field's document, drawn with React Router's `Link` for links to pages of this site. Everything else
+ * is as `AceRichText` from `@sandboxsonny/ace-kit/react`: safe by construction, bare elements to style yourself.
+ */
+declare function AceRichText({ document }: {
+    document: AceRichTextDocument;
+}): react.JSX.Element;
+
+type MetaDescriptor = {
+    title: string;
+} | {
+    name: string;
+    content: string;
+};
+/**
+ * The route's `meta`: the entry's title (followed by the site's name, if you give one), its description, and
+ * `noindex` for a preview so search engines ignore it.
+ *
+ *     export const meta = createMeta({ siteName: "Example Site" });
+ */
+declare function createMeta({ siteName }?: {
+    siteName?: string;
+}): ({ data }: {
+    data: unknown;
+}) => MetaDescriptor[];
+/** `createMeta()` without a site name. */
+declare const meta: ({ data }: {
+    data: unknown;
+}) => MetaDescriptor[];
+
+/** One link in a navigation bar, ready to draw. */
+type AceNavigationLink = {
+  label: string;
+  to: string;
+  /** Links shown under this one. */
+  children?: AceNavigationLink[];
+};
+
+/** The header menu's links (the CMS menu, or the fallback), as `[{ label, to, children? }]`. Needs `createRootLoader`. */
+declare function useAceMenu(): AceNavigationLink[];
+/**
+ * Keeps live preview fresh. Call it once, in the root component. When this page is shown inside the CMS's editor and the
+ * editor saves a draft, the page's data is loaded again and redrawn without a reload. Elsewhere it does nothing.
+ * Needs `createRootLoader`, which knows whether the page is a preview.
+ */
+declare function useAcePreview(): void;
+
+/** What the root loader (`createRootLoader`) puts in the root route's data, for `useAceMenu` and `useAcePreview`. */
+type AceRootData = {
+  ace: {
+    /** The header menu's links, or the fallback. */
+    menuLinks: AceNavigationLink[];
+    /** Where the CMS admin app runs, when this page is a preview shown inside its editor; otherwise null. */
+    previewAdminOrigin: string | null;
+  };
+};
+
+export { AceImage, AceNotice, AceRichText, type AceRootData, AceTextArea, createMeta, meta, useAceMenu, useAcePreview };

package/dist/react-router.js

@@ -0,0 +1,55 @@
+import { pageNotices } from './chunk-XPZY5R5A.js';
+import { AceRichText, usePreviewRefresh } from './chunk-KEV3YAWN.js';
+export { AceImage, AceTextArea } from './chunk-KEV3YAWN.js';
+import { isInternalPath } from './chunk-URLKW2YS.js';
+import './chunk-YN7LJWGI.js';
+import './chunk-M5WR5TCR.js';
+import './chunk-YLO6IAXF.js';
+import { Link, useRevalidator, useRouteLoaderData } from 'react-router';
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { useCallback } from 'react';
+
+function AceNotice({ page, className }) {
+  const { heading, message } = pageNotices[page.kind];
+  return /* @__PURE__ */ jsxs("div", { className, children: [
+    /* @__PURE__ */ jsx("h1", { children: heading }),
+    /* @__PURE__ */ jsx("p", { children: message }),
+    page.kind === "preview-expired" ? null : /* @__PURE__ */ jsx(Link, { to: "/", children: "Back to the home page" })
+  ] });
+}
+var RouterLink = ({ href, children }) => isInternalPath(href) ? /* @__PURE__ */ jsx(Link, { to: href, children }) : /* @__PURE__ */ jsx("a", { href, children });
+function AceRichText2({ document }) {
+  return /* @__PURE__ */ jsx(AceRichText, { document, link: RouterLink });
+}
+
+// src/react-router/meta.ts
+function createMeta({ siteName } = {}) {
+  const suffix = siteName ? ` | ${siteName}` : "";
+  return function meta2({ data }) {
+    const page = data;
+    if (!page) return siteName ? [{ title: siteName }] : [];
+    const descriptors = [];
+    if (page.kind === "entry") {
+      descriptors.push({ title: `${page.entry.title}${suffix}` });
+      if (page.entry.description) descriptors.push({ name: "description", content: page.entry.description });
+    } else if (siteName) {
+      descriptors.push({ title: siteName });
+    }
+    if (page.headers["Cache-Control"]) descriptors.push({ name: "robots", content: "noindex" });
+    return descriptors;
+  };
+}
+var meta = createMeta();
+function useAceRootData() {
+  return useRouteLoaderData("root")?.ace;
+}
+function useAceMenu() {
+  return useAceRootData()?.menuLinks ?? [];
+}
+function useAcePreview() {
+  const { revalidate } = useRevalidator();
+  const refresh = useCallback(() => revalidate(), [revalidate]);
+  usePreviewRefresh(useAceRootData()?.previewAdminOrigin, refresh);
+}
+
+export { AceNotice, AceRichText2 as AceRichText, createMeta, meta, useAceMenu, useAcePreview };

package/dist/react.d.ts

@@ -0,0 +1,88 @@
+import * as react from 'react';
+import { ImgHTMLAttributes, ComponentType, ReactNode } from 'react';
+
+/** An image as the CMS Ace public API returns it. Use `src` and `srcset` in an `<img>`. */
+type AceImageData = {
+  id: number;
+  /** The untouched original. */
+  url: string;
+  /** A web-sized copy, for browsers that ignore `srcset`. */
+  src: string;
+  /** Copies at several widths; empty when the image is too small to need them. */
+  srcset: string;
+  width: number | null;
+  height: number | null;
+  alt_text: string;
+  content_type: string;
+};
+
+type AceImageOptions = {
+    /** How wide the image is shown, e.g. "(min-width: 64rem) 64rem, 100vw". The browser uses it to pick a copy from srcset. */
+    sizes: string;
+    /** Leave on for images below the first screen; turn off for the one at the top of the page. */
+    lazy?: boolean;
+};
+
+type AceImageProps = AceImageOptions & {
+    image: AceImageData;
+} & Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "srcSet" | "sizes" | "width" | "height" | "alt" | "loading">;
+/** An image from the CMS as an `<img>` with a web-sized `src`, `srcset`, its size and its alt text. */
+declare function AceImage({ image, sizes, lazy, ...rest }: AceImageProps): react.JSX.Element;
+
+/** 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[] };
+
+/** What a link in the text is drawn with. Give one that uses your router's link to keep navigation client-side. */
+type AceRichTextLink = ComponentType<{
+    href: string;
+    children: ReactNode;
+}>;
+type AceRichTextProps = {
+    document: AceRichTextDocument;
+    /** Draws links; the default is a plain `<a>`. */
+    link?: AceRichTextLink;
+};
+/**
+ * A rich text field's document drawn as React elements. React escapes every piece of text, only the kinds of content
+ * the CMS allows are drawn, and links are checked again, so it is safe as it is. Wrap it in your own element to style it.
+ */
+declare function AceRichText({ document, link }: AceRichTextProps): react.JSX.Element;
+
+type AceTextAreaProps = {
+    /** The text area field's value. Missing or blank draws nothing. */
+    value: string | undefined;
+    /** True (the default): blank lines start new paragraphs and a single new line is a line break. False: one line of text. */
+    multiline?: boolean;
+};
+/**
+ * A text area field's text. Multi-line text becomes `<p>` paragraphs (a new line inside one is a `<br>`); with
+ * `multiline={false}` it is a single line of text with no element around it, to put inside your own. React escapes
+ * the text, so it is safe as it is.
+ */
+declare function AceTextArea({ value, multiline }: AceTextAreaProps): react.JSX.Element;
+
+/**
+ * Refreshes the page when the CMS's editor saves a draft, if the page is being shown inside its preview frame.
+ *
+ * - `adminOrigin`: where the CMS admin app runs. Pass null/undefined when the page isn't a preview and nothing happens.
+ * - `refresh`: how to get fresh content. Give your framework's own (React Router's `revalidator.revalidate`); the
+ *   default fetches the page again and swaps its content in.
+ */
+declare function usePreviewRefresh(adminOrigin: string | null | undefined, refresh?: () => Promise<void>): void;
+
+export { AceImage, AceRichText, type AceRichTextLink, AceTextArea, usePreviewRefresh };

package/dist/react.js

@@ -0,0 +1,5 @@
+export { AceImage, AceRichText, AceTextArea, usePreviewRefresh } from './chunk-KEV3YAWN.js';
+import './chunk-URLKW2YS.js';
+import './chunk-YN7LJWGI.js';
+import './chunk-M5WR5TCR.js';
+import './chunk-YLO6IAXF.js';

package/dist/vite.d.ts

@@ -0,0 +1,17 @@
+import { Plugin } from 'vite';
+
+/**
+ * A Vite plugin for sites whose server code reads Ace Kit's settings (`ACE_API_URL`, `ACE_SITE_DOMAIN`,
+ * `ACE_PREVIEW_ADMIN_ORIGIN`) from the environment, as the React Router adapter does. Vite only puts variables
+ * that start with `VITE_` into the code it runs, so without this a `.env` file would not reach the server in
+ * 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.
+ *
+ *     // vite.config.ts
+ *     export default defineConfig({ plugins: [ace(), reactRouter()] });
+ */
+declare function ace(): Plugin;
+
+export { ace as default };

package/dist/vite.js

@@ -0,0 +1,27 @@
+import { resolve } from 'path';
+import { loadEnv } from 'vite';
+
+// src/vite/plugin.ts
+
+// src/helpers/package-name.ts
+var packageName = "@sandboxsonny/ace-kit";
+
+// src/vite/plugin.ts
+function ace() {
+  return {
+    name: "ace-kit",
+    config(config, { mode }) {
+      const root = config.root ? resolve(config.root) : process.cwd();
+      const fromFiles = loadEnv(mode, root, "ACE_");
+      for (const [name, value] of Object.entries(fromFiles)) {
+        if (process.env[name] === void 0) process.env[name] = value;
+      }
+      return {
+        resolve: { dedupe: ["react", "react-dom", "react-router"] },
+        test: { server: { deps: { inline: [packageName] } } }
+      };
+    }
+  };
+}
+
+export { ace as default };

package/docs/api-reference.md

@@ -0,0 +1,105 @@
+# API reference
+
+Everything below is exported from `@sandboxsonny/ace-kit` unless a path is given.
+
+## Client
+
+|                                                                                      |                                                                                                           |
+| ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `createAceClient({ apiUrl, siteDomain, cacheSeconds?, fetchImplementation?, now? })` | A client. `fetchImplementation` and `now` are for tests.                                                  |
+| `client.getEntry(contentType, handle, { previewToken? })`                            | One live entry, or `null`. With a token, the entry it was made for with its draft applied (never cached). |
+| `client.getEntries(contentType, { limit? })`                                         | A content type's live entries, newest first.                                                              |
+| `client.getMenu(handle)`                                                             | A menu with every link worked out, or `null`.                                                             |
+| `client.getContentTypes()`                                                           | What the content types look like (used by `ace-kit generate`).                                            |
+| `AceUnavailableError`                                                                | The CMS could not be reached, or answered with something unexpected, or the site isn't set up.            |
+| `AcePreviewExpiredError`                                                             | The preview token has run out.                                                                            |
+
+## Pages and addresses
+
+|                                                                   |                                                                                                                                                   |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loadPage(client, { slug, url })`                                 | What to do for a request: `AcePage`, one of `entry`, `redirect`, `not-found`, `unavailable`, `preview-expired`, each with `status` and `headers`. |
+| `addressFromPath(slug)`                                           | `{ contentTypeHandle, entryHandle }` for `/{content type}/{entry}`, the home entry for `/`, or `null`.                                            |
+| `homeAddress`, `isHomeAddress(address)`, `pathOfAddress(address)` | The `home` entry of `pages`, and helpers.                                                                                                         |
+| `visitablePath(path)`                                             | `/pages/home` becomes `/` (it redirects there); anything else is unchanged.                                                                       |
+
+## Images
+
+|                                            |                                                                                                                            |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `imageAttributes(image, { sizes, lazy? })` | The attributes for an `<img>`: `src`, `srcSet`, `sizes`, `width`, `height`, `alt`, `loading`, `decoding`, `fetchPriority`. |
+
+## Menus
+
+|                                            |                                                                            |
+| ------------------------------------------ | -------------------------------------------------------------------------- |
+| `linksFromMenu(menu)`                      | `[{ label, to, children? }]` with the home link at `/`.                    |
+| `isCurrentPage(link, pathname)`            | Whether a link is the page being shown.                                    |
+| `loadMenuLinks(client, handle, fallback?)` | A menu's links, or the fallback if the menu is missing or the CMS is down. |
+
+## Rich text
+
+|                                        |                                                                                |
+| -------------------------------------- | ------------------------------------------------------------------------------ |
+| `renderRichText(document)`             | The document as safe HTML.                                                     |
+| `linkAddress(address)`                 | The address if a link may use it, otherwise `null`.                            |
+| `renderTextArea(text, { multiline? })` | A textarea field's text as safe HTML: paragraphs and line breaks, or one line. |
+
+## Live preview
+
+|                                                                          |                                                                                                                                                                |
+| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `previewTokenFrom(url)`, `previewParameter`                              | The token in an address (`cms_preview`).                                                                                                                       |
+| `previewHeaders`                                                         | `Cache-Control: no-store`, `X-Robots-Tag: noindex`.                                                                                                            |
+| `framingPolicy(adminOrigin)`                                             | The `Content-Security-Policy` value that lets the admin app frame the site.                                                                                    |
+| `addFramingPolicy(headers, adminOrigin)`                                 | Adds that policy to a response's headers, keeping any policy the site already sends (only its `frame-ancestors` is replaced). Use this in your own middleware. |
+| `originOf(address)`                                                      | The origin of a web address (`https://admin.example.com`), or `null`.                                                                                          |
+| `isRefreshRequest(event, adminOrigin)`, `refreshMessageType`             | Whether a message is the editor asking for a refresh, from the right origin.                                                                                   |
+| `swapPageContent(current, fresh)`                                        | Swaps a page's content for a fresh copy without reloading.                                                                                                     |
+| `listenForPreviewRefresh(adminOrigin, refresh?)`, `refreshPageContent()` | In the browser: refresh when the editor asks (only the admin origin counts); returns a function that stops listening.                                          |
+
+## Types
+
+`AceEntry<Values>`, `AceImageData`, `AceMenu`, `AceMenuItem`, `AceNavigationLink`, `AceRichTextDocument`, `AceRichTextNode`, `AceRichTextMark`, `AceContentTypeSchema`, `AceFieldSchema`, `AceAddress`, `AcePage`, `AceClient`, `AceClientOptions`, `AceImageAttributes`, `AceImageOptions`, and the ones generation fills in: `AceContentTypes`, `AceContentTypeHandle`, `AceValuesOf`.
+
+## Astro
+
+`@sandboxsonny/ace-kit/astro/integration`: the integration (default export), `ace()`.
+
+`@sandboxsonny/ace-kit/astro` (uses the integration's settings, so there is no client to create):
+
+|                                                                                           |                                                                                                                                                           |
+| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `getPage(Astro)`                                                                          | What to show for the page being requested; also sets the response's status and headers. A `redirect` is returned for you to act on with `Astro.redirect`. |
+| `getEntry(contentType, handle)`, `getEntries(contentType, { limit? })`, `getMenu(handle)` | As on the client.                                                                                                                                         |
+| `getMenuLinks(handle, { fallback? })`                                                     | A menu's links, or the fallback if the menu is missing or the CMS is down.                                                                                |
+| `applyPage(response, page)`                                                               | Puts a page's status and headers on a response.                                                                                                           |
+| `ace`                                                                                     | The client these use.                                                                                                                                     |
+
+Components, by file: `AceImage.astro`, `AceRichText.astro`, `AceTextArea.astro`, `AceMenu.astro`, `AceNotice.astro`, `AcePreviewRefresh.astro`.
+
+## React Router 7
+
+`@sandboxsonny/ace-kit/vite`: the plugin (default export), `ace()`.
+
+`@sandboxsonny/ace-kit/react-router` (browser-safe):
+
+|                                                       |                                                                      |
+| ----------------------------------------------------- | -------------------------------------------------------------------- |
+| `AceRichText`, `AceTextArea`, `AceImage`, `AceNotice` | Components; rich text links are router links.                        |
+| `createMeta({ siteName? })`, `meta`                   | The route's `meta`.                                                  |
+| `useAceMenu()`, `useAcePreview()`                     | Read the header menu; keep a preview fresh. Need `createRootLoader`. |
+
+`@sandboxsonny/ace-kit/react-router/server` (server only):
+
+|                                                                     |                                                                  |
+| ------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `createPageLoader<Values>()`, `loader`                              | The loader for the catch-all route that draws every page.        |
+| `headers`                                                           | The route's `headers` export.                                    |
+| `createRootLoader({ menu, fallback? })`                             | The root loader: the menu's links and whether this is a preview. |
+| `handleRequest`, `streamTimeout`                                    | The server entry.                                                |
+| `getEntry`, `getEntries`, `getMenu`, `getMenuLinks`, `getAceClient` | Read content from your own loaders.                              |
+
+## React (`@sandboxsonny/ace-kit/react`)
+
+`AceImage`, `AceRichText` (with `link`), `usePreviewRefresh(adminOrigin, refresh?)`.

package/docs/astro.md

@@ -0,0 +1,93 @@
+# Astro
+
+Needs `astro` 5 or newer, rendering on the server (`output: "server"`) so an edit published in the CMS shows on the next page load. There is nothing to wire up by hand: add the integration, and use the functions and components.
+
+## Set up
+
+```js
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import ace from "@sandboxsonny/ace-kit/astro/integration";
+
+export default defineConfig({
+  output: "server",
+  integrations: [ace()],
+});
+```
+
+The integration declares three settings, adds the middleware that lets the CMS's admin app (and only it) frame the site for [live preview](./live-preview.md), and makes Vite process the kit. The settings are read when the server starts, not baked into the build, so one build runs anywhere:
+
+| Setting                    | Default                 | Meaning                                                   |
+| -------------------------- | ----------------------- | --------------------------------------------------------- |
+| `ACE_API_URL`              | `http://localhost:8080` | where the CMS Ace API lives                               |
+| `ACE_SITE_DOMAIN`          | `localhost`             | the domain this site has in the CMS (the port is ignored) |
+| `ACE_PREVIEW_ADMIN_ORIGIN` | `http://localhost:5173` | where the CMS admin app runs                              |
+
+Put them in `.env` for development and in the environment for production.
+
+## Pages
+
+One catch-all route draws every page. `getPage` works out what to show from the address and sets the response's status and headers (a missing page is a 404, a preview is never cached or indexed):
+
+```astro
+---
+// src/pages/[...slug].astro
+import { getPage } from "@sandboxsonny/ace-kit/astro";
+import AceNotice from "@sandboxsonny/ace-kit/astro/AceNotice.astro";
+
+const page = await getPage(Astro);
+if (page.kind === "redirect") return Astro.redirect(page.location, page.status);
+---
+
+{page.kind === "entry" ? <h1>{page.entry.title}</h1> : <AceNotice page={page} />}
+```
+
+Addresses are `/{content type}/{entry}` as on Shopify, `/` is the `home` entry of `pages`, and `/pages/home` redirects to `/`. `page.kind` is `entry`, `redirect`, `not-found`, `unavailable` or `preview-expired`. `AceNotice` draws a heading and a message for the last three; draw your own if you prefer.
+
+## Reading content
+
+Anywhere in a page or component:
+
+```astro
+---
+import { getEntry, getEntries, getMenuLinks } from "@sandboxsonny/ace-kit/astro";
+
+const about = await getEntry("pages", "about"); // one entry, or null
+const posts = await getEntries("posts", { limit: 10 }); // a content type's entries, newest first
+const links = await getMenuLinks("main-menu", { fallback: [{ label: "Home", to: "/" }] });
+---
+```
+
+`getMenuLinks` returns `[{ label, to, children? }]`, ready to draw. If the site has no such menu yet, or the CMS can't be reached, you get the `fallback`, so a missing menu never takes a page down. With [typed content](./typed-content.md), `getEntry("pages", "about")` knows the shape of a page's values.
+
+There is a client behind these (`ace` from the same import, made with the three settings) if you want `getMenu`, `getContentTypes` or the raw client.
+
+## Components
+
+Import them by file:
+
+```astro
+---
+import AceImage from "@sandboxsonny/ace-kit/astro/AceImage.astro";
+import AceRichText from "@sandboxsonny/ace-kit/astro/AceRichText.astro";
+import AceTextArea from "@sandboxsonny/ace-kit/astro/AceTextArea.astro";
+import AceMenu from "@sandboxsonny/ace-kit/astro/AceMenu.astro";
+import AcePreviewRefresh from "@sandboxsonny/ace-kit/astro/AcePreviewRefresh.astro";
+---
+
+<AceMenu handle="main-menu" />
+<AceImage image={entry.values.hero} sizes="(min-width: 64rem) 64rem, 100vw" lazy={false} />
+<AceRichText document={entry.values.body} />
+<AcePreviewRefresh />
+```
+
+- **AceMenu** draws a whole menu as a `<nav>` with nested lists, marking the current page with `aria-current="page"`. Props: `handle`, `fallback`, `label` (what a screen reader calls it) and `class`. It is deliberately unstyled (`.ace-menu`, `.ace-menu__list`, `.ace-menu__sublist` are the hooks); to control the markup, use `getMenuLinks` and draw it yourself.
+- **AceImage** writes an `<img>` with `src`, `srcset`, `sizes`, `width`, `height`, `alt`, `loading` and `decoding`. Set `sizes` to how wide the image is shown, and `lazy={false}` for the image at the top of the page.
+- **AceRichText** draws a rich text field as HTML. It outputs bare elements (`h2`, `p`, `ul`, `a`...); style them from a wrapping element. Astro scopes styles, so reach them with `:global`, e.g. `.rich-text :global(h2) { ... }`.
+- **AceTextArea** draws a Textarea field (plain text): `multiline` (the default) makes paragraphs of blocks and a `<br>` of a new line; `multiline={false}` is one line of text with no element around it.
+- **AcePreviewRefresh** goes once in your layout. It does nothing unless the page was opened by the CMS's editor.
+- **AceNotice** is the message for a page that isn't an entry.
+
+## Without the integration
+
+The integration is what makes the settings and the middleware automatic. If you can't use it, use the framework-free [client](./getting-started.md#the-client) and `loadPage` from the core, and call `addFramingPolicy(response.headers, origin)` in your own middleware.

package/docs/getting-started.md

@@ -0,0 +1,62 @@
+# Getting started
+
+Ace Kit is everything a website needs to use CMS Ace (see the [README](../README.md)): a typed client for the public API, addressing (`/{content type}/{entry}`), responsive images, menus, rich text, live preview support, and thin Astro and React adapters. It has no runtime dependencies.
+
+## Install
+
+```sh
+npm install @sandboxsonny/ace-kit
+```
+
+(pnpm, Yarn and Bun work the same way.) Needs Node 22.12 or newer. `astro` (5 or newer), `react` (18 or newer), `react-router` (7) and `vite` are optional peer dependencies: install whichever adapter you use.
+
+## What you import from where
+
+| Import                                                   | What is in it                                                                                                                                                     |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@sandboxsonny/ace-kit`                                  | The framework-free core: the client, errors, `loadPage`, addressing, image attributes, menu helpers, rich text to HTML, preview helpers, all the types            |
+| `@sandboxsonny/ace-kit/astro/integration`                | The Astro integration: add it to `astro.config.mjs` and an Astro site is wired up                                                                                 |
+| `@sandboxsonny/ace-kit/astro`                            | What an Astro page calls: `getPage`, `getEntry`, `getEntries`, `getMenuLinks`, `getMenu`, `ace` (the client)                                                      |
+| `@sandboxsonny/ace-kit/astro/AceImage.astro` and friends | Astro components: `AceImage`, `AceRichText`, `AceMenu`, `AceNotice`, `AcePreviewRefresh`                                                                          |
+| `@sandboxsonny/ace-kit/react`                            | `AceImage`, `AceRichText`, `usePreviewRefresh`                                                                                                                    |
+| `@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                                                                                                |
+
+## The client
+
+**On Astro and React Router 7 you can skip this section**: the [Astro integration](./astro.md) and the [React Router adapter](./react-router.md) make the client for you, and you call `getEntry`, `getMenuLinks` and the page loaders directly.
+
+For anything else, create one client for the whole site, on the server. The browser never talks to the CMS API.
+
+```ts
+import { createAceClient } from "@sandboxsonny/ace-kit";
+
+export const cms = createAceClient({
+  apiUrl: "https://api.example.com", // where CMS Ace's API lives
+  siteDomain: "www.example.com", // the domain this site has in the CMS
+});
+
+const about = await cms.getEntry("pages", "about"); // one entry, or null
+const posts = await cms.getEntries("posts", { limit: 10 }); // a content type's live entries, newest first
+const menu = await cms.getMenu("main-menu"); // a navigation menu, or null
+```
+
+- Answers are reused for 5 seconds (`cacheSeconds`, `0` turns it off), because every visitor looks like one IP address to the API's rate limit.
+- A site that is not set up in the CMS, an unreachable CMS and an unexpected answer all throw `AceUnavailableError`, so a page can show "try again shortly" rather than "not found".
+- Entry handles are unique across a site; `getEntry("pages", "about")` returns `null` if `about` belongs to another content type.
+
+## Drawing pages
+
+`loadPage` works out what to do for a request, the same way for every framework:
+
+```ts
+import { loadPage } from "@sandboxsonny/ace-kit";
+
+const page = await loadPage(cms, { slug: "pages/about", url: new URL(request.url) });
+// page.kind: "entry" | "redirect" | "not-found" | "unavailable" | "preview-expired"
+// page.status, page.headers: what to send back
+```
+
+It reads `/{content type}/{entry}` addresses (as on Shopify), treats `/` as the `home` entry of `pages`, redirects `/pages/home` to `/`, and handles live preview tokens. See [Astro](./astro.md), [React Router](./react-router.md) and [React](./react.md) for routes that use it. `loadMenuLinks(client, handle, fallback)` does for menus what `getMenuLinks` does in Astro: the links, or the fallback if the menu is missing or the CMS is down.

package/docs/live-preview.md

@@ -0,0 +1,15 @@
+# Live preview
+
+CMS Ace's editor shows your real site next to the form. It opens your site inside a frame at the entry's address with a preview token (`?cms_preview=<token>`), and every time the editor saves a draft it asks the page to refresh. For that to work a site must:
+
+1. **Read the token and pass it on.** `loadPage` does: it hands the token to `getEntry`, which asks the API for the entry with its draft applied. A token that has run out gives `page.kind === "preview-expired"`.
+2. **Never cache or index a preview.** `page.headers` has `Cache-Control: no-store` and `X-Robots-Tag: noindex` for such pages; send them (`getPage` does in Astro). Add `<meta name="robots" content="noindex">` too.
+3. **Allow the admin app to frame the site, and nobody else.** Send `Content-Security-Policy: frame-ancestors 'self' <admin origin>` on every response. The Astro integration and the React Router adapter do this for you; elsewhere call `addFramingPolicy(headers, origin)` on each response, which adds the directive to any policy the site already sends instead of replacing it.
+4. **Refresh when asked.** A small script listens for the editor's message, accepts it only from the admin origin, fetches the page again and swaps the content in without a reload (the scroll position stays).
+   - Astro: render `<AcePreviewRefresh />` once in the layout. It knows whether the page is a preview and where the admin app is (`ACE_PREVIEW_ADMIN_ORIGIN`).
+   - React: call `usePreviewRefresh(adminOrigin, refresh)` once.
+   - Anything else: `listenForPreviewRefresh(adminOrigin)` from the core, in the browser.
+
+Then, in the CMS, set the site's **Preview address** (Settings) to where the site runs. The admin app and the site must both be `http` or both `https`: browsers refuse an `http` frame inside an `https` page.
+
+The admin origin is a setting of the site (`ACE_PREVIEW_ADMIN_ORIGIN` in Astro), because it differs between development and production.