@zerotal/admin 1.0.0

package/src/support/hostPage.ts

@@ -0,0 +1,30 @@
+/**
+ * Put a page inside the panel's chrome without touching the class that was
+ * handed over.
+ *
+ * A contributed page is owned by the package that wrote it, and that package may
+ * mount the same class somewhere else — its own standalone panel, say. Assigning
+ * `PageClass.layout = AdminLayout` would reach across and change it there too, so
+ * the panel hosts a *subclass* instead and leaves the original alone.
+ *
+ * The subclass keeps the original's name because Flow's component registry is
+ * keyed by constructor name: the browser sends that name back with every action
+ * frame, and an anonymous class would break the round-trip. Names being the key
+ * also means a single class can only be mounted under one route at a time — a
+ * page that wants to appear in two panels needs a distinct class per panel.
+ *
+ * Decorator metadata (`@expose`, `@url`, `@on`, …) is collected by walking the
+ * prototype chain, so it inherits into the subclass and interactivity survives.
+ */
+import { AdminLayout } from "../ui/AdminLayout.tsx";
+import type { PanelPageClass } from "../plugin.ts";
+
+export function hostedPage(PageClass: PanelPageClass): PanelPageClass {
+  if ((PageClass as { layout?: unknown }).layout === AdminLayout) return PageClass;
+
+  const Hosted = class extends PageClass {
+    static layout = AdminLayout;
+  };
+  Object.defineProperty(Hosted, "name", { value: PageClass.name, configurable: true });
+  return Hosted;
+}

package/src/table/Column.ts

@@ -0,0 +1,353 @@
+import type { HtmlNode } from "@zerotal/flow";
+
+/**
+ * Fluent table-column builder.
+ *
+ *   text("name").label("Full name").sortable().searchable()
+ *   text("status").badge((v) => v === "active" ? "success" : "muted")
+ *   text("created_at").since()
+ *
+ * A `Column` is a declarative description; the list page turns it into a
+ * `@zerotal/flow-ui` `TableColumn` (with a cell renderer) at render time.
+ */
+
+export type CellAlign = "start" | "center" | "end";
+export type BadgeTone = "default" | "primary" | "success" | "muted" | "destructive";
+/** Display style: text, inline toggle/select/text-input, image, color swatch, boolean icon. */
+export type ColumnKind = "text" | "toggle" | "select" | "input" | "image" | "color" | "icon";
+
+export interface ColumnOption {
+  value: string;
+  label: string;
+}
+
+/** A column summary aggregate — a footer total, average, count or range. */
+export type SummaryKind = "sum" | "avg" | "count" | "min" | "max" | "range";
+
+export interface ColumnSummary {
+  kind: SummaryKind;
+  label?: string | undefined;
+  /** Format a numeric result (e.g. currency). */
+  format?: ((value: number) => string) | undefined;
+}
+
+/** A computed summary line, ready to render. */
+export interface SummaryResult {
+  label: string;
+  text: string;
+}
+
+export interface RenderableCell {
+  /** Pre-escaped/plain text, or a badge descriptor. */
+  text: string;
+  badge?: BadgeTone | undefined;
+}
+
+export class Column {
+  /** @internal */ _key: string;
+  /** @internal Database column for query ops (search/sort); defaults to `_key`. */
+  _column?: string;
+  /** @internal */ _label?: string;
+  /** @internal */ _kind: ColumnKind = "text";
+  /** @internal */ _sortable = false;
+  /** @internal */ _searchable = false;
+  /** @internal Offers a filter box in the table header. */ _filterable = false;
+  /** @internal */ _copyable = false;
+  /** @internal Included in CSV exports unless switched off. */ _exportable = true;
+  /** @internal */ _circular = false;
+  /** @internal */ _options?: ColumnOption[];
+  /** @internal */ _inputType = "text";
+  /** @internal */ _align: CellAlign = "start";
+  /** @internal */ _format?: (value: unknown, row: Record<string, unknown>) => string;
+  /** @internal A custom renderer, replacing every built-in cell kind. */
+  _render?: (value: unknown, row: Record<string, unknown>) => HtmlNode | string;
+  /** @internal */ _badge?: (value: unknown, row: Record<string, unknown>) => BadgeTone | null;
+  /** @internal */ _summaries: ColumnSummary[] = [];
+
+  constructor(key: string) {
+    this._key = key;
+  }
+
+  static make(key: string): Column {
+    return new Column(key);
+  }
+
+  /** Human label for the header. Defaults to a title-cased key. */
+  label(label: string): this {
+    this._label = label;
+    return this;
+  }
+
+  /**
+   * The database column to query for search / sort / inline-edit, when it differs
+   * from the cell key. Use when the model exposes a camelCase accessor over a
+   * snake_case column: `text("authorName").column("author_name")`. The cell still
+   * reads `row[key]` (the accessor); only the SQL uses this column.
+   */
+  column(name: string): this {
+    this._column = name;
+    return this;
+  }
+
+  /** The database column for query operations (defaults to the cell key). */
+  getColumn(): string {
+    return this._column ?? this._key;
+  }
+
+  /** Allow clicking the header to sort by this column (URL-driven). */
+  sortable(value = true): this {
+    this._sortable = value;
+    return this;
+  }
+
+  /** Include this column in the list page's search. */
+  searchable(value = true): this {
+    this._searchable = value;
+    return this;
+  }
+
+  /**
+   * Give this column its own filter box in the table header.
+   *
+   * The list page derives the control from 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 beyond this call. Header filters write into
+   * the same `?filters=` parameter as declared filters and compose with tabs,
+   * search, sorting and pagination the same way.
+   */
+  filterable(value = true): this {
+    this._filterable = value;
+    return this;
+  }
+
+  /** Horizontal alignment of the cell content. */
+  align(align: CellAlign): this {
+    this._align = align;
+    return this;
+  }
+
+  /** Custom value formatter (e.g. dates, currency). */
+  format(fn: (value: unknown, row: Record<string, unknown>) => string): this {
+    this._format = fn;
+    return this;
+  }
+
+  /** Render the value as a colored badge; return `null` to fall back to text. */
+  badge(fn: (value: unknown, row: Record<string, unknown>) => BadgeTone | null): this {
+    this._badge = fn;
+    return this;
+  }
+
+  /** Inline boolean toggle — flips the column on the record when clicked. */
+  toggle(): this {
+    this._kind = "toggle";
+    return this;
+  }
+
+  /** Render the value as an image (avatar / thumbnail). */
+  image(): this {
+    this._kind = "image";
+    return this;
+  }
+
+  /** Round image (avatar style). */
+  circular(value = true): this {
+    this._circular = value;
+    return this;
+  }
+
+  /** Render the value as a color swatch + hex. */
+  color(): this {
+    this._kind = "color";
+    return this;
+  }
+
+  /** Render a boolean as a check / cross icon. */
+  icon(): this {
+    this._kind = "icon";
+    return this;
+  }
+
+  /** Inline single-choice select — saves the chosen value on change. */
+  editSelect(options: Record<string, string> | ColumnOption[]): this {
+    this._kind = "select";
+    this._options = Array.isArray(options)
+      ? options
+      : Object.entries(options).map(([value, label]) => ({ value, label }));
+    return this;
+  }
+
+  /** Inline text input — saves on change/blur. */
+  editText(type = "text"): this {
+    this._kind = "input";
+    this._inputType = type;
+    return this;
+  }
+
+  /** Show a copy-to-clipboard affordance on the cell. */
+  copyable(value = true): this {
+    this._copyable = value;
+    return this;
+  }
+
+  // ── Summaries ───────────────────────────────────────────────────────────────
+
+  /** Attach one or more summary aggregates, shown in the table/group footer. */
+  summarize(summary: ColumnSummary | ColumnSummary[]): this {
+    this._summaries = Array.isArray(summary) ? summary : [summary];
+    return this;
+  }
+
+  /** Sum the column (shorthand for `summarize({ kind: "sum" })`). */
+  sum(label?: string, format?: (n: number) => string): this {
+    this._summaries.push({ kind: "sum", label, format });
+    return this;
+  }
+
+  /** Average the column. */
+  avg(label?: string, format?: (n: number) => string): this {
+    this._summaries.push({ kind: "avg", label, format });
+    return this;
+  }
+
+  /** Count the rows. */
+  count(label?: string): this {
+    this._summaries.push({ kind: "count", label });
+    return this;
+  }
+
+  /** Min–max range of the column. */
+  range(label?: string, format?: (n: number) => string): this {
+    this._summaries.push({ kind: "range", label, format });
+    return this;
+  }
+
+  /** Whether this column has any summary aggregates. */
+  hasSummary(): boolean {
+    return this._summaries.length > 0;
+  }
+
+  /** Compute this column's summaries over a set of rows. */
+  computeSummaries(rows: Record<string, unknown>[]): SummaryResult[] {
+    return this._summaries.map((s) => {
+      const nums = rows.map((r) => Number(r[this._key])).filter((n) => Number.isFinite(n));
+      const fmt = s.format ?? ((n: number) => (Number.isInteger(n) ? String(n) : n.toFixed(2)));
+      switch (s.kind) {
+        case "count":
+          return { label: s.label ?? "Count", text: String(rows.length) };
+        case "sum":
+          return { label: s.label ?? "Sum", text: fmt(nums.reduce((a, b) => a + b, 0)) };
+        case "avg":
+          return {
+            label: s.label ?? "Average",
+            text: fmt(nums.length ? nums.reduce((a, b) => a + b, 0) / nums.length : 0),
+          };
+        case "min":
+          return { label: s.label ?? "Min", text: fmt(nums.length ? Math.min(...nums) : 0) };
+        case "max":
+          return { label: s.label ?? "Max", text: fmt(nums.length ? Math.max(...nums) : 0) };
+        case "range": {
+          const lo = nums.length ? Math.min(...nums) : 0;
+          const hi = nums.length ? Math.max(...nums) : 0;
+          return { label: s.label ?? "Range", text: `${fmt(lo)} – ${fmt(hi)}` };
+        }
+      }
+    });
+  }
+
+  /** Resolved header label. */
+  getLabel(): string {
+    return this._label ?? titleCase(this._key);
+  }
+
+  /** The raw cell value (for non-text column kinds the page renders itself). */
+  /**
+   * Whether this column may leave the panel in an export. Turn it off for
+   * anything that shouldn't land in a spreadsheet on someone's laptop.
+   */
+  exportable(value = true): this {
+    this._exportable = value;
+    return this;
+  }
+
+  /**
+   * Render this cell yourself, when no built-in kind fits — a sparkline, a
+   * progress bar, a stack of avatars.
+   *
+   *   text("health").render((v) => <HealthBar value={Number(v)} />)
+   *
+   * The renderer replaces the cell entirely, so `.format()` and `.badge()` no
+   * longer apply. Everything else about the column — its label, whether it
+   * sorts, whether it exports — still works, because those are the table's
+   * concerns rather than the cell's.
+   */
+  render(fn: (value: unknown, row: Record<string, unknown>) => HtmlNode | string): this {
+    this._render = fn;
+    return this;
+  }
+
+  raw(row: Record<string, unknown>): unknown {
+    return row[this._key];
+  }
+
+  /** Compute the display cell for a row. */
+  cell(row: Record<string, unknown>): RenderableCell {
+    const value = row[this._key];
+    const text = this._format ? this._format(value, row) : stringify(value);
+    const badge = this._badge ? (this._badge(value, row) ?? undefined) : undefined;
+    return { text, badge };
+  }
+}
+
+/** A text column — the one most columns are. */
+export function text(key: string): Column {
+  return Column.make(key);
+}
+
+/** Toggle column, editable in place without opening the record. */
+export function toggleColumn(key: string): Column {
+  return Column.make(key).toggle();
+}
+
+/** Image column — renders the value as a thumbnail. */
+export function imageColumn(key: string): Column {
+  return Column.make(key).image();
+}
+
+/** Color-swatch column. */
+export function colorColumn(key: string): Column {
+  return Column.make(key).color();
+}
+
+/** Boolean icon column — a tick or a cross rather than "true"/"false". */
+export function iconColumn(key: string): Column {
+  return Column.make(key).icon();
+}
+
+/** Select column, editable in place without opening the record. */
+export function selectColumn(
+  key: string,
+  options: Record<string, string> | ColumnOption[],
+): Column {
+  return Column.make(key).editSelect(options);
+}
+
+/** Text column, editable in place without opening the record. */
+export function textInputColumn(key: string): Column {
+  return Column.make(key).editText();
+}
+
+function stringify(value: unknown): string {
+  if (value === null || value === undefined) return "—";
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "boolean") return value ? "Yes" : "No";
+  return String(value);
+}
+
+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/Constraint.ts

@@ -0,0 +1,238 @@
+/**
+ * Constraints — the building blocks of the query-builder filter.
+ *
+ * A constraint names one thing a user may filter on and the operators that make
+ * sense for it, so the panel can offer "Title contains …" and "Total is greater
+ * than …" without the app writing either query:
+ *
+ *   queryBuilder("q").constraints([
+ *     textConstraint("title"),
+ *     numberConstraint("total").label("Order total"),
+ *     dateConstraint("created_at").label("Placed"),
+ *     selectConstraint("status").options({ paid: "Paid", refunded: "Refunded" }),
+ *     booleanConstraint("featured"),
+ *   ])
+ *
+ * Each constraint knows how to turn a chosen operator and value into query
+ * predicates, and applies them with either `AND` or `OR` so a rule can sit in
+ * either kind of group.
+ */
+import type { AdminQuery } from "../Resource.ts";
+
+export type ConstraintKind = "text" | "number" | "date" | "boolean" | "select";
+
+/** One comparison a constraint offers. */
+export interface ConstraintOperator {
+  value: string;
+  label: string;
+  /** True when the operator stands alone — "is empty" takes no value input. */
+  unary?: boolean;
+}
+
+export interface ConstraintOption {
+  value: string;
+  label: string;
+}
+
+/** Whether a rule joins what came before it with `AND` or `OR`. */
+export type Conjunction = "and" | "or";
+
+const TEXT_OPERATORS: ConstraintOperator[] = [
+  { value: "contains", label: "contains" },
+  { value: "not_contains", label: "does not contain" },
+  { value: "starts_with", label: "starts with" },
+  { value: "ends_with", label: "ends with" },
+  { value: "equals", label: "is" },
+  { value: "not_equals", label: "is not" },
+  { value: "is_empty", label: "is empty", unary: true },
+  { value: "is_not_empty", label: "is not empty", unary: true },
+];
+
+const NUMBER_OPERATORS: ConstraintOperator[] = [
+  { value: "equals", label: "is" },
+  { value: "not_equals", label: "is not" },
+  { value: "gt", label: "is greater than" },
+  { value: "gte", label: "is at least" },
+  { value: "lt", label: "is less than" },
+  { value: "lte", label: "is at most" },
+  { value: "is_empty", label: "is blank", unary: true },
+  { value: "is_not_empty", label: "is set", unary: true },
+];
+
+const DATE_OPERATORS: ConstraintOperator[] = [
+  { value: "equals", label: "is on" },
+  { value: "lt", label: "is before" },
+  { value: "gt", label: "is after" },
+  { value: "is_empty", label: "is blank", unary: true },
+  { value: "is_not_empty", label: "is set", unary: true },
+];
+
+const BOOLEAN_OPERATORS: ConstraintOperator[] = [
+  { value: "is_true", label: "is true", unary: true },
+  { value: "is_false", label: "is false", unary: true },
+];
+
+const SELECT_OPERATORS: ConstraintOperator[] = [
+  { value: "equals", label: "is" },
+  { value: "not_equals", label: "is not" },
+  { value: "is_empty", label: "is blank", unary: true },
+  { value: "is_not_empty", label: "is set", unary: true },
+];
+
+export class Constraint {
+  /** @internal */ _key: string;
+  /** @internal */ _kind: ConstraintKind;
+  /** @internal */ _label?: string;
+  /** @internal */ _column?: string;
+  /** @internal */ _options: ConstraintOption[] = [];
+
+  constructor(key: string, kind: ConstraintKind = "text") {
+    this._key = key;
+    this._kind = kind;
+  }
+
+  label(label: string): this {
+    this._label = label;
+    return this;
+  }
+
+  /** Database column to compare, when it differs from the constraint key. */
+  column(column: string): this {
+    this._column = column;
+    return this;
+  }
+
+  /** Choices for a select constraint — `{value: label}` map or `{value,label}[]`. */
+  options(options: Record<string, string> | ConstraintOption[]): this {
+    this._options = Array.isArray(options)
+      ? options
+      : Object.entries(options).map(([value, label]) => ({ value, label }));
+    return this;
+  }
+
+  getLabel(): string {
+    return this._label ?? titleCase(this._key);
+  }
+
+  getColumn(): string {
+    return this._column ?? this._key;
+  }
+
+  operators(): ConstraintOperator[] {
+    switch (this._kind) {
+      case "number":
+        return NUMBER_OPERATORS;
+      case "date":
+        return DATE_OPERATORS;
+      case "boolean":
+        return BOOLEAN_OPERATORS;
+      case "select":
+        return SELECT_OPERATORS;
+      default:
+        return TEXT_OPERATORS;
+    }
+  }
+
+  /** Whether `operator` stands alone, needing no value from the user. */
+  isUnary(operator: string): boolean {
+    return this.operators().find((o) => o.value === operator)?.unary === true;
+  }
+
+  /**
+   * Add this rule's predicates to `query`, joined by `conjunction`.
+   *
+   * Every branch picks between the `where*` and `orWhere*` families rather than
+   * emitting a bare `OR`, so a rule always combines with its siblings as one
+   * unit and never splits a surrounding scope.
+   */
+  apply(query: AdminQuery, operator: string, value: string, conjunction: Conjunction): AdminQuery {
+    const col = this.getColumn();
+    const or = conjunction === "or";
+    const q = query as AdminQuery &
+      Record<string, ((...args: unknown[]) => AdminQuery) | undefined>;
+    const call = (name: string, ...args: unknown[]): AdminQuery => {
+      const fn = q[name];
+      // The query surface is intentionally loose (resources run under partial
+      // mocks in tests); an unsupported method leaves the query unfiltered
+      // rather than throwing mid-render.
+      return typeof fn === "function" ? fn.apply(query, args) : query;
+    };
+    const like = (pattern: string): AdminQuery =>
+      call(or ? "orWhereLike" : "whereLike", col, pattern);
+    const compare = (op: string, v: unknown): AdminQuery =>
+      or ? call("orWhere", col, op, v) : query.where(col, op, v);
+
+    switch (operator) {
+      case "contains":
+        return like(`%${value}%`);
+      case "not_contains":
+        return call(or ? "orWhereNotLike" : "whereNotLike", col, `%${value}%`);
+      case "starts_with":
+        return like(`${value}%`);
+      case "ends_with":
+        return like(`%${value}`);
+      case "equals":
+        return compare("=", this._cast(value));
+      case "not_equals":
+        return compare("!=", this._cast(value));
+      case "gt":
+        return compare(">", this._cast(value));
+      case "gte":
+        return compare(">=", this._cast(value));
+      case "lt":
+        return compare("<", this._cast(value));
+      case "lte":
+        return compare("<=", this._cast(value));
+      case "is_true":
+        return compare("=", true);
+      case "is_false":
+        return compare("=", false);
+      case "is_empty":
+        return call(or ? "orWhereNull" : "whereNull", col);
+      case "is_not_empty":
+        return call(or ? "orWhereNotNull" : "whereNotNull", col);
+      default:
+        return query;
+    }
+  }
+
+  /** Coerce the submitted string to the type the column actually holds. */
+  private _cast(value: string): unknown {
+    if (this._kind !== "number") return value;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : value;
+  }
+}
+
+/** Free-text constraint — contains / starts with / is / is empty. */
+export function textConstraint(key: string): Constraint {
+  return new Constraint(key, "text");
+}
+
+/** Numeric constraint — comparisons and ranges. */
+export function numberConstraint(key: string): Constraint {
+  return new Constraint(key, "number");
+}
+
+/** Date constraint — on / before / after. */
+export function dateConstraint(key: string): Constraint {
+  return new Constraint(key, "date");
+}
+
+/** Boolean constraint — is true / is false. */
+export function booleanConstraint(key: string): Constraint {
+  return new Constraint(key, "boolean");
+}
+
+/** Fixed-choice constraint — is / is not one of the declared options. */
+export function selectConstraint(key: string): Constraint {
+  return new Constraint(key, "select");
+}
+
+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();
+}