@sandboxsonny/ace-kit 0.0.0-stage → 0.1.1

package/docs/react-router.md

@@ -0,0 +1,116 @@
+# React Router 7
+
+Ace Kit has a React Router adapter, so a site only writes its design. It needs `react-router` 7 in framework mode with server rendering (`ssr: true`, the default), `@react-router/node`, `react-dom` and `vite`.
+
+```
+app/
+  routes.ts            route("*", "routes/page.tsx")            one route draws every page
+  entry.server.tsx     one line
+  root.tsx             createRootLoader + your layout and header
+  routes/page.tsx      createPageLoader + your page
+vite.config.ts         plugins: [ace(), reactRouter()]
+```
+
+## Set up
+
+**1. The Vite plugin** reads the settings from `.env` in development and makes sure the site uses one copy of React:
+
+```ts
+// vite.config.ts
+import ace from "@sandboxsonny/ace-kit/vite";
+import { reactRouter } from "@react-router/dev/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({ plugins: [ace(), reactRouter()] });
+```
+
+The settings are environment variables, read when the server starts, so one build runs anywhere. Put them in `.env` for development and in the host's environment for production:
+
+| Variable                   | 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                              |
+
+**2. The server entry**, which renders pages and lets the CMS's admin app (and only it) frame the site for [live preview](./live-preview.md):
+
+```tsx
+// app/entry.server.tsx
+export { handleRequest as default, streamTimeout } from "@sandboxsonny/ace-kit/react-router/server";
+```
+
+It waits until a page is completely ready before answering (every page is fully loaded by its loader, and crawlers get whole pages). If you stream deferred data, write your own entry and call `addFramingPolicy(responseHeaders, origin)` in it.
+
+**3. One route for every page:**
+
+```ts
+// app/routes.ts
+import { type RouteConfig, route } from "@react-router/dev/routes";
+
+export default [route("*", "routes/page.tsx")] satisfies RouteConfig;
+```
+
+```tsx
+// app/routes/page.tsx
+import { AceNotice, createMeta } from "@sandboxsonny/ace-kit/react-router";
+import { createPageLoader } from "@sandboxsonny/ace-kit/react-router/server";
+import type { Route } from "./+types/page";
+
+export const loader = createPageLoader();
+export { headers } from "@sandboxsonny/ace-kit/react-router/server";
+export const meta = createMeta({ siteName: "My Site" });
+
+export default function Page({ loaderData: page }: Route.ComponentProps) {
+  return page.kind === "entry" ? <h1>{page.entry.title}</h1> : <AceNotice page={page} />;
+}
+```
+
+The loader reads the address (`/{content type}/{entry}`, and `/` is the `home` entry of `pages`), loads the entry and answers with the right status and headers: a missing page is a real 404, an unreachable CMS a 503, an expired preview a 403, `/pages/home` redirects to `/`, and a preview is never cached or indexed. `page.kind` is `entry`, `not-found`, `unavailable` or `preview-expired`. `createMeta` titles the page from the entry (followed by the site's name), adds its description, and asks search engines to ignore a preview. With [typed content](./typed-content.md), `createPageLoader<PageValues>()` gives `page.entry.values` its real shape.
+
+**4. The root route** loads the header menu and keeps previews fresh:
+
+```tsx
+// app/root.tsx
+import { useAceMenu, useAcePreview } from "@sandboxsonny/ace-kit/react-router";
+import { createRootLoader } from "@sandboxsonny/ace-kit/react-router/server";
+
+export const loader = createRootLoader({
+  menu: "main-menu", // the CMS menu with this handle
+  fallback: [{ label: "Home", to: "/" }], // if the site has none yet, or the CMS is down
+});
+
+export default function App() {
+  useAcePreview(); // in the CMS's preview frame, redraws the page when the editor saves a draft
+  const links = useAceMenu(); // [{ label, to, children? }]
+  return (/* your header, <Outlet />, your footer */);
+}
+```
+
+`useAcePreview` and `useAceMenu` read what `createRootLoader` loaded, so call them in the root route (or anywhere below it). If your root loader loads more, spread ours into yours: `return { ...(await aceLoader(args)), other }`.
+
+## Components
+
+From `@sandboxsonny/ace-kit/react-router` (these are safe in the browser):
+
+- **AceRichText** draws a rich text field. Links to pages of this site are router `Link`s, so navigating doesn't reload the page. It renders bare elements; style them from a wrapper.
+- **AceTextArea** draws a Textarea field (plain text): `multiline` (the default) makes paragraphs and line breaks, `multiline={false}` is one line of text.
+- **AceImage** is an `<img>` with `src`, `srcset`, `sizes`, size and alt text. Set `sizes` to how wide it is shown, and `lazy={false}` for the image at the top of the page.
+- **AceNotice** is the heading and message for a page that isn't an entry. Give it a `className`.
+
+## Reading content in your own loaders
+
+From `@sandboxsonny/ace-kit/react-router/server`, with no client to create:
+
+```ts
+import { getEntries, getEntry, getMenuLinks } from "@sandboxsonny/ace-kit/react-router/server";
+
+export async function loader() {
+  return { posts: await getEntries("posts", { limit: 10 }) };
+}
+```
+
+`getAceClient()` is the client behind them. Import these only in loaders, `headers` and `entry.server.tsx`: React Router leaves them out of the browser bundle, which is what keeps the settings and the CMS address on the server.
+
+## Without the adapter
+
+Everything the adapter does is built from the framework-free [core](./getting-started.md): `loadPage`, `loadMenuLinks`, `previewTokenFrom`, `addFramingPolicy`, the [React components](./react.md) and `usePreviewRefresh`. The adapter is about 150 lines; read it if you need to do something it doesn't.

package/docs/react.md

@@ -0,0 +1,81 @@
+# React
+
+Needs `react` 18 or newer. The components work with any React framework (React Router, Next.js, Remix, plain Vite). **On React Router 7, use the [React Router adapter](./react-router.md) instead of wiring this up yourself.** Fetch with the [client](./getting-started.md#the-client) on the server (a loader, a server component, `getServerSideProps`), then draw.
+
+```tsx
+import { AceImage, AceRichText } from "@sandboxsonny/ace-kit/react";
+```
+
+## AceImage
+
+```tsx
+<AceImage image={entry.values.hero} sizes="(min-width: 64rem) 64rem, 100vw" lazy={false} className="hero" />
+```
+
+An `<img>` with `src`, `srcset`, `sizes`, `width`, `height` and `alt`. Any other `<img>` prop (`className`, `style`, `onLoad`...) is passed through. `lazy` defaults to `true`; turn it off for the image at the top of the page.
+
+## AceRichText
+
+```tsx
+<div className="prose">
+  <AceRichText document={entry.values.body} />
+</div>
+```
+
+Draws a rich text field as React elements: no `dangerouslySetInnerHTML`, text is escaped by React, only the kinds of content the CMS allows are drawn, and link addresses are checked again. It renders bare elements, so style them from the wrapper.
+
+Give it your router's link so navigation stays in the browser:
+
+```tsx
+import { Link } from "react-router";
+
+<AceRichText document={body} link={({ href, children }) => <Link to={href}>{children}</Link>} />;
+```
+
+External links, `mailto:` and `tel:` links should stay plain `<a>`: have your `link` component check the address and fall back, if you mix them.
+
+## AceTextArea
+
+```tsx
+<AceTextArea value={entry.values.summary} />                       {/* paragraphs; a new line is a <br> */}
+<p><AceTextArea value={entry.values.tagline} multiline={false} /></p>  {/* one line, no element around it */}
+```
+
+Draws a Textarea field (plain text, not rich text). Text is escaped by React.
+
+## Live preview
+
+```tsx
+import { usePreviewRefresh } from "@sandboxsonny/ace-kit/react";
+import { useRevalidator } from "react-router";
+
+function PreviewRefresh({ adminOrigin }: { adminOrigin: string | null }) {
+  const { revalidate } = useRevalidator();
+  const refresh = useCallback(() => revalidate(), [revalidate]);
+  usePreviewRefresh(adminOrigin, refresh);
+  return null;
+}
+```
+
+Pass `adminOrigin` only for a page shown with a preview token (`previewTokenFrom(url)` tells you). See [Live preview](./live-preview.md) for the rest: call `addFramingPolicy(headers, origin)` on every response (React Router: `entry.server.tsx`), and pass `page.headers` on so a preview is never cached.
+
+## A route in React Router 7
+
+```tsx
+// app/routes.ts: one route draws every page
+export default [route("*", "routes/page.tsx")] satisfies RouteConfig;
+
+// app/routes/page.tsx
+export async function loader({ request, params }: Route.LoaderArgs) {
+  const page = await loadPage(ace, { slug: params["*"], url: new URL(request.url) });
+  if (page.kind === "redirect") return redirect(page.location, { status: page.status, headers: page.headers });
+  return data(page, { status: page.status, headers: page.headers });
+}
+export const headers: Route.HeadersFunction = ({ loaderHeaders }) => loaderHeaders;
+
+export default function Page({ loaderData: page }: Route.ComponentProps) {
+  return page.kind === "entry" ? <h1>{page.entry.title}</h1> : <p>Not here</p>;
+}
+```
+
+Returning `data(page, { status })` (rather than throwing) keeps a 404 or 503 inside your layout, with the header and footer.

package/docs/releasing.md

@@ -0,0 +1,45 @@
+# Releasing
+
+Versions and the changelog are managed with [Changesets](https://github.com/changesets/changesets), and releases are published to [npm](https://www.npmjs.com) by GitHub Actions. The package follows [semantic versioning](https://semver.org): patch for fixes, minor for backwards compatible additions, major for breaking changes. While the version is below 1.0.0, a minor release may contain breaking changes (say so in the changeset).
+
+## Day to day
+
+Every change that someone using the kit would notice gets a changeset:
+
+```sh
+npm run changeset
+```
+
+It asks for the size and a summary, and writes a small file in `.changeset/`. Commit it with the change. Nothing else is needed.
+
+## Releasing
+
+When changes are merged to `main`, the **Release** workflow opens (or updates) a pull request called "Version Packages". It bumps `package.json` and writes the summaries into `CHANGELOG.md`. Read it, then merge it: the workflow then publishes the new version to npm and tags it.
+
+Each published version carries npm **provenance**: a public statement, signed by GitHub, that this exact package was built from this repository by this workflow. People can check it on the package's npm page (and with `npm audit signatures`).
+
+## One-time setup
+
+1. **Own the scope.** The package is `@sandboxsonny/ace-kit`; a scope on npm belongs to a user or an organisation of that name. [Create an npm account](https://www.npmjs.com/signup) called `sandboxsonny` (or an organisation with that name) and turn on two-factor authentication. If the name isn't available, pick another scope and follow "If the scope changes" below.
+2. **A public repository,** with branch protection on `main` that requires the CI checks, so a release can only come from reviewed, passing code. Also turn on private vulnerability reporting (Settings → Security), which `SECURITY.md` points to.
+3. **The first publish,** which needs a token because the package doesn't exist yet to attach trusted publishing to. Create a _granular access token_ on npm with read and write permission on the scope and a short expiry, store it in the repository as the secret `NPM_TOKEN`, and pass it to the release step as `NODE_AUTH_TOKEN`. (Or publish version 0.1.0 by hand: `npm login`, then `npm run release`.)
+4. **Trusted publishing,** so no token is needed after that. On the package's page on npmjs.com → Settings → Trusted Publisher, add GitHub Actions with: the owner and repository exactly as GitHub spells them (**`sandboxSonny`** and **`ace-kit`**: the capitals matter), and the workflow file name **`release.yml`**. npm shows it as "not yet validated" until one publish goes through it, and drops it if that doesn't happen within 48 hours. Make the next release (even a patch with no code change) to validate it.
+5. **Remove the token:** delete the `NPM_TOKEN` secret and revoke the token on npm, and make sure the workflow does not pass `NODE_AUTH_TOKEN` (npm would use it instead of the trusted route).
+
+The workflow in this repository is already in the last state: no token, Node 24 with npm 11.5.1 or newer, and `id-token: write`. If a publish fails with a message about authentication, check that the repository name and workflow file name in the Trusted Publisher settings match exactly, and that the job really is running `release.yml` on `main`.
+
+## What the checks protect
+
+`npm run release` and CI run `npm run check`, which ends with `scripts/check-package.mjs`. It fails if a file the package points at is missing, if the command line tool has no `#!` line, if sources or tests would be published, or if `package.json` is not set up for publishing (scoped name, public access).
+
+## Trying it before it is published
+
+`npm run pack:local` builds the package and packs it into `sandboxsonny-ace-kit-<version>.tgz`, which is exactly what would be published. Install that file in a site (`npm install /path/to/sandboxsonny-ace-kit-0.1.0.tgz`). Prefer this to linking the folder (`file:../ace-kit`): a link hides problems a real install has (missing files, a wrong `exports` map), and Astro cannot find the preview script through an absolute link from outside the project.
+
+## If the scope changes
+
+The package name appears in `package.json`, in `src/helpers/package-name.ts` (generated types augment it; a test checks the two agree), in the docs, and in the integration code (`src/astro/integration.ts`). Search for `@sandboxsonny` and change it everywhere, then add a major changeset: consumers must change their imports.
+
+## Publishing to GitHub Packages instead
+
+Possible, with more friction for everyone who installs: GitHub's npm registry asks for a token even for public packages. Set `publishConfig.registry` to `https://npm.pkg.github.com`, `registry-url` in the workflow to the same, `NODE_AUTH_TOKEN` to `${{ secrets.GITHUB_TOKEN }}`, give the job `packages: write`, and tell users to add `@sandboxsonny:registry=https://npm.pkg.github.com` and a `read:packages` token to their `.npmrc`. (Provenance isn't available there.)

package/docs/rich-text.md

@@ -0,0 +1,54 @@
+# Rich text
+
+A rich text field's value is a **document**: a small, safe JSON tree (no HTML in it).
+
+```json
+{
+  "type": "doc",
+  "content": [
+    { "type": "heading", "attrs": { "level": 2 }, "content": [{ "type": "text", "text": "Hello" }] },
+    {
+      "type": "paragraph",
+      "content": [
+        { "type": "text", "text": "Read " },
+        { "type": "text", "text": "about us", "marks": [{ "type": "link", "attrs": { "href": "/pages/about" } }] }
+      ]
+    },
+    { "type": "image", "attrs": { "assetId": 12, "image": { "src": "...", "srcset": "...", "alt_text": "..." } } }
+  ]
+}
+```
+
+| Node                                  | Notes                                                        |
+| ------------------------------------- | ------------------------------------------------------------ |
+| `paragraph`, `blockquote`, `listItem` |                                                              |
+| `heading`                             | `attrs.level` 2, 3 or 4                                      |
+| `bulletList`, `orderedList`           | `orderedList` has `attrs.start` when it doesn't begin at 1   |
+| `text`                                | `marks`: `bold`, `italic`, `link`                            |
+| `hardBreak`                           |                                                              |
+| `image`                               | `attrs.image` is the usual image object, resolved by the API |
+
+Links arrive with their address already worked out: a link to an entry is `/{content type}/{entry}`. An image that was deleted is left out, and a link to a deleted entry keeps its words but loses the link.
+
+## Drawing it
+
+- **Astro:** `<AceRichText document={...} />` ([Astro](./astro.md)).
+- **React:** `<AceRichText document={...} />` ([React](./react.md)).
+- **Anything else:** `renderRichText(document)` returns an HTML string. Every piece of text and every attribute is escaped, so it is safe to put on a page as it is.
+
+All three draw only what is in the table, check link addresses again (only paths, `https://`, `http://`, `mailto:` and `tel:` are links), and leave out anything they don't know, so a newer CMS can't break an older site.
+
+## Plain text fields
+
+A _Textarea_ field (not rich text) holds a plain string. `AceTextArea` draws it, and `multiline` says how:
+
+```astro
+<AceTextArea value={entry.values.summary} />{" "}
+<!-- <p>…</p><p>…</p>: blank lines start paragraphs, a new line is a <br> -->
+<p>
+  <AceTextArea value={entry.values.tagline} multiline={false} />
+</p>
+<!-- one line of text, with no element around it -->
+```
+
+It is the same component in Astro (`AceTextArea.astro`), React and React Router (`AceTextArea`). Text is escaped. For anything else, `renderTextArea(text, { multiline })` returns the same thing as an HTML string.

package/docs/typed-content.md

@@ -0,0 +1,50 @@
+# Typed content
+
+The kit can write TypeScript types for your site's content types, so `getEntry` and `getEntries` return the right shape and a change in the CMS shows up as a type error in your site.
+
+```sh
+npx ace-kit generate --api-url http://localhost:8080 --domain localhost
+```
+
+or with the settings in the environment:
+
+```sh
+ACE_API_URL=http://localhost:8080 ACE_SITE_DOMAIN=localhost npx ace-kit generate
+```
+
+It reads `GET /public/content-types` (no login: it describes field names and kinds, never entries) and writes `src/ace-kit.generated.d.ts` (change it with `--out`). Make sure the file is inside your `tsconfig` `include`. Commit it, and run the command again whenever content types change (a good moment is a CI step, or a `generate` script next to `dev`).
+
+```ts
+// ace-kit.generated.d.ts (generated)
+declare module "@sandboxsonny/ace-kit" {
+  interface AceContentTypes {
+    pages: {
+      headline: string; // required fields are always there
+      body?: AceRichTextDocument; // others may be missing
+      hero?: AceImageData;
+    };
+  }
+}
+```
+
+Now the content type's handle is checked and its values are typed:
+
+```ts
+const about = await cms.getEntry("pages", "about"); // AceEntry<{ headline: string; body?: ...; hero?: ... }> | null
+about?.values.headline; // string
+cms.getEntry("pagez", "about"); // type error: no such content type
+```
+
+| Field                            | Type                                                |
+| -------------------------------- | --------------------------------------------------- |
+| Text, Textarea                   | `string`                                            |
+| Number                           | `number`                                            |
+| Checkbox                         | `boolean`                                           |
+| Select                           | a union of its options, e.g. `"formal" \| "casual"` |
+| Image                            | `AceImageData`                                      |
+| Rich text                        | `AceRichTextDocument`                               |
+| a kind this version doesn't know | `unknown`                                           |
+
+A field is optional unless it is marked required in the CMS. Before you generate, handles are plain `string` and values are `Record<string, unknown>`, so nothing breaks.
+
+For a content type you use in a component, name its values once: `type PageValues = AceContentTypes["pages"]`.

package/package.json

@@ -1,6 +1,160 @@
 {
   "name": "@sandboxsonny/ace-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Everything a website needs to use CMS Ace: a typed client, addressing, images, menus, rich text, live preview, and Astro and React adapters.",
+  "keywords": [
+    "cms",
+    "cms-ace",
+    "headless-cms",
+    "astro",
+    "react"
+  ],
+  "license": "MIT",
+  "author": "Adams Development <sonny@adamsdevelopment.co.uk>",
+  "homepage": "https://github.com/sandboxSonny/ace-kit#readme",
+  "bugs": {
+    "url": "https://github.com/sandboxSonny/ace-kit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sandboxSonny/ace-kit.git"
+  },
+  "type": "module",
+  "sideEffects": [
+    "./dist/preview-script.js"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "files": [
+    "dist",
+    "astro",
+    "docs",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./react-router": {
+      "types": "./dist/react-router.d.ts",
+      "import": "./dist/react-router.js"
+    },
+    "./react-router/server": {
+      "types": "./dist/react-router-server.d.ts",
+      "import": "./dist/react-router-server.js"
+    },
+    "./astro": {
+      "types": "./dist/astro.d.ts",
+      "import": "./dist/astro.js"
+    },
+    "./astro/integration": {
+      "types": "./dist/astro-integration.d.ts",
+      "import": "./dist/astro-integration.js"
+    },
+    "./astro/middleware": {
+      "import": "./dist/astro-middleware.js"
+    },
+    "./astro/*.astro": "./astro/*.astro",
+    "./preview-script": {
+      "import": "./dist/preview-script.js"
+    },
+    "./package.json": "./package.json",
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
+    }
+  },
+  "bin": {
+    "ace-kit": "./dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run format:check && npm run lint && npm run typecheck && npm test && npm run build && npm run check:package",
+    "check:package": "node scripts/check-package.mjs",
+    "pack:local": "npm run build && npm pack",
+    "storybook": "storybook dev -p 6006",
+    "build:storybook": "storybook build",
+    "changeset": "changeset",
+    "version": "changeset version && prettier --write CHANGELOG.md package.json",
+    "release": "npm run check && changeset publish"
+  },
+  "peerDependencies": {
+    "astro": ">=5",
+    "react": ">=18",
+    "react-router": ">=7",
+    "react-dom": ">=18",
+    "@react-router/node": ">=7",
+    "vite": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "astro": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-router": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "@react-router/node": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@changesets/cli": "^3.0.3",
+    "@eslint/js": "^10.0.1",
+    "@react-router/node": "^7.18.4",
+    "@storybook/addon-docs": "^10.6.1",
+    "@storybook/react-vite": "^10.6.1",
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/react": "^16.3.3",
+    "@types/node": "^22.20.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "astro": "^7.3.8",
+    "eslint": "^10.12.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-astro": "^1.7.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^17.13.0",
+    "jsdom": "^29.1.1",
+    "prettier": "^3.9.10",
+    "prettier-plugin-astro": "^1.1.1",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "react-router": "^7.18.4",
+    "storybook": "^10.6.1",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.71.1",
+    "vite": "^8.3.4",
+    "vitest": "^5.0.4"
+  },
+  "overrides": {
+    "esbuild": "^0.28.2"
+  }
+}