This release includes a handful of minor bug fixes to PopupToggleMixin (used in FilterComboBox), SpinBox (inherited by NumberSpinBox), and FormElementMixin (used by AutoSizeTextarea and other components).

One notable infrastructure change is that we migrated the scripts that project uses to generate various library files from CommonJS module format to ES modules. This necessitated adding type: "module" to the elix package.json file. We hope this doesn't cause issues for Elix users, but please file an issue if you run into problems.

This is a relatively small release, but includes the removal of some deprecated API members, so we're marking it as a major version to reflecting the potentially breaking changes for projects that have yet to update their code.

The following deprecated features have been removed:

• Old hyphenated event names (selected-index-changed) and the old template.html and standalone html template literal. For details on both of these, see the Elix 14.0.0 release notes.
• Old horizontalAlign and popupPosition properties in PopupSource.

This release also includes a number of fixes:

• Fixed regressions in ListComboBox that failed to leave the value's text selected after the popup list box was closed, or prevented the user from entering text that was not in the list.
• Various fixes in popup layout. This includes more reliable detection of cases where a left-aligned popup at the far right of the viewport will go outside the viewport bound's; in these cases, the popup should flip to right-aligned so the user can see the full popup.
• A fair amount of rework of structural styling in Overlays, including Dialog, Drawer, and Popup.

Other work:

• Adding #elixdebugpopup=true to the URL will suppress the default close-on-blur behavior in Elix popup components. This makes it much easier to inspect and debug popups in their opened state. Thanks to @klobetime for the suggestion.
• Track recent standard changes in the new CSS custom state selector for custom element states. The old syntax looked like my-button:state(selected), the new syntax is my-button:--selected. This updated standard is currently only supported in Google Chrome Canary.
• Pared back the amount of code required by the ReactiveElement base class.

A minor release:

• Rewrite of the logic used to layout popups to allow more positions, including left or right of the popup source.
• Bug fixes in TrackTextSelectionMixin so that components like AutoSizeTextarea can expose more accurate text selection properties.

Changes in this release:

• A new component called TooltipButton is intended for use as a base class for elements that produce a tooltip on focus or hover.
• A new mixin called MultiSelectValueAPIMixin defines a value property for multi-select list-like elements.
• The use of PopupToggleMixin has been moved out of PopupButton, since there exist popup buttons (notably TooltipSource, above) that don't want a popup toggle. The components that want the toggle are currently the Plain PopupButton variants and ComboBox.
• Like wise, the application of the aria-expanded attribute has been moved from PopupButton to the subclasses that want that, including MenuButton and DropdownList.
• PopupSource takes greater care to avoid affecting the page layout during the phase in which it is measuring the size of the popup before displaying it.
• All component property setters that accept a string defensively coerce the supplied value to a string before storing it or working with it. This replicates the behavior of string-valued properties in native HTML elements.
• ShadowTemplateMixin is now easier to use on its own. Normally ShadowTemplateMixin is picked up by a component by inheriting from ReactiveElement, but there are situations where it is nice to be able to use the mixin on its own, and that's now a little easier.

We've also added a locally-runable demo browser at /demos/index.html. You can load that page in any static web server to browse the demos. For the time being, you can also see that demo browser at https://component.kitchen/demos/, although that location may change.

The main focus of this release is on creating more accessible components, particularly in the DropdownList, ComboBox, and MenuButton families. This is rather challenging — ARIA makes it difficult to construct an accessible representation of a component that contains interesting information in both the light DOM and Shadow DOM.

• DropdownList and ComboBox now expose their list contents in a more ARIA-compliant way to accessibility technologies such as screen readers.
• DelegateInputLabelMixin has been extensively reworked to support a fuller range of ARIA labeling techniques.
• DropdownList now inherits from PopupSource instead of MenuButton so that it can provide different ARIA semantics.
• AutoCompleteInput has been reworked to implement ARIA 1.2 combobox semantics. This enables ComboBox variants that use AutoCompleteInput to provide proper accessibility.
• The new PopupDragSelectMixin handles the mouse interactions necessary to let users efficiently select an item from a dropdown-style element in a single mouse operation. This functionality had previously been part of MenuButton, but has been factored into a mixin so that components in the ComboBox family can also take advantage of it.
• The new PopupListMixin is designed for components like MenuButton, DropdownList, and ListComboBox that track their own list item cursor, and want to keep that in sync with the item cursor of an inner list shown in a popup.
• The new OptionList component is intended to present a collection of Option elements in components like DropdownList. Among other things, it does not assume that the selected item and the current item are the same. It also avoids the special focus behavior of Menu.
• ComboBox interactions have been improved to better match the behavior of well-designed combo boxes in applications like Microsoft Office and Google Docs. For example, pressing the Esc key while a combo box is open will now restore the previously-entered value instead of simply closing the combo box.
• ListComboBox exposes a new selectedItemValue property that returns the value attribute of the currently-selected item if one exists. For comparison, its value property is used to retrieve the current text in the combo box's input, which could be free-form text entered by the user.
• Fixed a bug in which a ComboBox popup could appear underneath the input of another nearby ComboBox.

This is a major release.

Event renaming

All of the custom events raised by Elix components are being renamed to better align with the precedent set by native HTML event names.

Until now, Elix event names have generally been in the past tense and include hyphens: e.g., when the selectedIndex property changes, a list-like component would raise a selected-index-changed event. The use of the past tense indicated that the given condition had already happened (inspecting the selectedIndex property in the event handler would show that the property value had already changed). The use of hyphens was intended to make the event names easier to read.

However, the list of native DOM events clearly show a general preference for present tense and names without hyphens (even if that results in a hard-to-read mash of words like vrdisplaypresentchange).

While we may not like the web's DOM event naming strategy, it's also our goal to create custom elements that feel native to the web. With that in mind, all Elix custom event names are changing to use the present tense and to omit hyphens:

Old event name → New event name

• closed → close
• current-changed → currentchange
• current-index-changed → currentindexchange
• date-changed → datechange
• disabled-changed → disabledchange
• effect-phase-changed → effectphasechange
• focus-visible-changed → focusvisiblechange
• items-changed → itemschange
• opened → open
• opened-changed → openedchange
• refreshing-changed → refreshingchange
• selected-changed → selectedchange
• selected-flags-changed → selecteditemflagschange (note addition of "item")
• selected-index-changed → selectedindexchange
• selection-effect-finished → selectioneffectend (note "end")
• value-changed → input (for consistency with native textarea)

The new event names are now available in Elix 14.0. The old event names are still available, but will be removed in a subsequent release. Normally we try to provide console warnings when you try to invoke a deprecated feature, but there's no clean way for Elix to know if you are using a deprecated event name.

We strongly recommend that you search for all occurrences of addEventListener and review whether you are listening to any of the old event names listed above. You might try searching your code with a regex like this one, which looks for hyphens in event names passed to addEventListener:

addEventListener\(\s*['"].+-.+['"]

New names for JavaScript template literals

Elix provides two JavaScript string template literals to make it easier to construct an HTMLTemplateElement or a DocumentFragment. These two literals are moving to a new file, elix/src/core/htmlLiterals.js. The literals are also getting new names:

import { fragmentFrom, templateFrom } from "elix/src/core/htmlLiterals.js";

templateFrom.html`<div>Hello</div>`; // returns an HTMLTemplateElement
fragmentFrom.html`<div>Hello</div>`; // returns a DocumentFragment

Previously, both of these literals were just called html, which made it slightly confusing to use both of them in the same file. The functions now hang off of two distinct objects, templateFrom and fragmentFrom that can be imported from htmlLiterals.js.

• You generally use templateFrom.html inside a component's template property if the component is defining a template from scratch.
• You generally use fragmentFrom.html inside a component's template property if the component is subclassing another component, and appending fragments of content to the template it inherits from its base class.

The reason both these template literal functions are called html is that development tools like Microsoft VS Code can format the contents of a template literal called exactly html with color formatting specifically for HTML. (For VS Code users, we recommend installing the lit-html extension to see HTML properly formatted inside of an Elix JavaScript component definition.)

The old template functions are deprecated, and using them will now trigger console warnings. They will be removed in a subsequent release.

Rework of FilterListBox and FilterComboBox

The Elix FilterListBox, which shows up in FilterComboBox, previously recalculated the component's set of items as the user typed a filter. This allowed the components to easily support the use of mixins like DirectionCursorMixin to navigate the set of filtered items.

However, dynamically redefining this items collection proved to have serious downsides. Chief among them was that the filtering components would return the index of the selected item in terms of the filtered items, rather than the full, original set of items. This made it challenging for a page using these components to determine the real selected item.

Fixing this ultimately required making substantial changes in a number of mixins, especially ItemsCursorMixin.

To define a custom filter for FilterListBox or FilterComboBox, you previously would define an element method called internal.itemMatchesState. This would be invoked for each item to see if it matched the current state. That approach has been replaced with one in which a filtering component can maintain a state member called availableItemFlags. This is an array of booleans: a true value indicates that the item in the corresponding position of items is "available". In a filtering context, an available item is one that matches the filter.

While doing this work, we implemented a request to have FilterListBox ignore diacritical marks like accents for filtering purposes. Thanks to @klobetime for the suggestion.

Redefinition of value property for list-like elements

Elix components like ListBox have long exposed a value property that returned the text of the selected item. User @chisholmd filed an issue that led us to realize that it wasn't helpful to have value work so differently from the value property on the native select element.

To fix this, we've made the following breaking change to all list-like elements in Elix:

• A list's value property now returns the value attribute of the selected item. Setting this property makes the item with that value the selected item.
• A new selectedText property gets/sets the text of the selected item. That is, it provides the behavior previously delivered through the old definition of the value property.

To facilitate components that want to provide value and selectedText properties like this, we've introduced two new mixins, SelectedValueAPIMixin and SelectedTextAPIMixin.

Introduction of checkable Option component for use in DropdownList

The DropdownList component now has a companion component, Option, that can be used to represent the user's choices in the list. The Option component supports a selected state, which the PlainOption variation in the Plain design system represents with a checkmark. This allows a user to see which item in the list is currently selected.

Mixin changes

While doing the work on FilterListBox and DropdownList, we ended up reworking a number of mixins:

• Renamed CurrentItemInViewMixin → CursorInViewMixin
• Introduced CursorSelectMixin, which keeps an element's currentIndex and selectedIndex in sync. This mixin is used in components like ListBox that link the concepts of an item cursor and a selection. This mixin is not used by DropdownList, since that component separates those two concepts — when you navigate the list, the item cursor moves, but the selection is unaffected until you close the dropdown.
• Introduced DelegateCursorMixin for components like the ListComboBox family that want to delegate item cursor operations to an inner list element.

This is a major release of Elix, and includes a number of breaking changes at the mixin level. Most components should work the same as before.

Multi-selection support

This release adds includes the project's first multi-select component, MultiSelectListBox.

Adding this component required substantially refactoring the large collection of mixins which deal with selection. In a single-selection list like ListBox, the current item in the list — the one which can be navigated with the keyboard — is also implicitly the selected item. In a multi-selection list, the concepts of the current item and the selection are independent. E.g., in what Microsoft calls a "simple multi-select" list box, the user can navigate the current item and then toggle the selected state of that item by pressing the Space key.

Renaming state members and mixins

Nearly all of the Elix mixins that dealt with selection actually dealt with the current item. In order to use those mixins in multi-select components, we needed to rewrite them to manipulate or respond to the item cursor: the conceptual pointer into a set of items which indicates which item is current.

Mostly this was a matter of renaming and reorganizing things.

For the most part, names at the component level have remained the same. A number of mixins have changed names. Significantly, two commonly-reference state members have been renamed:

• selectedIndex → currentIndex
• selectedItem → currentItem

Those renames affect the state members, not the public property names. The public APIs of the Elix list-like components still expose selectedIndex and selectedItem properties and a selected-index-changed event.

If you are constructing list-like components from mixins, you can use the new ItemsCursorMixin to define currentIndex and currentItem.

The following mixins have been renamed to reflect that they now work with the item cursor instead of "selection":

• DirectionSelectionMixin → DirectionCursorMixin
• KeyboardPagedSelectionMixin → KeyboardPagedCursorMixin
• KeyboardPrefixSelectionMixin → KeyboardPrefixCursorMixin
• SelectionInViewMixin → CurrentItemInViewMixin (The mixin's scrollSelectedItemIntoView method is now called scrollCurrentItemIntoView.)
• TapSelectionMixin → TapCursorMixin
• TimerSelectionMixin → TimerCursorMixin

Multi-select lists

A new mixin, ItemsMultiSelectMixin, tracks which items in a multi-select list are selected. This defines a state member selectedFlags, which is an array of flags of the same dimensions as the items state member. If a given item is selected, the corresponding position in the selectedFlags array will be true.

Additionally, AriaListMixin has been extended to support ARIA behavior for multi-select lists.

The new MultiSelectListBox makes use of ItemsMultiSelectMixin, AriaListMixin, and all of the renamed cursor mixins described above.

A "simple multi-select" list typically represents the individual list items as labeled check boxes. Clicks on the check box portion toggle the selection state of the item; clicks on the label merely make it the current item but leave selection unaffected. The release introduces a new component called CheckListItem to address this use case.

As with all Elix base components, MultiSelectListBox and CheckListItem provide structural styling only and no aesthetic styling. The Plain reference design system contains new components PlainMultiSelectListBox and PlainCheckListItem which subclass the base components to provide basic styling.

Mixins for public APIs

Until now, Elix mixins have defined both component internals and public APIs for working with those internals. E.g., the previous SingleSelectionMixin defined a selectedIndex state member and exposed that as a public selectedIndex property and selected-index-changed event.

In the long run, it seems better to factor internals from public APIs. A generic single-selection list may want to expose a public selectedItem property, but a single-selection list focused on a specific data object like a list of users may want to expose that same concept as a public selectedUser property.

To accommodate that, we would like to eventually factor out public APIs into mixins of their own. We used the above reworking of selection mixins into item cursor mixins to also factor out public APIs:

• ItemsAPIMixin exposes a public items collection and items-changed event. Previously, these had been defined by ContentItemsMixin.
• CursorAPIMixin exposes public currentIndex and currentItem properties and a current-index-changed event. This also exposes public cursor methods: goFirst, goLast, goNext, and goPrevious.
• SingleSelectAPIMixin exposes selectedIndex and selectedItem properties and a selected-index-changed event.
• MultiSelectAPIMixin exposes public selectedFlags and selectedItems properties and a selected-flags-changed event.

The list components apply these mixins as follows:

• ListBox includes ItemsAPIMixin, CursorAPIMixin, and SingleSelectAPIMixin. The currentIndex/currentItem properties will report the same values as the corresponding selectedIndex/selectedItem properties. Among other things, this arrangement ensures that pages that previously listened for a list's selected-index-changed event will continue to work.
• MultiSelectListBox includes ItemsAPIMixin, CursorAPIMixin, and MultiSelectAPIMixin.

The responsibilities of the previous SingleSelectionMixin are now split between the new internal-focused ItemsCursorMixin and the external-focused SingleSelectAPIMixin. You can apply both those mixins to a component to replace the use of SingleSelectionMixin.

If you were previously navigating a list's selection through public "select" methods defined by SingleSelectionMixin, you will now need to use the public cursor methods defined by ItemsCursorMixin:

• selectFirst → goFirst
• selectLast→ goLast
• selectNext→ goNext
• selectPrevious go→ Previous

Removals of deprecated features

This release removes some features that had been deprecated in Elix 12.0.0.

• The old lifecycle methods componentDidMount and componentDidUpdate have been removed.
• The template.createElement and template.transmute methods no longer support an HTMLTemplateElement as a part descriptor.

See the earlier release notes for migration instructions.

This is a minor bug fix release.

• Fixes a regression with typing and selection behavior in input and textarea components.
• Fixes a regression with auto-complete behavior in FilterComboBox.

This is a minor bug fix release.

• Fixes for some focus ring issues.
• Allow a list item to define a label via internal.getItemText. The default implementation looks at the aria-label attribute, the alt attribute, and textContent, in that order.
• Prefer display: inline-block, inline-flex, or inline-grid on host unless we actually need a block-type display. The inline variations tend to be more flexible as default display values.

This is a minor release.

• DarkModeMixin now tracks live changes the user makes to their OS color scheme preference. The demo on the docs page shows a carousel that updates itself to match the light or dark color scheme when the user applies that change through system properties.

Minor release to fix a regression in calendar components.

This is a minor release of Elix.

• The new SpinBox class can be used as the basis for input elements that let the user increment/decrement a value along a continuous range.
• The specific NumberSpinBox component extends SpinBox to optimize for simple numeric values. It’s comparable to a standard <input type=“number”>.
• The new RepeatButton component can be used to create buttons that repeat an action for as long as the user holds the mouse button down. A SpinBox can use this for its up and down button parts so the user can rapidly increment/decrement a value by holding the mouse button down.
• The repeat work in RepeatButton is handled by a new RepeatMousedownMixin that can be applied to any component to give it the repeating mouse down behavior.
• In complex elements like SpinBox and ComboBox that place interactive elements next to an input element, FocusVisibleMixin can now apply a focus ring around the entire component instance. This helps the user perceive the entire instance as a single interactive unit. To accomplish this, FocusVisibleMixin does its styling work through a style element it inserts in the component’s template. If you have a component that applies FocusVisibleMixin, be sure to have your internal.template getter invoke super so FocusVisibleMixin has a chance to modify the template.
• A number of Elix components are built around an inner input element. Two new mixins, DelegateInputLabelMixin and DelegateInputSelectionMixin make it easier for such components to deliver standard input features. The former ensures that any aria-label attribute set on the outer component is delegated to the inner input; the latter delegates standard HTML text selection methods like setRangeText to the inner input.

This release introduces breaking changes.

New rendered method replaces componentDidMount/componentDidUpdate

The componentDidMount and componentDidUpdate methods have been reworked into a single method called rendered. ReactiveMixin invokes this method after your component has completed all of its rendering work in the pre-existing render method. Like render, the new rendered method receives a changed parameter indicating which state member changes triggered rendering.

In both render and rendered, you can inspect a new internal.firstRender property: if true, the component is rendering for the first time (as in the previous componentDidMount method). This is a good time to do one-time work like wiring up event handlers; in many cases you can actually now move the wiring of events into the render call, since it will only be called once. (If you prefer, it's of course fine to do event wiring in the rendered call after rendering completes.)

If internal.firstRender is false, the component is rendering for a subsequent time (as in the previous componentDidUpdate method).

Old:

class MyElement extends ReactiveElement {
  [internal.componentDidMount]() {
    super[internal.componentDidMount]();
    this.addEventListener('click', event => { ... });
  }
}

New:

class MyElement extends ReactiveElement {
  [internal.render](changed) {
    super[internal.render](changed);
    if (this[internal.firstRender]) {
      this.addEventListener('click', event => { ... });
    }
  }
}

Calling componentDidMount or componentDidUpdate in Elix 12.0 will still work, but will trigger a console warning. Those methods will be dropped in the next major release of Elix.

transmute will longer accept an HTMLTemplateElement as a part descriptor

The template.transmute function previously let you pass one of three different part descriptors: 1) a component constructor, 2) an element tag name, or 3) an HTMLTemplateElement. The last was rarely used, and twisted the meaning of "transmute". In Elix 12.0, that will now trigger a console warning. In the next major release of Elix, that will stop working; you'll only be able to pass in a constructor or tag name.

If you were passing a template to transmute, chances are that you were using it to insert elements into a larger template inherited from a base class. In general, you should be able to do that using DOM methods directly — append, etc. — to perform the same manipulation without the overhead of transmute.

Additionally, the transmute function no longer accepts an array of nodes or a NodeList; you can only transmute one Node at a time. To transmute an array or NodeList, simply loop over it yourself and invoke transmute for each element in the array or list. Again, the goal of this removal was to simplify the definition of transmute.

Other changes

• OpenCloseMixin's opened property is now parsed and reflected like a native HTML boolean attribute. All Elix mixins with boolean attributes support both native boolean attribute formats: to set a boolean attribute like opened to true in HTML, you can write either <elix-drawer opened> or <elix-drawer opened=“opened”>.
• OpenCloseMixin’s closed property is now read-only. To change an element’s opened/closed state, set opened instead.
• The Drawer component no longer manipulates the opacity of the backdrop part; that functionality has been moved to PlainDrawer. Thanks to @nategreen, who reported this Drawer bug, as well as another that led to the two above changes.
• The template.wrap helper has been removed, as it was extremely specialized for the needs of a small number of mixins. Those mixins now make plain DOM calls directly to accomplish the same result.
• The dom.js helper replaceChildNodes has been renamed updateChildNodes, to better suggest that it updates the set of child nodes rather than completely replacing them.
• A number of type declarations have been tightened.
• The template.html and html helpers now leverage the native String.raw template function for better performance and reduced code size.
• All Elix components with replaceable parts now perform part replacement in both the template getter and the render method. The addition of the former means that, if you define a component subclass and override a part type defined by the base class, your component’s template will end up with the replaced part baked in — no parts will need to be replaced the first time instances are rendered.

Minor bug fix

This is a major release of Elix with numerous breaking changes.

The Plain reference design system

Previous releases of the Elix components included both base class behavior and a minimum degree of styling. This made it easy to pick up and use an Elix component if you were fine with that default styling, but made it harder to use Elix as the basis for implementing your own company’s design system as components.

Since one of Elix’s core goals is to be a foundation for design systems, we’ve factored the default styling out of the base components. The Elix base components now only include structural styling: styling necessary necessary to achieve the basic expectations of a user interface pattern. For example, a basic expectation of a combobox component is that it position a popup directly underneath (or above) an input element, so the Elix ComboBox base class has structural styling to make that possible.

But the base components do not contain any aesthetic styling to achieve a particular look and feel. If you try to instantiate a base component, it probably won’t be usable. It will be missing borders, background colors, and other visual cues to let the user recognize the component as an interactive UI element.

Aesthetic styling is now left up to component subclasses to provide. To demonstrate how that can be done, and to deliver components that can be used directly, Elix now provides a reference design system called “Plain”. As its name implies, the Plain design system is deliberately minimalistic so that it can fit in with a wide variety of applications. For every base component like Drawer, you’ll find a Plain version of that component that adds extremely basic aesthetic styling.

If you want to use Elix components in your application right away, you’ll want to use the new Plain versions. If you have been loading Elix components via the paths at /define, those will now load the Plain components automatically. E.g., elix/define/Drawer.js now loads the Plain version of the Drawer component.

File reorganization

The /src folder has been grouped into three subfolders:

• src/core – The ReactiveElement base class, the core files it’s built from, plus utilities
• src/base – Component mixins and generic components (typically can’t be instantiated directly)
• src/plain – Components in the new Plain reference design system

The base components include no styling, so you generally won’t be able to use them directly.

Updating imports

If you were importing files directly from the /src folder, you will need to update your import paths:

Imports of the core files should now include /core/:

  elix/src/internal.js → elix/src/core/internal.js
  elix/src/ReactiveElement.js → elix/src/core/ReactiveElement.js
  elix/src/template.js → elix/src/core/template.js
  elix/src/utilities.js → elix/src/core/utilities.js

One exception is internal.js. Import that file from src/base:

  elix/src/internal.js → elix/src/base/internal.js

Imports of component mixins will now need to include /base/, e.g.:

  elix/src/SingleSelectionMixin.js → elix/src/base/SingleSelectionMixin.js

If you are subclassing any Elix components, you will need to decide whether you want to start with the generic base component (and provide all styling yourself) or start with the Plain version of the base component:

  elix/src/Drawer.js → elix/src/base/Drawer.js (if you want the generic drawer)
  elix/src/Drawer.js → elix/src/plain/PlainDrawer.js (if you want the drawer with reference Plain styling)

Finally, the file utilities.js has been renamed dom.js to better reflect the fact that it contains DOM helpers:

  elix/src/utilities.js → elix/src/core/dom.js

Imports of elix/src/elix.js (or just import “elix” with bundlers like webpack) should still work as before.

Imports of any component in elix/define that auto-defined itself, e.g., /elix/define/Drawer, should still work as before.

If you use TypeScript or VS Code, all type-checking should still work as before.

New components and mixins

• The new UpDownToggle component can be used for the part of a combo box, menu button, expanding panel, etc. that can point up or down.
• The new SelectableMixin tracks the selected state of a button, tab, etc.

The Plain design system distinguishes between a Button, which has no border, and a BorderButton, which provides a border. Previous versions of Elix included a component called SeamlessButton that turned off the border styling it inherited from Button. Since the base Button component now has no border, SeamlessButton is no longer necessary. If you were using that, you can now use Button instead.

Simplification to defining templates

The template.concat function in previous versions of Elix has been deprecated in favor of calling the DOM API to directly append new elements to a template’s content. To make that a little easier, this version of Elix introduces an html utility in src/core/html.js that returns a DocumentFragment. That lets you directly append to a template’s content:

Old way to extend a template:

import * as internal from "elix/src/internal.js";
import * as template from "elix/src/template.js";

class MyElement extends SomeBaseElement {
  get [internal.template]() {
    return template.concat(
      super[internal.template],
      template.html`<style>…</style>`
    );
  }
}

New way to extend a template:

import * as internal from "elix/src/base/internal.js";
import html from "elix/src/core/html.js";

class MyElement extends SomeBaseElement {
  get [internal.template]() {
    const result = super[internal.template];
    result.content.append(
      html`
        <style>
          …
        </style>
      `
    );
    return result;
  }
}

Most of the Plain components in src/plain show use of this technique.

As part of this shift, the previous template.defaultSlot helper has been removed. Use the DOM API directly to find the slot with no name attribute — that will be the default slot.

Old:

const defaultSlot = template.defaultSlot(result.content);

New:

const defaultSlot = result.content.querySelector("slot:not([name])");

This essentially minor release does make a breaking change to an obscure part of Elix, so we're taking the precaution of marking it as a major release.

The change pertains to the way that Elix lets multiple mixins and classes ensure state consistency in situations where one mixin updates a state member and the change has implications for a state member handled by another mixin.

Previously, this was done by defining state through a special State class that had some magic. Since we prefer explicit code (including a bit of boilerplate) over magic, we've removed that State class, and have gone back to defining state as just a plain object. The State class' magic onChange handlers are now handled by a more explicit component method called internal.stateEffects.

We're not aware of anyone who was using the previous State class directly. If you have issues or questions, please get in touch. In most cases, this release should not be a breaking change for you.

Other work in this release:

• You can now create Elix components with closed shadow roots. ShadowTemplateMixin now looks at an optional shadowRootMode property to determine whether the shadow root should be open or closed. The default mode is still open.
• Expansion of our type-checking coverage to include the Elix unit test suite. Many thanks to @wolframkriesing for doing that work.

Minor bug fix release.

• Fix an internal function that converts camelcase fooBar property names to kebab-case foo-bar attribute names. Thanks to @rperki8 for spotting and fixing this!
• Fix ListComboBox and its variations so that the user can properly scroll the list when the list of items is longer than the available space. Also fix a ListComboBox bug in which clicking in the list's scroll bar to scroll the list would prematurely close the combo box.

This is a minor release.

• OverlayMixin now works around a quirk in Safari that prevented the correct calculation of a default z-index.
• Some of PopupButton's default button styling has been identified as generic styling so that you can more easily turn it off when created themed variations of that component.

This is a minor release.

• Components like buttons and input elements that want to inherit font styling from the document (instead of using default system fonts for such controls) now use font: inherit instead of more specific font-* properties. This lets them inherit all font aspects instead of just a few specific aspects.

This release adds initial support for CSS Shadow Parts and custom pseudo-classes.

• All components should now expose their key internal elements as CSS shadow parts.
• The Elix documentation has been updated to list those shadow parts. E.g., the API listing for Dialog shows that the component exposes backdrop and frame parts. These can be targeted in CSS as ::part(backdrop) and ::part(frame), respectively.
• Demos have been created or extended to showcase support for styling with ::part and :state. See the demos in the Customizing documentation.
• In order to match up with the new part language, the earlier Elix properties that ended in Role now end in PartType. The corresponding attributes that ended in "-role" now end in "-part-type". E.g., the stageRole property is now stagePartType, and the corresponding stage-role attribute is now stage-part-type.
• Elix components previously applied CSS classes in certain cases for styling purposes. E.g., a ListBox would apply a "selected" CSS class to the selected item. To avoid possible conflict with page CSS, Elix components now generally apply attributes instead of CSS classes. In the case of ListBox, it now applies a selected attribute (instead of a CSS class) to the selected item.

This is a minor release.

• Fixes #105: CrossfadeStage: Unselected items are transparent but can still interfere with interactions inside selected item.

Elix 8.0 is a major release with breaking changes that focuses on giving you greater manual control over component registration.

All Elix components in prior versions automatically registered themselves with the browser with a tag that looked like <elix-something>. Read this blog post for more details on why Elix did this, and some of the pros and cons of doing that.

To give projects more flexibility with Elix components, in Elix 8.0 all Elix component modules now come in two flavors:

• The modules in the project's /src folder now export a component class, but do not register that class as a custom element. You have to register it yourself. These /src modules are intended for use in apps that have some complexity, and where you want complete control over your components.
• The modules in the project's new /define folder export the corresponding class and register that class as a custom element. Example: elix/define/Carousel.js exports the Carousel class and registers it with the tag elix-carousel. The tag name is always the prefix elix- followed by the class name in kebab case, so ComboBox becomes elix-combo-box. These /define modules are a convenient way to use components in straightforward apps where you're more concerned about getting things done than having complete control, and the constraints of auto-registration are acceptable.

This is a breaking change, as most projects that want to continue using the auto-registered elix- component tags will need to find paths that reference components in the elix/src folder and replace those with the elix/define variations. At the same time, you'll want to leave paths that reference mixins and other helpers alone so that they continue to point to elix/src. Mixin file names end with the word "Mixin", and helper file names begin with a lowercase letter.

Examples:

• elix/src/ListBox.js becomes elix/define/ListBox.js (if you want the automatically-registered, default elix-list-box tag).
• elix/src/SingleSelectionMixin.js remains the same because it's a mixin.
• elix/src/template.js remains the same because it's a helper.

Migration

In editors like VS Code whose Find/Replace features support regular expressions with negative lookbehind, you can migrate your component paths to Elix 8.0 with a case-sensitive Find/Replace operation:

• Find: elix\/src\/([A-Z].+(?<!Mixin)\.js)
• Replace: elix/define/$1

Following the upgrade to Elix 8.0, you'll have the option of manually registering the Elix components with different tag names.

Different versions of the Elix 8.0 components can be loaded on the same page. Among other things, you can load Elix 7.0 (and earlier) components and Elix 8.0 components on the same page. See this sample project.

This release includes the following breaking changes intended to solidify the public APIs for all Elix components:

• All internal operations, like the setState or render methods, and the state property, are now behind symbols instead of string names.
• We've renamed our collection of Symbol keys from symbols.js (which focused on the data type) to internal.js (which focuses on the intended purpose). So an element accesses its state via this[internal.state].
• We've renamed our shorthand function that looks up shadow elements by ID. Previously, you could write this.$.foo to get a reference to a shadow element with the ID "foo". The equivalent new code is this[internal.ids].foo.

For the rationale behind these changes , see this blog post on Hiding internal framework methods and properties from web component APIs.

To update components built on Elix 6.0 or earlier, you will need to make the following replacements in your code:

$ -> [internal.ids] componentDidMount -> [internal.componentDidMount] componentDidUpdate -> [internal.componentDidUpdate] defaultState -> [internal.defaultState] render -> [internal.render] state -> [internal.state] setState -> [internal.setState]

Aside from the above breaking changes, this release includes no substantive changes in the Elix components or mixins themselves.

This release adds support for components that can be submitted with forms. As described in this explainer, custom elements can now sit inside a <form> and submit data along with the standard HTML input elements.

• The new FormElementMixin allows you to quickly make any component class participate in form submission.
• All Elix elements that have a value property now use the above FormElementMixin and can participate in forms. This includes: AutoCompleteComboBox, AutoCompleteInput, AutoSizeTextarea, CalendarMonthNavigator, ComboBox, DateComboBox, DateInput, DropdownList, FilterComboBox, FilterListBox, Input, ListBox, and ListComboBox.

As of this writing (September 2019), form support is only available in Chrome/Edge Canary builds. The first public release of a browser that supports form-enabled custom elements will likely be Chrome 78, currently scheduled to ship in late October 2019. Safari and Firefox have both expressed support for the API, although it is not yet known when they might ship that support.

This release focuses on improving support for vertically-oriented carousels and drawers:

• Added vertical support to TrackpadSwipeMixin. A component can set its orientation state to “vertical” to tell both TouchSwipeMixin and TrackpadSwipeMixin that it wants to support vertical swipes.
• Added vertical support to SlidingStage, SlidingPages, Explorer, Carousel, and carousel variations. See the vertical Carousel demo on the Carousel page.
• Introduce DrawerWithGrip component for drawers that want to leave a little grip visible at all times. This lets the user know the drawer is there, and give them something to click or swipe out to open the drawer.
• Added a demonstration of a highly-stylized custom drawer; see the above DrawerWithGrip page;

Bug fixes:

• ListComboBox now correctly raises the selected-index-changed event. Thanks to @catwell for the fix!

This release fixes a bug in TrackpadSwipeMixin in which a trackpad swipe to the left or right would result in moving two index positions to the left or right instead of one as expected.

This release introduces SwipeCommandsMixin for letting users swipe items in a list to the left or right to reveal commands.

Minor release including:

• Better support for compilation in Babel projects, e.g., React apps.
• Minor improvements to TypeScript declarations.

This minor release adds TypeScript .d.ts files for all components and helper functions. This allows people using Elix in a TypeScript project perform type-checking of their code that interacts with Elix components.

To try this out, see the sample TypeScript project at https://github.com/elix/typescript-example.

This is a major release, with a number of breaking changes.

Rendering

• ReactiveMixin now tracks which state members have actually changed between renders. See the ReactiveMixin example for more information. For an example that uses a template to define the Shadow DOM, see the corresponding ReactiveElement example.
• This means that the method identified by symbols.render accepts a changed parameter that must be passed to any superclasses so they can use it too.
• componentDidUpdate now accepts a changed parameter identical to the one passed to symbols.render. Previously a previousState property was passed to componentDidUpdate.
• Components are now expected to use symbols.render to directly make all of their updates to the DOM, taking advantage of the changed parameter to know what to update.
• Similarly, list-like components are now expected to directly render changes to list items to the DOM.
• With the above, the "updates" system previously handled by RenderUpdatesMixin is no longer supported. The similar "item updates" system handled by ContentItemsMixin has been dropped as well.
• Since no Elix components were using shouldComponentUpdate, that lifecycle method has been dropped. If we find cases where we need it, we'll add it back.

As result of the above changes, components now generally use the web platform more directly. This has allowed the size of our base ReactiveElement class to shrink. In Elix 5.0, a minified, gzip'ed package with ReactiveElement was 12K. In 6.0, the corresponding package is 7K.

End of polyfill support

With Microsoft's shift to using Chromium in Microsoft Edge, Elix will no longer support versions of Microsoft Edge using the EdgeHTML rendering engine, and will no longer support using Elix under the web components polyfills. With these changes, Elix has been able to drop a variety of hacks and workarounds that had only been necessary to support Microsoft Edge 18 and earlier.

Minor improvements

Many small bugs have been fixed. Some of the more notable fixes include:

• CenteredStripOpacity, and components like Carousel that use it, initially render their elements (e.g., a carousel's page dots) at low opacity, then makes the selected one opaque. Previously, it had done the reverse, which could cause flashing.
• ComboBox has received a number of fixes to address issue #89 and others related to popup overflow.
• ComboBox opens the popup if the user presses Page Up or Page Down when popup is closed.
• KeyboardPagedSelectionMixin had previously displayed some cross-browser differences in how paged scrolling work. These have been addressed.
• A number of components have been rewritten to use CSS for styling instead of applying inline styles. This makes it easier to override the generic styling that comes with those components.
• A new AriaRoleMixin helps components provide a default ARIA role.
• DateComboBox now exposes the same year/month/day format options as CalendarMonth.