@popover-kit/svelte 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,313 @@
+import { Snippet } from 'svelte';
+
+// =============================================================================
+// Popover Micro-Plugin — Type Definitions (single source of truth)
+// =============================================================================
+// ─── Placement ────────────────────────────────────────────────────────────────
+/**
+ * Where the panel appears relative to the trigger.
+ *
+ * Sides:     top | bottom | left | right
+ * Alignment: -start | -end  (no suffix = center)
+ * Special:   autoVertical — prefers bottom, flips to top when viewport clips it
+ */
+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`.
+ */
+export interface ResolvedPosition {
+	x: number;
+	y: number;
+	placement: Placement; // actual placement used (may differ from requested after flip)
+}
+// ─── State ────────────────────────────────────────────────────────────────────
+/** Fine-grained lifecycle state — drives CSS enter/exit transitions. */
+export type PopoverState = "closed" | "opening" | "open" | "closing";
+// ─── Controller interface ─────────────────────────────────────────────────────
+/**
+ * Public surface of PopoverController.
+ * All readonly getters are $state runes — Svelte templates track them.
+ */
+export interface IPopoverController {
+	// Reactive getters
+	readonly isOpen: boolean;
+	readonly state: PopoverState;
+	readonly resolvedPlacement: Placement;
+	readonly position: ResolvedPosition | null;
+	/** True while the panel should stay mounted (open OR exit-animating). */
+	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;
+}
+export interface PopoverSnapshot {
+	readonly isOpen: boolean;
+	readonly state: PopoverState;
+	readonly resolvedPlacement: Placement;
+	readonly triggerId: string;
+	readonly contentId: string;
+}
+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;
+	/** 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 {
+	animation?: PopoverAnimation;
+	showArrow?: boolean;
+	class?: string;
+	"aria-label"?: string;
+	triggerInteraction?: TriggerInteraction;
+	/** Delay (ms) before opening — useful for hover mode. */
+	openDelay?: number;
+	/** Delay (ms) before closing — useful for hover mode. */
+	closeDelay?: number;
+	/** External boolean for fully-controlled mode. */
+	open?: boolean;
+	/** 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;
+	controls: string;
+	expanded: boolean;
+	onclick: () => void;
+	onkeydown: (e: KeyboardEvent) => void;
+	onmouseenter: () => void;
+	onmouseleave: () => void;
+	onfocus: () => void;
+	onblur: () => void;
+	ctrl: IPopoverController;
+}
+/** Passed into `{#snippet content(ctx)}`. */
+export interface ContentSnippetCtx {
+	ctrl: IPopoverController;
+	resolvedPlacement: Placement;
+	state: PopoverState;
+}
+// ─── Accessibility handles ────────────────────────────────────────────────────
+export interface FocusTrapHandle {
+	activate(): void;
+	deactivate(): void;
+	destroy(): void;
+}
+// ─── Plugin factory ───────────────────────────────────────────────────────────
+export interface ThemeTokens {
+	borderRadius: string;
+	backdropBlur: string;
+	shadowColor: string;
+	lightBg: string;
+	darkBg: string;
+	lightBorder: string;
+	darkBorder: string;
+	lightText: string;
+	darkText: string;
+	accentColor: string;
+}
+export declare class PopoverController implements IPopoverController {
+	#private;
+	readonly triggerId: string;
+	readonly contentId: string;
+	constructor(opts?: ControllerOptions);
+	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.
+	 * 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;
+	open(): void;
+	close(): void;
+	toggle(): void;
+	setPlacement(p: Placement): void;
+	destroy(): void;
+}
+export interface Props extends PopoverProps {
+	trigger?: Snippet<[
+		TriggerSnippetCtx
+	]>;
+	content?: Snippet<[
+		ContentSnippetCtx
+	]>;
+	children?: Snippet<[
+		IPopoverController
+	]>;
+}
+export declare const Popover: import("svelte").Component<Props, {
+	open: () => void;
+	close: () => void;
+	toggle: () => void;
+	getController: () => PopoverController;
+}, "">;
+export type Popover = ReturnType<typeof Popover>;
+interface Props$1 {
+	ctx: TriggerSnippetCtx;
+	disabled?: boolean;
+	class?: string;
+	children?: Snippet;
+}
+export declare const PopoverTrigger: import("svelte").Component<Props$1, {}, "">;
+export type PopoverTrigger = ReturnType<typeof PopoverTrigger>;
+interface Props$2 {
+	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
+	]>;
+}
+export declare const PopoverContent: import("svelte").Component<Props$2, {}, "">;
+export type PopoverContent = ReturnType<typeof PopoverContent>;
+interface Props$3 {
+	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;
+}
+export declare const PopoverPanel: import("svelte").Component<Props$3, {}, "el">;
+export type PopoverPanel = ReturnType<typeof PopoverPanel>;
+interface Props$4 {
+	placement: Placement;
+	class?: string;
+}
+export declare const PopoverArrow: import("svelte").Component<Props$4, {}, "">;
+export type PopoverArrow = ReturnType<typeof PopoverArrow>;
+/** Split "bottom-start" → { side: 'bottom', alignment: 'start' } */
+export declare function parsePlacement(p: Placement): {
+	side: Side;
+	alignment: Alignment | null;
+};
+/** Reads the resolved (computed) writing direction of an element. */
+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().
+ *
+ * @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.
+ * @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 const DEFAULT_OPTIONS: {
+	readonly placement: "bottom";
+	readonly offset: 8;
+	readonly trapFocus: true;
+	readonly closeOnOutsideClick: true;
+	readonly closeOnEsc: true;
+};
+/**
+ * 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 DEFAULT_THEME_TOKENS: ThemeTokens;
+/**
+ * Generates a stable, unique DOM id.
+ *
+ * Deliberately a pure monotonic counter — NOT `Math.random()`. With SSR
+ * enabled, ids are generated once on the server and again on the client
+ * during hydration; a random suffix would differ between the two passes
+ * and mismatch the DOM, breaking `aria-controls`/`aria-labelledby` wiring
+ * the moment hydration reconciles attributes. A counter produces the same
+ * sequence both times as long as components mount in the same order, which
+ * holds for a given render tree.
+ */
+export declare function uid(prefix?: string): string;
+export interface PluginConfig {
+	defaults?: Partial<ControllerOptions>;
+	theme?: Partial<ThemeTokens>;
+}
+/**
+ * createPopoverPlugin — returns a config bundle with merged theme tokens.
+ * Use to create module-specific variants with different defaults.
+ *
+ * @example
+ * const SearchPopover = createPopoverPlugin({
+ *   defaults: { placement: 'bottom-start', trapFocus: false },
+ * });
+ */
+export declare function createPopoverPlugin(cfg?: PluginConfig): {
+	defaults: Partial<ControllerOptions>;
+	tokens: ThemeTokens;
+};
+
+export {};

package/dist/index.js

@@ -0,0 +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};

package/dist/utils/a11y.js

@@ -0,0 +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};

package/dist/utils/position.js

@@ -0,0 +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};

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@popover-kit/svelte",
+  "version": "0.1.0",
+  "description": "",
+  "keywords": [
+    "svelte",
+    "svelte5",
+    "popover",
+    "modal",
+    "drawer",
+    "daisyui",
+    "tailwindcss",
+    "rtl",
+    "a11y"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "svelte": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "svelte": "^5.0.0"
+  },
+  "dependencies": {
+    "lucide-svelte": "^0.462.0"
+  },
+  "devDependencies": {
+    "@sveltejs/package": "^2.3.0",
+    "@sveltejs/vite-plugin-svelte": "^4.0.0",
+    "@testing-library/svelte": "^5.2.0",
+    "@testing-library/jest-dom": "^6.6.0",
+    "@testing-library/user-event": "^14.5.0",
+    "@types/node": "^22.0.0",
+    "dts-bundle-generator": "^9.5.1",
+    "esbuild": "^0.24.0",
+    "jsdom": "^25.0.0",
+    "svelte": "^5.0.0",
+    "svelte-check": "^4.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "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"
+  }
+}