@viewfly/platform-browser 2.0.2 → 2.2.0

package/README.md

@@ -1,58 +1,55 @@
-Viewfly
-================================
+# @viewfly/platform-browser
 
-Viewfly 是一个简单、数据驱动的前端框架。此项目为内核运行在浏览器上的支持层。
+在**浏览器**中运行 Viewfly 应用的入口包：提供根应用的创建、挂载、销毁，以及子应用（`fork`）、Portal 等与 DOM 相关的能力。
+
+使用前请已安装并配置好 **`@viewfly/core`**（含 JSX 与 `reflect-metadata` 等约定）。
+
+---
 
 ## 安装
 
-```
-npm install @viewfly/platform-browser
+```bash
+pnpm add @viewfly/platform-browser @viewfly/core
 ```
 
-## API
+---
 
-### createApp()
+## 创建并挂载应用
 
-createApp 用于创建一个独立的应用。
+在 HTML 中准备挂载点，例如：
 
-```js
+```html
+<div id="app"></div>
+```
+
+在脚本中：
+
+```tsx
 import { createApp } from '@viewfly/platform-browser'
 
 function App() {
-  return () => {
-    return <div>App!</div>
-  }
+  return () => <div>Hello Viewfly</div>
 }
 
-const app = createApp(<App/>)
-app.mount(document.getElementById('app'))
+const app = createApp(<App />)
+app.mount(document.getElementById('app')!)
 
-// 销毁 app 实例
+// 需要时卸载并清理
 app.destroy()
 ```
 
-### fork()
+---
 
-可以在任意组件内创建一个子应用，并可以继承当前组件的上下文（特指当前组件的依赖注入树），常用于创建一个弹窗或对话框。
+具体 API 以类型定义与官网说明为准。
 
-```jsx
-function App() {
-  function Modal() {
-    return () => {
-      return <div>modal</div>
-    }
-  }
-  // 创建子应用
-  const childApp = fork(<Modal/>)
-  // 启动子应用
-  childApp.mount(document.getElementById('modal'))
-  // 销毁子应用
-  childApp.destroy()
-
-  return () => {
-    return <div>App!</div>
-  }
-}
-```
+---
+
+## 文档
+
+- **官方文档**：[viewfly.org](https://viewfly.org)
+
+---
+
+## License
 
-完整文档请参考官方网站：[viewfly.org](https://viewfly.org)
+MIT

package/dist/create-app.d.ts

@@ -0,0 +1,17 @@
+import { ViewFlyNode, Application, Config, NativeNode } from '@viewfly/core';
+/**
+ * 创建一个 Viewfly 实例
+ * @param root 应用根节点
+ * @param autoUpdate 是否自动更新视图，默认为 true，当值为 false 时，Viewfly
+ * 只会首次渲染，直到手动调用 app 的 render() 方法，这在单元测试中非常有用，
+ * 我们无需等待 Viewfly 默认的异步调度，实现同步更新视图
+ * ```tsx
+ * const app = createApp(<App/>, false).mount(document.getElementById('app'))
+ *
+ * // do something...
+ *
+ * app.render() // 手动更新视图
+ * ```
+ */
+export declare function createApp<T extends NativeNode>(root: ViewFlyNode, autoUpdate?: boolean): Application<T>;
+export declare function createApp<T extends NativeNode>(root: ViewFlyNode, config?: Partial<Omit<Config, 'root'>>): Application<T>;

package/dist/create-portal.d.ts

@@ -0,0 +1,35 @@
+import { JSXNode, NativeNode } from '@viewfly/core';
+/**
+ * 用于创建脱离当前 DOM 树的子节点，常用于弹窗等
+ * @deprecated 即将弃用，请使用 @viewfly/core 模块的 Portal 组件实现
+ * @param childRender
+ * @param host
+ * @example
+ * ```tsx
+ * function App() {
+ *   const number = createSignal(0)
+ *
+ *   setInterval(() => {
+ *     number.set(number() + 1)
+ *   }, 1000)
+ *
+ *   const ModalPortal = function (props) {
+ *     return createPortal(() => {
+ *       return <div class="modal">parent data is {props.text}</div>
+ *     }, document.body)
+ *   }
+ *   return () => {
+ *     return (
+ *       <div>
+ *         <div>data is {number()}</div>
+ *         <ModalPortal text={number()}/>
+ *       </div>
+ *     )
+ *   }
+ * }
+ * ```
+ */
+export declare function createPortal<T extends NativeNode>(childRender: () => JSXNode, host: T): {
+    $portalHost: T;
+    $render: () => JSXNode;
+};

package/dist/dom-renderer.d.ts

@@ -0,0 +1,28 @@
+import { ElementNamespace, NativeRenderer } from '@viewfly/core';
+export declare class DomRenderer extends NativeRenderer<HTMLElement, Text> {
+    static NAMESPACES: Record<string, string>;
+    propMap: Record<string, Record<string, string>>;
+    /**
+     * IDL 属性赋 `''` 会被转成数字 0（如 maxLength/minLength），无法表示「未设置」。
+     * 这些键在移除时应删掉对应 content attribute。
+     */
+    private static readonly REMOVE_VIA_ATTRIBUTE;
+    createElement(name: string, namespace: ElementNamespace): HTMLElement;
+    createTextNode(textContent: string): Text;
+    appendChild(parent: HTMLElement, newChild: any): void;
+    prependChild(parent: HTMLElement, newChild: HTMLElement | Text): void;
+    insertAfter(newNode: HTMLElement | Text, ref: HTMLElement | Text): void;
+    remove(node: HTMLElement | Text): void;
+    cleanChildren(node: HTMLElement): void;
+    setProperty(node: HTMLElement, key: string, value: any, namespace: ElementNamespace): void;
+    removeProperty(node: HTMLElement, key: string, namespace: ElementNamespace): void;
+    setClass(target: HTMLElement, className: string): void;
+    setStyle(target: HTMLElement, key: string, value: any): void;
+    removeStyle(target: HTMLElement, key: string): void;
+    listen<T = any>(node: HTMLElement, type: string, callback: (ev: T) => any): void;
+    unListen(node: HTMLElement, type: string, callback: (ev: any) => any): void;
+    syncTextContent(target: Text, content: string): void;
+    getNameSpace(type: string, namespace: ElementNamespace): string | void;
+    private normalizedEventType;
+    private insertBefore;
+}

package/dist/html-renderer.d.ts

@@ -0,0 +1,57 @@
+import { NativeRenderer } from '@viewfly/core';
+export declare class VDOMNode {
+    parent: VDOMElement | null;
+    remove(): void;
+}
+export declare class VDOMElement extends VDOMNode {
+    name: string;
+    props: Map<string, any>;
+    children: Array<VDOMElement | VDOMText>;
+    style: Map<string, any>;
+    className: string;
+    constructor(name: string);
+}
+export declare class VDOMText extends VDOMNode {
+    text: string;
+    constructor(text: string);
+}
+/**
+ * 用于生成模拟轻量 DOM 节点的渲染器
+ */
+export declare class HTMLRenderer extends NativeRenderer<VDOMElement, VDOMText> {
+    createElement(name: string): VDOMElement;
+    createTextNode(textContent: string): VDOMText;
+    setProperty(node: VDOMElement, key: string, value: any): void;
+    appendChild(parent: VDOMElement, newChild: VDOMElement | VDOMText): void;
+    prependChild(parent: VDOMElement, newChild: VDOMElement | VDOMText): void;
+    removeProperty(node: VDOMElement, key: string): void;
+    setStyle(target: VDOMElement, key: string, value: any): void;
+    removeStyle(target: VDOMElement, key: string): void;
+    setClass(target: VDOMElement, value: string): void;
+    listen(): void;
+    unListen(): void;
+    remove(node: VDOMElement | VDOMText): void;
+    cleanChildren(node: VDOMElement): void;
+    syncTextContent(target: VDOMText, content: string): void;
+    insertAfter(newNode: VDOMElement | VDOMText, ref: VDOMElement | VDOMText): void;
+    getNameSpace(): void;
+}
+/**
+ * 轻量 DOM 转换为 HTML 字符串的转换器
+ */
+export declare class OutputTranslator {
+    static singleTags: string[];
+    static simpleXSSFilter: {
+        text(text: string): string;
+        attrName(text: string): string;
+        attrValue(text: string): string;
+    };
+    private singleTagTest;
+    /**
+     * 将虚拟 DOM 转换为 HTML 字符串的方法
+     * @param vDom 虚拟 DOM 节点
+     */
+    transform(vDom: VDOMElement): string;
+    private vDomToHTMLString;
+    private replaceEmpty;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './create-app';
+export * from './create-portal';
+export * from './html-renderer';
+export * from './dom-renderer';
+export * from './jsx-dom';

package/dist/index.esm.js

@@ -0,0 +1,354 @@
+import { NativeRenderer, viewfly } from "@viewfly/core";
+//#region src/dom-renderer.ts
+var DomRenderer = class DomRenderer extends NativeRenderer {
+	static NAMESPACES = {
+		svg: "http://www.w3.org/2000/svg",
+		html: "http://www.w3.org/1999/xhtml",
+		xml: "http://www.w3.org/XML/1998/namespace",
+		xlink: "http://www.w3.org/1999/xlink",
+		xmlns: "http://www.w3.org/2000/xmlns/",
+		mathml: "http://www.w3.org/1998/Math/MathML"
+	};
+	propMap = {
+		INPUT: { readonly: "readOnly" },
+		TEXTAREA: { readonly: "readOnly" }
+	};
+	/**
+	* IDL 属性赋 `''` 会被转成数字 0（如 maxLength/minLength），无法表示「未设置」。
+	* 这些键在移除时应删掉对应 content attribute。
+	*/
+	static REMOVE_VIA_ATTRIBUTE = {
+		maxLength: "maxlength",
+		minLength: "minlength",
+		size: "size",
+		cols: "cols",
+		rows: "rows",
+		tabIndex: "tabindex"
+	};
+	createElement(name, namespace) {
+		const ns = namespace && DomRenderer.NAMESPACES[namespace];
+		if (ns) return document.createElementNS(ns, name);
+		return document.createElement(name);
+	}
+	createTextNode(textContent) {
+		return document.createTextNode(textContent);
+	}
+	appendChild(parent, newChild) {
+		parent.appendChild(newChild);
+	}
+	prependChild(parent, newChild) {
+		parent.prepend(newChild);
+	}
+	insertAfter(newNode, ref) {
+		if (ref.nextSibling) this.insertBefore(newNode, ref.nextSibling);
+		else if (ref.parentNode) this.appendChild(ref.parentNode, newNode);
+		else console.warn(`Element "${ref instanceof Text ? ref.textContent : ref.tagName}" was accidentally deleted, and viewfly is unable to update the current view`);
+	}
+	remove(node) {
+		node.remove();
+	}
+	cleanChildren(node) {
+		node.textContent = "";
+	}
+	setProperty(node, key, value, namespace) {
+		if (value == null) {
+			this.removeProperty(node, key, namespace);
+			return;
+		}
+		if (namespace) {
+			if (key.startsWith("xlink:")) {
+				const ns = key.substring(6);
+				node.setAttributeNS(ns, key, String(value));
+			} else node.setAttribute(key, String(value));
+			return;
+		}
+		const map = this.propMap[node.tagName];
+		if (map) key = map[key] || key;
+		if (key in node) {
+			if (map && document.activeElement === node && key === "value") return;
+			node[key] = value;
+		} else node.setAttribute(key, value);
+	}
+	removeProperty(node, key, namespace) {
+		if (namespace) {
+			if (key.startsWith("xlink:")) {
+				const ns = key.substring(6);
+				node.removeAttributeNS(ns, key.substring(6));
+			} else node.removeAttribute(key);
+			return;
+		}
+		const map = this.propMap[node.tagName];
+		const resolvedKey = map ? map[key] || key : key;
+		const attrName = DomRenderer.REMOVE_VIA_ATTRIBUTE[resolvedKey];
+		if (attrName) {
+			node.removeAttribute(attrName);
+			return;
+		}
+		if (resolvedKey in node) node[resolvedKey] = "";
+		else node.removeAttribute(key);
+	}
+	setClass(target, className) {
+		target.setAttribute("class", className);
+	}
+	setStyle(target, key, value) {
+		if (key.startsWith("--")) {
+			target.style.setProperty(key, value);
+			return;
+		}
+		target.style[key] = value ?? "";
+	}
+	removeStyle(target, key) {
+		if (key.startsWith("--")) {
+			target.style.removeProperty(key);
+			return;
+		}
+		target.style[key] = "";
+	}
+	listen(node, type, callback) {
+		const normalizedType = this.normalizedEventType(type);
+		node.addEventListener(normalizedType, callback);
+	}
+	unListen(node, type, callback) {
+		const normalizedType = this.normalizedEventType(type);
+		node.removeEventListener(normalizedType, callback);
+	}
+	syncTextContent(target, content) {
+		target.textContent = content;
+	}
+	getNameSpace(type, namespace) {
+		if (namespace === "svg") {
+			if (type === "foreignObject") return;
+			return namespace;
+		}
+		if (type === "svg") return type;
+		if (type === "math") return "mathml";
+		return namespace;
+	}
+	normalizedEventType(type) {
+		return type.substring(2).toLowerCase();
+	}
+	insertBefore(newNode, ref) {
+		if (ref.parentNode) ref.parentNode.insertBefore(newNode, ref);
+		else console.warn(`Element "${ref instanceof Text ? ref.textContent : ref.tagName}" was accidentally deleted, and viewfly is unable to update the current view`);
+	}
+};
+//#endregion
+//#region src/create-app.ts
+function createApp(root, config = true) {
+	const c = { autoUpdate: true };
+	if (typeof config === "boolean") c.autoUpdate = config;
+	else if (typeof config === "object") Object.assign(c, config);
+	return viewfly({
+		...c,
+		root,
+		nativeRenderer: c.nativeRenderer || new DomRenderer()
+	});
+}
+//#endregion
+//#region src/create-portal.ts
+/**
+* 用于创建脱离当前 DOM 树的子节点，常用于弹窗等
+* @deprecated 即将弃用，请使用 @viewfly/core 模块的 Portal 组件实现
+* @param childRender
+* @param host
+* @example
+* ```tsx
+* function App() {
+*   const number = createSignal(0)
+*
+*   setInterval(() => {
+*     number.set(number() + 1)
+*   }, 1000)
+*
+*   const ModalPortal = function (props) {
+*     return createPortal(() => {
+*       return <div class="modal">parent data is {props.text}</div>
+*     }, document.body)
+*   }
+*   return () => {
+*     return (
+*       <div>
+*         <div>data is {number()}</div>
+*         <ModalPortal text={number()}/>
+*       </div>
+*     )
+*   }
+* }
+* ```
+*/
+function createPortal(childRender, host) {
+	return {
+		$portalHost: host,
+		$render: childRender
+	};
+}
+//#endregion
+//#region src/html-renderer.ts
+var VDOMNode = class {
+	parent = null;
+	remove() {
+		if (this.parent) {
+			const i = this.parent.children.indexOf(this);
+			if (i > -1) this.parent.children.splice(i, 1);
+		}
+		this.parent = null;
+	}
+};
+var VDOMElement = class extends VDOMNode {
+	props = /* @__PURE__ */ new Map();
+	children = [];
+	style = /* @__PURE__ */ new Map();
+	className = "";
+	constructor(name) {
+		super();
+		this.name = name;
+	}
+};
+var VDOMText = class extends VDOMNode {
+	constructor(text) {
+		super();
+		this.text = text;
+	}
+};
+/**
+* 用于生成模拟轻量 DOM 节点的渲染器
+*/
+var HTMLRenderer = class extends NativeRenderer {
+	createElement(name) {
+		return new VDOMElement(name);
+	}
+	createTextNode(textContent) {
+		return new VDOMText(textContent);
+	}
+	setProperty(node, key, value) {
+		node.props.set(key, value);
+	}
+	appendChild(parent, newChild) {
+		newChild.remove();
+		parent.children.push(newChild);
+		newChild.parent = parent;
+	}
+	prependChild(parent, newChild) {
+		newChild.remove();
+		parent.children.unshift(newChild);
+		newChild.parent = parent;
+	}
+	removeProperty(node, key) {
+		node.props.delete(key);
+	}
+	setStyle(target, key, value) {
+		target.style.set(key, value);
+	}
+	removeStyle(target, key) {
+		target.style.delete(key);
+	}
+	setClass(target, value) {
+		target.className = value;
+	}
+	listen() {}
+	unListen() {}
+	remove(node) {
+		node.remove();
+	}
+	cleanChildren(node) {
+		node.children.forEach((i) => i.parent = null);
+		node.children = [];
+	}
+	syncTextContent(target, content) {
+		target.text = content;
+	}
+	insertAfter(newNode, ref) {
+		newNode.remove();
+		const parent = ref.parent;
+		if (parent) {
+			const i = parent.children.indexOf(ref);
+			if (i > -1) {
+				newNode.parent = parent;
+				parent.children.splice(i + 1, 0, newNode);
+			}
+		} else console.warn(`Element "${ref instanceof VDOMText ? ref.text : ref.name}" was accidentally deleted, and viewfly is unable to update the current view`);
+	}
+	getNameSpace() {}
+};
+/**
+* 轻量 DOM 转换为 HTML 字符串的转换器
+*/
+var OutputTranslator = class OutputTranslator {
+	static singleTags = "area,base,br,col,embed,hr,img,input,link,meta,source,track,wbr".split(",");
+	static simpleXSSFilter = {
+		text(text) {
+			return text.replace(/[><&]/g, (str) => {
+				return {
+					"<": "&lt;",
+					">": "&gt;",
+					"&": "&amp;"
+				}[str];
+			});
+		},
+		attrName(text) {
+			return text.replace(/[><"'&]/g, (str) => {
+				return {
+					"<": "&lt;",
+					">": "&gt;",
+					"\"": "&quot;",
+					"'": "&#x27;",
+					"&": "&amp;"
+				}[str];
+			});
+		},
+		attrValue(text) {
+			return text.replace(/["']/g, (str) => {
+				return {
+					"\"": "&quot;",
+					"'": "&#x27;"
+				}[str];
+			});
+		}
+	};
+	singleTagTest = new RegExp(`^(${OutputTranslator.singleTags.join("|")})$`, "i");
+	/**
+	* 将虚拟 DOM 转换为 HTML 字符串的方法
+	* @param vDom 虚拟 DOM 节点
+	*/
+	transform(vDom) {
+		return vDom.children.map((child) => {
+			return this.vDomToHTMLString(child);
+		}).join("");
+	}
+	vDomToHTMLString(vDom) {
+		const xssFilter = OutputTranslator.simpleXSSFilter;
+		if (vDom instanceof VDOMText) return this.replaceEmpty(xssFilter.text(vDom.text), "&nbsp;");
+		const styles = Array.from(vDom.style.keys()).filter((key) => {
+			const v = vDom.style.get(key);
+			return !(v === void 0 || v === null || v === "");
+		}).map((key) => {
+			const k = key.replace(/(?=[A-Z])/g, "-").toLowerCase();
+			return xssFilter.attrValue(`${k}:${vDom.style.get(key)}`);
+		}).join(";");
+		const attrs = Array.from(vDom.props.keys()).filter((key) => key !== "ref" && vDom.props.get(key) !== false).map((k) => {
+			const key = xssFilter.attrName(k);
+			const value = vDom.props.get(k);
+			return value === true && /^\w+$/.test(key) ? `${key}` : `${key}="${xssFilter.attrValue(`${value}`)}"`;
+		});
+		if (styles) attrs.push(`style="${styles}"`);
+		if (vDom.className) attrs.push(`class="${xssFilter.attrValue(vDom.className)}"`);
+		let attrStr = attrs.join(" ");
+		attrStr = attrStr ? " " + attrStr : "";
+		if (this.singleTagTest.test(vDom.name)) return `<${vDom.name}${attrStr}>`;
+		const childHTML = vDom.children.map((child) => {
+			return this.vDomToHTMLString(child);
+		}).join("");
+		return [
+			`<${vDom.name}${attrStr}>`,
+			childHTML,
+			`</${vDom.name}>`
+		].join("");
+	}
+	replaceEmpty(s, target) {
+		return s.replace(/\s\s+/g, (str) => {
+			return " " + Array.from({ length: str.length - 1 }).fill(target).join("");
+		}).replace(/^\s|\s$/g, target);
+	}
+};
+//#endregion
+export { DomRenderer, HTMLRenderer, OutputTranslator, VDOMElement, VDOMNode, VDOMText, createApp, createPortal };