@viewfly/platform-browser 2.1.0 → 2.2.1

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,35 @@
+import { ElementNamespace, NativeRenderer } from '@viewfly/core';
+export declare class DomRenderer extends NativeRenderer<HTMLElement, Text> {
+    private static readonly XLINK_NS;
+    /**
+     * React/JSX 式 xlink* 与 `xlink:` 开头的属性在 SVG/Math 等中须走 XLink 命名空间。
+     * 旧实现把 `xlink:` 后接的名字误当作 namespaceURI，且 `xlinkHref` 会退成普通 setAttribute 导致非标准属性名。
+     */
+    private static readonly XLINK_IDL_TO_LOCAL;
+    static NAMESPACES: Record<string, string>;
+    propMap: Record<string, Record<string, string>>;
+    createElement(name: string, namespace: ElementNamespace): HTMLElement;
+    createTextNode(textContent: string): Text;
+    appendChild(parent: HTMLElement, newChild: HTMLElement | Text): 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;
+    /**
+     * SVG / MathML 等非 HTML 下无 HTML5 的「反射 IDL」表；通常用属性字符串表示，false/空串/非数常表示不输出该属性。
+     */
+    private static isXmlAttributeUnsetValue;
+    private setNamespacedPresentation;
+    private clearNamespacedPresentation;
+    private normalizedEventType;
+    private insertBefore;
+}

package/dist/html-idl-reflection.d.ts

@@ -0,0 +1,23 @@
+/**
+ * HTML 反射 IDL 属性：在「与 default / 未设」一致时须 removeAttribute，不能写 `node[idl] = ''`，
+ * 否则会出现空 content 属性、错误约束（如 `pattern=""`、`maxLength=0` 等）。
+ * @see https://html.spec.whatwg.org/ 2.3.1 Reflected attributes
+ */
+/**
+ * 解析后的 IDL 名 -> content attribute 名。removeProperty 命中时仅 `removeAttribute(name)`。
+ */
+export declare const IDL_TO_CONTENT_ATTR: Readonly<Record<string, string>>;
+/**
+ * setProperty 时，若把 `false`、`''` 或非有限 number 当「不设置/默认」，应走 remove。
+ * 不在此集合的 IDL 由通用逻辑或单独分支处理；布尔见上表排除。
+ */
+export declare const IDL_FALSY_OR_NONFINITE_REMOVES: ReadonlySet<string>;
+/**
+ * 是否应把 setProperty 改为 remove（`null`/`undefined` 由 setProperty 开头处理，此处不返回 true）。
+ * `false`、`''`、非有限数（NaN、±∞）在允许列表上时视为与「未设」同义。
+ */
+export declare function isUnsetLikeReflectedIdlValue(resolvedIdlKey: string, value: unknown): boolean;
+/**
+ * 由 IDL 名取 content attribute 名，无则 undefined。
+ */
+export declare function getContentAttrNameForIdl(resolvedIdlKey: string): string | void;

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,7 @@
+export * from './create-app';
+export * from './create-portal';
+export * from './html-renderer';
+export * from './dom-renderer';
+export * from './html-idl-reflection';
+export * from './xml-jsx-attr-name';
+export * from './jsx-dom';