@zerotal/arch 1.7.0

package/docs/admin/extending.md

@@ -0,0 +1,205 @@
+---
+title: Admin Custom Pages & Plugins
+description: Add your own pages, and contribute pages or widgets to the panel from a package.
+---
+
+# Custom pages
+
+A resource is the right shape when you're editing rows in a table. When you aren't
+— a settings screen, a report, an ops console — extend `AdminPage` instead. It's a
+Flow component with some extra statics, so `@expose` state, actions and the
+WebSocket round-trip all behave exactly as they do on a resource page.
+
+```ts
+import { AdminPage, Panel } from "@zerotal/admin";
+
+class ReportsPage extends AdminPage {
+  static override slug = "reports";
+  static override title = "Reports";
+  static override navigationIcon = "chart";
+  static override navigationGroup = "Insights";
+  static override ability = "reports.view";
+
+  override async render() {
+    return <div>…</div>;
+  }
+}
+
+Panel.pages(ReportsPage);
+```
+
+The statics drive everything: `slug` becomes the route under the panel path,
+`title` the heading and the sidebar label (override with `navigationLabel`), and
+`ability` decides who sees it. Set `showInNavigation = false` for a page that
+should be reachable but not listed — a drill-in, say — and `routeParams` to hang
+extra segments off the same page, so `routeParams = [":section"]` serves both
+`/admin/reports` and `/admin/reports/revenue`.
+
+## Abilities
+
+Every custom page, contributed widget, nav entry and search provider names an
+ability, and the panel checks it twice: once to decide whether to draw the entry,
+and again in the route guard to decide whether to serve it. Both checks run the
+same resolver, so the sidebar and the router can't drift — what you cannot see,
+you cannot open by typing the URL.
+
+Three things can answer an ability check, in order:
+
+| Source                           | Use it when                                                          |
+| -------------------------------- | -------------------------------------------------------------------- |
+| `authorize` in `config/admin.ts` | The app models permissions itself.                                   |
+| The `gate` binding               | You use `@zerotal/auth` — policies and abilities answer directly.    |
+| Neither                          | Development only. Every ability is denied outside a dev environment. |
+
+That last row is the important one. A panel with no authorization wired stays
+closed in production, the same posture the panel guard already takes, which is
+what makes it safe for a package to add pages without the app asking.
+
+```ts
+// config/admin.ts
+export default {
+  authorize: (ability) => currentUser()?.permissions.includes(ability) ?? false,
+};
+```
+
+Resources are the exception: they authorize through their own
+`Resource.can("viewAny")`, because record-level checks need context an ability
+string can't carry. See [Authorization](/docs/admin/resources#authorization) above.
+
+## Extending the panel from a package
+
+The panel is a **host**. It publishes a write surface, binds it into the container
+as `admin.panel`, and names no contributor at all — so packages add pages, widgets,
+navigation and search results to the admin without the admin knowing they exist,
+and without depending on `@zerotal/admin`.
+
+A contributing provider resolves the binding in its `onBooting` and pushes:
+
+```ts
+// packages/queue/src/admin.ts
+interface AdminHost {
+  enabled(id: string): boolean;
+  page(c: { slug: string; page: unknown; title: string; ability: string }): void;
+}
+
+export function installQueueAdmin(app: Application): void {
+  const panel = app.container.tryMake("admin.panel") as AdminHost | undefined;
+  if (!panel?.enabled("queue")) return;
+  panel.page({ slug: "jobs", page: JobsPage, title: "Jobs", ability: "queue.view" });
+}
+```
+
+Declaring the host's shape locally rather than importing it is the point: the
+package compiles and ships with no dependency on the admin, and an app that runs
+the queue without the panel pulls in nothing extra — the binding simply isn't
+there and the function returns.
+
+This is the same inversion the observability sinks use, so there is one extension
+idiom across the framework rather than a bespoke plugin API here.
+
+### What a package can contribute
+
+| Surface            | Adds                                                    |
+| ------------------ | ------------------------------------------------------- |
+| `console()`        | A tabbed table page with actions, described as data.    |
+| `page()`           | A route under the panel path, plus a sidebar entry.     |
+| `widget()`         | A dashboard widget.                                     |
+| `navItem()`        | A sidebar link to somewhere the panel doesn't mount.    |
+| `searchProvider()` | A source of global-search results beyond the resources. |
+| `topbarSlot()`     | A status pill or control in the top bar.                |
+| `userMenuItem()`   | An entry in the account dropdown.                       |
+
+### Consoles: pages described rather than built
+
+Most packages want the same page — some tables, a few buttons, no bespoke layout.
+`console()` lets a package describe that instead of rendering it, so it needs no
+JSX, no `@zerotal/flow` dependency and no build configuration. The panel owns
+the markup, which also means every console looks like the rest of the admin
+without trying to.
+
+```ts
+panel.console({
+  slug: "jobs",
+  title: "Jobs",
+  ability: "queue.view",
+  navigationBadge: async () => (await Queue.failed()).length || null,
+  tabs: [
+    {
+      key: "failed",
+      label: "Failed",
+      columns: [
+        { key: "id", label: "ID", mono: true },
+        { key: "className", label: "Job" },
+        { key: "error", label: "Error", mono: true, format: firstLine },
+      ],
+      rows: () => Queue.failed(),
+      rowActions: [{ key: "retry", label: "Retry", icon: "undo", run: (row) => retry(row) }],
+      headerActions: [
+        { key: "clear", label: "Clear failed", danger: true, confirm: "Sure?", run: clearAll },
+      ],
+    },
+  ],
+});
+```
+
+An action returns a string to flash on success, or throws to flash an error;
+either way the table re-reads afterwards so it shows what the action just did.
+Tabs carry their own `badge()` count, and the console as a whole can carry a
+`navigationBadge()` that puts a number beside its sidebar entry.
+
+The console's ability is re-checked on every dispatched action, not just when the
+page renders — these are `@expose`d methods reachable from a client frame, so
+drawing the button and running it are separately enforced.
+
+Choose between the two doors on layout, not size: reach for `page()` when the
+page genuinely needs its own component — charts, a custom arrangement, its own
+reactive state — and `console()` for everything that is a table and some buttons.
+
+Contributed pages keep their own class. The panel hosts a subclass carrying its
+layout rather than assigning one onto the class it was handed, so a package that
+also mounts the page in its own standalone panel is unaffected.
+
+### Switching a contributor off
+
+Contributions are automatic — installing both providers is enough. To keep a
+provider installed but drop what it adds to the panel, name it in `plugins`:
+
+```ts
+// config/admin.ts
+export default {
+  plugins: { monitor: false },
+};
+```
+
+This belongs in `config/admin.ts` rather than `app/admin.ts` because it has to be
+in place before contributors ask whether they're enabled, and only the config file
+is read early enough.
+
+### Plugins written by the app
+
+Application code can name the panel directly, so it doesn't need the container
+dance. Group a set of related contributions behind an `AdminPlugin`:
+
+```ts
+await Panel.plugin({
+  id: "billing",
+  install: (panel) => {
+    panel.page({
+      slug: "invoices",
+      page: InvoicesPage,
+      title: "Invoices",
+      ability: "billing.view",
+    });
+    panel.userMenuItem({ label: "Billing", href: "/admin/invoices", ability: "billing.view" });
+  },
+});
+```
+
+Use `Panel.pages()` for a single page, an `AdminPlugin` when a feature adds
+several things at once and you want one switch (`plugins: { billing: false }`) to
+control them together.
+
+## Next steps
+
+- [Admin overview](/docs/admin) — the guide's front page and the rest of the sections.
+- [Reference](/docs/admin/references) — the full API surface in one table.

package/docs/admin/forms.md

@@ -0,0 +1,155 @@
+---
+title: Admin Forms & Infolists
+description: Build create and edit forms, and lay out the read-only view screen.
+---
+
+# Forms
+
+`form()` returns fields (and layout components). An empty `form()` disables
+Create/Edit for the resource.
+
+```ts
+import {
+  textInput, textarea, select, toggle, datePicker, fileUpload, richEditor,
+  formSection, formTabs, formTab, wizard, wizardStep,
+} from "@zerotal/admin";
+
+static form() {
+  return [
+    formSection("Content").columns(2).schema([
+      textInput("title").required().maxLength(160).columnSpan(2),
+      textInput("slug").required()
+        .live().afterStateUpdated((v) => ({ slug: slugify(String(v)) })),
+      select("status").options({ draft: "Draft", published: "Published" }).required(),
+      datePicker("published_at").visible((d) => d.status === "published"),
+    ]),
+    formSection("Body").schema([
+      richEditor("body"),
+      fileUpload("cover").image().disk("covers"),
+    ]),
+  ];
+}
+```
+
+## Field catalogue
+
+| Factory                                                     | Renders                                                                         |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `textInput(k)`                                              | text — plus `.email()/.password()/.numeric()/.url()/.tel()`                     |
+| `textarea(k)`                                               | multi-line text (`.rows(n)`)                                                    |
+| `select(k)`                                                 | select — `.options()/.optionsUsing()/.multiple()/.searchable()/.createOption()` |
+| `checkbox(k)`, `toggle(k)`                                  | boolean                                                                         |
+| `radio(k)`, `checkboxList(k)`                               | single / multi choice                                                           |
+| `datePicker`, `dateTimePicker`, `timePicker`, `colorPicker` | native pickers                                                                  |
+| `tagsInput(k)`                                              | tag/token array                                                                 |
+| `keyValue(k)`                                               | key/value object editor                                                         |
+| `fileUpload(k)`                                             | upload — `.image()/.disk(dir)/.accept(mime)/.multiple()`                        |
+| `slider(k)`                                                 | range → number (`.min()/.max()/.step()`)                                        |
+| `toggleButtons(k)`                                          | segmented buttons (`.multiple()`)                                               |
+| `codeEditor`, `markdownEditor`, `richEditor`                | code / markdown / WYSIWYG editors                                               |
+| `hidden(k)`                                                 | retained-but-hidden value                                                       |
+| `repeater(k)`, `builder(k)`                                 | nested object-arrays (see below)                                                |
+
+A control the catalogue lacks is `customField(k).render(fn)` — see
+[Extending the UI](/docs/admin/extending-ui#custom-renderers).
+
+## Common modifiers
+
+`.label()`, `.placeholder()`, `.helperText()`, `.default(v)`, `.required()`,
+`.minLength()/.maxLength()/.min()/.max()`, `.confirmed()`, `.rule(fn)`,
+`.columnSpan(n)`, `.disabled()`, `.visibleOn("create"|"edit")` / `.hiddenOn(...)`,
+and the reactive `.visible((data) => bool)` / `.disabledWhen((data) => bool)`.
+
+`.live()` re-evaluates dependent fields on change; `.afterStateUpdated((v, data) =>
+patch)` runs server-side and merges a patch into the form (e.g. derive a slug).
+
+## Layout components
+
+| Component                                    | Purpose                                 |
+| -------------------------------------------- | --------------------------------------- |
+| `formSection(heading).columns(n).schema([])` | Titled, multi-column card.              |
+| `formTabs([formTab("X").schema([])])`        | Tabbed groups (client-side switching).  |
+| `wizard([wizardStep("X").schema([])])`       | Stepped form with per-step validation.  |
+| `fieldset(legend)`                           | Bordered `<fieldset>`/`<legend>` group. |
+| `split([sectionA, sectionB])`                | Side-by-side sections.                  |
+| `callout(text).tone().icon().heading()`      | A toned notice block.                   |
+| `prime / primeHtml / primeImage`             | Static text / HTML / image display.     |
+
+## Repeater & Builder
+
+`repeater` edits an array of objects sharing one sub-schema; `builder` edits an array
+of typed blocks. Rows can be added, removed, and reordered.
+
+```ts
+import { repeater, builder, builderBlock, textInput, textarea, fileUpload } from "@zerotal/admin";
+
+repeater("contacts").minItems(1).addActionLabel("Add contact").schema([
+  textInput("name").required(),
+  textInput("email").email(),
+]),
+
+builder("content").blocks([
+  builderBlock("paragraph").schema([textarea("text")]),
+  builderBlock("image").icon("photo").schema([fileUpload("src").image()]),
+]),
+```
+
+Repeaters serialize to `[{ ...fields }]`; builders to `[{ type, data }]`.
+
+## Infolists (View page)
+
+`infolist()` describes the read-only detail page. Omit it to fall back to a section
+derived from `columns()`.
+
+```ts
+import { section, textEntry, iconEntry } from "@zerotal/admin";
+
+static infolist() {
+  return [
+    section("Overview").columns(2).schema([
+      textEntry("title").weight("semibold"),
+      textEntry("status").badge().color((v) => (v === "published" ? "success" : "muted")),
+      textEntry("email").copyable(),
+      textEntry("created_at").since(),
+      textEntry("price").money("USD"),
+      iconEntry("featured").boolean(),
+    ]),
+  ];
+}
+```
+
+### Entry kinds
+
+`textEntry` covers most of a view page. The rest exist because some values are not
+usefully read as text:
+
+| Factory                | Renders                                                                   |
+| ---------------------- | ------------------------------------------------------------------------- |
+| `textEntry(key)`       | A value, with `.badge()`, `.date()`, `.money()`, `.copyable()`, `.url()`. |
+| `iconEntry(key)`       | A check or a cross for a boolean.                                         |
+| `imageEntry(key)`      | An image from a URL — `.circular()`, `.height(px)`.                       |
+| `colorEntry(key)`      | A swatch beside the value.                                                |
+| `codeEntry(key)`       | A monospace block — `.language("json")`.                                  |
+| `keyValueEntry(key)`   | An object as a two-column table of its pairs.                             |
+| `repeatableEntry(key)` | A nested `.schema([…])` rendered once per array item.                     |
+
+`repeatableEntry` is the read side of `repeater`: whatever the form wrote into a
+JSON column, this reads back in the same shape.
+
+```ts
+section("Line items").schema([
+  repeatableEntry("lines")
+    .placeholder("This order has no line items.")
+    .schema([
+      textEntry("sku").label("SKU"),
+      textEntry("description"),
+      textEntry("quantity").label("Qty"),
+      textEntry("unitPrice").label("Unit price").money("USD"),
+    ]),
+]),
+```
+
+## Next steps
+
+- [Admin overview](/docs/admin) — the guide's front page and the rest of the sections.
+- [Reference](/docs/admin/references) — the full API surface in one table.

package/docs/admin/index.md

@@ -0,0 +1,144 @@
+---
+title: Admin Panel
+description: A Filament-style, server-driven admin panel — declare resources as classes and get tables, forms, infolists, actions, relations, dashboards, search, notifications, and auth pages.
+---
+
+# Admin Panel
+
+`@zerotal/admin` is a **Filament-style** admin panel for Zerotal. You describe each
+model with a `Resource` class — its table columns, form fields, infolist entries,
+filters, actions, and relations — and the panel renders fully reactive CRUD pages.
+
+It is **server-driven**: pages are [`@zerotal/flow`](/docs/flow) components and
+the UI is built from [`@zerotal/flow-ui`](/docs/components), so sorting, filtering,
+inline edits, modals, and live notifications all round-trip over Flow's WebSocket
+morph with no client store to maintain. Light + dark mode ship out of the box.
+
+> **Note** — This is the current, class-based admin. The earlier zero-config
+> `Admin.register(Model)` panel has been retired; it remains available in
+> pre-1.1 releases (and on the `admin-legacy` git tag) if you need to reference it.
+
+## Getting Started
+
+```bash
+bun add @zerotal/admin
+```
+
+The panel renders with Flow and flow-ui, and reads/writes through your
+[`@zerotal/orm`](/docs/orm) models. `@zerotal/auth` is an **optional** peer —
+needed only if you enable the built-in auth pages.
+
+## Register the providers
+
+Add `AdminProvider` **after** `FlowProvider` (which installs the `Router.flow()`
+macro and the WebSocket runtime the pages depend on):
+
+```ts
+// bootstrap/providers.ts
+import { FlowProvider } from "@zerotal/flow";
+import { AdminProvider } from "@zerotal/admin";
+
+export default [FlowProvider, AdminProvider];
+```
+
+On boot the provider auto-discovers `app/admin.ts` (where you configure the panel
+and register resources), then mounts the dashboard, search, notifications, and a
+List / View / Create / Edit page per resource under the configured `path`.
+
+## Quick start
+
+```ts
+// app/admin.ts
+import { Panel, Resource, text, textInput } from "@zerotal/admin";
+import { User } from "./models/User.ts";
+
+Panel.configure({ brand: "Acme", path: "/admin" });
+
+class UserResource extends Resource {
+  static model = User;
+  static navigationIcon = "users";
+  static navigationGroup = "Access";
+
+  static columns() {
+    return [
+      text("id").sortable(),
+      text("name").searchable().sortable(),
+      text("email").searchable().copyable(),
+      text("role").badge((v) => (v === "admin" ? "primary" : "muted")),
+      text("created_at").label("Joined").sortable(),
+    ];
+  }
+
+  static form() {
+    return [textInput("name").required().maxLength(120), textInput("email").email().required()];
+  }
+}
+
+Panel.register(UserResource);
+```
+
+Visit `/admin`. You now have a searchable, sortable, paginated table with Create /
+Edit / View / Delete — and the form above on the Create and Edit pages.
+
+> **Danger** — The panel is **unguarded by default** (fine for local exploration).
+> Set `middleware` in your config before shipping; see [Securing the panel](/docs/admin/auth#securing-the-panel).
+
+## Configuration
+
+Configure the panel with `Panel.configure(...)` in `app/admin.ts`, or by exporting
+an `admin` config object the provider merges on boot.
+
+```ts
+Panel.configure({
+  path: "/admin",
+  brand: "Acme",
+  tagline: "Control panel",
+  middleware: [AdminGuard], // guard every panel route
+  userMenu: {
+    // top-bar identity dropdown
+    label: "Jane Doe",
+    items: [
+      { label: "Profile", href: "/admin/profile", icon: "users" },
+      { label: "Sign out", href: "/admin/logout", icon: "logout" },
+    ],
+  },
+  theme: {/* see Theming */},
+  auth: {/* see Auth pages */},
+});
+```
+
+| Field        | Default     | Description                                                            |
+| ------------ | ----------- | ---------------------------------------------------------------------- |
+| `path`       | `"/admin"`  | URL prefix the panel mounts under.                                     |
+| `brand`      | `"Zerotal"` | Sidebar + login heading.                                               |
+| `tagline`    | `"Admin"`   | Small text under the brand.                                            |
+| `middleware` | `[]`        | Middleware guarding every panel route. **Set this before production.** |
+| `userMenu`   | —           | Top-bar dropdown: `{ label?, items: [{ label, href, icon? }] }`.       |
+| `theme`      | CDN         | Styling source — Tailwind Play CDN or a prebuilt stylesheet.           |
+| `auth`       | —           | Built-in login / profile / reset / verify pages.                       |
+| `authorize`  | —           | Decide the abilities pages and contributions name.                     |
+| `plugins`    | `{}`        | Switch contributing packages off by id, e.g. `{ monitor: false }`.     |
+
+## The rest of the guide
+
+| Page                                            | What it covers                                                                   |
+| ----------------------------------------------- | -------------------------------------------------------------------------------- |
+| [Resources](/docs/admin/resources)              | Declare a resource and get list, create, edit, and view screens for a model.     |
+| [Tables](/docs/admin/tables)                    | Columns, filters, sorting, search, and bulk actions on the list screen.          |
+| [Forms & Infolists](/docs/admin/forms)          | Build create and edit forms, and lay out the read-only view screen.              |
+| [Actions & Relations](/docs/admin/actions)      | Row, bulk, and page actions, related-record managers, and soft-delete handling.  |
+| [Panel Structure](/docs/admin/structure)        | Clusters, nested and singular resources, and running more than one panel.        |
+| [Dashboard & Navigation](/docs/admin/dashboard) | Widgets, global search, the command palette, notifications, and the nav tree.    |
+| [Extending the UI](/docs/admin/extending-ui)    | Custom cells and controls, render hooks, custom data sources, table layouts.     |
+| [Operations](/docs/admin/operations)            | History, impersonation, saved views, media, roles, and per-user dashboards.      |
+| [Custom Pages & Plugins](/docs/admin/extending) | Add your own pages, and contribute pages or widgets to the panel from a package. |
+| [Auth Pages & Theming](/docs/admin/auth)        | The built-in login and profile screens, and how to restyle the panel.            |
+| [Testing the Admin Panel](/docs/admin/testing)  | Drive panel screens in tests and assert on what they render.                     |
+| [References](/docs/admin/references)            | Every resource, table, form, and action API in one table.                        |
+
+## Next steps
+
+- [Flow](/docs/flow) — the reactivity layer the pages are built on.
+- [Components](/docs/components) — the flow-ui kit the panel renders with.
+- [ORM](/docs/orm) — the models, relations, and soft-deletes the panel reads.
+- [Authentication](/docs/authentication) / [Authorization](/docs/authorization) — the auth pages and `can()` policies.