@popover-kit/svelte 0.1.0 → 0.1.2

package/dist/index.d.ts

@@ -1,9 +1,5 @@
 import { Snippet } from 'svelte';
 
-// =============================================================================
-// Popover Micro-Plugin — Type Definitions (single source of truth)
-// =============================================================================
-// ─── Placement ────────────────────────────────────────────────────────────────
 /**
  * Where the panel appears relative to the trigger.
  *
@@ -14,7 +10,6 @@ import { Snippet } from 'svelte';
 export type Side = "top" | "bottom" | "left" | "right";
 export type Alignment = "start" | "end";
 export type Placement = "top" | "top-start" | "top-end" | "bottom" | "bottom-start" | "bottom-end" | "left" | "left-start" | "left-end" | "right" | "right-start" | "right-end" | "autoVertical";
-// ─── Computed position ────────────────────────────────────────────────────────
 /**
  * Output of the positioning engine.
  * x / y are viewport-relative px values suitable for `position: fixed`.
@@ -22,18 +17,42 @@ export type Placement = "top" | "top-start" | "top-end" | "bottom" | "bottom-sta
 export interface ResolvedPosition {
 	x: number;
 	y: number;
-	placement: Placement; // actual placement used (may differ from requested after flip)
+	placement: Placement;
 }
-// ─── State ────────────────────────────────────────────────────────────────────
 /** Fine-grained lifecycle state — drives CSS enter/exit transitions. */
 export type PopoverState = "closed" | "opening" | "open" | "closing";
-// ─── Controller interface ─────────────────────────────────────────────────────
+/**
+ * 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 {
-	// Reactive getters
+export interface IPopoverController extends AttachableController {
 	readonly isOpen: boolean;
 	readonly state: PopoverState;
 	readonly resolvedPlacement: Placement;
@@ -42,16 +61,10 @@ export interface IPopoverController {
 	readonly isVisible: boolean;
 	readonly triggerId: string;
 	readonly contentId: string;
-	// Core actions
 	open(): void;
 	close(): void;
 	toggle(): void;
 	setPlacement(p: Placement): void;
-	// Element wiring (called by Popover.svelte $effects and headless consumers)
-	attachTrigger(el: HTMLElement): void;
-	attachPanel(el: HTMLElement): void;
-	detachTrigger(): void;
-	detachPanel(): void;
 	getSnapshot(): PopoverSnapshot;
 	subscribe(cb: SubscriberFn): UnsubscribeFn;
 	destroy(): void;
@@ -65,22 +78,13 @@ export interface PopoverSnapshot {
 }
 export type SubscriberFn = (snap: PopoverSnapshot) => void;
 export type UnsubscribeFn = () => void;
-// ─── Controller options ───────────────────────────────────────────────────────
-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;
 }
-// ─── Component props ──────────────────────────────────────────────────────────
 export type PopoverAnimation = "scale" | "slide" | "fade" | "none";
 export type TriggerInteraction = "click" | "hover" | "focus" | "manual";
 export interface PopoverProps extends ControllerOptions {
@@ -98,7 +102,6 @@ export interface PopoverProps extends ControllerOptions {
 	/** Inject an existing controller; this component will not destroy it. */
 	controller?: IPopoverController;
 }
-// ─── Snippet contexts (Bits UI style — fully typed parameters) ────────────────
 /** Passed into `{#snippet trigger(ctx)}`. Spread these onto your trigger element. */
 export interface TriggerSnippetCtx {
 	id: string;
@@ -118,13 +121,11 @@ export interface ContentSnippetCtx {
 	resolvedPlacement: Placement;
 	state: PopoverState;
 }
-// ─── Accessibility handles ────────────────────────────────────────────────────
 export interface FocusTrapHandle {
 	activate(): void;
 	deactivate(): void;
 	destroy(): void;
 }
-// ─── Plugin factory ───────────────────────────────────────────────────────────
 export interface ThemeTokens {
 	borderRadius: string;
 	backdropBlur: string;
@@ -137,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<[
@@ -204,6 +288,14 @@ interface Props$2 {
 	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;
 }
 export declare const PopoverContent: import("svelte").Component<Props$2, {}, "">;
 export type PopoverContent = ReturnType<typeof PopoverContent>;
@@ -230,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;
@@ -241,31 +353,18 @@ export declare function getDirection(el: HTMLElement): "ltr" | "rtl";
  * Compute the `position:fixed` coordinates for the popover panel.
  *
  * The panel element MUST already be in the DOM (even if visibility:hidden)
- * so its dimensions can be read via getBoundingClientRect().
+ * so its dimensions can be read.
  *
  * @param triggerEl - The trigger / reference element.
  * @param panelEl   - The panel element to position.
  * @param placement - Requested placement (may be overridden by auto-flip).
  * @param offset    - Gap between trigger edge and panel in px.
+ * @param previousPlacement - The last resolved placement, if any. Used for
+ *   flip hysteresis (see `resolveAutoSide`) — pass the previous call's
+ *   `result.placement` on recomputes; omit on the first compute.
  * @returns { x, y, placement } — coordinates and the actual placement used.
  */
-export declare function computePosition(triggerEl: HTMLElement, panelEl: HTMLElement, placement: Placement, offset: number): 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 function computePosition(triggerEl: HTMLElement, panelEl: HTMLElement, placement: Placement, offset: number, previousPlacement?: Placement | null): ResolvedPosition;
 export declare const DEFAULT_OPTIONS: {
 	readonly placement: "bottom";
 	readonly offset: 8;
@@ -273,12 +372,19 @@ export declare const DEFAULT_OPTIONS: {
 	readonly closeOnOutsideClick: true;
 	readonly closeOnEsc: true;
 };
+export declare const DEFAULT_ANIMATION: "scale";
+export declare const DEFAULT_TRIGGER: "click";
+export declare const DEFAULT_OPEN_DELAY: number;
+export declare const DEFAULT_CLOSE_DELAY: number;
+export declare const DEFAULT_SHOW_ARROW: boolean;
 /**
  * Must match the longest `transition-duration` in PopoverPanel's CSS.
  * The controller waits this long after close() before setting state → 'closed'
  * so the exit animation completes before the panel is unmounted.
  */
 export declare const ANIMATION_DURATION_MS = 200;
+export declare const FOCUSABLE_SELECTOR: string;
+export declare const LIVE_REGION_ID = "pop-live-region";
 export declare const DEFAULT_THEME_TOKENS: ThemeTokens;
 /**
  * Generates a stable, unique DOM id.

package/dist/index.js

@@ -1 +1 @@
-import{default as q}from"./components/Popover.svelte";import{default as V}from"./components/PopoverTrigger.svelte";import{default as W}from"./components/PopoverContent.svelte";import{default as j}from"./elements/PopoverPanel.svelte";import{default as z}from"./elements/PopoverArrow.svelte";import{PopoverController as Q}from"./controller.svelte";function x(t){if(t==="autoVertical")return{side:"bottom",alignment:null};let[o,e=null]=t.split("-");return{side:o,alignment:e}}function w(t,o,e,n,i,s){let a,c;switch(e){case"bottom":c=t.bottom+i;break;case"top":c=t.top-o.height-i;break;case"left":a=t.left-o.width-i;break;case"right":a=t.right+i;break}if(e==="top"||e==="bottom"){let r=s?t.right-o.width:t.left,d=s?t.left:t.right-o.width;n==="start"?a=r:n==="end"?a=d:a=t.left+(t.width-o.width)/2}else n==="start"?c=t.top:n==="end"?c=t.bottom-o.height:c=t.top+(t.height-o.height)/2;return{x:a,y:c}}function T(t){return getComputedStyle(t).direction==="rtl"?"rtl":"ltr"}function v(t,o,e,n=6){return Math.max(n,Math.min(e-o-n,t))}function O(t,o,e,n,i){let s=window.innerWidth,a=window.innerHeight;switch(t){case"bottom":return o.bottom+i+e<=a?"bottom":"top";case"top":return o.top-i-e>=0?"top":"bottom";case"right":return o.right+i+n<=s?"right":"left";case"left":return o.left-i-n>=0?"left":"right"}}function _(t,o,e,n){let i=t.getBoundingClientRect(),s=o.getBoundingClientRect(),a=window.innerWidth,c=window.innerHeight,r=T(t)==="rtl",{side:d,alignment:p}=x(e),u=O(d,i,s.height,s.width,n),f=e==="autoVertical"?u==="top"?"top":"bottom":u===d?e:p?`${u}-${p}`:u,{x:m,y:h}=w(i,s,u,p,n,r);return u==="top"||u==="bottom"?m=v(m,s.width,a):h=v(h,s.height,c),{x:m,y:h,placement:f}}var L={placement:"bottom",offset:8,trapFocus:!0,closeOnOutsideClick:!0,closeOnEsc:!0};var k=200,A=["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",b={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))"},D=0;function S(t="pop"){return`${t}-${++D}`}function I(t,o){let e=!1,n=document.activeElement;function i(){return Array.from(t.querySelectorAll(A)).filter(r=>!r.hasAttribute("disabled")&&r.offsetParent!==null)}function s(r){if(!e||r.key!=="Tab")return;let d=i();if(!d.length){r.preventDefault();return}let p=d[0],u=d[d.length-1],f=document.activeElement;r.shiftKey?(f===p||!t.contains(f))&&(r.preventDefault(),u.focus()):(f===u||!t.contains(f))&&(r.preventDefault(),p.focus())}function a(){if(e)return;e=!0,n=document.activeElement,document.addEventListener("keydown",s,!0);let r=i()[0]??t;requestAnimationFrame(()=>r.focus())}function c(){if(!e)return;e=!1,document.removeEventListener("keydown",s,!0);let r=o??n;r&&typeof r.focus=="function"&&requestAnimationFrame(()=>r.focus())}return{activate:a,deactivate:c,destroy:c}}var l=null;function P(){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 F(t,o=80){let e=P();e.textContent="",setTimeout(()=>{e.textContent=t},o)}function y(t,o){function e(n){let i=n.target;t.some(s=>s.contains(i))||o(n)}return document.addEventListener("pointerdown",e,!0),()=>document.removeEventListener("pointerdown",e,!0)}function M(t={}){return{defaults:t.defaults??{},tokens:{...b,...t.theme}}}export{k as ANIMATION_DURATION_MS,L as DEFAULT_OPTIONS,b as DEFAULT_THEME_TOKENS,q as Popover,z as PopoverArrow,W as PopoverContent,Q as PopoverController,j as PopoverPanel,V as PopoverTrigger,F as announce,_ as computePosition,I as createFocusTrap,M as createPopoverPlugin,T as getDirection,y as onClickOutside,x as parsePlacement,S 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/dist/utils/a11y.js

@@ -1 +1 @@
-import{FOCUSABLE_SELECTOR as v,LIVE_REGION_ID as m}from"../constants/config.js";function y(o,r){let t=!1,i=document.activeElement;function u(){return Array.from(o.querySelectorAll(v)).filter(e=>!e.hasAttribute("disabled")&&e.offsetParent!==null)}function c(e){if(!t||e.key!=="Tab")return;const s=u();if(!s.length){e.preventDefault();return}const d=s[0],l=s[s.length-1],a=document.activeElement;e.shiftKey?(a===d||!o.contains(a))&&(e.preventDefault(),l.focus()):(a===l||!o.contains(a))&&(e.preventDefault(),d.focus())}function p(){if(t)return;t=!0,i=document.activeElement,document.addEventListener("keydown",c,!0);const e=u()[0]??o;requestAnimationFrame(()=>e.focus())}function f(){if(!t)return;t=!1,document.removeEventListener("keydown",c,!0);const e=r??i;e&&typeof e.focus=="function"&&requestAnimationFrame(()=>e.focus())}return{activate:p,deactivate:f,destroy:f}}let n=null;function g(){return n||(n=document.getElementById(m),n||(n=document.createElement("div"),n.id=m,n.setAttribute("aria-live","polite"),n.setAttribute("aria-atomic","true"),Object.assign(n.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(n)),n)}function h(o,r=80){const t=g();t.textContent="",setTimeout(()=>{t.textContent=o},r)}function b(o,r){function t(i){const u=i.target;o.some(c=>c.contains(u))||r(i)}return document.addEventListener("pointerdown",t,!0),()=>document.removeEventListener("pointerdown",t,!0)}export{h as announce,y as createFocusTrap,b as onClickOutside};
+import{FOCUSABLE_SELECTOR as v,LIVE_REGION_ID as m}from"../constants.js";function y(o,r){let t=!1,i=document.activeElement;function u(){return Array.from(o.querySelectorAll(v)).filter(e=>!e.hasAttribute("disabled")&&e.offsetParent!==null)}function c(e){if(!t||e.key!=="Tab")return;const s=u();if(!s.length){e.preventDefault();return}const d=s[0],l=s[s.length-1],a=document.activeElement;e.shiftKey?(a===d||!o.contains(a))&&(e.preventDefault(),l.focus()):(a===l||!o.contains(a))&&(e.preventDefault(),d.focus())}function p(){if(t)return;t=!0,i=document.activeElement,document.addEventListener("keydown",c,!0);const e=u()[0]??o;requestAnimationFrame(()=>e.focus())}function f(){if(!t)return;t=!1,document.removeEventListener("keydown",c,!0);const e=r??i;e&&typeof e.focus=="function"&&requestAnimationFrame(()=>e.focus())}return{activate:p,deactivate:f,destroy:f}}let n=null;function g(){return n||(n=document.getElementById(m),n||(n=document.createElement("div"),n.id=m,n.setAttribute("aria-live","polite"),n.setAttribute("aria-atomic","true"),Object.assign(n.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(n)),n)}function h(o,r=80){const t=g();t.textContent="",setTimeout(()=>{t.textContent=o},r)}function b(o,r){function t(i){const u=i.target;o.some(c=>c.contains(u))||r(i)}return document.addEventListener("pointerdown",t,!0),()=>document.removeEventListener("pointerdown",t,!0)}export{h as announce,y as createFocusTrap,b as onClickOutside};

package/dist/utils/position.js

@@ -1 +1 @@
-function p(t){if(t==="autoVertical")return{side:"bottom",alignment:null};const[o,n=null]=t.split("-");return{side:o,alignment:n}}const S={top:"bottom",bottom:"top",left:"right",right:"left"};function f(t,o,n,i,e,h){let l,s;switch(n){case"bottom":s=t.bottom+e;break;case"top":s=t.top-o.height-e;break;case"left":l=t.left-o.width-e;break;case"right":l=t.right+e;break}if(n==="top"||n==="bottom"){const d=h?t.right-o.width:t.left,r=h?t.left:t.right-o.width;i==="start"?l=d:i==="end"?l=r:l=t.left+(t.width-o.width)/2}else i==="start"?s=t.top:i==="end"?s=t.bottom-o.height:s=t.top+(t.height-o.height)/2;return{x:l,y:s}}function v(t){return getComputedStyle(t).direction==="rtl"?"rtl":"ltr"}function w(t,o,n,i=6){return Math.max(i,Math.min(n-o-i,t))}function x(t,o,n,i,e){const h=window.innerWidth,l=window.innerHeight;switch(t){case"bottom":return o.bottom+e+n<=l?"bottom":"top";case"top":return o.top-e-n>=0?"top":"bottom";case"right":return o.right+e+i<=h?"right":"left";case"left":return o.left-e-i>=0?"left":"right"}}function P(t,o,n,i){const e=t.getBoundingClientRect(),h=o.getBoundingClientRect(),l=window.innerWidth,s=window.innerHeight,d=v(t)==="rtl";let{side:r,alignment:c}=p(n);const u=x(r,e,h.height,h.width,i),b=n==="autoVertical"?u==="top"?"top":"bottom":u===r?n:c?`${u}-${c}`:u;let{x:m,y:a}=f(e,h,u,c,i,d);return u==="top"||u==="bottom"?m=w(m,h.width,l):a=w(a,h.height,s),{x:m,y:a,placement:b}}export{P as computePosition,v as getDirection,p as parsePlacement};
+function w(t){if(t==="autoVertical")return{side:"bottom",alignment:null};const[o,i=null]=t.split("-");return{side:o,alignment:i}}function P(t,o,i,l,u,c,e){let n,s;switch(l){case"bottom":s=t.bottom+c;break;case"top":s=t.top-i-c;break;case"left":n=t.left-o-c;break;case"right":n=t.right+c;break}if(l==="top"||l==="bottom"){const h=e?t.right-o:t.left,b=e?t.left:t.right-o;u==="start"?n=h:u==="end"?n=b:n=t.left+(t.width-o)/2}else u==="start"?s=t.top:u==="end"?s=t.bottom-i:s=t.top+(t.height-i)/2;return{x:n,y:s}}function k(t){return getComputedStyle(t).direction==="rtl"?"rtl":"ltr"}function p(t,o,i,l=6){return Math.max(l,Math.min(i-o-l,t))}const v={top:"bottom",bottom:"top",left:"right",right:"left"};function y(t,o,i,l,u,c,e,n=0){switch(t){case"bottom":return o.bottom+u+i+n<=e;case"top":return o.top-u-i-n>=0;case"right":return o.right+u+l+n<=c;case"left":return o.left-u-l-n>=0}}const A=24;function I(t,o,i,l,u,c,e,n){const s=v[t],h=(b,f=0)=>y(b,o,i,l,u,c,e,f);return n===s?h(t,A)?t:h(s)?s:t:h(t)?t:h(s)?s:n??t}function _(t,o,i,l,u){const c=t.getBoundingClientRect(),e=o.offsetWidth,n=o.offsetHeight,s=window.innerWidth,h=window.innerHeight,b=k(t)==="rtl";let{side:f,alignment:m}=w(i);const x=u?w(u).side:null,a=I(f,c,n,e,l,s,h,x),S=i==="autoVertical"?a==="top"?"top":"bottom":a===f?i:m?`${a}-${m}`:a;let{x:d,y:r}=P(c,e,n,a,m,l,b);return a==="top"||a==="bottom"?d=p(d,e,s):r=p(r,n,h),{x:d,y:r,placement:S}}export{_ as computePosition,k as getDirection,w as parsePlacement};

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@popover-kit/svelte",
-  "version": "0.1.0",
-  "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",
@@ -34,9 +36,6 @@
   "peerDependencies": {
     "svelte": "^5.0.0"
   },
-  "dependencies": {
-    "lucide-svelte": "^0.462.0"
-  },
   "devDependencies": {
     "@sveltejs/package": "^2.3.0",
     "@sveltejs/vite-plugin-svelte": "^4.0.0",
@@ -63,7 +62,6 @@
     "typecheck": "svelte-check --tsconfig ./tsconfig.json",
     "typecheck:test": "tsc -p tsconfig.test.json",
     "test": "vitest run",
-    "test:watch": "vitest",
-    "prepublishOnlyx": "pnpm run typecheck && pnpm run test && pnpm run build"
+    "test:watch": "vitest"
   }
 }