internal

Collection of shared Symbol objects for internal component communication

Overview

The shared Symbol objects in this module let mixins and a component internally communicate without exposing these internal properties and methods in the component's public API. They also help avoid unintentional name collisions, as a component developer must specifically import the internal module and reference one of its symbols.

To use these Symbol objects in your own component, include this module and then create a property or method whose key is the desired Symbol. E.g., ShadowTemplateMixin expects a component to define a property called template:

import { template } from 'elix/src/core/internal.js';
import { templateFrom } from 'elix/src/core/htmlLiterals.js'
import ShadowTemplateMixin from 'elix/src/core/ShadowTemplateMixin.js';

class MyElement extends ShadowTemplateMixin(HTMLElement) {
  [template]() {
    return templateFrom.html`Hello, <em>world</em>.`;
  }
}

The above use of the internal template member lets the mixin find the component's template in a way that will not pollute the component's public API or interfere with other component logic. For example, if for some reason the component wants to define a separate property with the plain string name, "template", it can do so without affecting the above property setter.

API

[internal.applyElementData] constant

Symbol for the applyElementData method.

Components that want to be able to apply data from one element to another can support this method. E.g., DropdownList uses this to apply data from the selected item to the component's value part.

[internal.checkSize] constant

Symbol for the checkSize method.

If defined, this method will be invoked by ResizeMixin when an element's size may have changed. The default implementation of this method compares the element's current clientHeight and clientWidth properties against the last known values of those properties (saved in state.clienHeight and state.clientWidth).

Components should override this method if they contain elements that may need to know about size changes as well. For example, when an Overlay mixin opens, it invokes this method on any content elements that define it. This gives the contents a chance to resize in response to being displayed.

[internal.closestAvailableItemIndex] constant

Symbol for the closestAvailableItemIndex method.

This method is defined by ItemsCursorMixin. You can call this if you want to find an item at a particular location, but may need to account for the fact that the item at that position is not available, and would like to find the closest item that is available.

[internal.contentSlot] constant

Symbol for the contentSlot property.

SlotContentMixin uses this to identify which slot element in the component's shadow tree that holds the component's content. By default, this is the first slot element with no "name" attribute. You can override this to return a different slot.

[internal.defaultState] constant

The default state for this element.

[internal.defaultTabIndex] constant

Symbol for the defaultTabIndex property.

KeyboardMixin uses this if it is unable to successfully parse a string tabindex attribute.

[internal.delegatesFocus] constant

Symbol for the delegatesFocus property.

DelegatesFocusMixin defines this property, returning true to indicate that the focus is being delegated, even in browsers that don't support that natively. Mixins like KeyboardMixin use this to accommodate focus delegation.

[internal.effectEndTarget] constant

Symbol for the effectEndTarget property.

TransitionEffectMixin inspects this property to determine which element's transitionend event will signal the end of a transition effect.

[internal.firstRender] constant

Symbol for the firstRender property.

ReactiveMixin sets the property to true during the element's first connectedCallback, then false in subsequent callbacks.

You can inspect this property in your own connectedCallback handler to do work like wiring up events that should only happen once.

[internal.focusTarget] constant

Symbol for the focusTarget property.

DelegatesFocusMixin defines this property as either:

  1. the element itself, in browsers that support native focus delegation or,
  2. the shadow root's first focusable element.

[internal.getItemText] constant

Symbol for the getItemText method.

This method can be applied to an item to return its text. KeyboardPrefixCursorMixin uses this to obtain the text for each item in a list, then matches keypresses again that text.

This method takes a single parameter: the HTMLElement of the item from which text should be extracted.

[internal.goDown] constant

Symbol for the goDown method.

This method is invoked when the user wants to go/navigate down.

[internal.goEnd] constant

Symbol for the goEnd method.

This method is invoked when the user wants to go/navigate to the end (e.g., of a list).

[internal.goFirst] constant

Symbol for the goFirst method.

This method is invoked when the user wants to go to the first item in a list.

[internal.goLast] constant

Symbol for the goLast method.

This method is invoked when the user wants to go to the last item in a list.

[internal.goLeft] constant

Symbol for the goLeft method.

This method is invoked when the user wants to go/navigate left. Mixins that make use of this method include KeyboardDirectionMixin and SwipeDirectionMixin.

[internal.goNext] constant

Symbol for the goNext method.

This method is invoked when the user wants to go/navigate to the next item.

[internal.goPrevious] constant

Symbol for the goPrevious method.

This method is invoked when the user wants to go/navigate to the previous item.

[internal.goRight] constant

Symbol for the goRight method.

This method is invoked when the user wants to go/navigate right. Mixins that make use of this method include KeyboardDirectionMixin and SwipeDirectionMixin.

[internal.goStart] constant

Symbol for the goStart method.

This method is invoked when the user wants to go/navigate to the start (e.g., of a list).

[internal.goToItemWithPrefix] constant

Symbol for the goToItemWithPrefix method.

This method is invoked by KeyboardPrefixCursorMixin when the user types text characters.

[internal.goUp] constant

Symbol for the goUp method.

This method is invoked when the user wants to go/navigate up.

[internal.hasDynamicTemplate] constant

Symbol for the hasDynamicTemplate property.

If your component class does not always use the same template, define a static class property getter with this symbol and have it return true. This will disable template caching for your component.

[internal.ids] constant

Symbol for the ids property.

ShadowTemplateMixin defines a shorthand function internal.ids that can be used to obtain a reference to a shadow element with a given ID.

Example: if component's template contains a shadow element <button id="foo">, you can use the reference this[ids].foo to obtain the corresponding button in the component instance's shadow tree. The ids function is simply a shorthand for getElementById, so this[ids].foo is the same as this.shadowRoot.getElementById('foo').

[internal.inputDelegate] constant

Symbol for the inputDelegate property.

DelegateInputSelectionMixin uses this property to indicate which shadow element is the input-type element to which text selection methods and properties should be delegated.

[internal.itemsDelegate] constant

Symbol for the itemsDelegate property.

A component using DelegateItemsMixin uses this property to indicate which one of its shadow elements is the one whose items property will be treated as the component's own items.

[internal.keydown] constant

Symbol for the keydown method.

This method is invoked when an element receives a keydown event.

An implementation of internal.keydown should return true if it handled the event, and false otherwise. If true is returned (the event was handled), KeyboardMixin invokes the event's preventDefault and stopPropagation methods to let the browser know the event was handled.

The convention for handling internal.keydown is that the last mixin applied wins. That is, if an implementation of internal.keydown did handle the event, it can return immediately. If it did not, it should invoke super to let implementations further up the prototype chain have their chance.

This method takes a KeyboardEvent parameter that contains the event being processed.

[internal.matchText] constant

Symbol for the matchText method.

AutoCompleteInput invokes this method when trying to find a match for a given input string against its set of texts.

[internal.mouseenter] constant

Symbol for the mouseenter method.

HoverMixin invokes this method when the user moves the mouse over a component. That mixin provides a base implementation of this method, but you can extend it to do additional work on mouseenter.

This method takes a MouseEvent parameter that contains the event being processed.

[internal.mouseleave] constant

Symbol for the mouseleave method.

HoverMixin invokes this method when the user moves off a component. That mixin provides a base implementation of this method, but you can extend it to do additional work on mouseleave.

This method takes a MouseEvent parameter that contains the event being processed.

[internal.nativeInternals] constant

Symbol for access to native HTML element internals.

[internal.raiseChangeEvents] constant

Symbol for the raiseChangeEvents property.

This property is used by mixins to determine whether they should raise property change events. The standard HTML pattern is to only raise such events in response to direct user interactions. For a detailed discussion of this point, see the Gold Standard checklist item for Propery Change Events.

The above article describes a pattern for using a flag to track whether work is being performed in response to internal component activity, and whether the component should therefore raise property change events. This raiseChangeEvents symbol is a shared flag used for that purpose by all Elix mixins and components. Sharing this flag ensures that internal activity (e.g., a UI event listener) in one mixin can signal other mixins handling affected properties to raise change events.

All UI event listeners (and other forms of internal handlers, such as timeouts and async network handlers) should set raiseChangeEvents to true at the start of the event handler, then false at the end:

this.addEventListener('click', event => {
  this[raiseChangeEvents] = true;
  // Do work here, possibly setting properties, like:
  this.foo = 'Hello';
  this[raiseChangeEvents] = false;
});

Elsewhere, property setters that raise change events should only do so it this property is true:

set foo(value) {
  // Save foo value here, do any other work.
  if (this[raiseChangeEvents]) {
    export const event = new CustomEvent('foochange');
    this.dispatchEvent(event);
  }
}

In this way, programmatic attempts to set the foo property will not trigger the foochange event, but UI interactions that update that property will cause those events to be raised.

[internal.render] constant

Symbol for the render method.

ReactiveMixin invokes this internal.render method to give the component a chance to render recent changes in component state.

[internal.renderChanges] constant

Symbol for the renderChanges method.

ReactiveMixin invokes this method in response to a setState call; you should generally not invoke this method yourself.

[internal.renderDataToElement] constant

Symbol for the renderDataToElement method.

DataItemsMixin invokes this method to render data to an element being used as an item in a list.

[internal.rendered] constant

Symbol for the rendered method.

ReactiveMixin will invoke this method after your element has completely finished rendering.

[internal.rendering] constant

Symbol for the rendering property.

ReactiveMixin sets this property to true during rendering, at other times it will be false.

[internal.scrollTarget] constant

Symbol for the scrollTarget property.

This property indicates which element in a component's shadow subtree should be scrolled. CursorInViewMixin can use this property to determine which element should be scrolled to keep the selected item in view.

[internal.setState] constant

Symbol for the setState method.

A component using ReactiveMixin can invoke this method to apply changes to the element's current state.

[internal.shadowRoot] constant

Symbol for the shadowRoot property.

This property holds a reference to an element's shadow root, like this.shadowRoot. This propery exists because this.shadowRoot is not available for components with closed shadow roots. ShadowTemplateMixin creates open shadow roots by default, but you can opt into creating closed shadow roots; see shadowRootMode.

[internal.shadowRootMode] constant

Symbol for the shadowRootMode property.

If true (the default), then ShadowTemplateMixin will create an open shadow root when the component is instantiated. Set this to false if you want to programmatically hide component internals in a closed shadow root.

[internal.startEffect] constant

Symbol for the startEffect method.

A component using TransitionEffectMixin can invoke this method to trigger the application of a named, asynchronous CSS transition effect.

This method takes a single string parameter giving the name of the effect to start.

[internal.state] constant

The element's current state.

This is managed by ReactiveMixin.

[internal.swipeDown] constant

Symbol for the swipeDown method.

The swipe mixin TouchSwipeMixin invokes this method when the user finishes a gesture to swipe down.

[internal.swipeDownComplete] constant

Symbol for the swipeDownComplete method.

SwipeCommandsMixin invokes this method after any animated transition associated with a swipe down has completed.

[internal.swipeLeft] constant

Symbol for the swipeLeft method.

The swipe mixins TouchSwipeMixin and TrackpadSwipeMixin invoke this method when the user finishes a gesture to swipe left.

[internal.swipeLeftTransitionEnd] constant

Symbol for the swipeLeftTransitionEnd method.

SwipeCommandsMixin invokes this method after any animated transition associated with a swipe left has completed.

[internal.swipeRight] constant

Symbol for the swipeRight method.

The swipe mixins TouchSwipeMixin and TrackpadSwipeMixin invoke this method when the user finishes a gesture to swipe right.

[internal.swipeRightTransitionEnd] constant

Symbol for the swipeRightTransitionEnd method.

SwipeCommandsMixin invokes this method after any animated transition associated with a swipe right has completed.

[internal.swipeStart] constant

Symbol for the swipeStart method.

TouchSwipeMixin and TrackpadSwipeMixin invoke this method when a swipe is starting, passing in the starting (x, y) client coordinate.

[internal.swipeTarget] constant

Symbol for the swipeTarget property.

By default, the swipe mixins TouchSwipeMixin and TrackpadSwipeMixin assume that the element the user is swiping the top-level element. In some cases (e.g., Drawer), the component wants to let the user swipe a shadow element. In such cases, this property should return the element that should be swiped.

The swipe target's offsetWidth is used by the mixin to calculate the state.swipeFraction member when the user drags their finger. The swipeFraction is the distance the user has dragged in the current drag operation over that offsetWidth.

[internal.swipeUp] constant

Symbol for the swipeUp method.

The swipe mixin TouchSwipeMixin invokes this method when the user finishes a gesture to swipe up.

[internal.swipeUpComplete] constant

Symbol for the swipeUpComplete method.

SwipeCommandsMixin invokes this method after any animated transition associated with a swipe up has completed.

[internal.tap] constant

Symbol for the tap method.

This method is invoked when an element receives an operation that should be interpreted as a tap. TapCursorMixin invokes this when the element receives a mousedown event, for example.

[internal.template] constant

Symbol for the template method.

ShadowTemplateMixin uses this property to obtain a component's template, which it will clone into a component's shadow root.

[internal.toggleSelectedFlag] constant

Symbol for the toggleSelectedFlag method.

ItemsMultiSelectMixin exposes this method to let other mixins like MultiSelectAPIMixin toggle the selected state of an individual item.