@zerotal/admin 1.0.0

package/src/pages/ConsolePage.tsx

@@ -0,0 +1,324 @@
+/** @jsxImportSource @zerotal/flow */
+// Renders a ConsoleContribution: tabbed tables with row and header actions.
+// The active tab lives in an `@url` prop so a console is linkable and survives a
+// refresh; actions re-resolve the rows afterwards so the table reflects what the
+// action just did without a full navigation.
+
+import { Component, url, expose } from "@zerotal/flow";
+import type { HtmlNode } from "@zerotal/flow";
+import { Table } from "@zerotal/flow-ui";
+import type { TableColumn } from "@zerotal/flow-ui";
+import { AdminLayout, makeAdminLayout } from "../ui/AdminLayout.tsx";
+import { Icon } from "../ui/icons.tsx";
+import { Panel } from "../Panel.ts";
+import type { PanelInstance } from "../PanelInstance.ts";
+import { AdminForbiddenError } from "../support/authorize.ts";
+import type {
+  ConsoleColumn,
+  ConsoleContribution,
+  ConsoleHeaderAction,
+  ConsoleRow,
+  ConsoleTab,
+} from "../plugin.ts";
+import type { BadgeTone } from "../table/Column.ts";
+
+const BADGE_TONE: Record<BadgeTone, string> = {
+  default: "bg-secondary text-secondary-foreground",
+  primary: "bg-primary/10 text-primary ring-1 ring-inset ring-primary/20",
+  success: "bg-success/10 text-success ring-1 ring-inset ring-success/20",
+  muted: "bg-muted text-muted-foreground",
+  destructive: "bg-destructive/10 text-destructive ring-1 ring-inset ring-destructive/20",
+};
+
+const ALIGN: Record<string, string> = {
+  start: "text-left",
+  center: "text-center",
+  end: "text-right tabular-nums",
+};
+
+export class ConsolePage extends Component {
+  static layout = AdminLayout;
+
+  /** Set on the per-console subclass by {@link makeConsolePage}. */
+  static console: ConsoleContribution;
+  /** The panel this console belongs to — set by {@link makeConsolePage}. */
+  static panel: PanelInstance;
+
+  @url tab = "";
+
+  /** Rows for the active tab, resolved on mount and after every action. */
+  @expose rows: ConsoleRow[] = [];
+  @expose tabBadges: Record<string, number> = {};
+
+  private get _console(): ConsoleContribution {
+    return (this.constructor as typeof ConsolePage).console;
+  }
+
+  private get _panel(): PanelInstance {
+    return (this.constructor as typeof ConsolePage).panel ?? Panel.current();
+  }
+
+  private _activeTab(): ConsoleTab {
+    const tabs = this._console.tabs;
+    return tabs.find((t) => t.key === this.tab) ?? (tabs[0] as ConsoleTab);
+  }
+
+  override async onMount(): Promise<void> {
+    await this._load();
+  }
+
+  private async _load(): Promise<void> {
+    const tab = this._activeTab();
+    this.rows = tab ? await tab.rows() : [];
+
+    const badges: Record<string, number> = {};
+    await Promise.all(
+      this._console.tabs.map(async (t) => {
+        if (!t.badge) return;
+        try {
+          const n = await t.badge();
+          if (n !== null && n !== undefined) badges[t.key] = n;
+        } catch {
+          /* a failing count must not take the console down */
+        }
+      }),
+    );
+    this.tabBadges = badges;
+  }
+
+  /**
+   * Re-read the active tab. Exposed so the refresh control and the client-side
+   * confirmation flow can both land here.
+   */
+  @expose async refresh(): Promise<void> {
+    await this._load();
+  }
+
+  @expose async switchTab(key: unknown): Promise<void> {
+    const tab = this._console.tabs.find((t) => t.key === key);
+    if (!tab) return;
+    this.tab = tab.key;
+    await this._load();
+  }
+
+  /**
+   * Run a row action.
+   *
+   * The ability is asserted here rather than trusted from the render pass: these
+   * are `@expose`d methods dispatched straight from a client frame, so a user who
+   * can load the page could otherwise call them with arguments of their choosing.
+   */
+  @expose async runRowAction(key: unknown, rowKey: unknown): Promise<void> {
+    await this._authorize();
+    const tab = this._activeTab();
+    const action = tab?.rowActions?.find((a) => a.key === key);
+    if (!action) return;
+
+    const idKey = tab.rowKey ?? "id";
+    const row = this.rows.find((r) => String(r[idKey]) === String(rowKey));
+    if (!row) return;
+
+    await this._run(() => action.run(row));
+  }
+
+  @expose async runHeaderAction(key: unknown): Promise<void> {
+    await this._authorize();
+    const action = this._activeTab()?.headerActions?.find((a) => a.key === key);
+    if (!action) return;
+    await this._run(() => action.run());
+  }
+
+  /** Re-check the console's ability on every dispatched action. */
+  private async _authorize(): Promise<void> {
+    if (!(await this._panel.can(this._console.ability))) {
+      throw new AdminForbiddenError(this._console.title);
+    }
+  }
+
+  /** Run an action, flash whatever it reports, and re-read the table either way. */
+  private async _run(fn: () => Promise<string | void> | string | void): Promise<void> {
+    try {
+      const message = await fn();
+      if (message) this.flash(message, "success");
+    } catch (err) {
+      this.flash(err instanceof Error ? err.message : String(err), "error");
+    }
+    await this._load();
+  }
+
+  override async render(): Promise<HtmlNode> {
+    const console = this._console;
+    const active = this._activeTab();
+    if (!active) return <div class="text-sm text-muted-foreground">This console has no tabs.</div>;
+
+    const columns: TableColumn[] = active.columns.map((c) => ({
+      key: c.key,
+      label: c.label,
+      class: cellClass(c),
+      render: (row: ConsoleRow) => cell(c, row),
+    }));
+
+    if (active.rowActions?.length) {
+      columns.push({
+        key: "__actions",
+        label: "",
+        class: "text-right",
+        render: (row: ConsoleRow) => this._rowActions(active, row),
+      });
+    }
+
+    return (
+      <div class="mx-auto w-full max-w-7xl space-y-6">
+        <div class="flex flex-wrap items-start justify-between gap-3">
+          <div>
+            <h1 class="text-2xl font-semibold tracking-tight">{console.title}</h1>
+            {active.description ? (
+              <p class="mt-1 text-sm text-muted-foreground">{active.description}</p>
+            ) : null}
+          </div>
+          <div class="flex items-center gap-2">
+            {(active.headerActions ?? []).map((a) => this._headerAction(a))}
+            <button
+              type="button"
+              onClick={this.refresh}
+              class="inline-flex h-9 items-center gap-1.5 rounded-lg border border-input bg-background px-3 text-sm font-medium transition-colors hover:bg-accent hover:text-accent-foreground"
+            >
+              <Icon name="undo" class="h-4 w-4" />
+              Refresh
+            </button>
+          </div>
+        </div>
+
+        {console.tabs.length > 1 ? (
+          <div class="flex flex-wrap items-center gap-1 border-b border-border">
+            {console.tabs.map((t) => {
+              const isActive = t.key === active.key;
+              const count = this.tabBadges[t.key];
+              return (
+                <button
+                  type="button"
+                  onClick={this.switchTab}
+                  data-args={JSON.stringify([t.key])}
+                  class={`-mb-px inline-flex items-center gap-2 border-b-2 px-3 py-2 text-sm font-medium transition-colors ${
+                    isActive
+                      ? "border-primary text-foreground"
+                      : "border-transparent text-muted-foreground hover:text-foreground"
+                  }`}
+                >
+                  {t.label}
+                  {count !== undefined ? (
+                    <span class="inline-flex min-w-5 items-center justify-center rounded-full bg-muted px-1.5 py-0.5 text-[11px] font-semibold text-muted-foreground">
+                      {String(count)}
+                    </span>
+                  ) : null}
+                </button>
+              );
+            })}
+          </div>
+        ) : null}
+
+        <div class="overflow-hidden rounded-xl border border-border bg-card text-card-foreground shadow-sm">
+          <div class="overflow-x-auto p-1.5">
+            {this.rows.length > 0 ? (
+              <Table columns={columns} rows={this.rows} hover />
+            ) : (
+              <p class="px-4 py-12 text-center text-sm text-muted-foreground">
+                {active.empty ?? "Nothing here."}
+              </p>
+            )}
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  private _rowActions(tab: ConsoleTab, row: ConsoleRow): HtmlNode {
+    const idKey = tab.rowKey ?? "id";
+    const rowKey = String(row[idKey] ?? "");
+    return (
+      <div class="flex items-center justify-end gap-1">
+        {(tab.rowActions ?? []).map((a) => (
+          <button
+            type="button"
+            onClick={this.runRowAction}
+            data-args={JSON.stringify([a.key, rowKey])}
+            {...(a.confirm ? { confirm: a.confirm } : {})}
+            class={`inline-flex h-8 items-center gap-1.5 rounded-md px-2.5 text-xs font-medium transition-colors ${
+              a.danger
+                ? "text-destructive hover:bg-destructive/10"
+                : "text-muted-foreground hover:bg-accent hover:text-accent-foreground"
+            }`}
+          >
+            {a.icon ? <Icon name={a.icon} class="h-3.5 w-3.5" /> : null}
+            {a.label}
+          </button>
+        ))}
+      </div>
+    );
+  }
+
+  private _headerAction(a: ConsoleHeaderAction): HtmlNode {
+    return (
+      <button
+        type="button"
+        onClick={this.runHeaderAction}
+        data-args={JSON.stringify([a.key])}
+        {...(a.confirm ? { confirm: a.confirm } : {})}
+        class={`inline-flex h-9 items-center gap-1.5 rounded-lg px-3 text-sm font-medium transition-colors ${
+          a.danger
+            ? "border border-destructive/30 text-destructive hover:bg-destructive/10"
+            : "border border-input bg-background hover:bg-accent hover:text-accent-foreground"
+        }`}
+      >
+        {a.icon ? <Icon name={a.icon} class="h-4 w-4" /> : null}
+        {a.label}
+      </button>
+    );
+  }
+}
+
+function cellClass(c: ConsoleColumn): string {
+  return [ALIGN[c.align ?? "start"], c.mono ? "font-mono text-xs" : ""].filter(Boolean).join(" ");
+}
+
+function cell(c: ConsoleColumn, row: ConsoleRow): HtmlNode | string {
+  const raw = row[c.key];
+  const text = c.format
+    ? c.format(raw, row)
+    : raw === null || raw === undefined
+      ? "—"
+      : String(raw);
+  const tone = c.badge?.(raw, row) ?? null;
+  if (!tone) return text;
+  return (
+    <span
+      class={`inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium ${BADGE_TONE[tone]}`}
+    >
+      {text}
+    </span>
+  );
+}
+
+/**
+ * Build the page class for one console. A subclass per console — rather than one
+ * shared class resolving itself from the route — keeps the console on a static
+ * and matches how resource list pages are generated. The explicit name matters:
+ * Flow's component registry is keyed by constructor name.
+ */
+export function makeConsolePage(
+  console: ConsoleContribution,
+  panel: PanelInstance = Panel.default(),
+): typeof ConsolePage {
+  const Page = class extends ConsolePage {
+    static override console = console;
+    static override panel = panel;
+    static override layout = makeAdminLayout(panel);
+  };
+  const pascal = console.slug
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+    .join("");
+  Object.defineProperty(Page, "name", { value: `${pascal}ConsolePage` });
+  return Page;
+}

package/src/pages/DashboardPage.tsx

@@ -0,0 +1,264 @@
+/** @jsxImportSource @zerotal/flow */
+// Admin home: a friendly overview with a card per registered resource.
+
+import { Component, expose } from "@zerotal/flow";
+import type { HtmlNode } from "@zerotal/flow";
+import { AdminLayout, makeAdminLayout } from "../ui/AdminLayout.tsx";
+import { Icon } from "../ui/icons.tsx";
+import { Panel } from "../Panel.ts";
+import type { PanelInstance } from "../PanelInstance.ts";
+import { widgetPollInterval } from "../widgets/Widget.ts";
+import { renderWidgets } from "../widgets/render.tsx";
+import type { DashboardWidget } from "../widgets/Widget.ts";
+import { applyLayout, moveKey, reconcile } from "../dashboardLayout.ts";
+
+export class DashboardPage extends Component {
+  static layout = AdminLayout;
+  /** The panel this page belongs to — set by each generated subclass. */
+  static panel: PanelInstance;
+
+  private get _panel(): PanelInstance {
+    return (this.constructor as typeof DashboardPage).panel ?? Panel.current();
+  }
+
+  /** Whether the arrange controls are showing. */
+  @expose arranging = false;
+  /** Every widget on this dashboard, keyed — recomputed each render. */
+  private _keyed: { key: string; widget: DashboardWidget; title: string }[] = [];
+
+  @expose toggleArranging(): void {
+    this.arranging = !this.arranging;
+  }
+
+  /** The declared widgets, in declaration order, with their stored identities. */
+  private async _allWidgets(): Promise<{ key: string; widget: DashboardWidget; title: string }[]> {
+    const panel = this._panel;
+    const widgets = [...panel.dashboardWidgets(), ...(await panel.visibleWidgets())];
+    return widgets.map((widget, index) => ({
+      key: widget.widgetKey(index),
+      widget,
+      title: (widget as { _title?: string })._title ?? "Overview",
+    }));
+  }
+
+  /** Read the current layout, reconciled against the widgets that exist now. */
+  private async _layout(): Promise<{ order: string[]; hidden: string[] } | null> {
+    const store = this._panel.dashboardLayoutStore();
+    if (!store) return null;
+    const keys = (await this._allWidgets()).map((k) => k.key);
+    return reconcile(await store.load(), keys);
+  }
+
+  @expose async moveWidget(key: unknown, direction: unknown): Promise<void> {
+    const store = this._panel.dashboardLayoutStore();
+    const layout = await this._layout();
+    if (!store || !layout) return;
+    await store.save({
+      ...layout,
+      order: moveKey(layout.order, String(key), Number(direction) < 0 ? -1 : 1),
+    });
+  }
+
+  @expose async toggleWidget(key: unknown): Promise<void> {
+    const store = this._panel.dashboardLayoutStore();
+    const layout = await this._layout();
+    if (!store || !layout) return;
+    const id = String(key);
+    await store.save({
+      ...layout,
+      hidden: layout.hidden.includes(id)
+        ? layout.hidden.filter((k) => k !== id)
+        : [...layout.hidden, id],
+    });
+  }
+
+  /** Put the dashboard back the way the app declares it. */
+  @expose async resetLayout(): Promise<void> {
+    const store = this._panel.dashboardLayoutStore();
+    if (!store) return;
+    await store.save({ order: [], hidden: [] });
+    this.flash("Dashboard reset.", "success");
+  }
+
+  /** The "Arrange" toggle, with a note when something is hidden. */
+  private _arrangeBar(
+    layout: { order: string[]; hidden: string[] },
+    hiddenCount: number,
+  ): HtmlNode {
+    return (
+      <div class="flex items-center justify-end gap-3 text-sm">
+        {hiddenCount > 0 ? (
+          <span class="text-xs text-muted-foreground">
+            {hiddenCount} widget{hiddenCount === 1 ? "" : "s"} hidden
+          </span>
+        ) : null}
+        <button
+          type="button"
+          onClick={this.toggleArranging}
+          class="inline-flex h-8 items-center gap-1.5 rounded-lg border border-input px-3 text-xs font-medium transition hover:bg-accent"
+        >
+          <Icon name="filter" class="h-3.5 w-3.5" />
+          {this.arranging ? "Done" : "Arrange"}
+        </button>
+        {layout.order.length > 0 || layout.hidden.length > 0 ? (
+          <button
+            type="button"
+            onClick={this.resetLayout}
+            confirm="Put the dashboard back the way it started?"
+            class="text-xs text-muted-foreground transition hover:text-foreground"
+          >
+            Reset
+          </button>
+        ) : null}
+      </div>
+    );
+  }
+
+  /** One row per widget: move up, move down, show or hide. */
+  private _arrangePanel(layout: { order: string[]; hidden: string[] }): HtmlNode {
+    // Listed in the saved order rather than declaration order, so what is on
+    // screen matches what the rows say.
+    const rows = layout.order
+      .map((key) => this._keyed.find((k) => k.key === key))
+      .filter((k): k is (typeof this._keyed)[number] => Boolean(k));
+
+    return (
+      <div class="divide-y divide-border rounded-lg border border-border bg-card">
+        {rows.map((row, index) => {
+          const hidden = layout.hidden.includes(row.key);
+          return (
+            <div class="flex items-center gap-3 px-3 py-2">
+              <span class={`flex-1 text-sm ${hidden ? "text-muted-foreground line-through" : ""}`}>
+                {row.title}
+              </span>
+              <button
+                type="button"
+                onClick={this.moveWidget}
+                data-args={JSON.stringify([row.key, -1])}
+                disabled={index === 0}
+                aria-label={`Move ${row.title} up`}
+                class="rounded p-1 text-muted-foreground transition hover:bg-accent hover:text-foreground disabled:opacity-30"
+              >
+                <Icon name="chevron-up" class="h-4 w-4" />
+              </button>
+              <button
+                type="button"
+                onClick={this.moveWidget}
+                data-args={JSON.stringify([row.key, 1])}
+                disabled={index === rows.length - 1}
+                aria-label={`Move ${row.title} down`}
+                class="rounded p-1 text-muted-foreground transition hover:bg-accent hover:text-foreground disabled:opacity-30"
+              >
+                <Icon name="chevron-down" class="h-4 w-4" />
+              </button>
+              <button
+                type="button"
+                onClick={this.toggleWidget}
+                data-args={JSON.stringify([row.key])}
+                aria-label={`${hidden ? "Show" : "Hide"} ${row.title}`}
+                class="rounded p-1 text-muted-foreground transition hover:bg-accent hover:text-foreground"
+              >
+                <Icon name="eye" class="h-4 w-4" />
+              </button>
+            </div>
+          );
+        })}
+      </div>
+    );
+  }
+
+  override async render(): Promise<HtmlNode> {
+    const panel = this._panel;
+    const cfg = panel.config();
+    // A nested resource has no URL without a parent record, so it gets no card.
+    const resources = panel.resources().filter((r) => !r.parent);
+
+    // The app's widgets first, then whatever packages contributed and this user
+    // may see — so a contributed widget never displaces the app's own headline.
+    // A saved layout then reorders and hides within that, per user.
+    this._keyed = await this._allWidgets();
+    const store = panel.dashboardLayoutStore();
+    const layout = store
+      ? reconcile(
+          await store.load(),
+          this._keyed.map((k) => k.key),
+        )
+      : null;
+    const arranged = applyLayout(this._keyed, (k) => k.key, layout);
+    const widgets = arranged.visible.map((k) => k.widget);
+    const widgetBlock = await renderWidgets(widgets);
+
+    // The keenest widget sets the page's refresh rate; with none, this renders
+    // once per navigation as before.
+    const poll = widgetPollInterval(widgets);
+
+    return (
+      <div class="mx-auto w-full max-w-7xl space-y-8" {...(poll ? { poll: { every: poll } } : {})}>
+        <div>
+          <h1 class="text-2xl font-semibold tracking-tight">Welcome to {cfg.brand}</h1>
+          <p class="mt-1 text-sm text-muted-foreground">
+            Manage your application's data from one place.
+          </p>
+        </div>
+
+        {store ? this._arrangeBar(layout!, arranged.hidden.length) : null}
+        {this.arranging && store ? this._arrangePanel(layout!) : null}
+
+        {widgetBlock}
+
+        {resources.length > 0 ? (
+          <div class="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
+            {resources.map((r) => (
+              <a
+                href={r.indexUrl(panel.base())}
+                navigate
+                class="group relative overflow-hidden rounded-xl border border-border bg-card p-5 text-card-foreground shadow-sm transition hover:border-primary/40 hover:shadow-md"
+              >
+                <div class="flex items-center gap-3">
+                  <div class="flex h-11 w-11 items-center justify-center rounded-lg bg-primary/10 text-primary transition group-hover:bg-primary group-hover:text-primary-foreground">
+                    <Icon name={r.navigationIcon} class="h-5 w-5" />
+                  </div>
+                  <div class="min-w-0">
+                    <div class="font-medium leading-tight">{r.getPluralLabel()}</div>
+                    {r.navigationGroup ? (
+                      <div class="text-xs text-muted-foreground">{r.navigationGroup}</div>
+                    ) : null}
+                  </div>
+                </div>
+                <div class="mt-4 flex items-center gap-1 text-sm font-medium text-primary">
+                  Manage
+                  <Icon
+                    name="chevron-right"
+                    class="h-4 w-4 transition group-hover:translate-x-0.5"
+                  />
+                </div>
+              </a>
+            ))}
+          </div>
+        ) : (
+          <div class="rounded-xl border border-dashed border-border p-12 text-center">
+            <div class="mx-auto flex h-12 w-12 items-center justify-center rounded-full bg-muted text-muted-foreground">
+              <Icon name="layout-grid" class="h-6 w-6" />
+            </div>
+            <p class="mt-3 text-sm font-medium">No resources registered yet</p>
+            <p class="mt-1 text-sm text-muted-foreground">
+              Register one with{" "}
+              <code class="rounded bg-muted px-1.5 py-0.5">Panel.register(...)</code> in your admin
+              bootstrap file.
+            </p>
+          </div>
+        )}
+      </div>
+    );
+  }
+}
+
+/** The dashboard for one panel, showing only that panel's resources and widgets. */
+export function makeDashboardPage(panel: PanelInstance = Panel.default()): typeof DashboardPage {
+  const Page = class extends DashboardPage {
+    static override panel = panel;
+    static override layout = makeAdminLayout(panel);
+  };
+  Object.defineProperty(Page, "name", { value: "DashboardPage" });
+  return Page;
+}