@diagrammo/dgmo 0.8.12 → 0.8.13

package/docs/guide/chart-c4.md

@@ -0,0 +1,300 @@
+# C4 Diagram
+
+> **Beta** — C4 diagram support is in beta. The DSL syntax may change in future releases.
+
+```dgmo
+c4 Internet Banking System
+
+person Customer | description: A customer of the bank
+
+system Internet Banking | description: Allows customers to view accounts and make payments
+  -Delivers content to [HTTPS]-> Customer
+  -Sends emails using [SMTP]-> Email
+
+  containers
+    container Web App | description: SPA for banking features, tech: React
+      -Makes API calls [JSON/HTTPS]-> API
+
+    container API | description: JSON/HTTPS API backend, tech: Node.js
+      -Reads from and writes to [SQL/TCP]-> Database
+
+    container Database | description: Stores account data, tech: PostgreSQL
+
+system Email | description: Sendgrid email delivery
+  ~Sends emails to~> Customer
+
+deployment
+  Vercel is a cloud
+    container Web App
+  Railway
+    container API
+  Neon is a database
+    container Database
+```
+
+## Overview
+
+C4 diagrams model software architecture at multiple zoom levels, following the [C4 model](https://c4model.com). Define people, systems, containers, and components — then drill down from context to detail. Relationships use the same arrow syntax as sequence diagrams.
+
+The diagram starts at the **Context** level (people + systems). Click a system to drill into its **Containers**, then click a container to see its **Components**.
+
+## Syntax
+
+```
+c4 Diagram Title
+
+person Name | description: ...
+system Name | description: ...
+  -label [technology]-> Target
+  ~async label~> Target
+
+  containers
+    container Name | tech: ..., description: ...
+
+      components
+        component Name | tech: ..., description: ...
+```
+
+## Element Types
+
+| Type        | Description                     | Example                    |
+| ----------- | ------------------------------- | -------------------------- |
+| `person`    | User or actor                   | `person Customer`          |
+| `system`    | Top-level software system       | `system Banking`           |
+| `container` | Runtime unit within a system    | `container API`            |
+| `component` | Logical part within a container | `component AuthController` |
+
+Elements are declared with their type keyword followed by a name. Add metadata after `|`:
+
+```
+system Analytics Platform | description: Multi-tenant analytics, tech: Node.js
+```
+
+## Shapes
+
+Shapes can be inferred from the element's technology or name, or declared explicitly:
+
+```
+container Database is a database
+container Cache is a cache
+container Event Bus is a queue
+system AWS is a cloud
+system Stripe is an external
+```
+
+| Shape      | Inferred from                                             |
+| ---------- | --------------------------------------------------------- |
+| `database` | `tech: PostgreSQL`, `tech: MySQL`, names ending in `DB`   |
+| `cache`    | `tech: Redis`, `tech: Memcache`, names containing `Cache` |
+| `queue`    | `tech: RabbitMQ`, `tech: Kafka`, names containing `Queue` |
+| `cloud`    | Explicit `is a cloud` only                                |
+| `external` | Explicit `is an external` only                            |
+
+## Metadata
+
+Key-value pairs on the same line with `|`, or indented below the element:
+
+```
+container API Gateway | tech: Node.js, team: Platform
+  description: REST API serving all frontends
+```
+
+Or fully inline:
+
+```
+container API Gateway | tech: Node.js, team: Platform, description: REST API
+```
+
+## Relationships
+
+### Arrow Types
+
+| Arrow | Meaning                 | Example                  |
+| ----- | ----------------------- | ------------------------ |
+| `->`  | Synchronous             | `-Makes API calls-> API` |
+| `~>`  | Async / fire-and-forget | `~Sends events~> Queue`  |
+
+For bidirectional relationships, use two separate lines:
+
+```
+API -Makes API calls-> Database
+Database -Returns results-> API
+```
+
+### Labeled Relationships
+
+Place the label inside the arrow. Add `[technology]` to annotate the protocol:
+
+```
+-Makes API calls [JSON/HTTPS]-> API
+-Reads from and writes to [SQL/TCP]-> Database
+~Submits analytics queries [AMQP]~> Query Engine
+```
+
+### Arrow-Label Syntax
+
+Labels can also be placed inside the arrow:
+
+```
+-Makes API calls [JSON/HTTPS]-> API
+~Sends events [AMQP]~> Queue
+```
+
+## Hierarchy
+
+Systems contain containers (via `containers`), containers contain components (via `components`). Indentation defines the hierarchy:
+
+```
+system Banking
+  containers
+    container Web App
+    container API
+      components
+        component AuthController
+        component PaymentService
+```
+
+At the **Context** level, container-level relationships are automatically rolled up to their parent system.
+
+## Groups
+
+Organize containers or components into visual boundaries:
+
+```
+containers
+  [Frontend]
+    container Dashboard | tech: React
+    container Admin Console | tech: React
+
+  [Backend]
+    container API Gateway | tech: Node.js
+    container Query Engine | tech: Node.js
+
+  [Data]
+    container Database | tech: PostgreSQL
+    container Cache is a cache | tech: Redis
+```
+
+## Tag Groups
+
+Color-code elements by technology, team, or any custom category:
+
+```
+tag Technology alias tech
+  React(blue)
+  Node.js(green)
+  PostgreSQL(purple)
+  Redis(red)
+
+tag Team alias t
+  Product(blue) default
+  Data(orange)
+  Infrastructure(teal)
+```
+
+Then reference tags in metadata: `container API | tech: Node.js, t: Product`.
+
+## Deployment
+
+Map containers to infrastructure with the `deployment` section:
+
+```
+deployment
+  AWS us-east-1 is a cloud
+    ECS Cluster
+      container API
+      container Worker
+    RDS is a database
+      container Database
+    ElastiCache is a cache
+      container Cache
+```
+
+- Nest deployment nodes to any depth
+- Use `container Name` to reference a defined container
+- Shapes (`is a database`, `is a cloud`) work on deployment nodes too
+
+## Comments
+
+```
+// This line is ignored by the parser
+```
+
+## Complete Example
+
+```dgmo
+c4 SaaS Analytics Platform
+
+tag Technology alias tech
+  React(blue)
+  Node.js(green)
+  PostgreSQL(purple)
+  Redis(red)
+
+tag Team alias t
+  Product(blue) default
+  Data(orange)
+  Infrastructure(teal)
+
+person End User | description: Views dashboards and creates reports
+person Account Admin | description: Manages workspace settings and members
+
+system Analytics Platform | description: Multi-tenant analytics and reporting
+  -Serves dashboards to [HTTPS]-> End User
+  -Provides admin console to [HTTPS]-> Account Admin
+  ~Sends scheduled reports via [SMTP]~> Email Service
+
+  containers
+    [Frontend]
+      container Dashboard App | tech: React, t: Product
+        description: Interactive data visualization SPA
+        -Fetches data from [JSON/HTTPS]-> API Gateway
+
+      container Admin Console | tech: React, t: Product
+        description: Workspace and user management
+        -Manages settings via [JSON/HTTPS]-> API Gateway
+
+    [Backend]
+      container API Gateway | tech: Node.js, t: Product
+        description: REST API serving all frontends
+        -Reads/writes user data [SQL/TCP]-> App Database
+        -Reads/writes sessions [TCP]-> Cache
+        ~Submits analytics queries [AMQP]~> Query Engine
+
+      container Query Engine | tech: Node.js, t: Data
+        description: Processes analytics queries asynchronously
+        -Runs queries against [SQL/TCP]-> Data Warehouse
+        ~Publishes results [AMQP]~> Event Bus
+
+    [Data]
+      container App Database | tech: PostgreSQL, t: Product
+        description: Users, workspaces, and dashboard configs
+
+      container Data Warehouse | tech: PostgreSQL, t: Data
+        description: Aggregated analytics data
+
+      container Cache is a cache | tech: Redis, t: Infrastructure
+        description: Session store and rate limiter
+
+      container Event Bus | tech: RabbitMQ, t: Infrastructure
+        description: Async messaging backbone
+
+system Email Service | description: Transactional email delivery
+  ~Delivers report emails to~> End User
+
+deployment
+  GCP us-central1 is a cloud
+    Cloud Run — Frontend
+      container Dashboard App
+      container Admin Console
+    Cloud Run — Backend
+      container API Gateway
+      container Query Engine
+    Cloud SQL is a database
+      container App Database
+      container Data Warehouse
+    Memorystore is a cache
+      container Cache
+    Cloud Pub/Sub
+      container Event Bus
+```

package/docs/guide/chart-chord.md

@@ -0,0 +1,43 @@
+# Chord Diagram
+
+```dgmo
+chord Pirate Alliance Network
+
+Blackbeard -> Bonnet 150
+Blackbeard -> Vane 80
+Blackbeard -> Hornigold 120
+Bonnet -> Rackham 40
+Vane -> Rackham 60
+Rackham -> Bonny 200
+Bonny -> Read 180
+Roberts -> Davis 90
+Roberts -> Anstis 70
+Hornigold -> Bonnet 50
+```
+
+## Syntax
+
+```
+chord Chart Title
+
+Source -> Target value
+```
+
+## Metadata Keys
+
+| Key     | Description                           | Required |
+| ------- | ------------------------------------- | -------- |
+| `chart` | Must be `chord`                       | Yes      |
+| `title` | Chart title displayed above the chart | No       |
+
+## Data Format
+
+Each data line defines a connection between two entities with a numeric weight:
+
+```
+Blackbeard -> Bonnet 150
+Blackbeard -> Vane 80
+Bonnet -> Rackham 40
+```
+
+Nodes are arranged around a circle. The width of each chord represents the strength of the connection.

package/docs/guide/chart-class.md

@@ -0,0 +1,204 @@
+# Class Diagram
+
+```dgmo
+class Ship Class Hierarchy
+
+Vessel [interface]
+  + sail(): void
+  + anchor(): void
+
+Ship implements Vessel [abstract]
+  # name: string
+  # crew: number
+  + getName(): string
+
+Galleon extends Ship
+  - cannons: number
+  + fire(): void
+
+Sloop extends Ship
+  - speed: number
+  + flee(): void
+
+ShipType [enum]
+  Galleon
+  Sloop
+  Frigate
+
+Ship -> ShipType : has type
+```
+
+## Overview
+
+Class diagrams render UML-style boxes with three compartments per the UML spec: name, attributes, and methods. Classes connect via relationships like inheritance, composition, and association. Layout is automatic via Dagre.
+
+## Syntax
+
+```
+class Diagram Title
+
+ClassName [modifier] (color)
+  + publicField: type
+  - privateField: type
+  # protectedField: type
+  + method(params): returnType
+
+ChildClass extends ParentClass
+  + field: type
+```
+
+## Settings
+
+| Key     | Description     | Default |
+| ------- | --------------- | ------- |
+| `chart` | Must be `class` | —       |
+| `title` | Diagram title   | None    |
+
+## Classes
+
+Declare a class on an unindented line. Members are indented below:
+
+```
+User
+  + name: string
+  + email: string
+  + login(password: string): boolean
+```
+
+### Modifiers
+
+Add a modifier in brackets to change the class type:
+
+| Modifier  | Syntax             | Appearance                              |
+| --------- | ------------------ | --------------------------------------- |
+| Interface | `Name [interface]` | `«interface»` badge, blue               |
+| Abstract  | `Name [abstract]`  | `«abstract»` badge, italic name, purple |
+| Enum      | `Name [enum]`      | `«enum»` badge, yellow                  |
+
+### Enum Values
+
+Enum classes list plain values instead of typed fields:
+
+```
+OrderStatus [enum]
+  Pending
+  Confirmed
+  Shipped
+  Delivered
+```
+
+## Fields and Methods
+
+Indented lines under a class are parsed as members.
+
+### Visibility
+
+| Symbol | Meaning   |
+| ------ | --------- |
+| `+`    | Public    |
+| `-`    | Private   |
+| `#`    | Protected |
+| (none) | Public    |
+
+### Fields
+
+```
+  + name: string
+  - password: string
+  # id: number
+```
+
+### Methods
+
+Methods are detected by the presence of parentheses:
+
+```
+  + login(email: string, pass: string): boolean
+  - validate(): void
+  + getInstance(): Logger {static}
+```
+
+Add `{static}` at the end to mark a member as static.
+
+## Relationships
+
+### Inheritance & Implementation
+
+Use `extends` or `implements` in the class declaration header:
+
+```
+Dog extends Animal
+  + breed: string
+
+Circle implements Drawable
+  - radius: number
+```
+
+This declares the class and establishes the relationship in one line. Members are indented below as usual.
+
+### Arrow Syntax
+
+For other relationships, use arrow notation:
+
+| Relationship   | Arrow   | Example                  |
+| -------------- | ------- | ------------------------ |
+| Inheritance    | `--\|>` | `Dog --\|> Animal`       |
+| Implementation | `..\|>` | `Dog ..\|> Serializable` |
+| Composition    | `*--`   | `Car *-- Engine`         |
+| Aggregation    | `o--`   | `Team o-- Player`        |
+| Dependency     | `..>`   | `Service ..> Logger`     |
+| Association    | `->`    | `Order -> Customer`      |
+
+### Labels
+
+Add a label after a colon:
+
+```
+Car *-- Engine : powered by
+Service ..> Logger : uses
+```
+
+## Colors
+
+Colors are auto-assigned by modifier type. Override with a color name in parentheses:
+
+```
+Ship (red)
+Engine [abstract] (purple)
+```
+
+## Comments
+
+```
+// This line is ignored by the parser
+```
+
+## Complete Example
+
+```dgmo
+class Design Patterns
+
+Drawable [interface]
+  + draw(): void
+  + resize(w: number, h: number): void
+
+Shape implements Drawable [abstract] (purple)
+  # x: number
+  # y: number
+  + area(): number
+
+Circle extends Shape
+  - radius: number
+  + getRadius(): number
+
+Rectangle extends Shape
+  - width: number
+  - height: number
+
+Canvas
+  - shapes: Shape[]
+  + render(): void
+
+Canvas *-- Shape : contains
+Canvas ..> Logger : uses
+```

package/docs/guide/chart-doughnut.md

@@ -0,0 +1,38 @@
+# Doughnut Chart
+
+```dgmo
+doughnut Plunder Distribution
+
+Captain's Share: 40
+Quartermaster: 20
+Crew Split: 25
+Ship Repairs: 10
+Provisions: 5
+```
+
+## Syntax
+
+```
+doughnut Chart Title
+
+Label: value
+```
+
+## Metadata Keys
+
+| Key     | Description                           | Required |
+| ------- | ------------------------------------- | -------- |
+| `chart` | Must be `doughnut`                    | Yes      |
+| `title` | Chart title displayed above the chart | No       |
+
+## Data Format
+
+Each data line follows the pattern `Label: value`:
+
+```
+Captain's Share: 40
+Quartermaster: 20
+Crew Split: 25
+```
+
+Segments are automatically colored using the Nord palette.