@data-slot/combobox 0.2.30

package/README.md

@@ -0,0 +1,207 @@
+# @data-slot/combobox
+
+A headless, accessible combobox component with autocomplete/typeahead filtering.
+
+## Installation
+
+```bash
+npm install @data-slot/combobox
+```
+
+## Usage
+
+### HTML Structure
+
+```html
+<div data-slot="combobox" data-placeholder="Search fruits...">
+  <input data-slot="combobox-input" />
+  <button data-slot="combobox-trigger">▼</button>
+  <div data-slot="combobox-content" hidden>
+    <div data-slot="combobox-list">
+      <div data-slot="combobox-empty">No results found</div>
+      <div data-slot="combobox-group">
+        <div data-slot="combobox-label">Fruits</div>
+        <div data-slot="combobox-item" data-value="apple">Apple</div>
+        <div data-slot="combobox-item" data-value="banana">Banana</div>
+      </div>
+      <div data-slot="combobox-separator"></div>
+      <div data-slot="combobox-item" data-value="other">Other</div>
+    </div>
+  </div>
+</div>
+```
+
+### JavaScript
+
+```javascript
+import { create, createCombobox } from '@data-slot/combobox';
+
+// Auto-discover and bind all comboboxes
+const controllers = create();
+
+// Or bind a specific element
+const root = document.querySelector('[data-slot="combobox"]');
+const controller = createCombobox(root, {
+  defaultValue: 'apple',
+  onValueChange: (value) => console.log('Selected:', value),
+});
+
+// Programmatic control
+controller.open();
+controller.close();
+controller.select('banana');
+controller.clear();
+console.log(controller.value); // 'banana'
+
+// Cleanup
+controller.destroy();
+```
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `combobox` | Root container |
+| `combobox-input` | Text input for filtering |
+| `combobox-trigger` | Optional button that toggles the popup |
+| `combobox-content` | Popup container |
+| `combobox-list` | Scrollable list wrapper |
+| `combobox-item` | Individual selectable option |
+| `combobox-group` | Groups related items |
+| `combobox-label` | Group label (inside a `combobox-group`) |
+| `combobox-separator` | Visual divider between items/groups |
+| `combobox-empty` | Message shown when no items match filter |
+
+### Native Label Support
+
+Use a standard HTML `<label for="...">` element to label the combobox. The `for` attribute should match the `id` on the input. Clicking the label focuses the input, and `aria-labelledby` is set automatically.
+
+```html
+<label for="fruit-input">Choose a fruit</label>
+<div data-slot="combobox">
+  <input data-slot="combobox-input" id="fruit-input" />
+  <div data-slot="combobox-content" hidden>
+    <div data-slot="combobox-list">
+      <div data-slot="combobox-item" data-value="apple">Apple</div>
+    </div>
+  </div>
+</div>
+```
+
+## Options
+
+Options can be passed via JavaScript or data attributes (JS takes precedence).
+
+| Option | Data Attribute | Type | Default | Description |
+|--------|---------------|------|---------|-------------|
+| `defaultValue` | `data-default-value` | `string` | `null` | Initial selected value |
+| `placeholder` | `data-placeholder` | `string` | `""` | Input placeholder text |
+| `disabled` | `data-disabled` | `boolean` | `false` | Disable interaction |
+| `required` | `data-required` | `boolean` | `false` | Form validation required |
+| `name` | `data-name` | `string` | - | Form field name (creates hidden input) |
+| `openOnFocus` | `data-open-on-focus` | `boolean` | `true` | Open popup when input is focused |
+| `autoHighlight` | `data-auto-highlight` | `boolean` | `true` | Auto-highlight first visible item when filtering |
+| `filter` | - | `function` | substring | Custom filter function |
+| `side` | `data-side` | `"top" \| "bottom"` | `"bottom"` | Popup placement |
+| `align` | `data-align` | `"start" \| "center" \| "end"` | `"start"` | Popup alignment |
+| `sideOffset` | `data-side-offset` | `number` | `4` | Distance from input (px) |
+| `alignOffset` | `data-align-offset` | `number` | `0` | Offset from alignment edge (px) |
+| `avoidCollisions` | `data-avoid-collisions` | `boolean` | `true` | Adjust to stay in viewport |
+| `collisionPadding` | `data-collision-padding` | `number` | `8` | Viewport edge padding (px) |
+
+### Callbacks
+
+| Callback | Type | Description |
+|----------|------|-------------|
+| `onValueChange` | `(value: string \| null) => void` | Called when selection changes |
+| `onOpenChange` | `(open: boolean) => void` | Called when popup opens/closes |
+| `onInputValueChange` | `(inputValue: string) => void` | Called when user types in the input |
+
+## Controller API
+
+```typescript
+interface ComboboxController {
+  readonly value: string | null;      // Current selected value
+  readonly inputValue: string;        // Current input text
+  readonly isOpen: boolean;           // Current open state
+  select(value: string): void;        // Select a value
+  clear(): void;                      // Clear selection
+  open(): void;                       // Open the popup
+  close(): void;                      // Close the popup
+  destroy(): void;                    // Cleanup
+}
+```
+
+## Events
+
+### Outbound Events (component emits)
+
+```javascript
+root.addEventListener('combobox:change', (e) => {
+  console.log('Value changed:', e.detail.value);
+});
+
+root.addEventListener('combobox:open-change', (e) => {
+  console.log('Open state:', e.detail.open);
+});
+
+root.addEventListener('combobox:input-change', (e) => {
+  console.log('Input changed:', e.detail.inputValue);
+});
+```
+
+### Inbound Events (component listens)
+
+```javascript
+// Set value
+root.dispatchEvent(new CustomEvent('combobox:set', {
+  detail: { value: 'apple' }
+}));
+
+// Set open state
+root.dispatchEvent(new CustomEvent('combobox:set', {
+  detail: { open: true }
+}));
+```
+
+## Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| `ArrowDown` | Open popup (when closed); move to next visible item |
+| `ArrowUp` | Open popup (when closed); move to previous visible item |
+| `Home` | Move to first visible item |
+| `End` | Move to last visible item |
+| `Enter` | Select highlighted item |
+| `Escape` | Close popup, restore input to committed value |
+| `Tab` | Close popup, restore input, allow normal tab flow |
+
+## Accessibility
+
+- Input: `role="combobox"`, `aria-expanded`, `aria-controls`, `aria-activedescendant`, `aria-autocomplete="list"`
+- List: `role="listbox"`, `aria-labelledby`
+- Item: `role="option"`, `aria-selected`, `aria-disabled`
+- Group: `role="group"`, `aria-labelledby`
+- Disabled items are skipped during keyboard navigation
+
+## Form Integration
+
+When `name` is provided, a hidden input is automatically created for form submission:
+
+```html
+<form>
+  <div data-slot="combobox" data-name="fruit">
+    <input data-slot="combobox-input" />
+    <div data-slot="combobox-content" hidden>
+      <div data-slot="combobox-list">
+        <div data-slot="combobox-item" data-value="apple">Apple</div>
+      </div>
+    </div>
+  </div>
+  <button type="submit">Submit</button>
+</form>
+```
+
+## 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`)),l=[`top`,`bottom`],u=[`start`,`center`,`end`];function d(e,t={}){let n=(0,c.getPart)(e,`combobox-input`),r=(0,c.getPart)(e,`combobox-content`),i=(0,c.getPart)(e,`combobox-list`)??(0,c.getPart)(r??e,`combobox-list`),a=(0,c.getPart)(e,`combobox-trigger`),o=(0,c.getPart)(i??r??e,`combobox-empty`);if(!n||!r)throw Error(`Combobox requires combobox-input and combobox-content slots`);let s=t.defaultValue??(0,c.getDataString)(e,`defaultValue`)??null,d=t.defaultOpen??(0,c.getDataBool)(e,`defaultOpen`)??!1,p=t.placeholder??(0,c.getDataString)(e,`placeholder`)??``,m=t.disabled??(0,c.getDataBool)(e,`disabled`)??!1,h=t.required??(0,c.getDataBool)(e,`required`)??!1,g=t.name??(0,c.getDataString)(e,`name`)??null,_=t.openOnFocus??(0,c.getDataBool)(e,`openOnFocus`)??!0,v=t.autoHighlight??(0,c.getDataBool)(e,`autoHighlight`)??!0,ee=t.filter??null,te=t.onValueChange,y=t.onOpenChange,ne=t.onInputValueChange,re=t.side??(0,c.getDataEnum)(r,`side`,l)??(0,c.getDataEnum)(e,`side`,l)??`bottom`,ie=t.align??(0,c.getDataEnum)(r,`align`,u)??(0,c.getDataEnum)(e,`align`,u)??`start`,b=t.sideOffset??(0,c.getDataNumber)(r,`sideOffset`)??(0,c.getDataNumber)(e,`sideOffset`)??4,ae=t.alignOffset??(0,c.getDataNumber)(r,`alignOffset`)??(0,c.getDataNumber)(e,`alignOffset`)??0,oe=t.avoidCollisions??(0,c.getDataBool)(r,`avoidCollisions`)??(0,c.getDataBool)(e,`avoidCollisions`)??!0,x=t.collisionPadding??(0,c.getDataNumber)(r,`collisionPadding`)??(0,c.getDataNumber)(e,`collisionPadding`)??8,S=!1,C=s,w=-1,T=!1,E=[],D=[],O=[],k=[],A=new Map,j=null,M=(0,c.createPortalLifecycle)({content:r,root:e}),N=e=>e.hasAttribute(`disabled`)||e.hasAttribute(`data-disabled`)||e.getAttribute(`aria-disabled`)===`true`,P=e=>{if(e.dataset.label)return e.dataset.label;let t=``;for(let n of e.childNodes)n.nodeType===Node.TEXT_NODE&&(t+=n.textContent);let n=t.trim();return n||(e.textContent?.trim()??``)},F=e=>e.hasAttribute(`data-value`)?e.getAttribute(`data-value`):void 0,I=e=>{if(e===null)return``;let t=i??r,n=(0,c.getParts)(t,`combobox-item`),a=n.find(t=>F(t)===e);return a?P(a):``},se=(0,c.ensureId)(n,`combobox-input`),L=i??r,ce=(0,c.ensureId)(L,`combobox-list`);n.setAttribute(`role`,`combobox`),n.setAttribute(`aria-autocomplete`,`list`),n.setAttribute(`autocomplete`,`off`),n.setAttribute(`aria-controls`,ce),i?i.setAttribute(`role`,`listbox`):r.setAttribute(`role`,`listbox`),a&&(a.hasAttribute(`type`)||a.setAttribute(`type`,`button`),a.tabIndex=-1,a.setAttribute(`aria-label`,`Toggle`));let R=document.querySelector(`label[for="${CSS.escape(se)}"]`);if(R){let e=(0,c.ensureId)(R,`combobox-label`),t=n.getAttribute(`aria-labelledby`);n.setAttribute(`aria-labelledby`,t?`${t} ${e}`:e),L.setAttribute(`aria-labelledby`,e)}m&&(n.setAttribute(`aria-disabled`,`true`),n.disabled=!0,a&&(a.setAttribute(`aria-disabled`,`true`),a.setAttribute(`data-disabled`,``))),h&&(n.setAttribute(`aria-required`,`true`),n.required=!0);let z=()=>{h&&n.setCustomValidity(C===null?`Please select a value`:``)};p&&(n.placeholder=p),g&&(n.name&&n.removeAttribute(`name`),j=document.createElement(`input`),j.type=`hidden`,j.name=g,j.value=C??``,e.appendChild(j));let B=(e,t,n)=>n.toLowerCase().includes(e.toLowerCase()),V=ee??B,H=()=>{let e=i??r;D=(0,c.getParts)(e,`combobox-item`);for(let e of D){e.setAttribute(`role`,`option`),(0,c.ensureId)(e,`combobox-item`),N(e)?e.setAttribute(`aria-disabled`,`true`):e.removeAttribute(`aria-disabled`);let t=F(e);t===C?((0,c.setAria)(e,`selected`,!0),e.setAttribute(`data-selected`,``)):((0,c.setAria)(e,`selected`,!1),e.removeAttribute(`data-selected`))}let t=(0,c.getParts)(e,`combobox-group`);for(let e of t){e.setAttribute(`role`,`group`);let t=(0,c.getPart)(e,`combobox-label`);if(t){let n=(0,c.ensureId)(t,`combobox-label`);e.setAttribute(`aria-labelledby`,n)}}U()},U=()=>{O=D.filter(e=>!e.hidden),k=O.filter(e=>!N(e)),A=new Map(k.map((e,t)=>[e,t]))},W=(e,t)=>{let n=t===`previous`?e.previousElementSibling:e.nextElementSibling;for(;n;){if(n instanceof HTMLElement&&!n.hidden&&n.dataset.slot!==`combobox-separator`)return!0;n=t===`previous`?n.previousElementSibling:n.nextElementSibling}return!1},G=e=>{let t=i??r,n=e.trim(),a=0;for(let e of D){let t=F(e)??``,r=P(e),i=n===``||V(n,t,r);e.hidden=!i,i&&a++}let s=(0,c.getParts)(t,`combobox-group`);for(let e of s){let t=(0,c.getParts)(e,`combobox-item`),n=t.some(e=>!e.hidden);e.hidden=!n}let l=(0,c.getParts)(t,`combobox-separator`);for(let e of l)e.hidden=!W(e,`previous`)||!W(e,`next`);o&&(o.hidden=a>0),a===0?r.setAttribute(`data-empty`,``):r.removeAttribute(`data-empty`),U()},K=()=>{let t=e.ownerDocument.defaultView??window,n=e.getBoundingClientRect();r.style.minWidth=`${n.width}px`;let i=r.getBoundingClientRect(),a=(0,c.computeFloatingPosition)({anchorRect:n,contentRect:i,side:re,align:ie,sideOffset:b,alignOffset:ae,avoidCollisions:oe,collisionPadding:x,allowedSides:l});r.style.position=`absolute`,r.style.top=`${a.y+t.scrollY}px`,r.style.left=`${a.x+t.scrollX}px`,r.style.margin=`0`,r.setAttribute(`data-side`,a.side),r.setAttribute(`data-align`,a.align)},q=(0,c.createPositionSync)({observedElements:[e,r],isActive:()=>S,ancestorScroll:!1,onUpdate:K,ignoreScrollTarget:e=>e instanceof Node&&r.contains(e)}),le=e=>i&&i.contains(e)&&i.scrollHeight>i.clientHeight?i:r,J=e=>{for(let t=0;t<k.length;t++){let r=k[t];t===e?(r.setAttribute(`data-highlighted`,``),n.setAttribute(`aria-activedescendant`,r.id),(0,c.ensureItemVisibleInContainer)(r,le(r))):r.removeAttribute(`data-highlighted`)}w=e},Y=()=>{for(let e of D)e.removeAttribute(`data-highlighted`);w=-1,n.removeAttribute(`aria-activedescendant`)},X=t=>{e.setAttribute(`data-state`,t),r.setAttribute(`data-state`,t),a&&a.setAttribute(`data-state`,t)},Z=(t,i=!1)=>{if(S!==t&&!(m&&t)){if(t){S=!0,(0,c.setAria)(n,`expanded`,!0),M.mount(),r.hidden=!1,X(`open`),H(),T=!1,G(n.value);let e=k.findIndex(e=>F(e)===C);e>=0?J(e):v&&k.length>0?J(0):Y(),q.start(),K(),q.update(),requestAnimationFrame(()=>{S&&q.update()})}else{S=!1,(0,c.setAria)(n,`expanded`,!1),M.restore(),r.hidden=!0,X(`closed`),Y(),T=!1,q.stop();let e=I(C);n.value=e}(0,c.emit)(e,`combobox:open-change`,{open:S}),y?.(S)}},Q=(t,a=!1)=>{if(C===t&&!a)return;let o=C;C=t,z(),j&&(j.value=t??``),t===null?e.removeAttribute(`data-value`):e.setAttribute(`data-value`,t);let s=i??r,l=D.length>0?D:(0,c.getParts)(s,`combobox-item`);for(let e of l){let n=F(e);n===t?((0,c.setAria)(e,`selected`,!0),e.setAttribute(`data-selected`,``)):((0,c.setAria)(e,`selected`,!1),e.removeAttribute(`data-selected`))}n.value=I(t),!a&&o!==t&&((0,c.emit)(e,`combobox:change`,{value:t}),te?.(t))},$=e=>{if(N(e))return;let t=F(e);t!==void 0&&(Q(t),Z(!1))},ue=e=>{if(!m)switch(e.key){case`ArrowDown`:{if(e.preventDefault(),!S){Z(!0);return}T=!0;let t=k.length;if(t===0)return;J(w===-1?0:(w+1)%t);break}case`ArrowUp`:{if(e.preventDefault(),!S){Z(!0);return}T=!0;let t=k.length;if(t===0)return;J(w===-1?t-1:(w-1+t)%t);break}case`Home`:if(!S)return;e.preventDefault(),T=!0,k.length>0&&J(0);break;case`End`:if(!S)return;e.preventDefault(),T=!0,k.length>0&&J(k.length-1);break;case`Enter`:if(!S)return;e.preventDefault(),w>=0&&w<k.length&&$(k[w]);break;case`Escape`:S?(e.preventDefault(),Z(!1)):C!==null&&(e.preventDefault(),Q(null));break;case`Tab`:S&&Z(!1,!0);break}},de=()=>{let t=n.value;(0,c.emit)(e,`combobox:input-change`,{inputValue:t}),ne?.(t),S?(G(t),v&&k.length>0?J(0):Y(),q.update()):Z(!0)},fe=()=>{m||(n.select(),_&&!S&&Z(!0))};(0,c.setAria)(n,`expanded`,!1),r.hidden=!0,X(`closed`),Q(C,!0),E.push((0,c.on)(n,`input`,de),(0,c.on)(n,`keydown`,ue),(0,c.on)(n,`focus`,fe)),a&&E.push((0,c.on)(a,`click`,()=>{m||(S?Z(!1):(Z(!0),n.focus()))})),E.push((0,c.on)(r,`click`,e=>{let t=e.target.closest?.(`[data-slot="combobox-item"]`);t&&!t.hidden&&$(t)}),(0,c.on)(r,`pointermove`,e=>{let t=e.target.closest?.(`[data-slot="combobox-item"]`);if(!(T&&(T=!1,t&&A.get(t)===w)))if(t&&!N(t)&&!t.hidden){let e=A.get(t);e!==void 0&&e!==w&&J(e)}else Y()}),(0,c.on)(r,`pointerleave`,()=>{T||Y()}),(0,c.on)(r,`mousedown`,e=>{e.preventDefault()})),E.push((0,c.createDismissLayer)({root:e,isOpen:()=>S,onDismiss:()=>Z(!1),closeOnClickOutside:!0,closeOnEscape:!1})),E.push((0,c.on)(e,`combobox:set`,e=>{let t=e.detail;t?.value!==void 0&&Q(t.value),t?.open!==void 0&&Z(t.open),t?.inputValue!==void 0&&(n.value=t.inputValue)}));let pe={get value(){return C},get inputValue(){return n.value},get isOpen(){return S},select:e=>Q(e),clear:()=>Q(null),open:()=>Z(!0),close:()=>Z(!1),destroy:()=>{q.stop(),M.cleanup(),E.forEach(e=>e()),E.length=0,j&&j.parentNode&&j.parentNode.removeChild(j),f.delete(e)}};return d&&Z(!0),pe}const f=new WeakSet;function p(e=document){let t=[];for(let n of(0,c.getRoots)(e,`combobox`)){if(f.has(n))continue;f.add(n),t.push(d(n))}return t}exports.create=p,exports.createCombobox=d;

package/dist/index.d.cts

@@ -0,0 +1,82 @@
+//#region src/index.d.ts
+/** Side of the input to place the content */
+type Side = "top" | "bottom";
+/** Alignment of the content relative to the input */
+type Align = "start" | "center" | "end";
+interface ComboboxOptions {
+  /** Initial selected value */
+  defaultValue?: string;
+  /** Callback when value changes */
+  onValueChange?: (value: string | null) => void;
+  /** Initial open state */
+  defaultOpen?: boolean;
+  /** Callback when open state changes */
+  onOpenChange?: (open: boolean) => void;
+  /** Callback when user types in the input (not on programmatic syncs) */
+  onInputValueChange?: (inputValue: string) => void;
+  /** Placeholder text for the input */
+  placeholder?: string;
+  /** Disable interaction */
+  disabled?: boolean;
+  /** Form validation required */
+  required?: boolean;
+  /** Form field name (auto-creates hidden input) */
+  name?: string;
+  /** Open popup when input receives focus @default true */
+  openOnFocus?: boolean;
+  /** Auto-highlight first visible item when filtering @default true */
+  autoHighlight?: boolean;
+  /** Custom filter function. Return true to show item. */
+  filter?: (inputValue: string, itemValue: string, itemLabel: string) => boolean;
+  /** @default "bottom" */
+  side?: Side;
+  /** @default "start" */
+  align?: Align;
+  /** @default 4 */
+  sideOffset?: number;
+  /** @default 0 */
+  alignOffset?: number;
+  /** @default true */
+  avoidCollisions?: boolean;
+  /** @default 8 */
+  collisionPadding?: number;
+}
+interface ComboboxController {
+  /** Current selected value */
+  readonly value: string | null;
+  /** Current input text */
+  readonly inputValue: string;
+  /** Current open state */
+  readonly isOpen: boolean;
+  /** Select a value programmatically */
+  select(value: string): void;
+  /** Clear selected value */
+  clear(): void;
+  /** Open the popup */
+  open(): void;
+  /** Close the popup */
+  close(): void;
+  /** Cleanup all event listeners */
+  destroy(): void;
+}
+/**
+ * Create a combobox controller for a root element.
+ *
+ * ## Events
+ * - **Outbound** `combobox:change` (on root): Fires when value changes.
+ *   `event.detail: { value: string | null }`
+ * - **Outbound** `combobox:open-change` (on root): Fires when popup opens/closes.
+ *   `event.detail: { open: boolean }`
+ * - **Outbound** `combobox:input-change` (on root): Fires when user types.
+ *   `event.detail: { inputValue: string }`
+ * - **Inbound** `combobox:set` (on root): Set value, open state, or input value.
+ *   `event.detail: { value?: string | null, open?: boolean, inputValue?: string }`
+ */
+declare function createCombobox(root: Element, options?: ComboboxOptions): ComboboxController;
+/**
+ * Find and bind all combobox components in a scope
+ * Returns array of controllers for programmatic access
+ */
+declare function create(scope?: ParentNode): ComboboxController[];
+//#endregion
+export { Align, ComboboxController, ComboboxOptions, Side, create, createCombobox };

package/dist/index.d.ts

@@ -0,0 +1,82 @@
+//#region src/index.d.ts
+/** Side of the input to place the content */
+type Side = "top" | "bottom";
+/** Alignment of the content relative to the input */
+type Align = "start" | "center" | "end";
+interface ComboboxOptions {
+  /** Initial selected value */
+  defaultValue?: string;
+  /** Callback when value changes */
+  onValueChange?: (value: string | null) => void;
+  /** Initial open state */
+  defaultOpen?: boolean;
+  /** Callback when open state changes */
+  onOpenChange?: (open: boolean) => void;
+  /** Callback when user types in the input (not on programmatic syncs) */
+  onInputValueChange?: (inputValue: string) => void;
+  /** Placeholder text for the input */
+  placeholder?: string;
+  /** Disable interaction */
+  disabled?: boolean;
+  /** Form validation required */
+  required?: boolean;
+  /** Form field name (auto-creates hidden input) */
+  name?: string;
+  /** Open popup when input receives focus @default true */
+  openOnFocus?: boolean;
+  /** Auto-highlight first visible item when filtering @default true */
+  autoHighlight?: boolean;
+  /** Custom filter function. Return true to show item. */
+  filter?: (inputValue: string, itemValue: string, itemLabel: string) => boolean;
+  /** @default "bottom" */
+  side?: Side;
+  /** @default "start" */
+  align?: Align;
+  /** @default 4 */
+  sideOffset?: number;
+  /** @default 0 */
+  alignOffset?: number;
+  /** @default true */
+  avoidCollisions?: boolean;
+  /** @default 8 */
+  collisionPadding?: number;
+}
+interface ComboboxController {
+  /** Current selected value */
+  readonly value: string | null;
+  /** Current input text */
+  readonly inputValue: string;
+  /** Current open state */
+  readonly isOpen: boolean;
+  /** Select a value programmatically */
+  select(value: string): void;
+  /** Clear selected value */
+  clear(): void;
+  /** Open the popup */
+  open(): void;
+  /** Close the popup */
+  close(): void;
+  /** Cleanup all event listeners */
+  destroy(): void;
+}
+/**
+ * Create a combobox controller for a root element.
+ *
+ * ## Events
+ * - **Outbound** `combobox:change` (on root): Fires when value changes.
+ *   `event.detail: { value: string | null }`
+ * - **Outbound** `combobox:open-change` (on root): Fires when popup opens/closes.
+ *   `event.detail: { open: boolean }`
+ * - **Outbound** `combobox:input-change` (on root): Fires when user types.
+ *   `event.detail: { inputValue: string }`
+ * - **Inbound** `combobox:set` (on root): Set value, open state, or input value.
+ *   `event.detail: { value?: string | null, open?: boolean, inputValue?: string }`
+ */
+declare function createCombobox(root: Element, options?: ComboboxOptions): ComboboxController;
+/**
+ * Find and bind all combobox components in a scope
+ * Returns array of controllers for programmatic access
+ */
+declare function create(scope?: ParentNode): ComboboxController[];
+//#endregion
+export { Align, ComboboxController, ComboboxOptions, Side, create, createCombobox };

package/dist/index.js

@@ -0,0 +1 @@
+import{computeFloatingPosition as e,createDismissLayer as t,createPortalLifecycle as n,createPositionSync as r,emit as i,ensureId as a,ensureItemVisibleInContainer as ee,getDataBool as o,getDataEnum as s,getDataNumber as c,getDataString as l,getPart as u,getParts as d,getRoots as f,on as p,setAria as m}from"@data-slot/core";const h=[`top`,`bottom`],g=[`start`,`center`,`end`];function _(f,_={}){let y=u(f,`combobox-input`),b=u(f,`combobox-content`),x=u(f,`combobox-list`)??u(b??f,`combobox-list`),S=u(f,`combobox-trigger`),C=u(x??b??f,`combobox-empty`);if(!y||!b)throw Error(`Combobox requires combobox-input and combobox-content slots`);let te=_.defaultValue??l(f,`defaultValue`)??null,ne=_.defaultOpen??o(f,`defaultOpen`)??!1,w=_.placeholder??l(f,`placeholder`)??``,T=_.disabled??o(f,`disabled`)??!1,E=_.required??o(f,`required`)??!1,re=_.name??l(f,`name`)??null,ie=_.openOnFocus??o(f,`openOnFocus`)??!0,ae=_.autoHighlight??o(f,`autoHighlight`)??!0,oe=_.filter??null,se=_.onValueChange,ce=_.onOpenChange,le=_.onInputValueChange,ue=_.side??s(b,`side`,h)??s(f,`side`,h)??`bottom`,de=_.align??s(b,`align`,g)??s(f,`align`,g)??`start`,fe=_.sideOffset??c(b,`sideOffset`)??c(f,`sideOffset`)??4,pe=_.alignOffset??c(b,`alignOffset`)??c(f,`alignOffset`)??0,me=_.avoidCollisions??o(b,`avoidCollisions`)??o(f,`avoidCollisions`)??!0,he=_.collisionPadding??c(b,`collisionPadding`)??c(f,`collisionPadding`)??8,D=!1,O=te,k=-1,A=!1,j=[],M=[],N=[],P=[],F=new Map,I=null,L=n({content:b,root:f}),R=e=>e.hasAttribute(`disabled`)||e.hasAttribute(`data-disabled`)||e.getAttribute(`aria-disabled`)===`true`,z=e=>{if(e.dataset.label)return e.dataset.label;let t=``;for(let n of e.childNodes)n.nodeType===Node.TEXT_NODE&&(t+=n.textContent);let n=t.trim();return n||(e.textContent?.trim()??``)},B=e=>e.hasAttribute(`data-value`)?e.getAttribute(`data-value`):void 0,V=e=>{if(e===null)return``;let t=x??b,n=d(t,`combobox-item`),r=n.find(t=>B(t)===e);return r?z(r):``},ge=a(y,`combobox-input`),H=x??b,_e=a(H,`combobox-list`);y.setAttribute(`role`,`combobox`),y.setAttribute(`aria-autocomplete`,`list`),y.setAttribute(`autocomplete`,`off`),y.setAttribute(`aria-controls`,_e),x?x.setAttribute(`role`,`listbox`):b.setAttribute(`role`,`listbox`),S&&(S.hasAttribute(`type`)||S.setAttribute(`type`,`button`),S.tabIndex=-1,S.setAttribute(`aria-label`,`Toggle`));let U=document.querySelector(`label[for="${CSS.escape(ge)}"]`);if(U){let e=a(U,`combobox-label`),t=y.getAttribute(`aria-labelledby`);y.setAttribute(`aria-labelledby`,t?`${t} ${e}`:e),H.setAttribute(`aria-labelledby`,e)}T&&(y.setAttribute(`aria-disabled`,`true`),y.disabled=!0,S&&(S.setAttribute(`aria-disabled`,`true`),S.setAttribute(`data-disabled`,``))),E&&(y.setAttribute(`aria-required`,`true`),y.required=!0);let ve=()=>{E&&y.setCustomValidity(O===null?`Please select a value`:``)};w&&(y.placeholder=w),re&&(y.name&&y.removeAttribute(`name`),I=document.createElement(`input`),I.type=`hidden`,I.name=re,I.value=O??``,f.appendChild(I));let ye=(e,t,n)=>n.toLowerCase().includes(e.toLowerCase()),be=oe??ye,xe=()=>{let e=x??b;M=d(e,`combobox-item`);for(let e of M){e.setAttribute(`role`,`option`),a(e,`combobox-item`),R(e)?e.setAttribute(`aria-disabled`,`true`):e.removeAttribute(`aria-disabled`);let t=B(e);t===O?(m(e,`selected`,!0),e.setAttribute(`data-selected`,``)):(m(e,`selected`,!1),e.removeAttribute(`data-selected`))}let t=d(e,`combobox-group`);for(let e of t){e.setAttribute(`role`,`group`);let t=u(e,`combobox-label`);if(t){let n=a(t,`combobox-label`);e.setAttribute(`aria-labelledby`,n)}}W()},W=()=>{N=M.filter(e=>!e.hidden),P=N.filter(e=>!R(e)),F=new Map(P.map((e,t)=>[e,t]))},G=(e,t)=>{let n=t===`previous`?e.previousElementSibling:e.nextElementSibling;for(;n;){if(n instanceof HTMLElement&&!n.hidden&&n.dataset.slot!==`combobox-separator`)return!0;n=t===`previous`?n.previousElementSibling:n.nextElementSibling}return!1},K=e=>{let t=x??b,n=e.trim(),r=0;for(let e of M){let t=B(e)??``,i=z(e),a=n===``||be(n,t,i);e.hidden=!a,a&&r++}let i=d(t,`combobox-group`);for(let e of i){let t=d(e,`combobox-item`),n=t.some(e=>!e.hidden);e.hidden=!n}let a=d(t,`combobox-separator`);for(let e of a)e.hidden=!G(e,`previous`)||!G(e,`next`);C&&(C.hidden=r>0),r===0?b.setAttribute(`data-empty`,``):b.removeAttribute(`data-empty`),W()},Se=()=>{let t=f.ownerDocument.defaultView??window,n=f.getBoundingClientRect();b.style.minWidth=`${n.width}px`;let r=b.getBoundingClientRect(),i=e({anchorRect:n,contentRect:r,side:ue,align:de,sideOffset:fe,alignOffset:pe,avoidCollisions:me,collisionPadding:he,allowedSides:h});b.style.position=`absolute`,b.style.top=`${i.y+t.scrollY}px`,b.style.left=`${i.x+t.scrollX}px`,b.style.margin=`0`,b.setAttribute(`data-side`,i.side),b.setAttribute(`data-align`,i.align)},q=r({observedElements:[f,b],isActive:()=>D,ancestorScroll:!1,onUpdate:Se,ignoreScrollTarget:e=>e instanceof Node&&b.contains(e)}),Ce=e=>x&&x.contains(e)&&x.scrollHeight>x.clientHeight?x:b,J=e=>{for(let t=0;t<P.length;t++){let n=P[t];t===e?(n.setAttribute(`data-highlighted`,``),y.setAttribute(`aria-activedescendant`,n.id),ee(n,Ce(n))):n.removeAttribute(`data-highlighted`)}k=e},Y=()=>{for(let e of M)e.removeAttribute(`data-highlighted`);k=-1,y.removeAttribute(`aria-activedescendant`)},X=e=>{f.setAttribute(`data-state`,e),b.setAttribute(`data-state`,e),S&&S.setAttribute(`data-state`,e)},Z=(e,t=!1)=>{if(D!==e&&!(T&&e)){if(e){D=!0,m(y,`expanded`,!0),L.mount(),b.hidden=!1,X(`open`),xe(),A=!1,K(y.value);let e=P.findIndex(e=>B(e)===O);e>=0?J(e):ae&&P.length>0?J(0):Y(),q.start(),Se(),q.update(),requestAnimationFrame(()=>{D&&q.update()})}else{D=!1,m(y,`expanded`,!1),L.restore(),b.hidden=!0,X(`closed`),Y(),A=!1,q.stop();let e=V(O);y.value=e}i(f,`combobox:open-change`,{open:D}),ce?.(D)}},Q=(e,t=!1)=>{if(O===e&&!t)return;let n=O;O=e,ve(),I&&(I.value=e??``),e===null?f.removeAttribute(`data-value`):f.setAttribute(`data-value`,e);let r=x??b,a=M.length>0?M:d(r,`combobox-item`);for(let t of a){let n=B(t);n===e?(m(t,`selected`,!0),t.setAttribute(`data-selected`,``)):(m(t,`selected`,!1),t.removeAttribute(`data-selected`))}y.value=V(e),!t&&n!==e&&(i(f,`combobox:change`,{value:e}),se?.(e))},$=e=>{if(R(e))return;let t=B(e);t!==void 0&&(Q(t),Z(!1))},we=e=>{if(!T)switch(e.key){case`ArrowDown`:{if(e.preventDefault(),!D){Z(!0);return}A=!0;let t=P.length;if(t===0)return;J(k===-1?0:(k+1)%t);break}case`ArrowUp`:{if(e.preventDefault(),!D){Z(!0);return}A=!0;let t=P.length;if(t===0)return;J(k===-1?t-1:(k-1+t)%t);break}case`Home`:if(!D)return;e.preventDefault(),A=!0,P.length>0&&J(0);break;case`End`:if(!D)return;e.preventDefault(),A=!0,P.length>0&&J(P.length-1);break;case`Enter`:if(!D)return;e.preventDefault(),k>=0&&k<P.length&&$(P[k]);break;case`Escape`:D?(e.preventDefault(),Z(!1)):O!==null&&(e.preventDefault(),Q(null));break;case`Tab`:D&&Z(!1,!0);break}},Te=()=>{let e=y.value;i(f,`combobox:input-change`,{inputValue:e}),le?.(e),D?(K(e),ae&&P.length>0?J(0):Y(),q.update()):Z(!0)},Ee=()=>{T||(y.select(),ie&&!D&&Z(!0))};m(y,`expanded`,!1),b.hidden=!0,X(`closed`),Q(O,!0),j.push(p(y,`input`,Te),p(y,`keydown`,we),p(y,`focus`,Ee)),S&&j.push(p(S,`click`,()=>{T||(D?Z(!1):(Z(!0),y.focus()))})),j.push(p(b,`click`,e=>{let t=e.target.closest?.(`[data-slot="combobox-item"]`);t&&!t.hidden&&$(t)}),p(b,`pointermove`,e=>{let t=e.target.closest?.(`[data-slot="combobox-item"]`);if(!(A&&(A=!1,t&&F.get(t)===k)))if(t&&!R(t)&&!t.hidden){let e=F.get(t);e!==void 0&&e!==k&&J(e)}else Y()}),p(b,`pointerleave`,()=>{A||Y()}),p(b,`mousedown`,e=>{e.preventDefault()})),j.push(t({root:f,isOpen:()=>D,onDismiss:()=>Z(!1),closeOnClickOutside:!0,closeOnEscape:!1})),j.push(p(f,`combobox:set`,e=>{let t=e.detail;t?.value!==void 0&&Q(t.value),t?.open!==void 0&&Z(t.open),t?.inputValue!==void 0&&(y.value=t.inputValue)}));let De={get value(){return O},get inputValue(){return y.value},get isOpen(){return D},select:e=>Q(e),clear:()=>Q(null),open:()=>Z(!0),close:()=>Z(!1),destroy:()=>{q.stop(),L.cleanup(),j.forEach(e=>e()),j.length=0,I&&I.parentNode&&I.parentNode.removeChild(I),v.delete(f)}};return ne&&Z(!0),De}const v=new WeakSet;function y(e=document){let t=[];for(let n of f(e,`combobox`)){if(v.has(n))continue;v.add(n),t.push(_(n))}return t}export{y as create,_ as createCombobox};

package/package.json

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