@tylertech/forge 3.12.0 → 3.13.0

package/esm/tree/tree/tree.js

@@ -0,0 +1,488 @@
+/**
+ * @license
+ * Copyright Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { __decorate } from "tslib";
+import { createContext, provide } from '@lit/context';
+import { html, LitElement, unsafeCSS } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+import { classMap } from 'lit/directives/class-map.js';
+import { setDefaultAria } from '../../core/utils/a11y-utils';
+import { toggleState } from '../../core/utils/utils';
+import { KeyActionController } from '../../core/utils/key-action';
+import { closeDescendants, eventPathIncludesTreeItemExpandIcon, eventPathIncludesTreeItemHeader, getFirstChildItem, getLastChildItem, getNextItem, getParentItem, getPreviousItem, getSiblingItems, getTreeItemFromEvent, getTreeItemsInEventPath, getTreeItemTarget, isTreeItem, searchItems } from '../tree-utils';
+import { TreeSelectionController } from './tree-selection-controller';
+const styles = ':host{display:block}.forge-tree{--_tree-background:var(--forge-tree-background, var(--forge-theme-primary-container, #d1d5ed));--_tree-color:var(--forge-tree-color, var(--forge-theme-on-primary-container, #222c62));--_tree-transition-duration:var(--forge-tree-transition-duration, var(--forge-animation-duration-short4, 200ms));--_tree-transition-timing:var(--forge-tree-transition-timing, var(--forge-animation-easing-standard, cubic-bezier(0.2, 0, 0, 1)));--_tree-shape:var(--forge-tree-shape, calc(var(--forge-shape-medium, 4px) * var(--forge-shape-factor, 1)));--_tree-padding:var(--forge-tree-padding, var(--forge-spacing-medium, 16px));--_tree-item-gap:var(--forge-tree-item-gap, var(--forge-spacing-xxxsmall, 2px))}.forge-tree{--_tree-item-check-display:var(--forge-tree-item-check-display, none);--_tree-item-indent-line-display:var(--forge-tree-item-indent-line-display, none);display:flex;flex-direction:column;gap:var(--_tree-item-gap)}.forge-tree.indent-lines{--_tree-item-indent-line-display:var(--forge-tree-item-indent-line-display, block)}.forge-tree.multiple{--_tree-item-check-display:var(--forge-tree-item-check-display, block);--forge-tree-item-selected-background:transparent}.forge-tree .icons{display:none}';
+export const TREE_CONTEXT = createContext('forge-tree');
+/**
+ * @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.
+ */
+let TreeComponent = class TreeComponent extends LitElement {
+    /**
+     * The value of all selected items.
+     * @default []
+     * @attribute
+     */
+    get value() {
+        return this._selectionController.value;
+    }
+    set value(value) {
+        this._selectionController.value = value;
+    }
+    constructor() {
+        super();
+        /**
+         * Whether opening an item closes all other items.
+         * @default false
+         * @attribute
+         */
+        this.accordion = false;
+        /**
+         * Toggles the rendering of indent lines showing hierarchy.
+         * @default false
+         * @attribute
+         */
+        this.indentLines = false;
+        /**
+         * How selecting tree items is handled.
+         * @default 'single'
+         * @attribute
+         */
+        this.mode = 'single';
+        /**
+         * Whether focusing an item also selects it. This takes no effect when in multiple mode.
+         * @default false
+         * @attribute
+         */
+        this.selectionFollowsFocus = false;
+        /**
+         * Whether selecting items is disabled.
+         * @default false
+         * @attribute
+         */
+        this.disabled = false;
+        this._keyActionController = new KeyActionController(this, {
+            actions: [
+                { key: ['ArrowUp', 'ArrowDown'], handler: this._handleArrowUpOrDown.bind(this), allowRepeat: true },
+                { key: 'ArrowLeft', handler: this._handleArrowLeft.bind(this), allowRepeat: true },
+                { key: 'ArrowRight', handler: this._handleArrowRight.bind(this), allowRepeat: true },
+                { key: 'Home', handler: this._handleHome.bind(this) },
+                { key: 'End', handler: this._handleEnd.bind(this) },
+                { key: '*', handler: this._handleAsterisk.bind(this) },
+                {
+                    key: [
+                        { key: 'a', modifier: 'ctrl' },
+                        { key: 'a', modifier: 'meta' }
+                    ],
+                    handler: this._handleA.bind(this)
+                },
+                { key: ['Enter', ' '], handler: this._handleEnterOrSpace.bind(this) }
+            ],
+            searchHandler: this._search.bind(this)
+        });
+        this._selectionController = new TreeSelectionController(this);
+        this._internals = this.attachInternals();
+        this._updateContext();
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.tabIndex = 0;
+        setDefaultAria(this, this._internals, { role: 'tree' });
+        // Listen for focus events on the host element
+        this.addEventListener('focusin', this._handleFocusIn.bind(this));
+        this.addEventListener('focusout', this._handleFocusOut.bind(this));
+        // Listen for item update events on the host element
+        this.addEventListener('forge-tree-item-update', this._handleUpdate.bind(this));
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this._expandIconObserver?.disconnect();
+        this._collapseIconObserver?.disconnect();
+    }
+    willUpdate(_changedProperties) {
+        if (_changedProperties.has('accordion')) {
+            if (this.accordion) {
+                closeDescendants(this);
+            }
+        }
+        if (_changedProperties.has('disabled')) {
+            this._setDisabled();
+        }
+        if (_changedProperties.has('disabled') || _changedProperties.has('indentLines') || _changedProperties.has('mode')) {
+            this._updateContext();
+        }
+        if (_changedProperties.has('mode')) {
+            this._setDisabled();
+            this._setMode();
+            this._selectionController.cleanup();
+        }
+    }
+    render() {
+        return html `
+      <div
+        part="root"
+        class=${classMap({ 'forge-tree': true, 'indent-lines': this.indentLines, multiple: this.mode === 'multiple' })}
+        @click=${this._handleClick}>
+        <slot></slot>
+        <div class="icons" @slotchange="${this._detectSlottedIcon}">
+          <slot name="expand-icon"></slot>
+          <slot name="collapse-icon"></slot>
+        </div>
+      </div>
+    `;
+    }
+    _updateContext() {
+        this._context = {
+            collapseIcon: this._collapseIcon,
+            disabled: this.disabled,
+            expandIcon: this._expandIcon,
+            indentLines: this.indentLines,
+            mode: this.mode
+        };
+    }
+    /**
+     * Toggle either the selected or open state of a key item when its header is clicked.
+     */
+    _handleClick(evt) {
+        // Ensure an item's header was clicked
+        if (!eventPathIncludesTreeItemHeader(evt)) {
+            return;
+        }
+        // Get the item
+        const item = getTreeItemTarget(evt);
+        if (!item) {
+            return;
+        }
+        // If the item is a leaf node toggle the selected state
+        if (item.leaf) {
+            // Do nothing if selection is off
+            if (this.mode === 'off') {
+                return;
+            }
+            if (evt.shiftKey) {
+                this._selectionController.extend(item);
+            }
+            this._selectionController.toggle(item);
+            return;
+        }
+        // If in leaf or off mode a click anywhere toggles the open state
+        if (this.mode === 'leaf' || this.mode === 'off') {
+            this._toggleOpen(item, evt.altKey && item.open);
+            return;
+        }
+        // Otherwise only a click on the expand icon toggles the open state
+        if (!item.openDisabled && eventPathIncludesTreeItemExpandIcon(evt)) {
+            this._toggleOpen(item, evt.altKey && item.open);
+            return;
+        }
+        if (evt.shiftKey) {
+            this._selectionController.extend(item);
+        }
+        this._selectionController.toggle(item);
+    }
+    /**
+     * Focuses the next or previous visible item.
+     */
+    _handleArrowUpOrDown(evt) {
+        const target = getTreeItemFromEvent(evt);
+        if (!target) {
+            return;
+        }
+        const destinationItem = evt.key === 'ArrowDown' ? getNextItem(target) : getPreviousItem(target);
+        if (destinationItem) {
+            if (evt.shiftKey && this.mode === 'multiple') {
+                this._selectionController.toggle(destinationItem, true);
+            }
+            this._focusItem(destinationItem);
+        }
+    }
+    /**
+     * If the focused item is open, closes it. Otherwise, focuses the parent item.
+     */
+    _handleArrowLeft(evt) {
+        const target = getTreeItemFromEvent(evt);
+        if (!target) {
+            return;
+        }
+        if (!target.open) {
+            const parent = getParentItem(target);
+            if (parent) {
+                this._focusItem(parent);
+            }
+        }
+        this._toggleOpen(target, false, false);
+    }
+    /**
+     * If the focused item is closed, opens it. Otherwise, focuses the first child item.
+     */
+    _handleArrowRight(evt) {
+        const target = getTreeItemFromEvent(evt);
+        if (!target || target.leaf) {
+            return;
+        }
+        if (target.open) {
+            const firstChild = getFirstChildItem(target);
+            if (firstChild) {
+                this._focusItem(firstChild);
+            }
+        }
+        this._toggleOpen(target, false, true);
+    }
+    /**
+     * Focuses the first visible item. If the mode is multiple and the meta key is pressed, selects
+     * all previous items.
+     */
+    _handleHome(evt) {
+        const target = getTreeItemFromEvent(evt);
+        if (!target) {
+            return;
+        }
+        // Select all previous items if the shift and meta keys are pressed
+        if (evt.shiftKey && (evt.metaKey || evt.ctrlKey) && this.mode === 'multiple') {
+            // TODO: can this just use the selection controller's extend method?
+            let previousItem = getPreviousItem(target);
+            while (previousItem) {
+                this._selectionController.toggle(previousItem, true);
+                previousItem = getPreviousItem(previousItem);
+            }
+        }
+        const firstItem = getFirstChildItem(this);
+        if (firstItem) {
+            this._focusItem(firstItem);
+        }
+    }
+    /**
+     * Focuses the last visible item. If the mode is multiple and the meta key is pressed, selects
+     * all subsequent items.
+     */
+    _handleEnd(evt) {
+        const target = getTreeItemFromEvent(evt);
+        if (!target) {
+            return;
+        }
+        // Select all subsequent items if the shift and meta keys are pressed
+        if (evt.shiftKey && (evt.metaKey || evt.ctrlKey) && this.mode === 'multiple') {
+            // TODO: can this just use the selection controller's extend method?
+            let nextItem = getNextItem(target);
+            while (nextItem) {
+                this._selectionController.toggle(nextItem, true);
+                nextItem = getNextItem(nextItem);
+            }
+        }
+        let lastItem = getLastChildItem(this);
+        while (lastItem && lastItem.open) {
+            lastItem = getLastChildItem(lastItem);
+        }
+        if (lastItem) {
+            this._focusItem(lastItem);
+        }
+    }
+    /**
+     * Opens the focused item and all sibling items.
+     */
+    _handleAsterisk(evt) {
+        const target = getTreeItemFromEvent(evt);
+        if (!target) {
+            return;
+        }
+        getSiblingItems(target, true).forEach(item => this._toggleOpen(item, false, true));
+    }
+    /**
+     * If the mode is multiple, selects all items.
+     */
+    _handleA() {
+        if (this.mode !== 'multiple') {
+            return;
+        }
+        this._selectionController.selectAll();
+    }
+    /**
+     * Toggles the open or selected state of the focused item.
+     */
+    _handleEnterOrSpace(evt) {
+        const target = getTreeItemFromEvent(evt);
+        if (!target) {
+            return;
+        }
+        if (target.leaf) {
+            if (this.mode === 'off') {
+                return;
+            }
+            if (evt.shiftKey) {
+                this._selectionController.extend(target);
+            }
+            this._selectionController.toggle(target);
+            return;
+        }
+        if (evt.key === 'Enter') {
+            this._toggleOpen(target, evt.altKey && target.open);
+        }
+        else if (this.mode !== 'off') {
+            this._selectionController.toggle(target);
+        }
+    }
+    _handleFocusIn(evt) {
+        // Focus either the last focused item or first item when the tree receives focus
+        if (evt.target === this) {
+            const itemToFocus = this._lastFocusedItem ?? getFirstChildItem(this);
+            if (!itemToFocus) {
+                return;
+            }
+            this._focusItem(itemToFocus);
+        }
+        // If a tree item was focused, set it as the last focused item and add it to the tab order
+        const target = evt.target;
+        if (target && isTreeItem(target)) {
+            if (this._lastFocusedItem) {
+                this._lastFocusedItem.tabIndex = -1;
+            }
+            target.tabIndex = 0;
+            this._lastFocusedItem = target;
+            // Remove this from the tab order while focus is inside
+            this.tabIndex = -1;
+        }
+    }
+    _handleFocusOut(evt) {
+        // If focus moved outside the tree, reset the tree's tab index
+        const relatedTarget = evt.relatedTarget;
+        if (!relatedTarget || !this.contains(relatedTarget)) {
+            this.tabIndex = 0;
+        }
+    }
+    _handleUpdate(evt) {
+        evt.stopPropagation();
+        if (evt.detail.reason === 'opened') {
+            // Do nothing if accordion isn't enabled
+            if (!this.accordion) {
+                return;
+            }
+            // Do nothing if the target is missing or closed
+            const target = getTreeItemFromEvent(evt);
+            if (!target || !target.open) {
+                return;
+            }
+            // If accordion is enabled, close all the items outside the target's path
+            const items = getTreeItemsInEventPath(evt);
+            closeDescendants(this);
+            items.forEach(item => (item.open = true));
+        }
+    }
+    _search(searchString, evt) {
+        const target = getTreeItemFromEvent(evt);
+        if (!target) {
+            return;
+        }
+        const item = searchItems(target, searchString);
+        if (item) {
+            this._focusItem(item);
+        }
+    }
+    _toggleOpen(item, flatten = false, force) {
+        if (item.openDisabled) {
+            return;
+        }
+        item.open = force ?? !item.open;
+        if (!item.open && flatten) {
+            closeDescendants(item);
+        }
+        // Dispatch an open event from the item
+        const event = new CustomEvent(`forge-tree-item-${item.open ? 'open' : 'close'}`, { bubbles: true, composed: true });
+        item.dispatchEvent(event);
+        if (event.defaultPrevented) {
+            return;
+        }
+    }
+    _focusItem(item) {
+        item.focus();
+        if (this.mode !== 'multiple' && this.selectionFollowsFocus) {
+            this._selectionController.toggle(item, true);
+        }
+    }
+    _detectSlottedIcon(evt) {
+        // Get the slot and clone the first assigned element
+        const slot = evt.target;
+        const assignedElement = slot.assignedElements()[0];
+        // If the assigned element is removed, remove the icon and update the context
+        if (!assignedElement) {
+            if (slot.name === 'expand-icon') {
+                this._expandIcon = undefined;
+                this._expandIconObserver?.disconnect();
+            }
+            else if (slot.name === 'collapse-icon') {
+                this._collapseIcon = undefined;
+                this._collapseIconObserver?.disconnect();
+            }
+            this._updateContext();
+            return;
+        }
+        if (slot.name === 'expand-icon') {
+            this._observeIcon(assignedElement, 'expand');
+        }
+        else if (slot.name === 'collapse-icon') {
+            this._observeIcon(assignedElement, 'collapse');
+        }
+    }
+    _observeIcon(assignedElement, type) {
+        const key = `_${type}IconObserver`;
+        this[key] ?? (this[key] = new MutationObserver(() => this._updateIcon(assignedElement, type)));
+        this[key].observe(assignedElement, { attributes: true, subtree: true, childList: true, characterData: true });
+        this._updateIcon(assignedElement, type);
+    }
+    _updateIcon(assignedElement, type) {
+        // Clone the element and remove any ids
+        const clone = assignedElement?.cloneNode(true);
+        [clone, ...clone.querySelectorAll('[id]')].forEach(el => el.removeAttribute('id'));
+        // Set the slot, save the clone to the appropriate property, and update the context
+        clone.slot = `context-${type}-icon`;
+        this[`_${type}Icon`] = clone;
+        this._updateContext();
+    }
+    _setDisabled() {
+        setDefaultAria(this, this._internals, { ariaDisabled: this.disabled ? 'true' : 'false' });
+        toggleState(this._internals, 'disabled', this.disabled);
+    }
+    _setMode() {
+        setDefaultAria(this, this._internals, {
+            ariaMultiSelectable: this.mode === 'multiple' ? 'true' : 'false' // || this.mode === 'multiple-discrete'
+        });
+    }
+};
+TreeComponent.styles = unsafeCSS(styles);
+__decorate([
+    property({ type: Boolean })
+], TreeComponent.prototype, "accordion", void 0);
+__decorate([
+    property({ type: Boolean, attribute: 'indent-lines' })
+], TreeComponent.prototype, "indentLines", void 0);
+__decorate([
+    property({ type: String })
+], TreeComponent.prototype, "mode", void 0);
+__decorate([
+    property({ type: Boolean, attribute: 'selection-follows-focus' })
+], TreeComponent.prototype, "selectionFollowsFocus", void 0);
+__decorate([
+    property({ type: Boolean })
+], TreeComponent.prototype, "disabled", void 0);
+__decorate([
+    property({ type: Array })
+], TreeComponent.prototype, "value", null);
+__decorate([
+    provide({ context: TREE_CONTEXT })
+], TreeComponent.prototype, "_context", void 0);
+TreeComponent = __decorate([
+    customElement('forge-tree')
+], TreeComponent);
+export { TreeComponent };

package/esm/tree/tree-item/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+export * from './tree-item';
+export declare function defineTreeItemComponent(): void;

package/esm/tree/tree-item/index.js

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { tryDefine } from '@tylertech/forge-core';
+import { TreeItemComponent } from './tree-item';
+export * from './tree-item';
+export function defineTreeItemComponent() {
+    tryDefine('forge-tree-item', TreeItemComponent);
+}

package/esm/tree/tree-item/tree-item.d.ts

@@ -0,0 +1,112 @@
+/**
+ * @license
+ * Copyright Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { LitElement, PropertyValues, TemplateResult } from 'lit';
+import { indeterminate } from '../tree-utils';
+import '../../icon';
+import '../../open-icon';
+export type TreeItemCheckboxIcon = 'check_box_outline_blank' | 'check_box' | 'indeterminate_check_box';
+export type TreeItemUpdateReason = 'added' | 'deselected' | 'opened' | 'removed' | 'selected';
+/**
+ * @tag forge-tree-item
+ *
+ * @dependency forge-circular-progress
+ * @dependency forge-icon
+ * @dependency forge-open-icon
+ *
+ * @event {CustomEvent<unknown>} forge-tree-item-select - Dispatched when the user selects a tree item.
+ * @event {CustomEvent<void>} forge-tree-item-open - Dispatched when the user opens a tree item.
+ * @event {CustomEvent<void>} forge-tree-item-close - Dispatched when the user closes a tree item.
+ */
+export declare class TreeItemComponent extends LitElement {
+    static styles: import("lit").CSSResult;
+    /**
+     * The value of the tree item.
+     * @default undefined
+     * @attribute
+     */
+    value: unknown;
+    /**
+     * Whether the tree item is selected.
+     * @default false
+     * @attribute
+     */
+    selected: boolean;
+    /**
+     * Whether the tree item is expanded.
+     * @default false
+     * @attribute
+     */
+    open: boolean;
+    /**
+     * Whether the tree item supports lazy loading.
+     * @default false
+     * @attribute
+     */
+    lazy: boolean;
+    /**
+     * Whether the tree item is disabled.
+     * @default false
+     * @attribute
+     */
+    disabled: boolean;
+    /**
+     * Whether opening the tree item is disabled.
+     * @default false
+     * @attribute
+     */
+    openDisabled: boolean;
+    /**
+     * Whether the selected value is indeterminate. This is a symbol property to avoid being set from
+     * outside the library.
+     * @ignore
+     * @default false
+     */
+    [indeterminate]: boolean;
+    /**
+     * The depth of the tree item within the tree's hierarchy.
+     */
+    get level(): number;
+    /**
+     * Whether the tree item has no child items.
+     */
+    get leaf(): boolean;
+    /**
+     * Whether the selected value is indeterminate.
+     */
+    get indeterminate(): boolean;
+    private _treeContext?;
+    private _level;
+    private _leaf;
+    private _loading;
+    private _hasSlottedExpandIcon;
+    private _hasSlottedCollapseIcon;
+    private _checkboxIcon;
+    private _children;
+    private _internals;
+    private _hasBeenSelected;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    willUpdate(changedProperties: PropertyValues<this>): void;
+    render(): TemplateResult;
+    private _expandIconTemplate;
+    private _slotInParent;
+    private _detectChildren;
+    private _detectSlottedExpandOrCollapseIcon;
+    private _setIconFromContext;
+    private _setDisabled;
+    private _setLoading;
+    private _setMode;
+    private _setOpen;
+    private _setOpenDisabled;
+    private _setSelected;
+    private _dispatchUpdate;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'forge-tree-item': TreeItemComponent;
+    }
+}