@djangocfg/widget-diagram 0.1.1

package/src/builders/SequenceDiagram/SequenceDiagram.ts

@@ -0,0 +1,158 @@
+/**
+ * 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, DynamicArrowType } 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);
+
+  // Arrow type to Mermaid syntax mapping
+  const arrowMap: Record<DynamicArrowType, string> = {
+    sync: '->>',
+    syncReply: '-->>',
+    async: '-)',
+    asyncReply: '--)',
+    solid: '->',
+    dotted: '-->',
+    cross: '-x',
+    crossDotted: '--x',
+  };
+
+  return {
+    d: messageBuilder,
+    note: noteBuilder,
+    activate: activationBuilder,
+
+    // Dynamic access methods
+    message(from: string, to: string, text: string, arrow: DynamicArrowType = 'sync') {
+      const arrowSyntax = arrowMap[arrow] || '->>';
+      store.add(`${from}${arrowSyntax}${to}: ${sanitizeLabel(text)}`);
+    },
+
+    noteOver(participant: string, text: string) {
+      store.add(`Note over ${participant}: ${sanitizeLabel(text)}`);
+    },
+
+    noteOverSpan(participant1: string, participant2: string, text: string) {
+      store.add(`Note over ${participant1},${participant2}: ${sanitizeLabel(text)}`);
+    },
+
+    noteLeft(participant: string, text: string) {
+      store.add(`Note left of ${participant}: ${sanitizeLabel(text)}`);
+    },
+
+    noteRight(participant: string, text: string) {
+      store.add(`Note right of ${participant}: ${sanitizeLabel(text)}`);
+    },
+
+    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/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/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');
+  };
+}

package/src/builders/SequenceDiagram/functions/getMessages.ts

@@ -0,0 +1,85 @@
+/**
+ * Message builder functions for SequenceDiagram
+ * @module Mermaid/builders/SequenceDiagram/functions/getMessages
+ */
+
+import { DiagramStore } from '../../core/DiagramStore';
+import { MESSAGE_ARROWS } from '../../core/types';
+import { sanitizeLabel } from '../../core/sanitize';
+import type { MessageBuilder, MessageAction, MessageTarget, MessageArrows } from '../types';
+
+/**
+ * Create message actions for a specific from -> arrow -> to combination
+ */
+function createMessageAction(
+  store: DiagramStore,
+  from: string,
+  arrow: string,
+  to: string,
+): MessageAction {
+  return {
+    msg(text: string) {
+      store.add(`${from}${arrow}${to}: ${sanitizeLabel(text)}`);
+    },
+    activate(text: string) {
+      store.add(`${from}${arrow}+${to}: ${sanitizeLabel(text)}`);
+    },
+    deactivate(text: string) {
+      store.add(`${from}${arrow}-${to}: ${sanitizeLabel(text)}`);
+    },
+  };
+}
+
+/**
+ * Create message target for a specific from -> arrow combination
+ */
+function createMessageTarget<P extends string>(
+  store: DiagramStore,
+  from: string,
+  arrow: string,
+  participants: readonly P[],
+): MessageTarget<P> {
+  const target = {} as MessageTarget<P>;
+
+  participants.forEach((to) => {
+    target[to] = createMessageAction(store, from, arrow, to);
+  });
+
+  return target;
+}
+
+/**
+ * Create arrow selector for a specific from participant
+ */
+function createMessageArrows<P extends string>(
+  store: DiagramStore,
+  from: P,
+  participants: readonly P[],
+): MessageArrows<P> {
+  return {
+    sync: createMessageTarget(store, from, MESSAGE_ARROWS.sync, participants),
+    syncReply: createMessageTarget(store, from, MESSAGE_ARROWS.syncReply, participants),
+    async: createMessageTarget(store, from, MESSAGE_ARROWS.async, participants),
+    asyncReply: createMessageTarget(store, from, MESSAGE_ARROWS.asyncReply, participants),
+    solid: createMessageTarget(store, from, MESSAGE_ARROWS.solid, participants),
+    dotted: createMessageTarget(store, from, MESSAGE_ARROWS.dotted, participants),
+    cross: createMessageTarget(store, from, MESSAGE_ARROWS.cross, participants),
+    crossDotted: createMessageTarget(store, from, MESSAGE_ARROWS.crossDotted, participants),
+  };
+}
+
+/**
+ * Create the full message builder for all participants
+ */
+export function createMessageBuilder<P extends string>(
+  store: DiagramStore,
+  participants: readonly P[],
+): MessageBuilder<P> {
+  const builder = {} as MessageBuilder<P>;
+
+  participants.forEach((from) => {
+    builder[from] = createMessageArrows(store, from, participants);
+  });
+
+  return builder;
+}

package/src/builders/SequenceDiagram/functions/getNotes.ts

@@ -0,0 +1,94 @@
+/**
+ * Note builder functions for SequenceDiagram
+ * @module Mermaid/builders/SequenceDiagram/functions/getNotes
+ */
+
+import { DiagramStore } from '../../core/DiagramStore';
+import { sanitizeLabel } from '../../core/sanitize';
+import type { NoteBuilder, NoteAction, NoteSideTarget, NoteOverTarget } from '../types';
+
+/**
+ * Create a single note action
+ */
+function createNoteAction(
+  store: DiagramStore,
+  position: string,
+): NoteAction {
+  return {
+    msg(text: string) {
+      store.add(`Note ${position}: ${sanitizeLabel(text)}`);
+    },
+  };
+}
+
+/**
+ * Create note targets for left/right positions
+ */
+function createNoteSideTarget<P extends string>(
+  store: DiagramStore,
+  position: 'left' | 'right',
+  participants: readonly P[],
+): NoteSideTarget<P> {
+  const target = {} as NoteSideTarget<P>;
+
+  participants.forEach((p) => {
+    target[p] = createNoteAction(store, `${position} of ${p}`);
+  });
+
+  return target;
+}
+
+/**
+ * Create note targets for "over" position (can span multiple participants)
+ */
+function createNoteOverTarget<P extends string>(
+  store: DiagramStore,
+  participants: readonly P[],
+): NoteOverTarget<P> {
+  const target = {} as NoteOverTarget<P>;
+
+  participants.forEach((first) => {
+    // Create object with msg for single participant note
+    const obj = {
+      msg(text: string) {
+        store.add(`Note over ${first}: ${sanitizeLabel(text)}`);
+      },
+    } as NoteAction & { [K in P]: NoteAction };
+
+    // Add targets for spanning to other participants
+    participants.forEach((second) => {
+      if (first !== second) {
+        (obj as Record<string, NoteAction>)[second] = {
+          msg(text: string) {
+            store.add(`Note over ${first},${second}: ${sanitizeLabel(text)}`);
+          },
+        };
+      } else {
+        // Self-reference just does single note
+        (obj as Record<string, NoteAction>)[second] = {
+          msg(text: string) {
+            store.add(`Note over ${first}: ${sanitizeLabel(text)}`);
+          },
+        };
+      }
+    });
+
+    target[first] = obj;
+  });
+
+  return target;
+}
+
+/**
+ * Create the full note builder
+ */
+export function createNoteBuilder<P extends string>(
+  store: DiagramStore,
+  participants: readonly P[],
+): NoteBuilder<P> {
+  return {
+    leftOf: createNoteSideTarget(store, 'left', participants),
+    rightOf: createNoteSideTarget(store, 'right', participants),
+    over: createNoteOverTarget(store, participants),
+  };
+}

package/src/builders/SequenceDiagram/functions/index.ts

@@ -0,0 +1,16 @@
+/**
+ * SequenceDiagram function exports
+ * @module Mermaid/builders/SequenceDiagram/functions
+ */
+
+export { createMessageBuilder } from './getMessages';
+export { createNoteBuilder } from './getNotes';
+export { createActivationBuilder } from './getActivations';
+export {
+  createLoopBuilder,
+  createAltBuilder,
+  createParBuilder,
+  createRectBuilder,
+  createCriticalBuilder,
+  createBreakBuilder,
+} from './getBlocks';

package/src/builders/SequenceDiagram/index.ts

@@ -0,0 +1,18 @@
+/**
+ * SequenceDiagram builder exports
+ * @module Mermaid/builders/SequenceDiagram
+ */
+
+export { SequenceDiagram } from './SequenceDiagram';
+export type {
+  ParticipantsObject,
+  SequenceDiagramOptions,
+  SequenceDiagramBuilder,
+  MessageBuilder,
+  MessageArrows,
+  MessageTarget,
+  MessageAction,
+  NoteBuilder,
+  ActivationBuilder,
+  DynamicArrowType,
+} from './types';

package/src/builders/SequenceDiagram/types.ts

@@ -0,0 +1,192 @@
+/**
+ * Types for SequenceDiagram builder
+ * @module Mermaid/builders/SequenceDiagram/types
+ */
+
+import type { ParticipantType, MessageArrowType } from '../core/types';
+
+/**
+ * Participants definition object
+ */
+export type ParticipantsObject<P extends string> = {
+  readonly [K in P]: ParticipantType | { type: ParticipantType; alias?: string };
+};
+
+/**
+ * Options for SequenceDiagram builder
+ */
+export interface SequenceDiagramOptions {
+  /** Enable auto-numbering of messages */
+  autoNumber?: boolean;
+}
+
+/**
+ * Message action builder
+ */
+export interface MessageAction {
+  /** Add a message with text */
+  msg(text: string): void;
+  /** Add a message that activates the target */
+  activate(text: string): void;
+  /** Add a message that deactivates the target */
+  deactivate(text: string): void;
+}
+
+/**
+ * Target participant selector for messages
+ */
+export type MessageTarget<P extends string> = {
+  [K in P]: MessageAction;
+};
+
+/**
+ * Arrow type selector for messages
+ */
+export type MessageArrows<P extends string> = {
+  /** Synchronous call ->> */
+  sync: MessageTarget<P>;
+  /** Synchronous reply -->> */
+  syncReply: MessageTarget<P>;
+  /** Async call -) */
+  async: MessageTarget<P>;
+  /** Async reply --) */
+  asyncReply: MessageTarget<P>;
+  /** Solid line -> */
+  solid: MessageTarget<P>;
+  /** Dotted line --> */
+  dotted: MessageTarget<P>;
+  /** Cross (failure) -x */
+  cross: MessageTarget<P>;
+  /** Dotted cross --x */
+  crossDotted: MessageTarget<P>;
+};
+
+/**
+ * Message builder - from participant to arrow type to target
+ */
+export type MessageBuilder<P extends string> = {
+  [K in P]: MessageArrows<P>;
+};
+
+/**
+ * Note position types
+ */
+export type NotePosition = 'leftOf' | 'rightOf' | 'over';
+
+/**
+ * Single note action
+ */
+export interface NoteAction {
+  msg(text: string): void;
+}
+
+/**
+ * Note target for "over" position (can span multiple participants)
+ */
+export type NoteOverTarget<P extends string> = {
+  [K in P]: NoteAction & {
+    /** Span to another participant */
+    [K2 in P]: NoteAction;
+  };
+};
+
+/**
+ * Note target for left/right positions
+ */
+export type NoteSideTarget<P extends string> = {
+  [K in P]: NoteAction;
+};
+
+/**
+ * Note builder
+ */
+export interface NoteBuilder<P extends string> {
+  leftOf: NoteSideTarget<P>;
+  rightOf: NoteSideTarget<P>;
+  over: NoteOverTarget<P>;
+}
+
+/**
+ * Activation builder
+ */
+export type ActivationBuilder<P extends string> = {
+  [K in P]: {
+    activate(): void;
+    deactivate(): void;
+  };
+};
+
+/**
+ * Arrow type for dynamic message method
+ */
+export type DynamicArrowType = 'sync' | 'syncReply' | 'async' | 'asyncReply' | 'solid' | 'dotted' | 'cross' | 'crossDotted';
+
+/**
+ * Main SequenceDiagram builder result
+ */
+export interface SequenceDiagramBuilder<P extends string> {
+  /** Message builder (d.Alice.sync.Bob.msg("Hello")) */
+  d: MessageBuilder<P>;
+  /** Note builder (note.over.Alice.msg("Thinking")) */
+  note: NoteBuilder<P>;
+  /** Activation builder (activate.Alice.activate()) */
+  activate: ActivationBuilder<P>;
+
+  // ============================================================================
+  // Dynamic access methods (for runtime participant names)
+  // ============================================================================
+
+  /**
+   * Send a message dynamically (for runtime participant names)
+   * @example message('Alice', 'Bob', 'Hello!') // sync arrow
+   * @example message('Alice', 'Bob', 'Hello!', 'async')
+   */
+  message(from: string, to: string, text: string, arrow?: DynamicArrowType): void;
+
+  /**
+   * Add a note over one participant dynamically
+   * @example noteOver('Alice', 'Thinking...')
+   */
+  noteOver(participant: string, text: string): void;
+
+  /**
+   * Add a note spanning two participants dynamically
+   * @example noteOverSpan('Alice', 'Bob', 'Handshake')
+   */
+  noteOverSpan(participant1: string, participant2: string, text: string): void;
+
+  /**
+   * Add a note to the left of a participant
+   * @example noteLeft('Alice', 'Waiting')
+   */
+  noteLeft(participant: string, text: string): void;
+
+  /**
+   * Add a note to the right of a participant
+   * @example noteRight('Alice', 'Done')
+   */
+  noteRight(participant: string, text: string): void;
+
+  // ============================================================================
+  // Block methods
+  // ============================================================================
+
+  /** Loop block */
+  loop(label: string, fn: () => void): void;
+  /** Optional/alternative block */
+  alt(label: string, fn: () => void): { else(label: string, fn: () => void): void };
+  /** Parallel block */
+  par(label: string, fn: () => void): { and(label: string, fn: () => void): void };
+  /** Colored rectangle box */
+  rect(color: string, fn: () => void): void;
+  /** Critical region */
+  critical(label: string, fn: () => void): { option(label: string, fn: () => void): void };
+  /** Break */
+  break(label: string, fn: () => void): void;
+  /** Add a comment */
+  comment(text: string): void;
+  /** Add blank line */
+  blank(): void;
+  /** Get the Mermaid string */
+  toString(): string;
+}