[add] DOM Reference callback property

[optimize] merge VNode interface & VDOMNode class
[optimize] Type & Logic details of VDOM & JSX

Author: TechQuery

package.json

@@ -1,6 +1,6 @@
 {
     "name": "dom-renderer",
-    "version": "2.0.0-rc.4",
+    "version": "2.0.0-rc.5",
     "license": "LGPL-3.0-or-later",
     "author": "[email protected]",
     "description": "A light-weight DOM Renderer supports Web components standard & TypeScript language",
@@ -35,7 +35,7 @@
         "jest-environment-jsdom": "^29.6.2",
         "lint-staged": "^13.2.3",
         "open-cli": "^7.2.0",
-        "prettier": "^3.0.0",
+        "prettier": "^3.0.1",
         "ts-jest": "^29.1.1",
         "typedoc": "^0.24.8",
         "typedoc-plugin-mdn-links": "^3.0.3",

pnpm-lock.yaml

@@ -8,17 +8,21 @@ import {
     toHyphenCase
 } from 'web-utility';
 
-import { DataObject, VDOMNode, VNode } from './VDOM';
+import { DataObject, VNode } from './VDOM';
 
 export class DOMRenderer {
     eventPattern = /^on[A-Z]/;
     ariaPattern = /^aira[A-Z]/;
 
+    protected treeCache = new WeakMap<Node, VNode>();
+
     protected keyOf = ({ key, text, props, selector }: VNode, index?: number) =>
-        key || props?.id || text || (selector && selector + index);
+        key?.toString() || props?.id || text || (selector && selector + index);
 
-    protected vNodeOf = (list: VNode[], key: string) =>
-        list.find((vNode, index) => this.keyOf(vNode, index) + '' === key);
+    protected vNodeOf = (list: VNode[], key?: VNode['key']) =>
+        list.find(
+            (vNode, index) => `${this.keyOf(vNode, index)}` === String(key)
+        );
 
     protected propsKeyOf = (key: string) =>
         key.startsWith('aria-')
@@ -27,12 +31,12 @@ export class DOMRenderer {
             ? key.toLowerCase()
             : key;
 
-    protected updateProps<T extends DataObject>(
-        node: T,
-        oldProps: DataObject = {},
-        newProps: DataObject = {},
-        onDelete?: (node: T, key: string) => any,
-        onAdd?: (node: T, key: string, value: any) => any
+    protected updateProps<N extends DataObject, P extends DataObject>(
+        node: N,
+        oldProps = {} as P,
+        newProps = {} as P,
+        onDelete?: (node: N, key: string) => any,
+        onAdd?: (node: N, key: string, value: any) => any
     ) {
         const { group } = diffKeys(
             Object.keys(oldProps),
@@ -58,8 +62,19 @@ export class DOMRenderer {
             ? document.createElement(vNode.tagName, { is: vNode.is })
             : document.createDocumentFragment();
 
-        return this.patch({ tagName: vNode.tagName, node: vNode.node }, vNode)
-            .node;
+        const { node } = this.patch(
+            { tagName: vNode.tagName, node: vNode.node },
+            vNode
+        );
+        if (node) vNode.ref?.(node);
+
+        return node;
+    }
+
+    deleteNode({ node, children }: VNode) {
+        if (node instanceof DocumentFragment)
+            children?.forEach(this.deleteNode);
+        else (node as ChildNode)?.remove();
     }
 
     protected updateChildren(
@@ -73,7 +88,7 @@ export class DOMRenderer {
         );
 
         for (const [key] of group[DiffStatus.Old] || [])
-            (this.vNodeOf(oldList, key)?.node as ChildNode)?.remove();
+            this.deleteNode(this.vNodeOf(oldList, key));
 
         const newNodes = newList.map((vNode, index) => {
             const key = this.keyOf(vNode, index);
@@ -101,7 +116,7 @@ export class DOMRenderer {
                     : node.removeAttribute(
                           this.ariaPattern.test(key)
                               ? toHyphenCase(key)
-                              : VDOMNode.propsMap[key] || key
+                              : VNode.propsMap[key] || key
                       ),
             (node, key, value) => {
                 // @ts-ignore
@@ -127,9 +142,13 @@ export class DOMRenderer {
     }
 
     render(vNode: VNode, node: Element = document.body) {
-        const root = new VDOMNode(node);
+        var root = this.treeCache.get(node) || VNode.fromDOM(node);
+
+        root = this.patch(root, { ...root, children: [vNode] });
+
+        this.treeCache.set(node, root);
 
-        return this.patch(root, { ...root, children: [vNode] });
+        return root;
     }
 
     renderToStaticMarkup(tree: VNode) {

source/dist/DOMRenderer.ts

@@ -2,85 +2,91 @@ import { HTMLProps, IndexKey } from 'web-utility';
 
 export type DataObject = Record<string, any>;
 
-export interface VNode {
+export class VNode {
     key?: IndexKey;
+    ref?: (node: Node) => any;
     text?: string;
     selector?: string;
     tagName?: string;
     is?: string;
     props?: DataObject;
-    style?: DataObject;
+    style?: HTMLProps<HTMLElement>['style'];
     children?: VNode[];
     node?: Node;
-}
 
-export class VDOMNode implements VNode {
-    text?: string;
-    tagName?: string;
-    is?: string;
-    props?: DataObject;
-    style?: DataObject;
-    children?: VNode[];
+    constructor(meta: VNode) {
+        Object.assign(this, meta);
+
+        const { tagName, is, props } = meta;
+
+        if (!tagName && !props?.className && !is) return;
 
-    static selectorOf = (tagName: string, is?: string, className?: string) =>
-        [
-            tagName.toLowerCase(),
-            className && `.${className.trim().replace(/\s+/, '.')}`,
+        this.selector = [
+            tagName?.toLowerCase(),
+            props?.className &&
+                `.${props.className.trim().replace(/\s+/, '.')}`,
             is && `[is="${is}"]`
         ]
             .filter(Boolean)
             .join('');
-
-    get selector() {
-        const { tagName, is, props } = this;
-
-        return tagName && VDOMNode.selectorOf(tagName, is, props?.className);
     }
 
-    static propsMap: DataObject = { className: 'class', htmlFor: 'for' };
+    static propsMap: Partial<
+        Record<keyof HTMLProps<HTMLLabelElement>, string>
+    > = {
+        className: 'class',
+        htmlFor: 'for'
+    };
 
-    static attrsMap = Object.fromEntries(
-        Object.entries(this.propsMap).map(item => item.reverse())
-    );
+    static attrsMap: Record<string, keyof HTMLProps<HTMLLabelElement>> =
+        Object.fromEntries(
+            Object.entries(this.propsMap).map(item => item.reverse())
+        );
 
-    constructor(public node: Node) {
-        if (node instanceof Text) {
-            this.text = node.nodeValue;
-            return;
-        }
-        if (!(node instanceof Element)) return;
-
-        const { tagName, attributes, style, childNodes } = node as HTMLElement;
+    static fromDOM(node: Node) {
+        if (node instanceof Text)
+            return new VNode({ node, text: node.nodeValue });
 
-        this.tagName = tagName.toLowerCase();
-        this.is = node.getAttribute('is');
+        if (!(node instanceof Element)) return new VNode({ node });
 
+        const { tagName, attributes, style, childNodes } = node as HTMLElement;
+        const vNode: VNode = {
+            node,
+            tagName: tagName.toLowerCase(),
+            is: node.getAttribute('is')
+        };
         const props = Array.from(
             attributes,
             ({ name, value }) =>
-                name !== 'style' && [VDOMNode.attrsMap[name] || name, value]
+                name !== 'style' && [this.attrsMap[name] || name, value]
         ).filter(Boolean);
 
-        if (props[0]) this.props = Object.fromEntries(props);
+        if (props[0]) vNode.props = Object.fromEntries(props);
 
         const styles = Array.from(style, key => [key, style[key]]);
 
-        if (styles[0]) this.style = Object.fromEntries(styles);
+        if (styles[0]) vNode.style = Object.fromEntries(styles);
+
+        const children = Array.from(childNodes, node => VNode.fromDOM(node));
 
-        const children = Array.from(childNodes, node => new VDOMNode(node));
+        if (children[0]) vNode.children = children;
 
-        if (children[0]) this.children = children;
+        return new VNode(vNode);
     }
 }
 
 declare global {
+    /**
+     * @see {@link https://www.typescriptlang.org/docs/handbook/jsx.html}
+     */
     namespace JSX {
         type Element = VNode;
 
         type IntrinsicElements = {
             [tagName in keyof HTMLElementTagNameMap]: HTMLProps<
                 HTMLElementTagNameMap[tagName]
-            >;
+            > &
+                Pick<VNode, 'is' | 'key' | 'ref'>;
         };
     }
 }

source/dist/VDOM.ts

@@ -1,14 +1,14 @@
 import { IndexKey, isHTMLElementClass, tagNameOf } from 'web-utility';
 
-import { DataObject, VDOMNode, VNode } from './dist/VDOM';
+import { DataObject, VNode } from './dist/VDOM';
 
 /**
  * @see {@link https://github.com/reactjs/rfcs/blob/createlement-rfc/text/0000-create-element-changes.md}
  * @see {@link https://babeljs.io/docs/babel-plugin-transform-react-jsx}
  */
 export function jsx(
     type: string | Function,
-    { is, style, children, ...props }: DataObject,
+    { ref, is, style, children, ...props }: DataObject,
     key?: IndexKey
 ): VNode {
     if (typeof type === 'function' && isHTMLElementClass(type))
@@ -20,20 +20,14 @@ export function jsx(
         node instanceof Object
             ? node
             : node === 0 || node
-            ? { text: node + '' }
-            : { text: '' }
+            ? new VNode({ text: node.toString() })
+            : new VNode({ text: '' })
     );
+    const commonProps: VNode = { key, ref, is, style, children };
+
     return typeof type === 'string'
-        ? {
-              key,
-              selector: VDOMNode.selectorOf(type, is, props.className),
-              tagName: type,
-              is,
-              props,
-              style,
-              children
-          }
-        : type({ is, style, children, ...props });
+        ? new VNode({ ...commonProps, tagName: type, props })
+        : type({ ...commonProps, ...props });
 }
 
 export const jsxs = jsx;
@@ -42,11 +36,11 @@ export const jsxs = jsx;
  * @see {@link https://babeljs.io/docs/babel-plugin-transform-react-jsx#react-automatic-runtime-1}
  */
 export const Fragment = ({
+    key,
+    ref,
+    is,
     style,
     children,
     ...props
-}: VNode['props'] & Pick<VNode, 'style' | 'children'>): VNode => ({
-    props,
-    style,
-    children
-});
+}: VNode['props'] & Omit<VNode, 'props'>) =>
+    new VNode({ key, ref, is, props, style, children });

source/jsx-runtime.ts

@@ -1,4 +1,4 @@
-import { DOMRenderer, VDOMNode, VNode } from '../source/dist';
+import { DOMRenderer, VNode } from '../source/dist';
 
 describe('DOM Renderer', () => {
     const renderer = new DOMRenderer(),
@@ -23,7 +23,7 @@ describe('DOM Renderer', () => {
     it('should update DOM styles', () => {
         const newVNode = renderer.patch(root, {
             ...root,
-            style: { margin: 0 }
+            style: { margin: '0' }
         });
         expect(document.body.style.margin).toBe('0px');
 
@@ -53,7 +53,7 @@ describe('DOM Renderer', () => {
     });
 
     it('should transfer a DOM node to a Virtual DOM node', () => {
-        const { tagName, selector, node } = new VDOMNode(document.body);
+        const { tagName, selector, node } = VNode.fromDOM(document.body);
 
         expect({ tagName, selector, node }).toEqual(root);
     });

test/DOMRenderer.spec.ts

@@ -91,6 +91,16 @@ describe('JSX runtime', () => {
         expect(onClick).toBeCalledTimes(1);
     });
 
+    it('should pass a real DOM Node by a callback', () => {
+        const ref = jest.fn();
+
+        renderer.render(jsx('b', { ref }));
+
+        expect(document.body.innerHTML).toBe('<b></b>');
+
+        expect(ref).toBeCalledWith(document.body.firstChild);
+    });
+
     it('should render to a Static String', () => {
         expect(renderer.renderToStaticMarkup(jsx('i', {}))).toBe('<i></i>');
     });