sirena 0.1.0

data/docs/_diagram_types/packet-diagram.adoc

@@ -0,0 +1,378 @@
+= Packet diagrams
+:toc:
+:toclevels: 3
+
+== Overview
+
+Packet diagrams in Sirena visualize network packet structures and protocol formats. They show how data is organized within network packets, including field layouts, bit ranges, and data organization across multiple rows.
+
+Packet diagrams are useful for:
+
+* Documenting network protocol specifications
+* Visualizing packet header structures
+* Teaching network communication concepts
+* Analyzing packet formats and field layouts
+* Designing new network protocols
+* Understanding data transmission formats
+
+== Syntax specification
+
+=== Diagram declaration
+
+Packet diagrams are declared using the `packet-beta` keyword:
+
+[source,mermaid]
+----
+packet-beta
+    <diagram-content>
+----
+
+=== Title
+
+Packets can have a descriptive title:
+
+[source,mermaid]
+----
+packet-beta
+  title TCP Header Structure
+----
+
+=== Field definitions
+
+Fields represent segments of the packet with bit ranges:
+
+[source,mermaid]
+----
+bit_start-bit_end: "Field Label"
+----
+
+Where:
+
+* `bit_start` - The starting bit position (0-based)
+* `bit_end` - The ending bit position (inclusive)
+* `Field Label` - Descriptive label for the field
+
+==== Bit range format
+
+Bit ranges use the format `start-end`:
+
+[source,mermaid]
+----
+packet-beta
+  0-7: "Source Port"
+  8-15: "Destination Port"
+  16-31: "Sequence Number"
+----
+
+This defines:
+
+* Bits 0-7 (8 bits): Source Port
+* Bits 8-15 (8 bits): Destination Port
+* Bits 16-31 (16 bits): Sequence Number
+
+== Examples
+
+=== Basic packet structure
+
+.Simple 32-bit packet
+[example]
+====
+[source,mermaid]
+----
+packet-beta
+  title Hello world
+  0-10: "hello"
+----
+
+This creates a simple packet with:
+
+* A title
+* One field spanning bits 0-10
+====
+
+=== TCP header structure
+
+.TCP packet header
+[example]
+====
+[source,mermaid]
+----
+packet-beta
+  title TCP Header
+  0-15: "Source Port"
+  16-31: "Destination Port"
+  32-63: "Sequence Number"
+  64-95: "Acknowledgment Number"
+  96-99: "Data Offset"
+  100-105: "Reserved"
+  106: "URG"
+  107: "ACK"
+  108: "PSH"
+  109: "RST"
+  110: "SYN"
+  111: "FIN"
+  112-127: "Window Size"
+  128-143: "Checksum"
+  144-159: "Urgent Pointer"
+----
+
+This demonstrates:
+
+* Standard TCP header fields
+* Mix of different field sizes
+* Single-bit flags (URG, ACK, etc.)
+* Multi-byte fields (ports, sequence numbers)
+====
+
+=== IP packet header
+
+.IPv4 packet header
+[example]
+====
+[source,mermaid]
+----
+packet-beta
+  title IPv4 Header
+  0-3: "Version"
+  4-7: "IHL"
+  8-13: "DSCP"
+  14-15: "ECN"
+  16-31: "Total Length"
+  32-47: "Identification"
+  48-50: "Flags"
+  51-63: "Fragment Offset"
+  64-71: "Time to Live"
+  72-79: "Protocol"
+  80-95: "Header Checksum"
+  96-127: "Source IP Address"
+  128-159: "Destination IP Address"
+----
+
+This shows:
+
+* IPv4 header structure
+* Various field sizes from 2 bits to 32 bits
+* Standard network protocol layout
+====
+
+=== UDP packet
+
+.UDP datagram structure
+[example]
+====
+[source,mermaid]
+----
+packet-beta
+  title UDP Datagram
+  0-15: "Source Port"
+  16-31: "Destination Port"
+  32-47: "Length"
+  48-63: "Checksum"
+  64-95: "Data (first 32 bits)"
+----
+
+This demonstrates:
+
+* Simple UDP header
+* Data section indicator
+* Standard 32-bit row layout
+====
+
+=== Ethernet frame
+
+.Ethernet frame structure
+[example]
+====
+[source,mermaid]
+----
+packet-beta
+  title Ethernet Frame
+  0-47: "Destination MAC"
+  48-95: "Source MAC"
+  96-111: "EtherType"
+  112-143: "Payload (start)"
+----
+
+This shows:
+
+* MAC address fields (48 bits each)
+* EtherType field
+* Payload beginning
+====
+
+== Features
+
+=== Flexible field sizes
+
+Fields can span any number of bits:
+
+[source,mermaid]
+----
+packet-beta
+  0-0: "Single bit"
+  1-8: "8 bits"
+  9-40: "32 bits"
+  41-104: "64 bits"
+----
+
+=== Multi-row layout
+
+Packets automatically wrap to multiple rows (typically 32 bits per row):
+
+[source,mermaid]
+----
+packet-beta
+  0-31: "Row 1"
+  32-63: "Row 2"
+  64-95: "Row 3"
+----
+
+=== Automatic bit numbering
+
+Bit positions are automatically labeled in the diagram for easy reference.
+
+=== Empty labels
+
+Fields can have empty labels if needed:
+
+[source,mermaid]
+----
+packet-beta
+  0-7: ""
+  8-15: "Used Field"
+----
+
+== Limitations
+
+=== Currently not supported
+
+The following features are not yet supported in Sirena:
+
+* Custom row widths (fixed at 32 bits per row)
+* Color customization for specific fields
+* Field descriptions beyond labels
+* Nested or hierarchical field structures
+* Variable-length fields
+* Click events or interactive elements
+
+=== Known issues
+
+* Very long field labels may be truncated
+* Packets with many fields may become large
+* Single-bit fields in crowded areas may be hard to read
+
+== Best practices
+
+=== Use descriptive field names
+
+Give fields clear, technical names:
+
+[source,mermaid]
+----
+%% Good
+packet-beta
+  0-3: "Version"
+  4-7: "Header Length"
+
+%% Less clear
+packet-beta
+  0-3: "V"
+  4-7: "HL"
+----
+
+=== Include title for context
+
+Always include a title identifying the packet type:
+
+[source,mermaid]
+----
+%% Good
+packet-beta
+  title TCP Segment
+  ...
+
+%% Missing context
+packet-beta
+  0-15: "Port"
+----
+
+=== Follow protocol standards
+
+For standard protocols, use official field names:
+
+[source,mermaid]
+----
+%% Good - standard TCP terminology
+packet-beta
+  title TCP Header
+  0-15: "Source Port"
+  16-31: "Destination Port"
+
+%% Confusing - non-standard names
+packet-beta
+  title TCP
+  0-15: "From Port"
+  16-31: "To Port"
+----
+
+=== Organize fields logically
+
+Order fields as they appear in the actual packet:
+
+[source,mermaid]
+----
+%% Good - sequential order
+packet-beta
+  0-15: "Field A"
+  16-31: "Field B"
+  32-47: "Field C"
+
+%% Confusing - out of order
+packet-beta
+  32-47: "Field C"
+  0-15: "Field A"
+  16-31: "Field B"
+----
+
+=== Document all header fields
+
+Include all relevant header fields for completeness:
+
+[source,mermaid]
+----
+%% Good - complete header
+packet-beta
+  title UDP Header
+  0-15: "Source Port"
+  16-31: "Destination Port"
+  32-47: "Length"
+  48-63: "Checksum"
+
+%% Incomplete
+packet-beta
+  title UDP Header
+  0-15: "Source Port"
+  16-31: "Destination Port"
+----
+
+=== Use standard bit numbering
+
+Start from 0 and follow protocol specifications:
+
+[source,mermaid]
+----
+%% Good - standard 0-based numbering
+packet-beta
+  0-7: "First byte"
+  8-15: "Second byte"
+
+%% Confusing - 1-based
+packet-beta
+  1-8: "First byte"
+  9-16: "Second byte"
+----
+
+== Related documentation
+
+* <<index.adoc#,Diagram types overview>>
+* link:https://mermaid.js.org/syntax/packet.html[Official Mermaid packet documentation]

data/docs/_diagram_types/pie-chart.adoc

@@ -0,0 +1,335 @@
+= Pie Chart Diagrams
+:toc:
+:toclevels: 3
+
+== General
+
+Pie chart diagrams visualize proportional data as circular segments. Each slice represents a portion of the whole, making it easy to see relative sizes and distributions at a glance.
+
+The pie chart implementation in Sirena follows the established Parslet architecture with full support for:
+
+* Multiple data slices with labels and values
+* Optional title display
+* Optional data value display (`showData` flag)
+* Accessibility features (accTitle, accDescr)
+* Decimal and negative values
+* Theme integration for colors
+* Case-insensitive syntax
+
+== Architecture
+
+The pie chart implementation consists of:
+
+* [`Diagram::Pie`](../lib/sirena/diagram/pie.rb) - Model classes for pie charts
+* [`Parser::Grammars::Pie`](../lib/sirena/parser/grammars/pie.rb) - Parslet grammar
+* [`Parser::Transforms::Pie`](../lib/sirena/parser/transforms/pie.rb) - Parse tree transformer
+* [`Parser::PieParser`](../lib/sirena/parser/pie.rb) - Main parser
+* [`Transform::PieTransform`](../lib/sirena/transform/pie.rb) - Layout transformer
+* [`Renderer::PieRenderer`](../lib/sirena/renderer/pie.rb) - SVG renderer
+
+== Syntax
+
+=== Basic pie chart
+
+The simplest pie chart requires only the `pie` keyword and data entries:
+
+[source,mermaid]
+----
+pie
+    "Apples" : 42
+    "Oranges" : 58
+----
+
+=== Pie chart with title
+
+Add a title using the `title` keyword in the header:
+
+[source,mermaid]
+----
+pie title Sales Distribution
+    "Product A" : 45
+    "Product B" : 30
+    "Product C" : 25
+----
+
+=== Pie chart with data values displayed
+
+Use the `showData` flag to display percentage values on labels:
+
+[source,mermaid]
+----
+pie showData
+    "Category A" : 100
+    "Category B" : 50
+----
+
+Where,
+
+`showData`:: Optional flag that enables display of data values and percentages on the chart.
+
+=== Data entries
+
+Each data entry consists of a quoted label, colon, and numeric value:
+
+[source,mermaid]
+----
+pie
+    "Label Text" : 42.5
+    "Another Label" : 57.5
+----
+
+Where,
+
+`"Label Text"`:: The label for the slice, must be in quotes (single or double).
+`value`:: Numeric value (integer or decimal), can be negative.
+
+=== Accessibility features
+
+[[accessibility-features]]
+==== General
+
+Pie charts support accessibility attributes for screen readers:
+
+[source,mermaid]
+----
+pie title Quarterly Report
+    accTitle: Q1-Q4 Sales Data
+    accDescr: Sales distribution across four quarters
+    "Q1" : 25
+    "Q2" : 30
+    "Q3" : 20
+    "Q4" : 25
+----
+
+Where,
+
+`accTitle`:: Accessible title for screen readers (single line).
+`accDescr`:: Accessible description for screen readers.
+
+==== Multi-line descriptions
+
+Accessibility descriptions can span multiple lines using braces:
+
+[source,mermaid]
+----
+pie title Annual Sales
+    accDescr {
+        This chart shows the annual sales distribution
+        across different product categories for 2024
+    }
+    "Electronics" : 40
+    "Clothing" : 35
+    "Food" : 25
+----
+
+=== Comments
+
+Comments are supported using `%%`:
+
+[source,mermaid]
+----
+pie
+    %% This is a comment
+    "Item 1" : 60
+    %% Another comment
+    "Item 2" : 40
+----
+
+== Model Structure
+
+The pie chart uses a hierarchical model structure:
+
+[source]
+----
+Diagram::Pie
+  ├── title (String, optional)
+  ├── show_data (Boolean, default: false)
+  ├── acc_title (String, optional)
+  ├── acc_description (String, optional)
+  └── slices (Array<PieSlice>)
+        └── PieSlice
+              ├── label (String)
+              └── value (Float)
+----
+
+.Example of a pie chart model with assigned values
+====
+[source]
+----
+Pie
+├── title = "Sales Report"
+├── show_data = true
+├── slices
+│   ├── PieSlice
+│   │   ├── label = "Product A"
+│   │   └── value = 45.0
+│   ├── PieSlice
+│   │   ├── label = "Product B"
+│   │   └── value = 30.0
+│   └── PieSlice
+│       ├── label = "Product C"
+│       └── value = 25.0
+└── total_value = 100.0
+----
+====
+
+== Rendering
+
+=== Layout calculation
+
+The renderer calculates:
+
+1. **Percentages**: Each slice's percentage of the total
+2. **Angles**: Each slice's angle in degrees (0-360)
+3. **Positions**: Label positions around the circle
+4. **Colors**: Colors from theme or default palette
+
+.Angle calculation
+====
+Given slices with values [45, 30, 25]:
+
+* Total value: 100
+* Slice 1: (45/100) × 360° = 162°
+* Slice 2: (30/100) × 360° = 108°
+* Slice 3: (25/100) × 360° = 90°
+====
+
+=== SVG generation
+
+The renderer creates:
+
+* SVG path elements for each pie slice
+* Text elements for labels
+* Optional title text
+* Optional percentage/value display
+
+== Theme Integration
+
+Pie charts use theme colors for slices and text:
+
+[source,yaml]
+----
+colors:
+  pie_slice_0: "#4472C4"  # First slice color
+  pie_slice_1: "#ED7D31"  # Second slice color
+  # ... additional slice colors
+  label_text: "#000000"   # Label text color
+  node_stroke: "#ffffff"  # Slice border color
+----
+
+If theme doesn't specify pie slice colors, the renderer uses a default color palette that cycles through 12 colors.
+
+== Advanced Features
+
+=== Decimal values
+
+Pie charts support decimal values for precise proportions:
+
+[source,mermaid]
+----
+pie title Market Share
+    "Company A" : 42.7
+    "Company B" : 31.2
+    "Company C" : 26.1
+----
+
+=== Negative values
+
+Negative values are allowed (though uncommon in pie charts):
+
+[source,mermaid]
+----
+pie
+    "Profit" : 100
+    "Loss" : -20
+----
+
+=== Empty diagrams
+
+Empty pie charts (for testing) are valid:
+
+[source,mermaid]
+----
+pie
+----
+
+=== Case-insensitive syntax
+
+The pie keyword is case-insensitive and accepts variants:
+
+[source,mermaid]
+----
+pie          # lowercase
+Pie          # capitalized
+pie chart    # with 'chart' suffix
+Pie Chart    # fully capitalized
+----
+
+== Examples
+
+=== Simple distribution
+
+[source,mermaid]
+----
+pie title Browser Usage
+    "Chrome" : 65
+    "Firefox" : 20
+    "Safari" : 10
+    "Others" : 5
+----
+
+=== Detailed report with data display
+
+[source,mermaid]
+----
+pie showData title Q4 Revenue by Region
+    "North America" : 45.2
+    "Europe" : 28.7
+    "Asia Pacific" : 18.3
+    "Latin America" : 5.4
+    "Other" : 2.4
+----
+
+=== Accessible chart
+
+[source,mermaid]
+----
+pie title Department Budget Allocation
+    accTitle: 2024 Budget Distribution
+    accDescr {
+        Budget allocation across departments.
+        Engineering receives the largest share at 40%
+    }
+    "Engineering" : 40
+    "Marketing" : 25
+    "Sales" : 20
+    "Operations" : 15
+----
+
+== Testing
+
+The pie chart implementation includes:
+
+* 49 Mermaid test fixtures (100% passing)
+* 13 RSpec tests covering all features
+* Parser, transform, and renderer tests
+* Edge case handling (empty diagrams, negative values, etc.)
+
+Run tests with:
+
+[source,shell]
+----
+bundle exec rspec spec/sirena/parser/pie_spec.rb
+----
+
+== Limitations
+
+* Very small slices (< 1%) may have overlapping labels
+* Extremely long labels may extend beyond the SVG bounds
+* The renderer uses a fixed circular layout (no 3D or exploded slices)
+
+== See Also
+
+* link:index.adoc[Documentation Index]
+* link:../lib/sirena/diagram/pie.rb[Pie Diagram Model]
+* link:../lib/sirena/renderer/pie.rb[Pie Renderer]