# Grid Panel (layout editor)

Links: [Home](../index.md)

Place rectangular blocks on a cell grid that grows on its own, then snapshot and restore the whole layout as one JSON object.

## Overview

`gadgets/grid-panel` is a layout editor for tiled dashboards, written by SGApps.IO. The user clicks two cells (or double-clicks one) and a block covering that rectangle appears; the grid keeps a margin of spare cells around the blocks so there is always room to grow. Every block is an `ApplicationPrototype` with a DOM container where you mount your own widget, and `panel.settings()` turns the layout -- geometry plus whatever metadata you attached to each block -- into a plain object that `panel.settings(snapshot)` rebuilds.

The module is made of three objects, each built by its own file and each an `ApplicationPrototype` instance (`on`, `once`, `off`, `emit`, `bind` are available on all of them):

| Object | File | Role |
|--------|------|------|
| **panel** | `gadgets/grid-panel.js` | `GridPanelBuilder(conf)` -- owns the block list, sizes the grid, wires the click interactions, serialises the layout |
| **block** | `gadgets/grid-panel/block.js` | one rectangle: cell coordinates, span, a DOM node with a content container, the configuration object it was created from |
| **grid** | `gadgets/grid-panel/grid.js` | the W x H matrix of **cells**: creates and removes cell nodes, tracks the active / hovered cell, generates the per-instance `<style>`, auto-loads `grid/style.css` |

The DOM produced by a panel:

```html
<div class="grid_panel">                              panel.node()
    <div class="grid_app">                            panel.grid().node()
        <div><style>.grid_cell.grid_id_<id> { width: 40px; height: 40px }</style></div>   grid.styleNode()
        <div class="grid_cell grid_id_<id>" style="left: 0px; top: 0px">                 one per cell, cell.node()
            <div class="grid_cell_content animated animated-0_5s bounceIn"></div>
        </div>
        ...
    </div>
    <div class="grid_block" style="left: 40px; top: 40px; width: 120px; height: 80px">   one per block, block.node()
        <div class="grid_block_content"></div>                                            block.container()
    </div>
    ...
</div>
```

Cells and blocks are absolutely positioned, so `.grid_panel` has **no intrinsic size**: mount it in an element with an explicit height (and `overflow: auto` if the grid may outgrow it).

## Advantages

- **Two-click authoring** -- click a cell, click another: the block spans the rectangle, with a live blue preview while the mouse moves
- **Self-sizing grid** -- the grid always keeps `drawPadding` spare cells past the farthest block, the active cell and the hovered cell, clamped by `minWidth` / `maxWidth` / `minHeight` / `maxHeight`
- **One JSON for the whole layout** -- `panel.settings()` returns every block's configuration; `panel.settings(snapshot)` rebuilds it and fires `evt.block.add` per block so content can be re-mounted
- **Metadata travels with the block** -- anything you pass to `blockAdd()` besides `geometric` stays on `block.settings()` and is part of the snapshot
- **Plain DOM containers** -- `block.container()` is an ordinary `<div>`: mount a chart, a table, a component, anything
- **Event driven** -- `evt.block.add`, `evt.block.remove`, `evt.settings.update` on the panel, `geometric-update` on a block, `statusUpdate` / `evt.grid.render` on the grid, plus the framework's `before` / `on` / `after` hooks on every bound method
- **Programmable geometry** -- `block.x()`, `y()`, `width()`, `height()` setters re-render the panel; the grid follows
- **Overridable look** -- one small stylesheet with stable class names; replace the editor visuals in production

## Getting Started

```js
App.require('gadgets/grid-panel').then(function (GridPanelBuilder) {
    var panel = GridPanelBuilder();
    document.getElementById('mount').appendChild(panel.node()); // #mount needs a height

    panel.on('evt.block.add', function (block) {
        // block.container() is the <div class="grid_block_content"> inside the block
        block.container().textContent = block.width() + 'x' + block.height();
    });

    // 4 cells wide, 3 cells high, top-left corner -- click two cells for the next one
    panel.blockAdd({ geometric: { x: 0, y: 0, width: 4, height: 3 } });
});
```

`gadgets/grid-panel` must be registered with `Application.moduleRegister` first -- `lib.js` at the repository root does that for every module:

```js
App.require('/application-prototype-modules/lib.js').then(function (loader) {
    loader(); // Application.moduleRegister('/application-prototype-modules', ['gadgets/grid-panel', ...])
});
```

The grid module requires the framework's `extensions/prototype` (for the `_()` DOM chain) and `uri-load` (to inject its stylesheet), so both must be resolvable by name -- `lib()` of the framework registers them.

## API Reference

### `GridPanelBuilder(conf)` -- the panel

Returns the panel, an `ApplicationPrototype`. The `conf` argument is **accepted but ignored**: the configuration is hard-coded and only reachable through `panel.config()`.

```js
var panel = GridPanelBuilder();
panel.config().drawPadding = 1; // the only way to change a setting -- takes effect at the next render()
```

#### Default configuration (`panel.config()`)

| Key | Default | Meaning |
|-----|---------|---------|
| `minWidth` | `4` | the grid is never narrower than this many cells |
| `minHeight` | `3` | the grid is never shorter than this many cells |
| `maxWidth` | `24` | the grid is never wider than this many cells (a block past it keeps its coordinates and is drawn beyond the last cell column, over no cells) |
| `maxHeight` | `10000` | the grid is never taller than this many cells |
| `drawPadding` | `2` | spare cells kept past the farthest block / active cell / hovered cell |
| `blocks` | `[]` | the live block list (`panel.blocks()` returns a copy of it) |
| `blockId` | `0` | monotonic counter behind `block.id` |
| `node` | `<div class="grid_panel">` | the root element, `panel.node()` |

`config()` returns the live object -- edits are visible immediately, but nothing re-renders on its own; call `panel.render()` after changing the limits.

#### Panel methods

| Method | Returns | Description |
|--------|---------|-------------|
| `node()` | HTMLElement | the `<div class="grid_panel">` to mount |
| `config()` | Object | the live configuration above (no lifecycle hooks) |
| `grid()` | grid | the grid instance (see below) |
| `blocks()` | block[] | a **copy** of the block list, in creation order (no lifecycle hooks) |
| `blockAdd(blockConfiguration)` | `undefined` (`false` when a `beforeBlockAdd` handler vetoed) | creates a block from `blockConfiguration` (see the block factory: `geometric` defaults to `{x: 0, y: 0, width: 1, height: 1}`, `node` is set on the object), attaches the panel to the block (`block.GridPanel(panel)`), assigns `block.id`, subscribes to its `geometric-update`, appends `block.node()` to `panel.node()`, pushes it to the list, emits `evt.settings.update` then `evt.block.add(block)`. It does **not** return the block -- read it from the `evt.block.add` argument or `panel.blocks()[panel.blocks().length - 1]` |
| `blockRemove(block)` | `undefined` | clears the block's panel reference, filters it out of the list by `id`, detaches `block.node()` from the DOM, emits `evt.settings.update` then `evt.block.remove(block)` |
| `render()` | `undefined` | re-positions every block (`grid.updateCoords(block)`) and sets the grid width / height with the algorithm below |
| `settings()` | `{ grid, blocks }` | getter -- see [What `settings()` returns](#what-settings-returns) |
| `settings(snapshot)` | `undefined` | setter -- removes every current block with `blockRemove()`, calls `grid.settings(snapshot.grid)` when it is an object (a no-op), then `blockAdd(blockConfiguration)` for every entry of `snapshot.blocks` when it is an array |

`blocks()`, `config()` are plain methods; every other method is bound with the default lifecycle configuration, so `panel.on('beforeBlockAdd', fn)` (return `false` to veto), `'onBlockAdd'`, `'afterBlockAdd'` (next tick) and the same for `blockRemove`, `render`, `settings`, `node`, `grid` all work. The hook handlers receive the **method arguments**: `afterBlockAdd` gets the configuration object, not the block.

`render()` is called automatically: on the next tick after every `blockAdd()` / `blockRemove()` (via `afterBlockAdd` / `afterBlockRemove`), on every block `geometric-update`, on every grid `update` (width / height / cellSize change) and on every grid `statusUpdate` (click or hover). It is **not** called synchronously by `blockAdd()`: right after the call the block node is in the DOM but still has no `left` / `top` / `width` / `height` inline styles.

#### What `settings()` returns

`panel.settings()` (no argument) returns a new object:

```js
{
    grid:   {},                 // always {} -- grid.settings() is a stub
    blocks: [ block.settings(), block.settings(), ... ]   // creation order
}
```

Each entry is the **live configuration object** of that block: the very object passed to `blockAdd()`, to which the block factory added a `node` key (the block's `<div class="grid_block">` element) and a `geometric` key when it was missing. Mutating an entry mutates the block (`entry.geometric.x = 3` moves it at the next render, without any event).

`JSON.stringify(panel.settings())` therefore contains, per block, `geometric`, every serialisable key you passed to `blockAdd()` and a junk `"node": {}` (a DOM element serialises as an empty object); functions such as a `renderMethods` key are dropped:

```json
{"grid":{},"blocks":[
    {"geometric":{"x":0,"y":0,"width":4,"height":3},"renderParams":{"type":"chart"},"node":{}},
    {"geometric":{"x":4,"y":0,"width":2,"height":3},"node":{}}
]}
```

Not in the snapshot: the grid's `cellSize`, `width` and `height` (width and height are re-derived by `render()` after a restore, `cellSize` simply stays whatever the grid currently has -- `40` on a fresh panel), the block `id`s (re-assigned on restore) and the content of `block.container()`. See [Persistence Contract](#persistence-contract) for the recommended wrapper.

#### The `render()` sizing algorithm

```text
pad     = drawPadding + 1                                   // 3 by default
activeCell  = grid.activeCell()                             // { cell, time } or false
hoveredCell = grid.hoveredCell()
wActive = activeCell ? activeCell.cell.x() + pad : 0        // hovered counts only while a cell is active
hActive = activeCell ? activeCell.cell.y() + pad : 0
wHover  = activeCell && hoveredCell ? hoveredCell.cell.x() + pad : 0
hHover  = activeCell && hoveredCell ? hoveredCell.cell.y() + pad : 0

for each block: grid.updateCoords(block)                    // left/top/width/height = cellSize * geometry
                wBox = max(wBox, block.x() + block.width())
                hBox = max(hBox, block.y() + block.height())
if (wBox) wBox += drawPadding                               // 2 spare columns past the farthest block
if (hBox) hBox += drawPadding

grid.width ( min(max(minWidth,  max(wActive, wHover, wBox)), maxWidth ) )
grid.height( min(max(minHeight, max(hActive, hHover, hBox)), maxHeight) )
```

In practice: the grid keeps `drawPadding` (2) free cells to the right of and below the farthest block edge, the active cell and, while a cell is active, the hovered cell. With the defaults an empty panel is 4 x 3; one block at `{x: 0, y: 0, width: 3, height: 2}` plus one at `{x: 3, y: 1, width: 2, height: 2}` give a 7 x 5 grid.

`grid.width(n)` / `grid.height(n)` emit `update` only when the value changes; `update` runs `grid.render()` (cells are added / removed) and the panel listens to it to run `panel.render()` again (re-entrantly, from inside the first `render()`) -- the cascade stops as soon as the values are stable, so one geometry change produces one `evt.grid.render` per dimension that actually changed (two when both width and height change, none when the grid already fits), and a `cellSize` change one more.

#### Built-in interactions

| Gesture | Effect |
|---------|--------|
| click a cell | the cell becomes **active** (`.grid_cell_active`, red); `statusUpdate('activeCell', cell, oldCell)` where `oldCell` is the previously active cell or `undefined` |
| click the active cell again | deactivates it (toggle), nothing is created; `statusUpdate('activeCell', cell, cell)` with `grid.activeCell()` already `false` |
| move the mouse over cells while a cell is active | the cells inside the rectangle between the active and the hovered cell get `.grid_cell_selected` (blue preview); the grid grows to keep `drawPadding` cells past the hovered cell |
| click a second cell | `blockAdd({ geometric: { x: min, y: min, width: abs(dx) + 1, height: abs(dy) + 1 } })`, then the active cell is cleared (`grid.activeCell(false)` + `cell.active(false)` on the second cell). The `.grid_cell_selected` class stays on the second cell until the mouse moves to another cell (the selection is only repainted on the next `statusUpdate`) |
| double-click a cell | `blockAdd({ geometric: { x, y, width: 1, height: 1 } })` (the `evt.grid.cell.dblclick` handler); the active cell is cleared |
| double-click a cell while **another** cell is active | **two** blocks: the first click of the double-click completes the two-click rectangle, then the `dblclick` adds the 1 x 1 block |

There is no built-in drag-to-move, drag-to-resize, delete gesture or overlap check: blocks may overlap each other, and a block covers the cells underneath it (no `pointer-events: none`), so a rectangle cannot be started from a covered cell. Implement moving / resizing with the block setters (`x()`, `y()`, `width()`, `height()`) and deleting with `blockRemove()`.

---

### `block` -- one rectangle

Built by `gadgets/grid-panel/block.js` for every `blockAdd(blockConfiguration)` call; you get it from `evt.block.add` / `evt.block.remove` and `panel.blocks()`. The factory sanitises nothing beyond this:

```js
if (!(typeof config === 'object' && config)) config = {};
config.node = document.createElement('div');                                 // overwrites any "node" key
config.geometric = config.geometric || { x: 0, y: 0, width: 1, height: 1 }; // only when missing -- a partial geometric is NOT completed
```

`block.node()` is `<div class="grid_block"><div class="grid_block_content"></div></div>`.

| Method | Returns | Description |
|--------|---------|-------------|
| `node()` | HTMLElement | the `<div class="grid_block">`, positioned by the panel with inline `left` / `top` / `width` / `height` |
| `container()` | HTMLElement | the `<div class="grid_block_content">` -- mount your content here (`querySelector` on every call) |
| `clear()` | `undefined` | `container().innerHTML = ''` |
| `x(n)` | number | cell column; setter accepts a **number `>= 0`** (floats included), anything else is ignored; an accepted value emits `geometric-update`. Always returns the current value |
| `y(n)` | number | cell row; same rules as `x()` |
| `width(n)` | number | span in cells; setter accepts a **number `> 1`** only -- `width(1)` is silently ignored, the getter keeps returning the old span. Emits `geometric-update` when accepted |
| `height(n)` | number | same rules as `width()` |
| `settings()` | Object | the **live** configuration object: `geometric`, your own keys, `node` |
| `GridPanel(panel)` | panel or `null` | the owning panel. An object argument sets it, a falsy non-`undefined` argument (`null`, `false`, `0`, `''`) clears it, no argument (or any truthy non-object such as a string) just reads it. The panel calls `GridPanel(app)` in `blockAdd()` and `GridPanel(null)` in `blockRemove()` |
| `detachFromGrid()` | boolean | `panel.blockRemove(block)` on the owning panel; `true` when there was one, `false` otherwise |

`block.id` is a **plain property** (not a method) set by `blockAdd()` from the panel's `blockId` counter: `1, 2, 3, ...` per panel, never reused, re-assigned after a restore.

All block methods are bound with the default lifecycle configuration: `block.on('afterWidth', fn)`, `block.on('beforeClear', fn)`, ... work, and every getter call (`x()`, `width()`, ...) emits its `before` / `on` hooks synchronously and its `after` hook on the next tick -- cheap while nobody listens, but not free.

---

### `grid` -- the cell matrix

Built by `gadgets/grid-panel/grid.js`; `panel.grid()` returns it. On module load (once, not per instance) it injects `gadgets/grid-panel/grid/style.css` into `<head>` through `uri-load`.

| Method | Returns | Description |
|--------|---------|-------------|
| `node()` | HTMLElement | the `<div class="grid_app">` (child of the panel node) |
| `styleNode()` | HTMLElement | the `<div>` holding the generated `<style>` (first child of `node()`) |
| `config()` | Object | live configuration: `{ id, node, styleNode, width, height, cellSize, idIndex, cells, status: { hoveredCell, activeCell } }` |
| `id()` | string | per-instance id, `<base36 time>_<base36 random>`; used in the `grid_id_<id>` cell class |
| `width(n)` | number | grid width in cells (default `1`: the grid renders itself once as 1 x 1 when built, then the panel constructor's `render()` raises it to `minWidth`). A number different from the current value is stored and `update` is emitted; not validated (`0` removes every cell). The panel's `render()` overwrites it, so set it only when you drive the grid without a panel |
| `height(n)` | number | grid height in cells; same behaviour |
| `cellSize(n)` | number | pixels per cell, default `40`; a different number is stored and `update` is emitted (cells resize through the generated `<style>`, blocks through `panel.render()`) |
| `activeCell(false)` | `{ cell, time }` or `false` | the cell activated by a click and when; only `false` is accepted as an argument (reset) -- there is no programmatic way to activate a cell |
| `hoveredCell(false)` | `{ cell, time }` or `false` | the cell last hovered; only `false` resets it. Never reset by the grid itself (there is no `mouseleave` handling) |
| `cells(fn)` | Object | the live map `{ "<x>x<y>": cell }`; with a function, calls `fn(cell)` for every cell first |
| `cellAdd(x, y)` | cell | creates the cell object and node, positions it, stores it in the map, appends it to `node()`, emits `evt.grid.cell.add(cell)`. No duplicate check -- `render()` is the only caller that guards |
| `cellRemove(cell)` | `undefined` | deletes the cell from the map, calls `cell.remove()` (bounce-out, node detached after 1000 ms), emits `evt.grid.cell.remove(cell)` |
| `updateCoords(item)` | `undefined` | sets `left` / `top` / `width` / `height` inline styles on `item.node()` from `cellSize * item.x()` etc. -- works for blocks (the panel uses it) and for anything with `node()`, `x()`, `y()`, `width()`, `height()` |
| `renderStyle()` | `undefined` | rewrites the generated `<style>`: `.grid_cell.grid_id_<id> { width: <cellSize>px; height: <cellSize>px; }` |
| `render()` | `undefined` | `renderStyle()`; removes (`cellRemove`) every cell with `x >= width` or `y >= height` and re-positions the others; adds (`cellAdd`) every missing `(x, y)`; emits `evt.grid.render` |
| `randomId()` | number | increments and returns `idIndex` (`1, 2, ...`); unused by the module |
| `settings()` | `{}` | **stub**: always returns an empty object and ignores its argument |

`config()`, `settings()`, `activeCell()`, `hoveredCell()`, `id()`, `randomId()`, `node()`, `styleNode()`, `cells()` are plain methods; `width`, `height`, `cellSize`, `renderStyle`, `cellAdd`, `cellRemove`, `updateCoords`, `render` carry the `before` / `on` / `after` hooks.

#### `cell` -- one square of the grid

Created by `grid.cellAdd(x, y)`; passed to the grid events and found in `grid.cells()`.

| Method | Returns | Description |
|--------|---------|-------------|
| `x()`, `y()` | number | fixed coordinates |
| `width()`, `height()` | `1` | constant |
| `id()` | string | `"<x>x<y>"`, e.g. `"3x2"` -- also the key in `grid.cells()` |
| `node()` | HTMLElement | `<div class="grid_cell grid_id_<gridId>">` with the `.grid_cell_content` child |
| `active(bool)` | `undefined` | adds / removes `.grid_cell_active`. **Calling it without a boolean throws** (`p.E(...).hasClass is not a function`: `hasClass` does not exist in `extensions/prototype`) -- test `cell.node().className` instead |
| `selected(bool)` | `undefined` | adds / removes `.grid_cell_selected`; same getter bug |
| `remove()` | `undefined` | swaps `bounceIn` for `bounceOut` on the content and detaches the node after 1000 ms. Does **not** touch `grid.cells()` -- use `grid.cellRemove(cell)` |
| `class()` | `undefined` | empty placeholder, does nothing |

`active`, `selected` and `remove` are bound with the default lifecycle configuration (`cell.on('beforeActive', fn)` receives the boolean, `afterRemove` fires on the next tick); `x`, `y`, `width`, `height`, `id`, `node` and `class` are plain methods.

The cell node gets its DOM handlers as **properties** (`onclick`, `ondblclick`, `onmousemove`) -- add your own with `addEventListener`, do not assign those properties.

## Events

Events are subscribed with `on(name, handler[, handlerId])` (returns the handler id; several names may be given comma-separated), `once(...)`, removed with `off(name[, handlerId])`. Handler exceptions are caught and logged by the framework (`Error detected:`), they do not break the emitter. A `before<Name>` hook vetoes only from an `on()` handler: `once()` wraps the handler and discards its return value, so `return false` from a `once('beforeBlockAdd', ...)` handler does not stop the call.

### Panel events

| Event | Arguments | Description |
|-------|-----------|-------------|
| `evt.block.add` | `block` | a block was created: it is already in `panel.blocks()` and its node is in the DOM (not yet positioned). Also fired for every block of a `settings(snapshot)` restore -- the place to (re)mount content |
| `evt.block.remove` | `block` | a block was removed from the list and from the DOM (`block.settings()` is still readable) |
| `evt.settings.update` | -- | the layout changed. Fired **twice** per `blockAdd()` / `blockRemove()`: synchronously inside the method and again on the next tick (from `afterBlockAdd` / `afterBlockRemove`). **Not** fired by the `x()` / `y()` / `width()` / `height()` setters (the module listens to `afterBlockResize` / `afterBlockMove`, but no `blockResize` / `blockMove` method exists, so those never fire) |
| `beforeBlockAdd`, `onBlockAdd`, `afterBlockAdd` | `blockConfiguration` | lifecycle hooks of `blockAdd()`; `before` may veto by returning `false` |
| `beforeBlockRemove`, `onBlockRemove`, `afterBlockRemove` | `block` | lifecycle hooks of `blockRemove()` |
| `beforeRender`, `onRender`, `afterRender` | -- | lifecycle hooks of `render()` (fires a lot: after every add / remove / move / hover) |
| `beforeSettings`, `onSettings`, `afterSettings` | `snapshot` or nothing | lifecycle hooks of `settings()`, getter calls included |

### Block events

| Event | Arguments | Description |
|-------|-----------|-------------|
| `geometric-update` | -- | an `x()` / `y()` / `width()` / `height()` setter accepted a value; the panel calls `render()` on it synchronously, so the node is already re-positioned when the setter returns |
| `beforeX` ... `afterHeight`, `beforeSettings`, `afterClear`, ... | method arguments | lifecycle hooks of every block method, including the getters |

### Grid events

| Event | Arguments | Description |
|-------|-----------|-------------|
| `update` | -- | `width`, `height` or `cellSize` changed; the grid re-renders itself and the panel re-renders the blocks |
| `statusUpdate` | `actionName, currentCell, oldCell` | `actionName` is `"activeCell"` (a cell was clicked; `oldCell` = the previously active cell or `undefined`) or `"hoveredCell"` (the mouse entered another cell; `oldCell` = the previously hovered cell or `undefined`). The panel updates the blue selection and creates the two-click block on it |
| `evt.grid.cell.add` | `cell` | a cell was created (bursts of them on every grid growth) |
| `evt.grid.cell.remove` | `cell` | a cell was dropped from the map; its node stays in the DOM for another second |
| `evt.grid.cell.dblclick` | `cell` | a cell was double-clicked (the panel adds the 1 x 1 block on it) |
| `evt.grid.render` | -- | a `render()` sweep finished (add + remove + reposition) |
| `beforeWidth` ... `afterRender`, `afterCellAdd`, ... | method arguments | lifecycle hooks of `width`, `height`, `cellSize`, `renderStyle`, `cellAdd`, `cellRemove`, `updateCoords`, `render` |

## Persistence Contract

### What is and is not in the snapshot

| Data | In `panel.settings()` | Notes |
|------|-----------------------|-------|
| block `geometric` | yes | `{ x, y, width, height }` |
| custom keys passed to `blockAdd()` | yes (JSON-serialisable ones) | functions are dropped by `JSON.stringify`, DOM nodes become `{}` |
| `node` | as `{}` junk | overwritten with a fresh element on restore -- harmless, but strip it if the snapshot is stored |
| `grid` | `{}` | stub |
| `cellSize` | **no** | stays whatever the grid has at restore time; persist it yourself |
| grid `width` / `height` | no | re-derived by `render()` from the restored blocks |
| `block.id` | no | re-assigned by the counter; add your own `uid` key if identity matters |
| `block.container()` content | no | every restored block is empty; re-mount from `evt.block.add` |

Restoring passes each snapshot entry **as is** to the block factory, which then owns and mutates that object (`node`, `geometric`) -- deep clone the snapshot before passing it if you keep it around.

### Recommended block metadata: `renderParams` + `renderMethods`

Split each block configuration in three keys with distinct persistence rules:

| Key | Persisted | Purpose |
|-----|-----------|---------|
| `geometric` | yes | required cell coordinates and span |
| `renderParams` | yes | pure data describing **how** to render the block (widget type, data source, chart options): everything needed to rebuild it after a restore |
| `renderMethods` | no (a function, dropped by `JSON.stringify`) | a single function returning a bundle of runtime accessors and lifecycle methods -- the only entry point to anything runtime-related |

```js
var chartInstance = null;
var subscription = null;

var blockConfiguration = {
    geometric:    { x: 0, y: 0, width: 4, height: 3 },
    renderParams: { type: 'chart', dataUrl: '/api/sales', chartOptions: { series: 'line' } }
};

blockConfiguration.renderMethods = function () {
    return {
        // live getters -- always reflect the current closure state
        get chart()        { return chartInstance; },
        get subscription() { return subscription; },
        setChart:  function (chart) { chartInstance = chart; },
        subscribe: function (topic) {
            subscription = eventBus.on(topic, function () {
                if (chartInstance) chartInstance.refresh();
            });
        },
        destroy: function () {
            if (subscription) subscription.off();
            if (chartInstance) chartInstance.dispose();
            chartInstance = subscription = null;
        }
    };
};

panel.blockAdd(blockConfiguration);
```

Inside the returned bundle expose runtime references only through getters or methods, never as raw property values: a raw `{ chart: chartInstance }` freezes the reference at call time and serialises oddly if somebody `JSON.stringify`s the bundle by accident.

### Hydration on restore

Functions do not survive serialisation, so on restore the consumer re-attaches `renderMethods` from `renderParams.type` -- in the same `evt.block.add` handler that mounts the widget, which makes freshly added and restored blocks identical:

```js
var renderers = {
    chart: function (block) {
        var configuration = block.settings();
        var chartInstance = null;

        configuration.renderMethods = function () {
            return {
                get chart() { return chartInstance; },
                destroy: function () {
                    if (chartInstance) chartInstance.dispose();
                    chartInstance = null;
                }
            };
        };

        chartInstance = createChart(block.container(), configuration.renderParams); // your widget
    }
};

panel.on('evt.block.add', function (block) {
    var params = block.settings().renderParams;
    if (params && renderers[params.type]) renderers[params.type](block);
});

panel.on('evt.block.remove', function (block) {
    var methods = block.settings().renderMethods;
    if (typeof methods === 'function') methods().destroy();
});
```

### Export / import wrapper

Because the native `settings()` returns live references, keeps a junk `node` key, does not persist `cellSize` and has no schema version, wrap it:

```js
var CURRENT_SCHEMA_VERSION = 1;

function exportSchema(panel) {
    var raw = panel.settings();
    return {
        version:  CURRENT_SCHEMA_VERSION,
        cellSize: panel.grid().cellSize(),
        // deep clone: detaches from the live objects, drops functions; then strip the DOM element placeholder
        blocks:   JSON.parse(JSON.stringify(raw.blocks)).map(function (blockConfiguration) {
            delete blockConfiguration.node;
            return blockConfiguration;
        })
    };
}

function importSchema(panel, schema) {
    // migrate older schema versions here
    if (typeof schema.cellSize === 'number') panel.grid().cellSize(schema.cellSize);
    // clone again: the block factory keeps and mutates the objects it receives
    panel.settings({ grid: {}, blocks: JSON.parse(JSON.stringify(schema.blocks)) });
    // evt.block.add fired once per block -- the hydration handler re-mounted the content
}

localStorage.setItem('layout', JSON.stringify(exportSchema(panel)));
// ... later
importSchema(panel, JSON.parse(localStorage.getItem('layout')));
```

## CSS Surface

`gadgets/grid-panel/grid/style.css` is injected into `<head>` by the grid module as soon as it loads (asynchronously: for a few milliseconds the cells render as plain block `<div>`s stacked vertically). Rules and hooks:

| Selector | Defined where | Purpose |
|----------|---------------|---------|
| `.grid_panel` | style.css | panel root: `position: relative; z-index: 1` -- **no width / height** |
| `.grid_app` | (no rule) | grid root; children are absolutely positioned |
| `.grid_cell`, `.grid_block` | style.css | `display: block; position: absolute`, fallback `10px x 10px` |
| `.grid_cell.grid_id_<id>` | generated `<style>` per grid | `width` / `height` = `cellSize` px (wins over the fallback by specificity) |
| `.grid_cell_content` | style.css | 100% box; its `::before` draws the rounded 90% inset outline (`3px` border, 15% black) |
| `.grid_cell:hover .grid_cell_content::before` | style.css | red outline (50%) |
| `.grid_cell.grid_cell_active .grid_cell_content::before` | style.css | red outline + red tint (15%) -- the clicked cell |
| `.grid_cell.grid_cell_selected .grid_cell_content::before` | style.css | blue outline (50%) + blue tint (15%); stronger on `:hover` -- the two-click preview |
| `.grid_block` | style.css | green translucent background (`rgba(19, 200, 135, .55)`), `3px` dark border, `5px` radius, `box-sizing: border-box` |
| `.grid_block_content` | style.css | absolutely centred (`top/left: 50%` + `translate(-50%, -50%)`), `width: 100%`, `min-height: 50%`, `max-height: 100%`, `overflow: auto`, `11px` bold monospace, white text at 69% |
| `.animated`, `.animated-0_5s`, `.bounceIn`, `.bounceOut` | **not shipped** | animate.css class names set on `.grid_cell_content`; load animate.css (or define them) to see the cell bounce -- without it cells appear / disappear instantly, the 1 s removal delay stays |

**Production override tip** -- the defaults (green blocks, monospace white label, red / blue overlays) are editor visuals. For a widget host, load your own stylesheet after the module's and override:

```css
/* blocks become plain widget frames */
.grid_block { background: #fff; border: 1px solid #ddd; border-radius: 4px; }
.grid_block_content { transform: none; top: 0; left: 0; min-height: 100%; font: inherit; color: inherit; }
/* read-only mode: hide the cells and stop the click / hover interactions */
.dashboard--readonly .grid_app { display: none; }
```

Keep the `.grid_cell_content::before` rules when the editing affordance must stay; hiding `.grid_app` (or setting `pointer-events: none` on it) is the only way to disable the built-in gestures, there is no API switch.

## Code Examples

### Example 1: Layout editor with labels and a delete button per block

```js
App.require('gadgets/grid-panel').then(function (GridPanelBuilder) {
    var panel = GridPanelBuilder();
    var mount = document.getElementById('mount'); // e.g. style="height: 480px; overflow: auto"
    mount.appendChild(panel.node());

    panel.on('evt.block.add', function (block) {
        var label = document.createElement('span');
        var remove = document.createElement('button');
        remove.textContent = 'x';
        remove.onclick = function () { block.detachFromGrid(); };
        block.container().appendChild(label);
        block.container().appendChild(remove);

        var update = function () {
            label.textContent = '#' + block.id + ' ' + block.width() + 'x' + block.height();
        };
        block.on('geometric-update', update);
        update();
    });

    panel.on('evt.block.remove', function (block) {
        console.log('removed #' + block.id);
    });

    // click two cells or double-click one to add blocks; move the last one one column right:
    panel.blockAdd({ geometric: { x: 1, y: 1, width: 3, height: 2 } });
    var last = panel.blocks()[panel.blocks().length - 1];
    last.x(last.x() + 1);
});
```

### Example 2: Widget host with hydration

```js
App.require('gadgets/grid-panel').then(function (GridPanelBuilder) {
    var panel = GridPanelBuilder();
    document.getElementById('mount').appendChild(panel.node());
    panel.grid().cellSize(60);

    var renderers = {
        clock: function (block) {
            var configuration = block.settings();
            var timer = setInterval(function () {
                block.container().textContent = new Date().toLocaleTimeString();
            }, 1000);
            configuration.renderMethods = function () {
                return {
                    destroy: function () { clearInterval(timer); }
                };
            };
        }
    };

    panel.on('evt.block.add', function (block) {
        var params = block.settings().renderParams;
        // the block is positioned on the next tick only -- size the content box from the geometry instead
        block.container().style.height = (block.height() * panel.grid().cellSize()) + 'px';
        if (params && renderers[params.type]) renderers[params.type](block);
    });

    panel.on('evt.block.remove', function (block) {
        var methods = block.settings().renderMethods;
        if (typeof methods === 'function') methods().destroy();
    });

    panel.blockAdd({
        geometric:    { x: 0, y: 0, width: 4, height: 2 },
        renderParams: { type: 'clock' }
    });
});
```

### Example 3: Save on every change, restore on load

```js
App.require('gadgets/grid-panel').then(function (GridPanelBuilder) {
    var panel = GridPanelBuilder();
    var timer = null;
    document.getElementById('mount').appendChild(panel.node());

    var save = function () {
        clearTimeout(timer); // evt.settings.update fires twice per add / remove -- debounce it
        timer = setTimeout(function () {
            localStorage.setItem('layout', JSON.stringify(exportSchema(panel))); // see Persistence Contract
        }, 100);
    };
    panel.on('evt.settings.update', save);

    // the geometry setters do not fire evt.settings.update: hook the blocks too
    panel.on('evt.block.add', function (block) {
        block.on('geometric-update', save);
    });

    var stored = localStorage.getItem('layout');
    if (stored) importSchema(panel, JSON.parse(stored));
});
```

### Example 4: Stable block identity across restores

```js
// block.id changes on every restore -- carry your own uid in the configuration
var uid = 0;
panel.on('beforeBlockAdd', function (blockConfiguration) {
    if (blockConfiguration && !blockConfiguration.uid) {
        blockConfiguration.uid = 'b' + (++uid) + '-' + Date.now().toString(36);
    }
    // return false here to reject a block (blockAdd() then returns false)
});

panel.on('evt.block.add', function (block) {
    console.log('block', block.settings().uid, 'is #' + block.id + ' in this session');
});
```

## Caveats

| Caveat | Impact |
|--------|--------|
| `GridPanelBuilder(conf)` ignores `conf` | `minWidth`, `maxWidth`, `drawPadding`, ... can only be changed through `panel.config()` followed by `panel.render()` |
| `.grid_panel` has no intrinsic size | mount it in an element with an explicit height (and `overflow: auto`), otherwise the layout collapses to 0 px and overflows its parent |
| the stylesheet arrives asynchronously | for a moment after the module loads the cells are plain block `<div>`s stacked vertically; the animate.css classes (`bounceIn` / `bounceOut`) are not shipped at all |
| `blockAdd()` returns `undefined` | get the block from the `evt.block.add` argument or from `panel.blocks()` |
| `render()` runs on the next tick after `blockAdd()` | right after the call (and inside `evt.block.add`) the block node has no `left` / `top` / `width` / `height`; measure it in `afterBlockAdd` (the module's own `afterBlockAdd` handler is registered first, so yours runs after the render), `afterRender` or a `setTimeout` |
| `evt.settings.update` fires twice per add / remove | debounce persistence handlers |
| `x()` / `y()` / `width()` / `height()` setters do not fire `evt.settings.update` | listen to the block's `geometric-update` as well (the `afterBlockResize` / `afterBlockMove` listeners in the source are dead: nothing binds `blockResize` / `blockMove`) |
| `width(1)` / `height(1)` are rejected (`n > 1`) | a block can never shrink back to one cell -- remove it and add it again with `geometric: { width: 1, height: 1 }` |
| the geometry setters accept floats, and no setter rounds | `x(2.5)` positions the block between cells; validate before calling |
| a partial `geometric` is not completed | `{ geometric: { x: 2 } }` gives `width() === undefined`, a block with only `left` set and a grid that ignores it (`NaN` comparisons); always pass all four keys |
| `block.settings()` is the live configuration object | mutating it mutates the block; the snapshot entries are the same objects -- deep clone before storing |
| `JSON.stringify(panel.settings())` contains `"node": {}` per block and drops functions | strip `node` in your export, re-attach `renderMethods` on `evt.block.add` |
| `grid.settings()` is a stub (`{}`, argument ignored) | `cellSize` is not persisted or restored -- store it next to the blocks |
| restore passes your snapshot objects to the block factory | they get a `node` key and become live -- pass a clone |
| `block.id` is volatile | `1, 2, 3, ...` per panel instance, re-assigned after every `settings(snapshot)`; use your own `uid` key for identity |
| `cell.active()` / `cell.selected()` **getters throw** | `hasClass` does not exist in `extensions/prototype`; only the boolean setters work -- read `cell.node().className` |
| `grid.hoveredCell()` is never reset by the grid | there is no `mouseleave` handling; while a cell is active the grid keeps room for the last hovered cell even after the pointer left. Call `grid.hoveredCell(false)` yourself |
| `grid.activeCell()` / `hoveredCell()` accept only `false` | there is no programmatic way to activate a cell or start a selection |
| no overlap check, blocks cover cells | blocks may overlap; the cells under a block are not clickable, so a selection cannot start there |
| double-click while another cell is active creates two blocks | the first click closes the pending rectangle, then the `dblclick` adds a 1 x 1 block |
| the blue preview is repainted only on `statusUpdate` | after the second click the last hovered cell keeps `.grid_cell_selected` until the mouse moves to another cell |
| `once('before...')` cannot veto | the framework's `once()` wrapper discards the handler's return value; use `on()` and `off()` for a one-shot veto |
| cell removal is delayed by 1000 ms | `evt.grid.cell.remove` is synchronous but the node stays in the DOM for a second; shrinking a grid repeatedly stacks detached-but-visible cells |
| grid growth re-renders in cascades | one geometry change runs `grid.render()` once per dimension that changed (twice when both width and height change, plus one for a `cellSize` change) and fires bursts of `evt.grid.cell.add` / `remove`; keep those handlers cheap |
| every getter has lifecycle hooks | `block.x()` emits `beforeX` / `onX` synchronously and `afterX` on a timer; `render()` makes about a dozen hooked getter calls per block (`node()`, `x()`, `y()`, `width()`, `height()` in `updateCoords()` and again in the bounding-box loop) -- fine for dozens of blocks, noticeable for thousands |
| cell DOM handlers are properties | the grid assigns `onclick`, `ondblclick`, `onmousemove` on each cell node; use `addEventListener` for your own |
| `grid.cellAdd()` does not check duplicates | calling it for an existing `(x, y)` appends a second node and orphans the first entry; let `render()` manage cells |
| the module depends on the `_()` global | `extensions/prototype` must be loaded (the grid module requires it) -- the framework's `lib()` registers it |

## Live Demo

Click a cell then another (or double-click) to add blocks, remove one with its **x** button, change the `cellSize`, follow `evt.block.add` / `remove` in the log, and Snapshot / Restore the layout through the export / import wrapper: [playground](playground.html#module=grid-panel ':ignore :target=_blank').

## Related Modules

- [Wrapper](wrapper.md) -- isolate a block's widget in its own iframe
- [Crop Sections](../elements/crop-sections.md) -- side-by-side panels when a column layout is enough
- `extensions/prototype` (framework) -- the `_()` DOM chain the grid uses; `uri-load` (framework) -- loads `grid/style.css`