diagram-manager Component Documentation

qds-diagram-manager

A full-screen diagram management interface with integrated file explorer and diagram viewer/editor. This component combines qds-tree-view and qds-diagram-host in a split-panel layout for managing and editing diagram files stored in Azure Blob Storage.

Features

Split-panel layout: Resizable tree view on the left, diagram viewer/editor on the right
Azure Storage integration: Browse and load diagrams from Azure Blob Storage containers
Provider-based architecture: Uses ITreeDataProvider for storage-agnostic data operations
File filtering: Automatically filters to show only diagram files (.drawio, .xml, .svg)
Responsive resizing: Drag handle between panels for custom layout
Event-driven: Emits events for file selection, diagram loading, and errors
Full-screen optimized: Designed to fill 100vw x 100vh viewport

Installation

The component is included in the Quantum Design System and automatically registered when you import the component library:

<script type="module" src="https://cdn.q360.ai/assets/components/index.js"></script>

Or import the specific component:

<script type="module" src="https://cdn.q360.ai/assets/components/diagram-manager/qds-diagram-manager.js"></script>

Dependencies

The diagram manager requires these components:

qds-tree-view - File tree display
qds-diagram-host - Diagram viewer/editor
AzureStorageTreeProvider - Azure Storage data provider

These are automatically loaded when you use the component.

Basic Usage

With Quantum Auth

<qds-diagram-manager
  storage-account="mystorageaccount"
  container="diagrams"
  auth-method="quantum-auth">
</qds-diagram-manager>

With SAS Token

<qds-diagram-manager
  storage-account="mystorageaccount"
  container="diagrams"
  auth-method="sas-token"
  sas-token="your-sas-token-here">
</qds-diagram-manager>

With Base Path Filter

<qds-diagram-manager
  storage-account="mystorageaccount"
  container="diagrams"
  base-path="engineering/schematics"
  tree-width="400px">
</qds-diagram-manager>

With Initial Path (Auto-open specific diagram)

<qds-diagram-manager
  storage-account="mystorageaccount"
  container="diagrams"
  initial-path="engineering/schematics/system-architecture.drawio.svg">
</qds-diagram-manager>

This will automatically navigate to and open the specified diagram when the component loads.

Attributes

Attribute	Type	Default	Description
`storage-account`	string	-	Required. Azure storage account name
`container`	string	-	Required. Azure storage container name
`base-path`	string	-	Optional base path to filter files (e.g., “folder/subfolder”)
`initial-path`	string	-	Optional path to a specific file to automatically open on load (e.g., “folder/diagram.drawio.svg”)
`tree-width`	string	`300px`	Initial width of the tree panel
`auth-method`	string	`quantum-auth`	Authentication method: `quantum-auth` or `sas-token`
`sas-token`	string	-	SAS token (required if `auth-method` is `sas-token`)

Properties

`dataProvider`

Get or set the data provider instance.

const manager = document.querySelector('qds-diagram-manager');

// Get current provider
const provider = manager.dataProvider;

// Set custom provider
import { AzureStorageTreeProvider } from './providers/AzureStorageTreeProvider.js';
manager.dataProvider = new AzureStorageTreeProvider({
  storageAccount: 'myaccount',
  container: 'mycontainer',
  authMethod: 'quantum-auth'
});

`selectedNode`

Get the currently selected node (read-only).

const manager = document.querySelector('qds-diagram-manager');
const selected = manager.selectedNode;

if (selected) {
  console.log(`Selected: ${selected.name} (${selected.type})`);
}

Events

`file-selected`

Fired when a file is selected in the tree view.

manager.addEventListener('file-selected', (event) => {
  const { node } = event.detail;
  console.log('File selected:', node.name, node.path);
});

Event Detail:

{
  node: TreeNode  // The selected tree node
}

`diagram-loaded`

Fired when a diagram is loaded into the diagram-host.

manager.addEventListener('diagram-loaded', (event) => {
  const { path, name } = event.detail;
  console.log('Diagram loaded:', name, 'from', path);
});

Event Detail:

{
  path: string  // Storage URL path
  name: string  // Diagram filename
}

`error`

Fired when an error occurs (provider initialization, file loading, etc.).

manager.addEventListener('error', (event) => {
  const { error } = event.detail;
  console.error('Error:', error.message);
});

Event Detail:

{
  error: Error  // The error object
}

CSS Parts

Style internal elements using CSS ::part() selector:

Part	Description
`container`	The main container element
`tree-panel`	The left panel containing the tree view
`diagram-panel`	The right panel containing the diagram host
`resize-handle`	The drag handle between panels

Example Styling

qds-diagram-manager::part(tree-panel) {
  background: #f5f5f5;
}

qds-diagram-manager::part(resize-handle) {
  background: #007bff;
}

qds-diagram-manager::part(diagram-panel) {
  background: #ffffff;
}

Advanced Examples

Programmatic Configuration

const manager = document.createElement('qds-diagram-manager');

// Set attributes
manager.setAttribute('storage-account', 'myaccount');
manager.setAttribute('container', 'diagrams');
manager.setAttribute('base-path', 'engineering');
manager.setAttribute('tree-width', '400px');

// Listen for events
manager.addEventListener('file-selected', (event) => {
  console.log('Selected:', event.detail.node.name);
});

manager.addEventListener('error', (event) => {
  alert(`Error: ${event.detail.error.message}`);
});

// Add to page
document.body.appendChild(manager);

Custom Provider

import { ITreeDataProvider } from './providers/ITreeDataProvider.js';
import { QdsDiagramManager } from './diagram-manager/qds-diagram-manager.js';

// Create custom provider (e.g., for local files or database)
class CustomTreeProvider implements ITreeDataProvider {
  // Implement all ITreeDataProvider methods
  async getRootNodes() { /* ... */ }
  async getChildren(nodeId) { /* ... */ }
  // ... other methods
}

// Use custom provider
const manager = document.querySelector('qds-diagram-manager');
manager.dataProvider = new CustomTreeProvider();

Reacting to Selection

const manager = document.querySelector('qds-diagram-manager');

manager.addEventListener('file-selected', (event) => {
  const { node } = event.detail;

  // Check file type
  if (node.metadata?.extension === 'drawio') {
    console.log('Draw.io diagram selected');
  }

  // Update external UI
  document.querySelector('#filename-display').textContent = node.name;
  document.querySelector('#file-path').textContent = node.path;
});

Changing Configuration Dynamically

const manager = document.querySelector('qds-diagram-manager');

// Change storage account
function switchAccount(accountName, containerName) {
  manager.setAttribute('storage-account', accountName);
  manager.setAttribute('container', containerName);
  // Provider will reinitialize automatically
}

// Change tree width
function setTreeWidth(width) {
  manager.setAttribute('tree-width', `${width}px`);
}

// Navigate to a specific diagram
function openDiagram(filePath) {
  manager.setAttribute('initial-path', filePath);
  // Note: This will only work once per page load
  // For dynamic navigation, you'll need to reinitialize the component
}

// Example usage
switchAccount('production-storage', 'prod-diagrams');
setTreeWidth(500);
openDiagram('engineering/network-diagram.drawio.svg');

Direct Linking to Diagrams

You can create direct links to specific diagrams using the URL query string. The component automatically checks for a qds-diagram-manager-path parameter:

<!-- No JavaScript needed! Just add the component -->
<qds-diagram-manager
  storage-account="mystorageaccount"
  container="diagrams">
</qds-diagram-manager>

Example URL: https://yourapp.com/?qds-diagram-manager-path=engineering/system-architecture.drawio.svg

The component will automatically detect the query parameter and open the specified diagram. This works alongside the initial-path attribute - if both are present, the attribute takes precedence.

Full-Screen Layout

The component is designed to fill the entire viewport (100vw x 100vh). For proper full-screen display:

<!DOCTYPE html>
<html>
<head>
  <style>
    html, body {
      margin: 0;
      padding: 0;
      width: 100%;
      height: 100%;
      overflow: hidden;
    }
  </style>
</head>
<body>
  <qds-diagram-manager
    storage-account="myaccount"
    container="diagrams">
  </qds-diagram-manager>
</body>
</html>

Integration with Quantum Auth

The component integrates seamlessly with the Quantum Authentication system:

<!-- Load quantum-auth first -->
<script src="https://cdn.q360.ai/auth/quantum-auth.js"></script>

<!-- Then load the diagram manager -->
<script type="module" src="https://cdn.q360.ai/assets/components/index.js"></script>

<qds-diagram-manager
  storage-account="myaccount"
  container="diagrams"
  auth-method="quantum-auth">
</qds-diagram-manager>

The component will automatically:

Wait for quantum-auth-initialized event
Get authentication tokens from the auth service
Use tokens for Azure Storage API calls
Handle token refresh automatically

Browser Support

Chrome 90+
Firefox 88+
Safari 14+
Edge 90+

Requires ES6 modules and Shadow DOM support.

Accessibility

The component is built with accessibility in mind:

Tree view supports full keyboard navigation (arrow keys, Enter, Space)
Proper ARIA labels and roles
Focus management between panels
Screen reader compatible

Performance

Tree data is cached after initial load
Lazy loading of folder children (configurable)
Efficient DOM updates using shadow DOM
Handles 100+ files without performance issues

Troubleshooting

Tree view is empty

Cause: Missing storage-account or container attributes, or authentication failed

Solution:

// Check configuration
const manager = document.querySelector('qds-diagram-manager');
console.log('Storage account:', manager.getAttribute('storage-account'));
console.log('Container:', manager.getAttribute('container'));

// Listen for errors
manager.addEventListener('error', (event) => {
  console.error('Error details:', event.detail.error);
});

Diagram doesn’t load

Cause: File might not be a valid Draw.io diagram, or path construction failed

Solution:

manager.addEventListener('diagram-loaded', (event) => {
  console.log('Loaded from:', event.detail.path);
  console.log('File name:', event.detail.name);
});

manager.addEventListener('error', (event) => {
  console.error('Load error:', event.detail.error.message);
});

Authentication errors

Cause: Quantum auth not initialized or token request failed

Solution:

Ensure quantum-auth is loaded before the diagram manager
Check that quantum-auth is properly configured
Verify Azure Storage permissions

// Check auth status
document.addEventListener('quantum-auth-initialized', () => {
  console.log('Auth initialized');
});

// Or use SAS token as fallback
manager.setAttribute('auth-method', 'sas-token');
manager.setAttribute('sas-token', 'your-token');

qds-tree-view - File tree component
qds-diagram-host - Diagram viewer/editor
ITreeDataProvider - Data provider interface
AzureStorageTreeProvider - Azure Storage implementation

License

Part of the Quantum Design System. Internal use only.

diagram-manager Component Documentation

qds-diagram-manager

Features

Installation

Dependencies

Basic Usage

With Quantum Auth

With SAS Token

With Base Path Filter

With Initial Path (Auto-open specific diagram)

Attributes

Properties

dataProvider

selectedNode

Events

file-selected

diagram-loaded

error

CSS Parts

Example Styling

Advanced Examples

Programmatic Configuration

Custom Provider

Reacting to Selection

Changing Configuration Dynamically

Direct Linking to Diagrams

Full-Screen Layout

Integration with Quantum Auth

Browser Support

Accessibility

Performance

Troubleshooting

Tree view is empty

Diagram doesn’t load

Authentication errors

Related Components

License

`dataProvider`

`selectedNode`

`file-selected`

`diagram-loaded`

`error`