@editframe/create 0.43.0 → 0.45.0

package/dist/skills/editframe-editor-gui/references/focus-overlay.md

@@ -0,0 +1,561 @@
+---
+title: Focus Overlay Element
+description: Visual focus indicator that highlights and outlines the currently selected element in an Editframe composition preview.
+type: reference
+nav:
+  parent: "Preview & Canvas"
+  priority: 20
+api:
+  properties:
+    - name: focusedElement
+      type: "HTMLElement | null"
+      description: Currently focused element (consumed from context)
+react:
+  generate: true
+  componentName: FocusOverlay
+  importPath: "@editframe/react"
+  additionalProps:
+    - name: className
+      type: string
+      description: CSS classes for styling
+  nav:
+    parent: "Components / Overlay System"
+    priority: 55
+    related: ["preview", "overlay-layer"]
+---
+
+<!-- html-only -->
+# ef-focus-overlay
+<!-- /html-only -->
+<!-- react-only -->
+# FocusOverlay
+<!-- /react-only -->
+
+Visual indicator that highlights the focused element in a composition.
+
+<!-- react-only -->
+## Import
+
+```tsx
+import { FocusOverlay } from "@editframe/react";
+```
+<!-- /react-only -->
+
+## Basic Usage
+
+<!-- html-only -->
+Display focus overlay in a preview:
+
+```html
+<ef-preview target="composition">
+  <ef-focus-overlay></ef-focus-overlay>
+</ef-preview>
+
+<ef-timegroup id="composition">
+  <!-- Focus overlay tracks focused element -->
+</ef-timegroup>
+```
+<!-- /html-only -->
+<!-- react-only -->
+```tsx
+import { FocusOverlay, Preview, Timegroup, Video } from "@editframe/react";
+
+export const App = () => {
+  return (
+    <div className="relative w-full h-screen">
+      <Preview className="w-full h-full">
+        <FocusOverlay className="absolute inset-0" />
+      </Preview>
+
+      <Timegroup mode="sequence" className="w-[1920px] h-[1080px]">
+        <Video src="/assets/video1.mp4" />
+        <Video src="/assets/video2.mp4" />
+      </Timegroup>
+    </div>
+  );
+};
+```
+<!-- /react-only -->
+
+## Focus Context
+
+<!-- html-only -->
+Focus overlay consumes focused element from context:
+
+```html
+<ef-preview target="composition">
+  <!-- Preview provides focusedElement context -->
+  <ef-focus-overlay></ef-focus-overlay>
+</ef-preview>
+```
+
+When an element receives focus, the overlay highlights it.
+<!-- /html-only -->
+<!-- react-only -->
+FocusOverlay consumes the `focusedElement` from Preview context:
+
+- Preview provides `focusedElementContext`
+- FocusOverlay subscribes to context changes
+- Automatically updates when focus changes
+- No manual wiring required
+<!-- /react-only -->
+
+## Visual Appearance
+
+Overlay displays:
+
+- **Outline**: 2px solid border
+- **Background**: Semi-transparent fill
+- **Blend mode**: Multiply for visibility over content
+- **Opacity**: 0.4
+
+## Positioning
+
+Overlay uses fixed positioning and tracks element bounds via `getBoundingClientRect()`:
+
+```javascript
+// Internal positioning (automatic)
+const rect = focusedElement.getBoundingClientRect();
+overlay.style.top = `${rect.top}px`;
+overlay.style.left = `${rect.left}px`;
+overlay.style.width = `${rect.width}px`;
+overlay.style.height = `${rect.height}px`;
+```
+
+## Animation Frame Loop
+
+Focus overlay updates position every frame:
+
+```javascript
+// Internal RAF loop
+const drawOverlay = () => {
+  if (focusedElement) {
+    updatePosition();
+    requestAnimationFrame(drawOverlay);
+  }
+};
+```
+
+Ensures overlay stays synchronized with moving or transforming elements.
+
+## Visibility
+
+Overlay automatically shows/hides based on focus state:
+
+- **Focused element exists**: Overlay visible
+- **No focused element**: Overlay hidden (`display: none`)
+
+## Styling
+
+Focus overlay uses CSS custom properties:
+
+<!-- html-only -->
+```css
+ef-focus-overlay {
+  /* Outline color */
+  --ef-focus-overlay-color: #2196f3;
+
+  /* Background color */
+  --ef-focus-overlay-background: #2196f3;
+}
+```
+
+Override to match your design:
+
+```html
+<style>
+  ef-focus-overlay {
+    --ef-focus-overlay-color: #ff5722;
+    --ef-focus-overlay-background: #ff5722;
+  }
+</style>
+
+<ef-focus-overlay></ef-focus-overlay>
+```
+<!-- /html-only -->
+<!-- react-only -->
+```tsx
+import { FocusOverlay } from "@editframe/react";
+
+export const StyledFocusOverlay = () => {
+  return (
+    <Preview className="w-full h-full">
+      <FocusOverlay
+        className="absolute inset-0"
+        style={{
+          "--ef-focus-overlay-color": "#10b981",
+          "--ef-focus-overlay-background": "rgba(16, 185, 129, 0.2)"
+        } as React.CSSProperties}
+      />
+    </Preview>
+  );
+};
+```
+<!-- /react-only -->
+
+<!-- html-only -->
+## Programmatic Control
+
+Set focused element via context provider:
+
+```javascript
+const preview = document.querySelector('ef-preview');
+const element = document.getElementById('my-element');
+
+// Focus is typically managed by preview
+element.focus();
+```
+<!-- /html-only -->
+
+## Pointer Events
+
+Focus overlay has `pointer-events: none` to avoid blocking interaction with underlying elements.
+
+<!-- html-only -->
+## Use Cases
+
+### Preview Focus Tracking
+
+```html
+<ef-preview target="composition">
+  <ef-focus-overlay></ef-focus-overlay>
+</ef-preview>
+```
+
+Overlay highlights the element that has browser focus.
+
+### Custom Focus Indicators
+
+```html
+<style>
+  ef-focus-overlay {
+    --ef-focus-overlay-color: #00ff00;
+    --ef-focus-overlay-background: rgba(0, 255, 0, 0.2);
+  }
+</style>
+
+<ef-preview target="composition">
+  <ef-focus-overlay></ef-focus-overlay>
+</ef-preview>
+```
+<!-- /html-only -->
+
+<!-- react-only -->
+## In Editor Layout
+
+```tsx
+import { FocusOverlay, Preview, Controls, Workbench } from "@editframe/react";
+
+export const Editor = () => {
+  return (
+    <div className="h-screen flex flex-col">
+      {/* Preview with focus indicator */}
+      <div className="flex-1 relative">
+        <Preview className="w-full h-full">
+          <FocusOverlay className="absolute inset-0" />
+        </Preview>
+      </div>
+
+      {/* Controls */}
+      <div className="p-4">
+        <Controls className="w-full" />
+      </div>
+
+      {/* Timeline */}
+      <div className="h-64">
+        <Workbench />
+      </div>
+    </div>
+  );
+};
+```
+
+## Multiple Preview Panes
+
+```tsx
+import { FocusOverlay, Preview } from "@editframe/react";
+
+export const SplitView = () => {
+  return (
+    <div className="grid grid-cols-2 gap-4 p-4">
+      {/* Main preview with focus */}
+      <div className="relative">
+        <h3 className="mb-2">Main View</h3>
+        <Preview className="w-full aspect-video">
+          <FocusOverlay className="absolute inset-0" />
+        </Preview>
+      </div>
+
+      {/* Secondary preview without focus overlay */}
+      <div className="relative">
+        <h3 className="mb-2">Reference View</h3>
+        <Preview className="w-full aspect-video" />
+      </div>
+    </div>
+  );
+};
+```
+
+## Focus-Aware Editing
+
+```tsx
+import { FocusOverlay, Preview, Timegroup, Video, Text } from "@editframe/react";
+
+export const FocusAwareEditor = () => {
+  const [focusedElement, setFocusedElement] = useState<HTMLElement | null>(null);
+
+  return (
+    <div className="flex gap-4">
+      {/* Preview with focus overlay */}
+      <div className="flex-1 relative">
+        <Preview className="w-full aspect-video">
+          <FocusOverlay className="absolute inset-0" />
+        </Preview>
+
+        <Timegroup mode="fixed" duration="10s" className="w-[1920px] h-[1080px]">
+          <Video
+            id="bg-video"
+            src="/assets/background.mp4"
+            duration="10s"
+            className="size-full"
+          />
+          <Text
+            id="title"
+            duration="5s"
+            className="absolute top-20 left-20 text-white text-4xl"
+          >
+            Title Text
+          </Text>
+        </Timegroup>
+      </div>
+
+      {/* Properties panel shows focused element info */}
+      <div className="w-64 p-4 bg-gray-100 rounded">
+        <h3 className="font-semibold mb-2">Focused Element</h3>
+        {focusedElement ? (
+          <div className="text-sm space-y-1">
+            <div>Tag: {focusedElement.tagName}</div>
+            <div>ID: {focusedElement.id || "(none)"}</div>
+          </div>
+        ) : (
+          <div className="text-sm text-gray-500">No element focused</div>
+        )}
+      </div>
+    </div>
+  );
+};
+```
+
+## Custom Focus Styles
+
+```tsx
+import { FocusOverlay } from "@editframe/react";
+
+export const CustomFocusStyles = () => {
+  return (
+    <div className="space-y-4">
+      {/* Blue focus */}
+      <Preview className="w-full aspect-video">
+        <FocusOverlay
+          className="absolute inset-0"
+          style={{
+            "--ef-focus-overlay-color": "#3b82f6",
+            "--ef-focus-overlay-background": "rgba(59, 130, 246, 0.15)"
+          } as React.CSSProperties}
+        />
+      </Preview>
+
+      {/* Green focus */}
+      <Preview className="w-full aspect-video">
+        <FocusOverlay
+          className="absolute inset-0"
+          style={{
+            "--ef-focus-overlay-color": "#10b981",
+            "--ef-focus-overlay-background": "rgba(16, 185, 129, 0.15)"
+          } as React.CSSProperties}
+        />
+      </Preview>
+
+      {/* Red focus */}
+      <Preview className="w-full aspect-video">
+        <FocusOverlay
+          className="absolute inset-0"
+          style={{
+            "--ef-focus-overlay-color": "#ef4444",
+            "--ef-focus-overlay-background": "rgba(239, 68, 68, 0.15)"
+          } as React.CSSProperties}
+        />
+      </Preview>
+    </div>
+  );
+};
+```
+
+## Toggle Focus Overlay
+
+```tsx
+import { FocusOverlay, Preview } from "@editframe/react";
+
+export const ToggleFocus = () => {
+  const [showFocus, setShowFocus] = useState(true);
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center gap-2">
+        <input
+          type="checkbox"
+          checked={showFocus}
+          onChange={(e) => setShowFocus(e.target.checked)}
+          id="show-focus"
+        />
+        <label htmlFor="show-focus">Show focus overlay</label>
+      </div>
+
+      <div className="relative">
+        <Preview className="w-full aspect-video">
+          {showFocus && <FocusOverlay className="absolute inset-0" />}
+        </Preview>
+      </div>
+    </div>
+  );
+};
+```
+<!-- /react-only -->
+
+## Blend Mode
+
+Overlay uses `mix-blend-mode: multiply` to ensure visibility over both light and dark content:
+
+```css
+.overlay {
+  mix-blend-mode: multiply;
+  opacity: 0.4;
+}
+```
+
+This creates a darkening effect that's visible regardless of background color.
+
+<!-- html-only -->
+## Update Lifecycle
+
+Overlay updates in three scenarios:
+
+1. **connectedCallback**: Start RAF loop
+2. **updated**: Redraw when focusedElement context changes
+3. **disconnectedCallback**: Cancel RAF loop
+<!-- /html-only -->
+
+## Performance
+
+Single RAF loop per overlay. RAF automatically pauses when no element is focused, resuming when focus changes.
+
+## Comparison with Selection Overlay
+
+**Focus overlay**:
+- Tracks browser focus (single element)
+- Used in preview/playback mode
+- Highlights interactive element
+<!-- html-only -->
+- Provided by ef-preview context
+<!-- /html-only -->
+<!-- react-only -->
+- Provided by Preview context
+<!-- /react-only -->
+
+**Selection overlay** (canvas):
+- Tracks canvas selection (multiple elements)
+- Used in editing mode
+- Shows selected elements
+<!-- html-only -->
+- Provided by ef-canvas
+<!-- /html-only -->
+<!-- react-only -->
+- Provided by Canvas
+<!-- /react-only -->
+
+## Context Requirement
+
+<!-- html-only -->
+Focus overlay requires a parent that provides `focusedElementContext`:
+
+```html
+<!-- Works - preview provides context -->
+<ef-preview target="composition">
+  <ef-focus-overlay></ef-focus-overlay>
+</ef-preview>
+
+<!-- Doesn't work - no context provider -->
+<ef-focus-overlay></ef-focus-overlay>
+```
+<!-- /html-only -->
+<!-- react-only -->
+FocusOverlay must be a child of Preview component. Preview provides the `focusedElementContext` that FocusOverlay consumes.
+<!-- /react-only -->
+
+## Fixed Positioning
+
+Overlay uses `position: fixed` to stay visible during scrolling and pan/zoom operations.
+
+## Container Sizing
+
+Overlay fills its container:
+
+```css
+ef-focus-overlay {
+  display: block;
+  position: relative;
+  width: 100%;
+  height: 100%;
+  pointer-events: none;
+}
+```
+
+Actual highlight overlay uses fixed positioning within.
+
+<!-- html-only -->
+## Debug Visibility
+
+To debug focus overlay:
+
+```javascript
+const overlay = document.querySelector('ef-focus-overlay');
+
+// Check if element is focused
+console.log(overlay.focusedElement);
+
+// Check overlay visibility
+const overlayDiv = overlay.shadowRoot.querySelector('.overlay');
+console.log(overlayDiv.style.display); // 'block' or 'none'
+```
+<!-- /html-only -->
+
+## Architecture
+
+- Uses `position: fixed` for overlay positioning
+- Runs continuous RAF loop for smooth tracking
+- Reads `getBoundingClientRect()` from focused element
+- Mix blend mode creates visual highlight effect
+- Automatically hidden when no element focused
+
+## CSS Customization
+
+Customize appearance with CSS variables:
+
+```css
+.focus-overlay {
+  --ef-focus-overlay-color: #3b82f6;           /* Border color */
+  --ef-focus-overlay-background: rgba(59, 130, 246, 0.4);  /* Fill color */
+}
+```
+
+<!-- react-only -->
+## Important Notes
+
+- Must be a child of Preview component
+- Position is `fixed` to viewport (not Preview-relative)
+- Updates every animation frame for smooth tracking
+- Pointer events are disabled (`pointer-events: none`)
+- Automatically syncs with Preview's focused element
+- Use for visual feedback in editor interfaces
+- Works with all composition elements (Video, Text, Image, etc.)
+<!-- /react-only -->