@xlabs-store/core 0.0.1

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

@@ -0,0 +1,750 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+import type { TreeSelectSize, TreeSelectStatus, TreeSelectPlacement, TreeSelectVariant, TreeSelectNode, TreeSelectChangeEventDetail, TreeSelectExpandEventDetail, TreeSelectSearchEventDetail, TreeSelectShowCheckedStrategy, TreeSelectFieldNames } from './types';
+export declare class XTreeSelect {
+    /**
+     * Host element reference.
+     */
+    el: HTMLElement;
+    /**
+     * Tree data source.
+     * @example
+     * <x-tree-select treeData={[{ key: '1', title: 'Node' }]}></x-tree-select>
+     */
+    treeData: TreeSelectNode[];
+    /**
+     * Current selected value(s).
+     * @example
+     * <x-tree-select value="1"></x-tree-select>
+     */
+    value: string | string[];
+    /**
+     * Default value.
+     * @example
+     * <x-tree-select defaultValue="1"></x-tree-select>
+     */
+    defaultValue: string | string[];
+    /**
+     * Placeholder text.
+     * @example
+     * <x-tree-select placeholder="Select"></x-tree-select>
+     */
+    placeholder: string;
+    /**
+     * Whether disabled.
+     * @example
+     * <x-tree-select disabled></x-tree-select>
+     */
+    disabled: boolean;
+    /**
+     * Whether allow multiple selection.
+     * @example
+     * <x-tree-select multiple></x-tree-select>
+     */
+    multiple: boolean;
+    /**
+     * Whether show checkbox (treeCheckable mode).
+     * @example
+     * <x-tree-select treeCheckable></x-tree-select>
+     */
+    treeCheckable: boolean;
+    /**
+     * Check node precisely (parent-child independent).
+     * @example
+     * <x-tree-select treeCheckStrictly></x-tree-select>
+     */
+    treeCheckStrictly: boolean;
+    /**
+     * Strategy for showing checked items.
+     * @example
+     * <x-tree-select showCheckedStrategy="SHOW_PARENT"></x-tree-select>
+     */
+    showCheckedStrategy: TreeSelectShowCheckedStrategy;
+    /**
+     * Whether allow clear.
+     * @example
+     * <x-tree-select allowClear></x-tree-select>
+     */
+    allowClear: boolean;
+    /**
+     * Whether show search input.
+     * @example
+     * <x-tree-select showSearch></x-tree-select>
+     */
+    showSearch: boolean;
+    /**
+     * Filter function for tree nodes.
+     * @example
+     * <x-tree-select filterTreeNode={(v, n) => n.title.startsWith(v)}></x-tree-select>
+     */
+    filterTreeNode: (inputValue: string, treeNode: TreeSelectNode) => boolean;
+    /**
+     * Filter tree nodes by input value (property name).
+     * @example
+     * <x-tree-select treeNodeFilterProp="title"></x-tree-select>
+     */
+    treeNodeFilterProp: string;
+    /**
+     * Size of the select.
+     * @example
+     * <x-tree-select size="small"></x-tree-select>
+     */
+    size: TreeSelectSize;
+    /**
+     * Validation status.
+     * @example
+     * <x-tree-select status="error"></x-tree-select>
+     */
+    status: TreeSelectStatus;
+    /**
+     * Dropdown placement.
+     * @example
+     * <x-tree-select placement="bottomRight"></x-tree-select>
+     */
+    placement: TreeSelectPlacement;
+    /**
+     * Variant style.
+     * @example
+     * <x-tree-select variant="filled"></x-tree-select>
+     */
+    variant: TreeSelectVariant;
+    /**
+     * Whether the dropdown is open.
+     * @example
+     * <x-tree-select open></x-tree-select>
+     */
+    open: boolean;
+    /**
+     * Max tag count to show in multiple mode.
+     * @example
+     * <x-tree-select multiple maxTagCount={2}></x-tree-select>
+     */
+    maxTagCount: number;
+    /**
+     * Placeholder for max tag count.
+     * @example
+     * <x-tree-select maxTagPlaceholder="+ more"></x-tree-select>
+     */
+    maxTagPlaceholder: string;
+    /**
+     * Whether show tree line.
+     * @example
+     * <x-tree-select treeLine></x-tree-select>
+     */
+    treeLine: boolean;
+    /**
+     * Default expanded keys.
+     * @example
+     * <x-tree-select defaultExpandedKeys={['1']}></x-tree-select>
+     */
+    defaultExpandedKeys: string[];
+    /**
+     * Default expand all tree nodes.
+     * @example
+     * <x-tree-select defaultExpandAll></x-tree-select>
+     */
+    defaultExpandAll: boolean;
+    /**
+     * Default expand parent nodes.
+     * @example
+     * <x-tree-select treeDefaultExpandParent={false}></x-tree-select>
+     */
+    treeDefaultExpandParent: boolean;
+    /**
+     * Expand on load.
+     * @example
+     * <x-tree-select treeExpandedKeys={['1']}></x-tree-select>
+     */
+    treeExpandedKeys: string[];
+    /**
+     * Auto focus on mount.
+     * @example
+     * <x-tree-select autofocus></x-tree-select>
+     */
+    autofocus: boolean;
+    /**
+     * Input ID.
+     * @example
+     * <x-tree-select inputId="tree"></x-tree-select>
+     */
+    inputId: string;
+    /**
+     * Name for form.
+     * @example
+     * <x-tree-select name="tree"></x-tree-select>
+     */
+    name: string;
+    /**
+     * Max height of dropdown.
+     * @example
+     * <x-tree-select listHeight={300}></x-tree-select>
+     */
+    listHeight: number;
+    /**
+     * Whether loading state.
+     * @example
+     * <x-tree-select loading></x-tree-select>
+     */
+    loading: boolean;
+    /**
+     * Text when no data.
+     * @example
+     * <x-tree-select notFoundContent="Empty"></x-tree-select>
+     */
+    notFoundContent: string;
+    /**
+     * Whether dropdown matches selector width.
+     * @example
+     * <x-tree-select popupMatchSelectWidth={false}></x-tree-select>
+     */
+    popupMatchSelectWidth: boolean;
+    /**
+     * Custom field names mapping.
+     * @example
+     * <x-tree-select fieldNames={{ title: 'label', value: 'id' }}></x-tree-select>
+     */
+    fieldNames: TreeSelectFieldNames;
+    /**
+     * Whether show arrow icon.
+     * @example
+     * <x-tree-select showArrow={false}></x-tree-select>
+     */
+    showArrow: boolean;
+    /**
+     * Whether show tree icon.
+     * @example
+     * <x-tree-select treeIcon></x-tree-select>
+     */
+    treeIcon: boolean;
+    /**
+     * Whether virtual scroll.
+     * @example
+     * <x-tree-select virtual={false}></x-tree-select>
+     */
+    virtual: boolean;
+    /**
+     * Label in value (for controlled mode).
+     * @example
+     * <x-tree-select labelInValue></x-tree-select>
+     */
+    labelInValue: boolean;
+    /**
+     * Focus state.
+     */
+    focused: boolean;
+    /**
+     * Hover state for clear icon.
+     */
+    hovering: boolean;
+    /**
+     * Current search value.
+     */
+    searchValue: string;
+    /**
+     * Expanded tree node keys.
+     */
+    expandedKeys: string[];
+    /**
+     * Selected keys for single/multiple mode.
+     */
+    selectedKeys: string[];
+    /**
+     * Checked keys for checkable mode.
+     */
+    checkedKeys: string[];
+    /**
+     * Half-checked keys for checkable mode.
+     */
+    halfCheckedKeys: string[];
+    /**
+     * Dropdown width for portal.
+     */
+    dropdownWidth: number;
+    /**
+     * Emitted when value changes.
+     * @example
+     * <x-tree-select onXChange={(ev) => console.log(ev.detail)}></x-tree-select>
+     */
+    xChange: EventEmitter<TreeSelectChangeEventDetail>;
+    /**
+     * Emitted when dropdown opens/closes.
+     * @example
+     * <x-tree-select onXOpenChange={(ev) => console.log(ev.detail)}></x-tree-select>
+     */
+    xOpenChange: EventEmitter<boolean>;
+    /**
+     * Emitted when tree node expands/collapses.
+     * @example
+     * <x-tree-select onXTreeExpand={(ev) => console.log(ev.detail)}></x-tree-select>
+     */
+    xTreeExpand: EventEmitter<TreeSelectExpandEventDetail>;
+    /**
+     * Emitted on search.
+     * @example
+     * <x-tree-select onXSearch={(ev) => console.log(ev.detail)}></x-tree-select>
+     */
+    xSearch: EventEmitter<TreeSelectSearchEventDetail>;
+    /**
+     * Emitted on focus.
+     * @example
+     * <x-tree-select onXFocus={(ev) => console.log(ev)}></x-tree-select>
+     */
+    xFocus: EventEmitter<FocusEvent>;
+    /**
+     * Emitted on blur.
+     * @example
+     * <x-tree-select onXBlur={(ev) => console.log(ev)}></x-tree-select>
+     */
+    xBlur: EventEmitter<FocusEvent>;
+    /**
+     * Emitted when dropdown visible changes.
+     * @example
+     * <x-tree-select onXDropdownVisibleChange={(ev) => console.log(ev.detail)}></x-tree-select>
+     */
+    xDropdownVisibleChange: EventEmitter<boolean>;
+    /**
+     * Input element reference.
+     */
+    private inputRef;
+    /**
+     * Wrapper element reference.
+     */
+    private wrapperRef;
+    /**
+     * Portal instance for dropdown.
+     */
+    private portalInstance;
+    /**
+     * Dropdown element reference.
+     */
+    private dropdownEl;
+    /**
+     * Tree Service Instance
+     */
+    private get treeService();
+    /**
+     * Destroy portal instance if present.
+     * @returns void
+     */
+    private destroyPortal;
+    /**
+     * Initialize state from value and expansion settings.
+     *
+     * Flow:
+     * 1. Initialize `expandedKeys` based on props (treeExpandedKeys, defaultExpandAll, defaultExpandedKeys, or parent of value).
+     * 2. Initialize `value` from `defaultValue` if `value` is undefined.
+     * 3. Sync `value` to internal state (`selectedKeys`, `checkedKeys`).
+     */
+    componentWillLoad(): void;
+    treeDataChanged(): void;
+    /**
+     * Auto focus on mount when enabled.
+     */
+    componentDidLoad(): void;
+    /**
+     * Cleanup portal on disconnect.
+     */
+    disconnectedCallback(): void;
+    /**
+     * Sync state when value changes.
+     */
+    valueChanged(): void;
+    /**
+     * Sync expanded keys when controlled prop changes.
+     * @param newValue - Expanded keys.
+     */
+    treeExpandedKeysChanged(newValue: string[]): void;
+    /**
+     * Handle open state changes and portal sync.
+     *
+     * Flow:
+     * 1. Emit `xOpenChange` and `xDropdownVisibleChange`.
+     * 2. If open, create or update portal.
+     * 3. If closed, destroy portal.
+     * @param newValue - Open state.
+     */
+    openChanged(newValue: boolean): void;
+    /**
+     * Close dropdown when clicking outside.
+     *
+     * Flow:
+     * 1. Check if click path includes component or portal.
+     * 2. If neither, close dropdown.
+     * @param ev - Mouse event.
+     */
+    handleWindowClick(ev: MouseEvent): void;
+    /**
+     * Handle keyboard open/close and tag removal.
+     *
+     * Flow:
+     * - Escape: Close dropdown.
+     * - Enter/Down/Up: Open dropdown if closed.
+     * - Tab: Close dropdown.
+     * - Backspace: Remove last tag in multiple mode if search is empty.
+     * @param ev - Keyboard event.
+     */
+    handleKeydown(ev: KeyboardEvent): void;
+    setFocus(): Promise<void>;
+    setBlur(): Promise<void>;
+    /**
+     * Resolve field name mapping.
+     * @param field - Field key.
+     * @returns Mapped field name.
+     */
+    private getFieldName;
+    /**
+     * Get node title using field mapping.
+     * @param node - Tree node.
+     * @returns Node title.
+     */
+    private getNodeTitle;
+    /**
+     * Get node value using field mapping.
+     * @param node - Tree node.
+     * @returns Node value.
+     */
+    private getNodeValue;
+    /**
+     * Get node children using field mapping.
+     * @param node - Tree node.
+     * @returns Array of children or undefined.
+     */
+    private getNodeChildren;
+    /**
+     * Determine if component is in multiple selection mode.
+     * @returns True if multiple or checkable.
+     */
+    private isMultiple;
+    /**
+     * Sync value prop into selected/checked keys state.
+     *
+     * Flow:
+     * 1. If checkable: update `checkedKeys` and calculate `halfCheckedKeys` (if not strict).
+     * 2. If multiple: update `selectedKeys` array.
+     * 3. If single: update `selectedKeys` with single value.
+     */
+    private syncValueToState;
+    /**
+     * Expand parent keys to include all descendants (for cascade mode).
+     * @param keys - Initial keys (potentially parents).
+     * @returns Array of keys including descendants.
+     */
+    private expandCheckedKeys;
+    /**
+     * Recalculate checked keys from bottom up to ensure consistency.
+     * If all children checked -> check parent.
+     * If not all children checked -> uncheck parent.
+     * @param currentChecked - Current checked keys.
+     * @returns Consistent checked keys.
+     */
+    private recalcCheckedKeys;
+    /**
+     * Get values based on showCheckedStrategy.
+     * @param checkedKeys - All checked keys.
+     * @returns Filtered keys.
+     */
+    private getCheckedStrategyValues;
+    /**
+     * Get parent keys path for given value(s).
+     *
+     * Flow:
+     * 1. Iterate over each selected value.
+     * 2. Traverse tree using TreeService to find path from root to node.
+     * @param value - Selected value(s).
+     * @returns Unique array of parent keys.
+     */
+    private getParentKeys;
+    /**
+     * Find node by key or value recursively.
+     * @param key - Node key or value.
+     * @returns Found node or null.
+     */
+    private findNode;
+    /**
+     * Get labels for currently selected keys.
+     * @returns Array of labels.
+     */
+    private getSelectedLabels;
+    /**
+     * Get all descendant keys for a node.
+     * @param node - Tree node.
+     * @returns Array of all child keys.
+     */
+    private getAllChildKeys;
+    /**
+     * Calculate half-checked keys based on current checked state.
+     *
+     * Flow:
+     * 1. Traverse tree bottom-up (implicitly via recursion).
+     * 2. If node has children, check their checked status.
+     * 3. If some children checked but not all, mark node as half-checked.
+     * @returns Array of half-checked keys.
+     */
+    private calculateHalfCheckedKeys;
+    private openDropdown;
+    /**
+     * Close dropdown and reset search.
+     */
+    private closeDropdown;
+    /**
+     * Handle tree node click.
+     *
+     * Flow:
+     * 1. If checkable, toggle check state.
+     * 2. If multiple, toggle selection.
+     * 3. If single, set selection and close dropdown.
+     * @param node - Tree node.
+     * @param e - Mouse event.
+     */
+    private handleNodeClick;
+    /**
+     * Handle node check/uncheck.
+     *
+     * Flow:
+     * 1. Determine if strict or cascade mode.
+     * 2. Update `checkedKeys` (and `halfCheckedKeys` if cascading).
+     * 3. Update `value` prop.
+     * 4. Emit `xChange` event.
+     * @param node - Tree node.
+     */
+    private handleNodeCheck;
+    /**
+     * Handle multiple selection for node.
+     * @param node - Tree node.
+     */
+    private handleMultipleSelect;
+    /**
+     * Handle single selection for node.
+     * @param node - Tree node.
+     */
+    private handleSingleSelect;
+    /**
+     * Handle node expand/collapse.
+     * @param node - Tree node.
+     * @param e - Mouse event.
+     */
+    private handleNodeExpand;
+    /**
+     * Handle search input changes.
+     *
+     * Flow:
+     * 1. Update search value state.
+     * 2. Emit `xSearch` event.
+     * 3. If searching, find and expand parent nodes of matched items.
+     * 4. If clearing search, reset expanded keys to default.
+     * @param e - Input event.
+     */
+    private handleSearch;
+    /**
+     * Collect parent keys of nodes matching search.
+     * @param searchValue - Search text.
+     * @returns Array of parent keys.
+     */
+    private getMatchedParentKeys;
+    /**
+     * Handle clear action.
+     *
+     * Flow:
+     * 1. Reset all selection and search states.
+     * 2. Emit `xChange` with empty/null value.
+     * @param e - Mouse event.
+     */
+    private handleClear;
+    /**
+     * Remove tag by key.
+     *
+     * Flow:
+     * 1. If checkable: update `checkedKeys` (and `halfCheckedKeys` if cascading).
+     * 2. Otherwise: filter `selectedKeys`.
+     * 3. Update `value` prop.
+     * 4. Emit `xChange`.
+     * @param key - Node key.
+     * @param e - Mouse event.
+     */
+    private removeTag;
+    /**
+     * Remove last selected tag.
+     */
+    private removeLastTag;
+    /**
+     * Handle selector click to open dropdown.
+     */
+    private handleSelectorClick;
+    /**
+     * Handle input focus.
+     * @param e - Focus event.
+     */
+    private handleInputFocus;
+    /**
+     * Handle input blur.
+     * @param e - Focus event.
+     */
+    private handleInputBlur;
+    /**
+     * Track hover state on wrapper enter.
+     */
+    private handleMouseEnter;
+    /**
+     * Track hover state on wrapper leave.
+     */
+    private handleMouseLeave;
+    /**
+     * Get wrapper element for portal.
+     * @returns Wrapper element or undefined.
+     */
+    private getWrapperEl;
+    /**
+     * Build dropdown content element and wire events.
+     *
+     * Flow:
+     * 1. Create `x-tree-select-dropdown-content` if not exists.
+     * 2. Attach selection, expansion, and check event listeners.
+     * 3. Filter tree data based on search value.
+     * 4. Sync current component state to dropdown element props.
+     * @returns Dropdown element.
+     */
+    private buildDropdownElement;
+    /**
+     * Create portal or update existing instance.
+     *
+     * Flow:
+     * 1. Build dropdown content.
+     * 2. Calculate popup width if required.
+     * 3. Create or update `PortalController` instance.
+     */
+    private createOrUpdatePortal;
+    /**
+     * Update portal content and placement.
+     */
+    private updatePortal;
+    /**
+     * Get selected values based on checkable mode.
+     * @returns Array of selected/checked values.
+     */
+    private getSelectedValues;
+    /**
+     * Filter tree nodes by search value recursively.
+     *
+     * Flow:
+     * 1. Traverse nodes.
+     * 2. Include node if title matches or any child matches.
+     * 3. If node matches, keep all its children.
+     * @param nodes - Tree nodes.
+     * @param searchValue - Search text.
+     * @returns Filtered tree nodes.
+     */
+    private filterTree;
+    /**
+     * Handle node selection from dropdown events.
+     * @param node - Tree node.
+     * @param _value - Node value.
+     */
+    private handleNodeSelect;
+    /**
+     * Handle expand event from dropdown.
+     * @param node - Tree node.
+     * @param expanded - Expanded state.
+     */
+    private handleNodeExpandFromEvent;
+    /**
+     * Handle check event from dropdown.
+     *
+     * Flow:
+     * 1. Determine strict or cascade mode.
+     * 2. Update `checkedKeys` and `halfCheckedKeys`.
+     * 3. Update `value` prop and emit `xChange`.
+     * @param node - Tree node.
+     * @param checked - Checked state.
+     */
+    private handleNodeCheckFromEvent;
+    /**
+     * Match node against search value.
+     * @param node - Tree node.
+     * @returns True if matches.
+     */
+    private matchSearch;
+    /**
+     * Check if node has children matching search.
+     * @param node - Tree node.
+     * @returns True if any child matches.
+     */
+    private hasMatchedChildren;
+    /**
+     * Determine whether to show node in filtered view.
+     * @param node - Tree node.
+     * @returns True if node or children match.
+     */
+    private shouldShowNode;
+    /**
+     * Render arrow icon.
+     * @returns JSX.Element
+     */
+    private renderArrowIcon;
+    /**
+     * Render clear icon.
+     * @returns JSX.Element
+     */
+    private renderClearIcon;
+    /**
+     * Render loading icon.
+     * @returns JSX.Element
+     */
+    private renderLoadingIcon;
+    /**
+     * Render switcher icon for tree nodes.
+     * @param expanded - Expanded state.
+     * @returns JSX.Element
+     */
+    private renderSwitcherIcon;
+    /**
+     * Render checkbox for tree node.
+     * @param checked - Checked state.
+     * @param halfChecked - Half checked state.
+     * @returns JSX.Element
+     */
+    private renderCheckbox;
+    /**
+     * Render remove icon for tags.
+     * @returns JSX.Element
+     */
+    private renderRemoveIcon;
+    /**
+     * Render tree node recursively.
+     *
+     * Flow:
+     * 1. Check if node should be shown.
+     * 2. Determine state (expanded, selected, checked, matched).
+     * 3. Render indentation, switcher, checkbox, and content.
+     * 4. Recursively render children if expanded.
+     * @param node - Tree node.
+     * @param level - Tree level.
+     * @returns JSX element or null.
+     */
+    private renderTreeNode;
+    /**
+     * Render title with search highlight.
+     * @param title - Node title.
+     * @returns Title with highlight span or plain string.
+     */
+    private renderHighlightedTitle;
+    /**
+     * Render tags for multiple selection mode.
+     *
+     * Flow:
+     * 1. Calculate tags to display based on `maxTagCount`.
+     * 2. Render each tag with remove icon.
+     * 3. Render rest placeholder if any.
+     * 4. Render search input.
+     * @returns JSX element.
+     */
+    private renderTags;
+    /**
+     * Render selector for single selection mode.
+     * @returns JSX element.
+     */
+    private renderSingleSelector;
+    /**
+     * Render tree select input and suffix icons.
+     * @returns JSX element.
+     */
+    render(): any;
+}