diagram-host Component Documentation

qds-diagram-host

A web component that displays diagrams using diagrams.net (draw.io) viewer with optional Azure Blob Storage backend. Users can view diagrams and edit them in a popup editor window.

Features

Display diagrams using diagrams.net viewer with full toolbar (zoom, layers, navigation)
Edit diagrams in popup window with diagrams.net editor
Optional Azure Blob Storage integration for persistent storage
Automatic save/load from storage
Local diagram updates even if storage fails
Clean, themeable UI with custom edit button

Basic Usage

Without Storage (In-Memory)

<qds-diagram-host
  width="100%"
  height="600px">
</qds-diagram-host>

This creates an empty diagram that can be edited. Changes are kept in memory during the session.

With Diagram XML

<qds-diagram-host
  diagram="<mxGraphModel>...</mxGraphModel>"
  width="100%"
  height="600px">
</qds-diagram-host>

Read-Only Diagram

<qds-diagram-host
  diagram="<mxGraphModel>...</mxGraphModel>"
  editable="false"
  width="100%"
  height="600px">
</qds-diagram-host>

With Azure Blob Storage

Note: Storage integration requires authentication via the Quantum Auth Service.

<!-- Standard .drawio format using default storage account and container -->
<qds-diagram-host
  path="engineering/widget-x/assembly"
  drawing-name="main-diagram"
  width="100%"
  height="600px">
</qds-diagram-host>

<!-- SVG format with embedded diagram data -->
<qds-diagram-host
  path="engineering/widget-x/assembly"
  drawing-name="flowchart.drawio.svg"
  width="100%"
  height="600px">
</qds-diagram-host>

<!-- Using a custom storage account/container -->
<qds-diagram-host
  storage-account="yourstorageaccount"
  container="yourcustomcontainer"
  path="engineering/widget-x/assembly"
  drawing-name="main-diagram"
  width="100%"
  height="600px">
</qds-diagram-host>

Attributes

Display Attributes

Attribute	Type	Default	Description
`width`	String	`100%`	Width of the diagram container
`height`	String	`600px`	Height of the diagram container
`diagram`	String	Empty diagram	XML content of the diagram
`editable`	Boolean	`true`	Whether the diagram can be edited (shows/hides Edit button)
`libraries`	String	`Quantum`	Comma-separated list of custom library names to load (without .xml extension)

Storage Attributes

When all required storage attributes (path and drawing-name) are provided and the user is authenticated, the component will automatically load from and save to Azure Blob Storage using Azure AD authentication.

Default Values: The component uses Quantum’s production storage by default:

Storage Account: qdqedprodqvc
Container: qed-prod-diagrams
Libraries: Quantum

These defaults can be overridden by providing the respective attributes.

Attribute	Type	Required	Default	Description
`storage-account`	String	No	`qdqedprodqvc`	Azure storage account name
`container`	String	No	`qed-prod-diagrams`	Blob container name
`path`	String	Yes*	-	Storage path (forward-slash delimited, e.g., “engineering/widget-x/assembly”)
`drawing-name`	String	Yes*	-	Diagram filename (extension optional; defaults to .drawio if not provided)

* Required if using storage integration

Authentication Requirements:

Quantum Auth Service must be initialized and user must be logged in
App registration must have https://storage.azure.com/user_impersonation API permission
User must have Azure RBAC role on the storage account:
- Storage Blob Data Contributor (for read/write access)
- Storage Blob Data Reader (for read-only access)

Storage Path

Diagrams are stored using the path pattern:

{container}/{path}/{drawing-name}

If drawing-name doesn’t include a file extension, .drawio is automatically appended.

The component automatically detects the diagram format from the file extension and configures the editor accordingly. Supported formats include:

.drawio or .xml - Standard XML format (default)
.drawio.svg or .svg - SVG with embedded diagram data
.drawio.png or .png - PNG with embedded diagram data
.html - HTML with embedded diagram data

Examples (using default storage account qdqedprodqvc and container qed-prod-diagrams):

<!-- drawing-name="main-diagram" -->
qed-prod-diagrams/engineering/widget-x/assembly/main-diagram.drawio

<!-- drawing-name="flowchart.drawio.svg" -->
qed-prod-diagrams/engineering/widget-x/assembly/flowchart.drawio.svg

<!-- drawing-name="architecture.xml" -->
qed-prod-diagrams/engineering/widget-x/assembly/architecture.xml

The path attribute provides flexibility to organize diagrams using any folder structure. For example:

engineering/widget-x/assembly
projects/2024/q1/project-alpha
team/design/mockups

Custom Shape Libraries

The component supports loading custom shape libraries that will be available in the editor’s left panel. The Quantum Design System includes a default Quantum library with standard shapes.

Using Custom Libraries

<qds-diagram-host
  libraries="Quantum"
  width="100%"
  height="600px">
</qds-diagram-host>

Multiple libraries can be specified as a comma-separated list:

<qds-diagram-host
  libraries="Quantum,CustomLibrary,AnotherLibrary"
  width="100%"
  height="600px">
</qds-diagram-host>

Library Files

Custom library files must be:

Placed in the libraries folder within the diagram-host component directory
Named with .xml extension (e.g., Quantum.xml)
Formatted as valid diagrams.net library XML
Publicly accessible (libraries are always loaded from the CDN)

Library files are automatically served from: https://cdn.q360.ai/assets/components/diagram-host/libraries/

Included Library:

Quantum.xml - Default library with Quantum Design System standard shapes

Note: Custom libraries are always loaded from the CDN, even during local development. This is because the diagrams.net editor (which runs at https://embed.diagrams.net/) needs to fetch the library files, and cannot access localhost URLs. To test custom libraries during development, you must deploy them to the CDN first.

Creating Custom Libraries

To create custom libraries:

Open diagrams.net desktop application
Create or edit shapes in a library
Click the pencil icon on the library
Select “Export” and save as XML
Place the XML file in src/components/diagram-host/libraries/
Reference the library name (without .xml) in the libraries attribute

Note: Libraries are read-only in the web editor. To edit a library, use the diagrams.net desktop application, then re-export and replace the XML file.

Events

Event	Detail	Description
`diagram-change`	`{ diagram: string }`	Fired when diagram content changes
`diagram-loaded`	`{ diagram: string, path: string }`	Fired when diagram loads from storage
`diagram-saved`	`{ diagram: string, path: string }`	Fired when diagram saves to storage successfully
`diagram-error`	`{ error: string }`	Fired when a storage error occurs

JavaScript API

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

// Get current diagram XML
const xml = diagramHost.diagram;

// Set diagram XML programmatically
diagramHost.diagram = '<mxGraphModel>...</mxGraphModel>';

// Listen for changes
diagramHost.addEventListener('diagram-change', (event) => {
  console.log('Diagram updated:', event.detail.diagram);
});

// Listen for storage events
diagramHost.addEventListener('diagram-saved', (event) => {
  console.log('Saved to:', event.detail.path);
});

diagramHost.addEventListener('diagram-error', (event) => {
  console.error('Storage error:', event.detail.error);
});

User Interaction

View Mode: Diagram is displayed using diagrams.net viewer with full toolbar
- Zoom controls
- Layer controls
- Navigation controls
- Print functionality
Edit Mode: Click the “Edit Diagram” button in the top-right corner
- Opens diagrams.net editor in popup window (1200x800)
- Full editing capabilities
- Save with Ctrl+S or File > Save
- Popup automatically closes after save
- Changes immediately reflected in viewer

Azure Blob Storage Setup

To use Azure Blob Storage integration, you need to:

Configure CORS on your storage account
Set up Azure AD authentication
Assign RBAC roles to users

Required CORS Settings

Configure CORS on your Azure Storage account to allow browser access:

Allowed Origins: *
Allowed Methods: GET, PUT, OPTIONS
Allowed Headers: *
Exposed Headers: *
Max Age: 3600

Authentication Setup

1. Azure AD App Registration

The app using diagram-host must have an Azure AD app registration with:

API Permission: https://storage.azure.com/user_impersonation (Delegated)
Redirect URI: Your application’s URL

2. Initialize Quantum Auth Service

// Initialize auth service (usually done at app startup)
import { initializeQuantumAuth } from 'quantum-design-system/services/auth';

const auth = initializeQuantumAuth({
  clientId: 'your-client-id',
  authority: 'https://login.microsoftonline.com/your-tenant-id',
  redirectUri: window.location.origin,
  scopes: ['User.Read', 'https://storage.azure.com/user_impersonation']
});

// Users must log in
await auth.login();

3. Assign Azure RBAC Roles

Users need appropriate roles on the storage account or container:

Storage Blob Data Contributor - For read/write access (recommended)
Storage Blob Data Reader - For read-only access

Azure CLI Setup

# Create storage account
az storage account create \
  --name youraccount \
  --resource-group yourgroup \
  --location eastus \
  --sku Standard_LRS

# Create container
az storage container create \
  --account-name youraccount \
  --name diagrams \
  --public-access off

# Set CORS
az storage cors add \
  --services b \
  --methods GET PUT OPTIONS \
  --origins '*' \
  --allowed-headers '*' \
  --exposed-headers '*' \
  --max-age 3600 \
  --account-name youraccount

Styling

The component supports CSS custom properties for theming:

qds-diagram-host {
  --theme-accent-primary: #445E89;
  --theme-accent-secondary: #3E495B;
  --theme-background-primary: #fff;
  --theme-border-primary: #e0e0e0;
  --theme-text-secondary: #666;
  --theme-error: #8B1F00;
}

The edit button can be styled using the ::part() selector:

qds-diagram-host::part(edit-button) {
  background: #custom-color;
}

Troubleshooting

Diagram doesn’t load from storage

Check that all required storage attributes are provided
Verify user is logged in (getQuantumAuth() should return an auth service)
Verify user has Storage Blob Data Reader or Storage Blob Data Contributor role on the storage account
Check browser console for authentication or CORS errors
Verify the blob exists at the expected path

Diagram doesn’t save to storage

Verify user is logged in and has valid authentication token
Verify user has Storage Blob Data Contributor role (read-only role won’t work for saves)
Check CORS settings on storage account (must allow PUT method)
Check browser console for errors
Note: Diagram will still update locally even if storage save fails

Authentication errors

Verify Quantum Auth Service is initialized before using diagram-host
Check that app registration has https://storage.azure.com/user_impersonation permission
Verify user has logged in successfully
Check browser console for “Authentication service not available” errors

Allow popups for your site in browser settings
Check console for “Failed to open editor window” error

Editor is empty/grayed out

Check browser console for postMessage errors
Verify popup is not being blocked
Ensure the diagram XML is valid

Browser Support

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

Requires support for:

Web Components (Custom Elements, Shadow DOM)
ES6 modules
Fetch API
postMessage API

License

Part of the Quantum Design System (QDS)