@djangocfg/ui-tools 2.1.157 → 2.1.159

package/src/tools/Mermaid/builders/FlowDiagram/functions/getStyles.ts

@@ -0,0 +1,90 @@
+/**
+ * Style builder functions for FlowDiagram
+ * @module Mermaid/builders/FlowDiagram/functions/getStyles
+ */
+
+import { DiagramStore } from '../../core/DiagramStore';
+import type { StyleProperties } from '../../core/types';
+import { toNodeId } from '../../core/sanitize';
+import type { StyleBuilder } from '../types';
+
+/**
+ * Convert style properties to Mermaid classDef syntax
+ */
+function propertiesToString(properties: StyleProperties): string {
+  const parts: string[] = [];
+
+  if (properties.fill) parts.push(`fill:${properties.fill}`);
+  if (properties.stroke) parts.push(`stroke:${properties.stroke}`);
+  if (properties['stroke-width']) parts.push(`stroke-width:${properties['stroke-width']}`);
+  if (properties.color) parts.push(`color:${properties.color}`);
+  if (properties['font-weight']) parts.push(`font-weight:${properties['font-weight']}`);
+  if (properties['stroke-dasharray']) parts.push(`stroke-dasharray:${properties['stroke-dasharray']}`);
+
+  return parts.join(',');
+}
+
+/**
+ * Create a style builder
+ */
+export function createStyleBuilder(store: DiagramStore): StyleBuilder {
+  return {
+    define(name: string, properties: StyleProperties): void {
+      const propsStr = propertiesToString(properties);
+      store.add(`classDef ${name} ${propsStr}`);
+    },
+
+    apply(className: string, ...nodeIds: string[]): void {
+      if (nodeIds.length === 0) return;
+      const safeIds = nodeIds.map((id) => toNodeId(id)).join(',');
+      store.add(`class ${safeIds} ${className}`);
+    },
+  };
+}
+
+// ============================================================================
+// Predefined Style Classes (Common patterns)
+// ============================================================================
+
+/**
+ * Common style presets for quick use
+ */
+export const STYLE_PRESETS = {
+  /** Green success style */
+  success: {
+    fill: '#22c55e',
+    stroke: '#16a34a',
+    color: '#fff',
+  },
+  /** Blue primary style */
+  primary: {
+    fill: '#3b82f6',
+    stroke: '#1d4ed8',
+    color: '#fff',
+  },
+  /** Red error/danger style */
+  danger: {
+    fill: '#ef4444',
+    stroke: '#dc2626',
+    color: '#fff',
+  },
+  /** Yellow warning style */
+  warning: {
+    fill: '#f59e0b',
+    stroke: '#d97706',
+    color: '#fff',
+  },
+  /** Gray muted style */
+  muted: {
+    fill: '#6b7280',
+    stroke: '#4b5563',
+    color: '#fff',
+  },
+  /** Emerald/teal accent */
+  accent: {
+    fill: '#10b981',
+    stroke: '#047857',
+    color: '#fff',
+    'font-weight': 'bold' as const,
+  },
+} satisfies Record<string, StyleProperties>;

package/src/tools/Mermaid/builders/FlowDiagram/functions/index.ts

@@ -0,0 +1,8 @@
+/**
+ * FlowDiagram function exports
+ * @module Mermaid/builders/FlowDiagram/functions
+ */
+
+export { createNodeBuilder } from './getNodes';
+export { createEdgeBuilder, createEdgesBuilder } from './getEdges';
+export { createStyleBuilder, STYLE_PRESETS } from './getStyles';

package/src/tools/Mermaid/builders/FlowDiagram/index.ts

@@ -0,0 +1,16 @@
+/**
+ * FlowDiagram builder exports
+ * @module Mermaid/builders/FlowDiagram
+ */
+
+export { FlowDiagram } from './FlowDiagram';
+export { STYLE_PRESETS } from './functions/getStyles';
+export type {
+  FlowDiagramOptions,
+  FlowDiagramBuilder,
+  NodeBuilder,
+  EdgeBuilder,
+  EdgeEndBuilder,
+  StyleBuilder,
+  SubgraphBuilder,
+} from './types';

package/src/tools/Mermaid/builders/FlowDiagram/types.ts

@@ -0,0 +1,130 @@
+/**
+ * Types for FlowDiagram builder
+ * @module Mermaid/builders/FlowDiagram/types
+ */
+
+import type { FlowDirection, NodeShape, StyleProperties } from '../core/types';
+
+/**
+ * Options for FlowDiagram builder
+ */
+export interface FlowDiagramOptions {
+  /** Diagram direction (default: 'TB') */
+  direction?: FlowDirection;
+}
+
+/**
+ * Node definition
+ */
+export interface NodeDefinition {
+  id: string;
+  label: string;
+  shape: NodeShape;
+  subtitle?: string;
+}
+
+/**
+ * Edge definition
+ */
+export interface EdgeDefinition {
+  from: string;
+  to: string;
+  label?: string;
+  style: 'solid' | 'dotted' | 'thick';
+}
+
+/**
+ * Style class definition for flow diagrams
+ */
+export interface FlowStyleClass {
+  name: string;
+  properties: StyleProperties;
+}
+
+/**
+ * Node builder interface - chainable API for creating nodes
+ */
+export interface NodeBuilder<Nodes extends string> {
+  /** Create a rectangular node [label] */
+  rect(label: string, subtitle?: string): void;
+  /** Create a rounded node (label) */
+  round(label: string, subtitle?: string): void;
+  /** Create a stadium/pill node ([label]) */
+  stadium(label: string, subtitle?: string): void;
+  /** Create a circular node ((label)) */
+  circle(label: string, subtitle?: string): void;
+  /** Create a rhombus/diamond node {label} */
+  rhombus(label: string, subtitle?: string): void;
+  /** Create a hexagon node {{label}} */
+  hexagon(label: string, subtitle?: string): void;
+  /** Create a cylinder/database node [(label)] */
+  cylinder(label: string, subtitle?: string): void;
+  /** Create a subroutine node [[label]] */
+  subroutine(label: string, subtitle?: string): void;
+  /** Create a double circle node (((label))) */
+  doubleCircle(label: string, subtitle?: string): void;
+}
+
+/**
+ * Edge builder interface - chainable API for creating edges
+ */
+export interface EdgeBuilder<Nodes extends string> {
+  /** Target node for the edge */
+  to(target: Nodes): EdgeEndBuilder;
+}
+
+/**
+ * Edge end builder - configures the edge after target is specified
+ */
+export interface EdgeEndBuilder {
+  /** Solid arrow --> */
+  solid(label?: string): void;
+  /** Dotted arrow -.-> */
+  dotted(label?: string): void;
+  /** Thick arrow ==> */
+  thick(label?: string): void;
+  /** Solid line without arrow --- */
+  line(label?: string): void;
+  /** Dotted line without arrow -.- */
+  dottedLine(label?: string): void;
+}
+
+/**
+ * Style builder interface
+ */
+export interface StyleBuilder {
+  /** Define a style class */
+  define(name: string, properties: StyleProperties): void;
+  /** Apply a class to nodes */
+  apply(className: string, ...nodeIds: string[]): void;
+}
+
+/**
+ * Subgraph builder interface
+ */
+export interface SubgraphBuilder<Nodes extends string> {
+  /** Set direction inside subgraph */
+  direction(dir: FlowDirection): void;
+  /** Create a node inside subgraph */
+  node(id: Nodes): NodeBuilder<Nodes>;
+}
+
+/**
+ * Main FlowDiagram builder result
+ */
+export interface FlowDiagramBuilder<Nodes extends string> {
+  /** Create a node */
+  node: (id: Nodes) => NodeBuilder<Nodes>;
+  /** Create an edge from a node */
+  edge: (from: Nodes) => EdgeBuilder<Nodes>;
+  /** Create a subgraph */
+  subgraph: (name: string, fn: (sub: SubgraphBuilder<Nodes>) => void) => void;
+  /** Style utilities */
+  style: StyleBuilder;
+  /** Add a comment */
+  comment: (text: string) => void;
+  /** Add a blank line */
+  blank: () => void;
+  /** Get the Mermaid string */
+  toString: () => string;
+}

package/src/tools/Mermaid/builders/JourneyDiagram/JourneyDiagram.ts

@@ -0,0 +1,88 @@
+/**
+ * JourneyDiagram Builder
+ * Declarative API for building Mermaid user journey diagrams
+ * @module Mermaid/builders/JourneyDiagram/JourneyDiagram
+ */
+
+import { DiagramStore } from '../core/DiagramStore';
+import type { TaskScore } from '../core/types';
+import { sanitizeLabel } from '../core/sanitize';
+import type { JourneyDiagramOptions, JourneyDiagramBuilder, SectionBuilder } from './types';
+
+/**
+ * Format actors for journey task
+ */
+function formatActors(actors: string | string[]): string {
+  if (Array.isArray(actors)) {
+    return actors.map(sanitizeLabel).join(', ');
+  }
+  return sanitizeLabel(actors);
+}
+
+/**
+ * Create a JourneyDiagram builder
+ *
+ * @example
+ * ```typescript
+ * const journey = JourneyDiagram({ title: 'User Registration Flow' });
+ *
+ * journey.section('Discovery')
+ *   .task('Visit website', 5, 'User')
+ *   .task('Read about product', 4, 'User');
+ *
+ * journey.section('Registration')
+ *   .task('Click sign up', 5, 'User')
+ *   .task('Fill form', 2, 'User')
+ *   .task('Verify email', 3, ['User', 'System']);
+ *
+ * journey.section('Onboarding')
+ *   .task('Complete profile', 4, 'User')
+ *   .task('Start using app', 5, 'User');
+ *
+ * console.log(journey.toString());
+ * ```
+ *
+ * @param options - Diagram options (title is required)
+ * @returns JourneyDiagram builder instance
+ */
+export function JourneyDiagram(options: JourneyDiagramOptions): JourneyDiagramBuilder {
+  const store = new DiagramStore('journey');
+  store.add(`title ${sanitizeLabel(options.title)}`);
+
+  /**
+   * Add a task line
+   */
+  const addTask = (name: string, score: TaskScore, actors: string | string[]) => {
+    const actorStr = formatActors(actors);
+    store.add(`${sanitizeLabel(name)}: ${score}: ${actorStr}`);
+  };
+
+  /**
+   * Create a section builder for chaining tasks
+   */
+  const createSectionBuilder = (): SectionBuilder => ({
+    task(name: string, score: TaskScore, actors: string | string[]) {
+      addTask(name, score, actors);
+      return this;
+    },
+  });
+
+  return {
+    section(name: string) {
+      store.add(`section ${sanitizeLabel(name)}`);
+      return createSectionBuilder();
+    },
+
+    task(name: string, score: TaskScore, actors: string | string[]) {
+      addTask(name, score, actors);
+    },
+
+    comment(text: string) {
+      store.addComment(text);
+    },
+
+    toString() {
+      return store.toString();
+    },
+  };
+}

package/src/tools/Mermaid/builders/JourneyDiagram/index.ts

@@ -0,0 +1,12 @@
+/**
+ * JourneyDiagram builder exports
+ * @module Mermaid/builders/JourneyDiagram
+ */
+
+export { JourneyDiagram } from './JourneyDiagram';
+export type {
+  JourneyDiagramOptions,
+  JourneyDiagramBuilder,
+  SectionBuilder,
+  TaskDefinition,
+} from './types';

package/src/tools/Mermaid/builders/JourneyDiagram/types.ts

@@ -0,0 +1,48 @@
+/**
+ * Types for JourneyDiagram builder
+ * @module Mermaid/builders/JourneyDiagram/types
+ */
+
+import type { TaskScore } from '../core/types';
+
+/**
+ * Options for JourneyDiagram builder
+ */
+export interface JourneyDiagramOptions {
+  /** Diagram title */
+  title: string;
+}
+
+/**
+ * Task definition
+ */
+export interface TaskDefinition {
+  /** Task name/description */
+  name: string;
+  /** Score (1-5, where 5 is best) */
+  score: TaskScore;
+  /** Actor(s) involved */
+  actors: string | string[];
+}
+
+/**
+ * Section builder interface
+ */
+export interface SectionBuilder {
+  /** Add a task to the current section */
+  task(name: string, score: TaskScore, actors: string | string[]): SectionBuilder;
+}
+
+/**
+ * Main JourneyDiagram builder result
+ */
+export interface JourneyDiagramBuilder {
+  /** Add a new section */
+  section(name: string): SectionBuilder;
+  /** Add a task directly (without section - goes to last section or creates implicit one) */
+  task(name: string, score: TaskScore, actors: string | string[]): void;
+  /** Add a comment */
+  comment(text: string): void;
+  /** Get the Mermaid string */
+  toString(): string;
+}

package/src/tools/Mermaid/builders/SequenceDiagram/SequenceDiagram.ts

@@ -0,0 +1,123 @@
+/**
+ * SequenceDiagram Builder
+ * Declarative API for building Mermaid sequence diagrams
+ * @module Mermaid/builders/SequenceDiagram/SequenceDiagram
+ */
+
+import { DiagramStore } from '../core/DiagramStore';
+import type { ParticipantType } from '../core/types';
+import { sanitizeLabel } from '../core/sanitize';
+import { createMessageBuilder } from './functions/getMessages';
+import { createNoteBuilder } from './functions/getNotes';
+import { createActivationBuilder } from './functions/getActivations';
+import {
+  createLoopBuilder,
+  createAltBuilder,
+  createParBuilder,
+  createRectBuilder,
+  createCriticalBuilder,
+  createBreakBuilder,
+} from './functions/getBlocks';
+import type { ParticipantsObject, SequenceDiagramOptions, SequenceDiagramBuilder } from './types';
+
+const DEFAULT_OPTIONS: Required<SequenceDiagramOptions> = {
+  autoNumber: false,
+};
+
+/**
+ * Normalize participant definition to { type, alias } format
+ */
+function normalizeParticipant(
+  value: ParticipantType | { type: ParticipantType; alias?: string },
+): { type: ParticipantType; alias?: string } {
+  if (typeof value === 'string') {
+    return { type: value };
+  }
+  return value;
+}
+
+/**
+ * Create a SequenceDiagram builder
+ *
+ * @example
+ * ```typescript
+ * const { d, note, loop, rect } = SequenceDiagram({
+ *   Alice: 'participant',
+ *   Bob: 'actor',
+ *   Charlie: { type: 'participant', alias: 'C' },
+ * }, { autoNumber: true });
+ *
+ * rect('rgb(200, 220, 255)', () => {
+ *   d.Alice.sync.Bob.msg('Hello!');
+ *   d.Bob.syncReply.Alice.msg('Hi there!');
+ * });
+ *
+ * loop('Every minute', () => {
+ *   d.Alice.async.Charlie.msg('Ping');
+ * });
+ *
+ * note.over.Alice.Bob.msg('Handshake complete');
+ *
+ * console.log(toString());
+ * ```
+ *
+ * @param participants - Participant definitions
+ * @param options - Diagram options
+ * @returns SequenceDiagram builder instance
+ */
+export function SequenceDiagram<P extends string>(
+  participants: ParticipantsObject<P>,
+  options: SequenceDiagramOptions = {},
+): SequenceDiagramBuilder<P> {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const store = new DiagramStore('sequenceDiagram');
+
+  // Add autonumber if requested
+  if (opts.autoNumber) {
+    store.add('autonumber');
+  }
+
+  // Get participant keys
+  const participantKeys = Object.keys(participants) as P[];
+
+  // Declare participants
+  store.addBlank();
+  participantKeys.forEach((key) => {
+    const def = normalizeParticipant(participants[key]);
+    if (def.alias) {
+      store.add(`${def.type} ${key} as ${sanitizeLabel(def.alias)}`);
+    } else {
+      store.add(`${def.type} ${key}`);
+    }
+  });
+  store.addBlank();
+
+  // Create builders
+  const messageBuilder = createMessageBuilder<P>(store, participantKeys);
+  const noteBuilder = createNoteBuilder<P>(store, participantKeys);
+  const activationBuilder = createActivationBuilder<P>(store, participantKeys);
+
+  return {
+    d: messageBuilder,
+    note: noteBuilder,
+    activate: activationBuilder,
+    loop: createLoopBuilder(store),
+    alt: createAltBuilder(store),
+    par: createParBuilder(store),
+    rect: createRectBuilder(store),
+    critical: createCriticalBuilder(store),
+    break: createBreakBuilder(store),
+
+    comment(text: string) {
+      store.addComment(text);
+    },
+
+    blank() {
+      store.addBlank();
+    },
+
+    toString() {
+      return store.toString();
+    },
+  };
+}

package/src/tools/Mermaid/builders/SequenceDiagram/functions/getActivations.ts

@@ -0,0 +1,30 @@
+/**
+ * Activation builder functions for SequenceDiagram
+ * @module Mermaid/builders/SequenceDiagram/functions/getActivations
+ */
+
+import { DiagramStore } from '../../core/DiagramStore';
+import type { ActivationBuilder } from '../types';
+
+/**
+ * Create the activation builder for all participants
+ */
+export function createActivationBuilder<P extends string>(
+  store: DiagramStore,
+  participants: readonly P[],
+): ActivationBuilder<P> {
+  const builder = {} as ActivationBuilder<P>;
+
+  participants.forEach((p) => {
+    builder[p] = {
+      activate() {
+        store.add(`activate ${p}`);
+      },
+      deactivate() {
+        store.add(`deactivate ${p}`);
+      },
+    };
+  });
+
+  return builder;
+}

package/src/tools/Mermaid/builders/SequenceDiagram/functions/getBlocks.ts

@@ -0,0 +1,112 @@
+/**
+ * Block builder functions for SequenceDiagram (loop, alt, par, rect, etc.)
+ * @module Mermaid/builders/SequenceDiagram/functions/getBlocks
+ */
+
+import { DiagramStore } from '../../core/DiagramStore';
+import { sanitizeLabel } from '../../core/sanitize';
+
+/**
+ * Create a loop block builder
+ */
+export function createLoopBuilder(store: DiagramStore) {
+  return (label: string, fn: () => void) => {
+    store.add(`loop ${sanitizeLabel(label)}`);
+    store.indent();
+    fn();
+    store.dedent();
+    store.add('end');
+  };
+}
+
+/**
+ * Create an alt (alternative/conditional) block builder
+ */
+export function createAltBuilder(store: DiagramStore) {
+  return (label: string, fn: () => void) => {
+    store.add(`alt ${sanitizeLabel(label)}`);
+    store.indent();
+    fn();
+    store.dedent();
+
+    return {
+      else(elseLabel: string, elseFn: () => void) {
+        store.add(`else ${sanitizeLabel(elseLabel)}`);
+        store.indent();
+        elseFn();
+        store.dedent();
+        store.add('end');
+      },
+    };
+  };
+}
+
+/**
+ * Create a parallel (par) block builder
+ */
+export function createParBuilder(store: DiagramStore) {
+  return (label: string, fn: () => void) => {
+    store.add(`par ${sanitizeLabel(label)}`);
+    store.indent();
+    fn();
+    store.dedent();
+
+    return {
+      and(andLabel: string, andFn: () => void) {
+        store.add(`and ${sanitizeLabel(andLabel)}`);
+        store.indent();
+        andFn();
+        store.dedent();
+        store.add('end');
+      },
+    };
+  };
+}
+
+/**
+ * Create a rect (colored box) block builder
+ */
+export function createRectBuilder(store: DiagramStore) {
+  return (color: string, fn: () => void) => {
+    store.add(`rect ${color}`);
+    store.indent();
+    fn();
+    store.dedent();
+    store.add('end');
+  };
+}
+
+/**
+ * Create a critical region block builder
+ */
+export function createCriticalBuilder(store: DiagramStore) {
+  return (label: string, fn: () => void) => {
+    store.add(`critical ${sanitizeLabel(label)}`);
+    store.indent();
+    fn();
+    store.dedent();
+
+    return {
+      option(optionLabel: string, optionFn: () => void) {
+        store.add(`option ${sanitizeLabel(optionLabel)}`);
+        store.indent();
+        optionFn();
+        store.dedent();
+        store.add('end');
+      },
+    };
+  };
+}
+
+/**
+ * Create a break block builder
+ */
+export function createBreakBuilder(store: DiagramStore) {
+  return (label: string, fn: () => void) => {
+    store.add(`break ${sanitizeLabel(label)}`);
+    store.indent();
+    fn();
+    store.dedent();
+    store.add('end');
+  };
+}