sirena 0.1.0

data/docs/_diagram_types/index.adoc

@@ -0,0 +1,192 @@
+---
+layout: default
+title: Diagram Types
+nav_order: 5
+has_children: true
+---
+
+== Diagram Types
+
+Complete reference documentation for all 19 diagram types supported by Sirena.
+
+== What's in This Section
+
+Detailed syntax and examples for:
+
+* Flowchart diagrams
+* Sequence diagrams
+* Class diagrams
+* State diagrams
+* ER diagrams
+* User journey diagrams
+* Git graph diagrams
+* Pie charts
+* Gantt charts
+* Quadrant charts
+* Requirement diagrams
+* C4 diagrams
+* Mindmaps
+* Timeline diagrams
+* Sankey diagrams
+* XY charts
+* Block diagrams
+* Architecture diagrams
+* Kanban boards
+
+Plus additional specialized types:
+
+* Radar charts
+* Treemap diagrams
+* Packet diagrams
+* Info diagrams
+* Error diagrams
+
+== Diagram Type Documentation Format
+
+Each diagram type page includes:
+
+* **Overview** - What the diagram type is for
+* **Use cases** - When to use this type
+* **Syntax specification** - Complete syntax reference
+* **Elements** - Available node/element types
+* **Relationships** - Connection and edge types
+* **Examples** - From basic to advanced
+* **Features** - Special capabilities
+* **Limitations** - Current constraints
+* **Best practices** - Recommended usage patterns
+
+== Quick Reference
+
+[cols="2,3,2"]
+|===
+|Diagram Type |Primary Use Case |Keyword
+
+|link:{% link _diagram_types/flowchart.adoc %}[Flowchart]
+|Process flows and decision trees
+|`graph`, `flowchart`
+
+|link:{% link _diagram_types/sequence-diagram.adoc %}[Sequence]
+|Message interactions over time
+|`sequenceDiagram`
+
+|link:{% link _diagram_types/class-diagram.adoc %}[Class]
+|Object-oriented design
+|`classDiagram`
+
+|link:{% link _diagram_types/state-diagram.adoc %}[State]
+|State machines
+|`stateDiagram-v2`
+
+|link:{% link _diagram_types/er-diagram.adoc %}[ER Diagram]
+|Database design
+|`erDiagram`
+
+|link:{% link _diagram_types/user-journey.adoc %}[User Journey]
+|User experience flows
+|`journey`
+
+|link:{% link _diagram_types/git-graph.adoc %}[Git Graph]
+|Repository history
+|`gitGraph`
+
+|link:{% link _diagram_types/pie-chart.adoc %}[Pie Chart]
+|Proportional data
+|`pie`
+
+|link:{% link _diagram_types/gantt-chart.adoc %}[Gantt]
+|Project timelines
+|`gantt`
+
+|link:{% link _diagram_types/quadrant-chart.adoc %}[Quadrant]
+|Priority matrices
+|`quadrantChart`
+
+|link:{% link _diagram_types/requirement-diagram.adoc %}[Requirement]
+|Requirements traceability
+|`requirementDiagram`
+
+|link:{% link _diagram_types/c4-diagram.adoc %}[C4]
+|Software architecture
+|`C4Context`, `C4Container`, `C4Component`, `C4Dynamic`, `C4Deployment`
+
+|link:{% link _diagram_types/mindmap.adoc %}[Mindmap]
+|Hierarchical ideas
+|`mindmap`
+
+|link:{% link _diagram_types/timeline.adoc %}[Timeline]
+|Historical events
+|`timeline`
+
+|link:{% link _diagram_types/sankey-diagram.adoc %}[Sankey]
+|Flow quantities
+|`sankey-beta`
+
+|link:{% link _diagram_types/xy-chart.adoc %}[XY Chart]
+|Data plotting
+|`xychart-beta`
+
+|link:{% link _diagram_types/block-diagram.adoc %}[Block]
+|Component relationships
+|`block-beta`
+
+|link:{% link _diagram_types/architecture-diagram.adoc %}[Architecture]
+|System architecture
+|`architecture-beta`
+
+|link:{% link _diagram_types/kanban-diagram.adoc %}[Kanban]
+|Workflow boards
+|`kanban`
+|===
+
+== Choosing the Right Diagram Type
+
+=== For Processes and Workflows
+
+* **Flowchart** - General process flows
+* **Sequence** - Time-based interactions
+* **State** - State transitions
+* **User Journey** - User experience flows
+
+=== For Structure and Relationships
+
+* **Class** - Object relationships
+* **ER Diagram** - Data relationships
+* **Block** - Component relationships
+* **Architecture** - System structure
+
+=== For Data Visualization
+
+* **Pie Chart** - Proportions
+* **XY Chart** - Data points
+* **Sankey** - Flow quantities
+* **Quadrant** - Priority/complexity matrices
+
+=== For Planning and Tracking
+
+* **Gantt** - Project schedules
+* **Timeline** - Historical events
+* **Kanban** - Workflow status
+* **Requirement** - Requirements traceability
+
+=== For Software Development
+
+* **C4** - Architecture documentation
+* **Git Graph** - Repository history
+* **Class** - Code structure
+* **Sequence** - API interactions
+
+== Mermaid.js Compatibility
+
+All diagram types maintain syntax compatibility with Mermaid.js. See link:{% link _pages/compatibility.adoc %}[Compatibility Guide] for detailed comparison.
+
+== Examples
+
+Find complete examples in the GitHub repository:
+
+* https://github.com/claricle/sirena/tree/main/examples[Example Diagrams]
+
+== Need Help?
+
+* Check link:{% link _tutorials/creating-first-diagram.adoc %}[Creating Your First Diagram] tutorial
+* See link:{% link _guides/best-practices.adoc %}[Best Practices] guide
+* Visit https://github.com/claricle/sirena/issues[GitHub Issues] for support

data/docs/_diagram_types/info-diagram.adoc

@@ -0,0 +1,103 @@
+= Info Diagram
+:toc:
+:toclevels: 3
+
+== Purpose
+
+Info diagrams display simple informational messages or status information in Mermaid syntax. They are utility diagrams used to show system information, help text, or status messages.
+
+== Syntax
+
+=== Basic info diagram
+
+The simplest form displays just an info indicator:
+
+[source,mermaid]
+----
+info
+----
+
+=== Info with showInfo flag
+
+You can enable the `showInfo` flag to display additional information:
+
+[source,mermaid]
+----
+info showInfo
+----
+
+The `showInfo` flag can also be specified on a separate line:
+
+[source,mermaid]
+----
+info
+    showInfo
+----
+
+== Features
+
+=== Visual representation
+
+Info diagrams render as:
+
+* A centered box with informational styling (light blue background)
+* "Info" text or "Info: showInfo enabled" when the flag is set
+* Clean, minimal design suitable for displaying status messages
+
+=== Theme integration
+
+Info diagrams integrate with Sirena's theme system:
+
+* `node_bg`: Background color for the info box (default: light blue)
+* `node_stroke`: Border color for the info box (default: blue)
+* `label_text`: Text color for the message (default: dark blue)
+* Typography settings for font family and size
+
+== Implementation details
+
+=== Parser
+
+The info diagram parser (`Sirena::Parser::InfoParser`) uses Parslet grammar to handle:
+
+* Basic `info` keyword
+* Optional `showInfo` flag (inline or on separate line)
+* Additional text after `info` keyword (ignored for compatibility)
+
+=== Model
+
+The info diagram model (`Sirena::Diagram::Info`) contains:
+
+* `show_info`: Boolean flag indicating if showInfo is enabled
+
+=== Renderer
+
+The info renderer (`Sirena::Renderer::InfoRenderer`) creates:
+
+* A rounded rectangle box (400x100 pixels)
+* Centered text displaying the info message
+* Theme-aware styling for colors and typography
+
+== Examples
+
+=== Simple info
+
+[source,mermaid]
+----
+info
+----
+
+=== Info with flag enabled
+
+[source,mermaid]
+----
+info showInfo
+----
+
+== Use cases
+
+Info diagrams are useful for:
+
+* Displaying system status messages
+* Showing help text in documentation
+* Indicating informational states in workflows
+* Testing and debugging diagram rendering

data/docs/_diagram_types/kanban-diagram.adoc

@@ -0,0 +1,262 @@
+= Kanban Board Diagrams
+:toc:
+:toclevels: 3
+
+== Overview
+
+Kanban board diagrams visualize workflow with columns and cards, commonly used in agile project management and task tracking.
+
+== Syntax
+
+=== Basic Structure
+
+[source,mermaid]
+----
+kanban
+  column_id[Column Title]
+    card_id[Card Text]
+----
+
+=== Complete Example
+
+[source,mermaid]
+----
+kanban
+  id1[Todo]
+    docs[Create Documentation]
+    blog[Create Blog]@{ priority: 'High', ticket: 'MC-1001' }
+  id2[In Progress]
+    feature[Implement Feature]@{ assigned: 'dev1' }
+  id3[Done]
+    release[Release v1.0]
+----
+
+== Features
+
+=== Columns
+
+Columns represent workflow stages (e.g., Todo, In Progress, Done).
+
+.Column Definition
+[source,mermaid]
+----
+kanban
+  column_id[Column Name]
+----
+
+Where:
+
+* `column_id`: Unique identifier for the column
+* `Column Name`: Display name for the column
+
+=== Cards
+
+Cards represent individual work items or tasks.
+
+.Card Definition
+[source,mermaid]
+----
+kanban
+  column_id[Column Name]
+    card_id[Card Text]
+----
+
+Where:
+
+* `card_id`: Unique identifier for the card
+* `Card Text`: Description of the work item
+
+=== Card Metadata
+
+Cards can include metadata for additional information.
+
+.Metadata Syntax
+[source,mermaid]
+----
+card_id[Card Text]@{ key: 'value', key2: 'value2' }
+----
+
+==== Supported Metadata Fields
+
+* `assigned`: User assigned to the task
+* `ticket`: External ticket/issue number
+* `priority`: Priority level (e.g., High, Medium, Low)
+* `icon`: Icon identifier
+* `label`: Additional label or tag
+
+.Metadata Example
+[source,mermaid]
+----
+kanban
+  todo[Todo]
+    task[Fix Bug]@{
+      assigned: 'john',
+      priority: 'High',
+      ticket: 'JIRA-123'
+    }
+----
+
+== Layout
+
+The renderer automatically:
+
+* Positions columns horizontally from left to right
+* Stacks cards vertically within each column
+* Calculates appropriate spacing and dimensions
+* Displays metadata below card text
+
+== Styling
+
+Kanban diagrams support theme customization:
+
+* Column headers use primary theme color
+* Cards use light backgrounds with borders
+* Metadata uses secondary text color
+* Card count badges appear on column headers
+
+== Implementation Details
+
+=== Architecture
+
+The Kanban implementation follows the standard 7-file architecture:
+
+. **Diagram Model** (`lib/sirena/diagram/kanban.rb`)
+   - `KanbanCard`: Card with text and metadata
+   - `KanbanColumn`: Column containing cards
+   - `Kanban`: Complete board with columns
+
+. **Parser Grammar** (`lib/sirena/parser/grammars/kanban.rb`)
+   - Parslet grammar for kanban syntax
+   - Handles columns, cards, and metadata
+
+. **Transform** (`lib/sirena/parser/transforms/kanban.rb`)
+   - Converts parse tree to diagram model
+   - Extracts and validates metadata
+
+. **Parser** (`lib/sirena/parser/kanban.rb`)
+   - Integrates grammar and transform
+   - Creates diagram instances
+
+. **Layout Transform** (`lib/sirena/transform/kanban.rb`)
+   - Calculates column positions
+   - Determines card layout within columns
+   - Computes dimensions based on content
+
+. **Renderer** (`lib/sirena/renderer/kanban.rb`)
+   - Draws column backgrounds and headers
+   - Renders cards with text
+   - Displays metadata fields
+
+. **Tests**
+   - Parser tests: `spec/sirena/parser/kanban_spec.rb`
+   - Renderer tests: `spec/sirena/renderer/kanban_spec.rb`
+
+=== Data Flow
+
+[source]
+----
+Mermaid Source
+    ↓
+Grammar (Parslet)
+    ↓
+Parse Tree
+    ↓
+Transform
+    ↓
+Diagram Model (Kanban, KanbanColumn, KanbanCard)
+    ↓
+Layout Transform
+    ↓
+Positioned Layout
+    ↓
+Renderer
+    ↓
+SVG Output
+----
+
+== Examples
+
+=== Simple Kanban Board
+
+[source,mermaid]
+----
+kanban
+  todo[Todo]
+    task1[Task 1]
+    task2[Task 2]
+  doing[Doing]
+    task3[Task 3]
+  done[Done]
+    task4[Task 4]
+----
+
+=== Board with Metadata
+
+[source,mermaid]
+----
+kanban
+  backlog[Backlog]
+    story1[User Story 1]@{ priority: 'High' }
+    story2[User Story 2]@{ priority: 'Medium' }
+  development[Development]
+    feature1[Feature A]@{ assigned: 'alice', ticket: 'DEV-101' }
+  review[Review]
+    feature2[Feature B]@{ assigned: 'bob' }
+  completed[Completed]
+    feature3[Feature C]
+----
+
+=== Complex Workflow
+
+[source,mermaid]
+----
+kanban
+  ideas[Ideas]
+    idea1[New Feature Idea]@{ label: 'enhancement' }
+  planning[Planning]
+    plan1[Sprint Planning]@{ assigned: 'team' }
+  development[Development]
+    dev1[API Implementation]@{
+      assigned: 'dev1',
+      priority: 'High',
+      ticket: 'PROJ-201'
+    }
+  testing[Testing]
+    test1[Integration Tests]@{ assigned: 'qa1' }
+  deployment[Deployment]
+    deploy1[Production Release]@{ ticket: 'REL-1.0' }
+----
+
+== Best Practices
+
+=== Column Organization
+
+* Use clear, action-oriented column names
+* Limit the number of columns to 3-6 for readability
+* Order columns from left (start) to right (end) in workflow sequence
+
+=== Card Content
+
+* Keep card text concise and descriptive
+* Use consistent naming conventions
+* Include relevant metadata for tracking
+
+=== Metadata Usage
+
+* Use `assigned` for ownership clarity
+* Include `ticket` numbers for traceability
+* Set `priority` to highlight important items
+* Add `label` for categorization
+
+=== Board Structure
+
+* Group related cards in appropriate columns
+* Limit cards per column for visual clarity
+* Use metadata instead of embedding info in text
+
+== See Also
+
+* link:../README.adoc[Sirena Documentation]
+* link:user-journey-diagram.adoc[User Journey Diagrams]
+* link:gantt-diagram.adoc[Gantt Charts]
+* link:timeline-diagram.adoc[Timeline Diagrams]