@grafloria/element 0.1.0

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

@@ -0,0 +1,345 @@
+/**
+ * `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 { GroupModel, NodeModel, type GridColumnLayout } from '@grafloria/engine';
+import { type DashboardGridHandle, type DashboardGridOptions, type DashboardResponsiveOptions } from './grid-binder';
+/** 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;
+}
+/**
+ * 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 declare function createDashboardHandle(ctx: DashboardHandleContext): DashboardHandle;
+export declare function dashboard(options: DashboardOptions): DashboardSpec;