@diagrammo/dgmo 0.8.20 → 0.8.22

package/docs/language-reference.md

@@ -20,7 +20,9 @@
 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. [Tech Radar Diagrams](#17-tech-radar-diagrams)
+18. [Wireframe Diagrams](#18-wireframe-diagrams)
+19. [Colon Usage Summary](#19-colon-usage-summary)
 
 ---
 
@@ -608,7 +610,28 @@ deployment
   container Web App    // reference existing container
 ```
 
-### 7.7 Options
+### 7.7 Element Descriptions
+
+```
+// Indented metadata form (colon required)
+Web App is a container
+  description: SPA built with React
+  description: Supports SSR and client-side routing
+
+// Keyword form (colon optional)
+API is a container
+  description Handles all REST endpoints
+
+// Pipe metadata form
+Database is a container | description: PostgreSQL with read replicas
+```
+
+- Multiple `description` lines accumulate into a multi-line description
+- `description` is extracted as a dedicated field, not stored in general metadata
+- Supports inline markdown: `**bold**`, `*italic*`, `` `code` ``, `[links](url)`
+- `- bullet text` renders as `• bullet text`
+
+### 7.8 Options
 
 - `direction-tb` (boolean; default is LR)
 
@@ -812,7 +835,28 @@ All permutations supported: node→group, group→node, group→group. Brackets
   Pricing | Auth: Public
 ```
 
-### 11.5 Options
+### 11.5 Node Descriptions
+
+```
+// Keyword form (colon optional)
+About
+  description Company history and team bios
+
+// Pipe metadata form
+Pricing | description: Compare plans and features
+
+// Multi-line
+Blog
+  description: Engineering and product updates
+  description: Published weekly
+```
+
+- `description` keyword required (bare prose lines are not auto-detected as descriptions)
+- Multiple `description` lines accumulate into a multi-line description
+- Supports inline markdown: `**bold**`, `*italic*`, `` `code` ``, `[links](url)`
+- `- bullet text` renders as `• bullet text`
+
+### 11.6 Options
 
 - `direction-tb` (boolean; default is LR)
 
@@ -1326,7 +1370,207 @@ Navigator 0.85 0.8
 
 ---
 
-## 17. Colon Usage Summary
+## 17. Tech Radar Diagrams
+
+```
+tech-radar Title
+
+rings
+  Adopt
+  Trial
+  Assess
+  Hold
+
+Techniques | quadrant: top-right
+  Continuous Deployment | ring: Adopt, trend: stable
+    Fully adopted across all services.
+  Micro Frontends | ring: Trial, trend: up
+
+Tools | quadrant: top-left
+  Vite | ring: Adopt, trend: up
+  Webpack | ring: Hold, trend: down
+```
+
+### Rings
+
+Declared in a `rings` block, one per indented line. Order: innermost (first) to outermost (last). Any names, any count.
+
+Aliases supported: `Adopt alias a` — then blips can use `ring: a`.
+
+### Quadrants
+
+Exactly 4 required. Each is a top-level header with pipe metadata:
+
+```
+Name | quadrant: position
+```
+
+**Positions:** `top-left`, `top-right`, `bottom-left`, `bottom-right` — each used exactly once.
+
+Optional color override: `Tools | quadrant: top-left, color: purple`
+
+Default colors: top-left=blue, top-right=green, bottom-left=red, bottom-right=orange.
+
+### Blips
+
+Indented under their quadrant. Require `ring` metadata (case-insensitive match). Optional `trend`:
+
+```
+  Item Name | ring: Adopt, trend: stable
+```
+
+**Trends:** `new` (double circle), `up` (inward crescent), `down` (outward crescent), `stable` (plain circle). Omitting renders plain circle.
+
+### Descriptions
+
+Further-indented lines below a blip. Supports inline markdown (bold, italic, code, links).
+
+```
+  Rust | ring: Assess, trend: new
+    Evaluating for **performance-critical** services.
+```
+
+### Numbering
+
+Blips receive sequential global numbers. Order: quadrants clockwise (top-left → top-right → bottom-right → bottom-left), then by ring (innermost first), then declaration order.
+
+---
+
+## 18. 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
+```
+
+---
+
+## 19. Colon Usage Summary
 
 ### Constructs Where Colons Are REQUIRED
 
@@ -1345,6 +1589,7 @@ Navigator 0.85 0.8
 | Construct | Diagram Type | Example |
 |-----------|-------------|---------|
 | Class relationship label | class | `--|> Vessel : extends` or `--|> Vessel extends` |
+| Description keyword (indented) | sitemap, c4 | `description text` or `description: text` |
 
 ### Colons NOT USED
 

package/gallery/fixtures/boxes-and-lines.dgmo

@@ -9,20 +9,27 @@ hide priority:Low
 direction LR
 
 // --- Services ---
-API Gateway | t: Backend, description: Main entry point for all requests
+API Gateway | t: Backend
+  Main entry point for all requests
+  Routes to **backend services**
   -routes-> UserService
   -routes-> ProductService
   -routes-> OrderService
 
-UserService | t: Backend, description: Handles auth and profiles
+UserService | t: Backend
+  Handles auth and profiles
+  Uses `JWT` tokens for sessions
   -reads-> UserDB
   -checks-> SessionCache
 
 ProductService | t: Frontend, description: Product catalog and search
+  Supports *full-text* search
   -queries-> ProductDB
   -invalidates-> ProductCache
 
-OrderService | t: Backend, description: Order processing pipeline
+OrderService | t: Backend
+  Order processing pipeline
+  Validates inventory before commit
   -writes-> OrderDB
   -publishes-> OrderQueue
 

package/gallery/fixtures/c4-full.dgmo

@@ -1,12 +1,12 @@
 c4 Online Bookstore — C4 Architecture
 
-tag Technology alias tech
+tag Technology tech
   React(blue)
   Node(green)
   Python(orange)
   PostgreSQL(purple)
 
-tag Team alias t
+tag Team t
   Frontend(blue)
   Backend(green)
   Platform(teal)

package/gallery/fixtures/cycle/ooda-loop.dgmo

@@ -0,0 +1,25 @@
+cycle OODA Loop
+
+Observe | color: blue
+  Gather raw information from the environment
+  Monitor unfolding circumstances
+  -Unfold circumstances-> | color: blue
+    Synthesize raw data into actionable context
+    Identify **key patterns** and anomalies
+
+Orient | color: green
+  Analyze and synthesize observations
+  Form a mental model of the situation
+  -Form hypothesis-> | color: green
+    Apply previous experience and cultural filters
+    Perform *destructive deduction* to break old models
+
+Decide | color: orange
+  Select a course of action
+  -Commit to action-> | color: orange
+
+Act | color: red
+  Execute the chosen course of action
+  Generate results that feed back
+  -Generate feedback-> | color: red
+    Results flow back into observation

package/gallery/fixtures/cycle/pdca-circle-nodes.dgmo

@@ -0,0 +1,12 @@
+cycle PDCA
+
+circle-nodes
+
+Plan | color: blue
+  Define goals and processes
+Do | color: green
+  Implement the plan
+Check | color: orange
+  Evaluate results
+Act | color: red
+  Adjust and improve

package/gallery/fixtures/cycle/pdca-minimal.dgmo

@@ -0,0 +1,6 @@
+cycle PDCA
+
+Plan | color: blue
+Do | color: green
+Check | color: orange
+Act | color: red

package/gallery/fixtures/cycle/sprint-cycle-span.dgmo

@@ -0,0 +1,17 @@
+cycle Sprint Cycle
+
+Planning | color: blue, span: 1
+  Sprint kickoff and backlog grooming
+  -Start sprint->
+
+Development | color: green, span: 3
+  Build and test features
+  -Demo ready->
+
+Review | color: orange, span: 1
+  Sprint demo and stakeholder feedback
+  -Retrospective->
+
+Retro | color: purple, span: 0.5
+  Team reflection and process improvement
+  -Next sprint->

package/gallery/fixtures/gantt-full.dgmo

@@ -4,13 +4,13 @@ today-marker 2024-03-01
 critical-path
 dependencies
 
-tag Team alias t
+tag Team t
   Engineering(blue)
   Design(purple)
   QA(orange)
   Marketing(green)
 
-tag Phase alias p
+tag Phase p
   Foundation(green)
   Growth(orange)
   Launch(red)

package/gallery/fixtures/gantt.dgmo

@@ -4,12 +4,12 @@ today-marker 2024-03-01
 critical-path
 dependencies
 
-tag Team alias t
+tag Team t
   Engineering(blue)
   Design(purple)
   QA(orange)
 
-tag Phase alias p
+tag Phase p
   Foundation(green)
   Growth(orange)
 

package/gallery/fixtures/infra-full.dgmo

@@ -1,11 +1,11 @@
 infra E-Commerce Platform — Full Infrastructure
 
-tag Team alias t
+tag Team t
   Backend(blue)
   Platform(teal)
   Data(purple)
 
-tag Tier alias r
+tag Tier r
   Edge(green)
   Core(blue)
   Storage(orange)

package/gallery/fixtures/infra.dgmo

@@ -1,6 +1,6 @@
 infra Production Traffic Flow
 
-tag Team alias t
+tag Team t
   Backend(blue)
   Platform(teal)
 

package/gallery/fixtures/sequence-tags-protocols.dgmo

@@ -1,13 +1,13 @@
 sequence Order Fulfillment — Protocols & Ownership
 active-tag Protocol
 
-tag Protocol alias p
+tag Protocol p
   REST(blue)
   gRPC(green)
   Async(orange)
   SQL(purple)
 
-tag Owner alias o
+tag Owner o
   Checkout(teal)
   Fulfillment(orange)
   Payments(red)

package/gallery/fixtures/sequence-tags.dgmo

@@ -1,13 +1,13 @@
 sequence API Gateway — Infrastructure Concerns
 active-tag Concern
 
-tag Concern alias c
+tag Concern c
   Caching(blue)
   Auth(green)
   RateLimiting(orange)
   BusinessLogic(purple) default
 
-tag Team alias t
+tag Team t
   Platform(teal)
   Product(orange)
   Security(red)

package/gallery/fixtures/tech-radar-dense.dgmo

@@ -0,0 +1,77 @@
+tech-radar Dense Radar Stress Test
+
+rings
+  Adopt
+  Trial
+  Assess
+  Hold
+
+Techniques | quadrant: top-right
+  CI/CD | ring: Adopt, trend: stable
+  IaC | ring: Adopt, trend: stable
+  Microservices | ring: Adopt, trend: stable
+  Event Sourcing | ring: Trial, trend: up
+  CQRS | ring: Trial, trend: up
+  Feature Flags | ring: Adopt, trend: new
+  Chaos Engineering | ring: Assess, trend: new
+  Trunk-Based Dev | ring: Trial, trend: up
+  Contract Testing | ring: Trial, trend: new
+  Design Tokens | ring: Assess, trend: new
+  Micro Frontends | ring: Assess, trend: up
+  Server Components | ring: Trial, trend: new
+  Edge Functions | ring: Trial, trend: up
+  Zero Trust | ring: Adopt, trend: stable
+  Observability | ring: Adopt, trend: stable
+  Platform Engineering | ring: Trial, trend: new
+
+Tools | quadrant: top-left
+  GitHub Copilot | ring: Trial, trend: new
+  Vite | ring: Adopt, trend: up
+  Playwright | ring: Adopt, trend: stable
+  Turborepo | ring: Trial, trend: new
+  Docker | ring: Adopt, trend: stable
+  Grafana | ring: Adopt, trend: stable
+  Datadog | ring: Trial, trend: up
+  Webpack | ring: Hold, trend: down
+  Storybook | ring: Adopt, trend: stable
+  Figma | ring: Adopt, trend: stable
+  Linear | ring: Trial, trend: new
+  Pulumi | ring: Assess, trend: new
+  Tailscale | ring: Trial, trend: up
+  Renovate | ring: Adopt, trend: stable
+  Bruno | ring: Assess, trend: new
+  Cursor | ring: Trial, trend: new
+
+Platforms | quadrant: bottom-left
+  Kubernetes | ring: Adopt, trend: stable
+  Cloudflare Workers | ring: Trial, trend: up
+  AWS Lambda | ring: Hold, trend: down
+  Vercel | ring: Trial, trend: up
+  Fly.io | ring: Assess, trend: new
+  Neon | ring: Trial, trend: new
+  PlanetScale | ring: Hold, trend: down
+  Supabase | ring: Assess, trend: up
+  Upstash | ring: Trial, trend: new
+  Railway | ring: Assess, trend: new
+  Deno Deploy | ring: Assess, trend: new
+  Google Cloud Run | ring: Adopt, trend: stable
+  Azure AKS | ring: Trial, trend: up
+  Hetzner | ring: Assess, trend: new
+  Tigris | ring: Assess, trend: new
+
+Languages & Frameworks | quadrant: bottom-right
+  TypeScript | ring: Adopt, trend: stable
+  Rust | ring: Assess, trend: new
+  React | ring: Adopt, trend: stable
+  Go | ring: Adopt, trend: stable
+  Python | ring: Adopt, trend: stable
+  Svelte | ring: Assess, trend: up
+  Solid | ring: Assess, trend: new
+  Zig | ring: Hold, trend: stable
+  Kotlin | ring: Trial, trend: up
+  Swift | ring: Adopt, trend: stable
+  Astro | ring: Trial, trend: new
+  HTMX | ring: Assess, trend: new
+  Effect-TS | ring: Assess, trend: new
+  Bun | ring: Trial, trend: up
+  Deno | ring: Assess, trend: up

package/gallery/fixtures/tech-radar.dgmo

@@ -0,0 +1,36 @@
+tech-radar Engineering Tech Radar Q2 2026
+
+rings
+  Adopt
+  Trial
+  Assess
+  Hold
+
+Techniques | quadrant: top-right
+  Continuous Deployment | ring: Adopt, trend: stable
+    Fully adopted across all services.
+  Infrastructure as Code | ring: Adopt, trend: stable
+  Micro Frontends | ring: Trial, trend: up
+    Exploring for the portal project.
+  Trunk-Based Development | ring: Assess, trend: new
+
+Tools | quadrant: top-left
+  GitHub Copilot | ring: Trial, trend: new
+    Evaluating for developer productivity.
+  Vite | ring: Adopt, trend: up
+  Webpack | ring: Hold, trend: down
+    Migrating to Vite across all projects.
+  Playwright | ring: Adopt, trend: stable
+  Turborepo | ring: Trial, trend: new
+
+Platforms | quadrant: bottom-left
+  Kubernetes | ring: Adopt, trend: stable
+  Cloudflare Workers | ring: Trial, trend: up
+  AWS Lambda | ring: Hold, trend: down
+    Consolidating onto Kubernetes.
+
+Languages & Frameworks | quadrant: bottom-right
+  TypeScript | ring: Adopt, trend: stable
+  Rust | ring: Assess, trend: new
+    Evaluating for performance-critical services.
+  React | ring: Adopt, trend: stable

package/gallery/fixtures/timeline.dgmo

@@ -1,7 +1,7 @@
 timeline Product Roadmap 2024-2025
 sort tag:Team
 
-tag Team alias t
+tag Team t
   Engineering(blue)
   Design(purple)
   Product(green)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.8.20",
+  "version": "0.8.22",
   "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 },