src/components/tf-help.js
/**
* `<tf-help>`: help instructions in a native modal `<dialog>`.
*
* Shadow root: `slot[name="trigger"]` (a slotted control is the
* control) and `<button part="trigger">` for the element-rendered
* case; a `<dialog part="dialog">` carrying
* `<div part="instructions">` with `slot[name="instructions"]` and a
* `part="instructions-text"` text part; a `<button part="close">` with
* `part="close-text"`.
*
* Attributes: `trigger-text`; `accessible-label` (trigger `aria-label`);
* `instructions-text`; `accessible-dialog-label` (dialog accessible name,
* falling back to `aria-labelledby` on the trigger); `close-text` (close
* control text and accessible name; the control is unnamed when the
* attribute is absent); `open` (reflects the dialog state); `disabled`
* (blocks trigger activation). Empty or absent attributes render
* empty.
*
* The dialog opens with `showModal()`, which traps focus inside it and
* closes it on `Escape`. A user dismissal (`Escape`, backdrop,
* close control, trigger toggle) returns focus
* to the trigger control: the slotted trigger when one is assigned, the
* element button otherwise, the host when slotted markup hides it. A
* programmatic close keeps the platform focus restore. Setting `open`
* opens the dialog, removing it closes the dialog, and `open-change`
* reports the state with `detail: {open}`.
*
* The element ships no class or presentational style; theme it via
* `::part()` and `--tf-*` custom properties. Importing this module
* registers the element.
*/
const TRIGGER_ID = 'trigger';
const DIALOG_ID = 'dialog';
// Controls and widgets that take focus; used to pick the focus target
// inside slotted trigger markup. Matches FOCUSABLE_TRIGGER in
// modules/help.js.
const FOCUSABLE = 'button:not([disabled]), a[href], ' +
'input:not([disabled]), select:not([disabled]), ' +
'textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
// Cloned into every instance's shadow root. Structure and `part` hooks
// only: no class or presentational style is baked in.
const TEMPLATE = document.createElement('template');
TEMPLATE.innerHTML = `
<slot name="trigger" part="trigger-slot"></slot>
<button type="button" part="trigger" id="${TRIGGER_ID}"
aria-haspopup="dialog" aria-expanded="false"
aria-controls="${DIALOG_ID}">
<span part="trigger-text"></span>
</button>
<dialog part="dialog" id="${DIALOG_ID}">
<div part="instructions">
<slot name="instructions"></slot>
<span part="instructions-text"></span>
</div>
<button type="button" part="close">
<span part="close-text"></span>
</button>
</dialog>
`;
export class TfHelpElement extends HTMLElement {
constructor() {
super();
this.attachShadow({ mode: 'open' });
this.shadowRoot.appendChild(TEMPLATE.content.cloneNode(true));
this._triggerSlot =
this.shadowRoot.querySelector('slot[name="trigger"]');
this._trigger = this.shadowRoot.querySelector('[part="trigger"]');
this._triggerText =
this.shadowRoot.querySelector('[part="trigger-text"]');
this._dialog = this.shadowRoot.querySelector('[part="dialog"]');
this._instructionsSlot =
this.shadowRoot.querySelector('slot[name="instructions"]');
this._instructionsText =
this.shadowRoot.querySelector('[part="instructions-text"]');
this._close = this.shadowRoot.querySelector('[part="close"]');
this._closeText =
this.shadowRoot.querySelector('[part="close-text"]');
this._reportedOpen = false;
this._userClosed = false;
this._trigger.addEventListener('click', () => this._toggle());
this._triggerSlot.addEventListener('click', () => this._toggle());
this._triggerSlot.addEventListener(
'slotchange', () => this._syncLayout());
this._instructionsSlot.addEventListener(
'slotchange', () => this._syncLayout());
this._dialog.addEventListener('click', (event) => {
// A backdrop click lands outside the dialog box; a click on
// the dialog's border or padding lands on the dialog
// element but inside the box.
if (event.target === this._dialog &&
!this._isInsideDialogBox(event)) {
this._dismiss();
return;
}
// A slotted element with class `close` dismisses; other
// content clicks keep the dialog open.
if (event.composedPath().some((node) =>
node.nodeType === 1 && node.classList &&
node.classList.contains('close'))) {
this._dismiss();
}
});
this._close.addEventListener('click', () => this._dismiss());
this._dialog.addEventListener(
'cancel', () => { this._userClosed = true; });
this._dialog.addEventListener('close', () => this._onClose());
}
static get observedAttributes() {
return ['accessible-label', 'trigger-text',
'accessible-dialog-label',
'instructions-text', 'close-text', 'open', 'disabled'];
}
connectedCallback() {
this._update();
this._applyOpen();
}
disconnectedCallback() {
if (this._dialog.open) {
this._dialog.close();
}
}
attributeChangedCallback(name) {
this._update();
if (name === 'open') {
this._applyOpen();
}
}
/**
* Set the trigger button's accessible name, rendered as `aria-label`.
* @param {*} label Accessible name
*/
setLabel(label) {
this.setAttribute('accessible-label',
label == null ? '' : String(label));
}
/**
* Set the trigger text, rendered into the trigger button.
* @param {*} text Trigger text
*/
setText(text) {
this.setAttribute('trigger-text',
text == null ? '' : String(text));
}
/**
* Set the dialog's accessible name.
* @param {*} label Accessible name
*/
setDialogLabel(label) {
this.setAttribute('accessible-dialog-label',
label == null ? '' : String(label));
}
/**
* Set the instructions text.
* @param {*} text Instructions text
*/
setInstructionsText(text) {
this.setAttribute('instructions-text',
text == null ? '' : String(text));
}
/**
* Open or close the dialog.
* @param {Boolean} open Whether the dialog is open
*/
setOpen(open) {
if (open) {
this.setAttribute('open', '');
} else {
this.removeAttribute('open');
}
}
/**
* Render attributes into the shadow parts.
*/
_update() {
if (!this._trigger) {
return;
}
this._setAriaLabel(this._trigger, 'accessible-label');
this._triggerText.textContent =
this.getAttribute('trigger-text') || '';
this._instructionsText.textContent =
this.getAttribute('instructions-text') || '';
this._closeText.textContent =
this.getAttribute('close-text') || '';
this._setDialogName();
if (this.hasAttribute('disabled')) {
this._trigger.setAttribute('disabled', '');
} else {
this._trigger.removeAttribute('disabled');
}
this._syncLayout();
this._syncExpanded();
}
/**
* Show the element-rendered trigger control only when the trigger
* slot has no assigned nodes, and the instructions text part only
* when the instructions slot has none.
*/
_syncLayout() {
if (!this._trigger) {
return;
}
this._trigger.hidden = this._triggerSlot
.assignedNodes({ flatten: true }).length > 0;
this._instructionsText.hidden = this._instructionsSlot
.assignedNodes({ flatten: true }).length > 0;
}
/**
* Name the dialog from its own attribute, or from the trigger.
*/
_setDialogName() {
const label = this.getAttribute('accessible-dialog-label') || '';
if (label) {
this._dialog.setAttribute('aria-label', label);
this._dialog.removeAttribute('aria-labelledby');
} else {
this._dialog.removeAttribute('aria-label');
this._dialog.setAttribute('aria-labelledby', TRIGGER_ID);
}
}
/**
* Render an attribute as `aria-label` on a shadow element, or remove
* it when the attribute is absent or empty.
* @param {Element} el Shadow element to name
* @param {String} attr Attribute holding the accessible name
*/
_setAriaLabel(el, attr) {
const label = this.getAttribute(attr) || '';
if (label) {
el.setAttribute('aria-label', label);
} else {
el.removeAttribute('aria-label');
}
}
/**
* Toggle the dialog from the trigger control.
*/
_toggle() {
if (this.hasAttribute('disabled')) {
return;
}
if (this._dialog.open) {
this._userClosed = true;
}
this.setOpen(!this._dialog.open);
}
/**
* Report whether a pointer event's coordinates fall inside the
* dialog's border box.
* @param {MouseEvent} event Pointer event
*/
_isInsideDialogBox(event) {
const rect = this._dialog.getBoundingClientRect();
return event.clientX >= rect.left && event.clientX <= rect.right &&
event.clientY >= rect.top && event.clientY <= rect.bottom;
}
/**
* Close the dialog from a user dismissal.
*/
_dismiss() {
this._userClosed = true;
this.setOpen(false);
}
/**
* Apply the host `open` attribute to the dialog.
*/
_applyOpen() {
if (!this.isConnected) {
return;
}
const open = this.hasAttribute('open');
if (open && !this._dialog.open) {
this._dialog.showModal();
} else if (!open && this._dialog.open) {
this._dialog.close();
}
this._syncExpanded();
this._reportOpen();
}
/**
* Keep `aria-expanded` in sync with the dialog state.
*/
_syncExpanded() {
this._trigger.setAttribute('aria-expanded',
String(this._dialog.open));
}
/**
* Dispatch `open-change` when the dialog state changes.
*/
_reportOpen() {
const open = this._dialog.open;
if (open === this._reportedOpen) {
return;
}
this._reportedOpen = open;
this.dispatchEvent(new CustomEvent('open-change', {
detail: { open },
bubbles: true,
composed: true
}));
}
/**
* Sync the host attribute when the dialog closes from the platform
* (`Escape`), the backdrop or the instructions container.
*/
_onClose() {
if (this._dialog.open) {
return;
}
if (this.hasAttribute('open')) {
this.removeAttribute('open');
}
this._syncExpanded();
this._reportOpen();
const userClosed = this._userClosed;
this._userClosed = false;
if (!userClosed) {
return;
}
// The platform restores focus to the element focused at
// showModal() after the close event; the deferred call runs
// after that restoration.
setTimeout(() => this._focusTrigger());
}
/**
* Move focus to the slotted trigger control, to the element button
* when the slot has none, or to the host when slotted markup hides
* the button.
*/
_focusTrigger() {
if (!this.isConnected) {
return;
}
const assigned = this._triggerSlot
.assignedNodes({ flatten: true })
.filter((node) => node.nodeType === Node.ELEMENT_NODE);
const slotted = assigned
.map((el) => el.matches(FOCUSABLE) ? el
: el.querySelector(FOCUSABLE))
.find(Boolean);
if (slotted) {
slotted.focus();
return;
}
if (this._trigger.hidden) {
this.tabIndex = -1;
this.focus();
return;
}
this._trigger.focus();
}
}
// Register once: loading this module twice (or on a page that already
// defined the element) must not throw.
if (typeof customElements !== 'undefined' &&
!customElements.get('tf-help')) {
customElements.define('tf-help', TfHelpElement);
}