@diagrammo/dgmo 0.8.20 → 0.8.21

package/docs/guide/chart-mindmap.md

@@ -0,0 +1,198 @@
+# Mind Map
+
+```dgmo
+mindmap Product Strategy
+
+Research
+  User Interviews
+    Surveys | description: Quarterly NPS survey
+    Focus Groups
+  Competitor Analysis
+    Feature Matrix
+    Pricing Review
+Development
+  MVP Features
+    Auth System
+      description: Handle login, signup, OAuth flows
+    Dashboard
+  Nice-to-haves | collapsed: true
+    Dark Mode
+    Export PDF
+Go-to-Market
+  Launch Plan
+    Blog Post
+    Demo Video | description: 2-min product walkthrough
+```
+
+## Overview
+
+Mind maps visualize hierarchical information radiating from a central concept. Each branch represents a subtopic, with deeper nesting for finer detail. Mind maps are useful for brainstorming, project planning, knowledge organization, and breaking down complex topics.
+
+**Interactive features:** Click nodes to navigate to their source line. Collapse and expand subtrees by clicking nodes with children. Toggle tag group coloring and depth-based coloring via the legend controls.
+
+## Syntax
+
+```
+mindmap Title
+
+Node
+  Child Node
+    Grandchild
+  Another Child
+```
+
+The first line declares the chart type. The title becomes the root node. Indentation establishes the parent-child hierarchy.
+
+## Nodes
+
+Every non-blank, non-directive line is a node. Nesting is set by indentation:
+
+```
+mindmap Root
+  Level 1a
+    Level 2a
+    Level 2b
+  Level 1b
+```
+
+### Node Colors
+
+Add a color suffix in parentheses:
+
+```
+Important Topic(red)
+  Sub-topic(blue)
+```
+
+### Descriptions
+
+Nodes can have descriptions shown as secondary text. Two forms:
+
+```
+// Pipe form (single line)
+Surveys | description: Quarterly NPS survey
+
+// Indented form (before children)
+Auth System
+  description: Handle login, signup, and OAuth flows
+  Login Page
+```
+
+### Collapse Default
+
+Set a node's default collapsed state with pipe metadata:
+
+```
+Nice-to-haves | collapsed: true
+  Dark Mode
+  Export PDF
+```
+
+Collapsed nodes show a drill-bar indicating hidden children. Click to expand.
+
+## Multi-Root
+
+Omit the title to create multiple independent root trees:
+
+```
+mindmap
+
+Q1 Goals
+  Ship MVP
+  Hire designers
+Q2 Goals
+  Launch marketing
+  Expand team
+```
+
+The diagram title is inferred from the first root's label.
+
+## Pipe Metadata
+
+Attach metadata after `|` with comma-separated `key: value` pairs:
+
+```
+Node | priority: High, status: Done
+```
+
+Tag values, descriptions, and `collapsed` are all set via pipe metadata.
+
+## Tag Groups
+
+Tag groups define color-coded categories. They appear before content and follow the standard tag syntax:
+
+```
+mindmap Root
+
+tag Priority p
+  High(red)
+  Medium(yellow)
+  Low(green)
+
+  Task A | p: High
+  Task B | p: Low
+```
+
+- The alias (`p`) provides a shorthand for metadata keys
+- The active tag group colors nodes by their tag value
+- Click a tag group name in the legend to activate or deactivate it
+
+## Options
+
+| Option | Effect |
+|--------|--------|
+| `active-tag GroupName` | Set the default active tag group |
+| `hide-descriptions` | Hide description text on all nodes |
+
+Options are placed on their own line before content:
+
+```
+mindmap Root
+
+tag Priority p
+  High(red)
+  Low(green)
+
+active-tag Priority
+hide-descriptions
+
+  Task A | p: High
+```
+
+## Complete Example
+
+```dgmo
+mindmap Product Strategy(blue)
+
+tag Priority p
+  High(red)
+  Medium(yellow)
+  Low(green)
+
+tag Department d
+  Engineering(blue)
+  Design(purple)
+  Marketing(orange)
+
+active-tag Priority
+
+Research | d: Marketing
+  User Interviews | p: High
+    Surveys | description: Quarterly NPS survey
+    Focus Groups
+  Competitor Analysis | d: Engineering
+    Feature Matrix
+    Pricing Review
+Development | p: High, d: Engineering
+  MVP Features
+    Auth System
+      description: Handle login, signup, OAuth flows
+    Dashboard
+  Nice-to-haves | p: Low, collapsed: true
+    Dark Mode
+    Export PDF
+Go-to-Market | d: Marketing
+  Launch Plan
+    Blog Post
+    Demo Video | description: 2-min product walkthrough
+```

package/docs/guide/chart-sequence.md

@@ -103,7 +103,29 @@ PaymentGW is a networking aka "Payment Gateway"
 OrderDB position -1
 ```
 
-Position `0` is leftmost, `-1` is rightmost. Unpositioned participants appear in first-mention order.
+## Participant Ordering
+
+Participants are laid out left-to-right based on **first appearance in messages** — the first participant mentioned gets the leftmost column.
+
+**Position values:**
+- `0` = leftmost, `1` = second from left, etc.
+- `-1` = rightmost, `-2` = second from right
+- If two participants target the same slot, the later one shifts to the nearest free position
+
+**Groups affect ordering:** members of the same group always stay adjacent (see [Groups](#groups) below). The group is placed where its first member would naturally appear.
+
+**Priority (highest wins):**
+1. Explicit `position N`
+2. Group adjacency
+3. First appearance in messages
+
+```
+// Example: force the database to the far right
+sequence
+User -placeOrder-> OrderService
+OrderService -save-> OrderDB
+OrderDB position -1
+```
 
 ## Messages
 

package/docs/guide/chart-wireframe.md

@@ -0,0 +1,100 @@
+# Wireframe
+
+```dgmo
+wireframe Login Page
+
+[Header]
+  Acme App
+  nav
+    Home | active
+    About
+    Pricing
+
+[Main]
+  # Sign In
+
+  Email  [user@example.com]
+  Password  [****] | password
+
+  <x> Remember me
+
+  (Sign In)
+  (Forgot Password?) | ghost
+
+  ---
+
+  New here? (Create Account) | ghost
+```
+
+## Overview
+
+Wireframe diagrams use **visual-mnemonic syntax** where bracket characters communicate the element type. The source text reads as a wireframe even before rendering.
+
+## Elements
+
+| Syntax | Element |
+|--------|---------|
+| `[text]` (no children) | Text input |
+| `[Name]` (with children) | Group / region |
+| `(Label)` | Button |
+| `{A \| B \| C}` | Dropdown |
+| `<x>` / `< >` | Checkbox |
+| `(*) Label` / `( ) Label` | Radio button |
+| `# Text` | Heading |
+| `## Text` | Subheading |
+| `---` | Divider |
+| `- text` | List item |
+
+## Keywords
+
+`nav`, `tabs`, `table`, `image`, `modal`, `skeleton`, `alert`, `progress`, `chart`
+
+- `image round` / `image wide` — shape hints
+- `chart line` / `chart bar` / `chart pie` — chart silhouettes
+- `progress 60` — percentage bar
+- `table 5x4` — skeleton table with dimensions
+
+## States
+
+Pipe metadata flags on elements:
+
+```
+(Submit) | disabled
+(Delete) | destructive
+(Cancel) | ghost
+[Email] | password
+[Notes] | textarea
+<x> Dark mode | toggle
+[Cards] | horizontal
+```
+
+## Layout
+
+- **Desktop** (default): 1200px, top-level regions side-by-side
+- **Mobile**: `mobile` keyword, 375px vertical stacking
+- **Smart sizing**: `sidebar` gets ~25%, `main` fills remaining
+- `| horizontal` on any group arranges children in a row
+
+## Multi-Element Lines
+
+Two or more spaces between elements on one line:
+
+```
+Email  [user@example.com]    // label + field
+(-)  1  (+)                  // inline stepper
+```
+
+## Tables
+
+```dgmo
+wireframe Data
+
+table
+  Name, Email, Role
+  John, john@, Admin
+  Sally, sally@, Editor
+
+// Skeleton shorthand:
+table 5x4
+  Name, Email, Role, Status
+```

package/docs/guide/index.md

@@ -4,6 +4,14 @@ Diagrammo is a diagram editor for creating charts and diagrams with a simple pla
 
 Learn more at **[diagrammo.app](https://diagrammo.app)**.
 
+## DGMO and Diagrammo
+
+**DGMO** is the plain-text markup language you write. **Diagrammo** is the app you write it in.
+
+Think of it like Markdown and your editor — Markdown is the syntax, and you can write it anywhere. DGMO works the same way: it's a `.dgmo` text file that describes a diagram. You can create and edit `.dgmo` files in the Diagrammo desktop app, the online editor, Obsidian (via plugin), or any text editor. The `dgmo` CLI renders them from the terminal, and the `@diagrammo/dgmo` npm package lets you render them programmatically.
+
+The name "DGMO" is shorthand for "Diagrammo" — shorter to type, easier to use as a file extension and command name.
+
 ## Getting Started
 
 - **Create a new file** using the file tree on the left, or press **Cmd + N**

package/docs/language-reference.md

@@ -20,7 +20,8 @@
 14. [Timeline Diagrams](#14-timeline-diagrams)
 15. [Data Charts](#15-data-charts)
 16. [Visualizations](#16-visualizations)
-17. [Colon Usage Summary](#17-colon-usage-summary)
+17. [Wireframe Diagrams](#17-wireframe-diagrams)
+18. [Colon Usage Summary](#18-colon-usage-summary)
 
 ---
 
@@ -1326,7 +1327,141 @@ Navigator 0.85 0.8
 
 ---
 
-## 17. Colon Usage Summary
+## 17. Wireframe Diagrams
+
+Wireframe diagrams use **visual-mnemonic syntax** where bracket characters communicate element type.
+
+### Declaration
+
+```
+wireframe Page Title
+```
+
+### Form Factor
+
+```
+mobile
+```
+
+Switches to narrow vertical layout (375px). Desktop (1200px, horizontal regions) is the default.
+
+### Visual-Mnemonic Elements
+
+| Syntax | Element | Example |
+|--------|---------|---------|
+| `[text]` (leaf) | Text input | `[Email address]` |
+| `[Name]` (with children) | Group/region | `[Sidebar]` + indented children |
+| `(Label)` | Button | `(Submit)` |
+| `{A \| B \| C}` | Dropdown/select | `{Small \| Medium \| Large}` |
+| `<x>` / `< >` | Checkbox | `<x> Remember me` |
+| `(*) Label` / `( ) Label` | Radio button | `(*) Option A` |
+| `# Text` / `## Text` | Heading | `# Sign In` |
+| `---` | Divider | `---` |
+| `- text` | List item | `- Electronics` |
+| Bare text | Text/paragraph | `Welcome to our app` |
+
+### Keyword Elements
+
+| Keyword | Type | Parameters |
+|---------|------|------------|
+| `nav` | Block | Children are nav items |
+| `tabs` | Block | Children are tab labels |
+| `table` | Block | Comma-separated rows; first = header |
+| `table RxC` | Skeleton table | `table 5x4` + optional header row |
+| `image` | Leaf | `round`, `wide` hints |
+| `modal Title` | Block | Rendered as separate panel below |
+| `skeleton` | Block | Children render as grey placeholders |
+| `alert` | Block | Optional semantic state |
+| `progress N` | Leaf | Value 0-100: `progress 60` |
+| `chart type` | Leaf | `chart line`, `chart bar`, `chart pie` |
+
+### Pipe Metadata (States)
+
+Wireframe uses flag keywords (not `key: value`):
+
+```
+(Submit) | disabled
+(Delete) | destructive
+(Cancel) | ghost
+[Email] | password
+[Notes] | textarea
+[Cards] | horizontal
+[Advanced] | collapsed
+[Messages] | scrollable
+<x> Dark mode | toggle
+```
+
+Available states: `disabled`, `active`, `selected`, `empty`, `ghost`, `destructive`, `success`, `warning`, `info`, `scrollable`, `collapsed`, `toggle`, `password`, `textarea`, `horizontal`, `primary`.
+
+Free-text annotations after states: `[Email] | required, validates email format`.
+
+### Multi-Element Lines
+
+Two or more spaces between segments create separate elements:
+
+```
+Email  [user@example.com]    // label + field (2 segments)
+(-)  1  (+)                  // 3 inline items
+$299.99  ~~$349.99~~         // 2 inline texts
+```
+
+- **2 segments** (bare text + element): label-for-element pairing
+- **3+ segments**: inline items, no label pairing
+- **Single space = same element**: `Cart (3)` is one text element
+
+### Group Disambiguation
+
+- `[Name]` with indented children = group/container
+- `[Name]` with no children = text input
+- `[Name] | horizontal/scrollable/collapsed` = group (even without children)
+
+### Table Syntax
+
+Explicit rows (comma-separated, first row = header):
+
+```
+table
+  Name, Email, Role
+  John, john@, Admin
+  Sally, sally@, Editor
+```
+
+Skeleton shorthand:
+
+```
+table 5x4
+  Name, Email, Role, Status
+```
+
+### Layout Model
+
+- Desktop: 1200px wide, top-level regions arrange horizontally
+- Mobile: 375px wide, all regions stack vertically
+- Smart sizing: `sidebar` → ~25%, `main`/`content` → fill, `header`/`footer` → full width
+- `| horizontal` on groups arranges children in a row
+
+### Example
+
+```
+wireframe Login Page
+
+[Header]
+  nav
+    Home | active
+    Settings
+
+[Main]
+  # Sign In
+  Email  [user@example.com]
+  Password  [****] | password
+  <x> Remember me
+  (Sign In)
+  (Forgot Password?) | ghost
+```
+
+---
+
+## 18. Colon Usage Summary
 
 ### Constructs Where Colons Are REQUIRED
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.8.20",
+  "version": "0.8.21",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
   "type": "module",

package/src/boxes-and-lines/collapse.ts

@@ -40,12 +40,28 @@ export function collapseBoxesAndLines(
   const nodeToGroup = new Map<string, string>();
   const collapsedChildCounts = new Map<string, number>();
 
+  // Recursively collect all descendants of a group (including sub-group children)
+  function collectDescendants(groupLabel: string): string[] {
+    const group = groupByLabel.get(groupLabel);
+    if (!group) return [];
+    const descendants: string[] = [];
+    for (const child of group.children) {
+      descendants.push(child);
+      // If child is itself a group, collect its descendants too
+      if (groupByLabel.has(child)) {
+        descendants.push(...collectDescendants(child));
+      }
+    }
+    return descendants;
+  }
+
   for (const groupLabel of collapsedGroups) {
     const group = groupByLabel.get(groupLabel);
     if (!group) continue;
     const groupId = `__group_${groupLabel}`;
 
-    for (const child of group.children) {
+    const allDescendants = collectDescendants(groupLabel);
+    for (const child of allDescendants) {
       nodeToGroup.set(child, groupId);
     }
     collapsedChildCounts.set(groupLabel, group.children.length);
@@ -67,8 +83,10 @@ export function collapseBoxesAndLines(
     edges.push({ ...edge, source: src, target: tgt });
   }
 
-  // Keep only groups that are not collapsed
-  const groups = parsed.groups.filter((g) => !collapsedGroups.has(g.label));
+  // Keep only groups that are not collapsed and not inside a collapsed group
+  const groups = parsed.groups.filter(
+    (g) => !collapsedGroups.has(g.label) && !nodeToGroup.has(g.label)
+  );
 
   return {
     parsed: { ...parsed, nodes, edges, groups },

package/src/boxes-and-lines/layout.ts

@@ -3,7 +3,7 @@
 // ============================================================
 
 import dagre from '@dagrejs/dagre';
-import type { ParsedBoxesAndLines, BLNode } from './types';
+import type { ParsedBoxesAndLines, BLNode, BLGroup } from './types';
 
 /**
  * Clip a point at (cx, cy) to the border of a rectangle centered at (cx, cy)
@@ -38,8 +38,7 @@ const CONTAINER_PAD_X = 30;
 const CONTAINER_PAD_TOP = 40;
 const CONTAINER_PAD_BOTTOM = 24;
 const MAX_PARALLEL_EDGES = 5;
-const PARALLEL_SPACING = 12;
-const PARALLEL_EDGE_MARGIN = 10;
+const PARALLEL_SPACING = 22;
 
 // ── Result types ───────────────────────────────────────────
 
@@ -116,12 +115,23 @@ export function layoutBoxesAndLines(
   });
   g.setDefaultEdgeLabel(() => ({}));
 
-  // Determine which groups are collapsed
+  // Determine which groups are collapsed (but not hidden inside a collapsed parent)
   const collapsedGroupLabels = new Set<string>();
   if (collapseInfo) {
+    // Build set of all groups that are missing from parsed (collapsed or hidden)
+    const missingGroups = new Set<string>();
     for (const og of collapseInfo.originalGroups) {
       if (!parsed.groups.some((g) => g.label === og.label)) {
-        collapsedGroupLabels.add(og.label);
+        missingGroups.add(og.label);
+      }
+    }
+    // Only show a collapsed group as a node if its parent is NOT also missing
+    // (i.e., it's a directly collapsed group, not one hidden inside a collapsed parent)
+    for (const label of missingGroups) {
+      const og = collapseInfo.originalGroups.find((g) => g.label === label);
+      const parentLabel = og?.parentGroup;
+      if (!parentLabel || !missingGroups.has(parentLabel)) {
+        collapsedGroupLabels.add(label);
       }
     }
   }
@@ -147,6 +157,25 @@ export function layoutBoxesAndLines(
     });
   }
 
+  // Re-establish parent relationships for collapsed groups
+  // (must run AFTER expanded groups are added to the graph)
+  const originalGroupByLabel = new Map<string, BLGroup>();
+  if (collapseInfo) {
+    for (const og of collapseInfo.originalGroups) {
+      originalGroupByLabel.set(og.label, og);
+    }
+  }
+  for (const label of collapsedGroupLabels) {
+    const og = originalGroupByLabel.get(label);
+    if (og?.parentGroup && !collapsedGroupLabels.has(og.parentGroup)) {
+      const gid = `__group_${label}`;
+      const parentGid = `__group_${og.parentGroup}`;
+      if (g.hasNode(parentGid)) {
+        g.setParent(gid, parentGid);
+      }
+    }
+  }
+
   // Add nodes
   for (const node of parsed.nodes) {
     const size = computeNodeSize(node);
@@ -157,10 +186,26 @@ export function layoutBoxesAndLines(
     });
   }
 
+  // Set parent relationships for nested groups
+  for (const group of parsed.groups) {
+    if (group.parentGroup) {
+      const childGid = `__group_${group.label}`;
+      const parentGid = `__group_${group.parentGroup}`;
+      if (g.hasNode(childGid) && g.hasNode(parentGid)) {
+        g.setParent(childGid, parentGid);
+      }
+    }
+  }
+
+  // Build set of group labels for skip-check below
+  const groupLabelSet = new Set(parsed.groups.map((gr) => gr.label));
+
   // Set parent relationships for nodes in groups
   for (const group of parsed.groups) {
     const gid = `__group_${group.label}`;
     for (const child of group.children) {
+      // Skip children that are sub-groups — their parent is set above
+      if (groupLabelSet.has(child)) continue;
       if (g.hasNode(child)) {
         g.setParent(child, gid);
       }
@@ -263,10 +308,7 @@ export function layoutBoxesAndLines(
       edgeParallelCounts[idx] = 0;
     }
     if (capped.length < 2) continue;
-    const effectiveSpacing = Math.min(
-      PARALLEL_SPACING,
-      (60 - PARALLEL_EDGE_MARGIN) / (capped.length - 1)
-    );
+    const effectiveSpacing = PARALLEL_SPACING;
     for (let j = 0; j < capped.length; j++) {
       edgeYOffsets[capped[j]] =
         (j - (capped.length - 1) / 2) * effectiveSpacing;

package/src/boxes-and-lines/parser.ts

@@ -20,7 +20,7 @@ import {
   OPTION_NOCOLON_RE,
 } from '../utils/parsing';
 
-const MAX_GROUP_DEPTH = 1;
+const MAX_GROUP_DEPTH = 2;
 
 /** Boxes-and-lines requires explicit first line — no heuristic detection. */
 export function looksLikeBoxesAndLines(_content: string): boolean {
@@ -387,13 +387,20 @@ export function parseBoxesAndLines(content: string): ParsedBoxesAndLines {
         }
       }
 
+      const parentGs = currentGroupState();
       const group: BLGroup = {
         label,
         children: [],
         lineNumber: lineNum,
         metadata: groupMeta,
+        ...(parentGs ? { parentGroup: parentGs.group.label } : {}),
       };
 
+      // Add nested group as child of parent group
+      if (parentGs && indent > parentGs.indent) {
+        parentGs.group.children.push(label);
+      }
+
       groupLabels.add(label);
       groupStack.push({ group, indent, depth: currentDepth });
       lastNodeLabel = label;