symbols

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 properties and methods in the component's public API. They also help avoid unintentional name collisions, as a component developer must specifically import the symbols 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 symbols.template:

import * as template from 'elix/src/template.js'
import * as symbols from 'elix/src/symbols.js';
import ShadowTemplateMixin from 'elix/src/ShadowTemplateMixin.js';

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

The above use of symbols.template 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.

While this project generally uses Symbol objects to hide component internals, Elix does make some exceptions for methods or properties that are very helpful to have handy during debugging. E.g., ReactiveMixin exposes its setState method publicly, even though invoking that method from outside a component is generally bad practice. The mixin exposes setState because it's very useful to have access to that in a debug console.

API

canGoLeft property

Symbol for the canGoLeft property.

A component can implement this property to indicate that the user is currently able to move to the left.

Type: boolean

canGoRight property

Symbol for the canGoRight property.

A component can implement this property to indicate that the user is currently able to move to the right.

Type: boolean

click() method

Symbol for the click method.

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

contentSlot property

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.

Type: HTMLSlotElement

defaultFocus constant

Symbol for the defaultFocus property.

This is used by the defaultFocus utility to determine the default focus target for an element.

elementsWithTransitions constant

Symbol for the elementsWithTransitions property.

TransitionEffectMixin inspects this property to determine which element(s) have CSS transitions applied to them for visual effects.

getItemText() method

Symbol for the getItemText method.

This method can be applied to an item to return its text. KeyboardPrefixSelectionMixin 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.

Returns: string the text of the item

goDown() method

Symbol for the goDown method.

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

goEnd() method

Symbol for the goEnd method.

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

goLeft() method

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.

goRight() method

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.

goStart() method

Symbol for the goStart method.

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

goUp() method

Symbol for the goUp method.

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

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.

keydown() method

Symbol for the keydown method.

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

An implementation of symbols.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 symbols.keydown is that the last mixin applied wins. That is, if an implementation of symbols.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.

mouseenter() method

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.

mouseleave() method

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.

raiseChangeEvents property

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[symbols.raiseChangeEvents] = true;
  // Do work here, possibly setting properties, like:
  this.foo = 'Hello';
  this[symbols.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[symbols.raiseChangeEvents]) {
    export const event = new CustomEvent('foo-changed');
    this.dispatchEvent(event);
  }
}

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

Type: boolean

render() method

Symbol for an internal render method.

ReactiveMixin has a public render method that can be invoked to force the component to render. That public method internally invokes an symbols.render method, which a component can implement to actually render itself.

You can implement a symbols.render method if necessary, but the most common way for Elix components to render themselves is to use RenderUpdatesMixin, ShadowTemplateMixin, and/or ContentItemsMixin, all of which provide a symbols.render method.

rendering property

Symbol for the rendering property.

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

Type: boolean

rightToLeft property

Symbol for the rightToLeft property.

LanguageDirectionMixin sets this to true if the if the element is rendered right-to-left (the element has or inherits a dir attribute with the value rtl).

This property wraps the internal state member state.languageDirection, and is true if that member equals the string "rtl".

Type: boolean

roles constant

Symbol for the roles property.

A role is an element in a component template that can be replaced by an alternative element. The element filling the role can be identified an element tag (e.g., "div"), a custom element class constructor (e.g., SeamlessButton), or a document fragment.

The roles property is a dictionary mapping a role name to the corresponding element that should be instantiated to fill that role.

scrollTarget property

Symbol for the scrollTarget property.

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

Type: Element

startEffect() method

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.

swipeDown() method

Symbol for the swipeDown method.

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

swipeLeft() method

Symbol for the swipeLeft method.

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

swipeRight() method

Symbol for the swipeLeft method.

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

swipeTarget property

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.

Type: HTMLElement

swipeUp() method

Symbol for the swipeUp method.

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

template property

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.

Type: HTMLTemplateElement