@popover-kit/svelte 0.1.1 → 0.1.2

package/README.md

@@ -78,14 +78,57 @@ ctrl.open();
 `PopoverController` is pure TypeScript (a `.svelte.ts` module using runes
 for its reactive state) — no component required.
 
-## Scripts
+## `DropdownController` — for CSS-anchored panels (no floating positioning)
+
+`PopoverController` computes `position: fixed` coordinates, which is more
+than you need for a panel that's already positioned with plain CSS (e.g.
+`position: relative` on a wrapper + `top-full` on the panel) — an account
+switcher, an inline menu, anything anchored by layout rather than JS.
+
+`DropdownController` is a separate, smaller primitive for exactly that case:
+open/close state, click-outside, Escape, and a focus trap — no
+`computePosition`, no `ResizeObserver`, no scroll/resize tracking, and no
+4-state animation lifecycle (Svelte's own `{#if isOpen}` + `transition:`
+already keeps a panel mounted through its exit transition natively, so
+there's nothing for the controller to coordinate there).
+
+`PopoverController` and `DropdownController` both extend
+`OverlayControllerBase`, which owns everything genuinely identical between
+them — id generation, options-as-getters, click-outside/Esc/focus-trap
+wiring — so the a11y behavior isn't duplicated or able to drift between the
+two. `OverlayControllerBase` is exported too, for a third overlay type
+(context menu, tooltip, ...) to extend the same way.
+
+Wire either controller to real DOM elements with `use:overlayTrigger` /
+`use:overlayPanel` — plain Svelte actions, no added DOM, no styling. This is
+the same mechanism `<Popover>`'s own trigger wiring uses internally, so it's
+exercised by the package's own components, not just offered for headless use:
 
-```bash
-pnpm build          # bundles src/ -> dist/index.js + dist/index.d.ts
-pnpm test           # vitest (position engine, a11y utils, controller)
-pnpm typecheck      # svelte-check
+```svelte
+<script lang="ts">
+	import { DropdownController, overlayTrigger, overlayPanel } from '@popover-kit/svelte';
+
+	const dropdown = new DropdownController({
+		hooks: {
+			// Runs right before the panel opens — e.g. refresh data on open.
+			beforeOpen: () => refreshList()
+		}
+	});
+</script>
+
+<button use:overlayTrigger={dropdown} onclick={() => dropdown.toggle()}>
+	Toggle
+</button>
+
+{#if dropdown.isOpen}
+	<div use:overlayPanel={dropdown} transition:fly={{ y: -5 }}>...</div>
+{/if}
 ```
 
+No `$effect`/`bind:this` wiring needed — the actions attach on mount and
+detach on unmount by themselves. `PopoverController` accepts the same
+`hooks.beforeOpen` option and works with the same two actions.
+
 ## License
 
 MIT

package/dist/actions.js

@@ -0,0 +1 @@
+function i(e,a){return(r,t)=>(e(t,r),{update(g){g!==t&&(a(t),t=g,e(t,r))},destroy(){a(t)}})}const n=i((e,a)=>e.attachTrigger(a),e=>e.detachTrigger()),u=i((e,a)=>e.attachPanel(a),e=>e.detachPanel());export{u as overlayPanel,n as overlayTrigger};

package/dist/components/Popover.svelte

@@ -4,14 +4,17 @@
 	 *
 	 * Architecture:
 	 *   • Creates or accepts an injected PopoverController.
-	 *   • Wires trigger and panel DOM refs via $effect (required — bind:this is async).
+	 *   • Trigger DOM ref: `use:overlayTrigger` (a plain Svelte action, no
+	 *     $effect needed — see actions.ts). Panel DOM ref: still $effect,
+	 *     since it's a $bindable prop from a child component, not a node in
+	 *     this component's own template (actions can only attach to elements
+	 *     in the same template).
 	 *   • Passes inline snippet contexts (no $derived — each used once, caching wastes).
 	 *   • Panel renders only while ctrl.isVisible (open + exit-animation).
 	 *
 	 * $effect usage (justified):
-	 *   1. triggerWrapEl wiring  — bind:this is async; must react to ref being set.
-	 *   2. panelEl wiring        — panel is conditionally mounted; $effect detects mount.
-	 *   3. controlled-mode sync  — external prop can change at any time.
+	 *   1. panelEl wiring        — panel is conditionally mounted; $effect detects mount.
+	 *   2. controlled-mode sync  — external prop can change at any time.
 	 *
 	 * Snippets (Bits UI style):
 	 *   {#snippet trigger(ctx: TriggerSnippetCtx)}  — render the trigger element
@@ -27,6 +30,7 @@
 	} from '../types.js';
 
 	import { PopoverController } from '../controller.svelte.js';
+	import { overlayTrigger } from '../actions.js';
 	import PopoverPanel from '../elements/PopoverPanel.svelte';
 	import {
 		DEFAULT_OPTIONS,
@@ -53,6 +57,7 @@
 		trapFocus = DEFAULT_OPTIONS.trapFocus,
 		closeOnOutsideClick = DEFAULT_OPTIONS.closeOnOutsideClick,
 		closeOnEsc = DEFAULT_OPTIONS.closeOnEsc,
+		hooks,
 		onOpen,
 		onClose,
 		onStateChange,
@@ -92,6 +97,7 @@
 			trapFocus,
 			closeOnOutsideClick,
 			closeOnEsc,
+			hooks,
 			onOpen,
 			onClose,
 			onStateChange
@@ -100,20 +106,12 @@
 
 	// ── DOM refs ─────────────────────────────────────────────────────────────────
 	//
-	// triggerWrapEl: root <span> — the position anchor for getBoundingClientRect().
-	// panelEl:       $bindable from PopoverPanel — wired to ctrl.attachPanel().
-	//
-	// Both use $effect because bind:this is asynchronous in Svelte 5 — the ref
-	// is set after the element is mounted, so there's no synchronous alternative.
+	// panelEl: $bindable from PopoverPanel — wired to ctrl.attachPanel() via
+	// $effect (bind:this is async, and the node lives in a child component's
+	// template, so an action can't attach to it directly from here).
 
-	let triggerWrapEl = $state<HTMLElement | null>(null);
 	let panelEl = $state<HTMLElement | null>(null);
 
-	$effect(() => {
-		if (triggerWrapEl) ctrl.attachTrigger(triggerWrapEl);
-		else ctrl.detachTrigger();
-	});
-
 	$effect(() => {
 		if (panelEl) ctrl.attachPanel(panelEl);
 		else ctrl.detachPanel();
@@ -210,12 +208,12 @@
 
 <!--
   Root wrapper: inline-block keeps it tight around the trigger so that
-  getBoundingClientRect() on triggerWrapEl returns the trigger's actual rect.
+  getBoundingClientRect() on it (wired via use:overlayTrigger) returns the trigger's actual rect.
 
   Snippet contexts are passed INLINE — each is used exactly once in the template,
   so storing them in $derived would add a reactive subscription with zero benefit.
 -->
-<span class="pop-root" bind:this={triggerWrapEl}>
+<span class="pop-root" use:overlayTrigger={ctrl}>
 	<!-- ── Trigger ─────────────────────────────────────────────────────────── -->
 	{#if triggerSnippet}
 		{@render triggerSnippet({

package/dist/controller.svelte.js

@@ -3,6 +3,13 @@
 //
 // File MUST be *.svelte.ts — Svelte 5 compiles $state runes only in .svelte.ts.
 //
+// Extends OverlayControllerBase (id, options-as-getters, click-outside/Esc/
+// focus-trap wiring — see that file for why it's a separate base rather than
+// this class doing everything). What's unique to PopoverController lives
+// here as true `#private` fields, since DropdownController never needs it:
+// the 4-state lifecycle, positioning (`computePosition`, flip hysteresis),
+// ResizeObserver, and scroll/resize tracking.
+//
 // Open sequence (critical — previous versions got this wrong):
 //
 // Two DOM-mounting strategies are supported, both converging on the same
@@ -14,7 +21,8 @@
 //     2. Svelte sees isVisible changed, mounts the panel element in the DOM.
 //     3. Svelte runs $effects. The $effect in Popover.svelte sees panelEl is
 //        now set and calls ctrl.attachPanel(el).
-//     4. attachPanel() detects state === 'opening' → calls #finishOpen().
+//     4. attachPanel() → base class calls _onPanelAttached() → state is
+//        'opening' → calls #finishOpen().
 //
 //   B) Headless / always-mounted panel (attachTrigger + attachPanel called
 //      once up front, before open() is ever called):
@@ -26,66 +34,48 @@
 //   position, sets up listeners, sets state → 'open'.
 //
 // This ordering guarantees:
-//   • #panelEl is always non-null when #setupListeners() runs.
+//   • #panelEl is always non-null when listeners are wired.
 //   • Click-outside uses the real panel element (not null).
 //   • No rAF/setTimeout hacks needed.
 //   • open() completes synchronously regardless of mounting strategy.
 // =============================================================================
+import { OverlayControllerBase } from "./overlay-controller-base.svelte.js";
 import { computePosition } from "./utils/position.js";
-import { createFocusTrap, onClickOutside, announce } from "./utils/a11y.js";
-import { uid, DEFAULT_OPTIONS, ANIMATION_DURATION_MS } from "./constants.js";
-export class PopoverController {
-    // ─── Stable IDs ───────────────────────────────────────────────────────────────
-    triggerId;
-    contentId;
-    // ─── Reactive state ($state runes — tracked by Svelte templates) ──────────────
-    #isOpen = $state(false);
+import { announce } from "./utils/a11y.js";
+import { DEFAULT_OPTIONS, ANIMATION_DURATION_MS } from "./constants.js";
+export class PopoverController extends OverlayControllerBase {
+    // ─── Reactive state — private to this subclass; DropdownController has no
+    //     use for any of it ────────────────────────────────────────────────────
     #state = $state("closed");
     #resolvedPlacement = $state("bottom");
     #pos = $state(null);
-    // ─── DOM refs ─────────────────────────────────────────────────────────────────
-    #triggerEl = null;
-    #panelEl = null;
-    // ─── Options (set at construction, immutable after) ───────────────────────────
-    #placement; // mutable via setPlacement()
-    #offset;
-    #trapFocus;
-    #closeOnOutsideClick;
-    #closeOnEsc;
-    #onOpen;
-    #onClose;
-    #onStateChange;
-    // ─── Lazy resources (null while closed — zero allocation at rest) ──────────────
-    #focusTrap = null;
-    #clickOutsideStop = null;
+    // ─── Positioning-only listeners (click-outside/Esc/focus-trap live in the
+    //     base class) ────────────────────────────────────────────────────────────
     #scrollResizeStop = null;
-    #escStop = null;
     #resizeObs = null;
-    // ─── Headless subscribers ─────────────────────────────────────────────────────
-    #subscribers = new Set();
+    #rafId = null;
     // ─── Timers ───────────────────────────────────────────────────────────────────
     #focusTrapTimer = null;
     #closeTimer = null;
-    // ─── rAF handle — coalesces scroll/resize into one recompute per frame ─────────
-    #rafId = null;
-    // =============================================================================
-    constructor(opts = {}) {
-        const id = opts.id ?? uid();
-        this.triggerId = `${id}-trigger`;
-        this.contentId = `${id}-content`;
-        this.#placement = opts.placement ?? DEFAULT_OPTIONS.placement;
-        this.#offset = opts.offset ?? DEFAULT_OPTIONS.offset;
-        this.#trapFocus = opts.trapFocus ?? DEFAULT_OPTIONS.trapFocus;
-        this.#closeOnOutsideClick = opts.closeOnOutsideClick ?? DEFAULT_OPTIONS.closeOnOutsideClick;
-        this.#closeOnEsc = opts.closeOnEsc ?? DEFAULT_OPTIONS.closeOnEsc;
-        this.#onOpen = opts.onOpen;
-        this.#onClose = opts.onClose;
-        this.#onStateChange = opts.onStateChange;
-        this.#resolvedPlacement = this.#placement;
+    constructor(options = {}) {
+        super(options, "pop");
+        this.#resolvedPlacement = this.placement;
+    }
+    // ─── Options getters unique to Popover (shared ones live in the base) ────────
+    get placement() {
+        return this._options.placement ?? DEFAULT_OPTIONS.placement;
+    }
+    get offset() {
+        return this._options.offset ?? DEFAULT_OPTIONS.offset;
+    }
+    get onStateChange() {
+        return this._options.onStateChange;
     }
     // ─── Reactive getters ─────────────────────────────────────────────────────────
+    /** Derived from `state`, not a separately-tracked flag — there is exactly one
+     *  state ('open') that means "open", so there's nothing to keep in sync. */
     get isOpen() {
-        return this.#isOpen;
+        return this.#state === "open";
     }
     get state() {
         return this.#state;
@@ -102,36 +92,20 @@ export class PopoverController {
     // ─── Snapshot ─────────────────────────────────────────────────────────────────
     getSnapshot() {
         return {
-            isOpen: this.#isOpen,
+            isOpen: this.isOpen,
             state: this.#state,
             resolvedPlacement: this.#resolvedPlacement,
             triggerId: this.triggerId,
             contentId: this.contentId
         };
     }
-    // ─── Subscriptions ────────────────────────────────────────────────────────────
-    subscribe(cb) {
-        this.#subscribers.add(cb);
-        cb(this.getSnapshot());
-        return () => this.#subscribers.delete(cb);
-    }
-    #emit() {
-        if (!this.#subscribers.size)
-            return;
-        const snap = this.getSnapshot();
-        this.#subscribers.forEach((cb) => cb(snap));
-    }
-    // ─── Element wiring ───────────────────────────────────────────────────────────
-    attachTrigger(el) {
-        this.#triggerEl = el;
-    }
+    // ─── Element wiring — base class handles attach/detach; this only reacts ─────
     /**
-     * Called by Popover.svelte's $effect after the panel element mounts.
+     * Called by the base class's attachPanel() after the panel element mounts.
      * If state is 'opening', we're in the open sequence → finish it now.
      * If state is already 'open', controller was re-attached → just recompute.
      */
-    attachPanel(el) {
-        this.#panelEl = el;
+    _onPanelAttached() {
         if (this.#state === "opening") {
             this.#finishOpen();
         }
@@ -139,81 +113,114 @@ export class PopoverController {
             this.#compute();
         }
     }
-    detachTrigger() {
-        this.#triggerEl = null;
-    }
-    detachPanel() {
-        this.#panelEl = null;
-    }
     // ─── Core actions ─────────────────────────────────────────────────────────────
     open() {
-        if (this.#isOpen || this.#state === "opening")
+        if (this.isOpen || this.#state === "opening")
             return;
         this.#cancelClose();
+        this.hooks.beforeOpen?.();
         // Set 'opening' FIRST → isVisible becomes true → Svelte mounts the panel
         // → $effect fires → attachPanel() → #finishOpen().
-        this.#setState(false, "opening");
+        this.#setState("opening");
         // Headless usage (or any consumer that keeps the panel element in the
         // DOM at all times instead of conditionally mounting it) already has
         // #panelEl set at this point — no attachPanel() call is coming to
         // finish the sequence, so finish it here instead. This makes open()
         // correct regardless of DOM-mounting strategy.
-        if (this.#panelEl)
+        if (this._panelEl)
             this.#finishOpen();
     }
     close() {
-        if (!this.#isOpen || this.#state === "closing")
+        if (this.#state === "opening") {
+            // open() was called but the panel never finished mounting (e.g. a
+            // consumer calls open() then close() synchronously, before Svelte's
+            // $effect had a chance to run attachPanel()). Nothing ever became
+            // visible, so there's no exit animation to run — cancel straight to
+            // 'closed' rather than getting stuck in 'opening' forever, since the
+            // normal close() guard below treats 'opening' as "already closed"
+            // and would otherwise silently no-op here.
+            this.#setState("closed");
+            return;
+        }
+        if (!this.isOpen || this.#state === "closing")
             return;
         this.#cancelFocusTrapTimer();
-        this.#setState(false, "closing");
-        this.#teardownListeners();
+        this.#setState("closing");
+        this._teardownSharedListeners();
+        this.#teardownPositionListeners();
         this.#closeTimer = setTimeout(() => {
             if (this.#state === "closing") {
-                this.#setState(false, "closed");
+                this.#setState("closed");
                 this.#pos = null;
                 announce("Popover closed");
-                this.#onClose?.();
+                this.onClose?.();
             }
         }, ANIMATION_DURATION_MS);
     }
-    toggle() {
-        this.#isOpen ? this.close() : this.open();
-    }
     setPlacement(p) {
-        this.#placement = p;
-        if (this.#state === "open")
-            this.#compute();
+        this._options = { ...this._options, placement: p };
+        if (this.#state === "open") {
+            // resetHysteresis: true — the consumer just explicitly asked for a
+            // *different* preferred side. Flip hysteresis (see #compute()) exists
+            // to stop the SAME requested placement from flip-flopping across
+            // repeated recomputes (scroll/resize) right at the viewport
+            // boundary; it should not fight a genuinely new request by
+            // "sticking" to the side that was resolved under the OLD
+            // placement. Without this, e.g. setPlacement('top') right after
+            // resolving to 'bottom' could stay on 'bottom' even when 'top' now
+            // fits, because 'bottom' still technically fits too.
+            this.#compute(true);
+            // #compute() alone only updates the $state fields (which Svelte
+            // templates pick up automatically via the getters above) — headless
+            // subscribe() consumers only ever hear about changes through an
+            // explicit snapshot push, so without this they'd keep the stale
+            // resolvedPlacement/position from before setPlacement() was called.
+            this._emit();
+        }
     }
     // ─── Destroy ──────────────────────────────────────────────────────────────────
     destroy() {
         this.#cancelFocusTrapTimer();
         this.#cancelClose();
-        this.#cancelRaf();
-        this.#teardownListeners();
-        this.#subscribers.clear();
-        this.#triggerEl = null;
-        this.#panelEl = null;
+        this.#teardownPositionListeners();
+        super.destroy(); // tears down shared a11y listeners + subscribers + refs
+    }
+    // ─── Focus-trap timing override — see base class doc comment ─────────────────
+    _activateFocusTrap() {
+        // Delayed so it activates after the enter animation completes.
+        // DropdownController has no such animation and activates immediately.
+        this.#focusTrapTimer = setTimeout(() => this._focusTrap?.activate(), ANIMATION_DURATION_MS);
     }
     // ─── Private: open sequence ───────────────────────────────────────────────────
     /**
-     * Called from attachPanel() when state === 'opening'.
+     * Called from _onPanelAttached() when state === 'opening'.
      * At this point the panel element is guaranteed to be in the DOM.
      */
     #finishOpen() {
         this.#compute(); // position panel (reads real dimensions)
-        this.#setupListeners(); // wire click-outside, Esc, scroll, resize
-        this.#setState(true, "open");
+        this._setupSharedListeners(); // click-outside, Esc, focus trap (base class)
+        this.#setupPositionListeners(); // scroll, resize, ResizeObserver (this class)
+        this.#setState("open");
         announce("Popover opened");
-        this.#onOpen?.();
+        this.onOpen?.();
     }
     // ─── Private: positioning ─────────────────────────────────────────────────────
-    #compute() {
-        if (!this.#triggerEl || !this.#panelEl)
+    /**
+     * @param resetHysteresis - Pass `true` when the *requested* placement
+     *   itself just changed (currently only `setPlacement()`), so the flip
+     *   decision starts fresh instead of being biased toward whatever side
+     *   was last resolved under the previous requested placement.
+     */
+    #compute(resetHysteresis = false) {
+        if (!this._triggerEl || !this._panelEl)
             return;
         // Pass the previous resolved placement for flip hysteresis — keeps the
         // panel on whichever side it's already showing on when that side still
-        // fits, instead of flip-flopping right at the viewport boundary.
-        const result = computePosition(this.#triggerEl, this.#panelEl, this.#placement, this.#offset, this.#resolvedPlacement);
+        // fits, instead of flip-flopping right at the viewport boundary. Only
+        // meaningful when recomputing the SAME requested placement (scroll,
+        // resize, a re-attached panel) — see resetHysteresis above.
+        const previousPlacement = resetHysteresis ? null : this.#resolvedPlacement;
+        const result = computePosition(this._triggerEl, this._panelEl, this.placement, this.offset, previousPlacement);
         this.#pos = result;
         this.#resolvedPlacement = result.placement;
     }
@@ -224,11 +231,11 @@ export class PopoverController {
             this.#rafId = null;
             // Guaranteed 'open' in practice — the scroll/resize/ResizeObserver
             // listeners that call this are only ever wired up in
-            // #setupListeners() (called from #finishOpen()) and torn down
-            // synchronously the moment close() runs, so no stale rAF can land
-            // here mid-'closing'. Checked anyway as defense-in-depth against
-            // exactly the class of "recomputed mid-exit-animation" bug that
-            // causes a panel to visibly jump/flip while fading out.
+            // #setupPositionListeners() (called from #finishOpen()) and torn
+            // down synchronously the moment close() runs, so no stale rAF can
+            // land here mid-'closing'. Checked anyway as defense-in-depth
+            // against exactly the class of "recomputed mid-exit-animation" bug
+            // that causes a panel to visibly jump/flip while fading out.
             if (this.#state === "open")
                 this.#compute();
         });
@@ -239,32 +246,10 @@ export class PopoverController {
             this.#rafId = null;
         }
     }
-    // ─── Private: listeners ───────────────────────────────────────────────────────
-    #setupListeners() {
-        const trigger = this.#triggerEl;
-        const panel = this.#panelEl;
-        // Click outside — uses pointerdown capture phase.
-        // Does NOT call preventDefault/stopPropagation → background elements stay
-        // fully interactive. The popover simply closes on the next tick.
-        if (this.#closeOnOutsideClick && trigger && panel) {
-            this.#clickOutsideStop = onClickOutside([trigger, panel], () => this.close());
-        }
-        // Esc key
-        if (this.#closeOnEsc) {
-            const handler = (e) => {
-                if (e.key === "Escape") {
-                    e.stopPropagation();
-                    this.close();
-                }
-            };
-            document.addEventListener("keydown", handler, true);
-            this.#escStop = () => document.removeEventListener("keydown", handler, true);
-        }
-        // Focus trap — delayed so it activates after enter animation completes
-        if (this.#trapFocus && panel) {
-            this.#focusTrap = createFocusTrap(panel, trigger ?? undefined);
-            this.#focusTrapTimer = setTimeout(() => this.#focusTrap?.activate(), ANIMATION_DURATION_MS);
-        }
+    // ─── Private: positioning-only listeners ─────────────────────────────────────
+    #setupPositionListeners() {
+        const trigger = this._triggerEl;
+        const panel = this._panelEl;
         // Scroll + resize → rAF-coalesced recompute (max one per frame)
         const recompute = () => this.#scheduleCompute();
         window.addEventListener("scroll", recompute, { passive: true, capture: true });
@@ -281,25 +266,18 @@ export class PopoverController {
                 this.#resizeObs.observe(panel);
         }
     }
-    #teardownListeners() {
-        this.#focusTrap?.deactivate();
-        this.#clickOutsideStop?.();
+    #teardownPositionListeners() {
         this.#scrollResizeStop?.();
-        this.#escStop?.();
         this.#resizeObs?.disconnect();
         this.#cancelRaf();
-        this.#focusTrap = null;
-        this.#clickOutsideStop = null;
         this.#scrollResizeStop = null;
-        this.#escStop = null;
         this.#resizeObs = null;
     }
     // ─── Private: state ───────────────────────────────────────────────────────────
-    #setState(isOpen, state) {
-        this.#isOpen = isOpen;
+    #setState(state) {
         this.#state = state;
-        this.#onStateChange?.(state);
-        this.#emit();
+        this.onStateChange?.(state);
+        this._emit();
     }
     #cancelFocusTrapTimer() {
         if (this.#focusTrapTimer !== null) {

package/dist/dropdown-controller.svelte.js

@@ -0,0 +1,65 @@
+// =============================================================================
+// Popover Micro-Plugin — DropdownController
+//
+// File MUST be *.svelte.ts — Svelte 5 compiles $state runes only in .svelte.ts.
+//
+// For CSS-anchored panels (account switchers, inline menus, anything placed
+// with plain CSS rather than `computePosition`) that only need: open/close
+// state, click-outside, Escape, a focus trap, and a `beforeOpen` hook to
+// refresh data — without any positioning engine, ResizeObserver, or
+// scroll/resize tracking.
+//
+// Extends OverlayControllerBase, which owns everything that's identical to
+// PopoverController (id, options-as-getters, click-outside/Esc/focus-trap
+// wiring). All this class adds is the plain boolean `isOpen` state and the
+// synchronous open()/close() sequence — no 4-state lifecycle, because
+// there's no positioning to keep settled during an exit animation. Svelte's
+// own `{#if isOpen}` + `transition:`/`in:`/`out:` already keeps a panel
+// mounted through its exit transition natively.
+// =============================================================================
+import { OverlayControllerBase } from "./overlay-controller-base.svelte.js";
+export class DropdownController extends OverlayControllerBase {
+    #isOpen = $state(false);
+    constructor(options = {}) {
+        super(options, "dd");
+    }
+    get isOpen() {
+        return this.#isOpen;
+    }
+    get onStateChange() {
+        return this._options.onStateChange;
+    }
+    _onPanelAttached() {
+        // Panel (re)attached while already open — e.g. re-rendered. Wire
+        // listeners against the new element. If we're not open yet, open()
+        // itself will wire them once it runs.
+        if (this.#isOpen)
+            this._setupSharedListeners();
+    }
+    open() {
+        if (this.#isOpen)
+            return;
+        this.hooks.beforeOpen?.();
+        this.#isOpen = true;
+        // Headless / already-mounted panel: no later attachPanel() call is
+        // coming, so wire listeners now. Conditionally-mounted panel: wired
+        // from _onPanelAttached() once it mounts.
+        if (this._panelEl)
+            this._setupSharedListeners();
+        this.onOpen?.();
+        this.onStateChange?.(true);
+        this._emit();
+    }
+    close() {
+        if (!this.#isOpen)
+            return;
+        this.#isOpen = false;
+        this._teardownSharedListeners();
+        this.onClose?.();
+        this.onStateChange?.(false);
+        this._emit();
+    }
+    getSnapshot() {
+        return { isOpen: this.#isOpen, triggerId: this.triggerId, contentId: this.contentId };
+    }
+}

package/dist/elements/PopoverArrow.svelte

@@ -19,6 +19,7 @@
 	 * bordered triangle that matches the card's border colour.
 	 */
 	import type { Placement } from '../types.js';
+	import { parsePlacement } from '../utils/position.js';
 
 	interface Props {
 		placement: Placement;
@@ -27,11 +28,9 @@
 
 	const { placement, class: cls = '' }: Props = $props();
 
-	const side = $derived(
-		placement === 'autoVertical'
-			? 'bottom'
-			: (placement.split('-')[0] as 'top' | 'bottom' | 'left' | 'right')
-	);
+	// Same parsing PopoverPanel.svelte uses for its own transform-origin —
+	// shared via parsePlacement rather than duplicated inline.
+	const side = $derived(parsePlacement(placement).side);
 </script>
 
 <span class="pop-arrow pop-arrow--{side} {cls}" aria-hidden="true"></span>

package/dist/elements/PopoverPanel.svelte

@@ -17,6 +17,7 @@
 	 */
 	import type { Snippet } from 'svelte';
 	import type { Placement, ResolvedPosition, PopoverAnimation } from '../types.js';
+	import { parsePlacement } from '../utils/position.js';
 	import PopoverArrow from './PopoverArrow.svelte';
 
 	interface Props {
@@ -64,10 +65,11 @@
 	/**
 	 * Primary side — drives animation transform-origin and direction.
 	 * autoVertical resolves to 'bottom' until the controller flips it.
+	 * Reuses the same parsing `computePosition` itself uses, rather than
+	 * re-deriving it with a separate inline ternary (PopoverArrow.svelte
+	 * needs the identical side, so this is shared, not duplicated).
 	 */
-	const side = $derived(
-		resolvedPlacement === 'autoVertical' ? 'bottom' : (resolvedPlacement.split('-')[0] as string)
-	);
+	const side = $derived(parsePlacement(resolvedPlacement).side);
 </script>
 
 <div

package/dist/index.d.ts

@@ -21,11 +21,38 @@ export interface ResolvedPosition {
 }
 /** Fine-grained lifecycle state — drives CSS enter/exit transitions. */
 export type PopoverState = "closed" | "opening" | "open" | "closing";
+/**
+ * Optional lifecycle hooks, scoped under `hooks` so the option list doesn't
+ * balloon as more get added. Start minimal: just `beforeOpen`. Signature is
+ * `void`-returning (fire-and-forget) for now — widening it to
+ * `void | Promise<void>` later (e.g. to await a data fetch before opening)
+ * is a non-breaking change for every existing synchronous hook.
+ */
+export interface OverlayHooks {
+	/** Called right before the overlay opens (before any DOM/listener setup). */
+	beforeOpen?: () => void;
+}
+export interface BaseOverlayOptions {
+	/** ID prefix for generated ARIA ids. Auto-generated if omitted. */
+	id?: string;
+	trapFocus?: boolean;
+	closeOnOutsideClick?: boolean;
+	closeOnEsc?: boolean;
+	hooks?: OverlayHooks;
+	onOpen?: () => void;
+	onClose?: () => void;
+}
+export interface AttachableController {
+	attachTrigger(el: HTMLElement): void;
+	detachTrigger(): void;
+	attachPanel(el: HTMLElement): void;
+	detachPanel(): void;
+}
 /**
  * Public surface of PopoverController.
  * All readonly getters are $state runes — Svelte templates track them.
  */
-export interface IPopoverController {
+export interface IPopoverController extends AttachableController {
 	readonly isOpen: boolean;
 	readonly state: PopoverState;
 	readonly resolvedPlacement: Placement;
@@ -38,10 +65,6 @@ export interface IPopoverController {
 	close(): void;
 	toggle(): void;
 	setPlacement(p: Placement): void;
-	attachTrigger(el: HTMLElement): void;
-	attachPanel(el: HTMLElement): void;
-	detachTrigger(): void;
-	detachPanel(): void;
 	getSnapshot(): PopoverSnapshot;
 	subscribe(cb: SubscriberFn): UnsubscribeFn;
 	destroy(): void;
@@ -55,18 +78,11 @@ export interface PopoverSnapshot {
 }
 export type SubscriberFn = (snap: PopoverSnapshot) => void;
 export type UnsubscribeFn = () => void;
-export interface ControllerOptions {
-	/** ID prefix for generated ARIA ids. Auto-generated if omitted. */
-	id?: string;
+export interface ControllerOptions extends BaseOverlayOptions {
 	/** Preferred placement. Default: `bottom`. */
 	placement?: Placement;
 	/** Gap between trigger and panel in px. Default: 8. */
 	offset?: number;
-	trapFocus?: boolean;
-	closeOnOutsideClick?: boolean;
-	closeOnEsc?: boolean;
-	onOpen?: () => void;
-	onClose?: () => void;
 	onStateChange?: (state: PopoverState) => void;
 }
 export type PopoverAnimation = "scale" | "slide" | "fade" | "none";
@@ -122,32 +138,115 @@ export interface ThemeTokens {
 	darkText: string;
 	accentColor: string;
 }
-export declare class PopoverController implements IPopoverController {
-	#private;
+export interface DropdownControllerOptions extends BaseOverlayOptions {
+	/** Fires on every open AND close, with the new `isOpen` value. For "run
+	 *  this only when opening" (e.g. refresh data), prefer `onOpen` (inherited
+	 *  from `BaseOverlayOptions`) or `hooks.beforeOpen`, both of which only
+	 *  fire on open. */
+	onStateChange?: (isOpen: boolean) => void;
+}
+export interface DropdownSnapshot {
+	readonly isOpen: boolean;
+	readonly triggerId: string;
+	readonly contentId: string;
+}
+export interface IDropdownController extends AttachableController {
+	readonly isOpen: boolean;
 	readonly triggerId: string;
 	readonly contentId: string;
-	constructor(opts?: ControllerOptions);
+	open(): void;
+	close(): void;
+	toggle(): void;
+	getSnapshot(): DropdownSnapshot;
+	subscribe(cb: (snap: DropdownSnapshot) => void): UnsubscribeFn;
+	destroy(): void;
+}
+/**
+ * Keeps keyboard focus inside `container` while active.
+ * Activation is deferred so it can be timed to the enter animation.
+ *
+ * @param container - The panel element to trap focus within.
+ * @param returnTo  - Element that receives focus when the trap deactivates.
+ */
+export declare function createFocusTrap(container: HTMLElement, returnTo?: HTMLElement): FocusTrapHandle;
+/** Announce a message to screen readers via the shared polite live region. */
+export declare function announce(message: string, delayMs?: number): void;
+/**
+ * Calls `callback` when a pointer-down event occurs outside all `elements`.
+ * Uses capture phase so stopPropagation inside the panel cannot suppress it.
+ * Returns a cleanup function.
+ */
+export declare function onClickOutside(elements: HTMLElement[], callback: (e: PointerEvent) => void): () => void;
+export declare abstract class OverlayControllerBase<TOptions extends BaseOverlayOptions, TSnapshot> implements AttachableController {
+	#private;
+	protected _options: TOptions;
+	/** Fallback id, generated once — NOT regenerated on every `id` read. */
+	protected readonly _generatedId: string;
+	protected _triggerEl: HTMLElement | null;
+	protected _panelEl: HTMLElement | null;
+	protected _focusTrap: ReturnType<typeof createFocusTrap> | null;
+	protected _clickOutsideStop: (() => void) | null;
+	protected _escStop: (() => void) | null;
+	constructor(options: TOptions, idPrefix: string);
+	get id(): string;
+	get triggerId(): string;
+	get contentId(): string;
+	get trapFocus(): boolean;
+	get closeOnOutsideClick(): boolean;
+	get closeOnEsc(): boolean;
+	get hooks(): OverlayHooks;
+	get onOpen(): (() => void) | undefined;
+	get onClose(): (() => void) | undefined;
+	abstract get isOpen(): boolean;
+	abstract open(): void;
+	abstract close(): void;
+	abstract getSnapshot(): TSnapshot;
+	/** Called from attachPanel() once the panel element is known. Each
+	 *  subclass decides what "the panel is available" means for its own
+	 *  open sequence (finish an in-progress open, or just recompute). */
+	protected abstract _onPanelAttached(el: HTMLElement): void;
+	toggle(): void;
+	attachTrigger(el: HTMLElement): void;
+	detachTrigger(): void;
+	attachPanel(el: HTMLElement): void;
+	detachPanel(): void;
+	subscribe(cb: (snap: TSnapshot) => void): () => void;
+	protected _emit(): void;
+	destroy(): void;
+	protected _setupSharedListeners(): void;
+	/** Extension point: PopoverController delays activation until its enter
+	 *  animation settles; DropdownController (no such animation) activates
+	 *  immediately. Overridden, not parameterized, since the two timings
+	 *  aren't expressible as a simple option without leaking animation
+	 *  details into the base class. */
+	protected _activateFocusTrap(): void;
+	protected _teardownSharedListeners(): void;
+}
+export declare class PopoverController extends OverlayControllerBase<ControllerOptions, PopoverSnapshot> implements IPopoverController {
+	#private;
+	constructor(options?: ControllerOptions);
+	get placement(): Placement;
+	get offset(): number;
+	get onStateChange(): ((s: PopoverState) => void) | undefined;
+	/** Derived from `state`, not a separately-tracked flag — there is exactly one
+	 *  state ('open') that means "open", so there's nothing to keep in sync. */
 	get isOpen(): boolean;
 	get state(): PopoverState;
 	get resolvedPlacement(): Placement;
 	get position(): ResolvedPosition | null;
 	get isVisible(): boolean;
 	getSnapshot(): PopoverSnapshot;
-	subscribe(cb: SubscriberFn): UnsubscribeFn;
-	attachTrigger(el: HTMLElement): void;
 	/**
-	 * Called by Popover.svelte's $effect after the panel element mounts.
+	 * Called by the base class's attachPanel() after the panel element mounts.
 	 * If state is 'opening', we're in the open sequence → finish it now.
 	 * If state is already 'open', controller was re-attached → just recompute.
 	 */
-	attachPanel(el: HTMLElement): void;
-	detachTrigger(): void;
-	detachPanel(): void;
+	protected _onPanelAttached(): void;
 	open(): void;
 	close(): void;
-	toggle(): void;
 	setPlacement(p: Placement): void;
 	destroy(): void;
+	protected _activateFocusTrap(): void;
 }
 export interface Props extends PopoverProps {
 	trigger?: Snippet<[
@@ -223,6 +322,26 @@ interface Props$4 {
 }
 export declare const PopoverArrow: import("svelte").Component<Props$4, {}, "">;
 export type PopoverArrow = ReturnType<typeof PopoverArrow>;
+export declare class DropdownController extends OverlayControllerBase<DropdownControllerOptions, DropdownSnapshot> implements IDropdownController {
+	#private;
+	constructor(options?: DropdownControllerOptions);
+	get isOpen(): boolean;
+	get onStateChange(): ((isOpen: boolean) => void) | undefined;
+	protected _onPanelAttached(): void;
+	open(): void;
+	close(): void;
+	getSnapshot(): DropdownSnapshot;
+}
+export interface ActionReturn<T> {
+	update?(next: T): void;
+	destroy?(): void;
+}
+/** Wires an element as a controller's trigger. Attaches on mount, detaches on
+ *  destroy, re-wires if the controller instance itself changes. */
+export declare const overlayTrigger: (node: HTMLElement, controller: AttachableController) => ActionReturn<AttachableController>;
+/** Wires an element as a controller's panel. Attaches on mount, detaches on
+ *  destroy, re-wires if the controller instance itself changes. */
+export declare const overlayPanel: (node: HTMLElement, controller: AttachableController) => ActionReturn<AttachableController>;
 /** Split "bottom-start" → { side: 'bottom', alignment: 'start' } */
 export declare function parsePlacement(p: Placement): {
 	side: Side;
@@ -246,22 +365,6 @@ export declare function getDirection(el: HTMLElement): "ltr" | "rtl";
  * @returns { x, y, placement } — coordinates and the actual placement used.
  */
 export declare function computePosition(triggerEl: HTMLElement, panelEl: HTMLElement, placement: Placement, offset: number, previousPlacement?: Placement | null): ResolvedPosition;
-/**
- * Keeps keyboard focus inside `container` while active.
- * Activation is deferred so it can be timed to the enter animation.
- *
- * @param container - The panel element to trap focus within.
- * @param returnTo  - Element that receives focus when the trap deactivates.
- */
-export declare function createFocusTrap(container: HTMLElement, returnTo?: HTMLElement): FocusTrapHandle;
-/** Announce a message to screen readers via the shared polite live region. */
-export declare function announce(message: string, delayMs?: number): void;
-/**
- * Calls `callback` when a pointer-down event occurs outside all `elements`.
- * Uses capture phase so stopPropagation inside the panel cannot suppress it.
- * Returns a cleanup function.
- */
-export declare function onClickOutside(elements: HTMLElement[], callback: (e: PointerEvent) => void): () => void;
 export declare const DEFAULT_OPTIONS: {
 	readonly placement: "bottom";
 	readonly offset: 8;

package/dist/index.js

@@ -1 +1 @@
-import{default as Q}from"./components/Popover.svelte";import{default as tt}from"./components/PopoverTrigger.svelte";import{default as ot}from"./components/PopoverContent.svelte";import{default as rt}from"./elements/PopoverPanel.svelte";import{default as st}from"./elements/PopoverArrow.svelte";import{PopoverController as ut}from"./controller.svelte.js";function b(t){if(t==="autoVertical")return{side:"bottom",alignment:null};let[n,o=null]=t.split("-");return{side:n,alignment:o}}function D(t,n,o,i,s,c,a){let r,e;switch(i){case"bottom":e=t.bottom+c;break;case"top":e=t.top-o-c;break;case"left":r=t.left-n-c;break;case"right":r=t.right+c;break}if(i==="top"||i==="bottom"){let u=a?t.right-n:t.left,d=a?t.left:t.right-n;s==="start"?r=u:s==="end"?r=d:r=t.left+(t.width-n)/2}else s==="start"?e=t.top:s==="end"?e=t.bottom-o:e=t.top+(t.height-o)/2;return{x:r,y:e}}function v(t){return getComputedStyle(t).direction==="rtl"?"rtl":"ltr"}function T(t,n,o,i=6){return Math.max(i,Math.min(o-n-i,t))}var I={top:"bottom",bottom:"top",left:"right",right:"left"};function F(t,n,o,i,s,c,a,r=0){switch(t){case"bottom":return n.bottom+s+o+r<=a;case"top":return n.top-s-o-r>=0;case"right":return n.right+s+i+r<=c;case"left":return n.left-s-i-r>=0}}var S=24;function k(t,n,o,i,s,c,a,r){let e=I[t],u=(d,p=0)=>F(d,n,o,i,s,c,a,p);return r===e?u(t,S)?t:u(e)?e:t:u(t)?t:u(e)?e:r??t}function C(t,n,o,i,s){let c=t.getBoundingClientRect(),a=n.offsetWidth,r=n.offsetHeight,e=window.innerWidth,u=window.innerHeight,d=v(t)==="rtl",{side:p,alignment:f}=b(o),L=s?b(s).side:null,m=k(p,c,r,a,i,e,u,L),O=o==="autoVertical"?m==="top"?"top":"bottom":m===p?o:f?`${m}-${f}`:m,{x:A,y:h}=D(c,a,r,m,f,i,d);return m==="top"||m==="bottom"?A=T(A,a,e):h=T(h,r,u),{x:A,y:h,placement:O}}var N={placement:"bottom",offset:8,trapFocus:!0,closeOnOutsideClick:!0,closeOnEsc:!0},P="scale",U="click",w=0,y=100,M=!1,B=200,x=["a[href]","button:not([disabled])","input:not([disabled])","select:not([disabled])","textarea:not([disabled])",'[tabindex]:not([tabindex="-1"])','[contenteditable="true"]',"details > summary"].join(", "),E="pop-live-region",_={borderRadius:"0.75rem",backdropBlur:"12px",shadowColor:"rgba(0,0,0,0.15)",lightBg:"oklch(var(--color-base-100))",darkBg:"oklch(var(--color-base-200))",lightBorder:"oklch(var(--color-base-300))",darkBorder:"oklch(var(--color-base-300))",lightText:"oklch(var(--color-base-content))",darkText:"oklch(var(--color-base-content))",accentColor:"oklch(var(--color-primary))"},G=0;function R(t="pop"){return`${t}-${++G}`}function K(t,n){let o=!1,i=document.activeElement;function s(){return Array.from(t.querySelectorAll(x)).filter(e=>!e.hasAttribute("disabled")&&e.offsetParent!==null)}function c(e){if(!o||e.key!=="Tab")return;let u=s();if(!u.length){e.preventDefault();return}let d=u[0],p=u[u.length-1],f=document.activeElement;e.shiftKey?(f===d||!t.contains(f))&&(e.preventDefault(),p.focus()):(f===p||!t.contains(f))&&(e.preventDefault(),d.focus())}function a(){if(o)return;o=!0,i=document.activeElement,document.addEventListener("keydown",c,!0);let e=s()[0]??t;requestAnimationFrame(()=>e.focus())}function r(){if(!o)return;o=!1,document.removeEventListener("keydown",c,!0);let e=n??i;e&&typeof e.focus=="function"&&requestAnimationFrame(()=>e.focus())}return{activate:a,deactivate:r,destroy:r}}var l=null;function g(){return l||(l=document.getElementById(E),l||(l=document.createElement("div"),l.id=E,l.setAttribute("aria-live","polite"),l.setAttribute("aria-atomic","true"),Object.assign(l.style,{position:"absolute",width:"1px",height:"1px",overflow:"hidden",clip:"rect(0 0 0 0)",whiteSpace:"nowrap",border:"0",padding:"0",margin:"-1px"}),document.body.appendChild(l)),l)}function H(t,n=80){let o=g();o.textContent="",setTimeout(()=>{o.textContent=t},n)}function V(t,n){function o(i){let s=i.target;t.some(c=>c.contains(s))||n(i)}return document.addEventListener("pointerdown",o,!0),()=>document.removeEventListener("pointerdown",o,!0)}function X(t={}){return{defaults:t.defaults??{},tokens:{..._,...t.theme}}}export{B as ANIMATION_DURATION_MS,P as DEFAULT_ANIMATION,y as DEFAULT_CLOSE_DELAY,w as DEFAULT_OPEN_DELAY,N as DEFAULT_OPTIONS,M as DEFAULT_SHOW_ARROW,_ as DEFAULT_THEME_TOKENS,U as DEFAULT_TRIGGER,x as FOCUSABLE_SELECTOR,E as LIVE_REGION_ID,Q as Popover,st as PopoverArrow,ot as PopoverContent,ut as PopoverController,rt as PopoverPanel,tt as PopoverTrigger,H as announce,C as computePosition,K as createFocusTrap,X as createPopoverPlugin,v as getDirection,V as onClickOutside,b as parsePlacement,R as uid};
+import{default as ot}from"./components/Popover.svelte";import{default as rt}from"./components/PopoverTrigger.svelte";import{default as st}from"./components/PopoverContent.svelte";import{default as ct}from"./elements/PopoverPanel.svelte";import{default as lt}from"./elements/PopoverArrow.svelte";import{PopoverController as ft}from"./controller.svelte.js";import{DropdownController as mt}from"./dropdown-controller.svelte.js";import{OverlayControllerBase as At}from"./overlay-controller-base.svelte.js";function b(t,e){return(o,r)=>(t(r,o),{update(i){i!==r&&(e(r),r=i,t(r,o))},destroy(){e(r)}})}var I=b((t,e)=>t.attachTrigger(e),t=>t.detachTrigger()),F=b((t,e)=>t.attachPanel(e),t=>t.detachPanel());function x(t){if(t==="autoVertical")return{side:"bottom",alignment:null};let[e,o=null]=t.split("-");return{side:e,alignment:o}}function S(t,e,o,r,i,a,u){let s,n;switch(r){case"bottom":n=t.bottom+a;break;case"top":n=t.top-o-a;break;case"left":s=t.left-e-a;break;case"right":s=t.right+a;break}if(r==="top"||r==="bottom"){let c=u?t.right-e:t.left,d=u?t.left:t.right-e;i==="start"?s=c:i==="end"?s=d:s=t.left+(t.width-e)/2}else i==="start"?n=t.top:i==="end"?n=t.bottom-o:n=t.top+(t.height-o)/2;return{x:s,y:n}}function O(t){return getComputedStyle(t).direction==="rtl"?"rtl":"ltr"}function _(t,e,o,r=6){return Math.max(r,Math.min(o-e-r,t))}var P={top:"bottom",bottom:"top",left:"right",right:"left"};function y(t,e,o,r,i,a,u,s=0){switch(t){case"bottom":return e.bottom+i+o+s<=u;case"top":return e.top-i-o-s>=0;case"right":return e.right+i+r+s<=a;case"left":return e.left-i-r-s>=0}}var C=24;function k(t,e,o,r,i,a,u,s){let n=P[t],c=(d,p=0)=>y(d,e,o,r,i,a,u,p);return s===n?c(t,C)?t:c(n)?n:t:c(t)?t:c(n)?n:s??t}function N(t,e,o,r,i){let a=t.getBoundingClientRect(),u=e.offsetWidth,s=e.offsetHeight,n=window.innerWidth,c=window.innerHeight,d=O(t)==="rtl",{side:p,alignment:f}=x(o),L=i?x(i).side:null,m=k(p,a,s,u,r,n,c,L),D=o==="autoVertical"?m==="top"?"top":"bottom":m===p?o:f?`${m}-${f}`:m,{x:A,y:h}=S(a,u,s,m,f,r,d);return m==="top"||m==="bottom"?A=_(A,u,n):h=_(h,s,c),{x:A,y:h,placement:D}}var w={placement:"bottom",offset:8,trapFocus:!0,closeOnOutsideClick:!0,closeOnEsc:!0},U="scale",g="click",B=0,M=100,G=!1,R=200,v=["a[href]","button:not([disabled])","input:not([disabled])","select:not([disabled])","textarea:not([disabled])",'[tabindex]:not([tabindex="-1"])','[contenteditable="true"]',"details > summary"].join(", "),E="pop-live-region",T={borderRadius:"0.75rem",backdropBlur:"12px",shadowColor:"rgba(0,0,0,0.15)",lightBg:"oklch(var(--color-base-100))",darkBg:"oklch(var(--color-base-200))",lightBorder:"oklch(var(--color-base-300))",darkBorder:"oklch(var(--color-base-300))",lightText:"oklch(var(--color-base-content))",darkText:"oklch(var(--color-base-content))",accentColor:"oklch(var(--color-primary))"},K=0;function H(t="pop"){return`${t}-${++K}`}function V(t,e){let o=!1,r=document.activeElement;function i(){return Array.from(t.querySelectorAll(v)).filter(n=>!n.hasAttribute("disabled")&&n.offsetParent!==null)}function a(n){if(!o||n.key!=="Tab")return;let c=i();if(!c.length){n.preventDefault();return}let d=c[0],p=c[c.length-1],f=document.activeElement;n.shiftKey?(f===d||!t.contains(f))&&(n.preventDefault(),p.focus()):(f===p||!t.contains(f))&&(n.preventDefault(),d.focus())}function u(){if(o)return;o=!0,r=document.activeElement,document.addEventListener("keydown",a,!0);let n=i()[0]??t;requestAnimationFrame(()=>n.focus())}function s(){if(!o)return;o=!1,document.removeEventListener("keydown",a,!0);let n=e??r;n&&typeof n.focus=="function"&&requestAnimationFrame(()=>n.focus())}return{activate:u,deactivate:s,destroy:s}}var l=null;function Y(){return l||(l=document.getElementById(E),l||(l=document.createElement("div"),l.id=E,l.setAttribute("aria-live","polite"),l.setAttribute("aria-atomic","true"),Object.assign(l.style,{position:"absolute",width:"1px",height:"1px",overflow:"hidden",clip:"rect(0 0 0 0)",whiteSpace:"nowrap",border:"0",padding:"0",margin:"-1px"}),document.body.appendChild(l)),l)}function q(t,e=80){let o=Y();o.textContent="",setTimeout(()=>{o.textContent=t},e)}function $(t,e){function o(r){let i=r.target;t.some(a=>a.contains(i))||e(r)}return document.addEventListener("pointerdown",o,!0),()=>document.removeEventListener("pointerdown",o,!0)}function Z(t={}){return{defaults:t.defaults??{},tokens:{...T,...t.theme}}}export{R as ANIMATION_DURATION_MS,U as DEFAULT_ANIMATION,M as DEFAULT_CLOSE_DELAY,B as DEFAULT_OPEN_DELAY,w as DEFAULT_OPTIONS,G as DEFAULT_SHOW_ARROW,T as DEFAULT_THEME_TOKENS,g as DEFAULT_TRIGGER,mt as DropdownController,v as FOCUSABLE_SELECTOR,E as LIVE_REGION_ID,At as OverlayControllerBase,ot as Popover,lt as PopoverArrow,st as PopoverContent,ft as PopoverController,ct as PopoverPanel,rt as PopoverTrigger,q as announce,N as computePosition,V as createFocusTrap,Z as createPopoverPlugin,O as getDirection,$ as onClickOutside,F as overlayPanel,I as overlayTrigger,x as parsePlacement,H as uid};

package/dist/overlay-controller-base.svelte.js

@@ -0,0 +1,176 @@
+// =============================================================================
+// Popover Micro-Plugin — OverlayControllerBase
+//
+// File MUST be *.svelte.ts — Svelte 5 compiles $state runes only in .svelte.ts.
+//
+// Shared logic between PopoverController and DropdownController, so the two
+// don't duplicate: id generation, options-as-getters, DOM ref storage,
+// subscribe/emit, and — the biggest chunk — click-outside + Escape + focus
+// trap wiring/teardown.
+//
+// What's NOT here, deliberately: `isOpen`, `open()`, `close()`, and
+// `getSnapshot()` are abstract. PopoverController's "open" is a multi-phase
+// sequence (needs panel dimensions, positions the panel, waits out an exit
+// animation before fully closing); DropdownController's is a single
+// synchronous boolean flip. Forcing both through one concrete open()/close()
+// would mean one of them fighting the other's assumptions. What genuinely IS
+// identical — the a11y wiring — lives here as `_setupSharedListeners()` /
+// `_teardownSharedListeners()`, which each subclass calls at the point in
+// its own open/close sequence where "the panel is now in the DOM and about
+// to be interactive" / "the panel is no longer interactive" respectively.
+//
+// Uses `protected` (not `#private`) fields for anything a subclass needs to
+// reach — JS `#private` fields are lexically scoped to the declaring class
+// and literally cannot be accessed from a subclass, even via `super`.
+// =============================================================================
+import { createFocusTrap, onClickOutside } from "./utils/a11y.js";
+import { uid, DEFAULT_OPTIONS } from "./constants.js";
+export class OverlayControllerBase {
+    // ─── Options — a plain object, deliberately NOT a rune ───────────────────────
+    //
+    // The controller doesn't own a reactivity model for its config — it just
+    // reads whatever `_options` currently holds through the getters below. If
+    // a caller wants a particular option to stay live (e.g. a Svelte
+    // component passing a reactive prop through), they pass a *getter* for
+    // it in the options object, backed by their own $state:
+    //
+    //   const myPlacement = $state('bottom');
+    //   new PopoverController({ get placement() { return myPlacement; } });
+    //
+    // Reading `this._options.placement` inside a tracked context (a template,
+    // a $derived) then invokes the caller's getter and correctly registers a
+    // dependency on THEIR $state — no rune needed on `_options` itself. This
+    // is the same reason `#pos`/`#resolvedPlacement`/`#state`/`#isOpen`
+    // staying real $state fields in the subclasses is what actually drives
+    // template reactivity for position/open-state; `_options` reassignment
+    // (e.g. setPlacement()) only needs to affect the NEXT read of a getter,
+    // not be tracked as a signal itself.
+    _options;
+    /** Fallback id, generated once — NOT regenerated on every `id` read. */
+    _generatedId;
+    // ─── DOM refs ─────────────────────────────────────────────────────────────────
+    _triggerEl = null;
+    _panelEl = null;
+    // ─── Lazy a11y resources (null while closed) ─────────────────────────────────
+    _focusTrap = null;
+    _clickOutsideStop = null;
+    _escStop = null;
+    // ─── Headless subscribers ───────────────────────────────────────────────────
+    #subscribers = new Set();
+    constructor(options, idPrefix) {
+        this._generatedId = uid(idPrefix);
+        this._options = options;
+    }
+    // ─── Shared option getters ────────────────────────────────────────────────────
+    get id() {
+        return this._options.id ?? this._generatedId;
+    }
+    get triggerId() {
+        return `${this.id}-trigger`;
+    }
+    get contentId() {
+        return `${this.id}-content`;
+    }
+    get trapFocus() {
+        return this._options.trapFocus ?? DEFAULT_OPTIONS.trapFocus;
+    }
+    get closeOnOutsideClick() {
+        return this._options.closeOnOutsideClick ?? DEFAULT_OPTIONS.closeOnOutsideClick;
+    }
+    get closeOnEsc() {
+        return this._options.closeOnEsc ?? DEFAULT_OPTIONS.closeOnEsc;
+    }
+    get hooks() {
+        return this._options.hooks ?? {};
+    }
+    get onOpen() {
+        return this._options.onOpen;
+    }
+    get onClose() {
+        return this._options.onClose;
+    }
+    toggle() {
+        this.isOpen ? this.close() : this.open();
+    }
+    // ─── Element wiring ───────────────────────────────────────────────────────────
+    attachTrigger(el) {
+        this._triggerEl = el;
+    }
+    detachTrigger() {
+        this._triggerEl = null;
+    }
+    attachPanel(el) {
+        this._panelEl = el;
+        this._onPanelAttached(el);
+    }
+    detachPanel() {
+        this._panelEl = null;
+    }
+    // ─── Subscriptions ────────────────────────────────────────────────────────────
+    subscribe(cb) {
+        this.#subscribers.add(cb);
+        cb(this.getSnapshot());
+        return () => this.#subscribers.delete(cb);
+    }
+    _emit() {
+        if (!this.#subscribers.size)
+            return;
+        const snap = this.getSnapshot();
+        this.#subscribers.forEach((cb) => cb(snap));
+    }
+    // ─── Destroy ──────────────────────────────────────────────────────────────────
+    destroy() {
+        this._teardownSharedListeners();
+        this.#subscribers.clear();
+        this._triggerEl = null;
+        this._panelEl = null;
+    }
+    // ─── Shared a11y wiring (click-outside / Escape / focus trap) ─────────────────
+    _setupSharedListeners() {
+        const trigger = this._triggerEl;
+        const panel = this._panelEl;
+        if (!panel)
+            return;
+        // Idempotent: if this is called a second time while already wired up
+        // (e.g. the panel element is re-attached while still open — a keyed
+        // #each remount, or a consumer calling attachPanel() again), tear
+        // down the previous listeners first. Without this, the old
+        // _clickOutsideStop/_escStop/_focusTrap references are silently
+        // overwritten and can never be cleaned up — a real listener leak.
+        this._teardownSharedListeners();
+        if (this.closeOnOutsideClick) {
+            const watch = trigger ? [trigger, panel] : [panel];
+            this._clickOutsideStop = onClickOutside(watch, () => this.close());
+        }
+        if (this.closeOnEsc) {
+            const handler = (e) => {
+                if (e.key === "Escape") {
+                    e.stopPropagation();
+                    this.close();
+                }
+            };
+            document.addEventListener("keydown", handler, true);
+            this._escStop = () => document.removeEventListener("keydown", handler, true);
+        }
+        if (this.trapFocus) {
+            this._focusTrap = createFocusTrap(panel, trigger ?? undefined);
+            this._activateFocusTrap();
+        }
+    }
+    /** Extension point: PopoverController delays activation until its enter
+     *  animation settles; DropdownController (no such animation) activates
+     *  immediately. Overridden, not parameterized, since the two timings
+     *  aren't expressible as a simple option without leaking animation
+     *  details into the base class. */
+    _activateFocusTrap() {
+        this._focusTrap?.activate();
+    }
+    _teardownSharedListeners() {
+        this._focusTrap?.deactivate();
+        this._clickOutsideStop?.();
+        this._escStop?.();
+        this._focusTrap = null;
+        this._clickOutsideStop = null;
+        this._escStop = null;
+    }
+}

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@popover-kit/svelte",
-  "version": "0.1.1",
-  "description": "",
+  "version": "0.1.2",
+  "description": "A primitive, headless-friendly popover and dropdown toolkit for Svelte 5 — positioning engine, accessibility (focus trap, click-outside, Escape), dark theme and RTL support.",
   "keywords": [
     "svelte",
     "svelte5",
     "popover",
+    "dropdown",
+    "overlay",
     "modal",
     "drawer",
     "daisyui",