# @grafloria/vue

Vue 3 bindings for Grafloria Diagrams and Grafloria Dashboards — an MIT diagram and dashboard engine: routing, auto-layout, undo, collaboration and dashboard layouts, native in Vue.

## Install

```bash
npm install @grafloria/vue @grafloria/engine @grafloria/renderer vue @grafloria/element
```

It expects these alongside it:

- `@grafloria/engine` ^0.3.0
- `@grafloria/renderer` ^0.4.16
- `vue` ^3.4.0
- `@grafloria/element` ^0.4.3

## Functions

### `useGrafloria`

The live `DiagramInstance` ref, `null` until a `<GrafloriaFlow>` mounts.

```ts
function useGrafloria(): ShallowRef<DiagramInstance | null>
```

### `useOnSelectionChange`

Fire a callback on every selection change; teardown is automatic.

```ts
function useOnSelectionChange(handler: (change: SelectionChange) => void): void
```

### `useSelection`

The current selection as reactive state (for an inspector panel).

```ts
function useSelection(): Ref<SelectionChange>
```

### `useViewport`

The live camera (zoom + world rect) as reactive state.

```ts
function useViewport(): Ref<{ zoom: number; x: number; y: number }>
```

## Constants

### `GRAFLORIA_STORE`

```ts
const GRAFLORIA_STORE: InjectionKey<ShallowRef<DiagramInstance | null>>
```

### `GrafloriaCommentPanel`

```ts
const GrafloriaCommentPanel: any
```

**Props**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `store` | `CommentStore` |  |  |
| `options?` | `CommentPanelOptions>, default: () =` |  |  |

**Events**

- `select`

### `GrafloriaDashboard`

```ts
const GrafloriaDashboard: any
```

**Props**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `views?` | `DashboardViewSpec[]` |  |  |
| `widgets?` | `DashboardWidgetSpec[]` |  |  |
| `options?` | `Partial<DashboardOptions>>, default: () =` |  |  |
| `activeView?` | `String` |  | The visible view — `v-model:active-view`. |
| `layout?` | `'grid' \| 'split'` |  | LIVE SWITCHES — the toolbar toggles as props: applied at mount (over |
| `sizing?` | `'fit' \| 'grow'` |  |  |
| `static?` | `Boolean` |  | Static board: the viewer's mode — no drag, no resize, no handles. |

**Events**

- `update:activeView`
- `ready`
- `layoutChange`

### `GrafloriaDiagram`

```ts
const GrafloriaDiagram: any
```

**Props**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `spec` | `RenderSpec` |  | Any kit spec — erDiagram(...), umlDiagram(...), dashboard(...), or DSL text. |
| `options?` | `RenderOptions>, default: () =` |  |  |

**Events**

- `ready`

### `GrafloriaFlow`

```ts
const GrafloriaFlow: any
```

**Props**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes?` | `NodeSpec[]` |  | Controlled nodes — `v-model:nodes`. |
| `edges?` | `EdgeSpec[]` |  | Controlled edges — `v-model:edges`. |
| `groups?` | `Array<GroupSpec \| GroupModel>` |  | Controlled groups — zones around some nodes (a spec's `groups`, or the live |
| `defaultNodes?` | `NodeSpec[]` |  | Uncontrolled initial data. |
| `defaultEdges?` | `EdgeSpec[]` |  |  |
| `defaultGroups?` | `Array<GroupSpec \| GroupModel>` |  |  |
| `theme?` | `Theme` |  |  |
| `layout?` | `string \| GrafloriaLayoutRequest` |  | Declarative auto-layout — any engine registry name ('elk', 'dagre', |
| `plugins?` | `boolean \| CanvasPluginOptions` |  | Canvas plugins — `true` mounts minimap + zoom/fit controls + background |
| `collab?` | `GrafloriaCollabOptions` |  | Real-time collaboration: a transport + actor id — the flow joins a CRDT |
| `comments?` | `boolean \| object` |  | Anchored comment threads — `true` creates a store; or pass a shared one. |
| `commentsViewer?` | `String` |  |  |
| `fitView?` | `Boolean` |  |  |
| `enablePan?` | `Boolean` |  |  |
| `enableZoom?` | `Boolean` |  |  |
| `readonly?` | `Boolean` |  |  |
| `minZoom?` | `Number` |  |  |
| `maxZoom?` | `Number` |  |  |
| `zoomSensitivity?` | `Number` |  |  |
| `rendererConfig?` | `Record<string, unknown>` |  | Renderer config passthrough (parallelLinks, parallelSpacing, jump styles, …). |
| `interaction?` | `Record<string, unknown>` |  | Interaction config passthrough (portVisibility, enableHelperLines, …). |
| `tokenBridge?` | `unknown` |  | Design-token bridge — adopt the app's shadcn / MUI / Tailwind CSS variables. |
| `highlighterConfig?` | `boolean \| Partial<HighlighterConfig>` |  | The outline layer Angular's canvas draws: outlines around the hovered node, |
| `highlightConnected?` | `boolean \| HighlightConnectedOptions` |  | Bring the selected nodes' lines forward and fade the rest: `true`, or |

**Events**

- `update:nodes`
- `update:edges`
- `init`
- `selectionChange`
- `connect`
- `nodeClick`
- `edgeClick`
- `layoutDone`
- `collabReady`

### `GrafloriaProvider`

Makes the nearest `<GrafloriaFlow>`'s instance reachable by SIBLINGS —
toolbars, inspectors, minimaps — through the composables below.

```ts
const GrafloriaProvider: any
```

## Interfaces

### `GrafloriaCollabOptions`

The uniform collab contract every Grafloria wrapper shares.

```ts
interface GrafloriaCollabOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `transport` | `SyncTransport` |  |  |
| `actor` | `string` |  |  |
| `presence?` | `boolean \| BindPresenceOptions` |  | Live cursors + remote selection outlines. `true` for defaults. |

### `GrafloriaLayoutRequest`

```ts
interface GrafloriaLayoutRequest
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  |  |
| `options?` | `Record<string, unknown>` |  |  |

### `NodeSlotProps`

Context handed to `#node-<type>` slots.

```ts
interface NodeSlotProps
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `node` | `NodeModel` |  |  |
| `data` | `Record<string, unknown>` |  |  |
| `engine` | `DiagramEngine` |  |  |

### `SelectionChange`

```ts
interface SelectionChange
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` | `NodeModel[]` |  |  |
| `edges` | `LinkModel[]` |  |  |

## Also exported from here

These names are documented with the package that defines them, and can be imported from this one too.

- From [@grafloria/renderer](https://atloria.dev/p/grafloria-h7YM7amryF/developer/grafloria-renderer-overview): `DARK_THEME`, `DiagramInstance`, `EdgeSpec`, `LIGHT_THEME`, `NodeSpec`, `Theme`