@djangocfg/ui-tools 2.1.158 → 2.1.160

package/README.md

@@ -49,8 +49,21 @@ import { Gallery, GalleryLightbox } from '@djangocfg/ui-tools/gallery';
 
 // Only loads Map (~800KB)
 import { MapContainer, MapMarker } from '@djangocfg/ui-tools/map';
+
+// Mermaid builders (no heavy Mermaid dependency until render)
+import { FlowDiagram, SequenceDiagram, JourneyDiagram } from '@djangocfg/ui-tools/mermaid';
 ```
 
+## Exports
+
+| Path | Content |
+|------|---------|
+| `@djangocfg/ui-tools` | All tools with lazy loading |
+| `@djangocfg/ui-tools/gallery` | Gallery components & hooks |
+| `@djangocfg/ui-tools/map` | Map components & utilities |
+| `@djangocfg/ui-tools/mermaid` | Mermaid component & declarative builders |
+| `@djangocfg/ui-tools/styles` | CSS styles |
+
 ## Gallery
 
 Full-featured image/video gallery with carousel, grid view, and fullscreen lightbox.
@@ -241,9 +254,9 @@ Render Mermaid diagrams with fullscreen zoom support and type-safe declarative b
 ### Basic Usage
 
 ```tsx
-import Mermaid from '@djangocfg/ui-tools/tools/Mermaid';
+import { LazyMermaid } from '@djangocfg/ui-tools';
 
-<Mermaid chart={`
+<LazyMermaid chart={`
   graph TD
     A[Start] --> B{Decision}
     B -->|Yes| C[Action]
@@ -265,13 +278,14 @@ import Mermaid from '@djangocfg/ui-tools/tools/Mermaid';
 Type-safe builders for creating Mermaid diagrams programmatically:
 
 ```tsx
-import Mermaid, {
+import { LazyMermaid } from '@djangocfg/ui-tools';
+import {
   FlowDiagram,
   SequenceDiagram,
   JourneyDiagram,
   useStylePresets,
   useBoxColors,
-} from '@djangocfg/ui-tools/tools/Mermaid';
+} from '@djangocfg/ui-tools/mermaid';
 
 function MyDiagram() {
   const presets = useStylePresets();
@@ -295,7 +309,7 @@ function MyDiagram() {
   flow.style.define('success', presets.success);
   flow.style.apply('success', 'success', 'finish');
 
-  return <Mermaid chart={flow.toString()} />;
+  return <LazyMermaid chart={flow.toString()} />;
 }
 ```
 
@@ -347,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',
@@ -354,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');
@@ -377,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.158",
+  "version": "2.1.160",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -47,6 +47,11 @@
       "import": "./src/tools/Map/index.ts",
       "require": "./src/tools/Map/index.ts"
     },
+    "./mermaid": {
+      "types": "./src/tools/Mermaid/index.tsx",
+      "import": "./src/tools/Mermaid/index.tsx",
+      "require": "./src/tools/Mermaid/index.tsx"
+    },
     "./styles": "./src/styles/index.css"
   },
   "files": [
@@ -63,8 +68,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.158",
-    "@djangocfg/ui-core": "^2.1.158",
+    "@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",
@@ -96,10 +101,10 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.158",
+    "@djangocfg/i18n": "^2.1.160",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.158",
-    "@djangocfg/ui-core": "^2.1.158",
+    "@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 */