@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 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
- # Temporary Holding Version
1
+ # @barqjs/universal
2
2
 
3
- 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.
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.
@@ -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"}