@grafloria/element 0.4.1 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafloria/element",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "type": "module",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",

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

@@ -44,6 +44,7 @@
  */
 import { GroupModel, NodeModel, type GridColumnLayout } from '@grafloria/engine';
 import { type DashboardGridHandle, type DashboardGridOptions, type DashboardResponsiveOptions } from './grid-binder.js';
+import type { SplitNode } from './split-layout.js';
 /** A widget, declared as data. */
 export interface DashboardWidgetSpec {
     id: string;
@@ -60,10 +61,50 @@ export interface DashboardWidgetSpec {
     y?: number;
     /** Pinned: never pushed, refuses the mover, survives every reflow. */
     pinned?: boolean;
+    /**
+     * SIZE LIMITS in cells (gridstack's minW/maxW/minH/maxH). A resize — by
+     * hand, by the API, or by a column change scaling widths — clamps to them.
+     * `maxRows` here is the WIDGET's row limit; a container's inner row count is
+     * its own `maxRows` field one level up, which is why these live in `limits`.
+     */
+    limits?: {
+        minSpan?: number;
+        maxSpan?: number;
+        minRows?: number;
+        maxRows?: number;
+    };
+    /** May the user drag it? Default true. The API can always move it. */
+    movable?: boolean;
+    /** May the user resize it? Default true (no handle when false). The API can always resize it. */
+    resizable?: boolean;
     /** Your payload — passed straight back to `renderWidget`. */
     data?: Record<string, unknown>;
     /** Optional title used by the built-in fallback renderer. */
     title?: string;
+    /**
+     * CONTAINMENT. A widget carrying `widgets` is a CONTAINER: it mounts as a
+     * member group (a locked slab in its parent's grid, exactly like a view's
+     * board one level down) with its own nested pack grid bound on it. Children
+     * lay out inside its frame; dragging a tile across the boundary adopts it
+     * live in either direction, and one undo restores the whole gesture.
+     * Containers may nest — tested to TWO levels; deeper is not exercised by
+     * the gates and rides at your own risk. A container renders no card of its
+     * own (`kind`/`data` are carried for your bookkeeping and serialization,
+     * not painted).
+     */
+    widgets?: DashboardWidgetSpec[];
+    /**
+     * Container only: column count of the INNER grid (default: the parent
+     * board's column count).
+     */
+    columns?: number;
+    /**
+     * Container only: the inner grid's designed row count. A child resized past
+     * it ESCALATES — the container's slab grows a row in the parent board (the
+     * ratchet), instead of the child overflowing the frame. Default: the row
+     * extent of the declared children.
+     */
+    maxRows?: number;
 }
 /** One board. Multiple views are the tab pattern: only one is on-camera. */
 export interface DashboardViewSpec {
@@ -74,14 +115,41 @@ export interface DashboardViewSpec {
     columns?: number;
     width?: number;
     height?: number;
+    /** Per-view layout (default: the dashboard-level `layout`). `toJSON()` writes it per view. */
+    layout?: 'grid' | 'split';
+    /**
+     * SPLIT layout only: the authored splitter tree (see `layout`). Omit it and
+     * the tree is derived from the widgets' cells, so a grid-authored view keeps
+     * its proportions when it opens as a split board. `toJSON()` writes it back.
+     */
+    tree?: SplitNode | null;
 }
 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 mode. 'grow': rows keep `rowHeight` and the board extends
+     * downward — the default on a FLUID board, and what every grid library
+     * does: dragging one tile never resizes another. 'fit': the board keeps its
+     * height and rows squeeze so everything stays on one screen (bounded, see
+     * `overflow`) — the default on a FIXED board, and the choice for a designer
+     * who wants the whole dashboard visible at once.
+     */
     sizing?: 'fit' | 'grow';
+    /**
+     * HOW THE BOARD IS LAID OUT (the DevExpress question, decided 6 Sep 2026).
+     * 'grid' (the default): the cell grid — columns, spans, push, gravity, the
+     *   gridstack model. 'split': a splitter tree — the board is always covered;
+     *   one widget fills it, a second halves it, a third halves the larger half
+     *   the other way; dividers drag as percentages; a drag lifts the widget out
+     *   and an insertion line on the nearest edge says where it lands; a removed
+     *   widget's slot goes to its siblings. Sizing is always fit under 'split'.
+     *   Switch live with `handle.setLayout()`: grid cells become a tree by
+     *   guillotine cuts, a tree becomes cells by snapping to the columns.
+     */
+    layout?: 'grid' | 'split';
     /** Row height in 'grow' mode, px (default 130). */
     rowHeight?: number;
     /** Board size, px (default 1180 × 660). */
@@ -89,6 +157,37 @@ export interface DashboardOptions {
     height?: number;
     /** Engine float mode (default false → gravity packs upward). */
     float?: boolean;
+    /**
+     * DIAGRAM OR LAYOUT — the one switch (decision of 2026-09-06).
+     *
+     * 'fluid' (the default): the board is 100% of its container, laid out at
+     *   real CSS pixels; zoom is pinned at 1; a plain wheel scrolls; in 'fit' the
+     *   height follows the container too. What every grid library does, and
+     *   what "responsive" means to a dashboard author.
+     * 'fixed': the authored `width`/`height` are the world, and the camera frames
+     *   them — today's behaviour, kept for a dashboard embedded inside a larger
+     *   diagram. An explicit `width` implies 'fixed', so existing boards keep
+     *   their behaviour without naming a mode.
+     */
+    mode?: 'fluid' | 'fixed';
+    /**
+     * FIT MEANS BOUNDED. In 'fit' the board never changes size; widgets do. Past
+     * the row floor the design height is a CAPACITY: a drop, resize or
+     * `addWidget()` that would need one row too many is refused (the placeholder
+     * stays put, the palette chip dims, `addWidget` returns undefined) — at
+     * design time, instead of tiles painted past the frame. A board that already
+     * holds more than fits (a grow→fit switch, a loaded document) squeezes its
+     * rows below the floor: a bounded fit board NEVER scrolls. 'scroll' is the
+     * opt-in for boards that want more than fits: the frame extends to hold the
+     * rows at the floor height and the canvas pans.
+     */
+    overflow?: 'bounded' | 'scroll';
+    /**
+     * STATIC board (gridstack's `staticGrid`): no drag, no resize, no handles —
+     * the viewer's mode. The API (moveTo, resize, addWidget, undo) still works,
+     * so a designer/viewer pair is one flag apart. Live: `handle.setStatic()`.
+     */
+    static?: 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
@@ -128,6 +227,14 @@ export interface DashboardSpec {
     finalize: (api: unknown) => void;
     /** Live handle, populated by finalize(). */
     readonly handle: DashboardHandle;
+    /**
+     * Instance options the spec asks `render()` to apply — a fluid board pins
+     * the zoom range to 1 so the layout can never become a scaled picture.
+     */
+    renderOptions?: {
+        minZoom?: number;
+        maxZoom?: number;
+    };
 }
 /**
  * A whole board as plain data: every `DashboardOptions` field except the
@@ -152,6 +259,14 @@ export interface DashboardHandle {
     widget(id: string): WidgetHandle | undefined;
     /** Every widget handle of a view (default: the active one). */
     widgetsOf(viewId?: string): WidgetHandle[];
+    /**
+     * Switch a view (default: the active one) between the cell grid and the
+     * split tree, live and keeping the picture: cells → tree by guillotine cuts,
+     * tree → cells by snapping to the columns. Persisted on the board, so a
+     * saved document reopens in the layout it was left in.
+     */
+    setLayout(layout: 'grid' | 'split', viewId?: string): void;
+    getLayout(viewId?: string): 'grid' | 'split';
     /** Live sizing/float switches — the two prototype toggles. */
     setSizing(mode: 'fit' | 'grow'): void;
     getSizing(): 'fit' | 'grow';
@@ -169,6 +284,9 @@ export interface DashboardHandle {
     /** RTL mirroring, live — pixels only, cells never change. */
     setRtl(on: boolean): void;
     getRtl(): boolean;
+    /** Static (read-only for the pointer) mode, live — the viewer/designer switch. */
+    setStatic(on: boolean): void;
+    getStatic(): 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.
@@ -287,15 +405,38 @@ export interface DashboardApiRef {
         addGroup(g: GroupModel): void;
         getGroup(id: string): GroupModel | undefined;
         removeGroup?(id: string): unknown;
+        removeNode?(id: string): unknown;
+        /** Derived writes (a layout switch) bypass the history like the binder's own. */
+        runSystemWrite?(fn: () => void): void;
     };
     getEngine?: () => {
         commandManager: {
             execute(c: unknown): unknown;
         };
+        /** The engine's bus — the kit listens for history events on it (D3). */
+        eventBus?: {
+            on(event: string, handler: (...args: unknown[]) => void): () => void;
+        };
     };
     renderNow(): void;
     viewport?: {
         fitToBounds(r: unknown, pad: number, o?: unknown): void;
+        /** Fluid boards pin the camera instead of framing the board. */
+        setZoom?(z: number): unknown;
+        getViewport?(): {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        setViewport?(r: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        }): void;
+        /** Camera changes (wheel, drag-pan, a canvas resize) — the fluid clamp listens. */
+        onChange?(listener: (state: unknown) => void): () => void;
     };
 }
 /**
@@ -316,7 +457,17 @@ export interface DashboardHandleContext {
     groups: Map<string, GroupModel>;
     binders: Map<string, DashboardGridHandle>;
     specById: Map<string, DashboardWidgetSpec>;
+    /** Widget id → the BOARD that owns it (a view id, or a container id). */
     viewOfWidget: Map<string, string>;
+    /** Every board group — the views PLUS every container. Views also live in
+     *  `groups` (the parking map showView drives); containers deliberately do
+     *  NOT — parking flings a group to OFFSCREEN_X, and a container must follow
+     *  its parent, not travel on its own. */
+    boardGroups: Map<string, GroupModel>;
+    /** Board id → its authored widgets array (views and containers alike). */
+    boardWidgets: Map<string, DashboardWidgetSpec[]>;
+    /** Board id → the VIEW it belongs to (identity for views). */
+    viewOfBoard: Map<string, string>;
     hosts: Map<string, HTMLElement>;
     renderWidget: (widget: DashboardWidgetSpec, host: HTMLElement) => void;
     columns: number;
@@ -324,6 +475,13 @@ export interface DashboardHandleContext {
     rowHeight: number;
     boardW: number;
     boardH: number;
+    /** See DashboardOptions.mode / overflow. */
+    mode: 'fluid' | 'fixed';
+    overflow: 'bounded' | 'scroll';
+    /** See DashboardOptions.layout — per view. */
+    layoutOf: Map<string, 'grid' | 'split'>;
+    /** Set by finalize: re-bind a VIEW's board under the given layout (setLayout). */
+    rebindView?: (viewId: string, layout: 'grid' | 'split') => void;
     /**
      * Spread verbatim into `toJSON()` output — carries width/height/responsive
      * and any other authored option so a new `DashboardOptions` field round-trips
@@ -335,6 +493,28 @@ export interface DashboardHandleContext {
     active: string;
     /** MUTABLE — set by the caller's finalize once the render API exists. */
     apiRef: DashboardApiRef | null;
+    /** The consumer's layout hook, if any (dashboard() passes its option). */
+    onLayoutChange?: (viewId: string, widgets: DashboardWidgetSpec[]) => void;
+    /**
+     * Set by createDashboardHandle. `reportChanged()` fires `onLayoutChange` for
+     * every view whose layout differs from the last report — ONE reporter for
+     * pointer commits, API calls, undo/redo and column changes alike, so a
+     * consumer's autosave sees every change and never the same change twice.
+     * `attachHistory()` is what finalize calls once `apiRef` exists: it
+     * subscribes the boards to the command history so an undo re-syncs them
+     * without the consumer calling refresh().
+     */
+    reportChanged?: () => void;
+    attachHistory?: () => void;
+    /** Unsubscribers dispose() runs. */
+    subscriptions?: Array<() => void>;
+    /**
+     * Re-bind a CONTAINER whose group came back through the history (undo of a
+     * container removal restores the group as a fresh GroupModel, which the old
+     * binder cannot see). Set by the two finalizes; called by the history
+     * handler for any board group the model holds without a binder.
+     */
+    rebindContainer?: (id: string) => void;
 }
 /**
  * Build THE `DashboardHandle` — the one and only implementation, shared by