@editframe/create 0.44.0 → 0.45.0

package/dist/skills/editframe-editor-gui/references/hierarchy.md

@@ -0,0 +1,544 @@
+---
+title: Hierarchy Element
+description: Layer panel that displays the composition element tree with collapsible groups, selection highlighting, and drag-to-reorder.
+type: reference
+nav:
+  parent: "Editor Shells"
+  priority: 11
+api:
+  attributes:
+    - name: target
+      type: string
+      description: ID of the target element (ef-canvas or ef-timegroup)
+    - name: header
+      type: string
+      description: Header text displayed at top of hierarchy
+    - name: show-header
+      type: boolean
+      default: false
+      description: Show or hide the header
+    - name: hideSelectors
+      type: string[]
+      description: CSS selectors for elements to hide from hierarchy
+    - name: showSelectors
+      type: string[]
+      description: CSS selectors for elements to include in hierarchy (overrides hide)
+  methods:
+    - name: select(elementId)
+      signature: "select(elementId: string | null): void"
+      description: Select an element in the hierarchy
+    - name: getSelectedElementId()
+      signature: "getSelectedElementId(): string | null"
+      description: Get the currently selected element ID
+      returns: string | null
+    - name: setHighlightedElement(element)
+      signature: "setHighlightedElement(element: HTMLElement | null): void"
+      description: Set the highlighted (hovered) element
+    - name: getHighlightedElement()
+      signature: "getHighlightedElement(): HTMLElement | null"
+      description: Get the currently highlighted element
+      returns: HTMLElement | null
+  events:
+    - name: hierarchy-select
+      detail: "{ elementId: string | null }"
+      description: Fired when selection changes
+    - name: hierarchy-reorder
+      detail: "{ sourceId: string, targetId: string, position: 'before' | 'after' | 'inside' }"
+      description: Fired when user reorders elements via drag-and-drop
+react:
+  generate: true
+  componentName: Hierarchy
+  importPath: "@editframe/react"
+  propMapping:
+    show-header: showHeader
+  additionalProps:
+    - name: className
+      type: string
+      description: CSS classes for styling
+  nav:
+    parent: "Components / Editor UI"
+    priority: 60
+    related: ["preview", "workbench"]
+---
+
+<!-- html-only -->
+# ef-hierarchy
+<!-- /html-only -->
+<!-- react-only -->
+# Hierarchy
+<!-- /react-only -->
+
+<!-- html-only -->
+Layer panel showing composition structure with selection and expansion controls.
+<!-- /html-only -->
+<!-- react-only -->
+Tree view displaying composition element hierarchy and layer structure.
+
+> **Note**: The Hierarchy component is currently not exported from `@editframe/react`. This documentation describes the underlying `ef-hierarchy` HTML element. To use it in React, you'll need to use the HTML element directly or wait for official React component export.
+<!-- /react-only -->
+
+## Basic Usage
+
+<!-- html-only -->
+Display a hierarchy of elements in a target container:
+
+```html live
+<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>
+```
+<!-- /html-only -->
+<!-- react-only -->
+## HTML Element Usage
+
+```tsx
+import { useRef, useEffect } from "react";
+
+export const App = () => {
+  const hierarchyRef = useRef<HTMLElement>(null);
+
+  useEffect(() => {
+    const hierarchy = hierarchyRef.current;
+    if (hierarchy) {
+      // Access methods via ref
+      (hierarchy as any).select("video-1");
+    }
+  }, []);
+
+  return (
+    <div className="flex h-screen">
+      {/* Hierarchy panel */}
+      <div className="w-64 border-r bg-gray-50">
+        <ef-hierarchy
+          ref={hierarchyRef as any}
+          target="canvas"
+          header="Layers"
+          show-header
+        />
+      </div>
+
+      {/* Canvas */}
+      <div className="flex-1">
+        <ef-canvas id="canvas">
+          <ef-timegroup mode="contain" className="w-[1920px] h-[1080px]">
+            <ef-video id="video-1" src="/assets/video.mp4" className="size-full" />
+            <ef-text id="title" duration="5s" className="text-white text-4xl">
+              Title
+            </ef-text>
+          </ef-timegroup>
+        </ef-canvas>
+      </div>
+    </div>
+  );
+};
+```
+<!-- /react-only -->
+
+<!-- html-only -->
+## Target Binding
+
+Hierarchy can target any element containing composition elements:
+
+### Canvas Target
+
+Show hierarchy of canvas elements:
+
+```html
+<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:
+
+```html
+<ef-hierarchy target="root-timegroup"></ef-hierarchy>
+<ef-timegroup id="root-timegroup">
+  <!-- Nested elements appear in hierarchy -->
+</ef-timegroup>
+```
+<!-- /html-only -->
+
+<!-- react-only -->
+## Editor Layout
+
+```tsx
+export const EditorWithHierarchy = () => {
+  return (
+    <div className="h-screen grid grid-cols-[250px_1fr_250px]">
+      {/* Left: Hierarchy */}
+      <div className="border-r bg-gray-50 overflow-auto">
+        <ef-hierarchy
+          target="editor-canvas"
+          header="Layers"
+          show-header
+        />
+      </div>
+
+      {/* Center: Preview */}
+      <div className="flex flex-col">
+        <div className="flex-1 p-4">
+          <ef-preview />
+        </div>
+        <div className="h-64 border-t">
+          <ef-filmstrip target="root-timegroup" />
+        </div>
+      </div>
+
+      {/* Right: Properties */}
+      <div className="border-l bg-gray-50 p-4">
+        <h3 className="font-semibold mb-2">Properties</h3>
+        {/* Properties panel content */}
+      </div>
+
+      {/* Composition */}
+      <ef-canvas id="editor-canvas">
+        <ef-timegroup
+          id="root-timegroup"
+          mode="sequence"
+          className="w-[1920px] h-[1080px]"
+        >
+          {/* Elements */}
+        </ef-timegroup>
+      </ef-canvas>
+    </div>
+  );
+};
+```
+<!-- /react-only -->
+
+## Selection Integration
+
+<!-- html-only -->
+Hierarchy syncs with ef-canvas selection:
+
+```html live
+<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.
+<!-- /html-only -->
+<!-- react-only -->
+```tsx
+export const SelectionAwareHierarchy = () => {
+  const hierarchyRef = useRef<HTMLElement>(null);
+
+  const handleElementClick = (elementId: string) => {
+    const hierarchy = hierarchyRef.current;
+    if (hierarchy) {
+      (hierarchy as any).select(elementId);
+    }
+  };
+
+  useEffect(() => {
+    const hierarchy = hierarchyRef.current;
+    if (!hierarchy) return;
+
+    const handleSelectionChange = (e: CustomEvent) => {
+      console.log("Selected element:", e.detail.elementId);
+    };
+
+    hierarchy.addEventListener("hierarchy-select" as any, handleSelectionChange);
+    return () => {
+      hierarchy.removeEventListener("hierarchy-select" as any, handleSelectionChange);
+    };
+  }, []);
+
+  return (
+    <div className="flex h-screen">
+      <div className="w-64 border-r">
+        <ef-hierarchy ref={hierarchyRef as any} target="canvas" />
+      </div>
+
+      <div className="flex-1">
+        <ef-canvas id="canvas">
+          <ef-timegroup mode="contain" className="w-[1920px] h-[1080px]">
+            <ef-video
+              id="video-1"
+              src="/assets/video.mp4"
+              onClick={() => handleElementClick("video-1")}
+            />
+          </ef-timegroup>
+        </ef-canvas>
+      </div>
+    </div>
+  );
+};
+```
+<!-- /react-only -->
+
+## Filtering Elements
+
+<!-- html-only -->
+Control which elements appear in the hierarchy:
+
+### Hide Selectors
+
+Hide specific elements by selector:
+
+```html
+<ef-hierarchy
+  target="canvas"
+  .hideSelectors=${['.helper', '.invisible']}>
+</ef-hierarchy>
+```
+
+### Show Selectors
+
+Override hiding for specific elements:
+
+```html
+<ef-hierarchy
+  target="canvas"
+  .hideSelectors=${['.helper']}
+  .showSelectors=${['.helper-visible']}>
+</ef-hierarchy>
+```
+<!-- /html-only -->
+<!-- react-only -->
+```tsx
+export const FilteredHierarchy = () => {
+  const hideSelectors = [".helper-element", "[data-hidden='true']"];
+
+  return (
+    <div className="w-64 h-screen border-r bg-gray-50">
+      <ef-hierarchy
+        target="canvas"
+        hide-selectors={JSON.stringify(hideSelectors)}
+      />
+    </div>
+  );
+};
+```
+<!-- /react-only -->
+
+## Programmatic Control
+
+<!-- html-only -->
+Select elements via JavaScript:
+
+```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:
+
+```javascript
+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:
+
+```javascript
+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.
+<!-- /html-only -->
+
+<!-- react-only -->
+## Features
+
+- **Tree structure**: Displays nested timegroups and elements
+- **Expand/collapse**: Click to expand or collapse nested items
+- **Selection sync**: Syncs with canvas selection state
+- **Drag and drop**: Reorder elements by dragging (when supported)
+- **Visual feedback**: Highlights selected and hovered elements
+- **Context menu**: Right-click for element actions
+- **Auto-scroll**: Scrolls to selected element
+<!-- /react-only -->
+
+## Styling
+
+Hierarchy uses CSS custom properties:
+
+```css
+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
+
+<!-- html-only -->
+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
+<!-- /html-only -->
+<!-- react-only -->
+The hierarchy displays specialized items for each element type:
+
+- `ef-timegroup` - Timegroup container
+- `ef-video` - Video layer
+- `ef-audio` - Audio layer
+- `ef-image` - Image layer
+- `ef-text` - Text layer
+- `ef-captions` - Captions layer
+- `ef-surface` - Surface (mirror) layer
+- `ef-waveform` - Waveform visualization
+<!-- /react-only -->
+
+<!-- html-only -->
+## Auto-Selection
+
+When target changes, hierarchy automatically selects the first root timegroup if nothing is selected.
+<!-- /html-only -->
+
+<!-- react-only -->
+## Events
+
+### hierarchy-select
+
+Fired when an element is selected in the hierarchy:
+
+```typescript
+interface HierarchySelectDetail {
+  elementId: string | null;
+}
+```
+
+### hierarchy-reorder
+
+Fired when elements are reordered:
+
+```typescript
+interface HierarchyReorderDetail {
+  sourceId: string;
+  targetId: string;
+  position: "before" | "after" | "inside";
+}
+```
+
+## Methods
+
+### select()
+
+Programmatically select an element:
+
+```tsx
+const hierarchy = hierarchyRef.current;
+if (hierarchy) {
+  (hierarchy as any).select("element-id");
+}
+```
+
+### getSelectedElementId()
+
+Get the currently selected element ID:
+
+```tsx
+const hierarchy = hierarchyRef.current;
+if (hierarchy) {
+  const selectedId = (hierarchy as any).getSelectedElementId();
+  console.log("Selected:", selectedId);
+}
+```
+
+## Integration with Canvas
+
+The hierarchy component works with `ef-canvas` to provide:
+
+- **Selection coordination**: Clicks in hierarchy select canvas elements
+- **Highlight sync**: Hover in hierarchy highlights canvas elements
+- **State sharing**: Uses Lit context for state synchronization
+- **Direct DOM access**: Can work as sibling via target ID
+
+## Important Notes
+
+- Currently requires using HTML element syntax in React
+- Target should be an `ef-canvas` or `ef-timegroup` element ID
+- Automatically initializes with all items expanded
+- Auto-selects first root timegroup on mount
+- Filters can use CSS selectors or data attributes
+- Selection state syncs bidirectionally with canvas
+- Use `show-header` to display panel title
+- Hierarchy updates automatically when DOM changes
+
+## Future React Component
+
+When officially exported as a React component, usage will be:
+
+```tsx
+import { Hierarchy } from "@editframe/react";
+
+<Hierarchy
+  target="canvas"
+  header="Layers"
+  showHeader
+  hideSelectors={[".helper"]}
+  onSelectionChange={(e) => console.log(e.detail)}
+/>
+```
+<!-- /react-only -->