@skdx/react 0.27.0 → 0.29.0

package/dist/select/types.d.ts

@@ -1,258 +1,346 @@
 import type * as React from 'react';
+import type { BadgeProps } from '../badge/types.js';
+import type { TagGroupProps } from '../tag-group/types.js';
+import type { AutoFocusEvent } from '../utils/dismissal.js';
 import type { FormValidityHandle } from '../utils/formControl.js';
+import type { PassThroughProps } from '../utils/passThrough.js';
 import type { PopperContentProps } from '../utils/popper.js';
 import type { PortalProps } from '../utils/portal.js';
 import type { PrimitivePropsWithRef } from '../utils/primitive.js';
+import type { ScoredFilterResult } from '../utils/scoredFilter.js';
 import type { InteractOutsideEvent } from '../utils/useDismiss.js';
-/**
- * One entry of the {@link SelectProps.items} collection: everything the root
- * needs to know about an option *before* that option has ever been rendered.
- */
+import type { OptionEntry } from '../utils/useOptionCollection.js';
+import type { SelectionChangeDetail, SelectionChangeReason } from '../utils/useSelection.js';
+/** One entry of {@link SelectProps.items}: option metadata before rendering. */
 export interface SelectItemDescriptor {
-    /** Identifier committed to the root's value when this option is chosen. */
+    /** Identifier committed to the root's value when chosen. */
     value: string;
-    /**
-     * Text shown by `SelectValue` and matched by trigger typeahead. A mounted
-     * `SelectItemText` overrides it.
-     * @default undefined — falls back to `value`.
-     */
-    label?: string;
-    /**
-     * Excludes this option from trigger typeahead. The rendered `SelectItem`'s
-     * own `disabled` is what excludes it from selection.
-     * @default false
-     */
-    disabled?: boolean;
+    /** Text for SelectValue and typeahead; overridden by mounted SelectItemText. @default undefined — falls back to value. */
+    label?: string | undefined;
+    /** Excludes from trigger typeahead; rendered SelectItem's disabled excludes from selection. @default false */
+    disabled?: boolean | undefined;
+}
+/** One option for {@link SelectProps.options} recipe prop — flat entry rendered as SelectItem. */
+export interface SelectOption {
+    /** Identifier committed when chosen. */
+    value: string;
+    /** Text for SelectValue and typeahead. @default undefined — falls back to value. */
+    label?: string | undefined;
+    /** Excludes from selection and typeahead. @default false */
+    disabled?: boolean | undefined;
 }
-/** @internal Shared state distributed from {@link Select} to its parts via context. Not part of the public API. */
+/** Labeled group of SelectOptions for SelectProps.options; grouping is data-driven. */
+export interface SelectOptionGroup {
+    /** Heading rendered as SelectLabel above this group's options. */
+    label: string;
+    /** Options in this group. */
+    options: SelectOption[];
+}
+/** One entry of {@link SelectProps.options}: a flat option, or a labeled group of them. */
+export type SelectOptionOrGroup = SelectOption | SelectOptionGroup;
+/** Decides which options survive the draft text: a boolean keeps or drops, a number filters and ranks. */
+export type SelectFilter = (itemText: string, inputValue: string) => ScoredFilterResult;
+/** Where opening should put the active option: 'selected', 'first', or 'last'. @internal */
+export type SelectOpenIntent = 'selected' | 'first' | 'last';
+/** @internal Shared state distributed from {@link Select} to its parts via context. */
 export interface SelectContextValue {
+    /** Hands focus back to the trigger; the one place `close-auto-focus` announces from. */
+    focusTrigger: () => void;
+    /** SelectContent's onCloseAutoFocus callback; mutable ref because Content's lifecycle spans the root's. */
+    closeAutoFocusRef: React.RefObject<((event: AutoFocusEvent) => void) | undefined>;
     triggerRef: React.RefObject<HTMLButtonElement | null>;
     contentRef: React.RefObject<HTMLDivElement | null>;
     contentId: string;
+    /** Id on SelectValue; trigger's aria-labelledby points at it. */
+    valueId: string;
+    /** Whether SelectValue is mounted (aria-labelledby must name an existing element). */
+    hasValuePart: boolean;
+    /** Called by SelectValue on mount/unmount to keep trigger's aria-labelledby valid. */
+    setHasValuePart: (present: boolean) => void;
+    /** Id of virtually-focused option or null; published as aria-activedescendant/data-highlighted. */
+    activeId: string | null;
+    /** Moves virtual focus to an option or clears it. */
+    setActiveId: (id: string | null) => void;
+    /** Where next open should put active option; written by trigger, read by SelectContent on mount. Ref for inter-part messaging, not rendering. */
+    openIntentRef: React.RefObject<SelectOpenIntent>;
+    /** The filter Input, which holds DOM focus in the trigger's place while `filterable`. */
+    inputRef: React.RefObject<HTMLInputElement | null>;
     /** Whether more than one option can be selected. */
     multiple: boolean;
-    /** Every selected value, normalised to an array whether or not `multiple`. */
+    /** Whether a filter Input stands in for the trigger and narrows the options. */
+    filterable: boolean;
+    /** Whether the option list is in flight, published as aria-busy/data-loading. */
+    loading: boolean;
+    /** Whether Control+A may sweep every enabled option while multiple. */
+    allowSelectAll: boolean;
+    /** Whether the selection reached maxSelected, capping the options that would grow it. */
+    atMax: boolean;
+    /** Draft text in the filter Input. */
+    inputValue: string;
+    /** Replaces the draft text, reporting it through onInputValueChange. */
+    setInputValue: (next: string) => void;
+    /** Whether committing an option closes the listbox (defaults to !multiple). */
+    closeOnSelect: boolean;
+    /** The rendered enabled options in traversal order, ranked when the filter scores. */
+    orderedOptions: () => HTMLElement[];
+    /** Rank each visible option renders in when the filter scores numerically; null leaves DOM order. */
+    itemOrder: ReadonlyMap<string, number> | null;
+    /** How many options currently survive the filter, for the Empty part. */
+    itemCount: number;
+    /** Publishes an option's filter text while it is rendered. */
+    registerItem: (id: string, entry: OptionEntry) => void;
+    /** Withdraws an option the filter dropped, or unmount removed. */
+    unregisterItem: (id: string) => void;
+    /** The entry an option id registered, for committing the highlighted option. */
+    getItem: (id: string) => OptionEntry | undefined;
+    /** Whether an option's text survives the current filter and draft text. */
+    matchesFilter: (text: string) => boolean;
+    /** Selects the run between the range anchor and the highlighted option. */
+    selectRange: () => void;
+    /** Selects from the highlighted option to one end of the list, additively. */
+    selectToEdge: (edge: 'first' | 'last') => void;
+    /** Selects every enabled option, or clears them when all are already selected. */
+    selectAllOrClear: () => void;
+    /** Empties the selection and any draft text in one step. */
+    clear: () => void;
+    /** Removes the last selected value, for Backspace on an empty filter Input. */
+    removeLast: () => void;
+    /** Removes one value from the selection, for a Tag's remove button. */
+    deselect: (value: string) => void;
+    /** Every selected value, normalized to an array. */
     selectedValues: string[];
     /** Whether one option value is currently selected. */
     isSelected: (value: string) => boolean;
-    /** Commits an option: replaces the selection, or toggles it within it when `multiple`. */
-    selectItem: (value: string) => void;
+    /** Commits an option: replaces or toggles it when multiple. */
+    selectItem: (value: string, reason?: SelectionChangeReason) => void;
     open: boolean;
     onOpenChange: (open: boolean) => void;
     disabled: boolean;
+    /** Selection is fixed; trigger stays focusable and in form submission, but listbox refuses to open. */
+    readOnly: boolean;
     required: boolean;
     invalid: boolean;
-    name?: string;
+    name?: string | undefined;
     registerOptionLabel: (value: string, label: string) => void;
-    /** Label for a value: a registered `SelectItemText` wins, then `items`, then the value itself. */
+    /** Label for a value: registered SelectItemText, then items, then value itself. */
     getOptionLabel: (value: string) => string;
-    /** Every option the root knows about without opening the listbox — the trigger-typeahead pool. */
+    /** Every option known without opening (the trigger-typeahead pool). */
     collection: SelectItemDescriptor[];
 }
-/** Props for the {@link Select} root. */
-export interface SelectProps {
+/** Props for Select root; standard attributes land on the derived SelectTrigger. */
+export interface SelectProps extends PassThroughProps {
     /**
-     * The trigger, portal, and content parts, distributed selection/open state via context.
+     * Trigger, portal, and content parts with selection/open state via context.
      * @default undefined
      */
-    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 until the user picks one.
-     */
-    defaultValue?: string | string[];
-    /**
-     * Fires with the new value whenever the selected option changes, 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`, choosing an option toggles it
-     * instead of replacing the selection, and the listbox stays open so several
-     * options can be picked in one pass.
-     * @default false
-     */
-    multiple?: boolean;
+    children?: React.ReactNode | undefined;
+    /** Selected option value(s) for controlled usage; pair with onValueChange. @default undefined — uncontrolled. */
+    value?: string | string[] | undefined;
+    /** Initially selected value(s) for uncontrolled usage. @default undefined — no option selected until user picks one. */
+    defaultValue?: string | string[] | undefined;
+    /** Fires when selection changes with the whole selection, not the toggled option. @default undefined — no-op if omitted. */
+    onValueChange?: ((detail: SelectionChangeDetail) => void) | undefined;
+    /** Allows more than one option selected. Sets aria-multiselectable="true" on Content, toggles options instead of replacing, keeps listbox open. @default false */
+    multiple?: boolean | undefined;
+    /** Picking the already-selected option in single-select mode clears it; ignored in multiple mode. @default false */
+    deselectable?: boolean | undefined;
+    /** Largest number of values selectable while multiple; unselected options go aria-disabled once reached, and selected ones stay removable. @default undefined — the selection grows without a cap. */
+    maxSelected?: number | undefined;
+    /** Whether Control+A selects every enabled option while multiple and the listbox is open, and the derived anatomy offers a SelectAll row. @default true */
+    allowSelectAll?: boolean | undefined;
+    /** Whether the derived anatomy renders a filter Input in the trigger's place, narrowing the options as the user types. @default false */
+    filterable?: boolean | undefined;
+    /** Controlled draft text in the filter Input; pair with onInputValueChange. Read only while filterable. @default undefined — uncontrolled. */
+    inputValue?: string | undefined;
+    /** Initial draft text in the filter Input, for uncontrolled usage. @default '' */
+    defaultInputValue?: string | undefined;
+    /** Fires with the new draft text on every keystroke, and with the empty string when a selection or Clear empties it. @default undefined — no-op if omitted. */
+    onInputValueChange?: ((inputValue: string) => void) | undefined;
+    /** Predicate deciding which options survive the draft text: a boolean filters, a number filters and ranks (0 excludes). Read only while filterable. @default undefined — every option survives. */
+    filter?: SelectFilter | undefined;
+    /** Whether the option list is in flight, published as aria-busy and data-loading without blocking interaction. @default false */
+    loading?: boolean | undefined;
+    /** Whether the derived anatomy renders a Clear button emptying the selection and draft text in one press. @default false */
+    clearable?: boolean | undefined;
+    /** Formats the message announced after each selection change while multiple; return an empty string to announce nothing. @default defaultGetSelectionLabel — "2 selected". */
+    getSelectionLabel?: ((count: number) => string) | undefined;
+    /** Option collection declared up front. Enables closed-trigger typeahead and labels on first paint before Content mounts. @default undefined — only knows rendered options. */
+    items?: SelectItemDescriptor[] | undefined;
+    /** Flat or grouped option data to render automatically — trigger, portal, listbox, and Items — instead of hand composition. @default undefined — compose parts yourself. */
+    options?: SelectOptionOrGroup[] | undefined;
+    /** Customizes how derived option renders inside SelectItem; receives option and selected state. @default undefined — renders option.label ?? option.value. */
+    renderOption?: ((option: SelectOption, state: {
+        selected: boolean;
+    }) => React.ReactNode) | undefined;
+    /** Customizes trigger content in place of default label/chips; receives selected option(s) or null. @default undefined — renders default label/placeholder/chips. */
+    renderValue?: ((selected: SelectOption | SelectOption[] | null) => React.ReactNode) | undefined;
+    /** Customises a selected value's content inside its derived Tag; only read while multiple and options derives the anatomy. @default undefined — renders option.label ?? option.value. */
+    renderTag?: ((option: SelectOption) => React.ReactNode) | undefined;
+    /** Placeholder shown by derived trigger while nothing is selected; only read while options derives. @default undefined — renders nothing when no option selected. */
+    placeholder?: string | undefined;
+    /** Picking an option closes the listbox. Defaults to !multiple; can override the default. @default !multiple */
+    closeOnSelect?: boolean | undefined;
+    /** Whether the listbox popup is open for controlled usage; pair with onOpenChange. @default undefined — uncontrolled. */
+    open?: boolean | undefined;
+    /** Initial open state for uncontrolled usage. @default false */
+    defaultOpen?: boolean | undefined;
+    /** Fires with new open state whenever it changes, controlled or not. @default undefined — no-op if omitted. */
+    onOpenChange?: ((open: boolean) => void) | undefined;
+    /** Fires with new open state once animation finishes (after SelectContent's enter/exit ends). @default undefined — no-op if omitted. */
+    onOpenChangeComplete?: ((open: boolean) => void) | undefined;
+    /** Disables the trigger and prevents opening. Distinct from readOnly, which keeps focusable and submits. @default false */
+    disabled?: boolean | undefined;
+    /** Unchangeable value. Trigger keeps tab stop and focus, carries aria-readonly="true" and data-readonly, submits the value. @default false */
+    readOnly?: boolean | undefined;
+    /** Marks hidden form controls as required for constraint validation (only meaningful when name is set). @default false */
+    required?: boolean | undefined;
+    /** Marks select as invalid, exposed as aria-invalid/data-invalid on SelectTrigger. @default false */
+    invalid?: boolean | undefined;
+    /** Visually-hidden native form control kept in sync with value for submission, reset, and validation. @default undefined — no hidden control. */
+    name?: string | undefined;
+    /** Form id the select submits into, forwarded to every hidden control so select can live outside the form it belongs to. @default undefined — submit into nearest ancestor form. */
+    form?: string | undefined;
+    /** Browser autofill hint, forwarded to the first mirrored hidden control — the same one that answers for the whole set's validity. @default undefined — no autofill hint. */
+    autoComplete?: string | undefined;
     /**
-     * The full option collection, declared up front.
-     *
-     * Options otherwise register their label only when `SelectContent` mounts,
-     * and `SelectContent` unmounts while closed — so before the listbox has
-     * ever been opened the root knows no labels at all, which leaves
-     * `SelectValue` rendering a raw `defaultValue` and leaves the closed trigger
-     * with nothing to run typeahead against. `items` closes both gaps from
-     * first paint. It renders nothing; mounted `SelectItem`s stay the source of
-     * truth for anything it doesn't cover.
-     * @default undefined — the root only knows options that have been rendered.
+     * Corner rung the skin rounds the control by, fed to the derived `SelectTrigger`.
+     * @default undefined — the skin's own default corner.
      */
-    items?: SelectItemDescriptor[];
+    shape?: 'rounded' | 'square' | 'pill' | (string & {}) | undefined;
     /**
-     * Whether the listbox popup is open, for controlled usage. Pair with `onOpenChange`.
-     * @default undefined — uncontrolled, tracks its own open state internally.
+     * Size rung the skin scales the control by, fed to the derived `SelectTrigger` and every derived Tag.
+     * @default undefined — the skin's own default size.
      */
-    open?: boolean;
+    size?: 'sm' | 'lg' | (string & {}) | undefined;
     /**
-     * Initial open state, for uncontrolled usage.
-     * @default false
+     * Severity rung the skin colours the chips by, fed to every derived Tag.
+     * @default undefined — the skin's own neutral styling.
      */
-    defaultOpen?: boolean;
+    status?: 'info' | 'success' | 'warning' | 'danger' | (string & {}) | undefined;
     /**
-     * Fires with the new open state whenever it changes, controlled or not.
-     * @default undefined — no-op if omitted.
+     * Spacing rung the skin packs the tag strip by, fed to the derived `SelectTagList`.
+     * @default undefined — the skin's own default spacing.
      */
-    onOpenChange?: (open: boolean) => void;
+    density?: 'comfortable' | 'compact' | (string & {}) | undefined;
     /**
-     * Fires with the new open state once the change has finished on screen — after
-     * `SelectContent`'s enter or exit animation ends, or as soon as the listbox has
-     * settled when it declares no animation. Use it for work that must not race the
-     * transition; use `onOpenChange` for work that must not wait for it.
-     * @default undefined — no-op if omitted.
+     * Matches the listbox width to the trigger, fed to the derived `SelectContent`.
+     * @default undefined — the panel sizes to its content.
      */
-    onOpenChangeComplete?: (open: boolean) => void;
+    matchWidth?: boolean | undefined;
     /**
-     * Disables the trigger and prevents opening the listbox.
-     * @default false
+     * Accessible name for the derived Trigger or filter Input, and the tag strip beside it.
+     * @default undefined — the field must be named some other way.
      */
-    disabled?: boolean;
-    /**
-     * Marks the underlying hidden `<select>` as required for form validation.
-     * Only meaningful when `name` is also set.
-     * @default false
-     */
-    required?: boolean;
+    'aria-label'?: string | undefined;
+}
+/** Props for {@link SelectTrigger}, the button that opens the listbox and displays the current value. */
+export interface SelectTriggerProps extends PrimitivePropsWithRef<'button'> {
     /**
-     * Marks the select as invalid, exposed as `aria-invalid`/`data-invalid` on
-     * the `SelectTrigger`.
-     * @default false
+     * Corner rung the skin rounds the trigger by, mirrored to `data-shape`.
+     * @default undefined — the skin's own default corner.
      */
-    invalid?: boolean;
+    shape?: 'rounded' | 'square' | 'pill' | (string & {}) | undefined;
     /**
-     * When set, renders a visually-hidden native `<select>` in sync with the value, so the select participates in native form submission and validation.
-     * @default undefined — no hidden input rendered.
+     * Size rung the skin scales the trigger by, mirrored to `data-size`.
+     * @default undefined — the skin's own default size.
      */
-    name?: string;
+    size?: 'sm' | 'lg' | (string & {}) | undefined;
 }
-/** Props for {@link SelectTrigger}, the button that opens the listbox and displays the current value. */
-export interface SelectTriggerProps extends PrimitivePropsWithRef<'button'> {
+/** Props for {@link SelectInput}, the filter text field that stands in for the trigger while `filterable`. */
+export interface SelectInputProps extends Omit<PrimitivePropsWithRef<'input'>, 'value' | 'defaultValue'> {
+}
+/** Props for {@link SelectTagList}, the strip holding one removable Tag per selected value. */
+export interface SelectTagListProps extends Omit<TagGroupProps, 'disabled' | 'tags' | 'onRemove'> {
+}
+/** Props for {@link SelectTag}, one selected value inside the tag strip. */
+export interface SelectTagProps extends Omit<BadgeProps, 'index' | 'value' | 'onDelete' | 'deletable' | 'deleteLabel' | 'dot' | 'leading' | 'selected' | 'trailing' | 'variant'> {
+    /** The selected value this tag represents; deselects it when remove is pressed. */
+    value: string;
+}
+/** Props for {@link SelectTagRemove}, the button deselecting its tag's value. */
+export interface SelectTagRemoveProps extends PrimitivePropsWithRef<'button'> {
+}
+/** Props for {@link SelectClear}, the button emptying selection and draft text in one press. */
+export interface SelectClearProps extends PrimitivePropsWithRef<'button'> {
 }
-/** Props for {@link SelectValue}, which renders the selected option's label (or a placeholder) inside the trigger. */
+/** Props for {@link SelectAll}, the listbox row toggling every enabled option at once. */
+export interface SelectAllProps extends PrimitivePropsWithRef<'div'> {
+}
+/** Props for {@link SelectEmpty}, the message shown when the filter leaves no option. */
+export interface SelectEmptyProps extends PrimitivePropsWithRef<'div'> {
+}
+/** Props for SelectValue: renders the selected option's label or placeholder inside the trigger. */
 export interface SelectValueProps extends PrimitivePropsWithRef<'span'> {
-    /**
-     * Content shown when no value is selected.
-     * @default undefined — renders nothing when no value is selected.
-     */
-    placeholder?: React.ReactNode;
+    /** Shown while no option is selected. @default undefined — renders nothing. */
+    placeholder?: React.ReactNode | undefined;
 }
-/** Props for {@link SelectIcon}, a decorative indicator inside the trigger (defaults to `▾`). */
+/** Props for SelectIcon, a decorative indicator inside the trigger (defaults to ▾). */
 export interface SelectIconProps extends PrimitivePropsWithRef<'span'> {
 }
-/** Props for {@link SelectPortal}, which teleports its content to `document.body` while the listbox is open. */
+/** Props for SelectPortal: teleports its content to document.body while the listbox is open. */
 export interface SelectPortalProps extends PortalProps {
-    /**
-     * Render (and mount `SelectContent`) 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;
+    /** Mount SelectContent even while closed, for animation exit transitions. @default false */
+    forceMount?: boolean | undefined;
 }
-/**
- * Props for {@link SelectContent}, the listbox popup. Extends
- * {@link PopperContentProps} (`side`, `align`, `sideOffset`, `alignOffset`,
- * `avoidCollisions`, `collisionPadding`) for floating-ui positioning relative
- * to the trigger — note `SelectContent` defaults `side` to `'bottom'`,
- * `align` to `'start'`, and `sideOffset` to `4`, instead of the popper base
- * defaults (`'bottom'` / `'center'` / `0`).
- */
+/** Props for SelectContent: the listbox popup with side='bottom', align='start', sideOffset=4 defaults. */
 export interface SelectContentProps extends PopperContentProps {
+    /** Mount listbox even while closed, for animation exit transitions. @default false */
+    forceMount?: boolean | undefined;
+    /** Fires on Escape while open; preventDefault() keeps it open. @default undefined — no-op if omitted. */
+    onEscapeKeyDown?: ((event: KeyboardEvent) => void) | undefined;
+    /** Fires on pointer-down outside listbox and trigger; preventDefault() keeps it open. @default undefined — no-op if omitted. */
+    onPointerDownOutside?: ((event: PointerEvent) => void) | undefined;
+    /** Fires when focus moves outside (cancelable focusin stand-in); preventDefault() keeps it open. @default undefined — no-op if omitted. */
+    onFocusOutside?: ((event: CustomEvent<FocusEvent>) => void) | undefined;
+    /** Fires for outside interaction before specific handler; preventDefault() vetoes both paths. @default undefined — no-op if omitted. */
+    onInteractOutside?: ((event: InteractOutsideEvent) => void) | undefined;
+    /** Fires before focus returns to trigger as listbox closes; preventDefault() suppresses return. @default undefined — no-op if omitted. */
+    onCloseAutoFocus?: ((event: AutoFocusEvent) => void) | undefined;
     /**
-     * Keep this listbox mounted even while closed, instead of unmounting it.
-     * @default false
-     */
-    forceMount?: boolean;
-    /**
-     * Fires on Escape while open. `preventDefault()` keeps the listbox open.
-     * @default undefined — no-op if omitted.
-     */
-    onEscapeKeyDown?: (event: KeyboardEvent) => void;
-    /**
-     * Fires on a pointer-down outside the listbox and trigger. `preventDefault()` keeps it open.
-     * @default undefined — no-op if omitted.
-     */
-    onPointerDownOutside?: (event: PointerEvent) => void;
-    /**
-     * Fires when focus moves outside the listbox and trigger, carrying a
-     * cancelable stand-in for the uncancelable `focusin`. `preventDefault()`
-     * keeps the listbox open.
-     * @default undefined — no-op if omitted.
+     * Matches this panel width to its trigger, mirrored as a bare `data-match-width`.
+     * @default undefined — the panel sizes to its content.
      */
-    onFocusOutside?: (event: CustomEvent<FocusEvent>) => void;
-    /**
-     * Fires for *either* kind of outside interaction, immediately before the
-     * specific handler and with the same event — so one `preventDefault()`
-     * vetoes both paths.
-     * @default undefined — no-op if omitted.
-     */
-    onInteractOutside?: (event: InteractOutsideEvent) => void;
+    matchWidth?: boolean | undefined;
 }
 /** Props for {@link SelectViewport}, the scrollable container for `SelectItem`s inside `SelectContent`. */
 export interface SelectViewportProps extends PrimitivePropsWithRef<'div'> {
 }
-/** @internal Shared state distributed from {@link SelectItem} to its text/indicator via context. Not part of the public API. */
+/** @internal Shared state distributed from SelectItem to its text/indicator via context. */
 export interface SelectItemContextValue {
     value: string;
     selected: boolean;
     registerText: (text: string) => void;
 }
-/** Props for a single {@link SelectItem} option within `SelectContent`. */
+/** Props for a single SelectItem option within SelectContent. */
 export interface SelectItemProps extends PrimitivePropsWithRef<'div'> {
-    /** Unique identifier committed to the select root's value when this option is chosen. */
+    /** Identifier committed to the root's value when chosen. */
     value: string;
-    /**
-     * Excludes this option from selection and keyboard/typeahead navigation.
-     * @default false
-     */
-    disabled?: boolean;
-    /**
-     * Text used for the trigger label; defaults to the item's text content.
-     * @default undefined — falls back to the item's rendered text content.
-     */
-    textValue?: string;
+    /** Excludes from selection and keyboard navigation. @default false */
+    disabled?: boolean | undefined;
+    /** Text for Trigger label and typeahead, published as data-text-value; falls back to rendered text. @default undefined — falls back to rendered text. */
+    textValue?: string | undefined;
 }
-/** Props for {@link SelectItemText}, the label content of a {@link SelectItem}, whose text is captured for `SelectValue`. */
+/** Props for SelectItemText: an Item's label content, captured so Value can render it inside Trigger. */
 export interface SelectItemTextProps extends PrimitivePropsWithRef<'span'> {
 }
-/** Props for {@link SelectItemIndicator}, shown inside a {@link SelectItem} when it's the selected option. */
+/** Props for SelectItemIndicator: selected-state glyph inside an Item, rendered only while selected. */
 export interface SelectItemIndicatorProps extends PrimitivePropsWithRef<'span'> {
-    /**
-     * Keep this indicator mounted even while its item isn't selected, instead
-     * of rendering nothing.
-     * @default false
-     */
-    forceMount?: boolean;
+    /** Mount this indicator even while its item isn't selected, for animation exit transitions. @default false */
+    forceMount?: boolean | undefined;
 }
-/** Props for {@link SelectGroup}, a labeled group of related `SelectItem`s. */
+/** Props for SelectGroup, a labeled group of related SelectItems. */
 export interface SelectGroupProps extends PrimitivePropsWithRef<'div'> {
 }
-/** Props for {@link SelectLabel}, a heading for a {@link SelectGroup}. */
+/** What SelectGroup publishes to its SelectLabel: the id the group points aria-labelledby at. */
+export interface SelectGroupContextValue {
+    /** The id the group's aria-labelledby names (null when SelectLabel rendered outside any group). */
+    labelId: string | null;
+}
+/** Props for SelectLabel: non-interactive heading for Group, providing its accessible name. */
 export interface SelectLabelProps extends PrimitivePropsWithRef<'div'> {
 }
-/** Props for {@link SelectSeparator}, a visual divider between items or groups. */
+/** Props for SelectSeparator: visual divider between Items or Groups inside Content, renders aria-hidden element. */
 export interface SelectSeparatorProps extends PrimitivePropsWithRef<'div'> {
 }
-/**
- * What {@link Select}'s forwarded ref carries. The root renders no DOM of its
- * own besides its mirrored inputs, so the ref is these two
- * constraint-validation methods and nothing else —
- * `React.useRef<SelectHandle>(null)`.
- */
+/** What Select's forwarded ref carries: constraint-validation methods only (root renders no DOM besides mirrored inputs). */
 export type SelectHandle = FormValidityHandle;

package/dist/skeleton/Skeleton.cjs

@@ -1 +1,2 @@
-"use strict";var n=Object.create;var m=Object.defineProperty;var d=Object.getOwnPropertyDescriptor;var y=Object.getOwnPropertyNames;var P=Object.getPrototypeOf,S=Object.prototype.hasOwnProperty;var x=(e,o)=>{for(var t in o)m(e,t,{get:o[t],enumerable:!0})},a=(e,o,t,p)=>{if(o&&typeof o=="object"||typeof o=="function")for(let r of y(o))!S.call(e,r)&&r!==t&&m(e,r,{get:()=>o[r],enumerable:!(p=d(o,r))||p.enumerable});return e};var c=(e,o,t)=>(t=e!=null?n(P(e)):{},a(o||!e||!e.__esModule?m(t,"default",{value:e,enumerable:!0}):t,e)),v=e=>a(m({},"__esModule",{value:!0}),e);var R={};x(R,{Skeleton:()=>f});module.exports=v(R);var s=c(require("react"),1),i=require("../utils/part.cjs"),l=require("../utils/primitive.cjs"),k=require("react/jsx-runtime"),f=s.forwardRef((e,o)=>(0,k.jsx)(l.Primitive.div,{"aria-hidden":"true","data-skdx-skeleton":"",...e,...(0,i.skdxPart)("skeleton","root",e.className),ref:o}));f.displayName="Skeleton";0&&(module.exports={Skeleton});
+'use client';
+"use strict";var a=Object.defineProperty;var n=Object.getOwnPropertyDescriptor;var k=Object.getOwnPropertyNames;var c=Object.prototype.hasOwnProperty;var d=(t,e)=>{for(var o in e)a(t,o,{get:e[o],enumerable:!0})},y=(t,e,o,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let p of k(e))!c.call(t,p)&&p!==o&&a(t,p,{get:()=>e[p],enumerable:!(r=n(e,p))||r.enumerable});return t};var P=t=>y(a({},"__esModule",{value:!0}),t);var S={};d(S,{Skeleton:()=>f});module.exports=P(S);var m=require("../utils/appearance.cjs"),i=require("../utils/part.cjs"),s=require("../utils/primitive.cjs"),l=require("react/jsx-runtime"),f=({animation:t,shape:e,ref:o,...r})=>(0,l.jsx)(s.Primitive.div,{...r,"aria-hidden":"true",...(0,m.appearanceAttrs)({animation:t,shape:e},r),...(0,i.skdxPart)("skeleton","root",r.className),ref:o});f.displayName="Skeleton";0&&(module.exports={Skeleton});

package/dist/skeleton/Skeleton.d.cts

@@ -1,14 +1,16 @@
-import * as React from 'react';
+import type * as React from 'react';
 import type { SkeletonProps } from './types.cjs';
 /**
- * Loading placeholder block. Renders a `<div>` with `aria-hidden="true"` and
- * `data-skdx-skeleton` — purely visual, hidden from assistive tech so screen
- * readers don't announce placeholder content as if it were real. Shape/size
- * and shimmer animation are brand-layer concerns applied via `className`.
+ * Loading placeholder block, rendered as a purely visual `<div>` with `aria-hidden="true"`.
  *
  * @example
  * ```tsx
- * <Skeleton style={{ width: 200, height: 20 }} />
+ * <section aria-busy={loading} aria-label="Recent activity">
+ *   {loading ? <Skeleton style={{ width: 200, height: 20 }} /> : <ActivityList />}
+ * </section>
  * ```
  */
-export declare const Skeleton: React.ForwardRefExoticComponent<Omit<SkeletonProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export declare const Skeleton: {
+    ({ animation, shape, ref: forwardedRef, ...props }: SkeletonProps): React.ReactNode;
+    displayName: string;
+};

package/dist/skeleton/Skeleton.d.ts

@@ -1,14 +1,16 @@
-import * as React from 'react';
+import type * as React from 'react';
 import type { SkeletonProps } from './types.js';
 /**
- * Loading placeholder block. Renders a `<div>` with `aria-hidden="true"` and
- * `data-skdx-skeleton` — purely visual, hidden from assistive tech so screen
- * readers don't announce placeholder content as if it were real. Shape/size
- * and shimmer animation are brand-layer concerns applied via `className`.
+ * Loading placeholder block, rendered as a purely visual `<div>` with `aria-hidden="true"`.
  *
  * @example
  * ```tsx
- * <Skeleton style={{ width: 200, height: 20 }} />
+ * <section aria-busy={loading} aria-label="Recent activity">
+ *   {loading ? <Skeleton style={{ width: 200, height: 20 }} /> : <ActivityList />}
+ * </section>
  * ```
  */
-export declare const Skeleton: React.ForwardRefExoticComponent<Omit<SkeletonProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export declare const Skeleton: {
+    ({ animation, shape, ref: forwardedRef, ...props }: SkeletonProps): React.ReactNode;
+    displayName: string;
+};

package/dist/skeleton/Skeleton.js

@@ -1 +1,2 @@
-import*as o from"react";import{skdxPart as r}from"../utils/part.js";import{Primitive as m}from"../utils/primitive.js";import{jsx as a}from"react/jsx-runtime";var p=o.forwardRef((e,t)=>a(m.div,{"aria-hidden":"true","data-skdx-skeleton":"",...e,...r("skeleton","root",e.className),ref:t}));p.displayName="Skeleton";export{p as Skeleton};
+'use client';
+import{appearanceAttrs as p}from"../utils/appearance.js";import{skdxPart as a}from"../utils/part.js";import{Primitive as m}from"../utils/primitive.js";import{jsx as s}from"react/jsx-runtime";var i=({animation:t,shape:o,ref:r,...e})=>s(m.div,{...e,"aria-hidden":"true",...p({animation:t,shape:o},e),...a("skeleton","root",e.className),ref:r});i.displayName="Skeleton";export{i as Skeleton};

package/dist/skeleton/types.d.cts

@@ -1,4 +1,14 @@
 import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
 /** Props for the {@link Skeleton} root. */
 export interface SkeletonProps extends PrimitivePropsWithRef<'div'> {
+    /**
+     * Turns the skin shimmer off, mirrored to `data-animation` on the root.
+     * @default undefined — the skin animates the placeholder.
+     */
+    animation?: 'none' | (string & {}) | undefined;
+    /**
+     * Corner rung the skin rounds the placeholder by, mirrored to `data-shape`.
+     * @default undefined — the skin's own default corner.
+     */
+    shape?: 'line' | 'circle' | (string & {}) | undefined;
 }