@diagrammo/dgmo 0.8.12 → 0.8.14

package/docs/guide/chart-sitemap.md

@@ -0,0 +1,248 @@
+# Sitemap
+
+```dgmo
+sitemap The Salty Compass
+
+tag Auth
+  Public(green)
+  Crew Only(blue)
+
+Home | Auth: Public
+  -shop-> Shop
+  -voyages-> Upcoming Voyages
+  -join crew-> Sign Up
+  -sign in-> Login
+
+[Ship Store]
+  Shop | Auth: Public
+    -> Eye Patches
+    -> Flags & Banners
+  Eye Patches | Auth: Public
+    -add to chest-> Cart
+  Flags & Banners | Auth: Public
+    -add to chest-> Cart
+  Cart | Auth: Public
+    -checkout-> Checkout
+  Checkout | Auth: Crew Only
+    -done-> My Orders
+
+[Voyages]
+  Upcoming Voyages | Auth: Public
+    -details-> Voyage Detail
+  Voyage Detail | Auth: Public
+    -enlist-> Sign Up
+
+[Crew Quarters]
+  Login | Auth: Public
+    -welcome aboard-> Dashboard
+    -new pirate-> Sign Up
+  Sign Up | Auth: Public
+    -welcome aboard-> Dashboard
+  Dashboard | Auth: Crew Only
+    -> My Orders
+  My Orders | Auth: Crew Only
+    -reorder-> Shop
+```
+
+## Overview
+
+Sitemap diagrams visualize website structure as a hierarchy of pages. Indentation defines the parent-child relationship between pages. Pages can be grouped into containers, connected with arrows, and annotated with metadata and color-coded tag groups.
+
+## Syntax
+
+```
+sitemap Site Title
+
+Page Name
+  Child Page
+    Grandchild Page
+```
+
+## Settings
+
+| Key            | Description                                   | Default  |
+| -------------- | --------------------------------------------- | -------- |
+| `chart`        | Must be `sitemap`                             | —        |
+| `title`        | Diagram title                                 | None     |
+| `direction-tb` | Top-to-bottom layout (omit for left-to-right) | off (LR) |
+| `hide`         | Comma-separated metadata to hide              | None     |
+
+## Pages
+
+Each line of text creates a page node. Indentation creates child pages:
+
+```
+Home
+  About
+  Products
+    Enterprise
+    Starter
+  Contact
+```
+
+## Groups (Containers)
+
+Use `[Group Name]` to create a visual container that groups its children:
+
+```
+Home
+  [Product Section]
+    Products
+    Pricing
+    Demo
+
+  [Support Section]
+    Help Center
+    Documentation
+```
+
+Containers render as labeled boxes. They can have their own metadata.
+
+## Arrows
+
+Add arrows between pages using `->` syntax indented under a page:
+
+```
+Home
+  -> Products
+  -explore-> Blog
+Products
+  Pricing
+    -upgrade(green)-> Enterprise
+```
+
+- `-> Target` — plain arrow
+- `-label-> Target` — labeled arrow
+- `-label(color)-> Target` — labeled and colored arrow
+
+## Metadata
+
+Add key-value pairs indented under a page:
+
+```
+Home
+  status: Live
+  owner: Marketing
+
+Products
+  status: Draft
+  owner: Product Team
+```
+
+Metadata renders as secondary text on the page card.
+
+### Pipe Syntax
+
+For concise entries, use `|` to put metadata on a single line:
+
+```
+Home | status: Live | owner: Marketing
+Products | status: Draft | owner: Product Team
+```
+
+## Node Colors
+
+Add a color name in parentheses after a page or group name:
+
+```
+Home(blue)
+[Admin Section(red)]
+  Dashboard
+  Settings
+```
+
+## Tag Groups
+
+Define color-coded tags for metadata values. Tag groups must appear before page content:
+
+```
+sitemap Company Site
+
+tag Status
+  Live(green)
+  Draft(yellow)
+  Deprecated(red)
+
+tag Owner
+  Marketing(blue)
+  Engineering(purple)
+
+Home
+  status: Live
+  owner: Marketing
+```
+
+- `tag GroupName` starts a tag group
+- When a tag group is active, pages are colored by their matching tag value
+- Click a tag group pill to activate it; click the eye icon to toggle that metadata's visibility on cards
+
+## Direction
+
+The default layout is left-to-right. Add `direction-tb` to switch to top-to-bottom:
+
+```
+sitemap
+direction-tb
+```
+
+## Collapse / Expand
+
+In the app, click a page or group that has children to focus it. Click again to collapse its subtree — a "+N" label shows how many nodes are hidden. Click once more to expand.
+
+Keyboard: Tab to focus a node, Enter or Space to toggle.
+
+## Comments
+
+```
+// This line is ignored by the parser
+```
+
+## Complete Example
+
+```dgmo
+sitemap The Salty Compass
+
+tag Auth
+  Public(green)
+  Crew Only(blue)
+
+tag Status
+  Live(cyan)
+  Coming Soon(yellow)
+
+Home | Auth: Public | Status: Live
+  -shop-> Shop
+  -voyages-> Upcoming Voyages
+  -join crew-> Sign Up
+  -sign in-> Login
+
+[Ship Store]
+  Shop | Auth: Public | Status: Live
+    -> Eye Patches
+    -> Flags & Banners
+  Eye Patches | Auth: Public | Status: Live
+    -add to chest-> Cart
+  Flags & Banners | Auth: Public | Status: Coming Soon
+    -add to chest-> Cart
+  Cart | Auth: Public | Status: Live
+    -checkout-> Checkout
+  Checkout | Auth: Crew Only | Status: Live
+    -done-> My Orders
+
+[Voyages]
+  Upcoming Voyages | Auth: Public | Status: Live
+    -details-> Voyage Detail
+  Voyage Detail | Auth: Public | Status: Live
+    -enlist-> Sign Up
+
+[Crew Quarters]
+  Login | Auth: Public | Status: Live
+    -welcome aboard-> Dashboard
+    -new pirate-> Sign Up
+  Sign Up | Auth: Public | Status: Live
+    -welcome aboard-> Dashboard
+  Dashboard | Auth: Crew Only | Status: Live
+    -> My Orders
+  My Orders | Auth: Crew Only | Status: Live
+    -reorder-> Shop
+```

package/docs/guide/chart-slope.md

@@ -0,0 +1,56 @@
+# Slope Chart
+
+```dgmo
+slope Pirate Fleet Strength: 1715 vs 1725
+
+period 1715 1725
+
+Blackbeard 40 4
+Bartholomew Roberts 12 52
+Charles Vane 20 2
+Anne Bonny 8 15
+Calico Jack 18 6
+```
+
+## Syntax
+
+```
+slope Chart Title
+
+period Period1 Period2
+
+Label value1 value2
+```
+
+For multi-token period labels, use an indented block:
+
+```
+period
+  Before COVID
+  After COVID
+```
+
+## Data Format
+
+The `period` directive defines the period labels (minimum 2 required). Data rows are space-separated with no colons:
+
+```
+period 2020 2025
+
+Product A 40 80
+Product B 70 30
+```
+
+Lines slope upward for increases and downward for decreases.
+
+## Color Annotations
+
+Add `(color)` after the label to set a custom color:
+
+```
+Python (blue) 3 1 1
+```
+
+## Thousands Commas
+
+Values can contain thousands commas: `Revenue 1,000 2,500`

package/docs/guide/chart-state.md

@@ -0,0 +1,171 @@
+# State Diagram
+
+```dgmo
+state Order Lifecycle
+
+[*] -> Pending
+
+Pending
+  -submit-> Validating
+
+Validating
+  -approved-> Processing
+  -rejected-> Cancelled
+
+[Fulfillment]
+  Processing
+    -pack-> Shipping
+    -out of stock-> Cancelled
+
+  Shipping
+    -delivered-> Delivered
+    -lost-> Refunded
+
+[Resolution]
+  Delivered
+    -return request-> Returning
+
+  Returning
+    -received-> Refunded
+
+Cancelled -> [*]
+Refunded -> [*]
+Delivered -> [*]
+```
+
+## Overview
+
+State diagrams model states and transitions. Write states as plain text and connect them with `->` arrows. Diagrammo handles the layout automatically. Use `[*]` for start/end pseudostates and indent lines to chain transitions from a parent state.
+
+## Syntax
+
+```
+state Diagram Title
+direction-tb
+
+[*] -> Idle
+Idle -event-> Active
+Active -> [*]
+```
+
+## Settings
+
+| Key            | Description                                     | Default |
+| -------------- | ----------------------------------------------- | ------- |
+| `chart`        | Must be `state`                                 | —       |
+| `title`        | Diagram title                                   | None    |
+| `direction-tb` | Top-to-bottom layout (default is left-to-right) | `TB`    |
+
+## States
+
+Write state names as plain text. States are created automatically when referenced:
+
+```
+Idle -> Active -> Done
+```
+
+### Pseudostates
+
+Use `[*]` for start and end points. They render as filled circles:
+
+```
+[*] -> Idle
+Done -> [*]
+```
+
+## Transitions
+
+Connect states with `->`. Add labels between dashes:
+
+```
+Idle -> Active
+Idle -start-> Active
+Active -finish(green)-> Done
+```
+
+### Indent-Based Source Inference
+
+Indent transitions under a state heading to chain them from that state:
+
+```
+Idle
+  -start-> Active
+  -reset-> Stopped
+Active
+  -> Done
+```
+
+This is equivalent to writing `Idle -start-> Active`, `Idle -reset-> Stopped`, and `Active -> Done`.
+
+### Transition Chains
+
+Chain multiple states on a single line:
+
+```
+[*] -> Idle -> Active -> Done -> [*]
+```
+
+## State Colors
+
+Add a color name in parentheses after a state label:
+
+```
+Active(green) -> Error(red)
+```
+
+## Transition Colors
+
+Add a color in parentheses inside the arrow label:
+
+```
+Idle -go(green)-> Active
+Active -fail(red)-> Error
+```
+
+## Groups
+
+Use bracket syntax `[Name]` to visually group states into regions. States indented under the bracket line belong to the group. The group closes when indentation returns to the bracket's level or below:
+
+```
+state
+
+[Happy Path](green)
+  [*] -> Processing -> Approved -> [*]
+
+[Error Handling](red)
+  Processing -fail-> Rejected -> [*]
+```
+
+Groups render as labeled background boxes with optional colors.
+
+## Comments
+
+```
+// This line is ignored by the parser
+[*] -> Idle
+```
+
+## Complete Example
+
+```dgmo
+state Order of the Jolly Roger
+
+[*] -> Docked
+Docked
+  -set sail-> At Sea
+At Sea
+  -spot treasure-> Treasure Hunt
+  -enemy ship!-> Battle
+Treasure Hunt
+  -found gold-> Celebrating
+  -empty chest-> At Sea
+Battle
+  -victory!-> Plundering
+  -retreat!-> At Sea
+Plundering
+  -> Celebrating
+Celebrating
+  -rum's gone-> At Sea
+  -retire-> Docked
+  -mutiny!-> [*]
+```

package/docs/guide/chart-timeline.md

@@ -0,0 +1,229 @@
+# Timeline
+
+```dgmo
+timeline The Golden Age of Piracy (1716–1722)
+scale on
+
+tag Pirate alias p
+  Blackbeard(red)
+  Bonny & Rackham(purple)
+  Roberts(blue)
+
+tag Outcome alias o
+  Victory(green)
+  Defeat(red)
+  Uncertain(yellow) default
+
+tag Theatre alias t
+  Caribbean(teal) default
+  Atlantic(blue)
+  Africa(orange)
+
+era 1716->1718 Nassau Republic
+era 1719->1722 Roberts Era
+
+marker 1718-07 Woodes Rogers arrives (orange)
+marker 1721-08 Roberts reaches peak (teal)
+
+1716->1717 Sails under Hornigold | p: Blackbeard, o: Victory
+1717-11->1718-06 Commands Queen Anne's Revenge | p: Blackbeard, o: Victory, t: Atlantic
+1718-05 Blockades Charleston harbor | p: Blackbeard, o: Victory
+1718-11-22 Killed at Ocracoke | p: Blackbeard, o: Defeat
+1718->1719 Rackham builds crew in Nassau | p: Bonny & Rackham, o: Victory
+1719-03->1720-10? Bonny & Rackham raid together | p: Bonny & Rackham
+1720-11 Rackham hanged at Port Royal | p: Bonny & Rackham, o: Defeat
+1719-06->1720 Raids West African coast | p: Roberts, o: Victory, t: Africa
+1720->1722 Captures 400+ ships | p: Roberts, o: Victory, t: Atlantic
+1722-02-10 Killed at Cape Lopez | p: Roberts, o: Defeat, t: Africa
+```
+
+## Syntax
+
+```
+timeline Chart Title
+sort group
+
+era YYYY->YYYY Era Name
+
+marker YYYY-MM-DD Marker Label (color)
+
+[Group Name](color)
+YYYY->YYYY Span event description
+YYYY-MM-DD Point event description
+```
+
+## Metadata Keys
+
+| Key         | Description                                                                                           | Required |
+| ----------- | ----------------------------------------------------------------------------------------------------- | -------- |
+| `chart`     | Must be `timeline`                                                                                    | Yes      |
+| `title`     | Chart title displayed above the chart                                                                 | No       |
+| `sort`      | Event ordering: `time` (default), `group`, `tag`, or `tag:GroupName`                                  | No       |
+| `swimlanes` | Show shaded backgrounds per group (boolean; `no-swimlanes` to disable). Works best with `sort group`. | No       |
+
+## Event Format
+
+### Point Events
+
+A single date followed by a description:
+
+```
+1718-11-22 Killed at Ocracoke
+1720-11 Rackham hanged at Port Royal
+```
+
+### Span Events
+
+A date range (start -> end) followed by a description:
+
+```
+1717-11->1718-06 Commands Queen Anne's Revenge
+1720->1722 Captures 400+ ships
+```
+
+### Duration Events
+
+Instead of specifying an end date, you can use a duration:
+
+```
+2026-07-15->30d Film release window
+2026-06-01->2w Festival run
+2026-01->6m Award season
+2026->2y Franchise arc
+```
+
+Supported duration units:
+
+| Unit | Meaning |
+| ---- | ------- |
+| `d`  | Days    |
+| `w`  | Weeks   |
+| `m`  | Months  |
+| `y`  | Years   |
+
+Decimals are supported (up to 2 places):
+
+```
+2026-01->1.25y Fifteen months (1 year + 3 months)
+2026-01->0.5y Half year (6 months)
+2026-01-01->1.5m Six weeks (1 month + 15 days)
+```
+
+The end date is calculated automatically and preserves the precision of the start date.
+
+### Uncertain End Dates
+
+Use `->?` to indicate an uncertain or approximate end date. The bar will fade out over the last 20%:
+
+```
+2026-07-15->?3m Project Alpha
+2026-01->?1.5y Long-term initiative
+```
+
+This visually communicates that the end date is an estimate rather than a fixed deadline.
+
+### Date Precision
+
+Dates support three levels of precision:
+
+- Year: `1718`
+- Year-Month: `1718-05`
+- Year-Month-Day: `1718-11-22`
+
+## Eras
+
+Background shaded regions that span a time range:
+
+```
+era 1716->1718 Nassau Republic
+era 1719->1722 Roberts Era
+```
+
+## Markers
+
+Notable moments displayed as a dashed vertical line with a diamond indicator:
+
+```
+marker 1718-11-22 Blackbeard Killed (red)
+marker 1720-11 Trial at Port Royal (orange)
+```
+
+Markers are not associated with groups and appear above all events. They're useful for highlighting key dates that span across all timeline tracks.
+
+## Groups
+
+Use `[Group Name](color)` headers to organize events into colored tracks:
+
+```
+[Blackbeard](red)
+1716->1717 Sails under Hornigold
+1718-11-22 Killed at Ocracoke
+
+[Roberts](blue)
+1719-06->1720 Raids West African coast
+1722-02-10 Killed at Cape Lopez
+```
+
+## Tag Groups
+
+Tag groups let you color and organize events by metadata categories like team, priority, or status — independent of the timeline's structural groups.
+
+### Declaring Tag Groups
+
+```
+tag Team
+  Engineering(blue)
+  Design(green)
+  QA(orange)
+```
+
+Each entry has a name and a color. You can add `default` to an entry to apply it to untagged events when the group is active:
+
+```
+tag Priority
+  High(red)
+  Medium(yellow) default
+  Low(gray)
+```
+
+### Tagging Events
+
+Add `| key: value` metadata after any event line:
+
+```
+2024-01->2024-06 Build API | Team: Engineering
+2024-03->2024-05 UX Review | Team: Design, Priority: High
+```
+
+Multiple tags can be separated by commas.
+
+### Tag-Based Swimlanes
+
+Use `sort: tag` or `sort: tag:GroupName` to arrange events into swimlanes by tag value:
+
+```dgmo
+timeline Project Roadmap
+sort tag:Team
+
+tag Team
+  Engineering(blue)
+  Design(green)
+  QA(orange)
+
+tag Priority
+  High(red)
+  Medium(yellow)
+  Low(gray)
+
+2024-01->2024-06 Build API | Team: Engineering, Priority: High
+2024-03->2024-05 UX Review | Team: Design, Priority: Medium
+2024-04->2024-07 Integration Tests | Team: QA, Priority: High
+2024-02->2024-04 Design System | Team: Design, Priority: Low
+```
+
+- `sort tag` — uses the first declared tag group for swimlanes
+- `sort tag:GroupName` — uses a specific tag group (aliases work: `sort tag:t` resolves to `sort tag:Team`)
+
+### Interactive Legend
+
+When tag groups are declared, a legend appears above the chart. Click a tag group pill to activate it — events are colored by that group's values. The swimlane tag group controls the spatial layout; the active tag group controls the coloring. These can be set independently.