@base44/vite-plugin 0.2.25 → 0.2.27

package/src/injections/layer-dropdown/LAYERS.md

@@ -0,0 +1,258 @@
+# Layer Dropdown Feature
+
+## Overview
+
+The layer dropdown lets users navigate the instrumented DOM hierarchy around a selected element. Clicking the chevron (`▾`) on an element's label reveals a dropdown showing **ancestors**, **siblings**, **the selected element**, and its **children** — all with depth-based indentation.
+
+```
+grandparent          (depth 0)
+  parent             (depth 1)
+    sibling-1        (depth 2)
+    ★ selected       (depth 2)   ← highlighted in blue
+      child-a        (depth 3)
+      child-b        (depth 3)
+    sibling-2        (depth 2)
+```
+
+Children are only expanded for the selected element, not for siblings.
+
+---
+
+## Architecture
+
+```
+┌─────────────┐     ┌────────────────┐     ┌────────────────┐
+│  types.ts   │◄────│  controller.ts │────►│  dropdown-ui.ts│
+│  consts.ts  │◄────│  (orchestrator)│     │  (rendering)   │
+└─────────────┘     └───────┬────────┘     └────────────────┘
+                            │
+                      ┌─────▼──────┐
+                      │  utils.ts  │
+                      │ (DOM walk) │
+                      └────────────┘
+```
+
+| File | Role |
+|------|------|
+| **types.ts** | `LayerInfo`, callback types, `LayerControllerDeps`, `LayerController` |
+| **consts.ts** | Style maps, depth limits, chevron character, attribute name |
+| **utils.ts** | DOM traversal — parent walking, sibling/descendant collection, depth assignment |
+| **dropdown-ui.ts** | Creates the dropdown DOM, positions it, handles hover/click/keyboard |
+| **controller.ts** | Stateful factory that wires everything together: build chain, show dropdown, handle selection |
+
+---
+
+## Data Model
+
+### `LayerInfo`
+
+```typescript
+interface LayerInfo {
+  element: Element;            // DOM reference
+  tagName: string;             // lowercase tag name ("div", "button")
+  selectorId: string | null;   // data-source-location or data-visual-selector-id
+  depth?: number;              // visual indentation level (set during chain building)
+}
+```
+
+An element is **instrumented** if it has `dataset.sourceLocation` or `dataset.visualSelectorId`. Only instrumented elements appear in the dropdown.
+
+### Key Constants
+
+| Constant | Value | Purpose |
+|----------|-------|---------|
+| `MAX_PARENT_DEPTH` | `2` | Max ancestor levels shown above selected |
+| `MAX_CHILD_DEPTH` | `2` | Max descendant levels shown below selected |
+| `DEPTH_INDENT_PX` | `10` | Extra left-padding per depth level |
+| `LABEL_CHEVRON` | `" ▾"` | Appended to label text when dropdown is available |
+
+---
+
+## How the Chain Is Built (`utils.ts`)
+
+`buildLayerChain(selectedElement)` is the entry point. It delegates to focused helper functions:
+
+```typescript
+export function buildLayerChain(selectedElement: Element): LayerInfo[] {
+  const parents = collectInstrumentedParents(selectedElement);
+  const chain: LayerInfo[] = [];
+  const selfDepth = appendParentsWithDepth(chain, parents);
+
+  const instrParent = getImmediateInstrParent(parents);
+  if (instrParent) {
+    const siblings = collectSiblings(instrParent, selectedElement);
+    appendSiblingsWithSelected(chain, siblings, selectedElement, selfDepth);
+  } else {
+    appendSelfAndDescendants(chain, selectedElement, selfDepth);
+  }
+
+  return chain;
+}
+```
+
+### Helper Functions
+
+| Function | Purpose |
+|----------|---------|
+| `toLayerInfo(element, depth?)` | Convert a DOM element to a `LayerInfo` object |
+| `collectInstrumentedParents(el)` | Walk up the DOM, collect up to `MAX_PARENT_DEPTH` instrumented ancestors, return outermost-first |
+| `appendParentsWithDepth(chain, parents)` | Push parents into chain with `depth = index` (0, 1, ...), return count as `selfDepth` |
+| `getImmediateInstrParent(parents)` | Return the innermost parent's DOM element, or `null` if `parents` is empty |
+| `collectSiblings(parent, selectedEl)` | Call `getInstrumentedDescendants(parent, 1)` to get all first-level instrumented children in DOM order; safety-guard ensures `selectedEl` is always included |
+| `appendSiblingsWithSelected(chain, siblings, selectedEl, depth)` | Iterate siblings at `selfDepth`; for the selected element, expand children via `appendSelfAndDescendants`; for others, just add at `selfDepth` |
+| `appendSelfAndDescendants(chain, el, depth)` | Push element + its descendants (up to `MAX_CHILD_DEPTH` levels) with assigned depths |
+| `getInstrumentedDescendants(parent, maxDepth)` | Recursive DOM walk — instrumented children increment depth, non-instrumented wrappers are transparent. Results in DOM order |
+| `assignDescendantDepths(root, descendants, startDepth)` | Second-pass walk assigning `depth = startDepth + instrDepth - 1` using a `Set`/`Map` for O(1) lookups |
+
+### Chain-Building Steps
+
+**Step 1 — `collectInstrumentedParents`**: Walk up from `selectedElement.parentElement`, skipping `document.body` and `document.documentElement`. Collect up to `MAX_PARENT_DEPTH` instrumented ancestors, then reverse so outermost comes first.
+
+**Step 2 — `appendParentsWithDepth`**: Each parent gets `depth = index` (0, 1, ...). The count becomes `selfDepth`.
+
+**Step 3 — `getImmediateInstrParent`**: Extract the innermost instrumented parent's element. If `parents` is empty, returns `null` (root-level element).
+
+**Step 4 — `collectSiblings`** (when parent exists): Call `getInstrumentedDescendants(instrParent, 1)` to get all first-level instrumented children of the parent in DOM order — this naturally includes the selected element among its siblings. A safety guard ensures the selected element is always present.
+
+**Step 5 — `appendSiblingsWithSelected`**: Iterate siblings in DOM order, all at `selfDepth`. For the selected element only, delegate to `appendSelfAndDescendants` which also collects and appends children. For other siblings, just push at `selfDepth` with no child expansion.
+
+**Fallback** (no parent): If no instrumented parent exists (root-level element), skip sibling collection and call `appendSelfAndDescendants` directly — just self + children.
+
+---
+
+## Controller Lifecycle (`controller.ts`)
+
+`createLayerController(deps)` returns `{ attachToOverlay, cleanup }`.
+
+### Dependency Injection
+
+| Dep | Called When |
+|-----|------------|
+| `createPreviewOverlay(el)` | User hovers a dropdown item |
+| `getSelectedElementId()` | Checking if hovered item is already selected |
+| `selectElement(el)` | User clicks a dropdown item — performs selection, returns overlay |
+| `onDeselect()` | Dropdown opens — temporarily clears selection for hover previews |
+
+### `attachToOverlay(overlay, element)`
+
+1. Extract the label `<div>` from the overlay.
+2. Call `buildLayerChain(element)`.
+3. **Guard**: if `layers.length <= 1`, return early — no chevron, no click handler. This is how the chevron is hidden when there's nothing to navigate to.
+4. Append chevron via `enhanceLabelWithChevron(label)`.
+5. Bind click handler to label (toggle behavior).
+
+### Click Handler Flow
+
+```
+Label clicked
+  ├─ Dropdown already open → close + reselect source element
+  └─ Dropdown closed →
+       1. Save source element (for Escape restore)
+       2. deps.onDeselect() (clear selection visual)
+       3. Register Escape key listener (capture phase)
+       4. showDropdown(label, layers, callbacks...)
+```
+
+### State Transitions
+
+```
+CLOSED ──[click chevron]──► OPEN
+OPEN   ──[click chevron]──► CLOSED (reselect original)
+OPEN   ──[Escape]──────────► CLOSED (reselect original)
+OPEN   ──[click item]─────► CLOSED → NEW ELEMENT SELECTED → reattach
+OPEN   ──[click outside]──► CLOSED
+```
+
+Selection is recursive — `selectElementFromLayer` calls `deps.selectElement()`, gets a new overlay, and calls `attachToOverlay()` again on it.
+
+---
+
+## Dropdown UI (`dropdown-ui.ts`)
+
+### Global State (singleton)
+
+Only one dropdown can be active at a time:
+
+```typescript
+let activeDropdown: HTMLDivElement | null = null;
+let outsideMousedownHandler: ((e: MouseEvent) => void) | null = null;
+let activeOnHoverEnd: OnLayerHoverEnd | null = null;
+let activeKeydownHandler: ((e: KeyboardEvent) => void) | null = null;
+```
+
+### `showDropdown(label, layers, currentSelectorId, onSelect, onHover, onHoverEnd)`
+
+1. Close any existing dropdown.
+2. Create dropdown element with all layer items.
+3. Position it below the label (`offsetTop + offsetHeight + 2px` gap).
+4. Append to the overlay's parent element.
+5. Set up keyboard navigation and outside-click handler.
+
+### Dropdown Item Rendering
+
+Each `LayerInfo` becomes a `<div>` row:
+
+- **Display name**: `layer.tagName` (e.g., "div", "section")
+- **Indentation**: `paddingLeft = 12 + depth * 10` px
+- **Active (selected) item**: blue text (`#526cff`), light blue bg (`#DBEAFE`), semi-bold
+- **Hover state**: light gray bg (`#f1f5f9`)
+- **Events**: `mouseenter` → preview, `mouseleave` → clear preview, `click` → select
+
+### Keyboard Navigation
+
+- **Arrow Down/Up**: Circular focus movement through items
+- **Enter**: Select focused item
+- All listeners use capture phase to intercept before bubbling
+
+### Outside Click
+
+Registered via `setTimeout(..., 0)` to prevent the opening click from immediately closing. Uses `mousedown` in capture phase for responsive dismissal.
+
+---
+
+## Edge Cases
+
+| Scenario | Behavior |
+|----------|----------|
+| No instrumented parent (root element) | Falls back to self + children only (no siblings) |
+| Only child (no other siblings) | Siblings list contains just self — same result as before |
+| Parent is `document.body`/`html` | Excluded by parent-walk guard, so `parents` is empty |
+| `layers.length <= 1` | No chevron appended, no click handler attached |
+| Element not in siblings list | Safety guard appends it |
+| Non-instrumented wrapper elements | Walked through transparently during descendant collection |
+
+---
+
+## Data Flow Summary
+
+```
+User selects element
+    ↓
+attachToOverlay(overlay, element)
+    ↓
+buildLayerChain(element)
+  ├── collectInstrumentedParents() → parents[] (outermost first)
+  ├── appendParentsWithDepth() → chain gets parents at depth 0,1,...
+  ├── getImmediateInstrParent() → instrParent or null
+  ├── collectSiblings(instrParent) → siblings[] (DOM order)
+  └── appendSiblingsWithSelected()
+       ├── sibling → chain at selfDepth (no expansion)
+       ├── ★ selected → appendSelfAndDescendants()
+       │    ├── self at selfDepth
+       │    ├── getInstrumentedDescendants(self, 2) → children[]
+       │    └── assignDescendantDepths() → children get depth values
+       └── sibling → chain at selfDepth (no expansion)
+    ↓
+LayerInfo[] with depth values
+    ↓
+layers.length > 1 ? enhanceLabelWithChevron() : return
+    ↓
+User clicks chevron → showDropdown()
+    ↓
+createDropdownElement(layers, currentId, callbacks)
+  └── createDropdownItem() for each layer (indented by depth)
+    ↓
+User hovers item → showLayerPreview() → preview overlay
+User clicks item → selectElementFromLayer() → new selection → reattach
+User presses Escape → closeDropdown() → reselect original
+```

package/src/injections/layer-dropdown/consts.ts

@@ -0,0 +1,49 @@
+/** Style constants for the layer dropdown UI */
+
+export const DROPDOWN_CONTAINER_STYLES: Record<string, string> = {
+  position: "absolute",
+  backgroundColor: "#ffffff",
+  border: "1px solid #e2e8f0",
+  borderRadius: "6px",
+  boxShadow: "0 4px 12px rgba(0, 0, 0, 0.15)",
+  fontSize: "12px",
+  minWidth: "120px",
+  maxHeight: "200px",
+  overflowY: "auto",
+  zIndex: "10001",
+  padding: "4px 0",
+  pointerEvents: "auto",
+};
+
+export const DROPDOWN_ITEM_BASE_STYLES: Record<string, string> = {
+  padding: "4px 12px",
+  cursor: "pointer",
+  color: "#334155",
+  backgroundColor: "transparent",
+  whiteSpace: "nowrap",
+  lineHeight: "1.5",
+  fontWeight: "400",
+};
+
+export const DROPDOWN_ITEM_ACTIVE_COLOR = "#526cff";
+export const DROPDOWN_ITEM_ACTIVE_BG = "#DBEAFE";
+export const DROPDOWN_ITEM_ACTIVE_FONT_WEIGHT = "600";
+
+export const DROPDOWN_ITEM_HOVER_BG = "#f1f5f9";
+
+export const DEPTH_INDENT_PX = 10;
+
+/** Chevron shown when dropdown is collapsed (click to expand) */
+export const CHEVRON_COLLAPSED = " \u25BE";
+/** Chevron shown when dropdown is expanded (click to collapse) */
+export const CHEVRON_EXPANDED = " \u25B4";
+
+export const BASE_PADDING_PX = 12;
+
+export const LAYER_DROPDOWN_ATTR = "data-layer-dropdown";
+
+/** Max instrumented ancestors to show above the selected element */
+export const MAX_PARENT_DEPTH = 2;
+
+/** Max instrumented depth levels to show below the selected element */
+export const MAX_CHILD_DEPTH = 2;

package/src/injections/layer-dropdown/controller.ts

@@ -0,0 +1,109 @@
+/** Controller that encapsulates layer-dropdown integration logic */
+
+import { getElementSelectorId } from "../utils.js";
+import { buildLayerChain } from "./utils.js";
+import {
+  enhanceLabelWithChevron,
+  showDropdown,
+  closeDropdown,
+  isDropdownOpen,
+} from "./dropdown-ui.js";
+import type { LayerInfo, LayerControllerConfig, LayerController } from "./types.js";
+
+export function createLayerController(config: LayerControllerConfig): LayerController {
+  let layerPreviewOverlay: HTMLDivElement | null = null;
+  let escapeHandler: ((e: KeyboardEvent) => void) | null = null;
+  let dropdownSourceLayer: LayerInfo | null = null;
+
+  const clearLayerPreview = () => {
+    if (layerPreviewOverlay && layerPreviewOverlay.parentNode) {
+      layerPreviewOverlay.remove();
+    }
+    layerPreviewOverlay = null;
+  };
+
+  const showLayerPreview = (layer: LayerInfo) => {
+    clearLayerPreview();
+    if (getElementSelectorId(layer.element) === config.getSelectedElementId()) return;
+
+    layerPreviewOverlay = config.createPreviewOverlay(layer.element);
+  };
+
+  const selectLayer = (layer: LayerInfo) => {
+    clearLayerPreview();
+    closeDropdown();
+    if (escapeHandler) {
+      document.removeEventListener("keydown", escapeHandler, true);
+      escapeHandler = null;
+    }
+    dropdownSourceLayer = null;
+
+    const firstOverlay = config.selectElement(layer.element);
+    attachToOverlay(firstOverlay, layer.element);
+  };
+
+  const restoreSelection = () => {
+    if (escapeHandler) {
+      document.removeEventListener("keydown", escapeHandler, true);
+      escapeHandler = null;
+    }
+    if (dropdownSourceLayer) {
+      selectLayer(dropdownSourceLayer);
+      dropdownSourceLayer = null;
+    }
+  };
+
+  const handleLabelClick = (e: MouseEvent, label: HTMLDivElement, element: Element, layers: LayerInfo[], currentId: string | null) => {
+    e.stopPropagation();
+    e.preventDefault();
+    if (isDropdownOpen()) {
+      closeDropdown();
+      restoreSelection();
+    } else {
+      dropdownSourceLayer = {
+        element,
+        tagName: element.tagName.toLowerCase(),
+        selectorId: currentId,
+      };
+      config.onDeselect();
+
+      escapeHandler = (ev: KeyboardEvent) => {
+        if (ev.key === "Escape") {
+          ev.stopPropagation();
+          closeDropdown();
+          restoreSelection();
+        }
+      };
+      document.addEventListener("keydown", escapeHandler, true);
+
+      showDropdown(label, layers, element, { onSelect: selectLayer, onHover: showLayerPreview, onHoverEnd: clearLayerPreview });
+    }
+  };
+
+  const attachToOverlay = (
+    overlay: HTMLDivElement | undefined,
+    element: Element
+  ) => {
+    if (!overlay) return;
+
+    const label = overlay.querySelector("div") as HTMLDivElement | null;
+    if (!label) return;
+
+    const layers = buildLayerChain(element);
+    if (layers.length <= 1) return;
+
+    const currentId = getElementSelectorId(element);
+    enhanceLabelWithChevron(label);
+
+    label.addEventListener("click", (e: MouseEvent) => {
+      handleLabelClick(e, label, element, layers, currentId);
+    });
+  };
+
+  const cleanup = () => {
+    clearLayerPreview();
+    closeDropdown();
+  };
+
+  return { attachToOverlay, cleanup };
+}

package/src/injections/layer-dropdown/dropdown-ui.ts

@@ -0,0 +1,230 @@
+/** Dropdown UI component for layer navigation */
+
+import {
+  DROPDOWN_CONTAINER_STYLES,
+  DROPDOWN_ITEM_BASE_STYLES,
+  DROPDOWN_ITEM_ACTIVE_COLOR,
+  DROPDOWN_ITEM_ACTIVE_BG,
+  DROPDOWN_ITEM_ACTIVE_FONT_WEIGHT,
+  DROPDOWN_ITEM_HOVER_BG,
+  DEPTH_INDENT_PX,
+  BASE_PADDING_PX,
+  CHEVRON_COLLAPSED,
+  CHEVRON_EXPANDED,
+  LAYER_DROPDOWN_ATTR,
+} from "./consts.js";
+import { applyStyles, getLayerDisplayName } from "./utils.js";
+import type { LayerInfo, DropdownCallbacks } from "./types.js";
+
+let activeDropdown: HTMLDivElement | null = null;
+let activeLabel: HTMLDivElement | null = null;
+let outsideMousedownHandler: ((e: MouseEvent) => void) | null = null;
+let activeOnHoverEnd: (() => void) | null = null;
+let activeKeydownHandler: ((e: KeyboardEvent) => void) | null = null;
+
+function createDropdownItem(
+  layer: LayerInfo,
+  isActive: boolean,
+  { onSelect, onHover, onHoverEnd }: DropdownCallbacks
+): HTMLDivElement {
+  const item = document.createElement("div");
+  item.textContent = getLayerDisplayName(layer);
+  applyStyles(item, DROPDOWN_ITEM_BASE_STYLES);
+
+  const depth = layer.depth ?? 0;
+  if (depth > 0) {
+    item.style.paddingLeft = `${BASE_PADDING_PX + depth * DEPTH_INDENT_PX}px`;
+  }
+
+  if (isActive) {
+    item.style.color = DROPDOWN_ITEM_ACTIVE_COLOR;
+    item.style.backgroundColor = DROPDOWN_ITEM_ACTIVE_BG;
+    item.style.fontWeight = DROPDOWN_ITEM_ACTIVE_FONT_WEIGHT;
+  }
+
+  item.addEventListener("mouseenter", () => {
+    if (!isActive) item.style.backgroundColor = DROPDOWN_ITEM_HOVER_BG;
+    if (onHover) onHover(layer);
+  });
+
+  item.addEventListener("mouseleave", () => {
+    if (!isActive) item.style.backgroundColor = "transparent";
+    if (onHoverEnd) onHoverEnd();
+  });
+
+  item.addEventListener("click", (e: MouseEvent) => {
+    e.stopPropagation();
+    e.preventDefault();
+    onSelect(layer);
+  });
+
+  return item;
+}
+
+/** Create the dropdown DOM element with layer items */
+export function createDropdownElement(
+  layers: LayerInfo[],
+  currentElement: Element | null,
+  callbacks: DropdownCallbacks
+): HTMLDivElement {
+  const container = document.createElement("div");
+  container.setAttribute(LAYER_DROPDOWN_ATTR, "true");
+  applyStyles(container, DROPDOWN_CONTAINER_STYLES);
+
+  layers.forEach((layer) => {
+    const isActive = layer.element === currentElement;
+    container.appendChild(createDropdownItem(layer, isActive, callbacks));
+  });
+
+  return container;
+}
+
+/** Add chevron indicator and pointer-events to the label */
+export function enhanceLabelWithChevron(label: HTMLDivElement): void {
+  const t = label.textContent ?? "";
+  if (t.endsWith(CHEVRON_COLLAPSED) || t.endsWith(CHEVRON_EXPANDED)) return;
+
+  label.textContent = t + CHEVRON_COLLAPSED;
+  label.style.cursor = "pointer";
+  label.style.userSelect = "none";
+  label.style.whiteSpace = "nowrap";
+  label.style.pointerEvents = "auto";
+  label.setAttribute(LAYER_DROPDOWN_ATTR, "true");
+}
+
+function setupKeyboardNavigation(
+  dropdown: HTMLDivElement,
+  layers: LayerInfo[],
+  currentElement: Element | null,
+  { onSelect, onHover, onHoverEnd }: DropdownCallbacks
+): void {
+  const items = Array.from(dropdown.children) as HTMLDivElement[];
+  let focusedIndex = layers.findIndex((l) => l.element === currentElement);
+
+  const setFocusedItem = (index: number) => {
+    if (focusedIndex >= 0 && focusedIndex < items.length) {
+      const prev = items[focusedIndex]!;
+      if (prev.style.color !== DROPDOWN_ITEM_ACTIVE_COLOR) {
+        prev.style.backgroundColor = "transparent";
+      }
+    }
+    focusedIndex = index;
+    if (focusedIndex >= 0 && focusedIndex < items.length) {
+      const cur = items[focusedIndex]!;
+      if (cur.style.color !== DROPDOWN_ITEM_ACTIVE_COLOR) {
+        cur.style.backgroundColor = DROPDOWN_ITEM_HOVER_BG;
+      }
+      cur.scrollIntoView({ block: "nearest" });
+      if (onHover && focusedIndex >= 0 && focusedIndex < layers.length) {
+        onHover(layers[focusedIndex]!);
+      }
+    }
+  };
+
+  activeKeydownHandler = (e: KeyboardEvent) => {
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      e.stopPropagation();
+      setFocusedItem(focusedIndex < items.length - 1 ? focusedIndex + 1 : 0);
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      e.stopPropagation();
+      setFocusedItem(focusedIndex > 0 ? focusedIndex - 1 : items.length - 1);
+    } else if (e.key === "Enter" && focusedIndex >= 0 && focusedIndex < layers.length) {
+      e.preventDefault();
+      e.stopPropagation();
+      if (onHoverEnd) onHoverEnd();
+      onSelect(layers[focusedIndex]!);
+      closeDropdown();
+    }
+  };
+  document.addEventListener("keydown", activeKeydownHandler, true);
+}
+
+function setupOutsideClickHandler(
+  dropdown: HTMLDivElement,
+  label: HTMLDivElement
+): void {
+  let skipFirst = true;
+  outsideMousedownHandler = (e: MouseEvent) => {
+    if (skipFirst) { skipFirst = false; return; }
+    const target = e.target as Node;
+    if (!dropdown.contains(target) && target !== label) {
+      closeDropdown();
+    }
+  };
+  document.addEventListener("mousedown", outsideMousedownHandler, true);
+}
+
+/** Show the dropdown below the label element */
+export function showDropdown(
+  label: HTMLDivElement,
+  layers: LayerInfo[],
+  currentElement: Element | null,
+  callbacks: DropdownCallbacks
+): void {
+  closeDropdown();
+
+  const dropdown = createDropdownElement(
+    layers,
+    currentElement,
+    {
+      ...callbacks,
+      onSelect: (layer) => {
+        if (callbacks.onHoverEnd) callbacks.onHoverEnd();
+        callbacks.onSelect(layer);
+        closeDropdown();
+      },
+    }
+  );
+
+  const overlay = label.parentElement;
+  if (!overlay) return;
+
+  dropdown.style.top = `${label.offsetTop + label.offsetHeight + 2}px`;
+  dropdown.style.left = `${label.offsetLeft}px`;
+
+  overlay.appendChild(dropdown);
+  activeDropdown = dropdown;
+  activeLabel = label;
+  if (label.textContent?.endsWith(CHEVRON_COLLAPSED.trim())) {
+    label.textContent = label.textContent.slice(0, -CHEVRON_COLLAPSED.length) + CHEVRON_EXPANDED;
+  }
+  activeOnHoverEnd = callbacks.onHoverEnd ?? null;
+
+  setupKeyboardNavigation(dropdown, layers, currentElement, callbacks);
+  setupOutsideClickHandler(dropdown, label);
+}
+
+/** Close the active dropdown and clean up listeners */
+export function closeDropdown(): void {
+  if (activeLabel?.textContent?.includes(CHEVRON_EXPANDED)) {
+    activeLabel.textContent = activeLabel.textContent.replace(CHEVRON_EXPANDED, CHEVRON_COLLAPSED);
+  }
+  activeLabel = null;
+
+  if (activeOnHoverEnd) {
+    activeOnHoverEnd();
+    activeOnHoverEnd = null;
+  }
+
+  if (activeDropdown && activeDropdown.parentNode) {
+    activeDropdown.remove();
+  }
+  activeDropdown = null;
+
+  if (outsideMousedownHandler) {
+    document.removeEventListener("mousedown", outsideMousedownHandler, true);
+    outsideMousedownHandler = null;
+  }
+
+  if (activeKeydownHandler) {
+    document.removeEventListener("keydown", activeKeydownHandler, true);
+    activeKeydownHandler = null;
+  }
+}
+
+/** Check if a dropdown is currently visible */
+export function isDropdownOpen(): boolean {
+  return activeDropdown !== null;
+}

package/src/injections/layer-dropdown/types.ts

@@ -0,0 +1,30 @@
+/** Shared types for the layer-dropdown module */
+
+export interface LayerInfo {
+  element: Element;
+  tagName: string;
+  selectorId: string | null;
+  depth?: number;
+}
+
+export type OnLayerSelect = (layer: LayerInfo) => void;
+export type OnLayerHover = (layer: LayerInfo) => void;
+export type OnLayerHoverEnd = () => void;
+
+export interface DropdownCallbacks {
+  onSelect: OnLayerSelect;
+  onHover?: OnLayerHover;
+  onHoverEnd?: OnLayerHoverEnd;
+}
+
+export interface LayerControllerConfig {
+  createPreviewOverlay: (element: Element) => HTMLDivElement;
+  getSelectedElementId: () => string | null;
+  selectElement: (element: Element) => HTMLDivElement | undefined;
+  onDeselect: () => void;
+}
+
+export interface LayerController {
+  attachToOverlay: (overlay: HTMLDivElement | undefined, element: Element) => void;
+  cleanup: () => void;
+}