@data-slot/popover 0.1.0

package/README.md

@@ -0,0 +1,193 @@
+# @data-slot/popover
+
+Headless popover component for vanilla JavaScript. Accessible, unstyled, tiny.
+
+## Installation
+
+```bash
+npm install @data-slot/popover
+```
+
+## Quick Start
+
+```html
+<div data-slot="popover">
+  <button data-slot="popover-trigger">Open Popover</button>
+  <div data-slot="popover-content" hidden>
+    <p>Popover content here</p>
+    <button data-slot="popover-close">Close</button>
+  </div>
+</div>
+
+<script type="module">
+  import { create } from "@data-slot/popover";
+  
+  const controllers = create();
+</script>
+```
+
+## API
+
+### `create(scope?)`
+
+Auto-discover and bind all popover instances in a scope (defaults to `document`).
+
+```typescript
+import { create } from "@data-slot/popover";
+
+const controllers = create(); // Returns PopoverController[]
+```
+
+### `createPopover(root, options?)`
+
+Create a controller for a specific element.
+
+```typescript
+import { createPopover } from "@data-slot/popover";
+
+const popover = createPopover(element, {
+  defaultOpen: false,
+  position: "bottom",
+  closeOnClickOutside: true,
+  closeOnEscape: true,
+  onOpenChange: (open) => console.log(open),
+});
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `defaultOpen` | `boolean` | `false` | Initial open state |
+| `position` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Position relative to trigger |
+| `closeOnClickOutside` | `boolean` | `true` | Close when clicking outside |
+| `closeOnEscape` | `boolean` | `true` | Close when pressing Escape |
+| `onOpenChange` | `(open: boolean) => void` | `undefined` | Callback when open state changes |
+
+### Controller
+
+| Method/Property | Description |
+|-----------------|-------------|
+| `open()` | Open the popover |
+| `close()` | Close the popover |
+| `toggle()` | Toggle the popover |
+| `isOpen` | Current open state (readonly `boolean`) |
+| `destroy()` | Cleanup all event listeners |
+
+## Markup Structure
+
+```html
+<div data-slot="popover">
+  <button data-slot="popover-trigger">Trigger</button>
+  <div data-slot="popover-content">
+    Content
+    <button data-slot="popover-close">Close</button>
+  </div>
+</div>
+```
+
+### Required Slots
+
+- `popover-trigger` - Button to toggle popover
+- `popover-content` - The popover panel
+
+### Optional Slots
+
+- `popover-close` - Button to close the popover
+
+### Data Attributes
+
+Set position via HTML:
+
+```html
+<div data-slot="popover-content" data-position="top">
+```
+
+## Styling
+
+Use `data-state` and `data-position` attributes:
+
+```css
+/* Hidden state */
+[data-slot="popover-content"][hidden] {
+  display: none;
+}
+
+/* Positioning */
+[data-slot="popover"] {
+  position: relative;
+}
+
+[data-slot="popover-content"] {
+  position: absolute;
+}
+
+[data-slot="popover-content"][data-position="top"] {
+  bottom: 100%;
+  left: 50%;
+  transform: translateX(-50%);
+}
+
+[data-slot="popover-content"][data-position="bottom"] {
+  top: 100%;
+  left: 50%;
+  transform: translateX(-50%);
+}
+
+[data-slot="popover-content"][data-position="left"] {
+  right: 100%;
+  top: 50%;
+  transform: translateY(-50%);
+}
+
+[data-slot="popover-content"][data-position="right"] {
+  left: 100%;
+  top: 50%;
+  transform: translateY(-50%);
+}
+```
+
+With Tailwind:
+
+```html
+<div data-slot="popover" class="relative">
+  <button data-slot="popover-trigger">Open</button>
+  <div 
+    data-slot="popover-content" 
+    class="absolute top-full left-1/2 -translate-x-1/2 mt-2 bg-white shadow-lg rounded-lg p-4 hidden data-[state=open]:block"
+  >
+    Content
+  </div>
+</div>
+```
+
+## Accessibility
+
+The component automatically handles:
+
+- `aria-haspopup="dialog"` on trigger
+- `aria-controls` linking trigger to content
+- `aria-expanded` state on trigger
+- Unique ID generation for content
+
+## Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| `Enter` / `Space` | Toggle popover (on trigger) |
+| `Escape` | Close popover and return focus to trigger |
+
+## Events
+
+Listen for changes via custom events:
+
+```javascript
+element.addEventListener("popover:change", (e) => {
+  console.log("Popover open:", e.detail.open);
+});
+```
+
+## License
+
+MIT
+

package/dist/index.cjs

@@ -0,0 +1 @@
+var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));const c=s(require(`@data-slot/core`));function l(e,t={}){let{defaultOpen:n=!1,onOpenChange:r,closeOnClickOutside:i=!0,closeOnEscape:a=!0}=t,o=(0,c.getPart)(e,`popover-trigger`),s=(0,c.getPart)(e,`popover-content`),l=(0,c.getPart)(e,`popover-close`);if(!o||!s)throw Error(`Popover requires trigger and content slots`);let u=t.position??s.dataset.position??`bottom`,d=n,f=[],p=(0,c.ensureId)(s,`popover-content`);o.setAttribute(`aria-haspopup`,`dialog`),o.setAttribute(`aria-controls`,p),s.setAttribute(`data-position`,u);let m=t=>{d!==t&&(d=t,(0,c.setAria)(o,`expanded`,d),s.hidden=!d,e.setAttribute(`data-state`,d?`open`:`closed`),(0,c.emit)(e,`popover:change`,{open:d}),r?.(d))};(0,c.setAria)(o,`expanded`,d),s.hidden=!d,e.setAttribute(`data-state`,d?`open`:`closed`),f.push((0,c.on)(o,`click`,()=>m(!d))),l&&f.push((0,c.on)(l,`click`,()=>m(!1))),i&&f.push((0,c.on)(document,`pointerdown`,t=>{if(!d)return;let n=t.target;e.contains(n)||m(!1)})),a&&f.push((0,c.on)(document,`keydown`,e=>{d&&e.key===`Escape`&&(e.preventDefault(),m(!1),o.focus())}));let h={open:()=>m(!0),close:()=>m(!1),toggle:()=>m(!d),get isOpen(){return d},destroy:()=>{f.forEach(e=>e()),f.length=0}};return h}const u=new WeakSet;function d(e=document){let t=[];for(let n of(0,c.getRoots)(e,`popover`)){if(u.has(n))continue;u.add(n),t.push(l(n))}return t}exports.create=d,exports.createPopover=l;

package/dist/index.d.cts

@@ -0,0 +1,48 @@
+//#region src/index.d.ts
+type PopoverPosition = "top" | "bottom" | "left" | "right";
+interface PopoverOptions {
+  /** Initial open state */
+  defaultOpen?: boolean;
+  /** Position of popover relative to trigger */
+  position?: PopoverPosition;
+  /** Callback when open state changes */
+  onOpenChange?: (open: boolean) => void;
+  /** Close when clicking outside */
+  closeOnClickOutside?: boolean;
+  /** Close when pressing Escape */
+  closeOnEscape?: boolean;
+}
+interface PopoverController {
+  /** Open the popover */
+  open(): void;
+  /** Close the popover */
+  close(): void;
+  /** Toggle the popover */
+  toggle(): void;
+  /** Current open state */
+  readonly isOpen: boolean;
+  /** Cleanup all event listeners */
+  destroy(): void;
+}
+/**
+ * Create a popover controller for a root element
+ *
+ * Expected markup:
+ * ```html
+ * <div data-slot="popover">
+ *   <button data-slot="popover-trigger">Open</button>
+ *   <div data-slot="popover-content">
+ *     Popover content
+ *     <button data-slot="popover-close">Close</button>
+ *   </div>
+ * </div>
+ * ```
+ */
+declare function createPopover(root: Element, options?: PopoverOptions): PopoverController;
+/**
+ * Find and bind all popover components in a scope
+ * Returns array of controllers for programmatic access
+ */
+declare function create(scope?: ParentNode): PopoverController[];
+//#endregion
+export { PopoverController, PopoverOptions, PopoverPosition, create, createPopover };

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+//#region src/index.d.ts
+type PopoverPosition = "top" | "bottom" | "left" | "right";
+interface PopoverOptions {
+  /** Initial open state */
+  defaultOpen?: boolean;
+  /** Position of popover relative to trigger */
+  position?: PopoverPosition;
+  /** Callback when open state changes */
+  onOpenChange?: (open: boolean) => void;
+  /** Close when clicking outside */
+  closeOnClickOutside?: boolean;
+  /** Close when pressing Escape */
+  closeOnEscape?: boolean;
+}
+interface PopoverController {
+  /** Open the popover */
+  open(): void;
+  /** Close the popover */
+  close(): void;
+  /** Toggle the popover */
+  toggle(): void;
+  /** Current open state */
+  readonly isOpen: boolean;
+  /** Cleanup all event listeners */
+  destroy(): void;
+}
+/**
+ * Create a popover controller for a root element
+ *
+ * Expected markup:
+ * ```html
+ * <div data-slot="popover">
+ *   <button data-slot="popover-trigger">Open</button>
+ *   <div data-slot="popover-content">
+ *     Popover content
+ *     <button data-slot="popover-close">Close</button>
+ *   </div>
+ * </div>
+ * ```
+ */
+declare function createPopover(root: Element, options?: PopoverOptions): PopoverController;
+/**
+ * Find and bind all popover components in a scope
+ * Returns array of controllers for programmatic access
+ */
+declare function create(scope?: ParentNode): PopoverController[];
+//#endregion
+export { PopoverController, PopoverOptions, PopoverPosition, create, createPopover };

package/dist/index.js

@@ -0,0 +1 @@
+import{emit as e,ensureId as t,getPart as n,getRoots as r,on as i,setAria as a}from"@data-slot/core";function o(r,o={}){let{defaultOpen:s=!1,onOpenChange:c,closeOnClickOutside:l=!0,closeOnEscape:u=!0}=o,d=n(r,`popover-trigger`),f=n(r,`popover-content`),p=n(r,`popover-close`);if(!d||!f)throw Error(`Popover requires trigger and content slots`);let m=o.position??f.dataset.position??`bottom`,h=s,g=[],_=t(f,`popover-content`);d.setAttribute(`aria-haspopup`,`dialog`),d.setAttribute(`aria-controls`,_),f.setAttribute(`data-position`,m);let v=t=>{h!==t&&(h=t,a(d,`expanded`,h),f.hidden=!h,r.setAttribute(`data-state`,h?`open`:`closed`),e(r,`popover:change`,{open:h}),c?.(h))};a(d,`expanded`,h),f.hidden=!h,r.setAttribute(`data-state`,h?`open`:`closed`),g.push(i(d,`click`,()=>v(!h))),p&&g.push(i(p,`click`,()=>v(!1))),l&&g.push(i(document,`pointerdown`,e=>{if(!h)return;let t=e.target;r.contains(t)||v(!1)})),u&&g.push(i(document,`keydown`,e=>{h&&e.key===`Escape`&&(e.preventDefault(),v(!1),d.focus())}));let y={open:()=>v(!0),close:()=>v(!1),toggle:()=>v(!h),get isOpen(){return h},destroy:()=>{g.forEach(e=>e()),g.length=0}};return y}const s=new WeakSet;function c(e=document){let t=[];for(let n of r(e,`popover`)){if(s.has(n))continue;s.add(n),t.push(o(n))}return t}export{c as create,o as createPopover};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@data-slot/popover",
+  "version": "0.1.0",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsdown"
+  },
+  "dependencies": {
+    "@data-slot/core": "workspace:*"
+  },
+  "keywords": ["headless", "ui", "popover", "vanilla", "data-slot"],
+  "license": "MIT"
+}