/Svelvet

🎛 A Svelte library for building dynamic, infinitely customizable node-based user interfaces and flowcharts

Primary LanguageSvelte

banner

MIT License NPM Downloads GitHub Stars GitHub Forks NPM Version

Infinitely Customizable Node-Based User Interfaces with Svelvet!

Svelvet is a lightweight Svelte component library for building interactive node-based user interfaces and diagrams.

⚡ Getting Started | 📚 Documentation | ⌨️ Blog | 💬 Twitter | 💼 LinkedIn

Version Updates

Shout out to our contributors! Here's what's new:

Changelog

v7.0.0
  • Changed primary API. Developers now pass Node and other exposed components directly as children to Svelvet
  • Added the ability to specify Anchors as inputs, outputs or any, enabling connection logic and "directionality" of Edge curvature
  • Added the ability to dynamically attach/reattach Edges
  • All new Anchor component that developers can add anywhere within custom nodes. Can be wrapped around custom anchor elements or customized via props
  • All new Edge component for developer customization
  • All new Node component for developer customization
  • Added ability to rotate nodes via the top left corner
  • All new Resizer component used when composing custom nodes
  • Improved reliability and DX around Edge click events
  • Node connections can be specified at the Node or Anchor level. Improved flexibility of input options
  • Improved consistency of touch events on mobile devices. Added touch support for controls component
  • Nodes and Edges no longer require specified IDs. Defaults to incrementing value
  • Added Controls component with zoom, reset, lock and unhide functionality plus the ability to pass custom control buttons as children
  • Added the ability to specify an arbitrary number of Anchors on default nodes
  • Added z-index stacking logic when interacting with Nodes
  • Improved step path algorithm, which now connects Anchors regardless of their position. Exposed corner radius as prop
  • Added keyboard navigation to canvas when focused
  • Added selection box functionality via Shift + Click. Color can be controlled via the selectionColor prop on the Svelvet component.
  • Added node grouping functionality via Shift + CMD + Click
  • Added the ability to pass custom edges at the Graph, Node and Anchor level
  • No longer required to pass width/height to Svelvet component. Will fill wrapping container by default
  • Added the ability to specify canvas/node direction as top-down TD or left-right LR. Controls placement of input/output anchors on default nodes
  • All new Minimap component that accepts props for placement, dimensions and styling the background and nodes (defaults to node color) and features dramatically improved tracking/visualization plus the ability to hide nodes
  • All new Theme Toggle component that can toggle between a main and alt theme
  • Enabled two way data binding for some parameters when creating default Nodes
  • All new Background component allowing customization of grid size and color
  • Exposed custom events on the Node component for on:nodeClicked, on:connection and on:disconnection that developers can listen for when implementing custom nodes
  • Added theme prop to Svelvet component. Defaults to light. Accepts parameters like "dark", "purple", "parchment"
  • Removed frontend website code from library repository
  • Added E2E tests using Playwright
  • Simplified bezier curve logic and added the ability to specify anchor "direction"
  • Added ability to parse Mermaid strings into node graphs + edges
  • Added a series of accessible input components (Slider, RadioGroup, TextField, ColorWheel) that can be composed in custom nodes and are linked with our data flow system
  • Library now features 100% TypeScript coverage and fully exported types
  • Removed D3-zoom dependency
  • Removed redundant window and event listeners
  • Added dynamic data flow/state management system that tracks Anchor connections
  • Updated home page to include newest collaborators
  • Temporarily removed dynamic anchor logic due to library re-write. May re-add
  • Made progress on restoring graph state from local storage. Coming soon!
v6.0.0
  • Added adaptive anchors. Anchors now automatically arrange themselves in an aesthetically pleasing way without user input. Adaptive anchors are now the default anchor mode.
  • Added dynamic anchors. Anchors now automatically shift position when nodes are moved to preserve aesthetics.
  • Added custom positioning of anchors. Users are able to specify custom positions of anchors using callbacks
  • Added accessibiilty features for edges. Edges now highlight on hover to make edge interactions easier.
  • Added functionality to resize nodes by dragging their bottom-right corner
  • Added custom classes for edges to allow for uniform styling
  • Added click event for edges that execute a user-defined callback
  • Added functionality to edit edges by right-clicking on a node to bring up a modal
  • Added feature to expand and collapse tree nodes.
  • Updated documentation page on website to include new features
  • Updated home page to include newest collaborators
  • Solved github issue #s:
v5.0.0
  • Now compatible with Safari (5.0.7 update)
  • Added interactive node linking & creation
  • Added ability to load custom Svelte components as nodes
  • Added an optional minimap that allows you to visualize larger diagrams
  • Added progammatic initial zoom and location
  • Added custom classes for nodes to allow for uniform styling
  • Added a feature that allows you to export and import diagrams
  • Added an optional boundary to the diagram
  • Added functionality to edit nodes by right-clicking on a node to bring up a modal
  • Added an optional feature that allows users to delete nodes
  • NOTE: Please make sure to give nodes and edges unique IDs to prevent forEach key duplicate error!
  • Solved github issue #s: 65, 78, 80, 81, 85, 86, 104, 105, 146, 147, 148, 151, 153, 158
  • Updated documentation page on website to include new features
  • Updated home page to include newest collaborators
v4.0.0
  • Added ability to include HTML in inside of nodes (i.e. videos, sounds, etc)
  • Added NPM Package folder in root directory of GitHub repo
  • this folder is used for adding changes to library & pushing updates to NPM; included here to have version control through GitHub
  • Added snap-to-grid functionality for use during runtime in the canvas (GitHub Issue 107)
  • Corrected issue where nodes become magnetized when moved outside of the visible canvas boundaries (GitHub Issues 120 & 125)
  • Removed unused dotenv & node.env dependency from NPM Package package.json (GitHub Issue 118)
  • Moved all dependancies in devDependancies to regular dependancies object, except for d3-zoom which is used by the client during runtime
  • Added group nodes functionality
  • Updated main website page to include newest set of collaborators
  • Added CSS option for canvas background
  • Added documentation for HTML in nodes, snap-to-grid, canvas background coloring, and node grouping to website documents
  • General refactoring throughout application to improve responsiveness and decrease size
  • Created documentation to assist future developers in understanding the flow of data in Svelvet and provide list of potential updates/upgrades
v3.0.0
  • Added right-click context menu functionality on REPL playground page
  • Added capability to add custom nodes and edges via context menu
  • Added custom node/edge shortcuts for optimized user experience
  • Incorporated dynamic addition of custom node/edge via predictive algorithm
  • Added ability to copy text from code editor
  • Node diagrams now have the option to be fixed in place
  • Added tutorial overlay for REPL playground page
  • Added ability to access quick view documentation via popup modal
  • Updated documentation to allow easier contributor access('.env' file setup)
  • Updated Community link on website to redirect to Svelvet thread on Stackoverflow
  • Implemented skeleton codebase for a Community Forum with full database/route accessibility(for future contributors)
v2.0.2
  • Added left and right anchor points
  • Added step and smoothstep edge types
  • Incorporated mixed edge functionality
  • Refactored how edge text and labels render for every edge
  • Fixed D3Zoom bias bug
  • Expanded styling options, including label color, label background, and edge color
  • Nodes are now able to contain images and will render differently based on the presence of label text
  • Nodes are now draggable on touch screens and reposition themselves to center on your touch
  • Implemented data reactivity
  • Expanded TypeScripting
  • Added E2E testing using Cypress
  • Expanded unit tests
  • Added a REPL to our documentation site
  • Added SQL database to our REPL
  • Added GitHub OAuth to enable users to save their custom diagrams created in our new REPL
  • Expanded documentation for new features
  • Added full CI/CD pipeline
v1.0.3
  • Fixed bug with running tests
  • Added ability to render multiple unique Svelvet components
  • Added a 'clickCallback' customization option for nodes
v1.0.2
  • Fixed bug with importing types for TypeScript applications
  • Added a 'borderRadius' customization option for nodes
  • Fixed SVG zoom/pan bug (zoom/pan is now limited to Svelvet component only)

Key Features

  • Easy to use: To get started with Svelvet, all you need is data for nodes and edges. Visit our documentation website for streamlined, user-friendly tutorials and examples on how to get the most out of your Svelvet interfaces!
  • Interactive: Elegant and smooth interface when selecting a node to drag it across the graph.
  • Customizable: Fully customizable Edges, Nodes, Backgrounds and components
  • Reliable: Svelvet is written in TypeScript and tested with Vitest, Playwright and Svelte Testing Library. Svelvet is maintained by motivated engineers seeking to contribute to the larger Svelte developer community and library ecosystem.
  • Room to Grow: There is so much we can do to improve, add features and make Svelvet the best version of itself - we welcome feedback and contributions! Scroll below for suggestions on what to contribute.

Installation

Svelvet is available as both an npm and a yarn package. You can install it by running one of the two commands:

npm install svelvet
yarn add svelvet

Quick Start

Start by importing the Svelvet and Node components into your application:

import { Svelvet, Node, Anchor, Edge } from 'svelvet';

A Svelvet canvas primarily consists of Nodes. You can pass any number of Nodes as children to the Svelvet wrapper. You can use all the standard conditional rendering syntax to populate nodes within the Svelvet component. Basic parameters like color, input and output count, label and more can be specified and feature two-way data binding with passed props. For greater customization, wrap your own custom components in our Node component and pass the whole thing to Svelvet.

Nodes, Edges and Anchors all feature click events, properties and functions to allow developers to fully customize the state of their graphs.

When creating custom Nodes, you can position any number of our Anchor components to enable dynamic connections. You can also wrap Nodes in a Group component to limit their boundaries and move them as one. These groups can be created dynamically by Shift + Click and dragging.

Finally, you can render our Controls, Minimap, Background and Theme Toggle components via props or named slots. In the latter use case, you can pass props to further customize them. The Controls component can wrap your own set of buttons as we expose the zoom/reset/lock actions using a let directive.

Svelvet is focused on dynamic edge connections, but if you'd like to specify edges ahead of time, you can pass an array of connections to any Anchor component. You can also pass a custom Edge component!

For more detailed use cases and examples, please visit svelvet.io.

<Svelvet width={500} height={500} theme="dark" initialZoom={0.6} minimap>
	<Node />
	<Node label="Demo Node" TD />
	<Node id="node-id" inputs={2} />
	<Node bgColor="red" inputs={10} outputs={5} height={200} position={{ x: 100, y: 100 }} />
	<Controls slot="controls" horizontal />
</Svelvet>

Visit our website to learn more!

Testing

Testing is done with Playwright and the Svelte Testing Library. You can find tests in the /tests folder. We plan on dramatically expanding test coverage very soon. In order to run the tests use the command:

For End-to-End testing

npx playwright test

The Svelvet Team

How to Contribute

Read src/lib/doc/README.md for suggestions on how to get started!

The following is a list of features and improvements by ourselves and the larger Svelte community for any open source developer to contribute. If you have any additional ideas, feel free to raise the issue or implement them as well!

  • Premade node menu with drag & drop abilities
  • Add documentation/video tutorial on how to set up a Svelvet demo
  • Custom error handling
  • Increase test coverage for scalability
  • Checkout the Roadmap for a current list of active projects
  • GET CREATIVE!! Svelvet is an amazing project that has so much room to grow.

Credits

Inspired by React Flow, Svelvet expands the tools available to Svelte developers and makes Svelte more inviting to both new and seasoned software engineers.

License

Svelvet is developed under the MIT license.