@grafloria/element 0.3.18 → 0.3.20

package/src/libs/engine/src/layout/grid-pack/grid-pack-engine.d.ts

@@ -0,0 +1,323 @@
+/**
+ * GridPackEngine — the dashboard-grid interaction engine (Phase 1 of the
+ * dashboard-grid plan; `documentation/api-architecture/dashboard-grid-plan.html`).
+ *
+ * A DOM-free, deterministic INTEGER-CELL engine implementing the gridstack
+ * interaction model, with semantics EMPIRICALLY RECORDED from the real
+ * gridstackjs.com demos (web1 + web2 driven with Playwright; gs-x/gs-y read at
+ * every stage), then hand-tested four rounds on the interactive prototype the
+ * plan page embeds. The recordings — not the gridstack source, which we found
+ * misleading on E4b — are this engine's contract:
+ *
+ *   E1  resize grow→shrink in ONE gesture: pushed tiles RETURN when the space
+ *       frees (emergent from re-settling after every step).
+ *   E2  tiles below CLIMB into vacated space live during a drag; after the
+ *       gesture ends there is NO memory (a later gesture re-resolves fresh).
+ *   E3  same-size side-by-side tiles SWAP cleanly, no oscillation.
+ *   E4b a move ONTO a locked tile is REFUSED outright — the placeholder never
+ *       enters it. (The source reads as "skip below"; the live demo refuses.)
+ *   E4c grow→shrink taller: full restore — same mechanism as E1.
+ *
+ * Plus three user-review rules the prototype rounds added:
+ *   S1  a swap exchanges CELLS exactly — never "the probe cell" (that left a
+ *       one-column overlap when the probe straddled the neighbour's edge).
+ *   S2  displaced tiles remember their gesture-start cell and TELEPORT home
+ *       when it frees — even from below a pinned row, which gravity alone can
+ *       never climb back through. This is a deliberate improvement over
+ *       gridstack itself. Memory clears at gesture end (E2).
+ *   S3  gridstack's swap() has THREE shapes, not one: same size; same ROW +
+ *       equal height (different widths — exchange horizontal order, union
+ *       span preserved); same COLUMN + equal width. And the >50% anti-jitter
+ *       gate must measure swap-eligible pairs against the SMALLER tile, or a
+ *       4-wide can never displace an 8-wide and swapping is one-directional.
+ *
+ * The engine mutates ONLY the {x,y,w,h} cells of the items it is given. Pixel
+ * mapping (row height, margins, the fit/grow sizing modes), placeholders,
+ * ghosts and commands belong to the binder built on top (Phase 2) — this
+ * class must stay pure enough to drive from a table-driven spec.
+ */
+/** One tile, in integer grid cells. */
+export interface GridPackItem {
+    id: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    /** Pinned: never pushed, never packed, refuses the mover outright (E4b). */
+    locked?: boolean;
+    /**
+     * Ask add() to IGNORE x/y and scan row-major for the first free hole —
+     * gridstack's autoPosition (addWidget without coordinates). Distinct from
+     * gravity, which climbs one column: a hole at (3,0) under an occupied
+     * column is only reachable by the scan. Seeding/load honours explicit
+     * cells; palette-style adds pass this flag.
+     */
+    autoPosition?: boolean;
+}
+/**
+ * How a COLUMN-COUNT change re-lays the board out — gridstack's
+ * `ColumnOptions`, recorded from its documented semantics:
+ *
+ *   'moveScale' (default) — scale both x and w by newColumns/oldColumns, so
+ *                the board keeps its proportions at any width;
+ *   'move'     — scale x only; widths survive verbatim (clamped to fit);
+ *   'scale'    — scale w only; x survives verbatim (clamped to fit);
+ *   'none'     — keep x and w exactly; clamp only what no longer fits.
+ *
+ * Whatever the mode, `columns === 1` forces a SINGLE STACK (every tile x=0,
+ * w=1) — the phone layout — and every mode re-places the result in reading
+ * order afterwards, so the outcome can never overlap.
+ */
+export type GridColumnLayout = 'moveScale' | 'move' | 'scale' | 'none';
+/** One item's cached geometry at a column count. `h` is column-independent. */
+export interface CachedCell {
+    x: number;
+    y: number;
+    w: number;
+}
+/**
+ * The PER-COLUMN LAYOUT CACHE, as plain data: column count → item id → cell.
+ * Exported/imported so a host that rebuilds its engine (the kit's `sync()`)
+ * carries the wider layouts across the rebuild instead of losing them.
+ */
+export type GridLayoutCache = Record<number, Record<string, CachedCell>>;
+export interface GridPackOptions {
+    /** Column count of the board. Default 12. */
+    columns?: number;
+    /**
+     * Float mode (gridstack `float: true`): tiles stay where placed and gaps
+     * are legal; gravity does not pack. Default false (gravity).
+     */
+    float?: boolean;
+    /**
+     * Row bound for a board whose DESIGN is a fixed strip (the nested KPI
+     * section: one row, always). Any op whose settled result would exceed it —
+     * a height resize, a width resize whose push spills a sibling down, a move
+     * displacing someone out of bounds — ROLLS BACK wholesale and reports
+     * `changed: false`; `add()` returns null when nothing can fit. Without
+     * this, growing a first-row KPI exploded the strip's `rows()` and fit-mode
+     * collapsed its row height (live report: "design is destroyed").
+     */
+    maxRows?: number;
+}
+/** Result of a move/resize attempt. */
+export interface GridPackResult {
+    /** Whether the board accepted (and applied) the change. */
+    changed: boolean;
+}
+/** Options for {@link GridPackEngine.moveCheck}. */
+export interface MoveCheckOptions {
+    /**
+     * The >50% anti-jitter coverage gate AND the swap heuristics it feeds.
+     * `gate: false` is the FIRST-PLACEMENT mode (a palette drag-in entering the
+     * board, or a dragged-out tile re-entering — gridstack's `dragInNode`
+     * behaviour): the cell is taken unconditionally — locked tiles still refuse
+     * (E4b), but any unlocked occupant is pushed down regardless of coverage,
+     * and no swap shape fires (an entering tile has no meaningful cell to
+     * exchange). Default true.
+     */
+    gate?: boolean;
+}
+export declare class GridPackEngine {
+    private _columns;
+    /** Live column count. Change it only through {@link setColumns}. */
+    get columns(): number;
+    float: boolean;
+    /** Row bound (see GridPackOptions.maxRows). Undefined = unbounded. */
+    readonly maxRows?: number;
+    private items;
+    /** Per-gesture displaced-tile memory (S2/E2). Item id → gesture-start cell. */
+    private memory;
+    /** Gesture-start snapshot of EVERY item, for cancel/Escape restore. */
+    private snapshot;
+    /**
+     * S4 — swap hysteresis. An accepted swap LOCKS the pair for the rest of the
+     * gesture: the same two tiles may swap again only on a DELIBERATE return —
+     * the mover's probe centre reaching the partner's centre. Without this, a
+     * slow sweep of a small tile across a big one ping-pongs: the row swap
+     * drops the mover at the row edge, far from the cursor, so the very next
+     * cell crossing still covers the partner and instantly swaps back (found
+     * by driving the REAL demo board with a real mouse — synthetic step sizes
+     * jumped past it). Same-size pairs land ON the probe cell, which is why
+     * the recorded E3 never showed the defect; the lock's inclusive-midpoint
+     * return keeps the S1 wiggle (swap, retreat, swap again) intact.
+     */
+    private swapLock;
+    /**
+     * THE PER-COLUMN LAYOUT CACHE (gridstack's `_layouts`). Column count → the
+     * layout the board had at that count. Written on the way OUT of a column
+     * count, read on the way BACK IN, so 12 → 1 → 12 round-trips losslessly
+     * instead of re-deriving a squashed 12 from the phone stack.
+     */
+    private layouts;
+    /**
+     * What the last column change ASSIGNED each item. It is the only way to
+     * tell a user edit made at the narrow count from a value the column change
+     * itself derived — an edit propagates into the wider cached layouts, a
+     * derived value must not (or every visit to 1 column would flatten the
+     * desktop layout to full-width tiles).
+     */
+    private assigned;
+    /** Re-entrancy guard: the column change's own writes never propagate. */
+    private inColumnChange;
+    constructor(items?: GridPackItem[], options?: GridPackOptions);
+    /** Bound check + wholesale rollback — the maxRows enforcement primitive. */
+    private cellsSnapshot;
+    private restoreCells;
+    /**
+     * Accept the op that just mutated the board — unless the settled result
+     * exceeds `maxRows`, in which case the whole op rolls back and is refused.
+     * (Trial-run-then-commit, the same shape gridstack uses for maxRow grids.)
+     */
+    private acceptWithinBound;
+    getItems(): readonly GridPackItem[];
+    getItem(id: string): GridPackItem | undefined;
+    /** Content height in rows: max(y+h) over all items (0 when empty). */
+    rows(): number;
+    /** True when any two items overlap — the invariant every op must preserve. */
+    hasOverlaps(): boolean;
+    /**
+     * Add an item. An explicit legal position is honoured verbatim. When the
+     * position collides — or the item asks for `autoPosition` — the tile
+     * AUTO-POSITIONS: a row-major scan for the first
+     * hole it fits, which is gridstack's `autoPosition` and NOT the same thing
+     * as gravity (gravity climbs one column; a hole at (3,0) under an occupied
+     * column is only reachable by the scan — the spec's first red proved it).
+     */
+    add(item: GridPackItem): GridPackItem | null;
+    remove(id: string): void;
+    /**
+     * Begin a drag/resize gesture: fresh displaced-tile memory, and a full
+     * snapshot so `cancelGesture` (Escape) can restore every tile (gridstack
+     * `saveInitial` / `restoreInitial`).
+     */
+    beginGesture(): void;
+    /** End a gesture: memory does NOT outlive it (E2, and the S4 swap lock). */
+    endGesture(): void;
+    /** Escape: restore every tile to its gesture-start cell. */
+    cancelGesture(): void;
+    /**
+     * Try to put `id` at cell (x,y). Applies the full pipeline on acceptance:
+     * swap (three shapes) | push-down (+skip below locked) → settle (teleport
+     * memory + gravity). Refuses: out-of-gesture no-ops, cells intersecting a
+     * locked tile (E4b), and collisions under the anti-jitter coverage gate.
+     * `{ gate: false }` (see {@link MoveCheckOptions}) is first-placement mode:
+     * gate and swaps are skipped, push-down still applies, E4b still refuses.
+     */
+    moveCheck(id: string, x: number, y: number, options?: MoveCheckOptions): GridPackResult;
+    /**
+     * Resize `id` to w×h cells. Growth is CLAMPED so the tile never covers a
+     * locked tile (E4b applied to size); displaced neighbours push + settle,
+     * and return when the size shrinks back (E1/S2).
+     */
+    resizeCheck(id: string, w: number, h: number): GridPackResult;
+    /**
+     * Change the board's COLUMN COUNT — gridstack's `column(n, layout)`, and the
+     * whole of responsive behaviour in one operation.
+     *
+     * Three things happen, in this order:
+     *
+     *  1. THE LAYOUT WE ARE LEAVING IS CACHED under its own column count. This
+     *     is the load-bearing step: without it, 12 → 1 → 12 would have to
+     *     re-derive twelve columns from a one-column stack and every tile would
+     *     come back full width.
+     *  2. GROWING RESTORES FROM THE CACHE, per item. Items the cache knows come
+     *     back at exactly the cells they had the last time the board was this
+     *     wide; items it does not know (added while narrow) fall through to the
+     *     scale rules below. Shrinking never restores — a narrower layout is
+     *     always derived from where the board is NOW, which is what makes a
+     *     gradual squeeze look natural.
+     *  3. THE REMAINDER IS SCALED by `layout` (see {@link GridColumnLayout}),
+     *     `columns === 1` forcing a single stack, and everything is re-placed in
+     *     reading order so the result cannot overlap.
+     *
+     * Returns true when the count actually changed.
+     */
+    setColumns(next: number, layout?: GridColumnLayout): boolean;
+    /**
+     * The layout to PERSIST — gridstack's `save()`, which serialises from the
+     * LARGEST cached column count rather than the live one. Saving while the
+     * board is narrow (a phone) therefore saves the DESKTOP layout: the cells a
+     * user authored at full width are the document, and the narrow arrangement
+     * is a projection of it.
+     *
+     * `h` is never cached because it does not depend on the column count, so it
+     * always comes from the live item; items the widest cache does not know
+     * (added while narrow) contribute their live cells, which are legal at any
+     * count at least as wide.
+     */
+    saveLayout(): {
+        columns: number;
+        items: GridPackItem[];
+    };
+    /** The column counts the cache currently holds a layout for (ascending). */
+    cachedColumns(): number[];
+    /** The cache as plain data — hand it to a rebuilt engine via {@link setLayouts}. */
+    getLayouts(): GridLayoutCache;
+    /**
+     * Adopt a cache exported by {@link getLayouts}. The kit calls this after
+     * rebuilding its engine from the model (`sync()`), which would otherwise
+     * throw the wider layouts away on every undo, add or refresh.
+     */
+    setLayouts(cache: GridLayoutCache): void;
+    /** Snapshot every item's x/y/w under `columns`. */
+    private cacheLayout;
+    /**
+     * Push an edit made at the LIVE column count into every WIDER (and narrower)
+     * cached layout, proportionally — so a widget re-arranged on a phone is
+     * still re-arranged when the desktop layout comes back.
+     *
+     *  - `y` always propagates verbatim: vertical order is column-independent,
+     *    and reordering is exactly what a user does on a narrow board.
+     *  - `x` and `w` propagate SCALED by cachedColumns/liveColumns, but only
+     *    when they differ from what the last column change assigned. That test
+     *    is what keeps a mere reorder at 1 column from rewriting every cached
+     *    width to full width (x=0,w=1 scaled by 12 would be x=0,w=12).
+     */
+    private propagateToCaches;
+    /**
+     * Re-place every item in READING ORDER after a column change: clamp it to
+     * the new width, then let `add()` resolve collisions exactly as it does for
+     * any other placement (row-major first-hole scan, then gravity).
+     *
+     * Reading order — not gridstack's reverse order — is what keeps the visible
+     * sequence intact: at 12 → 6 four 3-wide tiles on one row must become two
+     * rows of two IN ORDER, and placing bottom-right-first scrambles them.
+     */
+    private rePlace;
+    private static hit;
+    /**
+     * S4's return condition: on every axis where the pair's centres differ, the
+     * mover's PROBE centre must have reached (inclusive) the partner's centre
+     * from the mover's current side. Inclusive, so a same-size retreat onto the
+     * partner's exact cell (S1 wiggle) passes.
+     */
+    private static deliberateReturn;
+    /**
+     * Directional penetration of `probe` into the static tile `c`, given the
+     * mover's pre-step cell `from` (which encodes the direction of travel).
+     * Returns the tighter of the two axes; an axis the move does not approach
+     * from is unconstrained (Infinity) and never decides.
+     */
+    private static penetration;
+    private static overlapArea;
+    private collide;
+    private collideLocked;
+    private remember;
+    /** Sorted reading order — the deterministic iteration every rule uses. */
+    private ordered;
+    /**
+     * Displace whatever `placed` now covers: below the placed tile, then past
+     * any locked tile it lands on (gridstack `_skipDown` — without it a push
+     * cascade can bury the pinned row), recursively.
+     */
+    private pushDown;
+    /**
+     * The settle loop, run after EVERY accepted change: displaced tiles first
+     * try to TELEPORT back to their remembered gesture-start cell (works across
+     * a pinned row — S2), then gravity packs (each tile climbs while free).
+     * Loops until stable so one restore can cascade further restores; this is
+     * exactly why gridstack's E1 restore is emergent rather than special-cased.
+     */
+    private settle;
+}