@popover-kit/svelte 0.1.0 → 0.1.2

package/README.md

@@ -22,8 +22,9 @@ and **native RTL** support via Tailwind CSS v4 + daisyUI v5, and optional
 pnpm add @popover-kit/svelte
 ```
 
-Peer dependency: `svelte@^5`. Ships with `lucide-svelte` as a regular
-dependency (used for the built-in close icon).
+Peer dependency: `svelte@^5`. No icon library dependency — the built-in
+close button renders a plain "✕" character. Pass your own `iconSnippet`
+prop to `<PopoverContent>` (e.g. a `lucide-svelte` icon) to override it.
 
 ## Quick start
 
@@ -46,6 +47,13 @@ dependency (used for the built-in close icon).
 </Popover>
 ```
 
+See `demos/PageDemo.svelte` for 12 runnable scenarios (placements,
+alignments, `autoVertical`, hover/focus triggers, controlled mode, a
+shared/injected controller, a fully headless example, and three
+booking/e-commerce-flavored patterns: a Kayak-style search bar, a checkout
+confirmation, and a product-discovery tooltip). Run it in a browser via
+`examples/svelte` (see its README).
+
 ## Dark theme & RTL
 
 - **Dark theme**: the panel uses daisyUI's `card bg-base-100` tokens, so it
@@ -70,6 +78,56 @@ ctrl.open();
 `PopoverController` is pure TypeScript (a `.svelte.ts` module using runes
 for its reactive state) — no component required.
 
+## `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:
+
+```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
 

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,29 +4,33 @@
 	 *
 	 * 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
 	 *   {#snippet content(ctx: ContentSnippetCtx)}  — render the panel body
 	 *   {#snippet children(ctrl: IPopoverController)} — shorthand: default <button>
 	 */
-	import { onDestroy, type Snippet } from 'svelte';
+	import { onDestroy, untrack, type Snippet } from 'svelte';
 	import type {
 		PopoverProps,
 		IPopoverController,
 		TriggerSnippetCtx,
 		ContentSnippetCtx
-	} from '../types/types.js';
+	} from '../types.js';
 
-	import { PopoverController } from '../controller.svelte';
+	import { PopoverController } from '../controller.svelte.js';
+	import { overlayTrigger } from '../actions.js';
 	import PopoverPanel from '../elements/PopoverPanel.svelte';
 	import {
 		DEFAULT_OPTIONS,
@@ -35,7 +39,7 @@
 		DEFAULT_OPEN_DELAY,
 		DEFAULT_CLOSE_DELAY,
 		DEFAULT_SHOW_ARROW
-	} from '../constants/config.js';
+	} from '../constants.js';
 
 	// ── Props ────────────────────────────────────────────────────────────────────
 
@@ -53,6 +57,7 @@
 		trapFocus = DEFAULT_OPTIONS.trapFocus,
 		closeOnOutsideClick = DEFAULT_OPTIONS.closeOnOutsideClick,
 		closeOnEsc = DEFAULT_OPTIONS.closeOnEsc,
+		hooks,
 		onOpen,
 		onClose,
 		onStateChange,
@@ -72,43 +77,41 @@
 	// ── Controller ────────────────────────────────────────────────────────────────
 	// owned = we created it → destroy on unmount.
 	// injected = caller's lifecycle → only wire refs, never destroy.
+	//
+	// Deliberately constructed ONCE from the props' initial values — `id`,
+	// `placement`, etc. configure the controller at creation time only; later
+	// prop changes are intentionally not reactive here; `open` is the one
+	// exception, handled by its own $effect below. `untrack` tells the
+	// compiler this one-time read is intentional (not a missed dependency).
 
 	let owned = false;
-	let ctrl: PopoverController;
-
-	if (injectedCtrl instanceof PopoverController) {
-		ctrl = injectedCtrl;
-	} else {
+	const ctrl: PopoverController = untrack(() => {
+		if (injectedCtrl instanceof PopoverController) {
+			return injectedCtrl;
+		}
 		owned = true;
-		ctrl = new PopoverController({
+		return new PopoverController({
 			id,
 			placement,
 			offset,
 			trapFocus,
 			closeOnOutsideClick,
 			closeOnEsc,
+			hooks,
 			onOpen,
 			onClose,
 			onStateChange
 		});
-	}
+	});
 
 	// ── 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();
@@ -205,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/components/PopoverContent.svelte

@@ -18,8 +18,7 @@
 	 * {/snippet}
 	 */
 	import type { Snippet } from 'svelte';
-	import { X } from 'lucide-svelte';
-	import type { ContentSnippetCtx } from '../types/types.js';
+	import type { ContentSnippetCtx } from '../types.js';
 
 	interface Props {
 		ctx: ContentSnippetCtx;
@@ -31,6 +30,14 @@
 		body?: Snippet<[ContentSnippetCtx]>;
 		/** Fallback when no body snippet is provided. */
 		children?: Snippet<[ContentSnippetCtx]>;
+		/**
+		 * Overrides the default close-button glyph (a plain "X" character —
+		 * no icon library dependency shipped by this package). Pass e.g. a
+		 * `lucide-svelte` icon snippet from your own app to swap it in:
+		 *
+		 * {#snippet iconSnippet()}<X class="h-3 w-3" />{/snippet}
+		 */
+		iconSnippet?: Snippet;
 	}
 
 	const {
@@ -40,7 +47,8 @@
 		showClose = false,
 		class: cls = '',
 		body,
-		children
+		children,
+		iconSnippet
 	}: Props = $props();
 </script>
 
@@ -57,7 +65,11 @@
 					aria-label="Close"
 					onclick={() => ctx.ctrl.close()}
 				>
-					<X class="h-3 w-3" aria-hidden="true" />
+					{#if iconSnippet}
+						{@render iconSnippet()}
+					{:else}
+						<span class="text-xs leading-none" aria-hidden="true">✕</span>
+					{/if}
 				</button>
 			{/if}
 		</div>

package/dist/components/PopoverTrigger.svelte

@@ -12,7 +12,7 @@
 	 * {/snippet}
 	 */
 	import type { Snippet } from 'svelte';
-	import type { TriggerSnippetCtx } from '../types/types.js';
+	import type { TriggerSnippetCtx } from '../types.js';
 
 	interface Props {
 		ctx: TriggerSnippetCtx;