@zerotal/arch 1.7.0

package/docs/admin/actions.md

@@ -0,0 +1,183 @@
+---
+title: Admin Actions & Relations
+description: Row, bulk, and page actions, related-record managers, and soft-delete handling.
+---
+
+# Actions
+
+Actions power the row, header, and bulk buttons. The defaults are
+`viewAction()/editAction()/deleteAction()` (rows), `createAction()` (header), and
+`bulkDeleteAction()` (bulk) — override the corresponding methods to customize.
+
+```ts
+import { action, editAction, deleteAction, textInput } from "@zerotal/admin";
+
+static recordActions() {
+  return [
+    editAction(),
+    action("publish")
+      .label("Publish").icon("check-circle").color("success")
+      .requiresConfirmation("Publish this post?")
+      .authorize((rec) => this.can("update", rec))
+      .run(async (ctx) => { await ctx.record.publish(); }),
+    deleteAction(),
+  ];
+}
+```
+
+A row with more than three visible actions collapses the surplus into an overflow
+menu. Actions can also open a **modal form**:
+
+```ts
+action("assign")
+  .label("Assign reviewer")
+  .form([ select("reviewer_id").options(reviewers).required() ])
+  .run(async (ctx) => { await ctx.record.assign(ctx.data.reviewer_id); }),
+```
+
+`.run(ctx)` receives `{ resource, record?, ids?, data?, parentId?, listOptions? }`
+(row / header / bulk).
+
+## Action groups
+
+A row with seven buttons is unreadable. `actionGroup` collapses several into one
+labelled dropdown, so the row keeps the two people reach for and files the rest:
+
+```ts
+import { actionGroup, replicateAction, deleteAction } from "@zerotal/admin";
+
+static recordActions() {
+  return [
+    viewAction(),
+    editAction(),
+    actionGroup([
+      replicateAction(),
+      action("archive").label("Archive").icon("folder").run(…),
+      deleteAction(),
+    ]).label("More"),
+  ];
+}
+```
+
+Members are gated individually — a group whose every member is hidden draws
+nothing. Groups work in the header and the bulk toolbar too.
+
+## Replicate
+
+`replicateAction()` copies a record and opens the copy for editing. The primary key
+and timestamps are always dropped; name anything else that must stay unique:
+
+```ts
+replicateAction()
+  .excludeAttributes(["sku", "slug"])
+  .beforeReplicaSaved((data) => ({ ...data, name: `${data.name} (copy)`, status: "draft" })),
+```
+
+## Import and export
+
+```ts
+import { exportAction, importAction, bulkExportAction } from "@zerotal/admin";
+
+static headerActions() {
+  return [createAction(), exportAction(), importAction()];
+}
+
+static bulkActions() {
+  return [bulkExportAction(), bulkDeleteAction()];
+}
+```
+
+**Export** writes the current list as CSV — the same search, filters, tab and sort
+the user is looking at, not the whole table. Someone who has narrowed a view to the
+twelve rows they care about expects twelve rows in the file. `bulkExportAction()`
+exports the selection instead.
+
+Pass `"xlsx"` for a spreadsheet instead:
+
+```ts
+return [createAction(), exportAction(), exportAction("xlsx")];
+```
+
+CSV stays the better interchange format and the default. The workbook is for the case
+CSV genuinely cannot serve: a recipient who opens the file, finds `007` turned into
+`7` and a leading `=` treated as a formula, and reasonably calls the export broken.
+Cells are written with real types, so dates sort as dates and numbers total, and the
+header row is frozen with a filter over the used range.
+
+Keep a column out of the file with `.exportable(false)`. Pay, internal notes and
+anything else that should not travel in a spreadsheet belongs behind that flag:
+
+```ts
+text("salary").exportable(false),
+```
+
+**Import** takes a CSV through a modal in two steps on one screen: pick a file,
+then confirm which field each of its columns feeds. The selects start on whatever
+the headers match — case, spaces, underscores and hyphens are all treated the
+same — so a file the panel exported needs no adjustment, and a file from
+somewhere else needs only the columns that didn't line up. Mapping a column to
+"skip" leaves it out.
+
+Every row is validated through the resource's own fields, so an import cannot write
+anything a person could not have typed into the create form. A row that fails is
+reported by line number and skipped; one bad line out of five hundred does not
+discard the other four hundred and ninety-nine.
+
+### Large files
+
+An import runs inline by default, capped at 2,000 rows — a synchronous import
+holds a WebSocket round-trip open, and a bigger file looks like a hang. Hand it
+to a queue instead and the cap lifts:
+
+```ts
+static headerActions() {
+  return [createAction(), exportAction(), importAction({ queue: true })];
+}
+```
+
+The worker needs to be able to rebuild the job from its payload, so register the
+class where it can see it:
+
+```ts
+import { JobRegistry } from "@zerotal/queue";
+import { ImportRecordsJob } from "@zerotal/admin";
+
+JobRegistry.register(ImportRecordsJob);
+```
+
+With no queue configured, a queued import falls back to running inline rather
+than silently doing nothing. `@zerotal/queue` stays an optional peer: it is
+imported only when an import is actually queued.
+
+## Relations
+
+Relation managers appear as tables on the View page.
+
+```ts
+import { hasMany, belongsToMany } from "@zerotal/admin";
+
+static relations() {
+  return [
+    // Children referencing the parent — full CRUD links into their own resource.
+    hasMany(CommentResource, "post_id").title("Comments"),
+
+    // Many-to-many — attached rows with Detach + an Attach picker + pivot columns.
+    belongsToMany(TagResource, "tags")
+      .pivotColumns([{ key: "added_at", label: "Added" }]),
+  ];
+}
+```
+
+`belongsToMany(Resource, "tags")` drives the parent model's `tags().attach()` /
+`tags().detach()` / `tags().get()`.
+
+## Soft deletes
+
+When the model uses the ORM `SoftDeletes` mixin, the List page gains an
+**Active / All / Trashed** switch and the row + bulk actions gain Restore and
+Force-delete automatically — no extra configuration.
+
+## 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/auth.md

@@ -0,0 +1,89 @@
+---
+title: Admin Auth Pages & Theming
+description: The built-in login and profile screens, and how to restyle the panel.
+---
+
+# Auth pages
+
+Opt in with `Panel.auth({...})` (or `Panel.configure({ auth: {...} })`). The pages
+live behind the `@zerotal/admin/auth` subpath, so the `@zerotal/auth` dependency
+stays optional unless you enable them.
+
+```ts
+import { Panel } from "@zerotal/admin";
+
+Panel.auth({
+  enabled: true,
+  identifier: "email", // credential column
+  remember: true,
+  redirectTo: "/admin",
+  authenticateWhen: (u) => (u as { active?: boolean }).active === true,
+
+  // Optional — mounts the forgot/reset pages when provided:
+  passwordReset: {
+    sendResetLink: (email) => PasswordBroker.sendResetLink({ email }),
+    reset: (input) => PasswordBroker.reset(input),
+  },
+  // Optional — mounts the verify page + profile banner when provided:
+  emailVerification: {
+    isVerified: (u) => (u as { email_verified_at?: unknown }).email_verified_at != null,
+    resend: (u) =>
+      (
+        u as { sendEmailVerificationNotification(): Promise<void> }
+      ).sendEmailVerificationNotification(),
+  },
+});
+```
+
+| Page                 | Route              | Uses                                            |
+| -------------------- | ------------------ | ----------------------------------------------- |
+| `LoginPage`          | `/login`           | `Auth.attempt` (+ remember, `authenticateWhen`) |
+| `ProfilePage`        | `/profile`         | update details · change password · sign out     |
+| `ForgotPasswordPage` | `/forgot-password` | `passwordReset.sendResetLink`                   |
+| `ResetPasswordPage`  | `/reset-password`  | `passwordReset.reset`                           |
+| `VerifyEmailPage`    | `/verify-email`    | `emailVerification.resend`                      |
+
+Guest screens (login / forgot / reset) mount **outside** the panel guard so
+unauthenticated users can reach them; profile / verify mount behind it
+(override with `guestMiddleware` / `authMiddleware`). The 2FA **challenge** step is
+left to your auth middleware — the rest of the flow ships here.
+
+## Securing the panel
+
+The panel is public until you set guard middleware. A typical setup:
+
+```ts
+Panel.configure({ middleware: [AuthMiddleware, RequireRoleMiddleware.with("admin")] });
+Panel.auth({ enabled: true }); // login lives outside that guard automatically
+```
+
+## Theming
+
+By default the panel themes everything with the **Tailwind Play CDN** plus shadcn-style
+design tokens and a no-flash dark/light script — zero build step. The toggle in the
+top bar flips `.dark` on `<html>` and persists the choice.
+
+To ship a real build, point `theme.stylesheet` at your compiled CSS (the CDN is then
+dropped) and reuse the exported config + tokens so your build matches the default look:
+
+```ts
+import { Panel, adminTailwindConfig, adminTokensCss } from "@zerotal/admin";
+
+Panel.configure({
+  theme: {
+    stylesheet: "/assets/admin.css", // your prebuilt Tailwind output
+    // cdn: true,                      // keep both during migration
+    // tokensCss: ":root { --primary: 270 90% 60%; }",  // override tokens
+    // noFonts: true,                  // self-host Inter
+  },
+});
+```
+
+`adminTailwindConfig()` returns the token→CSS-var Tailwind config and
+`adminTokensCss()` the `:root`/`.dark` custom properties — feed both into your own
+`tailwind.config` so a compiled stylesheet renders identically.
+
+## 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/dashboard.md

@@ -0,0 +1,155 @@
+---
+title: Admin Dashboard & Navigation
+description: Widgets, global search, the command palette, notifications, and the nav tree.
+---
+
+# Dashboard widgets
+
+Register widgets with `Panel.widgets(...)`; they render on the dashboard.
+
+```ts
+import { Panel, statsWidget, stat, chartWidget, tableWidget } from "@zerotal/admin";
+
+Panel.widgets(
+  statsWidget(async () => [
+    stat("Users", await User.count())
+      .description("+12% this week")
+      .color("success"),
+    stat("Revenue", "$48k"),
+  ]),
+  chartWidget("Signups", async () => ({
+    type: "line",
+    labels: ["Mon", "Tue", "Wed"],
+    datasets: [{ label: "Signups", data: [4, 9, 7] }],
+  })),
+  tableWidget(
+    "Latest orders",
+    [
+      { key: "id", label: "#" },
+      { key: "total", label: "Total", align: "end" },
+    ],
+    async () => await Order.latest().limit(5).get(),
+  ),
+);
+```
+
+Charts use Chart.js via CDN (the dashboard renders once, so there's no morph re-init).
+
+## Widgets on a resource
+
+The dashboard answers "how is the business doing". A resource's own widgets
+answer "what is going on in _this_ list" — a pending count above the orders
+table, stock value above products:
+
+```ts
+export class OrderResource extends Resource {
+  static override widgets() {
+    return [
+      statsWidget(async () => [
+        stat("Awaiting payment", await Order.query().where("status", "pending").count()),
+      ]).poll("30s"),
+    ];
+  }
+}
+```
+
+They render above the table and use the same builders as the dashboard, polling
+included — and a polling widget there refreshes the table with it, which is what
+someone watching a queue actually wants.
+
+## Polling
+
+A dashboard on a second screen is stale the moment it renders. `.poll()` gives a
+widget an interval:
+
+```ts
+statsWidget(async () => [
+  stat("Awaiting payment", await Order.query().where("status", "pending").count()),
+]).poll("30s"),
+```
+
+The dashboard refreshes as one unit, at the shortest interval any of its widgets
+asked for. That costs a query per tick per viewer, so it is worth it for the
+numbers someone actually watches and wasteful on everything else — leave the rest
+to render once per navigation.
+
+## Global search & the command palette
+
+Any resource with `.searchable()` columns and a `recordTitleAttribute` joins **global
+search** — a top-bar box, a `/search` results page, and a client-side **⌘K / Ctrl-K
+command palette** that filters resources and escalates a free query to the search
+page.
+
+## Notifications
+
+The admin owns the bell + notifications page UI; your app supplies the data through a
+provider (the same split as relations — admin UI, app data):
+
+```ts
+import { Panel } from "@zerotal/admin";
+
+Panel.notifications({
+  async resolve() {
+    return (await Auth.user().notifications().latest().limit(20).get()).map((n) => ({
+      id: String(n.id),
+      title: n.data.title,
+      body: n.data.body,
+      href: n.data.url,
+      read: n.read_at != null,
+      time: n.created_at,
+    }));
+  },
+  async markRead(id) {
+    await Notification.find(id)?.markAsRead();
+  },
+  async markAllRead() {
+    await Auth.user().unreadNotifications().markAsRead();
+  },
+  async unreadCount() {
+    return Auth.user().unreadNotifications().count();
+  },
+});
+```
+
+The header bell shows a **live unread badge** (refreshed each navigation). The
+notifications page **polls** and listens for **broadcasts**: broadcast a notification
+from your app on the `NOTIFICATION_CHANNEL` / `NOTIFICATION_EVENT`
+(`admin-notifications` / `.notification.sent`) broadcast channel and the open page
+updates live. When no provider is configured, the bell and page stay hidden.
+
+### Database-backed notifications
+
+`Panel.notifications()` takes a provider because "the current user's
+notifications" depends on your auth and your schema. When both are the ordinary
+ones — `@zerotal/auth` for the user, `@zerotal/notifications`' `DatabaseChannel`
+for storage — there is a ready-made one:
+
+```ts
+import { databaseNotifications } from "@zerotal/admin";
+
+Panel.notifications(databaseNotifications());
+```
+
+Everything is adjustable: `notifiable` says whose notifications to show,
+`present` turns a stored row into a title and a link, `table` names the table,
+`limit` caps how many the bell holds.
+
+It fails soft throughout. A missing table, an unconfigured database or a
+signed-out user yields an empty bell rather than a broken panel — a notification
+centre is never worth taking the page down for.
+
+## Navigation
+
+The sidebar is derived from each resource's `navigationGroup`, `navigationSort`,
+`navigationIcon`, and `navigationParentItem`. Groups are collapsible (`<details>`),
+parent items nest their children, and `navigationBadge()` renders a colored count
+pill. The top-bar **user menu** comes from `Panel.configure({ userMenu })`.
+
+Custom pages and anything contributed by a package sit in the same sidebar, sorted
+and grouped by the same rules — a page's group heading is just a string, so a page
+and a resource that name the same group land 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/extending-ui.md

@@ -0,0 +1,229 @@
+---
+title: Extending the UI
+description: Render your own cells, controls and entries, inject markup into the panel's chrome, and back a resource with something other than a model.
+---
+
+# Extending the UI
+
+The catalogue covers most screens. When it doesn't, four escape hatches let you
+add what's missing without forking the panel.
+
+| You want                                       | Reach for                                   |
+| ---------------------------------------------- | ------------------------------------------- |
+| A cell, control or entry the catalogue lacks   | [Custom renderers](#custom-renderers)       |
+| Markup in the panel's chrome — banners, badges | [Render hooks](#render-hooks)               |
+| A resource backed by an API or a file          | [Custom data sources](#custom-data-sources) |
+| A different shape of table                     | [Table presentation](#table-presentation)   |
+
+## Custom renderers
+
+Every layer has a `.render()` that takes over its own markup and leaves
+everything else alone.
+
+**Table cells.** The column still owns its label, sorting, search and export;
+only the cell is yours:
+
+```ts
+text("health")
+  .label("Health")
+  .sortable()
+  .render((value) => <HealthBar value={Number(value)} />),
+```
+
+**Infolist entries.** The section's grid still places it:
+
+```ts
+textEntry("route").render((value) => <RouteMap path={String(value)} />),
+```
+
+**Form controls.** `customField` gives you a field that validates, binds and
+saves like any other — you supply only the control. Bind your markup to
+`form.<key>` for the value to round-trip:
+
+```ts
+customField("coordinates")
+  .label("Location")
+  .required()
+  .render((value, data) => <MapPicker value={value} country={data.country} />),
+```
+
+The renderer receives the whole form's data as well as its own value, which is
+what lets a control react to a sibling field.
+
+## Render hooks
+
+A contributed page can only add a page. A hook adds markup at a named position
+in the chrome — a trial banner, a compliance notice, an environment badge:
+
+```ts
+Panel.renderHook("page.header.end", () => <TrialBanner />);
+
+// Conditional placement: register once, decide per render.
+Panel.renderHook("table.start", (ctx) =>
+  ctx.resource === "orders" ? <ShippingNotice /> : null,
+);
+```
+
+Returning `null` renders nothing. A hook that throws is logged and skipped — a
+decoration must not be able to take down the page it decorates.
+
+The positions:
+
+| Group        | Names                                  |
+| ------------ | -------------------------------------- |
+| Shell        | `body.start`, `body.end`               |
+| Sidebar      | `sidebar.start`, `sidebar.end`         |
+| Top bar      | `topbar.start`, `topbar.end`           |
+| Page heading | `page.header.start`, `page.header.end` |
+| Table        | `table.start`, `table.end`             |
+| Form         | `form.start`, `form.end`               |
+| Record       | `record.start`, `record.end`           |
+
+Each hook receives a context naming the resource, the kind of screen and the
+record id where there is one, so one registration can serve every page and place
+itself only where it belongs.
+
+Packages get the same surface through the `admin.panel` binding — see
+[Custom Pages & Plugins](/docs/admin/extending).
+
+## Custom data sources
+
+A resource does not have to be backed by a model. Return rows from `data()` and
+the panel filters, sorts and paginates them in memory, so search, tabs,
+summaries and the query builder all keep working:
+
+```ts
+export class RegionResource extends Resource {
+  static override async data() {
+    return await fetch("https://api.example.com/regions").then((r) => r.json());
+  }
+
+  static override columns() {
+    return [text("code").searchable(), text("name").searchable(), text("population")];
+  }
+}
+```
+
+Reads are the easy half. A read-only source needs no `form()` — an empty one
+removes the create and edit pages. To make it writable, override `create`,
+`update` and `destroy` to push the change back wherever it belongs.
+
+In-memory means the whole set is loaded per request, so this suits hundreds of
+rows and not millions. Past that, back it with a model or a view.
+
+## Table presentation
+
+Four statics change how a list renders:
+
+```ts
+export class ProductResource extends Resource {
+  static override tableLayout = "grid"; // "table" (default) | "grid" | "kanban" | "calendar"
+  static override striped = true;
+  static override stickyHeader = true;
+  static override density = "compact"; // "comfortable" (default) | "compact"
+}
+```
+
+**Grid** trades columns for cards, which suits records you recognise by sight —
+products, media, people. The layout is derived from the columns you already
+declared: the first image column becomes the picture, the first text column the
+title, and the next few render as label/value pairs. No second description.
+
+**Kanban** turns a status column into lanes, for records that read as a pipeline:
+
+```ts
+static override tableLayout = "kanban";
+static override kanbanColumn = "status";
+static override kanbanLanes = { pending: "Pending", paid: "Paid", shipped: "Shipped" };
+```
+
+Each card carries arrows to move it to the neighbouring lane, which runs the same
+authorised update a row action would — a second way to do a thing the panel already
+does, not a second source of truth. A value present in the data but missing from
+`kanbanLanes` still gets a lane, so nothing is hidden by an incomplete declaration.
+
+**Calendar** lays the page out as a month grid keyed on a date column:
+
+```ts
+static override tableLayout = "calendar";
+static override calendarColumn = "startsOn";
+```
+
+The month shown is the one the listed rows fall in rather than the current month, so
+paging back through older records does not land on an empty grid.
+
+**Striped**, **sticky** and **compact** are what they sound like, and matter most
+on wide or long tables.
+
+### Trees
+
+A resource whose records nest under each other renders as a tree:
+
+```ts
+export class CategoryResource extends Resource {
+  static override treeParentColumn = "parentId";
+}
+```
+
+Each page is arranged so children sit under their parent and the first column indents
+by depth. The arranging happens over the rows on screen rather than in SQL — a
+recursive query is the right answer for a deep tree but is not portable across the
+drivers the panel supports, and a tree small enough to browse is small enough to
+arrange in memory. A row whose parent is not on the page stays at the top level rather
+than disappearing, so a filtered tree never hides a record.
+
+### Translations
+
+A resource whose text exists in several languages edits one at a time:
+
+```ts
+export class PostResource extends Resource {
+  static override translatable = ["title", "excerpt"];
+  static override locales = ["en", "fr"];
+}
+```
+
+The columns store `{ en: "…", fr: "…" }`. The list gains a locale switch and shows the
+active one; the form gains locale tabs, and switching banks what you have typed rather
+than discarding it. Saving one locale keeps the others, which is what stops an English
+edit from wiping the French. A value that was never translated is shown as-is, so
+turning this on for an existing column does not blank it.
+
+### Header filters
+
+A column can carry its own filter box in the table header:
+
+```ts
+text("sku").filterable();
+selectColumn("status", STATUS).filterable();
+```
+
+The control follows the column's kind — a text box for text, a yes/no switch for a
+toggle, the declared choices for a select — so a column usually needs nothing else.
+Header filters write into the same `?filters=` parameter as declared filters, which
+means they compose with tabs, search, sorting and pagination the same way, show up in
+the active-filter chips, and land in a saved view.
+
+### Filter placement
+
+Filters sit above the table by default. Once there are more than a few, collapse
+them:
+
+```ts
+static override filterLayout = "panel";   // "inline" (default) | "panel" | "drawer"
+```
+
+Both `panel` and `drawer` hide the controls behind a Filters button carrying a
+count of what's active; they differ in where the revealed controls sit.
+
+Whatever the layout, anything currently narrowing the list shows as a chip above
+the table — the search term, each filter, the trashed scope — and each chip is
+its own undo. A table showing four of two hundred rows for no visible reason is
+the most common way a panel misleads someone; the chips are the fix.
+
+## Next steps
+
+- [Tables](/docs/admin/tables) — columns, filters and the query builder.
+- [Forms & Infolists](/docs/admin/forms) — the built-in field and entry catalogue.
+- [Custom Pages & Plugins](/docs/admin/extending) — whole pages, and contributing from a package.
+- [References](/docs/admin/references) — the full API surface in one table.