@diagrammo/dgmo 0.8.11 → 0.8.13

package/docs/guide/chart-arc.md

@@ -0,0 +1,71 @@
+# Arc Diagram
+
+```dgmo
+arc Pirate Alliances
+//order appearance | name | group | degree
+
+// Source -> Target weight
+[Caribbean](red)
+  Blackbeard -> Bonnet 8
+  Blackbeard -> Vane 5
+  Blackbeard -> Hornigold 4
+  Hornigold -> Bonnet 2
+
+[Women Pirates](purple)
+  Bonny -> Rackham 9
+  Bonny -> Read 7
+  Rackham -> Vane 3
+
+[West Africa](teal)
+  Roberts -> Davis 6
+```
+
+## Syntax
+
+```
+arc Chart Title
+order appearance
+
+Source -> Target weight
+```
+
+## Metadata Keys
+
+| Key     | Description                                                         | Required |
+| ------- | ------------------------------------------------------------------- | -------- |
+| `chart` | Must be `arc`                                                       | Yes      |
+| `title` | Chart title displayed above the chart                               | No       |
+| `order` | Node ordering: `appearance` (default), `name`, `group`, or `degree` | No       |
+
+## Data Format
+
+Each data line defines a connection between two nodes with an optional weight:
+
+```
+Source -> Target weight
+Source -> Target
+```
+
+If weight is omitted, it defaults to 1. Arc thickness is proportional to weight.
+
+## Node Groups
+
+Use `[Group Name](color)` headers to group nodes by color:
+
+```
+[Captains](red)
+Blackbeard -> Bonnet 8
+Blackbeard -> Vane 5
+
+[Crew](blue)
+Bonny -> Read 7
+```
+
+Nodes inherit the color of the group in which they first appear.
+
+## Node Ordering
+
+- `appearance` — nodes appear in the order they are first mentioned (default)
+- `name` — nodes sorted alphabetically
+- `group` — nodes sorted by group, then by appearance within group
+- `degree` — nodes sorted by number of connections (most connected first)

package/docs/guide/chart-area.md

@@ -0,0 +1,73 @@
+# Area Chart
+
+```dgmo
+area Fleet Growth Over Time
+series Ships
+x-label Year
+
+era 1710 -> 1716 Rise (green)
+era 1716 -> 1720 Decline (red)
+
+1710: 3
+1712: 5
+1714: 9
+1716: 14
+1718: 8
+1720: 4
+```
+
+## Syntax
+
+```
+area Chart Title
+series Series Name
+x-label X Axis Label
+y-label Y Axis Label
+
+Label: value
+```
+
+## Era Bands
+
+Annotate named time periods with a shaded background band and label:
+
+```dgmo
+area Fleet Growth by Era
+x-label Year
+
+era 1710 -> 1714 Early Growth (blue)
+era 1714 -> 1720 Decline (red)
+
+1710: 3
+1712: 5
+1714: 9
+1716: 14
+1718: 8
+1720: 4
+```
+
+Era syntax: `era <start> -> <end> Label (color)`
+
+- `start` and `end` must exactly match data point labels
+- Color is optional; omit for the palette default
+
+## Metadata Keys
+
+| Key       | Description                               | Required |
+| --------- | ----------------------------------------- | -------- |
+| `chart`   | Must be `area`                            | Yes      |
+| `title`   | Chart title displayed above the chart     | No       |
+| `series`  | Name of the data series (shown in legend) | No       |
+| `x-label` | Label for the X axis                      | No       |
+| `y-label` | Label for the Y axis                      | No       |
+| `color`   | Override the area fill color              | No       |
+
+## Data Format
+
+Each data line follows the pattern `Label: value`:
+
+```
+1710: 3
+1712: 5
+1714: 9
+```

package/docs/guide/chart-bar-stacked.md

@@ -0,0 +1,61 @@
+# Stacked Bar Chart
+
+```dgmo
+bar-stacked Cargo by Voyage
+series Rum, Spices, Silk, Gold
+
+Voyage 1 40, 20, 10, 30
+Voyage 2 25, 35, 20, 20
+Voyage 3 15, 10, 45, 30
+Voyage 4 30, 25, 15, 30
+```
+
+## Syntax
+
+```
+bar-stacked Chart Title
+series Series1, Series2, Series3
+
+Label value1, value2, value3
+```
+
+## Metadata Keys
+
+| Key                      | Description                                                      | Required |
+| ------------------------ | ---------------------------------------------------------------- | -------- |
+| `chart`                  | Must be `bar-stacked`                                            | Yes      |
+| `title`                  | Chart title displayed above the chart                            | No       |
+| `series`                 | Comma-separated series names with optional colors in parentheses | Yes      |
+| `orientation-horizontal` | Horizontal bars (default is vertical)                            | No       |
+
+## Data Format
+
+Each data line provides comma-separated values matching the series order:
+
+```
+Voyage 1 40, 20, 10, 30
+Voyage 2 25, 35, 20, 20
+```
+
+## Series Colors
+
+Colors can be specified per series:
+
+```
+series Imports(blue), Exports(green), Tariffs(orange)
+```
+
+## Variants
+
+### Horizontal Stacked Bar
+
+```dgmo
+bar-stacked Port Revenue by Trade
+orientation-horizontal
+series Imports(blue), Exports(green), Tariffs(orange)
+
+Port Royal 300, 450, 80
+Tortuga 150, 200, 30
+Nassau 400, 350, 120
+Havana 500, 600, 150
+```

package/docs/guide/chart-bar.md

@@ -0,0 +1,62 @@
+# Bar Chart
+
+```dgmo
+bar Treasure Hauls by Port
+series Gold Doubloons
+
+Port Royal 850
+Tortuga 620
+Nassau 1100
+Havana 430
+Cartagena 780
+```
+
+## Syntax
+
+```
+bar Chart Title
+series Series Name
+x-label X Axis Label
+y-label Y Axis Label
+
+Label value
+```
+
+## Metadata Keys
+
+| Key                      | Description                               | Required |
+| ------------------------ | ----------------------------------------- | -------- |
+| `chart`                  | Must be `bar`                             | Yes      |
+| `title`                  | Chart title displayed above the chart     | No       |
+| `series`                 | Name of the data series (shown in legend) | No       |
+| `x-label`                | Label for the X axis                      | No       |
+| `y-label`                | Label for the Y axis                      | No       |
+| `orientation-horizontal` | Horizontal bars (default is vertical)     | No       |
+| `color`                  | Override the bar color (e.g., `red`)      | No       |
+
+## Data Format
+
+Each data line follows the pattern `Label value`:
+
+```
+Port Royal 850
+Tortuga 620
+Nassau 1100
+```
+
+## Variants
+
+### Horizontal Bar
+
+Add `orientation-horizontal` to display bars horizontally:
+
+```dgmo
+bar Crew Size by Ship
+orientation-horizontal
+series Crew Members
+
+Queen Anne's Revenge 300
+Royal Fortune 262
+Whydah Gally 146
+Adventure Galley 152
+```

package/docs/guide/chart-boxes-and-lines.md

@@ -0,0 +1,243 @@
+# Boxes and Lines
+
+```dgmo
+boxes-and-lines Pirate Software
+
+tag Status s
+  Done(green)
+  Doing(yellow)
+  Todo(red)
+  NA(gray) default
+
+active-tag Status
+
+MobileApp | s:Todo
+  -> API
+
+WebSite | s:Doing
+  -> API
+
+[Backend]
+  API | s:Doing
+    -> DB
+    -> AuthVendor
+
+  DB | s:Done
+
+AuthVendor
+```
+
+## Overview
+
+Boxes and lines is a general-purpose node-edge diagram for modeling systems, architectures, and relationships. Nodes are connected with labeled arrows, organized into nested groups, and annotated with color-coded tags.
+
+Unlike more specialized diagram types (infra for traffic simulation, C4 for system context), boxes-and-lines is intentionally flexible. Node shapes are inferred from names — a node called "UserDB" renders as a cylinder, "Redis" as a diamond, "OrderQueue" as a hexagon.
+
+## Declaration
+
+```
+boxes-and-lines Optional Title
+```
+
+The first line declares the diagram type and optional title.
+
+## Nodes
+
+Nodes are created explicitly or implicitly when referenced in edges.
+
+### Explicit nodes
+
+```
+API Gateway | description: Main entry point
+UserDB
+```
+
+A name on its own line creates a node. Pipe metadata is optional.
+
+### Implicit nodes
+
+```
+API Gateway -routes-> UserService
+```
+
+If `UserService` hasn't been declared yet, it's created automatically from the edge.
+
+### Pipe metadata
+
+```
+API Gateway | t: Backend, description: Main entry point
+```
+
+Metadata uses pipe syntax with `key: value` pairs separated by commas. Common keys:
+
+- Tag aliases (e.g., `t: Backend` where `t` is a tag alias)
+- `description` — shown as a subtitle on the node
+
+### Shape inference
+
+Node shapes are inferred from names:
+
+| Name contains                                  | Shape             |
+| ---------------------------------------------- | ----------------- |
+| `DB`, `Database`, `Postgres`, `MySQL`, `Mongo` | Cylinder          |
+| `Cache`, `Redis`, `Memcached`                  | Diamond           |
+| `Queue`, `Kafka`, `SQS`, `EventBus`            | Hexagon           |
+| `Gateway`, `LB`, `Proxy`, `Router`             | Wide rectangle    |
+| `User`, `Actor`, `Client`, `Admin`             | Rounded rectangle |
+| `External`, `Stripe`, `Twilio`                 | Dashed border     |
+| Everything else                                | Default rectangle |
+
+## Edges
+
+### Directed edges
+
+```
+A -> B                    // unlabeled
+A -routes-> B             // labeled
+```
+
+### Bidirectional edges
+
+```
+A <-syncs-> B             // bidirectional with label
+A <-> B                   // bidirectional unlabeled
+```
+
+### Indented shorthand
+
+When a node has multiple outbound edges, indent them below:
+
+```
+API Gateway
+  -routes-> UserService
+  -routes-> ProductService
+  -routes-> OrderService
+```
+
+This is equivalent to writing three separate edge lines with `API Gateway` as the source.
+
+### Edge metadata
+
+```
+SessionCache <-syncs-> ProductDB | p: Medium
+```
+
+Edges support pipe metadata, typically for tag values.
+
+## Groups
+
+Groups visually contain nodes in a dashed rectangle.
+
+### Basic groups
+
+```
+[AWS us-east-1]
+  API Gateway
+  UserService
+  ProductDB
+```
+
+### Nested groups (max 2 levels)
+
+```
+[AWS us-east-1]
+  [Compute]
+    API Gateway
+    UserService
+  [Data]
+    UserDB
+    ProductDB
+```
+
+### Group-to-group edges
+
+Groups can be edge endpoints:
+
+```
+[Frontend] -> [Backend]
+```
+
+## Tags
+
+Tags add colored metadata dimensions for filtering and visual grouping.
+
+### Declaring tags
+
+```
+tag Team t Backend(blue), Frontend(green), Platform(purple)
+tag Priority p High(red), Medium(orange), Low(gray)
+```
+
+Format: `tag Name alias Value1(color), Value2(color), ...`
+
+### Assigning tags
+
+Use the alias in pipe metadata:
+
+```
+API Gateway | t: Backend
+UserDB | t: Platform
+```
+
+### Filtering
+
+```
+active-tag Team           // color nodes by Team tag
+hide priority:Low         // hide nodes tagged Low priority
+```
+
+## Options
+
+| Directive    | Values         | Default | Description                                 |
+| ------------ | -------------- | ------- | ------------------------------------------- |
+| `direction`  | `LR`, `TB`     | `TB`    | Layout direction (left-right or top-bottom) |
+| `active-tag` | tag group name | none    | Which tag group drives node coloring        |
+| `hide`       | `alias:value`  | none    | Hide nodes with a specific tag value        |
+| `mode`       | `shapes`       | —       | Force shape rendering mode                  |
+
+## Comments
+
+```
+// This is a comment
+```
+
+Only `//` comments are supported.
+
+## Complete Example
+
+```dgmo
+boxes-and-lines Microservices
+
+tag Team t Backend(blue), Frontend(green), Infra(purple)
+active-tag Team
+direction LR
+
+WebApp | t: Frontend
+  -> API Gateway
+
+API Gateway | t: Infra
+  -auth-> AuthService
+  -data-> DataService
+
+AuthService | t: Backend
+  -> UserDB
+
+DataService | t: Backend
+  -> PostgreSQL
+  -> Redis
+
+UserDB | t: Infra
+PostgreSQL | t: Infra
+Redis | t: Infra
+
+[Cloud]
+  [Services]
+    API Gateway
+    AuthService
+    DataService
+  [Storage]
+    UserDB
+    PostgreSQL
+
+Redis <-cache-> DataService
+```