Shared mixins, tools, etc. that support developing Spectrum Web Components.

npm install @spectrum-web-components/shared

Individual base classes and mixins can be imported as follows:

import {
    Focusable,
    FocusVisiblePolyfillMixin,
    getActiveElement,
    LikeAnchor,
    ObserveSlotText,
} from '@spectrum-web-components/shared';

The getDeepElementFromPoint method allows you to obtain the deepest possible element at a given coordinates on the current page. The method will step into any available shadowRoots until it reaches the first element with no shadowRoot or no children available at the given coordinates.

The Focusable subclass of LitElement adds some helpers method and lifecycle coverage in order to support passing focus to a container element inside of a custom element. The Focusable base class handles tabindex setting into shadowed elements automatically and is based heavily on the aybolit delegate-focus-mixin.

import { Focusable } from '@spectrum-web-components/shared';
import { html } from 'lit-element';

class FocusableButton extends Focusable {
    public static override get styles(): CSSResultArray {
        return [...super.styles];
    }
    public get focusElement(): HTMLElement {
        return this.shadowRoot.querySelector('#button') as HTMLElement;
    }

    protected override render(): TemplateResult {
        return html`
            <button
                id="button"
            >
                Focus for this button is being managed by the focusable base class.
            </button>
        `;
    }
}

Use this mixin if you would like to leverage :focus-visible based selectors in your CSS. Learn more about the polyfill that powers this.

Use this helper to find an activeElement in your component. Learn more about tracking active elements over shadow DOM boundaries.

Mix download, label, href, and target properties into your element to allow it to act more like an HTMLAnchorElement.

When working with styles that are driven by the conditional presence of <slot>s in a component's shadow DOM, you will need to track whether light DOM that is meant for that slot exists. Use the ObserveSlotPresence mixin to target specific light DOM to observe the presence of and trigger this.requestUpdate() calls when content fulfilling that selector comes in and out of availability.

import { ObserveSlotPresence } from '@spectrum-web-components/shared';
import { LitElement, html } from 'lit-element';
class ObserveSlotPresenceElement extends ObserveSlotPresence(LitElement, '[slot="conditional-slot"]') {
    // translate the mixin properties into locally understandable language
    protected get hasConditionalSlotContent() {
        return this.slotContentIsPresent;
    }
    protected override render(): TemplateResult {
        return html`
            <button
                id="button"
            >
                ${this.hasConditionalSlotContent
                    ? html`
                        <slot
                            name="conditional-slot"
                        ></slot>
                    `
                    : html``
                }
            </button>
        `;
    }
    protected updated(): void {
        console.log(this.slotContentIsPresent); // => true when <observing-slot-presence-element><div slot="conditional-slot"></div></observing-slot-presence-element>
    }
}
customElements.define('observing-slot-presence-element', ObserveSlotPresenceElement);

When working with <slot>s and their slotchange event, you will have the opportunity to capture when the nodes and/or elements in your element are added or removed. However, if the textContent of a text node changes, you will not receive the slotchange event because the slot hasn't actually received new nodes and/or elements in the exchange. When working with a lit-html binding <your-element>${text}</your-element> that means you will not receive a slotchange event when the value of text goes from text = '' to text = 'something' or the other way. In these cases the ObserveSlotText can be leverages to apply a mutation observe onto your element that tracks characterData mutations so that you can resspond as desired.

import { ObserveSlotText } from '@spectrum-web-components/shared';
import { LitElement, html } from 'lit-element';

class ObserveSlotTextElement extends ObserveSlotText(LitElement, '#observing-slot') {
    protected override render(): TemplateResult {
        return html`
            <button
                id="button"
            >
                <slot
                    id="observing-slot"
                    @slotchange=${this.manageObservedSlot}
                ></slot>
            </button>
        `;
    }
    protected updated(): void {
        console.log(this.slotHasContent); // => true when <observing-slot-text-element>Text</observing-slot-text-element>
    }
}

customElements.define('observing-slot-text-element', ObserveSlotTextElement);

Changelog

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

• action-bar: support for action-menus (#3780) (4aff599)

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

• shared: ensure the "updateComplete" in Focusable is stable (885b4a5)

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

• support generating random IDs outside of secure contexts (485a67c)

Note: Version bump only for package @spectrum-web-components/shared

• shared: update and expand attribute coverage in likeAnchor (5cb5f1d)

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

• shared: scope querySelector to direct children, like slots are (515eaee)

Note: Version bump only for package @spectrum-web-components/shared

• overlay: ship Overlay API v2 (67b5d1b)

Note: Version bump only for package @spectrum-web-components/shared

• meter, progress-bar, progress-circle: use innerText when label is not provided (#3483) (59358c7)

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

• shared: allow "disabled" first to return to "tabindex=0" in "focusable" (160bc59)

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

• correct the relationship between overlayWillCloseCallback and phased animations (c63db8d)

• include all Dev Mode files in side effects (f70817c)

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

• conditionally load focus-visible polyfill (6b5e5cf)
• reparentChildren - insertAdjacentElement style API (07f966f)
• reparentChildren - refactored arguments - breaking change (dea2bc5)

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

• dialog: updates for delivering dialog content accessibly (f0ed33c)

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

• update lit-* dependencies, wip (377f3c8)

Note: Version bump only for package @spectrum-web-components/shared

• centralize updated first focusable selector (300e84c)

• add likeAnchor API to Card element (5c338fb)

• ensure lazily loaded focusElements do not crash (64f2a54)

Note: Version bump only for package @spectrum-web-components/shared

• allow detached elements to be used as content for an overlay (3ad8383)
• manage "lang" via context provided by "sp-theme" (b1e3457)

Note: Version bump only for package @spectrum-web-components/shared

• no scroll update when managing elements outside of the tab order (144c548)
• prevent tabindex=-1 elements from placing focus on their host (1ac1293)

• allow rendered anchors to be aria-hidden (2e9aa23)
• update "reparentChildren" types for flexibility (2d358be)

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

• renamed the file but not this (ad94e53)
• split-button tests & lots of cleanup based on review feedback (10b4a04), closes #1189

• picker: process field-label content for more accurate a11y tree (dc9df54)
• deprecate sp-menu in PickerBase derived classes (bbb773c)

Note: Version bump only for package @spectrum-web-components/shared

• use latest exports specification (a7ecf4b)

• update to latest spectrum-css packages (a5ca19f)

• allow activation of longpress content (55e71fd)

• button: relate to this.href correctly (fade3ea)
• include the "types" entry in package.json files (b432f59)
• use latest @spectrum-css/* versions (c35eb86)

• button: use synthetic button instead of native (49e94bc)
• shared: conditionally apply focus-visible polyfill (b854df6)

• shared: focus-visible, lazily instantiate the focus-visible polyfilling (fe257c1)

• button: relate to this.href correctly (fade3ea)
• include the "types" entry in package.json files (b432f59)
• use latest @spectrum-css/* versions (c35eb86)

• button: use synthetic button instead of native (49e94bc)
• shared: conditionally apply focus-visible polyfill (b854df6)

• shared: focus-visible, lazily instantiate the focus-visible polyfilling (fe257c1)

Note: Version bump only for package @spectrum-web-components/shared

• include default export in the "exports" fields (f32407d)

• update side effect listings (8160d3a)

• top-nav: prototype top-nav pattern (9708f6f)
• flatten assigned nodes to observe text of nested slots (08ffd68)

• split-button: follow visible tab order (966d3b6)

• split-button: add split-button pattern (4833a59)
• use 3.0.0-beta.* release for styles (877b485)

• ensure browser understandable extensions (f4e59f7)

• link: support rel attribute (df4b5a8)

• shared: prevent focusable returning focus to host (745f7b0)
• tabs: correct entry focus element (64407d3)

• leverage "exports" field in package.json (321abd7)

Note: Version bump only for package @spectrum-web-components/shared

• use "sideEffects" listing in package.json (7271614)

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

Note: Version bump only for package @spectrum-web-components/shared

• shared: fixes search input - fixes #463 (6833944)
• shared: removes mousedown event handling in focusable (4e90d4c)

• shared: prevent focusing focusable root on second click (0fb5006)

• sidenav: add keyboard accessibility (6ff622b)
• tab-list: autofocus, :before/after processing, visual test (83dddb0)

• apply Focuable styles in class extensions (38f7afd)

• shared: include an actual entry point for bundlephobia (00fd6ab)
• normalize "event" and "error" argument names (8d382cd)

• include "type" in package.json, generate custom-elements.json (1a8d716)

• shared: fixes focus-visible types in test (0dc7d68)
• shared: improves types for focus-visible (b980f2a)

• add screenshot regression testing to CI (8205dfe)
• use :focus-visable (via polyfill) instead of :focus (11c6fc7)

• shared: make Focusable pass disabled always (a339d6f)
• shared: quiet the angry soul of the explicit any linter (c278263)

• shared: add mixing for observing text content changes in a slot (1318150)

• use imported TypeScript helpers instead of inlining them (cc2bd0a)

Note: Version bump only for package @spectrum-web-components/shared