@bemedev/mind-flow 0.3.1 → 1.0.0

package/src/ui/components/FlowChart.tsx

@@ -1,53 +1,14 @@
 import { createState } from '@bemedev/app-solidjs';
-import type { inferT } from '@bemedev/app/typings';
-import { Component, onCleanup, onMount } from 'solid-js';
+import { type JSX, onCleanup, onMount } from 'solid-js';
+
+import { DEFAULT_NODES } from '#services/main.machine.data';
+import type { NodeData, NodeProps } from '#services/main.machine.typings';
 
-import { DEFAULT_NODES } from '../../services/main.machine.data';
-import type { edgeJSON, nodeJSON } from '../../services/main.machine.typings';
 import { useFlow } from './FlowChart.context';
+import type { FlowProps } from './FlowChart.types';
 import { NodesBoard } from './NodesBoard';
 
-/** Serialized node properties type inferred from schema {@linkcode nodeJSON}. */
-export type NodeProps = inferT<typeof nodeJSON>;
-
-/** Serialized edge properties type inferred from schema {@linkcode edgeJSON}. */
-export type EdgeProps = inferT<typeof edgeJSON>;
-
-/**
- * Configuration options and callback handlers for the {@linkcode FlowChart}
- * component.
- */
-export type FlowProps = {
-  /** Initial flowchart state configuration with nodes and edges. */
-  config?: {
-    nodes?: (NodeProps & { id: string })[];
-    edges?: (EdgeProps & { id: string })[];
-  };
-  /**
-   * Callback triggered when a new node is created.
-   *
-   * @param node - The created node object of type {@linkcode NodeProps}.
-   */
-  onNodeAdded?: (node: NodeProps) => void;
-  /**
-   * Callback triggered when a node is deleted.
-   *
-   * @param nodeId - The identifier of the deleted node.
-   */
-  onNodeDeleted?: (nodeId: string) => void;
-  /**
-   * Callback triggered when an edge is created.
-   *
-   * @param edge - The created edge object of type {@linkcode EdgeProps}.
-   */
-  onEdgeAdded?: (edge: EdgeProps) => void;
-  /**
-   * Callback triggered when an edge is deleted.
-   *
-   * @param edgeId - The identifier of the deleted edge.
-   */
-  onEdgeDeleted?: (edgeId: string) => void;
-};
+export type { NodeData, NodeProps };
 
 // const PARENT_CHILD_GAP_WIDTH = 75;
 
@@ -55,6 +16,9 @@ export type FlowProps = {
  * Flowchart board canvas component that renders interactive nodes, edges, pan/zoom,
  * and toolbar controls.
  *
+ * @template | {@linkcode NodeData} `D` - Custom node data dictionary type extending
+ *   {@linkcode NodeData}.
+ *
  * @param props - Flowchart configuration and event handlers of type
  *   {@linkcode FlowProps}.
  *
@@ -62,45 +26,44 @@ export type FlowProps = {
  *
  * @see {@linkcode NodesBoard}, {@linkcode useFlow}, {@linkcode DEFAULT_NODES}
  */
-export const FlowChart: Component<FlowProps> = props => {
+export const FlowChart = <D extends NodeData = NodeData>(
+  props: FlowProps<D>,
+): JSX.Element => {
   const primaryNodes = props.config?.nodes ?? DEFAULT_NODES;
   const primaryEdges = props.config?.edges;
-
   const service = useFlow();
-
   const hasNewEdge = createState(service, { selector: s => !!s.context.newEdge });
+  onCleanup(service.pause);
 
   onMount(() => {
     service.resume();
     service.send({
       type: 'CONFIGURE',
-      payload: { nodes: primaryNodes, edges: primaryEdges ?? [] },
+      payload: {
+        nodes: primaryNodes,
+        edges: primaryEdges ?? [],
+        defaultData: props.defaultData,
+      },
     });
   });
 
-  onCleanup(service.pause);
-
   return (
     <div
       class='relative h-full w-full'
       onMouseUp={() => service.send('CLEAR_NEW_EDGE')}
-      onMouseMove={event => {
-        service.send({
-          type: 'MOVE_NEW_EDGE',
-          payload: { x: event.clientX, y: event.clientY },
-        });
+      onMouseMove={({ clientX, clientY }) => {
+        if (hasNewEdge())
+          service.send({
+            type: 'MOVE_NEW_EDGE',
+            payload: { x: clientX, y: clientY },
+          });
       }}
-      style={{}}
     >
       <div
-        class='relative h-full w-full bg-white bg-size-[30px_30px]'
-        style={{
-          cursor: hasNewEdge() ? 'inherit' : 'crosshair',
-          'background-image':
-            'radial-gradient(circle, #b8b8b8bf 1px, rgba(0, 0, 0, 0) 1px)',
-        }}
+        class='h-full w-full'
+        style={{ cursor: hasNewEdge() ? 'inherit' : 'crosshair' }}
       >
-        <NodesBoard />
+        <NodesBoard panels={props.panels} component={props.component} />
       </div>
     </div>
   );

package/src/ui/components/FlowChart.types.ts

@@ -0,0 +1,92 @@
+import type { NotUndefined } from '@bemedev/app/bemedev';
+import type { Component, JSX } from 'solid-js';
+
+import type { EdgeProps } from '#services/main.machine.typings';
+
+import type { NodeData, NodeProps } from './FlowChart';
+
+/** Overlay panel slots positioned around the flowchart canvas. */
+export type FlowPanels = {
+  /** Top-left corner overlay panel slot. */
+  topLeft?: JSX.Element | Component;
+  /** Top-right corner overlay panel slot. */
+  topRight?: JSX.Element | Component;
+  /** Bottom-left corner overlay panel slot. */
+  bottomLeft?: JSX.Element | Component;
+};
+
+/**
+ * Configuration options and callback handlers for the {@linkcode FlowChart}
+ * component.
+ *
+ * @template | {@linkcode NodeData} `D` - Custom node data dictionary type extending
+ *   {@linkcode NodeData}.
+ */
+export type FlowProps<D extends NodeData = NodeData> = {
+  /** Optional delay in milliseconds before mounting the flowchart canvas. */
+  delay?: number;
+  /** Initial flowchart state configuration with nodes and edges. */
+  config?: {
+    nodes?: (NodeProps<D> & { id: string })[];
+    edges?: (EdgeProps & { id: string })[];
+  };
+  /** Custom node component to render inside each flowchart node. */
+  component?: Component<D>;
+
+  /** Default data for new nodes created in the flowchart. */
+  defaultData?: D;
+  /** Custom overlay panels positioned around the canvas. */
+  panels?: FlowPanels;
+  /**
+   * Callback triggered when a new node is created.
+   *
+   * @param node - The created node object of type {@linkcode NodeProps}.
+   */
+  onNodeAdded?: (node: NodeProps<D>) => void;
+  /**
+   * Callback triggered when a node is deleted.
+   *
+   * @param nodeId - The identifier of the deleted node.
+   */
+  onNodeDeleted?: (nodeId: string) => void;
+  /**
+   * Callback triggered when an edge is created.
+   *
+   * @param edge - The created edge object of type {@linkcode EdgeProps}.
+   */
+  onEdgeAdded?: (edge: EdgeProps) => void;
+  /**
+   * Callback triggered when an edge is deleted.
+   *
+   * @param edgeId - The identifier of the deleted edge.
+   */
+  onEdgeDeleted?: (edgeId: string) => void;
+};
+
+/**
+ * Type alias extracting the non-undefined flowchart configuration object.
+ *
+ * @template | {@linkcode NodeData} `D` - Custom node data dictionary type extending
+ *   {@linkcode NodeData}.
+ */
+export type ConfigFrom<D extends NodeData = NodeData> = NotUndefined<
+  FlowProps<D>['config']
+>;
+
+/**
+ * Type alias extracting the non-undefined list of nodes from flowchart
+ * configuration.
+ *
+ * @template | {@linkcode NodeData} `D` - Custom node data dictionary type extending
+ *   {@linkcode NodeData}.
+ */
+export type NodesFrom<D extends NodeData> = NotUndefined<ConfigFrom<D>['nodes']>;
+
+/**
+ * Type alias extracting the non-undefined list of edges from flowchart
+ * configuration.
+ *
+ * @template | {@linkcode NodeData} `D` - Custom node data dictionary type extending
+ *   {@linkcode NodeData}.
+ */
+export type EdgesFrom<D extends NodeData> = NotUndefined<ConfigFrom<D>['edges']>;

package/src/ui/components/NodeComponent.tsx

@@ -1,64 +1,64 @@
-/* eslint-disable @typescript-eslint/no-namespace */
 import { toArray } from '@bemedev/app';
 import { createState } from '@bemedev/app-solidjs';
 import { createDraggable } from '@thisbeyond/solid-dnd';
 import { dequal } from 'dequal';
-import { Component, Show } from 'solid-js';
+import { type Component, For, type JSX, Show } from 'solid-js';
+import { Dynamic } from 'solid-js/web';
 
 import {
   HANDLE_CONTAINER_OFFSET_X,
   HANDLE_MARGIN_TOP,
   HANDLE_SIZE,
 } from '#services/main.machine.data';
+import type { NodeData } from '#services/main.machine.typings';
 
+import { resize } from '../globals/directives';
 import { useFlow } from './FlowChart.context';
 
-declare module 'solid-js' {
-  namespace JSX {
-    interface Directives {
-      draggable: any;
-    }
-  }
-}
-
 /** Properties for rendering an individual flowchart node component. */
-type Props = {
+export type NodeComponentProps<D extends NodeData = NodeData> = {
   /** Unique identifier of the node. */
   id: string;
+  /** Custom node component to render inside the node container. */
+  children?: Component<D>;
 };
 
 /**
  * Interactive flowchart node component supporting dragging, selection, handle
  * connections, and child/sibling creation.
  *
- * @param props - Node rendering properties of type {@linkcode Props}.
+ * @template | {@linkcode NodeData} `D` - Custom node data dictionary type extending
+ *   {@linkcode NodeData}.
+ *
+ * @param props - Node rendering properties of type {@linkcode NodeComponentProps}.
  *
  * @returns The rendered Solid component.
  *
  * @see {@linkcode useFlow}, {@linkcode HANDLE_CONTAINER_OFFSET_X}, {@linkcode HANDLE_MARGIN_TOP}, {@linkcode HANDLE_SIZE}
  */
-export const NodeComponent: Component<Props> = props => {
+export const NodeComponent = <D extends NodeData = NodeData>(
+  props: NodeComponentProps<D>,
+): JSX.Element => {
   const service = useFlow();
+  const newEdge = createState(service, { selector: s => s.context.newEdge });
+  const draggable = createDraggable(props.id);
+  void draggable;
 
   const node = createState(service, {
     selector: ({ context }) => {
       const list = toArray.typed(context.data?.nodes);
-      const item = list.find(n => n.id === props.id)!;
+      const item = list.find(n => n.id === props.id);
       return {
-        x: item.position.x,
-        y: item.position.y,
-        label: item.data.label,
-        content: item.data.content ?? '',
-        input: item.input,
+        x: item?.position.x ?? 0,
+        y: item?.position.y ?? 0,
+        data: (item?.data ?? {}) as D,
       };
     },
     equals: dequal,
   });
 
-  const newEdge = createState(service, { selector: s => s.context.newEdge });
-
   const selected = createState(service, {
-    selector: s => s.context.selected === props.id,
+    selector: ({ context }) => context.selected === props.id,
   });
 
   const hasParent = createState(service, {
@@ -69,15 +69,12 @@ export const NodeComponent: Component<Props> = props => {
     },
   });
 
-  const draggable = createDraggable(props.id);
-  void draggable;
-
   return (
     <div
       classList={{
         'flex flex-col absolute cursor-grab bg-white rounded-md shadow-md select-none transition-[border,box-shadow] duration-200 ease-in-out hover:shadow-lg draggable': true,
-        'border border-[#e38c29] z-[100]': selected(),
-        'border border-[#e6d4be] z-[1]': !selected(),
+        'border border-[#e38c29] z-100': selected(),
+        'border border-[#e6d4be] z-1': !selected(),
       }}
 
       style={{ top: `${node().y}px`, left: `${node().x}px` }}
@@ -89,6 +86,10 @@ export const NodeComponent: Component<Props> = props => {
         e.stopPropagation();
         service.send({ type: 'SELECT', payload: props.id });
       }}
+      onDblClick={e => {
+        e.stopPropagation();
+        service.send({ type: 'EDIT', payload: props.id });
+      }}
     >
       <div
         classList={{
@@ -121,6 +122,7 @@ export const NodeComponent: Component<Props> = props => {
         <Show when={hasParent()}>
           <svg
             class='cursor-pointer overflow-visible rounded-full bg-green-500 p-0.5 text-center font-bold hover:bg-green-600'
+
             style={{
               'pointer-events': 'all',
               'fill-rule': 'evenodd',
@@ -144,6 +146,7 @@ export const NodeComponent: Component<Props> = props => {
             </g>
           </svg>
         </Show>
+
         <svg
           class='flex cursor-pointer items-center justify-center rounded-lg bg-blue-500 p-0.5 text-center font-bold text-white hover:bg-blue-600'
           onClick={() => service.send({ type: 'ADD_CHILD', payload: props.id })}
@@ -161,51 +164,71 @@ export const NodeComponent: Component<Props> = props => {
         </svg>
       </div>
 
-      <Show when={node().label} keyed>
-        {label => (
-          <span class='min-w-max border-b border-[#f0f0f0] p-3 whitespace-nowrap text-red-600 select-none'>
-            {label}
-          </span>
-        )}
-      </Show>
-
-      <Show when={node().content} keyed>
-        {content => <div class='p-3 select-none'>{content}</div>}
-      </Show>
+      <div ref={resize(props.id)}>
+        <Show
+          when={props.children}
+          fallback={
+            <div class='p-3 select-none'>
+              <Show when={node().data.label} keyed>
+                {label => (
+                  <span class='mb-2 block min-w-max border-b border-[#f0f0f0] pb-2 font-semibold whitespace-nowrap text-red-600 select-none'>
+                    {String(label)}
+                  </span>
+                )}
+              </Show>
+
+              <Show when={node().data.content} keyed>
+                {content => <div class='select-none'>{String(content)}</div>}
+              </Show>
+
+              <Show when={!node().data.label && !node().data.content}>
+                <For each={Object.entries(node().data)}>
+                  {([key, val]) => (
+                    <div>
+                      <span class='font-semibold'>{key}: </span>
+                      <span>{String(val)}</span>
+                    </div>
+                  )}
+                </For>
+              </Show>
+            </div>
+          }
+        >
+          <Dynamic component={props.children} {...node().data} />
+        </Show>
+      </div>
 
-      <Show when={node().input || hasParent()}>
+      <div
+        id='inputs'
+        class='pointer-events-none absolute top-0 z-10 flex cursor-default flex-col'
+        style={{ left: `-${HANDLE_CONTAINER_OFFSET_X}px` }}
+      >
         <div
-          id='outputs'
-          class='pointer-events-none absolute top-0 z-10 flex cursor-default flex-col'
-          style={{ left: `-${HANDLE_CONTAINER_OFFSET_X}px` }}
-        >
-          <div
-            class='cursor-default rounded-full bg-[#e38b29] shadow-md'
+          class='cursor-default rounded-full bg-[#e38b29] shadow-md'
 
-            style={{
-              width: `${HANDLE_SIZE}px`,
-              height: `${HANDLE_SIZE}px`,
-              'margin-top': `${HANDLE_MARGIN_TOP}px`,
-              'pointer-events': 'all',
-            }}
+          style={{
+            width: `${HANDLE_SIZE}px`,
+            height: `${HANDLE_SIZE}px`,
+            'margin-top': `${HANDLE_MARGIN_TOP}px`,
+            'pointer-events': 'all',
+          }}
 
-            onMouseDown={event => {
-              event.stopPropagation();
-            }}
+          onMouseDown={event => {
+            event.stopPropagation();
+          }}
 
-            onMouseUp={event => {
-              event.stopPropagation();
-              const from = newEdge()?.from;
+          onMouseUp={event => {
+            event.stopPropagation();
+            const from = newEdge()?.from;
 
-              if (from) {
-                service.send({ type: 'ADD_EDGE', payload: { from, to: props.id } });
-              } else service.send('CLEAR_NEW_EDGE');
-            }}
-          ></div>
-        </div>
-      </Show>
+            if (from) {
+              service.send({ type: 'ADD_EDGE', payload: { from, to: props.id } });
+            } else service.send('CLEAR_NEW_EDGE');
+          }}
+        ></div>
+      </div>
       <div
-        id='inputs'
+        id='outputs'
         class='pointer-events-none absolute top-0 z-10 flex flex-col'
         style={{ right: `-${HANDLE_CONTAINER_OFFSET_X}px` }}
       >

package/src/ui/components/NodesBoard.tsx

@@ -7,38 +7,55 @@ import {
 } from '@thisbeyond/solid-dnd';
 import { dequal } from 'dequal';
 import {
-  Component,
+  type Component,
   createEffect,
   createSignal,
   For,
+  type JSX,
   on,
   onMount,
   Show,
 } from 'solid-js';
 
 import { CANVAS_FACTOR, SCROLL_MULTIPLIER } from '../../services/main.machine.data';
+import type { NodeData } from '../../services/main.machine.typings';
 import { DragBounds } from './Bounds';
 import { EdgesBoard } from './EdgesBoard';
 import { useFlow } from './FlowChart.context';
+import type { FlowPanels } from './FlowChart.types';
 import { NodeComponent } from './NodeComponent';
+import { Panels } from './Panels';
+
+/** Properties for the {@linkcode NodesBoard} component. */
+type Props<D extends NodeData = NodeData> = {
+  /** Optional custom node component. */
+  component?: Component<D>;
+  /** Optional custom overlay panels. */
+  panels?: FlowPanels;
+};
 
 /**
  * Interactive board component containing the drag-drop viewport, zoom controls,
  * panning gestures, and rendered nodes/edges.
  *
+ * @template | {@linkcode NodeData} `D` - Custom node data dictionary type extending
+ *   {@linkcode NodeData}.
+ *
+ * @param props - Board component properties of type {@linkcode Props}.
+ *
  * @returns The rendered Solid component.
  *
  * @see {@linkcode DragBounds}, {@linkcode EdgesBoard}, {@linkcode NodeComponent}, {@linkcode useFlow}, {@linkcode CANVAS_FACTOR}, {@linkcode SCROLL_MULTIPLIER}
  */
-export const NodesBoard: Component = () => {
+export const NodesBoard = <D extends NodeData = NodeData>(
+  props: Props<D>,
+): JSX.Element => {
   let containerRef: HTMLDivElement;
   const [isPanning, setIsPanning] = createSignal(false);
   const [transform, setTransform] = createSignal({ x: 0, y: 0 });
-  const [id, setId] = createSignal<string | number>('');
   const [ref, setRef] = createSignal<HTMLDivElement | undefined>();
   let percentX = 0;
   let percentY = 0;
-
   const service = useFlow();
 
   const newEdge = createState(service, {
@@ -107,15 +124,6 @@ export const NodesBoard: Component = () => {
 
   const selectedId = createState(service, { selector: s => s.context?.selected });
 
-  /**
-   * Determines whether the given element ID matches the currently selected entity.
-   *
-   * @param id - The node or edge identifier to check.
-   *
-   * @returns `true` if the item is currently selected, otherwise `false`.
-   */
-  const selected = (id: string | number) => selectedId() === id;
-
   const nodeIds = createState(service, {
     selector: ({ context }) => {
       const list = toArray.typed(context.data?.nodes);
@@ -145,48 +153,42 @@ export const NodesBoard: Component = () => {
         }
       }}
 
-      class='relative mx-auto h-[calc(100vh-64px)] w-[calc(100vw-32px)] overflow-hidden'
+      class='relative mx-auto h-full w-full overflow-hidden'
     >
       <DragDropProvider
         onDragMove={({ draggable: { transform: _transform, node, id } }) => {
-          setId(id);
-          if (selected(id)) {
-            const grandParent = node.parentElement?.parentElement;
-            const currentZoom = zoom();
-            const minX = 0;
-            const maxX = grandParent
-              ? Math.max(0, grandParent.clientWidth / currentZoom - node.offsetWidth)
-              : Infinity;
-            const minY = 0;
-            const maxY = grandParent
-              ? Math.max(
-                  0,
-                  grandParent.clientHeight / currentZoom - node.offsetHeight,
-                )
-              : Infinity;
-
-            const targetX = node.offsetLeft + _transform.x / currentZoom;
-            const targetY = node.offsetTop + _transform.y / currentZoom;
-
-            const x = Math.min(Math.max(targetX, minX), maxX);
-            const y = Math.min(Math.max(targetY, minY), maxY);
-
-            const deltaX = x - node.offsetLeft;
-            const deltaY = y - node.offsetTop;
-
-            // Directly update the draggable node's CSS transform adjusted for zoom:
-            node.style.setProperty(
-              'transform',
-              `translate3d(${deltaX}px, ${deltaY}px, 0)`,
-            );
-
-            service.send({ type: 'MOVE_IMMEDIATE', payload: { id: `${id}`, x, y } });
-            setTransform({ x: deltaX * currentZoom, y: deltaY * currentZoom });
-          }
+          const grandParent = node.parentElement?.parentElement;
+          const currentZoom = zoom();
+          const minX = 0;
+          const maxX = grandParent
+            ? Math.max(0, grandParent.clientWidth / currentZoom - node.offsetWidth)
+            : Infinity;
+          const minY = 0;
+          const maxY = grandParent
+            ? Math.max(0, grandParent.clientHeight / currentZoom - node.offsetHeight)
+            : Infinity;
+
+          const targetX = node.offsetLeft + _transform.x / currentZoom;
+          const targetY = node.offsetTop + _transform.y / currentZoom;
+
+          const x = Math.min(Math.max(targetX, minX), maxX);
+          const y = Math.min(Math.max(targetY, minY), maxY);
+
+          const deltaX = x - node.offsetLeft;
+          const deltaY = y - node.offsetTop;
+
+          // Directly update the draggable node's CSS transform adjusted for zoom:
+          node.style.setProperty(
+            'transform',
+            `translate3d(${deltaX}px, ${deltaY}px, 0)`,
+          );
+
+          service.send({ type: 'MOVE_IMMEDIATE', payload: { id: `${id}`, x, y } });
+          setTransform({ x: deltaX * currentZoom, y: deltaY * currentZoom });
         }}
 
         onDragEnd={({ draggable: { node, id } }) => {
-          if (!selected(id)) return;
+          // if (!selected(id)) return;
 
           const grandParent = node.parentElement?.parentElement;
           const currentZoom = zoom();
@@ -219,7 +221,7 @@ export const NodesBoard: Component = () => {
             return (containerRef = el);
           }}
           onScroll={updateScrollPercentages}
-          class='relative h-full w-full overflow-auto rounded-lg border-2 border-gray-600'
+          class='relative h-full w-full overflow-auto'
         >
           <DragDropSensors />
           <div
@@ -227,11 +229,12 @@ export const NodesBoard: Component = () => {
             class='relative cursor-crosshair overflow-hidden'
             classList={{ 'cursor-grabbing': isPanning() }}
             style={{ height: cHeight(), width: cWidth() }}
-            onScroll={() => {}}
+            // onScroll={() => {}}
 
             onMouseDown={e => {
               if (newEdge() || e.button !== 0) return;
               service.send('DESELECT');
+              setIsPanning(true);
 
               // #region Props
               const startX = e.clientX;
@@ -240,8 +243,6 @@ export const NodesBoard: Component = () => {
               const startScrollTop = containerRef.scrollTop;
               // #endregion
 
-              setIsPanning(true);
-
               const handleMouseMove = (moveEvent: MouseEvent) => {
                 const dx = moveEvent.clientX - startX;
                 const dy = moveEvent.clientY - startY;
@@ -268,12 +269,16 @@ export const NodesBoard: Component = () => {
             >
               <DragBounds />
               <EdgesBoard />
-              <For each={nodeIds()}>{id => <NodeComponent id={id} />}</For>
+              <For each={nodeIds()}>
+                {id => <NodeComponent id={id} children={props.component} />}
+              </For>
             </div>
           </div>
         </div>
 
-        {/* Panel */}
+        <Panels {...props.panels} />
+
+        {/* Bottom-Right Panel (Main Zoom & Creation Controls) */}
         <div class='absolute right-4 bottom-4 z-50 flex items-center gap-2 rounded-xl border border-gray-200 bg-white/90 p-2 shadow-lg backdrop-blur-md'>
           <button
             type='button'
@@ -325,7 +330,7 @@ export const NodesBoard: Component = () => {
             </svg>
           </button>
         </div>
-        <Show when={!id() || !selected(id())}>
+        <Show when={!selectedId()}>
           <DragOverlay children='' />
         </Show>
       </DragDropProvider>