ContextQMD
Back to Tldraw

README

templates/workflow/README.md

5.2.14.9 KB
Original Source
<div alt style="text-align: center; transform: scale(.5);"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/tldraw/tldraw/main/assets/github-hero-dark.png" /> 
</picture>
</div>

This repo contains a starter-kit for making a workflow type application using tldraw.

Local development

Install dependencies with yarn or npm install.

Run the development server with yarn dev or npm run dev.

Open http://localhost:5173/ in your browser to see the app.

This starter kit has 3 main concepts:

  1. Nodes: Nodes are shapes that accept inputs, and produce outputs.
  2. Connections: A connection joins the output of one node to the input of another.
  3. Ports: Ports are places on nodes that connections can join to.

There are lots of useful interactions the user can take involving these concepts:

  • Clicking on an output port lets the user create a new node
  • Dragging from a port lets the user create a new connection
  • Dragging from an output port lets the user create a new node
  • Clicking in the middle of a port lets the user create a new node
  • Dragging a connection lets the user connect it to a different node, or disconnect it entirely

We also include a demonstration of how information might flow through a graph of nodes. Nodes update instantly to show their results. There's also a "play" button to show how execution in a real service that was making API calls might work.

File structure

  • src/App.tsx: The main entry-point of the app. This renders the <Tldraw /> component and brings in all the customizations the make this a workflow app.
  • src/nodes: Everything related to nodes
    • src/nodes/NodeShapeUtil.tsx: The node shape util, which defines a custom tldraw shape for our nodes.
    • src/nodes/nodePorts.tsx: Helpers for efficiently working with the ports on a node, and the values flowing through them.
    • src/nodes/types: Each different node type. We have nodes for basic math operations, setting number with a slider, and conditionals.
  • src/connection: Everything related to connections.
    • src/connection/ConnectionShapeUtil.tsx: The connection shape util, which defines a custom tldraw shape for our connections.
    • src/connection/ConnectionBindingUtil.tsx: The connection binding util. A binding is how tldraw models relationships between shapes. Each connection has two bindings - one to the start node, and one to the end node.
    • src/connection/insertNodeWithinConnection.tsx: A helper for inserting a new node in the middle of a connection.
    • src/connection/keepConnectionsAtBottom.tsx: A set of tldraw side effect listeners that make sure connection are below all other shapes in the z-order.
  • src/ports: Everything related to ports.
    • src/ports/Port.tsx: Defines the types for ports, and a React component for rendering them.
    • src/ports/PointingPort.tsx: An entry in tldraw's interaction state tree which extends the built-in select tool with custom behavior when interacting with ports.
  • src/execution: Everything related to async execution of workflow graphs
    • src/execution/ExecutionGraph.tsx: The execution graph, which runs workflows.
  • src/components: UI and on-canvas react components.
    • src/components/WorkflowToolbar.tsx: A replacement for tldraw's default toolbar. This one renders vertically down the left of the screen, and emphasizes our workflow tools.
    • src/components/OnCanvasComponentPicker.tsx: A panel that appears on the canvas that lets users choose a new node to insert. This is used with some of the on-canvas interactions described above.
    • src/components/WorkflowRegions.tsx: Finds sets of connected nodes that forms workflows, draws a box around them, and provides a "play" button for running the workflow.

License

This project is provided under the MIT license found here. The tldraw SDK is provided under the tldraw license.

Trademarks

Copyright (c) 2024-present tldraw Inc. The tldraw name and logo are trademarks of tldraw. Please see our trademark guidelines for info on acceptable usage.

Distributions

You can find tldraw on npm here.

Contribution

Found a bug? Please submit an issue.

Community

Have questions, comments or feedback? Join our discord. For the latest news and release notes, visit tldraw.dev.

Contact

Find us on Twitter/X at @tldraw.