@sandboxsonny/ace-kit 0.0.0-stage → 0.1.0

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,53 @@
+# 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.
+
+## 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), turn on two-factor authentication, and check <https://www.npmjs.com/package/@sandboxsonny/ace-kit> doesn't already exist. If the name isn't available, pick another scope and follow "If the scope changes" below.
+2. **A token for the workflow.** On npm: Access Tokens → Generate New Token → _Granular access token_, with **Read and write** permission on the `@sandboxsonny` scope, and no expiry longer than you want to manage. Add it to this repository as the secret **`NPM_TOKEN`** (Settings → Secrets and variables → Actions).
+3. **A public repository.** Provenance needs one. Also turn on branch protection for `main` and require the CI checks, so a release can only come from reviewed, passing code.
+
+### The very first release
+
+The first version can also be published by hand, from a clean checkout of `main`:
+
+```sh
+npm login
+npm run version      # turns the pending changeset into 0.1.0 and the changelog (if not already done)
+npm run release      # runs the whole check, then publishes
+```
+
+(Provenance is only added when publishing from GitHub Actions (the workflow turns it on with `NPM_CONFIG_PROVENANCE`), so a hand-published first version has none; later ones do. It is deliberately not in `package.json`: npm refuses to publish from a laptop when it is.)
+
+## 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.0",
+  "description": "Everything a website needs to use CMS Ace: a typed client, addressing, images, menus, rich text, live preview, and Astro and React adapters.",
+  "keywords": [
+    "cms",
+    "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"
+  }
+}