@bluealba/platform-cli 1.0.1 → 1.1.0

package/docs/guides/mermaid-diagrams.mdx

@@ -0,0 +1,212 @@
+---
+title: Using Interactive Mermaid Diagrams
+description: Guide to using the enhanced Mermaid diagram component with zoom and code viewing capabilities
+---
+
+import MermaidDiagram from '~/components/MermaidDiagram.astro';
+import { Aside } from '@astrojs/starlight/components';
+
+This guide demonstrates how to create interactive Mermaid diagrams in the documentation using our enhanced component.
+
+## Features
+
+The `MermaidDiagram` component provides several interactive features:
+
+- **Zoom Controls**: Zoom in, zoom out, and reset to default view
+- **Pan/Drag**: Click and drag to pan around large diagrams
+- **Wheel Zoom**: Hold Ctrl/Cmd and scroll to zoom smoothly
+- **View Source**: Toggle to see the raw Mermaid code
+- **Copy Code**: Easy one-click copy to clipboard
+
+## Basic Example
+
+Here's a simple flowchart:
+
+<MermaidDiagram
+  title="Simple Workflow"
+  code={`graph TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Process]
+    B -->|No| D[End]
+    C --> D`}
+/>
+
+## Complex Architecture Diagram
+
+For larger diagrams, the zoom and pan features become very useful:
+
+<MermaidDiagram
+  title="Microservices Architecture"
+  height="700px"
+  code={`graph TB
+    subgraph "Client Layer"
+        Web[Web Browser]
+        Mobile[Mobile App]
+    end
+
+    subgraph "API Gateway"
+        Gateway[API Gateway<br/>- Authentication<br/>- Rate Limiting<br/>- Load Balancing]
+    end
+
+    subgraph "Services Layer"
+        Auth[Auth Service]
+        User[User Service]
+        Order[Order Service]
+        Payment[Payment Service]
+        Notification[Notification Service]
+    end
+
+    subgraph "Data Layer"
+        DB1[(User DB)]
+        DB2[(Order DB)]
+        DB3[(Payment DB)]
+        Cache[(Redis Cache)]
+        Queue[Message Queue]
+    end
+
+    Web --> Gateway
+    Mobile --> Gateway
+    Gateway --> Auth
+    Gateway --> User
+    Gateway --> Order
+    Gateway --> Payment
+
+    Auth --> DB1
+    User --> DB1
+    Order --> DB2
+    Payment --> DB3
+
+    Order --> Queue
+    Payment --> Queue
+    Queue --> Notification
+
+    User --> Cache
+    Order --> Cache`}
+/>
+
+## Sequence Diagram
+
+Perfect for documenting API flows:
+
+<MermaidDiagram
+  title="Authentication Flow"
+  code={`sequenceDiagram
+    participant User
+    participant Browser
+    participant Gateway
+    participant AuthService
+    participant Database
+
+    User->>Browser: Enter credentials
+    Browser->>Gateway: POST /auth/login
+    Gateway->>AuthService: Validate credentials
+    AuthService->>Database: Query user
+    Database-->>AuthService: User data
+    AuthService-->>Gateway: JWT Token
+    Gateway-->>Browser: Set cookie
+    Browser-->>User: Redirect to dashboard`}
+/>
+
+## Entity Relationship Diagram
+
+Useful for database schema documentation:
+
+<MermaidDiagram
+  title="Database Schema"
+  code={`erDiagram
+    USER ||--o{ ORDER : places
+    USER {
+        string id PK
+        string username
+        string email
+        datetime created_at
+    }
+    ORDER ||--|{ ORDER_ITEM : contains
+    ORDER {
+        string id PK
+        string user_id FK
+        decimal total
+        string status
+        datetime created_at
+    }
+    PRODUCT ||--o{ ORDER_ITEM : "ordered in"
+    PRODUCT {
+        string id PK
+        string name
+        decimal price
+        int stock
+    }
+    ORDER_ITEM {
+        string id PK
+        string order_id FK
+        string product_id FK
+        int quantity
+        decimal price
+    }`}
+/>
+
+## State Diagram
+
+Great for documenting workflows:
+
+<MermaidDiagram
+  title="Order State Machine"
+  code={`stateDiagram-v2
+    [*] --> Pending
+    Pending --> Processing: Payment confirmed
+    Pending --> Cancelled: User cancels
+    Processing --> Shipped: Items dispatched
+    Processing --> Cancelled: Out of stock
+    Shipped --> Delivered: Received by customer
+    Delivered --> [*]
+    Cancelled --> [*]`}
+/>
+
+## Tips for Using the Component
+
+<Aside type="tip">
+**Zoom and Pan**: For complex diagrams, use the zoom controls or Ctrl/Cmd + scroll wheel to zoom. Click and drag to pan around the diagram.
+</Aside>
+
+<Aside type="tip">
+**View Source**: Click the code icon to see and copy the Mermaid source code. This is useful for learning or reusing diagram code.
+</Aside>
+
+<Aside type="note">
+**Custom Height**: For diagrams with many nodes, increase the height using the `height` prop: `height="800px"`
+</Aside>
+
+## Component Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `code` | `string` | Yes | - | The Mermaid diagram code |
+| `title` | `string` | No | - | Optional title shown above the diagram |
+| `height` | `string` | No | `"500px"` | Height of the diagram viewport |
+
+## Usage in MDX
+
+```jsx
+import MermaidDiagram from '~/components/MermaidDiagram.astro';
+
+<MermaidDiagram
+  title="My Diagram"
+  height="600px"
+  code={`graph LR
+    A --> B
+    B --> C`}
+/>
+```
+
+## Keyboard Shortcuts
+
+- **Ctrl/Cmd + Scroll**: Zoom in/out
+- **Click + Drag**: Pan around the diagram
+
+## Browser Support
+
+The component works in all modern browsers with support for:
+- ES6+ JavaScript
+- CSS Custom Properties
+- SVG rendering
+- Clipboard API (for copy functionality)