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

Install the Entire Library

npm install @uxpractice/ruc-lib

Install Individual Component

If you only need the DataFlow component:

For Angular 15:

npm install @ruc-lib/[email protected] @angular/material@^15.0.0 @angular/cdk@^15.0.0

For Angular 16:

npm install @ruc-lib/[email protected] @angular/material@^16.0.0 @angular/cdk@^16.0.0

For Angular 17:

npm install @ruc-lib/[email protected] @angular/material@^17.0.0 @angular/cdk@^17.0.0

For Angular 18:

npm install @ruc-lib/[email protected] @angular/material@^18.0.0 @angular/cdk@^18.0.0

For Angular 19:

npm install @ruc-lib/[email protected] @angular/material@^19.0.0 @angular/cdk@^19.0.0

For Angular 20:

npm install @ruc-lib/[email protected]

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.

📦 Version Compatibility

| 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

1. Import Styles

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.

// 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";

2. Import the Component

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

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. Use the Component

In your component's template, use the <uxp-ruclib-data-flow> selector:

<uxp-ruclib-data-flow
    [rucInputData]="dataFlowInput"
    [customTheme]="customTheme"
    (rucEvent)="handleDataFlowEvents($event)">
</uxp-ruclib-data-flow>

API Reference

Component Inputs

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

Component Outputs

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

rucInputData (IRucDataFlow)

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. |

ILine

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

IElement

| 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. |

IAttributes

| 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. |

IHTMLMarkup

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.

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:

.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!