← Back to Components

qds-tree-view

A tree view component for displaying hierarchical file and folder structures with expand/collapse functionality.

Features

• Provider-based architecture - Storage-backend agnostic through ITreeDataProvider interface
• Keyboard navigation - Full keyboard support (Arrow keys, Enter, Space)
• Expand/collapse - Interactive folder expansion with visual indicators
• Selection state - Track and highlight selected nodes
• Resizable - Optional resize handle for width adjustment
• Event system - Emits events for file selection, folder toggle, etc.
• Lazy loading - Support for loading children on-demand
• Search - Search through tree nodes
• Responsive - Works on desktop and tablet devices

Usage

Basic Example

<qds-tree-view id="myTree" width="300px"></qds-tree-view>

<script type="module">
  import { AzureStorageTreeProvider } from './providers/AzureStorageTreeProvider.js';

  const provider = new AzureStorageTreeProvider({
    storageAccount: 'your-storage-account',
    container: 'your-container',
    authMethod: 'quantum-auth'
  });

  const treeView = document.getElementById('myTree');
  treeView.dataProvider = provider;
</script>

With Resizing

<qds-tree-view
  width="250px"
  resizable>
</qds-tree-view>

Attributes

Attribute	Type	Default	Description
width	string	300px	Initial width of the tree view
resizable	boolean	false	Whether the tree view can be resized by dragging

Properties

dataProvider

Set the data provider for the tree view.

const provider = new AzureStorageTreeProvider(config);
treeView.dataProvider = provider;

selectedNode

Get the currently selected node (read-only).

const selected = treeView.selectedNode;
console.log(selected.name, selected.type);

Events

file-selected

Fired when a file node is selected.

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

Detail:

{
  node: TreeNode
}

folder-expanded

Fired when a folder is expanded.

treeView.addEventListener('folder-expanded', (event) => {
  const { node } = event.detail;
  console.log('Folder expanded:', node.name);
});

Detail:

{
  node: TreeNode
}

folder-collapsed

Fired when a folder is collapsed.

treeView.addEventListener('folder-collapsed', (event) => {
  const { node } = event.detail;
  console.log('Folder collapsed:', node.name);
});

Detail:

{
  node: TreeNode
}

node-selected

Fired when any node (file or folder) is selected.

treeView.addEventListener('node-selected', (event) => {
  const { node } = event.detail;
  console.log('Node selected:', node.name, node.type);
});

Detail:

{
  node: TreeNode
}

Keyboard Navigation

Key	Action
↑	Move to previous visible node
↓	Move to next visible node
→	Expand folder or move to first child
←	Collapse folder or move to parent
Enter / Space	Toggle folder or select file

CSS Parts

You can style the tree view using CSS shadow parts:

qds-tree-view::part(container) {
  background-color: #f5f5f5;
}

qds-tree-view::part(tree) {
  padding: 16px;
}

qds-tree-view::part(node) {
  /* Style all nodes */
}

qds-tree-view::part(folder) {
  /* Style folder nodes */
}

qds-tree-view::part(file) {
  /* Style file nodes */
}

qds-tree-view::part(resize-handle) {
  /* Style resize handle */
}

Data Providers

The tree view uses the ITreeDataProvider interface for data operations. This allows it to work with various storage backends.

Azure Storage Provider

import { AzureStorageTreeProvider } from './providers/AzureStorageTreeProvider.js';

const provider = new AzureStorageTreeProvider({
  storageAccount: 'your-storage-account',
  container: 'your-container',
  authMethod: 'quantum-auth',
  basePath: 'diagrams/',              // Optional: filter to specific path
  allowedExtensions: ['.drawio', '.svg'], // Optional: filter by extension
  lazyLoad: false,                    // Optional: lazy-load children
  cacheTTL: 0                         // Optional: cache duration (0 = indefinite)
});

treeView.dataProvider = provider;

Static Provider (for testing)

class StaticTreeProvider {
  constructor(data) {
    this.data = data;
    this.eventHandlers = new Map();
  }

  async getRootNodes() {
    return this.data;
  }

  async getChildren(nodeId) {
    const node = this._findNode(nodeId, this.data);
    return node?.items || [];
  }

  // Implement other ITreeDataProvider methods...
}

const sampleData = [
  {
    id: 'folder1',
    name: 'Folder 1',
    type: 'folder',
    path: 'folder1',
    icon: 'assets/icons/folder.svg',
    parentId: null,
    items: [
      {
        id: 'folder1/file1.drawio',
        name: 'file1.drawio',
        type: 'file',
        path: 'folder1/file1.drawio',
        icon: 'assets/icons/diagram.svg',
        parentId: 'folder1'
      }
    ]
  }
];

const provider = new StaticTreeProvider(sampleData);
treeView.dataProvider = provider;

TreeNode Structure

Nodes in the tree follow this structure:

interface TreeNode {
  id: string;                // Unique identifier (full path)
  name: string;              // Display name
  type: 'folder' | 'file';   // Node type
  path: string;              // Full path from root
  icon?: string;             // Icon path
  parentId?: string | null;  // Parent node ID
  items?: TreeNode[];        // Child nodes (for folders)
  childrenLoaded?: boolean;  // Whether children have been loaded
  expanded?: boolean;        // UI state
  selected?: boolean;        // UI state
  metadata?: {               // Optional metadata
    extension?: string;
    size?: number;
    modified?: Date;
    contentType?: string;
  };
}

Integration Examples

With Diagram Host

<div style="display: flex; height: 100vh;">
  <qds-tree-view id="tree" width="300px" resizable></qds-tree-view>
  <qds-diagram-host
    id="diagram"
    style="flex: 1;"
    storage-account="your-account"
    container="your-container"
    editable>
  </qds-diagram-host>
</div>

<script type="module">
  import { AzureStorageTreeProvider } from './providers/AzureStorageTreeProvider.js';

  const provider = new AzureStorageTreeProvider({
    storageAccount: 'your-account',
    container: 'your-container',
    authMethod: 'quantum-auth',
    allowedExtensions: ['.drawio']
  });

  const tree = document.getElementById('tree');
  const diagram = document.getElementById('diagram');

  tree.dataProvider = provider;

  // Load diagram when file is selected
  tree.addEventListener('file-selected', (e) => {
    const { node } = e.detail;
    const pathParts = node.path.split('/');
    const fileName = pathParts.pop();
    const dirPath = pathParts.join('/');

    diagram.setAttribute('path', dirPath);
    diagram.setAttribute('drawing-name', fileName);
  });
</script>

With Search

<input type="text" id="searchInput" placeholder="Search files...">
<qds-tree-view id="tree"></qds-tree-view>

<script type="module">
  const searchInput = document.getElementById('searchInput');
  const tree = document.getElementById('tree');

  searchInput.addEventListener('input', async (e) => {
    const query = e.target.value;
    if (!query) return;

    const results = await tree.dataProvider.search(query);
    console.log('Found:', results);
  });
</script>

Browser Support

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

Accessibility

• Full keyboard navigation support
• ARIA roles and attributes
• Focus management
• Screen reader compatible

Performance

• Virtual folder structure (no real folders in blob storage)
• Caching with configurable TTL
• Lazy loading support for large trees
• Efficient DOM updates

Related Components

• qds-diagram-host - Display and edit diagrams
• qds-diagram-manager - Complete diagram management interface
• AzureStorageTreeProvider - Azure Blob Storage backend
• ITreeDataProvider - Data provider interface

License

Proprietary - Quantum Capital Group