211 lines
9.1 KiB
Markdown
211 lines
9.1 KiB
Markdown
# @blinksgg/canvas — API Stability
|
|
|
|
This document defines the stability level of each export entry point.
|
|
Stable APIs follow semver — breaking changes only in major versions.
|
|
|
|
## Stability Levels
|
|
|
|
- **Stable** — Safe for production. Breaking changes only in major versions.
|
|
- **Beta** — API may change in minor versions. Use with awareness.
|
|
- **Experimental** — API may change in any release. Not recommended for production.
|
|
|
|
## Entry Points
|
|
|
|
### `@blinksgg/canvas` (root) — Stable
|
|
|
|
The main barrel export. Re-exports from all subpackages.
|
|
|
|
| Export | Stability | Notes |
|
|
|--------|-----------|-------|
|
|
| `Canvas` component | Stable | Main orchestrator |
|
|
| `canvasVersion` | Stable | Version info object |
|
|
| All components | Stable | See components section below |
|
|
| All hooks | Stable | See hooks section below |
|
|
| All core atoms | Stable | 219+ atoms, consistent `*Atom` naming |
|
|
|
|
### `@blinksgg/canvas/core` — Stable
|
|
|
|
Headless state management. All Jotai atoms, types, and pure functions.
|
|
|
|
| Module | Stability | Notes |
|
|
|--------|-----------|-------|
|
|
| `graph-store` | Stable | Graph state, graphId, edge creation |
|
|
| `graph-position` | Stable | Node position atoms and families |
|
|
| `graph-derived` | Stable | Computed atoms (uiNodes, nodeKeys, edgeKeys) |
|
|
| `graph-mutations` | Stable | Node/edge CRUD operations |
|
|
| `viewport-store` | Stable | Zoom, pan, viewport transforms |
|
|
| `selection-store` | Stable | Node/edge selection management |
|
|
| `history-store` | Stable | Delta-based undo/redo |
|
|
| `clipboard-store` | Stable | Copy/cut/paste/duplicate |
|
|
| `snap-store` | Stable | Grid snapping, alignment guides |
|
|
| `group-store` | Stable | Node grouping/nesting |
|
|
| `search-store` | Stable | Node/edge search and filter |
|
|
| `toast-store` | Stable | Toast notifications |
|
|
| `interaction-store` | Stable | Input modes, picking |
|
|
| `settings-store` | Stable | Event-action mappings, presets |
|
|
| `action-registry` | Stable | Action handler registration |
|
|
| `virtualization-store` | Stable | Viewport culling metrics |
|
|
| `locked-node-store` | Stable | Detail view lock/unlock |
|
|
| `sync-store` | Stable | Mutation queue, online status |
|
|
| `input-store` | Stable | Pointer tracking, input classification |
|
|
| `port-types` | Stable | Port definition types |
|
|
| `types` | Stable | Core type definitions |
|
|
| `canvas-api` | Stable | Headless programmatic API |
|
|
| `spatial-index` | Stable | O(visible) spatial grid |
|
|
| `perf` | Stable | Performance instrumentation |
|
|
| `gesture-rules` | Stable | Composable gesture rule system |
|
|
| `gesture-resolver` | Stable | Intent resolution types |
|
|
| `reduced-motion-store` | Stable | prefers-reduced-motion support |
|
|
| `external-keyboard-store` | Stable | External keyboard detection |
|
|
| `input-classifier` | Stable | Pointer source classification |
|
|
| `node-type-registry` | Stable | Custom node type registration |
|
|
|
|
### `@blinksgg/canvas/hooks` — Stable
|
|
|
|
React hooks for canvas interaction.
|
|
|
|
| Hook | Stability | Notes |
|
|
|------|-----------|-------|
|
|
| `useCanvasSelection` | Stable | Selection state subscription |
|
|
| `useCanvasViewport` | Stable | Viewport state subscription |
|
|
| `useCanvasDrag` | Stable | Drag state subscription |
|
|
| `useCanvasHistory` | Stable | Undo/redo with keyboard shortcuts |
|
|
| `useNodeSelection` | Stable | Per-node selection |
|
|
| `useNodeDrag` | Stable | Per-node drag mechanics |
|
|
| `useNodeResize` | Stable | Per-node resize mechanics |
|
|
| `useFitToBounds` | Stable | Fit viewport to selection/graph |
|
|
| `useLayout` | Stable | Layout engine base |
|
|
| `useTreeLayout` | Stable | Hierarchical tree layout |
|
|
| `useGridLayout` | Stable | Grid layout |
|
|
| `useAnimatedLayout` | Stable | Shared animation interpolation |
|
|
| `useForceLayout` | Stable | D3 force-directed layout (requires d3-force) |
|
|
| `useCanvasSettings` | Stable | Settings/preset management |
|
|
| `useActionExecutor` | Stable | Action execution |
|
|
| `useVirtualization` | Stable | Virtualization toggle/metrics |
|
|
| `useCanvasGraph` | Stable | Graph structure access |
|
|
| `useCommandLine` | Stable | Command palette state |
|
|
| `useGestureResolver` | Stable | Gesture resolution |
|
|
| `useArrowKeyNavigation` | Stable | Arrow key navigation |
|
|
| `useZoomTransition` | Stable | Animated zoom state |
|
|
| `useTapGesture` | Stable | Cross-input tap detection |
|
|
| `useSplitGesture` | Stable | Two-finger node split |
|
|
| `usePlugin` | Stable | Single plugin registration/lifecycle |
|
|
| `usePlugins` | Stable | Multi-plugin registration/lifecycle |
|
|
|
|
### `@blinksgg/canvas/components` — Stable
|
|
|
|
All React components.
|
|
|
|
| Component | Stability | Notes |
|
|
|-----------|-----------|-------|
|
|
| `Canvas` | Stable | Main component with gesture pipeline |
|
|
| `Viewport` | Stable | Pan/zoom container |
|
|
| `NodeRenderer` | Stable | Renders nodes with virtualization |
|
|
| `Node` | Stable | Individual node wrapper |
|
|
| `EdgeRenderer` | Stable | Renders edges with animations |
|
|
| `SelectionOverlay` | Stable | Lasso/rect selection |
|
|
| `Minimap` | Stable | Canvas overview |
|
|
| `ViewportControls` | Stable | Pan/zoom UI |
|
|
| `GroupNode` | Stable | Group container |
|
|
| `CommandLine` | Stable | Command palette UI |
|
|
| `CommandFeedbackOverlay` | Stable | Command input feedback |
|
|
| `NodeContextMenu` | Stable | Right-click context menu |
|
|
| `NodePorts` | Stable | Connection port bars |
|
|
| `EdgeOverlay` | Stable | Edge creation via drag |
|
|
| `EdgePreviewLine` | Stable | Edge drag preview |
|
|
| `EdgeLabelEditor` | Stable | Inline edge label editing |
|
|
| `ResizeHandle` | Stable | Node resize handles |
|
|
| `Grid`, `Crosshairs` | Stable | Background grid |
|
|
| `AlignmentGuides` | Stable | Snap alignment lines |
|
|
| `CanvasAnimations` | Stable | CSS animation injection |
|
|
| `CanvasToast` | Stable | Toast notifications |
|
|
| `TouchActionButton` | Stable | Mobile FAB radial menu |
|
|
| `SettingsPanel` | Stable | Headless settings UI |
|
|
| `NodeTypeCombobox` | Stable | Node type selector |
|
|
| `LockedNodeOverlay` | Stable | Full-screen node detail |
|
|
| `NodeErrorBoundary` | Stable | Per-node error isolation |
|
|
| `ConnectedNode` | Beta | Supabase-connected wrapper |
|
|
| `ConnectedNodeRenderer` | Beta | Supabase-connected renderer |
|
|
|
|
### `@blinksgg/canvas/commands` — Stable
|
|
|
|
Command palette system.
|
|
|
|
| Export | Stability | Notes |
|
|
|--------|-----------|-------|
|
|
| `CommandProvider` | Stable | Context provider |
|
|
| `commandRegistry` | Stable | Command registration |
|
|
| `registerBuiltinCommands` | Stable | Register all defaults |
|
|
| All command atoms | Stable | State management |
|
|
| `useGlobalKeyboard` | Stable | Keyboard shortcut handling |
|
|
| Built-in commands | Stable | Viewport, selection, history, layout, clipboard, grouping |
|
|
|
|
### `@blinksgg/canvas/gestures` — Stable
|
|
|
|
Gesture system v2. Exported from `@blinksgg/canvas/gestures`.
|
|
|
|
| Export | Stability | Notes |
|
|
|--------|-----------|-------|
|
|
| Types (`InputEvent`, `ResolvedAction`, etc.) | Stable | Core gesture types |
|
|
| `resolve`, `dispatch` | Stable | Resolution and dispatch functions |
|
|
| `InputProvider`, `GestureProvider` | Stable | React providers |
|
|
| `useCanvasGestures` | Stable | Canvas-level gesture handling |
|
|
| `useNodeGestures` | Stable | Node-level gesture handling |
|
|
| `useGestureSystem` | Stable | Full gesture system access |
|
|
| `useInputSystem` | Stable | Input pipeline access |
|
|
| Built-in contexts | Stable | DEFAULT, PALM_REJECTION, etc. |
|
|
|
|
### `@blinksgg/canvas/db` — Stable
|
|
|
|
Database integration layer. The storage adapter interface is settling but may evolve.
|
|
|
|
| Export | Stability | Notes |
|
|
|--------|-----------|-------|
|
|
| `CanvasStorageAdapter` interface | Beta | Abstract persistence interface |
|
|
| `SupabaseStorageAdapter` | Beta | Supabase implementation |
|
|
| `InMemoryStorageAdapter` | Stable | Test/demo adapter |
|
|
| `CanvasDbProvider` | Beta | Database provider component |
|
|
| DB hooks (`useCreateNode`, etc.) | Beta | React Query integration |
|
|
|
|
### `@blinksgg/canvas/nodes` — Beta
|
|
|
|
Pre-built node types.
|
|
|
|
| Export | Stability | Notes |
|
|
|--------|-----------|-------|
|
|
| `NoteNode` | Beta | Rich text node (requires @blocknote) |
|
|
|
|
### `@blinksgg/canvas/utils` — Stable
|
|
|
|
Utility functions.
|
|
|
|
| Export | Stability | Notes |
|
|
|--------|-----------|-------|
|
|
| Layout utilities | Stable | Bounds calculation, overlap detection |
|
|
| Edge path calculators | Stable | 8 path types (bezier, straight, step, etc.) |
|
|
| Hit-test utilities | Stable | Node/port hit detection |
|
|
| Debug utilities | Stable | Namespaced logging |
|
|
| Gesture config utilities | Stable | Input-source-aware thresholds |
|
|
|
|
## Naming Conventions
|
|
|
|
All 219+ public atoms follow consistent naming:
|
|
|
|
- **State atoms**: `{nounPhrase}Atom` — e.g., `graphAtom`, `selectedNodeIdsAtom`
|
|
- **Derived atoms**: `{is|has|can}{Phrase}Atom` — e.g., `canUndoAtom`, `hasSelectionAtom`
|
|
- **Action atoms**: `{verb}{Noun}Atom` — e.g., `pushHistoryAtom`, `clearSelectionAtom`
|
|
- **Family atoms**: `{noun}FamilyAtom` or `{noun}AtomFamily` — e.g., `nodePositionAtomFamily`
|
|
|
|
## onAction Callback Type
|
|
|
|
The `Canvas` component's `onAction` prop accepts `(event: InputEvent, resolution: ResolvedAction) => void`.
|
|
|
|
`InputEvent` is a union of `PointerGestureEvent | KeyInputEvent`. To handle pointer-only events:
|
|
|
|
```typescript
|
|
onAction={(event, resolution) => {
|
|
if (event.kind === 'key') return;
|
|
const { subject, worldPosition } = event; // narrowed to PointerGestureEvent
|
|
// ...
|
|
}}
|
|
```
|