parse-html-dom 1.0.0

package/lib/character-references.js

@@ -0,0 +1,164 @@
+/**
+ * @module character-references
+ */
+
+import { CHARACTER_REFERENCE_TABLE } from './character-reference-table.js';
+
+const REPLACEMENT_CHARACTER = '�';
+
+// The HTML spec's "numeric character reference end state" remaps this
+// Windows-1252 C1 control range onto Unicode punctuation, because that is
+// what every browser actually does with a numeric reference in this range.
+// A code point in the range with no entry here (0x81, 0x8D, 0x8F, 0x90, 0x9D)
+// is used as-is.
+const WINDOWS_1252_C1_REMAP = new Map([
+    [ 0x80, 0x20AC ],
+    [ 0x82, 0x201A ],
+    [ 0x83, 0x0192 ],
+    [ 0x84, 0x201E ],
+    [ 0x85, 0x2026 ],
+    [ 0x86, 0x2020 ],
+    [ 0x87, 0x2021 ],
+    [ 0x88, 0x02C6 ],
+    [ 0x89, 0x2030 ],
+    [ 0x8A, 0x0160 ],
+    [ 0x8B, 0x2039 ],
+    [ 0x8C, 0x0152 ],
+    [ 0x8E, 0x017D ],
+    [ 0x91, 0x2018 ],
+    [ 0x92, 0x2019 ],
+    [ 0x93, 0x201C ],
+    [ 0x94, 0x201D ],
+    [ 0x95, 0x2022 ],
+    [ 0x96, 0x2013 ],
+    [ 0x97, 0x2014 ],
+    [ 0x98, 0x02DC ],
+    [ 0x99, 0x2122 ],
+    [ 0x9A, 0x0161 ],
+    [ 0x9B, 0x203A ],
+    [ 0x9C, 0x0153 ],
+    [ 0x9E, 0x017E ],
+    [ 0x9F, 0x0178 ],
+]);
+
+function isAsciiAlphanumeric(char) {
+    return /^[A-Za-z0-9]$/.test(char);
+}
+
+function isAsciiDigit(char) {
+    return char >= '0' && char <= '9';
+}
+
+function isAsciiHexDigit(char) {
+    return /^[0-9A-Fa-f]$/.test(char);
+}
+
+function codePointToString(codePoint) {
+    if (codePoint === 0 || (codePoint >= 0xD800 && codePoint <= 0xDFFF) || codePoint > 0x10FFFF) {
+        return REPLACEMENT_CHARACTER;
+    }
+
+    if (codePoint >= 0x80 && codePoint <= 0x9F) {
+        const remapped = WINDOWS_1252_C1_REMAP.get(codePoint);
+        return String.fromCodePoint(remapped === undefined ? codePoint : remapped);
+    }
+
+    return String.fromCodePoint(codePoint);
+}
+
+// Numeric references are required to carry a trailing ";" in this project,
+// matching the named-reference rule below. Returns null when the text at
+// ampersandIndex is not a well-formed "&#...;" reference so the caller can
+// fall back to literal text.
+function decodeNumericReference(text, ampersandIndex) {
+    const isHex = text[ampersandIndex + 2] === 'x' || text[ampersandIndex + 2] === 'X';
+    const digitsStart = ampersandIndex + (isHex ? 3 : 2);
+    const isDigit = isHex ? isAsciiHexDigit : isAsciiDigit;
+
+    let cursor = digitsStart;
+
+    while (cursor < text.length && isDigit(text[cursor])) {
+        cursor += 1;
+    }
+
+    if (cursor === digitsStart || text[cursor] !== ';') {
+        return null;
+    }
+
+    const digits = text.slice(digitsStart, cursor);
+    const codePoint = parseInt(digits, isHex ? 16 : 10);
+
+    return {
+        text: codePointToString(codePoint),
+        nextIndex: cursor + 1,
+    };
+}
+
+// Named references are required to carry a trailing ";" in this project.
+// Every entity name is ASCII alphanumeric, so the run of alphanumeric
+// characters after "&" up to the first ";" is the only possible name
+// boundary — no shorter or longer candidate needs to be tried.
+function decodeNamedReference(text, ampersandIndex) {
+    let cursor = ampersandIndex + 1;
+
+    while (cursor < text.length && isAsciiAlphanumeric(text[cursor])) {
+        cursor += 1;
+    }
+
+    if (text[cursor] !== ';') {
+        return null;
+    }
+
+    const name = text.slice(ampersandIndex + 1, cursor + 1);
+    const replacement = CHARACTER_REFERENCE_TABLE[name];
+
+    if (replacement === undefined) {
+        return null;
+    }
+
+    return {
+        text: replacement,
+        nextIndex: cursor + 1,
+    };
+}
+
+/**
+ * Decodes HTML character references (named, decimal, and hexadecimal) in a
+ * string of text. A malformed or unknown reference is left as literal text
+ * rather than raising an error, matching how a browser recovers from one.
+ * @param {string} text - Text that may contain character references.
+ * @returns {string} The text with every well-formed reference replaced.
+ */
+export function decodeCharacterReferences(text) {
+    if (!text.includes('&')) {
+        return text;
+    }
+
+    let result = '';
+    let index = 0;
+
+    while (index < text.length) {
+        const ampersandIndex = text.indexOf('&', index);
+
+        if (ampersandIndex === -1) {
+            result += text.slice(index);
+            break;
+        }
+
+        result += text.slice(index, ampersandIndex);
+
+        const decoded = text[ampersandIndex + 1] === '#'
+            ? decodeNumericReference(text, ampersandIndex)
+            : decodeNamedReference(text, ampersandIndex);
+
+        if (decoded) {
+            result += decoded.text;
+            index = decoded.nextIndex;
+        } else {
+            result += '&';
+            index = ampersandIndex + 1;
+        }
+    }
+
+    return result;
+}

package/lib/document.js

@@ -0,0 +1,125 @@
+/**
+ * @module document
+ */
+
+import { ParentNode } from './node.js';
+
+/**
+ * @typedef {Object} DocumentType
+ * @property {string} name - The doctype name, lowercased.
+ * @property {string|null} publicId - The public identifier, or `null`.
+ * @property {string|null} systemId - The system identifier, or `null`.
+ */
+
+/**
+ * @typedef {Object} ParseError
+ * @property {string} code - A stable, kebab-case error identifier. Adding a
+ *   code is a compatible change; renaming one is a breaking change.
+ * @property {string} message - A human-readable description.
+ * @property {number} offset - 0-based index into the preprocessed source.
+ * @property {number} line - 1-based line number.
+ * @property {number} column - 1-based column number.
+ */
+
+/**
+ * The root of a parsed document. Construction is internal to this package —
+ * `parseHTML` is the supported way to obtain one — but the class is
+ * exported so callers can use `instanceof Document`.
+ *
+ * `documentElement`, `head`, and `body` are always non-null: `parseHTML`
+ * synthesizes them even for empty input, so callers never need to guard
+ * against a missing one.
+ */
+export class Document extends ParentNode {
+    #documentElement = null;
+    #head = null;
+    #body = null;
+    #doctype = null;
+    #parseErrors = Object.freeze([]);
+
+    constructor() {
+        super(9);
+    }
+
+    /**
+     * @returns {string} Always `'#document'`.
+     */
+    get nodeName() {
+        return '#document';
+    }
+
+    /**
+     * @returns {Element} The root `<html>` element.
+     */
+    get documentElement() {
+        return this.#documentElement;
+    }
+
+    /**
+     * @returns {Element} The `<head>` element.
+     */
+    get head() {
+        return this.#head;
+    }
+
+    /**
+     * @returns {Element} The `<body>` element.
+     */
+    get body() {
+        return this.#body;
+    }
+
+    /**
+     * @returns {DocumentType|null} The doctype, or `null` when the source
+     *   had none. Not a node: it is not in `childNodes` or `children`.
+     */
+    get doctype() {
+        return this.#doctype;
+    }
+
+    /**
+     * @returns {ParseError[]} Every recovery the parser performed, in
+     *   source order. Empty for a clean document.
+     */
+    get parseErrors() {
+        return this.#parseErrors;
+    }
+
+    /**
+     * @returns {Element[]} Always `[documentElement]` once parsing has set
+     *   it, otherwise an empty array.
+     */
+    get children() {
+        return this.#documentElement ? Object.freeze([ this.#documentElement ]) : Object.freeze([]);
+    }
+
+    // Internal: called only by the tree builder while assembling the
+    // document.
+    setDocumentElement(element) {
+        this.#documentElement = element;
+    }
+
+    // Internal: called only by the tree builder while assembling the
+    // document.
+    setHead(element) {
+        this.#head = element;
+    }
+
+    // Internal: called only by the tree builder while assembling the
+    // document.
+    setBody(element) {
+        this.#body = element;
+    }
+
+    // Internal: called only by the tree builder while assembling the
+    // document.
+    setDoctype(doctype) {
+        this.#doctype = doctype ? Object.freeze(doctype) : null;
+    }
+
+    // Internal: called only by the tree builder once parsing has finished
+    // collecting errors.
+    setParseErrors(errors) {
+        this.#parseErrors = Object.freeze(errors);
+    }
+}

package/lib/element.js

@@ -0,0 +1,258 @@
+/**
+ * @module element
+ */
+
+import { ParentNode } from './node.js';
+import { serializeInnerHTML, serializeOuterHTML } from './serialize.js';
+import { closest as findClosest } from './selector-matcher.js';
+
+// Frozen {name, value} pairs, exposed through the array-like `attributes`
+// getter below. Index access and Symbol.iterator are implemented with own
+// numeric properties rather than extending Array, since an Array instance
+// also carries push/splice/etc. that would misleadingly suggest the list
+// can be mutated.
+class AttributeList {
+    constructor(entries) {
+        entries.forEach((entry, index) => {
+            this[index] = entry;
+        });
+        this.length = entries.length;
+    }
+
+    /**
+     * @param {string} name - Attribute name to find.
+     * @returns {{name: string, value: string}|null} The matching entry, or
+     *   `null` when no attribute has this name.
+     */
+    getNamedItem(name) {
+        for (let index = 0; index < this.length; index += 1) {
+            if (this[index].name === name) {
+                return this[index];
+            }
+        }
+        return null;
+    }
+
+    [Symbol.iterator]() {
+        let index = 0;
+        const { length } = this;
+        const list = this;
+
+        return {
+            next() {
+                if (index >= length) {
+                    return { value: undefined, done: true };
+                }
+                const value = list[index];
+                index += 1;
+                return { value, done: false };
+            },
+        };
+    }
+}
+
+// A read-only DOMTokenList-alike over an attribute's whitespace-separated
+// value. Tokens are deduplicated preserving first occurrence, per the DOM's
+// ordered-set parser, so `class="a a"` has length 1 while `value` keeps the
+// raw string `'a a'`.
+class ClassList {
+    #tokens;
+    #value;
+
+    constructor(value) {
+        this.#value = value;
+
+        const seen = new Set();
+        this.#tokens = [];
+
+        for (const token of value.split(/\s+/u).filter(Boolean)) {
+            if (!seen.has(token)) {
+                seen.add(token);
+                this.#tokens.push(token);
+            }
+        }
+
+        this.#tokens.forEach((token, index) => {
+            this[index] = token;
+        });
+        this.length = this.#tokens.length;
+    }
+
+    /**
+     * @returns {string} The raw, undeduplicated attribute value.
+     */
+    get value() {
+        return this.#value;
+    }
+
+    /**
+     * @param {string} token - Class name to test for.
+     * @returns {boolean} Whether `token` is present.
+     */
+    contains(token) {
+        return this.#tokens.includes(token);
+    }
+
+    [Symbol.iterator]() {
+        return this.#tokens[Symbol.iterator]();
+    }
+}
+
+/**
+ * An element node. Construction is internal to this package — `parseHTML`
+ * is the supported way to obtain one — but the class is exported so callers
+ * can use `instanceof Element`.
+ */
+export class Element extends ParentNode {
+    #localName;
+    #rawName;
+    #isForeign;
+    #attributesArray;
+    #attributesMap;
+    #attributeList = null;
+    #classList = null;
+
+    /**
+     * @param {string} localName - Lowercase element name.
+     * @param {string} rawName - Element name as the author wrote it.
+     * @param {{name: string, rawName: string, value: string}[]} attributes -
+     *   Attributes in source order. Names are already lowercase.
+     * @param {boolean} isForeign - Whether this element is inside an `svg`
+     *   or `math` subtree.
+     */
+    constructor(localName, rawName, attributes, isForeign) {
+        super(1);
+        this.#localName = localName;
+        this.#rawName = rawName;
+        this.#isForeign = isForeign;
+        this.#attributesArray = attributes;
+        this.#attributesMap = new Map(attributes.map((attr) => [ attr.name, attr.value ]));
+    }
+
+    /**
+     * @returns {string} Same value as `tagName`, matching the DOM's
+     *   `Element.nodeName`.
+     */
+    get nodeName() {
+        return this.tagName;
+    }
+
+    /**
+     * @returns {string} The lowercase element name.
+     */
+    get localName() {
+        return this.#localName;
+    }
+
+    /**
+     * @returns {string} The element name exactly as the author wrote it.
+     */
+    get rawName() {
+        return this.#rawName;
+    }
+
+    /**
+     * @returns {boolean} Whether this element is inside an `svg` or `math`
+     *   subtree.
+     */
+    get isForeign() {
+        return this.#isForeign;
+    }
+
+    /**
+     * @returns {string} `rawName` for a foreign element (so `svg` reports
+     *   `'svg'` and `clipPath` reports `'clipPath'`), otherwise the
+     *   uppercased local name.
+     */
+    get tagName() {
+        return this.#isForeign ? this.#rawName : this.#localName.toUpperCase();
+    }
+
+    /**
+     * @returns {string} The `id` attribute's value, or `''` when absent.
+     */
+    get id() {
+        const value = this.getAttribute('id');
+        return value === null ? '' : value;
+    }
+
+    /**
+     * @param {string} name - Attribute name, matched case-insensitively.
+     * @returns {string|null} The attribute's value, or `null` when absent.
+     */
+    getAttribute(name) {
+        const value = this.#attributesMap.get(name.toLowerCase());
+        return value === undefined ? null : value;
+    }
+
+    /**
+     * @param {string} name - Attribute name, matched case-insensitively.
+     * @returns {boolean} Whether the attribute is present.
+     */
+    hasAttribute(name) {
+        return this.#attributesMap.has(name.toLowerCase());
+    }
+
+    /**
+     * @returns {string[]} Attribute names in source order.
+     */
+    getAttributeNames() {
+        return Object.freeze(this.#attributesArray.map((attr) => attr.name));
+    }
+
+    /**
+     * @returns {AttributeList} A frozen, iterable, array-like collection of
+     *   `{name, value}` entries in source order.
+     */
+    get attributes() {
+        if (!this.#attributeList) {
+            const entries = this.#attributesArray.map((attr) => Object.freeze({ name: attr.name, value: attr.value }));
+            this.#attributeList = Object.freeze(new AttributeList(entries));
+        }
+        return this.#attributeList;
+    }
+
+    /**
+     * @returns {ClassList} A read-only, iterable, array-like view of the
+     *   `class` attribute's tokens.
+     */
+    get classList() {
+        if (!this.#classList) {
+            this.#classList = Object.freeze(new ClassList(this.getAttribute('class') ?? ''));
+        }
+        return this.#classList;
+    }
+
+    /**
+     * @returns {string} HTML for this element's children only.
+     */
+    get innerHTML() {
+        return serializeInnerHTML(this);
+    }
+
+    /**
+     * @returns {string} HTML for this element, including its own tags.
+     */
+    get outerHTML() {
+        return serializeOuterHTML(this);
+    }
+
+    /**
+     * @param {string} selector - A CSS selector.
+     * @returns {Element|null} This element if it matches `selector`,
+     *   otherwise the nearest matching ancestor, stopping at
+     *   `documentElement`. `null` when nothing matches.
+     * @throws {SelectorSyntaxError} When `selector` is invalid.
+     */
+    closest(selector) {
+        return findClosest(this, selector);
+    }
+
+    // Internal: called only by serialize.js. The public `attributes` getter
+    // and `getAttributeNames()` intentionally hide rawName casing behind
+    // lowercase names; serialization is the one place that needs it back,
+    // to reproduce an author's "viewBox" rather than "viewbox".
+    getAttributesForSerialization() {
+        return this.#attributesArray;
+    }
+}

package/lib/html-tags.js

@@ -0,0 +1,129 @@
+/**
+ * @module html-tags
+ *
+ * Lookup tables that classify HTML element names. Every table is keyed (or,
+ * for the auto-close table, valued) by lowercase element name. Consumers must
+ * not mutate the exported `Set` and `Map` instances; ES module bindings keep
+ * the exported names themselves from being reassigned, but the collections
+ * are ordinary mutable objects by convention only.
+ */
+
+/**
+ * Elements that never have children and never have an end tag.
+ * @type {Set<string>}
+ */
+export const VOID_ELEMENTS = new Set([
+    'area',
+    'base',
+    'br',
+    'col',
+    'embed',
+    'hr',
+    'img',
+    'input',
+    'link',
+    'meta',
+    'source',
+    'track',
+    'wbr',
+]);
+
+/**
+ * Elements whose content is raw text: no tags and no character references
+ * are recognized inside.
+ * @type {Set<string>}
+ */
+export const RAW_TEXT_ELEMENTS = new Set([
+    'script',
+    'style',
+]);
+
+/**
+ * Elements whose content is RCDATA: character references are recognized,
+ * tags are not.
+ * @type {Set<string>}
+ */
+export const RCDATA_ELEMENTS = new Set([
+    'title',
+    'textarea',
+]);
+
+/**
+ * Elements that root a foreign-content subtree.
+ * @type {Set<string>}
+ */
+export const FOREIGN_ROOT_ELEMENTS = new Set([
+    'svg',
+    'math',
+]);
+
+/**
+ * Elements that belong in the implied `<head>` while it is still open.
+ * @type {Set<string>}
+ */
+export const HEAD_ELEMENTS = new Set([
+    'base',
+    'link',
+    'meta',
+    'noscript',
+    'script',
+    'style',
+    'template',
+    'title',
+]);
+
+/**
+ * Maps an open element's name to the set of start tag names that close it.
+ * Read an entry as: "if this element is open and one of these start tags
+ * arrives, close it first." The tree builder applies this repeatedly so
+ * nested cases unwind correctly.
+ * @type {Map<string, Set<string>>}
+ */
+export const AUTO_CLOSED_BY = new Map([
+    [ 'p', new Set([
+        'address',
+        'article',
+        'aside',
+        'blockquote',
+        'details',
+        'div',
+        'dl',
+        'fieldset',
+        'figcaption',
+        'figure',
+        'footer',
+        'form',
+        'h1',
+        'h2',
+        'h3',
+        'h4',
+        'h5',
+        'h6',
+        'header',
+        'hgroup',
+        'hr',
+        'main',
+        'menu',
+        'nav',
+        'ol',
+        'p',
+        'pre',
+        'section',
+        'table',
+        'ul',
+    ]) ],
+    [ 'li', new Set([ 'li' ]) ],
+    [ 'dt', new Set([ 'dt', 'dd' ]) ],
+    [ 'dd', new Set([ 'dt', 'dd' ]) ],
+    [ 'option', new Set([ 'option', 'optgroup' ]) ],
+    [ 'optgroup', new Set([ 'optgroup' ]) ],
+    [ 'tr', new Set([ 'tr' ]) ],
+    [ 'td', new Set([ 'td', 'th', 'tr' ]) ],
+    [ 'th', new Set([ 'td', 'th', 'tr' ]) ],
+    [ 'thead', new Set([ 'tbody', 'tfoot' ]) ],
+    [ 'tbody', new Set([ 'tbody', 'tfoot' ]) ],
+    [ 'caption', new Set([ 'thead', 'tbody', 'tfoot', 'tr' ]) ],
+    [ 'colgroup', new Set([ 'thead', 'tbody', 'tfoot', 'tr' ]) ],
+    [ 'rt', new Set([ 'rt', 'rp' ]) ],
+    [ 'rp', new Set([ 'rt', 'rp' ]) ],
+]);