@grafloria/element 0.3.20 → 0.3.22

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

@@ -1,323 +0,0 @@
-/**
- * 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;
-}