@tylertech/forge 3.12.1 → 3.13.0

package/esm/tree/tree/tree-selection-controller.js

@@ -0,0 +1,375 @@
+/**
+ * @license
+ * Copyright Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { getChildItems, getFirstChildItem, getNextItem, getParentItem, getPreviousItem, getTreeItemFromEvent, indeterminate, isIndeterminate } from '../tree-utils';
+export class TreeSelectionController {
+    /**
+     * An array containing the values of all selected tree items.
+     */
+    get value() {
+        return this.items.filter(item => !item.indeterminate).map(item => item.value);
+    }
+    set value(value) {
+        this.items = [];
+        const allItems = getChildItems(this.host, true);
+        // If multiple selections are not allowed, select the first item with a matching value
+        if (this.host.mode !== 'multiple') {
+            const singleItem = allItems.find(item => item.value === value[0]);
+            if (singleItem) {
+                this._selectItem(singleItem, true);
+                this.items.push(singleItem);
+            }
+            this._clearIndeterminate(allItems);
+            return;
+        }
+        // Keep track of changes for more efficient updates to ancestor items
+        const changedItems = [];
+        // Select the items with matching values
+        allItems.forEach(item => {
+            const willSelect = value.includes(item.value);
+            if (willSelect === item.selected) {
+                return;
+            }
+            this._selectItem(item, willSelect);
+            if (item.selected) {
+                this.items.push(item);
+            }
+            changedItems.push(item);
+        });
+        // Update all selected item descendants
+        this.items.forEach(item => this._updateDescendentSelections(item));
+        // Update all changed item ancestors
+        changedItems.forEach(item => this._updateAncestorSelections(item));
+    }
+    constructor(host) {
+        /**
+         * An array containing all selected tree items.
+         */
+        this.items = [];
+        // A set of items that are currently being selected or deselected to distinguish between
+        // user-initiated and programmatic toggles and prevent user events from being handled twice
+        this._itemsBeingToggled = new WeakSet();
+        this._updateListener = (evt) => this._handleUpdateEvent(evt);
+        this.host = host;
+        host.addController(this);
+    }
+    hostConnected() {
+        this.host.addEventListener('forge-tree-item-update', this._updateListener);
+    }
+    hostDisconnected() {
+        this.host.removeEventListener('forge-tree-item-update', this._updateListener);
+    }
+    /**
+     * Deselects items that are not allowed for a given selection mode
+     */
+    cleanup() {
+        if (!this.items.length) {
+            return;
+        }
+        let changedItems = [];
+        switch (this.host.mode) {
+            case 'single': {
+                // The last selected item is the only one that should remain
+                if (this.items.length === 1) {
+                    return;
+                }
+                const singleItem = this.items.splice(-1, 1);
+                changedItems = [...this.items];
+                this.items.forEach(item => this._selectItem(item, false));
+                this.items = singleItem;
+                break;
+            }
+            case 'leaf': {
+                // The last selected leaf item is the only one that should remain
+                const index = this.items.reverse().findIndex(item => item.leaf); // TODO: replace with findLastIndex()
+                const leafItem = index > -1 ? this.items.splice(index, 1) : null;
+                changedItems = [...this.items];
+                this.items.forEach(item => this._selectItem(item, false));
+                if (leafItem) {
+                    this.items = leafItem;
+                }
+                break;
+            }
+            case 'multiple':
+                // No items should be deselected but descendent items should be updated
+                changedItems = this.items;
+                changedItems.forEach(item => this._updateDescendentSelections(item));
+                break;
+            case 'off':
+                // All items should be deselected
+                changedItems = [...this.items];
+                this.items.forEach(item => this._selectItem(item, false));
+                this.items = [];
+                break;
+        }
+        // Update all changed item ancestors
+        changedItems.forEach(item => this._updateAncestorSelections(item));
+    }
+    /**
+     * Selects or deselects a tree item.
+     * @param item The tree item to toggle.
+     * @param force If true, the item will be selected. If false, the item will be deselected.
+     */
+    toggle(item, force) {
+        if (item.disabled) {
+            return;
+        }
+        // Save a snapshot of the current state in case the event is canceled
+        let snapshot = [];
+        this._addToSnapshot(item, snapshot);
+        const selected = force ?? !item.selected;
+        this._selectItem(item, selected);
+        // Save the current selected items in case the event is canceled
+        const oldSelectedItems = this.items.slice();
+        // Update the selected items array and deselect items if necessary
+        snapshot = this._updateSelectionsFromItem(item, snapshot);
+        // Dispatch a select event from the item
+        const event = new CustomEvent('forge-tree-item-select', { bubbles: true, composed: true, detail: item.value });
+        item.dispatchEvent(event);
+        // Revert if the event was canceled
+        if (event.defaultPrevented) {
+            this._restoreSnapshot(snapshot);
+            this.items = oldSelectedItems;
+        }
+    }
+    /**
+     * Selects all tree items between the last selected item and the given item.
+     * @param item The end item to extend the selection to.
+     */
+    extend(item) {
+        if (item.disabled) {
+            return;
+        }
+        if (this.host.mode !== 'multiple') {
+            return;
+        }
+        const lastSelectedItem = this.items[this.items.length - 1];
+        if (!lastSelectedItem) {
+            return;
+        }
+        const positionComparison = item.compareDocumentPosition(lastSelectedItem);
+        // If the items are the same, do nothing
+        if (positionComparison === 0) {
+            return;
+        }
+        // eslint-disable-next-line no-bitwise
+        const extendForward = positionComparison & Node.DOCUMENT_POSITION_FOLLOWING;
+        const iteratorFn = extendForward ? getNextItem : getPreviousItem;
+        // Select all items between the item and the last selected item
+        let nextItem = iteratorFn(item);
+        while (nextItem) {
+            // Exit the loop after reaching the last selected item
+            if (nextItem === lastSelectedItem) {
+                break;
+            }
+            // Don't select open non-leaf items to avoid selecting entire branches twice
+            if (nextItem.leaf || !nextItem.open) {
+                this.toggle(nextItem, true);
+            }
+            nextItem = iteratorFn(nextItem);
+        }
+    }
+    /**
+     * Selects all tree items.
+     */
+    selectAll() {
+        this.items = [];
+        const allItems = getChildItems(this.host, true);
+        allItems.forEach(child => {
+            this._selectItem(child, true);
+            this.items.push(child);
+        });
+        allItems.reverse().forEach(child => {
+            this._updateAncestorSelections(child);
+        });
+        this.host.dispatchEvent(new CustomEvent('forge-tree-select-all', { bubbles: true, composed: true }));
+    }
+    /**
+     * Updates other items when an item is updated outside of the tree's interaction handlers.
+     * @param evt The update event emitted from a tree item.
+     */
+    _handleUpdateEvent(evt) {
+        const item = getTreeItemFromEvent(evt);
+        if (!item) {
+            return;
+        }
+        switch (evt.detail.reason) {
+            case 'deselected':
+            case 'selected':
+                if (!this._itemsBeingToggled.has(item)) {
+                    this._updateSelectionsFromItem(item);
+                }
+                this._itemsBeingToggled.delete(item);
+                break;
+            case 'added':
+            case 'removed':
+                this._updateAncestorSelections(item);
+                break;
+        }
+    }
+    /**
+     * Selects or deselects the given tree item and updates the list of selected items to reflect
+     * the change.
+     * @param item The item to select or deselect.
+     * @param changes The original state of all changed tree items.
+     */
+    _updateSelectionsFromItem(item, changes = []) {
+        // Remove a deselected item from the array
+        if (!item.selected) {
+            const index = this.items.indexOf(item);
+            if (index !== -1) {
+                this.items.splice(index, 1);
+            }
+            if (this.host.mode === 'multiple') {
+                // Update descendants and ancestors
+                changes = this._updateDescendentSelections(item, changes);
+                changes = this._updateAncestorSelections(item, changes);
+            }
+        }
+        else if (this.host.mode !== 'multiple') {
+            // Deselect all other items if an item was selected and the mode is not multiple
+            this.items.forEach(selectedItem => {
+                if (selectedItem !== item) {
+                    this._addToSnapshot(selectedItem, changes);
+                    this._selectItem(selectedItem, false);
+                }
+            });
+            this.items = [item];
+            return changes;
+        }
+        else if (item.selected) {
+            // If the item was selected in multiple mode just add the item to the array
+            this.items.push(item);
+        }
+        // Update descendants and ancestors
+        changes = this._updateDescendentSelections(item, changes);
+        changes = this._updateAncestorSelections(item, changes);
+        return changes;
+    }
+    /**
+     * Sets the selected state of all children of the given item.
+     * @param item The item that was selected or deselected.
+     * @param changes The original state of all changed tree items.
+     * @returns The updated snapshot of all changed tree items.
+     */
+    _updateDescendentSelections(item, changes = []) {
+        // Exit if the item has no children
+        if (item.leaf) {
+            return changes;
+        }
+        // Recursively get all children and set their selected states
+        const children = getChildItems(item, true);
+        children.forEach(child => {
+            this._addToSnapshot(child, changes);
+            if (child.selected !== item.selected) {
+                this._selectItem(child, item.selected);
+            }
+            const index = this.items.indexOf(child);
+            if (item.selected && index === -1) {
+                this.items.push(child);
+            }
+            else if (!item.selected && index !== -1) {
+                this.items.splice(index, 1);
+            }
+        });
+        // Find all items with children and set their indeterminate states
+        const branches = children.filter(child => !child.leaf);
+        branches.reverse().forEach(branch => {
+            this._addToSnapshot(branch, changes, { indeterminate: true });
+            branch[indeterminate] = isIndeterminate(branch);
+        });
+        this._addToSnapshot(item, changes, { indeterminate: true });
+        item[indeterminate] = isIndeterminate(item);
+        // Return the snapshot of the affected items
+        return changes;
+    }
+    /**
+     * Sets ancestor items of the given item to selected, deselected, or indeterminate based on the
+     * state of the item.
+     * @param item The item that was selected or deselected.
+     * @param changes The original state of all changed tree items.
+     * @return The updated snapshot of all changed tree items.
+     */
+    _updateAncestorSelections(item, changes = []) {
+        let parentItem = getParentItem(item);
+        while (parentItem) {
+            // Save a snapshot of the parent item's current state
+            this._addToSnapshot(parentItem, changes);
+            // Set the parent item's indeterminate state
+            parentItem[indeterminate] = isIndeterminate(parentItem);
+            // If the parent item is not indetermine, set the selected state from the first child
+            if (!parentItem.indeterminate) {
+                const firstChild = getFirstChildItem(parentItem);
+                const willSelect = firstChild?.selected ?? false;
+                if (parentItem.selected !== willSelect) {
+                    this._selectItem(parentItem, willSelect);
+                }
+                // Add or remove the parent item from the selected items array
+                const index = this.items.indexOf(parentItem);
+                if (parentItem.selected && index === -1) {
+                    this.items.push(parentItem);
+                }
+                else if (!parentItem.selected && index !== -1) {
+                    this.items.splice(index, 1);
+                }
+            }
+            // Go up the tree one level and repeat
+            parentItem = getParentItem(parentItem);
+        }
+        return changes;
+    }
+    /**
+     * Adds a tree item to a snapshot of all changed tree items.
+     * @param item The tree item.
+     * @param snapshot The snapshot of all changed tree items.
+     * @param options Properties of the tree item to change if it already exists in the snapshot.
+     */
+    _addToSnapshot(item, snapshot, options) {
+        const exisitingState = snapshot.find(state => state.el === item);
+        if (exisitingState) {
+            options = options ?? { indeterminate: true, open: true, selected: true };
+            exisitingState.indeterminate = options.indeterminate ? item.indeterminate : exisitingState.indeterminate;
+            exisitingState.open = options.open ? item.open : exisitingState.open;
+            exisitingState.selected = options.selected ? item.selected : exisitingState.selected;
+            return;
+        }
+        snapshot.push({
+            el: item,
+            indeterminate: item.indeterminate,
+            open: item.open,
+            selected: item.selected
+        });
+    }
+    /**
+     * Restores the state of all changed tree items from a snapshot.
+     * @param snapshot An array containing the original state of all changed tree items.
+     */
+    _restoreSnapshot(snapshot) {
+        snapshot.forEach(state => {
+            state.el.open = state.open;
+            state.el[indeterminate] = state.indeterminate;
+            this._selectItem(state.el, state.selected);
+        });
+    }
+    /**
+     * Clears the indeterminate state of all tree items.
+     * @param items An optional array of items to clear the indeterminate state of.
+     */
+    _clearIndeterminate(items) {
+        (items ?? getChildItems(this.host)).forEach(item => {
+            item[indeterminate] = false;
+        });
+    }
+    /**
+     * Sets a tree item's selected state and adds it to the set of items being toggled to prevent the
+     * event from being handled twice.
+     * @param item The item to select or deselect.
+     * @param force If true, the item will be selected. If false, the item will be deselected.
+     */
+    _selectItem(item, force) {
+        this._itemsBeingToggled.add(item);
+        item.selected = force;
+    }
+}

package/esm/tree/tree/tree.d.ts

@@ -0,0 +1,141 @@
+/**
+ * @license
+ * Copyright Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { LitElement, PropertyValues, TemplateResult } from 'lit';
+export type TreeMode = 'single' | 'multiple' | 'leaf' | 'off';
+export interface ITreeContext {
+    collapseIcon?: HTMLElement;
+    disabled: boolean;
+    expandIcon?: HTMLElement;
+    indentLines: boolean;
+    mode: TreeMode;
+}
+export declare const TREE_CONTEXT: {
+    __context__: ITreeContext;
+};
+/**
+ * @tag forge-tree
+ *
+ * @summary Trees are interactive lists that allow users to navigate through hierarchical data.
+ *
+ * @dependency forge-tree-item
+ *
+ * @event {CustomEvent<void>} forge-tree-select-all - Dispatched when the user selects all items.
+ *
+ * @csspart root - The root tree element.
+ *
+ * @slot - The default slot for tree items.
+ * @slot expand-icon - A custom expand icon to show when an item is closed.
+ * @slot collapse-icon - A custom collapse icon to show when an item is open.
+ */
+export declare class TreeComponent extends LitElement {
+    static styles: import("lit").CSSResult;
+    /**
+     * Whether opening an item closes all other items.
+     * @default false
+     * @attribute
+     */
+    accordion: boolean;
+    /**
+     * Toggles the rendering of indent lines showing hierarchy.
+     * @default false
+     * @attribute
+     */
+    indentLines: boolean;
+    /**
+     * How selecting tree items is handled.
+     * @default 'single'
+     * @attribute
+     */
+    mode: TreeMode;
+    /**
+     * Whether focusing an item also selects it. This takes no effect when in multiple mode.
+     * @default false
+     * @attribute
+     */
+    selectionFollowsFocus: boolean;
+    /**
+     * Whether selecting items is disabled.
+     * @default false
+     * @attribute
+     */
+    disabled: boolean;
+    /**
+     * The value of all selected items.
+     * @default []
+     * @attribute
+     */
+    get value(): unknown[];
+    set value(value: unknown[]);
+    private _context;
+    private _internals;
+    private _keyActionController;
+    private _selectionController;
+    private _lastFocusedItem?;
+    private _expandIcon?;
+    private _collapseIcon?;
+    private _expandIconObserver?;
+    private _collapseIconObserver?;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    willUpdate(_changedProperties: PropertyValues<this>): void;
+    render(): TemplateResult;
+    private _updateContext;
+    /**
+     * Toggle either the selected or open state of a key item when its header is clicked.
+     */
+    private _handleClick;
+    /**
+     * Focuses the next or previous visible item.
+     */
+    private _handleArrowUpOrDown;
+    /**
+     * If the focused item is open, closes it. Otherwise, focuses the parent item.
+     */
+    private _handleArrowLeft;
+    /**
+     * If the focused item is closed, opens it. Otherwise, focuses the first child item.
+     */
+    private _handleArrowRight;
+    /**
+     * Focuses the first visible item. If the mode is multiple and the meta key is pressed, selects
+     * all previous items.
+     */
+    private _handleHome;
+    /**
+     * Focuses the last visible item. If the mode is multiple and the meta key is pressed, selects
+     * all subsequent items.
+     */
+    private _handleEnd;
+    /**
+     * Opens the focused item and all sibling items.
+     */
+    private _handleAsterisk;
+    /**
+     * If the mode is multiple, selects all items.
+     */
+    private _handleA;
+    /**
+     * Toggles the open or selected state of the focused item.
+     */
+    private _handleEnterOrSpace;
+    private _handleFocusIn;
+    private _handleFocusOut;
+    private _handleUpdate;
+    private _search;
+    private _toggleOpen;
+    private _focusItem;
+    private _detectSlottedIcon;
+    private _observeIcon;
+    private _updateIcon;
+    private _setDisabled;
+    private _setMode;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'forge-tree': TreeComponent;
+    }
+}