@zerotal/admin 1.0.0

package/src/table/Filter.ts

@@ -0,0 +1,275 @@
+/**
+ * Table filters. A filter scopes the list query and
+ * its active value lives in the URL (`?filters=…`), so it composes cleanly with
+ * search, sort, tabs, and pagination — every one of which is URL-driven.
+ *
+ *   selectFilter("status").options({ active: "Active", archived: "Archived" })
+ *   ternaryFilter("verified")
+ *     .label("Email verified")
+ *     .query((q, v) => (v === "1" ? q.whereNotNull!("email_verified_at") : q.whereNull!("email_verified_at")))
+ */
+import type { AdminQuery } from "../Resource.ts";
+import type { Conjunction, Constraint } from "./Constraint.ts";
+
+export type FilterType = "select" | "ternary" | "builder" | "text";
+
+/**
+ * A node in a query-builder filter's rule tree: either one comparison, or a
+ * group combining several with `AND`/`OR`. Groups nest, so "status is paid AND
+ * (total > 100 OR customer contains acme)" is expressible.
+ */
+export type QueryRule =
+  | { type: "rule"; constraint: string; operator: string; value?: string }
+  | { type: "group"; operator: Conjunction; rules: QueryRule[] };
+
+/** Parse the JSON a query-builder filter stores in the URL. Invalid input filters nothing. */
+export function parseRuleTree(value: string): QueryRule | null {
+  if (!value) return null;
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    return isRule(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function isRule(node: unknown): node is QueryRule {
+  if (!node || typeof node !== "object") return false;
+  const n = node as Record<string, unknown>;
+  if (n["type"] === "rule")
+    return typeof n["constraint"] === "string" && typeof n["operator"] === "string";
+  if (n["type"] === "group") return Array.isArray(n["rules"]) && n["rules"].every(isRule);
+  return false;
+}
+
+/**
+ * A short human summary of a rule tree, for the active-filter chips.
+ *
+ * "Advanced filter: 3 rules" tells someone their list is narrowed and by roughly
+ * how much; the builder itself shows the detail. One rule gets named outright,
+ * since that is the common case and the label fits.
+ */
+export function describeRuleTree(
+  node: QueryRule | null,
+  filter?: { _constraints: Constraint[] },
+): string {
+  if (!node) return "none";
+  const rules: Extract<QueryRule, { type: "rule" }>[] = [];
+  const walk = (n: QueryRule): void => {
+    if (n.type === "rule") rules.push(n);
+    else n.rules.forEach(walk);
+  };
+  walk(node);
+
+  if (rules.length === 0) return "none";
+  if (rules.length === 1) {
+    const rule = rules[0]!;
+    const constraint = filter?._constraints.find((c) => c._key === rule.constraint);
+    const label = constraint?.getLabel() ?? rule.constraint;
+    const operator =
+      constraint?.operators().find((o) => o.value === rule.operator)?.label ?? rule.operator;
+    return [label, operator, rule.value].filter(Boolean).join(" ");
+  }
+  return `${rules.length} rules`;
+}
+
+/** Does this tree actually constrain anything? An empty group is a no-op. */
+export function ruleTreeIsEmpty(node: QueryRule | null): boolean {
+  if (!node) return true;
+  if (node.type === "rule") return false;
+  return node.rules.every(ruleTreeIsEmpty);
+}
+
+export interface FilterOption {
+  value: string;
+  label: string;
+}
+
+export type FilterApply = (query: AdminQuery, value: string) => AdminQuery;
+
+export class Filter {
+  /** @internal */ _key: string;
+  /** @internal */ _label?: string;
+  /** @internal */ _type: FilterType;
+  /** @internal */ _column?: string;
+  /** @internal */ _options: FilterOption[] = [];
+  /** @internal */ _apply?: FilterApply;
+  /** @internal */ _trueLabel = "Yes";
+  /** @internal */ _falseLabel = "No";
+  /** @internal Available comparisons, for a query-builder filter. */ _constraints: Constraint[] =
+    [];
+
+  constructor(key: string, type: FilterType = "select") {
+    this._key = key;
+    this._type = type;
+  }
+
+  static make(key: string): Filter {
+    return new Filter(key);
+  }
+
+  label(label: string): this {
+    this._label = label;
+    return this;
+  }
+
+  /** Column to filter on (defaults to the filter key). */
+  column(column: string): this {
+    this._column = column;
+    return this;
+  }
+
+  /** Options for a select filter — `{value: label}` map or `{value,label}[]`. */
+  options(options: Record<string, string> | FilterOption[]): this {
+    this._options = Array.isArray(options)
+      ? options
+      : Object.entries(options).map(([value, label]) => ({ value, label }));
+    return this;
+  }
+
+  /** Labels for the two states of a ternary filter. */
+  labels(trueLabel: string, falseLabel: string): this {
+    this._trueLabel = trueLabel;
+    this._falseLabel = falseLabel;
+    return this;
+  }
+
+  /** Comparisons a query-builder filter offers. */
+  constraints(constraints: Constraint[]): this {
+    this._constraints = constraints;
+    return this;
+  }
+
+  /** Custom query scope; receives the raw active value. */
+  query(fn: FilterApply): this {
+    this._apply = fn;
+    return this;
+  }
+
+  getLabel(): string {
+    return this._label ?? titleCase(this._key);
+  }
+
+  /** The selectable options including the implicit "all"/ternary states. */
+  choices(): FilterOption[] {
+    if (this._type === "ternary") {
+      return [
+        { value: "1", label: this._trueLabel },
+        { value: "0", label: this._falseLabel },
+      ];
+    }
+    return this._options;
+  }
+
+  /** Apply this filter's scope for a chosen value. */
+  apply(query: AdminQuery, value: string): AdminQuery {
+    if (this._apply) return this._apply(query, value);
+    if (this._type === "builder") return this._applyRuleTree(query, value);
+    const col = this._column ?? this._key;
+    if (this._type === "ternary") return query.where(col, value === "1");
+    // A typed-in filter matches anywhere in the value: someone typing three
+    // letters into a header box is looking for a substring, not an exact row.
+    if (this._type === "text") return query.where(col, "like", `%${value}%`);
+    return query.where(col, value);
+  }
+
+  /**
+   * Apply a rule tree, wrapping the whole thing in one group.
+   *
+   * The wrapper matters: without it an `OR` at the top level would break out of
+   * whatever scope the list page already applied — a tab, a parent record, a
+   * soft-delete filter — and widen the result set past what the user is allowed
+   * to see. Grouping keeps the tree a single `AND`ed unit.
+   */
+  private _applyRuleTree(query: AdminQuery, value: string): AdminQuery {
+    const tree = parseRuleTree(value);
+    if (ruleTreeIsEmpty(tree)) return query;
+    const byKey = new Map(this._constraints.map((c) => [c._key, c]));
+    const group: Extract<QueryRule, { type: "group" }> =
+      tree!.type === "group" ? tree! : { type: "group", operator: "and", rules: [tree!] };
+
+    // Nothing survives validation — an unknown constraint, a rule still waiting
+    // for its value. Emitting the wrapper anyway would leave an empty `WHERE ()`.
+    if (!hasApplicableRule(group, byKey)) return query;
+
+    return query.where((sub: AdminQuery) => applyGroup(sub, group, byKey));
+  }
+}
+
+/** Whether any rule in this subtree names a known constraint and is complete. */
+function hasApplicableRule(node: QueryRule, byKey: Map<string, Constraint>): boolean {
+  if (node.type === "group") return node.rules.some((r) => hasApplicableRule(r, byKey));
+  const constraint = byKey.get(node.constraint);
+  if (!constraint) return false;
+  return constraint.isUnary(node.operator) || Boolean(node.value);
+}
+
+/** Add a group's rules to `query`, each joined by the group's operator. */
+function applyGroup(
+  query: AdminQuery,
+  group: Extract<QueryRule, { type: "group" }>,
+  byKey: Map<string, Constraint>,
+): void {
+  let first = true;
+  for (const rule of group.rules) {
+    if (ruleTreeIsEmpty(rule)) continue;
+    // The first predicate in a group always joins with AND — there is nothing
+    // yet for it to be an alternative to.
+    const conjunction: Conjunction = first ? "and" : group.operator;
+
+    if (rule.type === "group") {
+      // Same reasoning as the outer wrapper: skip a subgroup with nothing to say.
+      if (!hasApplicableRule(rule, byKey)) continue;
+      const nest = (conjunction === "or" ? query.orWhere : query.where) as
+        ((fn: (sub: AdminQuery) => void) => AdminQuery) | undefined;
+      if (typeof nest !== "function") continue;
+      nest.call(query, (sub: AdminQuery) => applyGroup(sub, rule, byKey));
+    } else {
+      const constraint = byKey.get(rule.constraint);
+      // An unknown constraint is a URL naming a column the resource never
+      // offered — drop it rather than filtering on attacker-chosen input.
+      if (!constraint) continue;
+      if (!constraint.isUnary(rule.operator) && !rule.value) continue;
+      constraint.apply(query, rule.operator, rule.value ?? "", conjunction);
+    }
+    first = false;
+  }
+}
+
+/** Single-choice dropdown filter. */
+export function selectFilter(key: string): Filter {
+  return new Filter(key, "select");
+}
+
+/** Free-text filter, matching anywhere in the column. */
+export function textFilter(key: string): Filter {
+  return new Filter(key, "text");
+}
+
+/** Three-state filter — all / yes / no. */
+export function ternaryFilter(key: string): Filter {
+  return new Filter(key, "ternary");
+}
+
+/**
+ * A build-your-own filter: the user stacks comparisons and nests AND/OR groups
+ * rather than picking from fixed choices. Declare what may be compared with
+ * {@link Filter.constraints}.
+ *
+ *   queryBuilder("q").constraints([
+ *     textConstraint("name"),
+ *     numberConstraint("total"),
+ *     selectConstraint("status").options({ open: "Open", closed: "Closed" }),
+ *   ])
+ */
+export function queryBuilder(key: string): Filter {
+  return new Filter(key, "builder");
+}
+
+function titleCase(key: string): string {
+  return key
+    .replace(/[_-]+/g, " ")
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .replace(/\b\w/g, (c) => c.toUpperCase())
+    .trim();
+}

package/src/table/Group.ts

@@ -0,0 +1,73 @@
+/**
+ * Row grouping for the list table. A resource lists
+ * the groupings it supports via `static groups()`; the list page offers a
+ * "Group by" menu and renders a header row before each group's rows.
+ *
+ *   static groups() {
+ *     return [
+ *       group("status"),
+ *       group("created_at").label("Joined").getTitleUsing((r) => formatMonth(r.created_at)),
+ *     ];
+ *   }
+ *   static defaultGroup = "status";
+ */
+export class Group {
+  /** @internal */ _column: string;
+  /** @internal */ _label?: string;
+  /** @internal */ _getTitle?: (row: Record<string, unknown>) => string;
+  /** @internal */ _collapsible = false;
+
+  constructor(column: string) {
+    this._column = column;
+  }
+
+  static make(column: string): Group {
+    return new Group(column);
+  }
+
+  /** Heading label for the grouping (defaults to a title-cased column). */
+  label(label: string): this {
+    this._label = label;
+    return this;
+  }
+
+  /** Derive each group's title from a row (e.g. bucket a date into a month). */
+  getTitleUsing(fn: (row: Record<string, unknown>) => string): this {
+    this._getTitle = fn;
+    return this;
+  }
+
+  collapsible(value = true): this {
+    this._collapsible = value;
+    return this;
+  }
+
+  /** The grouping's column key (also its stable identifier). */
+  getColumn(): string {
+    return this._column;
+  }
+
+  getLabel(): string {
+    return this._label ?? titleCase(this._column);
+  }
+
+  /** The group title for a given row. */
+  titleFor(row: Record<string, unknown>): string {
+    if (this._getTitle) return this._getTitle(row);
+    const v = row[this._column];
+    return v === null || v === undefined || v === "" ? "—" : String(v);
+  }
+}
+
+/** Group the list's rows under a column's value. */
+export function group(column: string): Group {
+  return new Group(column);
+}
+
+function titleCase(key: string): string {
+  return key
+    .replace(/[_-]+/g, " ")
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .replace(/\b\w/g, (c) => c.toUpperCase())
+    .trim();
+}

package/src/table/Tab.ts

@@ -0,0 +1,77 @@
+/**
+ * List-page tabs — filter presets shown above the table. Each tab scopes the
+ * query and can show a badge count.
+ *
+ *   tab("all").label("All"),
+ *   tab("verified").label("Verified").badge().modifyQuery((q) => q.whereNotNull("email_verified_at")),
+ *   tab("unverified").label("Unverified").badge("!" ).badgeColor("warning")
+ *     .modifyQuery((q) => q.whereNull("email_verified_at")),
+ */
+import type { QueryModifier } from "../Resource.ts";
+import type { BadgeTone } from "./Column.ts";
+
+export class Tab {
+  /** @internal */ _key: string;
+  /** @internal */ _label?: string;
+  /** @internal */ _icon?: string;
+  /** @internal */ _badge = false;
+  /** @internal */ _badgeValue?: number | string;
+  /** @internal */ _badgeTone: BadgeTone = "muted";
+  /** @internal */ _modify?: QueryModifier;
+
+  constructor(key: string) {
+    this._key = key;
+  }
+
+  static make(key: string): Tab {
+    return new Tab(key);
+  }
+
+  label(label: string): this {
+    this._label = label;
+    return this;
+  }
+
+  icon(name: string): this {
+    this._icon = name;
+    return this;
+  }
+
+  /**
+   * Show a count badge. With no argument the panel counts matching records;
+   * pass a value to show a fixed badge instead.
+   */
+  badge(value?: number | string): this {
+    this._badge = true;
+    if (value !== undefined) this._badgeValue = value;
+    return this;
+  }
+
+  badgeColor(tone: BadgeTone): this {
+    this._badgeTone = tone;
+    return this;
+  }
+
+  /** Scope the table query for this tab. */
+  modifyQuery(fn: QueryModifier): this {
+    this._modify = fn;
+    return this;
+  }
+
+  getLabel(): string {
+    return this._label ?? titleCase(this._key);
+  }
+}
+
+/** A filter preset shown as a tab above the list. */
+export function tab(key: string): Tab {
+  return new Tab(key);
+}
+
+function titleCase(key: string): string {
+  return key
+    .replace(/[_-]+/g, " ")
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .replace(/\b\w/g, (c) => c.toUpperCase())
+    .trim();
+}

package/src/testing.ts

@@ -0,0 +1,121 @@
+/**
+ * Admin testing helpers — thin, resource-aware wrappers over Flow's in-process
+ * test harness ({@link FlowTest}). They mount a resource's List / View / Form
+ * page without the route boilerplate, and add assertions phrased in admin terms
+ * (columns, records, actions, fields).
+ *
+ * @example
+ * import { AdminTest, assertHasColumn, assertHasAction } from "@zerotal/admin/testing";
+ *
+ * const t = await AdminTest.list(UserResource);
+ * assertHasColumn(t, UserResource, "email");
+ * assertHasAction(t, "Create");
+ * t.assertSee("ada@example.com");
+ *
+ * const form = await AdminTest.form(UserResource, "create");
+ * await form.set("form", { name: "" });
+ * await form.call("save");
+ * form.assertHasErrors("name");
+ */
+import { FlowTest } from "@zerotal/flow/testing";
+import type { Component } from "@zerotal/flow";
+import type { ResourceClass } from "./Panel.ts";
+import { Panel } from "./Panel.ts";
+import type { PanelInstance } from "./PanelInstance.ts";
+import type { FieldMode } from "./form/index.ts";
+import { makeResourceForm, flattenFields } from "./form/index.ts";
+import { makeResourceListPage } from "./pages/ResourceListPage.tsx";
+import { makeRecordViewPage } from "./pages/RecordViewPage.tsx";
+import { ResourceFormPage, registerResourceForm } from "./pages/ResourceFormPage.tsx";
+
+/** A mounted Flow test for any admin page. */
+export type AdminPageTest = FlowTest<Component>;
+
+export const AdminTest = {
+  /** Mount a resource's List page. `props` seed `@url` state (search/sort/page/…). */
+  async list(
+    resource: ResourceClass,
+    props: Record<string, unknown> = {},
+    panel: PanelInstance = Panel.default(),
+  ): Promise<AdminPageTest> {
+    return FlowTest.mount(
+      makeResourceListPage(resource, panel) as unknown as new () => Component,
+      props as Partial<Component>,
+    );
+  },
+
+  /** Mount a resource's View page for a record id. */
+  async view(
+    resource: ResourceClass,
+    recordId: string | number,
+    panel: PanelInstance = Panel.default(),
+  ): Promise<AdminPageTest> {
+    return FlowTest.mount(
+      makeRecordViewPage(resource, panel) as unknown as new () => Component,
+      {
+        recordId: String(recordId),
+      } as Partial<Component>,
+    );
+  },
+
+  /**
+   * Mount a resource's Create/Edit form page. Registers the resource's form
+   * config (as the provider does) so the shared page can resolve it by slug.
+   */
+  async form(
+    resource: ResourceClass,
+    mode: FieldMode = "create",
+    props: Record<string, unknown> = {},
+    panel: PanelInstance = Panel.default(),
+  ): Promise<AdminPageTest> {
+    const slug = resource.getSlug();
+    const model = resource.getModelName();
+    const fields = resource.form();
+    const create = makeResourceForm(fields, "create", `${model}CreateTestForm`);
+    const edit = makeResourceForm(fields, "edit", `${model}EditTestForm`);
+    registerResourceForm(panel.id, slug, {
+      resource,
+      create: { FormClass: create.FormClass, fields: create.fields },
+      edit: { FormClass: edit.FormClass, fields: edit.fields },
+    });
+    return FlowTest.mount(
+      ResourceFormPage as unknown as new () => Component,
+      {
+        slug,
+        mode,
+        panelId: panel.id,
+        ...props,
+      } as Partial<Component>,
+    );
+  },
+};
+
+// ── Resource-aware assertions ───────────────────────────────────────────────
+
+/** Assert a column's header is rendered (by key → its resolved label). */
+export function assertHasColumn(t: AdminPageTest, resource: ResourceClass, key: string): void {
+  const col = resource.columns().find((c) => c._key === key);
+  t.assertSee(col ? col.getLabel() : key);
+}
+
+/** Assert an action label is present on the page. */
+export function assertHasAction(t: AdminPageTest, label: string): void {
+  t.assertSee(label);
+}
+
+/** Assert a form field's label is rendered (by key → its resolved label). */
+export function assertHasField(t: AdminPageTest, resource: ResourceClass, key: string): void {
+  const field = flattenFields(resource.form()).find((f) => f._key === key);
+  t.assertSee(field ? field.getLabel() : key);
+}
+
+/** Assert the rendered HTML contains a record's title (a row is present). */
+export function assertSeesRecord(
+  t: AdminPageTest,
+  resource: ResourceClass,
+  record: Record<string, unknown>,
+): void {
+  t.assertSee(resource.recordTitle(record));
+}
+
+export { FlowTest };

package/src/theme.ts

@@ -0,0 +1,70 @@
+/**
+ * Admin theme — the `<head>` payload that makes the panel look good in both
+ * light and dark mode with zero build step.
+ *
+ * The tokens themselves live in `@zerotal/flow-ui`, because they are the kit's
+ * tokens: flow-ui components are written against `bg-primary`,
+ * `text-muted-foreground`, `border-input` and friends, so whoever defines those
+ * variables themes the components. The admin is one consumer of that theme and
+ * the monitor is another; keeping the palette in the kit is what stops the two
+ * from drifting apart.
+ *
+ * This module is the admin's thin wrapper over it: the same head payload, under
+ * the names the panel's own config uses.
+ */
+import {
+  flowUiHead,
+  flowTokensCss,
+  flowTailwindConfig,
+  THEME_STORAGE_KEY as FLOW_THEME_STORAGE_KEY,
+  THEME_TOGGLE_SCRIPT as FLOW_THEME_TOGGLE_SCRIPT,
+} from "@zerotal/flow-ui";
+
+/** localStorage key the toggle and the no-flash script share. */
+export const THEME_STORAGE_KEY = FLOW_THEME_STORAGE_KEY;
+
+/** Client helpers (theme toggle + copy-to-clipboard), eval-free. */
+export const THEME_TOGGLE_SCRIPT = FLOW_THEME_TOGGLE_SCRIPT;
+
+/**
+ * Styling source for the admin shell. By default the Tailwind **Play CDN** themes
+ * everything with zero build step. To ship a real build, point `stylesheet` at
+ * your compiled CSS (built from your own `tailwind.config` — reuse
+ * {@link adminTailwindConfig} + {@link adminTokensCss}); the CDN is then dropped
+ * automatically (set `cdn: true` to keep both during migration).
+ */
+export interface AdminThemeConfig {
+  /** A prebuilt stylesheet URL/path to link instead of (or alongside) the CDN. */
+  stylesheet?: string;
+  /** Keep loading the Tailwind Play CDN. Defaults to `true` unless `stylesheet` is set. */
+  cdn?: boolean;
+  /** Extra design-token CSS appended after the defaults (override `:root` / `.dark`). */
+  tokensCss?: string;
+  /** Skip the bundled Google Fonts links (e.g. you self-host Inter). */
+  noFonts?: boolean;
+}
+
+/** The design-token CSS (`:root` + `.dark` custom properties + base styles). */
+export function adminTokensCss(): string {
+  return flowTokensCss();
+}
+
+/**
+ * The Tailwind config (token → CSS-var mappings, fonts, radius, animations) as a
+ * JS string. Reuse it in your own `tailwind.config.js` when building real CSS so a
+ * compiled build matches the CDN look exactly.
+ */
+export function adminTailwindConfig(): string {
+  return flowTailwindConfig();
+}
+
+/**
+ * Full `<head>` markup for the admin shell. Inject as `Layout.head`.
+ *
+ * With no `theme` (or `theme.cdn !== false`) it loads the Tailwind Play CDN. Set
+ * `theme.stylesheet` to link a prebuilt CSS file and drop the CDN — only this
+ * file's wiring changes; pages stay identical.
+ */
+export function adminHead(title = "Admin", theme: AdminThemeConfig = {}): string {
+  return flowUiHead(title, theme);
+}