# Templates

Import these from `@grafloria/engine`.

## Functions

### `builtInStencils`

The stencils that ship with Grafloria — the 80 generated NOTATION masters
(flowchart / BPMN / UML / ERD), each a true silhouette the SVG canvas draws. Freshly built on each call so a caller can mutate the returned arrays without
corrupting the built-ins.

```ts
function builtInStencils(): Stencil[]
```

### `generatedTemplates`

All generated masters, deduped by id (the registry keys on id anyway).

```ts
function generatedTemplates(): NodeTemplate[]
```

### `getStencil`

Built-in stencils, by id.

```ts
function getStencil(id: string): Stencil | undefined
```

### `listStencils`

Alias of {@link builtInStencils} — the palette's "what can I show?" call.

```ts
function listStencils(): Stencil[]
```

### `registerGeneratedTemplates`

Register every generated master into `registry`. Returns the number
registered. Idempotent — re-registering an id overwrites in place.

```ts
function registerGeneratedTemplates(registry: TemplateRegistry): number
```

### `registerStencils`

Register every master of the given stencils (default: all built-ins) into a
{@link TemplateRegistry}, so `NodeFactory` can stamp any of them by id. Returns the number of masters registered.

```ts
function registerStencils(registry: TemplateRegistry, stencils: Stencil[] = builtInStencils()): number
```

## Classes

### `NodeFactory`

```ts
class NodeFactory
```

**Methods**

- `constructor( private templateRegistry: TemplateRegistry, private diagram: DiagramModel )`
- `createFromTemplate( templateId: string, data: Record<string, any>, position: { x: number; y: number } ): NodeModel` — Create node(s) from template

### `TemplateLoader`

```ts
class TemplateLoader
```

**Methods**

- `static fromJSON(json: string): NodeTemplate` (static) — Load template from JSON string
- `static fromObject(obj: any): NodeTemplate` (static) — Load template from object
- `static fromJSONArray(json: string): NodeTemplate[]` (static) — Load multiple templates from JSON array
- `static toJSON(template: NodeTemplate, pretty: boolean = true): string` (static) — Export template to JSON string
- `static toJSONArray(templates: NodeTemplate[], pretty: boolean = true): string` (static) — Export multiple templates to JSON array

### `TemplateRegistry`

```ts
class TemplateRegistry
```

**Methods**

- `constructor(private eventBus: EventBus)`
- `register(template: NodeTemplate): void` — Register a template
- `registerMany(templates: NodeTemplate[]): void` — Register multiple templates
- `unregister(templateId: string): boolean` — Unregister a template
- `get(id: string): NodeTemplate | undefined` — Get template by ID
- `getAll(): NodeTemplate[]` — Get all registered templates
- `getByCategory(category: string): NodeTemplate[]` — Get templates by category
- `search(query: string): NodeTemplate[]` — Search templates by name, description, or tags
- `getCategories(): string[]` — Get all unique categories (sorted)
- `has(templateId: string): boolean` — Check if template exists
- `count(): number` — Get template count
- `clear(): void` — Clear all templates
- `registerValidator(id: string, validator: ConnectionValidator): void` — Register custom connection validator
- `getValidator(id: string): ConnectionValidator | undefined` — Get connection validator

## Interfaces

### `DataBindConfig`

Data binding configuration

```ts
interface DataBindConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `bindings?` | `Record<string, string>` |  |  |
| `condition?` | `string` |  |  |

### `DragHandlerConfig`

Drag handler configuration

```ts
interface DragHandlerConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `isDragHandler` | `boolean` |  |  |
| `dragChildren?` | `boolean` |  |  |
| `snapToGrid?` | `boolean` |  |  |
| `gridSize?` | `number` |  |  |

### `HtmlConfig`

HTML rendering configuration
Enhanced to support LemonadeJS templates for framework-agnostic rendering

```ts
interface HtmlConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode?` | `'component' \| 'template'` |  | Rendering mode - 'component': Reference to a framework-specific component (Angular, React, etc.) - 'template': LemonadeJS template string (framework-agnostic) |
| `component?` | `string` |  | Component reference (for mode='component') Used when integrating with framework-specific components |
| `template?` | `string` |  | LemonadeJS template string (for mode='template') HTML string with LemonadeJS binding syntax Example: '<div>{{data.name}}</div>' |
| `className?` | `string \| string[]` |  | CSS classes to apply |
| `style?` | `Record<string, any>` |  | Inline styles |
| `bindings?` | `Record<string, string>` |  | Data bindings (property mappings) Maps template variables to node data paths Example: { userName: 'data.user.name', count: 'data.items.length' } |
| `events?` | `Record<string, string>` |  | Event handlers Maps DOM events to engine event names Example: { click: 'node:clicked', input: 'node:valueChanged' } |
| `zIndex?` | `number` |  | Z-index for HTML layer positioning |
| `pointerEvents?` | `boolean` |  | Whether to enable pointer events If false, the HTML layer won't capture mouse events (pass-through to SVG) |

### `NodeStructureDefinition`

Node structure definition (recursive)

```ts
interface NodeStructureDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `string` |  |  |
| `role?` | `NodeRole` |  |  |
| `size?` | `{ width?: number \| string; height?: number \| string; minWidth?: number; maxWidth?: number; minHeight?: number; maxHeight?: number; }` |  |  |
| `shape?` | `ShapeConfig` |  | Shape configuration for SVG rendering Defines the geometric shape of the node If not specified, defaults to rectangle |
| `labelPlacement?` | `'inside' \| 'below'` |  | Where the node's caption paints. `'inside'` (default) centres it in the shape's inner rect; `'below'` paints it centred UNDER the silhouette — the Visio/BPMN convention for glyph-sized masters (event circles, gateway diamonds, connectors, fork/join bars) whose caption cannot fit inside. Carried to the node as `metadata.labelPlacement`; the renderer consumes it. |
| `layout?` | `LayoutConfig` |  |  |
| `ports?` | `PortsConfig` |  |  |
| `behavior?` | `{ draggable?: boolean; dragHandler?: DragHandlerConfig; selectable?: boolean; connectable?: boolean; resizable?: boolean; deletable?: boolean; }` |  |  |
| `connectionGroup?` | `string` |  |  |
| `connectionRestrictions?` | `{ allowedGroups?: string[]; disallowedGroups?: string[]; customValidatorId?: string; }` |  |  |
| `html?` | `HtmlConfig` |  |  |
| `dataBind?` | `DataBindConfig` |  |  |
| `className?` | `string` |  |  |
| `style?` | `Record<string, any>` |  |  |
| `children?` | `NodeStructureDefinition[]` |  |  |
| `repeater?` | `RepeaterConfig` |  |  |

### `NodeTemplate`

Node template definition

```ts
interface NodeTemplate
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | Unique template identifier |
| `version` | `string` |  | Template version (semver) |
| `meta` | `TemplateMetadata` |  | Template metadata |
| `structure` | `NodeStructureDefinition` |  | Root node structure |
| `dataSchema?` | `Record<string, any>` |  | Data schema for validation (JSON Schema) |
| `defaultData?` | `Record<string, any>` |  | Default data values |
| `styles?` | `Record<string, any>` |  | Style presets |

### `PortConfig`

Port configuration for a specific side

```ts
interface PortConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled` | `boolean` |  |  |
| `visibility?` | `PortVisibility` |  |  |
| `type?` | `'input' \| 'output' \| 'bi'` |  |  |
| `maxConnections?` | `number` |  |  |

### `PortRenderingConfig`

Port rendering configuration

```ts
interface PortRenderingConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | `PortRenderingMode` |  | Rendering mode: 'svg', 'html', or 'auto' |
| `size?` | `{ width: number; height: number; hoverScale?: number; }` |  | Port size |
| `html?` | `{ component?: string; className?: string \| string[]; style?: Record<string, any>; zIndex?: number; }` |  | HTML-specific configuration |
| `svg?` | `{ shape?: 'circle' \| 'rect' \| 'custom'; fill?: string; stroke?: string; strokeWidth?: number; }` |  | SVG-specific configuration |
| `visibility?` | `{ default?: PortVisibility; showOnNodeHover?: boolean; showOnNodeSelected?: boolean; }` |  | Visibility configuration |

### `PortsConfig`

```ts
interface PortsConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled?` | `boolean` |  |  |
| `defaultVisibility?` | `PortVisibility` |  |  |
| `rendering?` | `PortRenderingConfig` |  |  |
| `groups?` | `PortGroupSpec[]` |  | . When present, the four side slots below are not consulted. |
| `top?` | `PortConfig` |  |  |
| `right?` | `PortConfig` |  |  |
| `bottom?` | `PortConfig` |  |  |
| `left?` | `PortConfig` |  |  |

### `RepeaterConfig`

Repeater configuration for dynamic children

```ts
interface RepeaterConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `dataSource` | `string` |  |  |
| `itemTemplate` | `NodeStructureDefinition` |  |  |
| `keyField?` | `string` |  |  |

### `ShapeConfig`

Shape configuration for SVG node rendering
Defines the geometric shape of the node in the SVG layer

```ts
interface ShapeConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `ShapeType` |  | Shape type |
| `fill?` | `string` |  | Fill color (CSS color) |
| `stroke?` | `string` |  | Stroke color (CSS color) |
| `strokeWidth?` | `number` |  | Stroke width in pixels |
| `cornerRadius?` | `number` |  | Corner radius for rectangles (in pixels) |
| `opacity?` | `number` |  | Opacity (0-1) |

### `Stencil`

A named, categorized set of masters — one section of a stencil palette.

```ts
interface Stencil
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | Stable id, e.g. `'bpmn'`. |
| `name` | `string` |  | Display name for the palette section, e.g. `'BPMN'`. |
| `description` | `string` |  | One-line description of what the set covers. |
| `masters` | `NodeTemplate[]` |  | The shape masters in this set. |

### `TemplateMetadata`

Template metadata

```ts
interface TemplateMetadata
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  |  |
| `description?` | `string` |  |  |
| `category` | `string` |  |  |
| `icon?` | `string` |  |  |
| `preview?` | `string` |  |  |
| `tags?` | `string[]` |  |  |
| `author?` | `string` |  |  |
| `license?` | `string` |  |  |

## Types

### `FlexDirection`

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

Flexbox direction

```ts
type FlexDirection = 'row' | 'column' | 'row-reverse' | 'column-reverse';
```

### `NodeRole`

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

Node role in hierarchy

```ts
type NodeRole = 'container' | 'drag-handler' | 'content' | 'repeater';
```

### `PortRenderingMode`

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

Port rendering mode

```ts
type PortRenderingMode = 'svg' | 'html' | 'auto';
```

### `PortVisibility`

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

Port visibility strategy

```ts
type PortVisibility = 'always' | 'on-hover' | 'never';
```

### `ShapeType`

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

Shape type for SVG rendering.

The five originals (rect/circle/ellipse/diamond/hexagon) plus the extended
flowchart / BPMN / UML / ERD figure library. Every value here has a matching
ShapeDefinition in the renderer's shape registry (libs/renderer/src/svg/
shape-registry.ts); adding a shape means: register its geometry there and add
its name here. A few widely-used aliases (database, stadium, data …) are
included so callers can type the vocabulary they already know.

```ts
type ShapeType =

  | 'rect'
  | 'circle'
  | 'ellipse'
  | 'diamond'
  | 'hexagon'

  | 'parallelogram'
  | 'parallelogram-top'
  | 'trapezoid'
  | 'trapezoid-bottom'
  | 'triangle'
  | 'triangle-down'
  | 'package'
  | 'cube'
  | 'document'
  | 'cylinder'
  | 'cloud'
  | 'predefined-process'
  | 'component'
  | 'note'
  | 'terminal'
  | 'actor'

  | 'delay'
  | 'display'
  | 'summing-junction'
  | 'or-junction'
  | 'sync-bar'
  | 'double-rect'
  | 'double-diamond'
  | 'double-ellipse'

  | 'gateway-xor'
  | 'gateway-or'
  | 'gateway-and'
  | 'event-intermediate'
  | 'final-node'

  | 'database'
  | 'stadium'
  | 'data'
  | 'subroutine'
  | 'folder';
```