ef-hierarchy

Layer panel showing composition structure with selection and expansion controls.

Basic Usage

Display a hierarchy of elements in a target container:

<div class="flex gap-4 h-[400px]">
  <ef-hierarchy target="canvas-1" header="Layers" show-header class="w-64 border border-gray-300 rounded"></ef-hierarchy>

  <ef-canvas id="canvas-1" class="flex-1 bg-gray-100 relative">
    <ef-timegroup id="scene-1" class="absolute top-4 left-4 w-48 h-32 bg-blue-500 text-white p-4">
      <h2>Scene 1</h2>
    </ef-timegroup>
    <ef-timegroup id="scene-2" class="absolute top-40 left-4 w-48 h-32 bg-green-500 text-white p-4">
      <h2>Scene 2</h2>
    </ef-timegroup>
  </ef-canvas>
</div>

Target Binding

Hierarchy can target any element containing composition elements:

Canvas Target

Show hierarchy of canvas elements:

<ef-hierarchy target="my-canvas"></ef-hierarchy>
<ef-canvas id="my-canvas">
  <!-- Canvas elements appear in hierarchy -->
</ef-canvas>

Timegroup Target

Show hierarchy of a single timegroup:

<ef-hierarchy target="root-timegroup"></ef-hierarchy>
<ef-timegroup id="root-timegroup">
  <!-- Nested elements appear in hierarchy -->
</ef-timegroup>

Selection Integration

Hierarchy syncs with ef-canvas selection:

<div class="flex gap-4 h-[400px]">
  <ef-hierarchy target="canvas-2" show-header header="Layers" class="w-64 border border-gray-300 rounded"></ef-hierarchy>

  <ef-pan-zoom class="flex-1 border border-gray-300 rounded overflow-hidden">
    <ef-canvas id="canvas-2" class="w-[720px] h-[480px] bg-gray-100">
      <div id="box-1" class="absolute top-8 left-8 w-32 h-32 bg-blue-500 text-white flex items-center justify-center">Box 1</div>
      <div id="box-2" class="absolute top-48 left-48 w-32 h-32 bg-green-500 text-white flex items-center justify-center">Box 2</div>
      <div id="box-3" class="absolute top-8 left-48 w-32 h-32 bg-red-500 text-white flex items-center justify-center">Box 3</div>
    </ef-canvas>
  </ef-pan-zoom>
</div>

Click items in the hierarchy or canvas to select. Selection stays in sync.

Filtering Elements

Control which elements appear in the hierarchy:

Hide Selectors

Hide specific elements by selector:

<ef-hierarchy
  target="canvas"
  .hideSelectors=${['.helper', '.invisible']}>
</ef-hierarchy>

Show Selectors

Override hiding for specific elements:

<ef-hierarchy
  target="canvas"
  .hideSelectors=${['.helper']}
  .showSelectors=${['.helper-visible']}>
</ef-hierarchy>

Programmatic Control

Select elements via JavaScript:

const hierarchy = document.querySelector('ef-hierarchy');

// Select an element
hierarchy.select('element-id');

// Get current selection
const selectedId = hierarchy.getSelectedElementId();

// Clear selection
hierarchy.select(null);

// Listen for selection changes
hierarchy.addEventListener('hierarchy-select', (e) => {
  console.log('Selected:', e.detail.elementId);
});

Hover Highlighting

Hierarchy shows highlighted (hovered) elements:

const hierarchy = document.querySelector('ef-hierarchy');

// Highlight an element
const element = document.getElementById('my-element');
hierarchy.setHighlightedElement(element);

// Get highlighted element
const highlighted = hierarchy.getHighlightedElement();

// Clear highlight
hierarchy.setHighlightedElement(null);

Drag and Drop Reordering

Listen for reorder events when user drags items:

const hierarchy = document.querySelector('ef-hierarchy');

hierarchy.addEventListener('hierarchy-reorder', (e) => {
  const { sourceId, targetId, position } = e.detail;
  // position is 'before', 'after', or 'inside'
  console.log(`Move ${sourceId} ${position} ${targetId}`);
});

Expansion State

Hierarchy automatically expands all items on initialization. Users can collapse and expand items by clicking the disclosure triangle.

Styling

Hierarchy uses CSS custom properties:

ef-hierarchy {
  --hierarchy-bg: #fff;
  --hierarchy-border: #e0e0e0;
  --hierarchy-text: #000;
  --hierarchy-hover-bg: #f0f0f0;
  --hierarchy-selected-bg: #e3f2fd;
  --hierarchy-ancestor-selected-bg: #f5f5f5;
  --hierarchy-focused-bg: #bbdefb;
}

Item Variants

Hierarchy automatically renders appropriate icons and labels for each element type:

• ef-timegroup - Container icon with duration
• ef-video - Video icon with filename
• ef-audio - Audio icon with filename
• ef-image - Image icon with filename
• ef-text - Text icon with preview
• ef-captions - Caption icon
• ef-waveform - Waveform icon
• ef-surface - Mirror icon
• div and other HTML - HTML tag name

Auto-Selection

When target changes, hierarchy automatically selects the first root timegroup if nothing is selected.