@cardinali-studio/adminkit 2.2.24 → 2.2.25

package/LICENSE

@@ -0,0 +1,12 @@
+Copyright (C) 2026 Emanuele Cardinali
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+# AdminKit
+
+AdminKit is the administration engine we use for small, content-driven websites built with Hugo and deployed on Cloudflare Pages.
+
+It turns a Zod schema into three things that must agree:
+
+- the model edited in the browser;
+- the YAML front matter stored in the repository;
+- the validation performed by the server.
+
+There is no second list of fields hidden in the UI, and no second serializer hidden in a Worker. A field is declared once. The rest of the system reads that declaration.
+
+The package also contains the React administration shell, a media library for R2, Cloudflare Pages Functions, and the persistence primitives used by the D1 publication path.
+
+## The important property
+
+An admin panel should not damage a file merely because it does not understand all of it.
+
+AdminKit preserves the Markdown body, unknown front-matter keys, and their comments. An omitted managed field means “leave it alone”, not “delete it”. Before overwriting an existing file, `checkFidelity()` can prove that reading and writing it again is byte-for-byte stable.
+
+If the codec cannot reproduce a file, it says so. Refusing a save is better than producing plausible-looking YAML with missing data.
+
+## Install
+
+```sh
+npm install @cardinali-studio/adminkit zod
+```
+
+The core codec needs Zod 4. The React application and form exports also use the optional peer dependencies listed in `package.json`; install the ones required by the entry points you use.
+
+The package is ESM-only.
+
+## A complete codec example
+
+Each field has two pieces of metadata:
+
+- `ui` describes how a human edits it;
+- `fm` describes how it lives in the file.
+
+```ts
+import * as z from "zod";
+import {
+  checkFidelity,
+  deserializeItem,
+  fm,
+  serializeItem,
+  ui,
+  yamlStr,
+} from "@cardinali-studio/adminkit";
+
+const Article = {
+  title: z.string().min(1).max(120)
+    .register(ui, {
+      label: "Title",
+      widget: "text",
+      group: "content",
+    })
+    .register(fm, {
+      keys: ["title"],
+      encode: (value) => [`title: ${yamlStr(value)}`],
+      decode: (raw) => String(raw.title ?? ""),
+    }),
+
+  published: z.boolean()
+    .register(ui, {
+      label: "Published",
+      widget: "boolean",
+      group: "visibility",
+    })
+    .register(fm, {
+      keys: ["visible"],
+      encode: (value) => [`visible: ${value === true}`],
+      decode: (raw) => raw.visible === true,
+    }),
+};
+
+const markdown = `---
+# Kept with the field.
+title: "A small page"
+visible: false
+
+# AdminKit does not own this key, so it stays untouched.
+build-note: "keep me"
+---
+The Markdown body stays untouched too.
+`;
+
+if (!checkFidelity(markdown, Article).ok) {
+  throw new Error("This file cannot be edited without loss");
+}
+
+const article = deserializeItem(markdown, Article);
+
+const updated = serializeItem(
+  { ...article, published: true },
+  { shape: Article, oldMd: markdown },
+);
+```
+
+Notice that the model calls the boolean `published` while the file calls it `visible`. That conversion belongs to the schema. Hugo templates, React components, and API handlers should not each invent their own version of it.
+
+### Deleting and retiring fields
+
+Absence is not deletion. To clear a value, pass the empty value understood by its encoder and return no YAML lines.
+
+When a key is obsolete, `retired(schema, keys)` keeps ownership of the old key while emitting nothing. Existing files then lose that key on their next intentional save, without maintaining a separate migration list.
+
+## Mounting the admin application
+
+The application is deliberately mounted as one unit:
+
+```ts
+import { mountAdmin, type SiteAdminConfig } from "@cardinali-studio/adminkit/app";
+import "@cardinali-studio/adminkit/theme.css";
+import "./site-theme.css";
+
+const site: SiteAdminConfig = {
+  // Site identity, page types, schemas, enabled modules and persistence mode.
+  // TypeScript checks the complete contract here.
+};
+
+mountAdmin({
+  site,
+  root: document.querySelector("#root"),
+  storagePrefix: "example-admin",
+});
+```
+
+Import the site's theme after AdminKit's theme. This lets a site replace the CSS custom properties without increasing selector specificity.
+
+`storagePrefix` is part of the site's browser data. Changing it on a live installation silently resets saved media preferences, so migrations should keep the old value.
+
+The shell currently speaks Italian. Content can be monolingual or multilingual; the language of the administration interface is a separate concern.
+
+## Cloudflare Pages Functions
+
+Cloudflare routes Functions by file, while an npm package cannot create files in a consuming project's `functions/` directory. A site therefore keeps two small adapters.
+
+The API catch-all:
+
+```js
+// functions/admin/api/[[path]].js
+import { handleAdminApi } from "@cardinali-studio/adminkit/functions";
+import { serverConfig } from "../../../src/admin/site-config.js";
+
+export function onRequest(context) {
+  return handleAdminApi(context, serverConfig);
+}
+```
+
+And the access middleware:
+
+```js
+// functions/admin/_middleware.js
+export { adminAccess as onRequest } from "@cardinali-studio/adminkit/functions";
+```
+
+Site-specific endpoints may live beside these files. More specific Cloudflare routes take precedence over the catch-all.
+
+The server configuration is site-owned. It supplies schemas, repository details, enabled modules, storage bindings and, in D1 mode, the complete document validator. Missing optional modules fail closed.
+
+## Persistence and publication
+
+The original persistence path writes Markdown through GitHub and lets Hugo build it. The newer path stores immutable revisions in D1 and publishes an exact release snapshot.
+
+The D1 modules are intentionally lower-level than the admin shell. They provide:
+
+- deterministic request checksums and idempotent saves;
+- compare-and-swap protection for concurrent drafts;
+- immutable, checksum-covered release exports;
+- a single deployment lane for code and content;
+- copy-first media moves and delete journals for R2;
+- versioned site-access secrets;
+- pure release materialization, with filesystem effects left to CI.
+
+They do not decide what a site's document means. Validation and materialization remain site-owned.
+
+## Entry points
+
+| Import | Purpose |
+| --- | --- |
+| `@cardinali-studio/adminkit` | Schema registries, front-matter codec, API client, i18n, persistence and release primitives |
+| `@cardinali-studio/adminkit/app` | Complete React administration shell |
+| `@cardinali-studio/adminkit/form` | Schema form and media components |
+| `@cardinali-studio/adminkit/functions` | Cloudflare Pages API router and access middleware |
+| `@cardinali-studio/adminkit/materializer` | Pure release-to-files materialization |
+| `@cardinali-studio/adminkit/preview` | Local preview component |
+| `@cardinali-studio/adminkit/testing` | Content-stability checks for consuming sites |
+| `@cardinali-studio/adminkit/theme.css` | Default design tokens |
+
+## What this is not
+
+AdminKit is not a generic headless CMS, a form builder, or a promise to support every YAML construct.
+
+It is opinionated about the useful narrow case: Hugo content, React 19, Zod 4, Cloudflare Pages, R2 and optionally D1. The front-matter emitter supports the structures used by that system and throws on values it cannot represent safely.
+
+This narrowness is intentional. A smaller system with explicit failure modes is easier to trust around content that people have edited by hand.
+
+## Development
+
+```sh
+npm test
+npm run build
+npm run check
+```
+
+`npm run check` rebuilds the package and runs the Node test suite. The tests include byte-identical codec round trips, malformed-input rejection, import resolution, concurrency conflicts, release invariants, media-operation transitions, and a guard against site-specific code entering the shared package.
+
+Generated files live in `dist/` and are the only application files included in the npm tarball, in addition to npm's standard package metadata and this README.
+
+## License
+
+[0BSD](./LICENSE). Use it, copy it, change it, ship it. Attribution is appreciated but not required.

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@cardinali-studio/adminkit",
-  "version": "2.2.24",
+  "version": "2.2.25",
   "type": "module",
   "description": "Motore riusabile di un pannello di amministrazione per siti Hugo su Cloudflare Pages: codec del front matter guidato dallo schema, form React, libreria media su R2. NIENTE di specifico di un sito qui dentro.",
-  "license": "UNLICENSED",
+  "license": "0BSD",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {