ruclib-data-flow

A highly configurable component for creating interactive data flow diagrams and canvases. It allows users to visually represent relationships between different data entities, tables, or process steps, and connect them with customizable links.

Features

- Dynamic Canvas: Create a workspace where users can add, move, and arrange containers or nodes.
- Customizable Nodes: Define the appearance and behavior of nodes using a flexible HTML markup structure.
- Element Palette: Optionally display a palette of predefined elements that can be dragged onto the canvas.
- Interactive Connections: Draw different types of connection lines (e.g., Arrowed, Dotted, Plain) between nodes.
- In-place Editing: Double-click on nodes or table rows to edit attributes directly.
- Context Menus: Access a customizable action menu by double-clicking on a node.
- Grid Layout: Toggle between a free-form canvas and a structured grid view.
- Search Functionality: Search for specific content within tables on the canvas.
- Theming: Apply custom theme classes for tailored styling.

Installation Guide

$3

``bash
npm install @uxpractice/ruc-lib
`

$3

If you only need the DataFlow component:

For Angular 15:
`bash
npm install @ruc-lib/data-flow@3.2.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0
`

For Angular 16:
`bash
npm install @ruc-lib/data-flow@3.2.0 @angular/material@^16.0.0 @angular/cdk@^16.0.0
`

For Angular 17:
`bash
npm install @ruc-lib/data-flow@4.0.0 @angular/material@^17.0.0 @angular/cdk@^17.0.0
`

For Angular 18:
`bash
npm install @ruc-lib/data-flow@4.0.0 @angular/material@^18.0.0 @angular/cdk@^18.0.0
`

For Angular 19:
`bash
npm install @ruc-lib/data-flow@4.0.0 @angular/material@^19.0.0 @angular/cdk@^19.0.0
`

For Angular 20:
`bash
npm install @ruc-lib/data-flow@4.0.0
`

> Note: When installing in Angular 15-19 apps, you must specify the matching @angular/material and @angular/cdk versions to avoid peer dependency conflicts. Angular 20 will automatically use the correct versions.

$3

| Angular Version | Compatible Version | Installation Command |
|-----------------|--------------------|-------------------------------------------------------------------------------------------|
| 15.x.x | 3.2.0 | npm install @ruc-lib/data-flow@^3.2.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0 |
| 16.x.x | 3.2.0 | npm install @ruc-lib/data-flow@^3.2.0 @angular/material@^16.0.0 @angular/cdk@^16.0.0 |
| 17.x.x | 4.0.0 | npm install @ruc-lib/data-flow@^4.0.0 @angular/material@^17.0.0 @angular/cdk@^17.0.0 |
| 18.x.x | 4.0.0 | npm install @ruc-lib/data-flow@^4.0.0 @angular/material@^18.0.0 @angular/cdk@^18.0.0 |
| 19.x.x | 4.0.0 | npm install @ruc-lib/data-flow@^4.0.0 @angular/material@^19.0.0 @angular/cdk@^19.0.0 |
| 20.x.x | 4.0.0 | npm install @ruc-lib/data-flow@^4.0.0 |

Usage

$3

In your global styles.scss file, import the necessary CSS from jointjs and the component's own styles. The path may vary based on your project setup.

`scss
// Required for layout and diagramming
@import "jointjs/css/layout.css";

// For Complete Library
@import "@uxpractice/ruc-lib/data-flow/lib/data-flow.scss";

// For Individual Package
@import "@ruc-lib/data-flow/lib/data-flow.scss";
`

$3

In your Angular component file (e.g., app.component.ts), import the RuclibDataFlowComponent:

`typescript
import { Component } from '@angular/core';

// For Complete Library
import { RuclibDataFlowComponent } from '@uxpractice/ruc-lib/data-flow';

// For Individual Package
import { RuclibDataFlowComponent } from '@ruc-lib/data-flow';

@Component({
selector: 'app-root',
imports: [RuclibDataFlowComponent],
templateUrl: './app.component.html',
})
export class AppComponent {
// Component code here
}
`

$3

In your component's template, use the selector:

`html
[rucInputData]="dataFlowInput"
[customTheme]="customTheme"
(rucEvent)="handleDataFlowEvents($event)">

`

API Reference

$3

| Input | Type | Description |
|----------------|-----------------------|------------------------------------------------------|
| rucInputData | IRucDataFlow | The main configuration object for the data flow. |
| customTheme | string | An optional CSS class for custom theming. |

$3

| Output | Type | Description |
|------------|-------|--------------------------------------------------|
| ruc
| rucEvent | any | Emits events when changes occur in the data flow component (e.g., node added, link created). |

$3

This is the main configuration object for the Data Flow component.

| Property | Type | Description |
|-------------------------|-----------------|---------------------------------------------------------------------------------------------------------|
| title | string | The main title displayed for the data flow component. |
| defaultCellHeader | string | Default header text for new containers/tables added to the canvas. |
| line | ILine | Configuration object for the connection lines. See ILine table below. |
| drawGrid | boolean | If true, a grid pattern is drawn on the canvas background. Default is false. |
| showMenuOnDoubleClick | boolean | If true, a context menu appears when a node is double-clicked. Default is false. |
| fieldValues | object | An object containing default values for the dynamic fields defined in htmlMarkup. |
| htmlMarkup | IHTMLMarkup | A structured object that defines the HTML template for each node on the canvas. See IHTMLMarkup table. |
| hasElements | boolean | If true, displays a palette of predefined elements that can be dragged onto the canvas. Default is false. |
| elements | IElement[] | An array of element configurations for the palette. Used when hasElements is true. See IElement table. |
| attributes | IAttributes | An object to control global attributes of the nodes, like size. See IAttributes table below. |
| menuOptions | any[] | An array of options to display in the context menu. |

$3

| Property | Type | Description |
|----------|-------------|---------------------------------------------------------------------------------------------------------|
| type | ELineType | The style of the connection line. Can be ELineType.Plain, ELineType.Arrowed, ELineType.Dotted, etc. |

$3

| Property | Type | Description |
|--------------|----------|-------------------------------------------------------------------|
| icon | string | Path to the default icon for the element in the palette. |
| activeIcon | string | Path to the icon used when the element is active or selected. |
| title | string | The label displayed for the element in the palette. |

$3

| Property | Type | Description |
|-----------------------|----------|--------------------------------------------------------------------------|
| width | number | The width of the nodes on the canvas. |
| height | number | The height of the nodes on the canvas. |
| titleCharacterLimit | number | The maximum number of characters to display for a node's title. |

$3

This object defines the structure of a custom node.

| Property | Type | Description |
|-----------------|-----------------|--------------------------------------------------------------------------------|
| tagName | string | The HTML tag for the element (e.g., 'div', 'p', 'img'). |
| selector | string | A unique identifier for this part of the markup within the node. |
| groupSelector | string | Groups elements together. Used for applying fieldValues. |
| className | string | CSS class name(s) to apply to the element. |
| style | object | An object of CSS styles to apply to the element. |
| attributes | object | HTML attributes to apply (e.g., {'data-attribute': 'title'}). |
| textContent | string | The static text content for the element. |
| children | IHTMLMarkup[] | An array of child markup objects, allowing for nested structures. |

Example Configuration

Here's an example of how to configure the Data Flow component in your component's TypeScript file.

``typescript
import { Component } from '@angular/core';

// For Complete Library
import { IRucDataFlow, ELineType } from '@uxpractice/ruc-lib/data-flow';

// For Individual Package
// import { IRucDataFlow, ELineType } from '@ruc-lib/data-flow';

@Component({
selector: 'app-root',
templateUrl: './app.component.html',
})
export class AppComponent {
customTheme = 'ruc-dark-theme';

dataFlowInput: IRucDataFlow = {
title: 'Data Flow Pipeline',
defaultCellHeader: 'New Step',
line: {
type: ELineType.Arrowed,
},
drawGrid: true,
showMenuOnDoubleClick: true,
hasElements: true,
attributes: {
width: 65,
height: 65,
titleCharacterLimit: 12,
},
fieldValues: {
icon: '../assets/pipeline/generic.png',
title: 'Generic',
isMenuOpen: 'false',
activeIcon: '../assets/pipeline/active/generic.png',
},
elements: [
{
icon: '../assets/pipeline/migration.png',
activeIcon: '../assets/pipeline/active/migration.png',
title: 'Migration',
},
{
icon: '../assets/pipeline/validation.png',
activeIcon: '../assets/pipeline/active/validation.png',
title: 'Validation',
},
// ... more elements
],
htmlMarkup: {
tagName: 'div',
selector: 'htmlRoot',
className: 'canvas__element',
children: [
{
tagName: 'div',
className: 'canvas__element--icon',
selector: 'iconWrapper',
children: [
{
tagName: 'img',
groupSelector: 'field',
attributes: { 'data-attribute': 'icon' },
},
],
},
{
tagName: 'p',
className: 'canvas__element--title',
groupSelector: 'field',
textContent: 'Node',
attributes: { 'data-attribute': 'title' },
},
],
},
menuOptions: [
{ label: 'Properties', action: 'properties' },
{ label: 'Delete', action: 'delete' }
],
};

handleDataFlowEvents(event: any) {
console.log('Data Flow Event:', event);
// Example: if(event.type === 'delete') { ... }
}
}
`

> ⚠️ IMPORTANT: Custom Theme Usage in Angular Material

When implementing custom themes, such as:

`scss
.custom-theme-1 {
@include angular-material-theme($custom-theme);
}

// You must also include the typography mixin to ensure text styles are applied correctly as shown below:
.custom-theme-1 {
@include angular-material-theme($custom-theme);
@include mat.typography-level($theme-custom-typography-name, body-1);
}
``

Contribution

Contributions are welcome! Feel free to open issues or pull requests for any enhancements or fixes.

Acknowledgements

Thank you for choosing the Data Flow Component Library. If you have any feedback or suggestions, please let us know!