@diagrammo/dgmo 0.8.21 → 0.8.23

package/docs/guide/chart-cycle.md

@@ -0,0 +1,156 @@
+# Cycle Diagram
+
+```dgmo
+cycle OODA Loop
+
+Observe | color: blue
+  Gather raw information from the environment
+  Monitor unfolding circumstances
+  -Unfold circumstances-> | color: blue
+
+Orient | color: green
+  Analyze and synthesize observations
+  Form a mental model of the situation
+  -Form hypothesis-> | color: green
+
+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
+```
+
+## Overview
+
+Cycle diagrams show a circular process flow where nodes are arranged on a circle and directed edges connect each to the next, with the last wrapping back to the first. They are ideal for OODA loops, PDCA cycles, product lifecycles, continuous improvement processes, and any workflow that repeats.
+
+## Syntax
+
+```
+cycle Title
+
+NodeLabel
+NodeLabel | color: blue, span: 2
+```
+
+The first line declares the chart type and title. Each top-level line declares a node. Nodes are positioned around a circle in declaration order.
+
+## Nodes
+
+Every non-indented, non-directive line is a node:
+
+```
+cycle Seasons
+
+Spring | color: green
+Summer | color: yellow
+Autumn | color: orange
+Winter | color: blue
+```
+
+### Node Pipe Metadata
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `color` | palette name | auto | Node fill color |
+| `span` | positive number | `1` | Relative arc distance to next node |
+| `description` | string | — | One-liner shown below the label |
+
+### Descriptions
+
+Indented lines under a node add description text. Markdown inline formatting is supported (`**bold**`, `*italic*`, `` `code` ``, `[links](url)`). Bullet points with `- item` render as `• item`.
+
+```
+Observe | color: blue
+  Gather raw information from the environment
+  Monitor unfolding circumstances
+```
+
+If both `| description: text` and indented lines exist, they concatenate (pipe first, then indented).
+
+## Edges
+
+Edges are **implicit** — every node connects to the next, with the last wrapping to the first. The `->` syntax annotates edges with labels, descriptions, and styling:
+
+```
+Observe | color: blue
+  -Unfold circumstances-> | color: blue
+    Synthesize raw data into context
+
+Orient | color: green
+  -> | width: 4
+```
+
+Edge lines are indented under their source node. A label goes between `-` and `->`. Pipe metadata supports `color` and `width`.
+
+### Edge Descriptions
+
+Indented lines under an edge line add description text:
+
+```
+Observe
+  -Analyze->
+    Break down observations into components
+    Identify **key patterns**
+```
+
+## Span
+
+The `span` metadata controls relative arc distance between nodes. A node with `span: 2` gets twice the arc space to the next node:
+
+```
+cycle Weighted Process
+
+Important Step | span: 2
+Quick Step
+Another Step | span: 1.5
+```
+
+## Directives
+
+| Directive | Effect |
+|-----------|--------|
+| `direction-counterclockwise` | Reverse cycle direction (default: clockwise) |
+| `hide-descriptions` | Hide description text on all nodes and edges |
+| `circle-nodes` | Render nodes as circles instead of rounded rectangles |
+
+```
+cycle Simple Loop
+
+direction-counterclockwise
+
+Plan
+Do
+Check
+Act
+```
+
+## Complete Example
+
+```dgmo
+cycle PDCA Continuous Improvement
+
+Plan | color: blue, span: 1.5
+  Define objectives and processes
+  Establish expected outcomes
+  -Start implementation->
+
+Do | color: green
+  Execute the plan on a small scale
+  Collect data for analysis
+  -Gather results->
+
+Check | color: orange
+  Compare results against expectations
+  Identify deviations and root causes
+  -Propose changes-> | color: orange
+
+Act | color: red
+  Standardize successful changes
+  Address remaining gaps
+  -Feed back into planning-> | color: red
+    Begin the next improvement cycle
+```

package/docs/guide/chart-journey-map.md

@@ -0,0 +1,179 @@
+# Journey Map
+
+```dgmo
+journey-map Coffee Shop Visit
+
+[Order]
+  Walk in | 4
+  Wait in line | 2
+  Order drink | 4
+
+[Wait]
+  Find a seat | 3
+  Wait for drink | 2
+
+[Enjoy]
+  Get drink | 5
+```
+
+## Overview
+
+Journey maps visualize a user's experience across a process or service, plotting emotional highs and lows as a continuous curve. Each step has a score (1–5, high is good) that drives the emotion landscape. Phases group related steps, annotations capture pain points, opportunities, and thoughts, and tags add cross-cutting dimensions like channel or touchpoint.
+
+Journey maps are ideal for UX research, customer experience mapping, service design, and identifying friction points.
+
+## Syntax
+
+```
+journey-map Title
+
+persona Name
+
+[Phase Name]
+  Step Name | score
+  Step Name | score Emotion
+```
+
+The first line must be `journey-map` followed by a title. Phases use bracket syntax at indent 0. Steps are indented within phases.
+
+## Persona
+
+Declares the journey's protagonist:
+
+```
+persona Tech-Savvy Shopper
+  28yo developer, price-sensitive, does extensive research
+```
+
+Name is everything after `persona `. Indented lines add description text. Only one persona per diagram.
+
+## Phases
+
+Phases group steps into logical stages:
+
+```
+[Research]
+  Compare specs | 4
+  Watch reviews | 5
+
+[Purchase]
+  Add to cart | 3
+  Complete payment | 3
+```
+
+Phases are optional — steps can appear at root level for a flat continuous flow.
+
+## Steps
+
+Steps appear indented within phases (or at indent 0 in flat mode).
+
+### Score Syntax
+
+The score goes in the pipe, separating step name from data:
+
+```
+Step Name | 4                        // bare score
+Step Name | 4 Delighted              // score + emotion label
+Step Name | 4, ch: Web               // score + tag metadata
+Step Name | 4 Delighted, ch: Web     // score + label + metadata
+Step Name | score: 4, ch: Web        // explicit score key
+Step Name                            // no pipe = scoreless step
+```
+
+- **Score scale**: 1–5 integer (high = good)
+- **Emotion label**: optional single word after the score (e.g., `Frustrated`, `Delighted`, `Neutral`)
+- **Scoreless steps**: render as cards but produce no emotion curve point
+
+## Annotations
+
+Deeper-indented lines under a step add context:
+
+```
+  Forced account creation | 1 Frustrated
+    pain: Wants guest checkout
+    opportunity: Add guest checkout option
+    thought: Why do I need an account?
+    description: User abandoned cart twice
+```
+
+| Prefix | Rendering |
+|--------|-----------|
+| `pain:` | Pain point (red accent) |
+| `opportunity:` | Improvement opportunity (green accent) |
+| `thought:` | User thought (italic) |
+| `description:` | General context text |
+
+Multiple annotations per step are allowed.
+
+## Tag Groups
+
+Tags add color-coded dimensions like channel or touchpoint:
+
+```
+tag Channel ch
+  Web(blue)
+  Mobile(purple)
+  In-Person(green)
+
+[Research]
+  Compare specs | 4, ch: Web
+  Ask friends | 4, ch: In-Person
+```
+
+Reference tag values in step pipes via the alias.
+
+## Flat Mode
+
+Steps at root level (no `[Phase]` brackets) render as a continuous horizontal strip:
+
+```dgmo
+journey-map Quick Feedback
+
+Opened app | 4
+Searched for feature | 3
+Hit error | 1 Frustrated
+  pain: No helpful error message
+Contacted support | 2
+Got resolution | 5 Relieved
+```
+
+## Directives
+
+| Directive | Effect |
+|-----------|--------|
+| `no-legend` | Hide the score legend |
+| `active-tag GroupName` | Set the active tag group for coloring |
+
+## Complete Example
+
+```dgmo
+journey-map Buying a Laptop
+
+persona Tech-Savvy Shopper
+  28yo developer, price-sensitive, does extensive research
+
+tag Channel ch
+  Web(blue)
+  Mobile(purple)
+  Email(teal)
+  In-Person(green)
+
+[Research]
+  Compare specs | 4, ch: Web
+    description: Checked 12 laptops across 4 review sites
+  Watch reviews | 5 Engaged, ch: Mobile
+  Ask friends | 4, ch: In-Person
+
+[Purchase]
+  Add to cart | 3, ch: Web
+  Forced account creation | 1 Frustrated, ch: Web
+    pain: Wants guest checkout
+    pain: Password requirements too strict
+  Complete payment | 3, ch: Web
+
+[Delivery]
+  Track package | 4, ch: Mobile
+  Unboxing | 5 Delighted, ch: In-Person
+    opportunity: Include setup guide
+    thought: Excited to try it out
+```

package/docs/guide/chart-pyramid.md

@@ -0,0 +1,111 @@
+# Pyramid Diagram
+
+```dgmo
+pyramid Maslow's Hierarchy of Needs
+
+Self-Actualization | color: purple
+  Morality, creativity, acceptance of facts.
+
+Esteem | color: blue
+  Respect, recognition, confidence.
+
+Love & Belonging | color: green
+  Friendship, intimacy, family.
+
+Safety | color: yellow
+  Security, employment, health.
+
+Physiological | color: orange
+  Food, water, warmth, rest.
+```
+
+## Overview
+
+Pyramid diagrams show a hierarchy of stacked layers. Each layer gets a colored band with a label and an optional description. Source order reads apex-first — the first layer in the file is the narrowest (visual top), the last is the widest (visual bottom). Use `inverted` to flip into a funnel orientation.
+
+## Syntax
+
+```
+pyramid Title
+
+LayerLabel
+LayerLabel | color: blue
+LayerLabel | color: green
+  Indented description
+```
+
+The first line declares the chart type and an optional title. Each non-indented, non-directive line declares one layer. At least two layers are required.
+
+## Layers
+
+```
+pyramid Roles
+
+Executives | color: purple
+Managers | color: blue
+Individual Contributors | color: green
+```
+
+### Layer Pipe Metadata
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `color` | palette name | auto-assigned | Layer color |
+| `description` | string | — | One-liner shown beside the layer |
+
+### Descriptions
+
+Indented lines under a layer add description text. Markdown inline formatting is supported (`**bold**`, `*italic*`, `` `code` ``, `[links](url)`). Bullet points with `- item` render as `• item`.
+
+```
+Wisdom | color: purple
+  Ethical judgment, acting with insight.
+  - Knowing *why* something matters
+  - Acting with long-term perspective
+```
+
+If both `| description: text` and indented lines exist, they concatenate (pipe first, then indented).
+
+## Directives
+
+| Directive | Effect |
+|-----------|--------|
+| `inverted` | Flip apex to the bottom (funnel orientation). Source order is preserved — the first layer is always the visual top. |
+
+```
+pyramid Acquisition Funnel
+
+inverted
+
+Visitors | color: blue
+Signups | color: cyan
+Activated | color: green
+Paid | color: orange
+```
+
+## Overflow Handling
+
+When descriptions don't fit a layer's band, the renderer automatically:
+
+- **Wraps** text at the column edge so nothing leaves the canvas
+- **Truncates** with "…" when content exceeds the available lines
+- **Alternates** descriptions left ↔ right when a single column can't hold them
+- **Reveals** the full description when a layer is highlighted (in-app), hiding siblings so it has room
+
+## Complete Example
+
+```dgmo
+pyramid The DIKW Pyramid
+
+Wisdom | color: purple
+  Ethical judgment, acting with insight — knowing *why*.
+
+Knowledge | color: blue
+  Synthesized information — knowing *how*.
+
+Information | color: green
+  Processed data with context — knowing *what*.
+
+Data | color: yellow
+  Raw facts and measurements — unprocessed signals.
+```

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
+```