# Config

Import these from `@grafloria/engine`.

## Constants

### `DEFAULT_INTERACTION_CONFIG`

Default interaction configuration
Optimized for modern diagramming workflows

```ts
const DEFAULT_INTERACTION_CONFIG: InteractionConfig
```

### `DELIBERATE_MODE_CONFIG`

Deliberate mode preset (safe workflow)

```ts
const DELIBERATE_MODE_CONFIG: Partial<InteractionConfig>
```

### `DIRECT_MODE_CONFIG`

Direct mode preset (fast workflow)

```ts
const DIRECT_MODE_CONFIG: Partial<InteractionConfig>
```

### `SMART_MODE_CONFIG`

Smart mode preset (Visio-style)

```ts
const SMART_MODE_CONFIG: Partial<InteractionConfig>
```

## Interfaces

### `ControlPointEditorConfig`

Control point editor configuration

```ts
interface ControlPointEditorConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `snapToGrid` | `boolean` |  | Snap control points to grid |
| `gridSize` | `number` |  | Grid size for snapping (in pixels) |
| `handleRadius` | `number` |  | Control point handle radius (in pixels) |
| `handleColor` | `string` |  | Control point handle color |
| `handleStrokeColor` | `string` |  | Control point handle stroke color |
| `controlLineColor` | `string` |  | Control line color (line from anchor to control point) |
| `controlLineWidth` | `number` |  | Control line stroke width |
| `controlLineDash` | `number[]` |  | Control line dash pattern (e.g., [5, 5] for dashed) |
| `clickDetectionRadius` | `number` |  | Maximum distance from control handle to detect click (in pixels) |
| `showControlLines` | `boolean` |  | Show control lines connecting anchors to control points |
| `symmetricControls` | `boolean` |  | Auto-generate symmetric control points (mirror on both sides) |

### `InteractionConfig`

Interaction configuration

```ts
interface InteractionConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | `InteractionMode` |  | Interaction mode (direct, deliberate, smart) |
| `dragThreshold` | `number` |  | Movement threshold in screen pixels that separates a click from a drag. A pointer must travel farther than this from its down position before a gesture is treated as a drag (node move / marquee) rather than a click. This is what prevents a plain click from micro-jittering a node's position. Default: 4. |
| `portVisibility` | `PortVisibilityStrategy` |  | Port visibility strategy |
| `portHoverScaleFactor` | `number` |  | Port hover scale factor (e.g., 1.5 = 50% larger on hover) |
| `portDefaultRadius` | `number` |  | Port default radius in pixels |
| `snapToPortRadius` | `number` |  | Snap to port radius in pixels Connection will snap when mouse is within this distance |
| `showConnectionPreview` | `boolean` |  | Show connection preview line while dragging |
| `connectionLineStyle` | `ConnectionLineStyle` |  | Connection line style for preview |
| `enableLinkReconnection` | `boolean` |  | Enable link endpoint reconnection |
| `showLinkEndpointHandles` | `boolean` |  | Show endpoint handles on selected links |
| `enableSmartAutoConnect` | `boolean` |  | Enable smart mode nearest port auto-connect When enabled, dropping on node body connects to nearest port |
| `highlightValidTargets` | `boolean` |  | Highlight valid connection targets during drag |
| `animateConnectionPreview` | `boolean` |  | Show animated dots on connection preview |
| `enableWaypointEditing` | `boolean` |  | Enable waypoint editing on links Allow users to add/move/remove waypoints by clicking/dragging link paths |
| `showWaypointHandles` | `boolean` |  | Show waypoint handles on selected links |
| `waypointEditor?` | `WaypointEditorConfig` |  | Waypoint editor configuration |
| `enableControlPointEditing` | `boolean` |  | Enable control point editing on bezier curves Allow users to adjust bezier control points by dragging handles |
| `showControlPointHandles` | `boolean` |  | Show control point handles on selected bezier links |
| `controlPointEditor?` | `ControlPointEditorConfig` |  | Control point editor configuration |
| `enableGroupDrag` | `boolean` |  | (gap 1) — Drag a group's frame to move the whole subflow: the container and every member node (recursively through nested groups) translate by the same delta, committed as ONE undoable step. |
| `enableProximityConnect` | `boolean` |  | After a node drag, if one of its ports comes within `proximityConnectRadius` of a compatible port on another node, auto-create the link on drop (one undoable command). Drives the shipped `SnapController.findProximityConnection` from the LIVE drag path, not from host glue. Default false (opt-in). |
| `proximityConnectRadius` | `number` |  | (gap 2) — Auto-link radius in world units for {@link enableProximityConnect}. Defaults to `DEFAULT_SNAP_CONFIG`'s value when unset/0. |
| `enableHelperLines` | `boolean` |  | While dragging a single top-level node, snap it to sibling edge/centre alignments and equal spacing, and draw the guides as dashed overlay lines. The SnapController always could compute this; nothing drove it from a live drag until now. Default false (opt-in) so the stock drag feel is unchanged. |
| `enableGroupMembershipOnDrop` | `boolean` |  | T8/visio — Visio-style containment: dropping a node inside a container's frame REPARENTS it (and dropping it outside every container unembeds it), so it then moves with its container. |
| `enableInPlaceTextEdit` | `boolean` |  | T10/visio — double-click a node to edit its label in place. The editor (session + undoable commit) shipped in the renderer but was auto-wired ONLY in the Angular wrapper, so a vanilla / React / Vue embed got a `node:doubleclick` event and no caret. Default false (opt-in) so a host that already answers that event with its own editor keeps sole control. |
| `enableKeyboardNudge` | `boolean` |  | visio-depth — arrow keys NUDGE the selected node(s): 1 world unit per press, ×10 with Shift, committed through MoveNodeCommand so every nudge is undoable (and successive presses inside the CommandManager's merge window collapse to one undo entry). |
| `enableEasyConnect` | `boolean` |  | Make the whole node BODY a connection handle. A press on a node body (not over a specific port) starts a connection from the node's nearest/default port instead of a move. Default false (opt-in) so normal body-drag-to-move is preserved; when on, hold no modifier to connect and the configured {@link easyConnectModifier} (if any) still gates it. |
| `easyConnectModifier` | `'none' \| 'shift' \| 'alt' \| 'ctrl' \| 'meta'` |  | (gap 3) — Optional modifier that must be held for an easy-connect body press to start a connection (e.g. 'shift'). When 'none' (the default) any plain body press connects while {@link * enableEasyConnect} is on. Lets a host keep body-drag-to-move as the default gesture and gate connect behind a key. |

### `WaypointEditorConfig`

Waypoint editor configuration

```ts
interface WaypointEditorConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `snapToGrid` | `boolean` |  | Snap waypoints to grid |
| `gridSize` | `number` |  | Grid size for snapping (in pixels) |
| `removeOnDoubleClick` | `boolean` |  | Remove waypoint on double-click |
| `handleRadius` | `number` |  | Waypoint handle radius (in pixels) |
| `handleColor` | `string` |  | Waypoint handle color |
| `handleStrokeColor` | `string` |  | Waypoint handle stroke color |
| `minDistanceFromEndpoints` | `number` |  | Minimum distance from endpoints to add waypoint (in pixels) |
| `clickDetectionRadius` | `number` |  | Maximum distance from path to detect click (in pixels) |

## Enums

### `ConnectionLineStyle`

Connection line style for preview

```ts
enum ConnectionLineStyle
```

**Members**

- `STRAIGHT = 'straight'` — Straight line from port to mouse
- `BEZIER = 'bezier'` — Smooth bezier curve
- `STEP = 'step'` — Step function (orthogonal)

### `InteractionMode`

Interaction modes for node dragging and connection creation

```ts
enum InteractionMode
```

**Members**

- `DIRECT = 'direct'` — Direct Mode: Click+drag body=move immediately, drag port=connect
Fast workflow, industry standard
- `DELIBERATE = 'deliberate'` — Deliberate Mode: Must select node first, then drag to move
Safer workflow, prevents accidental moves
- `SMART = 'smart'` — Smart Mode (Visio-style): Hover reveals ports, intelligent auto-connect
Ports appear on hover, drop on body connects to nearest port

### `PortVisibilityStrategy`

Port visibility strategies

```ts
enum PortVisibilityStrategy
```

**Members**

- `ALWAYS = 'always'` — Ports always visible
Best for technical diagrams with few ports
- `ON_HOVER = 'on-hover'` — Ports visible only when hovering over node
Industry standard, reduces visual clutter
- `HIDDEN = 'hidden'` — Ports hidden - drag-to-connect disabled
For diagrams where connections are created programmatically