# WidgetHandle

Import it from `@grafloria/element`.

One widget's OO surface (mirrors ErTable/UmlClass).

```ts
interface WidgetHandle
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `viewId` | `string` |  |  |
| `node` | `NodeModel \| undefined` |  |  |
| `spec` | `DashboardWidgetSpec` |  | The DECLARED spec — read it back (title/kind/data) without a side map. |
| `cell` | `{ x: number; y: number; w: number; h: number } \| undefined` |  | Current cell, as data. |
| `rect` | `{ x: number; y: number; width: number; height: number } \| undefined` |  | The world rect the current cell projects to. |
| `pinned` | `boolean` |  |  |

**Members**

- `resize(span: number, rows: number): Promise<boolean>` — Resize in CELLS. Resolves TRUE when the board accepted it.
- `moveTo(x: number, y: number): Promise<boolean>` — Move to a cell. Resolves TRUE when the board accepted it.
- `pin(on?: boolean): void` — Pin / unpin (a pinned widget refuses the mover and never gets pushed).
- `bringToFront(): void` — Raise / lower — one undoable step each (mirrors the toolbar commands).
- `sendToBack(): void`
- `remove(displaced?: unknown[]): void` — Remove it — ONE undoable step including the survivors' re-pack. `displaced` accepts the commands a drag-out gesture already computed;
omit it and the handle plans them itself.
- `update(patch: Partial<Pick<DashboardWidgetSpec, 'data' | 'title' | 'kind'>>): void` — Replace the widget's `data` (and optionally title) and repaint.
- `repaint(): void` — Repaint through `renderWidget` (after your data changed).