@skdx/react 0.26.0

package/dist/combobox/Combobox.js

@@ -0,0 +1 @@
+import*as o from"react";import{createSafeContext as xe}from"../utils/createContext.js";import{formValidityHandle as Ce,useFormReset as Re}from"../utils/formControl.js";import{HiddenInput as ge}from"../utils/hiddenInput.js";import{announce as ye}from"../utils/liveAnnouncer.js";import{PopperRoot as Ie}from"../utils/popper.js";import{useControllableState as $}from"../utils/useControllableState.js";import{useOpenChangeComplete as he}from"../utils/useOpenChangeComplete.js";import{useSelection as Pe}from"../utils/useSelection.js";import{jsx as z,jsxs as He}from"react/jsx-runtime";var H='[role="option"]:not([data-disabled])';function ve(a){return`${a} result${a===1?"":"s"} available`}var[Ee,C]=xe("Combobox"),we=o.forwardRef(function({children:c,value:e,defaultValue:l,onValueChange:g,multiple:s=!1,allowCustomValue:t=!1,filter:x="manual",autoHighlight:m=!1,loading:R=!1,inputValue:n,defaultInputValue:f="",onInputValueChange:u,open:y,defaultOpen:A=!1,onOpenChange:I,onOpenChangeComplete:oe,invalid:ne=!1,readOnly:re=!1,getResultCountLabel:V=ve,name:N,required:q=!1},ae){let F=o.useRef(null),W=o.useRef(null),h=o.useRef(null),[P,v]=o.useState(null),[M,K]=o.useState(()=>new Map),S=o.useRef(null),{selectedValues:T,isSelected:ie,selectItem:_,setSelection:se}=Pe({value:e,defaultValue:l,onValueChange:g,multiple:s}),[L="",E]=$({prop:n,defaultProp:f,onChange:u}),[p=!1,w]=$({prop:y,defaultProp:A,onChange:I});he(p,h,oe);let[le,me]=o.useState(p);p!==le&&(me(p),p||v(null)),o.useEffect(()=>{if(!p)return;let r=requestAnimationFrame(()=>{let i=S.current;if(S.current=null,!i)return;let d=h.current?.querySelectorAll(H);if(!d||d.length===0)return;let k=i==="last"?d[d.length-1]:d[0];v(D=>D??k.id)});return()=>cancelAnimationFrame(r)},[p]);let O=M.size;o.useLayoutEffect(()=>{if(P===null)return;let r=Array.from(h.current?.querySelectorAll(H)??[]);r.some(i=>i.id===P)||v(r[0]?.id??null)}),o.useEffect(()=>{if(!m||!p||P!==null)return;let r=requestAnimationFrame(()=>{let i=h.current?.querySelector(H);i&&v(i.id)});return()=>cancelAnimationFrame(r)},[m,p,P,O]),o.useEffect(()=>{!p||R||ye(V(O))},[p,R,O,V]);let ue=o.useCallback(r=>{S.current=r,w(!0)},[w]),ce=o.useCallback((r,i)=>{K(d=>{let k=d.get(r);if(k?.value===i.value&&k.text===i.text)return d;let D=new Map(d);return D.set(r,i),D})},[]),fe=o.useCallback(r=>{K(i=>{if(!i.has(r))return i;let d=new Map(i);return d.delete(r),d})},[]),pe=o.useCallback(r=>M.get(r),[M]),de=o.useCallback(r=>x==="manual"||x(r,L),[x,L]),be=o.useCallback((r,i)=>{if(_(r),!s){E(i),w(!1);return}E("")},[_,s,E,w]);return o.useImperativeHandle(ae,()=>Ce(W),[]),Re(F,()=>{l!==void 0&&se(l),E(f)}),z(Ie,{children:He(Ee,{inputRef:F,contentRef:h,contentId:o.useId(),multiple:s,selectedValues:T,isSelected:ie,selectItem:be,inputValue:L,onInputValueChange:E,open:p,onOpenChange:w,activeId:P,setActiveId:v,openWithHighlight:ue,itemCount:O,registerItem:ce,unregisterItem:fe,getItem:pe,matchesFilter:de,invalid:ne,readOnly:re,loading:R,allowCustomValue:t,required:q,children:[c,N&&(T.length>0?T:[""]).map((r,i)=>z(ge,{ref:i===0?W:void 0,type:"text",name:N,value:r,required:q},r||i))]})})});we.displayName="Combobox";import*as B from"react";import{useComposedRefs as Oe}from"../utils/composeRefs.js";import{skdxPart as ke}from"../utils/part.js";import{PopperAnchor as De}from"../utils/popper.js";import{composeEventHandlers as G,Primitive as Ae}from"../utils/primitive.js";import{jsx as U}from"react/jsx-runtime";var J=B.forwardRef((a,c)=>{let e=C("ComboboxInput"),l=Oe(c,e.inputRef),g=t=>{let x=e.contentRef.current;if(!x)return;let m=Array.from(x.querySelectorAll(H));if(m.length===0)return;let n=m.findIndex(f=>f.id===e.activeId)+t;n<0&&(n=0),n>=m.length&&(n=m.length-1),e.setActiveId(m[n].id)},s=()=>{if(!e.activeId)return;let t=e.getItem(e.activeId);t&&e.selectItem(t.value,t.text||t.value)};return U(De,{asChild:!0,children:U(Ae.input,{type:"text",role:"combobox","aria-expanded":e.open,"aria-controls":e.contentId,"aria-autocomplete":"list","aria-activedescendant":e.activeId??void 0,autoComplete:"off",readOnly:e.readOnly,"aria-invalid":e.invalid?!0:void 0,"aria-required":e.required?!0:void 0,"aria-readonly":e.readOnly?!0:void 0,"aria-busy":e.loading?!0:void 0,"data-invalid":e.invalid?"":void 0,"data-readonly":e.readOnly?"":void 0,"data-loading":e.loading?"":void 0,"data-multiple":e.multiple?"":void 0,...a,...ke("combobox","input",a.className),ref:l,value:e.inputValue,onChange:G(a.onChange,t=>{e.onInputValueChange(t.target.value),e.open||e.onOpenChange(!0)}),onKeyDown:G(a.onKeyDown,t=>{t.key==="ArrowDown"?(t.preventDefault(),e.open?g(1):e.openWithHighlight("first")):t.key==="ArrowUp"?(t.preventDefault(),e.open?g(-1):e.openWithHighlight("last")):t.key==="Enter"?e.activeId?(t.preventDefault(),s()):e.allowCustomValue&&e.inputValue!==""&&(t.preventDefault(),e.selectItem(e.inputValue,e.inputValue)):t.key==="Escape"&&e.open&&!e.contentRef.current&&(t.preventDefault(),e.onOpenChange(!1))})})})});J.displayName="ComboboxInput";import{Portal as Me}from"../utils/portal.js";import{jsx as Se}from"react/jsx-runtime";var Q=({forceMount:a,children:c,...e})=>{let l=C("ComboboxPortal");return a||l.open?Se(Me,{...e,children:c}):null};Q.displayName="ComboboxPortal";import*as X from"react";import{useComposedRefs as Te}from"../utils/composeRefs.js";import{skdxPart as Le}from"../utils/part.js";import{PopperContent as Ve}from"../utils/popper.js";import{composeEventHandlers as Ne}from"../utils/primitive.js";import{useDismiss as qe}from"../utils/useDismiss.js";import{jsx as Fe}from"react/jsx-runtime";var Y=X.forwardRef(({forceMount:a,side:c="bottom",align:e="start",sideOffset:l=4,onEscapeKeyDown:g,onPointerDownOutside:s,onFocusOutside:t,onInteractOutside:x,...m},R)=>{let n=C("ComboboxContent"),f=Te(R,n.contentRef);return qe({enabled:n.open,onEscapeKeyDown:u=>{g?.(u),u.defaultPrevented||n.onOpenChange(!1)},onInteractOutside:x,onPointerDownOutside:u=>{s?.(u),u.defaultPrevented||n.onOpenChange(!1)},onFocusOutside:u=>{t?.(u),u.defaultPrevented||n.onOpenChange(!1)}},[n.contentRef,n.inputRef]),a||n.open?Fe(Ve,{component:"combobox",role:"listbox",id:n.contentId,"aria-multiselectable":n.multiple?!0:void 0,"aria-busy":n.loading?!0:void 0,"data-state":n.open?"open":"closed","data-loading":n.loading?"":void 0,"data-multiple":n.multiple?"":void 0,side:c,align:e,sideOffset:l,...m,...Le("combobox","content",m.className),ref:f,onMouseDown:Ne(m.onMouseDown,u=>u.preventDefault())}):null});Y.displayName="ComboboxContent";import*as b from"react";import{useComposedRefs as We}from"../utils/composeRefs.js";import{skdxPart as Ke}from"../utils/part.js";import{composeEventHandlers as Z,Primitive as _e}from"../utils/primitive.js";import{jsx as $e}from"react/jsx-runtime";var j=b.forwardRef(({value:a,disabled:c,textValue:e,...l},g)=>{let s=C("ComboboxItem"),t=b.useId(),x=b.useRef(null),m=We(g,x),R=s.isSelected(a),n=s.activeId===t,[f,u]=b.useState(e??null);b.useLayoutEffect(()=>{let I=e??x.current?.textContent;I!=null&&I!==f&&u(I)});let y=f===null||s.matchesFilter(f);b.useEffect(()=>{if(y)return s.registerItem(t,{value:a,text:f??""}),()=>s.unregisterItem(t)},[t,y,a,f]);let A=()=>{c||(s.selectItem(a,f??a),s.inputRef.current?.focus())};return y?$e(_e.div,{role:"option",id:t,"data-value":a,"aria-selected":R,"data-state":R?"checked":"unchecked","data-highlighted":n?"":void 0,"data-disabled":c?"":void 0,...l,...Ke("combobox","item",l.className),ref:m,onClick:Z(l.onClick,A),onPointerEnter:Z(l.onPointerEnter,()=>{c||s.setActiveId(t)})}):null});j.displayName="ComboboxItem";import*as ee from"react";import{skdxPart as ze}from"../utils/part.js";import{Primitive as Ge}from"../utils/primitive.js";import{jsx as Ue}from"react/jsx-runtime";var te=ee.forwardRef((a,c)=>C("ComboboxEmpty").itemCount===0?Ue(Ge.div,{role:"presentation",...a,...ze("combobox","empty",a.className),ref:c}):null);te.displayName="ComboboxEmpty";export{we as Combobox,Y as ComboboxContent,te as ComboboxEmpty,J as ComboboxInput,j as ComboboxItem,Q as ComboboxPortal,Ee as ComboboxProvider,H as OPTION_SELECTOR,ve as defaultGetResultCountLabel,C as useComboboxContext};

package/dist/combobox/ComboboxContent.d.cts

@@ -0,0 +1,27 @@
+import * as React from 'react';
+import type { ComboboxContentProps } from './types.cjs';
+/**
+ * The listbox popup for a {@link Combobox}, positioned relative to the input
+ * via floating-ui (see {@link ComboboxContentProps}). Renders a
+ * `<div role="listbox">` with `data-state` and `data-side`/`data-align` from
+ * the popper, plus `aria-multiselectable="true"` while the root is `multiple`
+ * and `aria-busy`/`data-loading` while it is `loading`. Prevents `mousedown`
+ * from stealing focus off the input (real DOM focus must never leave
+ * `ComboboxInput`). Unmounts when closed unless `forceMount` is set.
+ *
+ * Closes on Escape (leaving focus on the input, which never lost it) or on an
+ * outside interaction — pointer-down outside or focus moving outside, each
+ * reported to `onPointerDownOutside`/`onFocusOutside` and, just before them and
+ * with the same event, to `onInteractOutside`. Any of those (or
+ * `onEscapeKeyDown`) calling `event.preventDefault()` keeps it open. The input
+ * counts as inside: clicking or tabbing back into it is not an outside
+ * interaction.
+ *
+ * @example
+ * ```tsx
+ * <ComboboxContent>
+ *   <ComboboxItem value="Apple">Apple</ComboboxItem>
+ * </ComboboxContent>
+ * ```
+ */
+export declare const ComboboxContent: React.ForwardRefExoticComponent<Omit<ComboboxContentProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/combobox/ComboboxContent.d.ts

@@ -0,0 +1,27 @@
+import * as React from 'react';
+import type { ComboboxContentProps } from './types.js';
+/**
+ * The listbox popup for a {@link Combobox}, positioned relative to the input
+ * via floating-ui (see {@link ComboboxContentProps}). Renders a
+ * `<div role="listbox">` with `data-state` and `data-side`/`data-align` from
+ * the popper, plus `aria-multiselectable="true"` while the root is `multiple`
+ * and `aria-busy`/`data-loading` while it is `loading`. Prevents `mousedown`
+ * from stealing focus off the input (real DOM focus must never leave
+ * `ComboboxInput`). Unmounts when closed unless `forceMount` is set.
+ *
+ * Closes on Escape (leaving focus on the input, which never lost it) or on an
+ * outside interaction — pointer-down outside or focus moving outside, each
+ * reported to `onPointerDownOutside`/`onFocusOutside` and, just before them and
+ * with the same event, to `onInteractOutside`. Any of those (or
+ * `onEscapeKeyDown`) calling `event.preventDefault()` keeps it open. The input
+ * counts as inside: clicking or tabbing back into it is not an outside
+ * interaction.
+ *
+ * @example
+ * ```tsx
+ * <ComboboxContent>
+ *   <ComboboxItem value="Apple">Apple</ComboboxItem>
+ * </ComboboxContent>
+ * ```
+ */
+export declare const ComboboxContent: React.ForwardRefExoticComponent<Omit<ComboboxContentProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/combobox/ComboboxEmpty.d.cts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import type { ComboboxEmptyProps } from './types.cjs';
+/**
+ * Fallback shown in place of the item list when no `ComboboxItem`s are
+ * currently rendered — because the consumer's filtered results are empty, or
+ * because the root's `filter` predicate rejected every item. Renders a
+ * `<div role="presentation">`; renders nothing while at least one item is
+ * registered.
+ *
+ * @example
+ * ```tsx
+ * <ComboboxContent>
+ *   {filtered.length === 0 ? (
+ *     <ComboboxEmpty>No results</ComboboxEmpty>
+ *   ) : (
+ *     filtered.map((fruit) => <ComboboxItem value={fruit} key={fruit}>{fruit}</ComboboxItem>)
+ *   )}
+ * </ComboboxContent>
+ * ```
+ */
+export declare const ComboboxEmpty: React.ForwardRefExoticComponent<Omit<ComboboxEmptyProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/combobox/ComboboxEmpty.d.ts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import type { ComboboxEmptyProps } from './types.js';
+/**
+ * Fallback shown in place of the item list when no `ComboboxItem`s are
+ * currently rendered — because the consumer's filtered results are empty, or
+ * because the root's `filter` predicate rejected every item. Renders a
+ * `<div role="presentation">`; renders nothing while at least one item is
+ * registered.
+ *
+ * @example
+ * ```tsx
+ * <ComboboxContent>
+ *   {filtered.length === 0 ? (
+ *     <ComboboxEmpty>No results</ComboboxEmpty>
+ *   ) : (
+ *     filtered.map((fruit) => <ComboboxItem value={fruit} key={fruit}>{fruit}</ComboboxItem>)
+ *   )}
+ * </ComboboxContent>
+ * ```
+ */
+export declare const ComboboxEmpty: React.ForwardRefExoticComponent<Omit<ComboboxEmptyProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/combobox/ComboboxInput.d.cts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import type { ComboboxInputProps } from './types.cjs';
+/**
+ * Text field that drives a {@link Combobox}'s filtering and keeps real DOM
+ * focus for the whole interaction, and doubles as the popper anchor the
+ * listbox positions against. Renders an `<input type="text" role="combobox">`
+ * with `aria-expanded`, `aria-controls` pointing at the content,
+ * `aria-autocomplete="list"`, `aria-activedescendant` tracking the
+ * virtually-focused option, `autoComplete="off"`,
+ * `aria-invalid`/`data-invalid`, `aria-required`, the native `readOnly` attribute with
+ * `aria-readonly`/`data-readonly`, and `aria-busy`/`data-loading` from the
+ * root's `invalid`/`readOnly`/`loading` props.
+ *
+ * Typing opens the listbox and updates the draft text; Arrow Down/Up open the
+ * listbox (or move the highlight by one option when already open); Enter
+ * commits the highlighted option — or, with `allowCustomValue` and nothing
+ * highlighted, the draft text itself; Escape closes the listbox.
+ *
+ * @example
+ * ```tsx
+ * <ComboboxInput placeholder="Search a fruit…" />
+ * ```
+ */
+export declare const ComboboxInput: React.ForwardRefExoticComponent<Omit<ComboboxInputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;

package/dist/combobox/ComboboxInput.d.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import type { ComboboxInputProps } from './types.js';
+/**
+ * Text field that drives a {@link Combobox}'s filtering and keeps real DOM
+ * focus for the whole interaction, and doubles as the popper anchor the
+ * listbox positions against. Renders an `<input type="text" role="combobox">`
+ * with `aria-expanded`, `aria-controls` pointing at the content,
+ * `aria-autocomplete="list"`, `aria-activedescendant` tracking the
+ * virtually-focused option, `autoComplete="off"`,
+ * `aria-invalid`/`data-invalid`, `aria-required`, the native `readOnly` attribute with
+ * `aria-readonly`/`data-readonly`, and `aria-busy`/`data-loading` from the
+ * root's `invalid`/`readOnly`/`loading` props.
+ *
+ * Typing opens the listbox and updates the draft text; Arrow Down/Up open the
+ * listbox (or move the highlight by one option when already open); Enter
+ * commits the highlighted option — or, with `allowCustomValue` and nothing
+ * highlighted, the draft text itself; Escape closes the listbox.
+ *
+ * @example
+ * ```tsx
+ * <ComboboxInput placeholder="Search a fruit…" />
+ * ```
+ */
+export declare const ComboboxInput: React.ForwardRefExoticComponent<Omit<ComboboxInputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;

package/dist/combobox/ComboboxItem.d.cts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+import type { ComboboxItemProps } from './types.cjs';
+/**
+ * A single selectable option within {@link ComboboxContent}. Renders a
+ * `<div role="option">` with `data-value`, `aria-selected`, `data-state`
+ * (`"checked"` | `"unchecked"`), `data-highlighted` (virtual focus, mirrored
+ * by the input's `aria-activedescendant`), and `data-disabled`. Registers
+ * itself — and its text — with the root, so `ComboboxEmpty` knows when the
+ * list is empty and Enter can commit the highlighted option. Click selects the
+ * item, updates the input's draft text to its text, closes the listbox, and
+ * refocuses the input — or, while the root is `multiple`, toggles it, clears
+ * the draft text, and leaves the listbox open. Pointer hover moves the virtual
+ * highlight onto it.
+ *
+ * When the root has a `filter` predicate, an item the predicate rejects
+ * renders nothing at all and unregisters itself, so it is absent from the DOM
+ * rather than hidden — a hidden option would still be reachable through
+ * `aria-activedescendant` and would still be counted as a result.
+ *
+ * @example
+ * ```tsx
+ * <ComboboxItem value="Apple">Apple</ComboboxItem>
+ * ```
+ */
+export declare const ComboboxItem: React.ForwardRefExoticComponent<Omit<ComboboxItemProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/combobox/ComboboxItem.d.ts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+import type { ComboboxItemProps } from './types.js';
+/**
+ * A single selectable option within {@link ComboboxContent}. Renders a
+ * `<div role="option">` with `data-value`, `aria-selected`, `data-state`
+ * (`"checked"` | `"unchecked"`), `data-highlighted` (virtual focus, mirrored
+ * by the input's `aria-activedescendant`), and `data-disabled`. Registers
+ * itself — and its text — with the root, so `ComboboxEmpty` knows when the
+ * list is empty and Enter can commit the highlighted option. Click selects the
+ * item, updates the input's draft text to its text, closes the listbox, and
+ * refocuses the input — or, while the root is `multiple`, toggles it, clears
+ * the draft text, and leaves the listbox open. Pointer hover moves the virtual
+ * highlight onto it.
+ *
+ * When the root has a `filter` predicate, an item the predicate rejects
+ * renders nothing at all and unregisters itself, so it is absent from the DOM
+ * rather than hidden — a hidden option would still be reachable through
+ * `aria-activedescendant` and would still be counted as a result.
+ *
+ * @example
+ * ```tsx
+ * <ComboboxItem value="Apple">Apple</ComboboxItem>
+ * ```
+ */
+export declare const ComboboxItem: React.ForwardRefExoticComponent<Omit<ComboboxItemProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/combobox/ComboboxPortal.d.cts

@@ -0,0 +1,20 @@
+import type { ComboboxPortalProps } from './types.cjs';
+/**
+ * Teleports its children (typically {@link ComboboxContent}) to
+ * `document.body` (or `container`, via `PortalProps`) while the
+ * {@link Combobox}'s listbox is open, so it escapes clipping/overflow from
+ * ancestors. Renders nothing while closed unless `forceMount` is set.
+ *
+ * @example
+ * ```tsx
+ * <ComboboxPortal>
+ *   <ComboboxContent>
+ *     <ComboboxItem value="Apple">Apple</ComboboxItem>
+ *   </ComboboxContent>
+ * </ComboboxPortal>
+ * ```
+ */
+export declare const ComboboxPortal: {
+    ({ forceMount, children, ...props }: ComboboxPortalProps): import("react").JSX.Element | null;
+    displayName: string;
+};

package/dist/combobox/ComboboxPortal.d.ts

@@ -0,0 +1,20 @@
+import type { ComboboxPortalProps } from './types.js';
+/**
+ * Teleports its children (typically {@link ComboboxContent}) to
+ * `document.body` (or `container`, via `PortalProps`) while the
+ * {@link Combobox}'s listbox is open, so it escapes clipping/overflow from
+ * ancestors. Renders nothing while closed unless `forceMount` is set.
+ *
+ * @example
+ * ```tsx
+ * <ComboboxPortal>
+ *   <ComboboxContent>
+ *     <ComboboxItem value="Apple">Apple</ComboboxItem>
+ *   </ComboboxContent>
+ * </ComboboxPortal>
+ * ```
+ */
+export declare const ComboboxPortal: {
+    ({ forceMount, children, ...props }: ComboboxPortalProps): import("react").JSX.Element | null;
+    displayName: string;
+};

package/dist/combobox/index.d.cts

@@ -0,0 +1,7 @@
+export * from './Combobox.cjs';
+export { ComboboxInput } from './ComboboxInput.cjs';
+export { ComboboxPortal } from './ComboboxPortal.cjs';
+export { ComboboxContent } from './ComboboxContent.cjs';
+export { ComboboxItem } from './ComboboxItem.cjs';
+export { ComboboxEmpty } from './ComboboxEmpty.cjs';
+export type { ComboboxFilter, ComboboxProps, ComboboxHandle, ComboboxInputProps, ComboboxPortalProps, ComboboxContentProps, ComboboxItemProps, ComboboxEmptyProps, } from './types.cjs';

package/dist/combobox/index.d.ts

@@ -0,0 +1,7 @@
+export * from './Combobox.js';
+export { ComboboxInput } from './ComboboxInput.js';
+export { ComboboxPortal } from './ComboboxPortal.js';
+export { ComboboxContent } from './ComboboxContent.js';
+export { ComboboxItem } from './ComboboxItem.js';
+export { ComboboxEmpty } from './ComboboxEmpty.js';
+export type { ComboboxFilter, ComboboxProps, ComboboxHandle, ComboboxInputProps, ComboboxPortalProps, ComboboxContentProps, ComboboxItemProps, ComboboxEmptyProps, } from './types.js';

package/dist/combobox/types.d.cts

@@ -0,0 +1,275 @@
+import type * as React from 'react';
+import type { FormValidityHandle } from '../utils/formControl.cjs';
+import type { PopperContentProps } from '../utils/popper.cjs';
+import type { PortalProps } from '../utils/portal.cjs';
+import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
+import type { FocusOutsideEvent, InteractOutsideEvent } from '../utils/useDismiss.cjs';
+/**
+ * How a {@link Combobox} decides which Items to show. `'manual'` filters
+ * nothing — the consumer renders only the matches, which is what async or
+ * server-side search needs. A predicate moves filtering inside the component.
+ */
+export type ComboboxFilter = 'manual' | ((itemText: string, inputValue: string) => boolean);
+/** @internal What one registered {@link ComboboxItem} contributes to the root's collection. */
+export interface ComboboxItemEntry {
+    /** Identifier committed to the root's value when this option is chosen. */
+    value: string;
+    /** The item's `textValue`, or its rendered text — matched by `filter` and written back into the input. */
+    text: string;
+}
+/** @internal Shared state distributed from {@link Combobox} to its parts via context. Not part of the public API. */
+export interface ComboboxContextValue {
+    inputRef: React.RefObject<HTMLInputElement | null>;
+    contentRef: React.RefObject<HTMLDivElement | null>;
+    contentId: string;
+    /** Whether more than one option can be selected. */
+    multiple: boolean;
+    /** Every selected value, normalised to an array whether or not `multiple`. */
+    selectedValues: string[];
+    /** Whether one option value is currently selected. */
+    isSelected: (value: string) => boolean;
+    /**
+     * Commits an option: replaces the selection, writes `text` into the input
+     * and closes — or, when `multiple`, toggles it within the selection, clears
+     * the draft text, and leaves the listbox open.
+     */
+    selectItem: (value: string, text: string) => void;
+    inputValue: string;
+    onInputValueChange: (value: string) => void;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    activeId: string | null;
+    setActiveId: (id: string | null) => void;
+    /** Opens the listbox and, once its items are mounted, highlights the first (or last) one. */
+    openWithHighlight: (edge: 'first' | 'last') => void;
+    itemCount: number;
+    registerItem: (id: string, entry: ComboboxItemEntry) => void;
+    unregisterItem: (id: string) => void;
+    /** The registered entry behind an option id, for committing the virtually-focused option. */
+    getItem: (id: string) => ComboboxItemEntry | undefined;
+    /** Whether an item with this text survives the current `filter` and draft text. */
+    matchesFilter: (itemText: string) => boolean;
+    invalid: boolean;
+    readOnly: boolean;
+    loading: boolean;
+    allowCustomValue: boolean;
+    required: boolean;
+}
+/**
+ * What {@link Combobox}'s forwarded ref carries. The root renders no DOM of
+ * its own, so the ref is these two constraint-validation methods and nothing
+ * else — `React.useRef<ComboboxHandle>(null)`.
+ */
+export type ComboboxHandle = FormValidityHandle;
+/** Props for the {@link Combobox} root. */
+export interface ComboboxProps {
+    /**
+     * The `ComboboxInput`/`ComboboxPortal` parts, rendered as children — `Combobox` itself renders no DOM.
+     * @default undefined — renders nothing without children.
+     */
+    children?: React.ReactNode;
+    /**
+     * Selected option's value, for controlled usage — a `string[]` when
+     * `multiple`, a `string` otherwise. Pair with `onValueChange`.
+     * @default undefined — uncontrolled, tracks its own selected value internally.
+     */
+    value?: string | string[];
+    /**
+     * Initially selected option's value, for uncontrolled usage. Same shape as
+     * `value`: a `string[]` when `multiple`.
+     * @default undefined — no option selected initially.
+     */
+    defaultValue?: string | string[];
+    /**
+     * Fires with the new value whenever an option is chosen, controlled or not —
+     * the whole `string[]` when `multiple`, not the toggled option.
+     * @default undefined — no-op if omitted.
+     */
+    onValueChange?: (value: string | string[]) => void;
+    /**
+     * Allows more than one option to be selected: `value` becomes a `string[]`,
+     * the listbox gets `aria-multiselectable`, and committing an option toggles
+     * it, clears the draft text, and leaves the listbox open.
+     * @default false
+     */
+    multiple?: boolean;
+    /**
+     * Lets Enter commit the draft text itself when no option is highlighted, so
+     * the combobox can create values that aren't in the list. Off by default —
+     * a combobox that silently accepts unmatched text is the wrong control for a
+     * closed set of options.
+     * @default false
+     */
+    allowCustomValue?: boolean;
+    /**
+     * How `ComboboxItem`s are filtered against the draft text. `'manual'` filters
+     * nothing: the consumer renders only the matching items, which is what async
+     * or server-side search needs. A predicate moves filtering inside the
+     * component — every item is measured (its `textValue`, or its rendered text)
+     * and the rejected ones render nothing at all, so they leave the option
+     * count, the highlight order, and `ComboboxEmpty` exactly as if the consumer
+     * had removed them.
+     * @default 'manual'
+     */
+    filter?: ComboboxFilter;
+    /**
+     * Keeps the first option highlighted whenever the (filtered) list changes
+     * while open, so Enter always has an obvious target. Off by default: it
+     * makes Enter commit something the user never pointed at, which is wrong
+     * when the draft text is itself a valid answer.
+     * @default false
+     */
+    autoHighlight?: boolean;
+    /**
+     * Marks results as in flight: `aria-busy`/`data-loading` on `ComboboxInput`
+     * and `ComboboxContent`, and no result-count announcement (a count measured
+     * mid-fetch would announce "0 results available" for every request).
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * The text field's draft text, for controlled usage. Pair with
+     * `onInputValueChange` — typically used to drive filtering of the
+     * `ComboboxItem` list, since filtering itself is left to the consumer.
+     * @default undefined — uncontrolled, tracks its own draft text internally.
+     */
+    inputValue?: string;
+    /**
+     * Initial draft text, for uncontrolled usage.
+     * @default ''
+     */
+    defaultInputValue?: string;
+    /**
+     * Fires with the new draft text as the user types, or when a selection updates it, controlled or not.
+     * @default undefined — no-op if omitted.
+     */
+    onInputValueChange?: (value: string) => void;
+    /**
+     * Whether the listbox popup is open, for controlled usage. Pair with `onOpenChange`.
+     * @default undefined — uncontrolled, tracks its own open state internally.
+     */
+    open?: boolean;
+    /**
+     * Initial open state, for uncontrolled usage.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * Fires with the new open state whenever it changes, controlled or not.
+     * @default undefined — no-op if omitted.
+     */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Fires with the new open state once the change has finished on screen —
+     * after `ComboboxContent`'s enter or exit animation ends, or as soon as it
+     * has settled when the listbox declares no animation. Use it for work that
+     * must not race the transition (measuring the panel, tearing down an
+     * expensive child); use `onOpenChange` for work that must not wait for it.
+     * @default undefined — no-op if omitted.
+     */
+    onOpenChangeComplete?: (open: boolean) => void;
+    /**
+     * Marks the combobox as invalid, exposed as `aria-invalid`/`data-invalid`
+     * on the `ComboboxInput`.
+     * @default false
+     */
+    invalid?: boolean;
+    /**
+     * Makes the `ComboboxInput` read-only, exposed as the native `readOnly`
+     * attribute plus `aria-readonly`/`data-readonly`.
+     * @default false
+     */
+    readOnly?: boolean;
+    /**
+     * Formats the message announced (through the shared `LiveAnnouncer`) each
+     * time the number of rendered `ComboboxItem`s changes while the listbox is
+     * open — filtering is silent for screen-reader users otherwise. Return an
+     * empty string to announce nothing.
+     * @default defaultGetResultCountLabel — e.g. `"3 results available"`
+     */
+    getResultCountLabel?: (count: number) => string;
+    /**
+     * Form field name. With it, visually-hidden native inputs mirror the
+     * *selected* value — never the draft `inputValue` — so the combobox
+     * participates in native form submission, reset and validation. A `multiple`
+     * combobox mirrors one control per selected value under the same `name`, the
+     * way a native `<select multiple>` submits repeated entries.
+     * @default undefined — submits nothing.
+     */
+    name?: string;
+    /**
+     * Marks the combobox required: `aria-required` on `ComboboxInput`, and —
+     * with `name` — native `valueMissing` while nothing is selected, reported
+     * through `checkValidity()`/`reportValidity()`.
+     * @default false
+     */
+    required?: boolean;
+}
+/** Props for {@link ComboboxInput}, the text field that drives filtering and keeps real DOM focus while the listbox is open. */
+export interface ComboboxInputProps extends Omit<PrimitivePropsWithRef<'input'>, 'value' | 'defaultValue'> {
+}
+/** Props for {@link ComboboxPortal}, which teleports its content to `document.body` while the listbox is open. */
+export interface ComboboxPortalProps extends PortalProps {
+    /**
+     * Render (and mount `ComboboxContent`) even while closed, instead of
+     * unmounting. Useful for animation libraries that need the outgoing
+     * content present in the DOM during an exit transition.
+     * @default false
+     */
+    forceMount?: boolean;
+}
+/**
+ * Props for {@link ComboboxContent}, the listbox popup. Extends
+ * {@link PopperContentProps} (`side`, `align`, `sideOffset`, `alignOffset`,
+ * `avoidCollisions`, `collisionPadding`) for floating-ui positioning relative
+ * to the input — note `ComboboxContent` defaults `side` to `'bottom'`,
+ * `align` to `'start'`, and `sideOffset` to `4`, instead of the popper base
+ * defaults (`'bottom'` / `'center'` / `0`).
+ */
+export interface ComboboxContentProps extends PopperContentProps {
+    /**
+     * Keep this listbox mounted even while closed, instead of unmounting it.
+     * @default false
+     */
+    forceMount?: boolean;
+    /**
+     * Fires when Escape is pressed while the listbox is open. Call `event.preventDefault()` to stop it from closing.
+     * @default undefined — no-op if omitted.
+     */
+    onEscapeKeyDown?: (event: KeyboardEvent) => void;
+    /**
+     * Fires on pointer-down outside the listbox and the input. Call `event.preventDefault()` to stop the listbox from closing.
+     * @default undefined — no-op if omitted.
+     */
+    onPointerDownOutside?: (event: PointerEvent) => void;
+    /**
+     * Fires when focus moves to an element outside the listbox and the input. Call `event.preventDefault()` to stop the listbox from closing. Receives a cancelable stand-in carrying the original `focusin` as its `detail`, since `focusin` itself cannot be canceled.
+     * @default undefined — no-op if omitted.
+     */
+    onFocusOutside?: (event: FocusOutsideEvent) => void;
+    /**
+     * Fires for either kind of outside interaction — pointer-down or focus — immediately before the specific handler above and with the same event, so one `event.preventDefault()` here vetoes the dismissal whichever way it was triggered.
+     * @default undefined — no-op if omitted.
+     */
+    onInteractOutside?: (event: InteractOutsideEvent) => void;
+}
+/** Props for a single {@link ComboboxItem} option within `ComboboxContent`. */
+export interface ComboboxItemProps extends PrimitivePropsWithRef<'div'> {
+    /** Unique identifier committed to the combobox root's value when this option is chosen. */
+    value: string;
+    /**
+     * Excludes this option from selection and pointer highlight.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Text the root's `filter` predicate matches against, and the text a
+     * selection writes back into `ComboboxInput`. Only needed when the item
+     * renders more than its label (an icon, a secondary line).
+     * @default undefined — falls back to the item's rendered text content.
+     */
+    textValue?: string;
+}
+/** Props for {@link ComboboxEmpty}, shown in place of the item list when no `ComboboxItem`s are rendered (because the consumer, or `filter`, removed them all). */
+export interface ComboboxEmptyProps extends PrimitivePropsWithRef<'div'> {
+}