npm package: @ruc-lib/data-flow
Description: 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.
Latest version: 4.0.0

# 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
```bash
npm install @uxpractice/ruc-lib
```

### Install Individual Component

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.

### 📦 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.

```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";
```

### 2. Import the Component
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. Use the Component
In your component's template, use the `<uxp-ruclib-data-flow>` selector:

```html
<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.

```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!