@stencila/thema/dist/util/index.d.ts

Themes for executable documents

import { translate } from '../selectors';
export { translate };
/**
 * Convenience functions for manipulating the DOM.
 *
 * Most of the names of these functions mirror their analogs
 * in https://api.jquery.com.
 * Inspiration also taken from https://plainjs.com/javascript.
 */
/**
 * Register a function to be executed when the DOM is fully loaded.
 *
 * @detail
 *
 * Use this to wrap calls to the DOM selection and manipulation functions
 * to be sure that the DOM is ready before working on it.
 *
 * @example
 *
 * ready(() => {
 *   // Use other DOM manipulation functions here
 * })
 *
 * @param {function} func Function to register
 */
export declare function ready(func: () => unknown): void;
/**
 * When the DOM is ready, call all of the functions registered
 * using `ready()`.
 *
 * Clears `readyList` to allow for garbage collection of closures.
 *
 * @private
 */
export declare function whenReady(): void;
export declare function first(selector: string): Element | null;
export declare function first(elem: Document | Element, selector: string): Element | null;
export declare function select(selector: string): Element[];
export declare function select(elem: Document | Element, selector: string): Element[];
/**
 * Create a new element.
 *
 * @detail This function allows creation of new elements using either
 * (a) a HTML (or SVG) string (b) a CSS selector like string, or (c) an `Element`.
 * CSS selectors are a convenient way to create elements with attributes,
 * particularly Microdata elements. They can be prone to syntax errors however.
 * Alternatively, the second argument can be an object of attribute name:value pairs.
 *
 * @example <caption>Create a <figure> with id, class and itemtype attributes</caption>
 *
 * create('figure #fig1 .fig :--Figure')
 * // <figure id="fig1" class="fig" itemscope="" itemtype="http://schema.stenci.la/Figure">
 * // </figure>
 *
 * @example <caption>As above but using an object to specify attributes</caption>
 *
 * create('figure', {
 *   id: 'fig1',
 *   class: 'fig',
 *   itemscope: '',
 *   itemtype: translate(':--Figure')
 * })
 *
 * @example <caption>Create a Person with a name property</caption>
 *
 * create(':--Person', create('span :--name', 'John Doe'))
 * // <div itemscope="" itemtype="http://schema.org/Person">
 * //   <span itemprop="name">John Doe</span>
 * // </div>
 *
 * @example <caption>Create a link around an SVG image</caption>
 *
 * create('a', {href: 'https://example.com'}, create(imageSVG))
 * // <a href="https://example.com">
 * //   <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="....
 * // </a>
 *
 * @param {string | Element} [spec] Specification of element to create.
 * @param {(object | undefined | null | boolean | number | string | Element)} [attributes] Attributes for the element.
 * @param {...(undefined | null | boolean | number | string | Element)} children Child nodes to to add as text content or elements.
 * @returns {Element}
 */
export declare function create(spec?: string | Element, attributes?: Record<string, undefined | null | boolean | number | string> | (Record<string, unknown> | undefined | null | boolean | number | string | Element), ...children: (undefined | null | boolean | number | string | Element)[]): Element;
export declare function tag(target: Element): string;
export declare function tag(target: Element, value: string): Element;
export declare function attrs(target: Element): Record<string, string>;
export declare function attrs(target: Element, value: Record<string, unknown>): undefined;
export declare function attr(target: Element, name: string): string;
export declare function attr(target: Element, name: string, value: string): null;
export declare function text(target: Element): string | null;
export declare function text(target: Element, value: string): undefined;
/**
 * Append new child elements to an element.
 *
 * @param {Element} target The element to append to
 * @param {...Element} elems The elements to append
 */
export declare function append(target: Element, ...elems: (undefined | null | boolean | number | string | Element)[]): void;
/**
 * Prepend new child elements to an element.
 *
 * @detail When called with multiple elements to prepend
 * will maintain the order of those elements (at the top
 * of the target element).
 *
 * @param {Element} target The element to prepend to
 * @param {...Element} elems The elements to prepend
 */
export declare function prepend(target: Element, ...elems: Element[]): void;
/**
 * Insert new elements before an element.
 *
 * @param {Element} target The element before which the elements are to be inserted
 * @param {...Element} elems The elements to insert
 */
export declare function before(target: Element, ...elems: Element[]): void;
/**
 * Insert new elements after an element.
 *
 * @param {Element} target The element after which the elements are to be inserted
 * @param {...Element} elems The elements to insert
 */
export declare function after(target: Element, ...elems: Element[]): void;
/**
 * Replace an element with a new element.
 *
 * @param {Element} target The element to replace
 * @param {...Element} elems The elements to replace it with
 */
export declare function replace(target: Element, ...elems: Element[]): void;
/**
 * Wrap an element with a new element.
 *
 * @detail This function can be useful if you need
 * to create a container element to more easily style
 * a type of element.
 *
 * @example <caption>Wrap all figure captions in a <div></caption>
 *
 * select(':--Figure :--caption')
 *   .forEach(caption => wrap(caption, create('div')))
 *
 * @param target The element to wrap
 * @param elem The element to wrap it in
 */
export declare function wrap(target: Element, elem: Element): void;