@tylertech/forge 3.12.0 → 3.13.0

package/esm/tree/tree-utils.js

@@ -0,0 +1,315 @@
+/**
+ * @license
+ * Copyright Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+/**
+ * A symbol property to represent the indeterminate state of a tree item.
+ */
+export const indeterminate = Symbol('indeterminate');
+//
+// Identity
+//
+/**
+ * Checks if the given element is a tree component.
+ *
+ * @param el - The element to check.
+ * @returns True if the element is a tree component, false otherwise.
+ */
+export function isTree(el) {
+    return el.tagName.toLowerCase() === 'forge-tree';
+}
+/**
+ * Checks if an element is a tree item component.
+ *
+ * @param el - The element to check.
+ * @returns True if the element is a tree item component, false otherwise.
+ */
+export function isTreeItem(el) {
+    return el.tagName.toLowerCase() === 'forge-tree-item';
+}
+//
+// Events
+//
+/**
+ * Returns whether an event originates from within a tree item.
+ *
+ * @param evt An event dispatched from a tree item.
+ * @returns Whether the event includes a tree item.
+ */
+export function getTreeItemFromEvent(evt) {
+    return evt.target.closest('forge-tree-item');
+}
+/**
+ * Gets all tree item components in an event path.
+ *
+ * @param evt An event dispatched from a tree item.
+ * @returns The dispatching tree item and all tree item ancestors.
+ */
+export function getTreeItemsInEventPath(evt) {
+    const path = evt.composedPath();
+    return path.filter((el) => el instanceof HTMLElement && isTreeItem(el));
+}
+/**
+ * Returns whether an event includes a tree item header.
+ *
+ * @param evt An event dispatched from a tree item.
+ * @returns Whether the event includes a header element within a tree item.
+ */
+export function eventPathIncludesTreeItemHeader(evt) {
+    const path = evt.composedPath();
+    const treeItemIndex = path.findIndex((el) => el instanceof HTMLElement && isTreeItem(el));
+    const headerIndex = path.findIndex((el) => el instanceof HTMLElement && el.matches('.header'));
+    return treeItemIndex >= 0 && headerIndex >= 0 && headerIndex < treeItemIndex;
+}
+/**
+ * Returns whether an event includes a tree item expand icon.
+ *
+ * @param evt An event dispatched from a tree item.
+ * @returns Whether the event includes an expand icon element within a tree item.
+ */
+export function eventPathIncludesTreeItemExpandIcon(evt) {
+    const path = evt.composedPath();
+    const treeItemIndex = path.findIndex((el) => el instanceof HTMLElement && isTreeItem(el));
+    const expandIconIndex = path.findIndex((el) => el instanceof HTMLElement && el.matches('.expand-icon'));
+    return treeItemIndex >= 0 && expandIconIndex >= 0 && expandIconIndex < treeItemIndex;
+}
+/**
+ * Gets the target tree item component from an event.
+ *
+ * @param evt An event dispatched from the target item.
+ * @returns The tree item component or null if not found.
+ */
+export function getTreeItemTarget(evt) {
+    const target = evt.target;
+    return target.closest('forge-tree-item');
+}
+//
+// DOM
+//
+/**
+ * Returns the level of the given tree item component.
+ * The level represents the depth of the item in the tree hierarchy.
+ *
+ * @param el - The tree item component.
+ * @returns The level of the tree item component.
+ */
+export function getLevel(el) {
+    let level = 0;
+    let parent = getParentItem(el);
+    while (parent) {
+        level++;
+        parent = getParentItem(parent);
+    }
+    return level;
+}
+/**
+ * Returns the parent tree component of the given tree item component.
+ *
+ * @param el - The tree item component.
+ * @returns The parent tree component or null if not found.
+ */
+export function getParentTree(el) {
+    return el.closest('forge-tree');
+}
+/**
+ * Retrieves the parent item of a given tree item component.
+ *
+ * @param el - The tree item component for which to find the parent item.
+ * @returns The parent item of the given tree item component, or `null` if the parent item is not found.
+ */
+export function getParentItem(el) {
+    if (!el.parentElement) {
+        return null;
+    }
+    return isTreeItem(el.parentElement) ? el.parentElement : null;
+}
+/**
+ * Retrieves the child items of a tree component or tree item component.
+ *
+ * @param el The tree component or tree item component.
+ * @param flatten - If `true`, the function will return all child items recursively.
+ * @returns An array of child tree item components.
+ */
+export function getChildItems(el, flatten = false) {
+    if (!flatten) {
+        return Array.from(el.children).filter(child => isTreeItem(child));
+    }
+    return Array.from(el.querySelectorAll('forge-tree-item'));
+}
+/**
+ * Returns the first child item of a tree component or tree item component.
+ *
+ * @param el - The tree component or tree item component.
+ * @returns The first child item if found, or `null` if no child item exists.
+ */
+export function getFirstChildItem(el) {
+    return Array.from(el.children).find(child => isTreeItem(child)) ?? null;
+}
+/**
+ * Returns the last child item of a tree component or tree item component.
+ *
+ * @param el - The tree component or tree item component.
+ * @returns The last child item, or `null` if there are no child items.
+ */
+export function getLastChildItem(el) {
+    // TODO: use `findLast()`
+    const children = Array.from(el.children).filter(child => isTreeItem(child));
+    return children[children.length - 1] ?? null;
+}
+/**
+ * Retrieves the sibling items of a given tree item.
+ *
+ * @param el - The tree item for which to retrieve the sibling items.
+ * @param includeSelf - Optional parameter to include the given tree item itself in the result.
+ * @returns An array of sibling tree items.
+ */
+export function getSiblingItems(el, includeSelf = false) {
+    const parent = getParentItem(el) ?? getParentTree(el);
+    return parent ? getChildItems(parent).filter(item => includeSelf || item !== el) : [];
+}
+/**
+ * Retrieves the next tree item component in the tree hierarchy.
+ *
+ * @param el - The current tree item component.
+ * @returns The next tree item component, or `null` if there is no next item.
+ */
+export function getNextItem(el, includeChildren = true) {
+    // If the item is open and has children, return the first child
+    if (includeChildren && el.open && !!getFirstChildItem(el)) {
+        return getFirstChildItem(el);
+    }
+    // Next search for the next tree item sibling
+    let nextElement = el.nextElementSibling;
+    while (nextElement && !isTreeItem(nextElement)) {
+        nextElement = nextElement.nextElementSibling;
+    }
+    if (nextElement) {
+        return nextElement;
+    }
+    // Repeat the process on the parent item until the next item is found
+    const parentItem = getParentItem(el);
+    if (!parentItem) {
+        return null;
+    }
+    return getNextItem(parentItem, false);
+}
+/**
+ * Retrieves the previous sibling tree item component of the given element.
+ * If there are no previous sibling items, it returns the parent item.
+ *
+ * @param el - The current tree item component.
+ * @returns The previous sibling tree item component or the parent item if there are no previous siblings.
+ */
+export function getPreviousItem(el) {
+    // Get the previous sibling item
+    let previousElement = el.previousElementSibling;
+    while (previousElement && !isTreeItem(previousElement)) {
+        previousElement = previousElement.previousElementSibling;
+    }
+    // There's no previous sibling, return the parent item or null
+    if (!previousElement) {
+        return getParentItem(el);
+    }
+    // If the previous sibling is closed or a leaf, return it
+    if (!previousElement.open || previousElement.leaf) {
+        return previousElement;
+    }
+    // If it's open, recursively check the last child item until we find a closed or leaf item
+    let lastChild = getLastChildItem(previousElement);
+    while (lastChild && lastChild.open) {
+        lastChild = getLastChildItem(lastChild);
+    }
+    return lastChild;
+}
+/**
+ * Searches for an item in a tree based on a query string, starting from the position of a given item and wrapping around the
+ * beginning of the tree if necessary.
+ *
+ * @param from The starting item to search from.
+ * @param query The query string to search for.
+ * @returns The matching item if found, otherwise null.
+ */
+export function searchItems(from, query) {
+    // Check if the item matches the query
+    const matchesQuery = (item) => item.textContent?.trim().toLowerCase().startsWith(query) ?? false;
+    // Recursively search the children of an item
+    const searchChildren = (item) => {
+        const children = getChildItems(item);
+        for (const child of children) {
+            if (matchesQuery(child)) {
+                return child;
+            }
+            if (!child.open) {
+                continue;
+            }
+            result = searchChildren(child);
+            if (result) {
+                return result;
+            }
+        }
+        return null;
+    };
+    // Search the siblings of an item and their children
+    const searchSiblings = (item, skipFirst = true) => {
+        const siblings = getSiblingItems(item, true);
+        const startIndex = siblings.indexOf(item) + (skipFirst ? 1 : 0);
+        for (let i = startIndex; i < siblings.length; i++) {
+            if (matchesQuery(siblings[i])) {
+                return siblings[i];
+            }
+            if (!siblings[i].open) {
+                continue;
+            }
+            result = searchChildren(siblings[i]);
+            if (result) {
+                return result;
+            }
+        }
+        return null;
+    };
+    query = query.toLowerCase();
+    let result = null;
+    let current = from;
+    let didSearchStart = false;
+    while (!result && current) {
+        result = searchSiblings(current, didSearchStart);
+        if (!result) {
+            didSearchStart = true;
+            current = getParentItem(current);
+        }
+    }
+    if (result) {
+        return result;
+    }
+    // All of the tree after the starting item has been searched, now start from the beginning
+    // TODO: stop the search if it wraps around to the starting point
+    const tree = getParentTree(from);
+    if (!tree) {
+        return null;
+    }
+    current = getFirstChildItem(tree);
+    if (!current) {
+        return null;
+    }
+    return searchSiblings(current, false);
+}
+//
+// State
+//
+/**
+ * Checks if an item in a tree is indeterminate.
+ *
+ * @param el - The tree item component to check.
+ * @returns True if any child items are indeterminate or if the selected states of the child items are not all the same, false otherwise.
+ */
+export function isIndeterminate(el) {
+    return getChildItems(el).some((child, _, children) => child.indeterminate || child.selected !== children[0].selected);
+}
+/**
+ * Closes all descendant items of a tree or tree item component.
+ * @param el The tree or tree item component to close the descendants of.
+ */
+export function closeDescendants(el) {
+    getChildItems(el, true).forEach(item => (item.open = false));
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tylertech/forge",
   "description": "Tyler Forge™ Web Components library",
-  "version": "3.12.0",
+  "version": "3.13.0",
   "author": "Tyler Technologies, Inc.",
   "license": "Apache-2.0",
   "repository": {
@@ -14,6 +14,7 @@
   "sideEffects": false,
   "dependencies": {
     "@floating-ui/dom": "^1.7.4",
+    "@lit/context": "^1.1.3",
     "@tylertech/forge-core": "^3.2.1",
     "@tylertech/tyler-icons": "^2.0.4",
     "imask": "^7.6.1",

package/sass/core/styles/tokens/tree/tree/_tokens.scss

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+@use 'sass:map';
+@use '../../../animation';
+@use '../../../shape';
+@use '../../../spacing';
+@use '../../../theme';
+@use '../../../utils';
+
+$tokens: (
+  background: utils.module-val(tree, background, theme.variable(primary-container)),
+  color: utils.module-val(tree, color, theme.variable(on-primary-container)),
+  transition-duration: utils.module-val(tree, transition-duration, animation.variable(duration-short4)),
+  transition-timing: utils.module-val(tree, transition-timing, animation.variable(easing-standard)),
+  shape: utils.module-val(tree, shape, shape.variable(medium)),
+  padding: utils.module-val(tree, padding, spacing.variable(medium))
+) !default;
+
+@function get($key) {
+  @return map.get($tokens, $key);
+}

package/sass/core/styles/tokens/tree/tree-item/_tokens.scss

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+@use 'sass:map';
+@use '../../../animation';
+@use '../../../border';
+@use '../../../shape';
+@use '../../../spacing';
+@use '../../../theme';
+@use '../../../utils';
+
+$tokens: (
+  // Color
+  selected-background: utils.module-val(tree-item, selected-background, theme.variable(primary-container-low)),
+  // Size and shape
+  min-block-size: utils.module-val(tree-item, min-block-size, spacing.variable(xlarge)),
+  shape: utils.module-val(tree-item, shape, shape.variable(medium)),
+  expand-icon-inline-size: utils.module-val(tree-item, expand-icon-inline-size, spacing.variable(large)),
+  // Spacing
+  padding-inline: utils.module-val(tree-item, padding-inline, spacing.variable(xxsmall)),
+  padding-inline-start: utils.module-ref(tree-item, padding-inline-start, padding-inline),
+  padding-inline-end: utils.module-ref(tree-item, padding-inline-end, padding-inline),
+  gap: utils.module-val(tree-item, gap, spacing.variable(xxxsmall)),
+  header-inline-gap: utils.module-val(tree-item, header-inline-gap, spacing.variable(xsmall)),
+  indent-size: utils.module-val(tree-item, indent-size, spacing.variable(medium)),
+  // Indent lines
+  indent-line-style: utils.module-val(tree-item, indent-line-style, solid),
+  indent-line-width: utils.module-val(tree-item, indent-line-width, border.variable(thin)),
+  indent-line-color: utils.module-val(tree-item, indent-line-color, theme.variable(outline)),
+  indent-line-offset: utils.module-val(tree-item, indent-line-offset, 11.5px),
+  // Disabled
+  disabled-opacity: utils.module-val(tree-item, disabled-opacity, theme.emphasis(medium-low))
+) !default;
+
+@function get($key) {
+  @return map.get($tokens, $key);
+}

package/sass/tree/tree/_core.scss

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+@use './token-utils' as *;
+@use '../tree-item/token-utils' as tree-item-token-utils;
+
+@forward './token-utils';
+
+@mixin host() {
+  display: block;
+}
+
+@mixin base() {
+  @include tree-item-token-utils.override(check-display, none, value);
+  @include tree-item-token-utils.override(indent-line-display, none, value);
+
+  display: flex;
+  flex-direction: column;
+  gap: #{tree-item-token-utils.token(gap)};
+}
+
+@mixin multiple {
+  @include tree-item-token-utils.override(check-display, block, value);
+  --forge-tree-item-selected-background: transparent;
+}
+
+@mixin with-indent-lines() {
+  @include tree-item-token-utils.override(indent-line-display, block, value);
+}

package/sass/tree/tree/_token-utils.scss

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+@use '../../core/styles/tokens/tree/tree/tokens';
+@use '../../core/styles/tokens/token-utils';
+
+$_module: tree;
+$_tokens: tokens.$tokens;
+
+@mixin provide-theme($theme) {
+  @include token-utils.provide-theme($_module, $_tokens, $theme);
+}
+
+@function token($name, $type: token) {
+  @return token-utils.token($_module, $_tokens, $name, $type);
+}
+
+@function declare($token) {
+  @return token-utils.declare($_module, $token);
+}
+
+@mixin override($token, $token-or-value, $type: token) {
+  @include token-utils.override($_module, $_tokens, $token, $token-or-value, $type);
+}
+
+@mixin tokens($includes: null, $excludes: null) {
+  @include token-utils.tokens($_module, $_tokens, $includes, $excludes);
+}

package/sass/tree/tree/index.scss

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+@forward './core';

package/sass/tree/tree/tree.scss

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * Copyright Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+@use './core';
+@use '../tree-item/token-utils' as tree-item-token-utils;
+
+//
+// Host
+//
+
+:host {
+  @include core.host;
+}
+
+//
+// Base
+//
+
+.forge-tree {
+  @include core.tokens;
+  @include tree-item-token-utils.tokens(
+    $includes: (
+      gap
+    )
+  );
+}
+
+.forge-tree {
+  @include core.base;
+
+  &.indent-lines {
+    @include core.with-indent-lines;
+  }
+
+  &.multiple {
+    @include core.multiple;
+  }
+
+  .icons {
+    display: none;
+  }
+}

package/sass/tree/tree-item/_core.scss

@@ -0,0 +1,121 @@
+/**
+ * @license
+ * Copyright Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+@use './token-utils' as *;
+@use '../../core/styles/typography';
+
+@forward './token-utils';
+
+@mixin host {
+  display: block;
+  outline: none;
+}
+
+@mixin base {
+  @include override(checkbox-color, var(--forge-theme-text-low), value);
+}
+
+@mixin header {
+  @include typography.style(body2);
+
+  display: flex;
+  align-items: center;
+  gap: #{token(header-inline-gap)};
+  position: relative;
+
+  border-radius: #{token(shape)};
+  min-block-size: #{token(min-block-size)};
+  padding-inline-start: calc(#{token(indent-size)} * #{token(level, custom)} + #{token(padding-inline-start)});
+  padding-inline-end: #{token(padding-inline-end)};
+}
+
+@mixin children-header-footer {
+  position: relative;
+
+  padding-inline-start: calc(
+    #{token(indent-size)} * (#{token(level, custom)} + 1) + #{token(padding-inline-start)} + #{token(expand-icon-inline-size)} + #{token(header-inline-gap)} * 2
+  );
+  padding-inline-end: calc(#{token(padding-inline-end)} + #{token(header-inline-gap)});
+}
+
+@mixin interactive-header {
+  cursor: pointer;
+}
+
+@mixin content {
+  overflow: hidden;
+  margin-inline-end: auto;
+
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+@mixin expand-icon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  position: relative;
+
+  border-radius: #{token(shape)};
+  inline-size: #{token(expand-icon-inline-size)};
+  min-block-size: #{token(min-block-size)};
+}
+
+@mixin disabled-expand-icon {
+  opacity: #{token(disabled-opacity)};
+}
+
+@mixin leaf-spacer {
+  inline-size: #{token(expand-icon-inline-size)};
+}
+
+@mixin checkbox {
+  --forge-icon-color: #{token(checkbox-color, custom)};
+
+  display: #{token(check-display, custom)};
+}
+
+@mixin selected {
+  @include override(checkbox-color, var(--forge-theme-tertiary), value);
+
+  background: #{token(selected-background)};
+}
+
+@mixin indeterminate {
+  @include override(checkbox-color, var(--forge-theme-tertiary), value);
+}
+
+@mixin children {
+  display: flex;
+  flex-direction: column;
+  gap: #{token(gap)};
+  position: relative;
+
+  margin-block-start: #{token(gap)};
+}
+
+@mixin indent-line {
+  display: #{token(indent-line-display, custom)};
+  position: absolute;
+  left: calc(#{token(indent-size)} * #{token(level, custom)} + #{token(indent-line-offset)} + #{token(padding-inline-start)});
+
+  block-size: 100%;
+  inline-size: #{token(indent-line-width)};
+  border-inline-start-style: #{token(indent-line-style)};
+  border-inline-start-width: #{token(indent-line-width)};
+  border-inline-start-color: #{token(indent-line-color)};
+  pointer-events: none;
+
+  content: '';
+}
+
+// Use this in conjunction with disabled-header to apply the pointer only to the expand icon
+@mixin enabled-expand-icon {
+  cursor: pointer;
+}
+
+@mixin disabled-header-content {
+  opacity: #{token(disabled-opacity)};
+}

package/sass/tree/tree-item/_token-utils.scss

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+@use '../../core/styles/tokens/tree/tree-item/tokens';
+@use '../../core/styles/tokens/token-utils';
+
+$_module: tree-item;
+$_tokens: tokens.$tokens;
+
+@mixin provide-theme($theme) {
+  @include token-utils.provide-theme($_module, $_tokens, $theme);
+}
+
+@function token($name, $type: token) {
+  @return token-utils.token($_module, $_tokens, $name, $type);
+}
+
+@function declare($token) {
+  @return token-utils.declare($_module, $token);
+}
+
+@mixin override($token, $token-or-value, $type: token) {
+  @include token-utils.override($_module, $_tokens, $token, $token-or-value, $type);
+}
+
+@mixin tokens($includes: null, $excludes: null) {
+  @include token-utils.tokens($_module, $_tokens, $includes, $excludes);
+}

package/sass/tree/tree-item/index.scss

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+@forward './core';