@tylertech/forge 3.12.0 → 3.13.0

package/dist/vscode.css-custom-data.json

@@ -6071,6 +6071,7 @@
     {
       "name": "::part(scroll-container)",
       "description": "The scroll container element."
-    }
+    },
+    { "name": "::part(root)", "description": "The root tree element." }
   ]
 }

package/dist/vscode.html-custom-data.json

@@ -43,6 +43,11 @@
           "description": "Gets/sets whether the first option in the dropdown will be focused automatically when opened or not.",
           "values": []
         },
+        {
+          "name": "select-first-option-on-blur",
+          "description": "Determines whether the first available option should be selected automatically when blurring mid-filter.",
+          "values": []
+        },
         {
           "name": "allow-unmatched",
           "description": "Controls whether unmatched text entered by the user will stay visible an option in the dropdown is not found.",
@@ -900,7 +905,12 @@
         },
         {
           "name": "trigger",
-          "description": "The id of the button that the expansion panel is associated with.",
+          "description": "The id of the button that the expansion panel should be toggled by.",
+          "values": []
+        },
+        {
+          "name": "open-icon",
+          "description": "The id of the `<forge-open-icon>` that the expansion panel should toggle.",
           "values": []
         }
       ],
@@ -3929,6 +3939,80 @@
       ],
       "references": []
     },
+    {
+      "name": "forge-tree",
+      "description": "Trees are interactive lists that allow users to navigate through hierarchical data.\n---\n\n\n### **Events:**\n - **forge-tree-select-all** - Dispatched when the user selects all items.\n\n### **Slots:**\n - _default_ - The default slot for tree items.\n- **expand-icon** - A custom expand icon to show when an item is closed.\n- **collapse-icon** - A custom collapse icon to show when an item is open.\n\n### **CSS Parts:**\n - **root** - The root tree element.",
+      "attributes": [
+        {
+          "name": "accordion",
+          "description": "Whether opening an item closes all other items.",
+          "values": []
+        },
+        {
+          "name": "indentLines",
+          "description": "Toggles the rendering of indent lines showing hierarchy.",
+          "values": []
+        },
+        {
+          "name": "mode",
+          "description": "How selecting tree items is handled.",
+          "values": [{ "name": "TreeMode" }]
+        },
+        {
+          "name": "selectionFollowsFocus",
+          "description": "Whether focusing an item also selects it. This takes no effect when in multiple mode.",
+          "values": []
+        },
+        {
+          "name": "disabled",
+          "description": "Whether selecting items is disabled.",
+          "values": []
+        },
+        {
+          "name": "value",
+          "description": "The value of all selected items.",
+          "values": [{ "name": "unknown[]" }]
+        }
+      ],
+      "references": []
+    },
+    {
+      "name": "forge-tree-item",
+      "description": "\n---\n\n\n### **Events:**\n - **forge-tree-item-update**\n- **forge-tree-item-select** - Dispatched when the user selects a tree item.\n- **forge-tree-item-open** - Dispatched when the user opens a tree item.\n- **forge-tree-item-close** - Dispatched when the user closes a tree item.",
+      "attributes": [
+        {
+          "name": "value",
+          "description": "The value of the tree item.",
+          "values": []
+        },
+        {
+          "name": "selected",
+          "description": "Whether the tree item is selected.",
+          "values": []
+        },
+        {
+          "name": "open",
+          "description": "Whether the tree item is expanded.",
+          "values": []
+        },
+        {
+          "name": "lazy",
+          "description": "Whether the tree item supports lazy loading.",
+          "values": []
+        },
+        {
+          "name": "disabled",
+          "description": "Whether the tree item is disabled.",
+          "values": []
+        },
+        {
+          "name": "openDisabled",
+          "description": "Whether opening the tree item is disabled.",
+          "values": []
+        }
+      ],
+      "references": []
+    },
     {
       "name": "forge-view",
       "description": "Represents a single view content area within a view-switcher for organizing and displaying content sections.\n---\n",

package/esm/autocomplete/autocomplete-constants.d.ts

@@ -14,6 +14,7 @@ export declare const AUTOCOMPLETE_CONSTANTS: {
         DEBOUNCE: string;
         FILTER_ON_FOCUS: string;
         FILTER_FOCUS_FIRST: string;
+        SELECT_FIRST_OPTION_ON_BLUR: string;
         ALLOW_UNMATCHED: string;
         POPUP_TARGET: string;
         POPUP_CLASSES: string;

package/esm/autocomplete/autocomplete-constants.js

@@ -11,6 +11,7 @@ const attributes = {
     DEBOUNCE: 'debounce',
     FILTER_ON_FOCUS: 'filter-on-focus',
     FILTER_FOCUS_FIRST: 'filter-focus-first',
+    SELECT_FIRST_OPTION_ON_BLUR: 'select-first-option-on-blur',
     ALLOW_UNMATCHED: 'allow-unmatched',
     POPUP_TARGET: 'popup-target',
     POPUP_CLASSES: 'popup-classes',

package/esm/autocomplete/autocomplete-core.d.ts

@@ -14,6 +14,7 @@ export interface IAutocompleteCore extends IListDropdownAwareCore {
     debounce: number;
     filterOnFocus: boolean;
     filterFocusFirst: boolean;
+    selectFirstOptionOnBlur: boolean;
     allowUnmatched: boolean;
     popupTarget: string;
     filterText: string;
@@ -38,6 +39,7 @@ export declare class AutocompleteCore extends ListDropdownAwareCore implements I
     private _popupTarget;
     private _filterOnFocus;
     private _filterFocusFirst;
+    private _selectFirstOptionOnBlur;
     private _optionBuilder?;
     private _filter?;
     private _selectedTextBuilder;
@@ -46,6 +48,7 @@ export declare class AutocompleteCore extends ListDropdownAwareCore implements I
     private _selectedOptions;
     private _values;
     private _pendingFilterPromises;
+    private _selectOnBlurPending;
     private _identifier;
     private _matchKey?;
     private _filterFn;
@@ -81,6 +84,7 @@ export declare class AutocompleteCore extends ListDropdownAwareCore implements I
     private _onFocus;
     private _onBlur;
     private _applyBlur;
+    private _shouldSelectFirstOptionOnBlur;
     private _onInput;
     private _debounceFilter;
     private _onKeydown;
@@ -131,6 +135,8 @@ export declare class AutocompleteCore extends ListDropdownAwareCore implements I
     /** Gets/sets whether the first option in the dropdown will be focused automatically when opened or not. */
     get filterFocusFirst(): boolean;
     set filterFocusFirst(value: boolean);
+    get selectFirstOptionOnBlur(): boolean;
+    set selectFirstOptionOnBlur(value: boolean);
     /** Controls whether unmatched text entered by the user will stay visible an option in the dropdown is not found. */
     get allowUnmatched(): boolean;
     set allowUnmatched(value: boolean);

package/esm/autocomplete/autocomplete-core.js

@@ -21,11 +21,13 @@ export class AutocompleteCore extends ListDropdownAwareCore {
         this._allowUnmatched = false;
         this._filterOnFocus = true;
         this._filterFocusFirst = true;
+        this._selectFirstOptionOnBlur = false;
         this._options = [];
         this._filterText = '';
         this._selectedOptions = [];
         this._values = [];
         this._pendingFilterPromises = [];
+        this._selectOnBlurPending = false;
         this._matchKey = null;
         this._clickListener = evt => this._onClick(evt);
         this._focusListener = () => this._onFocus();
@@ -147,6 +149,7 @@ export class AutocompleteCore extends ListDropdownAwareCore {
         this._adapter.emitHostEvent(AUTOCOMPLETE_CONSTANTS.events.SCROLLED_BOTTOM);
     }
     _onFocus() {
+        this._selectOnBlurPending = false;
         if (!this._isDropdownOpen && this._adapter.getInputValue() && !Platform.isMobile) {
             this._adapter.selectInputValue();
         }
@@ -159,11 +162,11 @@ export class AutocompleteCore extends ListDropdownAwareCore {
         this._applyBlur();
     }
     _applyBlur() {
+        this._selectOnBlurPending = this._shouldSelectFirstOptionOnBlur();
         if (this._isDropdownOpen) {
             this._closeDropdown();
         }
-        // If we are in stateless mode, we don't need to do anything further
-        if (this._mode === AutocompleteMode.Stateless) {
+        if (this._selectOnBlurPending || this._mode === AutocompleteMode.Stateless) {
             return;
         }
         if (!this._selectedOptions.length) {
@@ -176,6 +179,9 @@ export class AutocompleteCore extends ListDropdownAwareCore {
             this._adapter.setSelectedText(this._getSelectedText());
         }
     }
+    _shouldSelectFirstOptionOnBlur() {
+        return this._selectFirstOptionOnBlur && !this._multiple && this._mode !== AutocompleteMode.Stateless && !!this._filter && !!this._filterText;
+    }
     _onInput(evt) {
         if (this._selectedOptions.length && !this._multiple && (!this._adapter.getInputValue() || this._allowUnmatched) && !this._adapter.isWrappingChipField()) {
             this._selectedOptions = [];
@@ -203,10 +209,14 @@ export class AutocompleteCore extends ListDropdownAwareCore {
         // If the dropdown is open, show the spinner and execute the filter. If not open, then we need to
         // show the dropdown (which will handle showing the spinner and executing the filter for us) so
         // we use the promise from that method instead.
-        if (this._isDropdownOpen) {
+        const keepDropdownClosed = this._selectOnBlurPending && !this._adapter.hasFocus();
+        if (this._isDropdownOpen && keepDropdownClosed) {
+            this._closeDropdown();
+        }
+        else if (this._isDropdownOpen) {
             this._adapter.setBusyVisibility(true);
         }
-        else {
+        else if (!keepDropdownClosed) {
             this._showDropdown({ filter: false });
         }
         try {
@@ -215,6 +225,7 @@ export class AutocompleteCore extends ListDropdownAwareCore {
         catch {
             // When an exception occurs, we just flush the pending promises and clean up
             this._pendingFilterPromises = [];
+            this._selectOnBlurPending = false;
             if (this._isDropdownOpen) {
                 this._closeDropdown();
             }
@@ -307,21 +318,38 @@ export class AutocompleteCore extends ListDropdownAwareCore {
             .catch(e => reject(`An unexpected error occurred while filtering: ${e}`)));
     }
     _onFilterComplete() {
-        if (!this._adapter.hasFocus()) {
+        const shouldSelectOnBlur = this._selectFirstOptionOnBlur && this._selectOnBlurPending;
+        if (!this._options.length) {
+            this._selectOnBlurPending = false;
             if (this._isDropdownOpen) {
                 this._closeDropdown();
             }
+            if (shouldSelectOnBlur && !this._allowUnmatched) {
+                this._filterText = '';
+                this._adapter.setSelectedText('');
+                this._clearValue();
+            }
             return;
         }
-        if (this._options.length) {
-            const sendFilterText = this._allowUnmatched && !this._selectedOptions.length;
-            this._dropdownReady({ userTriggered: sendFilterText });
-            if (this._filterFocusFirst && this._filterText) {
-                this._adapter.activateFirstOption();
+        if (shouldSelectOnBlur) {
+            this._selectOnBlurPending = false;
+            const firstOption = this._flatOptions[0];
+            if (firstOption) {
+                this._onSelect(firstOption.value, false);
             }
+            return;
         }
-        else {
-            this._closeDropdown();
+        if (!this._adapter.hasFocus()) {
+            this._selectOnBlurPending = false;
+            if (this._isDropdownOpen) {
+                this._closeDropdown();
+            }
+            return;
+        }
+        const sendFilterText = this._allowUnmatched && !this._selectedOptions.length;
+        this._dropdownReady({ userTriggered: sendFilterText });
+        if (this._filterFocusFirst && this._filterText) {
+            this._adapter.activateFirstOption();
         }
     }
     _clearValue() {
@@ -758,6 +786,15 @@ export class AutocompleteCore extends ListDropdownAwareCore {
             this._adapter.toggleHostAttribute(AUTOCOMPLETE_CONSTANTS.attributes.FILTER_FOCUS_FIRST, this._filterFocusFirst);
         }
     }
+    get selectFirstOptionOnBlur() {
+        return this._selectFirstOptionOnBlur;
+    }
+    set selectFirstOptionOnBlur(value) {
+        if (this._selectFirstOptionOnBlur !== value) {
+            this._selectFirstOptionOnBlur = value;
+            this._adapter.toggleHostAttribute(AUTOCOMPLETE_CONSTANTS.attributes.SELECT_FIRST_OPTION_ON_BLUR, this._selectFirstOptionOnBlur);
+        }
+    }
     /** Controls whether unmatched text entered by the user will stay visible an option in the dropdown is not found. */
     get allowUnmatched() {
         return this._allowUnmatched;

package/esm/autocomplete/autocomplete.d.ts

@@ -12,6 +12,7 @@ export interface IAutocompleteComponent extends IListDropdownAware {
     debounce: number;
     filterOnFocus: boolean;
     filterFocusFirst: boolean;
+    selectFirstOptionOnBlur: boolean;
     allowUnmatched: boolean;
     matchKey: string | null | undefined;
     popupTarget: string;
@@ -88,6 +89,12 @@ export declare class AutocompleteComponent extends ListDropdownAware implements
      * @attribute filter-focus-first
      */
     filterFocusFirst: boolean;
+    /**
+     * Determines whether the first available option should be selected automatically when blurring mid-filter.
+     * @default false
+     * @attribute select-first-option-on-blur
+     */
+    selectFirstOptionOnBlur: boolean;
     /**
      * Controls whether unmatched text entered by the user will stay visible an option in the dropdown is not found.
      * @default false

package/esm/autocomplete/autocomplete.js

@@ -37,6 +37,7 @@ let AutocompleteComponent = class AutocompleteComponent extends ListDropdownAwar
             AUTOCOMPLETE_CONSTANTS.attributes.DEBOUNCE,
             AUTOCOMPLETE_CONSTANTS.attributes.FILTER_ON_FOCUS,
             AUTOCOMPLETE_CONSTANTS.attributes.FILTER_FOCUS_FIRST,
+            AUTOCOMPLETE_CONSTANTS.attributes.SELECT_FIRST_OPTION_ON_BLUR,
             AUTOCOMPLETE_CONSTANTS.attributes.ALLOW_UNMATCHED,
             AUTOCOMPLETE_CONSTANTS.attributes.POPUP_TARGET,
             AUTOCOMPLETE_CONSTANTS.attributes.OPEN,
@@ -79,6 +80,9 @@ let AutocompleteComponent = class AutocompleteComponent extends ListDropdownAwar
             case AUTOCOMPLETE_CONSTANTS.attributes.FILTER_FOCUS_FIRST:
                 this.filterFocusFirst = coerceBoolean(newValue);
                 break;
+            case AUTOCOMPLETE_CONSTANTS.attributes.SELECT_FIRST_OPTION_ON_BLUR:
+                this.selectFirstOptionOnBlur = coerceBoolean(newValue);
+                break;
             case AUTOCOMPLETE_CONSTANTS.attributes.ALLOW_UNMATCHED:
                 this.allowUnmatched = coerceBoolean(newValue);
                 break;
@@ -133,6 +137,9 @@ __decorate([
 __decorate([
     coreProperty()
 ], AutocompleteComponent.prototype, "filterFocusFirst", void 0);
+__decorate([
+    coreProperty()
+], AutocompleteComponent.prototype, "selectFirstOptionOnBlur", void 0);
 __decorate([
     coreProperty()
 ], AutocompleteComponent.prototype, "allowUnmatched", void 0);

package/esm/calendar/calendar-core.d.ts

@@ -376,11 +376,13 @@ export declare class CalendarCore implements ICalendarCore {
     /**
      * Sets the month text and attribute in the adapter.
      * @param userSelected Whether the month was explicitly selected by the user (optional)
+     * @param suppressEvent Whether to suppress emitting the month change event (optional)
      * */
     private _setMonth;
     /**
      * Sets the year text and attribute in the adapter.
      * @param userSelected Whether the year was explicity selected by the user (optional)
+     * @param suppressEvent Whether to suppress emitting the month change event (optional)
      * */
     private _setYear;
     /**

package/esm/calendar/calendar-core.js

@@ -1183,7 +1183,7 @@ export class CalendarCore {
         else {
             this._month = 0;
             this._year += 1;
-            this._setYear();
+            this._setYear(undefined, true);
         }
         this._setMonth();
         this._resetDateGrid();
@@ -1198,7 +1198,7 @@ export class CalendarCore {
         else {
             this._month = 11;
             this._year -= 1;
-            this._setYear();
+            this._setYear(undefined, true);
         }
         this._setMonth();
         this._resetDateGrid();
@@ -1315,33 +1315,39 @@ export class CalendarCore {
     /**
      * Sets the month text and attribute in the adapter.
      * @param userSelected Whether the month was explicitly selected by the user (optional)
+     * @param suppressEvent Whether to suppress emitting the month change event (optional)
      * */
-    _setMonth(userSelected) {
+    _setMonth(userSelected, suppressEvent) {
         this._adapter.setMonth(this._month, this._locale);
         this._adapter.setHostAttribute(CALENDAR_CONSTANTS.attributes.MONTH, this._month.toString());
         if (this._isInitialized) {
             this._setNavigationButtonStates();
-            this._adapter.emitHostEvent(CALENDAR_CONSTANTS.events.MONTH_CHANGE, {
-                month: this._month,
-                userSelected: userSelected ?? false,
-                year: this._year
-            });
+            if (!suppressEvent) {
+                this._adapter.emitHostEvent(CALENDAR_CONSTANTS.events.MONTH_CHANGE, {
+                    month: this._month,
+                    userSelected: userSelected ?? false,
+                    year: this._year
+                });
+            }
         }
     }
     /**
      * Sets the year text and attribute in the adapter.
      * @param userSelected Whether the year was explicity selected by the user (optional)
+     * @param suppressEvent Whether to suppress emitting the month change event (optional)
      * */
-    _setYear(userSelected) {
+    _setYear(userSelected, suppressEvent) {
         this._adapter.setYear(this._year, this._locale);
         this._adapter.setHostAttribute(CALENDAR_CONSTANTS.attributes.YEAR, this._year.toString());
         if (this._isInitialized) {
             this._setNavigationButtonStates();
-            this._adapter.emitHostEvent(CALENDAR_CONSTANTS.events.MONTH_CHANGE, {
-                month: this._month,
-                userSelected: userSelected ?? false,
-                year: this._year
-            });
+            if (!suppressEvent) {
+                this._adapter.emitHostEvent(CALENDAR_CONSTANTS.events.MONTH_CHANGE, {
+                    month: this._month,
+                    userSelected: userSelected ?? false,
+                    year: this._year
+                });
+            }
         }
     }
     /**

package/esm/core/testing/test-harness.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+export declare abstract class TestHarness<T extends HTMLElement> {
+    element: T;
+    constructor(element: T);
+    abstract initElementRefs(): void;
+    invalidate(): void;
+}

package/esm/core/testing/test-harness.js

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+export class TestHarness {
+    constructor(element) {
+        this.element = element;
+        this.initElementRefs();
+    }
+    invalidate() {
+        this.initElementRefs();
+    }
+}

package/esm/core/testing/utils.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+export declare function tryCleanupPopovers(): void;
+export declare function isVisibleInScrollContainer(scrollContainer: HTMLElement, element: HTMLElement): boolean;

package/esm/core/testing/utils.js

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+export function tryCleanupPopovers() {
+    const popovers = Array.from(document.querySelectorAll('forge-popover'));
+    popovers.forEach(p => p.remove());
+}
+export function isVisibleInScrollContainer(scrollContainer, element) {
+    const elemTop = element.offsetTop - scrollContainer.offsetTop;
+    const elemBottom = elemTop + element.offsetHeight;
+    return elemTop >= scrollContainer.scrollTop && elemBottom <= scrollContainer.scrollTop + scrollContainer.offsetHeight;
+}

package/esm/core/utils/index.d.ts

@@ -9,6 +9,7 @@ export * from './dismissible-stack';
 export * from './event-utils';
 export * from './feature-detection';
 export * from './form-utils';
+export * from './key-action';
 export * from './reflect-utils';
 export * from './svg-utils';
 export * from './time-utils';

package/esm/core/utils/index.js

@@ -9,6 +9,7 @@ export * from './dismissible-stack';
 export * from './event-utils';
 export * from './feature-detection';
 export * from './form-utils';
+export * from './key-action';
 export * from './reflect-utils';
 export * from './svg-utils';
 export * from './time-utils';

package/esm/core/utils/key-action.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @license
+ * Copyright Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { ReactiveController, ReactiveControllerHost } from 'lit';
+export type ModifierKey = 'alt' | 'ctrl' | 'meta' | 'shift';
+export type SearchFn = (searchString: string, evt: KeyboardEvent) => void;
+/**
+ * Defines a key combination.
+ */
+export interface KeyCombination {
+    /**
+     * The key.
+     */
+    key: string;
+    /**
+     * One or more modifier keys that must be pressed in conjunction with the key.
+     */
+    modifier?: ModifierKey | ModifierKey[];
+}
+/**
+ * Configuration interface for a key action.
+ */
+export interface IKeyAction {
+    /**
+     * One or more keys or key combinations that trigger the handler.
+     */
+    key: string | string[] | KeyCombination | KeyCombination[];
+    /**
+     * The function to be called when the specified key(s) are pressed.
+     * @param event - The keyboard event that triggered the handler.
+     * @returns A boolean or void. Returning `true` allows fallthrough to the next key handler.
+     */
+    handler(event: KeyboardEvent): boolean | void;
+    /**
+     * Indicates whether the handler should be called repeatedly while the key is held down.
+     */
+    allowRepeat?: boolean;
+}
+/**
+ * Configuration interface for the key action controller.
+ */
+export interface IKeyActionControllerConfig {
+    /**
+     * An optional array of key interaction configurations.
+     */
+    actions?: IKeyAction[];
+    /**
+     * An optional search handling function. If not provided, searching is disabled.
+     */
+    searchHandler?: SearchFn;
+}
+/**
+ * A Lit controller for attaching key down actions to a component host.
+ *
+ * @example
+ * class ExampleComponent extends LitElement {
+ *   private _keyActionController = new KeyActionController(this, {
+ *     actions: [
+ *       {
+ *         key: ['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'],
+ *         handler: this._handleArrowKey.bind(this),
+ *         allowRepeat: true
+ *       },
+ *       { key: 'Enter', handler: this._handleEnterKey.bind(this) },
+ *       { key: { key: 'a', modifier: 'shift' }, handler: this._handleAKey.bind(this) }
+ *     ],
+ *     searchHandler: this.handleSearch.bind(this)
+ *   });
+ *
+ *   private _handleArrowKey(evt: KeyboardEvent): void {
+ *     console.log(evt.key);
+ *   }
+ *
+ *   private _handleEnterKey(evt: KeyboardEvent): void {
+ *     console.log(evt.key);
+ *   }
+ *
+ *   private _handleAKey(evt: KeyboardEvent): void {
+ *     console.log(evt.key);
+ *   }
+ *
+ *   private _handleSearch(searchString: string): void {
+ *     console.log(searchString);
+ *   }
+ */
+export declare class KeyActionController implements ReactiveController {
+    private static _searchTimeout;
+    host: ReactiveControllerHost;
+    actions: IKeyAction[];
+    searchHandler?: SearchFn;
+    private _searchString;
+    private _searchTimeout?;
+    private _keyDownListener;
+    constructor(host: ReactiveControllerHost, config?: IKeyActionControllerConfig);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    private _handleKeyDown;
+    private _handleSearch;
+    private _eventMatchesKey;
+}