@skdx/react 0.26.0 → 0.28.0

package/dist/select/primitives.d.cts

@@ -0,0 +1,39 @@
+/**
+ * Primitives for `Select` — manual composition escape hatch.
+ *
+ * @example
+ * ```tsx
+ * import { Select, SelectTrigger, SelectValue, SelectIcon, SelectPortal, SelectContent, SelectViewport, SelectItem, SelectItemIndicator, SelectItemText } from '@skdx/react/primitives/select';
+ *
+ * <Select defaultValue="react">
+ *   <SelectTrigger>
+ *     <SelectValue placeholder="Pick a framework" />
+ *     <SelectIcon />
+ *   </SelectTrigger>
+ *   <SelectPortal>
+ *     <SelectContent>
+ *       <SelectViewport>
+ *         <SelectItem value="react">
+ *           <SelectItemIndicator>✓</SelectItemIndicator>
+ *           <SelectItemText>React</SelectItemText>
+ *         </SelectItem>
+ *       </SelectViewport>
+ *     </SelectContent>
+ *   </SelectPortal>
+ * </Select>
+ * ```
+ */
+export { Select } from './Select.cjs';
+export { SelectTrigger } from './SelectTrigger.cjs';
+export { SelectValue } from './SelectValue.cjs';
+export { SelectIcon } from './SelectIcon.cjs';
+export { SelectPortal } from './SelectPortal.cjs';
+export { SelectContent } from './SelectContent.cjs';
+export { SelectViewport } from './SelectViewport.cjs';
+export { SelectItem } from './SelectItem.cjs';
+export { SelectItemText } from './SelectItemText.cjs';
+export { SelectItemIndicator } from './SelectItemIndicator.cjs';
+export { SelectGroup } from './SelectGroup.cjs';
+export { SelectLabel } from './SelectLabel.cjs';
+export { SelectSeparator } from './SelectSeparator.cjs';
+export type { SelectProps, SelectTriggerProps, SelectValueProps, SelectIconProps, SelectPortalProps, SelectContentProps, SelectViewportProps, SelectItemProps, SelectItemTextProps, SelectItemIndicatorProps, SelectGroupProps, SelectLabelProps, SelectSeparatorProps, } from './types.cjs';

package/dist/select/primitives.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Primitives for `Select` — manual composition escape hatch.
+ *
+ * @example
+ * ```tsx
+ * import { Select, SelectTrigger, SelectValue, SelectIcon, SelectPortal, SelectContent, SelectViewport, SelectItem, SelectItemIndicator, SelectItemText } from '@skdx/react/primitives/select';
+ *
+ * <Select defaultValue="react">
+ *   <SelectTrigger>
+ *     <SelectValue placeholder="Pick a framework" />
+ *     <SelectIcon />
+ *   </SelectTrigger>
+ *   <SelectPortal>
+ *     <SelectContent>
+ *       <SelectViewport>
+ *         <SelectItem value="react">
+ *           <SelectItemIndicator>✓</SelectItemIndicator>
+ *           <SelectItemText>React</SelectItemText>
+ *         </SelectItem>
+ *       </SelectViewport>
+ *     </SelectContent>
+ *   </SelectPortal>
+ * </Select>
+ * ```
+ */
+export { Select } from './Select.js';
+export { SelectTrigger } from './SelectTrigger.js';
+export { SelectValue } from './SelectValue.js';
+export { SelectIcon } from './SelectIcon.js';
+export { SelectPortal } from './SelectPortal.js';
+export { SelectContent } from './SelectContent.js';
+export { SelectViewport } from './SelectViewport.js';
+export { SelectItem } from './SelectItem.js';
+export { SelectItemText } from './SelectItemText.js';
+export { SelectItemIndicator } from './SelectItemIndicator.js';
+export { SelectGroup } from './SelectGroup.js';
+export { SelectLabel } from './SelectLabel.js';
+export { SelectSeparator } from './SelectSeparator.js';
+export type { SelectProps, SelectTriggerProps, SelectValueProps, SelectIconProps, SelectPortalProps, SelectContentProps, SelectViewportProps, SelectItemProps, SelectItemTextProps, SelectItemIndicatorProps, SelectGroupProps, SelectLabelProps, SelectSeparatorProps, } from './types.js';

package/dist/select/types.d.cts

@@ -1,258 +1,210 @@
 import type * as React from 'react';
 import type { FormValidityHandle } from '../utils/formControl.cjs';
+import type { PassThroughProps } from '../utils/passThrough.cjs';
 import type { PopperContentProps } from '../utils/popper.cjs';
 import type { PortalProps } from '../utils/portal.cjs';
 import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
 import type { InteractOutsideEvent } from '../utils/useDismiss.cjs';
-/**
- * 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 { AutoFocusEvent } from '../utils/useFocusTrap.cjs';
+import type { SelectionChangeDetail } from '../utils/useSelection.cjs';
+/** 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`.
-     */
+    /** Text for SelectValue and typeahead; overridden by mounted SelectItemText. @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
-     */
+    /** Excludes from trigger typeahead; rendered SelectItem's disabled excludes from selection. @default false */
+    disabled?: boolean;
+}
+/** 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;
+    /** Excludes from selection and typeahead. @default false */
     disabled?: boolean;
 }
+/** 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;
+/** 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. Not part of the public API. */
 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.MutableRefObject<((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.MutableRefObject<SelectOpenIntent>;
     /** Whether more than one option can be selected. */
     multiple: boolean;
-    /** Every selected value, normalised to an array whether or not `multiple`. */
+    /** Whether committing an option closes the listbox (defaults to !multiple). */
+    closeOnSelect: boolean;
+    /** 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`. */
+    /** Commits an option: replaces or toggles it when multiple. */
     selectItem: (value: string) => 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;
     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.
-     */
+    /** Selected option value(s) for controlled usage; pair with onValueChange. @default undefined — uncontrolled. */
     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.
-     */
+    /** Initially selected value(s) for uncontrolled usage. @default undefined — no option selected until 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
-     */
+    /** Fires when selection changes with the whole selection, not the toggled option. @default undefined — no-op if omitted. */
+    onValueChange?: (detail: SelectionChangeDetail) => void;
+    /** Allows more than one option selected. Sets aria-multiselectable="true" on Content, toggles options instead of replacing, keeps listbox open. @default false */
     multiple?: boolean;
-    /**
-     * 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.
-     */
+    /** Picking the already-selected option in single-select mode clears it; ignored in multiple mode. @default false */
+    deselectable?: boolean;
+    /** 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[];
-    /**
-     * Whether the listbox popup is open, for controlled usage. Pair with `onOpenChange`.
-     * @default undefined — uncontrolled, tracks its own open state internally.
-     */
+    /** Flat or grouped option data to render automatically — trigger, portal, listbox, and Items — instead of hand composition. @default undefined — compose parts yourself. */
+    options?: SelectOptionOrGroup[];
+    /** 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;
+    /** 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;
+    /** Placeholder shown by derived trigger while nothing is selected; only read while options derives. @default undefined — renders nothing when no option selected. */
+    placeholder?: string;
+    /** Picking an option closes the listbox. Defaults to !multiple; can override the default. @default !multiple */
+    closeOnSelect?: boolean;
+    /** Whether the listbox popup is open for controlled usage; pair with onOpenChange. @default undefined — uncontrolled. */
     open?: boolean;
-    /**
-     * Initial open state, for uncontrolled usage.
-     * @default false
-     */
+    /** 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.
-     */
+    /** Fires with 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
-     * `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.
-     */
+    /** Fires with new open state once animation finishes (after SelectContent's enter/exit ends). @default undefined — no-op if omitted. */
     onOpenChangeComplete?: (open: boolean) => void;
-    /**
-     * Disables the trigger and prevents opening the listbox.
-     * @default false
-     */
+    /** Disables the trigger and prevents opening. Distinct from readOnly, which keeps focusable and submits. @default false */
     disabled?: boolean;
-    /**
-     * Marks the underlying hidden `<select>` as required for form validation.
-     * Only meaningful when `name` is also set.
-     * @default false
-     */
+    /** Unchangeable value. Trigger keeps tab stop and focus, carries aria-readonly="true" and data-readonly, submits the value. @default false */
+    readOnly?: boolean;
+    /** Marks hidden form controls as required for constraint validation (only meaningful when name is set). @default false */
     required?: boolean;
-    /**
-     * Marks the select as invalid, exposed as `aria-invalid`/`data-invalid` on
-     * the `SelectTrigger`.
-     * @default false
-     */
+    /** Marks select as invalid, exposed as aria-invalid/data-invalid on SelectTrigger. @default false */
     invalid?: boolean;
-    /**
-     * 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.
-     */
+    /** Visually-hidden native form control kept in sync with value for submission, reset, and validation. @default undefined — no hidden control. */
     name?: string;
+    /** 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;
+    /** 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;
 }
 /** Props for {@link SelectTrigger}, the button that opens the listbox and displays the current value. */
 export interface SelectTriggerProps extends PrimitivePropsWithRef<'button'> {
 }
-/** Props for {@link SelectValue}, which renders the selected option's label (or a placeholder) inside the trigger. */
+/** 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.
-     */
+    /** Shown while no option is selected. @default undefined — renders nothing. */
     placeholder?: React.ReactNode;
 }
-/** 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
-     */
+    /** Mount SelectContent even while closed, for animation exit transitions. @default false */
     forceMount?: boolean;
 }
-/**
- * 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 {
-    /**
-     * Keep this listbox mounted even while closed, instead of unmounting it.
-     * @default false
-     */
+    /** Mount listbox even while closed, for animation exit transitions. @default false */
     forceMount?: boolean;
-    /**
-     * Fires on Escape while open. `preventDefault()` keeps the listbox open.
-     * @default undefined — no-op if omitted.
-     */
+    /** Fires on Escape while open; preventDefault() keeps it 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.
-     */
+    /** Fires on pointer-down outside 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.
-     */
+    /** Fires when focus moves outside (cancelable focusin stand-in); preventDefault() keeps it open. @default undefined — no-op if omitted. */
     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.
-     */
+    /** Fires for outside interaction before specific handler; preventDefault() vetoes both paths. @default undefined — no-op if omitted. */
     onInteractOutside?: (event: InteractOutsideEvent) => void;
+    /** Fires before focus returns to trigger as listbox closes; preventDefault() suppresses return. @default undefined — no-op if omitted. */
+    onCloseAutoFocus?: (event: AutoFocusEvent) => void;
 }
 /** 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
-     */
+    /** Excludes from selection and keyboard 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.
-     */
+    /** 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;
 }
-/** 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
-     */
+    /** Mount this indicator even while its item isn't selected, for animation exit transitions. @default false */
     forceMount?: boolean;
 }
-/** 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;