@barqjs/universal 0.0.0-stage → 0.2.0-next.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +154 -2
- package/dist/index.d.ts +108 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +685 -0
- package/dist/index.js.map +1 -0
- package/dist/jsx-runtime.d.ts +47 -0
- package/dist/jsx-runtime.d.ts.map +1 -0
- package/dist/jsx-runtime.js +1 -0
- package/package.json +73 -4
- package/src/index.ts +23 -0
- package/src/jsx-runtime.ts +76 -0
- package/src/renderer.ts +1061 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Salama Ashoush
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,155 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @barqjs/universal
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
barq on a host other than the document: a terminal, a canvas scene graph, a
|
|
4
|
+
native view tree, or anything else that has nodes with children. You describe
|
|
5
|
+
the host's node operations once, and `createRenderer` returns `render` and the
|
|
6
|
+
runtime the compiler's universal target calls. Signals, components and control
|
|
7
|
+
flow come from `@barqjs/core`, which this package lists as a peer dependency.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
bun add @barqjs/core @barqjs/universal
|
|
13
|
+
bun add -d @barqjs/vite vite
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## A renderer
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
// src/renderer.ts
|
|
20
|
+
import { createRenderer } from "@barqjs/universal";
|
|
21
|
+
|
|
22
|
+
export const {
|
|
23
|
+
render,
|
|
24
|
+
createElement,
|
|
25
|
+
createTextNode,
|
|
26
|
+
insertNode,
|
|
27
|
+
setProp,
|
|
28
|
+
insert,
|
|
29
|
+
spread,
|
|
30
|
+
branch,
|
|
31
|
+
each,
|
|
32
|
+
boundary,
|
|
33
|
+
island,
|
|
34
|
+
reveal,
|
|
35
|
+
portal,
|
|
36
|
+
dynamic,
|
|
37
|
+
Portal,
|
|
38
|
+
} = createRenderer<SceneNode>({
|
|
39
|
+
createElement: (tag) => new SceneNode(tag),
|
|
40
|
+
createTextNode: (value) => new SceneText(value),
|
|
41
|
+
replaceText: (node, value) => ((node as SceneText).value = value),
|
|
42
|
+
isTextNode: (node) => node instanceof SceneText,
|
|
43
|
+
setProperty: (node, name, value) => node.set(name, value),
|
|
44
|
+
insertNode: (parent, node, anchor) => parent.insertBefore(node, anchor),
|
|
45
|
+
removeNode: (parent, node) => parent.removeChild(node),
|
|
46
|
+
getParentNode: (node) => node.parent,
|
|
47
|
+
getFirstChild: (node) => node.firstChild,
|
|
48
|
+
getNextSibling: (node) => node.nextSibling,
|
|
49
|
+
});
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
`insertNode` has to move a node that already has a parent, as the document's
|
|
53
|
+
`insertBefore` does. `createSentinel` and `createContainer` are optional: the
|
|
54
|
+
first defaults to an empty text node, the second to `createElement("#container")`.
|
|
55
|
+
|
|
56
|
+
`attachRef(node, deliver)` is optional too. Without it a `ref` is handed the
|
|
57
|
+
node. A host whose node stands for an object it builds later, such as a three.js
|
|
58
|
+
object that needs constructor arguments a later property brings, calls
|
|
59
|
+
`deliver` with that object once it exists and again whenever it is replaced, and
|
|
60
|
+
returns a function that stops delivering.
|
|
61
|
+
|
|
62
|
+
`placed(parent)` is optional as well. The renderer calls it once a batch of
|
|
63
|
+
inserts under `parent` is over: a list it placed, a hole it filled, a range it
|
|
64
|
+
moved. A host that keeps a second order of its own, such as three.js's
|
|
65
|
+
`children` array, can append during the batch and sort once here.
|
|
66
|
+
|
|
67
|
+
## Compiling for it
|
|
68
|
+
|
|
69
|
+
Point the compiler at the renderer module for the files that render through it:
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
// vite.config.ts
|
|
73
|
+
import barq from "@barqjs/vite";
|
|
74
|
+
|
|
75
|
+
export default {
|
|
76
|
+
plugins: [
|
|
77
|
+
barq({
|
|
78
|
+
compiler: {
|
|
79
|
+
renderers: [
|
|
80
|
+
{ include: ["src/scene/**"], target: "universal", moduleSource: "/src/renderer.ts" },
|
|
81
|
+
],
|
|
82
|
+
},
|
|
83
|
+
}),
|
|
84
|
+
],
|
|
85
|
+
};
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Every other file keeps compiling for the document, so one app can hold both.
|
|
89
|
+
A whole project for one host sets `compiler: { target: "universal",
|
|
90
|
+
moduleSource }` instead. In the files compiled for it, an element is created with
|
|
91
|
+
`createElement`, every attribute and event is one `setProp` call
|
|
92
|
+
(`onClick={handler}` is `setProp(node, "onClick", handler)`), and `<Show>`,
|
|
93
|
+
`<For>`, `<Loading>`, `<Errored>` and `<Portal>` run over the host. `bind:`,
|
|
94
|
+
a form `action`, `hydratable` and `ssr` are document concepts and are
|
|
95
|
+
reported as errors.
|
|
96
|
+
|
|
97
|
+
Set `"jsxImportSource": "@barqjs/universal"` for any tag and any property, or
|
|
98
|
+
point it at your renderer package's own `jsx-runtime` to type its tags.
|
|
99
|
+
|
|
100
|
+
### Inside a document file
|
|
101
|
+
|
|
102
|
+
A component can host the renderer inside a page, the way a canvas hosts a
|
|
103
|
+
scene. Declare it in the renderer package's `package.json` and `@barqjs/vite`
|
|
104
|
+
compiles its children for the renderer in every file that imports it, while
|
|
105
|
+
the JSX around it stays the document's:
|
|
106
|
+
|
|
107
|
+
```json
|
|
108
|
+
"barq": {
|
|
109
|
+
"boundaries": [{ "name": "Canvas", "target": "universal", "moduleSource": "@acme/scene/renderer" }]
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
The component receives its children unbuilt and renders them in a root of its
|
|
114
|
+
own, which is what gives them this host:
|
|
115
|
+
|
|
116
|
+
```ts
|
|
117
|
+
import { getOwner, onCleanup } from "@barqjs/core";
|
|
118
|
+
import { render } from "./renderer.ts";
|
|
119
|
+
|
|
120
|
+
export function Canvas(props: { children?: unknown }) {
|
|
121
|
+
const scene = createScene();
|
|
122
|
+
onCleanup(render(() => props.children as never, scene.root, { owner: getOwner() }));
|
|
123
|
+
return scene.canvas;
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
A server build renders `Canvas` itself and leaves its children out.
|
|
128
|
+
|
|
129
|
+
Components built from the renderer's tags are usually declared outside the
|
|
130
|
+
`Canvas`, in the page's file or one of their own. The package claims those
|
|
131
|
+
tags, and a tree rooted at one compiles for the renderer wherever it is
|
|
132
|
+
written:
|
|
133
|
+
|
|
134
|
+
```json
|
|
135
|
+
"barq": {
|
|
136
|
+
"intrinsics": [{ "tags": ["mesh", "group"], "target": "universal", "moduleSource": "@acme/scene/renderer" }]
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
A component that only arranges others, such as a `<For>` over `<Box>` or a
|
|
141
|
+
`<Show>` choosing between two of them, names no tag and needs no claim: its
|
|
142
|
+
control flow builds on the host of the root it is rendered in.
|
|
143
|
+
|
|
144
|
+
## Rendering
|
|
145
|
+
|
|
146
|
+
```tsx
|
|
147
|
+
import { render } from "./renderer.ts";
|
|
148
|
+
|
|
149
|
+
const dispose = render(() => <App />, scene.root);
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
A tree rendered this way renders `<Show>` and its siblings through this host
|
|
153
|
+
even in an app that also renders into the document. `<Portal mount={node}>`
|
|
154
|
+
mounts into another node of the same host, and into the render root when
|
|
155
|
+
`mount` is left out.
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@barqjs/universal`: barq on a host other than the document. A renderer
|
|
3
|
+
* module calls `createRenderer` with the host's node operations once and
|
|
4
|
+
* exports what it returns; the compiler, given that module as `moduleSource`
|
|
5
|
+
* and `target: "universal"`, builds every element through it.
|
|
6
|
+
*
|
|
7
|
+
* ```ts
|
|
8
|
+
* export const {
|
|
9
|
+
* render, createElement, createTextNode, insertNode, setProp, insert, spread,
|
|
10
|
+
* branch, each, boundary, island, reveal, portal, dynamic, Portal,
|
|
11
|
+
* } = createRenderer(ops);
|
|
12
|
+
* ```
|
|
13
|
+
*/
|
|
14
|
+
import { Block, BoundaryKind, COUNT, Cell, JSXElement, Maybe, RevealOrder, Scope } from "@barqjs/core";
|
|
15
|
+
import { RangeHost, SyncRows } from "@barqjs/core/internal";
|
|
16
|
+
/**
|
|
17
|
+
* What a host gives the renderer. `N` is the host's node; the renderer never
|
|
18
|
+
* looks inside one.
|
|
19
|
+
*
|
|
20
|
+
* `insertNode` MOVES a node that already has a parent, the way the document's
|
|
21
|
+
* `insertBefore` does: a reorder is an insert of a node that is already in
|
|
22
|
+
* the tree, and the renderer never removes it first.
|
|
23
|
+
*/
|
|
24
|
+
interface HostOps<N extends object> {
|
|
25
|
+
createElement(tag: string): N;
|
|
26
|
+
createTextNode(value: string): N;
|
|
27
|
+
replaceText(node: N, value: string): void;
|
|
28
|
+
isTextNode(node: N): boolean;
|
|
29
|
+
/** `prev` is the value this name was last set to on this node, `undefined` the first time. */
|
|
30
|
+
setProperty(node: N, name: string, value: unknown, prev: unknown): void;
|
|
31
|
+
/** Put `node` under `parent` before `anchor`, or last when `anchor` is `null`. */
|
|
32
|
+
insertNode(parent: N, node: N, anchor: N | null): void;
|
|
33
|
+
removeNode(parent: N, node: N): void;
|
|
34
|
+
getParentNode(node: N): N | null | undefined;
|
|
35
|
+
getFirstChild(node: N): N | null | undefined;
|
|
36
|
+
getNextSibling(node: N): N | null | undefined;
|
|
37
|
+
/** A node that renders nothing, to anchor a range against. Defaults to an empty text node. */
|
|
38
|
+
createSentinel?(): N;
|
|
39
|
+
/**
|
|
40
|
+
* A detached node that holds children, for content built while it is not
|
|
41
|
+
* shown: a `<Loading>` boundary's body while its fallback stands, or a range
|
|
42
|
+
* built before anything placed it. Defaults to `createElement("#container")`.
|
|
43
|
+
*/
|
|
44
|
+
createContainer?(): N;
|
|
45
|
+
/**
|
|
46
|
+
* Hand a `ref` what it should hold for `node`, in place of the node itself.
|
|
47
|
+
* A host whose node stands for an object it builds later (once a property
|
|
48
|
+
* the object's constructor needs has arrived) calls `deliver` with that
|
|
49
|
+
* object when it exists and again each time it is replaced, and returns the
|
|
50
|
+
* function that stops delivering. Without it a ref is handed the node, once.
|
|
51
|
+
*/
|
|
52
|
+
attachRef?(node: N, deliver: (value: unknown) => void): () => void;
|
|
53
|
+
/**
|
|
54
|
+
* Told once a batch of inserts under `parent` is done: the nodes a list
|
|
55
|
+
* placed, a hole filled, a range moved. A host that keeps its own order of
|
|
56
|
+
* children cheaply by appending during the batch puts them in order here,
|
|
57
|
+
* so nothing reads them in the wrong order.
|
|
58
|
+
*/
|
|
59
|
+
placed?(parent: N): void;
|
|
60
|
+
}
|
|
61
|
+
/** What `render` accepts besides the tree and the node it is mounted into. */
|
|
62
|
+
interface RenderOptions {
|
|
63
|
+
/** Parents the root, so the tree reads that owner's contexts and is disposed with it. */
|
|
64
|
+
readonly owner?: Scope | null;
|
|
65
|
+
readonly renderId?: string;
|
|
66
|
+
}
|
|
67
|
+
interface PortalProps<N extends object> {
|
|
68
|
+
/** The node the children mount into. Defaults to the node the tree was rendered into. */
|
|
69
|
+
mount?: N | null | (() => N | null | undefined);
|
|
70
|
+
children: unknown;
|
|
71
|
+
}
|
|
72
|
+
/** What a `dynamic` source may answer with: a tag name or a function of one props object. */
|
|
73
|
+
type DynamicTag = string | ((props: never) => unknown);
|
|
74
|
+
type Spreadable = Record<string, unknown> | (() => Record<string, unknown>);
|
|
75
|
+
/**
|
|
76
|
+
* What `createRenderer` returns. Every member is a function of its arguments
|
|
77
|
+
* alone, so a renderer module destructures them into its exports.
|
|
78
|
+
*/
|
|
79
|
+
interface Renderer<N extends object> {
|
|
80
|
+
/**
|
|
81
|
+
* Build `code` under a new root and put what it renders into `root`. The
|
|
82
|
+
* returned function disposes the root and removes what it placed.
|
|
83
|
+
*/
|
|
84
|
+
render: (code: (() => JSXElement) | JSXElement, root: N, options?: RenderOptions) => () => void;
|
|
85
|
+
createElement: (tag: string) => N;
|
|
86
|
+
createTextNode: (value: string) => N;
|
|
87
|
+
insertNode: (parent: N, node: N, anchor?: N | null) => void;
|
|
88
|
+
/** Writes one property and returns `value`, so a binding can keep it as its previous value. */
|
|
89
|
+
setProp: <T>(node: N, name: string, value: T, prev?: unknown) => T;
|
|
90
|
+
insert: (parent: N, value: unknown, anchor?: N | null) => void;
|
|
91
|
+
spread: (node: N, props: Spreadable, later?: readonly string[]) => void;
|
|
92
|
+
branch: <K>(parent: N | null, anchor: N | null, key: Cell<K>, bodies: Block<unknown> | readonly (Block<unknown> | null | undefined)[], flags?: number) => N | N[] | null;
|
|
93
|
+
each: <T>(parent: N | null, anchor: N | null, src: Cell<Maybe<readonly T[]>> | Cell<number>, carrier: ((item: T) => unknown) | false | null | typeof COUNT | Cell<unknown>, row: Block<unknown, never[]>, flags?: number, fallback?: Block<unknown> | null) => N | N[] | null;
|
|
94
|
+
boundary: (parent: N | null, anchor: N | null, kind: BoundaryKind, fallback: Block<unknown> | null | undefined, body: Block<unknown>, flags?: number, on?: Cell<unknown>) => N | N[] | null;
|
|
95
|
+
island: (parent: N | null, anchor: N | null, block: Block<unknown>, flags?: number) => N | null;
|
|
96
|
+
reveal: (order: Cell<RevealOrder | undefined>, collapsed: Cell<boolean | undefined>, block: Block<unknown>) => N[];
|
|
97
|
+
portal: (target: Cell<N | null | undefined>, block: Block<unknown>, flags?: number) => N;
|
|
98
|
+
/** Solid 2.0's factory for a component chosen at run time: a tag name or a component. */
|
|
99
|
+
dynamic: (source: () => DynamicTag | null | undefined | false) => (props: Record<string, unknown>) => JSXElement;
|
|
100
|
+
Portal: (props: PortalProps<N>) => JSXElement;
|
|
101
|
+
/** The host control flow writes through, for a construct written by hand. */
|
|
102
|
+
host: RangeHost<N>;
|
|
103
|
+
/** The list reorder `each` hands control flow, over the same operations. */
|
|
104
|
+
syncRows: SyncRows<N>;
|
|
105
|
+
}
|
|
106
|
+
export declare function createRenderer<N extends object>(ops: HostOps<N>): Renderer<N>;
|
|
107
|
+
export type { DynamicTag, HostOps, PortalProps, RenderOptions, Renderer, Spreadable };
|
|
108
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","names":[],"sources":["../src/renderer.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;UAwEiB,QAAQ;EACvB,cAAc,cAAc;EAC5B,eAAe,gBAAgB;EAC/B,YAAY,MAAM,GAAG;EACrB,WAAW,MAAM;;EAEjB,YAAY,MAAM,GAAG,cAAc,gBAAgB;;EAEnD,WAAW,QAAQ,GAAG,MAAM,GAAG,QAAQ;EACvC,WAAW,QAAQ,GAAG,MAAM;EAC5B,cAAc,MAAM,IAAI;EACxB,cAAc,MAAM,IAAI;EACxB,eAAe,MAAM,IAAI;;EAEzB,mBAAmB;;;;;;EAMnB,oBAAoB;;;;;;;;EAQpB,WAAW,MAAM,GAAG,UAAU;;;;;;;EAO9B,QAAQ,QAAQ;;;UAID;;WAEN,QAAQ;WACR;;UAGM,YAAY;;EAE3B,QAAQ,kBAAkB;EAC1B;;;KAIU,wBAAwB;KAExB,aAAa,iCAAiC;;;;;UAMzC,SAAS;;;;;EAKxB,SAAS,aAAa,cAAc,YAAY,MAAM,GAAG,UAAU;EACnE,gBAAgB,gBAAgB;EAChC,iBAAiB,kBAAkB;EACnC,aAAa,QAAQ,GAAG,MAAM,GAAG,SAAS;;EAE1C,UAAU,GAAG,MAAM,GAAG,cAAc,OAAO,GAAG,mBAAmB;EACjE,SAAS,QAAQ,GAAG,gBAAgB,SAAS;EAC7C,SAAS,MAAM,GAAG,OAAO,YAAY;EACrC,SAAS,GACP,QAAQ,UACR,QAAQ,UACR,KAAK,KAAK,IACV,QAAQ,2BAA2B,sCACnC,mBACG,IAAI;EACT,OAAO,GACL,QAAQ,UACR,QAAQ,UACR,KAAK,KAAK,eAAe,QAAQ,cACjC,WAAW,MAAM,uCAAuC,QAAQ,eAChE,KAAK,yBACL,gBACA,WAAW,0BACR,IAAI;EACT,WACE,QAAQ,UACR,QAAQ,UACR,MAAM,cACN,UAAU,mCACV,MAAM,gBACN,gBACA,KAAK,kBACF,IAAI;EACT,SAAS,QAAQ,UAAU,QAAQ,UAAU,OAAO,gBAAgB,mBAAmB;EACvF,SACE,OAAO,KAAK,0BACZ,WAAW,2BACX,OAAO,mBACJ;EACL,SAAS,QAAQ,KAAK,uBAAuB,OAAO,gBAAgB,mBAAmB;;EAEvF,UACE,cAAc,2CACV,OAAO,4BAA4B;EACzC,SAAS,OAAO,YAAY,OAAO;;EAEnC,MAAM,UAAU;;EAEhB,UAAU,SAAS;;wBAoBL,eAAe,kBAAkB,KAAK,QAAQ,KAAK,SAAS"}
|