Workflow Canvas Component

A flexible and interactive workflow canvas component for ClojureScript applications, built with re-frame. This component allows you to create, connect, and manipulate nodes in a workflow-style interface.

Features

• Draggable nodes with customizable content
• Interactive edge connections with multiple styles
• Zoom controls
• Configurable grid background
• Edge styling options (bezier, straight, manhattan, etc.)
• Node connection management
• Responsive layout

Installation

Add the workflow canvas component to your ClojureScript project:

[workflow-canvas "0.1.0"]  ; Replace with actual version

Basic Usage

(ns your-app.core
  (:require [workflow.components.workflow-canvas :refer [workflow-canvas]]))

(defn your-component []
  [workflow-canvas {:nodes [{:id 1 :x 100 :y 100 :type :default :config {:label "Node 1"}}
                           {:id 2 :x 300 :y 200 :type :default :config {:label "Node 2"}}]
                   :edges [{:from 1 :to 2 :key "1-2"}]
                   :grid-size 20
                   :grid-color "#eee"
                   :zoom-controls true}])

Component Properties

Property	Type	Description	Default
:nodes	Vector	Collection of node objects	[]
:edges	Vector	Collection of edge objects	[]
:floating-edge	Map	Current floating edge state	nil
:on-node-move	Function	Callback for node movement (fn [id dx dy])	nil
:on-edge-create	Function	Callback for edge creation (fn [from-id to-id])	nil
:on-edge-delete	Function	Callback for edge deletion (fn [edge-key])	nil
:grid-size	Number	Size of grid squares in pixels	20
:grid-color	String	Color of grid lines	"#aaa"
:zoom-controls	Boolean	Show zoom controls	false

Node Structure

Nodes are maps with the following structure:

{:id 1                    ; Unique identifier
 :x 100                  ; X position
 :y 100                  ; Y position
 :type :default          ; Node type
 :config {:label "Node"} ; Configuration map
}

Edge Structure

Edges are maps with the following structure:

{:from 1              ; Source node ID
 :to 2               ; Target node ID
 :key "1-2"          ; Unique edge identifier
}

Customizing Node Content

You can customize the appearance of nodes by providing your own node content component:

(defn custom-node-content [{:keys [type config]}]
  [:div.custom-node
   {:style {:padding "15px"
            :background "#f8f9fa"
            :border-radius "8px"}}
   [:h3 (:label config)]
   [:div.node-type type]])

;; Use in workflow canvas
[workflow-canvas {:nodes nodes
                 :edges edges
                 :node-content custom-node-content}]

Edge Styles

The canvas supports multiple edge styles:

• :bezier - Curved Bezier lines
• :straight - Direct straight lines
• :manhattan - Right-angled lines
• :vertical - Vertical-first routing
• :horizontal - Horizontal-first routing

Configure edge styles through the edge settings:

{:style :bezier
 :color "#000000"
 :thickness 2
 :pattern :solid  ; :solid, :dashed, or :dotted
 :arrow :standard ; :none, :standard, :reverse, or :both
}

Event Handlers

The component dispatches several re-frame events that you can handle:

• :start-floating-edge - When starting a new edge connection
• :update-floating-edge - When dragging a floating edge
• :finalize-edge - When completing an edge connection
• :delete-edge - When deleting an edge
• :move-node - When moving a node
• :update-edge-style - When updating edge styles

Example Usage with Event Handlers

(ns your-app.views
  (:require [re-frame.core :as rf]
            [workflow.components.workflow-canvas :refer [workflow-canvas]]))

(rf/reg-event-db
 :on-node-move
 (fn [db [_ id dx dy]]
   ;; Handle node movement
   ))

(rf/reg-event-db
 :on-edge-create
 (fn [db [_ from-id to-id]]
   ;; Handle edge creation
   ))

(defn main-panel []
  [workflow-canvas
   {:nodes @(rf/subscribe [:nodes])
    :edges @(rf/subscribe [:edges])
    :on-node-move #(rf/dispatch [:on-node-move %1 %2 %3])
    :on-edge-create #(rf/dispatch [:on-edge-create %1 %2])
    :on-edge-delete #(rf/dispatch [:delete-edge %])
    :grid-size 20
    :zoom-controls true}])

Styling

The component uses CSS classes that you can override for custom styling:

.workflow-canvas {
  /* Canvas container */
}

.workflow-node {
  /* Node styling */
}

.node-content {
  /* Default node content */
}

.zoom-controls {
  /* Zoom controls styling */
}

License

GNU Lesser General Public License v3.0 (LGPL-3.0)

This component is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0).

What you can do:

• Use the component in commercial applications
• Modify the component's source code
• Integrate the component into your own software, which can be licensed under different terms
• Distribute copies of the component
• Distribute your modifications to the component

What you must do:

• Include a copy of the full license text and copyright notice
• State changes made to the component
• Make available the source code of the component when you distribute it
• License any modifications to the component itself under LGPL-3.0
• Include installation instructions

What you don't have to do:

• Make your entire application open source
• License your application under LGPL
• Provide source code for your application that uses the component

Full License Text

                   GNU LESSER GENERAL PUBLIC LICENSE
                       Version 3, 29 June 2007

 Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.

  This version of the GNU Lesser General Public License incorporates
the terms and conditions of version 3 of the GNU General Public
License, supplemented by the additional permissions listed below.

  0. Additional Definitions.

  As used herein, "this License" refers to version 3 of the GNU Lesser
General Public License, and the "GNU GPL" refers to version 3 of the GNU
General Public License.

  "The Library" refers to a covered work governed by this License,
other than an Application or a Combined Work as defined below.

  An "Application" is any work that makes use of an interface provided
by the Library, but which is not otherwise based on the Library.
Defining a subclass of a class defined by the Library is deemed a mode
of using an interface provided by the Library.

  A "Combined Work" is a work produced by combining or linking an
Application with the Library. The particular version of the Library
with which the Combined Work was made is also called the "Linked
Version".

Disclaimer

This is a brief summary of the LGPL-3.0 license. For the full terms and conditions, see the GNU Lesser General Public License v3.0.

Contributing

Contributions to this component are welcome! By contributing, you agree that your contributions will be licensed under the LGPL-3.0 license.

To contribute:

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

Please make sure to update tests as appropriate and adhere to the existing coding style.

---

Copyright (C) 2025 Matt Fitzgerald

This component is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This component is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this component. If not, see https://www.gnu.org/licenses/.