BookStack/resources/js/services/dom.js
Dan Brown 88785aa71b
Page display pointer: Considerably improved accessibility
- Updated pointer to move within content DOM so that you can back-focus
  into the pointer if desired.
- Added new "Section select mode" which toggles focusabiltiy for main
  content sections, with ability to show pointer via enter press on
  these.
- Updated pointer with proper input/button labelling.

Tested via orca screen reader on Firefox/Fedora/Gnome.
For #3975
2023-05-31 16:44:20 +01:00

193 lines
5.2 KiB
JavaScript

/**
* Create a new element with the given attrs and children.
* Children can be a string for text nodes or other elements.
* @param {String} tagName
* @param {Object<String, String>} attrs
* @param {Element[]|String[]}children
* @return {*}
*/
export function elem(tagName, attrs = {}, children = []) {
const el = document.createElement(tagName);
for (const [key, val] of Object.entries(attrs)) {
if (val === null) {
el.removeAttribute(key);
} else {
el.setAttribute(key, val);
}
}
for (const child of children) {
if (typeof child === 'string') {
el.append(document.createTextNode(child));
} else {
el.append(child);
}
}
return el;
}
/**
* Run the given callback against each element that matches the given selector.
* @param {String} selector
* @param {Function<Element>} callback
*/
export function forEach(selector, callback) {
const elements = document.querySelectorAll(selector);
for (const element of elements) {
callback(element);
}
}
/**
* Helper to listen to multiple DOM events
* @param {Element} listenerElement
* @param {Array<String>} events
* @param {Function<Event>} callback
*/
export function onEvents(listenerElement, events, callback) {
for (const eventName of events) {
listenerElement.addEventListener(eventName, callback);
}
}
/**
* Helper to run an action when an element is selected.
* A "select" is made to be accessible, So can be a click, space-press or enter-press.
* @param {HTMLElement|Array} elements
* @param {function} callback
*/
export function onSelect(elements, callback) {
if (!Array.isArray(elements)) {
elements = [elements];
}
for (const listenerElement of elements) {
listenerElement.addEventListener('click', callback);
listenerElement.addEventListener('keydown', event => {
if (event.key === 'Enter' || event.key === ' ') {
event.preventDefault();
callback(event);
}
});
}
}
/**
* Listen to key press on the given element(s).
* @param {String} key
* @param {HTMLElement|Array} elements
* @param {function} callback
*/
function onKeyPress(key, elements, callback) {
if (!Array.isArray(elements)) {
elements = [elements];
}
const listener = event => {
if (event.key === key) {
callback(event);
}
};
elements.forEach(e => e.addEventListener('keydown', listener));
}
/**
* Listen to enter press on the given element(s).
* @param {HTMLElement|Array} elements
* @param {function} callback
*/
export function onEnterPress(elements, callback) {
onKeyPress('Enter', elements, callback);
}
/**
* Listen to escape press on the given element(s).
* @param {HTMLElement|Array} elements
* @param {function} callback
*/
export function onEscapePress(elements, callback) {
onKeyPress('Escape', elements, callback);
}
/**
* Set a listener on an element for an event emitted by a child
* matching the given childSelector param.
* Used in a similar fashion to jQuery's $('listener').on('eventName', 'childSelector', callback)
* @param {Element} listenerElement
* @param {String} childSelector
* @param {String} eventName
* @param {Function} callback
*/
export function onChildEvent(listenerElement, childSelector, eventName, callback) {
listenerElement.addEventListener(eventName, event => {
const matchingChild = event.target.closest(childSelector);
if (matchingChild) {
callback.call(matchingChild, event, matchingChild);
}
});
}
/**
* Look for elements that match the given selector and contain the given text.
* Is case insensitive and returns the first result or null if nothing is found.
* @param {String} selector
* @param {String} text
* @returns {Element}
*/
export function findText(selector, text) {
const elements = document.querySelectorAll(selector);
text = text.toLowerCase();
for (const element of elements) {
if (element.textContent.toLowerCase().includes(text)) {
return element;
}
}
return null;
}
/**
* Show a loading indicator in the given element.
* This will effectively clear the element.
* @param {Element} element
*/
export function showLoading(element) {
element.innerHTML = '<div class="loading-container"><div></div><div></div><div></div></div>';
}
/**
* Get a loading element indicator element.
* @returns {Element}
*/
export function getLoading() {
const wrap = document.createElement('div');
wrap.classList.add('loading-container');
wrap.innerHTML = '<div></div><div></div><div></div>';
return wrap;
}
/**
* Remove any loading indicators within the given element.
* @param {Element} element
*/
export function removeLoading(element) {
const loadingEls = element.querySelectorAll('.loading-container');
for (const el of loadingEls) {
el.remove();
}
}
/**
* Convert the given html data into a live DOM element.
* Initiates any components defined in the data.
* @param {String} html
* @returns {Element}
*/
export function htmlToDom(html) {
const wrap = document.createElement('div');
wrap.innerHTML = html;
window.$components.init(wrap);
return wrap.children[0];
}