@grafloria/element 0.3.19 → 0.3.21

package/src/lib/dashboard-kit/dashboard.ts

@@ -1,906 +0,0 @@
-/**
- * `dashboard({ views, widgets })` — the DATA-FIRST dashboard authoring API.
- *
- * The exact shape `erDiagram()` / `umlDiagram()` have for ER and UML: you
- * describe WHAT the dashboard is, `render()` runs the returned `finalize(api)`
- * automatically, and every interactive part (the pack grid, drag/resize with
- * live push and a truthful placeholder, fit/grow, float, pin, undoable
- * commands) wires itself.
- *
- * Before this, a developer got `bindDashboardGrid()` — a gesture BINDER one
- * layer down — and had to hand-assemble everything above it: a GroupModel per
- * view, a NodeModel per widget, `useHTMLLayer` / `widgetKind` metadata, grid
- * cells, membership, then the bind. The demo page needed ~143 lines just to
- * build its boards. That was the missing authoring layer; this is it:
- *
- * ```js
- * const SPEC = dashboard({
- *   columns: 12,
- *   sizing: 'fit',
- *   views: [{
- *     id: 'overview', name: 'Overview',
- *     widgets: [
- *       { id: 'rev',   kind: 'kpi',   span: 3, rows: 1, data: {…} },
- *       { id: 'trend', kind: 'line',  span: 8, rows: 2, data: {…} },
- *       { id: 'mix',   kind: 'donut', span: 4, rows: 2, pinned: true },
- *     ],
- *   }],
- *   renderWidget: (widget, host) => { … },   // optional: your charts
- * });
- * render(SPEC, host);
- * ```
- *
- * WHAT IT DELIBERATELY DOES NOT DO: pick a charting library. `renderWidget` is
- * the seam — the kit hands you the widget and a raw HTML host (the renderer's
- * custom-node path, which unlike `metadata.html` is not sanitised, so real
- * `<svg>`/`<canvas>` is fine). Omit it and `defaultWidgetRenderer` (widgets.ts)
- * draws the declared `kind` from your own `data` with hand-rolled inline SVG —
- * kpi / line / bar / donut / funnel / table, no dependency, no sample dataset —
- * falling back to a titled frame for kinds it does not know, so a layout is
- * testable before any chart exists.
- *
- * Cells are the truth and live in the existing `GridItemConfig`, so save/load
- * round-trips with no extra work — same as every other kit.
- */
-
-import {
-  AddToGroupCommand,
-  BatchCommand,
-  BringNodeToFrontCommand,
-  Command,
-  GroupModel,
-  NodeModel,
-  RemoveFromGroupCommand,
-  RemoveNodeCommand,
-  SendNodeToBackCommand,
-  type GridColumnLayout,
-} from '@grafloria/engine';
-import {
-  bindDashboardGrid,
-  type DashboardGridHandle,
-  type DashboardGridOptions,
-  type DashboardResponsiveOptions,
-} from './grid-binder';
-import { gridItemFromCell } from './grid-mapping';
-import { ensureDashboardKitStyles } from './styles';
-import { defaultWidgetRenderer } from './widgets';
-
-/** A widget, declared as data. */
-export interface DashboardWidgetSpec {
-  id: string;
-  /** Free-form kind string handed back to `renderWidget` (e.g. 'kpi', 'line'). */
-  kind?: string;
-  /** Column span (default 3) and row span (default 1). */
-  span?: number;
-  rows?: number;
-  /**
-   * Explicit cell. Omit and widgets flow in declaration order, wrapping at
-   * the column count — the common case needs no coordinates at all.
-   */
-  x?: number;
-  y?: number;
-  /** Pinned: never pushed, refuses the mover, survives every reflow. */
-  pinned?: boolean;
-  /** Your payload — passed straight back to `renderWidget`. */
-  data?: Record<string, unknown>;
-  /** Optional title used by the built-in fallback renderer. */
-  title?: string;
-}
-
-/** One board. Multiple views are the tab pattern: only one is on-camera. */
-export interface DashboardViewSpec {
-  id: string;
-  name?: string;
-  widgets: DashboardWidgetSpec[];
-  /** Per-view overrides of the dashboard-level geometry. */
-  columns?: number;
-  width?: number;
-  height?: number;
-}
-
-export interface DashboardOptions {
-  /** Column count for every view (default 12). */
-  columns?: number;
-  /** Gap between widgets AND the board padding, px (default 8). */
-  gap?: number;
-  /** Sizing mode (default 'fit' — squeeze rows; 'grow' extends the board). */
-  sizing?: 'fit' | 'grow';
-  /** Row height in 'grow' mode, px (default 130). */
-  rowHeight?: number;
-  /** Board size, px (default 1180 × 660). */
-  width?: number;
-  height?: number;
-  /** Engine float mode (default false → gravity packs upward). */
-  float?: boolean;
-  /**
-   * RIGHT-TO-LEFT boards: column x=0 renders at the RIGHT edge and columns run
-   * leftwards. Cells are untouched — the same `widgets` array describes the
-   * same layout in both directions, and a layout saved in one renders mirrored
-   * in the other with identical cells.
-   */
-  rtl?: boolean;
-  /**
-   * RESPONSIVE COLUMN COUNT: derive the live count from each board's width.
-   * `{ columnWidth: 100 }` gives one column per ~100px (capped by `columns`);
-   * `{ breakpoints: [{ w: 480, c: 1 }, { w: 900, c: 6 }] }` names the steps.
-   * The count changes through the engine's per-column layout CACHE, so
-   * narrowing and widening again restores the wide layout exactly, and
-   * `toJSON()` keeps serialising the widest layout however narrow the board is.
-   */
-  responsive?: DashboardResponsiveOptions;
-  /** One view, or many (the tab pattern). Mutually exclusive with `widgets`. */
-  views?: DashboardViewSpec[];
-  /** Shorthand for a single unnamed view. */
-  widgets?: DashboardWidgetSpec[];
-  /**
-   * Paint a widget into its host element. Called once per widget when it
-   * mounts (the host is reused across re-renders, so this is not a per-frame
-   * hook). Omit for a titled placeholder frame.
-   */
-  renderWidget?: (widget: DashboardWidgetSpec, host: HTMLElement) => void;
-  /** Fires after any committed gesture, with the view whose layout changed. */
-  onLayoutChange?: (viewId: string, widgets: DashboardWidgetSpec[]) => void;
-  /** Extra binder options, merged last (escape hatch to the layer below). */
-  binder?: Partial<DashboardGridOptions>;
-}
-
-/** What `dashboard()` returns — a render spec plus the runtime handle. */
-export interface DashboardSpec {
-  nodes: Array<Record<string, unknown>>;
-  edges: Array<Record<string, unknown>>;
-  renderCustomNode: (node: unknown, host: HTMLElement) => void;
-  finalize: (api: unknown) => void;
-  /** Live handle, populated by finalize(). */
-  readonly handle: DashboardHandle;
-}
-
-/**
- * A whole board as plain data: every `DashboardOptions` field except the
- * function seams. `dashboard({ ...snapshot, renderWidget })` rebuilds it.
- *
- * Typed as an Omit rather than a hand-written twin on purpose — a field added
- * to `DashboardOptions` then joins the snapshot automatically instead of being
- * silently dropped, which is the exact failure this type exists to end.
- */
-export type DashboardSnapshot = Omit<
-  DashboardOptions,
-  'renderWidget' | 'onLayoutChange' | 'views'
-> & { views: DashboardViewSpec[] };
-
-/** The typed façade — the `erTable`/`umlClass` equivalent for dashboards. */
-export interface DashboardHandle {
-  /** The view ids, in declaration order. */
-  readonly views: string[];
-  /** Show a view (the others park off-camera) and frame it. */
-  showView(id: string): void;
-  /** The currently shown view id. */
-  readonly activeView: string;
-  /** A widget handle by id (undefined when unknown). */
-  widget(id: string): WidgetHandle | undefined;
-  /** Every widget handle of a view (default: the active one). */
-  widgetsOf(viewId?: string): WidgetHandle[];
-  /** Live sizing/float switches — the two prototype toggles. */
-  setSizing(mode: 'fit' | 'grow'): void;
-  getSizing(): 'fit' | 'grow';
-  setFloat(on: boolean): void;
-  getFloat(): boolean;
-  /**
-   * Set the COLUMN COUNT of every board (or one view), live. Goes through the
-   * engine's per-column layout cache, so shrinking then growing back restores
-   * the wide layout rather than re-deriving it. An explicit call PINS the
-   * count — the width-driven `responsive` evaluator stops overriding it.
-   */
-  setColumns(n: number, layout?: GridColumnLayout, viewId?: string): void;
-  /** The LIVE column count of a view (default: the active one). */
-  getColumns(viewId?: string): number;
-  /** RTL mirroring, live — pixels only, cells never change. */
-  setRtl(on: boolean): void;
-  getRtl(): boolean;
-  /**
-   * Add a widget to a view. CREATES the node (you do not pre-build one), wires
-   * its metadata, and commits node + membership as ONE undoable step.
-   * Auto-positions when the spec names no cell.
-   */
-  addWidget(spec: DashboardWidgetSpec, viewId?: string): WidgetHandle | undefined;
-  /**
-   * Re-read every board from the model — call after undo/redo, or any
-   * out-of-band mutation, so the grid and the projection agree again.
-   */
-  refresh(): void;
-  /** Re-frame the camera on a view (default: the active one). */
-  fit(viewId?: string): void;
-  /** Live geometry of a view's board (columns, gap, rows, rowHeight, frame…). */
-  metrics(viewId?: string): ReturnType<DashboardGridHandle['metrics']> | undefined;
-  /**
-   * The whole board as plain data — feed it straight back to `dashboard()`:
-   *
-   * ```ts
-   * dashboard({ ...handle.toJSON(), renderWidget });   // a true round trip
-   * ```
-   *
-   * Everything `DashboardOptions` takes EXCEPT the function seams
-   * (`renderWidget`, `onLayoutChange`), which cannot be written to a file and
-   * must be supplied again on the way back in.
-   *
-   * Values are read from the LIVE board, not from the authored literal, so a
-   * mode or column count the user changed after mount is what you get back.
-   *
-   * This used to return only `views`, which made the round-trip claim true of
-   * the layout and false of the board: a board authored `grow` at a 10-column,
-   * 6px-gap geometry reloaded as a 12-column `fit` one. It is also what
-   * `JSON.stringify(handle)` calls, so the partial answer was a permanent
-   * footgun in a save API rather than merely an omission.
-   */
-  toJSON(): DashboardSnapshot;
-  /**
-   * The node ids ONE view occupies — pass straight to `includeIds` to export
-   * just that board:
-   *
-   * ```ts
-   * api.export('pdf', { includeIds: handle.exportIds() });
-   * ```
-   *
-   * WHY THIS EXISTS. Tabs park the inactive views far off-camera, which is
-   * invisible on screen and ruinous on export: `export()` frames the whole
-   * MODEL, so a two-view board writes a ~21,000px document that is almost
-   * entirely empty — with no warning, because nothing is technically wrong.
-   * Scoping was always possible; knowing WHAT to scope to was not.
-   *
-   * The set includes the view's GROUP as well as its widgets. Rolling this by
-   * hand from `toJSON()` looks equivalent and is not — it drops the group, and
-   * the widgets export without the frame they sit in.
-   */
-  exportIds(viewId?: string): Set<string>;
-  /**
-   * THE DOCUMENTED ESCAPE HATCH: the view's own `bindDashboardGrid` handle
-   * (default: the active view). Reach for it only for what this façade does
-   * not cover yet — palette drag-in (`beginPaletteDrag`), board `metrics()`,
-   * `cellRectOf`, `planRemoval`, and re-`sync()` after an external undo. Every
-   * call site is a named gap in this API, not a normal way to drive a board.
-   */
-  binderOf(viewId?: string): DashboardGridHandle | undefined;
-  dispose(): void;
-}
-
-/** One widget's OO surface (mirrors ErTable/UmlClass). */
-export interface WidgetHandle {
-  readonly id: string;
-  readonly viewId: string;
-  readonly node: NodeModel | undefined;
-  /** The DECLARED spec — read it back (title/kind/data) without a side map. */
-  readonly spec: DashboardWidgetSpec;
-  /** Current cell, as data. */
-  readonly cell: { x: number; y: number; w: number; h: number } | undefined;
-  /** The world rect the current cell projects to. */
-  readonly rect: { x: number; y: number; width: number; height: number } | undefined;
-  /** Resize in CELLS. Resolves TRUE when the board accepted it. */
-  resize(span: number, rows: number): Promise<boolean>;
-  /** Move to a cell. Resolves TRUE when the board accepted it. */
-  moveTo(x: number, y: number): Promise<boolean>;
-  /** Pin / unpin (a pinned widget refuses the mover and never gets pushed). */
-  pin(on?: boolean): void;
-  readonly pinned: boolean;
-  /** Raise / lower — one undoable step each (mirrors the toolbar commands). */
-  bringToFront(): void;
-  sendToBack(): void;
-  /**
-   * Remove it — ONE undoable step including the survivors' re-pack.
-   * `displaced` accepts the commands a drag-out gesture already computed;
-   * omit it and the handle plans them itself.
-   */
-  remove(displaced?: unknown[]): void;
-  /** Replace the widget's `data` (and optionally title) and repaint. */
-  update(patch: Partial<Pick<DashboardWidgetSpec, 'data' | 'title' | 'kind'>>): void;
-  /** Repaint through `renderWidget` (after your data changed). */
-  repaint(): void;
-}
-
-/**
- * Add a widget node AND its board membership as ONE undoable step.
- *
- * A `BatchCommand([AddNodeCommand, AddToGroupCommand])` cannot express this:
- * the manager validates the whole batch up front, and
- * `AddToGroupCommand.canExecute` pre-gates on the node ALREADY being in the
- * diagram — which it is not until the first command runs. Sequencing two
- * commands works but costs two undo steps, so an interactive "add widget"
- * would need two Ctrl-Z. This composite does both in its own execute(), and
- * unwinds both in undo().
- */
-class AddWidgetCommand extends Command {
-  constructor(
-    private node: NodeModel,
-    private groupId: string
-  ) {
-    super('Add widget');
-  }
-
-  override execute(context: { diagram?: unknown }): void {
-    const diagram = context.diagram as
-      | { addNode(n: NodeModel): void; getGroup(id: string): GroupModel | undefined }
-      | undefined;
-    if (!diagram) return;
-    diagram.addNode(this.node);
-    diagram.getGroup(this.groupId)?.addMember(this.node.id);
-  }
-
-  override undo(context: { diagram?: unknown }): void {
-    const diagram = context.diagram as
-      | { removeNode(id: string): unknown; getGroup(id: string): GroupModel | undefined }
-      | undefined;
-    if (!diagram) return;
-    diagram.getGroup(this.groupId)?.removeMember(this.node.id);
-    diagram.removeNode(this.node.id);
-  }
-
-  override serialize() {
-    return {
-      id: this.id,
-      name: this.name,
-      timestamp: this.timestamp,
-      data: { nodeId: this.node.id, groupId: this.groupId },
-    };
-  }
-}
-
-const DEFAULTS = { columns: 12, gap: 8, rowHeight: 130, width: 1180, height: 660 };
-const OFFSCREEN_X = -20000;
-let autoId = 0;
-
-/** The node a widget spec becomes — one place, so addWidget() and the initial
- *  spec build can never drift apart on metadata. */
-function buildWidgetNode(w: DashboardWidgetSpec, rowHeight: number): NodeModel {
-  const node = new NodeModel({
-    id: w.id,
-    type: 'widget',
-    position: { x: 0, y: 0 },
-    size: { width: 120, height: rowHeight, depth: 0 },
-  });
-  node.setMetadata('useHTMLLayer', true);
-  node.setMetadata('widgetKind', w.kind ?? 'widget');
-  node.setMetadata('widgetSpec', w.data ?? {});
-  // The TITLE was the one authored field that never reached the node — so a
-  // document-level reload rebuilt every card with `titleOf()` falling through to
-  // the kind, and a board of "Revenue vs target" / "Top reps by revenue" came
-  // back as "line" / "table". Only written when authored, so an untitled widget
-  // serialises exactly as it always did.
-  if (w.title !== undefined) node.setMetadata('widgetTitle', w.title);
-  node.setMetadata('columnSpan', w.span ?? 3);
-  node.setMetadata('rowSpan', w.rows ?? 1);
-  if (w.x !== undefined && w.y !== undefined) {
-    node.setGridItem({
-      columnStart: w.x + 1,
-      columnEnd: w.x + 1 + (w.span ?? 3),
-      rowStart: w.y + 1,
-      rowEnd: w.y + 1 + (w.rows ?? 1),
-    });
-  }
-  // A dashboard widget is not a wiring endpoint: no ports, no hover glyphs.
-  node.setBehavior({ connectable: false });
-  for (const p of [...node.getPorts().values()]) node.removePort(p.id);
-  return node;
-}
-
-/** Flow widgets that declared no cell: left-to-right, wrapping at `columns`. */
-function assignCells(widgets: DashboardWidgetSpec[], columns: number): void {
-  let x = 0;
-  let y = 0;
-  let rowMax = 0;
-  for (const w of widgets) {
-    const span = Math.max(1, Math.min(columns, w.span ?? 3));
-    const rows = Math.max(1, w.rows ?? 1);
-    if (w.x === undefined || w.y === undefined) {
-      if (x + span > columns) {
-        x = 0;
-        y += rowMax || 1;
-        rowMax = 0;
-      }
-      w.x = x;
-      w.y = y;
-      x += span;
-      rowMax = Math.max(rowMax, rows);
-    }
-    w.span = span;
-    w.rows = rows;
-  }
-}
-
-/**
- * The API surface the handle drives — the slice of a DiagramInstance both
- * `dashboard().finalize` and `fromDocument().finalize` hand in. Named (was an
- * inline type on the old `apiRef` local) because two call sites now share it.
- */
-export interface DashboardApiRef {
-  getModel(): {
-    getNode(id: string): NodeModel | undefined;
-    addGroup(g: GroupModel): void;
-    getGroup(id: string): GroupModel | undefined;
-    removeGroup?(id: string): unknown;
-  };
-  getEngine?: () => { commandManager: { execute(c: unknown): unknown } };
-  renderNow(): void;
-  viewport?: { fitToBounds(r: unknown, pad: number, o?: unknown): void };
-}
-
-/**
- * Everything one `DashboardHandle` closes over, gathered into ONE object so a
- * single builder can serve both `dashboard()` (context built from the authored
- * literal) and `fromDocument()` (context reconstructed from the loaded model).
- *
- * `active` and `apiRef` are the two MUTABLE cells: the handle READS them on
- * every call and the builder WRITES them (showView reassigns `active`, the
- * caller's finalize sets `apiRef`). They live here rather than as free `let`s
- * precisely because there are now two call sites — a boxed cell one builder
- * reads and writes is the whole reason a second handle implementation, which
- * would silently drift, is not needed.
- */
-export interface DashboardHandleContext {
-  /** The views — MUTATED in place by addWidget (push) and remove (filter). */
-  views: DashboardViewSpec[];
-  groups: Map<string, GroupModel>;
-  binders: Map<string, DashboardGridHandle>;
-  specById: Map<string, DashboardWidgetSpec>;
-  viewOfWidget: Map<string, string>;
-  hosts: Map<string, HTMLElement>;
-  renderWidget: (widget: DashboardWidgetSpec, host: HTMLElement) => void;
-  columns: number;
-  gap: number;
-  rowHeight: number;
-  boardW: number;
-  boardH: number;
-  /**
-   * Spread verbatim into `toJSON()` output — carries width/height/responsive
-   * and any other authored option so a new `DashboardOptions` field round-trips
-   * for free (dashboard() passes the whole `options`; fromDocument() passes the
-   * geometry it can recover from the persisted board metadata).
-   */
-  optionsBase: Partial<DashboardOptions>;
-  /** MUTABLE — reassigned by showView(). */
-  active: string;
-  /** MUTABLE — set by the caller's finalize once the render API exists. */
-  apiRef: DashboardApiRef | null;
-}
-
-/**
- * Build THE `DashboardHandle` — the one and only implementation, shared by
- * `dashboard()` and `fromDocument()`. Reads/writes the mutable `ctx.active` /
- * `ctx.apiRef` cells so the caller's finalize can wire the API in afterwards.
- */
-export function createDashboardHandle(ctx: DashboardHandleContext): DashboardHandle {
-  const { views, groups, binders, specById, viewOfWidget } = ctx;
-
-  const hostOf = (id: string): HTMLElement | undefined => ctx.hosts.get(id);
-
-  const execCommand = (cmd: unknown): void => {
-    try {
-      const r = ctx.apiRef?.getEngine?.()?.commandManager.execute(cmd) as {
-        catch?: (f: () => void) => void;
-      };
-      // Fire-and-forget like the binder's own commits, but never leave an
-      // unhandled rejection: a refused command is a no-op, not a crash.
-      r?.catch?.(() => undefined);
-    } catch {
-      /* a refused command must not break the caller */
-    }
-  };
-
-  const handle: DashboardHandle = {
-    get views() {
-      return views.map((v) => v.id);
-    },
-    get activeView() {
-      return ctx.active;
-    },
-    showView(id) {
-      if (!groups.has(id)) return;
-      ctx.active = id;
-      for (const [vid, g] of groups) {
-        const x = vid === id ? 0 : OFFSCREEN_X;
-        const s = g.size ?? { width: ctx.boardW, height: ctx.boardH };
-        if (g.position.x !== x) g.setFrame({ x, y: 0, width: s.width, height: s.height });
-      }
-      binders.get(id)?.sync();
-      ctx.apiRef?.renderNow();
-      const g = groups.get(id)!;
-      const gs = g.size ?? { width: ctx.boardW, height: ctx.boardH };
-      ctx.apiRef?.viewport?.fitToBounds(
-        { x: g.position.x, y: g.position.y, width: gs.width, height: gs.height },
-        26,
-        { maxZoom: 1 }
-      );
-    },
-    widget(id) {
-      return makeWidgetHandle(id);
-    },
-    widgetsOf(viewId) {
-      const v = views.find((x) => x.id === (viewId ?? ctx.active));
-      return (v?.widgets ?? []).map((w) => makeWidgetHandle(w.id)).filter(Boolean) as WidgetHandle[];
-    },
-    setSizing(mode) {
-      for (const b of binders.values()) b.setSizing(mode);
-      ctx.apiRef?.renderNow();
-    },
-    getSizing: () => binders.get(ctx.active)?.getSizing() ?? (ctx.optionsBase.sizing ?? 'fit'),
-    setFloat(on) {
-      for (const b of binders.values()) b.setFloat(on);
-      ctx.apiRef?.renderNow();
-    },
-    getFloat: () => binders.get(ctx.active)?.getFloat() ?? (ctx.optionsBase.float ?? false),
-    setColumns(n, layout, viewId) {
-      const targets = viewId ? [binders.get(viewId)] : [...binders.values()];
-      for (const b of targets) b?.setColumns(n, layout);
-      ctx.apiRef?.renderNow();
-    },
-    getColumns: (viewId) => binders.get(viewId ?? ctx.active)?.getColumns() ?? ctx.columns,
-    setRtl(on) {
-      for (const b of binders.values()) b.setRtl(on);
-      ctx.apiRef?.renderNow();
-    },
-    getRtl: () => binders.get(ctx.active)?.getRtl() ?? (ctx.optionsBase.rtl ?? false),
-    addWidget(spec, viewId) {
-      const vid = viewId ?? ctx.active;
-      const v = views.find((x) => x.id === vid);
-      const model = ctx.apiRef?.getModel();
-      const group = groups.get(vid);
-      if (!v || !model || !group) return undefined;
-      const w: DashboardWidgetSpec = {
-        ...spec,
-        id: spec.id || `w-${++autoId}`,
-        span: spec.span ?? 3,
-        rows: spec.rows ?? 1,
-      };
-      // REGISTER FIRST: a custom node mounts exactly once, and the painter
-      // returns early for an id the spec does not know — so the widget must be
-      // known before the node reaches the model, or it paints blank forever.
-      v.widgets.push(w);
-      specById.set(w.id, w);
-      viewOfWidget.set(w.id, vid);
-
-      const existing = model.getNode(w.id);
-      const node = existing ?? buildWidgetNode(w, ctx.rowHeight);
-      if (w.pinned) node.setState({ locked: true });
-      // ONE undoable step (see AddWidgetCommand for why this cannot be a batch).
-      execCommand(existing ? new AddToGroupCommand(group.id, w.id) : new AddWidgetCommand(node, group.id));
-
-      binders.get(vid)?.sync();
-      ctx.apiRef?.renderNow();
-      return makeWidgetHandle(w.id);
-    },
-    refresh() {
-      for (const b of binders.values()) b.sync();
-      ctx.apiRef?.renderNow();
-    },
-    fit(viewId) {
-      const g = groups.get(viewId ?? ctx.active);
-      if (!g) return;
-      const gs = g.size ?? { width: ctx.boardW, height: ctx.boardH };
-      ctx.apiRef?.viewport?.fitToBounds(
-        { x: g.position.x, y: g.position.y, width: gs.width, height: gs.height },
-        26,
-        { maxZoom: 1 }
-      );
-    },
-    metrics(viewId) {
-      return binders.get(viewId ?? ctx.active)?.metrics();
-    },
-    binderOf(viewId) {
-      return binders.get(viewId ?? ctx.active);
-    },
-    exportIds(viewId) {
-      const id = viewId ?? ctx.active;
-      const ids = new Set<string>();
-      // A view with no group is a view that was never finalized — an empty set
-      // is the honest answer, and scoping an export to nothing is a visible
-      // failure rather than a silently enormous document.
-      if (!groups.has(id)) return ids;
-      ids.add(id);
-      // Read the SPEC, not the group's member Set: membership is maintained by
-      // commands and an in-flight drag can have a widget momentarily reparented.
-      // The spec is what the view IS.
-      for (const w of views.find((v) => v.id === id)?.widgets ?? []) ids.add(w.id);
-      return ids;
-    },
-    toJSON() {
-      // SAVING ON A PHONE SAVES THE DESKTOP LAYOUT. The binder serialises from
-      // the engine's LARGEST cached column count (gridstack's `save()`), so a
-      // board currently squeezed to 1 column still writes out the 12-column
-      // layout its user authored — and the view's `columns` is that count, so
-      // feeding this straight back into dashboard() rebuilds the wide board.
-      const savedViews = views.map((v) => {
-        const saved = binders.get(v.id)?.saveLayout();
-        return {
-          ...v,
-          ...(saved ? { columns: saved.columns } : {}),
-          widgets: v.widgets.map((w) => {
-            const cell = saved?.cells.get(w.id) ?? binders.get(v.id)?.cellOf(w.id);
-            return cell ? { ...w, x: cell.x, y: cell.y, span: cell.w, rows: cell.h } : { ...w };
-          }),
-        };
-      });
-
-      // Board options come off the LIVE board wherever the handle can see it —
-      // `sizing` and `float` are the two a user changes from the toolbar, and
-      // reading them from the authored literal would restore the board they
-      // started with rather than the one they are looking at.
-      return {
-        ...ctx.optionsBase,
-        renderWidget: undefined,
-        onLayoutChange: undefined,
-        columns: ctx.columns,
-        gap: ctx.gap,
-        rowHeight: ctx.rowHeight,
-        sizing: handle.getSizing(),
-        float: handle.getFloat(),
-        rtl: handle.getRtl(),
-        views: savedViews,
-      } as DashboardSnapshot;
-    },
-    dispose() {
-      for (const b of binders.values()) b.dispose();
-      binders.clear();
-      // The groups finalize() created are ours to clean up — leaving them
-      // behind made a rebuild stack a second set of boards on the first.
-      const model = ctx.apiRef?.getModel();
-      for (const id of groups.keys()) model?.removeGroup?.(id);
-      groups.clear();
-      ctx.hosts.clear();
-    },
-  };
-
-  function makeWidgetHandle(id: string): WidgetHandle | undefined {
-    const spec = specById.get(id);
-    const viewId = viewOfWidget.get(id);
-    if (!spec || !viewId) return undefined;
-    const binder = () => binders.get(viewId);
-    const node = () => ctx.apiRef?.getModel().getNode(id);
-    return {
-      id,
-      viewId,
-      get node() {
-        return node();
-      },
-      get spec() {
-        return spec;
-      },
-      get cell() {
-        return binder()?.cellOf(id);
-      },
-      get rect() {
-        return binder()?.cellRectOf(id);
-      },
-      get pinned() {
-        return node()?.state?.locked === true;
-      },
-      async resize(span, rows) {
-        return (await binder()?.resizeTo(id, span, rows)) ?? false;
-      },
-      async moveTo(x, y) {
-        return (await binder()?.moveTo(id, x, y)) ?? false;
-      },
-      pin(on) {
-        const n = node();
-        if (!n) return;
-        n.setState({ locked: on ?? !(n.state?.locked === true) });
-        // Re-sync so the ENGINE's locked flag (never pushed, drags refused)
-        // and the hidden corner handle take effect on this frame, not the next
-        // gesture.
-        binder()?.sync();
-        ctx.apiRef?.renderNow();
-      },
-      bringToFront() {
-        execCommand(new BringNodeToFrontCommand(id));
-        ctx.apiRef?.renderNow();
-      },
-      sendToBack() {
-        execCommand(new SendNodeToBackCommand(id));
-        ctx.apiRef?.renderNow();
-      },
-      update(patch) {
-        if (patch.data !== undefined) spec.data = patch.data;
-        if (patch.title !== undefined) spec.title = patch.title;
-        if (patch.kind !== undefined) spec.kind = patch.kind;
-        const host = hostOf(id);
-        if (host) ctx.renderWidget(spec, host);
-      },
-      remove(displaced) {
-        const n = node();
-        const group = groups.get(viewId);
-        const b = binder();
-        if (!n || !group || !b) return;
-        // ONE undoable step, survivors' re-pack folded in — the same atomic
-        // shape the kit's own drag-out-to-remove uses. A gesture that ALREADY
-        // computed the survivors passes them in: after a drag-out the tile is
-        // gone from the engine, so planRemoval() would return [] and the
-        // survivors' cells would never commit.
-        const survivors = (displaced as never[] | undefined) ?? b.planRemoval(id);
-        const cmds = [...survivors, new RemoveFromGroupCommand(group.id, id), new RemoveNodeCommand(id)];
-        void execCommand(new BatchCommand('Remove widget', cmds));
-        const v = views.find((x) => x.id === viewId);
-        if (v) v.widgets = v.widgets.filter((w) => w.id !== id);
-        specById.delete(id);
-        viewOfWidget.delete(id);
-        b.sync();
-        ctx.apiRef?.renderNow();
-      },
-      repaint() {
-        const host = hostOf(id);
-        if (host) ctx.renderWidget(spec, host);
-      },
-      // (hosts are captured in renderCustomNode, so repaint works for every
-      //  widget the renderer has mounted — including after a rebuild.)
-    };
-  }
-
-  return handle;
-}
-
-export function dashboard(options: DashboardOptions): DashboardSpec {
-  ensureDashboardKitStyles();
-
-  const columns = options.columns ?? DEFAULTS.columns;
-  const gap = options.gap ?? DEFAULTS.gap;
-  const rowHeight = options.rowHeight ?? DEFAULTS.rowHeight;
-  const boardW = options.width ?? DEFAULTS.width;
-  const boardH = options.height ?? DEFAULTS.height;
-
-  const views: DashboardViewSpec[] = options.views
-    ? options.views.map((v) => ({ ...v, widgets: v.widgets.map((w) => ({ ...w })) }))
-    : [{ id: 'main', widgets: (options.widgets ?? []).map((w) => ({ ...w })) }];
-  for (const v of views) assignCells(v.widgets, v.columns ?? columns);
-
-  // -- the render spec: one custom-HTML node per widget ----------------------
-  const nodes: Array<Record<string, unknown>> = [];
-  const specById = new Map<string, DashboardWidgetSpec>();
-  const viewOfWidget = new Map<string, string>();
-  for (const v of views) {
-    for (const w of v.widgets) {
-      specById.set(w.id, w);
-      viewOfWidget.set(w.id, v.id);
-      nodes.push({
-        id: w.id,
-        type: 'widget',
-        position: { x: 0, y: 0 },
-        size: { width: 100, height: rowHeight },
-        custom: true,
-        metadata: {
-          useHTMLLayer: true,
-          widgetKind: w.kind ?? 'widget',
-          widgetSpec: w.data ?? {},
-          // See buildWidgetNode(): the title has to reach the node or a reload
-          // cannot rebuild the card's header. These two paths are the drift the
-          // comment on buildWidgetNode warns about — they must agree.
-          ...(w.title !== undefined ? { widgetTitle: w.title } : {}),
-          columnSpan: w.span,
-          rowSpan: w.rows,
-          gridItem: { columnStart: w.x! + 1, columnEnd: w.x! + 1 + w.span!, rowStart: w.y! + 1, rowEnd: w.y! + 1 + w.rows! },
-        },
-      });
-    }
-  }
-
-  // No renderWidget → the built-in renderers draw the declared `kind` from the
-  // developer's own `data` (widgets.ts), unknown kinds landing on the titled
-  // frame they always did.
-  const renderWidget = options.renderWidget ?? defaultWidgetRenderer;
-
-  // -- runtime: ONE shared handle over a boxed context -----------------------
-  // The two MUTABLE cells the handle used to close over as free `let`s —
-  // `active` (showView reassigns it) and `apiRef` (finalize sets it) — are boxed
-  // on `ctx`, so the SAME builder that fromDocument() calls reads and writes
-  // them. Everything else is the stable state; the handle is identical to what
-  // was inline here, moved verbatim into createDashboardHandle().
-  const ctx: DashboardHandleContext = {
-    views,
-    groups: new Map<string, GroupModel>(),
-    binders: new Map<string, DashboardGridHandle>(),
-    specById,
-    viewOfWidget,
-    hosts: new Map<string, HTMLElement>(),
-    renderWidget,
-    columns,
-    gap,
-    rowHeight,
-    boardW,
-    boardH,
-    optionsBase: options,
-    active: views[0]?.id ?? 'main',
-    apiRef: null,
-  };
-  const { binders, groups } = ctx;
-  const handle = createDashboardHandle(ctx);
-
-  return {
-    nodes,
-    edges: [],
-    renderCustomNode: (node: unknown, host: HTMLElement) => {
-      const n = node as { id: string };
-      const spec = specById.get(n.id);
-      if (!spec) return;
-      ctx.hosts.set(n.id, host);
-      renderWidget(spec, host);
-    },
-    get handle() {
-      return handle;
-    },
-    finalize: (api: unknown) => {
-      const a = api as DashboardApiRef | null;
-      if (!a) return;
-      ctx.apiRef = a;
-      const model = a.getModel();
-
-      for (const v of views) {
-        // One board per view; the group is a pure LAYOUT CONTAINER, so its
-        // chrome is suppressed (frameChrome) exactly as a dashboard needs.
-        const g = new GroupModel({ id: v.id, name: v.name ?? v.id });
-        model.addGroup(g);
-        g.setMetadata('frameChrome', 'none');
-        // THE BOARD'S GEOMETRY, PERSISTED. Cells alone do not describe a board:
-        // the column count, gap and sizing mode are what turn them into pixels,
-        // and they live only in the `dashboard()` call. Without them a reloaded
-        // document could paint the widgets but never rebind the grid — the
-        // reload would be a picture of a dashboard rather than a dashboard.
-        // Serializable values only: the binder's callbacks belong to the app.
-        g.setMetadata('dashboardBoard', {
-          columns: v.columns ?? columns,
-          gap,
-          padding: gap,
-          sizing: options.sizing ?? 'fit',
-          baseRowHeight: rowHeight,
-          designHeight: v.height ?? boardH,
-          float: options.float ?? false,
-          rtl: options.rtl ?? false,
-        });
-        g.size = { width: v.width ?? boardW, height: v.height ?? boardH, depth: 0 };
-        g.position = { x: v.id === ctx.active ? 0 : OFFSCREEN_X, y: 0 };
-        groups.set(v.id, g);
-        for (const w of v.widgets) {
-          const n = model.getNode(w.id);
-          if (!n) continue;
-          // DECLARED CELLS ARE AUTHORITATIVE. `metadata.gridItem` on the node
-          // SPEC is inert — the model's GridItemConfig is a real field
-          // (`setGridItem`), and it is the only thing the binder reads. Without
-          // this write the board silently auto-positioned instead, which
-          // matched the declaration only while flow order happened to agree,
-          // and made toJSON() → dashboard() NOT round-trip (a saved layout
-          // rebuilt back into its declaration order rather than its cells).
-          if (w.x !== undefined && w.y !== undefined) {
-            n.setGridItem(gridItemFromCell({ x: w.x, y: w.y, w: w.span ?? 3, h: w.rows ?? 1 }));
-          }
-          if (w.pinned) n.setState({ locked: true });
-          // A dashboard widget is not a wiring endpoint. This MUST happen here
-          // rather than on the node spec: the render-input path IGNORES a
-          // spec-level `behavior` (the same trap erDiagram documents for
-          // `resizable`), so a DECLARED widget shipped connectable with four
-          // default ports and sprouted glyphs on hover — while addWidget()'s
-          // directly-built nodes were already correct. One path being right is
-          // exactly what hid it, and why the tooth now covers both.
-          n.setBehavior({ connectable: false });
-          for (const p of [...n.getPorts().values()]) n.removePort(p.id);
-          g.addMember(w.id);
-        }
-        binders.set(
-          v.id,
-          bindDashboardGrid(a as never, g, {
-            columns: v.columns ?? columns,
-            gap,
-            padding: gap,
-            sizing: options.sizing ?? 'fit',
-            baseRowHeight: rowHeight,
-            designHeight: v.height ?? boardH,
-            float: options.float ?? false,
-            rtl: options.rtl ?? false,
-            ...(options.responsive ? { responsive: options.responsive } : {}),
-            ...(options.binder ?? {}),
-            onGesture: (e) => {
-              if (e.type === 'commit' && options.onLayoutChange) {
-                const snapshot = handle.toJSON().views.find((x) => x.id === v.id);
-                if (snapshot) options.onLayoutChange(v.id, snapshot.widgets);
-              }
-              options.binder?.onGesture?.(e);
-            },
-          })
-        );
-      }
-      handle.showView(ctx.active);
-    },
-  };
-}