ef-focus-overlay

Visual indicator that highlights the focused element in a composition.

Basic Usage

Display focus overlay in a preview:

<ef-preview target="composition">
  <ef-focus-overlay></ef-focus-overlay>
</ef-preview>

<ef-timegroup id="composition">
  <!-- Focus overlay tracks focused element -->
</ef-timegroup>

Focus Context

Focus overlay consumes focused element from context:

<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.

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():

// 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:

// 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:

ef-focus-overlay {
  /* Outline color */
  --ef-focus-overlay-color: #2196f3;

  /* Background color */
  --ef-focus-overlay-background: #2196f3;
}

Override to match your design:

<style>
  ef-focus-overlay {
    --ef-focus-overlay-color: #ff5722;
    --ef-focus-overlay-background: #ff5722;
  }
</style>

<ef-focus-overlay></ef-focus-overlay>

Programmatic Control

Set focused element via context provider:

const preview = document.querySelector('ef-preview');
const element = document.getElementById('my-element');

// Focus is typically managed by preview
element.focus();

Pointer Events

Focus overlay has pointer-events: none to avoid blocking interaction with underlying elements.

Use Cases

Preview Focus Tracking

<ef-preview target="composition">
  <ef-focus-overlay></ef-focus-overlay>
</ef-preview>

Overlay highlights the element that has browser focus.

Custom Focus Indicators

<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>

Blend Mode

Overlay uses mix-blend-mode: multiply to ensure visibility over both light and dark content:

.overlay {
  mix-blend-mode: multiply;
  opacity: 0.4;
}

This creates a darkening effect that's visible regardless of background color.

Update Lifecycle

Overlay updates in three scenarios:

1. connectedCallback: Start RAF loop
2. updated: Redraw when focusedElement context changes
3. disconnectedCallback: Cancel RAF loop

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
• Provided by ef-preview context

Selection overlay (canvas):

• Tracks canvas selection (multiple elements)
• Used in editing mode
• Shows selected elements
• Provided by ef-canvas

Context Requirement

Focus overlay requires a parent that provides focusedElementContext:

<!-- 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>

Fixed Positioning

Overlay uses position: fixed to stay visible during scrolling and pan/zoom operations.

Container Sizing

Overlay fills its container:

ef-focus-overlay {
  display: block;
  position: relative;
  width: 100%;
  height: 100%;
  pointer-events: none;
}

Actual highlight overlay uses fixed positioning within.

Debug Visibility

To debug focus overlay:

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'

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:

.focus-overlay {
  --ef-focus-overlay-color: #3b82f6;           /* Border color */
  --ef-focus-overlay-background: rgba(59, 130, 246, 0.4);  /* Fill color */
}