@xlabs-store/core 0.0.1

package/dist/types/components/x-select/x-select.d.ts

@@ -0,0 +1,635 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+import type { SelectOption, SelectOptionType, SelectValue, SelectMode, SelectSize, SelectStatus, SelectPlacement, SelectShowAction, SelectChangeEventDetail } from './types';
+/**
+ * Select Component - Following Ant Design Specification
+ *
+ * A select component that allows users to choose from a list of options.
+ * Supports single and multiple selection modes.
+ *
+ * @part selector - The selector container
+ * @part dropdown - The dropdown container
+ * @part arrow - The arrow icon
+ * @part clear - The clear icon
+ */
+export declare class XSelect {
+    /**
+     * Host element reference.
+     */
+    el: HTMLElement;
+    /**
+     * Whether the select is disabled.
+     * @example
+     * <x-select disabled></x-select>
+     */
+    disabled: boolean;
+    /**
+     * The mode of select: 'multiple' | 'tags' | undefined (single).
+     * @example
+     * <x-select mode="multiple"></x-select>
+     */
+    mode?: SelectMode;
+    /**
+     * Whether to show the clear button.
+     * @example
+     * <x-select allowClear></x-select>
+     */
+    allowClear: boolean;
+    /**
+     * Whether to show search input.
+     * @example
+     * <x-select showSearch></x-select>
+     */
+    showSearch: boolean;
+    /**
+     * Placeholder text.
+     * @example
+     * <x-select placeholder="Choose one"></x-select>
+     */
+    placeholder: string;
+    /**
+     * Size of select: 'large' | 'middle' | 'small'.
+     * @example
+     * <x-select size="small"></x-select>
+     */
+    size: SelectSize;
+    /**
+     * Current selected value.
+     * @example
+     * <x-select value="a"></x-select>
+     */
+    value?: SelectValue;
+    /**
+     * Default selected value.
+     * @example
+     * <x-select defaultValue="a"></x-select>
+     */
+    defaultValue?: SelectValue;
+    /**
+     * Whether dropdown is open (controlled).
+     * @example
+     * <x-select open></x-select>
+     */
+    open: boolean;
+    /**
+     * Whether to show loading spinner.
+     * @example
+     * <x-select loading></x-select>
+     */
+    loading: boolean;
+    /**
+     * Maximum number of tags to display in multiple mode.
+     * @example
+     * <x-select mode="multiple" maxTagCount={2}></x-select>
+     */
+    maxTagCount?: number | 'responsive';
+    /**
+     * Placeholder for hidden tags.
+     * @example
+     * <x-select mode="multiple" maxTagPlaceholder="+ more"></x-select>
+     */
+    maxTagPlaceholder?: string;
+    /**
+     * Maximum length of tag text to display.
+     * @example
+     * <x-select mode="multiple" maxTagTextLength={8}></x-select>
+     */
+    maxTagTextLength?: number;
+    /**
+     * Whether to show border.
+     * @example
+     * <x-select bordered={false}></x-select>
+     */
+    bordered: boolean;
+    /**
+     * Validation status: 'error' | 'warning'.
+     * @example
+     * <x-select status="error"></x-select>
+     */
+    status?: SelectStatus;
+    /**
+     * Dropdown placement.
+     * @example
+     * <x-select placement="bottomRight"></x-select>
+     */
+    placement: SelectPlacement;
+    /**
+     * Whether to include label in value object.
+     * @example
+     * <x-select labelInValue></x-select>
+     */
+    labelInValue: boolean;
+    /**
+     * Custom filter function for search.
+     * @example
+     * <x-select filterOption={(input, opt) => opt.label.startsWith(input)}></x-select>
+     */
+    filterOption: boolean | ((inputValue: string, option: SelectOption) => boolean);
+    /**
+     * Sort function for filtered options.
+     * @example
+     * <x-select filterSort={(a, b) => a.label.localeCompare(b.label)}></x-select>
+     */
+    filterSort?: (optionA: SelectOption, optionB: SelectOption) => number;
+    /**
+     * Text to show when no options match search.
+     * @example
+     * <x-select notFoundContent="Empty"></x-select>
+     */
+    notFoundContent: string;
+    /**
+     * Whether auto focus on mount.
+     * @example
+     * <x-select autofocus></x-select>
+     */
+    autofocus: boolean;
+    /**
+     * ID for the input element.
+     * @example
+     * <x-select inputId="country"></x-select>
+     */
+    inputId?: string;
+    /**
+     * Name attribute for form.
+     * @example
+     * <x-select name="country"></x-select>
+     */
+    name?: string;
+    /**
+     * Trigger actions to open dropdown.
+     * @example
+     * <x-select showAction={['click','focus']}></x-select>
+     */
+    showAction: SelectShowAction[];
+    /**
+     * Custom dropdown class.
+     * @example
+     * <x-select dropdownClassName="my-select-dropdown"></x-select>
+     */
+    dropdownClassName?: string;
+    /**
+     * Custom dropdown style.
+     * @example
+     * <x-select dropdownStyle={{ minWidth: '240px' }}></x-select>
+     */
+    dropdownStyle?: {
+        [key: string]: string;
+    };
+    /**
+     * Whether dropdown matches selector width.
+     * @example
+     * <x-select dropdownMatchSelectWidth={false}></x-select>
+     */
+    dropdownMatchSelectWidth: boolean | number;
+    /**
+     * Height of dropdown list.
+     * @example
+     * <x-select listHeight={300}></x-select>
+     */
+    listHeight: number;
+    /**
+     * Number of items to render initially and per scroll.
+     * @example
+     * <x-select pageSize={50}></x-select>
+     */
+    pageSize: number;
+    /**
+     * Options data, use this instead of x-select-option children. Supports SelectOption and OptionGroup.
+     * @example
+     * <x-select options={[{ value: 'a', label: 'A' }]}></x-select>
+     */
+    options?: SelectOptionType[];
+    /**
+     * Emitted when value changes.
+     * @example
+     * <x-select onXChange={(ev) => console.log(ev.detail)}></x-select>
+     */
+    xChange: EventEmitter<SelectChangeEventDetail>;
+    /**
+     * Emitted when search value changes.
+     * @example
+     * <x-select onXSearch={(ev) => console.log(ev.detail)}></x-select>
+     */
+    xSearch: EventEmitter<string>;
+    /**
+     * Emitted when dropdown opens/closes.
+     * @example
+     * <x-select onXDropdownVisibleChange={(ev) => console.log(ev.detail)}></x-select>
+     */
+    xDropdownVisibleChange: EventEmitter<boolean>;
+    /**
+     * Emitted on blur.
+     * @example
+     * <x-select onXBlur={(ev) => console.log(ev)}></x-select>
+     */
+    xBlur: EventEmitter<FocusEvent>;
+    /**
+     * Emitted on focus.
+     * @example
+     * <x-select onXFocus={(ev) => console.log(ev)}></x-select>
+     */
+    xFocus: EventEmitter<FocusEvent>;
+    /**
+     * Emitted when clear button is clicked.
+     * @example
+     * <x-select onXClear={() => {}}></x-select>
+     */
+    xClear: EventEmitter<void>;
+    /**
+     * Emitted when a tag is removed.
+     * @example
+     * <x-select onXDeselect={(ev) => console.log(ev.detail)}></x-select>
+     */
+    xDeselect: EventEmitter<SelectOption>;
+    /**
+     * Emitted when an option is selected.
+     * @example
+     * <x-select onXSelect={(ev) => console.log(ev.detail)}></x-select>
+     */
+    xSelect: EventEmitter<SelectOption>;
+    /**
+     * Current search input value.
+     */
+    searchValue: string;
+    /**
+     * Selected options state.
+     */
+    selectedOptions: SelectOption[];
+    /**
+     * Focus state.
+     */
+    focused: boolean;
+    /**
+     * Active option index for keyboard navigation.
+     */
+    activeIndex: number;
+    /**
+     * Flattened internal options.
+     */
+    internalOptions: SelectOption[];
+    /**
+     * Visible option count for incremental rendering.
+     */
+    visibleCount: number;
+    /**
+     * Input element reference.
+     */
+    private inputRef?;
+    /**
+     * Dropdown content wrapper reference.
+     */
+    private dropdownRef?;
+    /**
+     * Mutation observer for slotted options.
+     */
+    private mutationObserver?;
+    /**
+     * Portal instance for dropdown.
+     */
+    private portalInstance;
+    /**
+     * Dropdown element reference.
+     */
+    private dropdownEl;
+    /**
+     * Whether current mode is multiple or tags.
+     * @returns boolean
+     */
+    private get isMultiple();
+    /**
+     * Whether any value is selected.
+     * @returns boolean
+     */
+    private get hasValue();
+    /**
+     * Options filtered by search input and filterOption.
+     * @returns SelectOption[]
+     */
+    private get filteredOptions();
+    /**
+     * Start observing slot changes for options.
+     * @returns void
+     */
+    connectedCallback(): void;
+    /**
+     * Initialize value and options before render.
+     * @returns void
+     */
+    componentWillLoad(): void;
+    /**
+     * Auto focus on mount when enabled.
+     * @returns void
+     */
+    componentDidLoad(): void;
+    /**
+     * Update portal after render.
+     * @returns void
+     */
+    componentDidRender(): void;
+    /**
+     * Cleanup observer and portal on disconnect.
+     * @returns void
+     */
+    disconnectedCallback(): void;
+    /**
+     * Sync selected options when value changes.
+     * @returns void
+     */
+    onValueChange(): void;
+    /**
+     * Handle open state changes.
+     * @param isOpen - Open state.
+     * @returns void
+     */
+    onOpenChange(isOpen: boolean): void;
+    /**
+     * Sync options when options prop changes.
+     * @returns void
+     */
+    onOptionsChange(): void;
+    /**
+     * Close dropdown when clicking outside.
+     * @param ev - Mouse event.
+     * @returns void
+     */
+    handleWindowClick(ev: MouseEvent): void;
+    /**
+     * Handle keyboard navigation and selection.
+     * @param ev - Keyboard event.
+     * @returns void
+     */
+    handleKeydown(ev: KeyboardEvent): void;
+    /**
+     * Focus the select input.
+     * @returns Promise<void>
+     * @example
+     * await el.setFocus()
+     */
+    setFocus(): Promise<void>;
+    /**
+     * Blur the select input.
+     * @returns Promise<void>
+     * @example
+     * await el.setBlur()
+     */
+    setBlur(): Promise<void>;
+    /**
+     * Flattens the options array, extracting options from OptionGroups.
+     * This creates a single list of options for easier navigation and filtering.
+     *
+     * @param options - The mixed list of options and option groups.
+     * @returns SelectOption[] - A flat list of all selectable options.
+     */
+    private flattenOptions;
+    /**
+     * Synchronizes internal options state from either the `options` prop or slotted `x-select-option` elements.
+     * Priority is given to the `options` prop.
+     *
+     * Flow:
+     * 1. If `options` prop exists, flatten and use it.
+     * 2. If not, query for `x-select-option` elements in the slot.
+     * 3. Map elements to `SelectOption` objects, extracting value, label, and disabled state.
+     */
+    private syncOptionsFromSlot;
+    /**
+     * Synchronizes `selectedOptions` state based on the current `value` prop.
+     * Handles both single and multiple selection modes, as well as `labelInValue` format.
+     *
+     * Flow:
+     * 1. If `value` is undefined/null, clear selection.
+     * 2. If `labelInValue` is true, map the object(s) directly to selected options.
+     * 3. If `labelInValue` is false, find the corresponding options from `internalOptions` using the value.
+     *    - If option found, use its label.
+     *    - If not found, fallback to string representation of value.
+     */
+    private syncSelectedFromValue;
+    /**
+     * Determines the initial active index for the dropdown.
+     *
+     * Flow:
+     * 1. If there is a selected option, find its index in the filtered options.
+     * 2. If no selection, find the first non-disabled option.
+     *
+     * @returns number - The index of the option to highlight.
+     */
+    private getInitialActiveIndex;
+    /**
+     * Opens the dropdown menu.
+     *
+     * Flow:
+     * 1. Checks if disabled or already open.
+     * 2. Sets `open` state to true.
+     * 3. Calculates initial active index.
+     * 4. Focuses the input element.
+     */
+    private openDropdown;
+    /**
+     * Closes the dropdown menu.
+     * Resets search value and active index.
+     */
+    private closeDropdown;
+    /**
+     * Toggles the dropdown open/closed state.
+     */
+    private toggleDropdown;
+    /**
+     * Handles the selection of an option.
+     *
+     * Flow:
+     * 1. Checks if option is disabled.
+     * 2. If multiple mode:
+     *    - Checks if already selected.
+     *    - If yes, deselects it.
+     *    - If no, adds to selection and emits change.
+     *    - Clears search but keeps dropdown open and input focused.
+     * 3. If single mode:
+     *    - Sets selection to just this option.
+     *    - Emits change.
+     *    - Closes dropdown.
+     *
+     * @param option - The option being selected.
+     */
+    private selectOption;
+    /**
+     * Removes an option from the selection.
+     *
+     * Flow:
+     * 1. Filters out the option from `selectedOptions`.
+     * 2. Emits change event.
+     * 3. Emits `xDeselect` event.
+     *
+     * @param option - The option to remove.
+     */
+    private deselectOption;
+    /**
+     * Emits the `xChange` event with the current value.
+     * Normalizes the value format based on `labelInValue` and mode (single/multiple).
+     */
+    private emitChange;
+    /**
+     * Handles ArrowDown key press.
+     * Moves active focus to the next non-disabled option.
+     * Opens dropdown if closed.
+     *
+     * @param options - The list of currently visible options.
+     */
+    private handleArrowDown;
+    /**
+     * Handles ArrowUp key press.
+     * Moves active focus to the previous non-disabled option.
+     * Opens dropdown if closed.
+     *
+     * @param options - The list of currently visible options.
+     */
+    private handleArrowUp;
+    /**
+     * Handles Enter key press.
+     * Selects the currently active option if open.
+     * Opens dropdown if closed.
+     *
+     * @param options - The list of currently visible options.
+     */
+    private handleEnter;
+    /**
+     * Handles Backspace key press.
+     * Removes the last selected tag if in multiple mode and search input is empty.
+     */
+    private handleBackspace;
+    /**
+     * Scrolls the dropdown to ensure the active option is visible.
+     */
+    private scrollToActiveOption;
+    /**
+     * Handles click on the main selector element.
+     * Toggles dropdown if trigger includes 'click'.
+     */
+    private handleSelectorClick;
+    /**
+     * Handles focus event on the input.
+     * Opens dropdown if trigger includes 'focus'.
+     */
+    private handleInputFocus;
+    /**
+     * Handles blur event on the input.
+     * Delays blur processing to allow for clicks on dropdown items.
+     */
+    private handleInputBlur;
+    /**
+     * Handles input changes for search functionality.
+     * Updates search value, resets active index to 0, and opens dropdown.
+     */
+    private handleSearchInput;
+    /**
+     * Handles click on the clear icon.
+     * Clears selection and search value.
+     */
+    private handleClear;
+    /**
+     * Handles click on a tag's remove icon (multiple mode).
+     * Deselects the specific option associated with the tag.
+     */
+    private handleTagRemove;
+    /**
+     * Handles click on an option in the dropdown.
+     * Selects the clicked option.
+     */
+    private handleOptionClick;
+    /**
+     * Handles scroll event on the dropdown content.
+     * Implements infinite/lazy loading by checking if scroll is near bottom.
+     * Increases `visibleCount` to render more options.
+     */
+    private handleDropdownScroll;
+    /**
+     * Builds the dropdown DOM structure for the portal.
+     *
+     * Flow:
+     * 1. Creates or reuses `x-select-dropdown-content` element.
+     * 2. Calculates width (match select or fixed).
+     * 3. Sets classes and styles.
+     * 4. Renders options (handling groups if present) or "Not Found" state.
+     * 5. Attaches scroll listener for lazy loading.
+     *
+     * @returns HTMLElement - The constructed dropdown element.
+     */
+    private buildDropdownElement;
+    /**
+     * Creates a single option DOM element.
+     *
+     * Flow:
+     * 1. Determines state (selected, active, disabled).
+     * 2. Sets ARIA attributes.
+     * 3. Renders label content.
+     * 4. If selected, renders a checkmark icon.
+     * 5. Attaches click listener.
+     *
+     * @param option - The option data.
+     * @param index - The index of the option.
+     * @returns HTMLElement - The option element.
+     */
+    private createOptionElement;
+    /**
+     * Renders options respecting OptionGroup structure.
+     * Iterates through groups and options, creating headers and items.
+     *
+     * @param container - The container to append elements to.
+     * @param filteredOptions - The flat list of filtered options to verify visibility.
+     */
+    private renderOptionsWithGroups;
+    /**
+     * Retrieves the wrapper element from the shadow DOM.
+     * @returns HTMLElement | undefined
+     */
+    private getWrapperEl;
+    /**
+     * Creates or updates the portal instance for the dropdown.
+     * Manages position, content, and open state.
+     */
+    private updatePortal;
+    /**
+     * Destroys the portal instance and clears the dropdown element reference.
+     */
+    private destroyPortal;
+    /**
+     * Renders the arrow icon or loading spinner.
+     * @returns JSX.Element
+     */
+    private renderArrowIcon;
+    /**
+     * Renders the clear icon if allowed and value exists.
+     * @returns JSX.Element | null
+     */
+    private renderClearIcon;
+    /**
+     * Renders a selected tag item (for multiple/tags mode).
+     *
+     * @param option - The option to render as a tag.
+     * @returns JSX.Element
+     */
+    private renderTag;
+    /**
+     * Renders the selector content for multiple/tags mode.
+     * Includes tags, hidden tag counter, search input, and placeholder.
+     *
+     * @returns JSX.Element
+     */
+    private renderMultipleSelector;
+    /**
+     * Renders the selector content for single selection mode.
+     * Includes selected label (or placeholder) and search input.
+     *
+     * @returns JSX.Element[]
+     */
+    private renderSingleSelector;
+    /**
+     * Main render method for the Select component.
+     *
+     * Flow:
+     * 1. Calculates host classes based on props (size, mode, status, etc.).
+     * 2. Renders the main wrapper.
+     * 3. Renders the selector (single or multiple) inside the wrapper.
+     * 4. Renders suffix icons (clear, arrow/loading).
+     *
+     * @returns JSX.Element
+     */
+    render(): any;
+}

package/dist/types/components/x-select-option/x-select-option.d.ts

@@ -0,0 +1,51 @@
+export declare class XSelectOption {
+    /**
+     * Host element reference.
+     */
+    el: HTMLElement;
+    /**
+     * Whether the option is disabled.
+     * @example
+     * <x-select-option disabled></x-select-option>
+     */
+    disabled: boolean;
+    /**
+     * The value of the option.
+     * @example
+     * <x-select-option value="us"></x-select-option>
+     */
+    value: string | number;
+    /**
+     * The label of the option (used for display in the select box when selected)
+     * If not provided, will try to use the text content.
+     * @example
+     * <x-select-option label="United States"></x-select-option>
+     */
+    label: string;
+    /**
+     * Title attribute.
+     * @example
+     * <x-select-option optionTitle="Tooltip"></x-select-option>
+     */
+    optionTitle: string;
+    /**
+     * Internal: whether this option is selected.
+     */
+    selected: boolean;
+    /**
+     * Internal: whether this option is active (hovered/focused via keyboard).
+     */
+    active: boolean;
+    /**
+     * Renders the Select Option component.
+     *
+     * Flow:
+     * 1. Applies classes based on state (selected, active, disabled).
+     * 2. Sets ARIA roles for accessibility.
+     * 3. Renders the option content (projected via slot).
+     * 4. Renders a checkmark icon if the option is selected.
+     *
+     * @returns JSX.Element - The host element representing an option.
+     */
+    render(): any;
+}