@zerotal/admin 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog — @zerotal/admin
+
+All notable changes to this package are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/); this package
+follows the Zerotal monorepo's unified versioning.
+
+**Maturity: `experimental`**
+
+## [Unreleased]
+
+### Added
+
+#### Panel structure
+
+- `Cluster` — a shared URL segment and one sidebar entry for a group of resources. Members opt in with `static cluster = ShopCluster`, and a cluster's `ability` gates every route inside it.
+- Nested resources — `static parent = { resource: () => PostResource, foreignKey: "post_id" }` moves a resource under its parent's records (`/admin/posts/7/comments`). Every list is scoped to the parent before any tab or filter, and new records inherit the foreign key from the URL rather than from a form field.
+- Singular resources — `static singular = true` collapses list, view and edit into one route for a one-row resource. The row is resolved on first visit and created from the form's defaults if absent.
+- Multiple panels — `Panel.make(id, config)` creates an additional panel with its own resources, pages, widgets, guard, branding and URL prefix. `Panel` remains a facade over the panel owning the current request, so single-panel apps are unaffected.
+- Resources build their own URLs: `routePath()`, `indexUrl()`, `recordUrl()`, `createUrl()`, `editUrl()`. Linking through these lets a resource move into a cluster or under a parent without any caller changing.
+
+#### Tables
+
+- `queryBuilder(key)` — a build-your-own filter with nested AND/OR rule groups, backed by `textConstraint` / `numberConstraint` / `dateConstraint` / `booleanConstraint` / `selectConstraint`. The whole tree is wrapped in one group so an inner `OR` cannot widen a tab, parent or soft-delete scope, and a rule naming an undeclared constraint is dropped.
+- Active-filter indicators — a chip per filter narrowing the list, each its own undo.
+- `filterLayout` — `"inline"` (default), `"panel"` or `"drawer"`.
+- `tableLayout: "grid"`, `striped`, `stickyHeader`, `density`. The grid derives its cards from the columns already declared.
+- `Resource.emptyState()` — a heading, description, icon and actions in place of a blank table. A narrowed view that matches nothing gets a different, automatic message.
+- `Column.exportable(false)` keeps a column out of CSV exports.
+
+#### Actions
+
+- `exportAction()` / `bulkExportAction()` — CSV of the current list, matching its search, filters, tab and sort exactly.
+- `importAction()` — CSV import through a two-step modal: pick a file, then map each column to a field. Mapping is seeded by matching headers to field names and labels. Rows are validated through the resource's own fields; failures are reported by line number and skipped.
+- `importAction({ queue: true })` dispatches `ImportRecordsJob`, lifting the inline row cap. `@zerotal/queue` is resolved lazily and stays optional; with no queue configured the import runs inline.
+- `actionGroup([...])` collapses several actions into one dropdown.
+- `replicateAction()` copies a record and opens the copy, with `.excludeAttributes()` and `.beforeReplicaSaved()`.
+- `Action.formUsing(fn)` builds a modal's fields from what it currently holds.
+
+#### Infolists and forms
+
+- `imageEntry`, `colorEntry`, `codeEntry`, `keyValueEntry`, `repeatableEntry` — the last renders a nested schema once per array item, the read side of `repeater`.
+- `customField(key).render(fn)`, plus `.render()` on `Column` and `Entry`, for controls and cells the catalogue lacks. The renderer owns only the markup; label, validation, sorting and binding still come from the declaration.
+
+#### Extensibility
+
+- Render hooks — 14 named positions in the panel's chrome (`table.start`, `page.header.end`, `sidebar.end`, …). A hook returning `null` renders nothing; one that throws is logged and skipped. Available to packages through the `admin.panel` binding.
+- `Resource.data()` — back a resource with an API, a file or a computation instead of a model. The panel filters, sorts and paginates in memory, so search, tabs and summaries keep working.
+- `Resource.widgets()` — widgets above a resource's table, using the same builders as the dashboard.
+- `databaseNotifications()` — a ready-made notification provider over `@zerotal/notifications`' `DatabaseChannel`, failing soft to an empty bell at every step.
+
+#### Other
+
+- Breadcrumbs derived from panel → cluster → parent record → resource → record.
+- `.poll(interval)` on every widget kind; the dashboard refreshes at the shortest interval any of its widgets asked for.
+- `bun zt make:admin-resource <Model>` with `--cluster`, `--parent`, `--foreign-key` and `--singular`.
+- An `admin` template for `bun create zerotal`.
+
+- `AdminProvider` also loads `app/admin/index.ts`, so a panel large enough to need a directory can have one. `app/admin.ts` still works and is tried first.
+- `AdminProvider` now boots in the `console` environment as well, solely to register `make:admin-resource`; it mounts no routes there.
+- `recordActions()`, `headerActions()` and `bulkActions()` return `ActionItem[]` — an action or an `ActionGroup`.
+- `registerResourceForm()` is keyed by panel and slug, so two panels can each register the same resource slug.
+
+## [1.0.0] — 2026-08-05
+
+_First public release._
+
+### Notes
+
+- Conforms to the Zerotal package conventions (provider in `src/provider/`, PascalCase config factory, `ZerotalError`-based errors, test coverage).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zerotal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,344 @@
+# @zerotal/admin
+
+> A Filament-style, server-driven admin panel for Zerotal — built on
+> [`@zerotal/flow`](../flow) (reactivity) and [`@zerotal/flow-ui`](../flow-ui) (components).
+
+You declare a **Resource** per model; the panel renders the navigation, the data
+table, search, sorting, and pagination for you. Pages are Flow components, so
+everything runs on the server and streams over WebSocket — no API layer, no
+client store.
+
+The default UI ships with **light + dark mode out of the box**. Styling currently
+loads Tailwind via the Play CDN (configured in `theme.ts`); swapping to a real
+Tailwind build later only touches that one file.
+
+> **Status:** experimental. You get navigation, list pages (search / sort /
+> paginate), a read-only **View** page (infolists), reactive **Create / Edit**
+> forms with validation, a **Delete** row action, and a configurable auth
+> **guard**. The previous config-driven admin has been retired; it remains
+> available in pre-1.1 releases (and on the `admin-legacy` git tag).
+
+## Setup
+
+```ts
+// bootstrap/providers.ts
+import { FlowProvider } from "@zerotal/flow";
+import { AdminProvider } from "@zerotal/admin"; // after FlowProvider
+
+export default [FlowProvider, AdminProvider];
+```
+
+```ts
+// app/admin.ts  (auto-loaded on boot)
+import { Panel, Resource, text } 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(),
+      text("role").badge((v) => (v === "admin" ? "primary" : "muted")),
+      text("created_at").label("Joined").sortable(),
+    ];
+  }
+}
+
+Panel.register(UserResource);
+```
+
+Visit `/admin`. Each resource gets a list page (`/admin/users`), a read-only
+detail page (`/admin/users/:id`), and a Delete action on every row.
+
+### Guarding the panel
+
+The panel is public by default — fine locally, not in production. Pass
+`middleware` to gate every route (it runs on the list, view, and dashboard):
+
+```ts
+import { AuthMiddleware } from "@zerotal/auth";
+
+Panel.configure({
+  path: "/admin",
+  middleware: [AuthMiddleware.with({ mustVerifyEmail: true })],
+});
+```
+
+### View page (infolists)
+
+The detail page renders a Filament-style **infolist** — read-only entries grouped
+into sections. Define `infolist()` to customize it; omit it and the page falls
+back to one section derived from `columns()`.
+
+```ts
+import { Resource, section, textEntry, iconEntry } from "@zerotal/admin";
+
+class UserResource extends Resource {
+  static infolist() {
+    return [
+      section("Profile")
+        .description("Identity and sign-in details")
+        .icon("users")
+        .columns(2)
+        .schema([
+          textEntry("name").weight("semibold").size("lg"),
+          textEntry("email").icon("mail").copyable(),
+          iconEntry("email_verified_at").label("Email verified"), // ✓ / ✗ boolean
+          textEntry("role")
+            .badge()
+            .color((v) => (v === "admin" ? "primary" : "muted")),
+        ]),
+      section("Activity")
+        .columns(2)
+        .schema([
+          textEntry("created_at").label("Joined").dateTime(),
+          textEntry("created_at").label("Member for").since(),
+        ]),
+    ];
+  }
+}
+```
+
+Entry API: `.label()`, `.state(fn)`, `.default()`, `.placeholder()`, `.format(fn)`,
+`.badge()`, `.color()`, `.icon()`, `.copyable()`, `.url(fn)`, `.weight()`, `.size()`,
+`.tooltip()`, `.columnSpan()`, `.limit()`, `.date()` / `.dateTime()` / `.since()`,
+`.money()`. `iconEntry(...)` renders a boolean check/cross. Section API:
+`.heading()`, `.description()`, `.icon()`, `.columns()`, `.collapsible()`.
+
+### Create / Edit forms
+
+Declare `form()` to get reactive Create (`/admin/users/create`) and Edit
+(`/admin/users/:id/edit`) pages. Fields bind two-way over Flow's WebSocket
+runtime and validate on save — no API layer, no client store.
+
+```ts
+import { Resource, textInput, textarea, select } from "@zerotal/admin";
+import { Hash } from "@zerotal/auth";
+
+class UserResource extends Resource {
+  static form() {
+    return [
+      textInput("name").required().minLength(2).maxLength(120),
+      textInput("email").email().required(),
+      select("role").options({ admin: "Admin", member: "Member" }).required(),
+      // Hash on save; only ask for it when creating.
+      textInput("password")
+        .password()
+        .required()
+        .minLength(8)
+        .visibleOn("create")
+        .mutate((v) => Hash.make(String(v))),
+    ];
+  }
+}
+```
+
+Field API: `textInput` / `textarea` / `select` / `checkbox`; type modifiers
+`.email()`, `.password()`, `.numeric()`, `.url()`, `.tel()`; `.label()`,
+`.placeholder()`, `.helperText()`, `.default()`, `.required()`, `.minLength()` /
+`.maxLength()` / `.min()` / `.max()`, `.confirmed()`, `.options()`, `.rows()`,
+`.columnSpan()`, `.disabled()`, `.rule(fn)`, `.mutate(fn)` (transform before
+save, e.g. hashing), and `.visibleOn()` / `.hiddenOn()` to vary a field by page.
+
+## Column API (Phase 1)
+
+```ts
+text("name")
+  .label("Full name")     // header text (defaults to a title-cased key)
+  .sortable()             // clickable, URL-driven sort header
+  .searchable()           // included in the list search box
+  .align("end")           // "start" | "center" | "end"
+  .format((v) => …)       // custom value formatter
+  .badge((v) => "success" | "primary" | "muted" | "destructive" | null)
+```
+
+## Theming / dark mode
+
+`theme.ts` defines the shadcn-style design tokens (the same ones flow-ui
+components consume) for both `:root` and `.dark`, plus a no-flash init script.
+The toggle in the top bar persists the choice to `localStorage`. To rebrand,
+edit the `--primary` (and friends) HSL values in `theme.ts`.
+
+## Listing: tabs + default sort
+
+Add filter **tabs** (Filament's `getTabs()`) above the table, each scoping the
+query with an optional count badge, and set a **default sort**:
+
+```ts
+import { Resource, tab } from "@zerotal/admin";
+
+class UserResource extends Resource {
+  static defaultSort = { column: "created_at", direction: "desc" as const };
+
+  static tabs() {
+    return [
+      tab("all").label("All").badge(),
+      tab("verified")
+        .label("Verified")
+        .badge()
+        .badgeColor("success")
+        .modifyQuery((q) => q.whereNotNull!("email_verified_at")),
+      tab("unverified")
+        .label("Unverified")
+        .badge()
+        .modifyQuery((q) => q.whereNull!("email_verified_at")),
+    ];
+  }
+}
+```
+
+`tab(key)` API: `.label()`, `.icon()`, `.badge(value?)` (no arg = live count),
+`.badgeColor(tone)`, `.modifyQuery(q => q)`. The active tab lives in the URL
+(`?tab=…`) and composes with search, sort, and pagination.
+
+Badge **counts are cached** per resource and invalidated automatically whenever
+one of its records is created / updated / deleted (via the ORM's `ModelChanged`
+event), so the `COUNT(*)` per tab runs only after a write — not on every list
+view. Caching is best-effort: with no cache driver bound, counts are computed
+each render.
+
+## Relationships
+
+Three pieces, mirroring Filament's relationship support:
+
+```ts
+class PostResource extends Resource {
+  static model = Post;
+  static eager = ["author"]; // eager-load relations for the table/view
+
+  static columns() {
+    return [
+      text("title").searchable().sortable(),
+      // BelongsTo column — read the loaded relation
+      text("author")
+        .label("Author")
+        .format((author) => author?.name ?? "—"),
+    ];
+  }
+
+  static form() {
+    return [
+      textInput("title").required(),
+      // BelongsTo <select> — options loaded from the related model
+      select("userId")
+        .label("Author")
+        .required()
+        .optionsUsing(async () =>
+          (await User.all()).map((u) => ({ value: String(u.id), label: u.name })),
+        ),
+    ];
+  }
+}
+
+class UserResource extends Resource {
+  static model = User;
+  // HasMany relation manager — the user's posts, as a linked table on the View page
+  static relations() {
+    return [hasMany(PostResource, "user_id").title("Posts")];
+  }
+}
+```
+
+- `static eager: string[]` — relations to eager-load for list + view (so a column
+  or entry can read `row.author.name`).
+- `select(key).optionsUsing(async () => …)` — async option source for a BelongsTo
+  picker. FK columns should be cast (`@column("integer")`) so they match the
+  parent key type when the ORM resolves the relation.
+- `relations()` + `hasMany(RelatedResource, foreignKey)` — renders the children as
+  a table on the parent's View page, linking into their own resource for full CRUD.
+
+## Custom pages
+
+Anything that isn't a model to edit — a settings screen, a report, an ops console
+— extends `AdminPage`. It's a Flow component with statics describing where it
+belongs, so the panel mounts the route and adds the sidebar entry for you.
+
+```ts
+import { AdminPage, Panel } from "@zerotal/admin";
+
+class ReportsPage extends AdminPage {
+  static override slug = "reports";
+  static override title = "Reports";
+  static override navigationGroup = "Insights";
+  static override ability = "reports.view";
+
+  override async render() {
+    return <div>…</div>;
+  }
+}
+
+Panel.pages(ReportsPage);
+```
+
+`ability` is checked twice: once to draw the sidebar entry, once in the route
+guard. Both run the same resolver, so a link the user can't see is a URL they
+can't open. Abilities resolve through `authorize` in `config/admin.ts`, then the
+`gate` binding when `@zerotal/auth` is installed — and with neither configured
+they're denied outside a development environment, so an unwired panel stays closed
+in production.
+
+## Extending the panel from a package
+
+The panel is a host. It publishes a contribution surface as the `admin.panel`
+container binding and names no contributor, so another package can add pages,
+widgets, navigation and search results without depending on this one:
+
+```ts
+// In a contributing provider's onBooting()
+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" });
+```
+
+Contributors declare the host's shape locally rather than importing it, so nothing
+links the two packages at build time. Contributions are automatic — installing
+both providers is enough — and `plugins: { queue: false }` in `config/admin.ts`
+switches one off without uninstalling it.
+
+See [the admin guide](../../docs/admin/extending.md) for the full contribution surface.
+
+## Structuring a larger panel
+
+Six resources need no structure. Past that:
+
+- **Clusters** give a group of resources a shared URL segment and one sidebar
+  entry — `static cluster = ShopCluster` puts a resource at `/admin/shop/products`.
+- **Nested resources** move a resource inside its parent's records:
+  `static parent = { resource: () => PostResource, foreignKey: "post_id" }` gives
+  `/admin/posts/7/comments`, scoped to that post.
+- **Singular resources** back a single row — `static singular = true` collapses
+  list, view and edit into one route.
+- **Multiple panels** serve a second audience: `Panel.make("console", { path: "/app" })`
+  gets its own registry, guard and branding.
+
+See [Panel Structure](../../docs/admin/structure.md) for the details.
+
+## Scaffolding
+
+```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
+```
+
+Or start a whole project from the panel: `bun create zerotal my-admin` and choose
+the **Admin** template.
+
+## Not yet covered
+
+Multi-tenancy and the 2FA challenge step.
+
+> **Design note:** the List and View pages are generated as one subclass per
+> resource and are **URL-driven** — search, sort, pagination, and tabs live in
+> `@url` props that re-seed from the query string on every navigation, so they
+> work for any number of resources. The Create/Edit page is different: it binds a
+> client-reactive `@expose form` object over the WebSocket, which Flow's
+> field-decorator registration ties to a single prototype, so it's a single
+> shared class that resolves the resource from the route slug.

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@zerotal/admin",
+  "version": "1.0.0",
+  "license": "MIT",
+  "maturity": "experimental",
+  "private": false,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./auth": "./src/auth/index.ts",
+    "./testing": "./src/testing.ts"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/__fixtures__/**"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@zerotal/cache": "1.0.0",
+    "@zerotal/core": "1.0.0",
+    "@zerotal/flow": "1.0.0",
+    "@zerotal/flow-ui": "1.0.0",
+    "@zerotal/validator": "1.0.0"
+  },
+  "devDependencies": {
+    "@zerotal/orm": "1.0.0",
+    "@zerotal/auth": "1.0.0",
+    "@zerotal/queue": "1.0.0"
+  },
+  "peerDependencies": {
+    "@zerotal/orm": "^1.0.0",
+    "@zerotal/auth": "^1.0.0",
+    "@zerotal/queue": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@zerotal/orm": {
+      "optional": true
+    },
+    "@zerotal/auth": {
+      "optional": true
+    },
+    "@zerotal/queue": {
+      "optional": true
+    }
+  },
+  "description": "Auto-generated admin panel (resources, tables, forms, widgets) for Zerotal apps.",
+  "keywords": [
+    "zerotal",
+    "bun",
+    "typescript",
+    "framework",
+    "admin",
+    "crud",
+    "panel"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zerotaldev/zerotal.git",
+    "directory": "packages/admin"
+  },
+  "homepage": "https://github.com/zerotaldev/zerotal/tree/main/packages/admin#readme",
+  "bugs": "https://github.com/zerotaldev/zerotal/issues"
+}

package/src/Cluster.ts

@@ -0,0 +1,50 @@
+/**
+ * Cluster — a named section of the panel that owns a group of resources and
+ * pages, giving them a shared URL segment and a single sidebar entry.
+ *
+ * A panel with thirty resources spread across three business areas is easier to
+ * navigate as three clusters than as one long list. Members declare which
+ * cluster they belong to; the panel does the rest:
+ *
+ *   export class ShopCluster extends Cluster {
+ *     static override slug = "shop";
+ *     static override title = "Shop";
+ *     static override navigationIcon = "collection";
+ *   }
+ *
+ *   export class ProductResource extends Resource {
+ *     static override cluster = ShopCluster;   // → /admin/shop/products
+ *   }
+ *
+ * The cluster's own `ability` gates the whole section: deny it and every member
+ * disappears from the sidebar and refuses its route, without each member having
+ * to repeat the check.
+ */
+export abstract class Cluster {
+  /** URL segment the cluster's members live under. */
+  static slug: string;
+  /** Heading shown for the cluster in navigation and breadcrumbs. */
+  static title: string;
+  /** Sidebar label, when it should differ from the title. */
+  static navigationLabel?: string;
+  /** Navigation icon key (see `ui/icons.ts`). */
+  static navigationIcon = "layout-grid";
+  /** Optional sidebar group the cluster itself sits in. */
+  static navigationGroup?: string;
+  /** Sort order within the sidebar (lower = higher). */
+  static navigationSort = 0;
+  /** Ability gating the whole cluster, checked for the entry and every route. */
+  static ability?: string;
+
+  static getNavigationLabel(): string {
+    return this.navigationLabel ?? this.title;
+  }
+
+  /** The cluster's URL prefix under a panel base. */
+  static url(base: string): string {
+    return `${base}/${this.slug}`;
+  }
+}
+
+/** A Cluster subclass (used by its static surface — never instantiated). */
+export type ClusterClass = typeof Cluster;