@everystack/admin 0.2.3 → 0.2.5

package/src/types.ts

@@ -5,6 +5,85 @@
  * admin dashboards declaratively.
  */
 
+import type { ReactNode } from 'react';
+import type { DataAdapter } from './adapters/types';
+
+// =============================================================================
+// Rendering & Extensibility
+// =============================================================================
+//
+// One resolution chain for every customizable slot:
+//   explicit override (your fn) → named renderer → type-based default.
+// The type default is the sane out-of-the-box behavior; the override is the
+// no-patch escape hatch. See docs/plans/admin-extensibility.md.
+
+/** Image dimensions. A bare number is a square (width = height). */
+export type ImageSize = number | { width: number; height?: number };
+
+/** Passed to a field's custom cell renderer (`field.render`). */
+export interface CellContext {
+  /** Which view is rendering the cell. */
+  view: 'list' | 'show';
+}
+
+/**
+ * Passed to a row action's `onPress`/`render`. Carries the capability a custom
+ * button needs — call an rpc via the adapter, refresh the view, navigate —
+ * rather than reaching for module-level singletons.
+ */
+export interface ActionContext {
+  /** The record the action operates on. */
+  record: DataRecord;
+  /** The active data adapter (use `adapter.rpc` for backend calls). */
+  adapter: DataAdapter;
+  /** Re-fetch the current view after a mutation. */
+  refetch: () => Promise<void> | void;
+  /** Navigate to an admin path, when the route layer provides it. */
+  navigate?: (path: string) => void;
+}
+
+/**
+ * Passed to a field's custom form input (`field.input`). The custom input owns
+ * its element — render the control (and, if you want, the label/error frame via
+ * `@everystack/ui` FormField). `error` is the current validation message.
+ */
+export interface InputContext {
+  value: unknown;
+  onChange: (value: unknown) => void;
+  field: FieldDefinition;
+  record?: DataRecord;
+  error?: string;
+}
+
+/**
+ * Content format an editor reads and writes. The field declares it; the editor
+ * adapter serializes accordingly. The render/sanitize pipeline keys on this.
+ */
+export type ContentFormat = 'html' | 'markdown' | 'mdx' | 'email' | 'json';
+
+/**
+ * Props every editor adapter receives. The contract that makes editors
+ * swappable — TipTap, MDXEditor, Lexical, a GrapesJS email builder, etc. each
+ * implement this and own their own serialization to/from `format`.
+ */
+export interface EditorProps {
+  value: unknown;
+  onChange: (value: unknown) => void;
+  field: FieldDefinition;
+  format: ContentFormat;
+  error?: string;
+}
+
+/** A registered editor component (e.g. a TipTap adapter). */
+export type EditorComponent = (props: EditorProps) => ReactNode;
+
+/**
+ * App-provided map of editor name → component, passed to AdminRoot/AdminShell.
+ * A field selects one via `field.editor` (or falls back to `field.type`).
+ * Editors are opt-in plugins — the core admin depends on none of them.
+ */
+export type EditorRegistry = Record<string, EditorComponent>;
+
 // =============================================================================
 // Field Types
 // =============================================================================
@@ -54,6 +133,29 @@ export interface FieldDefinition {
   };
   /** Renderer variant for this field type (e.g., 'avatar' for image fields) */
   renderer?: string;
+  /**
+   * Per-view image dimensions (image fields). Falls back to sane defaults —
+   * a square thumbnail in the list, a large image on the detail view.
+   */
+  image?: { list?: ImageSize; show?: ImageSize };
+  /**
+   * Custom cell renderer — wins over the type-based default. Receives the cell
+   * value, the full record, and the view context (`ctx.view` is 'list' | 'show').
+   */
+  render?: (value: unknown, record: DataRecord, ctx: CellContext) => ReactNode;
+  /**
+   * Custom form input (create/edit) — wins over the type/renderer input. The
+   * custom input owns its element (control + optional label/error frame).
+   */
+  input?: (ctx: InputContext) => ReactNode;
+  /**
+   * Name of a registered editor (see EditorRegistry) to use as this field's
+   * form input — e.g. 'tiptap', 'markdown'. Falls back to a registry entry
+   * matching `type`. `field.input` still wins over this.
+   */
+  editor?: string;
+  /** Content format the editor reads/writes (default 'html'). */
+  format?: ContentFormat;
 }
 
 // =============================================================================
@@ -61,8 +163,13 @@ export interface FieldDefinition {
 // =============================================================================
 
 /**
- * A declarative, RPC-backed action on a single record (retry/cancel a job).
- * Rendered on the show view; invoked via adapter.rpc(rpc, { id }).
+ * A declarative action on a single record (delete/restore, retry/cancel a job),
+ * rendered on both the list and show views and gated by the `when` clause.
+ *
+ * Behavior, in precedence order — provide exactly one:
+ *   - `render`  : a fully custom element (you own the chrome)
+ *   - `onPress` : custom behavior with the default button chrome
+ *   - `rpc`     : declarative; calls adapter.rpc(rpc, { id: record[primaryKey] })
  */
 export interface RowActionConfig {
   /** Unique action identifier */
@@ -70,8 +177,12 @@ export interface RowActionConfig {
   /** Button label */
   label: string;
   /** RPC function name, called with { id: record[primaryKey] } */
-  rpc: string;
-  /** Require a confirming second press; shown as the interim label */
+  rpc?: string;
+  /** Custom behavior with the default button chrome and confirm flow. */
+  onPress?: (ctx: ActionContext) => void | Promise<void>;
+  /** Fully custom element; bypasses the default button entirely. */
+  render?: (ctx: ActionContext) => ReactNode;
+  /** Require a confirming second press; shown as the interim label (rpc/onPress). */
   confirm?: string;
   /** Button styling */
   variant?: 'primary' | 'outline' | 'destructive';
@@ -128,7 +239,11 @@ export type StatDialValue =
   | { type: 'count' }
   | { type: 'count_where'; column: string; equals: string }
   | { type: 'distinct'; column: string }
-  | { type: 'table_count'; table: string; timestampColumn?: string };
+  | { type: 'table_count'; table: string; timestampColumn?: string }
+  // Field-fold dials over a rollup 'sum' field (artifact-backed dashboards only,
+  // e.g. snapshot memory/cpu averages). The SQL DB path ignores these.
+  | { type: 'sum'; column: string }
+  | { type: 'avg'; column: string };
 
 /** Configuration for a single stat dial in the dashboard header. */
 export interface StatDialConfig {
@@ -279,8 +394,10 @@ export interface MenuItem {
   resource?: string;
   /** Dashboard ID (for dashboard links) */
   dashboard?: string;
-  /** Nested menu items */
+  /** Nested menu items — renders this item as a collapsible group header. */
   children?: MenuItem[];
+  /** For a group (has children): start expanded. Default true. */
+  defaultOpen?: boolean;
   /** Badge content */
   badge?: string | number;
 }

package/src/utils/admin-routing.ts

@@ -0,0 +1,66 @@
+/**
+ * Admin routing — pure path↔route mapping behind AdminRouter.
+ *
+ * The package owns CRUD dispatch and navigation targets without depending on a
+ * router: AdminRouter is handed the current `pathname` and a `{ push }` port by
+ * the app's catch-all route. These pure functions turn the path into a screen
+ * match and build the hrefs to navigate to. See docs/plans/admin-routing.md.
+ */
+
+export type AdminScreen = 'dashboard' | 'list' | 'show' | 'create' | 'edit';
+
+export interface AdminRouteMatch {
+  screen: AdminScreen;
+  resource?: string;
+  id?: string;
+}
+
+const CREATE = 'create';
+const EDIT = 'edit';
+
+/** Strip `basePath` from a pathname and return the remaining path segments. */
+export function pathToSegments(pathname: string, basePath: string): string[] {
+  const base = basePath.replace(/\/+$/, '');
+  let rel = pathname;
+  if (base && (pathname === base || pathname.startsWith(`${base}/`))) {
+    rel = pathname.slice(base.length);
+  }
+  return rel.split('/').filter(Boolean);
+}
+
+/**
+ * Map admin path segments to a screen. `create` is a reserved segment, so a
+ * record can't have the literal id "create" (matches the navigation convention).
+ */
+export function resolveAdminRoute(segments: string[]): AdminRouteMatch {
+  const s = segments.filter(Boolean);
+  if (s.length === 0) return { screen: 'dashboard' };
+
+  const [resource, second, third] = s;
+  if (s.length === 1) return { screen: 'list', resource };
+  if (second === CREATE) return { screen: CREATE, resource };
+  if (s.length >= 3 && third === EDIT) return { screen: EDIT, resource, id: second };
+  return { screen: 'show', resource, id: second };
+}
+
+export interface AdminHrefParts {
+  resource?: string;
+  id?: string | number;
+  action?: 'create' | 'edit';
+}
+
+/** Build an admin path. The inverse of resolveAdminRoute. */
+export function adminHref(basePath: string, parts: AdminHrefParts = {}): string {
+  const base = basePath.replace(/\/+$/, '');
+  const segs: string[] = [];
+  if (parts.resource) {
+    segs.push(parts.resource);
+    if (parts.action === CREATE) {
+      segs.push(CREATE);
+    } else if (parts.id != null) {
+      segs.push(String(parts.id));
+      if (parts.action === EDIT) segs.push(EDIT);
+    }
+  }
+  return [base, ...segs].join('/') || '/';
+}

package/src/utils/breadcrumbs.ts

@@ -0,0 +1,81 @@
+/**
+ * Breadcrumbs — derive the trail from the current route + admin config.
+ *
+ * Pure mapping: `(config, match, activeItem) → Crumb[]`. A crumb with an `href`
+ * is navigable; the last (current) crumb usually has none. The trail mirrors the
+ * nav: Admin → [group] → resource → [record/action].
+ */
+
+import type { AdminConfig } from '../types';
+import type { AdminRouteMatch } from './admin-routing';
+import { adminHref } from './admin-routing';
+
+export interface Crumb {
+  label: string;
+  /** Admin path to navigate to; omitted for the current (non-link) crumb. */
+  href?: string;
+}
+
+/** Find the active menu item (and its parent group) by id or linked resource. */
+function locate(
+  config: AdminConfig,
+  activeItem: string | undefined,
+  resource: string | undefined,
+): { groupLabel?: string; itemLabel?: string; itemPath?: string } {
+  for (const top of config.menu ?? []) {
+    if (top.children?.length) {
+      const child = top.children.find(
+        c => c.id === activeItem || (resource != null && c.resource === resource),
+      );
+      if (child) return { groupLabel: top.label, itemLabel: child.label, itemPath: child.path };
+    } else if (top.id === activeItem || (resource != null && top.resource === resource)) {
+      return { itemLabel: top.label, itemPath: top.path };
+    }
+  }
+  return {};
+}
+
+export function buildBreadcrumbs(
+  config: AdminConfig,
+  match: AdminRouteMatch,
+  activeItem: string | undefined,
+  basePath = '/admin',
+): Crumb[] {
+  const home: Crumb = { label: config.title ?? 'Admin', href: basePath };
+  if (match.screen === 'dashboard') return [home];
+
+  const { groupLabel, itemLabel, itemPath } = locate(config, activeItem, match.resource);
+  const resourceConfig = match.resource
+    ? config.resources.find(r => r.name === match.resource)
+    : undefined;
+
+  const listLabel =
+    resourceConfig?.labelPlural ?? resourceConfig?.label ?? itemLabel ?? match.resource ?? '';
+  const singular = resourceConfig?.label ?? itemLabel ?? match.resource ?? 'Record';
+  const listHref =
+    itemPath ?? (match.resource ? adminHref(basePath, { resource: match.resource }) : undefined);
+
+  const crumbs: Crumb[] = [home];
+  if (groupLabel) crumbs.push({ label: groupLabel });
+
+  if (match.screen === 'list') {
+    crumbs.push({ label: listLabel });
+    return crumbs;
+  }
+
+  // show / create / edit → the list crumb links back.
+  crumbs.push({ label: listLabel, href: listHref });
+
+  if (match.screen === 'create') {
+    crumbs.push({ label: `New ${singular}` });
+  } else if (match.screen === 'show') {
+    crumbs.push({ label: match.id != null ? `#${match.id}` : singular });
+  } else if (match.screen === 'edit') {
+    if (match.id != null && match.resource) {
+      crumbs.push({ label: `#${match.id}`, href: adminHref(basePath, { resource: match.resource, id: match.id }) });
+    }
+    crumbs.push({ label: 'Edit' });
+  }
+
+  return crumbs;
+}

package/src/utils/render-resolution.ts

@@ -0,0 +1,91 @@
+/**
+ * Rendering resolution — the precedence behind the admin's extensibility
+ * contract. Each customizable slot resolves through:
+ *
+ *   explicit override (your fn) → named renderer → type-based default
+ *
+ * These are the pure pieces of that chain. The screens consume them; the
+ * JSX lives there, the decisions live here. See docs/plans/admin-extensibility.md.
+ */
+
+import type { ImageTransformOptions } from '@everystack/ui/image-url';
+import type { FieldDefinition, ImageSize, RowActionConfig, EditorRegistry, EditorComponent } from '../types';
+
+export type ImageView = 'list' | 'show';
+
+export interface ImageRenderSpec {
+  /** Rendered width in px. */
+  width: number;
+  /** Rendered height in px. */
+  height: number;
+  /** Transform passed to resolveImageUrl (CDN sizing). */
+  transform: ImageTransformOptions;
+  /** Show the storage-key caption beneath the image. */
+  showCaption: boolean;
+  /** Render through the circular Avatar component instead of a plain Image. */
+  isAvatar: boolean;
+}
+
+// Sane defaults: a compact square in the list, a large image (caption-bearing)
+// on the detail view, a fixed square for the avatar variant.
+const SIZE_DEFAULTS: Record<'avatar' | ImageView, { width: number; height: number }> = {
+  avatar: { width: 128, height: 128 },
+  list: { width: 100, height: 100 },
+  show: { width: 448, height: 336 },
+};
+
+function normalizeSize(size: ImageSize): { width: number; height: number } {
+  if (typeof size === 'number') return { width: size, height: size };
+  return { width: size.width, height: size.height ?? size.width };
+}
+
+/**
+ * Resolve how an image field renders in a given view. `renderer: 'avatar'`
+ * wins over per-view sizing; otherwise `field.image[view]` overrides the
+ * sane default for that view.
+ */
+export function imageRenderSpec(field: FieldDefinition, view: ImageView): ImageRenderSpec {
+  if (field.renderer === 'avatar') {
+    const { width, height } = SIZE_DEFAULTS.avatar;
+    return { width, height, transform: { width, height, fit: 'cover' }, showCaption: false, isAvatar: true };
+  }
+  const override = field.image?.[view];
+  const { width, height } = override ? normalizeSize(override) : SIZE_DEFAULTS[view];
+  return {
+    width,
+    height,
+    transform: { width, height, fit: 'cover' },
+    showCaption: view === 'show',
+    isAvatar: false,
+  };
+}
+
+/** List/show cell precedence: custom render → image → type text. */
+export function cellRenderKind(field: FieldDefinition): 'custom' | 'image' | 'text' {
+  if (field.render) return 'custom';
+  if (field.type === 'image') return 'image';
+  return 'text';
+}
+
+/** Row action precedence: render → onPress → rpc (none if unconfigured). */
+export function actionBehavior(action: RowActionConfig): 'render' | 'onPress' | 'rpc' | 'none' {
+  if (action.render) return 'render';
+  if (action.onPress) return 'onPress';
+  if (action.rpc) return 'rpc';
+  return 'none';
+}
+
+/**
+ * Resolve a registered editor for a field: by explicit `field.editor` name,
+ * else by a registry entry matching `field.type`. Returns undefined when none
+ * is registered (the form falls back to the built-in type input).
+ */
+export function editorFor(
+  field: FieldDefinition,
+  registry: EditorRegistry | undefined,
+): EditorComponent | undefined {
+  if (!registry) return undefined;
+  if (field.editor && registry[field.editor]) return registry[field.editor];
+  if (field.type && registry[field.type]) return registry[field.type];
+  return undefined;
+}

package/src/utils/standard-actions.ts

@@ -0,0 +1,48 @@
+/**
+ * Standard row actions — the built-in Show / Edit / Delete buttons every CRUD
+ * list offers, gated by the resource's `actions.{show,edit,delete}` flags.
+ *
+ * They are ordinary RowActionConfigs (see RowActionButton), so they render in
+ * the same actions column as custom rowActions and share the confirm/busy/error
+ * chrome. Show/Edit navigate via the supplied callbacks; Delete self-serves
+ * through adapter.delete and lets RowActionButton refetch afterward.
+ */
+
+import type { ResourceConfig, RowActionConfig, DataRecord } from '../types';
+
+export interface StandardActionNav {
+  /** Navigate to the record's detail view (also the row-press target). */
+  onShow?: (record: DataRecord) => void;
+  /** Navigate to the record's edit screen. */
+  onEdit?: (record: DataRecord) => void;
+}
+
+export function standardRowActions(
+  resourceConfig: ResourceConfig,
+  nav: StandardActionNav,
+): RowActionConfig[] {
+  const actions = resourceConfig.actions ?? {};
+  const primaryKey = resourceConfig.primaryKey ?? 'id';
+  const idOf = (record: DataRecord): string | number =>
+    (record[primaryKey] as string | number) ?? (record.id as string | number);
+
+  const out: RowActionConfig[] = [];
+
+  if (actions.show !== false && nav.onShow) {
+    out.push({ id: '__show', label: 'Show', variant: 'outline', onPress: ({ record }) => nav.onShow!(record) });
+  }
+  if (actions.edit !== false && nav.onEdit) {
+    out.push({ id: '__edit', label: 'Edit', variant: 'outline', onPress: ({ record }) => nav.onEdit!(record) });
+  }
+  if (actions.delete !== false) {
+    out.push({
+      id: '__delete',
+      label: 'Delete',
+      variant: 'destructive',
+      confirm: 'Confirm delete',
+      onPress: ({ record, adapter }) => adapter.delete(resourceConfig.name, idOf(record)),
+    });
+  }
+
+  return out;
+}

package/src/utils/view-filters.ts

@@ -0,0 +1,75 @@
+/**
+ * Pure mappers between URL query params and analytics/table filters.
+ *
+ * Kept React-free so they're trivially testable and reusable: the URL is the
+ * source of truth for a resource's filter state, these translate it to the
+ * AnalyticsHeader's DashboardFilters and the CRUD table's PostgREST conditions.
+ */
+
+import type { ViewParams } from '../hooks/useViewState';
+import type { DimensionConfig, ResourceDashboardConfig } from '../types';
+import type { DashboardFilters } from '../rpc/resource-dashboard-rpc';
+
+/** URL query → analytics filters (time range + per-dimension selections). */
+export function paramsToFilters(params: ViewParams, dimensions: DimensionConfig[]): DashboardFilters {
+  const filters: DashboardFilters = {};
+  if (params.from && params.to) filters.time = [params.from, params.to];
+  for (const dim of dimensions) {
+    const v = params[dim.column];
+    if (v) filters[dim.column] = v.split(',');
+  }
+  return filters;
+}
+
+/** Analytics filters → a query-param delta that clears then sets controlled keys. */
+export function filtersToParams(filters: DashboardFilters, dimensions: DimensionConfig[]): Record<string, string | undefined> {
+  const update: Record<string, string | undefined> = { from: undefined, to: undefined };
+  for (const dim of dimensions) update[dim.column] = undefined;
+  if (filters.time && filters.time[0] && filters.time[1]) {
+    update.from = filters.time[0];
+    update.to = filters.time[1];
+  }
+  for (const dim of dimensions) {
+    const v = filters[dim.column] as string[] | undefined;
+    if (v && v.length) update[dim.column] = v.join(',');
+  }
+  return update;
+}
+
+/** Query params reserved for view state (not column filters). */
+const RESERVED_PARAMS = new Set(['from', 'to', 'sort', 'order', 'page', 'q']);
+
+/**
+ * Pass-through column filters: any query param that names a real resource field
+ * (and isn't reserved or already a dimension) becomes a table filter. Powers
+ * arbitrary drill-downs like `?traceId=abc` or `?group_id=<fingerprint>`. Values
+ * are passed as-is — the adapter wraps a plain value with `eq.`.
+ */
+export function paramsToColumnFilters(
+  params: ViewParams,
+  fieldNames: Set<string>,
+  exclude: Set<string> = new Set(),
+): Record<string, unknown> {
+  const f: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(params)) {
+    if (RESERVED_PARAMS.has(k) || exclude.has(k)) continue;
+    if (fieldNames.has(k) && v) f[k] = v;
+  }
+  return f;
+}
+
+/** Analytics filters → the table's baseFilter (PostgREST conditions). */
+export function filtersToBaseFilter(
+  filters: DashboardFilters,
+  dashboard: ResourceDashboardConfig,
+): Record<string, unknown> | undefined {
+  const f: Record<string, unknown> = {};
+  if (filters.time && filters.time[0] && filters.time[1]) {
+    f[dashboard.timestampColumn] = [`gte.${filters.time[0]}`, `lte.${filters.time[1]}`];
+  }
+  for (const dim of dashboard.dimensions) {
+    const vals = filters[dim.column] as string[] | undefined;
+    if (vals && vals.length) f[dim.column] = `in.(${vals.join(',')})`;
+  }
+  return Object.keys(f).length ? f : undefined;
+}