wj-elements/dist/packages/wje-breadcrumbs/breadcrumbs.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';
/**
 * @summary This class represents a Breadcrumbs container, extending the WJElement class. It acts as a wrapper for individual breadcrumb elements and manages their behavior, such as collapsing and marking the last breadcrumb.
 * @documentation https://elements.webjet.sk/components/breadcrumbs
 * @status stable
 * @augments WJElement
 * @slot - The container for breadcrumb elements.
 * @slot breakpoint-collapse-trigger - Custom trigger used when breakpoint-collapse="menu" moves the full trail into a dropdown.
 * @csspart container - The component's container wrapper.
 * @property {Array<{id: string|number, label: string, href?: string, icon?: string, title?: string, disabled?: boolean, data?: any}>} items - Data-driven breadcrumb items.
 * @attribute {number} max-items - The maximum number of visible breadcrumbs before collapsing.
 * @attribute {number} items-before-collapse - The number of breadcrumbs to show before the collapsed indicator.
 * @attribute {number} items-after-collapse - The number of breadcrumbs to show after the collapsed indicator.
 * @attribute {string} collapsed-variant - The UI used for collapsed breadcrumbs. Use "dropdown" to render a menu, or "text", "back", "parent-title", "menu-title", and "sheet" for compact breakpoint menu layouts.
 * @attribute {string} breakpoint - The viewport breakpoint where collapsing starts.
 * @attribute {string} breakpoint-collapse - The collapse behavior used below the breakpoint. Use "menu" to put the whole trail into one menu.
 * @attribute {string} breakpoint-collapse-icon - Icon used by the default breakpoint menu trigger.
 * // @fires wje-breadcrumbs:item-click - Dispatched when a data-driven breadcrumb item is clicked.
 * @tag wje-breadcrumbs
 * @example
 * <!-- Example usage -->
 * <wje-breadcrumbs max-items="5" items-before-collapse="2" items-after-collapse="2">
 *   <wje-breadcrumb>Home</wje-breadcrumb>
 *   <wje-breadcrumb>About</wje-breadcrumb>
 *   <wje-breadcrumb>Services</wje-breadcrumb>
 *   <wje-breadcrumb>Portfolio</wje-breadcrumb>
 *   <wje-breadcrumb>Contact</wje-breadcrumb>
 * </wje-breadcrumbs>
 *
 * <!-- Output: Only the first two and last two breadcrumbs will be visible, with a collapsed indicator in the middle -->
 */
export default class Breadcrumbs extends WJElement {
    static BREAKPOINTS: {
        sm: number;
        md: number;
        lg: number;
        xl: number;
        '2xl': number;
        xxl: number;
    };
    /**
     * Get CSS stylesheet for the Breadcrumbs element.
     * @static
     * @returns {object} styles - The CSS styles
     */
    static get cssStyleSheet(): object;
    /**
     * Get observed attributes for the Breadcrumb element.
     * @static
     * @returns {Array<string>} - The observed attributes array for the Breadcrumb element.
     */
    static get observedAttributes(): Array<string>;
    /**
     * Last breadcrumb flag
     * @type {boolean}
     */
    last: boolean;
    _isCollapsedByBreakpoint: boolean;
    _items: any[];
    _itemRecords: any[];
    _hasItemsValue: boolean;
    handleManagedItemClick: (e: any) => void;
    /**
     * Sets data-driven breadcrumb items.
     * @param {Array|string|null|undefined} value Breadcrumb items or a JSON string.
     */
    set items(value: any[] | string | null | undefined);
    /**
     * Gets data-driven breadcrumb items.
     * @returns {Array}
     */
    get items(): any[];
    /**
     * Set variant attribute for the Breadcrumbs element.
     * @param value
     */
    set variant(value: string);
    /**
     * Get variant attribute for the Breadcrumbs element.
     * @returns {string}
     */
    get variant(): string;
    /**
     * Get the collapsed indicator variant.
     * @param {string} value Collapsed indicator variant.
     */
    set collapsedVariant(value: string);
    /**
     * Get the collapsed indicator variant.
     * @returns {string}
     */
    get collapsedVariant(): string;
    /**
     * Gets the collapsed indicator variant as a normalized token.
     * @returns {string}
     */
    get normalizedCollapsedVariant(): string;
    /**
     * Sets the collapse breakpoint token or value.
     * @param {string} value Breakpoint token or CSS size.
     */
    set breakpoint(value: string);
    /**
     * Gets the collapse breakpoint token or value.
     * @returns {string}
     */
    get breakpoint(): string;
    /**
     * Sets the collapse behavior used below the configured breakpoint.
     * @param {string} value Collapse behavior.
     */
    set breakpointCollapse(value: string);
    /**
     * Gets the collapse behavior used below the configured breakpoint.
     * @returns {string}
     */
    get breakpointCollapse(): string;
    /**
     * Sets the icon used by the default breakpoint menu trigger.
     * @param {string} value Icon name.
     */
    set breakpointCollapseIcon(value: string);
    /**
     * Gets the icon used by the default breakpoint menu trigger.
     * @returns {string}
     */
    get breakpointCollapseIcon(): string;
    /**
     * Get items before collapse attribute.
     * @param {string} value
     */
    set maxItems(value: string);
    /**
     * Get items before collapse attribute.
     * @returns {number}
     */
    get maxItems(): number;
    /**
     * Get items before collapse attribute.
     * @param value
     */
    set itemsBeforeCollapse(value: number);
    /**
     * Get items before collapse attribute.
     * @returns {number}
     */
    get itemsBeforeCollapse(): number;
    /**
     * Get items after collapse attribute.
     * @param value
     */
    set itemsAfterCollapse(value: number);
    /**
     * Get items after collapse attribute.
     * @returns {number}
     */
    get itemsAfterCollapse(): number;
    /**
     * Handles attribute changes that affect light-DOM breadcrumb indicators.
     * @param {string} name Updated attribute.
     * @param {string|null} oldValue Previous value.
     * @param {string|null} newValue Next value.
     */
    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
    /**
     * Syncs host navigation semantics while preserving user-provided names.
     */
    syncAria(): void;
    /**
     * Draw method for the Breadcrumbs element.
     * @returns {object} fragment - The document fragment
     */
    draw(): object;
    defaultSlot: HTMLSlotElement;
    /**
     * Updates the breadcrumb elements after they are drawn on the page.
     * It manages attributes on breadcrumb items and handles the logic for collapsing breadcrumbs
     * if the total exceeds the specified maximum items.
     * @returns {void} This method does not return a value.
     */
    afterDraw(): void;
    onSlotChange: () => void;
    handleResize: () => void;
    /**
     * Upgrades properties set before the custom element definition was loaded.
     * @param {string} property Property name.
     */
    upgradeProperty(property: string): void;
    /**
     * Normalizes incoming item data for keyed DOM diffing.
     * @param {Array|string|null|undefined} value Breadcrumb item data.
     * @returns {Array<object>}
     */
    normalizeItems(value: any[] | string | null | undefined): Array<object>;
    /**
     * Normalizes a single item while preserving the original object for events.
     * @param {object|string|number} item Source value for a breadcrumb entry.
     * @param {number} index Position of the value in the current items array.
     * @param {Set<string>} usedKeys Keys that have already been assigned during this update.
     * @returns {object}
     */
    normalizeItem(item: object | string | number, index: number, usedKeys: Set<string>): object;
    /**
     * Resolves a stable key for an item.
     * @param {object} item Normalized source object used to resolve the key.
     * @param {number} index Fallback position used when the item has no id.
     * @param {Set<string>} usedKeys Keys that have already been assigned during this update.
     * @returns {string}
     */
    getItemKey(item: object, index: number, usedKeys: Set<string>): string;
    /**
     * Incrementally synchronizes data-driven items into light DOM breadcrumbs.
     * @param {Array<object>} records Normalized records for the next breadcrumb trail.
     */
    syncItems(records: Array<object>): void;
    /**
     * Creates a managed breadcrumb element.
     * @param {object} record Normalized data used to create the breadcrumb.
     * @param {number} index Position assigned to the created breadcrumb.
     * @returns {HTMLElement}
     */
    createItemElement(record: object, index: number): HTMLElement;
    /**
     * Updates a managed breadcrumb element only where values changed.
     * @param {HTMLElement} breadcrumb Existing managed element to update.
     * @param {object} record Normalized data used for the next rendered state.
     * @param {number} index Position assigned to the managed breadcrumb.
     */
    updateItemElement(breadcrumb: HTMLElement, record: object, index: number): void;
    /**
     * Synchronizes an attribute when its value changed.
     * @param {HTMLElement} element Element receiving the synchronized attribute.
     * @param {string} name Attribute to add, update, or remove.
     * @param {string|null|undefined} value Next serialized value for the attribute.
     */
    syncItemAttribute(element: HTMLElement, name: string, value: string | null | undefined): void;
    /**
     * Synchronizes a boolean attribute.
     * @param {HTMLElement} element Element receiving the boolean attribute.
     * @param {string} name Boolean attribute to toggle.
     * @param {boolean} isEnabled Whether the attribute should be present.
     */
    syncBooleanItemAttribute(element: HTMLElement, name: string, isEnabled: boolean): void;
    /**
     * Synchronizes slotted icon and text nodes for a managed breadcrumb.
     * @param {HTMLElement} breadcrumb Breadcrumb element.
     * @param {object} record Normalized item record.
     */
    syncItemContent(breadcrumb: HTMLElement, record: object): void;
    /**
     * Returns a small signature for structural changes that need item replacement.
     * @param {object} record Normalized item record.
     * @returns {string}
     */
    getItemStructureSignature(record: object): string;
    /**
     * Dispatches the data-driven item click event.
     * @param {MouseEvent} e Original click event.
     */
    dispatchManagedItemClick(e: MouseEvent): void;
    /**
     * Finds the managed breadcrumb that originated an event.
     * @param {Event} e Event whose composed path should be inspected.
     * @returns {HTMLElement|null}
     */
    getManagedBreadcrumbFromEvent(e: Event): HTMLElement | null;
    /**
     * Reacts to viewport resize only when the breakpoint mode actually changes.
     * @returns {void}
     */
    handleBreakpointResize(): void;
    /**
     * Recalculates breadcrumb collapse state.
     * @returns {void}
     */
    updateCollapse(): void;
    /**
     * Collapses the whole breadcrumb trail into a single menu indicator.
     * @param {Array<Element>} breadcrumbs Breadcrumb items.
     */
    applyMenuCollapse(breadcrumbs: Array<Element>): void;
    /**
     * Returns whether the active breakpoint mode should move the full trail into one menu.
     * @returns {boolean}
     */
    isBreakpointMenuCollapseActive(): boolean;
    /**
     * Returns whether the active collapsed variant is one of the mobile compact layouts.
     * @returns {boolean}
     */
    usesMobileCollapsedVariant(): boolean;
    /**
     * Clears attributes/classes managed by the collapse algorithm.
     * @param {Array<Element>} breadcrumbs Breadcrumb items.
     */
    resetCollapseState(breadcrumbs?: Array<Element>): void;
    /**
     * Applies a managed boolean attribute only when its value truly changes.
     * @param {Element} element Breadcrumb item whose responsive state is being synchronized.
     * @param {string} name Managed state flag that should be synchronized on the breadcrumb item.
     * @param {boolean} isEnabled Whether the attribute should be present.
     */
    syncManagedAttribute(element: Element, name: string, isEnabled: boolean): void;
    /**
     * Redraws active collapsed indicators when parent-only rendering inputs change.
     */
    refreshCollapsedIndicators(): void;
    /**
     * Returns whether collapse rules should currently be applied.
     * @returns {boolean}
     */
    shouldApplyBreakpointCollapse(): boolean;
    /**
     * Resolves the configured breakpoint to a pixel width.
     * @returns {number|null}
     */
    getBreakpointWidth(): number | null;
    /**
     * Returns the custom trigger element configured for breakpoint menu collapse.
     * @returns {Element|null}
     */
    getBreakpointCollapseTrigger(): Element | null;
    /**
     * Retrieves all breadcrumb elements within the current instance.
     * @returns {Array<Element>} An array of breadcrumb elements (`wje-breadcrumb`) found within the instance. Returns an empty array if no breadcrumbs are found.
     */
    getBreadcrumbs(): Array<Element>;
    /**
     * Retrieves breadcrumbs managed by the items property.
     * @returns {Array<Element>}
     */
    getManagedBreadcrumbs(): Array<Element>;
    /**
     * Retrieves all breadcrumb elements that have the 'collapsed' attribute.
     * @returns {Array<Element>} An array of DOM elements representing breadcrumbs with the 'collapsed' attribute.
     */
    getBreadcrumbsCollapsed(): Array<Element>;
}