hyper-dom-expressions 0.50.0-next.2 → 0.50.0-next.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # hyper-dom-expressions
 
+## 0.50.0-next.3
+
+### Patch Changes
+
+- 4c4fb65: Fix ownership leak when composing control-flow components (`For`, `Show`, etc.) in hyperscript (solidjs/solid#2453). `h(...)` now returns a tagged zero-arity thunk whose body runs under `untrack`, so render effects created inside a child component — notably per-row effects created by `mapArray` inside `For` — are rooted under the child's owner instead of whichever `r.insert` effect happens to consume it. Mutating a parent list signal no longer disposes sibling rows' render effects.
+
+  The exported surface changes shape: `h(...)` previously returned a DOM node (or array) eagerly; it now returns a thunk you invoke. Recommended usage is `r.render(h(App), mountEl)` — `render` calls the thunk inside its root. Nested `h(...)` calls compose freely; tagged thunks auto-invoke at consumption and user accessors (`() => expr`) continue to route through `r.insert`. `props.children` is uniformly wrapped via `dynamicProperty` the same way other zero-arity function props are, matching Solid JSX's getter convention — consumers that want reactive re-reads wrap the access in a thunk (`h("p", () => props.children)`).
+
+- 4dae801: Normalize the `repository` field in every package to the standard npm
+  convention: a `git+https://github.com/ryansolid/dom-expressions.git` URL
+  with a `directory` pointing at the package within the monorepo. Restores
+  "View source" / "Open in repo" links on the npm registry and unblocks
+  tooling that resolves source from package metadata.
+
 ## 0.50.0-next.2
 
 ### Patch Changes

package/README.md

@@ -5,66 +5,114 @@
 ![](https://img.shields.io/bundlephobia/minzip/hyper-dom-expressions.svg?style=flat)
 ![](https://img.shields.io/npm/dt/hyper-dom-expressions.svg?style=flat)
 
-This package is a Runtime API built for [DOM Expressions](https://github.com/ryansolid/dom-expressions) to provide HyperScript DSL for reactive libraries that do fine grained change detection. While the JSX plugin [Babel Plugin JSX DOM Expressions](https://github.com/ryansolid/dom-expressions/blob/main/packages/babel-plugin-jsx-dom-expressions) is more optimized with precompilation, smaller size, and cleaner syntax, this HyperScript solution has the flexibility of not being precompiled. However, Tagged Template Literals are likely a better choice in terms of performance in non-compiled environments [Lit DOM Expressions](https://github.com/ryansolid/dom-expressions/blob/main/packages/lit-dom-expressions).
+HyperScript DSL for [DOM Expressions](https://github.com/ryansolid/dom-expressions), targeting fine-grained reactive libraries that want a no-build authoring syntax.
+
+> **Performance note.** Of the four DOM-expressions frontends, hyperscript is the **slowest**. Every `h(...)` call materializes a small tree at runtime, versus the precompiled constants and cloned templates emitted by [`babel-plugin-jsx-dom-expressions`](https://github.com/ryansolid/dom-expressions/blob/main/packages/babel-plugin-jsx-dom-expressions), or the parse-once-then-clone caching of [`lit-dom-expressions`](https://github.com/ryansolid/dom-expressions/blob/main/packages/lit-dom-expressions). Both hyper and lit run with no build step — if you just want a no-tooling authoring syntax, prefer `lit-dom-expressions`; it's considerably faster. Hyperscript's niche is interop with React-style JSX transforms and other ecosystems that already emit `h(tag, props, …children)` calls.
 
 ## Compatible Libraries
-* [Solid](https://github.com/ryansolid/solid): A declarative JavaScript library for building user interfaces.
-* [ko-jsx](https://github.com/ryansolid/ko-jsx): Knockout JS with JSX rendering.
-* [mobx-jsx](https://github.com/ryansolid/mobx-jsx): Ever wondered how much more performant MobX is without React? A lot.
+
+- [Solid](https://github.com/ryansolid/solid)
+- [ko-jsx](https://github.com/ryansolid/ko-jsx)
+- [mobx-jsx](https://github.com/ryansolid/mobx-jsx)
 
 ## Getting Started
 
-Install alongside the DOM Expressions and the fine grained library of your choice. For example with S.js:
+Install alongside DOM Expressions and a reactive library. For Solid:
 
 ```sh
-> npm install s-js dom-expressions hyper-dom-expressions
+npm install @solidjs/signals dom-expressions hyper-dom-expressions
 ```
-Create your configuration and run dom-expressions command to generate runtime.js. More info [here](https://github.com/ryansolid/dom-expressions).
 
-Use it to initialize your Hyper function
+Initialize `h` against the runtime:
+
 ```js
-import { createHyperScript } from 'hyper-dom-expressions';
-import * as r from './runtime';
+import { createHyperScript } from "hyper-dom-expressions";
+import * as r from "dom-expressions/src/client";
 
 const h = createHyperScript(r);
 ```
 
-Profit:
+Consumers typically re-export a pre-wired `h` — Solid exposes `solid-js/h`.
+
+## The `h` contract
+
+`h(...)` is **lazy**. Every call returns a zero-arity thunk tagged with an internal symbol; the thunk materializes DOM (or invokes the component) under the current reactive owner when called. Laziness is what keeps per-row render effects inside `For`/`mapArray` rooted under their own owners rather than the parent `insert` effect.
+
 ```js
-const view = h('table.table.table-hover.table-striped.test-data',
-  h('tbody', mapSample(() => state.data, row =>
-    h('tr', [
-      h('td.col-md-1', row.id),
-      h('td.col-md-4', h('a', {onClick: [select, row.id]}, () => row.label)),
-      h('td.col-md-1', h('a', {onClick: [remove, row.id]}, h('span.glyphicon.glyphicon-remove'))),
-      h('td.col-md-6')
-    ])
-  ))
-));
-
-S.root(() => r.insert(document.getElementById('main'), view());)
+const tree = h("div", h(Counter)); // thunk
+tree(); // materializes DOM
 ```
 
-Libraries may expose access to h in different ways. For example Solid has it's own entry point 'solid-js/h'.
+Mount via `r.render`. Pass the thunk directly; `render` invokes it inside its root so the whole tree materializes under that owner:
 
-## Differences from JSX
+```js
+import { render } from "dom-expressions/src/client";
+
+const App = () => h("main", h(Home));
+
+render(h(App), document.getElementById("app"));
+```
+
+Inside `h(...)` composition works without ceremony: nested `h(...)` children are invoked once at consumption, and user-supplied accessors (`() => expr`) route through `r.insert` so they stay reactive.
 
-There are also several small differences but generally follows HyperScript conventions. Ref work by passing a function. Keep in mind you need to wrap expressions in functions if you want them to be observed. For attributes since wrapping in a function is the only indicator of reactivity, passing a non-event function as a value requires wrapping it in a function.
+## Components, props, and children
 
-Fragments are just arrays. Components are handled by passing a Function to the first argument of the h function. Ie:
-```jsx
-const view = <>
-  <Component prop={value} />
-  {someValue()}
-</>
+- **Props are uniform.** Zero-arity function props are routed through `dynamicProperty` so reading them invokes the accessor and returns the current value — the same getter-style convention Solid's JSX compiler produces. Event props (`on…`) and higher-arity functions (e.g. a `For` render callback) pass through unchanged.
 
-// is equivalent to:
-const view = [
-  h(Component, {prop: value}),
-  () => someValue()
-]
+- **`props.children`** mirrors the caller's input:
+
+  | call shape | `props.children` |
+  | --- | --- |
+  | `h(Comp)` | `undefined` |
+  | `h(Comp, { children: v })` | `v` |
+  | `h(Comp, null, a)` | `a` |
+  | `h(Comp, null, a, b, c)` | `[a, b, c]` |
+
+  Nested `h(...)` thunks flow through as-is and auto-invoke once when consumed.
+
+- **Reactive consumption.** `h("p", props.children)` reads `props.children` once at render time. For reactive re-reads, the consumer wraps in its own accessor: `h("p", () => props.children)`. `r.insert` tracks the read and re-runs on change. This mirrors Solid JSX, which compiles `{props.children}` to `insert(el, () => props.children)`.
+
+- **Fragments** are either plain arrays (`[h(...), h(...)]`) or the built-in `h.Fragment` component.
+
+- **JSX-compiler interop.** Components compiled by `babel-plugin-jsx-dom-expressions` can be invoked from inside `h(...)`. Their bodies see the same `props` shape they expect from compiled call sites (getters for dynamic props, `children` as a value / function / array), so typical library components (e.g. Solid Router routes) work. The reverse direction — passing a hyperscript thunk to compiled call sites expecting an element — is not supported.
+
+## Example
+
+```js
+import { createHyperScript } from "hyper-dom-expressions";
+import * as r from "dom-expressions/src/client";
+import { createSignal, mapArray } from "@solidjs/signals";
+
+const h = createHyperScript(r);
+
+const For = props => mapArray(() => props.each, props.children);
+
+const App = () => {
+  const [rows, setRows] = createSignal([
+    { id: 1, label: "one" },
+    { id: 2, label: "two" }
+  ]);
+  return h(
+    "table.table",
+    h(
+      "tbody",
+      h(For, { each: rows }, row =>
+        h(
+          "tr",
+          h("td.col-md-1", () => row().id),
+          h("td.col-md-4", () => row().label)
+        )
+      )
+    )
+  );
+};
+
+r.render(h(App), document.getElementById("main"));
 ```
 
-## Status
+## Differences from JSX
 
-I'm still working out API details and performance profiling.
+- Refs are passed as a function prop (`ref: el => { … }`).
+- Reactivity is explicit: wrap expressions in a function when they should be tracked (`() => count()`), including when forwarding a component prop (`h("p", () => props.foo)`).
+- Fragments are arrays (or `h.Fragment`).
+- Tag selectors understand `#id` and `.class` shorthands (`h("div#main.sel", …)`).

package/dist/hyper-dom-expressions.js

@@ -1,14 +1,36 @@
+// Tags h() thunks so consumers can distinguish them from user-written
+// accessors and invoke them once under the correct owner rather than
+// wrapping them in an effect.
+const $ELEMENT = Symbol("hyper-element");
+
+
+
+
+
+
+
+
+
+
+
 // Inspired by https://github.com/hyperhype/hyperscript
 function createHyperScript(r) {
-  function h() {
-    let args = [].slice.call(arguments),
-      e,
-      classes = [],
-      multiExpression = false;
+  function h(...rawArgs) {
+    if (rawArgs.length === 1 && Array.isArray(rawArgs[0])) return rawArgs[0];
+    const thunk = () => r.untrack(() => materialize(rawArgs));
+    thunk[$ELEMENT] = true;
+    return thunk;
+  }
+
+  function materialize(args) {
+    let e;
+    let classes = [];
+    let multiExpression = false;
+    args = args.slice();
 
     function item(l) {
+      if (l == null) return;
       const type = typeof l;
-      if (l == null) ;else
       if ("string" === type) {
         if (!e) parseClass(l);else
         e.appendChild(document.createTextNode(l));
@@ -47,40 +69,34 @@ function createHyperScript(r) {
         r.assign(e, l, !!args.length);
       } else if ("function" === type) {
         if (!e) {
-          let props,
-            next = args[0];
-          if (
-          next == null ||
-          typeof next === "object" && !Array.isArray(next) && !(next instanceof Element))
-
-          props = args.shift();
-          props || (props = {});
-          if (args.length) {
-            props.children = args.length > 1 ? args : args[0];
-          }
-          const d = Object.getOwnPropertyDescriptors(props);
-          for (const k in d) {
-            if (typeof d[k].value === "function" && !d[k].value.length) r.dynamicProperty(props, k);
+          const first = args[0];
+          const props =
+          first == null ||
+          typeof first === "object" && !Array.isArray(first) && !(first instanceof Element) ?
+          args.shift() || {} :
+          {};
+          if (args.length) props.children = args.length > 1 ? args : args[0];
+          for (const k in props) {
+            const v = props[k];
+            if (typeof v === "function" && !v.length) r.dynamicProperty(props, k);
           }
           e = r.createComponent(l, props);
+          // Drain nested h() thunks so downstream sees the real render result.
+          while (typeof e === "function" && e[$ELEMENT]) e = e();
           args = [];
-        } else {
-          r.insert(e, l, multiExpression ? null : undefined);
-        }
+        } else if (l[$ELEMENT]) item(l());else
+        r.insert(e, l, multiExpression ? null : undefined);
       }
     }
 
-    if (args.length === 1 && Array.isArray(args[0])) return args[0];
-    typeof args[0] === "string" && detectMultiExpression(args);
+    if (typeof args[0] === "string") detectMultiExpression(args);
     while (args.length) item(args.shift());
     if (e instanceof Element && classes.length) e.classList.add(...classes);
     return e;
 
     function parseClass(string) {
-      // Our minimal parser doesn’t understand escaping CSS special
-      // characters like `#`. Don’t use them. More reading:
-      // https://mathiasbynens.be/notes/css-escapes .
-
+      // Does not understand escaped CSS specials; see
+      // https://mathiasbynens.be/notes/css-escapes.
       const m = string.split(/([\.#]?[^\s#.]+)/);
       if (/^\.|#/.test(m[1])) e = document.createElement("div");
       for (let i = 0; i < m.length; i++) {

package/lib/hyper-dom-expressions.js

@@ -1,16 +1,38 @@
 'use strict';
 
+// Tags h() thunks so consumers can distinguish them from user-written
+// accessors and invoke them once under the correct owner rather than
+// wrapping them in an effect.
+const $ELEMENT = Symbol("hyper-element");
+
+
+
+
+
+
+
+
+
+
+
 // Inspired by https://github.com/hyperhype/hyperscript
 function createHyperScript(r) {
-  function h() {
-    let args = [].slice.call(arguments),
-      e,
-      classes = [],
-      multiExpression = false;
+  function h(...rawArgs) {
+    if (rawArgs.length === 1 && Array.isArray(rawArgs[0])) return rawArgs[0];
+    const thunk = () => r.untrack(() => materialize(rawArgs));
+    thunk[$ELEMENT] = true;
+    return thunk;
+  }
+
+  function materialize(args) {
+    let e;
+    let classes = [];
+    let multiExpression = false;
+    args = args.slice();
 
     function item(l) {
+      if (l == null) return;
       const type = typeof l;
-      if (l == null) ;else
       if ("string" === type) {
         if (!e) parseClass(l);else
         e.appendChild(document.createTextNode(l));
@@ -49,40 +71,34 @@ function createHyperScript(r) {
         r.assign(e, l, !!args.length);
       } else if ("function" === type) {
         if (!e) {
-          let props,
-            next = args[0];
-          if (
-          next == null ||
-          typeof next === "object" && !Array.isArray(next) && !(next instanceof Element))
-
-          props = args.shift();
-          props || (props = {});
-          if (args.length) {
-            props.children = args.length > 1 ? args : args[0];
-          }
-          const d = Object.getOwnPropertyDescriptors(props);
-          for (const k in d) {
-            if (typeof d[k].value === "function" && !d[k].value.length) r.dynamicProperty(props, k);
+          const first = args[0];
+          const props =
+          first == null ||
+          typeof first === "object" && !Array.isArray(first) && !(first instanceof Element) ?
+          args.shift() || {} :
+          {};
+          if (args.length) props.children = args.length > 1 ? args : args[0];
+          for (const k in props) {
+            const v = props[k];
+            if (typeof v === "function" && !v.length) r.dynamicProperty(props, k);
           }
           e = r.createComponent(l, props);
+          // Drain nested h() thunks so downstream sees the real render result.
+          while (typeof e === "function" && e[$ELEMENT]) e = e();
           args = [];
-        } else {
-          r.insert(e, l, multiExpression ? null : undefined);
-        }
+        } else if (l[$ELEMENT]) item(l());else
+        r.insert(e, l, multiExpression ? null : undefined);
       }
     }
 
-    if (args.length === 1 && Array.isArray(args[0])) return args[0];
-    typeof args[0] === "string" && detectMultiExpression(args);
+    if (typeof args[0] === "string") detectMultiExpression(args);
     while (args.length) item(args.shift());
     if (e instanceof Element && classes.length) e.classList.add(...classes);
     return e;
 
     function parseClass(string) {
-      // Our minimal parser doesn’t understand escaping CSS special
-      // characters like `#`. Don’t use them. More reading:
-      // https://mathiasbynens.be/notes/css-escapes .
-
+      // Does not understand escaped CSS specials; see
+      // https://mathiasbynens.be/notes/css-escapes.
       const m = string.split(/([\.#]?[^\s#.]+)/);
       if (/^\.|#/.test(m[1])) e = document.createElement("div");
       for (let i = 0; i < m.length; i++) {

package/package.json

@@ -1,19 +1,20 @@
 {
   "name": "hyper-dom-expressions",
   "description": "A Fine-Grained Rendering Runtime API using HyperScript",
-  "version": "0.50.0-next.2",
+  "version": "0.50.0-next.3",
   "author": "Ryan Carniato",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/ryansolid/dom-expressions/blob/main/packages/hyper-dom-expressions"
+    "url": "git+https://github.com/ryansolid/dom-expressions.git",
+    "directory": "packages/hyper-dom-expressions"
   },
   "main": "lib/hyper-dom-expressions.js",
   "module": "dist/hyper-dom-expressions.js",
   "types": "types/index.d.ts",
   "sideEffects": false,
   "devDependencies": {
-    "dom-expressions": "0.50.0-next.2"
+    "dom-expressions": "0.50.0-next.3"
   },
   "scripts": {
     "build": "rollup -c --bundleConfigAsCjs && tsc",

package/types/index.d.ts

@@ -5,6 +5,7 @@ interface Runtime {
     assign(node: Element, props: any, skipChildren?: Boolean): void;
     createComponent(Comp: (props: any) => any, props: any): any;
     dynamicProperty(props: any, key: string): any;
+    untrack<T>(fn: () => T): T;
     SVGElements: Set<string>;
     MathMLElements: Set<string>;
     Namespaces: Record<string, string>;
@@ -12,11 +13,16 @@ interface Runtime {
 type ExpandableNode = Node & {
     [key: string]: any;
 };
+declare const $ELEMENT: unique symbol;
+export type HyperElement = {
+    (): ExpandableNode | ExpandableNode[];
+    [$ELEMENT]: true;
+};
 export type HyperScript = {
-    (...args: any[]): ExpandableNode | ExpandableNode[];
+    (...args: any[]): HyperElement | ExpandableNode[];
     Fragment: (props: {
-        children: ExpandableNode | ExpandableNode[];
-    }) => ExpandableNode | ExpandableNode[];
+        children: any;
+    }) => any;
 };
 export declare function createHyperScript(r: Runtime): HyperScript;
 export {};