@kenos-ui/react-select 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,320 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React, { HTMLAttributes, ReactNode, RefObject, ButtonHTMLAttributes } from 'react';
+
+interface SelectItemRecord {
+    value: string;
+    /** Displayed label (from ItemText child). */
+    label: string;
+    /** Used by typeahead. Defaults to label. */
+    textValue: string;
+    disabled: boolean;
+    /** The DOM element for the option — needed for aria-activedescendant. */
+    ref: HTMLElement | null;
+    groupId: string | null;
+}
+type SelectItemEqualFn = (a: string, b: string) => boolean;
+interface SelectStoreState {
+    open: boolean;
+    openSource: "trigger" | null;
+    value: string | string[] | null;
+    highlightedValue: string | null;
+    /** Item registry: populated as Select.Item mounts. */
+    items: Map<string, SelectItemRecord>;
+}
+interface SelectRootPropsBase {
+    children: ReactNode;
+    /** Controlled open state. */
+    open?: boolean | undefined;
+    defaultOpen?: boolean | undefined;
+    onOpenChange?: ((open: boolean) => void) | undefined;
+    /** Fires when open transitions finish (including presence exit). */
+    onOpenChangeComplete?: ((open: boolean) => void) | undefined;
+    /** Native <select> name for form submission. */
+    name?: string | undefined;
+    disabled?: boolean | undefined;
+    required?: boolean | undefined;
+    readOnly?: boolean | undefined;
+    /**
+     * When true, a focus trap + aria-modal is applied.
+     * **Default: false** (interop-first per popup-policy).
+     */
+    modal?: boolean | undefined;
+    /** Unique id prefix (auto-generated when omitted). */
+    id?: string | undefined;
+    /**
+     * Static value→label map for Value/HiddenSelect when items are not mounted.
+     * Registry labels take precedence when both exist.
+     */
+    items?: Record<string, string> | undefined;
+    /** Custom equality for value matching. Default: strict `===`. */
+    isItemEqualToValue?: SelectItemEqualFn | undefined;
+    /**
+     * When true, focusing the trigger opens the listbox.
+     * **Default: false**
+     */
+    openOnFocus?: boolean | undefined;
+}
+interface SelectRootPropsSingle extends SelectRootPropsBase {
+    multiple?: false | undefined;
+    /** Controlled value. */
+    value?: string | null | undefined;
+    /** Uncontrolled default value. */
+    defaultValue?: string | null | undefined;
+    onValueChange?: ((value: string | null) => void) | undefined;
+}
+interface SelectRootPropsMultiple extends SelectRootPropsBase {
+    multiple: true;
+    /** Controlled value. */
+    value?: string[] | undefined;
+    /** Uncontrolled default value. */
+    defaultValue?: string[] | undefined;
+    onValueChange?: ((value: string[]) => void) | undefined;
+}
+type SelectRootProps = SelectRootPropsSingle | SelectRootPropsMultiple;
+type SelectPortalContainer = HTMLElement | RefObject<HTMLElement | null> | null;
+interface SelectPortalProps {
+    children?: ReactNode;
+    /** Portal mount target. Defaults to `document.body`. */
+    container?: SelectPortalContainer | undefined;
+}
+interface SelectPositionerProps {
+    children?: ReactNode;
+    side?: "top" | "bottom" | "left" | "right" | undefined;
+    align?: "start" | "center" | "end" | undefined;
+    sideOffset?: number | undefined;
+    alignOffset?: number | undefined;
+    avoidCollisions?: boolean | undefined;
+    collisionPadding?: number | undefined;
+    /** Match the trigger's width. Default: false. */
+    sameWidth?: boolean | undefined;
+    /**
+     * When true, positions content to cover the trigger.
+     * For `side="bottom"`, aligns the top of content with the top of the trigger.
+     * **Default: false**
+     */
+    alignItemWithTrigger?: boolean | undefined;
+}
+interface SelectBackdropProps extends HTMLAttributes<HTMLDivElement> {
+}
+interface SelectClearTriggerProps extends HTMLAttributes<HTMLSpanElement> {
+}
+interface SelectScrollButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    direction: "up" | "down";
+    /**
+     * Keep the button in the DOM when the list is not scrollable in this direction.
+     * **Default: false**
+     */
+    keepMounted?: boolean | undefined;
+}
+type SelectScrollUpButtonProps = Omit<SelectScrollButtonProps, "direction">;
+type SelectScrollDownButtonProps = Omit<SelectScrollButtonProps, "direction">;
+type ScrollToIndexAlign = "auto" | "start" | "end" | "center" | "nearest";
+interface ScrollToIndexOptions {
+    align?: ScrollToIndexAlign | undefined;
+}
+interface SelectContentProps {
+    children?: ReactNode;
+    /** Force content to stay in the DOM even when closed. */
+    forceMount?: boolean | undefined;
+    side?: "top" | "bottom" | "left" | "right" | undefined;
+    align?: "start" | "center" | "end" | undefined;
+    sideOffset?: number | undefined;
+    alignOffset?: number | undefined;
+    avoidCollisions?: boolean | undefined;
+    collisionPadding?: number | undefined;
+    /**
+     * When true, the content renders in a portal appended to document.body.
+     * **Default: false** (interop-first per popup-policy).
+     */
+    portal?: boolean | undefined;
+    /**
+     * Portal mount target when `portal` is true.
+     * Defaults to `document.body`. Ignored when nested inside `<Select.Portal>`.
+     */
+    container?: SelectPortalContainer | undefined;
+    /** Match the trigger's width. Default: false. */
+    sameWidth?: boolean | undefined;
+    /**
+     * When true, positions content to cover the trigger.
+     * For `side="bottom"`, aligns the top of content with the top of the trigger.
+     * **Default: false**
+     */
+    alignItemWithTrigger?: boolean | undefined;
+    /** Skip DOM until first open. Default: true. */
+    lazyMount?: boolean | undefined;
+    /** Remove from DOM when closed. Default: false. */
+    unmountOnExit?: boolean | undefined;
+    /**
+     * Fires when open transitions finish (including presence exit).
+     * Prefer `onOpenChangeComplete` on `<Select.Root>`; this prop overrides the root callback.
+     */
+    onOpenChangeComplete?: ((open: boolean) => void) | undefined;
+}
+
+declare function Root(props: SelectRootProps): react_jsx_runtime.JSX.Element;
+
+type LabelProps = React.LabelHTMLAttributes<HTMLLabelElement>;
+declare function Label({ children, ...props }: LabelProps): react_jsx_runtime.JSX.Element;
+
+type TriggerProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "aria-haspopup" | "aria-expanded" | "aria-controls"> & {
+    /**
+     * When true, focusing the trigger opens the listbox.
+     * Overrides `openOnFocus` on `<Select.Root>` when set.
+     */
+    openOnFocus?: boolean | undefined;
+};
+declare function Trigger({ children, onClick, onFocus, disabled, openOnFocus: openOnFocusProp, ...props }: TriggerProps): react_jsx_runtime.JSX.Element;
+
+interface ValueProps extends React.HTMLAttributes<HTMLSpanElement> {
+    placeholder?: string | undefined;
+}
+declare function Value({ placeholder, ...props }: ValueProps): react_jsx_runtime.JSX.Element;
+
+type IconProps = React.HTMLAttributes<HTMLSpanElement>;
+/** Chevron/arrow slot — render your own icon as children. */
+declare function Icon({ children, ...props }: IconProps): react_jsx_runtime.JSX.Element;
+
+declare function Content({ children, forceMount, side, align, sideOffset, alignOffset, avoidCollisions, collisionPadding, portal, container, sameWidth, alignItemWithTrigger, lazyMount, unmountOnExit, onOpenChangeComplete: onOpenChangeCompleteProp, style, onKeyDown, ...props }: SelectContentProps & React.HTMLAttributes<HTMLDivElement>): react_jsx_runtime.JSX.Element | null;
+
+declare function Portal({ children, container }: SelectPortalProps): react_jsx_runtime.JSX.Element | null;
+
+declare function Positioner({ children, side, align, sideOffset, alignOffset, avoidCollisions, collisionPadding, sameWidth, alignItemWithTrigger, }: SelectPositionerProps): react_jsx_runtime.JSX.Element;
+
+declare function Backdrop({ style, ...props }: SelectBackdropProps): react_jsx_runtime.JSX.Element | null;
+
+declare function ClearTrigger({ onClick, ...props }: SelectClearTriggerProps): react_jsx_runtime.JSX.Element | null;
+
+type ListProps = React.HTMLAttributes<HTMLUListElement> & {
+    /**
+     * When set, scrolls the list to the item at this index.
+     * Useful with virtualization or controlled scroll sync.
+     */
+    scrollToIndex?: number | undefined;
+};
+declare function List({ children, scrollToIndex, ...props }: ListProps): react_jsx_runtime.JSX.Element;
+
+interface ItemProps extends React.HTMLAttributes<HTMLLIElement> {
+    value: string;
+    disabled?: boolean | undefined;
+    textValue?: string | undefined;
+}
+declare function Item({ value, disabled, textValue, children, onClick, onPointerMove, ...props }: ItemProps): react_jsx_runtime.JSX.Element;
+declare namespace Item {
+    var displayName: string;
+}
+
+type ItemTextProps = React.HTMLAttributes<HTMLSpanElement>;
+/** Text label for a Select.Item — also used by Select.Value to display the selected label. */
+declare function ItemText({ children, ...props }: ItemTextProps): react_jsx_runtime.JSX.Element;
+
+interface ItemIndicatorProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /** The item value to check — reads from the nearest Item when not provided. */
+    value?: string | undefined;
+}
+/**
+ * Renders only when the parent item is selected.
+ * Wrap a checkmark or any indicator icon as children.
+ */
+declare function ItemIndicator({ value, children, style, ...props }: ItemIndicatorProps): react_jsx_runtime.JSX.Element;
+
+type GroupProps = React.HTMLAttributes<HTMLDivElement>;
+declare function Group({ children, ...props }: GroupProps): react_jsx_runtime.JSX.Element;
+
+type GroupLabelProps = React.HTMLAttributes<HTMLDivElement>;
+declare function GroupLabel({ children, ...props }: GroupLabelProps): react_jsx_runtime.JSX.Element;
+
+declare function HiddenSelect(): react_jsx_runtime.JSX.Element | null;
+
+type ScrollUpButtonProps = Omit<SelectScrollButtonProps, "direction">;
+declare function ScrollUpButton(props: ScrollUpButtonProps): react_jsx_runtime.JSX.Element;
+
+type ScrollDownButtonProps = Omit<SelectScrollButtonProps, "direction">;
+declare function ScrollDownButton(props: ScrollDownButtonProps): react_jsx_runtime.JSX.Element;
+
+declare const index_parts_Backdrop: typeof Backdrop;
+declare const index_parts_ClearTrigger: typeof ClearTrigger;
+declare const index_parts_Content: typeof Content;
+declare const index_parts_Group: typeof Group;
+declare const index_parts_GroupLabel: typeof GroupLabel;
+declare const index_parts_HiddenSelect: typeof HiddenSelect;
+declare const index_parts_Icon: typeof Icon;
+declare const index_parts_Item: typeof Item;
+declare const index_parts_ItemIndicator: typeof ItemIndicator;
+declare const index_parts_ItemText: typeof ItemText;
+declare const index_parts_Label: typeof Label;
+declare const index_parts_List: typeof List;
+declare const index_parts_Portal: typeof Portal;
+declare const index_parts_Positioner: typeof Positioner;
+declare const index_parts_Root: typeof Root;
+declare const index_parts_ScrollDownButton: typeof ScrollDownButton;
+declare const index_parts_ScrollUpButton: typeof ScrollUpButton;
+declare const index_parts_Trigger: typeof Trigger;
+declare const index_parts_Value: typeof Value;
+declare namespace index_parts {
+  export { index_parts_Backdrop as Backdrop, index_parts_ClearTrigger as ClearTrigger, index_parts_Content as Content, index_parts_Group as Group, index_parts_GroupLabel as GroupLabel, index_parts_HiddenSelect as HiddenSelect, index_parts_Icon as Icon, index_parts_Item as Item, index_parts_ItemIndicator as ItemIndicator, index_parts_ItemText as ItemText, index_parts_Label as Label, index_parts_List as List, index_parts_Portal as Portal, index_parts_Positioner as Positioner, index_parts_Root as Root, index_parts_ScrollDownButton as ScrollDownButton, index_parts_ScrollUpButton as ScrollUpButton, index_parts_Trigger as Trigger, index_parts_Value as Value };
+}
+
+declare function scrollToIndexInState(state: SelectStoreState, index: number, options?: ScrollToIndexOptions): void;
+
+type Listener = () => void;
+declare class SelectStore {
+    private state;
+    private listeners;
+    constructor(initial?: Partial<SelectStoreState>);
+    getState(): SelectStoreState;
+    subscribe(listener: Listener): () => void;
+    private notify;
+    setOpen(open: boolean, source?: "trigger" | null): void;
+    setValue(value: string | null): void;
+    setValues(values: string[]): void;
+    toggleValue(value: string, comparator: SelectItemEqualFn): void;
+    clearValue(multiple: boolean): void;
+    isSelected(value: string, multiple: boolean, comparator: SelectItemEqualFn): boolean;
+    setHighlightedValue(value: string | null): void;
+    registerItem(record: SelectItemRecord): void;
+    unregisterItem(value: string): void;
+    updateItemRef(value: string, ref: HTMLElement | null): void;
+}
+
+interface SelectRefs {
+    triggerRef: RefObject<HTMLButtonElement | null>;
+    contentRef: RefObject<HTMLDivElement | null>;
+    listRef: RefObject<HTMLUListElement | null>;
+}
+interface SelectContextValue {
+    store: SelectStore;
+    ids: {
+        root: string;
+        label: string;
+        trigger: string;
+        content: string;
+    };
+    refs: SelectRefs;
+    config: {
+        disabled: boolean;
+        required: boolean;
+        readOnly: boolean;
+        modal: boolean;
+        name: string | undefined;
+        multiple: boolean;
+        items: Record<string, string>;
+        isItemEqualToValue: SelectItemEqualFn;
+        openOnFocus: boolean;
+    };
+    isControlledOpen: boolean;
+    isControlledValue: boolean;
+    onOpenChangeComplete: ((open: boolean) => void) | undefined;
+    /** Close the listbox and restore focus to the trigger. */
+    close: () => void;
+    /** Select a value (toggle in multiple mode, set + close in single mode). */
+    selectValue: (value: string) => void;
+    /** Alias for selectValue — kept for backward compatibility. */
+    selectAndClose: (value: string) => void;
+    /** Clear the current selection. */
+    clearValue: () => void;
+    /** Scroll the list to the item at the given index. */
+    scrollToIndex: (index: number, options?: ScrollToIndexOptions) => void;
+}
+declare function useSelectContext(): SelectContextValue;
+
+export { type ScrollToIndexAlign, type ScrollToIndexOptions, index_parts as Select, type SelectContentProps, type SelectContextValue, type SelectItemRecord, type SelectRootProps, type SelectScrollDownButtonProps, type SelectScrollUpButtonProps, type SelectStoreState, scrollToIndexInState, useSelectContext };