@skdx/react 0.26.0

package/dist/color-picker/types.d.ts

@@ -0,0 +1,211 @@
+import type * as React from 'react';
+import type { ColorFormat, HsbColor } from '../utils/color.js';
+import type { PrimitivePropsWithRef } from '../utils/primitive.js';
+/** @internal Shared state distributed from {@link ColorPicker} to its parts via context. Not part of the public API. */
+export interface ColorPickerContextValue {
+    /** The canonical colour. HSB, so hue survives a trip to black — see `utils/color.md`. */
+    color: HsbColor;
+    /** The colour serialised in the current `format`; what `value`/`onValueChange` speak. */
+    value: string;
+    format: ColorFormat;
+    alpha: boolean;
+    step: number;
+    disabled: boolean;
+    readOnly: boolean;
+    /** `!disabled && !readOnly` — the single condition every part gates input on. */
+    interactive: boolean;
+    /** Human-readable description of a colour, used both as `aria-valuetext` and as the body of a live announcement. */
+    describe: (color: HsbColor) => string;
+    /** Applies a new colour. `announce` is for controls whose own role does not already speak the result — see `ColorPicker.md`. */
+    setColor: (next: HsbColor, options?: {
+        announce?: boolean;
+    }) => void;
+    /** Fires `onValueCommit` with the value as it currently stands. Called once at the end of a drag. */
+    commit: () => void;
+    setFormat: (format: ColorFormat) => void;
+}
+/** Which single channel a {@link ColorPickerInput} edits. */
+export type ColorChannel = 'hex' | 'red' | 'green' | 'blue' | 'hue' | 'saturation' | 'brightness' | 'lightness' | 'alpha';
+/** Props for the {@link ColorPicker} root. */
+export interface ColorPickerProps extends Omit<PrimitivePropsWithRef<'div'>, 'onChange'> {
+    /**
+     * Current colour as a string in the active `format`, for controlled usage.
+     * Pair with `onValueChange`. Anything {@link parseColor} understands is
+     * accepted regardless of `format`; an unparseable string is ignored and the
+     * last good colour is kept, because a half-typed `#ab` should not blank the
+     * picker.
+     * @default undefined — uncontrolled, tracks its own colour internally.
+     */
+    value?: string;
+    /**
+     * Initial colour, for uncontrolled usage, seeding the first render.
+     * @default '#000000' — opaque black, the one colour every format agrees on.
+     */
+    defaultValue?: string;
+    /**
+     * Fires with the new string on every change: each arrow key, each frame of a
+     * drag that moves the colour, each swatch click — and also on a `format`
+     * change, because the string genuinely changed even though the colour did not.
+     * @default undefined — no-op if omitted.
+     */
+    onValueChange?: (value: string) => void;
+    /**
+     * Fires once with the final string when a pointer drag ends (release or
+     * cancel). This is the callback to hang an expensive effect on: a drag emits
+     * `onValueChange` per frame and this one exactly once, so a consumer can
+     * repaint continuously without also making a network call per frame.
+     *
+     * Keyboard and click changes do not fire it — each is already a discrete
+     * commit, reported by `onValueChange`.
+     * @default undefined — no-op if omitted.
+     */
+    onValueCommit?: (value: string) => void;
+    /**
+     * Previous name for `onValueCommit`, kept so 0.20 code keeps working.
+     * @deprecated Renamed to `onValueCommit` in 0.21. The contract, Vue and Web
+     * Components have always called this `value-commit`, and React's own
+     * `Slider`/`Editable` already spelled it `onValueCommit` — only
+     * `AngleSlider` and `ColorPicker` used `onValueChangeEnd`. Still honoured
+     * when `onValueCommit` is not supplied; it will be removed in 0.22.
+     * @default undefined — no-op if omitted.
+     */
+    onValueChangeEnd?: (value: string) => void;
+    /**
+     * Notation `value` is written in, for controlled usage. Pair with
+     * `onFormatChange`. The colour itself is stored as HSB whatever this says;
+     * the format only decides how it is spelled on the way out.
+     * @default undefined — uncontrolled, tracks its own format internally.
+     */
+    format?: ColorFormat;
+    /**
+     * The notation the picker starts in when it is left uncontrolled.
+     * @default 'hex' — the notation people paste, type and recognise.
+     */
+    defaultFormat?: ColorFormat;
+    /**
+     * Fires with the new notation whenever it changes. `onValueChange` fires
+     * alongside it with the re-spelled string.
+     * @default undefined — no-op if omitted.
+     */
+    onFormatChange?: (format: ColorFormat) => void;
+    /**
+     * Whether the picker has an alpha channel. When `false`, `ColorPickerAlphaSlider`
+     * renders nothing and every emitted string is fully opaque — so a consumer
+     * that cannot handle transparency never receives an `rgba()` it must strip.
+     * @default true
+     */
+    alpha?: boolean;
+    /**
+     * Keyboard increment, in the units of whichever channel is being stepped:
+     * percentage points for saturation/brightness/alpha, degrees for hue. Shift
+     * multiplies it by ten, so a 1-unit picker still has a coarse gear.
+     * @default 1 — every whole unit is reachable without a pointer.
+     */
+    step?: number;
+    /**
+     * Blocks pointer and keyboard interaction across every part, and takes the
+     * focusable parts out of the tab order.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Displays the colour but blocks changes, while every part stays focusable
+     * and in the tab order — unlike `disabled`, a read-only picker can still be
+     * reached and read by a keyboard user.
+     * @default false
+     */
+    readOnly?: boolean;
+}
+/** Props for the {@link ColorPickerArea}, the 2D saturation/brightness surface. */
+export interface ColorPickerAreaProps extends PrimitivePropsWithRef<'div'> {
+}
+/**
+ * Props for the {@link ColorPickerAreaThumb}, the handle on the 2D surface.
+ *
+ * `asChild` is deliberately absent: the thumb renders the area's two
+ * `role="slider"` axes as its own children, and `Slot` merges onto exactly one
+ * element, so there is nothing here to slot onto.
+ */
+export interface ColorPickerAreaThumbProps extends Omit<PrimitivePropsWithRef<'div'>, 'asChild'> {
+    /**
+     * Accessible name of the horizontal axis, which is a `role="slider"` of its own.
+     * @default 'Saturation'
+     */
+    saturationLabel?: string;
+    /**
+     * Accessible name of the vertical axis, which is a second `role="slider"`.
+     * @default 'Brightness'
+     */
+    brightnessLabel?: string;
+}
+/** Props for the {@link ColorPickerHueSlider}, the 0–360° hue track. */
+export interface ColorPickerHueSliderProps extends Omit<PrimitivePropsWithRef<'div'>, 'onChange'> {
+    /**
+     * Axis the track runs along, which decides whether pointer position is read
+     * from `clientX` or `clientY` and is published as `data-orientation`.
+     * Vertical tracks run bottom-to-top, matching `Slider`.
+     * @default 'horizontal'
+     */
+    orientation?: 'horizontal' | 'vertical';
+}
+/** Props for the {@link ColorPickerHueSliderThumb}, the handle on the hue track. */
+export interface ColorPickerHueSliderThumbProps extends PrimitivePropsWithRef<'div'> {
+}
+/** Props for the {@link ColorPickerAlphaSlider}, the 0–100% opacity track. */
+export interface ColorPickerAlphaSliderProps extends Omit<PrimitivePropsWithRef<'div'>, 'onChange'> {
+    /**
+     * Axis the track runs along, which decides whether pointer position is read
+     * from `clientX` or `clientY` and is published as `data-orientation`.
+     * Vertical tracks run bottom-to-top, matching `Slider`.
+     * @default 'horizontal'
+     */
+    orientation?: 'horizontal' | 'vertical';
+}
+/** Props for the {@link ColorPickerAlphaSliderThumb}, the handle on the alpha track. */
+export interface ColorPickerAlphaSliderThumbProps extends PrimitivePropsWithRef<'div'> {
+}
+/** Props for the {@link ColorPickerSwatchGroup}, the container for preset swatches. */
+export interface ColorPickerSwatchGroupProps extends PrimitivePropsWithRef<'div'> {
+    /**
+     * Whether arrow-key navigation wraps from the last swatch back to the first.
+     * @default true
+     */
+    loop?: boolean;
+}
+/** Props for a single {@link ColorPickerSwatch} preset. */
+export interface ColorPickerSwatchProps extends PrimitivePropsWithRef<'button'> {
+    /**
+     * The colour this swatch selects, in any notation {@link parseColor}
+     * understands. An unparseable value renders a disabled swatch rather than a
+     * button that silently does nothing when clicked.
+     */
+    value: string;
+}
+/** Props for a {@link ColorPickerInput} text field. */
+export interface ColorPickerInputProps extends Omit<PrimitivePropsWithRef<'input'>, 'value' | 'defaultValue'> {
+    /**
+     * Which single channel this input edits. Omit it and the input carries the
+     * whole colour as one string in the picker's current `format` — which is the
+     * hex box people expect, and which re-spells itself when the format changes.
+     * @default undefined — the whole colour, in the current format.
+     */
+    channel?: ColorChannel;
+}
+/** Props for the {@link ColorPickerFormatSelect}, a native `<select>` over the notations. */
+export interface ColorPickerFormatSelectProps extends Omit<React.ComponentPropsWithRef<'select'>, 'value' | 'defaultValue' | 'children'> {
+    /**
+     * Which notations to offer, in the order they should appear.
+     * @default ['hex', 'rgb', 'hsl', 'hsb'] — every format the picker can emit.
+     */
+    formats?: ColorFormat[];
+    /**
+     * Replaces the generated `<option>` list wholesale, for a consumer who wants
+     * their own labels or grouping. Their `value` attributes must still be
+     * {@link ColorFormat} strings.
+     * @default undefined — one `<option>` per entry in `formats`.
+     */
+    children?: React.ReactNode;
+}
+/** Props for the {@link ColorPickerEyeDropper} trigger. */
+export interface ColorPickerEyeDropperProps extends PrimitivePropsWithRef<'button'> {
+}

package/dist/color-picker/useChannelSlider.d.cts

@@ -0,0 +1,84 @@
+import type * as React from 'react';
+/** @internal Options for {@link useChannelSlider}. */
+export interface UseChannelSliderOptions {
+    /** Published as `data-channel`, and the name reported if the part is rendered outside a `ColorPicker`. */
+    channel: 'hue' | 'alpha';
+    /** Name of the calling part, for the context error message. */
+    consumerName: string;
+    /** Top of the range as ARIA reports it; the bottom is always 0. */
+    max: number;
+    /**
+     * Highest value actually reachable, when that is not `max`. Hue needs it:
+     * the axis genuinely spans 360°, but 360 *is* 0, so the track stops at the
+     * last hue on the step grid below it rather than folding round and throwing
+     * the thumb back to the left edge mid-drag.
+     * @default options.max
+     */
+    limit?: number;
+    /** Current position on that range. */
+    value: number;
+    orientation: 'horizontal' | 'vertical';
+    /** Accessible name used when the consumer supplies none. */
+    defaultLabel: string;
+    /** Builds `aria-valuetext` — the number alone never conveys which colour resulted. */
+    valueText: (value: number) => string;
+    /** Receives an already clamped and step-snapped value. */
+    onChange: (value: number) => void;
+}
+/**
+ * @internal Element props plus the `data-*` keys TypeScript only permits when
+ * they are written inline in JSX — the same escape the `--skdx-*` custom
+ * property bags use, and for the same reason.
+ */
+type ChannelSliderElementProps = React.ComponentPropsWithoutRef<'div'> & Record<`data-${string}`, string | number | undefined>;
+/** @internal What {@link useChannelSlider} hands back for the part to assemble. */
+export interface ChannelSlider {
+    /** ARIA, `data-*` and `tabIndex`. Spread **before** the consumer's props so every one of them stays overridable. */
+    props: ChannelSliderElementProps;
+    /** Compose onto the element's `onKeyDown`. */
+    onKeyDown: (event: React.KeyboardEvent<HTMLDivElement>) => void;
+    /** Compose onto the element's `onPointerDown`. */
+    onPointerDown: (event: React.PointerEvent<HTMLDivElement>) => void;
+    /** Merge **before** the consumer's `style`. */
+    style: React.CSSProperties;
+    dragging: boolean;
+}
+/** @internal Two decimals, so a fractional `step` neither leaks float noise into the DOM nor is rounded away. */
+export declare function round2(value: number): number;
+/**
+ * @internal Rounds a raw channel value onto the `step` grid — with the
+ * float-drift correction a fractional step needs, the same one `Slider` and
+ * `AngleSlider` apply — and then into `0…max`. Shared by every channel in the
+ * family so the hue track, the alpha track and the 2D area all land on the
+ * same grid.
+ */
+export declare function snapChannel(raw: number, step: number, max: number): number;
+/**
+ * @internal `step: 0` means "continuous under the pointer", not "the keyboard
+ * does nothing" — the arrows fall back to one unit so every value stays
+ * reachable without a pointer, the same fallback `AngleSlider` makes.
+ */
+export declare function arrowStep(step: number): number;
+/**
+ * The behaviour shared by `ColorPickerHueSlider` and
+ * `ColorPickerAlphaSlider`: a linear `role="slider"` track over `0…max` with
+ * pointer drag, click-to-seek and a full keyboard path.
+ *
+ * The two parts differ only in their range, their wording and which field of
+ * the colour they write, so the alternative to this hook is one file copied
+ * onto another with three identifiers changed — and a keyboard bug fixed in
+ * one of them.
+ *
+ * **The track has ends; it does not wrap.** Hue is circular, but a linear
+ * control reporting `aria-valuemin=0`/`aria-valuemax=360` that silently
+ * teleported from one end to the other would be lying to assistive tech.
+ * `AngleSlider` is the wrapping control.
+ *
+ * Pointer geometry is physical (left-to-right, bottom-to-top), matching
+ * `Slider`; only the arrow **keys** are mirrored under `dir="rtl"`, via
+ * `directionalKey`.
+ *
+ * @internal
+ */
+export declare function useChannelSlider(options: UseChannelSliderOptions): ChannelSlider;
+export {};

package/dist/color-picker/useChannelSlider.d.ts

@@ -0,0 +1,84 @@
+import type * as React from 'react';
+/** @internal Options for {@link useChannelSlider}. */
+export interface UseChannelSliderOptions {
+    /** Published as `data-channel`, and the name reported if the part is rendered outside a `ColorPicker`. */
+    channel: 'hue' | 'alpha';
+    /** Name of the calling part, for the context error message. */
+    consumerName: string;
+    /** Top of the range as ARIA reports it; the bottom is always 0. */
+    max: number;
+    /**
+     * Highest value actually reachable, when that is not `max`. Hue needs it:
+     * the axis genuinely spans 360°, but 360 *is* 0, so the track stops at the
+     * last hue on the step grid below it rather than folding round and throwing
+     * the thumb back to the left edge mid-drag.
+     * @default options.max
+     */
+    limit?: number;
+    /** Current position on that range. */
+    value: number;
+    orientation: 'horizontal' | 'vertical';
+    /** Accessible name used when the consumer supplies none. */
+    defaultLabel: string;
+    /** Builds `aria-valuetext` — the number alone never conveys which colour resulted. */
+    valueText: (value: number) => string;
+    /** Receives an already clamped and step-snapped value. */
+    onChange: (value: number) => void;
+}
+/**
+ * @internal Element props plus the `data-*` keys TypeScript only permits when
+ * they are written inline in JSX — the same escape the `--skdx-*` custom
+ * property bags use, and for the same reason.
+ */
+type ChannelSliderElementProps = React.ComponentPropsWithoutRef<'div'> & Record<`data-${string}`, string | number | undefined>;
+/** @internal What {@link useChannelSlider} hands back for the part to assemble. */
+export interface ChannelSlider {
+    /** ARIA, `data-*` and `tabIndex`. Spread **before** the consumer's props so every one of them stays overridable. */
+    props: ChannelSliderElementProps;
+    /** Compose onto the element's `onKeyDown`. */
+    onKeyDown: (event: React.KeyboardEvent<HTMLDivElement>) => void;
+    /** Compose onto the element's `onPointerDown`. */
+    onPointerDown: (event: React.PointerEvent<HTMLDivElement>) => void;
+    /** Merge **before** the consumer's `style`. */
+    style: React.CSSProperties;
+    dragging: boolean;
+}
+/** @internal Two decimals, so a fractional `step` neither leaks float noise into the DOM nor is rounded away. */
+export declare function round2(value: number): number;
+/**
+ * @internal Rounds a raw channel value onto the `step` grid — with the
+ * float-drift correction a fractional step needs, the same one `Slider` and
+ * `AngleSlider` apply — and then into `0…max`. Shared by every channel in the
+ * family so the hue track, the alpha track and the 2D area all land on the
+ * same grid.
+ */
+export declare function snapChannel(raw: number, step: number, max: number): number;
+/**
+ * @internal `step: 0` means "continuous under the pointer", not "the keyboard
+ * does nothing" — the arrows fall back to one unit so every value stays
+ * reachable without a pointer, the same fallback `AngleSlider` makes.
+ */
+export declare function arrowStep(step: number): number;
+/**
+ * The behaviour shared by `ColorPickerHueSlider` and
+ * `ColorPickerAlphaSlider`: a linear `role="slider"` track over `0…max` with
+ * pointer drag, click-to-seek and a full keyboard path.
+ *
+ * The two parts differ only in their range, their wording and which field of
+ * the colour they write, so the alternative to this hook is one file copied
+ * onto another with three identifiers changed — and a keyboard bug fixed in
+ * one of them.
+ *
+ * **The track has ends; it does not wrap.** Hue is circular, but a linear
+ * control reporting `aria-valuemin=0`/`aria-valuemax=360` that silently
+ * teleported from one end to the other would be lying to assistive tech.
+ * `AngleSlider` is the wrapping control.
+ *
+ * Pointer geometry is physical (left-to-right, bottom-to-top), matching
+ * `Slider`; only the arrow **keys** are mirrored under `dir="rtl"`, via
+ * `directionalKey`.
+ *
+ * @internal
+ */
+export declare function useChannelSlider(options: UseChannelSliderOptions): ChannelSlider;
+export {};

package/dist/color-picker/usePointerRatio.d.cts

@@ -0,0 +1,40 @@
+import * as React from 'react';
+/** Position inside an element's border box, as fractions of its width and height. `{ x: 0, y: 0 }` is the top-left corner. */
+export interface PointerRatio {
+    x: number;
+    y: number;
+}
+/** Options for {@link usePointerRatio}. */
+export interface UsePointerRatioOptions {
+    /** Fires with the position on pointer down and on every subsequent move that changes it, plus the native event. */
+    onRatioChange: (ratio: PointerRatio, event: PointerEvent) => void;
+    /** Fires once when the drag ends — `pointerup` or `pointercancel`. The final position was already reported by `onRatioChange`. */
+    onRatioChangeEnd?: (event: PointerEvent) => void;
+}
+/** Return value of {@link usePointerRatio}. */
+export interface UsePointerRatioResult {
+    /** Spread onto the element whose box defines the coordinate space. It is re-measured on every move. */
+    onPointerDown: (event: React.PointerEvent<Element>) => void;
+    /** `true` between pointer down and pointer up/cancel. Suitable for a `data-dragging` styling hook. */
+    dragging: boolean;
+}
+/**
+ * The linear twin of `usePointerAngle`: turns a pointer position inside an
+ * element into normalized `x`/`y` fractions in `[0, 1]`, for widgets whose
+ * input is a *position* rather than a direction — the colour picker's 2D area
+ * and its hue and alpha tracks.
+ *
+ * It exists rather than three copies of `Slider`'s pointer block because those
+ * three parts each need a genuine drag-end signal (`onValueCommit` fires
+ * once per drag) and each needs `data-dragging`, and because document-level
+ * listeners keep a drag alive when the pointer leaves the window — which
+ * element-level `pointermove` does not.
+ *
+ * Deliberately knows nothing about value ranges, channels, ARIA, RTL, or
+ * `disabled`/`readOnly`: `x` is always measured left-to-right from the border
+ * box, exactly as `Slider` measures it, and a part that must ignore pointer
+ * input simply does not wire up `onPointerDown`.
+ *
+ * @internal
+ */
+export declare function usePointerRatio(options: UsePointerRatioOptions): UsePointerRatioResult;

package/dist/color-picker/usePointerRatio.d.ts

@@ -0,0 +1,40 @@
+import * as React from 'react';
+/** Position inside an element's border box, as fractions of its width and height. `{ x: 0, y: 0 }` is the top-left corner. */
+export interface PointerRatio {
+    x: number;
+    y: number;
+}
+/** Options for {@link usePointerRatio}. */
+export interface UsePointerRatioOptions {
+    /** Fires with the position on pointer down and on every subsequent move that changes it, plus the native event. */
+    onRatioChange: (ratio: PointerRatio, event: PointerEvent) => void;
+    /** Fires once when the drag ends — `pointerup` or `pointercancel`. The final position was already reported by `onRatioChange`. */
+    onRatioChangeEnd?: (event: PointerEvent) => void;
+}
+/** Return value of {@link usePointerRatio}. */
+export interface UsePointerRatioResult {
+    /** Spread onto the element whose box defines the coordinate space. It is re-measured on every move. */
+    onPointerDown: (event: React.PointerEvent<Element>) => void;
+    /** `true` between pointer down and pointer up/cancel. Suitable for a `data-dragging` styling hook. */
+    dragging: boolean;
+}
+/**
+ * The linear twin of `usePointerAngle`: turns a pointer position inside an
+ * element into normalized `x`/`y` fractions in `[0, 1]`, for widgets whose
+ * input is a *position* rather than a direction — the colour picker's 2D area
+ * and its hue and alpha tracks.
+ *
+ * It exists rather than three copies of `Slider`'s pointer block because those
+ * three parts each need a genuine drag-end signal (`onValueCommit` fires
+ * once per drag) and each needs `data-dragging`, and because document-level
+ * listeners keep a drag alive when the pointer leaves the window — which
+ * element-level `pointermove` does not.
+ *
+ * Deliberately knows nothing about value ranges, channels, ARIA, RTL, or
+ * `disabled`/`readOnly`: `x` is always measured left-to-right from the border
+ * box, exactly as `Slider` measures it, and a part that must ignore pointer
+ * input simply does not wire up `onPointerDown`.
+ *
+ * @internal
+ */
+export declare function usePointerRatio(options: UsePointerRatioOptions): UsePointerRatioResult;

package/dist/combobox/Combobox.cjs

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

package/dist/combobox/Combobox.d.cts

@@ -0,0 +1,79 @@
+import * as React from 'react';
+import type { ComboboxContextValue, ComboboxProps } from './types.cjs';
+/**
+ * WAI-ARIA 1.2 "combobox with list autocomplete": real DOM focus always
+ * stays on the input; the highlighted option is tracked as virtual focus
+ * via `aria-activedescendant`. Filtering is the consumer's responsibility by
+ * default (`filter: 'manual'`) and moves inside the component as soon as a
+ * `filter` predicate is supplied.
+ */
+export declare const OPTION_SELECTOR = "[role=\"option\"]:not([data-disabled])";
+/** Default `getResultCountLabel`: `"1 result available"` / `"3 results available"`. */
+export declare function defaultGetResultCountLabel(count: number): string;
+export declare const ComboboxProvider: {
+    (props: ComboboxContextValue & {
+        children: React.ReactNode;
+    }): React.JSX.Element;
+    displayName: string;
+}, useComboboxContext: (consumerName: string) => ComboboxContextValue;
+/**
+ * Root of a WAI-ARIA 1.2 "combobox with list autocomplete": real DOM focus
+ * always stays on `ComboboxInput`; the highlighted option is tracked as
+ * virtual focus via `aria-activedescendant` rather than moved with `tabIndex`.
+ * Owns the selected value, the input's draft text, and the popup's open
+ * state, handing all three down to every other `Combobox*` part via context.
+ * Renders no DOM of its own.
+ *
+ * Filtering is the consumer's job by default (`filter: 'manual'`): you filter
+ * your data by `inputValue` and render only the `ComboboxItem`s that match,
+ * which is what an async or server-side search needs. Pass a `filter`
+ * predicate instead and the component filters its own children.
+ *
+ * Works controlled (`value` + `onValueChange`, `inputValue` +
+ * `onInputValueChange`, `open` + `onOpenChange`) or uncontrolled
+ * (`defaultValue`, `defaultInputValue`, `defaultOpen`).
+ *
+ * @example Consumer-side (default) filtering:
+ * ```tsx
+ * function FruitCombobox() {
+ *   const [inputValue, setInputValue] = React.useState('');
+ *   const filtered = FRUITS.filter((f) => f.toLowerCase().includes(inputValue.toLowerCase()));
+ *
+ *   return (
+ *     <Combobox inputValue={inputValue} onInputValueChange={setInputValue}>
+ *       <ComboboxInput placeholder="Search a fruit…" />
+ *       <ComboboxPortal>
+ *         <ComboboxContent>
+ *           {filtered.length === 0 ? (
+ *             <ComboboxEmpty>No results</ComboboxEmpty>
+ *           ) : (
+ *             filtered.map((fruit) => (
+ *               <ComboboxItem value={fruit} key={fruit}>{fruit}</ComboboxItem>
+ *             ))
+ *           )}
+ *         </ComboboxContent>
+ *       </ComboboxPortal>
+ *     </Combobox>
+ *   );
+ * }
+ * ```
+ *
+ * @example Built-in filtering, multi-select, creatable:
+ * ```tsx
+ * <Combobox
+ *   multiple
+ *   allowCustomValue
+ *   autoHighlight
+ *   filter={(text, input) => text.toLowerCase().includes(input.toLowerCase())}
+ * >
+ *   <ComboboxInput placeholder="Search a fruit…" />
+ *   <ComboboxPortal>
+ *     <ComboboxContent>
+ *       {FRUITS.map((fruit) => <ComboboxItem value={fruit} key={fruit}>{fruit}</ComboboxItem>)}
+ *       <ComboboxEmpty>No results</ComboboxEmpty>
+ *     </ComboboxContent>
+ *   </ComboboxPortal>
+ * </Combobox>
+ * ```
+ */
+export declare const Combobox: React.ForwardRefExoticComponent<ComboboxProps & React.RefAttributes<import("../index.cjs").FormValidityHandle>>;

package/dist/combobox/Combobox.d.ts

@@ -0,0 +1,79 @@
+import * as React from 'react';
+import type { ComboboxContextValue, ComboboxProps } from './types.js';
+/**
+ * WAI-ARIA 1.2 "combobox with list autocomplete": real DOM focus always
+ * stays on the input; the highlighted option is tracked as virtual focus
+ * via `aria-activedescendant`. Filtering is the consumer's responsibility by
+ * default (`filter: 'manual'`) and moves inside the component as soon as a
+ * `filter` predicate is supplied.
+ */
+export declare const OPTION_SELECTOR = "[role=\"option\"]:not([data-disabled])";
+/** Default `getResultCountLabel`: `"1 result available"` / `"3 results available"`. */
+export declare function defaultGetResultCountLabel(count: number): string;
+export declare const ComboboxProvider: {
+    (props: ComboboxContextValue & {
+        children: React.ReactNode;
+    }): React.JSX.Element;
+    displayName: string;
+}, useComboboxContext: (consumerName: string) => ComboboxContextValue;
+/**
+ * Root of a WAI-ARIA 1.2 "combobox with list autocomplete": real DOM focus
+ * always stays on `ComboboxInput`; the highlighted option is tracked as
+ * virtual focus via `aria-activedescendant` rather than moved with `tabIndex`.
+ * Owns the selected value, the input's draft text, and the popup's open
+ * state, handing all three down to every other `Combobox*` part via context.
+ * Renders no DOM of its own.
+ *
+ * Filtering is the consumer's job by default (`filter: 'manual'`): you filter
+ * your data by `inputValue` and render only the `ComboboxItem`s that match,
+ * which is what an async or server-side search needs. Pass a `filter`
+ * predicate instead and the component filters its own children.
+ *
+ * Works controlled (`value` + `onValueChange`, `inputValue` +
+ * `onInputValueChange`, `open` + `onOpenChange`) or uncontrolled
+ * (`defaultValue`, `defaultInputValue`, `defaultOpen`).
+ *
+ * @example Consumer-side (default) filtering:
+ * ```tsx
+ * function FruitCombobox() {
+ *   const [inputValue, setInputValue] = React.useState('');
+ *   const filtered = FRUITS.filter((f) => f.toLowerCase().includes(inputValue.toLowerCase()));
+ *
+ *   return (
+ *     <Combobox inputValue={inputValue} onInputValueChange={setInputValue}>
+ *       <ComboboxInput placeholder="Search a fruit…" />
+ *       <ComboboxPortal>
+ *         <ComboboxContent>
+ *           {filtered.length === 0 ? (
+ *             <ComboboxEmpty>No results</ComboboxEmpty>
+ *           ) : (
+ *             filtered.map((fruit) => (
+ *               <ComboboxItem value={fruit} key={fruit}>{fruit}</ComboboxItem>
+ *             ))
+ *           )}
+ *         </ComboboxContent>
+ *       </ComboboxPortal>
+ *     </Combobox>
+ *   );
+ * }
+ * ```
+ *
+ * @example Built-in filtering, multi-select, creatable:
+ * ```tsx
+ * <Combobox
+ *   multiple
+ *   allowCustomValue
+ *   autoHighlight
+ *   filter={(text, input) => text.toLowerCase().includes(input.toLowerCase())}
+ * >
+ *   <ComboboxInput placeholder="Search a fruit…" />
+ *   <ComboboxPortal>
+ *     <ComboboxContent>
+ *       {FRUITS.map((fruit) => <ComboboxItem value={fruit} key={fruit}>{fruit}</ComboboxItem>)}
+ *       <ComboboxEmpty>No results</ComboboxEmpty>
+ *     </ComboboxContent>
+ *   </ComboboxPortal>
+ * </Combobox>
+ * ```
+ */
+export declare const Combobox: React.ForwardRefExoticComponent<ComboboxProps & React.RefAttributes<import("../index.js").FormValidityHandle>>;