@zerotal/admin 1.0.0

package/src/widgets/Widget.ts

@@ -0,0 +1,251 @@
+/**
+ * Dashboard widgets — stat rows, charts and small tables whose values are
+ * computed on the server each time the dashboard renders. A widget is a *data
+ * provider*: the dashboard page owns the markup, so widgets stay
+ * framework-light and easy to test.
+ *
+ *   Panel.widgets(
+ *     statsWidget(async () => [
+ *       stat("Users", await User.count()).icon("users").tone("primary"),
+ *       stat("Posts", await Post.count()).description("Published").icon("document"),
+ *     ]).poll("30s"),
+ *   );
+ *
+ * A widget that polls re-renders itself on an interval, so an ops dashboard left
+ * open on a wall display stays current without anyone reloading it.
+ */
+import type { BadgeTone } from "../table/Column.ts";
+
+export type WidgetTone = BadgeTone;
+
+/**
+ * Re-render interval shared by every widget kind.
+ *
+ * Kept as the caller's own string ("30s", "5s") because that is what the poll
+ * directive takes; an unset interval means the widget renders once per page load.
+ */
+abstract class PollableWidget {
+  /** @internal */ _poll?: string;
+  /** @internal Stable identity, for a persisted dashboard layout. */ _key?: string;
+
+  /**
+   * Re-render this widget every `interval` — `"10s"`, `"1m"`. Costs a query per
+   * tick per viewer, so reach for it on dashboards that are watched, not on
+   * every widget by habit.
+   */
+  poll(interval: string): this {
+    this._poll = interval;
+    return this;
+  }
+
+  /**
+   * Name this widget, so a saved dashboard layout can refer to it.
+   *
+   * Worth setting on any widget whose title might change: a layout keyed by
+   * title silently resets the moment somebody rewords a heading, whereas an
+   * explicit key survives it.
+   */
+  key(key: string): this {
+    this._key = key;
+    return this;
+  }
+
+  /** The identity a layout stores. Falls back to the title, then the position. */
+  widgetKey(index: number): string {
+    if (this._key) return this._key;
+    const title = (this as { _title?: string })._title;
+    return title
+      ? title
+          .toLowerCase()
+          .replace(/[^a-z0-9]+/g, "-")
+          .replace(/^-|-$/g, "")
+      : `widget-${index}`;
+  }
+}
+
+export class Stat {
+  /** @internal */ _label: string;
+  /** @internal */ _value: string | number;
+  /** @internal */ _description?: string;
+  /** @internal */ _icon?: string;
+  /** @internal */ _tone: WidgetTone = "default";
+
+  constructor(label: string, value: string | number) {
+    this._label = label;
+    this._value = value;
+  }
+
+  description(text: string): this {
+    this._description = text;
+    return this;
+  }
+
+  icon(name: string): this {
+    this._icon = name;
+    return this;
+  }
+
+  tone(tone: WidgetTone): this {
+    this._tone = tone;
+    return this;
+  }
+}
+
+/** Build a single stat card. */
+export function stat(label: string, value: string | number): Stat {
+  return new Stat(label, value);
+}
+
+export type StatsResolver = () => Promise<Stat[]> | Stat[];
+
+export class StatsWidget extends PollableWidget {
+  /** @internal */ _resolver: StatsResolver;
+  /** @internal */ _columns = 4;
+
+  constructor(resolver: StatsResolver) {
+    super();
+    this._resolver = resolver;
+  }
+
+  /** Number of cards per row (responsive; 1–4). */
+  columns(n: number): this {
+    this._columns = Math.min(4, Math.max(1, n));
+    return this;
+  }
+
+  /** Resolve the stats for this render. */
+  async stats(): Promise<Stat[]> {
+    return this._resolver();
+  }
+}
+
+/** A row of stat cards. */
+export function statsWidget(resolver: StatsResolver): StatsWidget {
+  return new StatsWidget(resolver);
+}
+
+// ── Chart widget ─────────────────────────────────────────────────────────────
+
+export type ChartType = "line" | "bar" | "doughnut" | "pie";
+
+export interface ChartDataset {
+  label?: string;
+  data: number[];
+  /** CSS color; defaults to the panel's primary token. */
+  color?: string;
+}
+
+export interface ChartData {
+  type: ChartType;
+  labels: string[];
+  datasets: ChartDataset[];
+}
+
+export type ChartResolver = () => Promise<ChartData> | ChartData;
+
+export class ChartWidget extends PollableWidget {
+  /** @internal */ _title: string;
+  /** @internal */ _resolver: ChartResolver;
+  /** @internal */ _columns = 2;
+  /** @internal */ _height = 220;
+
+  constructor(title: string, resolver: ChartResolver) {
+    super();
+    this._title = title;
+    this._resolver = resolver;
+  }
+
+  /** Grid span on the dashboard (1–4). */
+  columns(n: number): this {
+    this._columns = Math.min(4, Math.max(1, n));
+    return this;
+  }
+
+  /** Canvas height in pixels. */
+  height(px: number): this {
+    this._height = px;
+    return this;
+  }
+
+  async data(): Promise<ChartData> {
+    return this._resolver();
+  }
+}
+
+/** A chart, drawn with Chart.js on the dashboard. */
+export function chartWidget(title: string, resolver: ChartResolver): ChartWidget {
+  return new ChartWidget(title, resolver);
+}
+
+// ── Table widget ─────────────────────────────────────────────────────────────
+
+export interface TableWidgetColumn {
+  key: string;
+  label: string;
+}
+
+export type TableRowsResolver = () =>
+  Promise<Record<string, unknown>[]> | Record<string, unknown>[];
+
+export class TableWidget extends PollableWidget {
+  /** @internal */ _title: string;
+  /** @internal */ _columns: TableWidgetColumn[];
+  /** @internal */ _resolver: TableRowsResolver;
+  /** @internal */ _wide = true;
+
+  constructor(title: string, columns: TableWidgetColumn[], resolver: TableRowsResolver) {
+    super();
+    this._title = title;
+    this._columns = columns;
+    this._resolver = resolver;
+  }
+
+  /** Span the full dashboard width (default) or a single column. */
+  wide(value = true): this {
+    this._wide = value;
+    return this;
+  }
+
+  async rows(): Promise<Record<string, unknown>[]> {
+    return this._resolver();
+  }
+}
+
+/** A small data table on the dashboard. */
+export function tableWidget(
+  title: string,
+  columns: TableWidgetColumn[],
+  resolver: TableRowsResolver,
+): TableWidget {
+  return new TableWidget(title, columns, resolver);
+}
+
+/** A dashboard widget — stats overview, chart, or table. */
+export type DashboardWidget = StatsWidget | ChartWidget | TableWidget;
+
+/**
+ * The shortest poll interval among these widgets, or `undefined` when none
+ * polls. The dashboard polls as one unit, so the keenest widget sets the pace.
+ */
+export function widgetPollInterval(widgets: DashboardWidget[]): string | undefined {
+  const intervals = widgets.map((w) => w._poll).filter((i): i is string => Boolean(i));
+  if (intervals.length === 0) return undefined;
+  return intervals.reduce((a, b) => (pollMs(b) < pollMs(a) ? b : a));
+}
+
+/** Parse a poll interval to milliseconds; an unparseable one sorts last. */
+function pollMs(interval: string): number {
+  const match = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/.exec(interval.trim());
+  if (!match) return Number.MAX_SAFE_INTEGER;
+  const n = Number(match[1]);
+  switch (match[2]) {
+    case "ms":
+      return n;
+    case "m":
+      return n * 60_000;
+    case "h":
+      return n * 3_600_000;
+    default:
+      return n * 1000;
+  }
+}

package/src/widgets/render.tsx

@@ -0,0 +1,154 @@
+/** @jsxImportSource @zerotal/flow */
+// Widget rendering, shared by the dashboard and by resource pages.
+//
+// Widgets are data providers — they resolve values and leave the markup to the
+// panel. Keeping that markup in one place is what lets the same widget appear on
+// the dashboard and above a resource's table without being written twice.
+
+import type { HtmlNode } from "@zerotal/flow";
+import { Table } from "@zerotal/flow-ui";
+import { Icon } from "../ui/icons.tsx";
+import { StatsWidget, ChartWidget, TableWidget } from "./Widget.ts";
+import type { DashboardWidget, WidgetTone } from "./Widget.ts";
+
+const STAT_TONE: Record<WidgetTone, string> = {
+  default: "bg-secondary text-secondary-foreground",
+  primary: "bg-primary/10 text-primary",
+  success: "bg-success/10 text-success",
+  muted: "bg-muted text-muted-foreground",
+  destructive: "bg-destructive/10 text-destructive",
+};
+
+const STAT_COLS: Record<number, string> = {
+  1: "sm:grid-cols-1",
+  2: "sm:grid-cols-2",
+  3: "sm:grid-cols-3",
+  4: "sm:grid-cols-2 lg:grid-cols-4",
+};
+
+/**
+ * Build the inline Chart.js init script (injected raw via dangerouslySetInnerHTML
+ * so its `<`/`>` operators aren't HTML-escaped). Loads Chart.js from the CDN on
+ * demand, then draws each canvas once.
+ *
+ * `idPrefix` keeps canvases unique when two widget sets share a page — a
+ * resource's own widgets above its table, say, alongside a contributed one.
+ */
+export function chartInitScript(configs: unknown[]): string {
+  if (!Array.isArray(configs) || configs.length === 0) return "";
+  const data = JSON.stringify(configs);
+  return `(function(){var C=${data};function pal(n){var o=[];for(var i=0;i<n;i++){o.push('hsl('+((i*53)%360)+' 70% 55%)');}return o;}function draw(){var r=getComputedStyle(document.documentElement);var p='hsl('+r.getPropertyValue('--primary').trim()+')';C.forEach(function(c){var el=document.getElementById(c.id);if(!el||el.__k){return;}el.__k=1;var pie=(c.type==='doughnut'||c.type==='pie');var line=(c.type==='line');new Chart(el,{type:c.type,data:{labels:c.labels,datasets:c.datasets.map(function(d){var col=d.color||p;return{label:d.label,data:d.data,backgroundColor:pie?pal(c.labels.length):(line?col+'33':col),borderColor:pie?'transparent':col,borderWidth:2,tension:0.35,fill:line};})},options:{responsive:true,maintainAspectRatio:false,plugins:{legend:{display:(c.datasets.length>1)||pie}},scales:pie?{}:{y:{beginAtZero:true}}}});});}if(window.Chart){draw();}else{var s=document.createElement('script');s.src='https://cdn.jsdelivr.net/npm/chart.js@4.4.1/dist/chart.umd.min.js';s.onload=draw;document.head.appendChild(s);}})();`;
+}
+
+/**
+ * Resolve and render a set of widgets.
+ *
+ * Returns `null` when there is nothing to draw, so a caller can drop the whole
+ * block rather than leaving an empty gap above its table.
+ */
+export async function renderWidgets(
+  widgets: DashboardWidget[],
+  idPrefix = "kchart",
+): Promise<HtmlNode | null> {
+  if (widgets.length === 0) return null;
+
+  const statGroups = await Promise.all(
+    widgets
+      .filter((w): w is StatsWidget => w instanceof StatsWidget)
+      .map(async (w) => ({ columns: w._columns, stats: await w.stats() })),
+  );
+
+  const charts = await Promise.all(
+    widgets
+      .filter((w): w is ChartWidget => w instanceof ChartWidget)
+      .map(async (w, i) => ({
+        id: `${idPrefix}-${i}`,
+        title: w._title,
+        wide: w._columns >= 2,
+        height: w._height,
+        data: await w.data(),
+      })),
+  );
+
+  const tables = await Promise.all(
+    widgets
+      .filter((w): w is TableWidget => w instanceof TableWidget)
+      .map(async (w) => ({
+        title: w._title,
+        wide: w._wide,
+        columns: w._columns.map((c) => ({ key: c.key, label: c.label })),
+        rows: await w.rows(),
+      })),
+  );
+
+  const chartScript = chartInitScript(
+    charts.map((c) => ({
+      id: c.id,
+      type: c.data.type,
+      labels: c.data.labels,
+      datasets: c.data.datasets,
+    })),
+  );
+
+  return (
+    <div class="space-y-4">
+      {statGroups.map((group) => (
+        <div
+          class={`grid grid-cols-1 gap-4 ${STAT_COLS[group.columns] ?? "sm:grid-cols-2 lg:grid-cols-4"}`}
+        >
+          {group.stats.map((s) => (
+            <div class="rounded-xl border border-border bg-card p-5 text-card-foreground shadow-sm">
+              <div class="flex items-center justify-between">
+                <p class="text-sm font-medium text-muted-foreground">{s._label}</p>
+                {s._icon ? (
+                  <span
+                    class={`flex h-8 w-8 items-center justify-center rounded-lg ${STAT_TONE[s._tone]}`}
+                  >
+                    <Icon name={s._icon} class="h-4 w-4" />
+                  </span>
+                ) : null}
+              </div>
+              <p class="mt-2 text-3xl font-semibold tracking-tight">{String(s._value)}</p>
+              {s._description ? (
+                <p class="mt-1 text-xs text-muted-foreground">{s._description}</p>
+              ) : null}
+            </div>
+          ))}
+        </div>
+      ))}
+
+      {charts.length > 0 ? (
+        <div class="grid grid-cols-1 gap-4 lg:grid-cols-2">
+          {charts.map((c) => (
+            <div
+              class={`rounded-xl border border-border bg-card p-5 text-card-foreground shadow-sm ${c.wide ? "lg:col-span-2" : ""}`}
+            >
+              <h3 class="text-sm font-semibold">{c.title}</h3>
+              <div class="mt-3" style={`position:relative;height:${c.height}px`}>
+                <canvas id={c.id} />
+              </div>
+            </div>
+          ))}
+        </div>
+      ) : null}
+      {chartScript ? <script dangerouslySetInnerHTML={{ __html: chartScript }} /> : null}
+
+      {tables.map((t) => (
+        <div
+          class={`overflow-hidden rounded-xl border border-border bg-card text-card-foreground shadow-sm ${t.wide ? "" : "lg:max-w-2xl"}`}
+        >
+          <div class="border-b border-border px-5 py-3">
+            <h3 class="text-sm font-semibold">{t.title}</h3>
+          </div>
+          <div class="overflow-x-auto p-1.5">
+            {t.rows.length > 0 ? (
+              <Table columns={t.columns} rows={t.rows} hover />
+            ) : (
+              <p class="px-4 py-8 text-center text-sm text-muted-foreground">No data.</p>
+            )}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}