@spinjs/components 0.1.0-preview.1 → 0.2.0-alpha.1

package/dist/runtime/component/synthesize.js

@@ -0,0 +1,385 @@
+import { interpret } from "../machine/fsm/machine.js";
+import { computed, effect, scope, untrack } from "../core/signal.js";
+import { dataAttr } from "./define.js";
+import { focuser, ids, measurer } from "./ids.js";
+import { resolveTwins } from "../props.js";
+// src/runtime/component/synthesize.ts
+/**
+* The props the host actually wrote, as a predicate.
+* Controlled components live on the authored/written split: a host that
+* writes `value` owns it, and the element marks the write so the bridge can
+* tell a live prop from a coerced default.
+*/
+function authoredProps(props) {
+	return (name) => {
+		const predicate = props()["@@authored"];
+		return typeof predicate === "function" ? predicate(name) : false;
+	};
+}
+/** A callback prop, when the host wrote a function for it. */
+function pickCallback(props, name) {
+	const value = props[name];
+	return typeof value === "function" ? value : void 0;
+}
+/** A text prop, or empty when the host wrote anything else. */
+function textProp(raw) {
+	return typeof raw === "string" ? raw : "";
+}
+function applyContract(svc, fields, props, authored, cursor, send) {
+	if (Object.keys(fields).length === 0) return {
+		moved: false,
+		events: []
+	};
+	const parsed = props();
+	const context = svc.state.context;
+	const events = [];
+	let moved = false;
+	for (const [field, contract] of Object.entries(fields)) {
+		const raw = parsed[field];
+		if (raw === void 0 || raw === null) continue;
+		if (!authored(field)) continue;
+		if (Object.is(cursor.get(field), raw)) continue;
+		cursor.set(field, raw);
+		if (contract.event === void 0) {
+			const value = contract.parse === void 0 ? raw : contract.parse(raw);
+			if (context[field] !== value) {
+				svc.setContext({ [field]: value });
+				moved = true;
+			}
+			continue;
+		}
+		const event = {
+			type: contract.event,
+			[field]: raw
+		};
+		events.push(event);
+		moved = true;
+		send(event);
+	}
+	return {
+		moved,
+		events
+	};
+}
+const sameWatch = (a, b) => a.length === b.length && a.every((value, index) => value === b[index]);
+function defineComponent(def) {
+	const segments = /* @__PURE__ */ new Map();
+	for (const [key, partDef] of Object.entries(def.parts)) segments.set(key, partDef.id ?? key);
+	for (const [key, slotDef] of Object.entries(def.slots ?? {})) segments.set(key, slotDef.id ?? key);
+	const createBridge = (props, root = () => {
+		throw new Error("[spin] bridge needs a root element");
+	}, id) => {
+		if (def.machine === void 0) throw new Error(`[spin] ${def.name} has no machine`);
+		const owner = scope();
+		const lastContract = /* @__PURE__ */ new Map();
+		const lastWatched = /* @__PURE__ */ new Map();
+		const authored = authoredProps(props);
+		const names = ids(def.name, id);
+		const resolveId = (part, slot) => names(segments.get(part) ?? part, slot);
+		const focusPart = focuser(names);
+		const measurePart = measurer(names);
+		let machine;
+		const machineOf = () => {
+			if (machine !== void 0) return machine;
+			const resolved = resolveTwins(props(), authored);
+			const args = def.args === void 0 ? resolved : def.args(resolved);
+			machine = def.machine(args, authored);
+			return machine;
+		};
+		const refresh = (svc) => {
+			if (def.scalars === void 0 && def.scalarsOf === void 0) return false;
+			const parsed = props();
+			const writable = svc.state.context;
+			const patch = {};
+			if (def.scalarsOf !== void 0) {
+				const merge = def.scalarsOf(parsed, authored);
+				for (const [key, value] of Object.entries(merge)) if (writable[key] !== value) patch[key] = value;
+			} else for (const name of def.scalars ?? []) {
+				if (parsed[name] === null || parsed[name] === void 0) continue;
+				if (writable[name] !== parsed[name]) patch[name] = parsed[name];
+			}
+			if (Object.keys(patch).length === 0) return false;
+			svc.setContext(patch);
+			return true;
+		};
+		const readCallbacks = () => {
+			const raw = props();
+			const out = {};
+			for (const event of Object.values(def.events)) {
+				const found = pickCallback(raw, event.prop);
+				if (found !== void 0) out[event.prop] = found;
+			}
+			return out;
+		};
+		const notify = (svc, callbacks, kind, event, beforeSnapshot, parsed, source) => {
+			const context = svc.state.context;
+			const state = svc.state.value;
+			for (const [name, defEvent] of Object.entries(def.events)) {
+				if (defEvent.on === "commit" && kind !== "commit") continue;
+				const watched = defEvent.watch(context, state);
+				const last = lastWatched.get(name);
+				lastWatched.set(name, watched);
+				if (defEvent.select !== void 0) {
+					const before = beforeSnapshot?.context;
+					if (event === void 0 || before === void 0) continue;
+					const beforeState = beforeSnapshot?.state ?? state;
+					const payload = defEvent.select(event, before, context, {
+						was: beforeState,
+						is: state
+					}, source);
+					if (payload !== null) {
+						if (Array.isArray(payload)) for (const report of payload) callbacks[defEvent.prop]?.(report);
+						else callbacks[defEvent.prop]?.(payload);
+					}
+					continue;
+				}
+				if (defEvent.on !== "commit" && last !== void 0 && sameWatch(last, watched)) continue;
+				callbacks[defEvent.prop]?.(defEvent.detail(watched, event, parsed, context));
+			}
+		};
+		let service;
+		const transmit = (event) => {
+			const svc = ensureService();
+			refresh(svc);
+			const before = {
+				context: { ...svc.state.context },
+				state: svc.state.value
+			};
+			svc.send(event);
+			def.settled?.({
+				event,
+				before,
+				after: {
+					context: svc.state.context,
+					state: svc.state.value
+				},
+				props: props(),
+				root,
+				id: resolveId,
+				focus: focusPart,
+				measure: measurePart,
+				send: (report) => send(report)
+			});
+			return {
+				svc,
+				before
+			};
+		};
+		const send = (event) => {
+			const { svc, before } = transmit(event);
+			notify(svc, readCallbacks(), def.commitEvents?.includes(event.type) === true ? "commit" : "move", event, before, props());
+		};
+		const ensureService = () => {
+			if (service !== void 0) return service;
+			const startState = typeof def.start === "function" ? def.start(props(), authored) : def.start;
+			service = owner.run(() => {
+				const svc = interpret(machineOf()).start(startState);
+				refresh(svc);
+				return svc;
+			});
+			for (const event of def.establish?.(props(), authored) ?? []) transmit(event);
+			notify(service, {}, "move", void 0, void 0, props());
+			return service;
+		};
+		const dispatch = (event) => {
+			send(def.dispatch !== void 0 ? def.dispatch(event, props()) : event);
+		};
+		let api;
+		let mounted = false;
+		const ensureConnect = () => {
+			if (api !== void 0) return api;
+			const svc = ensureService();
+			const built = {};
+			for (const [name, command] of Object.entries(def.commands)) {
+				if (command.view !== void 0) {
+					const view = command.view;
+					built[name] = (...args) => view({
+						args,
+						id: resolveId,
+						focus: focusPart,
+						measure: measurePart,
+						root
+					});
+					continue;
+				}
+				const toEvent = command.event;
+				built[name] = (...args) => dispatch(toEvent(args, svc.state.context, resolveId));
+			}
+			for (const [name, reader] of Object.entries(def.readers ?? {})) Object.defineProperty(built, name, {
+				get: () => reader.read(svc.state.context, svc.state.value, props(), root),
+				enumerable: true
+			});
+			if (def.readers?.["state"] === void 0) Object.defineProperty(built, "state", {
+				get: () => svc.state.value,
+				enumerable: true
+			});
+			for (const [name, method] of Object.entries(def.methods ?? {})) built[name] = (...args) => method.call(svc.state.context, svc.state.value, args, props(), resolveId);
+			const liveProps = new Proxy({}, {
+				get: (_target, key) => props()[key],
+				has: (_target, key) => typeof key === "string" && key in props()
+			});
+			const viewFor = (slot) => {
+				const view = {
+					props: liveProps,
+					context: svc.state.context,
+					root,
+					id: resolveId,
+					measure: measurePart,
+					send: dispatch,
+					attr: dataAttr,
+					slot
+				};
+				Object.defineProperty(view, "state", {
+					get: () => svc.state.value,
+					enumerable: true
+				});
+				return view;
+			};
+			const baseView = viewFor(void 0);
+			const zeroArgBags = /* @__PURE__ */ new Map();
+			for (const [part, partDef] of Object.entries(def.parts)) {
+				const method = `get${part[0]?.toUpperCase() ?? ""}${part.slice(1)}Props`;
+				const segment = partDef.id ?? part;
+				built[method] = (...callArgs) => {
+					const raw = callArgs[0];
+					if (raw === void 0) {
+						let cached = zeroArgBags.get(part);
+						if (cached === void 0) {
+							const run = computed(() => ({
+								id: resolveId(part === "root" ? "" : part),
+								"data-scope": def.name,
+								"data-part": segment,
+								...partDef.attrs === void 0 ? {} : partDef.attrs(baseView, void 0)
+							}));
+							cached = () => run();
+							zeroArgBags.set(part, cached);
+						}
+						return cached();
+					}
+					const stamped = {
+						id: resolveId(part === "root" ? "" : part),
+						"data-scope": def.name,
+						"data-part": segment
+					};
+					if (partDef.attrs === void 0) return stamped;
+					return {
+						...stamped,
+						...partDef.attrs(raw === void 0 ? baseView : viewFor(raw), raw)
+					};
+				};
+			}
+			for (const [slotName, slotDef] of Object.entries(def.slots ?? {})) {
+				const cap = `${slotName[0]?.toUpperCase() ?? ""}${slotName.slice(1)}`;
+				const segment = slotDef.id ?? slotName;
+				built[`get${cap}Props`] = (slot, ...callArgs) => {
+					const attrs = slotDef.attrs(viewFor(slot), callArgs[0]);
+					if (slotDef.stamp === false) return attrs;
+					return {
+						"data-scope": def.name,
+						"data-part": segment,
+						...attrs
+					};
+				};
+				const indexesMemo = computed(() => slotDef.indexes(svc.state.context, props()));
+				built[`get${cap}Indexes`] = () => indexesMemo();
+			}
+			api = built;
+			if (!mounted) {
+				mounted = true;
+				def.mounted?.({
+					props: props(),
+					root,
+					id: resolveId,
+					focus: focusPart,
+					measure: measurePart
+				});
+			}
+			return api;
+		};
+		owner.run(() => effect(() => {
+			props();
+			untrack(() => {
+				const svc = ensureService();
+				const beforeContext = {
+					context: { ...svc.state.context },
+					state: svc.state.value
+				};
+				refresh(svc);
+				const syncResult = applyContract(svc, machineOf().fields, props, authored, lastContract, (event) => transmit(event));
+				const parsed = props();
+				const reconciled = [];
+				const derivedMoved = def.reconcile?.({
+					context: svc.state.context,
+					state: svc.state.value,
+					parsed,
+					authored,
+					send: (event) => {
+						const typed = event;
+						reconciled.push(typed);
+						transmit(typed);
+					}
+				}) ?? false;
+				const kindOf = (type) => def.commitEvents?.includes(type) === true ? "commit" : "move";
+				for (const event of syncResult.events) notify(svc, readCallbacks(), kindOf(event.type), event, beforeContext, props());
+				if (reconciled.length > 0) {
+					const last = reconciled[reconciled.length - 1];
+					if (last !== void 0) notify(svc, readCallbacks(), kindOf(last.type), last, beforeContext, props(), "reconcile");
+				}
+				if (syncResult.events.length === 0 && reconciled.length === 0 && derivedMoved) notify(svc, readCallbacks(), "commit", void 0, beforeContext, props());
+			});
+		}));
+		return {
+			api: new Proxy({}, {
+				get: (_target, key) => Reflect.get(ensureConnect(), key),
+				has: (_target, key) => Reflect.has(ensureConnect(), key),
+				ownKeys: () => Reflect.ownKeys(ensureConnect()),
+				getOwnPropertyDescriptor: (_target, key) => {
+					const descriptor = Reflect.getOwnPropertyDescriptor(ensureConnect(), key);
+					if (descriptor === void 0) return void 0;
+					return {
+						...descriptor,
+						configurable: true
+					};
+				}
+			}),
+			dispose: () => {
+				service?.stop();
+				owner.dispose();
+			}
+		};
+	};
+	const events = {};
+	for (const [name, event] of Object.entries(def.events)) events[name] = {
+		on: event.prop,
+		detail: (change) => change
+	};
+	const fieldSet = new Set(def.scalars ?? []);
+	for (const event of Object.values(def.events)) fieldSet.add(event.prop);
+	if (def.machine !== void 0) try {
+		const probed = def.machine(def.args === void 0 ? {} : def.args({}), () => false);
+		for (const key of Object.keys(probed.fields)) fieldSet.add(key);
+		for (const key of Object.keys(probed.initialState.context)) fieldSet.add(key);
+	} catch {}
+	const manifest = {
+		parts: Object.keys(def.parts),
+		slots: Object.keys(def.slots ?? {}),
+		readers: [...Object.keys(def.readers ?? {}), "state"],
+		methods: Object.keys(def.methods ?? {}),
+		commands: Object.keys(def.commands ?? {}),
+		events: Object.keys(def.events ?? {})
+	};
+	const component = (_args) => {
+		throw new Error(`[spin] ${def.name}() is a <script> binding compiled by spin-components; use ${def.name}.createBridge() for imperative bridges`);
+	};
+	Object.defineProperty(component, "name", { value: def.name });
+	return Object.assign(component, {
+		fields: [...fieldSet],
+		createBridge,
+		commands: Object.keys(def.commands),
+		events,
+		manifest
+	});
+}
+export { authoredProps, defineComponent, pickCallback, textProp };
+
+//# sourceMappingURL=synthesize.js.map

package/dist/runtime/core/signal.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The reactive primitives alien-signals does not ship: `batch`, `untrack`, and
+ * a `scope` whose `dispose` reaches every effect created under its `run`.
+ *
+ * The cascade is the point: a binding that outlives its element writes into
+ * detached DOM and throws nothing, so `dispose` has to be exhaustive.
+ */
+import { computed, effect, signal, trigger } from "alien-signals";
+/** A readable-and-writable value. */
+export type Signal<T> = {
+  (): T;
+  (value: T): void;
+};
+/**
+ * Run `fn` with writes deferred, then flush once.
+ *
+ * Every write inside `fn` schedules the same flush, so an effect that reads
+ * three of them still runs exactly once.
+ */
+export declare function batch<T>(fn: () => T): T;
+/**
+ * Read without subscribing.
+ *
+ * Reads made inside `fn` are invisible to the surrounding effect, which is how
+ * a binding renders a value it must not be woken by.
+ */
+export declare function untrack<T>(fn: () => T): T;
+/** A unit of ownership: work created under `run` dies with `dispose`. */
+export interface OwnerScope {
+  /** Runs `fn` with this scope active, so what it creates is owned here. */
+  run<T>(fn: () => T): T;
+  /** Registers teardown to run at `dispose`. */
+  own(dispose: () => void): void;
+  /** Tears down everything created under `run`, plus everything `own`ed. */
+  dispose(): void;
+  /** The scope this one was created within, if any. */
+  readonly parent: OwnerScope | undefined;
+}
+/**
+ * The object form of alien-signals' `effectScope`.
+ *
+ * `run` may be called any number of times; each call opens its own group and
+ * the group's effects die with the scope. Teardown runs newest-first, so an
+ * inner resource is released before the outer one it was built on, and effects
+ * go before `own`ed teardown — a binding's last run should not be able to
+ * write into a node the teardown has already removed.
+ */
+export declare function scope(parent?: OwnerScope | undefined): OwnerScope;
+/**
+ * Registers teardown with the scope currently running.
+ *
+ * The standalone spelling of `scope.own`, for code inside `run` that does not
+ * hold the scope. Outside a scope there is nothing to defer the teardown to,
+ * and silently dropping it would leak, so this throws instead.
+ */
+export declare function own(dispose: () => void): void;
+export { computed, effect, signal, trigger };

package/dist/runtime/core/signal.js

@@ -0,0 +1,100 @@
+import { computed, effect, effectScope, endBatch, setActiveSub, signal, startBatch, trigger } from "alien-signals";
+// src/runtime/core/signal.ts
+/**
+* The reactive primitives alien-signals does not ship: `batch`, `untrack`, and
+* a `scope` whose `dispose` reaches every effect created under its `run`.
+*
+* The cascade is the point: a binding that outlives its element writes into
+* detached DOM and throws nothing, so `dispose` has to be exhaustive.
+*/
+/**
+* Run `fn` with writes deferred, then flush once.
+*
+* Every write inside `fn` schedules the same flush, so an effect that reads
+* three of them still runs exactly once.
+*/
+function batch(fn) {
+	startBatch();
+	try {
+		return fn();
+	} finally {
+		endBatch();
+	}
+}
+/**
+* Read without subscribing.
+*
+* Reads made inside `fn` are invisible to the surrounding effect, which is how
+* a binding renders a value it must not be woken by.
+*/
+function untrack(fn) {
+	const prevSub = setActiveSub(void 0);
+	try {
+		return fn();
+	} finally {
+		setActiveSub(prevSub);
+	}
+}
+/** The scope whose `run` is currently executing, if any. */
+let activeScope;
+/**
+* The object form of alien-signals' `effectScope`.
+*
+* `run` may be called any number of times; each call opens its own group and
+* the group's effects die with the scope. Teardown runs newest-first, so an
+* inner resource is released before the outer one it was built on, and effects
+* go before `own`ed teardown — a binding's last run should not be able to
+* write into a node the teardown has already removed.
+*/
+function scope(parent = activeScope) {
+	const groups = [];
+	const teardowns = [];
+	let disposed = false;
+	const self = {
+		parent,
+		run(fn) {
+			if (disposed) throw new Error("scope.run: the scope is disposed");
+			const prevScope = activeScope;
+			activeScope = self;
+			try {
+				let value;
+				groups.push(effectScope(() => {
+					value = fn();
+				}));
+				return value;
+			} finally {
+				activeScope = prevScope;
+			}
+		},
+		own(dispose) {
+			if (disposed) {
+				dispose();
+				return;
+			}
+			teardowns.push(dispose);
+		},
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			for (let i = groups.length - 1; i >= 0; i--) groups[i]?.();
+			groups.length = 0;
+			for (let i = teardowns.length - 1; i >= 0; i--) teardowns[i]?.();
+			teardowns.length = 0;
+		}
+	};
+	return self;
+}
+/**
+* Registers teardown with the scope currently running.
+*
+* The standalone spelling of `scope.own`, for code inside `run` that does not
+* hold the scope. Outside a scope there is nothing to defer the teardown to,
+* and silently dropping it would leak, so this throws instead.
+*/
+function own(dispose) {
+	if (activeScope === void 0) throw new Error("own: called outside of scope.run");
+	activeScope.own(dispose);
+}
+export { batch, computed, effect, own, scope, signal, trigger, untrack };
+
+//# sourceMappingURL=signal.js.map

package/dist/runtime/core/style.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The one style serializer the runtime ships.
+ *
+ * `{ backgroundColor: "red" }` → `"background-color:red;"`. Custom properties
+ * pass through untouched: their case IS their name, and a `--camelCased`
+ * property is a different property. Everything else is camelCase, because the
+ * values arrive from JS-side bindings.
+ *
+ * The string is written to `style` — never to a `style` attribute: the IDL
+ * path composes, while an attribute write replaces every declaration the
+ * theme, a utility, or an animation put there.
+ */
+/** `{ backgroundColor: "red" }` → `"background-color:red;"`. */
+export declare function toStyleString(style: Record<string, unknown>): string;

package/dist/runtime/core/style.js

@@ -0,0 +1,31 @@
+// src/runtime/core/style.ts
+/**
+* The one style serializer the runtime ships.
+*
+* `{ backgroundColor: "red" }` → `"background-color:red;"`. Custom properties
+* pass through untouched: their case IS their name, and a `--camelCased`
+* property is a different property. Everything else is camelCase, because the
+* values arrive from JS-side bindings.
+*
+* The string is written to `style` — never to a `style` attribute: the IDL
+* path composes, while an attribute write replaces every declaration the
+* theme, a utility, or an animation put there.
+*/
+/** `{ backgroundColor: "red" }` → `"background-color:red;"`. */
+function toStyleString(style) {
+	let out = "";
+	for (const key in style) {
+		const value = style[key];
+		if (value === null || value === void 0) continue;
+		if (!key.startsWith("--")) {
+			const dashed = key.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+			out += `${dashed}:${value};`;
+			continue;
+		}
+		out += `${key}:${value};`;
+	}
+	return out;
+}
+export { toStyleString };
+
+//# sourceMappingURL=style.js.map

package/dist/runtime/directives/bind.d.ts

@@ -0,0 +1,38 @@
+export type Signal<T> = {
+  (): T;
+  (value: T): void;
+};
+export declare function bindText(node: Text, get: () => unknown): void;
+/** The class a markup's class attribute holds.
+ *
+ * The attribute takes the shape the markup reads best: a list of parts,
+ * where a part is a string of classes or an object of conditions.
+ *
+ *     class={["mb-4 text-sm text-muted", { "bg-primary": focused }]}
+ *
+ * A string is the classes themselves — plain text, so the build's
+ * extractor sees them as they are. An object's keys are the classes and
+ * its values the conditions; a key whose value is truthy is in.
+ *
+ * The values are live reads, so the class follows the state.
+ */
+export declare function classOf(classes: unknown): string;
+export declare function bindAttr(el: Element, name: string, get: () => unknown): void;
+export declare function bindProp(el: Element, name: string, get: () => unknown): void;
+export declare function bindDynamic(el: Element, name: string, get: () => unknown): void;
+export interface Writable<T> {
+  (): T;
+  set(next: T): void;
+}
+export interface Binding {
+  pull(): void;
+  stop(): void;
+}
+export declare function bindValue(el: Element, source: Writable<string>): Binding;
+export declare function bindChecked(el: HTMLInputElement, source: Writable<boolean>): Binding;
+export declare function projectSlots(el: HTMLElement): Map<string, Node[]>;
+/**
+ * Places assigned nodes (moved, never cloned — state and listeners travel)
+ * before `anchor`, or the fallback nodes when nothing was assigned.
+ */
+export declare function placeSlot(host: Node, anchor: Comment, assigned: Node[] | undefined, fallback: Node[]): void;