@djangocfg/ui-tools 2.1.159 → 2.1.160

package/README.md

@@ -361,6 +361,8 @@ flow.style.apply('myStyle', 'A', 'B');
 
 ### SequenceDiagram API
 
+**Static API** (type-safe, for known participants):
+
 ```tsx
 const { d, rect, alt, loop, toString } = SequenceDiagram({
   User: 'actor',
@@ -368,7 +370,7 @@ const { d, rect, alt, loop, toString } = SequenceDiagram({
   API: 'participant',
 }, { autoNumber: true });
 
-// Messages
+// Messages (type-safe chain)
 d.User.sync.App.msg('Click button');
 d.App.async.API.msg('Fetch data');
 d.API.asyncReply.App.msg('Response');
@@ -391,6 +393,43 @@ loop('Every 5s', () => {
 return toString();
 ```
 
+**Dynamic API** (for runtime participant names):
+
+```tsx
+// Participants from API/database
+const characters = ['Alice', 'Bob', 'Charlie'];
+const participants: Record<string, 'participant'> = {};
+characters.forEach(c => { participants[c] = 'participant'; });
+
+const seq = SequenceDiagram(participants, { autoNumber: true });
+
+// Dynamic methods - no type assertions needed
+seq.message('Alice', 'Bob', 'Hello!');
+seq.message('Bob', 'Alice', 'Hi!', 'syncReply');
+seq.message('Alice', 'Charlie', 'Ping', 'async');
+
+// Notes
+seq.noteOver('Alice', 'Thinking...');
+seq.noteOverSpan('Alice', 'Bob', 'Discussion');
+seq.noteLeft('Charlie', 'Waiting');
+seq.noteRight('Charlie', 'Done');
+
+// Blocks work the same
+seq.rect('rgba(100,200,255,0.2)', () => {
+  seq.message('Alice', 'Bob', 'Secret message');
+});
+
+return seq.toString();
+```
+
+| Dynamic Method | Description |
+|----------------|-------------|
+| `message(from, to, text, arrow?)` | Send message (arrow: sync, syncReply, async, asyncReply, solid, dotted, cross) |
+| `noteOver(participant, text)` | Note over one participant |
+| `noteOverSpan(p1, p2, text)` | Note spanning two participants |
+| `noteLeft(participant, text)` | Note left of participant |
+| `noteRight(participant, text)` | Note right of participant |
+
 ### JourneyDiagram API
 
 ```tsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.159",
+  "version": "2.1.160",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -68,8 +68,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.159",
-    "@djangocfg/ui-core": "^2.1.159",
+    "@djangocfg/i18n": "^2.1.160",
+    "@djangocfg/ui-core": "^2.1.160",
     "lucide-react": "^0.545.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
@@ -101,10 +101,10 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.159",
+    "@djangocfg/i18n": "^2.1.160",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.159",
-    "@djangocfg/ui-core": "^2.1.159",
+    "@djangocfg/typescript-config": "^2.1.160",
+    "@djangocfg/ui-core": "^2.1.160",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",

package/src/tools/Mermaid/Mermaid.story.tsx

@@ -96,6 +96,39 @@ function useJourneyDiagram() {
   return journey.toString();
 }
 
+/**
+ * Example using dynamic methods for runtime participant names
+ * Useful when participants are not known at compile time
+ */
+function useDynamicSequenceDiagram() {
+  const boxes = useBoxColors();
+
+  // Participants from dynamic data (e.g., from API)
+  const participants = ['Alice', 'Bob', 'Charlie'];
+  const participantsObj: Record<string, 'participant'> = {};
+  participants.forEach(p => { participantsObj[p] = 'participant'; });
+
+  const seq = SequenceDiagram(participantsObj, { autoNumber: true });
+
+  // Using dynamic methods - no type assertions needed
+  seq.rect(boxes.primary, () => {
+    seq.noteOver('Alice', 'Starting conversation');
+    seq.message('Alice', 'Bob', 'Hello Bob!');
+    seq.message('Bob', 'Alice', 'Hi Alice!', 'syncReply');
+  });
+
+  seq.blank();
+
+  seq.rect(boxes.success, () => {
+    seq.noteOverSpan('Alice', 'Charlie', 'Group discussion');
+    seq.message('Alice', 'Charlie', 'Hey Charlie!');
+    seq.message('Charlie', 'Bob', 'Bob, join us!');
+    seq.message('Bob', 'Charlie', 'On my way!', 'async');
+  });
+
+  return seq.toString();
+}
+
 function useArchitectureDiagram() {
   type Nodes = 'client' | 'nginx' | 'api1' | 'api2' | 'db' | 'cache' | 'queue';
   const flow = FlowDiagram<Nodes>({ direction: 'TB' });
@@ -148,7 +181,7 @@ function useArchitectureDiagram() {
 
 export const Interactive = () => {
   const [diagramType] = useSelect('diagramType', {
-    options: ['flow', 'sequence', 'journey', 'architecture'] as const,
+    options: ['flow', 'sequence', 'sequenceDynamic', 'journey', 'architecture'] as const,
     defaultValue: 'flow',
     label: 'Diagram Type',
   });
@@ -160,12 +193,14 @@ export const Interactive = () => {
 
   const flowChart = useFlowDiagram();
   const sequenceChart = useSequenceDiagram();
+  const sequenceDynamicChart = useDynamicSequenceDiagram();
   const journeyChart = useJourneyDiagram();
   const architectureChart = useArchitectureDiagram();
 
   const charts = {
     flow: flowChart,
     sequence: sequenceChart,
+    sequenceDynamic: sequenceDynamicChart,
     journey: journeyChart,
     architecture: architectureChart,
   };

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

@@ -18,7 +18,7 @@ import {
   createCriticalBuilder,
   createBreakBuilder,
 } from './functions/getBlocks';
-import type { ParticipantsObject, SequenceDiagramOptions, SequenceDiagramBuilder } from './types';
+import type { ParticipantsObject, SequenceDiagramOptions, SequenceDiagramBuilder, DynamicArrowType } from './types';
 
 const DEFAULT_OPTIONS: Required<SequenceDiagramOptions> = {
   autoNumber: false,
@@ -97,10 +97,45 @@ export function SequenceDiagram<P extends string>(
   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),

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

@@ -14,4 +14,5 @@ export type {
   MessageAction,
   NoteBuilder,
   ActivationBuilder,
+  DynamicArrowType,
 } from './types';

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

@@ -116,6 +116,11 @@ export type ActivationBuilder<P extends string> = {
   };
 };
 
+/**
+ * Arrow type for dynamic message method
+ */
+export type DynamicArrowType = 'sync' | 'syncReply' | 'async' | 'asyncReply' | 'solid' | 'dotted' | 'cross' | 'crossDotted';
+
 /**
  * Main SequenceDiagram builder result
  */
@@ -126,6 +131,46 @@ export interface SequenceDiagramBuilder<P extends string> {
   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 */