# Ext — Components

Import these from `@grafloria/renderer`.

## Functions

### `attachCanvasPlugins`

```ts
function attachCanvasPlugins(
  instance: CanvasPluginHost,
  options: CanvasPluginOptions = {}
): CanvasPlugins
```

### `createBackground`

Create the background grid inside `root`, tracking `viewport`.

```ts
function createBackground(
  root: HTMLElement,
  viewport: ViewportController,
  options: BackgroundOptions = {}
): BackgroundHandle
```

### `createControls`

```ts
function createControls(
  root: HTMLElement,
  viewport: ViewportController,
  options: ControlsOptions = {}
): ControlsHandle
```

### `createMiniMap`

```ts
function createMiniMap(
  root: HTMLElement,
  viewport: ViewportController,
  getModel: () => DiagramModel,
  options: MiniMapOptions = {}
): MiniMapHandle
```

## Constants

### `BACKGROUND_LAYER_CLASS`

```ts
const BACKGROUND_LAYER_CLASS: "grafloria-background-layer"
```

## Interfaces

### `BackgroundHandle`

```ts
interface BackgroundHandle
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `element` | `SVGSVGElement` |  |  |

**Members**

- `update(options: Partial<BackgroundOptions>): void` — Change any option; re-renders immediately.
- `setVisible(visible: boolean): void` — Show/hide without tearing down (this is what `gridEnabled` drives).
- `isVisible(): boolean`
- `dispose(): void`

### `BackgroundOptions`

```ts
interface BackgroundOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `variant?` | `BackgroundVariant` |  | Pattern style. Default `'dots'`. |
| `gap?` | `number` |  | Grid spacing in WORLD units. Default 20. |
| `size?` | `number` |  | Dot radius / line thickness in CSS px. Default 1 (dots) or 1 (lines). |
| `color?` | `string` |  | Pattern colour. Default a theme-neutral grey. |
| `backgroundColor?` | `string` |  | Page colour painted under the pattern. Default transparent. |
| `majorEvery?` | `number` |  | Draw a heavier line every N cells (graph-paper look). 0 = off (default). Only meaningful for `'lines'` / `'cross'`. |
| `majorColor?` | `string` |  | Colour of the major lines. Defaults to `color` at higher opacity. |
| `minZoom?` | `number` |  | Hide the grid below this zoom, so it does not turn into visual mud when you zoom way out. Default 0.25. Set 0 to always draw. |
| `idSuffix?` | `string` |  | Unique-ish suffix for the pattern id, when several diagrams share a page. |

### `CanvasPluginHost`

The structural surface the plugins actually need. `DiagramInstance`
satisfies it; so does any framework canvas that keeps a live
`ViewportController` (the Angular wrapper builds exactly this adapter).

```ts
interface CanvasPluginHost
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement` |  |  |
| `viewport` | `DiagramInstance['viewport']` |  |  |

**Members**

- `getModel(): DiagramModel`
- `getEngine(): DiagramEngine`
- `fitView(padding?: number): void`

### `CanvasPluginOptions`

```ts
interface CanvasPluginOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `background?` | `boolean \| BackgroundOptions` |  | Background grid. `true` = defaults; an object = options; omitted/false = off. When the engine's `gridEnabled` flag is present it OVERRIDES visibility. |
| `minimap?` | `boolean \| MiniMapOptions` |  | MiniMap. Visibility is additionally gated by the store's `showMinimap`. |
| `controls?` | `boolean \| ControlsOptions` |  | Zoom/fit/lock toolbar. |
| `bindToStore?` | `boolean` |  | Honour `DiagramStore.gridEnabled` / `showMinimap` and keep them in sync. Default true — this is what makes the flags real. Turn it off if you want the component visibility to be purely declarative. |

### `CanvasPlugins`

```ts
interface CanvasPlugins
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `background?` | `BackgroundHandle` |  |  |
| `minimap?` | `MiniMapHandle` |  |  |
| `controls?` | `ControlsHandle` |  |  |
| `dispose` | `Disposer` |  |  |

### `ControlsHandle`

```ts
interface ControlsHandle
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `portal` | `Portal` |  |  |
| `element` | `HTMLElement` |  |  |

**Members**

- `setVisible(visible: boolean): void`
- `isVisible(): boolean`
- `setLocked(locked: boolean): void` — Reflect a lock state changed elsewhere (keeps `aria-pressed` honest).
- `dispose(): void`

### `ControlsOptions`

```ts
interface ControlsOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `placement?` | `PortalPlacement` |  |  |
| `offset?` | `number` |  |  |
| `showZoom?` | `boolean` |  | Which buttons to show. Default: all except lock. |
| `showFitView?` | `boolean` |  |  |
| `showLock?` | `boolean` |  |  |
| `orientation?` | `'vertical' \| 'horizontal'` |  | Lay the buttons out horizontally instead of vertically. |
| `zoomStep?` | `number` |  | Zoom step per click (multiplicative). Default 1.2. |
| `onFitView?` | `() => void` |  | Called when "fit view" is pressed. Wire this to `instance.fitView()`. |
| `onToggleLock?` | `(locked: boolean) => void` |  | Called when the lock is toggled. Return/ignore as you like. |
| `locked?` | `boolean` |  | Initial lock state. |

### `MiniMapHandle`

```ts
interface MiniMapHandle
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `portal` | `Portal` |  |  |
| `element` | `SVGSVGElement` |  |  |

**Members**

- `refresh(): void` — Rebuild the node layer (call when the model changed).
- `setVisible(visible: boolean): void`
- `isVisible(): boolean`
- `update(options: Partial<MiniMapOptions>): void`
- `dispose(): void`

### `MiniMapOptions`

```ts
interface MiniMapOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `placement?` | `PortalPlacement` |  |  |
| `offset?` | `number` |  |  |
| `width?` | `number` |  |  |
| `height?` | `number` |  |  |
| `padding?` | `number` |  | Padding (world units) around the content in the minimap's viewBox. |
| `nodeColor?` | `string \| ((node: NodeModel) => string)` |  | Node fill. A function lets you colour-code by type/state. |
| `maskColor?` | `string` |  | Fill of the camera rectangle. |
| `maskStroke?` | `string` |  | Stroke of the camera rectangle. |
| `panelBackground?` | `string` |  |  |
| `panelBorder?` | `string` |  |  |
| `interactive?` | `boolean` |  | Allow click/drag-to-pan and wheel-to-zoom. Default true. |
| `showLinks?` | `boolean` |  | Draw links too. Default false (nodes carry the shape of a diagram). |
| `linkColor?` | `string` |  |  |
| `ariaLabel?` | `string` |  | ARIA label on the panel. |

## Types

### `BackgroundVariant`

Also has every member of `String`, listed on its own entry.

```ts
type BackgroundVariant = 'dots' | 'lines' | 'cross' | 'none';
```