@blender-ui/native 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# @blender-ui/native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Blender's UI toolkit from JavaScript: native windows drawn on the CPU or with
+Direct3D 11, HTML elements, CSS and Tailwind classes, and signals. It runs on
+Node.js and Bun through a native addon (napi-rs), with no browser and no
+Electron. For React, see
+[`@blender-ui/react`](https://www.npmjs.com/package/@blender-ui/react).
+
+```sh
+npm install @blender-ui/native
+```
+
+```js
+const { App, signal } = require('@blender-ui/native')
+
+const app = new App({ gpu: true })
+const win = app.window({ title: 'Hello', width: 360, height: 200 })
+win.body.className = 'm-0 p-6 flex flex-col gap-3 bg-[#2b2b2b] text-[#e6e6e6]'
+
+const clicks = signal(0)
+const label = win.createElement('span')
+label.textContent = clicks            // follows the signal
+const button = win.createElement('button')
+button.textContent = 'Add one'
+button.addEventListener('click', () => clicks.value++)
+win.body.appendChild(label)
+win.body.appendChild(button)
+```
+
+## API
+
+- **A DOM-like tree:** `createElement`, `createTextNode`, `appendChild`,
+  `insertBefore`, `removeChild`, `setAttribute`, `className` (with Tailwind
+  classes), `style` (a string or an object), `textContent`.
+- **Events:** `addEventListener` for `click`, `mousedown`, `mouseup`,
+  `mousemove`, `mouseenter`, `mouseleave`, `wheel`, `keydown`, `keyup`, `input`
+  and `change`. They bubble through the tree, and `stopPropagation()` works.
+  They arrive after BUI has handled them, so `preventDefault()` only marks the
+  event.
+- **Frames and measurement:** `win.requestAnimationFrame(cb)` is paced by the
+  display. `el.getBoundingClientRect()` and `win.screenshot()` return
+  promises.
+- **Signals:** `signal`, `memo`, `effect`, `batch`, `untrack`,
+  `startTransition`. Pass a signal to `setAttribute`, `style`, `textContent`
+  or `createTextNode`, and its changes update that node alone. The signals are
+  also available without the addon: `require('@blender-ui/native/signals')`.
+- **Tests:** `new App({ headless: true })` renders off-screen, and
+  `win.click(x, y)` simulates input.
+
+## How it's fast
+
+- **Its own UI thread:** BUI renders on a thread of its own, so it never
+  blocks Node and an idle window uses no CPU.
+- **Only changes cross:** each tick, a window sends one batch of operations
+  (an `Int32Array` and a string table) to the UI thread.
+- **Styles parsed once:** a `style` value is parsed when it's set, not every
+  frame.
+
+## Requirements
+
+- **Prebuilt for Windows x64.** On other platforms, build from a clone of the
+  [repository](https://github.com/ppmpreetham/BUI) with `npm run build` in
+  `bindings/node`. That needs Rust, CMake and a C compiler; native windows
+  there are not supported yet, so use `headless: true`.
+- **Runtimes:** Node.js 18 or newer, or Bun.
+
+Guide, benchmarks and internals:
+[docs/javascript.md](https://github.com/ppmpreetham/BUI/blob/main/docs/javascript.md).
+License: GPL-2.0-or-later.

package/index.d.ts

@@ -0,0 +1,187 @@
+// Types for @blender-ui/native.
+export interface AppOptions {
+  /** Draw on the GPU (Direct3D 11). */
+  gpu?: boolean
+  /** GPU text from glyph outlines (Slug, default) or a per-glyph atlas. */
+  slug?: boolean
+  /** No native windows: tests, screenshots, CI. */
+  headless?: boolean
+  /** Quit when the last window closes (default true). */
+  quitOnLastWindowClosed?: boolean
+}
+
+export interface WindowOptions {
+  title?: string
+  width?: number
+  height?: number
+  resizable?: boolean
+  gpu?: boolean
+}
+
+export type EventType = 'click' | 'mousedown' | 'mouseup' | 'mousemove' | 'mouseenter' | 'mouseleave' |
+  'wheel' | 'keydown' | 'keyup' | 'change' | 'input'
+
+export class BuiEvent {
+  type: EventType
+  target: Element
+  currentTarget: Element
+  clientX: number
+  clientY: number
+  x: number
+  y: number
+  button: number
+  detail: number
+  deltaY: number
+  key?: string
+  char?: string
+  shiftKey: boolean
+  ctrlKey: boolean
+  altKey: boolean
+  metaKey: boolean
+  timeStamp: number
+  preventDefault (): void
+  stopPropagation (): void
+}
+
+export class Node {
+  readonly ownerWindow: Window
+  readonly id: number
+  parentNode: Element | null
+  childNodes: Node[]
+  readonly firstChild: Node | null
+  readonly lastChild: Node | null
+  readonly nextSibling: Node | null
+  textContent: string
+  appendChild<T extends Node> (child: T): T
+  insertBefore<T extends Node> (child: T, before: Node | null): T
+  removeChild<T extends Node> (child: T): T
+  remove (): void
+  /** Free the node and its subtree natively (after removing it). */
+  destroy (): void
+}
+
+export class TextNode extends Node {
+  /** A string, or a signal (the text then follows it). */
+  data: string | ReadSignal<unknown>
+  nodeValue: string
+}
+
+export class Element extends Node {
+  readonly tagName: string
+  readonly localName: string
+  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
+  /** A value, or a signal: the attribute then follows it (null / false removes it). */
+  setAttribute (name: string, value: unknown): void
+  getAttribute (name: string): string | null
+  hasAttribute (name: string): boolean
+  removeAttribute (name: string): void
+  addEventListener (type: EventType, listener: (event: BuiEvent) => void): void
+  removeEventListener (type: EventType, listener: (event: BuiEvent) => void): void
+  getBoundingClientRect (): Promise<{ x: number, y: number, width: number, height: number } | null>
+}
+
+export class Window {
+  readonly app: App
+  readonly id: number
+  readonly body: Element
+  closed: boolean
+  createElement (tag: string): Element
+  createTextNode (text: string | ReadSignal<unknown>): TextNode
+  /** Send pending changes now (they are otherwise sent once per tick). */
+  flush (): void
+  /** Run `cb` before the next frame, paced by the display. */
+  requestAnimationFrame (cb: (time: number) => void): number
+  cancelAnimationFrame (id: number): void
+  screenshot (): Promise<{ width: number, height: number, data: Buffer }>
+  click (x: number, y: number): void
+  close (): void
+  on (event: 'close', listener: () => void): this
+}
+
+export class App {
+  constructor (options?: AppOptions)
+  readonly headless: boolean
+  readonly windows: Map<number, Window>
+  quitOnLastWindowClosed: boolean
+  window (options?: WindowOptions): Window
+  setSlug (on: boolean): void
+  quit (): void
+}
+
+export function styleText (style: Record<string, string | number | null | undefined>): string
+
+// Signals: BUI's hooks (the Rust crate's Signal / Memo / Effect).
+// Bind one to an attribute, `style` or text and that node alone updates.
+
+export interface ReadSignal<T> {
+  /** Read, subscribing the running memo / effect. */
+  readonly value: T
+  get (): T
+  /** Read without subscribing. */
+  peek (): T
+  with<R> (fn: (value: T) => R): R
+  /** Call `fn` now and on every change; returns the unsubscribe function. */
+  subscribe (fn: (value: T) => void): () => void
+  /** `count + 1`, `count > 5` read the value (`===` and truthiness don't: use `.value`). */
+  valueOf (): T
+}
+
+export class Signal<T> implements ReadSignal<T> {
+  constructor (value: T, options?: { equals?: (a: T, b: T) => boolean })
+  value: T
+  get (): T
+  peek (): T
+  set (value: T): void
+  update (fn: (value: T) => T): void
+  with<R> (fn: (value: T) => R): R
+  subscribe (fn: (value: T) => void): () => void
+  valueOf (): T
+}
+
+export class Memo<T> implements ReadSignal<T> {
+  readonly value: T
+  get (): T
+  peek (): T
+  with<R> (fn: (value: T) => R): R
+  subscribe (fn: (value: T) => void): () => void
+  valueOf (): T
+}
+
+export function signal<T> (value: T, options?: { equals?: (a: T, b: T) => boolean }): Signal<T>
+/** A lazily derived, cached value, recomputed when the signals it read change. */
+export function memo<T> (fn: () => T, options?: { equals?: (a: T, b: T) => boolean }): Memo<T>
+export const computed: typeof memo
+/** Runs `fn` now and when what it read changes; `fn` may return a cleanup. Returns `dispose`. */
+export function effect (fn: () => void | (() => void)): () => void
+/** Several writes, one update. */
+export function batch<R> (fn: () => R): R
+export function untrack<R> (fn: () => R): R
+/** Leptos / Solid style getter and setter. */
+export function createSignal<T> (value: T): [() => T, (value: T | ((prev: T) => T)) => void]
+export function isSignal (x: unknown): x is ReadSignal<unknown>
+/** Writes in `fn` update what they affect after urgent work, in slices. Settles
+ *  when done; rejects with the error of an async `fn`. */
+export function startTransition (fn: () => void | Promise<void>): Promise<void>
+/** Run `fn` at urgent priority, even inside a transition. */
+export function urgent<R> (fn: () => R): R
+
+/** A ref whose `.current` effects and memos can follow (reading it while a
+ *  React component renders doesn't subscribe). */
+export class Ref<T> extends Signal<T> { current: T }
+export function ref<T> (value: T): Ref<T>
+/** Run `fn` outside any owning effect: effects it creates live until disposed. */
+export function unowned<R> (fn: () => R): R
+
+/** The addon (internal), plus counters for benchmarks. */
+export const native: {
+  /** CPU cycles of every thread of this process (Windows), or null. */
+  processCpuCycles (): number | null
+  /** The x86-64 time-stamp counter, or null. */
+  timestampCounter (): number | null
+  [key: string]: unknown
+}