@ni/fast-foundation 0.0.2

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

@@ -0,0 +1,150 @@
+import { __decorate } from "tslib";
+import { attr, observable } from "@ni/fast-element";
+import { isHTMLElement } from "@ni/fast-web-utilities";
+import { StartEnd } from "../patterns/start-end.js";
+import { applyMixins } from "../utilities/apply-mixins.js";
+import { FoundationElement, } from "../foundation-element/foundation-element.js";
+/**
+ * check if the item is a tree item
+ * @public
+ * @remarks
+ * determines if element is an HTMLElement and if it has the role treeitem
+ */
+export function isTreeItemElement(el) {
+    return isHTMLElement(el) && el.getAttribute("role") === "treeitem";
+}
+/**
+ * A Tree item Custom HTML Element.
+ *
+ * @slot start - Content which can be provided before the tree item content
+ * @slot end - Content which can be provided after the tree item content
+ * @slot - The default slot for tree item text content
+ * @slot item - The slot for tree items (fast tree items manage this assignment themselves)
+ * @slot expand-collapse-button - The expand/collapse button
+ * @csspart positioning-region - The element used to position the tree item content with exception of any child nodes
+ * @csspart content-region - The element containing the expand/collapse, start, and end slots
+ * @csspart items - The element wrapping any child items
+ * @csspart expand-collapse-button - The expand/collapse button
+ * @fires expanded-change - Fires a custom 'expanded-change' event when the expanded state changes
+ * @fires selected-change - Fires a custom 'selected-change' event when the selected state changes
+ *
+ * @public
+ */
+export class TreeItem extends FoundationElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * When true, the control will be appear expanded by user interaction.
+         * @public
+         * @remarks
+         * HTML Attribute: expanded
+         */
+        this.expanded = false;
+        /**
+         * Whether the item is focusable
+         *
+         * @internal
+         */
+        this.focusable = false;
+        /**
+         * Whether the tree is nested
+         *
+         * @public
+         */
+        this.isNestedItem = () => {
+            return isTreeItemElement(this.parentElement);
+        };
+        /**
+         * Handle expand button click
+         *
+         * @internal
+         */
+        this.handleExpandCollapseButtonClick = (e) => {
+            if (!this.disabled && !e.defaultPrevented) {
+                this.expanded = !this.expanded;
+            }
+        };
+        /**
+         * Handle focus events
+         *
+         * @internal
+         */
+        this.handleFocus = (e) => {
+            this.setAttribute("tabindex", "0");
+        };
+        /**
+         * Handle blur events
+         *
+         * @internal
+         */
+        this.handleBlur = (e) => {
+            this.setAttribute("tabindex", "-1");
+        };
+    }
+    expandedChanged() {
+        if (this.$fastController.isConnected) {
+            this.$emit("expanded-change", this);
+        }
+    }
+    selectedChanged() {
+        if (this.$fastController.isConnected) {
+            this.$emit("selected-change", this);
+        }
+    }
+    itemsChanged(oldValue, newValue) {
+        if (this.$fastController.isConnected) {
+            this.items.forEach((node) => {
+                if (isTreeItemElement(node)) {
+                    // TODO: maybe not require it to be a TreeItem?
+                    node.nested = true;
+                }
+            });
+        }
+    }
+    /**
+     * Places document focus on a tree item
+     *
+     * @public
+     * @param el - the element to focus
+     */
+    static focusItem(el) {
+        el.focusable = true;
+        el.focus();
+    }
+    /**
+     * Gets number of children
+     *
+     * @internal
+     */
+    childItemLength() {
+        const treeChildren = this.childItems.filter((item) => {
+            return isTreeItemElement(item);
+        });
+        return treeChildren ? treeChildren.length : 0;
+    }
+}
+__decorate([
+    attr({ mode: "boolean" })
+], TreeItem.prototype, "expanded", void 0);
+__decorate([
+    attr({ mode: "boolean" })
+], TreeItem.prototype, "selected", void 0);
+__decorate([
+    attr({ mode: "boolean" })
+], TreeItem.prototype, "disabled", void 0);
+__decorate([
+    observable
+], TreeItem.prototype, "focusable", void 0);
+__decorate([
+    observable
+], TreeItem.prototype, "childItems", void 0);
+__decorate([
+    observable
+], TreeItem.prototype, "items", void 0);
+__decorate([
+    observable
+], TreeItem.prototype, "nested", void 0);
+__decorate([
+    observable
+], TreeItem.prototype, "renderCollapsedChildren", void 0);
+applyMixins(TreeItem, StartEnd);

package/dist/esm/tree-item/tree-item.template.js

@@ -0,0 +1,52 @@
+import { children, elements, html, ref, slotted, when } from "@ni/fast-element";
+import { endSlotTemplate, startSlotTemplate } from "../patterns/start-end.js";
+/**
+ * The template for the {@link @ni/fast-foundation#(TreeItem:class)} component.
+ * @public
+ */
+export const treeItemTemplate = (context, definition) => html `
+    <template
+        role="treeitem"
+        slot="${x => (x.isNestedItem() ? "item" : void 0)}"
+        tabindex="-1"
+        class="${x => (x.expanded ? "expanded" : "")} ${x => x.selected ? "selected" : ""} ${x => (x.nested ? "nested" : "")}
+            ${x => (x.disabled ? "disabled" : "")}"
+        aria-expanded="${x => x.childItems && x.childItemLength() > 0 ? x.expanded : void 0}"
+        aria-selected="${x => x.selected}"
+        aria-disabled="${x => x.disabled}"
+        @focusin="${(x, c) => x.handleFocus(c.event)}"
+        @focusout="${(x, c) => x.handleBlur(c.event)}"
+        ${children({
+    property: "childItems",
+    filter: elements(),
+})}
+    >
+        <div class="positioning-region" part="positioning-region">
+            <div class="content-region" part="content-region">
+                ${when(x => x.childItems && x.childItemLength() > 0, html `
+                        <div
+                            aria-hidden="true"
+                            class="expand-collapse-button"
+                            part="expand-collapse-button"
+                            @click="${(x, c) => x.handleExpandCollapseButtonClick(c.event)}"
+                            ${ref("expandCollapseButton")}
+                        >
+                            <slot name="expand-collapse-glyph">
+                                ${definition.expandCollapseGlyph || ""}
+                            </slot>
+                        </div>
+                    `)}
+                ${startSlotTemplate(context, definition)}
+                <slot></slot>
+                ${endSlotTemplate(context, definition)}
+            </div>
+        </div>
+        ${when(x => x.childItems &&
+    x.childItemLength() > 0 &&
+    (x.expanded || x.renderCollapsedChildren), html `
+                <div role="group" class="items" part="items">
+                    <slot name="item" ${slotted("items")}></slot>
+                </div>
+            `)}
+    </template>
+`;

package/dist/esm/tree-view/index.js

@@ -0,0 +1,2 @@
+export * from "./tree-view.template.js";
+export * from "./tree-view.js";

package/dist/esm/tree-view/tree-view.js

@@ -0,0 +1,268 @@
+import { __decorate } from "tslib";
+import { attr, DOM, observable } from "@ni/fast-element";
+import { getDisplayedNodes, isHTMLElement, keyArrowDown, keyArrowLeft, keyArrowRight, keyArrowUp, keyEnd, keyEnter, keyHome, } from "@ni/fast-web-utilities";
+import { isTreeItemElement, TreeItem } from "../tree-item/tree-item.js";
+import { FoundationElement } from "../foundation-element/foundation-element.js";
+/**
+ * A Tree view Custom HTML Element.
+ * Implements the {@link https://w3c.github.io/aria-practices/#TreeView | ARIA TreeView }.
+ *
+ * @slot - The default slot for tree items
+ *
+ * @public
+ */
+export class TreeView extends FoundationElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * The tree item that is designated to be in the tab queue.
+         *
+         * @internal
+         */
+        this.currentFocused = null;
+        /**
+         * Handle focus events
+         *
+         * @internal
+         */
+        this.handleFocus = (e) => {
+            if (this.slottedTreeItems.length < 1) {
+                // no child items, nothing to do
+                return;
+            }
+            if (e.target === this) {
+                if (this.currentFocused === null) {
+                    this.currentFocused = this.getValidFocusableItem();
+                }
+                if (this.currentFocused !== null) {
+                    TreeItem.focusItem(this.currentFocused);
+                }
+                return;
+            }
+            if (this.contains(e.target)) {
+                this.setAttribute("tabindex", "-1");
+                this.currentFocused = e.target;
+            }
+        };
+        /**
+         * Handle blur events
+         *
+         * @internal
+         */
+        this.handleBlur = (e) => {
+            if (e.target instanceof HTMLElement &&
+                (e.relatedTarget === null || !this.contains(e.relatedTarget))) {
+                this.setAttribute("tabindex", "0");
+            }
+        };
+        /**
+         * KeyDown handler
+         *
+         *  @internal
+         */
+        this.handleKeyDown = (e) => {
+            if (e.defaultPrevented) {
+                return;
+            }
+            if (this.slottedTreeItems.length < 1) {
+                return true;
+            }
+            const treeItems = this.getVisibleNodes();
+            switch (e.key) {
+                case keyHome:
+                    if (treeItems.length) {
+                        TreeItem.focusItem(treeItems[0]);
+                    }
+                    return;
+                case keyEnd:
+                    if (treeItems.length) {
+                        TreeItem.focusItem(treeItems[treeItems.length - 1]);
+                    }
+                    return;
+                case keyArrowLeft:
+                    if (e.target && this.isFocusableElement(e.target)) {
+                        const item = e.target;
+                        if (item instanceof TreeItem &&
+                            item.childItemLength() > 0 &&
+                            item.expanded) {
+                            item.expanded = false;
+                        }
+                        else if (item instanceof TreeItem &&
+                            item.parentElement instanceof TreeItem) {
+                            TreeItem.focusItem(item.parentElement);
+                        }
+                    }
+                    return false;
+                case keyArrowRight:
+                    if (e.target && this.isFocusableElement(e.target)) {
+                        const item = e.target;
+                        if (item instanceof TreeItem &&
+                            item.childItemLength() > 0 &&
+                            !item.expanded) {
+                            item.expanded = true;
+                        }
+                        else if (item instanceof TreeItem && item.childItemLength() > 0) {
+                            this.focusNextNode(1, e.target);
+                        }
+                    }
+                    return;
+                case keyArrowDown:
+                    if (e.target && this.isFocusableElement(e.target)) {
+                        this.focusNextNode(1, e.target);
+                    }
+                    return;
+                case keyArrowUp:
+                    if (e.target && this.isFocusableElement(e.target)) {
+                        this.focusNextNode(-1, e.target);
+                    }
+                    return;
+                case keyEnter:
+                    // In single-select trees where selection does not follow focus (see note below),
+                    // the default action is typically to select the focused node.
+                    this.handleClick(e);
+                    return;
+            }
+            // don't prevent default if we took no action
+            return true;
+        };
+        /**
+         * Handles the selected-changed events bubbling up
+         * from child tree items
+         *
+         *  @internal
+         */
+        this.handleSelectedChange = (e) => {
+            if (e.defaultPrevented) {
+                return;
+            }
+            if (!(e.target instanceof Element) || !isTreeItemElement(e.target)) {
+                return true;
+            }
+            const item = e.target;
+            if (item.selected) {
+                if (this.currentSelected && this.currentSelected !== item) {
+                    this.currentSelected.selected = false;
+                }
+                // new selected item
+                this.currentSelected = item;
+            }
+            else if (!item.selected && this.currentSelected === item) {
+                // selected item deselected
+                this.currentSelected = null;
+            }
+            return;
+        };
+        /**
+         * Updates the tree view when slottedTreeItems changes
+         */
+        this.setItems = () => {
+            // force single selection
+            // defaults to first one found
+            const selectedItem = this.treeView.querySelector("[aria-selected='true']");
+            this.currentSelected = selectedItem;
+            // invalidate the current focused item if it is no longer valid
+            if (this.currentFocused === null || !this.contains(this.currentFocused)) {
+                this.currentFocused = this.getValidFocusableItem();
+            }
+            // toggle properties on child elements
+            this.nested = this.checkForNestedItems();
+            const treeItems = this.getVisibleNodes();
+            treeItems.forEach(node => {
+                if (isTreeItemElement(node)) {
+                    node.nested = this.nested;
+                }
+            });
+        };
+        /**
+         * check if the item is focusable
+         */
+        this.isFocusableElement = (el) => {
+            return isTreeItemElement(el);
+        };
+        this.isSelectedElement = (el) => {
+            return el.selected;
+        };
+    }
+    slottedTreeItemsChanged() {
+        if (this.$fastController.isConnected) {
+            // update for slotted children change
+            this.setItems();
+        }
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.setAttribute("tabindex", "0");
+        DOM.queueUpdate(() => {
+            this.setItems();
+        });
+    }
+    /**
+     * Handles click events bubbling up
+     *
+     *  @internal
+     */
+    handleClick(e) {
+        if (e.defaultPrevented) {
+            // handled, do nothing
+            return;
+        }
+        if (!(e.target instanceof Element) || !isTreeItemElement(e.target)) {
+            // not a tree item, ignore
+            return true;
+        }
+        const item = e.target;
+        if (!item.disabled) {
+            item.selected = !item.selected;
+        }
+        return;
+    }
+    /**
+     * Move focus to a tree item based on its offset from the provided item
+     */
+    focusNextNode(delta, item) {
+        const visibleNodes = this.getVisibleNodes();
+        if (!visibleNodes) {
+            return;
+        }
+        const focusItem = visibleNodes[visibleNodes.indexOf(item) + delta];
+        if (isHTMLElement(focusItem)) {
+            TreeItem.focusItem(focusItem);
+        }
+    }
+    /**
+     * checks if there are any nested tree items
+     */
+    getValidFocusableItem() {
+        const treeItems = this.getVisibleNodes();
+        // default to selected element if there is one
+        let focusIndex = treeItems.findIndex(this.isSelectedElement);
+        if (focusIndex === -1) {
+            // otherwise first focusable tree item
+            focusIndex = treeItems.findIndex(this.isFocusableElement);
+        }
+        if (focusIndex !== -1) {
+            return treeItems[focusIndex];
+        }
+        return null;
+    }
+    /**
+     * checks if there are any nested tree items
+     */
+    checkForNestedItems() {
+        return this.slottedTreeItems.some((node) => {
+            return isTreeItemElement(node) && node.querySelector("[role='treeitem']");
+        });
+    }
+    getVisibleNodes() {
+        return getDisplayedNodes(this, "[role='treeitem']") || [];
+    }
+}
+__decorate([
+    attr({ attribute: "render-collapsed-nodes" })
+], TreeView.prototype, "renderCollapsedNodes", void 0);
+__decorate([
+    observable
+], TreeView.prototype, "currentSelected", void 0);
+__decorate([
+    observable
+], TreeView.prototype, "slottedTreeItems", void 0);

package/dist/esm/tree-view/tree-view.template.js

@@ -0,0 +1,18 @@
+import { html, ref, slotted } from "@ni/fast-element";
+/**
+ * The template for the {@link @ni/fast-foundation#TreeView} component.
+ * @public
+ */
+export const treeViewTemplate = (context, definition) => html `
+    <template
+        role="tree"
+        ${ref("treeView")}
+        @keydown="${(x, c) => x.handleKeyDown(c.event)}"
+        @focusin="${(x, c) => x.handleFocus(c.event)}"
+        @focusout="${(x, c) => x.handleBlur(c.event)}"
+        @click="${(x, c) => x.handleClick(c.event)}"
+        @selected-change="${(x, c) => x.handleSelectedChange(c.event)}"
+    >
+        <slot ${slotted("slottedTreeItems")}></slot>
+    </template>
+`;

package/dist/esm/utilities/apply-mixins.js

@@ -0,0 +1,20 @@
+import { AttributeConfiguration } from "@ni/fast-element";
+/**
+ * Apply mixins to a constructor.
+ * Sourced from {@link https://www.typescriptlang.org/docs/handbook/mixins.html | TypeScript Documentation }.
+ * @public
+ */
+export function applyMixins(derivedCtor, ...baseCtors) {
+    const derivedAttributes = AttributeConfiguration.locate(derivedCtor);
+    baseCtors.forEach(baseCtor => {
+        Object.getOwnPropertyNames(baseCtor.prototype).forEach(name => {
+            if (name !== "constructor") {
+                Object.defineProperty(derivedCtor.prototype, name, 
+                /* eslint-disable-next-line @typescript-eslint/no-non-null-assertion */
+                Object.getOwnPropertyDescriptor(baseCtor.prototype, name));
+            }
+        });
+        const baseAttributes = AttributeConfiguration.locate(baseCtor);
+        baseAttributes.forEach(x => derivedAttributes.push(x));
+    });
+}

package/dist/esm/utilities/composed-contains.js

@@ -0,0 +1,22 @@
+import { composedParent } from "./composed-parent.js";
+/**
+ * Determines if the reference element contains the test element in a "composed" DOM tree that
+ * ignores shadow DOM boundaries.
+ *
+ * Returns true of the test element is a descendent of the reference, or exist in
+ * a shadow DOM that is a logical descendent of the reference. Otherwise returns false.
+ * @param reference - The element to test for containment against.
+ * @param test - The element being tested for containment.
+ *
+ * @public
+ */
+export function composedContains(reference, test) {
+    let current = test;
+    while (current !== null) {
+        if (current === reference) {
+            return true;
+        }
+        current = composedParent(current);
+    }
+    return false;
+}

package/dist/esm/utilities/composed-parent.js

@@ -0,0 +1,23 @@
+/**
+ * Retrieves the "composed parent" element of a node, ignoring DOM tree boundaries.
+ * When the parent of a node is a shadow-root, it will return the host
+ * element of the shadow root. Otherwise it will return the parent node or null if
+ * no parent node exists.
+ * @param element - The element for which to retrieve the composed parent
+ *
+ * @public
+ */
+export function composedParent(element) {
+    const parentNode = element.parentElement;
+    if (parentNode) {
+        return parentNode;
+    }
+    else {
+        const rootNode = element.getRootNode();
+        if (rootNode.host instanceof HTMLElement) {
+            // this is shadow-root
+            return rootNode.host;
+        }
+    }
+    return null;
+}

package/dist/esm/utilities/direction.js

@@ -0,0 +1,10 @@
+import { Direction } from "@ni/fast-web-utilities";
+/**
+ * a method to determine the current localization direction of the view
+ * @param rootNode - the HTMLElement to begin the query from, usually "this" when used in a component controller
+ * @public
+ */
+export const getDirection = (rootNode) => {
+    const dirNode = rootNode.closest("[dir]");
+    return dirNode !== null && dirNode.dir === "rtl" ? Direction.rtl : Direction.ltr;
+};

package/dist/esm/utilities/index.js

@@ -0,0 +1,8 @@
+export * from "./apply-mixins.js";
+export * from "./composed-parent.js";
+export { composedContains } from "./composed-contains.js";
+export * from "./match-media-stylesheet-behavior.js";
+export * from "./property-stylesheet-behavior.js";
+export * from "./style/index.js";
+export * from "./direction.js";
+export * from "./whitespace-filter.js";

package/dist/esm/utilities/intersection-service.js

@@ -0,0 +1,91 @@
+import { $global } from "@ni/fast-element";
+/**
+ *  A service to batch intersection event callbacks so multiple elements can share a single observer
+ *
+ * @public
+ */
+export class IntersectionService {
+    constructor() {
+        this.intersectionDetector = null;
+        this.observedElements = new Map();
+        /**
+         * Request the position of a target element
+         *
+         * @internal
+         */
+        this.requestPosition = (target, callback) => {
+            var _a;
+            if (this.intersectionDetector === null) {
+                return;
+            }
+            if (this.observedElements.has(target)) {
+                (_a = this.observedElements.get(target)) === null || _a === void 0 ? void 0 : _a.push(callback);
+                return;
+            }
+            this.observedElements.set(target, [callback]);
+            this.intersectionDetector.observe(target);
+        };
+        /**
+         * Cancel a position request
+         *
+         * @internal
+         */
+        this.cancelRequestPosition = (target, callback) => {
+            const callbacks = this.observedElements.get(target);
+            if (callbacks !== undefined) {
+                const callBackIndex = callbacks.indexOf(callback);
+                if (callBackIndex !== -1) {
+                    callbacks.splice(callBackIndex, 1);
+                }
+            }
+        };
+        /**
+         * initialize intersection detector
+         */
+        this.initializeIntersectionDetector = () => {
+            if (!$global.IntersectionObserver) {
+                //intersection observer not supported
+                return;
+            }
+            this.intersectionDetector = new IntersectionObserver(this.handleIntersection, {
+                root: null,
+                rootMargin: "0px",
+                threshold: [0, 1],
+            });
+        };
+        /**
+         *  Handle intersections
+         */
+        this.handleIntersection = (entries) => {
+            if (this.intersectionDetector === null) {
+                return;
+            }
+            const pendingCallbacks = [];
+            const pendingCallbackParams = [];
+            // go through the entries to build a list of callbacks and params for each
+            entries.forEach((entry) => {
+                var _a;
+                // stop watching this element until we get new update requests for it
+                (_a = this.intersectionDetector) === null || _a === void 0 ? void 0 : _a.unobserve(entry.target);
+                const thisElementCallbacks = this.observedElements.get(entry.target);
+                if (thisElementCallbacks !== undefined) {
+                    thisElementCallbacks.forEach((callback) => {
+                        let targetCallbackIndex = pendingCallbacks.indexOf(callback);
+                        if (targetCallbackIndex === -1) {
+                            targetCallbackIndex = pendingCallbacks.length;
+                            pendingCallbacks.push(callback);
+                            pendingCallbackParams.push([]);
+                        }
+                        pendingCallbackParams[targetCallbackIndex].push(entry);
+                    });
+                    this.observedElements.delete(entry.target);
+                }
+            });
+            // execute callbacks
+            pendingCallbacks.forEach((callback, index) => {
+                callback(pendingCallbackParams[index]);
+            });
+        };
+        this.initializeIntersectionDetector();
+    }
+}