utilities

Miscellaneous utility functions for web components

API

applyChildNodes(element, childNodes) static method

Sets the element's childNodes to the given set of nodes.

This adds or removes the element's childNodes as necessary to match the nodes indicated in the childNodes parameter.

Parameters:

  • element: Nodethe element to update
  • childNodes: NodeList|Array.the set of nodes to apply

closestFocusableAncestor(node) static method

Return the closest focusable ancestor in the composed tree. If no focusable ancestor is found, returns null.

Parameters:

  • node: Node

Returns: HTMLElementnull

composedAncestors(node) static method

Return the ancestors of the given node in the composed tree.

In the composed tree, the ancestor of a node assigned to a slot is that slot, not the node's DOM ancestor. The ancestor of a shadow root is its host.

Parameters:

  • node: Node

Returns: Iterable.

deepContains(container, target) static method

Returns true if the first node contains the second, even if the second node is in a shadow tree.

The standard Node.contains() function does not account for Shadow DOM, and returns false if the supplied target node is sitting inside a shadow tree within the container.

Parameters:

  • container: NodeThe container to search within.
  • target: NodeThe node that may be inside the container.

Returns: boolean - True if the container contains the target node.

ensureId(element) static method

If the given element already has an ID, return it. If not, generate a previously unused ID and return that.

Parameters:

  • element: Element

Returns: string

firstFocusableElement(root) static method

Return the first focusable element in the composed tree below the given root. The composed tree includes nodes assigned to slots.

This heuristic considers only the document order of the elements below the root and whether a given element is focusable. It currently does not respect the tab sort order defined by tabindex values greater than zero.

Parameters:

  • root: Nodethe root of the tree in which to search

Returns: HTMLElementnull - the first focusable element, or null if none was found

forwardFocus(origin, target) static method

Trap any mousedown events on the origin element and prevent the default behavior from setting the focus on that element. Instead, put the focus on the target element (or, if the target is not focusable, on the target's closest focusable ancestor).

If this method is called again with the same origin element, the old forwarding is overridden, and focus will now go to the new target element.

If the target parameter is null, focus handling will be removed from the indicated origin.

Parameters:

  • origin: HTMLElement
  • target: HTMLElement|null

indexOfItemContainingTarget(items, target) static method

Search a list element for the item that contains the specified target.

When dealing with UI events (e.g., mouse clicks) that may occur in subelements inside a list item, you can use this routine to obtain the containing list item.

Parameters:

  • items: NodeList|Array.A list element containing a set of items
  • target: NodeA target element that may or may not be an item in the list.

Returns: number - The index of the list child that is or contains the indicated target node. Returns -1 if not found.

ownEvent(node, event) static method

Return true if the event came from within the node (or from the node itself); false otherwise.

Parameters:

  • node: NodeThe node to consider in relation to the event
  • event: EventThe event which may have been raised within/by the node

Returns: boolean - True if the event was raised within or by the node

selfAndComposedAncestors(node) static method

Returns the set that includes the given node and all of its ancestors in the composed tree. See composedAncestors for details on the latter.

Parameters:

  • node: Node

Returns: Iterable.