@redvars/peacock 3.5.1 → 3.6.0

package/src/flow-designer/DEMO.md

@@ -0,0 +1,239 @@
+# Flow Designer Component Demo
+
+## Basic Usage
+
+```html
+<wc-flow-designer id="designer"></wc-flow-designer>
+
+<script type="module">
+  import { FlowDesigner, Workflow } from '@redvars/peacock';
+
+  // Define a workflow
+  const workflow = {
+    workflow_id: 'demo_workflow',
+    nodes: {
+      id: 'start',
+      type: 'trigger',
+      label: 'Start Process',
+      children: [
+        {
+          id: 'validate',
+          type: 'decision',
+          label: 'Data Valid?',
+          branches: {
+            yes: [
+              {
+                id: 'process',
+                type: 'action',
+                label: 'Process Data',
+              }
+            ],
+            no: [
+              {
+                id: 'error',
+                type: 'action',
+                label: 'Log Error',
+              }
+            ]
+          }
+        }
+      ]
+    }
+  };
+
+  // Set workflow on component
+  const designer = document.getElementById('designer');
+  designer.workflow = workflow;
+
+  // Listen for changes
+  designer.addEventListener('workflow-changed', (e) => {
+    console.log('Workflow changed:', e.detail.type);
+    console.log('Updated workflow:', e.detail.workflow);
+  });
+
+  // Add a new node
+  const newNode = {
+    id: 'new_action',
+    type: 'action',
+    label: 'New Action'
+  };
+  designer.addNode(newNode, 'start');
+
+  // Undo/Redo
+  if (designer.canUndo()) {
+    designer.undo();
+  }
+
+  if (designer.canRedo()) {
+    designer.redo();
+  }
+
+  // Validate
+  designer.validate();
+
+  // Export
+  const json = designer.exportWorkflow();
+</script>
+```
+
+## Customizing Node Templates
+
+```html
+<wc-flow-designer id="designer">
+  <!-- Custom trigger node template -->
+  <div slot="trigger-header" style="color: green; font-weight: bold;">
+    🚀 Custom Trigger
+  </div>
+
+  <!-- Custom action node template -->
+  <div slot="action-header" style="color: blue;">
+    ⚙️ Custom Action
+  </div>
+  <p slot="action-body">Custom action content here</p>
+
+  <!-- Custom decision template -->
+  <div slot="decision-header" style="color: orange;">
+    ❓ Custom Decision
+  </div>
+</wc-flow-designer>
+```
+
+## Workflow Structure
+
+The component supports complex workflows:
+
+```javascript
+{
+  workflow_id: 'complex_workflow',
+  nodes: {
+    id: 'trigger_1',
+    type: 'trigger',
+    label: 'Input Received',
+    
+    // Sequential flow
+    children: [
+      {
+        id: 'loop_1',
+        type: 'loop_start',
+        label: 'Begin Loop',
+        
+        children: [
+          {
+            id: 'decision_1',
+            type: 'decision',
+            label: 'Check Condition',
+            
+            // Conditional branching
+            branches: {
+              yes: [
+                {
+                  id: 'fork_1',
+                  type: 'fork',
+                  label: 'Parallel Tasks',
+                  
+                  // Parallel execution
+                  tasks: [
+                    { id: 'task_1', type: 'action', label: 'Task A' },
+                    { id: 'task_2', type: 'action', label: 'Task B' }
+                  ],
+                  
+                  // Join point
+                  join: {
+                    id: 'join_1',
+                    type: 'join',
+                    label: 'Merge',
+                    children: [
+                      {
+                        id: 'loop_end_1',
+                        type: 'loop_end',
+                        label: 'Loop Back',
+                        target_id: 'loop_1'
+                      }
+                    ]
+                  }
+                }
+              ],
+              no: [
+                { id: 'skip', type: 'action', label: 'Skip' }
+              ]
+            }
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Available Node Types
+
+- **trigger** - Start of workflow
+- **action** - Perform an action
+- **decision** - Branch on condition (yes/no)
+- **loop_start** - Begin loop
+- **loop_end** - End loop (loop_start target)
+- **fork** - Parallel execution start
+- **join** - Parallel execution end
+
+## Events
+
+- `workflow-changed` - Emitted when workflow is modified
+- `node-selected` - Emitted when node is clicked
+- `node-edited` - Emitted when node is edited
+- `node-deleted` - Emitted when node is deleted
+- `validation-result` - Emitted when validate() is called
+
+## Properties
+
+- `workflow: Workflow` - Current workflow definition
+- `readonly: boolean` - Read-only mode (default: false)
+- `disabled: boolean` - Disabled state (default: false)
+- `showValidation: boolean` - Show validation errors (default: false)
+
+## Methods
+
+- `addNode(node, parentId, connectionType?, branchKey?)` - Add node
+- `deleteNode(nodeId)` - Delete node
+- `editNode(nodeId, updates)` - Edit node
+- `moveNode(nodeId, newParentId, newIndex, connectionType?, branchKey?)` - Move node
+- `undo()` - Undo last operation
+- `redo()` - Redo last undone operation
+- `canUndo()` - Check if undo available
+- `canRedo()` - Check if redo available
+- `validate()` - Validate workflow
+- `exportWorkflow()` - Export as JSON
+
+## Validation
+
+The component automatically validates workflows after each change:
+
+- ✅ Detects circular loops
+- ✅ Detects orphaned nodes
+- ✅ Validates decision branches (yes/no)
+- ✅ Validates fork/join pairs
+- ✅ Validates loop targets
+
+Invalid workflows will prompt user confirmation before accepting changes.
+
+## Styling
+
+Custom CSS properties available:
+
+```css
+wc-flow-designer {
+  --flow-designer-height: 600px;
+  --flow-designer-border-color: var(--color-outline-variant);
+  --flow-designer-background: var(--color-surface);
+  --flow-designer-border-radius: var(--shape-corner-medium);
+  --flow-designer-action-bar-bg: var(--color-surface-container);
+}
+```
+
+## Keyboard Shortcuts
+
+- **Ctrl+Z** / **Cmd+Z** - Undo
+- **Ctrl+Y** / **Cmd+Y** - Redo
+- **Delete** - Delete selected node
+- **Enter** / **Space** - Select/activate node
+- **Click + Drag** - Pan canvas
+- **Scroll** - Zoom in/out (via toolbar)

package/src/flow-designer/commands.ts

@@ -0,0 +1,278 @@
+import type { Workflow, WorkflowNode, WorkflowCommand } from './types.js';
+import {
+  findNodeById,
+  cloneWorkflow,
+  removeNodeById,
+  insertNodeIntoWorkflow,
+} from './workflow-utils.js';
+
+/**
+ * Add Node Command
+ */
+export class AddNodeCommand implements WorkflowCommand {
+  description = 'Add node';
+
+  constructor(
+    private nodeToAdd: WorkflowNode,
+    private parentNodeId: string,
+    private connectionType: 'child' | 'branch' | 'task' = 'child',
+    private branchKey?: string
+  ) {}
+
+  execute(workflow: Workflow): Workflow {
+    const result = cloneWorkflow(workflow);
+    const parent = findNodeById(result.nodes, this.parentNodeId);
+    if (!parent) return workflow; // Validation in parent component
+
+    insertNodeIntoWorkflow(parent, this.nodeToAdd, this.connectionType, this.branchKey);
+    return result;
+  }
+
+  undo(workflow: Workflow): Workflow {
+    const result = cloneWorkflow(workflow);
+    removeNodeById(result.nodes, this.nodeToAdd.id);
+    return result;
+  }
+}
+
+/**
+ * Delete Node Command
+ */
+export class DeleteNodeCommand implements WorkflowCommand {
+  description = 'Delete node';
+  private deletedNode: WorkflowNode | null = null;
+  private parentReference: {
+    parentId: string;
+    connectionType: 'child' | 'branch' | 'task';
+    branchKey?: string;
+  } | null = null;
+
+  constructor(
+    private nodeId: string,
+    workflow?: Workflow
+  ) {
+    if (workflow) {
+      this.captureNodeContext(workflow);
+    }
+  }
+
+  private captureNodeContext(workflow: Workflow) {
+    const node = findNodeById(workflow.nodes, this.nodeId);
+    if (!node) return;
+    this.deletedNode = cloneWorkflow({ workflow_id: '', nodes: node }).nodes;
+
+    // Find parent reference
+    this.findParentReference(workflow.nodes);
+  }
+
+  private findParentReference(node: WorkflowNode) {
+    if (node.children) {
+      const idx = node.children.findIndex((n) => n.id === this.nodeId);
+      if (idx !== -1) {
+        this.parentReference = {
+          parentId: node.id,
+          connectionType: 'child',
+        };
+        return;
+      }
+      for (const child of node.children) {
+        this.findParentReference(child);
+      }
+    }
+
+    if (node.tasks) {
+      const idx = node.tasks.findIndex((n) => n.id === this.nodeId);
+      if (idx !== -1) {
+        this.parentReference = {
+          parentId: node.id,
+          connectionType: 'task',
+        };
+        return;
+      }
+      for (const task of node.tasks) {
+        this.findParentReference(task);
+      }
+    }
+
+    if (node.branches) {
+      for (const [branchKey, branchNodes] of Object.entries(node.branches)) {
+        const idx = branchNodes.findIndex((n) => n.id === this.nodeId);
+        if (idx !== -1) {
+          this.parentReference = {
+            parentId: node.id,
+            connectionType: 'branch',
+            branchKey,
+          };
+          return;
+        }
+        for (const branchNode of branchNodes) {
+          this.findParentReference(branchNode);
+        }
+      }
+    }
+  }
+
+  execute(workflow: Workflow): Workflow {
+    const result = cloneWorkflow(workflow);
+    removeNodeById(result.nodes, this.nodeId);
+    return result;
+  }
+
+  undo(workflow: Workflow): Workflow {
+    if (!this.deletedNode || !this.parentReference) return workflow;
+    const result = cloneWorkflow(workflow);
+    const parent = findNodeById(result.nodes, this.parentReference.parentId);
+    if (!parent) return workflow;
+
+    insertNodeIntoWorkflow(
+      parent,
+      this.deletedNode,
+      this.parentReference.connectionType,
+      this.parentReference.branchKey
+    );
+    return result;
+  }
+}
+
+/**
+ * Edit Node Command
+ */
+export class EditNodeCommand implements WorkflowCommand {
+  description = 'Edit node';
+  private previousState: Record<string, any> = {};
+
+  constructor(
+    private nodeId: string,
+    private updates: Partial<WorkflowNode>,
+    workflow?: Workflow
+  ) {
+    if (workflow) {
+      const node = findNodeById(workflow.nodes, nodeId);
+      if (node) {
+        // Store only edited fields
+        Object.keys(updates).forEach((key) => {
+          this.previousState[key] = (node as Record<string, any>)[key];
+        });
+      }
+    }
+  }
+
+  execute(workflow: Workflow): Workflow {
+    const result = cloneWorkflow(workflow);
+    const node = findNodeById(result.nodes, this.nodeId);
+    if (!node) return workflow;
+
+    Object.assign(node, this.updates);
+    return result;
+  }
+
+  undo(workflow: Workflow): Workflow {
+    const result = cloneWorkflow(workflow);
+    const node = findNodeById(result.nodes, this.nodeId);
+    if (!node) return workflow;
+
+    Object.assign(node, this.previousState);
+    return result;
+  }
+}
+
+/**
+ * Move Node Command - reorder in array or change parent
+ */
+export class MoveNodeCommand implements WorkflowCommand {
+  description = 'Move node';
+  private previousState: {
+    parentId: string;
+    index: number;
+    connectionType: 'child' | 'branch' | 'task';
+    branchKey?: string;
+  } | null = null;
+
+  constructor(
+    private nodeId: string,
+    private newParentId: string,
+    private newIndex: number,
+    private newConnectionType: 'child' | 'branch' | 'task' = 'child',
+    private newBranchKey?: string,
+    workflow?: Workflow
+  ) {
+    if (workflow) {
+      this.captureCurrentPosition(workflow);
+    }
+  }
+
+  private captureCurrentPosition(workflow: Workflow) {
+    // Store current parent/position for undo
+    // Implementation depends on finding current parent location
+  }
+
+  execute(workflow: Workflow): Workflow {
+    // Remove from old parent, insert at new parent
+    let result = cloneWorkflow(workflow);
+    result.nodes = removeNodeById(result.nodes, this.nodeId);
+    const newParent = findNodeById(result.nodes, this.newParentId);
+    if (!newParent) return workflow;
+
+    const node = findNodeById(workflow.nodes, this.nodeId);
+    if (!node) return workflow;
+
+    insertNodeIntoWorkflow(
+      newParent,
+      node,
+      this.newConnectionType,
+      this.newBranchKey
+    );
+    return result;
+  }
+
+  undo(workflow: Workflow): Workflow {
+    // Restore to previous position
+    if (!this.previousState) return workflow;
+    let result = cloneWorkflow(workflow);
+    result.nodes = removeNodeById(result.nodes, this.nodeId);
+    const prevParent = findNodeById(result.nodes, this.previousState.parentId);
+    if (!prevParent) return workflow;
+
+    const node = findNodeById(workflow.nodes, this.nodeId);
+    if (!node) return workflow;
+
+    insertNodeIntoWorkflow(
+      prevParent,
+      node,
+      this.previousState.connectionType,
+      this.previousState.branchKey
+    );
+    return result;
+  }
+}
+
+/**
+ * Batch Command - combine multiple commands into one undo/redo step
+ */
+export class BatchCommand implements WorkflowCommand {
+  description: string;
+
+  constructor(
+    private commands: WorkflowCommand[],
+    description: string = `Batch operation (${commands.length} steps)`
+  ) {
+    this.description = description;
+  }
+
+  execute(workflow: Workflow): Workflow {
+    let result = workflow;
+    for (const command of this.commands) {
+      result = command.execute(result);
+    }
+    return result;
+  }
+
+  undo(workflow: Workflow): Workflow {
+    let result = workflow;
+    // Execute commands in reverse order to undo
+    for (let i = this.commands.length - 1; i >= 0; i--) {
+      result = this.commands[i].undo(result);
+    }
+    return result;
+  }
+}

package/src/flow-designer/flow-designer-node.ts

@@ -0,0 +1,172 @@
+import { html, LitElement, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import IndividualComponent from '@/IndividualComponent.js';
+import styles from './flow-designer.scss';
+import type { WorkflowNode } from './types.js';
+
+/**
+ * Individual node component for flow designer
+ * Renders a single workflow node with customizable slot templates
+ *
+ * @tag wc-flow-designer-node
+ * @rawTag flow-designer-node
+ * @wip true
+ */
+@IndividualComponent
+export class FlowDesignerNode extends LitElement {
+  static styles = [styles];
+
+  /**
+   * The workflow node to render
+   */
+  @property({ type: Object })
+  node: WorkflowNode = { id: '', type: 'action', label: '' };
+
+  /**
+   * Whether this node is currently selected
+   */
+  @property({ type: Boolean, reflect: true, attribute: 'selected' })
+  isSelected: boolean = false;
+
+  /**
+   * Whether this node is in edit mode
+   */
+  @property({ type: Boolean, reflect: true, attribute: 'editing' })
+  isEditing: boolean = false;
+
+  /**
+   * Whether this node is disabled
+   */
+  @property({ type: Boolean, reflect: true })
+  disabled: boolean = false;
+
+  /**
+   * Whether to show the delete button
+   */
+  @property({ type: Boolean, attribute: 'show-delete' })
+  showDelete: boolean = true;
+
+  private _handleClick = () => {
+    this.dispatchEvent(
+      new CustomEvent('node-click', {
+        detail: { nodeId: this.node.id },
+        bubbles: true,
+        composed: true,
+      })
+    );
+  };
+
+  private _handleDoubleClick = () => {
+    this.dispatchEvent(
+      new CustomEvent('node-edit-start', {
+        detail: { nodeId: this.node.id },
+        bubbles: true,
+        composed: true,
+      })
+    );
+  };
+
+  private _handleDelete = (e: Event) => {
+    e.stopPropagation();
+    if (confirm(`Delete "${this.node.label}"?`)) {
+      this.dispatchEvent(
+        new CustomEvent('node-delete', {
+          detail: { nodeId: this.node.id },
+          bubbles: true,
+          composed: true,
+        })
+      );
+    }
+  };
+
+  private _handleMouseEnter = () => {
+    // Node hover state handled via CSS
+  };
+
+  private _handleMouseLeave = () => {
+    // Node hover state handled via CSS
+  };
+
+  render() {
+    const { node, isSelected, isEditing, disabled } = this;
+    const nodeType = node.type || 'action';
+
+    return html`
+      <div
+        class="node-card ${nodeType}"
+        ?selected=${isSelected}
+        ?editing=${isEditing}
+        ?disabled=${disabled}
+        @click=${this._handleClick}
+        @dblclick=${this._handleDoubleClick}
+        role="button"
+        tabindex="0"
+        @keydown=${(e: KeyboardEvent) => {
+          if (e.key === 'Enter' || e.key === ' ') this._handleClick();
+        }}
+      >
+        <!-- Customizable header slot -->
+        <slot name="${nodeType}-header">
+          ${this._renderDefaultHeader()}
+        </slot>
+
+        <!-- Customizable body slot -->
+        <slot name="${nodeType}-body">${this._renderDefaultBody()}</slot>
+
+        <!-- Action buttons -->
+        ${this.isEditing
+          ? html`
+              <div class="node-actions">
+                <button class="btn-sm" @click=${this._handleDelete}>
+                  Delete
+                </button>
+              </div>
+            `
+          : nothing}
+      </div>
+    `;
+  }
+
+  private _renderDefaultHeader() {
+    const { node } = this;
+    const iconMap: Record<string, string> = {
+      trigger: 'play-circle',
+      action: 'check-circle',
+      decision: 'help-circle',
+      loop_start: 'repeat',
+      loop_end: 'repeat',
+      fork: 'git-branch',
+      join: 'git-merge',
+    };
+
+    const icon = iconMap[node.type] || 'activity';
+
+    return html`
+      <div class="node-header">
+        <wc-icon name=${icon} class="node-icon"></wc-icon>
+        <span class="node-title">${node.label}</span>
+      </div>
+    `;
+  }
+
+  private _renderDefaultBody() {
+    const { node } = this;
+    return html`
+      <div class="node-body">
+        ${node.description
+          ? html`<p class="node-description">${node.description}</p>`
+          : nothing}
+        <div class="node-metadata">
+          <span class="node-type-tag">${node.type}</span>
+          ${node.id ? html`<span class="node-id">${node.id}</span>` : nothing}
+        </div>
+      </div>
+    `;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'wc-flow-designer-node': FlowDesignerNode;
+  }
+}