Blender's GPU Accelerated UI, Decoupled from it's original codebase. Supports Rust, Python, JS, React, C & C++. Twice as good as GPUI
dom tree
Preetham Pemmasani032e57e01ae2
diff --git a/bindings/node/dom.js b/bindings/node/dom.jsnew file mode 100644index 0000000..8bc46c3--- /dev/null+++ b/bindings/node/dom.js@@ -0,0 +1,716 @@+// The DOM-like tree: nodes, elements, events and a window-less `document`.+//+// A node lives in a window (`ownerWindow`), where each change becomes an op+// sent to the native UI thread (index.js), or is detached: made by+// `document` (or `cloneNode`) and kept in JavaScript until it is inserted+// into a window's tree, which then creates it and its subtree natively in+// one go. Siblings are a linked list, as in the DOM: insertBefore, remove+// and nextSibling are O(1).+//+// SPDX-License-Identifier: GPL-2.0-or-later+'use strict'++const { isSignal, effect, unowned, memo } = require('./signals')++// Keep in sync with bindings/rust/blenderui-node/src/lib.rs.+const OP = { CREATE: 0, TEXT: 1, SET_ATTR: 2, REMOVE_ATTR: 3, APPEND: 4, INSERT: 5, REMOVE: 6, SET_TEXT: 7, LISTEN: 8, FREE: 9 }+const EVENT_BITS = {+ click: 1, mousedown: 2, mouseup: 4, mousemove: 8, mouseenter: 16, mouseleave: 16,+ wheel: 32, keydown: 64, keyup: 128, change: 256, input: 512,+}+const BUTTONS = ['left', 'middle', 'right']+// DOM: these don't bubble+const NO_BUBBLE = new Set(['mouseenter', 'mouseleave'])+const ELEMENT_NODE = 1, TEXT_NODE = 3, COMMENT_NODE = 8, FRAGMENT_NODE = 11+const XHTML = 'http://www.w3.org/1999/xhtml'++/** Capitalized Blender widgets for `createElement`: [HTML tag, input type]. */+const BLENDER_COMPONENTS = {+ Button: ['button'],+ Checkbox: ['input', 'checkbox'],+ Radio: ['input', 'radio'],+ NumberField: ['input', 'number'],+ NumberSlider: ['input', 'range'],+ TextField: ['input', 'text'],+ TextArea: ['textarea'],+ ColorSwatch: ['input', 'color'],+ Dropdown: ['select'],+ ProgressBar: ['progress'],+}++/** The event object handlers receive (a subset of the DOM's). */+class BuiEvent {+ constructor (raw, target) {+ this.type = raw.kind+ this.bubbles = !NO_BUBBLE.has(raw.kind)+ // the deepest element listening for this type (BUI reports no deeper target)+ this.target = target+ this.currentTarget = target+ this.clientX = this.x = raw.x+ this.clientY = this.y = raw.y+ this.button = raw.button+ this.detail = raw.clickCount+ this.deltaY = -raw.delta * 100 // DOM: positive scrolls down+ this.key = raw.key ?? undefined+ this.char = raw.keyChar ?? undefined+ this.shiftKey = raw.shift+ this.ctrlKey = raw.ctrl+ this.altKey = raw.alt+ this.metaKey = false+ this.timeStamp = performance.now()+ this.defaultPrevented = false+ this.propagationStopped = false+ this.immediatePropagationStopped = false+ }++ /** Events reach JavaScript after BUI handled them: this marks the event only. */+ preventDefault () { this.defaultPrevented = true }+ stopPropagation () { this.propagationStopped = true }+ stopImmediatePropagation () { this.propagationStopped = this.immediatePropagationStopped = true }+ get cancelBubble () { return this.propagationStopped }+ set cancelBubble (v) { if (v) this.propagationStopped = true }+ /** The target and its ancestors, innermost first. */+ composedPath () {+ const path = []+ for (let n = this.target; n !== null; n = n.parentNode) path.push(n)+ return path+ }+}++/** Nodes (and strings, as text) for before / after / append / prepend / replaceWith. */+function toNode (parent, n) {+ return typeof n === 'string' ? parent._createText(n) : n+}++class Node {+ constructor () {+ this.ownerWindow = null+ this.id = -1+ this.parentNode = null+ this._first = null+ this._last = null+ this._prev = null+ this._next = null+ this._bindings = null+ this._nextParent = null+ // made by `document`: freed natively when removed and left without a+ // parent at the end of the tick (DOM frameworks drop nodes, never free them)+ this._auto = false+ }++ // accessors on the prototype, as the DOM has them (Svelte reads their getters)+ get firstChild () { return this._first }+ get lastChild () { return this._last }+ get nextSibling () { return this._next }+ get previousSibling () { return this._prev }++ /** The children, as an array (a copy). */+ get childNodes () {+ const a = []+ for (let c = this._first; c !== null; c = c._next) a.push(c)+ return a+ }++ get ownerDocument () { return document }+ get parentElement () { return this.parentNode }+ /** In a window's tree (under its body). */+ get isConnected () {+ let n = this+ while (n.parentNode !== null) n = n.parentNode+ return n.id === 0 && n.ownerWindow !== null+ }++ hasChildNodes () { return this._first !== null }+ contains (other) {+ for (let n = other; n !== null; n = n.parentNode) if (n === this) return true+ return false+ }++ appendChild (child) { return this.insertBefore(child, null) }++ insertBefore (child, before) {+ if (before == null) before = null+ else if (before.parentNode !== this) throw new Error('blenderui: insertBefore: the reference node is not a child of this node')+ if (child.nodeType === FRAGMENT_NODE) { // a fragment inserts its children+ for (let c = child._first; c !== null; c = child._first) this.insertBefore(c, before)+ return child+ }+ if (child === before) return child+ this._adopt(child)+ child._detach()+ this._link(child, before)+ const w = this.ownerWindow+ if (w !== null) {+ if (before === null) w._op(OP.APPEND, this.id, child.id)+ else w._op(OP.INSERT, this.id, child.id, before.id)+ }+ return child+ }++ removeChild (child) {+ if (child.parentNode !== this) return child+ this._unlink(child)+ const w = this.ownerWindow+ if (w !== null) w._op(OP.REMOVE, this.id, child.id)+ if (child._auto && child.ownerWindow !== null) child.ownerWindow._orphan(child)+ return child+ }++ replaceChild (child, old) {+ this.insertBefore(child, old)+ return this.removeChild(old)+ }++ remove () { this.parentNode?.removeChild(this) }++ // ChildNode / ParentNode (strings become text nodes)+ before (...nodes) {+ const p = this.parentNode+ if (p !== null) for (const n of nodes) p.insertBefore(toNode(p, n), this)+ }++ after (...nodes) {+ const p = this.parentNode+ if (p === null) return+ const next = this._next+ for (const n of nodes) p.insertBefore(toNode(p, n), next)+ }++ append (...nodes) { for (const n of nodes) this.insertBefore(toNode(this, n), null) }+ prepend (...nodes) {+ const first = this._first+ for (const n of nodes) this.insertBefore(toNode(this, n), first)+ }++ replaceWith (...nodes) {+ const p = this.parentNode+ if (p === null) return+ const next = this._next+ p.removeChild(this)+ for (const n of nodes) p.insertBefore(toNode(p, n), next)+ }++ /** A detached copy (with its subtree when `deep`); listeners aren't copied. */+ cloneNode (deep = false) {+ const copy = this._clone()+ copy._auto = true+ if (deep) for (let c = this._first; c !== null; c = c._next) copy.appendChild(c.cloneNode(true))+ return copy+ }++ _link (child, before) {+ const prev = before === null ? this._last : before._prev+ child.parentNode = this+ child._prev = prev+ child._next = before+ if (prev === null) this._first = child+ else prev._next = child+ if (before === null) this._last = child+ else before._prev = child+ }++ _unlink (child) {+ const prev = child._prev+ const next = child._next+ if (prev === null) this._first = next+ else prev._next = next+ if (next === null) this._last = prev+ else next._prev = prev+ child.parentNode = child._prev = child._next = null+ }++ _detach () {+ const p = this.parentNode+ if (p === null) return+ p._unlink(this)+ const w = p.ownerWindow+ // same parent: APPEND / INSERT reorders it natively+ if (w !== null && p !== this._nextParent) w._op(OP.REMOVE, p.id, this.id)+ }++ /** Checks before `child` moves under this node (as the DOM does); a+ * detached child joins this node's window. */+ _adopt (child) {+ for (let n = this; n !== null; n = n.parentNode) {+ if (n === child) throw new Error('blenderui: a node cannot be inserted into itself or its descendants')+ }+ const w = this.ownerWindow+ if (child.ownerWindow !== w) {+ if (child.ownerWindow === null) child._attach(w)+ else if (w !== null) throw new Error('blenderui: the node belongs to another window')+ // else: a window's node parked in a detached node (a fragment): allowed+ }+ child._nextParent = this+ }++ /** Create this detached node and its subtree in `win`. */+ _attach (win) {+ this.ownerWindow = win+ this.id = win._next+++ win._nodes.set(this.id, this)+ this._create(win)+ for (let c = this._first; c !== null; c = c._next) {+ if (c.ownerWindow === null) c._attach(win)+ else if (c.ownerWindow !== win) throw new Error('blenderui: the node belongs to another window')+ win._op(OP.APPEND, this.id, c.id)+ }+ }++ /** A text node in this node's window (or detached). */+ _createText (text) {+ const t = new TextNode('')+ t._auto = this._auto+ t.data = text+ return t+ }++ /** Keep `key` (an attribute, or the text) following `source`: each change+ * updates this node alone. */+ _bind (key, source, apply) {+ this._unbind(key)+ // unowned: a binding made inside an effect lives as long as the node, not that effect's run+ ;(this._bindings ??= new Map()).set(key, unowned(() => effect(() => { apply(source.value) })))+ }++ _unbind (key) {+ const dispose = this._bindings?.get(key)+ if (dispose) {+ dispose()+ this._bindings.delete(key)+ }+ }++ _unbindAll () {+ if (this._bindings) {+ for (const dispose of this._bindings.values()) dispose()+ this._bindings = null+ }+ }++ /** Free this node and its subtree on the native side (after removing it). */+ destroy () {+ for (let c = this._first; c !== null; c = c._next) c.destroy()+ if (this.ownerWindow !== null) this.ownerWindow._free(this)+ else this._unbindAll()+ }++ /** The text of the subtree (comments excluded). */+ get textContent () {+ let s = ''+ for (let c = this._first; c !== null; c = c._next) if (c.nodeType !== COMMENT_NODE) s += c.textContent+ return s+ }+}++class TextNode extends Node {+ constructor (text) {+ super()+ this._text = text+ }++ get nodeType () { return TEXT_NODE }+ get nodeName () { return '#text' }+ get data () { return this._text }+ /** A string, or a signal (the text then follows it). */+ set data (t) {+ if (isSignal(t)) return this._bind('data', t, (v) => this._setText(v))+ this._unbind('data')+ this._setText(t)+ }++ _setText (t) {+ t = t == null ? '' : String(t)+ if (t !== this._text) {+ this._text = t+ const w = this.ownerWindow+ if (w !== null) w._op(OP.SET_TEXT, this.id, w._s(t))+ }+ }++ _create (win) { win._op(OP.TEXT, this.id, win._s(this._text)) }+ _clone () { return new TextNode(this._text) }++ get nodeValue () { return this._text }+ set nodeValue (t) { this.data = t }+ get textContent () { return this._text }+ set textContent (t) { this.data = t }+}++/** A comment: an anchor for DOM frameworks; natively an empty text node,+ * which takes no space. */+class Comment extends Node {+ constructor (data) {+ super()+ this.data = data+ }++ get nodeType () { return COMMENT_NODE }+ get nodeName () { return '#comment' }+ get nodeValue () { return this.data }+ set nodeValue (v) { this.data = String(v) }+ get textContent () { return this.data }+ set textContent (v) { this.data = String(v) }+ _create (win) { win._op(OP.TEXT, this.id, win._s('')) }+ _clone () { return new Comment(this.data) }+}++/** Nodes to insert together; inserting it moves its children. Never in a tree. */+class DocumentFragment extends Node {+ get nodeType () { return FRAGMENT_NODE }+ get nodeName () { return '#document-fragment' }+ _create () { throw new Error('blenderui: a fragment cannot be inserted itself') }+ _clone () { return new DocumentFragment() }+}++/** `el.style`: CSS text, edited a declaration at a time (`setProperty`). */+class Style {+ constructor (el) { this._el = el }++ get cssText () { return this._el._attrs.get('style') ?? '' }+ set cssText (v) {+ if (v == null || v === '') this._el.removeAttribute('style')+ else this._el.setAttribute('style', v)+ }++ _declarations () {+ const m = new Map()+ for (const d of this.cssText.split(';')) {+ const i = d.indexOf(':')+ if (i > 0) m.set(d.slice(0, i).trim(), d.slice(i + 1).trim())+ }+ return m+ }++ _write (m) {+ let s = ''+ for (const [k, v] of m) s += `${k}: ${v}; `+ this.cssText = s+ }++ getPropertyValue (name) { return this._declarations().get(name) ?? '' }+ setProperty (name, value, priority) {+ if (value == null || value === '') return this.removeProperty(name)+ const m = this._declarations()+ m.set(name, priority ? `${value} !important` : String(value))+ this._write(m)+ }++ removeProperty (name) {+ const m = this._declarations()+ const old = m.get(name)+ if (old === undefined) return ''+ m.delete(name)+ this._write(m)+ return old+ }++ toString () { return this.cssText }+}++/** `el.classList`, over the `class` attribute. */+class ClassList {+ constructor (el) { this._el = el }+ _list () { return (this._el._attrs.get('class') ?? '').split(/\s+/).filter(Boolean) }+ _write (list) { this._el.setAttribute('class', list.join(' ')) }+ get value () { return this._el._attrs.get('class') ?? '' }+ get length () { return this._list().length }+ contains (name) { return this._list().includes(name) }+ add (...names) {+ const list = this._list()+ for (const n of names) if (!list.includes(n)) list.push(n)+ this._write(list)+ }++ remove (...names) { this._write(this._list().filter((n) => !names.includes(n))) }+ toggle (name, force) {+ const on = force ?? !this.contains(name)+ if (on) this.add(name)+ else this.remove(name)+ return on+ }++ toString () { return this.value }+}++class Element extends Node {+ constructor (tag) {+ super()+ this.tagName = tag.toUpperCase()+ this.localName = tag+ this._attrs = new Map()+ this._listeners = new Map()+ this._bits = 0+ this._style = null+ // form controls: the latest value from input / change events+ this._value = undefined+ this._checked = undefined+ this.valueAsNumber = undefined+ }++ get nodeType () { return ELEMENT_NODE }+ get nodeName () { return this.tagName }+ get namespaceURI () { return XHTML }+ get children () { return this.childNodes.filter((c) => c.nodeType === ELEMENT_NODE) }++ /** A value, or a signal: the attribute then follows it (null / false removes it). */+ setAttribute (name, value) {+ if (isSignal(value)) {+ return this._bind(name, value, (v) => {+ if (v == null || v === false) this._removeAttr(name)+ else this._setAttr(name, name === 'style' && typeof v === 'object' ? styleText(v) : v === true ? '' : v)+ })+ }+ this._unbind(name)+ this._setAttr(name, value)+ }++ setAttributeNS (ns, name, value) { this.setAttribute(name, value) }++ _setAttr (name, value) {+ value = String(value)+ if (this._attrs.get(name) === value) return+ this._attrs.set(name, value)+ const w = this.ownerWindow+ if (w !== null) w._op(OP.SET_ATTR, this.id, w._s(name), w._s(value))+ }++ getAttribute (name) { return this._attrs.get(name) ?? null }+ hasAttribute (name) { return this._attrs.has(name) }+ getAttributeNames () { return [...this._attrs.keys()] }+ get attributes () { return [...this._attrs].map(([name, value]) => ({ name, value })) }+ toggleAttribute (name, force) {+ const on = force ?? !this.hasAttribute(name)+ if (on) this.setAttribute(name, '')+ else this.removeAttribute(name)+ return on+ }++ removeAttribute (name) {+ this._unbind(name)+ this._removeAttr(name)+ }++ _removeAttr (name) {+ if (this._attrs.delete(name)) {+ const w = this.ownerWindow+ if (w !== null) w._op(OP.REMOVE_ATTR, this.id, w._s(name))+ }+ }++ get className () { return this._attrs.get('class') ?? '' }+ set className (v) { this.setAttribute('class', v) }+ get classList () { return new ClassList(this) }+ /** The inline style (`cssText`, `setProperty` ...). */+ get style () { return (this._style ??= new Style(this)) }+ /** A CSS declaration string, or an object (`{ backgroundColor: 'red', width: 40 }`). */+ set style (v) {+ if (v == null) return this.removeAttribute('style')+ if (typeof v === 'string' || isSignal(v)) return this.setAttribute('style', v)+ // an object: plain values, or some signals (`{ color: colorSignal }`), then bound+ for (const k in v) if (isSignal(v[k])) return this.setAttribute('style', memo(() => styleText(v)))+ this.setAttribute('style', styleText(v))+ }++ get textContent () { return super.textContent }+ set textContent (t) {+ for (let c = this._first; c !== null; c = this._first) {+ this.removeChild(c)+ if (!c._auto) c.destroy() // a document's nodes: freed at the end of the tick, unless reinserted+ }+ if (t !== '' && t != null) this.appendChild(this._createText(isSignal(t) ? t : String(t)))+ }++ /** Any event type; those BUI reports (`EVENT_BITS`) arrive from the UI thread. */+ addEventListener (type, fn) {+ let set = this._listeners.get(type)+ if (!set) this._listeners.set(type, (set = new Set()))+ set.add(fn)+ this._listen()+ }++ removeEventListener (type, fn) {+ this._listeners.get(type)?.delete(fn)+ this._listen()+ }++ _listen () {+ let bits = 0+ for (const [type, set] of this._listeners) if (set.size) bits |= EVENT_BITS[type] ?? 0+ if (bits !== this._bits) {+ this._bits = bits+ const w = this.ownerWindow+ if (w !== null) w._op(OP.LISTEN, this.id, bits)+ }+ }++ _create (win) {+ win._op(OP.CREATE, this.id, win._s(this.localName))+ for (const [name, value] of this._attrs) win._op(OP.SET_ATTR, this.id, win._s(name), win._s(value))+ if (this._bits !== 0) win._op(OP.LISTEN, this.id, this._bits)+ }++ _clone () {+ const el = new HTMLElement(this.localName)+ for (const [name, value] of this._attrs) el._attrs.set(name, value)+ return el+ }++ _dispatch (raw) {+ if (raw.kind === 'input' || raw.kind === 'change') {+ this._value = raw.value+ this._checked = raw.checked+ this.valueAsNumber = raw.number+ }+ this._propagate(new BuiEvent(raw, this))+ }++ /** Dispatch a DOM event (`new CustomEvent('introstart')` ...) through this+ * element's listeners and, if it bubbles, its ancestors'. */+ dispatchEvent (event) {+ const own = { value: this, writable: true, configurable: true }+ Object.defineProperties(event, { target: own, currentTarget: own })+ this._propagate(event)+ return !event.defaultPrevented+ }++ _propagate (e) {+ for (let n = this; n !== null; n = n.parentNode) {+ const set = n._listeners?.get(e.type)+ if (set && set.size) {+ e.currentTarget = n+ for (const fn of [...set]) {+ try { fn.call(n, e) } catch (err) { queueMicrotask(() => { throw err }) }+ if (e.immediatePropagationStopped) break+ }+ }+ if (e.cancelBubble || !e.bubbles) break+ }+ e.currentTarget = null+ }++ /** Web Animations aren't run: the animation finishes at once (as React's+ * `<ViewTransition>` commits without animating). */+ animate () {+ const a = { playState: 'finished', currentTime: 0, onfinish: null, cancel () {}, finish () {}, pause () {}, play () {} }+ a.finished = Promise.resolve(a)+ queueMicrotask(() => a.onfinish?.())+ return a+ }++ /** Layout box `{ x, y, width, height }` in logical pixels (or null). */+ getBoundingClientRect () {+ const w = this.ownerWindow+ if (w === null) return Promise.resolve(null)+ w.flush() // the UI thread must see the tree first+ return w.app.native.bounds(w.id, this.id)+ }+}++/** An HTML element: its DOM properties (`disabled`, `value` ...) are setters+ * here, below Element, where frameworks look for them (as in browsers). */+class HTMLElement extends Element {+ /** Form controls: the latest value from input / change events, else the attribute. */+ get value () { return this._value ?? this._attrs.get('value') ?? (this.localName === 'input' || this.localName === 'textarea' ? '' : undefined) }+ set value (v) {+ this._value = v == null ? '' : String(v)+ this.setAttribute('value', this._value)+ }++ get checked () { return this._checked ?? this._attrs.has('checked') }+ set checked (v) {+ this._checked = !!v+ this.toggleAttribute('checked', this._checked)+ }+}++// DOM properties that reflect a boolean attribute.+for (const [prop, attr] of [['disabled', 'disabled'], ['hidden', 'hidden'], ['selected', 'selected'],+ ['readOnly', 'readonly'], ['required', 'required'], ['multiple', 'multiple'], ['open', 'open'],+ ['indeterminate', 'indeterminate'], ['autofocus', 'autofocus'], ['defaultChecked', 'checked']]) {+ Object.defineProperty(HTMLElement.prototype, prop, {+ get () { return this._attrs.has(attr) },+ set (v) { this.toggleAttribute(attr, !!v) },+ configurable: true,+ })+}+// ... and a string attribute.+// (not `id`: a node's `id` is its native id; use setAttribute('id', ...))+for (const [prop, attr] of [['type', 'type'], ['name', 'name'], ['placeholder', 'placeholder'],+ ['title', 'title'], ['min', 'min'], ['max', 'max'], ['step', 'step'], ['href', 'href'], ['src', 'src'],+ ['defaultValue', 'value'], ['tabIndex', 'tabindex'], ['htmlFor', 'for']]) {+ Object.defineProperty(HTMLElement.prototype, prop, {+ get () { return this._attrs.get(attr) ?? '' },+ set (v) { this.setAttribute(attr, v) },+ configurable: true,+ })+}++const UNITLESS = new Set(['opacity', 'z-index', 'flex', 'flex-grow', 'flex-shrink', 'order', 'font-weight',+ 'line-height', 'zoom', 'aspect-ratio', 'grid-row', 'grid-column', 'scale'])++/** `{ backgroundColor: 'red', width: 40 }` -> `background-color: red; width: 40px` */+function styleText (o) {+ let s = ''+ for (const k in o) {+ const raw = o[k]+ const v = isSignal(raw) ? raw.value : raw // read: a memo around this follows it+ if (v == null || v === false || v === '') continue+ const prop = k.startsWith('--') ? k : k.replace(/[A-Z]/g, m => '-' + m.toLowerCase())+ s += `${prop}: ${typeof v === 'number' && v !== 0 && !UNITLESS.has(prop) ? v + 'px' : v}; `+ }+ return s+}++/** An element in `win`, or detached (`win` null). Capitalized tags are+ * Blender's widgets; their lowercase HTML counterparts look like a browser's+ * (Blender's inside `styled`). */+function createElement (win, tag) {+ const blender = BLENDER_COMPONENTS[tag]+ const el = new HTMLElement(blender ? blender[0] : tag)+ if (blender) {+ if (blender[1]) el._attrs.set('type', blender[1])+ el._attrs.set('bui-blender', '')+ }+ if (win !== null) el._attach(win)+ else el._auto = true+ return el+}++/** The window-less document of DOM frameworks: its nodes are detached until+ * inserted into a window's tree, and freed when removed and dropped. */+class Document {+ constructor () {+ this.head = createElement(null, 'head')+ this.activeElement = null+ this._listeners = new Map()+ }++ get nodeType () { return 9 }+ createElement (tag) { return createElement(null, tag) }+ createElementNS (ns, tag) { return createElement(null, tag) }+ createTextNode (text) {+ const t = new TextNode('')+ t._auto = true+ t.data = text+ return t+ }++ createComment (data = '') {+ const c = new Comment(String(data))+ c._auto = true+ return c+ }++ createDocumentFragment () { return new DocumentFragment() }+ importNode (node, deep) { return node.cloneNode(deep) }+ // events never reach the document (they bubble up to a window's body)+ addEventListener () {}+ removeEventListener () {}+}++const document = new Document()++module.exports = {+ OP, EVENT_BITS, BUTTONS, BLENDER_COMPONENTS, BuiEvent, Node, TextNode, Comment, DocumentFragment, Element, HTMLElement, Document,+ document, createElement, styleText,+}diff --git a/bindings/node/index.d.ts b/bindings/node/index.d.tsindex 4c63d15..aa46202 100644--- a/bindings/node/index.d.ts+++ b/bindings/node/index.d.ts@@ -43,22 +43,50 @@ export class BuiEvent {timeStamp: numberpreventDefault (): voidstopPropagation (): void+ stopImmediatePropagation (): void+ /** Set by stopPropagation(). */+ cancelBubble: boolean+ /** The target and its ancestors, innermost first. */+ composedPath (): Element[]}+/** A node lives in a window (`ownerWindow`) or is detached (made by+ * `document` or `cloneNode`): it is created natively, with its subtree, when+ * inserted into a window's tree. */export class Node {- readonly ownerWindow: Window+ readonly ownerWindow: Window | null+ /** The native id (-1 while detached). */readonly id: number- parentNode: Element | null- childNodes: Node[]+ readonly nodeType: number+ readonly nodeName: string+ readonly parentNode: Element | DocumentFragment | null+ readonly parentElement: Element | DocumentFragment | null+ /** The children (a new array each time). */+ readonly childNodes: Node[]readonly firstChild: Node | nullreadonly lastChild: Node | nullreadonly nextSibling: Node | null+ readonly previousSibling: Node | null+ /** Under a window's body. */+ readonly isConnected: boolean+ readonly ownerDocument: DocumenttextContent: stringappendChild<T extends Node> (child: T): TinsertBefore<T extends Node> (child: T, before: Node | null): TremoveChild<T extends Node> (child: T): T+ replaceChild<T extends Node> (child: Node, old: T): Tremove (): void- /** Free the node and its subtree natively (after removing it). */+ before (...nodes: (Node | string)[]): void+ after (...nodes: (Node | string)[]): void+ append (...nodes: (Node | string)[]): void+ prepend (...nodes: (Node | string)[]): void+ replaceWith (...nodes: (Node | string)[]): void+ contains (other: Node | null): boolean+ hasChildNodes (): boolean+ /** A detached copy (and its subtree when `deep`); listeners aren't copied. */+ cloneNode (deep?: boolean): this+ /** Free the node and its subtree natively (after removing it). Nodes made+ * by `document` are freed for you once removed and dropped. */destroy (): void}@@ -68,32 +96,101 @@ export class TextNode extends Node {nodeValue: string}+/** A comment (an anchor for DOM frameworks): natively an empty text node. */+export class Comment extends Node {+ data: string+ nodeValue: string+}++/** Nodes inserted together: inserting the fragment moves its children. */+export class DocumentFragment extends Node {}++/** `el.style`: the inline style. */+export interface Style {+ cssText: string+ getPropertyValue (name: string): string+ setProperty (name: string, value: string | null, priority?: string): void+ removeProperty (name: string): string+}++export interface ClassList {+ readonly value: string+ readonly length: number+ add (...names: string[]): void+ remove (...names: string[]): void+ toggle (name: string, force?: boolean): boolean+ contains (name: string): boolean+}++type StyleValue = string | Record<string, string | number | null | undefined>+export class Element extends Node {readonly tagName: stringreadonly localName: string+ readonly namespaceURI: string+ readonly children: Element[]className: string- /** CSS text, or an object such as `{ backgroundColor: 'red', width: 40 }`. */- style: string | Record<string, string | number | null | undefined> | ReadSignal<string | Record<string, string | number | null | undefined>>- /** Form controls: the latest value from input / change events. */- value?: string- checked?: boolean+ readonly classList: ClassList+ /** Reads the inline style; takes CSS text, an object such as+ * `{ backgroundColor: 'red', width: 40 }`, or a signal of either. */+ get style (): Style+ set style (v: StyleValue | ReadSignal<StyleValue> | null)/** A value, or a signal: the attribute then follows it (null / false removes it). */setAttribute (name: string, value: unknown): voidgetAttribute (name: string): string | nullhasAttribute (name: string): booleanremoveAttribute (name: string): void- addEventListener (type: EventType, listener: (event: BuiEvent) => void): void- removeEventListener (type: EventType, listener: (event: BuiEvent) => void): void+ toggleAttribute (name: string, force?: boolean): boolean+ getAttributeNames (): string[]+ /** Any type; BUI's own (`EventType`) arrive from the UI thread. */+ addEventListener (type: EventType | (string & {}), listener: (event: BuiEvent) => void, options?: unknown): void+ removeEventListener (type: EventType | (string & {}), listener: (event: BuiEvent) => void, options?: unknown): void+ /** Run the listeners for `event.type` here (and up, if it bubbles). */+ dispatchEvent (event: { type: string, bubbles?: boolean }): boolean+ /** Web Animations aren't run: the animation finishes at once. */+ animate (keyframes?: unknown, options?: unknown): { onfinish: (() => void) | null, cancel (): void, finished: Promise<unknown> }getBoundingClientRect (): Promise<{ x: number, y: number, width: number, height: number } | null>}+/** An HTML element: its DOM properties reflect attributes. */+export class HTMLElement extends Element {+ /** Form controls: the latest value from input / change events, else the attribute. */+ value: string+ checked: boolean+ disabled: boolean+ hidden: boolean+ type: string+}++/** The window-less document: its nodes are detached until inserted into a+ * window's tree. DOM frameworks use it through `@blender-ui/native/globals`. */+export class Document {+ readonly head: HTMLElement+ /** Capitalized tags are Blender's widgets. */+ createElement (tag: string): HTMLElement+ createElementNS (ns: string, tag: string): HTMLElement+ createTextNode (text: string | ReadSignal<unknown>): TextNode+ createComment (data?: string): Comment+ createDocumentFragment (): DocumentFragment+ importNode<T extends Node> (node: T, deep?: boolean): T+}+export const document: Document++/** BUI's event types and their native bits. */+export const EVENT_BITS: Record<EventType, number>+/** Capitalized Blender widgets: [HTML tag, input type]. */+export const BLENDER_COMPONENTS: Record<string, [string, string?]>+export class Window {readonly app: Appreadonly id: number- readonly body: Element+ readonly body: HTMLElementclosed: boolean- createElement (tag: string): Element+ /** Capitalized tags are Blender's widgets (`Button`, `NumberSlider` ...). */+ createElement (tag: string): HTMLElementcreateTextNode (text: string | ReadSignal<unknown>): TextNode+ createComment (data?: string): Comment+ createDocumentFragment (): DocumentFragment/** Send pending changes now (they are otherwise sent once per tick). */flush (): void/** Run `cb` before the next frame, paced by the display. */diff --git a/bindings/node/index.js b/bindings/node/index.jsindex 3ba87a7..8891ca2 100644--- a/bindings/node/index.js+++ b/bindings/node/index.js@@ -30,306 +30,8 @@ function loadAddon () {}}const signals = require('./signals')-const { isSignal, effect, unowned, memo } = signals--// Keep in sync with bindings/rust/blenderui-node/src/lib.rs.-const OP = { CREATE: 0, TEXT: 1, SET_ATTR: 2, REMOVE_ATTR: 3, APPEND: 4, INSERT: 5, REMOVE: 6, SET_TEXT: 7, LISTEN: 8, FREE: 9 }-const EVENT_BITS = {- click: 1, mousedown: 2, mouseup: 4, mousemove: 8, mouseenter: 16, mouseleave: 16,- wheel: 32, keydown: 64, keyup: 128, change: 256, input: 512,-}-const BUTTONS = ['left', 'middle', 'right']-// DOM: these don't bubble-const NO_BUBBLE = new Set(['mouseenter', 'mouseleave'])--/** The event object handlers receive (a subset of the DOM's). */-class BuiEvent {- constructor (raw, target) {- this.type = raw.kind- this.bubbles = !NO_BUBBLE.has(raw.kind)- // the deepest element listening for this type (BUI reports no deeper target)- this.target = target- this.currentTarget = target- this.clientX = this.x = raw.x- this.clientY = this.y = raw.y- this.button = raw.button- this.detail = raw.clickCount- this.deltaY = -raw.delta * 100 // DOM: positive scrolls down- this.key = raw.key ?? undefined- this.char = raw.keyChar ?? undefined- this.shiftKey = raw.shift- this.ctrlKey = raw.ctrl- this.altKey = raw.alt- this.metaKey = false- this.timeStamp = performance.now()- this.defaultPrevented = false- this.propagationStopped = false- this.immediatePropagationStopped = false- }-- /** Events reach JavaScript after BUI handled them: this marks the event only. */- preventDefault () { this.defaultPrevented = true }- stopPropagation () { this.propagationStopped = true }- stopImmediatePropagation () { this.propagationStopped = this.immediatePropagationStopped = true }-}--class Node {- constructor (win, id) {- this.ownerWindow = win- this.id = id- this.parentNode = null- this._bindings = null- this.childNodes = []- }-- get firstChild () { return this.childNodes[0] ?? null }- get lastChild () { return this.childNodes[this.childNodes.length - 1] ?? null }- get nextSibling () {- const p = this.parentNode- return p ? p.childNodes[p.childNodes.indexOf(this) + 1] ?? null : null- }-- appendChild (child) {- this._adopt(child)- child._detach()- this.childNodes.push(child)- child.parentNode = this- this.ownerWindow._op(OP.APPEND, this.id, child.id)- return child- }-- insertBefore (child, before) {- if (!before) return this.appendChild(child)- if (before.parentNode !== this) throw new Error('blenderui: insertBefore: the reference node is not a child of this node')- if (child === before) return child- this._adopt(child)- child._detach()- this.childNodes.splice(this.childNodes.indexOf(before), 0, child)- child.parentNode = this- this.ownerWindow._op(OP.INSERT, this.id, child.id, before.id)- return child- }-- removeChild (child) {- const i = this.childNodes.indexOf(child)- if (i >= 0) {- this.childNodes.splice(i, 1)- child.parentNode = null- this.ownerWindow._op(OP.REMOVE, this.id, child.id)- }- return child- }-- remove () { this.parentNode?.removeChild(this) }-- _detach () {- const p = this.parentNode- if (p) {- p.childNodes.splice(p.childNodes.indexOf(this), 1)- this.parentNode = null- if (p !== this._nextParent) this.ownerWindow._op(OP.REMOVE, p.id, this.id)- }- }-- /** Checks before `child` moves under this node (as the DOM does). */- _adopt (child) {- if (child.ownerWindow !== this.ownerWindow) throw new Error('blenderui: the node belongs to another window')- for (let n = this; n; n = n.parentNode) {- if (n === child) throw new Error('blenderui: a node cannot be inserted into itself or its descendants')- }- child._nextParent = this // same parent: APPEND / INSERT reorders it natively- }-- /** Keep `key` (an attribute, or the text) following `source`: each change- * updates this node alone. */- _bind (key, source, apply) {- this._unbind(key)- // unowned: a binding made inside an effect lives as long as the node, not that effect's run- ;(this._bindings ??= new Map()).set(key, unowned(() => effect(() => { apply(source.value) })))- }-- _unbind (key) {- const dispose = this._bindings?.get(key)- if (dispose) {- dispose()- this._bindings.delete(key)- }- }-- _unbindAll () {- if (this._bindings) {- for (const dispose of this._bindings.values()) dispose()- this._bindings = null- }- }-- /** Free this node and its subtree on the native side (after removing it). */- destroy () {- for (const c of this.childNodes) c.destroy()- this.ownerWindow._free(this)- }-- get textContent () { return this.childNodes.map(c => c.textContent).join('') }-}--class TextNode extends Node {- constructor (win, id, text) {- super(win, id)- this._text = text- }-- get nodeType () { return 3 }- get data () { return this._text }- /** A string, or a signal (the text then follows it). */- set data (t) {- if (isSignal(t)) return this._bind('data', t, (v) => this._setText(v))- this._unbind('data')- this._setText(t)- }-- _setText (t) {- t = t == null ? '' : String(t)- if (t !== this._text) {- this._text = t- this.ownerWindow._op(OP.SET_TEXT, this.id, this.ownerWindow._s(t))- }- }-- get nodeValue () { return this._text }- set nodeValue (t) { this.data = t }- get textContent () { return this._text }- set textContent (t) { this.data = t }-}--class Element extends Node {- constructor (win, id, tag) {- super(win, id)- this.tagName = tag.toUpperCase()- this.localName = tag- this._attrs = new Map()- this._listeners = new Map()- this._bits = 0- // form controls: the latest value from input / change events- this.value = undefined- this.checked = undefined- }-- get nodeType () { return 1 }-- /** A value, or a signal: the attribute then follows it (null / false removes it). */- setAttribute (name, value) {- if (isSignal(value)) {- return this._bind(name, value, (v) => {- if (v == null || v === false) this._removeAttr(name)- else this._setAttr(name, name === 'style' && typeof v === 'object' ? styleText(v) : v === true ? '' : v)- })- }- this._unbind(name)- this._setAttr(name, value)- }-- _setAttr (name, value) {- value = String(value)- if (this._attrs.get(name) === value) return- this._attrs.set(name, value)- const w = this.ownerWindow- w._op(OP.SET_ATTR, this.id, w._s(name), w._s(value))- }-- getAttribute (name) { return this._attrs.get(name) ?? null }- hasAttribute (name) { return this._attrs.has(name) }-- removeAttribute (name) {- this._unbind(name)- this._removeAttr(name)- }-- _removeAttr (name) {- if (this._attrs.delete(name)) this.ownerWindow._op(OP.REMOVE_ATTR, this.id, this.ownerWindow._s(name))- }-- get className () { return this._attrs.get('class') ?? '' }- set className (v) { this.setAttribute('class', v) }- get style () { return this._attrs.get('style') ?? '' }- /** A CSS declaration string, or an object (`{ backgroundColor: 'red', width: 40 }`). */- set style (v) {- if (v == null) return this.removeAttribute('style')- if (typeof v === 'string' || isSignal(v)) return this.setAttribute('style', v)- // an object: plain values, or some signals (`{ color: colorSignal }`), then bound- for (const k in v) if (isSignal(v[k])) return this.setAttribute('style', memo(() => styleText(v)))- this.setAttribute('style', styleText(v))- }- get textContent () { return super.textContent }- set textContent (t) {- for (const c of [...this.childNodes]) { this.removeChild(c); c.destroy() }- if (t !== '' && t != null) this.appendChild(this.ownerWindow.createTextNode(isSignal(t) ? t : String(t)))- }-- addEventListener (type, fn) {- if (!(type in EVENT_BITS)) throw new Error(`blenderui: unsupported event "${type}"`)- let set = this._listeners.get(type)- if (!set) this._listeners.set(type, (set = new Set()))- set.add(fn)- this._listen()- }-- removeEventListener (type, fn) {- this._listeners.get(type)?.delete(fn)- this._listen()- }-- _listen () {- let bits = 0- for (const [type, set] of this._listeners) if (set.size) bits |= EVENT_BITS[type]- if (bits !== this._bits) {- this._bits = bits- this.ownerWindow._op(OP.LISTEN, this.id, bits)- }- }-- _dispatch (raw) {- if (raw.kind === 'input' || raw.kind === 'change') {- this.value = raw.value- this.checked = raw.checked- this.valueAsNumber = raw.number- }- const e = new BuiEvent(raw, this)- for (let n = this; n !== null; n = n.parentNode) {- const set = n._listeners?.get(raw.kind)- if (set && set.size) {- e.currentTarget = n- for (const fn of [...set]) {- try { fn.call(n, e) } catch (err) { queueMicrotask(() => { throw err }) }- if (e.immediatePropagationStopped) break- }- }- if (e.propagationStopped || !e.bubbles) break- }- e.currentTarget = null- }-- /** Layout box `{ x, y, width, height }` in logical pixels (or null). */- getBoundingClientRect () {- this.ownerWindow.flush() // the UI thread must see the tree first- return this.ownerWindow.app.native.bounds(this.ownerWindow.id, this.id)- }-}--const UNITLESS = new Set(['opacity', 'z-index', 'flex', 'flex-grow', 'flex-shrink', 'order', 'font-weight',- 'line-height', 'zoom', 'aspect-ratio', 'grid-row', 'grid-column', 'scale'])--/** `{ backgroundColor: 'red', width: 40 }` -> `background-color: red; width: 40px` */-function styleText (o) {- let s = ''- for (const k in o) {- const raw = o[k]- const v = isSignal(raw) ? raw.value : raw // read: a memo around this follows it- if (v == null || v === false || v === '') continue- const prop = k.startsWith('--') ? k : k.replace(/[A-Z]/g, m => '-' + m.toLowerCase())- s += `${prop}: ${typeof v === 'number' && v !== 0 && !UNITLESS.has(prop) ? v + 'px' : v}; `- }- return s-}+const dom = require('./dom')+const { OP, HTMLElement, TextNode, Comment, DocumentFragment, createElement } = domclass Window {constructor (app, id, options = {}) {@@ -347,8 +49,11 @@ class Window {this._nextFrameId = 1this._framePending = falsethis._inFrame = false+ this._orphans = []/** The root element: node 0. */- this.body = new Element(this, 0, 'body')+ this.body = new HTMLElement('body')+ this.body.ownerWindow = this+ this.body.id = 0this._nodes.set(0, this.body)app.native.openWindow(id, {title: options.title, width: options.width, height: options.height,@@ -356,37 +61,29 @@ class Window {})}- createElement (tag) {- // Blender's widgets: capitalized tags are always Blender widgets; their- // lowercase HTML counterparts look like a browser's (Blender's inside `styled`)- const blender = BLENDER_COMPONENTS[tag]- if (blender) {- const el = this.createElement(blender[0])- if (blender[1]) el.setAttribute('type', blender[1])- el.setAttribute('bui-blender', '')- return el- }- const id = this._next++- const el = new Element(this, id, tag)- this._nodes.set(id, el)- this._op(OP.CREATE, id, this._s(tag))- return el- }+ /** An element. Capitalized tags are Blender's widgets (`Button`, `NumberSlider` ...). */+ createElement (tag) { return createElement(this, tag) }/** A text node; `text` may be a signal (the text then follows it). */createTextNode (text) {- const id = this._next++- const bound = isSignal(text)- const t = new TextNode(this, id, bound ? String(text.peek() ?? '') : String(text))- this._nodes.set(id, t)- this._op(OP.TEXT, id, this._s(t._text))- if (bound) t.data = text+ const t = new TextNode('')+ t.data = text+ t._attach(this)return t}+ createComment (data = '') {+ const c = new Comment(String(data))+ c._attach(this)+ return c+ }++ createDocumentFragment () { return new DocumentFragment() }+/** Changes are sent once per tick; `flush()` sends them now. */flush () {this._scheduled = false+ if (this._orphans.length > 0) this._sweep()if (this.closed) {this._ops = []this._strings = []@@ -493,6 +190,21 @@ class Window {return i}+ /** A node of `document` was removed: freed at the next flush unless reinserted. */+ _orphan (node) {+ this._orphans.push(node)+ if (!this._scheduled) {+ this._scheduled = true+ queueMicrotask(() => this.flush())+ }+ }++ _sweep () {+ const orphans = this._orphans+ this._orphans = []+ for (const n of orphans) if (n.parentNode === null) n.destroy()+ }+_free (node) {node._unbindAll()if (node.id === 0 || !this._nodes.delete(node.id)) return // the body, or freed already@@ -565,19 +277,4 @@ class App {}}-/** Capitalized Blender widgets for `createElement`: [HTML tag, input type]. */-const BLENDER_COMPONENTS = {- Button: ['button'],- Checkbox: ['input', 'checkbox'],- Radio: ['input', 'radio'],- NumberField: ['input', 'number'],- NumberSlider: ['input', 'range'],- TextField: ['input', 'text'],- TextArea: ['textarea'],- ColorSwatch: ['input', 'color'],- Dropdown: ['select'],- ProgressBar: ['progress'],-}--module.exports = {- BLENDER_COMPONENTS, App, Window, Element, TextNode, Node, BuiEvent, styleText, BUTTONS, native, ...signals }+module.exports = { ...dom, App, Window, native, ...signals }diff --git a/bindings/node/package.json b/bindings/node/package.jsonindex 594f60f..4f8f5ba 100644--- a/bindings/node/package.json+++ b/bindings/node/package.json@@ -17,6 +17,7 @@},"files": ["index.js",+ "dom.js","signals.js","index.d.ts","cli.js",diff --git a/bindings/node/test/native.test.js b/bindings/node/test/native.test.jsindex 94b6476..09ea232 100644--- a/bindings/node/test/native.test.js+++ b/bindings/node/test/native.test.js@@ -122,3 +122,59 @@ test('DOM semantics: moving nodes, insertBefore checks, bubbling with stopPropagawait tick()assert.deepStrictEqual(log, ['x', 'b target=true current=true'], 'stopPropagation stops it')})++test('document: detached nodes join a window when inserted; fragments, clones, comments (headless)', async (t) => {+ const { App, document } = require('..')+ const app = new App({ headless: true })+ t.after(() => app.quit())+ const win = app.window({ width: 100, height: 100 })+ win.body.style = 'margin: 0'+ const tpl = document.createElement('div')+ tpl.className = 'flex gap-[20px]'+ tpl.append(document.createElement('Button'), document.createComment('anchor'), 'text')+ assert.strictEqual(tpl.ownerWindow, null, 'detached: nothing native yet')+ const copy = tpl.cloneNode(true)+ assert.deepStrictEqual(copy.childNodes.map(n => n.nodeName), ['BUTTON', '#comment', '#text'])+ assert.strictEqual(copy.firstChild.getAttribute('bui-blender'), '', 'a Blender widget, cloned')+ const frag = document.createDocumentFragment()+ frag.append(copy)+ win.body.appendChild(frag)+ assert.strictEqual(frag.firstChild, null, 'a fragment inserts its children')+ assert.strictEqual(copy.ownerWindow, win)+ assert.ok(copy.childNodes.every(n => n.ownerWindow === win && win._nodes.get(n.id) === n), 'the subtree joined the window')+ assert.strictEqual(copy.textContent, 'text', 'comments are not text')+ assert.ok(copy.isConnected)+ // linked siblings+ const [btn, comment, text] = copy.childNodes+ assert.strictEqual(btn.nextSibling, comment)+ assert.strictEqual(text.previousSibling, comment)+ comment.after('more')+ assert.strictEqual(comment.nextSibling.data, 'more')+ // the style object, classList, reflected properties+ btn.style.setProperty('width', '30px')+ btn.style.setProperty('height', '10px')+ btn.style.removeProperty('width')+ assert.strictEqual(btn.style.cssText.trim(), 'height: 10px;')+ btn.classList.add('a', 'b')+ btn.classList.toggle('a')+ assert.strictEqual(btn.className, 'b')+ btn.disabled = true+ assert.strictEqual(btn.getAttribute('disabled'), '')+ btn.disabled = false+ assert.strictEqual(btn.hasAttribute('disabled'), false)+ // dispatchEvent and composedPath; event types BUI doesn't report are accepted+ const seen = []+ win.body.addEventListener('custom', (e) => seen.push(e.target === btn && e.currentTarget === win.body))+ btn.addEventListener('pointerdown', () => {})+ btn.dispatchEvent(new CustomEvent('custom', { bubbles: true }))+ assert.deepStrictEqual(seen, [true])+ // a document's node removed and dropped is freed at the end of the tick; reinserted, kept+ await new Promise(r => setTimeout(r, 30))+ const size = win._nodes.size+ text.remove()+ btn.remove()+ copy.appendChild(btn)+ await new Promise(r => setTimeout(r, 30))+ assert.strictEqual(win._nodes.size, size - 1, 'the dropped text node is freed; the moved button is not')+ assert.ok(win._nodes.has(btn.id))+})