wj-elements/dist/packages/wje-tree/tree.element.d.ts

WebJET Elements is a modern set of user interface tools harnessing the power of web components designed to simplify web application development.

import { default as WJElement } from '../wje-element/element.js';
/**
 * `Tree` is a custom web component that represents a hierarchical tree structure.
 * It extends from `WJElement`.
 * @summary This element visually represents a tree structure, supporting single or multiple selection modes and hierarchy management.
 * @documentation https://elements.webjet.sk/components/tree
 * @status stable
 * @augments {WJElement}
 * @attribute {boolean} reorder - Enables moving tree items by dragging direct start slot content.
 * @csspart native - The native container part of the tree.
 * @slot - The default slot to place `wje-tree-item` child components.
 * @tag wje-tree
 */
export default class Tree extends WJElement {
    /**
     * Returns the CSS stylesheet for the component.
     * @static
     * @returns {CSSStyleSheet} The CSS stylesheet
     */
    static get cssStyleSheet(): CSSStyleSheet;
    draggedItem: HTMLElement;
    dropTarget: any;
    dropPosition: string;
    /**
     * Sets the selection attribute for the element.
     * @param {string} value The value to set as the selection attribute.
     */
    set selection(value: string);
    /**
     * Gets the current selection mode for the element.
     * If no selection is explicitly set, it defaults to 'single'.
     * @returns {string} The current selection mode, either set by the element's attribute or the default value 'single'.
     */
    get selection(): string;
    /**
     * Enables reordering tree items by dragging an element assigned to the start slot.
     * @param {boolean} value Whether reordering is enabled.
     */
    set reorder(value: boolean);
    /**
     * Indicates whether tree items can be reordered with the start slot handle.
     * @returns {boolean}
     */
    get reorder(): boolean;
    /**
     * A method called before the drawing or rendering process of tree items.
     * It iterates through all `wje-tree-item` elements, updating their selection state
     * and managing their expand/collapse icons accordingly.
     * @returns {void} This method does not return a value.
     */
    beforeDraw(): void;
    /**
     * Draw method for the tree.
     * @returns {object} Document fragment
     */
    draw(): object;
    /**
     * Called after the draw process of the component is completed.
     * Typically used to add event listeners or perform operations
     * that are dependent on the component's drawn state.
     * @returns {void} This method does not return a value.
     */
    afterDraw(): void;
    /**
     * Syncs ARIA attributes on the host element.
     */
    syncAria(): void;
    /**
     * Handles the click event triggered by the user interaction.
     * Identifies the closest tree item element to the event target and sets it
     * as the selected item. Ensures that only one item is selected at a time, resetting
     * the selection state for all other items.
     * @param {Event} e The click event object.
     */
    handleClick: (e: Event) => void;
    /**
     * Starts dragging a tree item when the drag begins from the configured start slot handle.
     * @param {DragEvent} e The drag event.
     * @returns {void}
     */
    handleDragStart: (e: DragEvent) => void;
    /**
     * Updates the current drop target and exposes a visual drop position.
     * @param {DragEvent} e The drag event.
     * @returns {void}
     */
    handleDragOver: (e: DragEvent) => void;
    /**
     * Completes a tree item move.
     * @param {DragEvent} e The drop event.
     * @returns {void}
     */
    handleDrop: (e: DragEvent) => void;
    /**
     * Clears drag state after the browser drag operation ends.
     * @returns {void}
     */
    handleDragEnd: () => void;
    /**
     * Retrieves all items that match the selector 'wje-tree-item' within the current context.
     * @returns {Array<Element>} An array of all matching DOM elements.
     */
    getAllItems(): Array<Element>;
    /**
     * Retrieves and appends a template slot to a tree item.
     * @param {HTMLElement} item The DOM element to which the slot content will be appended.
     * @param {HTMLTemplateElement|null} template Template that may provide reusable slot content.
     * @param {string} slotName Name of the projected slot content to clone.
     * @returns {void}
     */
    appendTemplateSlot(item: HTMLElement, template: HTMLTemplateElement | null, slotName: string): void;
    /**
     * Returns the internal class used to identify cloned template slot content.
     * @param {string} slotName Name of the projected slot.
     * @returns {string}
     */
    getTemplateSlotClass(slotName: string): string;
    /**
     * Marks direct start slot content as the drag handle for reorderable trees.
     * @param {HTMLElement} item Host item that receives draggable start content.
     * @returns {void}
     */
    setupReorderHandle(item: HTMLElement): void;
    /**
     * Finds a tree item from a composed event path.
     * @param {Event} e User interaction that may originate inside shadow DOM.
     * @returns {HTMLElement|null}
     */
    getTreeItemFromEvent(e: Event): HTMLElement | null;
    /**
     * Checks whether the event started from a reorder handle.
     * @param {Event} e User interaction to inspect.
     * @returns {boolean}
     */
    isReorderHandleEvent(e: Event): boolean;
    /**
     * Checks whether a node is a tree item element.
     * @param {object} node The node to inspect.
     * @returns {boolean}
     */
    isTreeItem(node: object): boolean;
    /**
     * Returns direct tree item children for a tree or tree item parent.
     * @param {HTMLElement} parent The parent element.
     * @returns {HTMLElement[]}
     */
    getDirectTreeItems(parent: HTMLElement): HTMLElement[];
    /**
     * Gets the index of a tree item among direct tree item siblings.
     * @param {HTMLElement} item Element whose sibling position should be resolved.
     * @returns {number}
     */
    getTreeItemIndex(item: HTMLElement): number;
    /**
     * Determines whether the dragged item can be dropped on the target.
     * @param {HTMLElement} draggedItem Item currently being moved.
     * @param {HTMLElement} targetItem Candidate item under the pointer.
     * @returns {boolean}
     */
    canDrop(draggedItem: HTMLElement, targetItem: HTMLElement): boolean;
    /**
     * Resolves the drop position against the visible tree item row.
     * @param {DragEvent} e Browser drag event carrying pointer coordinates.
     * @param {HTMLElement|null} target Item used to calculate row boundaries.
     * @returns {'before'|'inside'|'after'}
     */
    getDropPosition(e: DragEvent, target: HTMLElement | null): "before" | "inside" | "after";
    /**
     * Applies the visual drop position to the current target item.
     * @param {HTMLElement} target Item currently showing insertion feedback.
     * @param {string} position Resolved insertion area for the target row.
     * @returns {void}
     */
    setDropState(target: HTMLElement, position: string): void;
    /**
     * Clears visual drop target state.
     * @returns {void}
     */
    clearDropState(): void;
    /**
     * Clears the active drag state.
     * @returns {void}
     */
    clearDragState(): void;
    /**
     * Returns the internal class used to render a drop marker.
     * @param {'before'|'inside'|'after'} position Drop marker position.
     * @returns {string}
     */
    getDropPositionClass(position: "before" | "inside" | "after"): string;
    /**
     * Moves a tree item relative to another tree item and syncs nesting metadata.
     * @param {HTMLElement} draggedItem The item being moved.
     * @param {HTMLElement} targetItem Item that receives or anchors the moved item.
     * @param {'before'|'inside'|'after'} position The target position.
     * @returns {object|null} Move detail, or null when the move is invalid.
     */
    moveItem(draggedItem: HTMLElement, targetItem: HTMLElement, position?: "before" | "inside" | "after"): object | null;
    /**
     * Returns cloned direct tree item children for an event detail.
     * @param {HTMLElement} parent Parent whose direct tree item children should be serialized.
     * @returns {HTMLElement[]}
     */
    getOrderElements(parent: HTMLElement): HTMLElement[];
    /**
     * Returns stable ids for direct tree item children when they are available.
     * @param {HTMLElement} parent Parent whose direct tree item children should be serialized.
     * @returns {Array<string|null>}
     */
    getOrderIds(parent: HTMLElement): Array<string | null>;
    /**
     * Gets an application-facing id from a tree item.
     * @param {HTMLElement|null} item Tree item to read.
     * @returns {string|null}
     */
    getItemId(item: HTMLElement | null): string | null;
    /**
     * Syncs item selection mode and nesting metadata after a DOM move.
     * @returns {void}
     */
    syncTreeItems(): void;
    /**
     * Redraws affected parent items so expand/collapse affordances match current children.
     * @param {HTMLElement[]} items Items that may need refresh.
     * @returns {void}
     */
    refreshMovedItems(items: HTMLElement[]): void;
    /**
     * Updates the state of a checkbox, syncing the state both upwards to parent elements
     * and downwards to child elements as necessary.
     * @param {object} changedItem The specific item whose checkbox state has changed.
     * @param {boolean} [isInitialSync] Indicates whether the state update is part of the initial synchronization process.
     * @returns {void} This method does not return a value.
     */
    updateCheckboxState(changedItem: object, isInitialSync?: boolean): void;
    isInitialSync: boolean;
    /**
     * Updates the state of the parent item based on the state of its child items.
     * Recursively propagates changes up to all parent items to reflect the selection
     * or indeterminate state accurately.
     * @param {object} item The current tree item whose parent state needs to be updated.
     * It is expected to have properties `selected`, `indeterminate`,
     * and a method `getChildrenItems({ includeDisabled: boolean })`.
     * @returns {void} This method does not return a value.
     */
    updateParentState(item: object): void;
    /**
     * Propagates the state changes of an item upwards through its ancestors in the hierarchy.
     * Calls the `updateParentState` method for each parent element until no parent exists.
     * @param {HTMLElement} item The current item whose state to propagate to its parent.
     * @returns {void} This method does not return a value.
     */
    propagateStateUpwards(item: HTMLElement): void;
    /**
     * Propagates the selected state of an item to its children recursively. Depending on the `isInitialSync` flag,
     * it also determines how the state should be applied to the child items and updates the parent state if needed.
     * @param {object} item The item whose state is being propagated to its child items. The item must have properties
     * such as `selected` and methods like `getChildrenItems` to retrieve its child elements.
     * @returns {void} This method does not return a value.
     */
    propagateStateDownwards(item: object): void;
}