• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1import type { DOCUMENT_MODE, NS } from '../common/html.js';
2import type { Attribute, ElementLocation } from '../common/token.js';
3
4export interface TreeAdapterTypeMap<
5    Node = unknown,
6    ParentNode = unknown,
7    ChildNode = unknown,
8    Document = unknown,
9    DocumentFragment = unknown,
10    Element = unknown,
11    CommentNode = unknown,
12    TextNode = unknown,
13    Template = unknown,
14    DocumentType = unknown
15> {
16    node: Node;
17    parentNode: ParentNode;
18    childNode: ChildNode;
19    document: Document;
20    documentFragment: DocumentFragment;
21    element: Element;
22    commentNode: CommentNode;
23    textNode: TextNode;
24    template: Template;
25    documentType: DocumentType;
26}
27
28/**
29 * Tree adapter is a set of utility functions that provides minimal required abstraction layer beetween parser and a specific AST format.
30 * Note that `TreeAdapter` is not designed to be a general purpose AST manipulation library. You can build such library
31 * on top of existing `TreeAdapter` or use one of the existing libraries from npm.
32 *
33 * @see The default implementation {@link parse5.treeAdapters.default}
34 */
35export interface TreeAdapter<T extends TreeAdapterTypeMap = TreeAdapterTypeMap> {
36    /**
37     * Copies attributes to the given element. Only attributes that are not yet present in the element are copied.
38     *
39     * @param recipient - Element to copy attributes into.
40     * @param attrs - Attributes to copy.
41     */
42    adoptAttributes(recipient: T['element'], attrs: Attribute[]): void;
43
44    /**
45     * Appends a child node to the given parent node.
46     *
47     * @param parentNode - Parent node.
48     * @param newNode -  Child node.
49     */
50    appendChild(parentNode: T['parentNode'], newNode: T['childNode']): void;
51
52    /**
53     * Creates a comment node.
54     *
55     * @param data - Comment text.
56     */
57    createCommentNode(data: string): T['commentNode'];
58
59    /**
60     * Creates a document node.
61     */
62    createDocument(): T['document'];
63
64    /**
65     * Creates a document fragment node.
66     */
67    createDocumentFragment(): T['documentFragment'];
68
69    /**
70     * Creates an element node.
71     *
72     * @param tagName - Tag name of the element.
73     * @param namespaceURI - Namespace of the element.
74     * @param attrs - Attribute name-value pair array. Foreign attributes may contain `namespace` and `prefix` fields as well.
75     */
76    createElement(tagName: string, namespaceURI: NS, attrs: Attribute[]): T['element'];
77
78    /**
79     * Removes a node from its parent.
80     *
81     * @param node - Node to remove.
82     */
83    detachNode(node: T['childNode']): void;
84
85    /**
86     * Returns the given element's attributes in an array, in the form of name-value pairs.
87     * Foreign attributes may contain `namespace` and `prefix` fields as well.
88     *
89     * @param element - Element.
90     */
91    getAttrList(element: T['element']): Attribute[];
92
93    /**
94     * Returns the given node's children in an array.
95     *
96     * @param node - Node.
97     */
98    getChildNodes(node: T['parentNode']): T['childNode'][];
99
100    /**
101     * Returns the given comment node's content.
102     *
103     * @param commentNode - Comment node.
104     */
105    getCommentNodeContent(commentNode: T['commentNode']): string;
106
107    /**
108     * Returns [document mode](https://dom.spec.whatwg.org/#concept-document-limited-quirks).
109     *
110     * @param document - Document node.
111     */
112    getDocumentMode(document: T['document']): DOCUMENT_MODE;
113
114    /**
115     * Returns the given document type node's name.
116     *
117     * @param doctypeNode - Document type node.
118     */
119    getDocumentTypeNodeName(doctypeNode: T['documentType']): string;
120
121    /**
122     * Returns the given document type node's public identifier.
123     *
124     * @param doctypeNode - Document type node.
125     */
126    getDocumentTypeNodePublicId(doctypeNode: T['documentType']): string;
127
128    /**
129     * Returns the given document type node's system identifier.
130     *
131     * @param doctypeNode - Document type node.
132     */
133    getDocumentTypeNodeSystemId(doctypeNode: T['documentType']): string;
134
135    /**
136     * Returns the first child of the given node.
137     *
138     * @param node - Node.
139     */
140    getFirstChild(node: T['parentNode']): T['childNode'] | null;
141
142    /**
143     * Returns the given element's namespace.
144     *
145     * @param element - Element.
146     */
147    getNamespaceURI(element: T['element']): NS;
148
149    /**
150     * Returns the given node's source code location information.
151     *
152     * @param node - Node.
153     */
154    getNodeSourceCodeLocation(node: T['node']): ElementLocation | undefined | null;
155
156    /**
157     * Returns the given node's parent.
158     *
159     * @param node - Node.
160     */
161    getParentNode(node: T['node']): T['parentNode'] | null;
162
163    /**
164     * Returns the given element's tag name.
165     *
166     * @param element - Element.
167     */
168    getTagName(element: T['element']): string;
169
170    /**
171     * Returns the given text node's content.
172     *
173     * @param textNode - Text node.
174     */
175    getTextNodeContent(textNode: T['textNode']): string;
176
177    /**
178     * Returns the `<template>` element content element.
179     *
180     * @param templateElement - `<template>` element.
181     */
182    getTemplateContent(templateElement: T['template']): T['documentFragment'];
183
184    /**
185     * Inserts a child node to the given parent node before the given reference node.
186     *
187     * @param parentNode - Parent node.
188     * @param newNode -  Child node.
189     * @param referenceNode -  Reference node.
190     */
191    insertBefore(parentNode: T['parentNode'], newNode: T['childNode'], referenceNode: T['childNode']): void;
192
193    /**
194     * Inserts text into a node. If the last child of the node is a text node, the provided text will be appended to the
195     * text node content. Otherwise, inserts a new text node with the given text.
196     *
197     * @param parentNode - Node to insert text into.
198     * @param text - Text to insert.
199     */
200    insertText(parentNode: T['parentNode'], text: string): void;
201
202    /**
203     * Inserts text into a sibling node that goes before the reference node. If this sibling node is the text node,
204     * the provided text will be appended to the text node content. Otherwise, inserts a new sibling text node with
205     * the given text before the reference node.
206     *
207     * @param parentNode - Node to insert text into.
208     * @param text - Text to insert.
209     * @param referenceNode - Node to insert text before.
210     */
211    insertTextBefore(parentNode: T['parentNode'], text: string, referenceNode: T['childNode']): void;
212
213    /**
214     * Determines if the given node is a comment node.
215     *
216     * @param node - Node.
217     */
218    isCommentNode(node: T['node']): node is T['commentNode'];
219
220    /**
221     * Determines if the given node is a document type node.
222     *
223     * @param node - Node.
224     */
225    isDocumentTypeNode(node: T['node']): node is T['documentType'];
226
227    /**
228     * Determines if the given node is an element.
229     *
230     * @param node - Node.
231     */
232    isElementNode(node: T['node']): node is T['element'];
233
234    /**
235     * Determines if the given node is a text node.
236     *
237     * @param node - Node.
238     */
239    isTextNode(node: T['node']): node is T['textNode'];
240
241    /**
242     * Sets the [document mode](https://dom.spec.whatwg.org/#concept-document-limited-quirks).
243     *
244     * @param document - Document node.
245     * @param mode - Document mode.
246     */
247    setDocumentMode(document: T['document'], mode: DOCUMENT_MODE): void;
248
249    /**
250     * Sets the document type. If the `document` already contains a document type node, the `name`, `publicId` and `systemId`
251     * properties of this node will be updated with the provided values. Otherwise, creates a new document type node
252     * with the given properties and inserts it into the `document`.
253     *
254     * @param document - Document node.
255     * @param name -  Document type name.
256     * @param publicId - Document type public identifier.
257     * @param systemId - Document type system identifier.
258     */
259    setDocumentType(document: T['document'], name: string, publicId: string, systemId: string): void;
260
261    /**
262     * Attaches source code location information to the node.
263     *
264     * @param node - Node.
265     */
266    setNodeSourceCodeLocation(node: T['node'], location: ElementLocation | null): void;
267
268    /**
269     * Updates the source code location information of the node.
270     *
271     * @param node - Node.
272     */
273    updateNodeSourceCodeLocation(node: T['node'], location: Partial<ElementLocation>): void;
274
275    /**
276     * Sets the `<template>` element content element.
277     *
278     * @param templateElement - `<template>` element.
279     * @param contentElement -  Content element.
280     */
281    setTemplateContent(templateElement: T['template'], contentElement: T['documentFragment']): void;
282
283    /**
284     * Optional callback for elements being pushed to the stack of open elements.
285     *
286     * @param element The element being pushed to the stack of open elements.
287     */
288    onItemPush?: (item: T['element']) => void;
289
290    /**
291     * Optional callback for elements being popped from the stack of open elements.
292     *
293     * @param item The element being popped.
294     */
295    onItemPop?: (item: T['element'], newTop: T['parentNode']) => void;
296}
297