@mantaq/lit 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anders Can
+
+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

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+> Experimental: API may change.
 
-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.
+# @mantaq/lit
+
+Bind a mantaq actor into a [lit-html](https://lit.dev/docs/libraries/standalone-templates/) template with one function, `watch(actor, select)`. It renders `select(snapshot)` now and again on every change, synchronously, so the DOM is current when `send` returns.
+
+```sh
+pnpm add @mantaq/lit lit-html
+```
+
+## Quick start
+
+```ts
+import { html, render } from "lit-html";
+import { repeat } from "lit-html/directives/repeat.js";
+import { watch } from "@mantaq/lit";
+
+const row = (t: Todo) => html`<li data-id=${t.id}><span>${t.text}</span></li>`;
+
+render(
+  html`<ul>
+    ${watch(todos, (s) => repeat(s.context.items, (t) => t.id, row))}
+  </ul>`,
+  document.body,
+);
+```
+
+`watch` subscribes while the part is connected and unsubscribes when it is cleared. Passing a new inline `select` on each render does not resubscribe, and the latest `select` is the one used. Passing a different actor moves the subscription.
+
+## Gotchas
+
+These are pinned by `src/lit-assumptions.test.ts`.
+
+- **Key lists by `id`.** `repeat(items, (t) => t.id, row)` keeps and moves the existing `<li>` elements and writes only the text that changed. Keying by object identity recreates every row whenever items are cloned, and a plain `items.map(row)` reuses rows by index, so removing the first item rewrites the text of every row after it.
+- **Components that take an item as a property do not see in-place edits.** A custom element with `.item=${t}` compares by `Object.is`, so a handler that mutates `t` leaves it stale. Bind the fields (`.text=${t.text}`), or replace the changed item with a new object.
+- **Selectors run on every change.** `watch` does not compare values, because an in-place edit returns the same array again and must still update the list. lit already skips equal primitives, so keep selectors cheap.
+- **`prev.context === snap.context` after an in-place edit.** Compare fields, not contexts, when you detect changes yourself.
+
+## Not included
+
+Scheduling options, value dedupe and a view-transition option (mantaq #296) are not part of this package yet.

package/dist/index.d.mts

@@ -0,0 +1,11 @@
+import { DirectiveResult } from "lit-html/directive.js";
+import { Snapshot } from "@mantaq/core";
+type Watchable<C> = {
+  snapshot(): Snapshot<C>;
+  on(event: "change", options: {
+    fn: (snapshot: Snapshot<C>) => void;
+  }): () => void;
+};
+/** Binds a lit part to an actor: renders `select(snapshot)` now and on every change. */
+export declare function watch<C, R>(actor: Watchable<C>, select: (snapshot: Snapshot<C>) => R): DirectiveResult;
+export {};

package/dist/index.mjs

@@ -0,0 +1,48 @@
+import { AsyncDirective } from "lit-html/async-directive.js";
+import { directive } from "lit-html/directive.js";
+// src/watch.ts
+var WatchDirective = class extends AsyncDirective {
+	#actor;
+	#source;
+	#unsubscribe;
+	render(source) {
+		this.#source = source;
+		if (source.actor !== this.#actor) {
+			this.#stop();
+			this.#actor = source.actor;
+			if (this.isConnected) this.#start();
+		}
+		return source.read();
+	}
+	disconnected() {
+		this.#stop();
+	}
+	reconnected() {
+		this.#start();
+		if (this.#source) this.setValue(this.#source.read());
+	}
+	#start() {
+		const source = this.#source;
+		if (!source || this.#unsubscribe) return;
+		let seeding = true;
+		this.#unsubscribe = source.listen(() => {
+			if (seeding || !this.#source) return;
+			this.setValue(this.#source.read());
+		});
+		seeding = false;
+	}
+	#stop() {
+		this.#unsubscribe?.();
+		this.#unsubscribe = void 0;
+	}
+};
+const watchDirective = directive(WatchDirective);
+/** Binds a lit part to an actor: renders `select(snapshot)` now and on every change. */
+function watch(actor, select) {
+	return watchDirective({
+		actor,
+		read: () => select(actor.snapshot()),
+		listen: (fn) => actor.on("change", { fn })
+	});
+}
+export { watch };

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@mantaq/lit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Bind mantaq actors into lit-html templates with one directive.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AndersCan/mantaq",
+    "directory": "packages/lit"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "happy-dom": "^21.0.4",
+    "lit": "^3.3.0",
+    "lit-html": "^3.3.0",
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.4.0",
+    "vite-plus": "1.4.0",
+    "@mantaq/core": "^0.6.0"
+  },
+  "peerDependencies": {
+    "lit-html": "^3.3.0",
+    "@mantaq/core": "^0.6.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check"
+  }
 }