@skdx/react 0.26.0

package/dist/select/SelectSeparator.d.ts

@@ -0,0 +1,16 @@
+import * as React from 'react';
+import type { SelectSeparatorProps } from './types.js';
+/**
+ * Visual divider between `SelectItem`s or `SelectGroup`s inside
+ * {@link SelectContent}. Renders an `aria-hidden` `<div>`.
+ *
+ * @example
+ * ```tsx
+ * <SelectViewport>
+ *   <SelectItem value="react"><SelectItemText>react</SelectItemText></SelectItem>
+ *   <SelectSeparator />
+ *   <SelectItem value="vue"><SelectItemText>vue</SelectItemText></SelectItem>
+ * </SelectViewport>
+ * ```
+ */
+export declare const SelectSeparator: React.ForwardRefExoticComponent<Omit<SelectSeparatorProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/select/SelectTrigger.d.cts

@@ -0,0 +1,27 @@
+import * as React from 'react';
+import type { SelectTriggerProps } from './types.cjs';
+/**
+ * Opens the {@link Select}'s listbox and displays the current value, and
+ * doubles as the popper anchor the listbox positions against. Renders a
+ * `<button type="button" role="combobox">` with `aria-haspopup="listbox"`,
+ * `aria-expanded`, `aria-controls` pointing at the content, `aria-required`,
+ * `data-state`, `data-disabled`, `data-placeholder`, and
+ * `aria-invalid`/`data-invalid` when the select is `invalid`. Click, Enter,
+ * Space, or Arrow Up/Down opens the listbox.
+ *
+ * Printable characters run typeahead against the root's option collection
+ * *without* opening the listbox, the way a native closed `<select>` behaves —
+ * which needs labels the root already knows, so pass `items` on the root if
+ * the listbox has never been opened. A `multiple` select opens the listbox
+ * instead: changing an unseen selection blind would silently toggle an option
+ * the user cannot check.
+ *
+ * @example
+ * ```tsx
+ * <SelectTrigger>
+ *   <SelectValue placeholder="Pick a framework" />
+ *   <SelectIcon />
+ * </SelectTrigger>
+ * ```
+ */
+export declare const SelectTrigger: React.ForwardRefExoticComponent<Omit<SelectTriggerProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/select/SelectTrigger.d.ts

@@ -0,0 +1,27 @@
+import * as React from 'react';
+import type { SelectTriggerProps } from './types.js';
+/**
+ * Opens the {@link Select}'s listbox and displays the current value, and
+ * doubles as the popper anchor the listbox positions against. Renders a
+ * `<button type="button" role="combobox">` with `aria-haspopup="listbox"`,
+ * `aria-expanded`, `aria-controls` pointing at the content, `aria-required`,
+ * `data-state`, `data-disabled`, `data-placeholder`, and
+ * `aria-invalid`/`data-invalid` when the select is `invalid`. Click, Enter,
+ * Space, or Arrow Up/Down opens the listbox.
+ *
+ * Printable characters run typeahead against the root's option collection
+ * *without* opening the listbox, the way a native closed `<select>` behaves —
+ * which needs labels the root already knows, so pass `items` on the root if
+ * the listbox has never been opened. A `multiple` select opens the listbox
+ * instead: changing an unseen selection blind would silently toggle an option
+ * the user cannot check.
+ *
+ * @example
+ * ```tsx
+ * <SelectTrigger>
+ *   <SelectValue placeholder="Pick a framework" />
+ *   <SelectIcon />
+ * </SelectTrigger>
+ * ```
+ */
+export declare const SelectTrigger: React.ForwardRefExoticComponent<Omit<SelectTriggerProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/select/SelectValue.d.cts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import type { SelectValueProps } from './types.cjs';
+/**
+ * Displays the selected {@link Select} option's label (as registered by its
+ * `SelectItemText`, or declared in the root's `items`), or `placeholder` when
+ * nothing is selected. Renders a `<span>` with `pointer-events: none` so
+ * clicks pass through to the trigger. Pass explicit `children` to override the
+ * auto-derived label entirely.
+ *
+ * While the root is `multiple`, renders one chip per selected option instead —
+ * a `data-chip` span carrying `data-value`, to be styled like a TagsInput tag.
+ * The chips are deliberately inert: the trigger is a `<button>`, so a remove
+ * button nested inside one would be invalid HTML and unreachable by keyboard.
+ * Deselecting happens in the listbox.
+ *
+ * @example
+ * ```tsx
+ * <SelectTrigger>
+ *   <SelectValue placeholder="Pick a framework" />
+ *   <SelectIcon />
+ * </SelectTrigger>
+ * ```
+ */
+export declare const SelectValue: React.ForwardRefExoticComponent<Omit<SelectValueProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/select/SelectValue.d.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import type { SelectValueProps } from './types.js';
+/**
+ * Displays the selected {@link Select} option's label (as registered by its
+ * `SelectItemText`, or declared in the root's `items`), or `placeholder` when
+ * nothing is selected. Renders a `<span>` with `pointer-events: none` so
+ * clicks pass through to the trigger. Pass explicit `children` to override the
+ * auto-derived label entirely.
+ *
+ * While the root is `multiple`, renders one chip per selected option instead —
+ * a `data-chip` span carrying `data-value`, to be styled like a TagsInput tag.
+ * The chips are deliberately inert: the trigger is a `<button>`, so a remove
+ * button nested inside one would be invalid HTML and unreachable by keyboard.
+ * Deselecting happens in the listbox.
+ *
+ * @example
+ * ```tsx
+ * <SelectTrigger>
+ *   <SelectValue placeholder="Pick a framework" />
+ *   <SelectIcon />
+ * </SelectTrigger>
+ * ```
+ */
+export declare const SelectValue: React.ForwardRefExoticComponent<Omit<SelectValueProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/select/SelectViewport.d.cts

@@ -0,0 +1,16 @@
+import * as React from 'react';
+import type { SelectViewportProps } from './types.cjs';
+/**
+ * Scrollable container for `SelectItem`s inside {@link SelectContent}.
+ * Renders a plain `<div>` with `overflow: auto`.
+ *
+ * @example
+ * ```tsx
+ * <SelectViewport>
+ *   <SelectItem value="react">
+ *     <SelectItemText>react</SelectItemText>
+ *   </SelectItem>
+ * </SelectViewport>
+ * ```
+ */
+export declare const SelectViewport: React.ForwardRefExoticComponent<Omit<SelectViewportProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/select/SelectViewport.d.ts

@@ -0,0 +1,16 @@
+import * as React from 'react';
+import type { SelectViewportProps } from './types.js';
+/**
+ * Scrollable container for `SelectItem`s inside {@link SelectContent}.
+ * Renders a plain `<div>` with `overflow: auto`.
+ *
+ * @example
+ * ```tsx
+ * <SelectViewport>
+ *   <SelectItem value="react">
+ *     <SelectItemText>react</SelectItemText>
+ *   </SelectItem>
+ * </SelectViewport>
+ * ```
+ */
+export declare const SelectViewport: React.ForwardRefExoticComponent<Omit<SelectViewportProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/select/index.d.cts

@@ -0,0 +1,14 @@
+export * 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 { SelectItemDescriptor, SelectProps, SelectHandle, SelectTriggerProps, SelectValueProps, SelectIconProps, SelectPortalProps, SelectContentProps, SelectViewportProps, SelectItemProps, SelectItemTextProps, SelectItemIndicatorProps, SelectGroupProps, SelectLabelProps, SelectSeparatorProps, } from './types.cjs';

package/dist/select/index.d.ts

@@ -0,0 +1,14 @@
+export * 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 { SelectItemDescriptor, SelectProps, SelectHandle, SelectTriggerProps, SelectValueProps, SelectIconProps, SelectPortalProps, SelectContentProps, SelectViewportProps, SelectItemProps, SelectItemTextProps, SelectItemIndicatorProps, SelectGroupProps, SelectLabelProps, SelectSeparatorProps, } from './types.js';

package/dist/select/types.d.cts

@@ -0,0 +1,258 @@
+import type * as React from 'react';
+import type { FormValidityHandle } from '../utils/formControl.cjs';
+import type { PopperContentProps } from '../utils/popper.cjs';
+import type { PortalProps } from '../utils/portal.cjs';
+import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
+import type { 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.
+ */
+export interface SelectItemDescriptor {
+    /** Identifier committed to the root's value when this option is 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;
+}
+/** @internal Shared state distributed from {@link Select} to its parts via context. Not part of the public API. */
+export interface SelectContextValue {
+    triggerRef: React.RefObject<HTMLButtonElement | null>;
+    contentRef: React.RefObject<HTMLDivElement | null>;
+    contentId: string;
+    /** Whether more than one option can be selected. */
+    multiple: boolean;
+    /** Every selected value, normalised to an array whether or not `multiple`. */
+    selectedValues: string[];
+    /** Whether one option value is currently selected. */
+    isSelected: (value: string) => boolean;
+    /** Commits an option: replaces the selection, or toggles it within it when `multiple`. */
+    selectItem: (value: string) => void;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    disabled: 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. */
+    getOptionLabel: (value: string) => string;
+    /** Every option the root knows about without opening the listbox — the trigger-typeahead pool. */
+    collection: SelectItemDescriptor[];
+}
+/** Props for the {@link Select} root. */
+export interface SelectProps {
+    /**
+     * The trigger, portal, and content parts, distributed 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;
+    /**
+     * 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.
+     */
+    items?: SelectItemDescriptor[];
+    /**
+     * Whether the listbox popup is open, for controlled usage. Pair with `onOpenChange`.
+     * @default undefined — uncontrolled, tracks its own open state internally.
+     */
+    open?: boolean;
+    /**
+     * Initial open state, for uncontrolled usage.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * Fires with the new open state whenever it changes, controlled or not.
+     * @default undefined — no-op if omitted.
+     */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Fires with the new open state once the change has finished on screen — after
+     * `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.
+     */
+    onOpenChangeComplete?: (open: boolean) => void;
+    /**
+     * Disables the trigger and prevents opening the listbox.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Marks the underlying hidden `<select>` as required for form validation.
+     * Only meaningful when `name` is also set.
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * Marks the select as invalid, exposed as `aria-invalid`/`data-invalid` on
+     * the `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.
+     */
+    name?: 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. */
+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;
+}
+/** Props for {@link 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. */
+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;
+}
+/**
+ * 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`).
+ */
+export interface SelectContentProps extends PopperContentProps {
+    /**
+     * 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.
+     */
+    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;
+}
+/** 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. */
+export interface SelectItemContextValue {
+    value: string;
+    selected: boolean;
+    registerText: (text: string) => void;
+}
+/** Props for a single {@link SelectItem} option within `SelectContent`. */
+export interface SelectItemProps extends PrimitivePropsWithRef<'div'> {
+    /** Unique identifier committed to the select root's value when this option is 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;
+}
+/** Props for {@link SelectItemText}, the label content of a {@link SelectItem}, whose text is captured for `SelectValue`. */
+export interface SelectItemTextProps extends PrimitivePropsWithRef<'span'> {
+}
+/** Props for {@link SelectItemIndicator}, shown inside a {@link SelectItem} when it's the selected option. */
+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;
+}
+/** Props for {@link SelectGroup}, a labeled group of related `SelectItem`s. */
+export interface SelectGroupProps extends PrimitivePropsWithRef<'div'> {
+}
+/** Props for {@link SelectLabel}, a heading for a {@link SelectGroup}. */
+export interface SelectLabelProps extends PrimitivePropsWithRef<'div'> {
+}
+/** Props for {@link SelectSeparator}, a visual divider between items or groups. */
+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)`.
+ */
+export type SelectHandle = FormValidityHandle;