> ## Documentation Index
> Fetch the complete documentation index at: https://calcs.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Interactive Diagrams

> Custom, interactive diagrams built with modern web technologies for enhanced user experience

Interactive Diagrams, also known as "Custom Diagrams", are a newer generation of visualization tools that provide enhanced interactivity and customization beyond the capabilities of legacy diagrams.

## Overview

Interactive diagrams are built using modern web technologies and can provide:

* Real-time parameter updates
* Interactive elements (zoom, pan, click)
* Custom animations and transitions
* Complex geometric visualizations
* Industry-specific diagram types

## Key Differences from Legacy Diagrams

<Accordion title="Interactive vs Legacy Diagrams">
  | Feature           | Legacy Diagrams        | Interactive Diagrams      |
  | ----------------- | ---------------------- | ------------------------- |
  | **Technology**    | Pre-built widget types | Custom JavaScript/SVG     |
  | **Customization** | Limited to parameters  | Fully customizable        |
  | **Interactivity** | Static display         | Interactive elements      |
  | **Development**   | Template configuration | Code development required |
  | **Performance**   | Fast rendering         | Optimized for complexity  |
  | **Maintenance**   | Platform managed       | Custom code maintenance   |
</Accordion>

## Development Workflow

Interactive diagrams are developed in separate GitHub repositories and then compiled for use in Calcs.com templates.

### Repository Structure

<CodeBlock title="Typical Repository Structure">
  ```
  custom-diagram-repo/
  ├── src/
  │   ├── interactive/          # Interactive diagram source
  │   │   ├── interface.ts
  │   │   └── ...
  │   ├── static/              # Static diagram source  
  │   │   ├── render.ts
  │   │   └── ...
  │   └── shared/              # Shared components
  │       ├── svgjsExtensions/
  │       ├── utils/
  │       └── assets/
  ├── dist/                    # Compiled output
  ├── package.json
  └── README.md
  ```
</CodeBlock>

### Development Setup

<Note>
  **First Time Setup (Mac):**

  1. Install brew: [https://brew.sh/](https://brew.sh/)
  2. Run `brew install npm` in terminal
  3. Clone the diagram repository
  4. Run `git pull` to get latest version
  5. Navigate to `/static` or `/interactive` folder
  6. Run `npm install`
</Note>

### Build Process

<CodeBlock title="Build and Deploy Steps">
  ```bash theme={null}
  # 1. Update repository
  git pull

  # 2. Navigate to diagram folder
  cd /static  # or /interactive

  # 3. Install dependencies
  npm install

  # 4. Compile diagram
  npm run-script compile

  # 5. Output files:
  # - Static: /dist/compiled.js
  # - Interactive: output/index.html
  ```
</CodeBlock>

## Implementation in Templates

Interactive diagrams are implemented using the diagram widget with custom types:

<CodeBlock title="Interactive Diagram Widget">
  ```json theme={null}
  {
      "type": "sheetTemplateWidgets", 
      "attributes": {
          "type": "diagram",
          "diagram": [
              {
                  "type": "custom",
                  "src": "path/to/compiled.js"
              }
          ],
          "equation": [
              {
                  "result": "{
                      diagramType: \"splice_atlas\",
                      param1: value1,
                      param2: value2,
                      // ... other parameters
                  }",
                  "condition": "@default"
              }
          ],
          "referenceId": "custom_diagram"
      }
  }
  ```
</CodeBlock>

### Multiple Diagram Types

Some repositories contain multiple diagram types, distinguished by the `diagramType` parameter:

<CodeBlock title="Multiple Diagram Types">
  ```javascript theme={null}
  {
      // Atlas Tube splice diagram
      diagramType: "splice_atlas",
      memberType: "tube",
      dimensions: tube_dimensions
  }

  // or

  {
      // Atlas Tube bracket diagram  
      diagramType: "bracket_atlas",
      bracketType: "corner",
      loads: applied_loads
  }
  ```
</CodeBlock>

## Data Flow Architecture

<Accordion title="Interactive Diagram Data Flow">
  The typical data flow for interactive diagrams follows this pattern:

  1. **Initialize**: `interface.ts : initialize()` - Sets up basic framework
  2. **Client Initialize**: `interface.ts : clientInitialize()` - Creates canvas and loads defaults
     * Calls `ParamsInterface.ts : defaultParams` - Loads default parameters
     * Calls `render.ts : update()` - Renders with default parameters
     * Calls `getTransformations.ts` - Calculates element positioning
  3. **Render**: `interface.ts : render()` - Updates with actual sheet data
     * Similar flow to clientInitialize but with real parameters
     * Clears canvas and re-renders with new data
</Accordion>

## Shared Components

Interactive diagrams leverage shared components for consistency:

### SVG Extensions

* Custom SVG elements specific to Calcs.com
* Reusable geometric shapes and annotations
* Standardized styling and behavior

### Utility Functions

* Helper functions for calculations and transformations
* Common geometric operations
* Data formatting and validation

### Asset Library

* SVG images for standard components
* Icons and symbols
* Material representations

## Testing and Development

<Note>
  **Testing Setup:**

  1. Run `npm start` to start development server
  2. Run `npm test` in a separate terminal
  3. Both must be running simultaneously
  4. Pass `diagramType` parameter in test calls
  5. Select diagram type in dropdown when testing
</Note>

### Video Tutorial

For a complete walkthrough of the development workflow:
[GitHub to Calcs Builder Workflow Video](https://www.loom.com/share/ac16400594814901b5f0b713010507bc)

## Best Practices

1. **Version Control**: Always work from the latest repository version
2. **Testing**: Test thoroughly before uploading to template builder
3. **Documentation**: Document parameters and behavior changes
4. **Performance**: Optimize for rendering speed and responsiveness
5. **Consistency**: Use shared components when possible

## Example: Atlas Tube Diagrams

The Atlas Tube custom diagrams provide a comprehensive example of interactive diagram implementation:

* **Repository**: [custom-diagrams-library](https://github.com/ClearCalcs/custom-diagrams-library)
* **Multiple Types**: Splice and bracket diagrams
* **Complex Geometry**: Parametric tube connections
* **Industry Specific**: Tailored for structural steel connections

<Tip>
  Interactive diagrams are powerful tools for creating highly specialized visualizations. While they require more development effort than legacy diagrams, they provide unmatched flexibility for complex engineering visualizations.
</Tip>

<Warning>
  Interactive diagrams require JavaScript/TypeScript development skills and ongoing maintenance. Consider using legacy diagrams for standard visualizations and reserve interactive diagrams for cases requiring unique functionality.
</Warning>