@djangocfg/ui-tools 2.1.157 → 2.1.159

package/src/tools/Mermaid/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/tools/Mermaid/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/tools/Mermaid/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/tools/Mermaid/builders/SequenceDiagram/index.ts

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

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

@@ -0,0 +1,147 @@
+/**
+ * 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;
+  };
+};
+
+/**
+ * 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>;
+  /** 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;
+}

package/src/tools/Mermaid/builders/core/DiagramStore.ts

@@ -0,0 +1,138 @@
+/**
+ * DiagramStore - Base class for building Mermaid diagrams
+ * Accumulates diagram lines with proper indentation
+ * @module Mermaid/builders/core/DiagramStore
+ */
+
+export interface DiagramStoreOptions {
+  /** Indentation string (default: '  ' - two spaces) */
+  indent?: string;
+}
+
+const DEFAULT_OPTIONS: Required<DiagramStoreOptions> = {
+  indent: '  ',
+};
+
+/**
+ * Base store for accumulating Mermaid diagram code
+ * Handles indentation and line management
+ */
+export class DiagramStore {
+  protected lines: string[] = [];
+  protected indentLevel = 0;
+  protected options: Required<DiagramStoreOptions>;
+
+  constructor(header: string, options: DiagramStoreOptions = {}) {
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+    this.lines.push(header);
+  }
+
+  /**
+   * Add a line to the diagram with current indentation
+   */
+  add(line: string): this {
+    const indent = this.options.indent.repeat(this.indentLevel);
+    this.lines.push(indent + line);
+    return this;
+  }
+
+  /**
+   * Add a raw line without indentation
+   */
+  addRaw(line: string): this {
+    this.lines.push(line);
+    return this;
+  }
+
+  /**
+   * Add an empty line
+   */
+  addBlank(): this {
+    this.lines.push('');
+    return this;
+  }
+
+  /**
+   * Add a comment line
+   */
+  addComment(comment: string): this {
+    return this.add(`%% ${comment}`);
+  }
+
+  /**
+   * Increase indentation level
+   */
+  indent(): this {
+    this.indentLevel++;
+    return this;
+  }
+
+  /**
+   * Decrease indentation level
+   */
+  dedent(): this {
+    if (this.indentLevel > 0) {
+      this.indentLevel--;
+    }
+    return this;
+  }
+
+  /**
+   * Execute a callback within an indented block
+   * @param header - Block header line
+   * @param fn - Callback to execute inside the block
+   * @param footer - Block footer line (default: 'end')
+   */
+  block(header: string, fn: () => void, footer = 'end'): this {
+    this.add(header);
+    this.indent();
+    fn();
+    this.dedent();
+    this.add(footer);
+    return this;
+  }
+
+  /**
+   * Execute a callback within a subgraph block
+   * @param name - Subgraph name/title
+   * @param fn - Callback to execute inside the subgraph
+   */
+  subgraph(name: string, fn: () => void): this {
+    return this.block(`subgraph ${name}`, fn);
+  }
+
+  /**
+   * Add direction directive (for subgraphs)
+   */
+  direction(dir: 'TB' | 'BT' | 'LR' | 'RL'): this {
+    return this.add(`direction ${dir}`);
+  }
+
+  /**
+   * Get the current indentation string
+   */
+  getIndent(): string {
+    return this.options.indent.repeat(this.indentLevel);
+  }
+
+  /**
+   * Get the current indentation level
+   */
+  getIndentLevel(): number {
+    return this.indentLevel;
+  }
+
+  /**
+   * Convert the diagram to a Mermaid string
+   */
+  toString(): string {
+    return this.lines.join('\n');
+  }
+
+  /**
+   * Get all lines (for debugging)
+   */
+  getLines(): readonly string[] {
+    return this.lines;
+  }
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Core exports for Mermaid builders
+ * @module Mermaid/builders/core
+ */
+
+export { DiagramStore, type DiagramStoreOptions } from './DiagramStore';
+export * from './types';
+export * from './theme';

package/src/tools/Mermaid/builders/core/sanitize.ts

@@ -0,0 +1,78 @@
+/**
+ * Sanitization utilities for Mermaid diagrams
+ * @module Mermaid/builders/core/sanitize
+ */
+
+/**
+ * Characters that need to be escaped or removed in Mermaid labels
+ */
+const UNSAFE_CHARS = /["\n\r\\<>{}|]/g;
+
+/**
+ * Mermaid reserved keywords that cannot be used as node IDs
+ */
+const RESERVED_WORDS = new Set([
+  'end',
+  'graph',
+  'subgraph',
+  'direction',
+  'click',
+  'style',
+  'class',
+  'classDef',
+  'linkStyle',
+  'callback',
+]);
+
+/**
+ * Sanitize a label for use in Mermaid diagrams
+ * Removes or escapes characters that could break the diagram syntax
+ */
+export function sanitizeLabel(label: string): string {
+  return label
+    .replace(UNSAFE_CHARS, '')
+    .replace(/&/g, '&amp;')
+    .replace(/'/g, "'")
+    .trim();
+}
+
+/**
+ * Convert an ID to a valid Mermaid node ID
+ * - Removes special characters
+ * - Adds optional prefix to ensure uniqueness
+ * - Ensures ID starts with a letter
+ * - Escapes reserved Mermaid keywords
+ */
+export function toNodeId(id: string, prefix = ''): string {
+  // Remove special characters and spaces
+  const cleanId = id.replace(/[^a-zA-Z0-9_]/g, '_');
+
+  // Ensure starts with letter
+  let safeId = /^[a-zA-Z]/.test(cleanId) ? cleanId : `n${cleanId}`;
+
+  // Escape reserved words by adding underscore suffix
+  if (RESERVED_WORDS.has(safeId.toLowerCase())) {
+    safeId = `${safeId}_`;
+  }
+
+  return prefix ? `${prefix}_${safeId}` : safeId;
+}
+
+/**
+ * Escape a string for use in quoted Mermaid labels
+ */
+export function escapeQuoted(str: string): string {
+  return str
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '<br/>');
+}
+
+/**
+ * Format a label with optional subtitle using HTML-like syntax
+ */
+export function formatLabel(main: string, subtitle?: string): string {
+  const sanitized = sanitizeLabel(main);
+  if (!subtitle) return sanitized;
+  return `${sanitized}<br/><small>${sanitizeLabel(subtitle)}</small>`;
+}

package/src/tools/Mermaid/builders/core/theme.ts

@@ -0,0 +1,42 @@
+/**
+ * Theme utilities for Mermaid builders
+ *
+ * Re-exports palette hooks from @djangocfg/ui-core for convenience.
+ *
+ * @example
+ * ```tsx
+ * import { useStylePresets, useBoxColors } from './theme';
+ *
+ * function MyDiagram() {
+ *   const presets = useStylePresets();
+ *   const boxes = useBoxColors();
+ *
+ *   const flow = FlowDiagram();
+ *   flow.style.define('success', presets.success);
+ *
+ *   const { rect } = SequenceDiagram({ ... });
+ *   rect(boxes.primary, () => { ... });
+ * }
+ * ```
+ *
+ * @module Mermaid/builders/core/theme
+ */
+
+// Re-export from ui-core palette
+export {
+  // Types
+  type ThemePalette,
+  type StyleColors,
+  type StylePresets,
+  type BoxColors,
+
+  // Hooks
+  useThemePalette,
+  useStylePresets,
+  useBoxColors,
+
+  // Utils
+  hslToHex,
+  hslToRgbString,
+  hslToRgba,
+} from '@djangocfg/ui-core/styles/palette';