ef-overlay-layer

Container for positioned overlays that track element positions in a canvas or composition.

Basic Usage

Overlay layer provides a coordinate system for overlays:

<div class="relative w-[600px] h-[400px] border border-gray-300 rounded overflow-hidden">
  <ef-overlay-layer class="absolute inset-0 pointer-events-none">
    <ef-overlay-item target="#target-box" class="border-2 border-blue-500 pointer-events-auto">
      <div class="absolute -top-6 left-0 bg-blue-500 text-white text-xs px-2 py-1 rounded">Label</div>
    </ef-overlay-item>
  </ef-overlay-layer>

  <div id="target-box" class="absolute top-8 left-8 w-32 h-24 bg-gray-200 rounded"></div>
</div>

With Pan/Zoom

Overlay layer automatically syncs with ef-pan-zoom transforms:

<div class="relative w-[600px] h-[400px] border border-gray-300 rounded overflow-hidden">
  <ef-pan-zoom class="w-full h-full">
    <div class="w-[1200px] h-[800px] bg-gray-100">
      <div id="element-1" class="absolute top-12 left-12 w-40 h-32 bg-blue-500 text-white flex items-center justify-center rounded">
        Element 1
      </div>
      <div id="element-2" class="absolute top-48 left-48 w-40 h-32 bg-green-500 text-white flex items-center justify-center rounded">
        Element 2
      </div>
    </div>
  </ef-pan-zoom>

  <ef-overlay-layer class="absolute inset-0 pointer-events-none">
    <ef-overlay-item target="#element-1" class="border-2 border-blue-600"></ef-overlay-item>
    <ef-overlay-item target="#element-2" class="border-2 border-green-600"></ef-overlay-item>
  </ef-overlay-layer>
</div>

Pan and zoom the canvas - overlays stay perfectly positioned on their targets.

Architecture

Overlay layer runs a single RAF loop that:

1. Reads the current pan/zoom transform
2. Applies transform to the layer container
3. Updates all registered overlay items
4. Schedules next frame

This ensures all overlays update synchronously without individual RAF loops.

Transform Context

Overlay layer consumes pan/zoom transform from context when nested inside ef-pan-zoom:

<ef-pan-zoom>
  <!-- Transform provided via context -->
  <ef-overlay-layer>
    <ef-overlay-item target="#element"></ef-overlay-item>
  </ef-overlay-layer>
</ef-pan-zoom>

For sibling relationships, overlay layer reads transform directly from the DOM:

<div class="relative">
  <ef-pan-zoom>
    <!-- Pan/zoom content -->
  </ef-pan-zoom>

  <!-- Sibling overlay layer reads transform from ef-pan-zoom -->
  <ef-overlay-layer class="absolute inset-0">
    <ef-overlay-item target="#element"></ef-overlay-item>
  </ef-overlay-layer>
</div>

Fallback Transform

Provide transform as property for testing or standalone usage:

const overlayLayer = document.querySelector('ef-overlay-layer');
overlayLayer.panZoomTransform = { x: 0, y: 0, scale: 1 };

Coordinate System

Overlay layer creates a coordinate space that:

• Matches the transformed canvas position
• Allows overlay items to use absolute positioning
• Updates every frame via RAF loop
• Supports pointer events through pointer-events: auto on overlay items

Registration

Overlay items auto-register with their parent layer:

// Registration happens automatically in connectedCallback
const item = document.createElement('ef-overlay-item');
item.target = '#my-element';
overlayLayer.appendChild(item); // Item registers itself

// Unregistration happens in disconnectedCallback
item.remove(); // Item unregisters itself

Manual registration is possible but not required:

const overlayLayer = document.querySelector('ef-overlay-layer');
const overlayItem = document.querySelector('ef-overlay-item');

overlayLayer.registerOverlayItem(overlayItem);
// Later...
overlayLayer.unregisterOverlayItem(overlayItem);

Pointer Events

Overlay layer has pointer-events: none by default. Enable pointer events on individual items:

<ef-overlay-layer>
  <ef-overlay-item target="#element" class="pointer-events-auto cursor-pointer">
    <button>Click me</button>
  </ef-overlay-item>
</ef-overlay-layer>

Performance

Single RAF loop ensures:

• No RAF proliferation (one loop for all overlays)
• No change detection overhead
• No delay between transform and overlay updates
• Synchronized updates across all overlay items

Positioning

Overlay layer uses position: absolute and inset: 0 to fill its container:

<div class="relative w-full h-full">
  <!-- Overlay layer fills parent -->
  <ef-overlay-layer></ef-overlay-layer>
</div>

Transform Origin

Overlay layer uses transform-origin: 0 0 to match canvas transform behavior.

Important Notes

• Must be positioned with position: absolute or fixed
• Use with ef-overlay-item children to track specific elements
• Automatically handles pan/zoom transforms when inside ef-pan-zoom
• Updates continuously - no manual refresh needed
• All overlay items update in sync to prevent visual glitches