@dom-expressions/tagged-jsx 0.50.0-next.15

package/CHANGELOG.md

@@ -0,0 +1,96 @@
+# tagged-jsx-dom-expressions
+
+## 0.50.0-next.15
+
+### Patch Changes
+
+- 402ead1: Rename the prerelease `sld-dom-expressions` package to `tagged-jsx-dom-expressions`, with matching public API names: `createTaggedJSXRuntime`, `TaggedJSXInstance`, and the `.jsx` self-reference tag.
+- df03fb8: Move all packages under the `@dom-expressions` npm scope with new names:
+  - `dom-expressions` → `@dom-expressions/runtime`
+  - `babel-plugin-jsx-dom-expressions` → `@dom-expressions/babel-plugin-jsx`
+  - `jsx-dom-expressions-compiler` → `@dom-expressions/jsx-compiler`
+  - `hyper-dom-expressions` → `@dom-expressions/hyperscript`
+  - `tagged-jsx-dom-expressions` → `@dom-expressions/tagged-jsx`
+
+  The old unscoped names stop receiving `next` prereleases and remain in use
+  only by the Solid 1.x maintenance line published from `main`.
+
+  `lit-dom-expressions` is dropped from the prerelease line; it has been
+  superseded by `@dom-expressions/tagged-jsx`.
+
+  `@dom-expressions/jsx-compiler` now distributes prebuilt native binaries
+  through per-platform packages (`@dom-expressions/jsx-compiler-darwin-x64`,
+  `-darwin-arm64`, `-linux-x64-gnu`, `-linux-arm64-gnu`, `-win32-x64-msvc`)
+  resolved automatically via `optionalDependencies`, instead of shipping a
+  binary inside the main package.
+
+## 0.50.0-next.14
+
+## 0.50.0-next.13
+
+## 0.50.0-next.12
+
+### Patch Changes
+
+- 54880f4: Fix SLD templates so top-level element siblings each get their own template, allowing adjacent top-level expressions to update and clean up correctly.
+
+## 0.50.0-next.11
+
+### Patch Changes
+
+- d5cd499: Remove `on:` namespace event support from compiler, runtime, JSX types, and renderer packages.
+
+## 0.50.0-next.10
+
+## 0.50.0-next.9
+
+### Patch Changes
+
+- 9994328: Support line and block comments inside SLD tags.
+
+## 0.50.0-next.8
+
+## 0.50.0-next.7
+
+## 0.50.0-next.6
+
+### Patch Changes
+
+- a843315: Fix SLD `<template>` rendering so dynamic expressions are inserted into inert template content.
+- a8a8f81: Inline `csstype` in the `sld-dom-expressions` build output so the published type declarations do not require consumers to resolve that transitive JSX type dependency separately.
+
+## 0.50.0-next.5
+
+## 0.50.0-next.4
+
+## 0.50.0-next.3
+
+### Patch Changes
+
+- 8f56bc8: Add `sld-dom-expressions`: an AST-based tagged-template runtime that avoids runtime code generation (CSP-safe) and supports a named component registry for tooling-friendly templates.
+- 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.
+- 5463c56: `createSLDRuntime(runtime)` now returns a ready-to-use tag directly (with an empty component registry) instead of a factory that needs a second call. Components are registered via `.define({ ... })` on the returned tag, which already existed for derivation. This removes the awkward `createSLDRuntime(r)({})` for the no-components case and makes the runtime-binding step single-purpose.
+
+  Migration:
+
+  ```ts
+  // before
+  const sld = createSLDRuntime(runtime)({ For, Show });
+
+  // after
+  const sld = createSLDRuntime(runtime).define({ For, Show });
+
+  // no components case
+  const sld = createSLDRuntime(runtime);
+  ```
+
+- f32587f: Apply the single-node flatten uniformly so an `sld` template that resolves to one node/value returns it as a scalar (matching the existing behaviour of templateless paths). This lets downstream `insert` take the fast scalar path instead of reconciling a one-element array. The tag's return type is updated to `JSX.Element` to reflect the actual scalar-or-array shape; consumers that iterate or spread should normalize via `Array.isArray(result) ? result : [result]`.
+- bacbd0c: Expose `Runtime`, `ComponentRegistry`, and `FunctionComponent` from the
+  package entry so consumers wiring a custom reactive core can type their
+  runtime object. Fix `Runtime.spread`'s `skipChildren` parameter type from
+  `Boolean` to `boolean`. Mark the package as `sideEffects: false` so
+  bundlers can tree-shake unused exports.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018-2019 Ryan Carniato
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,259 @@
+# @dom-expressions/tagged-jsx
+
+A tagged-template runtime for fine-grained signals libraries such as Solid.js.
+Any signals library can be hooked into `html` by implementing a `Runtime` adapter.
+
+`html` parses templates at runtime and installs reactive bindings against the
+resulting DOM. Component references are real JavaScript values — either a name
+registered via `.define()` or an expression hole — never a string parsed at
+render time.
+
+## Install
+
+```sh
+npm install @dom-expressions/tagged-jsx
+```
+
+## Tooling
+
+For editor support, the
+[Tagged JSX Tools VS Code extension](https://marketplace.visualstudio.com/items?itemName=DanielRKling.tagged-jsx-vscode)
+provides syntax highlighting, formatting, conversion commands, and TypeScript
+diagnostics for JSX inside tagged template literals.
+
+## Quick start
+
+`createTaggedJSXRuntime(runtime)` returns a ready-to-use tag bound to the runtime of a signals library.
+Components are registered via `.define({ ... })`, which returns a new tag with the
+combined registry.
+
+```ts
+import { createTaggedJSXRuntime } from "@dom-expressions/tagged-jsx";
+
+// In this example, we will specifically connect Solid.js to tagged JSX, but any
+// signals-style library could export a compatible interface.
+import * as web from "@solidjs/web";
+
+import { For, Show, createSignal } from "solid-js";
+import { render } from "@solidjs/web";
+
+// This creates a tagged JSX template tag that is reactive specifically to
+// Solid.js signals by passing in the Solid.js web runtime, and registers
+// two components for use via PascalCase tag names inside of the template
+// strings.
+const html = createTaggedJSXRuntime(web).define({ For, Show });
+
+function Counter() {
+  const [count, setCount] = createSignal(0);
+
+  // Finally, write reactive templates!
+  return html`
+    <button onClick=${() => setCount(c => c + 1)}>
+      Count: ${count}
+    </button>
+
+    <For each=${...}>
+      ...
+    </For>
+
+    <Show when=${...}>
+      ...
+    </Show>
+  `;
+}
+
+render(Counter, document.body);
+```
+
+The returned tag can be assigned to any local variable, but `html` matches the
+default editor tooling configuration. If you wrap or rename the tag, the `.jsx`
+self-reference below gives tooling a stable tag name to recognize.
+
+## API
+
+### `createTaggedJSXRuntime(runtime): TaggedJSXInstance<{}>`
+
+Binds the runtime once and returns a tag with an empty component registry (`{}`).
+The `runtime` object provides the reactive primitives and HTML facts the tag
+needs at render time. When using `@solidjs/web`, the module's exports (the `web` in
+`import * as web from "@solidjs/web"`) satisfy the shape.
+
+The exported `Runtime` type can be implemented by any signals-style library for use
+with `html` templates:
+
+```ts
+import { type Runtime } from "@dom-expressions/tagged-jsx";
+
+import { ... } from '@preact/signals'; // For example, make tagged JSX work with Preact Signals
+
+const preactTaggedJSXRuntime: Runtime = {
+  // ...implement the required shape for tagged JSX compatibility, using
+  // Preact Signals primitives...
+}
+
+const html = createTaggedJSXRuntime(preactTaggedJSXRuntime);
+```
+
+The `Runtime` shape is:
+
+```ts
+interface Runtime {
+  insert(parent: Node, accessor: any, marker?: Node | null, init?: any): any;
+  spread(node: Element, accessor: any, skipChildren?: boolean): void;
+  createComponent(Comp: (props: any) => any, props: any): any;
+  mergeProps(...sources: unknown[]): any;
+  SVGElements: Set<string>;
+  MathMLElements: Set<string>;
+  VoidElements: Set<string>;
+  RawTextElements: Set<string>;
+}
+```
+
+### `tag.define(components): TaggedJSXInstance<PreviousComponents & NewComponents>`
+
+Returns a new tag with the supplied components merged into the registry.
+The original tag is unchanged.
+
+```ts
+const base = createTaggedJSXRuntime(web);
+const withFor = base.define({ For });
+const withForAndShow = withFor.define({ Show });
+```
+
+### `tag.jsx`
+
+A self-reference. This makes it possible to write templates through a `.jsx`
+tag regardless of which local variable name was used to reference the instance.
+That gives codemods, syntax highlighters, and formatters a stable tag name to
+recognize.
+
+```js
+const withForAndShow = withFor.define({ Show }); // from above
+
+console.log(withForAndShow === withForAndShow.jsx) // true
+
+// Both of these are functionally equivalent, but the second one
+// helps tooling that specifically looks for "jsx" in code.
+
+withForAndShow`
+    <For each=${...}>
+      ...
+    </For>
+
+    <Show when=${...}>
+      ...
+    </Show>
+`
+
+withForAndShow.jsx`
+    <For each=${...}>
+      ...
+    </For>
+
+    <Show when=${...}>
+      ...
+    </Show>
+`
+```
+
+### `tag.components`
+
+The current registry, as a plain object.
+
+## Template syntax
+
+### Elements and components
+
+```ts
+html`<div />`; // self-closing
+html`<div></div>`; // matched
+html`<MyComponent />`; // registered component (capitalized)
+html`<${MyComponent} />`; // inline component via expression hole
+html`<${MyComponent}>...<//>`; // shorthand close for inline component (see Limitations)
+```
+
+- Tag names start with `a-zA-Z$_` and may contain `a-zA-Z0-9$.:-_`.
+- Capitalized tag names are looked up in the registry. An unregistered
+  capitalized name throws.
+- Lowercase tag names are HTML/SVG/MathML elements; namespace is inferred
+  from the element name and walked into nested children.
+
+### Text and whitespace
+
+- Text content is decoded as HTML (`&copy;` → `©`, `&gt;` → `>`).
+- Pure-whitespace runs between elements are dropped from the AST.
+- Leading and trailing whitespace inside an element is dropped when the
+  element contains at least one expression hole.
+- When in doubt, use an expression: `` html`<p>${" exact  spaces   "}</p>` ``.
+
+### Attributes and properties
+
+```ts
+html`<input value="hi" />`           // static string attribute
+html`<input disabled />`             // static boolean attribute
+html`<input value=${val} />`         // dynamic attribute or property (auto)
+html`<input prop:value=${val} />`    // forced DOM property
+html`<input attr:foo=${val} />`      // forced HTML attribute
+html`<input ...${props} />`          // spread
+html`<input ref=${el => ...} />`     // ref (not reactive)
+html`<input onClick=${handler} />`   // delegated event when supported by the runtime
+html`<input onclick=${handler} />`   // bound listener (legacy lowercase)
+```
+
+`children` as an attribute is honored only when the element has no template
+children, matching JSX behavior.
+
+### Reactivity
+
+A function passed to a non-event, non-`ref` attribute is auto-wrapped as a
+getter if it takes zero arguments. Both forms below are reactive and
+equivalent:
+
+```ts
+const [count] = createSignal(0);
+
+html`<button count=${() => count()} />`;
+html`<button count=${count} />`;
+```
+
+If the value you want to pass is itself a zero-arg function and you don't
+want it auto-wrapped, wrap it again to break the heuristic:
+
+```ts
+html`<Route component=${() => Counter} />`;
+```
+
+`on*` and `ref` props are never auto-wrapped — they're passed as-is.
+
+## JSX vs `html`
+
+| Feature            | Solid JSX                               | `html` tagged template                                    |
+| :----------------- | :-------------------------------------- | :------------------------------------------------------- |
+| **Fragments**      | Required: `<>...</>` for multiple roots | None needed: returns a node, or array of nodes           |
+| **Spread**         | `<div {...props} />`                    | `<div ...${props} />`                                    |
+| **Comments**       | `{/* ... */}`                           | `<!-- ... -->` (stripped)                                |
+| **Raw-text tags**  | `innerHTML` workaround                  | `<style>` / `<script>` bodies are raw text               |
+| **Whitespace**     | JSX-style stripping                     | Trims between tags; preserves inside text                |
+| **Reactivity**     | Signals auto-wrapped                    | Zero-arg functions auto-wrapped (use `() =>` to opt out) |
+| **Component refs** | Identifier in scope                     | Registered name (`<Foo />`) or expression (`<${Foo} />`) |
+
+Because `html` returns a `JSX.Element` — which can be a single node when the template
+resolves to one root, or an array when it resolves to many — consumers that
+need to iterate or spread should normalize the result:
+
+```ts
+const result = html`<div />`; // div
+const nodes = [result].flat(); // [div]
+```
+```ts
+const result = html`
+  <div />
+  <span />
+`; // [div, span]
+
+const nodes = [result].flat(); // [div, span]
+```
+
+## License
+
+You've got a license to build awesome apps: MIT