@aotter/mantle 0.2.0-alpha.6 → 0.2.0-alpha.8

package/docs/examples/reservation.md

@@ -1,142 +0,0 @@
----
-description: Accept public reservation requests and expose the queue to staff. One SQL INSERT, no handler code.
----
-# Reservation requests
-
-[Examples hub](./README.md)
-
-Visitors ask for a reservation and staff confirm by hand. The manifests are
-fully declarative: the one Procedure is a SQL `INSERT`. Use this for
-appointments, bookings or table requests where a person decides.
-
-## Problem
-
-A visitor gives a name, an email address, the requested slot, an optional party
-size and a note. Staff see the newest requests first through Admin's API or the
-staff MCP surface, and follow up outside the system. Requests are records, so
-the Schema is `operational`. The system does not decide whether a slot is free.
-
-## Manifest
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v2
-kind: Schema
-metadata: { name: reservations }
-spec:
-  title: Reservations
-  lifecycle: operational
-  checks: ["partySize IS NULL OR partySize BETWEEN 1 AND 20"]
-  schema:
-    type: object
-    additionalProperties: false
-    required: [name, email, requestedFor]
-    properties:
-      name: { type: string, minLength: 1, maxLength: 120 }
-      email: { type: string, format: email }
-      requestedFor: { type: string, description: Requested date, time or slot. }
-      partySize: { type: integer, minimum: 1 }
-      note: { type: string, maxLength: 1000 }
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: View
-metadata: { name: reservation-queue }
-spec:
-  title: Reservation queue
-  surface: staff
-  requires: { auth: { all: [{ ctx.staff: [owner, editor, contributor] }] } }
-  sql: |
-    SELECT id, name, email, requestedFor, partySize, note, created_at
-    FROM reservations
-    ORDER BY created_at DESC LIMIT 50
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Procedure
-metadata: { name: submit-reservation }
-spec:
-  title: Submit reservation
-  description: Ask for a reservation; staff confirm it by hand.
-  input:
-    type: object
-    additionalProperties: false
-    required: [name, email, requestedFor]
-    properties:
-      name: { type: string, minLength: 1, maxLength: 120 }
-      email: { type: string, format: email }
-      requestedFor: { type: string }
-      partySize: { type: integer, minimum: 1 }
-      note: { type: string, maxLength: 1000 }
-  output: { type: object }
-  handler:
-    sql: |
-      INSERT INTO reservations (name, email, requestedFor, partySize, note)
-      VALUES (input.name, input.email, input.requestedFor, input.partySize, input.note)
-      RETURNING id
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Trigger
-metadata: { name: submit-reservation-http }
-spec:
-  source: { kind: http, method: POST, path: /api/reservations }
-  target: { procedure: submit-reservation }
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Trigger
-metadata: { name: submit-reservation-mcp }
-spec:
-  source: { kind: mcp, surface: public }
-  target: { procedure: submit-reservation }
-```
-
-- `requestedFor` is a free string on purpose: the example imposes no calendar
-  model. The queue orders by the native `created_at`, so the newest request is
-  first whatever slot it asks for.
-- An optional input that the caller leaves out binds as `NULL`.
-- `checks` are boolean SQL over the row's own columns, enforced on every insert
-  and update, Admin's included. The input schema already refuses `partySize: 0`;
-  the check also caps the party for writes that do not come through this
-  Procedure.
-
-## Handlers
-
-None.
-
-## Try it
-
-```sh
-curl -sS -X POST http://127.0.0.1:8787/api/reservations \
-  -H 'content-type: application/json' \
-  -d '{"name":"Ada","email":"ada@example.test","requestedFor":"2026-10-03T19:00:00+08:00","partySize":4}'
-```
-
-The answer is `{ "results": [[{ "id": "…" }]] }`. A `partySize` of `0` is
-HTTP 400 `INPUT_VALIDATION_FAILED`; `25` fails the check, also with a 400.
-
-Staff list the queue at `GET /admin/api/views/reservation-queue?limit=50` with
-a staff session. `GET /admin/api/views/reservation-queue/export` returns the
-rows as CSV.
-
-| MCP surface | Tool | From |
-|---|---|---|
-| `/mcp` | `submit_reservation` | the `submit-reservation-mcp` Trigger |
-| `/mcp/staff` | `reservation_queue` | the staff View |
-
-## What this leaves out
-
-A successful `POST` records the request, nothing more.
-
-- **Slot inventory and double booking.** Two requests for one time both
-  succeed. With a `slots` Schema, a capacity column and `checks: ["booked <=
-  capacity"]`, a two-statement Procedure (insert the reservation, then
-  `UPDATE slots SET booked = booked + 1 WHERE id = input.slotId`) refuses the
-  overbooking atomically, as [Commerce inventory](./commerce-inventory.md) does
-  for stock.
-- **Past dates.** Reject them in a `requires.guard` handler, as
-  [Intake with bot check and notification](./intake-hooks.md) does for its
-  token.
-- **Calendar sync, payments and confirmation emails.** An `after_create` hook
-  as in the intake example.
-
-## Source
-
-- [Procedure reference](../handbook/reference/procedure.md)
-- [Schema reference](../handbook/reference/schema.md): `checks`

package/docs/handbook/guides/admin-extensions.md

@@ -1,191 +0,0 @@
----
-description: Add your own pages, settings, actions, record panels and field widgets to Admin in 0.2.0, bind them from manifest uiSchema, and verify them.
----
-# Extend Admin
-
-Manifests decide most of what Admin shows ([Customize Admin from
-manifests](admin-ui.md)). When a project needs UI of its own, it adds an
-**Admin extension**: a declaration that is plain data, server handlers, and
-optionally one ES module with renderers. The contract is
-[ADR-lite 1376](../../adr/adr-lite-1376-admin-extensions.md).
-
-For a new project with feature `admin`, the preset writes
-`src/admin-extensions.ts` (yours to edit) and passes its `adminExtensions` to
-`createAdminSurface`. The preset is written once: when `src/service.ts`
-already exists, `mantle generate` leaves it alone, so add the file and
-`extensions: adminExtensions` to your `createAdminSurface` call yourself.
-
-## What you can add
-
-| Contribution | Where it appears | Client code |
-|---|---|---|
-| `pages` | `/admin/x/{extension}/{page}`; in **More** when it declares `nav` | a renderer |
-| `settings` | `/admin/x/{extension}/{id}`, always in **More** | none: Admin renders a form from `schema`, which must be the form subset (a flat object whose properties are `string`, `number`, `integer` or `boolean`, with `title`, `description`, `default`, `enum`, `oneOf`, `minimum`, `maximum`, `minLength`, `maxLength`) |
-| `actions` | `record/v1` (a record's header), `list.selection/v1` (the bulk bar), `list.toolbar/v1` (a list's toolbar) | none for `run` and `confirm` (a server `run`); a renderer for `dialog` |
-| `panels` | `record.sidebar/v1` (a record's side column), `home/v1` (the home page) | a renderer |
-| `fields` | `field.input/v1` (a form control), `field.cell/v1` (a list cell) | a renderer |
-
-Pages, settings, actions and panels need a minimum staff `role`; a field
-widget's `role` is optional and defaults to `contributor` (below it, Admin's
-own control is used). The server sends each staff member only the
-contributions their role reaches, and checks the session and role again on
-every extension route: hiding a button is never the only guard.
-
-- A settings page and an action are checked against their own `role`.
-- The extension's `api` and its served `source` are shared by all its
-  contributions, so they need only the **lowest** role among them: an owner-only
-  page does not make the `api` owner-only.
-
-Finer rules belong in your handlers, which receive the caller.
-
-## A complete extension
-
-```ts
-// src/admin-extensions.ts
-import type { AdminExtension } from "@aotter/mantle/admin";
-
-const brand: AdminExtension = {
-  apiVersion: 1,
-  id: "brand",
-  title: { en: "Brand", "zh-TW": "品牌" },
-  // Admin serves this at /admin/extensions/brand.js, with its integrity computed
-  source: BRAND_MODULE,
-  contributes: {
-    pages: [{ id: "palette", title: "Palette", role: "editor", nav: { group: "more" } }],
-    settings: [{ id: "defaults", title: "Brand defaults", role: "owner", schema: {
-      type: "object", required: ["accent"],
-      properties: { accent: { type: "string", title: "Accent", enum: ["teal", "navy"] }, limit: { type: "integer", minimum: 1, maximum: 20 } },
-    } }],
-    actions: [{ id: "reindex", title: "Re-index colors", role: "editor", target: "record/v1", presentation: "confirm", when: { schema: ["products"] } }],
-    panels: [{ id: "usage", title: "Where it is used", role: "contributor", target: "record.sidebar/v1", when: { schema: ["products"] } }],
-    fields: [
-      { id: "color", target: "field.input/v1", optionsSchema: { type: "object", properties: { palette: { type: "string", enum: ["brand", "web"] } } } },
-      { id: "swatch", target: "field.cell/v1" },
-    ],
-  },
-  handlers: {
-    settings: { defaults: { load: async () => ({ accent: "teal" }), save: async (_caller, value) => value } },
-    actions: { reindex: { run: async (caller, { record }) => ({ message: `Re-indexed ${record!.id}` }) } },
-    // GET/POST /admin/api/x/brand/api/{path}; null answers 404
-    api: async (request, { caller, path }) => (path === "usage" ? Response.json({ count: 3 }) : null),
-  },
-};
-
-export const adminExtensions: readonly AdminExtension[] = [brand];
-```
-
-`source` is the module's code (or a function returning it). How you load the
-text is up to your host: a string constant, a Wrangler `Text` module rule, or
-Bun's `with { type: "text" }` import. A host that serves the file itself sets
-`module: "/path.js"` (same-origin) and optionally `integrity` instead.
-
-## The module
-
-The module needs no build step. Admin's import map provides `react`,
-`react/jsx-runtime`, `react-dom`, `react-dom/client`,
-`@aotter/mantle-ui/kit` and `@aotter/mantle-ui/extension`, so the module
-uses Admin's own React and kit and looks like the rest of Admin. If you do
-bundle it, mark those specifiers external.
-
-```js
-import { jsx } from "react/jsx-runtime";
-import { useEffect, useState } from "react";
-import { createRoot } from "react-dom/client";
-import { Badge, Input } from "@aotter/mantle-ui/kit";
-import { defineAdminExtension } from "@aotter/mantle-ui/extension";
-
-// a renderer gets an element and a context; it may return a cleanup or { update, unmount }
-const react = (Component) => (element, context) => {
-  const root = createRoot(element);
-  root.render(jsx(Component, { context }));
-  return { update: (next) => root.render(jsx(Component, { context: next })), unmount: () => root.unmount() };
-};
-
-function Usage({ context }) {
-  const [count, setCount] = useState(null);
-  useEffect(() => { fetch(`${context.apiBase}/usage`).then((r) => r.json()).then((b) => setCount(b.count)); }, [context.apiBase]);
-  return jsx(Badge, { children: count === null ? "…" : `${count} pages` });
-}
-function Color({ context }) {
-  return jsx(Input, { "aria-label": context.field.name, value: String(context.field.value ?? ""), onChange: (e) => context.onChange(e.target.value) });
-}
-
-export default defineAdminExtension({
-  pages: { palette: react(() => jsx("p", { children: "Palette" })) },
-  panels: { usage: react(Usage) },
-  fields: {
-    color: react(Color),
-    swatch: (element, context) => { element.textContent = `■ ${context.field.value ?? ""}`; },
-  },
-});
-```
-
-The context holds `extension`, `contribution`, `apiBase` (your `api`
-handler), `language`, `theme`, `caller.role`, and where it applies `record`
-(`{ schema, id, version }`), `selection`, `schema`, `field`, `options` and,
-for `field.input/v1`, `onChange`. `host.navigate(path)`, `host.notify(text)`
-and `host.close()` (a dialog action) are the supported console API. They are
-not a sandbox: a module is trusted same-origin code and can still reach the
-DOM, `fetch` and whatever the signed-in session may do (see Trust).
-
-## Bind contributions from manifests
-
-A manifest's `uiSchema` can name a project contribution as
-`<extension>/<contribution>`. The binding sits next to the field it changes,
-so one change (and one review) covers both:
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v2
-kind: Schema
-metadata: { name: products }
-spec:
-  title: Products
-  lifecycle: operational
-  uiSchema:
-    fields:
-      color: { widget: brand/color, options: { palette: brand } }
-    list:
-      columns: [color]
-      cells: { color: brand/swatch }
-    panels: [brand/usage]
-  schema:
-    type: object
-    required: [name]
-    properties:
-      name: { type: string }
-      color: { type: string }
-```
-
-- `fields.<name>.widget` names a `field.input/v1` contribution (any field type);
-  `options` must satisfy its `optionsSchema`.
-- `list.cells.<field>` (Schemas, and staff Views by output name) names a
-  `field.cell/v1` contribution.
-- `panels` (Schemas) names `record.sidebar/v1` contributions.
-- Procedure `uiSchema.fields.<name>.widget` works like a Schema's.
-
-`mantle generate` checks the shape of the names. `createAdminSurface` checks
-that each named contribution exists, has the right target and accepts its
-`options`, and refuses to start otherwise (`UI_EXTENSION_UNKNOWN`,
-`UI_EXTENSION_TARGET`, `UI_EXTENSION_OPTIONS`). Name only your project's own
-extensions, so the project renders the same locally and deployed; a host that
-adds extensions attaches them with `when`. Core checks that a name exists, not
-whose extension it is. When a manifest names a widget for a field (even
-`textarea`), a matching `when` does not replace it. `uiSchema` stays presentation only: the field's JSON Schema
-still validates whatever a widget sends.
-
-## Trust
-
-An extension's module runs in Admin's origin with the viewer's session. It
-has no more power than the project already has: whoever deploys the project
-already controls its handlers and storage. Keep host routes that act beyond
-this project (an organization console, other projects) on another origin.
-
-## Verify
-
-- `createAdminSurface` validates every declaration at start
-  (`UI_EXTENSION_INVALID` names the first problem).
-- `ADMIN_EXTENSION_JSON_SCHEMA` (from `@aotter/mantle/admin`) describes a
-  declaration for tooling; `diffAdminExtensions(before, after)` lists added,
-  removed and changed contributions for review.
-- Sign in as each role and check what appears; call
-  `/admin/api/x/{extension}/...` as a lower role and expect 403.