@vobs/dom 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vobs contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @vobs/dom
+
+Browser DOM adapter implementing the `VobsRenderer` interface, plus the runtime node and reactive binding primitives.
+
+## Install
+
+```bash
+npm install @vobs/dom
+```
+
+## Quick start
+
+```ts
+import { createDOMRenderer, setRenderer, createElement, createText, insertBefore, bindText } from '@vobs/dom'
+import { state } from '@vobs/reactivity'
+
+setRenderer(createDOMRenderer())
+
+const count = state(0)
+const span = createElement('span')
+const text = createText('')
+insertBefore(span, text, null)
+bindText(text, () => `count: ${count.value}`)
+insertBefore(document.body, span, null)
+```
+
+## API
+
+| Signature | Description |
+| --- | --- |
+| `createDOMRenderer(): VobsRenderer<Node, Text, Element, Comment>` | Create the browser DOM renderer implementation. |
+| `setRenderer(renderer)` / `getRenderer()` | Install or read the renderer used by the node factories. |
+| `createElement(tag)` / `createText(content)` / `createComment(content)` | Create nodes through the active renderer. |
+| `insertBefore(parent, child, anchor)` / `removeChild(parent, child)` | Insert or remove nodes. |
+| `setTextContent(node, content)` / `setProperty(node, key, value)` / `setAttribute(node, key, value)` | Update node content, properties and attributes. |
+| `setStaticProps(node, props)` | Apply a static props object to an element. |
+| `addEventListener(node, event, handler)` / `removeEventListener(node, event, handler)` | Bind or unbind event handlers. |
+| `bindText(node, source)` / `bindAttribute(node, key, source)` | Reactive bindings from a `ValueSource` (signal or getter). |
+| `insertDynamic(parent, anchor, factory)` | Conditional block that creates and disposes nodes reactively. |
+| `insertList(parent, anchor, source, renderItem, keyOf?)` | Keyed or indexed list rendering. |
+| `createComponent(fn, props)` / `createFragment(factory)` / `createBlock(factory)` | Component, fragment and lazy block primitives. |
+| `ref(initialValue?)` / `setRef(node, target)` | Ref objects for direct node access. |
+| `insertErrorBoundary(parent, anchor, options)` / `insertAsyncBoundary(parent, anchor, options)` | Error and async boundaries without wrapper nodes. |
+| `insertProfiler(parent, anchor, options)` | Profiler scope. |
+| `disposeNodeOwner(node)` / `clear(container)` | Dispose a node's owner / remove all children. |
+
+## Types
+
+VobsRenderer, FragmentFactory, VobsFragment, VobsNode, ValueSource, Ref, RefTarget, NodeFactory, ErrorBoundaryFallback, ErrorBoundaryOptions, AsyncBoundaryFallback, AsyncBoundaryOptions, AsyncBoundaryProps, AsyncBoundaryView, ProfilerOptions, ProfilerProps, ProfilerRenderInfo

package/package.json

@@ -0,0 +1,22 @@
+{
+  "license": "MIT",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "name": "@vobs/dom",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@vobs/runtime": "1.0.0"
+  },
+  "devDependencies": {
+    "@vobs/reactivity": "1.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+export { createDOMRenderer } from './renderer'
+export type { VobsRenderer } from '@vobs/runtime'
+export {
+  setRenderer,
+  getRenderer,
+  createText,
+  createElement,
+  createComment,
+  insertBefore,
+  removeChild,
+  setTextContent,
+  setProperty,
+  setAttribute,
+  setStaticProps,
+  addEventListener,
+  removeEventListener,
+  clear,
+  createComponent,
+  createBlock,
+  createFragment,
+  isVobsFragment,
+  disposeNodeOwner
+} from '@vobs/runtime'
+export type { FragmentFactory, VobsFragment, VobsNode } from '@vobs/runtime'
+export { bindText, bindAttribute } from '@vobs/runtime'
+export type { ValueSource } from '@vobs/runtime'
+export { ref, setRef } from '@vobs/runtime'
+export type { Ref, RefTarget } from '@vobs/runtime'
+export { insertDynamic, insertList } from '@vobs/runtime'
+export type { NodeFactory } from '@vobs/runtime'
+export { insertErrorBoundary } from '@vobs/runtime'
+export type { ErrorBoundaryFallback, ErrorBoundaryOptions } from '@vobs/runtime'
+export { AsyncBoundary, insertAsyncBoundary, Profiler, insertProfiler } from '@vobs/runtime'
+export type { AsyncBoundaryFallback, AsyncBoundaryOptions, AsyncBoundaryProps, AsyncBoundaryView, ProfilerOptions, ProfilerProps, ProfilerRenderInfo } from '@vobs/runtime'

package/src/renderer.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import {
+  createDOMRenderer,
+  setRenderer,
+  createText,
+  createElement,
+  insertBefore,
+  bindText,
+  insertDynamic,
+  insertList
+} from './index'
+import { onDispose, state } from '@vobs/reactivity'
+
+describe('dom', () => {
+  beforeEach(() => {
+    setRenderer(createDOMRenderer())
+  })
+
+  it('创建文本节点', () => {
+    const text = createText('hello')
+
+    expect(text.textContent).toBe('hello')
+  })
+
+  it('创建元素并插入', () => {
+    const parent = createElement('div')
+    const child = createElement('span')
+    const text = createText('内容')
+
+    insertBefore(child, text, null)
+    insertBefore(parent, child, null)
+
+    expect(parent.innerHTML).toBe('<span>内容</span>')
+  })
+
+  it('bindText 响应式更新', async () => {
+    const count = state(0)
+    const text = createText('')
+
+    bindText(text, count)
+
+    expect(text.textContent).toBe('0')
+
+    count.value = 5
+    await Promise.resolve()
+
+    expect(text.textContent).toBe('5')
+  })
+
+  it('动态 getter 会追踪读取到的 state', async () => {
+    const count = state(0)
+    const text = createText('')
+
+    bindText(text, () => `count: ${count.value}`)
+    count.value = 2
+    await Promise.resolve()
+
+    expect(text.textContent).toBe('count: 2')
+  })
+
+  it('条件块切换时创建和销毁节点', async () => {
+    const show = state(true)
+    const parent = createElement('div')
+    let disposed = 0
+
+    insertDynamic(parent, null, () => {
+      if (!show.value) return null
+      onDispose(() => { disposed++ })
+      const child = createElement('span')
+      insertBefore(child, createText('visible'), null)
+      return child
+    })
+
+    expect(parent.textContent).toContain('visible')
+    show.value = false
+    await Promise.resolve()
+
+    expect(parent.textContent).not.toContain('visible')
+    expect(disposed).toBe(1)
+  })
+
+  it('keyed 列表复用节点、更新内容并保留顺序', async () => {
+    const items = state([
+      { id: 1, name: 'A' },
+      { id: 2, name: 'B' }
+    ])
+    const parent = createElement('ul')
+    const created: Element[] = []
+
+    insertList(
+      parent,
+      null,
+      () => items.value,
+      item => {
+        const node = createElement('li')
+        created.push(node)
+        const text = createText('')
+        insertBefore(node, text, null)
+        bindText(text, () => item.name)
+        return node
+      },
+      item => item.id
+    )
+
+    const first = created[0]
+    items.value = [
+      { id: 2, name: 'B updated' },
+      { id: 1, name: 'A' }
+    ]
+    await Promise.resolve()
+
+    expect(created).toHaveLength(2)
+    expect(parent.children[1]).toBe(first)
+    expect(parent.textContent).toContain('B updated')
+  })
+
+  it('keyed 列表在复用带 index 的渲染项时使用新索引', async () => {
+    const items = state([{ id: 'a' }, { id: 'b' }])
+    const parent = createElement('ul')
+
+    insertList(
+      parent,
+      null,
+      () => items.value,
+      (item, index) => {
+        const node = createElement('li')
+        const text = createText('')
+        insertBefore(node, text, null)
+        bindText(text, () => `${item.id}:${index}`)
+        return node
+      },
+      item => item.id
+    )
+
+    items.value = [items.value[1]!, items.value[0]!]
+    await Promise.resolve()
+
+    expect(parent.textContent).toBe('b:0a:1')
+  })
+
+  it('列表项删除时销毁其 Owner', async () => {
+    const items = state([{ id: 1 }])
+    const parent = createElement('ul')
+    let disposed = false
+
+    insertList(
+      parent,
+      null,
+      () => items.value,
+      () => {
+        onDispose(() => { disposed = true })
+        return createElement('li')
+      },
+      item => item.id
+    )
+
+    items.value = []
+    await Promise.resolve()
+
+    expect(disposed).toBe(true)
+  })
+})

package/src/renderer.ts

@@ -0,0 +1,55 @@
+// 浏览器 DOM 适配器
+
+import type { VobsRenderer } from '@vobs/runtime'
+
+export function createDOMRenderer(): VobsRenderer<Node, Text, Element, Comment> {
+  return {
+    createText(content: string): Text {
+      return document.createTextNode(content)
+    },
+
+    createElement(tag: string): Element {
+      return document.createElement(tag)
+    },
+
+    createComment(content: string): Comment {
+      return document.createComment(content)
+    },
+
+    insertBefore(parent: Node, child: Node, anchor: Node | null): void {
+      parent.insertBefore(child, anchor)
+    },
+
+    removeChild(parent: Node, child: Node): void {
+      parent.removeChild(child)
+    },
+
+    setTextContent(node: Text, content: string): void {
+      node.textContent = content
+    },
+
+    setProperty(node: Element, key: string, value: unknown): void {
+      Reflect.set(node, key, value)
+    },
+
+    setAttribute(node: Element, key: string, value: string): void {
+      node.setAttribute(key, value)
+    },
+
+    addEventListener(node: Element, event: string, handler: EventListener): void {
+      node.addEventListener(event, handler)
+    },
+
+    removeEventListener(node: Element, event: string, handler: EventListener): void {
+      node.removeEventListener(event, handler)
+    },
+
+    nextSibling(node: Node): Node | null {
+      return node.nextSibling
+    },
+
+    clear(container: Node): void {
+      container.textContent = ''
+    }
+  }
+}