@zerotal/arch 1.7.0

package/docs/admin/structure.md

@@ -0,0 +1,158 @@
+---
+title: Panel Structure
+description: Group resources into clusters, nest one resource under another's records, back a single row, and run more than one panel from a single app.
+---
+
+# Panel Structure
+
+A panel with six resources needs no structure at all: register them and the sidebar
+reads fine. Past that it starts to matter, and four tools cover almost every shape a
+real back office takes.
+
+| You have                                              | Reach for                                 |
+| ----------------------------------------------------- | ----------------------------------------- |
+| Too many resources for one sidebar list               | [Clusters](#clusters)                     |
+| Records that only make sense inside a parent          | [Nested resources](#nested-resources)     |
+| Exactly one row — settings, a company profile         | [Singular resources](#singular-resources) |
+| Two audiences who should not see each other's screens | [Multiple panels](#multiple-panels)       |
+
+## Clusters
+
+A cluster gives a group of resources a shared URL segment and a single sidebar
+entry. Declare one, then point resources at it:
+
+```ts
+import { Cluster } from "@zerotal/admin";
+
+export class ShopCluster extends Cluster {
+  static override slug = "shop";
+  static override title = "Shop";
+  static override navigationIcon = "collection";
+}
+
+export class ProductResource extends Resource {
+  static override model = Product;
+  static override cluster = ShopCluster; // → /admin/shop/products
+}
+```
+
+Members collapse under one expandable entry rather than sitting loose in the
+sidebar, and every URL the panel builds — links, redirects, breadcrumbs — picks up
+the cluster segment on its own. Nothing in a resource needs to know its own path.
+
+A cluster's `ability` gates the whole section:
+
+```ts
+export class FinanceCluster extends Cluster {
+  static override slug = "finance";
+  static override title = "Finance";
+  static override ability = "finance.view";
+}
+```
+
+Every member route enforces it, so no resource has to restate the check. Custom
+pages join a cluster the same way, with `static cluster = FinanceCluster`.
+
+## Nested resources
+
+Some records have no meaning apart from their parent. Comments belong to a post;
+there is no useful screen listing every comment in the database. Declare the
+parent and the resource moves inside it:
+
+```ts
+export class CommentResource extends Resource {
+  static override model = Comment;
+  static override parent = { resource: () => PostResource, foreignKey: "post_id" };
+}
+```
+
+That gives you `/admin/posts/7/comments`, and three things follow automatically:
+
+- **Every list is scoped to the parent.** The scope is applied before any tab or
+  filter, so nothing a user selects can widen the query past their parent record.
+- **New records inherit the foreign key** from the URL rather than from a form
+  field, so it cannot be tampered with on the way to the server.
+- **The resource leaves the sidebar,** because there is no parent-free URL to
+  link to. It is reached through the parent's own pages.
+
+The parent is named by a **function**, not a direct reference. The two resources
+almost always point at each other — the parent lists the child as a relation, the
+child names the parent here — and a direct reference would resolve to `undefined`
+on whichever side of the import cycle evaluated first.
+
+When the parent declares the child with `hasMany`, its view page links into the
+nested pages instead of rendering an inline table:
+
+```ts
+export class PostResource extends Resource {
+  static override relations() {
+    return [hasMany(CommentResource, "post_id").title("Comments")];
+  }
+}
+```
+
+## Singular resources
+
+Site settings are one row. A list of one, with a view page and an edit page behind
+it, is three screens too many:
+
+```ts
+export class SettingsResource extends Resource {
+  static override model = Setting;
+  static override singular = true;
+  static override slug = "settings";
+
+  static override form() {
+    return [
+      formSection("Identity").schema([
+        textInput("siteName").required(),
+        toggle("ordersOpen").label("Accepting orders"),
+      ]),
+    ];
+  }
+}
+```
+
+`/admin/settings` opens the form directly. There is no list, no create page and no
+id in the URL. The row is resolved on first visit and created from the form's
+defaults if it does not exist yet, so a fresh install has something to edit rather
+than an error.
+
+## Multiple panels
+
+Most applications have one panel, and `Panel.configure(...)` / `Panel.register(...)`
+write to it. When a second audience needs a second set of screens, make another:
+
+```ts
+// The back office — everything.
+Panel.configure({ brand: "Acme", path: "/admin", middleware: [AuthMiddleware] });
+Panel.register(ProductResource, OrderResource, UserResource);
+
+// A read-only console for the wider team.
+const console = Panel.make("console", {
+  brand: "Acme Console",
+  path: "/app",
+  middleware: [AuthMiddleware],
+});
+console.register(TeamPostResource);
+```
+
+Each panel owns its resources, pages, widgets, guard, branding and URL prefix.
+Neither can see the other's registrations, so the same model can appear in both
+under different resources — a full CRUD resource in one, a read-only one in the
+other. That is a better answer than one resource with half its buttons hidden,
+because the second panel simply never mounts the routes it should not have.
+
+Give each panel a distinct path; two panels sharing a prefix cannot be told apart
+from a URL. Where they nest, the longest match wins, so `/admin/billing` can be its
+own panel inside `/admin`.
+
+Sharing a sign-in is the common case — one identity, two sets of screens — so
+point both at the same guard.
+
+## Next steps
+
+- [Resources](/docs/admin/resources) — what a resource declares.
+- [Tables](/docs/admin/tables) — columns, filters and the query builder.
+- [Custom Pages & Plugins](/docs/admin/extending) — pages that aren't a model.
+- [References](/docs/admin/references) — the full API surface in one table.

package/docs/admin/tables.md

@@ -0,0 +1,185 @@
+---
+title: Admin Tables
+description: Columns, filters, sorting, search, and bulk actions on the list screen.
+---
+
+# Tables
+
+`columns()` returns `Column`s built with `text(key)` plus chainable modifiers.
+
+```ts
+static columns() {
+  return [
+    text("title").label("Title").sortable().searchable(),
+    text("status").badge((v) => (v === "published" ? "success" : "muted")),
+    text("views").align("end").sum("Total views"),
+    text("created_at").label("Created").since().sortable(),
+  ];
+}
+```
+
+## Column kinds & modifiers
+
+| Modifier / factory                      | Effect                                                  |
+| --------------------------------------- | ------------------------------------------------------- |
+| `.label(text)`                          | Header label (defaults to a title-cased key).           |
+| `.sortable()`                           | Clickable, URL-driven sort header.                      |
+| `.searchable()`                         | Include in the table's search box.                      |
+| `.align("start" \| "center" \| "end")`  | Cell alignment.                                         |
+| `.format((v, row) => string)`           | Custom value formatter.                                 |
+| `.badge((v, row) => tone \| null)`      | Render as a colored pill.                               |
+| `.copyable()`                           | Copy-to-clipboard affordance.                           |
+| `toggleColumn(key)` / `.toggle()`       | Inline boolean toggle — writes on click.                |
+| `selectColumn(key, options)`            | Inline select — saves the chosen value on change.       |
+| `textInputColumn(key)` / `.editText()`  | Inline text input — saves on change/blur.               |
+| `imageColumn(key)` / `.circular()`      | Image / avatar cell.                                    |
+| `colorColumn(key)`, `iconColumn(key)`   | Color swatch, boolean check/cross icon.                 |
+| `.sum() / .avg() / .count() / .range()` | Column **summaries** (see below). Or `.summarize([…])`. |
+
+## Summaries
+
+`.sum()`, `.avg()`, `.count()`, `.range()` (each takes an optional label and number
+formatter) render a `<tfoot>` total computed over the **full filtered dataset**, plus
+per-group subtotals when grouping is active.
+
+```ts
+text("amount").align("end").sum("Revenue", (n) => `$${n.toFixed(2)}`),
+text("id").count("Orders"),
+```
+
+## Filters
+
+```ts
+import { selectFilter, ternaryFilter } from "@zerotal/admin";
+
+static filters() {
+  return [
+    selectFilter("status").options({ draft: "Draft", published: "Published" }),
+    ternaryFilter("featured").labels("Featured", "Standard"),
+    // custom query:
+    selectFilter("author").options(authorMap).query((q, v) => q.where("author_id", v)),
+  ];
+}
+```
+
+Filters are URL-driven and compose with tabs, search, sort, and pagination.
+
+## The query builder
+
+Fixed filters work when you can name the useful questions in advance. A catalogue
+or a ledger is queried in too many ways for that, so `queryBuilder` lets the user
+stack their own comparisons and nest AND/OR groups:
+
+```ts
+import {
+  queryBuilder, textConstraint, numberConstraint,
+  selectConstraint, booleanConstraint, dateConstraint,
+} from "@zerotal/admin";
+
+static filters() {
+  return [
+    queryBuilder("q").label("Advanced filter").constraints([
+      textConstraint("name"),
+      numberConstraint("price").label("Price (cents)"),
+      dateConstraint("created_at").label("Created"),
+      selectConstraint("status").options({ draft: "Draft", active: "Active" }),
+      booleanConstraint("featured"),
+    ]),
+  ];
+}
+```
+
+You declare **what may be compared**; the panel supplies the operators each kind
+deserves — `contains` / `starts with` / `is empty` for text, `is at least` / `is
+before` for numbers and dates — and turns the result into predicates.
+
+Two things are worth knowing about how it applies:
+
+- **The whole tree is wrapped in one group.** An `OR` inside a rule can never
+  break out and widen a scope the page already applied: a tab, a parent record, a
+  soft-delete filter. The tree narrows; it cannot escape.
+- **A rule naming a constraint you never declared is dropped.** The active tree
+  travels in the URL, so it is user input; only the columns you listed are
+  reachable, and a hand-edited URL cannot filter on a password hash.
+
+Groups nest as deep as the question needs — a group inside a group inside a
+group — and the whole tree lives in the same `?filters=` parameter as everything
+else, so it composes with tabs, search, sort and pagination. A narrowed view is a
+link someone can send to a colleague.
+
+## Tabs
+
+`tab(key)` adds quick-filter tabs above the table, each scoping the query and
+optionally showing a count badge.
+
+```ts
+import { tab } from "@zerotal/admin";
+
+static tabs() {
+  return [
+    tab("all").label("All"),
+    tab("published").modifyQuery((q) => q.where("status", "published")).badge(),
+    tab("draft").modifyQuery((q) => q.where("status", "draft")).badgeColor("muted"),
+  ];
+}
+```
+
+## Grouping
+
+`group(column)` adds a "Group by" menu; the page renders header rows per bucket with
+counts (and per-group summary subtotals).
+
+```ts
+import { group } from "@zerotal/admin";
+
+static groups() {
+  return [group("status"), group("author").label("Author")];
+}
+static defaultGroup = "status";   // optional
+```
+
+## Reordering
+
+Set `reorderable` to an integer position column to show up/down handles that persist
+order:
+
+```ts
+static reorderable = "sort";
+```
+
+## Built-in table affordances
+
+Per-page selector, a **Columns** visibility manager (`?cols=`), full-text search
+across `.searchable()` columns, and bulk selection with a toolbar all ship
+automatically and are URL-driven.
+
+## Empty states
+
+A blank table teaches nobody anything. Override `emptyState()` to say why the list
+is empty and what will fill it:
+
+```ts
+static emptyState() {
+  return {
+    heading: "No orders yet",
+    description: "Orders appear here as soon as a customer checks out.",
+    icon: "inbox",
+    actions: [createAction()],
+  };
+}
+```
+
+A search or filter that matches nothing gets a different, automatic message — this
+is for a genuinely empty resource, which is a different problem and wants a
+different answer.
+
+## Layout and placement
+
+How the table renders — grid instead of rows, striping, sticky headers, density —
+and where the filters sit are covered in
+[Extending the UI](/docs/admin/extending-ui#table-presentation).
+
+## 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/testing.md

@@ -0,0 +1,138 @@
+---
+title: Testing the Admin Panel
+description: Drive panel screens in tests and assert on what they render.
+---
+
+# Testing
+
+`@zerotal/admin/testing` mounts a resource's pages on Flow's in-process test
+harness and adds assertions phrased in admin terms — columns, fields, actions and
+records — so a test reads like a description of the screen rather than a walk
+through its markup.
+
+Nothing is served over the network. Mounting a page instantiates the component,
+runs its real lifecycle, and renders once, so there is no server to boot and no
+WebSocket to connect. Tests stay fast enough to cover every resource you register.
+
+## Mounting a page
+
+Three helpers cover the three screens a resource renders. Each returns a
+`FlowTest`, so every assertion in [Flow's testing guide](/docs/flow/testing)
+works alongside the admin-specific ones below.
+
+| Helper                             | Screen             | Reach for it to check                            |
+| ---------------------------------- | ------------------ | ------------------------------------------------ |
+| `AdminTest.list(Resource, props?)` | List page          | Columns, search, sorting, filters, bulk actions  |
+| `AdminTest.view(Resource, id)`     | View page          | Infolist entries and header actions for a record |
+| `AdminTest.form(Resource, mode?)`  | Create / Edit form | Fields, validation and saving                    |
+
+```ts
+// tests/admin/users.test.ts
+import { AdminTest, assertHasColumn, assertHasAction } from "@zerotal/admin/testing";
+import { UserResource } from "../../app/admin/UserResource.ts";
+
+const list = await AdminTest.list(UserResource);
+assertHasColumn(list, UserResource, "email");
+assertHasAction(list, "Create");
+list.assertSee("ada@example.com");
+```
+
+`AdminTest.form()` takes the mode as its second argument — `"create"` (the
+default) or `"edit"`. Drive the form through its `form` property, which holds
+every field's value:
+
+```ts
+const form = await AdminTest.form(UserResource, "create");
+assertHasField(form, UserResource, "name");
+await form.set("form", { name: "" });
+await form.call("save");
+form.assertHasErrors("name");
+```
+
+## Seeding list state
+
+The List page keeps search, sorting, pagination and filters in `@url` state. Pass
+those values as the second argument to `AdminTest.list()` and the page mounts as
+though the reader had arrived on that URL — which is how you assert on a filtered
+or sorted table without first driving the clicks that would produce it.
+
+```ts
+const list = await AdminTest.list(UserResource, {
+  search: "ada",
+  sortBy: "createdAt",
+  sortDir: "desc",
+  page: "2",
+});
+```
+
+| Prop                 | Seeds                            |
+| -------------------- | -------------------------------- |
+| `search`             | The search box                   |
+| `sortBy` / `sortDir` | Sort column and direction        |
+| `page` / `perPage`   | Pagination                       |
+| `filters`            | Active filter values             |
+| `tab`                | The selected tab                 |
+| `trashed`            | The soft-delete scope            |
+| `group`              | Active grouping                  |
+| `cols`               | Column visibility toggles        |
+| `locale`             | The locale translated values use |
+
+Every one of these is a string, because they round-trip through the query string.
+
+## Admin assertions
+
+These four take a key from the resource definition and assert against the
+_resolved_ label. A test written this way keeps passing when a column is
+relabelled through `.label()`, and fails when the column is removed — usually the
+change you wanted the test to catch.
+
+| Assertion                               | Passes when                              |
+| --------------------------------------- | ---------------------------------------- |
+| `assertHasColumn(t, Resource, key)`     | That column's header is rendered         |
+| `assertHasField(t, Resource, key)`      | That form field's label is rendered      |
+| `assertHasAction(t, label)`             | An action with that label is on the page |
+| `assertSeesRecord(t, Resource, record)` | The record's title appears in a row      |
+
+`assertSeesRecord` composes the title through the resource's
+`recordTitleAttribute`, so it finds the row however that title is assembled.
+`assertHasField` searches through nested layout components, so a field inside a
+tab or section is found without naming its container.
+
+## Driving and inspecting the page
+
+The harness inherits Flow's actions and assertions. Two are worth calling out,
+because reaching for the wrong one hides bugs:
+
+- **`set(prop, value)`** assigns a property directly and skips the
+  `updating`/`updated` hooks. Use it to arrange state before the behaviour you are
+  actually testing.
+- **`update(prop, value)`** takes the same path a change from the browser does and
+  fires those hooks. Use it when the hooks _are_ the behaviour under test — a
+  filter that refetches rows, or a field that derives another field.
+
+`call(method, ...args)` invokes an action the way a button would. For assertions,
+`assertSee` / `assertDontSee` cover rendered text, `assertHasErrors(field)` and
+`assertNoErrors()` cover validation, `assertRedirectedTo(url)` covers a save that
+navigates away, and `assertFlashed(level?, message?)` covers the notification a
+successful action leaves behind.
+
+When an assertion fails and you need to see why, `html()` returns the rendered
+markup, `errors()` the validation bag, and `page()` the live component instance.
+
+## Testing a non-default panel
+
+Every helper accepts a panel as its last argument, defaulting to
+`Panel.default()`. Apps that register more than one panel pass the one under test,
+so the page resolves that panel's own configuration and navigation:
+
+```ts
+const shop = Panel.get("shop");
+
+const list = await AdminTest.list(OrderResource, {}, shop);
+const form = await AdminTest.form(OrderResource, "edit", { recordId: "1" }, shop);
+```
+
+## Next steps
+
+- [Admin overview](/docs/admin) — the guide's front page and the rest of the sections.
+- [Flow testing](/docs/flow/testing) — the harness these helpers are built on.