@zerotal/arch 1.7.0

package/docs/admin/operations.md

@@ -0,0 +1,224 @@
+---
+title: Operations
+description: The features a panel grows once real people use it daily — record history, impersonation, saved views, the media library, roles and permissions, and a dashboard each person arranges.
+---
+
+# Operations
+
+Everything in the rest of this guide is about getting a panel to show your data. This
+page is about the things people start asking for once they use it every day: who
+changed that, why can't this person see the thing they say they see, why do I have to
+set up the same filters every morning.
+
+| Somebody asks                                      | Reach for                                               |
+| -------------------------------------------------- | ------------------------------------------------------- |
+| "Who changed this price, and can we put it back?"  | [Record history](#record-history)                       |
+| "The customer says the button is missing"          | [Impersonation](#impersonation)                         |
+| "I set these filters up every single morning"      | [Saved views](#saved-views)                             |
+| "Where did that logo go? I uploaded it last week"  | [The media library](#the-media-library)                 |
+| "Can support see orders but not delete them?"      | [Roles and permissions](#roles-and-permissions)         |
+| "I don't care about revenue, I care about tickets" | [A dashboard per person](#a-dashboard-per-person)       |
+| "I edited it and my changes vanished"              | [Record locking](#record-locking)                       |
+| "Am I on production right now?"                    | [The environment indicator](#the-environment-indicator) |
+
+Most of these need somewhere to keep something, and where that is depends on your
+app rather than on the panel. So each takes a small provider you supply, and none of
+them appears in the UI until you do — a panel with nothing configured looks exactly
+as it does today.
+
+## Record history
+
+Turn it on per resource:
+
+```ts
+export class ProductResource extends Resource {
+  static override history = true;
+}
+```
+
+The view page grows a History card listing what changed, when, and by whom, with a
+Revert button on each entry that can be undone. It reads from `@zerotal/audit`, so
+you need that package recording the model — the panel does not keep a second trail of
+its own, which would only be a second thing to disagree with the first.
+
+Reverting restores the previous values of the fields that entry changed, not the whole
+record as it was. That distinction matters: reverting a price change from three weeks
+ago should not also undo the description somebody fixed yesterday.
+
+## Impersonation
+
+The support request nobody can reproduce is usually solved by seeing what the person
+actually sees.
+
+```ts
+export class UserResource extends Resource {
+  static override impersonatable = true;
+
+  static override can(ability: string, record?: AdminRecord): boolean {
+    if (ability !== "impersonate") return true;
+    // Nobody impersonates an administrator — otherwise this is a way to
+    // acquire more access than you have.
+    return !((record?.roles as string[]) ?? []).includes("admin");
+  }
+}
+```
+
+Add `impersonateAction()` to the resource's row actions and the panel handles the
+rest: it remembers who started the impersonation in the session, shows an amber banner
+across the top while it is going on, and offers one link back. The original user is
+remembered in the session rather than derived from the impersonated account, so
+returning always works even if the account you switched into is broken.
+
+Two rules are enforced rather than suggested. Impersonation never nests — a second one
+on top of a first makes "stop" ambiguous, so it is refused. And `can("impersonate")`
+decides per record, defaulting to refusing.
+
+## Saved views
+
+Every bit of list state already lives in the URL: search, filters, tab, sort, column
+visibility, grouping, page size. So a saved view is a saved query string, and
+restoring one is a link.
+
+```ts
+Panel.savedViews({
+  async list(resource) {
+    /* … */
+  },
+  async save(view) {
+    /* … */
+  },
+  async remove(id) {
+    /* … */
+  },
+});
+```
+
+A Views control then appears above every list, with a name box for saving the current
+one. Page number is deliberately excluded from what a view stores: a view should
+restore how a list was _shaped_, not which page of it somebody happened to be on.
+
+## The media library
+
+A file upload field puts a file somewhere and stores a path. That works until the same
+logo is needed on twenty products, or somebody wants to know what is still pointing at
+a file before deleting it.
+
+```ts
+import { databaseMedia, mediaPicker } from "@zerotal/admin";
+
+Panel.media(databaseMedia());
+```
+
+`databaseMedia()` expects a table with `path`, `name`, `mime`, `size`, `alt`, `folder`
+and `uploaded_at`; the column names are adjustable, so an existing table usually needs
+no migration. Supply your own `{ list, save, remove }` if the catalogue belongs
+somewhere else.
+
+Configured, the panel gains a Media page — a grid with upload, search, folder
+filtering, alt-text editing and deletion — and forms can use the picker:
+
+```ts
+mediaPicker("imageUrl").label("Image");
+```
+
+which offers the library in a modal, with upload-and-select in the same dialog.
+
+The split between the two halves is deliberate. `zerotal/storage` holds the bytes;
+the catalogue holds the record of them. Listing a bucket is not a substitute, because
+it cannot tell you alt text, who uploaded something, or what it is for — and on a
+large disk it is slow besides.
+
+## Roles and permissions
+
+Authorization already works without a UI: a resource's `can()` answers every question
+the panel asks. What is missing is the other direction — seeing who can do what, and
+changing it, without editing code.
+
+```ts
+import { authRoles } from "@zerotal/admin";
+
+Panel.roles(authRoles({ superusers: ["admin"] }));
+```
+
+`authRoles()` drives the role-based access control in `@zerotal/auth`, so the matrix
+edits the same roles and permissions the app already checks against — ticking a box
+makes a real check start passing. Supply your own `{ list, permissionsFor,
+setPermissions }` if roles live elsewhere.
+
+The permission catalogue is derived, not declared. The panel walks its registered
+resources, pages and actions and reports every ability it actually checks:
+`products.viewAny`, `products.delete`, the soft-delete abilities where the model has
+them, and every custom action's key. A hand-maintained list drifts the moment somebody
+adds a resource, and a matrix missing a row is worse than no matrix, because it
+quietly implies the permission does not exist.
+
+A role named as a superuser is shown holding everything and cannot be edited or
+deleted from the panel. That is worth modelling explicitly rather than by ticking
+every box, so an administrator does not silently lose access to a resource added next
+week.
+
+## A dashboard per person
+
+What belongs at the top of a dashboard differs by role, and neither the finance lead
+nor support wants to scroll past the other's widget every morning.
+
+```ts
+Panel.dashboardLayout({
+  async load() {
+    return Auth.user()?.dashboard ?? null;
+  },
+  async save(layout) {
+    await Auth.user()?.update({ dashboard: layout });
+  },
+});
+```
+
+An Arrange control appears on the dashboard, with move-up, move-down and hide per
+widget, and a Reset that puts it back the way the app declares it. Name your widgets
+with `.key("revenue")` if their titles might change — a layout keyed by title silently
+resets the moment somebody rewords a heading.
+
+This is order and visibility, not a drag-around canvas. Dragging boxes on a grid is a
+lot of machinery to maintain and mostly produces layouts that break at the next screen
+width; reordering and hiding covers what people actually ask for and stays responsive
+by construction.
+
+The declaration stays the source of truth for _which_ widgets exist. A widget added
+since somebody last arranged their dashboard appears at the end, where it is
+noticeable rather than lost, and a widget since removed does not come back because a
+stale key mentions it.
+
+## Record locking
+
+Two people editing the same record is normal; one of them losing their work silently
+is not.
+
+```ts
+export class ProductResource extends Resource {
+  static override optimisticLock = "version";
+}
+```
+
+The form remembers the version it loaded, and a save against a stale one is refused
+with a field error rather than going through. Refusing is the only safe answer here:
+overwriting loses somebody's work, and merging blind is worse.
+
+## The environment indicator
+
+The expensive mistake is editing production believing it is staging.
+
+```ts
+import { environmentIndicator } from "@zerotal/admin";
+
+Panel.renderHook("body.start", environmentIndicator());
+```
+
+A coloured strip across the top names the environment — red for production, amber for
+staging. It returns nothing in local development, so registering it unconditionally is
+the intended usage; there is nothing to switch off per environment.
+
+## Next steps
+
+- [Panel Structure](/docs/admin/structure) — clusters, nested resources, multiple panels.
+- [Extending the UI](/docs/admin/extending-ui) — render hooks, custom cells, table layouts.
+- [Reference](/docs/admin/references) — the full API surface in one table.

package/docs/admin/references.md

@@ -0,0 +1,174 @@
+---
+title: Admin References
+description: Every resource, table, form, and action API in one table.
+---
+
+# References
+
+## `Panel`
+
+| Method                                   | Description                                       |
+| ---------------------------------------- | ------------------------------------------------- |
+| `Panel.configure(config)`                | Merge panel configuration.                        |
+| `Panel.register(...resources)`           | Register one or more `Resource` classes.          |
+| `Panel.pages(...pages)`                  | Register `AdminPage` subclasses.                  |
+| `Panel.plugin(...plugins)`               | Install app-authored plugins.                     |
+| `Panel.widgets(...widgets)`              | Register dashboard widgets.                       |
+| `Panel.notifications(provider)`          | Wire the notification center.                     |
+| `Panel.auth(config)`                     | Enable + configure the auth pages.                |
+| `Panel.can(ability)`                     | Resolve an ability the way the panel does.        |
+| `Panel.host()`                           | The contribution surface, bound as `admin.panel`. |
+| `Panel.resources()` / `find(slug)`       | Inspect the resource registry.                    |
+| `Panel.registeredPages()` / `findPage()` | Inspect the page registry.                        |
+| `Panel.navigation()`                     | The full sidebar map, unfiltered.                 |
+| `Panel.visibleNavigation()`              | The sidebar as the current user may see it.       |
+| `Panel.make(id, config)`                 | Create an additional panel on its own path.       |
+| `Panel.get(id)` / `Panel.all()`          | Inspect the panel registry.                       |
+| `Panel.default()`                        | The panel every app starts with.                  |
+| `Panel.current()`                        | The panel owning the request being served.        |
+| `Panel.renderHook(name, fn)`             | Render into a named position in the chrome.       |
+| `Panel.renderHooks(name)`                | The hooks registered at a position.               |
+
+## `Resource` statics
+
+`model`, `slug`, `label`, `pluralLabel`, `primaryKey`, `perPage`, `defaultSort`,
+`eager`, `recordTitleAttribute`, `navigationIcon`, `navigationGroup`,
+`navigationSort`, `navigationParentItem`, `navigationBadgeColor`, `reorderable`,
+`defaultGroup`, `cluster`, `parent`, `singular`, `tableLayout`, `striped`,
+`stickyHeader`, `density`, `filterLayout` — plus the methods `columns()`,
+`form()`, `infolist()`, `filters()`, `tabs()`, `groups()`, `relations()`,
+`recordActions()`, `headerActions()`, `bulkActions()`, `navigationBadge()`,
+`emptyState()`, `widgets()`, `data()`, `can()`, and the lifecycle hooks above.
+
+Each resource also builds its own URLs — `indexUrl(base)`, `recordUrl(base, id)`,
+`createUrl(base)`, `editUrl(base, id)` and `routePath()`. Link through these rather
+than assembling paths by hand, and a resource can move into a cluster or under a
+parent without anything else changing.
+
+## Generator
+
+```bash
+bun zt make:admin-resource Product
+bun zt make:admin-resource Comment --parent=Post --foreign-key=post_id
+bun zt make:admin-resource Setting --singular
+bun zt make:admin-resource Order --cluster=ShopCluster
+```
+
+Writes `app/admin/<Name>Resource.ts`. Named `make:admin-resource` because
+`make:resource` already belongs to the API transformer generator.
+
+## Configuration and middleware
+
+| Export                   | Signature                                                   | Description                                                                              |
+| ------------------------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `AdminConfig`            | `(options?: Partial<AdminConfigShape>) => AdminConfigShape` | Build `config/admin.ts` with defaults filled in, the same shape `Panel.configure` takes. |
+| `AdminGuardMiddleware`   | middleware class                                            | Gates every panel route behind the configured auth check.                                |
+| `AdminAbilityMiddleware` | middleware class                                            | Enforces the resolved ability for the route being served.                                |
+| `adminHead`              | `(title?, theme?) => string`                                | The panel shell's `<head>` markup, for use as `Layout.head` in a custom layout.          |
+
+## Row and bulk actions
+
+The [Actions guide](/docs/admin/actions) covers `createAction`, `editAction`,
+`viewAction`, `deleteAction`, `replicateAction`, `importAction`, `exportAction` and
+`impersonateAction`. The rest of the built-ins:
+
+| Export                  | Signature                 | Description                                                                 |
+| ----------------------- | ------------------------- | --------------------------------------------------------------------------- |
+| `restoreAction`         | `() => Action`            | Restore a soft-deleted record. Pair with `Model.using(SoftDeletes)`.        |
+| `forceDeleteAction`     | `() => Action`            | Permanently delete a soft-deleted record, bypassing the trash.              |
+| `bulkEditAction`        | `(fields?: string[])`     | Edit the named fields across every selected record in one form.             |
+| `bulkRestoreAction`     | `() => Action`            | Restore every selected soft-deleted record.                                 |
+| `bulkForceDeleteAction` | `() => Action`            | Permanently delete every selected record.                                   |
+| `textFilter`            | `(key: string) => Filter` | A free-text filter on one column, alongside `selectFilter`/`ternaryFilter`. |
+
+`RelationManager` is the base class a resource's `relations()` returns; see
+[Actions & Relations](/docs/admin/actions).
+
+## Impersonation
+
+Backing the `impersonateAction` button, for wiring it into your own UI. Each returns
+a `[true]` / `[false, reason]` pair rather than throwing, so a refusal is a value you
+can render.
+
+| Export               | Signature                                        | Description                                         |
+| -------------------- | ------------------------------------------------ | --------------------------------------------------- |
+| `startImpersonating` | `(userId) => Promise<[true] \| [false, string]>` | Become another user, remembering the original.      |
+| `stopImpersonating`  | `() => Promise<[true] \| [false, string]>`       | Return to the original user.                        |
+| `isImpersonating`    | `() => Promise<boolean>`                         | Whether the session is currently impersonating.     |
+| `impersonatedName`   | `() => Promise<string \| null>`                  | The impersonated user's display name, for a banner. |
+
+## Media
+
+The pieces behind `mediaPicker` and the media library, for driving uploads yourself.
+
+| Export            | Signature                                                           | Description                                                |
+| ----------------- | ------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `storeMedia`      | `(file, options) => Promise<[true, MediaItem] \| [false, string]>`  | Store an upload and record it against the provider.        |
+| `deleteMedia`     | `(item, { provider, disk? }) => Promise<[true] \| [false, string]>` | Remove a stored item and its record.                       |
+| `mediaUrl`        | `(item, disk?) => Promise<string \| null>`                          | A browser-fetchable URL, signed when the disk requires it. |
+| `mediaPath`       | `(name, folder?) => string`                                         | The storage path a given file name resolves to.            |
+| `resolveMediaSrc` | `(value, disk?) => string \| null`                                  | Turn a stored field value into an `src`, or `null`.        |
+| `formatSize`      | `(bytes: number) => string`                                         | Human file size — `1.4 MB`.                                |
+| `databaseMedia`   | provider                                                            | The built-in provider storing media rows in your database. |
+
+## Import and export
+
+| Export             | Signature                                                        | Description                                                                       |
+| ------------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `importCsv`        | `(resource, csv, mapping?, { limit? }) => Promise<ImportResult>` | Import rows into a resource, honouring the column mapping.                        |
+| `parseCsv`         | `(text) => string[][]`                                           | Parse CSV text into rows of cells.                                                |
+| `toCsv`            | `(rows, columns) => string`                                      | Render rows as CSV using a resource's columns.                                    |
+| `toXlsx`           | `(rows, columns, { sheet? }) => Uint8Array`                      | Render rows as a spreadsheet.                                                     |
+| `dispatchImport`   | `(payload) => Promise<boolean>`                                  | Queue an import; `false` when no queue is bound, so the caller can run it inline. |
+| `runQueuedImport`  | `(payload) => Promise<ImportResult>`                             | Run a queued import — exported so an app can drive it from its own job class.     |
+| `ImportRecordsJob` | job class                                                        | The built-in job `dispatchImport` enqueues.                                       |
+
+## Builder classes
+
+You build these through their factories rather than constructing them; the class
+names matter only when you want to annotate a variable or a return type.
+
+| Class           | Built by                                                                                                  |
+| --------------- | --------------------------------------------------------------------------------------------------------- |
+| `Constraint`    | `textConstraint()`, `numberConstraint()`, `dateConstraint()`, `selectConstraint()`, `booleanConstraint()` |
+| `FormSplit`     | `split(sections)` — side-by-side form sections                                                            |
+| `Prime`         | `prime(text)`, `primeHtml(html)`, `primeImage(src)` — static display blocks in a schema                   |
+| `PanelInstance` | `Panel.make(id, config)`, `Panel.get(id)`, `Panel.current()`                                              |
+
+The same holds for `Section`, `Tab`, `FormSection`, `FormTab`, `FormTabs`, `Wizard`,
+`WizardStep`, `Stat`, `Callout`, `ActionGroup`, `BuilderBlock`, and the dashboard
+widgets `StatsWidget`, `ChartWidget` and `TableWidget` — each is the return type of
+the like-named factory documented in its own guide.
+
+## History and permissions
+
+| Export             | Signature                                | Description                                                                                        |
+| ------------------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `recordHistory`    | `(options) => Promise<HistoryEntry[]>`   | A record's audit history, newest first; empty rather than throwing when the audit table is absent. |
+| `panelPermissions` | `(panel: PanelInstance) => Permission[]` | Every permission a panel checks, derived from what it has registered — use it to seed roles.       |
+| `roleHas`          | `(role, held: string) => boolean`        | Whether a role holds a permission; a superuser holds everything by definition.                     |
+| `authRoles`        | roles helper                             | The role set the auth pages recognise.                                                             |
+
+## Subpaths
+
+| Import                   | Contents                                               |
+| ------------------------ | ------------------------------------------------------ |
+| `@zerotal/admin`         | Resources, columns, fields, actions, widgets, `Panel`. |
+| `@zerotal/admin/auth`    | The opt-in auth page classes + `registerAuthRoutes`.   |
+| `@zerotal/admin/testing` | `AdminTest` + the assertion helpers.                   |
+
+## Deliberately deferred
+
+Multi-tenancy and the 2FA challenge step are intentionally out of scope for now.
+
+Everything else once listed here has landed: [clusters, nested and singular
+resources, and multiple panels](/docs/admin/structure); [CSV and spreadsheet import
+and export](/docs/admin/actions); the [visual query-builder
+filter](/docs/admin/tables); [kanban, calendar and tree layouts, header filters and
+translations](/docs/admin/extending-ui); and [record history, impersonation, saved
+views, the media library, roles and per-user
+dashboards](/docs/admin/operations).
+
+## Next steps
+
+- [Admin overview](/docs/admin) — the guide's front page and the rest of the sections.

package/docs/admin/resources.md

@@ -0,0 +1,132 @@
+---
+title: Admin Resources
+description: Declare a resource and get list, create, edit, and view screens for a model.
+---
+
+# Resources
+
+A `Resource` is a `static`-only class describing one model. Override the statics and
+methods you need; everything has a sensible default.
+
+Nothing instantiates a resource — the class itself is the configuration, read by the
+panel when it builds a screen. That is why every member is `static`, and why a
+resource can be imported and inspected anywhere without constructing anything.
+
+Scaffold one with the generator, which writes `app/admin/<Name>Resource.ts`:
+
+```bash
+bun zt make:admin-resource Post
+```
+
+```ts
+class PostResource extends Resource {
+  static model = Post;
+
+  // Navigation
+  static navigationIcon = "document";
+  static navigationGroup = "Content";
+  static navigationSort = 10;
+  static navigationParentItem = "Blog"; // nest under another item's label
+  static navigationBadgeColor = "primary";
+
+  // Identity & data
+  static slug = "posts"; // default: kebab-cased plural
+  static label = "Post"; // default: from model name
+  static pluralLabel = "Posts";
+  static primaryKey = "id";
+  static perPage = 15;
+  static defaultSort = { column: "created_at", direction: "desc" };
+  static eager = ["author"]; // relations to eager-load
+  static recordTitleAttribute = "title"; // used by search / breadcrumbs
+
+  // A live count badge in the sidebar
+  static async navigationBadge() {
+    return this.count((q) => q.where("status", "draft"));
+  }
+
+  static columns() {
+    /* … */ return [];
+  }
+  static form() {
+    /* … */ return [];
+  }
+  static infolist() {
+    /* … */ return [];
+  }
+  static filters() {
+    /* … */ return [];
+  }
+  static tabs() {
+    /* … */ return [];
+  }
+  static groups() {
+    /* … */ return [];
+  }
+  static relations() {
+    /* … */ return [];
+  }
+}
+```
+
+A resource does nothing until the panel knows about it. Register it where the panel
+is configured:
+
+```ts
+Panel.register(PostResource);
+```
+
+Three of the statics are load-bearing in ways worth calling out. `slug` becomes the
+URL segment, so changing it changes every link to the resource — set it once and
+leave it alone. `eager` is the cure for a list page issuing one query per row: name
+the relations your columns read and they are loaded up front.
+`recordTitleAttribute` decides how a record names itself in breadcrumbs, global
+search results, and relation pickers, so a resource without a meaningful one stays
+hard to navigate even when every screen renders correctly.
+
+Rather than assembling URLs by hand, ask the resource: `indexUrl(base)`,
+`recordUrl(base, id)`, `createUrl(base)`, `editUrl(base, id)` and `routePath()`
+build them for you, so a resource can move under a parent or into a cluster without
+any of its links changing.
+
+## Authorization
+
+Override `can(ability, record?)` to gate the built-in actions. Abilities used by the
+presets: `create`, `update`, `delete`, `restore`, `forceDelete`.
+
+```ts
+static can(ability: string, record?: AdminRecord) {
+  return Gate.allows(ability, record ?? this.model);
+}
+```
+
+Delegating to `Gate` is usually the whole implementation, and it is the reason to
+write policies once rather than per screen: the same rule then governs the list
+page's row actions, the form's save button, and the bulk actions without being
+restated in each. A denied ability hides the control rather than merely rejecting
+the request, so the panel never offers a button that cannot work.
+
+## Lifecycle hooks
+
+| Hook                             | When                                                     |
+| -------------------------------- | -------------------------------------------------------- |
+| `mutateFormDataBeforeFill(data)` | Transform a record into form state before Edit fills.    |
+| `mutateBeforeSave(data, mode)`   | Transform validated form data just before create/update. |
+| `afterSave(record, mode)`        | After a successful create/update (e.g. sync relations).  |
+
+The first two are mirror images, and implementing them as a pair is what keeps a
+field stored differently from how it is edited working in both directions —
+splitting a stored `fullName` into two inputs on fill, rejoining them on save.
+
+`mutateBeforeSave` runs _after_ validation, so its input is already valid and its
+job is to shape data rather than sanitise it. `afterSave` receives the persisted
+record, which is the moment to sync related rows: the record has an id by then,
+including on create.
+
+Both save hooks receive the `mode`, so one implementation can branch on `"create"`
+versus `"edit"` instead of duplicating the resource.
+
+## Next steps
+
+- [Admin overview](/docs/admin) — the guide's front page and the rest of the sections.
+- [Tables](/docs/admin/tables) — the columns, filters, and tabs declared above.
+- [Forms & Infolists](/docs/admin/forms) — the fields the save hooks operate on.