mtrl 0.10.7

This library continues as the npm package material, from version 3.0.0: where these notes
say material 3.0.0, they mean the next version of this code. To move, stay on the latest
mtrl 0.10.x until you are ready; then change the package name to material (version 3)
and follow its migration guide.

What material 3.0.0 decided after 0.10.6 is told in the code, as an "In material 3.0.0 …"
note in the TSDoc: the overlays' open and close, the chips' click order, the text
field's two-word tag and classes, and what material 3.0.0 takes out of its contract:
the progress component's five drawing members (marked deprecated), the slider's
components, the import path mtrl/core/compose/features, and tab.badge before its
badge is shown. None of those notes changes anything at run time. One
thing can be written the new way early: the text field's import paths resolve under their
two-word names from this release. Three limits of 0.10.x that material 3.0.0 fixes are
documented, and one accessibility fix is ported: scrolling from script honours reduced
motion. Upgrade to this release before the move.

Added

• The text field's two-word import paths, ahead of material 3.0.0 (FLO-560).
  material 3.0.0 spells the text field in two words in its paths too. These resolve from
  0.10.7, to the same modules as the one-word paths, so every path can be written the new
  way before the move:
  mtrl/components/text-field, mtrl/components/text-field/constants,
  mtrl/styles/text-field and mtrl/elements/css/text-field; and, for a stylesheet that
  @uses mtrl's Sass sources, components/text-field. Nothing else of the rename can move
  early: the <m-textfield> tag, the mtrl-textfield classes and ::part(textfield) keep
  their names on 0.10.x.

Changed

• Documented, three limits of 0.10.x that material 3.0.0 fixes and 0.10.x does not
  (each is a sentence in the TSDoc):
  • a layer: "top" dialog that refuses Escape (closeOnEscape: false, or a beforeclose
    listener that prevents it) is still closed by the third press: the browser lets a page
    refuse twice in a row and forces the third. The same for a layer: "top" modal sheet
    with closeOnEscape: false and a modal drawer with dismissible: false;
  • a snackbar waiting behind another, then dropped by a queueBehavior: 'replace' snackbar
    or by clearSnackbars(), keeps state "visible" and cannot be shown again: create a
    new one;
  • a docked date picker opened with open() from a click outside it is closed by that same
    click: call open() once the click has finished.

Deprecated

Comments only: nothing changes at run time. Each is changed in material 3.0.0, decided
after 0.10.6. "Today" in a note means 0.10.x.

• Told in the TSDoc, for material 3.0.0, the overlays' open and close: when open()
  or close() returns, the state has changed and the event has been emitted.

  • Dialog: open is emitted inside open() (without layer: "top" it comes about 10 ms
    later today), so a listener added after calling open() no longer hears it: add it
    before the call, or listen to afteropen. close() on a closed dialog emits nothing.
  • Menu, and the select and split button that hold one: close is emitted inside
    close() (about 50 ms later today), while the menu is still in the document, and
    close() then open() at once reopens it. The open and close payloads of the menu
    and the select, and the select's change payload, lose preventDefault and
    defaultPrevented, which did nothing there.
  • FAB menu, menu presentation: open() sets isOpen() and emits open in the call
    (after the menu's module has loaded today), and close is emitted inside close().
  • <m-menu> and <m-fab-menu>: the open attribute or property set by script is
    applied at once and dispatches no open and no close, as on <m-dialog> (a microtask
    later today, dispatching both). Code that sets it and waits for the event must read the
    state on the next line, or call show() / hide(), which still dispatch.
  • Escape, on every modal (the dialog, the modal sheets and drawer, the time picker, the
    modal date picker, the full-screen search): handled as a key press in both layers. Only
    the topmost open modal answers, after what is open inside it (a menu, a select) has used
    the key, and never for the key press that opened it. Escape with a menu open inside a
    dialog closes the menu only; without layer: "top" it closes the dialog as well today.
  • Snackbar: state is "queued", not "visible", while a snackbar waits behind
    another, and hide() on a queued one emits nothing. material 3.0.0 adds isOpen().
  • Time picker: isOpen is a method, isOpen(), not a property; the config option
    isOpen is named open, and TIMEPICKER_DEFAULTS.IS_OPEN is OPEN. Created with it,
    the picker is open when its factory returns (on a 0 ms timer today).

• Told in the TSDoc, for material 3.0.0, chips: a chip's onClick runs before the chip
  toggles, so isSelected() inside it is the state before the click (read the new one in onChange); a
  refused deselect in a selectionRequired set emits no change and calls no onChange or
  onSelect.

• Told in the TSDoc, for material 3.0.0, types: the search's expand and collapse
  listeners are typed with what they carry, { component, state, viewMode }; the <m-search> and
  <m-timepicker> components' on and off take a closed map of event names.

• splitButton.menu: its note now names what material 3.0.0 gives in its place for
  the items, setItems() and getItems().

• The text field is written in two words everywhere in material 3.0.0, its strings
  included (FLO-560). After the identifiers (0.10.5), material 3.0.0 renames:

  • the tag: <m-textfield> is <m-text-field>;
  • the classes: mtrl-textfield… is mtrl-text-field…. Page CSS and classList calls that
    keep the old name match nothing, and nothing warns;
  • the part: ::part(textfield) is ::part(text-field), on the text field and on the select;
  • the defaults key: setComponentDefaults('textfield', …) and
    setGlobalDefaults({ textfield }) take 'text-field';
  • the constants' values (TEXT_FIELD_CLASSES.*), and SELECT_CLASSES.TEXTFIELD's class,
    select__text-field. This corrects 0.10.5's note, which said that class stays;
  • the registry key: elements.textfield (mtrl/elements) is elements.textField;
  • generated ids: an input given no id gets one starting mtrl-text-field-, not
    mtrl-textfield-;
  • the import paths, which resolve under the new names from this release (see Added).

  Only the paths can be written the new way before the move.

• Typography leaves the base stylesheet in material 3.0.0. The type classes (.mtrl-display-large …
  .mtrl-label-small), the text utilities, mtrl's styles for h1–h6 and p, and the
  --mtrl-sys-typescale-* properties other than body-medium's then need
  import 'material/styles/typography' beside material/styles/base. The full stylesheet,
  material/styles, still includes them. There
  is nothing to change on 0.10.x: the new entry does not exist here.

• Explicit contrast levels leave the base stylesheet and the themes in material 3.0.0.
  data-theme-contrast="medium" and "high" then need import 'material/styles/contrast'
  (and material/themes/<name>-contrast for a theme imported on its own); without it the
  attribute changes no colour and nothing warns. Standard contrast and prefers-contrast: more
  stay in the base, and the full stylesheet, material/styles, still includes the levels. There
  is nothing to change on 0.10.x: the new entries do not exist here.

• The progress component's canvas, resize, track, indicator and buffer leave
  the public type in material 3.0.0. They named how the indicator is drawn (one
  canvas; track, indicator and buffer were that same canvas under the names of an
  older SVG), which tied the public type to one way of drawing it. The objects stay on
  the component at run time; the type no longer promises them. For the canvas, read
  progress.element.querySelector('canvas'); setBuffer() and getBuffer(), the
  buffer's value, are unchanged; nothing replaces resize(), which the component does
  itself on a size change.

• The slider's components bag is internal in material 3.0.0. The public
  SliderComponent never had it, nothing in the library fills it, and it may go in any
  release. Use the slider's own API (setValue(), getValue() and the rest of
  SliderComponent) and slider.element.

• mtrl/core/compose/features leaves the public contract in material 3.0.0
  (FLO-414). The path does not resolve there: import its names from
  material/core/compose, which exports them (withLifecycle among them; on 0.10.x
  every name except withBadge, LabelManager and the badge feature's BadgeComponent
  and BadgeConfig, so all the others can be written the new way now). The README
  teaches the new path.

• tab.badge may be undefined in material 3.0.0 until the badge is shown. The
  type always allowed it; it is now the documented contract, so a later release can
  create the badge only when it is shown. Read it with a guard, or use setBadge(),
  getBadge(), showBadge() and hideBadge(), which work whether it exists yet or not.

Fixed

• Accessibility: scrolling from script honours reduced motion in the chips, the tabs and the
  search (FLO-553). The chip set's scrollToChip, the tabs' scroll buttons and the search's
  arrow keys through the suggestions each asked for a smooth scroll explicitly, which overrides
  the stylesheet, so they glided with the reduced-motion preference on. They now name no
  behaviour: each scroller scrolls smoothly from its stylesheet (scroll-behavior: smooth,
  new on the tabs' scroller and the suggestion list), and jumps at once under reduced motion,
  in the factories and inside <m-chips>, <m-tabs> and <m-search> (their shadow roots
  carry the reduced-motion rule since 0.10.6). A script of yours that scrolls the tabs'
  scroller or the suggestion list now scrolls it smoothly too.

---

npm: mtrl@0.10.7 · Docs: md3.io · Full history: CHANGELOG.md