@diagrammo/dgmo 0.8.20 → 0.8.22

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-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/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/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" },