@popover-kit/svelte 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 popover-kit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# @popover-kit/svelte
+
+A primitive, headless-friendly popover/tooltip/menu building block for
+**Svelte 5** (runes), with SSR-safe internals, first-class **dark theme**
+and **native RTL** support via Tailwind CSS v4 + daisyUI v5, and optional
+[Lucide](https://lucide.dev) icons.
+
+- **Pluggable** — use the batteries-included `<Popover>` component, or go
+  fully headless and wire `PopoverController` to your own markup.
+- **Configurable** — placement (12 positions + `autoVertical`), offset,
+  animation, trigger interaction (click/hover/focus/manual), focus trap,
+  click-outside, Esc-to-close — all optional props with sane defaults.
+- **Overridable** — every visual surface is a plain `.svelte` component
+  shipped as source, styled with daisyUI's `card`/`btn` primitives and a
+  handful of scoped CSS classes (`pop-*`) you can target or replace.
+- **Zero-cost at rest** — no listeners, observers, or focus traps are
+  created until the popover actually opens.
+
+## Install
+
+```bash
+pnpm add @popover-kit/svelte
+```
+
+Peer dependency: `svelte@^5`. Ships with `lucide-svelte` as a regular
+dependency (used for the built-in close icon).
+
+## Quick start
+
+```svelte
+<script lang="ts">
+	import { Popover, PopoverTrigger, PopoverContent } from '@popover-kit/svelte';
+</script>
+
+<Popover placement="bottom-start" showArrow>
+	{#snippet trigger(ctx)}
+		<PopoverTrigger {ctx} class="btn-primary">Open</PopoverTrigger>
+	{/snippet}
+	{#snippet content(ctx)}
+		<PopoverContent {ctx} title="Hello 👋" showClose>
+			{#snippet body(ctx)}
+				<p class="text-sm">Placement: {ctx.resolvedPlacement}</p>
+			{/snippet}
+		</PopoverContent>
+	{/snippet}
+</Popover>
+```
+
+## Dark theme & RTL
+
+- **Dark theme**: the panel uses daisyUI's `card bg-base-100` tokens, so it
+  follows whatever `data-theme` you set on an ancestor — no extra config.
+- **RTL**: set `dir="rtl"` on any ancestor (or the trigger's own element).
+  Logical alignments (`*-start` / `*-end`) automatically resolve to the
+  correct physical side based on computed writing direction; `left`/`right`
+  placements stay physical, matching how most positioning libraries (and
+  CSS itself) draw the distinction.
+
+## Headless usage
+
+```ts
+import { PopoverController } from '@popover-kit/svelte';
+
+const ctrl = new PopoverController({ placement: 'bottom' });
+ctrl.attachTrigger(triggerEl);
+ctrl.attachPanel(panelEl);
+ctrl.open();
+```
+
+`PopoverController` is pure TypeScript (a `.svelte.ts` module using runes
+for its reactive state) — no component required.
+
+
+## License
+
+MIT

package/dist/components/Popover.svelte

@@ -0,0 +1,285 @@
+<script lang="ts">
+	/**
+	 * Popover — lightweight composition component.
+	 *
+	 * Architecture:
+	 *   • Creates or accepts an injected PopoverController.
+	 *   • Wires trigger and panel DOM refs via $effect (required — bind:this is async).
+	 *   • 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.
+	 *
+	 * 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 type {
+		PopoverProps,
+		IPopoverController,
+		TriggerSnippetCtx,
+		ContentSnippetCtx
+	} from '../types/types.js';
+
+	import { PopoverController } from '../controller.svelte';
+	import PopoverPanel from '../elements/PopoverPanel.svelte';
+	import {
+		DEFAULT_OPTIONS,
+		DEFAULT_ANIMATION,
+		DEFAULT_TRIGGER,
+		DEFAULT_OPEN_DELAY,
+		DEFAULT_CLOSE_DELAY,
+		DEFAULT_SHOW_ARROW
+	} from '../constants/config.js';
+
+	// ── Props ────────────────────────────────────────────────────────────────────
+
+	interface Props extends PopoverProps {
+		trigger?: Snippet<[TriggerSnippetCtx]>;
+		content?: Snippet<[ContentSnippetCtx]>;
+		children?: Snippet<[IPopoverController]>;
+	}
+
+	let {
+		controller: injectedCtrl,
+		id,
+		placement = DEFAULT_OPTIONS.placement,
+		offset = DEFAULT_OPTIONS.offset,
+		trapFocus = DEFAULT_OPTIONS.trapFocus,
+		closeOnOutsideClick = DEFAULT_OPTIONS.closeOnOutsideClick,
+		closeOnEsc = DEFAULT_OPTIONS.closeOnEsc,
+		onOpen,
+		onClose,
+		onStateChange,
+		animation = DEFAULT_ANIMATION,
+		showArrow = DEFAULT_SHOW_ARROW,
+		class: cls = '',
+		'aria-label': ariaLabel,
+		triggerInteraction = DEFAULT_TRIGGER,
+		openDelay = DEFAULT_OPEN_DELAY,
+		closeDelay = DEFAULT_CLOSE_DELAY,
+		open: controlledOpen,
+		trigger: triggerSnippet,
+		content: contentSnippet,
+		children
+	}: Props = $props();
+
+	// ── Controller ────────────────────────────────────────────────────────────────
+	// owned = we created it → destroy on unmount.
+	// injected = caller's lifecycle → only wire refs, never destroy.
+
+	let owned = false;
+	let ctrl: PopoverController;
+
+	if (injectedCtrl instanceof PopoverController) {
+		ctrl = injectedCtrl;
+	} else {
+		owned = true;
+		ctrl = new PopoverController({
+			id,
+			placement,
+			offset,
+			trapFocus,
+			closeOnOutsideClick,
+			closeOnEsc,
+			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.
+
+	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();
+	});
+
+	// ── Controlled mode ───────────────────────────────────────────────────────────
+	// Genuinely needs $effect — reacts to an external boolean prop changing over time.
+
+	$effect(() => {
+		if (controlledOpen === undefined) return;
+		if (controlledOpen && !ctrl.isOpen) ctrl.open();
+		else if (!controlledOpen && ctrl.isOpen) ctrl.close();
+	});
+
+	// ── Hover / focus delay timers ────────────────────────────────────────────────
+
+	let openTimer: ReturnType<typeof setTimeout> | null = null;
+	let closeTimer: ReturnType<typeof setTimeout> | null = null;
+
+	function scheduleOpen(): void {
+		if (closeTimer) {
+			clearTimeout(closeTimer);
+			closeTimer = null;
+		}
+		if (ctrl.isOpen) return;
+		if (openDelay > 0) openTimer = setTimeout(() => ctrl.open(), openDelay);
+		else ctrl.open();
+	}
+
+	function scheduleClose(): void {
+		if (openTimer) {
+			clearTimeout(openTimer);
+			openTimer = null;
+		}
+		if (!ctrl.isOpen) return;
+		if (closeDelay > 0) closeTimer = setTimeout(() => ctrl.close(), closeDelay);
+		else ctrl.close();
+	}
+
+	// ── Interaction handlers ──────────────────────────────────────────────────────
+
+	function handleClick(): void {
+		if (triggerInteraction === 'click' || triggerInteraction === 'manual') ctrl.toggle();
+	}
+
+	function handleKeydown(e: KeyboardEvent): void {
+		if (e.key === 'Enter' || e.key === ' ') {
+			e.preventDefault();
+			ctrl.toggle();
+		}
+	}
+
+	function handleMouseEnter(): void {
+		if (triggerInteraction === 'hover') scheduleOpen();
+	}
+	function handleMouseLeave(): void {
+		if (triggerInteraction === 'hover') scheduleClose();
+	}
+
+	function handleFocus(): void {
+		if (triggerInteraction === 'focus' || triggerInteraction === 'hover') scheduleOpen();
+	}
+	function handleBlur(): void {
+		if (triggerInteraction === 'focus' || triggerInteraction === 'hover') scheduleClose();
+	}
+
+	// ── Lifecycle ─────────────────────────────────────────────────────────────────
+
+	onDestroy(() => {
+		if (openTimer) clearTimeout(openTimer);
+		if (closeTimer) clearTimeout(closeTimer);
+		if (owned) ctrl.destroy();
+		else {
+			ctrl.detachTrigger();
+			ctrl.detachPanel();
+		}
+	});
+
+	// ── Public API (bind:this on <Popover>) ───────────────────────────────────────
+
+	export function open(): void {
+		ctrl.open();
+	}
+	export function close(): void {
+		ctrl.close();
+	}
+	export function toggle(): void {
+		ctrl.toggle();
+	}
+	export function getController(): PopoverController {
+		return ctrl;
+	}
+</script>
+
+<!--
+  Root wrapper: inline-block keeps it tight around the trigger so that
+  getBoundingClientRect() on triggerWrapEl 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}>
+	<!-- ── Trigger ─────────────────────────────────────────────────────────── -->
+	{#if triggerSnippet}
+		{@render triggerSnippet({
+			id: ctrl.triggerId,
+			controls: ctrl.contentId,
+			expanded: ctrl.isOpen,
+			onclick: handleClick,
+			onkeydown: handleKeydown,
+			onmouseenter: handleMouseEnter,
+			onmouseleave: handleMouseLeave,
+			onfocus: handleFocus,
+			onblur: handleBlur,
+			ctrl
+		})}
+	{:else}
+		<button
+			id={ctrl.triggerId}
+			type="button"
+			class="btn"
+			aria-haspopup="dialog"
+			aria-expanded={ctrl.isOpen}
+			aria-controls={ctrl.contentId}
+			onclick={handleClick}
+			onkeydown={handleKeydown}
+			onmouseenter={handleMouseEnter}
+			onmouseleave={handleMouseLeave}
+			onfocus={handleFocus}
+			onblur={handleBlur}
+		>
+			{@render children?.(ctrl)}
+		</button>
+	{/if}
+
+	<!-- ── Panel ───────────────────────────────────────────────────────────── -->
+	<!--
+    Mounted only while ctrl.isVisible (open OR exit-animating).
+    When it mounts, the $effect above fires → ctrl.attachPanel(panelEl)
+    → controller detects state==='opening' → runs #finishOpen().
+    Click-outside: pointerdown fires on the clicked element BEFORE this close()
+    runs, so background elements remain fully interactive.
+  -->
+	{#if ctrl.isVisible}
+		<PopoverPanel
+			id={ctrl.contentId}
+			triggerId={ctrl.triggerId}
+			isOpen={ctrl.isOpen}
+			position={ctrl.position}
+			resolvedPlacement={ctrl.resolvedPlacement}
+			{showArrow}
+			{animation}
+			class={cls}
+			aria-label={ariaLabel}
+			bind:el={panelEl}
+		>
+			{#snippet children()}
+				{#if contentSnippet}
+					{@render contentSnippet({
+						ctrl,
+						resolvedPlacement: ctrl.resolvedPlacement,
+						state: ctrl.state
+					})}
+				{/if}
+			{/snippet}
+		</PopoverPanel>
+	{/if}
+</span>
+
+<style>
+	.pop-root {
+		display: inline-block;
+	}
+</style>

package/dist/components/PopoverContent.svelte

@@ -0,0 +1,75 @@
+<script lang="ts">
+	/**
+	 * PopoverContent — padded panel body wrapper.
+	 *
+	 * Provides optional title, description, and close button chrome.
+	 * All snippets receive `ContentSnippetCtx` so nested components can reach
+	 * the controller without additional prop drilling.
+	 *
+	 * Styling: daisyUI card-title, card-body, btn-ghost; Tailwind for spacing.
+	 *
+	 * @example
+	 * {#snippet content(ctx)}
+	 *   <PopoverContent {ctx} title="Settings" showClose>
+	 *     {#snippet body(ctx)}
+	 *       <MySettings ctrl={ctx.ctrl} />
+	 *     {/snippet}
+	 *   </PopoverContent>
+	 * {/snippet}
+	 */
+	import type { Snippet } from 'svelte';
+	import { X } from 'lucide-svelte';
+	import type { ContentSnippetCtx } from '../types/types.js';
+
+	interface Props {
+		ctx: ContentSnippetCtx;
+		title?: string;
+		description?: string;
+		showClose?: boolean;
+		class?: string;
+		/** Primary body slot — receives ctx for controller access. */
+		body?: Snippet<[ContentSnippetCtx]>;
+		/** Fallback when no body snippet is provided. */
+		children?: Snippet<[ContentSnippetCtx]>;
+	}
+
+	const {
+		ctx,
+		title,
+		description,
+		showClose = false,
+		class: cls = '',
+		body,
+		children
+	}: Props = $props();
+</script>
+
+<div class="flex flex-col gap-3 p-4 {cls}">
+	{#if title || showClose}
+		<div class="flex items-center justify-between gap-2">
+			{#if title}
+				<h3 class="card-title text-sm">{title}</h3>
+			{/if}
+			{#if showClose}
+				<button
+					type="button"
+					class="btn btn-circle btn-ghost btn-xs ms-auto"
+					aria-label="Close"
+					onclick={() => ctx.ctrl.close()}
+				>
+					<X class="h-3 w-3" aria-hidden="true" />
+				</button>
+			{/if}
+		</div>
+	{/if}
+
+	{#if description}
+		<p class="text-xs leading-relaxed opacity-60">{description}</p>
+	{/if}
+
+	{#if body}
+		{@render body(ctx)}
+	{:else}
+		{@render children?.(ctx)}
+	{/if}
+</div>

package/dist/components/PopoverTrigger.svelte

@@ -0,0 +1,43 @@
+<script lang="ts">
+	/**
+	 * PopoverTrigger — pre-wired ARIA trigger button.
+	 *
+	 * Accepts the full `TriggerSnippetCtx` as `ctx` and wires all ARIA attributes
+	 * and interaction handlers automatically. Consumers only need to provide the
+	 * visual classes (daisyUI btn variants).
+	 *
+	 * @example
+	 * {#snippet trigger(ctx)}
+	 *   <PopoverTrigger {ctx} class="btn btn-primary">Open</PopoverTrigger>
+	 * {/snippet}
+	 */
+	import type { Snippet } from 'svelte';
+	import type { TriggerSnippetCtx } from '../types/types.js';
+
+	interface Props {
+		ctx: TriggerSnippetCtx;
+		disabled?: boolean;
+		class?: string;
+		children?: Snippet;
+	}
+
+	const { ctx, disabled = false, class: cls = '', children }: Props = $props();
+</script>
+
+<button
+	id={ctx.id}
+	type="button"
+	class="btn {cls}"
+	aria-haspopup="dialog"
+	aria-expanded={ctx.expanded}
+	aria-controls={ctx.controls}
+	{disabled}
+	onclick={ctx.onclick}
+	onkeydown={ctx.onkeydown}
+	onmouseenter={ctx.onmouseenter}
+	onmouseleave={ctx.onmouseleave}
+	onfocus={ctx.onfocus}
+	onblur={ctx.onblur}
+>
+	{@render children?.()}
+</button>

package/dist/constants/config.js

@@ -0,0 +1 @@
+const e={placement:"bottom",offset:8,trapFocus:!0,closeOnOutsideClick:!0,closeOnEsc:!0},r="scale",c="click",a=0,l=100,n=!1,s=200,d=["a[href]","button:not([disabled])","input:not([disabled])","select:not([disabled])","textarea:not([disabled])",'[tabindex]:not([tabindex="-1"])','[contenteditable="true"]',"details > summary"].join(", "),i="pop-live-region",p={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))"};let t=0;function E(o="pop"){return`${o}-${++t}`}export{s as ANIMATION_DURATION_MS,r as DEFAULT_ANIMATION,l as DEFAULT_CLOSE_DELAY,a as DEFAULT_OPEN_DELAY,e as DEFAULT_OPTIONS,n as DEFAULT_SHOW_ARROW,p as DEFAULT_THEME_TOKENS,c as DEFAULT_TRIGGER,d as FOCUSABLE_SELECTOR,i as LIVE_REGION_ID,E as uid};