npm - @data-slot/dropdown-menu - Versions diffs - 0.2.2 - Mend

@data-slot/dropdown-menu 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,156 @@
+# @data-slot/dropdown-menu
+Headless dropdown menu component with full keyboard navigation and ARIA support.
+## Installation
+```bash
+npm install @data-slot/dropdown-menu
+```
+## Usage
+### HTML Structure
+```html
+<div data-slot="dropdown-menu">
+  <button data-slot="dropdown-menu-trigger">Options</button>
+  <div data-slot="dropdown-menu-content">
+    <div data-slot="dropdown-menu-group">
+      <div data-slot="dropdown-menu-label">Actions</div>
+      <button data-slot="dropdown-menu-item">
+        Edit
+        <span data-slot="dropdown-menu-shortcut">Ctrl+E</span>
+      </button>
+      <button data-slot="dropdown-menu-item" data-variant="destructive">Delete</button>
+    </div>
+    <div data-slot="dropdown-menu-separator"></div>
+    <button data-slot="dropdown-menu-item" data-disabled>Disabled</button>
+  </div>
+</div>
+```
+### JavaScript
+```js
+import { create, createDropdownMenu } from "@data-slot/dropdown-menu";
+// Auto-bind all dropdown menus in the document
+const controllers = create();
+// Or bind a specific element
+const root = document.querySelector('[data-slot="dropdown-menu"]');
+const controller = createDropdownMenu(root, {
+  onOpenChange: (open) => console.log("Menu open:", open),
+  onSelect: (value) => console.log("Selected:", value),
+});
+// Programmatic control
+controller.open();
+controller.close();
+controller.toggle();
+controller.destroy();
+```
+## Slots
+| Slot | Description |
+|------|-------------|
+| `dropdown-menu` | Root container |
+| `dropdown-menu-trigger` | Button that opens the menu |
+| `dropdown-menu-content` | The menu panel |
+| `dropdown-menu-group` | Groups related items |
+| `dropdown-menu-label` | Non-interactive label for groups |
+| `dropdown-menu-item` | Clickable menu item |
+| `dropdown-menu-separator` | Visual divider |
+| `dropdown-menu-shortcut` | Keyboard shortcut hint |
+## Data Attributes
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `data-state` | `open`, `closed` | Current menu state (on root and content) |
+| `data-side` | `top`, `right`, `bottom`, `left` | Computed side after collision avoidance (may flip) |
+| `data-align` | `start`, `center`, `end` | Requested alignment (position may shift to fit viewport) |
+| `data-variant` | `default`, `destructive` | Item variant for styling |
+| `data-inset` | - | Adds left padding for alignment |
+| `data-disabled` | - | Disables the item |
+| `data-highlighted` | - | Currently focused item |
+| `data-value` | string | Optional value for item selection |
+## Keyboard Navigation
+| Key | Action |
+|-----|--------|
+| `Enter` / `Space` | Open menu (on trigger) or activate item |
+| `ArrowDown` | Open menu (on trigger) or move to next item |
+| `ArrowUp` | Move to previous item |
+| `Home` | Move to first item |
+| `End` | Move to last item |
+| `Escape` | Close menu |
+| `A-Z` | Jump to item starting with letter (typeahead) |
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `dropdown-menu:change` | `{ open: boolean }` | Fired when menu opens or closes |
+| `dropdown-menu:select` | `{ value: string }` | Fired when an item is selected |
+## Options
+```ts
+interface DropdownMenuOptions {
+  /** Initial open state */
+  defaultOpen?: boolean;
+  /** Callback when open state changes */
+  onOpenChange?: (open: boolean) => void;
+  /** Callback when an item is selected */
+  onSelect?: (value: string) => void;
+  /** Close when clicking outside (default: true) */
+  closeOnClickOutside?: boolean;
+  /** Close when pressing Escape (default: true) */
+  closeOnEscape?: boolean;
+  /** Close when an item is selected (default: true) */
+  closeOnSelect?: boolean;
+  // Positioning options (Radix-compatible)
+  /** Preferred side of trigger: "top" | "right" | "bottom" | "left" (default: "bottom") */
+  side?: "top" | "right" | "bottom" | "left";
+  /** Alignment against trigger: "start" | "center" | "end" (default: "start") */
+  align?: "start" | "center" | "end";
+  /** Distance from trigger in px (default: 4) */
+  sideOffset?: number;
+  /** Offset from alignment edge in px (default: 0) */
+  alignOffset?: number;
+  /** Flip/shift to stay in viewport (default: true) */
+  avoidCollisions?: boolean;
+  /** Viewport edge padding in px (default: 8) */
+  collisionPadding?: number;
+}
+```
+## Positioning
+The dropdown menu uses `position: fixed` and automatically positions itself relative to the trigger. It supports all standard placement options:
+```js
+createDropdownMenu(root, {
+  side: "bottom",     // top, right, bottom, left
+  align: "start",     // start, center, end
+  sideOffset: 4,      // gap from trigger
+  alignOffset: 0,     // shift along alignment axis
+  avoidCollisions: true,
+  collisionPadding: 8,
+});
+```
+When `avoidCollisions` is enabled (default), the menu will:
+- Flip to the opposite side if it would overflow the viewport
+- Shift/clamp to stay within the viewport with the specified padding
+The content element receives `data-side` (computed, may flip) and `data-align` (requested, position may shift) attributes, useful for animations.
+## License
+MIT

package/dist/index.cjs ADDED Viewed

@@ -0,0 +1 @@

+ const e=(e,t)=>e.querySelector(`[data-slot="${t}"]`),t=(e,t)=>[...e.querySelectorAll(`[data-slot="${t}"]`)],n=(e,t)=>[...e.querySelectorAll(`[data-slot="${t}"]`)];let r=0;const i=(e,t)=>e.id||=`${t}-${++r}`,a=(e,t,n)=>{n===null?e.removeAttribute(`aria-${t}`):e.setAttribute(`aria-${t}`,String(n))};function o(e,t,n,r){return e.addEventListener(t,n,r),()=>e.removeEventListener(t,n,r)}const s=(e,t,n)=>e.dispatchEvent(new CustomEvent(t,{bubbles:!0,detail:n})),c={top:`bottom`,bottom:`top`,left:`right`,right:`left`};function l(n,r={}){let{defaultOpen:l=!1,onOpenChange:d,onSelect:f,closeOnClickOutside:p=!0,closeOnEscape:m=!0,closeOnSelect:h=!0,side:g=`bottom`,align:_=`start`,sideOffset:v=4,alignOffset:y=0,avoidCollisions:b=!0,collisionPadding:x=8}=r,S=e(n,`dropdown-menu-trigger`),C=e(n,`dropdown-menu-content`);if(!S||!C)throw Error(`DropdownMenu requires trigger and content slots`);let w=!1,T=null,E=-1,D=``,O=null,k=!1,A=[],j=[],M=[],N=new Map,P=null,F=[],I=e=>e.hasAttribute(`disabled`)||e.hasAttribute(`data-disabled`)||e.getAttribute(`aria-disabled`)===`true`,L=i(S,`dropdown-menu-trigger`),R=i(C,`dropdown-menu-content`);S.setAttribute(`aria-haspopup`,`menu`),S.setAttribute(`aria-controls`,R),C.setAttribute(`role`,`menu`),C.setAttribute(`aria-labelledby`,L),C.tabIndex=-1;let z=()=>{j=t(C,`dropdown-menu-item`);for(let e of j)e.setAttribute(`role`,`menuitem`),e.hasAttribute(`data-disabled`)||e.hasAttribute(`disabled`)?e.setAttribute(`aria-disabled`,`true`):e.removeAttribute(`aria-disabled`),e.tabIndex=-1;M=j.filter(e=>!I(e)),N=new Map(M.map((e,t)=>[e,t]))},B=(e,t,n,r)=>{let i=0,a=0;return e===`top`?a=n.top-r.height-v:e===`bottom`?a=n.bottom+v:i=e===`left`?n.left-r.width-v:n.right+v,e===`top`||e===`bottom`?i=t===`start`?n.left+y:t===`center`?n.left+n.width/2-r.width/2+y:n.right-r.width-y:a=t===`start`?n.top+y:t===`center`?n.top+n.height/2-r.height/2+y:n.bottom-r.height-y,{x:i,y:a}},V=()=>{let e=S.getBoundingClientRect(),t=C.getBoundingClientRect(),n=window.innerWidth,r=window.innerHeight,i=g,a=B(i,_,e,t);if(b){let o=(e,i)=>e===`top`?i.y<x:e===`bottom`?i.y+t.height>r-x:e===`left`?i.x<x:i.x+t.width>n-x;if(o(i,a)){let n=c[i],r=B(n,_,e,t);o(n,r)||(i=n,a=r)}a.x<x?a.x=x:a.x+t.width>n-x&&(a.x=n-t.width-x),a.y<x?a.y=x:a.y+t.height>r-x&&(a.y=r-t.height-x)}C.style.position=`fixed`,C.style.top=`${a.y}px`,C.style.left=`${a.x}px`,C.style.margin=`0`,C.setAttribute(`data-side`,i),C.setAttribute(`data-align`,_)},H=()=>{P===null&&(P=requestAnimationFrame(()=>{P=null,w&&V()}))},U=()=>{P!==null&&(cancelAnimationFrame(P),P=null),F.forEach(e=>e()),F.length=0},W=()=>{if(F.length>0)return;let e=()=>H();window.addEventListener(`resize`,e),window.addEventListener(`scroll`,e,!0),F.push(()=>window.removeEventListener(`resize`,e),()=>window.removeEventListener(`scroll`,e,!0));let t=new ResizeObserver(e);t.observe(S),t.observe(C),F.push(()=>t.disconnect())},G=(e,t=!0)=>{for(let n=0;n<M.length;n++){let r=M[n];n===e?(r.setAttribute(`data-highlighted`,``),t&&r.focus()):r.removeAttribute(`data-highlighted`)}E=e},K=()=>{for(let e of j)e.removeAttribute(`data-highlighted`);E=-1},q=e=>{n.setAttribute(`data-state`,e),C.setAttribute(`data-state`,e)},J=e=>{w!==e&&(e?(T=document.activeElement,w=!0,a(S,`expanded`,!0),C.hidden=!1,q(`open`),z(),k=!1,K(),W(),V(),C.focus()):(w=!1,a(S,`expanded`,!1),C.hidden=!0,q(`closed`),K(),D=``,k=!1,U(),requestAnimationFrame(()=>{T&&document.contains(T)?T.focus():S&&document.contains(S)&&S.focus(),T=null})),s(n,`dropdown-menu:change`,{open:w}),d?.(w))},Y=e=>{if(I(e))return;let t=e.dataset.value||e.textContent?.trim()||``;s(n,`dropdown-menu:select`,{value:t}),f?.(t),h&&J(!1)},X=e=>{let t=M.length;if(t!==0)switch(e.key){case`ArrowDown`:e.preventDefault(),k=!0,G(E===-1?0:(E+1)%t);break;case`ArrowUp`:e.preventDefault(),k=!0,G(E===-1?t-1:(E-1+t)%t);break;case`Home`:e.preventDefault(),k=!0,G(0);break;case`End`:e.preventDefault(),k=!0,G(t-1);break;case`Enter`:case` `:e.preventDefault(),E>=0&&Y(M[E]);break;case`Tab`:J(!1);break;default:e.key.length===1&&!e.ctrlKey&&!e.metaKey&&!e.altKey&&(e.preventDefault(),Z(e.key.toLowerCase()))}},Z=e=>{O&&clearTimeout(O),O=setTimeout(()=>{D=``},500),D+=e;let t=M.findIndex(e=>(e.textContent?.trim().toLowerCase()||``).startsWith(D));if(t===-1&&D.length===1){let n=E+1;for(let r=0;r<M.length;r++){let i=(n+r)%M.length;if((M[i].textContent?.trim().toLowerCase()||``).startsWith(e)){t=i;break}}}t!==-1&&(k=!0,G(t))};a(S,`expanded`,!1),C.hidden=!0,q(`closed`),A.push(o(S,`click`,()=>J(!w)),o(S,`keydown`,e=>{(e.key===`Enter`||e.key===` `||e.key===`ArrowDown`)&&!w&&(e.preventDefault(),J(!0))})),A.push(o(C,`keydown`,X),o(C,`click`,e=>{let t=e.target.closest?.(`[data-slot="dropdown-menu-item"]`);t&&Y(t)}),o(C,`pointermove`,e=>{let t=e.target.closest?.(`[data-slot="dropdown-menu-item"]`);if(!(k&&(k=!1,t&&N.get(t)===E))&&t&&!I(t)){let e=N.get(t);e!==void 0&&e!==E&&G(e,!1)}})),p&&A.push(o(document,`pointerdown`,e=>{let t=e.target;w&&!n.contains(t)&&!C.contains(t)&&J(!1)})),m&&A.push(o(document,`keydown`,e=>{w&&e.key===`Escape`&&(e.preventDefault(),J(!1))}));let Q={open:()=>J(!0),close:()=>J(!1),toggle:()=>J(!w),get isOpen(){return w},destroy:()=>{O&&clearTimeout(O),U(),A.forEach(e=>e()),A.length=0,u.delete(n)}};return l&&J(!0),Q}const u=new WeakSet;function d(e=document){let t=[];for(let r of n(e,`dropdown-menu`)){if(u.has(r))continue;u.add(r),t.push(l(r))}return t}exports.create=d,exports.createDropdownMenu=l;

package/dist/index.d.cts ADDED Viewed

@@ -0,0 +1,88 @@
+//#region src/index.d.ts
+/** Side of the trigger to place the content */
+type Side = "top" | "right" | "bottom" | "left";
+/** Alignment of the content relative to the trigger */
+type Align = "start" | "center" | "end";
+interface DropdownMenuOptions {
+  /** Initial open state */
+  defaultOpen?: boolean;
+  /** Callback when open state changes */
+  onOpenChange?: (open: boolean) => void;
+  /** Callback when an item is selected */
+  onSelect?: (value: string) => void;
+  /** Close when clicking outside */
+  closeOnClickOutside?: boolean;
+  /** Close when pressing Escape */
+  closeOnEscape?: boolean;
+  /** Close when an item is selected */
+  closeOnSelect?: boolean;
+  /**
+   * The preferred side of the trigger to render against.
+   * Will be reversed when collisions occur and `avoidCollisions` is enabled.
+   * @default "bottom"
+   */
+  side?: Side;
+  /**
+   * The preferred alignment against the trigger.
+   * May change when collisions occur.
+   * @default "start"
+   */
+  align?: Align;
+  /**
+   * The distance in pixels from the trigger.
+   * @default 4
+   */
+  sideOffset?: number;
+  /**
+   * An offset in pixels from the "start" or "end" alignment options.
+   * @default 0
+   */
+  alignOffset?: number;
+  /**
+   * When true, overrides side/align preferences to prevent collisions with viewport edges.
+   * @default true
+   */
+  avoidCollisions?: boolean;
+  /**
+   * The padding between the content and the viewport edges when avoiding collisions.
+   * @default 8
+   */
+  collisionPadding?: number;
+}
+interface DropdownMenuController {
+  /** Open the dropdown menu */
+  open(): void;
+  /** Close the dropdown menu */
+  close(): void;
+  /** Toggle the dropdown menu */
+  toggle(): void;
+  /** Current open state */
+  readonly isOpen: boolean;
+  /** Cleanup all event listeners */
+  destroy(): void;
+}
+/**
+ * Create a dropdown menu controller for a root element.
+ *
+ * Supports Radix-compatible positioning props for precise placement:
+ * - `side`: "top" | "right" | "bottom" | "left" (default: "bottom")
+ * - `align`: "start" | "center" | "end" (default: "start")
+ * - `sideOffset`: distance from trigger in px (default: 4)
+ * - `alignOffset`: offset from alignment edge in px (default: 0)
+ * - `avoidCollisions`: flip/shift to stay in viewport (default: true)
+ * - `collisionPadding`: viewport edge padding in px (default: 8)
+ *
+ * ## Events
+ * - **Outbound** `dropdown-menu:change` (on root): Fires when menu opens/closes.
+ *   `event.detail: { open: boolean }`
+ * - **Outbound** `dropdown-menu:select` (on root): Fires when an item is selected.
+ *   `event.detail: { value: string }`
+ */
+declare function createDropdownMenu(root: Element, options?: DropdownMenuOptions): DropdownMenuController;
+/**
+ * Find and bind all dropdown menu components in a scope
+ * Returns array of controllers for programmatic access
+ */
+declare function create(scope?: ParentNode): DropdownMenuController[];
+//#endregion
+export { Align, DropdownMenuController, DropdownMenuOptions, Side, create, createDropdownMenu };

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,88 @@
+//#region src/index.d.ts
+/** Side of the trigger to place the content */
+type Side = "top" | "right" | "bottom" | "left";
+/** Alignment of the content relative to the trigger */
+type Align = "start" | "center" | "end";
+interface DropdownMenuOptions {
+  /** Initial open state */
+  defaultOpen?: boolean;
+  /** Callback when open state changes */
+  onOpenChange?: (open: boolean) => void;
+  /** Callback when an item is selected */
+  onSelect?: (value: string) => void;
+  /** Close when clicking outside */
+  closeOnClickOutside?: boolean;
+  /** Close when pressing Escape */
+  closeOnEscape?: boolean;
+  /** Close when an item is selected */
+  closeOnSelect?: boolean;
+  /**
+   * The preferred side of the trigger to render against.
+   * Will be reversed when collisions occur and `avoidCollisions` is enabled.
+   * @default "bottom"
+   */
+  side?: Side;
+  /**
+   * The preferred alignment against the trigger.
+   * May change when collisions occur.
+   * @default "start"
+   */
+  align?: Align;
+  /**
+   * The distance in pixels from the trigger.
+   * @default 4
+   */
+  sideOffset?: number;
+  /**
+   * An offset in pixels from the "start" or "end" alignment options.
+   * @default 0
+   */
+  alignOffset?: number;
+  /**
+   * When true, overrides side/align preferences to prevent collisions with viewport edges.
+   * @default true
+   */
+  avoidCollisions?: boolean;
+  /**
+   * The padding between the content and the viewport edges when avoiding collisions.
+   * @default 8
+   */
+  collisionPadding?: number;
+}
+interface DropdownMenuController {
+  /** Open the dropdown menu */
+  open(): void;
+  /** Close the dropdown menu */
+  close(): void;
+  /** Toggle the dropdown menu */
+  toggle(): void;
+  /** Current open state */
+  readonly isOpen: boolean;
+  /** Cleanup all event listeners */
+  destroy(): void;
+}
+/**
+ * Create a dropdown menu controller for a root element.
+ *
+ * Supports Radix-compatible positioning props for precise placement:
+ * - `side`: "top" | "right" | "bottom" | "left" (default: "bottom")
+ * - `align`: "start" | "center" | "end" (default: "start")
+ * - `sideOffset`: distance from trigger in px (default: 4)
+ * - `alignOffset`: offset from alignment edge in px (default: 0)
+ * - `avoidCollisions`: flip/shift to stay in viewport (default: true)
+ * - `collisionPadding`: viewport edge padding in px (default: 8)
+ *
+ * ## Events
+ * - **Outbound** `dropdown-menu:change` (on root): Fires when menu opens/closes.
+ *   `event.detail: { open: boolean }`
+ * - **Outbound** `dropdown-menu:select` (on root): Fires when an item is selected.
+ *   `event.detail: { value: string }`
+ */
+declare function createDropdownMenu(root: Element, options?: DropdownMenuOptions): DropdownMenuController;
+/**
+ * Find and bind all dropdown menu components in a scope
+ * Returns array of controllers for programmatic access
+ */
+declare function create(scope?: ParentNode): DropdownMenuController[];
+//#endregion
+export { Align, DropdownMenuController, DropdownMenuOptions, Side, create, createDropdownMenu };

package/dist/index.js ADDED Viewed

@@ -0,0 +1 @@

package/package.json ADDED Viewed

@@ -0,0 +1,44 @@
+{
+  "name": "@data-slot/dropdown-menu",
+  "version": "0.2.2",
+  "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"
+  },
+  "devDependencies": {
+    "@data-slot/core": "workspace:*"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bejamas/data-slot",
+    "directory": "packages/dropdown-menu"
+  },
+  "keywords": [
+    "headless",
+    "ui",
+    "dropdown-menu",
+    "menu",
+    "vanilla",
+    "data-slot"
+  ],
+  "license": "MIT"
+}