@popover-kit/svelte 0.1.0 → 0.1.2

package/dist/controller.svelte.js

@@ -3,76 +3,79 @@
 //
 // 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):
 //
-//   1. open() sets state → 'opening' (isVisible = true) and returns.
-//   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().
-//   5. #finishOpen() reads panel dimensions (element is in DOM), computes
-//      position, sets up listeners, sets state → 'open'.
+// Two DOM-mounting strategies are supported, both converging on the same
+// #finishOpen():
+//
+//   A) Conditionally-mounted panel (Popover.svelte's default):
+//     1. open() sets state → 'opening' (isVisible = true) and returns —
+//        #panelEl isn't set yet, so it can't finish synchronously.
+//     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() → 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):
+//     1. open() sets state → 'opening', then immediately sees #panelEl is
+//        already set and calls #finishOpen() itself — there's no later
+//        attachPanel() call coming to do it.
+//
+//   #finishOpen() reads panel dimensions (element is in DOM), computes
+//   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/config.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;
@@ -89,108 +92,135 @@ 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();
         }
-        else if (this.isVisible) {
+        else if (this.#state === "open") {
             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(). Nothing else happens here.
-        this.#setState(false, "opening");
+        // → $effect fires → attachPanel() → #finishOpen().
+        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)
+            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.isVisible)
-            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;
-        const result = computePosition(this.#triggerEl, this.#panelEl, this.#placement, this.#offset);
+        // 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. 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;
     }
@@ -199,7 +229,14 @@ export class PopoverController {
             return;
         this.#rafId = requestAnimationFrame(() => {
             this.#rafId = null;
-            if (this.isVisible)
+            // Guaranteed 'open' in practice — the scroll/resize/ResizeObserver
+            // listeners that call this are only ever wired up in
+            // #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();
         });
     }
@@ -209,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 });
@@ -251,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

@@ -18,7 +18,8 @@
 	 * A border on two sides of the square, combined with the clip, produces a
 	 * bordered triangle that matches the card's border colour.
 	 */
-	import type { Placement } from '../types/types.js';
+	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

@@ -16,7 +16,8 @@
 	 * Pure CSS handles animations — no Svelte transitions needed.
 	 */
 	import type { Snippet } from 'svelte';
-	import type { Placement, ResolvedPosition, PopoverAnimation } from '../types/types.js';
+	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