@popover-kit/svelte 0.1.0

package/dist/controller.svelte.js

@@ -0,0 +1,286 @@
+// =============================================================================
+// Popover Micro-Plugin — PopoverController
+//
+// File MUST be *.svelte.ts — Svelte 5 compiles $state runes only in .svelte.ts.
+//
+// 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'.
+//
+// This ordering guarantees:
+//   • #panelEl is always non-null when #setupListeners() runs.
+//   • Click-outside uses the real panel element (not null).
+//   • No rAF/setTimeout hacks needed.
+// =============================================================================
+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);
+    #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;
+    #scrollResizeStop = null;
+    #escStop = null;
+    #resizeObs = null;
+    // ─── Headless subscribers ─────────────────────────────────────────────────────
+    #subscribers = new Set();
+    // ─── 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;
+    }
+    // ─── Reactive getters ─────────────────────────────────────────────────────────
+    get isOpen() {
+        return this.#isOpen;
+    }
+    get state() {
+        return this.#state;
+    }
+    get resolvedPlacement() {
+        return this.#resolvedPlacement;
+    }
+    get position() {
+        return this.#pos;
+    }
+    get isVisible() {
+        return this.#state !== "closed";
+    }
+    // ─── Snapshot ─────────────────────────────────────────────────────────────────
+    getSnapshot() {
+        return {
+            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;
+    }
+    /**
+     * Called by Popover.svelte's $effect 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;
+        if (this.#state === "opening") {
+            this.#finishOpen();
+        }
+        else if (this.isVisible) {
+            this.#compute();
+        }
+    }
+    detachTrigger() {
+        this.#triggerEl = null;
+    }
+    detachPanel() {
+        this.#panelEl = null;
+    }
+    // ─── Core actions ─────────────────────────────────────────────────────────────
+    open() {
+        if (this.#isOpen || this.#state === "opening")
+            return;
+        this.#cancelClose();
+        // Set 'opening' FIRST → isVisible becomes true → Svelte mounts the panel
+        // → $effect fires → attachPanel() → #finishOpen(). Nothing else happens here.
+        this.#setState(false, "opening");
+    }
+    close() {
+        if (!this.#isOpen || this.#state === "closing")
+            return;
+        this.#cancelFocusTrapTimer();
+        this.#setState(false, "closing");
+        this.#teardownListeners();
+        this.#closeTimer = setTimeout(() => {
+            if (this.#state === "closing") {
+                this.#setState(false, "closed");
+                this.#pos = null;
+                announce("Popover closed");
+                this.#onClose?.();
+            }
+        }, ANIMATION_DURATION_MS);
+    }
+    toggle() {
+        this.#isOpen ? this.close() : this.open();
+    }
+    setPlacement(p) {
+        this.#placement = p;
+        if (this.isVisible)
+            this.#compute();
+    }
+    // ─── Destroy ──────────────────────────────────────────────────────────────────
+    destroy() {
+        this.#cancelFocusTrapTimer();
+        this.#cancelClose();
+        this.#cancelRaf();
+        this.#teardownListeners();
+        this.#subscribers.clear();
+        this.#triggerEl = null;
+        this.#panelEl = null;
+    }
+    // ─── Private: open sequence ───────────────────────────────────────────────────
+    /**
+     * Called from attachPanel() 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");
+        announce("Popover opened");
+        this.#onOpen?.();
+    }
+    // ─── Private: positioning ─────────────────────────────────────────────────────
+    #compute() {
+        if (!this.#triggerEl || !this.#panelEl)
+            return;
+        const result = computePosition(this.#triggerEl, this.#panelEl, this.#placement, this.#offset);
+        this.#pos = result;
+        this.#resolvedPlacement = result.placement;
+    }
+    #scheduleCompute() {
+        if (this.#rafId !== null)
+            return;
+        this.#rafId = requestAnimationFrame(() => {
+            this.#rafId = null;
+            if (this.isVisible)
+                this.#compute();
+        });
+    }
+    #cancelRaf() {
+        if (this.#rafId !== null) {
+            cancelAnimationFrame(this.#rafId);
+            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);
+        }
+        // Scroll + resize → rAF-coalesced recompute (max one per frame)
+        const recompute = () => this.#scheduleCompute();
+        window.addEventListener("scroll", recompute, { passive: true, capture: true });
+        window.addEventListener("resize", recompute, { passive: true });
+        this.#scrollResizeStop = () => {
+            window.removeEventListener("scroll", recompute, { capture: true });
+            window.removeEventListener("resize", recompute);
+        };
+        // ResizeObserver: trigger or panel dimensions changing also needs a recompute
+        if (trigger) {
+            this.#resizeObs = new ResizeObserver(recompute);
+            this.#resizeObs.observe(trigger);
+            if (panel)
+                this.#resizeObs.observe(panel);
+        }
+    }
+    #teardownListeners() {
+        this.#focusTrap?.deactivate();
+        this.#clickOutsideStop?.();
+        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;
+        this.#state = state;
+        this.#onStateChange?.(state);
+        this.#emit();
+    }
+    #cancelFocusTrapTimer() {
+        if (this.#focusTrapTimer !== null) {
+            clearTimeout(this.#focusTrapTimer);
+            this.#focusTrapTimer = null;
+        }
+    }
+    #cancelClose() {
+        if (this.#closeTimer !== null) {
+            clearTimeout(this.#closeTimer);
+            this.#closeTimer = null;
+        }
+    }
+}

package/dist/elements/PopoverArrow.svelte

@@ -0,0 +1,95 @@
+<script lang="ts">
+	/**
+	 * PopoverArrow — decorative caret pointing from the panel toward the trigger.
+	 *
+	 * Uses a single rotated square clipped to a triangle via CSS clip-path.
+	 * The square is large enough (12×12px) that the rotated tip clearly protrudes
+	 * beyond the panel edge when the wrapper is placed at the correct offset.
+	 *
+	 *   Panel side   Panel edge   Arrow points
+	 *   ──────────   ──────────   ────────────
+	 *   bottom       top          up   ▲
+	 *   top          bottom       down ▼
+	 *   right        left         left ◄
+	 *   left         right        right ►
+	 *
+	 * The wrapper is 12×12px positioned so its center sits on the panel edge.
+	 * clip-path cuts the square into the half that protrudes outward.
+	 * 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';
+
+	interface Props {
+		placement: Placement;
+		class?: string;
+	}
+
+	const { placement, class: cls = '' }: Props = $props();
+
+	const side = $derived(
+		placement === 'autoVertical'
+			? 'bottom'
+			: (placement.split('-')[0] as 'top' | 'bottom' | 'left' | 'right')
+	);
+</script>
+
+<span class="pop-arrow pop-arrow--{side} {cls}" aria-hidden="true"></span>
+
+<style>
+	/*
+   * Single element arrow — no pseudo-element needed.
+   * The element itself is rotated 45° to create a diamond, then clip-path
+   * cuts it to a triangle. The border is applied before rotation so the
+   * visible edges match the panel's card border.
+   *
+   * Size: 12px × 12px. Rotated 45° → diagonal = 17px.
+   * The half that protrudes = ~8.5px, which is enough to be visible.
+   */
+	.pop-arrow {
+		position: absolute;
+		display: block;
+		width: 12px;
+		height: 12px;
+		background: oklch(var(--color-base-100));
+		border: 1px solid oklch(var(--color-base-300));
+		pointer-events: none;
+		z-index: 1;
+	}
+
+	/* ── Panel below trigger → arrow at top of panel, pointing up ──────────── */
+	.pop-arrow--bottom {
+		top: -7px; /* (12px / 2) + 1px for border overlap */
+		left: 1.25rem;
+		transform: rotate(45deg);
+		/* Keep only the top-left triangle (the outward-pointing half) */
+		clip-path: polygon(0% 0%, 100% 0%, 0% 100%);
+	}
+
+	/* ── Panel above trigger → arrow at bottom of panel, pointing down ─────── */
+	.pop-arrow--top {
+		bottom: -7px;
+		left: 1.25rem;
+		transform: rotate(45deg);
+		/* Keep only the bottom-right triangle */
+		clip-path: polygon(100% 0%, 100% 100%, 0% 100%);
+	}
+
+	/* ── Panel to the right of trigger → arrow at left of panel, pointing left */
+	.pop-arrow--right {
+		left: -7px;
+		top: 1.25rem;
+		transform: rotate(45deg);
+		/* Keep only the left triangle */
+		clip-path: polygon(0% 0%, 0% 100%, 100% 100%);
+	}
+
+	/* ── Panel to the left of trigger → arrow at right of panel, pointing right */
+	.pop-arrow--left {
+		right: -7px;
+		top: 1.25rem;
+		transform: rotate(45deg);
+		/* Keep only the right triangle */
+		clip-path: polygon(0% 0%, 100% 0%, 100% 100%);
+	}
+</style>

package/dist/elements/PopoverPanel.svelte

@@ -0,0 +1,188 @@
+<script lang="ts">
+	/**
+	 * PopoverPanel — atomic floating panel element.
+	 *
+	 * Uses `position:fixed` with coordinates from the controller.
+	 * Parked off-screen when coordinates are not yet computed (position=null)
+	 * so the controller can measure its dimensions via getBoundingClientRect().
+	 *
+	 * Animation direction CSS classes (pop-side-*) are derived from resolvedPlacement
+	 * so the scale/slide transform-origin and direction are always correct.
+	 *
+	 * The `el` prop is `$bindable` — Popover.svelte passes panelEl through it
+	 * so the controller's $effect can call attachPanel() once the element mounts.
+	 *
+	 * daisyUI `card` provides the surface (bg, border, radius, shadow).
+	 * Pure CSS handles animations — no Svelte transitions needed.
+	 */
+	import type { Snippet } from 'svelte';
+	import type { Placement, ResolvedPosition, PopoverAnimation } from '../types/types.js';
+	import PopoverArrow from './PopoverArrow.svelte';
+
+	interface Props {
+		id: string;
+		triggerId: string;
+		isOpen: boolean;
+		position: ResolvedPosition | null;
+		resolvedPlacement: Placement;
+		showArrow: boolean;
+		animation: PopoverAnimation;
+		role?: 'dialog' | 'listbox' | 'tooltip' | 'menu' | 'tree' | 'grid';
+		class?: string;
+		'aria-label'?: string;
+		/** $bindable — Popover.svelte reads this for the controller's attachPanel(). */
+		el?: HTMLElement | null;
+		children?: Snippet;
+	}
+
+	let {
+		id,
+		triggerId,
+		isOpen,
+		position,
+		resolvedPlacement,
+		showArrow,
+		animation,
+		role = 'dialog',
+		class: cls = '',
+		'aria-label': ariaLabel,
+		el = $bindable(null),
+		children
+	}: Props = $props();
+
+	/**
+	 * position:fixed inline style.
+	 * null → parked at -9999px so dimensions are measurable without visual flash.
+	 * set  → placed at computed coordinates.
+	 */
+	const panelStyle = $derived(
+		position
+			? `position:fixed;left:${position.x}px;top:${position.y}px;z-index:9000;`
+			: `position:fixed;top:-9999px;left:-9999px;visibility:hidden;pointer-events:none;z-index:9000;`
+	);
+
+	/**
+	 * Primary side — drives animation transform-origin and direction.
+	 * autoVertical resolves to 'bottom' until the controller flips it.
+	 */
+	const side = $derived(
+		resolvedPlacement === 'autoVertical' ? 'bottom' : (resolvedPlacement.split('-')[0] as string)
+	);
+</script>
+
+<div
+	bind:this={el}
+	{id}
+	class="pop-panel card card-border bg-base-100 shadow-xl pop-side-{side} pop-anim-{animation} {cls}"
+	class:pop-panel--open={isOpen}
+	{role}
+	aria-modal={role === 'dialog' ? 'true' : undefined}
+	aria-labelledby={ariaLabel ? undefined : triggerId}
+	aria-label={ariaLabel}
+	tabindex="-1"
+	style={panelStyle}
+>
+	{#if showArrow}
+		<PopoverArrow placement={resolvedPlacement} />
+	{/if}
+
+	<div class="card-body relative z-10 p-0">
+		{@render children?.()}
+	</div>
+</div>
+
+<style>
+	/* ── Base: hidden until open ─────────────────────────────────────────────── */
+	.pop-panel {
+		position: fixed;
+		z-index: 9000;
+		min-width: 12rem;
+		max-width: min(22.5rem, calc(100vw - 1rem));
+		outline: none;
+		opacity: 0;
+		visibility: hidden;
+		pointer-events: none;
+		transition:
+			opacity 200ms ease,
+			transform 200ms cubic-bezier(0.34, 1.56, 0.64, 1),
+			visibility 0s linear 200ms;
+	}
+
+	/* ── Open ────────────────────────────────────────────────────────────────── */
+	.pop-panel--open {
+		opacity: 1;
+		visibility: visible;
+		pointer-events: auto;
+		transition:
+			opacity 200ms ease,
+			transform 200ms cubic-bezier(0.34, 1.56, 0.64, 1),
+			visibility 0s linear 0s;
+	}
+
+	/* ── Scale: transform-origin matches which side the trigger is on ─────────── */
+	.pop-anim-scale.pop-side-bottom {
+		transform-origin: top center;
+	}
+	.pop-anim-scale.pop-side-top {
+		transform-origin: bottom center;
+	}
+	.pop-anim-scale.pop-side-left {
+		transform-origin: right center;
+	}
+	.pop-anim-scale.pop-side-right {
+		transform-origin: left center;
+	}
+	.pop-anim-scale:not(.pop-panel--open) {
+		transform: scale(0.92);
+	}
+	.pop-anim-scale.pop-panel--open {
+		transform: scale(1);
+	}
+
+	/* ── Slide ────────────────────────────────────────────────────────────────── */
+	.pop-anim-slide.pop-side-bottom:not(.pop-panel--open) {
+		transform: translateY(-6px);
+	}
+	.pop-anim-slide.pop-side-top:not(.pop-panel--open) {
+		transform: translateY(6px);
+	}
+	.pop-anim-slide.pop-side-left:not(.pop-panel--open) {
+		transform: translateX(6px);
+	}
+	.pop-anim-slide.pop-side-right:not(.pop-panel--open) {
+		transform: translateX(-6px);
+	}
+	.pop-anim-slide.pop-panel--open {
+		transform: none;
+	}
+
+	/* ── Fade: opacity only ───────────────────────────────────────────────────── */
+	.pop-anim-fade:not(.pop-panel--open) {
+		transform: none;
+	}
+
+	/* ── None ─────────────────────────────────────────────────────────────────── */
+	.pop-anim-none {
+		transition:
+			opacity 0s,
+			transform 0s,
+			visibility 0s;
+	}
+
+	/* ── Reduced motion ───────────────────────────────────────────────────────── */
+	@media (prefers-reduced-motion: reduce) {
+		.pop-panel {
+			transition:
+				opacity 0s,
+				transform 0s,
+				visibility 0s;
+		}
+	}
+
+	/* ── Mobile ───────────────────────────────────────────────────────────────── */
+	@media (max-width: 480px) {
+		.pop-panel {
+			max-width: calc(100vw - 1.25rem);
+		}
+	}
+</style>