@grafloria/element 0.1.0

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

@@ -0,0 +1,277 @@
+/**
+ * `bindDashboardGrid(api, group, options)` — the dashboard-grid gesture binder
+ * (Phase 2 of the dashboard-grid plan; the plan page's Section-1 prototype is
+ * the executable spec of the feel this reproduces).
+ *
+ * One binder owns ONE `GridPackEngine` mirroring the group's members — the
+ * engine is the single source of truth for cell math (three swap shapes, the
+ * >50% anti-jitter gate, locked refusal, push-down + skipDown, teleport-home
+ * settle). This module only converts: pointer → cells in, cells → pixels out,
+ * gesture → ONE undoable BatchCommand.
+ *
+ * HOW THE RENDERER'S OWN NODE-DRAG IS BYPASSED — a registered `CanvasTool`
+ * (the renderer's wave-6 tool registry, `registerTool`). The tool makes a
+ * POINT-SPECIFIC claim (priority 2, like the whiteboard ink tool): any
+ * pointerdown whose hit node is a member of the bound group, or that lands
+ * inside a member group's frame with no node under it (the KPI-slab dead
+ * zone — otherwise the built-in group-drag would fight the pack layout
+ * there). A claimed gesture bypasses the ENTIRE built-in ladder — node-drag,
+ * selection, marquee, wave-12 resize handles — and the DomEventBinder
+ * forwards move/up/cancel with world coordinates already computed. This beats
+ * `behavior.draggable = false` (which still runs selection and shows the
+ * built-in resize handles) and beats capture-phase DOM listeners (which fight
+ * the binder's own preventDefault bookkeeping). `click` is NOT a
+ * compatibility mouse event, so the page's click-to-focus keeps firing for
+ * sub-threshold presses.
+ *
+ * DURING a gesture, positions are written through the MODEL, not commands:
+ *  - the held tile is a GHOST — transition-exempt, tracking the cursor in
+ *    WORLD coordinates (no `position: fixed` hack; the html layer carries the
+ *    camera transform, and the tool events arrive already converted);
+ *  - every cell crossing runs `engine.moveCheck` / `resizeCheck`; every item
+ *    the engine displaced is re-projected cells→pixels. Those writes are
+ *    DERIVED state, so they run inside `diagram.runSystemWrite` — which is
+ *    also what lets a PINNED tile's pixels follow a fit-mode row-height
+ *    change without violating the authoritative geometry lock (its CELLS
+ *    never change; the pin protects the document fact, not the projection);
+ *  - a dashed PLACEHOLDER (`.axdb-ph`) always shows the engine's current cell
+ *    for the held tile — the truthful drop preview.
+ *
+ * The gesture ends in ONE `BatchCommand`: `SetGridItemCommand` per tile whose
+ * cells changed (cells are the truth) + `MoveNodeCommand`/`ResizeNodeCommand`
+ * (merge-opted-OUT) per unlocked node whose geometry changed, so a bare undo
+ * restores geometry AND cells with no binder help. Escape restores the
+ * engine snapshot (`cancelGesture`) and every pixel — nothing is committed.
+ *
+ * MEMBER GROUPS (e.g. a KPI section) ride as LOCKED slab items — never
+ * pushed, never packed, drags onto them refused (the prototype's pinned
+ * full-width row). Their cells persist in group metadata `gridItem` (groups
+ * carry no GridItemConfig); their INNER layout is their own concern — bind a
+ * second `bindDashboardGrid` on the section for a nested pack grid.
+ */
+import { Command, type DiagramModel, type GridColumnLayout, type GroupModel, type NodeModel } from '@grafloria/engine';
+import { type CellRect, type WorldRect } from './grid-mapping';
+/** The slice of a DiagramInstance the binder needs (structural, test-friendly). */
+export interface DashboardGridApi {
+    getModel(): DiagramModel;
+    getEngine(): {
+        commandManager: {
+            execute(cmd: Command): Promise<unknown> | unknown;
+        };
+    };
+    readonly container: HTMLElement;
+    readonly viewport?: {
+        clientToWorld(clientX: number, clientY: number, rect: {
+            left: number;
+            top: number;
+            width: number;
+            height: number;
+        }): {
+            x: number;
+            y: number;
+        };
+    };
+    render(): void;
+    renderNow(): void;
+}
+/**
+ * RESPONSIVE COLUMN COUNT — gridstack's `columnOpts`, driven by the BOARD's
+ * width. Give it `columnWidth`, or `breakpoints`, or both (breakpoints win).
+ *
+ * The binder owns the recomputation, not the page: it re-evaluates whenever
+ * the group's frame changes AND whenever the canvas container resizes, so a
+ * board that tracks the viewport and a board resized by a control both work
+ * with no page code. Column changes are DERIVED state — they re-project
+ * pixels and re-write cells through `runSystemWrite`, never through the
+ * command stack, so responding to a window resize can never land in undo.
+ */
+export interface DashboardResponsiveOptions {
+    /**
+     * Target width of ONE column, px. The count is `round(boardWidth /
+     * columnWidth)`, clamped to `[1, columnMax]` — gridstack's `columnWidth`.
+     */
+    columnWidth?: number;
+    /**
+     * Upper bound for the derived count, and the count used when no breakpoint
+     * matches. Defaults to the binder's declared `columns`.
+     */
+    columnMax?: number;
+    /**
+     * Explicit steps, gridstack-style: the FIRST entry (ascending by `w`) whose
+     * `w` is at least the board width decides the count. Wider than every entry
+     * → `columnMax`. Each step may name its own re-layout mode.
+     */
+    breakpoints?: Array<{
+        w: number;
+        c: number;
+        layout?: GridColumnLayout;
+    }>;
+    /** Default re-layout mode for a change (see {@link GridColumnLayout}). */
+    layout?: GridColumnLayout;
+}
+export interface DashboardGridOptions {
+    /** Column count (default 12). With `responsive`, the starting/maximum count. */
+    columns?: number;
+    /**
+     * RIGHT-TO-LEFT board. Cells are unchanged — x=0 is still the first column —
+     * but it renders at the board's RIGHT edge and columns run leftwards. Purely
+     * a pixel-mapping concern: the engine, the cells and every saved layout are
+     * direction-agnostic.
+     */
+    rtl?: boolean;
+    /** Derive the column count from the board's width (see the interface). */
+    responsive?: DashboardResponsiveOptions;
+    /** Fires after a responsive (or programmatic) column-count change. */
+    onColumnsChange?: (columns: number, previous: number) => void;
+    /** Gap between cells, px (default 12). */
+    gap?: number;
+    /** Board padding, px (default = gap). */
+    padding?: number;
+    /** Sizing mode (default 'fit' — the user decision recorded in the plan). */
+    sizing?: 'fit' | 'grow';
+    /** 'grow' row height, px (default 110). */
+    baseRowHeight?: number;
+    /** 'fit' row-height floor, px (default 28). */
+    minRowHeight?: number;
+    /**
+     * The board's design height (default: the group's height at bind time).
+     * 'fit' pins the frame to it; 'grow' never shrinks the frame below it.
+     */
+    designHeight?: number;
+    /** Engine float mode (default false → gravity packs upward). */
+    float?: boolean;
+    /**
+     * Engine row bound (see GridPackOptions.maxRows). A nested strip like the
+     * KPI section passes 1: its DESIGN is one row, so height growth and pushes
+     * that would spill a sibling downward are refused (siblings shift along the
+     * row instead), and the strip can never be squeezed.
+     */
+    maxRows?: number;
+    /**
+     * What dragging a tile OUT of the board means (default 'cancel' — the tile
+     * snaps back on release). 'remove' dims the ghost outside the board and a
+     * release outside calls `onRemoveRequest` — deletion stays on the page's
+     * atomic command path.
+     */
+    dragOut?: 'remove' | 'cancel';
+    /**
+     * With dragOut:'remove', restrict deletion to an EXPLICIT drop zone (the
+     * page passes "over the palette" — gridstack web2's trash semantics).
+     * Outside the zone a release snaps home instead: a 60px overshoot past the
+     * frame edge must never destroy a widget (live parity review — the plan
+     * prototype clamps at its edges and cannot delete at all).
+     */
+    removeZone?: (screen: {
+        x: number;
+        y: number;
+    }, world: {
+        x: number;
+        y: number;
+    }) => boolean;
+    /**
+     * Page hook for drag-out removal: execute ONE undoable batch that removes
+     * `nodeId` AND applies `displaced` (the survivors' cell commits, so undo
+     * restores the exact board).
+     */
+    onRemoveRequest?: (nodeId: string, displaced: Command[]) => void | Promise<void>;
+    /**
+     * Page hook for palette drag-in release: add `node` (already carrying
+     * `cell` in its gridItem, already placed in the engine) through the page's
+     * command path, folding `displaced` into the same batch.
+     */
+    onDropIn?: (node: NodeModel, cell: CellRect, displaced: Command[]) => void | Promise<void>;
+    /** Fires after commits/cancels/removals so the page can refocus/refit/flash. */
+    onGesture?: (e: {
+        type: 'commit' | 'cancel' | 'remove' | 'drop-in';
+        kind: 'move' | 'resize' | 'palette';
+        nodeId: string;
+        changed: boolean;
+    }) => void;
+    /** Inject the hover-revealed corner resize handle into member hosts (default true). */
+    resizeHandles?: boolean;
+}
+export interface DashboardGridHandle {
+    /** Rebuild the engine from the group's members + their cells, re-project pixels. */
+    sync(): void;
+    setSizing(mode: 'fit' | 'grow'): void;
+    getSizing(): 'fit' | 'grow';
+    /**
+     * Engine float mode, live (the prototype's second toggle): ON — tiles stay
+     * exactly where placed, vertical gaps are legal; OFF — gravity re-packs
+     * upward immediately.
+     */
+    setFloat(on: boolean): void;
+    getFloat(): boolean;
+    /**
+     * Change the COLUMN COUNT live (gridstack's `column(n, layout)`), through the
+     * engine's per-column layout cache: shrinking caches the layout it leaves,
+     * growing back restores it. Returns true when the count actually changed.
+     *
+     * Calling this directly PINS the count — it switches the responsive
+     * evaluator off, so a board under an explicit count is not fought by its own
+     * width observer. `setColumns(n, layout, { responsive: true })` is the
+     * evaluator's own path back.
+     */
+    setColumns(n: number, layout?: GridColumnLayout, opts?: {
+        responsive?: boolean;
+    }): boolean;
+    getColumns(): number;
+    /** RTL mirroring, live. Cells never change — only the pixels. */
+    setRtl(on: boolean): void;
+    getRtl(): boolean;
+    /**
+     * The layout to PERSIST — from the engine's LARGEST cached column count, so
+     * saving while the board is narrow still saves the wide layout the user
+     * authored (gridstack's `save()` semantics).
+     */
+    saveLayout(): {
+        columns: number;
+        cells: Map<string, CellRect>;
+    };
+    /** Live board metrics (mapping inputs + derived row height / rows). */
+    metrics(): {
+        /** The LIVE column count — with `responsive`, this is what width chose. */
+        columns: number;
+        /** The declared maximum (the count the board was authored at). */
+        maxColumns: number;
+        rtl: boolean;
+        responsive: boolean;
+        gap: number;
+        padding: number;
+        sizing: 'fit' | 'grow';
+        rows: number;
+        rowHeight: number;
+        columnUnit: number;
+        boardHeight: number;
+        frame: WorldRect;
+    };
+    /** The engine's cell record for a member (undefined when not a member). */
+    cellOf(id: string): CellRect | undefined;
+    /** World rect the member's current cells project to. */
+    cellRectOf(id: string): WorldRect | undefined;
+    /** Commands that reconcile the survivors after removing `id` — fold into the remove batch. */
+    planRemoval(id: string): Command[];
+    /**
+     * Programmatic single-step gestures — the demo asserts' deterministic hook.
+     * Same pipeline as a pointer gesture, committed as ONE BatchCommand. Unlike
+     * a pointer commit (which fire-and-forgets, wave-3 style, because the
+     * visible state is already final), these AWAIT the command execution so a
+     * caller can undo immediately after.
+     */
+    moveTo(id: string, x: number, y: number): Promise<boolean>;
+    resizeTo(id: string, w: number, h: number): Promise<boolean>;
+    /**
+     * Palette drag-in: `node` is a DETACHED widget node (not yet in the model).
+     * A chip follows the cursor; entering the board places the node's item in
+     * the engine (first placement skips the anti-jitter gate, as gridstack's
+     * drag-in does) and the normal live-push loop takes over. Release inside →
+     * `onDropIn`; release outside / Escape → aborted, nothing committed.
+     */
+    beginPaletteDrag(node: NodeModel, spec: {
+        w: number;
+        h: number;
+        chip?: HTMLElement;
+    }, event: PointerEvent): void;
+    dispose(): void;
+}
+export declare function bindDashboardGrid(api: DashboardGridApi, group: GroupModel, options?: DashboardGridOptions): DashboardGridHandle;