@diagrammo/dgmo 0.8.21 → 0.8.22

package/docs/guide/chart-sitemap.md

@@ -7,7 +7,7 @@ tag Auth
   Public(green)
   Crew Only(blue)
 
-Home | Auth: Public
+Home | Auth: Public, description: Landing page with interactive demos
   -shop-> Shop
   -voyages-> Upcoming Voyages
   -join crew-> Sign Up
@@ -39,6 +39,7 @@ Home | Auth: Public
   Sign Up | Auth: Public
     -welcome aboard-> Dashboard
   Dashboard | Auth: Crew Only
+    description Full overview of crew activity and orders
     -> My Orders
   My Orders | Auth: Crew Only
     -reorder-> Shop
@@ -140,6 +141,22 @@ Home | status: Live | owner: Marketing
 Products | status: Draft | owner: Product Team
 ```
 
+## Descriptions
+
+Add a description to any page using the `description` keyword (indented) or pipe metadata:
+
+```
+// Pipe metadata form
+Pricing | description: Compare plans and features
+
+// Indented keyword form (colon optional)
+Dashboard
+  description Full overview of crew activity and orders
+  My Orders
+```
+
+Descriptions render as secondary text on the page card. The indented form must come before child pages. Multiple `description` lines accumulate into a multi-line description.
+
 ## Node Colors
 
 Add a color name in parentheses after a page or group name:

package/docs/guide/chart-tech-radar.md

@@ -0,0 +1,219 @@
+# Technology Radar
+
+```dgmo
+tech-radar Pirate Operations Radar — Q2 1718
+
+rings
+  Full Sail
+  Trial Run
+  Spyglass
+  Davy Jones
+
+Tactics | quadrant: top-right
+  Ambush at Dawn | ring: Full Sail, trend: stable
+    Our most reliable boarding tactic. **90% success rate** when
+    approaching from the east with the sun behind us.
+    - Crew morale peaks at dawn — grog hasn't worn off yet
+    - Reduced cannon fire needed: *3 volleys* vs 8 at midday
+  Boarding Parties | ring: Full Sail, trend: stable
+  Decoy Flags | ring: Trial Run, trend: up
+    Flying false colours until within cannon range. Early results
+    are promising — merchant ships drop anchor **40% more often**.
+  Smoke Screens | ring: Trial Run, trend: new
+  Kraken Diplomacy | ring: Spyglass, trend: new
+    Exploring alliances with *sea monsters*. Negotiations ongoing.
+
+Vessels | quadrant: top-left
+  Brigantine | ring: Full Sail, trend: stable
+    Our workhorse. Fast, manoeuvrable, carries **18 cannons**.
+    - Crew capacity: 100 pirates
+    - Top speed: *11 knots* in fair wind
+  Sloop | ring: Full Sail, trend: up
+  War Galleon | ring: Trial Run, trend: up
+    Captured from the Spanish fleet. Massive firepower but
+    **slow to turn** — best for convoy raids, not chases.
+  Longboat | ring: Davy Jones, trend: down
+
+Plunder Targets | quadrant: bottom-left
+  Merchant Convoys | ring: Full Sail, trend: stable
+    Core revenue stream — **78% of total plunder**. East India
+    Company ships running the spice route remain most lucrative.
+  Port Raids | ring: Trial Run, trend: up
+  Rival Pirates | ring: Trial Run, trend: new
+  Royal Treasury Ships | ring: Spyglass, trend: new
+    High risk, astronomical reward. Requires:
+    - Inside information from *corrupt harbourmasters*
+    - At least **3 allied ships** for the blockade
+    - A really good escape plan
+  Whaling Ships | ring: Spyglass, trend: stable
+  Fishing Villages | ring: Davy Jones, trend: down
+    Terrible ROI and **bad for reputation**. The parrot union
+    filed a formal complaint.
+
+Crew Welfare | quadrant: bottom-right
+  Grog Rations | ring: Full Sail, trend: stable
+    Non-negotiable. Cutting grog rations caused the *Great Mutiny of 1716*.
+  Sea Shanty Program | ring: Trial Run, trend: new
+    Hired a shanty master. Crew productivity up **25%** during
+    long voyages. Signature tune: *"Yo Ho Ho and a Bottle of Rum"*.
+  Dental Plan | ring: Spyglass, trend: up
+    Exploring options. Most crew down to **4 teeth** on average.
+    Parley with a Port Royal dentist scheduled for Q3.
+```
+
+## Overview
+
+Technology radars visualize how an organization adopts and evaluates technologies, practices, or strategies. Inspired by the [ThoughtWorks Technology Radar](https://www.thoughtworks.com/radar), each radar arranges items ("blips") into concentric rings indicating adoption stage, grouped by quadrant categories.
+
+Click any quadrant label to drill down into a detail view with expanded blip descriptions. Click the "Blip Legend" toggle to show or hide the numbered reference listing below the radar.
+
+## Syntax
+
+```
+tech-radar Title
+
+rings
+  Ring1
+  Ring2
+
+Quadrant Name | quadrant: position
+  Blip Name | ring: RingName, trend: value
+    Description text (markdown supported)
+```
+
+## Settings
+
+| Key | Description | Default |
+| --- | ----------- | ------- |
+| `chart` | Must be `tech-radar` | — |
+| `title` | Radar title | None |
+
+## Rings
+
+Rings represent adoption stages, ordered from innermost (highest commitment) to outermost (lowest). Declare them in a `rings` block:
+
+```
+rings
+  Adopt
+  Trial
+  Assess
+  Hold
+```
+
+You can use any ring names — the classic Adopt/Trial/Assess/Hold is common but not required.
+
+### Ring Aliases
+
+Rings support aliases for shorter blip references:
+
+```
+rings
+  Adopt alias a
+  Trial alias t
+  Assess alias x
+  Hold alias h
+
+Quadrant | quadrant: top-right
+  Item Name | ring: a, trend: up
+```
+
+## Quadrants
+
+Exactly 4 quadrants are required. Each needs a unique position:
+
+```
+Techniques | quadrant: top-right
+Tools | quadrant: top-left
+Platforms | quadrant: bottom-left
+Languages | quadrant: bottom-right
+```
+
+**Positions:** `top-left`, `top-right`, `bottom-left`, `bottom-right`
+
+### Custom Colors
+
+Override the default quadrant color with `color`:
+
+```
+Tools | quadrant: top-left, color: purple
+```
+
+Default colors: top-left=blue, top-right=green, bottom-left=red, bottom-right=orange.
+
+## Blips
+
+Blips are items placed on the radar. Each is indented under its quadrant and requires a `ring` reference:
+
+```
+  Kubernetes | ring: Adopt
+  Micro Frontends | ring: Trial, trend: up
+```
+
+Ring matching is case-insensitive — `ring: adopt` and `ring: Adopt` both work.
+
+## Trends
+
+The optional `trend` metadata controls the visual indicator on each blip:
+
+| Trend | Indicator | Meaning |
+| ----- | --------- | ------- |
+| `new` | Double circle | Newly added to the radar |
+| `up` | Inward crescent | Moving toward center (higher adoption) |
+| `down` | Outward crescent | Moving away from center (declining) |
+| `stable` | Plain circle | No change since last assessment |
+
+Omitting `trend` renders a plain circle (same as `stable`).
+
+## Descriptions
+
+Further-indented lines below a blip become its description. Descriptions support inline markdown:
+
+```
+  Rust | ring: Assess, trend: new
+    Evaluating for **performance-critical** services.
+    Key benefits: *zero-cost abstractions* and `no GC pauses`.
+    - 12x throughput improvement in image pipeline
+    - See [evaluation doc](https://wiki.example.com/rust)
+```
+
+Descriptions appear in the quadrant detail view and on hover/click in the main radar view.
+
+## Complete Example
+
+```dgmo
+tech-radar Fleet Readiness Radar
+
+rings
+  Battle Ready
+  Sea Trials
+  Scouting
+  Scuttle
+
+Navigation | quadrant: top-right
+  Star Charts | ring: Battle Ready, trend: stable
+  Compass Calibration | ring: Sea Trials, trend: up
+    New lodestone from Madagascar shows **30% better accuracy**.
+  Sextant | ring: Battle Ready, trend: stable
+  Treasure Maps | ring: Scouting, trend: new
+  Celestial Tables | ring: Scouting, trend: new
+
+Armaments | quadrant: top-left
+  Cannon Broadside | ring: Battle Ready, trend: stable
+  Greek Fire | ring: Sea Trials, trend: new
+  Chain Shot | ring: Sea Trials, trend: up
+  Catapult | ring: Scuttle, trend: down
+
+Provisions | quadrant: bottom-left
+  Salted Pork | ring: Battle Ready, trend: stable
+  Citrus Rations | ring: Sea Trials, trend: up
+    Reduced scurvy cases by **80%** in trial crews.
+  Rum Distillation | ring: Scouting, trend: new
+  Hardtack | ring: Scuttle, trend: down
+  Barnacle Soup | ring: Scuttle, trend: down
+
+Morale | quadrant: bottom-right
+  Shore Leave | ring: Battle Ready, trend: stable
+  Sea Shanties | ring: Battle Ready, trend: up
+  Parrot Companions | ring: Scouting, trend: new
+  Plank Walking | ring: Scuttle, trend: down
+```

package/docs/guide/registry.json

@@ -42,6 +42,7 @@
     { "slug": "chart-org", "title": "Org Chart", "group": "business", "file": "chart-org.md" },
     { "slug": "chart-quadrant", "title": "Quadrant Chart", "group": "business", "file": "chart-quadrant.md" },
     { "slug": "chart-sankey", "title": "Sankey Diagram", "group": "business", "file": "chart-sankey.md" },
+    { "slug": "chart-tech-radar", "title": "Technology Radar", "group": "business", "file": "chart-tech-radar.md" },
     { "slug": "chart-venn", "title": "Venn Diagram (Beta)", "group": "business", "file": "chart-venn.md" },
     { "slug": "chart-wordcloud", "title": "Word Cloud", "group": "business", "file": "chart-wordcloud.md" },
 

package/docs/language-reference.md

@@ -20,8 +20,9 @@
 14. [Timeline Diagrams](#14-timeline-diagrams)
 15. [Data Charts](#15-data-charts)
 16. [Visualizations](#16-visualizations)
-17. [Wireframe Diagrams](#17-wireframe-diagrams)
-18. [Colon Usage Summary](#18-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)
 
 ---
 
@@ -609,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)
 
@@ -813,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)
 
@@ -1327,7 +1370,73 @@ Navigator 0.85 0.8
 
 ---
 
-## 17. Wireframe Diagrams
+## 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.
 
@@ -1461,7 +1570,7 @@ wireframe Login Page
 
 ---
 
-## 18. Colon Usage Summary
+## 19. Colon Usage Summary
 
 ### Constructs Where Colons Are REQUIRED
 
@@ -1480,6 +1589,7 @@ wireframe Login Page
 | 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)