@diagrammo/dgmo 0.8.12 → 0.8.13

package/docs/guide/chart-sankey.md

@@ -0,0 +1,103 @@
+# Sankey Diagram
+
+```dgmo
+sankey Rum Supply Chain of the Caribbean
+
+Sugar Plantations(green)
+  Tortuga Distillery(orange) 3000
+  Nassau Distillery(orange) 2500
+  Kingston Distillery(orange) 2000
+
+Tortuga Distillery
+  Pirate Taverns(red) 2000
+  Ship Provisions(teal) 1000
+
+Nassau Distillery
+  Pirate Taverns 1500
+  Black Market(purple) 1000
+
+Kingston Distillery
+  Royal Navy(blue) 1200
+  Pirate Taverns 800
+
+Pirate Taverns
+  Crew Morale 3500
+  Bar Fights 800 (red)
+
+Ship Provisions -> Long Voyages 1000
+```
+
+## Syntax
+
+### Arrow syntax
+
+```
+sankey Chart Title
+
+Source -> Target value
+```
+
+### Indentation syntax
+
+```
+sankey
+
+Source
+  Target A 300
+  Target B 200
+
+Target A
+  Sub-target 150
+```
+
+Indent targets under a bare source label. Both syntaxes can be mixed in the same diagram.
+
+## Color Annotations
+
+### Node colors
+
+Add `(color)` after a node name to color that node:
+
+```
+Revenue(green)
+  Costs(red) 600
+  Profit(blue) 400
+
+// or with arrows
+Revenue(green) -> Costs(red) 600
+```
+
+Uncolored nodes use the palette's default series colors.
+
+### Link colors
+
+Add `(color)` after the value to color a specific link:
+
+```
+Revenue
+  Costs 600 (orange)
+
+// or with arrows
+Revenue -> Costs 600 (orange)
+```
+
+Uncolored links use a gradient between their source and target node colors.
+
+## Metadata Keys
+
+| Key     | Description                           | Required |
+| ------- | ------------------------------------- | -------- |
+| `chart` | Must be `sankey`                      | Yes      |
+| `title` | Chart title displayed above the chart | No       |
+
+## Data Format
+
+Each data line defines a flow from source to target with a numeric value:
+
+```
+Sugar Plantations -> Distillery 3000
+Distillery -> Taverns 2000
+Distillery -> Ship Provisions 1000
+```
+
+Nodes are created automatically from the source and target names. The same node can appear as both a source and a target to create multi-level flows.

package/docs/guide/chart-scatter.md

@@ -0,0 +1,94 @@
+# Scatter Plot
+
+```dgmo
+scatter Cannon Range vs Powder Charge
+x-label Powder (lbs)
+y-label Range (yards)
+
+// label: x, y
+Long Tom: 12, 1800
+Demi-Culverin: 8, 1200
+Carronade: 4, 400
+Swivel Gun: 2, 250
+Nine-Pounder: 6, 900
+Eighteen-Pounder: 10, 1500
+Basilisk: 14, 2000
+Falconet: 3, 350
+Minion: 5, 700
+Saker: 7, 1050
+```
+
+## Syntax
+
+```
+scatter Chart Title
+x-label X Axis Label
+y-label Y Axis Label
+no-labels
+size-label Size Legend Label
+
+// label: x, y
+Point Name: x, y
+
+// or with size (bubble chart)
+// label: x, y, size
+Point Name: x, y, size
+```
+
+## Metadata Keys
+
+| Key          | Description                                                | Required |
+| ------------ | ---------------------------------------------------------- | -------- |
+| `chart`      | Must be `scatter`                                          | Yes      |
+| `title`      | Chart title displayed above the chart                      | No       |
+| `x-label`    | Label for the X axis                                       | No       |
+| `y-label`    | Label for the Y axis                                       | No       |
+| `no-labels`  | Hide point labels (labels are on by default)               | No       |
+| `size-label` | Label for the size dimension (shown in legend for bubbles) | No       |
+
+## Data Format
+
+Each data line provides X and Y values, with an optional third value for bubble size:
+
+```
+// 2D scatter
+Point A: 12, 1800
+Point B: 8, 1200
+
+// 3D bubble
+Point A: 85, 90, 80
+Point B: 45, 55, 35
+```
+
+## Category Groups
+
+Use `[Category Name](color)` headers to group points into colored categories:
+
+```
+[English Pirates](red)
+Blackbeard: 85, 90, 80
+Calico Jack: 45, 55, 35
+
+[French Buccaneers](blue)
+L'Olonnais: 70, 80, 60
+```
+
+## Variants
+
+### Bubble Chart
+
+Add a third value per data point and use `sizelabel` to label the size dimension:
+
+```dgmo
+scatter Pirate Fleets of the Caribbean
+size-label Crew
+
+[English Pirates](red)
+Blackbeard: 85, 90, 80
+Calico Jack: 45, 55, 35
+Anne Bonny: 50, 70, 30
+
+[French Buccaneers](blue)
+L'Olonnais: 70, 80, 60
+Pierre le Grand: 30, 45, 25
+```

package/docs/guide/chart-sequence.md

@@ -0,0 +1,332 @@
+# Sequence Diagram
+
+```dgmo
+sequence Treasure Hunt App
+
+User -Search nearby loot-> WebApp
+WebApp -GET /treasures?nearby-> TreasureAPI | c: Search
+note
+  - check location
+  - use compass
+  - http://example.com
+TreasureAPI -Find within 5nm-> MapDB | c: Search
+MapDB -3 results-> TreasureAPI
+TreasureAPI -locations-> WebApp
+WebApp -Show treasure map-> User
+```
+
+Notice that `User` renders as a stick figure, `OrderDB` as a cylinder, `WebApp` as a monitor, and `PaymentGateway` as a hexagon — all inferred automatically from the names. No declarations needed.
+
+## Overview
+
+The sequence diagram uses an **inference-driven** syntax. Just write messages between participants and Diagrammo automatically:
+
+- **Creates participants** from their first mention — no declarations needed
+- **Infers participant shapes** from naming conventions — `User` gets a stick figure, `OrderDB` gets a cylinder, `API` gets a rounded box
+- **Tracks activation bars** from call stacks
+
+No `end` keywords are needed — blocks are scoped by indentation.
+
+## Syntax
+
+```
+sequence Diagram Title
+no-activations
+
+== Section Label ==
+
+A -message-> B
+A ~async message~> B
+
+if condition
+  A -message-> B
+else
+  A -alternative-> C
+
+loop description
+  A -retry-> B
+```
+
+## Settings
+
+| Key              | Description                             | Default  |
+| ---------------- | --------------------------------------- | -------- |
+| `chart`          | `sequence` (inferred from `->` content) | Optional |
+| `title`          | Diagram title                           | None     |
+| `no-activations` | Hide activation bars (on by default)    | off      |
+| `active-tag`     | Tag group to activate on load           | None     |
+| `collapse-notes` | Collapse notes by default               | off      |
+
+## Participants
+
+### Automatic Type Inference
+
+Participants are created automatically when first mentioned in a message. Their shape is inferred from the name — just use descriptive names and Diagrammo does the rest:
+
+```
+User -createOrder-> OrderService
+OrderService -save-> OrderDB
+OrderService -cache result-> Redis
+OrderService ~publish event~> EventBus
+```
+
+This creates five participants, each with a different shape — no declarations needed.
+
+The inference rules are checked in priority order (first match wins):
+
+| Type         | Shape               | Naming Patterns                                                                                      |
+| ------------ | ------------------- | ---------------------------------------------------------------------------------------------------- |
+| `actor`      | Stick figure        | `User`, `Customer`, `Client`, `Admin`, `Guest`, `Visitor`, `Operator`                                |
+| `database`   | Cylinder            | Names ending in `DB`; `Database`, `Store`, `Storage`, `Repo`, `Postgres`, `MySQL`, `Mongo`, `Dynamo` |
+| `cache`      | Dashed cylinder     | `Cache`, `Redis`, `Memcache`                                                                         |
+| `queue`      | Horizontal cylinder | `Queue`, `Kafka`, `RabbitMQ`, `EventBus`, `SQS`, `SNS`, `PubSub`, `Topic`, `Stream`                  |
+| `networking` | Hexagon             | `Gateway`, `Proxy`, `CDN`, `LoadBalancer`, `Firewall`, `DNS`, `Ingress`                              |
+| `frontend`   | Monitor             | `WebApp`, `Dashboard`, `MobileApp`, `Browser`, `CLI`, `Terminal`                                     |
+| `service`    | Rounded rectangle   | `Service`, `API`, `Lambda`, `Handler`, `Controller`, `Processor`, `Worker`                           |
+| `external`   | Dashed rectangle    | `External`, `ThirdParty`, `Vendor`                                                                   |
+| `default`    | Rectangle           | Anything unrecognized                                                                                |
+
+Names like `Router`, `Scheduler`, `Controller`, `Handler`, `Worker`, etc. are treated as services (not actors), even though they end in `-er`.
+
+### Explicit Declarations (Optional)
+
+You only need explicit declarations when you want to **override** the inferred type, set a **display alias**, or control **position**:
+
+```
+// Override type when the name doesn't match conventions
+Stripe is an external
+
+// Set a display alias for a cleaner label
+PaymentGW is a networking aka "Payment Gateway"
+
+// Control left-to-right ordering
+OrderDB position -1
+```
+
+Position `0` is leftmost, `-1` is rightmost. Unpositioned participants appear in first-mention order.
+
+## Messages
+
+### Call Arrows
+
+A solid arrow from one participant to another:
+
+```
+User -login-> API
+```
+
+### Return Arrows
+
+Return arrows are generated automatically from the call stack. When A calls B, a dashed return arrow from B back to A appears once B's work is done:
+
+```
+User -login-> API
+API -query-> UserDB
+// Auto-return: UserDB → API (dashed)
+// Auto-return: API → User (dashed)
+```
+
+### Async / Fire-and-Forget
+
+No return arrow, no activation on the target — use the `~` arrow:
+
+```
+API ~sendWelcomeEmail~> EmailService
+API ~logEvent~> LogService
+```
+
+### Self-Calls
+
+A participant calling itself renders as a loopback arrow:
+
+```
+OrderService -validate-> OrderService
+```
+
+## Blocks
+
+Blocks use **indentation** for scoping — no `end` keyword needed.
+
+### If / Else
+
+```
+if user authenticated
+  API -getOrders-> OrderService
+  OrderService -query-> OrderDB
+else
+  API -401 Unauthorized-> User
+```
+
+Renders as a dashed frame with an `if` label and an optional `else` divider.
+
+### Loop
+
+```
+loop retry up to 3 times
+  OrderService -request-> ExternalAPI
+```
+
+### Parallel
+
+```
+parallel send notifications
+  API ~email~> EmailService
+  API ~text~> SMSService
+```
+
+Blocks can nest inside each other. Unindent to end a block.
+
+## Notes
+
+Add context between messages with `note`:
+
+```
+User -POST /login-> API
+note Validates credentials against LDAP
+API -query-> UserDB
+```
+
+The note appears between the two surrounding messages.
+
+## Sections
+
+Full-width horizontal dividers to organize phases:
+
+```
+== Authentication ==
+
+User -login-> API
+
+== Data Fetch ==
+
+API -query-> OrderDB
+
+== Response ==
+
+API -results-> User
+```
+
+## Groups
+
+Organize participants into labeled boxes in the header:
+
+```
+[Backend]
+  OrderService
+  PaymentService
+  OrderDB
+
+[Frontend]
+  WebApp
+  MobileApp
+```
+
+- `[Name]` declares a named group
+- Indented names belong to the group
+- Grouped participants stay adjacent in the layout
+- Groups can carry tag metadata: `[Backend | team: Product]`
+
+## Activation Bars
+
+Thin vertical rectangles on lifelines show when a participant has an active call. They are computed automatically from the call stack:
+
+- Appear from call arrow to auto-generated return
+- Nested calls show overlapping bars
+- Self-calls show offset overlapping bars
+- Disabled with `no-activations`
+
+## Comments
+
+```
+// This is a comment
+// Use // for all comments
+```
+
+Lines starting with `//` are ignored by the parser.
+
+## Tags
+
+Tags add color-coded metadata dimensions to sequence diagrams. Define a tag group, list its values with colors, then attach values to participants, messages, and groups with pipe metadata.
+
+### Defining Tag Groups
+
+```
+tag Concern alias c
+  Caching(blue)
+  Auth(green)
+  BusinessLogic(purple) default
+```
+
+- `tag Name` declares a tag group; `alias x` adds a shorthand
+- Each entry: `Value(color)` — named color for that value
+- `default` on an entry applies it to untagged elements when the group is active
+
+### Attaching Tags
+
+Use `| key: value` after participant declarations, message lines, or group headers:
+
+```
+API is a service | concern: Caching, team: Platform
+User -login-> API | concern: Auth
+[Backend | concern: BusinessLogic]
+  OrderAPI
+  DB
+```
+
+- Multiple tags: `| key1: val1, key2: val2`
+- Aliases work: `| c: Caching` (if `alias c` was declared)
+
+### Tag Resolution
+
+When a tag group is active, colors are resolved in priority order:
+
+1. Explicit metadata on the element
+2. Group propagation (participant inherits from its group)
+3. Receiver inheritance (all incoming tagged messages agree on the same value)
+4. `default` entry value
+5. Neutral (no color)
+
+### Legend
+
+A legend is rendered automatically above participants when tag groups exist. The active group expands to show colored entry dots. In the desktop app, click a group pill to activate it — participants and messages recolor to show that dimension.
+
+Set `active-tag GroupName` in settings to activate a group on load.
+
+## Complete Example
+
+```dgmo
+sequence E-Commerce Checkout
+
+tag Layer alias l
+  Frontend(teal)
+  Backend(blue)
+  Storage(purple)
+
+[Backend]
+  OrderService
+  PaymentGateway
+  OrderDB
+
+== Browse & Select ==
+
+User -Add items to cart-> WebApp
+WebApp -validateCart-> OrderService
+
+== Payment ==
+
+User -Submit payment-> WebApp
+WebApp -createOrder-> OrderService
+OrderService -charge(amount)-> PaymentGateway
+
+if payment successful
+  OrderService -saveOrder-> OrderDB
+  OrderService ~sendReceipt~> EmailService
+  WebApp -Order confirmed-> User
+else
+  WebApp -Payment declined-> User
+
+== Cleanup ==
+
+loop expire stale carts
+  OrderService -purgeExpired-> OrderDB
+```