@aquera/nile-elements 0.0.80 → 0.0.82

package/src/nile-tree/nile-tree.ts

@@ -0,0 +1,433 @@
+/**
+ * Copyright Aquera Inc 2023
+ *
+ * This source code is licensed under the BSD-3-Clause license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {LitElement, CSSResultArray, TemplateResult} from 'lit-element';
+import {styles} from './nile-tree.css';
+import NileElement from '../internal/nile-element';
+import { clamp } from '../internal/math';
+import { customElement, property, query } from 'lit/decorators.js';
+import { html } from 'lit';
+import { watch } from '../internal/watch';
+import NileTreeItem from '../nile-tree-item/nile-tree-item';
+import type { CSSResultGroup } from 'lit';
+
+function syncCheckboxes(changedTreeItem: NileTreeItem, initialSync = false) {
+  function syncParentItem(treeItem: NileTreeItem) {
+    const children = treeItem.getChildrenItems({ includeDisabled: false });
+
+    if (children.length) {
+      const allChecked = children.every(item => item.selected);
+      const allUnchecked = children.every(item => !item.selected && !item.indeterminate);
+
+      treeItem.selected = allChecked;
+      treeItem.indeterminate = !allChecked && !allUnchecked;
+    }
+  }
+
+  function syncAncestors(treeItem: NileTreeItem) {
+    const parentItem: NileTreeItem | null = treeItem.parentElement as NileTreeItem;
+
+    if (NileTreeItem.isTreeItem(parentItem)) {
+      syncParentItem(parentItem);
+      syncAncestors(parentItem);
+    }
+  }
+
+  function syncDescendants(treeItem: NileTreeItem) {
+    for (const childItem of treeItem.getChildrenItems()) {
+      childItem.selected = initialSync
+        ? treeItem.selected || childItem.selected
+        : !childItem.disabled && treeItem.selected;
+
+      syncDescendants(childItem);
+    }
+
+    if (initialSync) {
+      syncParentItem(treeItem);
+    }
+  }
+
+  syncDescendants(changedTreeItem);
+  syncAncestors(changedTreeItem);
+}
+
+
+/**
+ * @summary Trees allow you to display a hierarchical list of selectable [tree items](/components/tree-item). Items with children can be expanded and collapsed as desired by the user.
+ *
+ * @event {{ selection: NileTreeItem[] }} nile-selection-change - Emitted when a tree item is selected or deselected.
+ *
+ * @slot - The default slot.
+ * @slot expand-icon - The icon to show when the tree item is expanded. Works best with `<nile-icon>`.
+ * @slot collapse-icon - The icon to show when the tree item is collapsed. Works best with `<nile-icon>`.
+ *
+ * @csspart base - The component's base wrapper.
+ *
+ * @cssproperty [--indent-size=var(--nile-spacing-medium)] - The size of the indentation for nested items.
+ * @cssproperty [--indent-guide-color=var(--nile-color-neutral-200)] - The color of the indentation line.
+ * @cssproperty [--indent-guide-offset=0] - The amount of vertical spacing to leave between the top and bottom of the
+ *  indentation line's starting position.
+ * @cssproperty [--indent-guide-style=solid] - The style of the indentation line, e.g. solid, dotted, dashed.
+ * @cssproperty [--indent-guide-width=0] - The width of the indentation line.
+ */
+
+@customElement('nile-tree')
+export class NileTree extends NileElement {
+
+	static styles: CSSResultGroup = styles;
+
+  @query('slot:not([name])') defaultSlot: HTMLSlotElement;
+  @query('slot[name=expand-icon]') expandedIconSlot: HTMLSlotElement;
+  @query('slot[name=collapse-icon]') collapsedIconSlot: HTMLSlotElement;
+
+  /**
+   * The selection behavior of the tree. Single selection allows only one node to be selected at a time. Multiple
+   * displays checkboxes and allows more than one node to be selected. Leaf allows only leaf nodes to be selected.
+   */
+  @property() selection: 'single' | 'multiple' | 'leaf' = 'leaf';
+
+  //
+  // A collection of all the items in the tree, in the order they appear. The collection is live, meaning it is
+  // automatically updated when the underlying document is changed.
+  //
+  private lastFocusedItem: NileTreeItem;
+  private mutationObserver: MutationObserver;
+  private clickTarget: NileTreeItem | null = null;
+
+  async connectedCallback() {
+    super.connectedCallback();
+    this.handleTreeChanged = this.handleTreeChanged.bind(this);
+    this.handleFocusIn = this.handleFocusIn.bind(this);
+    this.handleFocusOut = this.handleFocusOut.bind(this);
+
+    this.setAttribute('role', 'tree');
+    this.setAttribute('tabindex', '0');
+
+    this.addEventListener('focusin', this.handleFocusIn);
+    this.addEventListener('focusout', this.handleFocusOut);
+    this.addEventListener('nile-lazy-change', this.handleSlotChange);
+
+    await this.updateComplete;
+
+    this.mutationObserver = new MutationObserver(this.handleTreeChanged);
+    this.mutationObserver.observe(this, { childList: true, subtree: true });
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+
+    this.mutationObserver.disconnect();
+
+    this.removeEventListener('focusin', this.handleFocusIn);
+    this.removeEventListener('focusout', this.handleFocusOut);
+    this.removeEventListener('nile-lazy-change', this.handleSlotChange);
+  }
+
+  // Generates a clone of the expand icon element to use for each tree item
+  private getExpandButtonIcon(status: 'expand' | 'collapse') {
+    const slot = status === 'expand' ? this.expandedIconSlot : this.collapsedIconSlot;
+    const icon = slot.assignedElements({ flatten: true })[0] as HTMLElement;
+
+    // Clone it, remove ids, and slot it
+    if (icon) {
+      const clone = icon.cloneNode(true) as HTMLElement;
+      [clone, ...clone.querySelectorAll('[id]')].forEach(el => el.removeAttribute('id'));
+      clone.setAttribute('data-default', '');
+      clone.slot = `${status}-icon`;
+
+      return clone;
+    }
+
+    return null;
+  }
+
+  // Initializes new items by setting the `selectable` property and the expanded/collapsed icons if any
+  private initTreeItem = (item: NileTreeItem) => {
+    item.selectable = this.selection === 'multiple';
+
+    ['expand', 'collapse']
+      .filter(status => !!this.querySelector(`[slot="${status}-icon"]`))
+      .forEach((status: 'expand' | 'collapse') => {
+        const existingIcon = item.querySelector(`[slot="${status}-icon"]`);
+
+        if (existingIcon === null) {
+          // No separator exists, add one
+          item.append(this.getExpandButtonIcon(status)!);
+        } else if (existingIcon.hasAttribute('data-default')) {
+          // A default separator exists, replace it
+          existingIcon.replaceWith(this.getExpandButtonIcon(status)!);
+        } else {
+          // The user provided a custom icon, leave it alone
+        }
+      });
+  };
+
+  private handleTreeChanged(mutations: MutationRecord[]) {
+    for (const mutation of mutations) {
+      const addedNodes: NileTreeItem[] = [...mutation.addedNodes].filter(NileTreeItem.isTreeItem) as NileTreeItem[];
+      const removedNodes = [...mutation.removedNodes].filter(NileTreeItem.isTreeItem) as NileTreeItem[];
+
+      addedNodes.forEach(this.initTreeItem);
+
+      // If the focused item has been removed form the DOM, move the focus to the first focusable item
+      if (removedNodes.includes(this.lastFocusedItem)) {
+        this.focusItem(this.getFocusableItems()[0]);
+      }
+    }
+  }
+
+  private syncTreeItems(selectedItem: NileTreeItem) {
+    const items = this.getAllTreeItems();
+
+    if (this.selection === 'multiple') {
+      syncCheckboxes(selectedItem);
+    } else {
+      for (const item of items) {
+        if (item !== selectedItem) {
+          item.selected = false;
+        }
+      }
+    }
+  }
+
+  private selectItem(selectedItem: NileTreeItem) {
+    const previousSelection = [...this.selectedItems];
+
+    if (this.selection === 'multiple') {
+      selectedItem.selected = !selectedItem.selected;
+      if (selectedItem.lazy) {
+        selectedItem.expanded = true;
+      }
+      this.syncTreeItems(selectedItem);
+    } else if (this.selection === 'single' || selectedItem.isLeaf) {
+      selectedItem.expanded = !selectedItem.expanded;
+      selectedItem.selected = true;
+
+      this.syncTreeItems(selectedItem);
+    } else if (this.selection === 'leaf') {
+      selectedItem.expanded = !selectedItem.expanded;
+    }
+
+    const nextSelection = this.selectedItems;
+
+    if (
+      previousSelection.length !== nextSelection.length ||
+      nextSelection.some(item => !previousSelection.includes(item))
+    ) {
+      // Wait for the tree items' DOM to update before emitting
+      Promise.all(nextSelection.map(el => el.updateComplete)).then(() => {
+        this.emit('nile-selection-change', { detail: { selection: nextSelection } });
+      });
+    }
+  }
+
+  private getAllTreeItems() {
+    return [...this.querySelectorAll<NileTreeItem>('nile-tree-item')];
+  }
+
+  private focusItem(item?: NileTreeItem | null) {
+    item?.focus();
+  }
+
+  private handleKeyDown(event: KeyboardEvent) {
+    if (!['ArrowDown', 'ArrowUp', 'ArrowRight', 'ArrowLeft', 'Home', 'End', 'Enter', ' '].includes(event.key)) {
+      return;
+    }
+
+    const items = this.getFocusableItems();
+    const isLtr = true;
+    const isRtl = false;
+
+    if (items.length > 0) {
+      event.preventDefault();
+      const activeItemIndex = items.findIndex(item => item.matches(':focus'));
+      const activeItem: NileTreeItem | undefined = items[activeItemIndex];
+
+      const focusItemAt = (index: number) => {
+        const item = items[clamp(index, 0, items.length - 1)];
+        this.focusItem(item);
+      };
+      const toggleExpand = (expanded: boolean) => {
+        activeItem.expanded = expanded;
+      };
+
+      if (event.key === 'ArrowDown') {
+        // Moves focus to the next node that is focusable without opening or closing a node.
+        focusItemAt(activeItemIndex + 1);
+      } else if (event.key === 'ArrowUp') {
+        // Moves focus to the next node that is focusable without opening or closing a node.
+        focusItemAt(activeItemIndex - 1);
+      } else if ((isLtr && event.key === 'ArrowRight') || (isRtl && event.key === 'ArrowLeft')) {
+        //
+        // When focus is on a closed node, opens the node; focus does not move.
+        // When focus is on a open node, moves focus to the first child node.
+        // When focus is on an end node (a tree item with no children), does nothing.
+        //
+        if (!activeItem || activeItem.disabled || activeItem.expanded || (activeItem.isLeaf && !activeItem.lazy)) {
+          focusItemAt(activeItemIndex + 1);
+        } else {
+          toggleExpand(true);
+        }
+      } else if ((isLtr && event.key === 'ArrowLeft') || (isRtl && event.key === 'ArrowRight')) {
+        //
+        // When focus is on an open node, closes the node.
+        // When focus is on a child node that is also either an end node or a closed node, moves focus to its parent node.
+        // When focus is on a closed `tree`, does nothing.
+        //
+        if (!activeItem || activeItem.disabled || activeItem.isLeaf || !activeItem.expanded) {
+          focusItemAt(activeItemIndex - 1);
+        } else {
+          toggleExpand(false);
+        }
+      } else if (event.key === 'Home') {
+        // Moves focus to the first node in the tree without opening or closing a node.
+        focusItemAt(0);
+      } else if (event.key === 'End') {
+        // Moves focus to the last node in the tree that is focusable without opening the node.
+        focusItemAt(items.length - 1);
+      } else if (event.key === 'Enter' || event.key === ' ') {
+        // Selects the focused node.
+        if (!activeItem.disabled) {
+          this.selectItem(activeItem);
+        }
+      }
+    }
+  }
+
+  private handleClick(event: Event) {
+    const target = event.target as NileTreeItem;
+    const treeItem = target.closest('nile-tree-item')!;
+    const isExpandButton = event
+      .composedPath()
+      .some((el: HTMLElement) => el?.classList?.contains('tree-item__expand-button'));
+
+    //
+    // Don't Do anything if there's no tree item, if it's disabled, or if the click doesn't match the initial target
+    // from mousedown. The latter case prevents the user from starting a click on one item and ending it on another,
+    // causing the parent node to collapse.
+    //
+    if (!treeItem || treeItem.disabled || target !== this.clickTarget) {
+      return;
+    }
+
+    if (this.selection === 'multiple' && isExpandButton) {
+      treeItem.expanded = !treeItem.expanded;
+    } else {
+      this.selectItem(treeItem);
+    }
+  }
+
+  handleMouseDown(event: MouseEvent) {
+    // Record the click target so we know which item the click initially targeted
+    this.clickTarget = event.target as NileTreeItem;
+  }
+
+  private handleFocusOut(event: FocusEvent) {
+    const relatedTarget = event.relatedTarget as HTMLElement;
+
+    // If the element that got the focus is not in the tree
+    if (!relatedTarget || !this.contains(relatedTarget)) {
+      this.tabIndex = 0;
+    }
+  }
+
+  private handleFocusIn(event: FocusEvent) {
+    const target = event.target as NileTreeItem;
+
+    // If the tree has been focused, move the focus to the last focused item
+    if (event.target === this) {
+      this.focusItem(this.lastFocusedItem || this.getAllTreeItems()[0]);
+    }
+
+    // If the target is a tree item, update the tabindex
+    if (NileTreeItem.isTreeItem(target) && !target.disabled) {
+      if (this.lastFocusedItem) {
+        this.lastFocusedItem.tabIndex = -1;
+      }
+      this.lastFocusedItem = target;
+      this.tabIndex = -1;
+
+      target.tabIndex = 0;
+    }
+  }
+
+  private handleSlotChange() {
+    const items = this.getAllTreeItems();
+    items.forEach(this.initTreeItem);
+  }
+
+  @watch('selection')
+  async handleSelectionChange() {
+    const isSelectionMultiple = this.selection === 'multiple';
+    const items = this.getAllTreeItems();
+
+    this.setAttribute('aria-multiselectable', isSelectionMultiple ? 'true' : 'false');
+
+    for (const item of items) {
+      item.selectable = isSelectionMultiple;
+    }
+
+    if (isSelectionMultiple) {
+      await this.updateComplete;
+
+      [...this.querySelectorAll(':scope > nile-tree-item')].forEach((treeItem: NileTreeItem) =>
+        syncCheckboxes(treeItem, true)
+      );
+    }
+  }
+
+  /** @internal Returns the list of tree items that are selected in the tree. */
+  get selectedItems(): NileTreeItem[] {
+    const items = this.getAllTreeItems();
+    const isSelected = (item: NileTreeItem) => item.selected;
+
+    return items.filter(isSelected);
+  }
+
+  /** @internal Gets focusable tree items in the tree. */
+  getFocusableItems() {
+    const items = this.getAllTreeItems();
+    const collapsedItems = new Set();
+
+    return items.filter(item => {
+      // Exclude disabled elements
+      if (item.disabled) return false;
+
+      // Exclude those whose parent is collapsed or loading
+      const parent: NileTreeItem | null | undefined = item.parentElement?.closest('[role=treeitem]');
+      if (parent && (!parent.expanded || parent.loading || collapsedItems.has(parent))) {
+        collapsedItems.add(item);
+      }
+
+      return !collapsedItems.has(item);
+    });
+  }
+
+  render() {
+    return html`
+      <div
+        part="base"
+        class="tree"
+        @click=${this.handleClick}
+        @keydown=${this.handleKeyDown}
+        @mousedown=${this.handleMouseDown}
+      >
+        <slot @slotchange=${this.handleSlotChange}></slot>
+        <slot name="expand-icon" hidden aria-hidden="true"> </slot>
+        <slot name="collapse-icon" hidden aria-hidden="true"> </slot>
+      </div>
+    `;
+  }
+}
+
+export default NileTree;
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'nile-tree': NileTree;
+  }
+}

package/src/nile-tree-item/index.ts

@@ -0,0 +1 @@
+export { NileTreeItem } from './nile-tree-item';

package/src/nile-tree-item/nile-tree-item.css.ts

@@ -0,0 +1,178 @@
+/**
+* Copyright Aquera Inc 2023
+*
+* This source code is licensed under the BSD-3-Clause license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+
+import {css} from 'lit-element';
+
+/**
+ * TreeItem CSS
+ */
+export const styles = css`
+  :host {
+    box-sizing: border-box;
+  }
+
+  :host *,
+  :host *::before,
+  :host *::after {
+    box-sizing: inherit;
+  }
+
+  [hidden] {
+    display: none !important;
+  }
+
+  :host {
+    display: block;
+    outline: 0;
+    z-index: 0;
+  }
+
+  :host(:focus) {
+    outline: none;
+  }
+
+  slot:not([name])::slotted(nile-icon) {
+    margin-inline-end: 0.5rem;
+  }
+
+  .tree-item {
+    position: relative;
+    display: flex;
+    align-items: stretch;
+    flex-direction: column;
+    color: #777D82;
+    cursor: pointer;
+    user-select: none;
+  }
+
+  .tree-item__checkbox {
+    pointer-events: none;
+  }
+
+  .tree-item__expand-button,
+  .tree-item__checkbox,
+  .tree-item__label {
+    font-family: var(--nile-font-family-serif);
+    font-size: 16px;
+    font-weight: 400;
+  }
+
+  .tree-item__checkbox::part(base) {
+    display: flex;
+    align-items: center;
+  }
+
+  .tree-item__indentation {
+    display: block;
+    width: 1em;
+    flex-shrink: 0;
+  }
+
+  .tree-item__expand-button {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    box-sizing: content-box;
+    color: #C7CED4;
+    padding: 0.5rem;
+    width: 1rem;
+    height: 1rem;
+    flex-shrink: 0;
+    cursor: pointer;
+  }
+
+  .tree-item__expand-button {
+    transition: 250ms rotate ease;
+  }
+
+  .tree-item--expanded .tree-item__expand-button {
+    rotate: 90deg;
+  }
+
+  .tree-item--expanded.tree-item--rtl .tree-item__expand-button {
+    rotate: -90deg;
+  }
+
+  .tree-item--expanded slot[name='expand-icon'],
+  .tree-item:not(.tree-item--expanded) slot[name='collapse-icon'] {
+    display: none;
+  }
+
+  .tree-item:not(.tree-item--has-expand-button) .tree-item__expand-icon-slot {
+    display: none;
+  }
+
+  .tree-item__expand-button--visible {
+    cursor: pointer;
+  }
+
+  .tree-item__item {
+    display: flex;
+    align-items: center;
+    border-inline-start: solid 3px transparent;
+  }
+
+  .tree-item--disabled .tree-item__item {
+    opacity: 0.5;
+    outline: none;
+    cursor: not-allowed;
+  }
+
+  :host(:focus-visible) .tree-item__item {
+    outline: solid 3px #C7CED4;
+    outline-offset: 1px;
+    z-index: 2;
+  }
+
+  :host(:not([aria-disabled='true'])) .tree-item--selected .tree-item__item {
+    background-color: #eaecf0;
+    border-inline-start-color: #035da6;
+  }
+
+  :host(:not([aria-disabled='true'])) .tree-item__expand-button {
+    color: #777D82;
+  }
+
+  .tree-item__label {
+    display: flex;
+    align-items: center;
+    transition: 150ms color;
+  }
+
+  .tree-item__children {
+    display: block;
+    font-size: calc(1em + var(--indent-size, 1rem));
+  }
+
+  /* Indentation lines */
+  .tree-item__children {
+    position: relative;
+  }
+
+  .tree-item__children::before {
+    content: '';
+    position: absolute;
+    top: var(--indent-guide-offset);
+    bottom: var(--indent-guide-offset);
+    left: calc(1em - (var(--indent-guide-width) / 2) - 1px);
+    border-inline-end: var(--indent-guide-width) var(--indent-guide-style) var(--indent-guide-color);
+    z-index: 1;
+  }
+
+  .tree-item--rtl .tree-item__children::before {
+    left: auto;
+    right: 1em;
+  }
+
+  @media (forced-colors: active) {
+    :host(:not([aria-disabled='true'])) .tree-item--selected .tree-item__item {
+      outline: dashed 1px SelectedItem;
+    }
+  }
+`;
+
+export default [styles];