@bemedev/mind-flow 0.1.0 → 0.3.0

package/src/services/main.machine.ts

@@ -1,39 +1,42 @@
 import { createMachine } from '@bemedev/app';
-import { type } from '@bemedev/app/bemedev';
+import { toArray, type } from '@bemedev/app/bemedev';
+import type { useDragDropContext } from '@thisbeyond/solid-dnd';
 import { nanoid } from 'nanoid';
 
-import { edgeJSON, extremities, nodeJSON } from './main.typings';
+/** Type alias for drag-drop state extracted from {@linkcode useDragDropContext}. */
+export type DragDropState = Exclude<ReturnType<typeof useDragDropContext>, null>[0];
 
-/**
- * Constructs a unique edge identifier string from source and destination node IDs.
- *
- * @param out - The source node ID string.
- * @param _in - The destination node ID string.
- *
- * @returns Formatted edge identifier string.
- */
-export const buildEdgeId = (out: string, _in: string) => {
-  return `edge = ${out} => ${_in}`;
-};
-
-/**
- * Constructs a formatted node identifier string from a generated ID.
- *
- * @param generated - The generated unique ID string or `null`/`undefined`.
- *
- * @returns Formatted node identifier string.
- */
-export const buildNodeID = (generated?: string | null) => {
-  return `node-${generated}`;
-};
+import { DEFAULT_INPUT_OFFSET, getDefaultOutputOffset } from './main.machine.data';
+import {
+  buildEdgeId,
+  buildNodeID,
+  calculateDimensions,
+} from './main.machine.helpers';
+import {
+  dimension,
+  edgeJSON,
+  extremities,
+  newEdge,
+  nodeJSON,
+  point,
+  vector,
+  board,
+  type Dimension,
+  type Point,
+  type Board,
+} from './main.machine.typings';
 
 /**
  * State machine managing flowchart state transitions, nodes, edges, selection, and
  * layout actions.
+ *
+ * @see {@linkcode calculateDimensions}, {@linkcode buildEdgeId}, {@linkcode buildNodeID}, {@linkcode getDefaultOutputOffset}, {@linkcode DEFAULT_INPUT_OFFSET}
  */
 export const machine = createMachine(
   {
     initial: 'idle',
+
+    on: { SET_BOARD: { actions: ['setBoard'] } },
     states: {
       idle: {
         on: {
@@ -47,9 +50,7 @@ export const machine = createMachine(
       working: {
         on: {
           MOVE_IMMEDIATE: {
-            actions: [
-              { name: 'buildImmediateUI', description: 'Must be in the ui' },
-            ],
+            actions: [{ name: 'buildUI', description: 'Must be in the ui' }],
           },
 
           ADD_CHILD: {
@@ -70,6 +71,8 @@ export const machine = createMachine(
             target: '/construction',
           },
 
+          ADD_DIMENSION: { actions: ['addDimension'] },
+
           ADD_SIBLING: {
             actions: [
               'generateID',
@@ -81,9 +84,15 @@ export const machine = createMachine(
 
           MOVE: { actions: ['moveNode', 'buildUI'], target: '/construction' },
           ADD_EDGE: { actions: ['addEdge'], target: '/construction' },
+          START_NEW_EDGE: { actions: ['startNewEdge'] },
+          MOVE_NEW_EDGE: { actions: ['moveNewEdge'] },
+          CLEAR_NEW_EDGE: { actions: ['clearNewEdge'] },
           DELETE: { actions: ['delete'], target: '/construction' },
           SELECT: { actions: ['select'] },
           DESELECT: { actions: ['deselect'] },
+          ZOOM: { actions: ['zoom'] },
+          TOGGLE_ZOOM: { actions: ['toggleZoom'] },
+          SET_BOARD: { actions: ['setBoard'] },
         },
       },
     },
@@ -95,6 +104,7 @@ export const machine = createMachine(
         edges: array(intersection(use(edgeJSON), { id: 'string' })),
       },
 
+      SET_BOARD: use(board),
       CONFIGURE_EMPTY: 'never',
       MOVE: { id: 'string', x: 'number', y: 'number' },
       MOVE_IMMEDIATE: { id: 'string', x: 'number', y: 'number' },
@@ -105,79 +115,261 @@ export const machine = createMachine(
       SELECT: 'string',
       DESELECT: 'never',
       ADD_EDGE: use(extremities),
+      START_NEW_EDGE: 'string',
+      MOVE_NEW_EDGE: use(point),
+      CLEAR_NEW_EDGE: 'never',
+      ZOOM: 'number',
+      TOGGLE_ZOOM: 'never',
+      ADD_DIMENSION: { id: 'string', dimension: use(dimension) },
     })),
 
     sync: true,
-    pContext: type(({ union }) => ({ generatedId: union('string', 'null') })),
+    pContext: type(({ union, optional, record, use, custom }) => ({
+      generatedId: union('string', 'null'),
+      previousZoom: optional('number'),
+      dimensions: record(use(dimension)),
+
+      getBoardPosition:
+        custom<(clientX: number, clientY: number, board: Board) => Point>(),
 
-    context: type(({ optional, use, array }) => ({
+      clampPosition:
+        custom<
+          (
+            board: Board,
+            x: number,
+            y: number,
+            nodeWidth?: number,
+            nodeHeight?: number,
+          ) => Point
+        >(),
+
+      calculateDimensions:
+        custom<
+          (
+            position: { x: number; y: number },
+            parentDimension?: Pick<
+              {
+                width: number;
+                height: number;
+                output: { x: number; y: number };
+                input?: { x: number; y: number } | undefined;
+                inputOffset?: { x: number; y: number } | undefined;
+                outputOffset?: { x: number; y: number } | undefined;
+              },
+              'width' | 'height' | 'inputOffset' | 'outputOffset'
+            >,
+          ) => Dimension
+        >(),
+    })),
+
+    context: type(({ optional, use, array, record }) => ({
       data: optional({
         nodes: array({ ...use(nodeJSON), id: 'string' }),
         edges: array({ ...use(edgeJSON), id: 'string' }),
       }),
+      board: optional(use(board)),
 
+      edgesPositions: record(use(vector)),
+      newEdge: optional(use(newEdge)),
       selected: optional('string'),
       updatingUI: optional('boolean'),
+      zoom: 'number',
+      bounds: use(point),
     })),
   },
-).provideOptions(({ assign, batch, erase }) => ({
+).provideOptions(({ assign, batch, erase, filter, action }) => ({
   actions: {
     configure: batch(
-      assign('context.data', () => ({ nodes: [], edges: [] })),
-      assign('context.data.nodes', { CONFIGURE: ({ payload: { nodes } }) => nodes }),
-      assign('context.data.edges', { CONFIGURE: ({ payload: { edges } }) => edges }),
-      assign('context.updatingUI', () => false),
-      assign('pContext.generatedId', () => null),
+      assign('data', { CONFIGURE: ({ payload }) => payload }),
+      assign('newEdge', () => undefined),
+      assign('updatingUI', () => false),
+      action(({ pContext }) => {
+        pContext.generatedId = null;
+      }),
+      action({
+        CONFIGURE: ({ payload: { nodes }, pContext: { dimensions } }) => {
+          nodes.forEach(({ id, position }) => {
+            dimensions[id] = calculateDimensions(position);
+          });
+        },
+      }),
+    ),
+
+    startNewEdge: assign('newEdge', {
+      START_NEW_EDGE: ({ payload: from, pContext: { dimensions } }) => {
+        const { x, y } = dimensions[from].output;
+        return { from, x0: x, y0: y, x1: x, y1: y };
+      },
+    }),
+
+    setBoard: assign('board', { SET_BOARD: ({ payload }) => payload }),
+
+    buildUI: batch(
+      assign('edgesPositions', {
+        MOVE: ({
+          context: { data, edgesPositions },
+          payload,
+          pContext: { dimensions },
+        }) => {
+          const edges = data?.edges;
+          const dimension = dimensions[payload.id];
+
+          const outputOffset =
+            dimension?.outputOffset ?? getDefaultOutputOffset(dimension?.width);
+
+          const inputOffset = dimension?.inputOffset ?? DEFAULT_INPUT_OFFSET;
+
+          const output = {
+            x: payload.x + outputOffset.x,
+            y: payload.y + outputOffset.y,
+          };
+
+          const input = {
+            x: payload.x + inputOffset.x,
+            y: payload.y + inputOffset.y,
+          };
+
+          if (dimension) {
+            dimension.output = output;
+            dimension.input = input;
+          }
+
+          edges?.forEach(({ from, to, id }) => {
+            if (from === payload.id) {
+              edgesPositions[id].x0 = output.x;
+              edgesPositions[id].y0 = output.y;
+            }
+            if (to === payload.id) {
+              edgesPositions[id].x1 = input.x;
+              edgesPositions[id].y1 = input.y;
+            }
+          });
+
+          return edgesPositions;
+        },
+        MOVE_IMMEDIATE: ({
+          context: { data, edgesPositions },
+          payload,
+          pContext: { dimensions },
+        }) => {
+          const edges = data?.edges;
+
+          edges?.forEach(({ from, to, id }) => {
+            if (from === payload.id) {
+              const dimension = dimensions[payload.id];
+              const offset =
+                dimension?.outputOffset ?? getDefaultOutputOffset(dimension?.width);
+
+              const x0 = payload.x + offset.x;
+              const y0 = payload.y + offset.y;
+              edgesPositions[id].x0 = x0;
+              edgesPositions[id].y0 = y0;
+
+              if (dimension) {
+                dimension.output.x = x0;
+                dimension.output.y = y0;
+              }
+            }
+
+            if (to === payload.id) {
+              const dimension = dimensions[payload.id];
+              const offset = dimension?.inputOffset ?? DEFAULT_INPUT_OFFSET;
+
+              const x1 = payload.x + offset.x;
+              const y1 = payload.y + offset.y;
+              edgesPositions[id].x1 = x1;
+              edgesPositions[id].y1 = y1;
+
+              if (dimension) {
+                dimension.input = { x: x1, y: y1 };
+              }
+            }
+          });
+
+          return edgesPositions;
+        },
+        else: ({ context: { data, edgesPositions }, pContext: { dimensions } }) => {
+          const edges = data?.edges ?? [];
+          edgesPositions = {};
+
+          edges.forEach(({ from, id, to }) => {
+            const output = dimensions[from]?.output;
+            const input = dimensions[to]?.input;
+
+            if (output && input) {
+              edgesPositions[id] = {
+                x0: output.x,
+                y0: output.y,
+                x1: input.x,
+                y1: input.y,
+              };
+            } else {
+              delete edgesPositions[id];
+            }
+          });
+
+          return edgesPositions;
+        },
+      }),
+
+      assign('updatingUI', () => true),
     ),
 
-    generateID: assign('pContext.generatedId', () => nanoid()),
+    addDimension: action({
+      ADD_DIMENSION: ({ payload: { id, dimension }, pContext: { dimensions } }) => {
+        dimensions[id] = dimension;
+      },
+    }),
+
+    generateID: action(({ pContext }) => {
+      pContext.generatedId = nanoid();
+    }),
 
     linkChild: batch(
-      assign('context.data.edges', {
-        ADD_CHILD: ({ context, pContext, payload }) => {
-          const data = context.data;
+      assign('data.edges', {
+        ADD_CHILD: ({ context: { data }, pContext, payload }) => {
+          const edges = toArray.typed(data?.edges);
           const from = payload;
           const generatedId = pContext?.generatedId;
           const to = buildNodeID(generatedId);
           const id = buildEdgeId(from, to);
-          return [...(data?.edges ?? []), { id, from, to }];
+          edges.push({ id, from, to });
+          return edges;
         },
       }),
 
-      assign('context.selected', ({ pContext: { generatedId } }) =>
+      assign('selected', ({ pContext: { generatedId } }) =>
         buildNodeID(generatedId),
       ),
     ),
 
     linkSibling: batch(
-      assign('context.data.edges', {
-        ADD_SIBLING: ({ pContext, payload, context }) => {
-          const edges = context.data?.edges;
+      assign('data.edges', {
+        ADD_SIBLING: ({ pContext, payload, context: { data } }) => {
+          const edges = toArray.typed(data?.edges);
           const generatedId = pContext?.generatedId;
-          const out = [...(edges ?? [])];
-          const from = edges?.find(({ to }) => to === payload)?.from;
-          if (!from) return out;
+          const from = edges.find(({ to }) => to === payload)?.from;
+          if (!from) return edges;
 
           const to = buildNodeID(generatedId);
           const id = buildEdgeId(from, to);
-          out.push({ from, to, id });
-          return out;
+          edges.push({ from, to, id });
+          return edges;
         },
       }),
 
-      assign('context.selected', ({ pContext: { generatedId } }) =>
+      assign('selected', ({ pContext: { generatedId } }) =>
         buildNodeID(generatedId),
       ),
     ),
 
-    selectParent: assign('context.selected', ({ pContext: { generatedId } }) =>
+    selectParent: assign('selected', ({ pContext: { generatedId } }) =>
       buildNodeID(generatedId),
     ),
 
-    moveNode: assign('context.data.nodes', {
+    moveNode: assign('data.nodes', {
       MOVE: ({ context: { data }, payload }) => {
         const { id, x, y } = payload;
-        if (!id) return data?.nodes ?? [];
 
         return (
           data?.nodes?.map(d => {
@@ -190,30 +382,56 @@ export const machine = createMachine(
       },
     }),
 
-    select: assign('context.selected', { SELECT: ({ payload }) => payload }),
+    select: assign('selected', { SELECT: ({ payload }) => payload }),
 
-    delete: assign(['context.data.nodes', 'context.data.edges'], {
-      DELETE: ({ context: { data }, payload }) => {
-        const nodes = data?.nodes?.filter(({ id }) => id !== payload);
-        const edges = data?.edges?.filter(
-          ({ id, from, to }) => id !== payload && from !== payload && to !== payload,
-        );
+    delete: batch(
+      filter('data.edges', {
+        DELETE: ({ id, from, to }, _, { payload }) => {
+          return id !== payload && from !== payload && to !== payload;
+        },
+      }),
+
+      filter('data.nodes', { DELETE: ({ id }, _, { payload }) => id !== payload }),
+    ),
+
+    addEdge: batch(
+      assign('data.edges', {
+        ADD_EDGE: ({ context, payload: { from, to } }) => {
+          const edges = context.data?.edges ?? [];
+          const id = buildEdgeId(from, to);
+          if (edges.some(e => e.id === id)) return edges;
 
-        return [nodes, edges];
+          const out = [...edges, { id, from, to }];
+          return out;
+        },
+      }),
+      erase('newEdge'),
+    ),
+
+    clearNewEdge: erase('newEdge'),
+    deselect: erase('selected'),
+
+    zoom: assign('zoom', {
+      ZOOM: ({ context: { zoom }, payload, pContext }) => {
+        const next = zoom + payload;
+        const clamped = Math.min(Math.max(Number(next.toFixed(2)), 0.2), 3);
+        pContext.previousZoom = undefined;
+        return clamped;
       },
     }),
 
-    addEdge: assign('context.data.edges', {
-      ADD_EDGE: ({ context, payload: { from, to } }) => {
-        const edges = context.data?.edges ?? [];
-        const id = buildEdgeId(from, to);
-        if (edges.some(e => e.id === id)) return edges;
+    toggleZoom: assign('zoom', {
+      TOGGLE_ZOOM: ({ context: { zoom }, pContext }) => {
+        const previous = pContext.previousZoom;
 
-        const out = [...edges, { id, from, to }];
-        return out;
+        if (previous !== undefined) {
+          pContext.previousZoom = undefined;
+          return previous;
+        }
+
+        pContext.previousZoom = zoom;
+        return 1;
       },
     }),
-
-    deselect: erase('context.selected'),
   },
 }));

package/src/services/main.machine.typings.ts

@@ -0,0 +1,98 @@
+import { type } from '@bemedev/app/bemedev';
+import type { inferT } from '@bemedev/app/typings';
+
+/** Schema definition for 2D coordinates `(x, y)`. */
+export const point = type({ x: 'number', y: 'number' });
+
+/** 2D coordinate point type inferred from schema {@linkcode point}. */
+export type Point = inferT<typeof point>;
+
+/**
+ * Schema definition for node handle offsets (input and output).
+ *
+ * @see {@linkcode point}
+ */
+export const nodeOffset = type(({ optional, use }) => ({
+  input: optional(use(point)),
+  output: use(point),
+}));
+
+/** Schema definition for edge extremities. */
+export const extremities = type({ from: 'string', to: 'string' });
+
+/**
+ * Schema definition for a serialized flowchart node entity.
+ *
+ * @see {@linkcode point}
+ */
+export const nodeJSON = type(({ optional, use }) => ({
+  position: use(point),
+  data: { label: optional('string'), content: 'string' },
+  input: 'boolean',
+}));
+
+/**
+ * Schema definition for a serialized flowchart edge entity.
+ *
+ * @see {@linkcode extremities}
+ */
+export const edgeJSON = extremities;
+
+/**
+ * Schema definition for layout dimensions and connection points of a node.
+ *
+ * @see {@linkcode point}
+ */
+export const dimension = type(({ optional, use }) => ({
+  width: 'number',
+  height: 'number',
+  output: use(point),
+  input: optional(use(point)),
+  inputOffset: optional(use(point)),
+  outputOffset: optional(use(point)),
+}));
+
+/** Node layout dimension type inferred from schema {@linkcode dimension}. */
+export type Dimension = inferT<typeof dimension>;
+
+/**
+ * Schema definition for a 2D line vector representing edge coordinates `(x0, y0)` to
+ * `(x1, y1)`.
+ */
+export const vector = type({
+  x0: 'number',
+  y0: 'number',
+  x1: 'number',
+  y1: 'number',
+});
+
+/** 2D vector coordinate type inferred from schema {@linkcode vector}. */
+export type Vector = inferT<typeof vector>;
+
+/**
+ * Schema definition for an ongoing new connection edge creation preview between
+ * source node and cursor position.
+ *
+ * @see {@linkcode vector}
+ */
+export const newEdge = type(({ intersection, use }) =>
+  intersection({ from: 'string' }, use(vector)),
+);
+
+/** Ongoing new connection edge preview type inferred from schema {@linkcode newEdge}. */
+export type Edge = inferT<typeof newEdge>;
+
+/** Schema definition for flowchart board geometry and container scroll dimensions. */
+export const board = type(({ optional }) => ({
+  self: { left: 'number', top: 'number', width: 'number', height: 'number' },
+
+  parent: optional({
+    scrollLeft: 'number',
+    scrollTop: 'number',
+    height: 'number',
+    width: 'number',
+  }),
+}));
+
+/** Flowchart board layout type inferred from schema {@linkcode board}. */
+export type Board = inferT<typeof board>;

package/src/ui/Flow.tsx

@@ -11,6 +11,8 @@ import { Provider } from './components/FlowChart.context';
  *   {@linkcode FlowProps}.
  *
  * @returns The rendered Solid component.
+ *
+ * @see {@linkcode Provider}
  */
 export const Flow: Component<FlowProps> = props => (
   <Provider>

package/src/ui/components/Bounds.tsx

@@ -1,8 +1,10 @@
+import { createState } from '@bemedev/app-solidjs';
 import { useDragDropContext, type Transformer } from '@thisbeyond/solid-dnd';
 import { type Component } from 'solid-js';
 
+import { BOUNDS_CONSTRAINTS } from '#services/main.machine.data';
+
 import { useFlow } from './FlowChart.context';
-import { BOUNDS_CONSTRAINTS } from './FlowChart.data';
 
 /**
  * Drag boundary transformer component that clamps draggable nodes within container
@@ -10,12 +12,15 @@ import { BOUNDS_CONSTRAINTS } from './FlowChart.data';
  *
  * @returns `null` as this component performs side-effect transformer registrations
  *   only.
+ *
+ * @see {@linkcode useFlow}, {@linkcode BOUNDS_CONSTRAINTS}
  */
 export const DragBounds: Component = () => {
-  const {
-    board: [ref],
-    zoom: [zoom],
-  } = useFlow();
+  const service = useFlow();
+
+  const zoom = createState(service, { selector: ({ context }) => context.zoom });
+
+  const board = createState(service, { selector: ({ context }) => context.board });
 
   const [state, { addTransformer, removeTransformer, onDragStart, onDragEnd }] =
     useDragDropContext()!;
@@ -24,7 +29,7 @@ export const DragBounds: Component = () => {
     id: 'clamp-to-container',
     order: 100,
     callback: transform => {
-      const container = ref();
+      const container = board()?.self;
       const activeDraggable = state.active.draggable;
       if (!container || !activeDraggable) return transform;
 
@@ -37,7 +42,7 @@ export const DragBounds: Component = () => {
       const minBoardX = BOUNDS_CONSTRAINTS.horizontal;
       const maxBoardX = Math.max(
         minBoardX,
-        container.clientWidth / currentZoom -
+        container.width / currentZoom -
           node.offsetWidth -
           BOUNDS_CONSTRAINTS.horizontal,
       );
@@ -45,7 +50,7 @@ export const DragBounds: Component = () => {
       const minBoardY = BOUNDS_CONSTRAINTS.vertical;
       const maxBoardY = Math.max(
         minBoardY,
-        container.clientHeight / currentZoom -
+        container.height / currentZoom -
           node.offsetHeight -
           BOUNDS_CONSTRAINTS.vertical,
       );