DOM
MDC DOM provides commonly-used utilities for inspecting, traversing, and manipulating the DOM.
Most of the time, you shouldn't need to depend on mdc-dom directly. It is useful however if you'd like to write custom components that follow MDC Web's pattern and elegantly integrate with the MDC Web ecosystem.
Installation
npm install @material/dom
Basic Usage
import * as ponyfill from '@material/dom/ponyfill';
See Importing the JS component for more information on how to import JavaScript.
Ponyfill Functions
The ponyfill module provides the following functions:
| Function Signature | Description |
|---|
closest(element: Element, selector: string) => ?Element | Returns the ancestor of the given element matching the given selector (which may be the element itself if it matches), or null if no matching ancestor is found. |
matches(element: Element, selector: string) => boolean | Returns true if the given element matches the given CSS selector. |
estimateScrollWidth(element: Element) => number | Returns the true optical width of the element if visible or an estimation if hidden by a parent element with display: none;. |
Event Functions
External frameworks and libraries can use the following event utility methods.
| Method Signature | Description |
|---|
util.applyPassive(globalObj = window) => object | Determine whether the current browser supports passive event listeners |
Focus Trap
The FocusTrap utility traps focus within a given element. It is intended for usage from MDC-internal
components like dialog and modal drawer.
| Method Signature | Description |
|---|
trapFocus() => void | Traps focus in the root element. Also focuses on initialFocusEl if set; otherwise, sets initial focus to the first focusable child element. |
releaseFocus() => void | Releases focus from the root element. Also restores focus to the previously focused element. |
Announce
The announce utility file contains a single helper method for announcing a message via an aria-live region. It is intended for usage from MDC-internal components.
| Method Signature | Description |
|---|
announce(message: string, priority?: AnnouncerPriority) => void | Announces the message via an aria-live region with the given priority (defaults to polite) |
Keyboard
The keyboard utility provides helper methods for normalizing KeyboardEvent keys across browsers. It is intended for usage from MDC-internal components.
| Method Signature | Description |
|---|
normalizeKey(evt: KeyboardEvent) => string | Returns a normalized string derived from KeyboardEvent's keyCode property to be standard across browsers. |
isNavigationEvent(evt: KeyboardEvent) => boolean | Returns true if the event is a navigation event (Page Up, Page Down, Home, End, Left, Up, Right, Down). |
Mixins
The module provides a single SASS mixin which helps improves a DOM element's UX for high-contrast mode users.
| Mixin | Description |
|---|
transparent-border | Emits necessary layout styles to set a transparent border around an element without interfering with the rest of its component layout. The border is only visible in high-contrast mode. The target element should be a child of a relatively positioned top-level element (i.e. a ::before pseudo-element). |
11.0.0 (2021-04-15)
Bug Fixes
- banner: Use role alertdialog. (a07b6d4)
- button: add missing feature-targeting import (71fe9a0)
- button: Fixed button's icon size scaling on browser zoom (bc104ba)
- chips: Expose deprecated resources in top-level TypeScript file (67d780c)
- chips: Fix incorrect references between deprecated and non-deprecated resources (f8579b7)
- chips: Make chips wrap by default (24255c4)
- chips: Remove obsolete chips resources now in chips/deprecated/* (87ac2fd)
- chips: Remove obsolete resources (40dd242)
- chips: rename deprecated trailing action classes (48f4b67)
- chips: Un-remove obsolete chips resources now in chips/deprecated/* (7cf6782)
- chips: Use deprecated chips in autoinit (d2a39d3)
- circular-progress: add annotation (06dead2)
- dialog: Add transparent border to dialog surface for HCM support. (b2fa996)
- dialog: Remove the unnecessary border on the dialog title when not needed, this adds an extra line in the UI on high contrast mode. With margins it is possible to keep the previous spacing and only add the border when needed. (3344d12)
- dom: do not cache focusable elements in focus-trap (7899e0f)
- fab: add alternate decorator only when necessary (0fd56a8)
- fab: Apply extended shape radius in Extended FAB's theme mixin (81911b7)
- list: Correcting the selector mapping for CHILD_ELEMENTS_TO_TOGGLE_TABINDEX and FOCUSABLE_CHILD_ELEMENTS. (8943b99), closes #6829 #6829
- list: do not activate typeahead on certain modifier keys (f1b1fd5)
- progress-indicators: hide from screenreaders on close (d3a6862)
- ripple: Update states-selector() to use
:active:active to match active specificity styles. (faa7d32) - select: do not conduct anchor typeahead when modifier keys pressed (6f678a9)
- select: set hidden input value before firing change event (2d6ba2c), closes #6904
- shape: duplication bug with nested custom properties (f77a4dd)
- slider: Fire custom
input event on input change (i.e. value change via keyboard), mirroring the native input event behavior for range inputs. (ec8f846) - slider: Fix #quantize to use min value as the baseline. (0f358dd)
- slider: Fix JS floating point rounding errors by rounding values to a set number of decimal places based on the step size. (6072ed6)
- slider: Fix track height. (67eb0df)
- slider: Improve HCM borders, add missing @noflip annotations. (e7202cb)
- slider: Modify behavior such that for range sliders, presses in the middle of the range change the value (of the closest thumb). This provides a single-pointer alternative option to an otherwise gesture-based interaction. (0b8cff7)
- slider: Throttle slider UI updates. (7d6a4bb)
- slider: Throw error for invalid initial values based on the step. (3955d8d)
- tab: Update ripple adapter to reflect sass ripple-target. (97c4d40)
- theme: do not emit when theme.property() replacements are null (aa0aaf0)
- theme: parsing error when @import-ing mdc-theme (b62b126)
- theme: replace works for multiple replacements (95322b1)
- update README to correct links. (71e615b)
- tooltip: flip precedence of data-tooltip-id and aria-describedby when finding TT id (b2d22df)
- typography: do not emit styles when setting null from global variable (f5f1b61)
Code Refactoring
- snackbar: Update a11y structure (c60449b)
- tooltip: Moved the anchor element blur event listener from the component to within the foundation. (0b4a4b2)
- typography: Rename typography Sass function from pxToRem() to px-to-rem() (8f0a11e)
Features
- base: add non-statics foundation constructor type (e3ec22f)
- base: add observer mixin (4ceb422)
- chips: Expose "action" component (03d34bb)
- chips: Expose "chip" component (cbc57c6)
- chips: Expose "chipset" component (d6c5bcf)
- chips: Expose top-level resources (fefc668)
- chips: Remove touch target wrapper selector from chip set spacing (367d88b)
- chips: Start deprecation of chip (e683bdf)
- chips: Start deprecation of chip root directory (73a2271)
- chips: Start deprecation of chip set (148e8cf)
- chips: Start deprecation of chip trailing action (9eeb35c)
- chips: Truncate long chip labels by default (f5c6db8)
- dialog: Adding
resize and orientationchange event handlers into MDCDialogFoundation. (1e06534) - dialog: Adds support for "surface-scrim" over full-screen dialogs. This prevents a "double scrim" from appearing when showing a secondary dialog over a full-screen dialog on larger screens. (cddb035)
- dom: add option to skip restoring focus on release focus (5c0ab74)
- dom: add tab key keyboard.ts (dc9c840)
- fab: Add theming API to Extended FABs (f19c86d)
- fab: Added
$focus-outline-width param to extended-padding() FAB mixin (8ecd7c9) - fab: Added focus outline theme keys to FAB theme mixin (d6d8d04)
- fab: Added theme mixin to primary FAB variant. (f19bbc4)
- fab: border custom prop support & add CPs for padding (a6b3101)
- fix: Ensure that secondary controls do not ripple. (1f636b2)
- fix: Fix divider layout in right-to-left locales. (f524626)
- fix: Remove old MDC list class names, preparing to release evolution. (5f0fc44)
- fix: Remove the "evolution" prefix from list evolution's class names. (0cde52f)
- fix: Simplify divider styles to reflect new design guidance. (f77c508)
- linear-progress: add getBuffer (9c85d50)
- list: Add "deprecated" aliases for old list mixins / variables. (f9cac96)
- list: Add missing "deprecated" aliases for old list mixin. (302c7a9)
- list: Finalize list mixin/variable rename. (c97d7d8)
- list: Rename deprecated MDC list class names. (a678806)
- list: Rename deprecated MDC list class names. (941ca3b)
- list: Update deprecated list class names so evolution can become default. (606e767)
- list: Update styles to reference "deprecated" mixins/variables. (3201cae)
- list: Update styles to remove "evolution" prefix from mixins/variables. (f9c9e39)
- menu: add maxHeight setter (bf670da)
- menu-surface: add option to always horizontally center on viewport (23ea2d8)
- ripple: add active() mixin for styling active styles. (9f2e85f)
- select: allow programmatic change without firing event (79ce087), closes #6166
- slider: Add mixin to customize thumb color in the activated (hover, focus, pressed) state. (94f50b2)
- Add support for "mdc-deprecated-list-*" class names. (9e52f55)
- switch: add high-contrast mode focus shim mixin (c91e8d1)
- theme: add configuration support for custom-properties (1f318ff)
- theme: add create-varname() for custom properties (b522724)
- theme: add key store (07ff0c4)
- tooltip: Adding logic to position the caret relative to the tooltip. (76da787)
- tooltip: Adding touchstart/touchend event listeners to tooltip. This allows tooltips attached to non-focusable elements to be surfaced on mobile. (7cd26af)
- tooltip: Creating an
mdc-tooltip__surface-animation class that holds all the style properties responsible for animating the tooltip in and out of the page. The existing mdc-tooltip__surface class will hold all the style properties that impact the visual appearance of the tooltip. (56fc269) - tooltip: Expose method that allows users to register additional scroll handlers on elements in the DOM. This should be used in situations where the tooltip anchor is a child of a scrollable element, and will ensure that the tooltip remains attached to the anchor when this element is scrolled. (24609b8)
BREAKING CHANGES
- typography: Renamed typography Sass function from pxToRem() to px-to-rem()
PiperOrigin-RevId: 368489085
- fix: the old list implementation has been deprecated and now requires that class names use an "mdc-deprecated-list-" prefix. The new implementation (list evolution), no longer uses a prefix ("mdc-evolution-list-" is now just "mdc-list-*").
PiperOrigin-RevId: 364441086
- snackbar: Dom structure change, see README.md
PiperOrigin-RevId: 363926666
- tooltip: Added adapter method:
- registerAnchorEventHandler<K extends EventType>(
evtType: K, handler: SpecificEventListener<K>): void;
- deregisterAnchorEventHandler<K extends EventType>(
evtType: K, handler: SpecificEventListener<K>): void;
PiperOrigin-RevId: 358401984
