npm - @kumikijs/runtime - Versions diffs - 0.3.0 → 0.4.0 - Mend

@kumikijs/runtime 0.3.0 → 0.4.0

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.

Files changed (3) hide show

package/dist/index.d.ts CHANGED Viewed

@@ -1,3 +1,36 @@
+//#region src/element.d.ts
+/** Maps one observed attribute to a slot, with an optional parser (default: raw string). */
+type AttributeSlotBinding = {
+  slot: string;
+  parse?: (raw: string | null) => unknown;
+};
+type KumikiElementOptions = {
+  /** Host implementations for custom capabilities (the inbound seam), forwarded to mount. */providers?: Record<string, CapabilityProvider>;
+  /**
+   * Custom-capability names to surface as DOM CustomEvents on the element. For
+   * each, emitting the effect dispatches `CustomEvent(cap, { detail: input })`
+   * (bubbling, composed) and resolves ok — so a host can bind via
+   * `addEventListener(cap, …)` / framework `@cap`. A `providers[cap]` entry
+   * takes precedence over the passthrough for the same capability.
+   */
+  events?: string[]; /** Observed attributes mapped to slots; updates flow in on connect and on change. */
+  attributeSlots?: Record<string, AttributeSlotBinding>;
+  /**
+   * Render into an open shadow root for full style isolation: the app's
+   * theme/motion/state `<style>` nodes are injected into the shadow root (not the
+   * document head), so host-page CSS does not bleed in and Kumiki's CSS does not
+   * leak out. Default: false (light DOM — the runtime's document-level styles
+   * apply, matching a standalone Kumiki page).
+   */
+  shadow?: boolean;
+};
+/**
+ * Register `app` as the custom element `tagName`. Idempotent: if the tag is
+ * already defined this is a no-op (so re-imports / HMR don't throw). Requires a
+ * DOM environment.
+ */
+declare function defineKumikiElement(tagName: string, app: AppShape | (() => AppShape), options?: KumikiElementOptions): void;
+//#endregion
 //#region src/scenario.d.ts
 /** One thing to do to the app. Exactly one field should be set. */
 type Action = {
@@ -87,7 +120,7 @@ declare function smoke(app: AppShape, root: HTMLElement, opts?: SmokeOptions): P
 type RefinementCheck = (v: unknown) => boolean;
 type EventHandler = (el: Record<string, unknown>) => void;
 /**
- * A controlled panic — Kumiki's "stop the program" signal (spec/stdlib.md §2.2:
+ * A controlled panic — Kumiki's "stop the program" signal (docs/spec/stdlib.md §2.2:
  * `panic(message)`; `Option/Result.get` on the empty case; `Result.get-err` on
  * `Ok`). On the live path a panic is caught — the dispatch episode is rolled
  * back (no partial slot writes) and an error boundary / top-level fallback is
@@ -264,8 +297,33 @@ type EffectResult = {
   kind: "err";
   value: unknown;
 };
+/**
+ * A host-supplied implementation for a custom capability (one registered via
+ * `kumiki.caps.json`). This is Kumiki's inbound ecosystem seam: arbitrary JS /
+ * npm libraries live here, behind a typed, mockable capability boundary, so the
+ * Kumiki core stays pure (no language-level FFI). `input` is the effect's
+ * (already `map-request`-mapped) request; the return may be sync or async.
+ */
+type CapabilityProvider = (input: unknown, caps: CapabilityRegistry) => Promise<EffectResult> | EffectResult;
 type CapabilityRegistry = {
-  has(cap: string): boolean;
+  has(cap: string): boolean; /** The host provider registered for `cap` at mount, or undefined. */
+  provider(cap: string): CapabilityProvider | undefined;
+};
+/** Options accepted by `mount`. */
+type MountOptions = {
+  /** Host implementations for custom capabilities, keyed by capability name. */providers?: Record<string, CapabilityProvider>;
+  /**
+   * Where Kumiki injects its `<style>` nodes (motion / theme / state styles).
+   * Defaults to `document` (styles go in `<head>`). Pass a `ShadowRoot` to keep
+   * them encapsulated — used by `defineKumikiElement({ shadow: true })`.
+   */
+  styleRoot?: Document | ShadowRoot;
+  /**
+   * The element whose inline style carries theme background/foreground/font
+   * (the `<body>` equivalent). Defaults to `document.body`; the shadow element
+   * passes its in-shadow container so theming stays encapsulated.
+   */
+  styleHost?: HTMLElement;
 };
 type RouteEntry = {
   pattern: string; /** Returns the TileNode for this route given the current state. */
@@ -301,7 +359,7 @@ type AppShape = {
   live?: Record<string, unknown>;
   _rerender?: () => void;
 };
-declare function mount(app: AppShape, target: HTMLElement): {
+declare function mount(app: AppShape, target: HTMLElement, options?: MountOptions): {
   dispose: () => void;
 };
 type TestResult = {
@@ -386,7 +444,7 @@ declare const _stdlib: {
   now(): number;
   recordCopy(rec: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown>;
   /**
-   * `.get` — the polymorphic unwrap for Option AND Result. Per spec/stdlib.md
+   * `.get` — the polymorphic unwrap for Option AND Result. Per docs/spec/stdlib.md
    * §2.2 it PANICS on the empty case (`None` / `Err`); `Some(v)` / `Ok(v)`
    * unwrap to `v`. A plain (non-variant) value passes through unchanged. (Before
    * v0.3 this returned the value unchanged on the empty case, so `.get` and
@@ -440,4 +498,4 @@ declare const builtinEffects: {
   httpFetch(method: string, input: unknown, baseUrl: string): Promise<EffectResult>;
 };
 //#endregion
-export { type Action, AppShape, CapabilityRegistry, EffectResult, type EffectScript, EffectSpec, EmitSpec, EventHandler, type Expect, KumikiPanic, RedirectEntry, ReducerSpec, RefinementCheck, RouteEntry, type Scenario, type ScenarioReport, type ScenarioStep, SlotMeta, type SmokeIssue, type SmokeOptions, type SmokePhase, type SmokeReport, type StepResult, TestResult, Theme, ThemeValue, TileNode, TileProps, _stdlib, builtinEffects, mount, runScenario, smoke };
+export { type Action, AppShape, type AttributeSlotBinding, CapabilityProvider, CapabilityRegistry, EffectResult, type EffectScript, EffectSpec, EmitSpec, EventHandler, type Expect, type KumikiElementOptions, KumikiPanic, MountOptions, RedirectEntry, ReducerSpec, RefinementCheck, RouteEntry, type Scenario, type ScenarioReport, type ScenarioStep, SlotMeta, type SmokeIssue, type SmokeOptions, type SmokePhase, type SmokeReport, type StepResult, TestResult, Theme, ThemeValue, TileNode, TileProps, _stdlib, builtinEffects, defineKumikiElement, mount, runScenario, smoke };

package/dist/index.js CHANGED Viewed

@@ -1,3 +1,85 @@
+//#region src/element.ts
+/**
+* Register `app` as the custom element `tagName`. Idempotent: if the tag is
+* already defined this is a no-op (so re-imports / HMR don't throw). Requires a
+* DOM environment.
+*/
+function defineKumikiElement(tagName, app, options = {}) {
+	if (typeof customElements === "undefined") throw new Error("defineKumikiElement requires a DOM environment (customElements is undefined).");
+	if (customElements.get(tagName)) return;
+	const makeApp = typeof app === "function" ? app : () => app;
+	const attributeSlots = options.attributeSlots ?? {};
+	const observed = Object.keys(attributeSlots);
+	const buildProviders = (el) => {
+		const merged = {};
+		for (const cap of options.events ?? []) merged[cap] = (input) => {
+			el.dispatchEvent(new CustomEvent(cap, {
+				detail: input,
+				bubbles: true,
+				composed: true
+			}));
+			return {
+				kind: "ok",
+				value: null
+			};
+		};
+		return Object.assign(merged, options.providers ?? {});
+	};
+	class KumikiAppElement extends HTMLElement {
+		static get observedAttributes() {
+			return observed;
+		}
+		handle = null;
+		app = null;
+		connectedCallback() {
+			if (this.handle) return;
+			this.app = makeApp();
+			let target = this;
+			const mountOpts = { providers: buildProviders(this) };
+			if (options.shadow) {
+				const root = this.shadowRoot ?? this.attachShadow({ mode: "open" });
+				root.replaceChildren();
+				const container = document.createElement("div");
+				root.appendChild(container);
+				target = container;
+				mountOpts.styleRoot = root;
+				mountOpts.styleHost = container;
+			}
+			this.handle = mount(this.app, target, mountOpts);
+			for (const attr of observed) if (this.hasAttribute(attr)) this.applyAttr(attr, this.getAttribute(attr));
+		}
+		disconnectedCallback() {
+			this.handle?.dispose();
+			this.handle = null;
+		}
+		attributeChangedCallback(name, _old, value) {
+			if (this.handle) this.applyAttr(name, value);
+		}
+		applyAttr(name, raw) {
+			const binding = attributeSlots[name];
+			if (!binding) return;
+			this.setSlot(binding.slot, binding.parse ? binding.parse(raw) : raw);
+		}
+		/** Write a live slot (respects its refinement) and re-render. */
+		setSlot(name, value) {
+			this.app?._setSlot?.(name, value);
+		}
+		/** Write several live slots at once. */
+		setSlots(values) {
+			for (const [name, value] of Object.entries(values)) this.setSlot(name, value);
+		}
+		/** Read a single live slot value. */
+		getSlot(name) {
+			return this.app?.live?.[name];
+		}
+		/** A snapshot of the current live slot values. */
+		get slots() {
+			return { ...this.app?.live ?? {} };
+		}
+	}
+	customElements.define(tagName, KumikiAppElement);
+}
+//#endregion
 //#region src/scenario.ts
 const settle$1 = (ms) => new Promise((r) => setTimeout(r, ms));
 async function runScenario(app, root, scenario, opts = {}) {
@@ -362,7 +444,7 @@ function errStr(e) {
 //#endregion
 //#region src/index.ts
 /**
-* A controlled panic — Kumiki's "stop the program" signal (spec/stdlib.md §2.2:
+* A controlled panic — Kumiki's "stop the program" signal (docs/spec/stdlib.md §2.2:
 * `panic(message)`; `Option/Result.get` on the empty case; `Result.get-err` on
 * `Ok`). On the live path a panic is caught — the dispatch episode is rolled
 * back (no partial slot writes) and an error boundary / top-level fallback is
@@ -439,15 +521,18 @@ function emptyRoute() {
 		hash: null
 	};
 }
-function mount(app, target) {
+function mount(app, target, options = {}) {
 	if (!app.live) {
 		app.live = {};
 		for (const [k, v] of Object.entries(app.slots)) app.live[k] = v.value;
 	}
 	if (!("route" in app.live)) app.live.route = emptyRoute();
+	currentStyleRoot = options.styleRoot ?? document;
+	currentStyleHost = options.styleHost ?? null;
+	stateStylesEl = null;
 	ensureMotionStyles(app);
 	const slotValues = app.live;
-	const dispatcher = makeEffectDispatcher(app, makeCapabilityRegistry(app.caps), (effect, outcome, value, key) => {
+	const dispatcher = makeEffectDispatcher(app, makeCapabilityRegistry(app.caps, options.providers), (effect, outcome, value, key) => {
 		handleEffectResult(effect, outcome, value, key);
 	});
 	let currentRoot = null;
@@ -504,7 +589,7 @@ function mount(app, target) {
 	}
 	let inPanicHandler = false;
 	/**
-	* Handle a caught live panic per spec/lifecycle.md §7.2: the dispatch episode
+	* Handle a caught live panic per docs/spec/lifecycle.md §7.2: the dispatch episode
 	* is already rolled back (the caller never applied the failed result), so we
 	* surface it (console.error → smoke/scenario see it) and fire the `app.error`
 	* reducer(s) with `$event = PanicInfo`, exactly as §7.2.3 specifies.
@@ -621,9 +706,12 @@ function mount(app, target) {
 		dispatcher.dispose();
 	} };
 }
-function makeCapabilityRegistry(allowed) {
+function makeCapabilityRegistry(allowed, providers) {
 	const ok = new Set(allowed);
-	return { has: (c) => ok.has(c) };
+	return {
+		has: (c) => ok.has(c),
+		provider: (c) => providers?.[c]
+	};
 }
 function makeEffectDispatcher(app, caps, onResult) {
 	const state = {
@@ -700,43 +788,50 @@ function makeEffectDispatcher(app, caps, onResult) {
 	};
 }
 function registerBuiltinEffects(app, navigate, getLive, rerender) {
+	const overridable = (cap, fn) => {
+		return async (input, caps) => {
+			const p = caps.provider(cap);
+			if (p) return p(input, caps);
+			return fn(input);
+		};
+	};
 	app.effects.navigate = {
 		name: "navigate",
 		cap: "nav.push",
-		invoke: async (input) => {
+		invoke: overridable("nav.push", async (input) => {
 			navigate(buildPath(input), false);
 			return {
 				kind: "ok",
 				value: null
 			};
-		}
+		})
 	};
 	app.effects["navigate-replace"] = {
 		name: "navigate-replace",
 		cap: "nav.replace",
-		invoke: async (input) => {
+		invoke: overridable("nav.replace", async (input) => {
 			navigate(buildPath(input), true);
 			return {
 				kind: "ok",
 				value: null
 			};
-		}
+		})
 	};
 	app.effects["navigate-back"] = {
 		name: "navigate-back",
 		cap: "nav.back",
-		invoke: async () => {
+		invoke: overridable("nav.back", async () => {
 			history.back();
 			return {
 				kind: "ok",
 				value: null
 			};
-		}
+		})
 	};
 	app.effects.toast = {
 		name: "toast",
 		cap: "notification.show",
-		invoke: async (input) => {
+		invoke: overridable("notification.show", async (input) => {
 			const t = input;
 			const banner = document.createElement("div");
 			banner.style.cssText = "position:fixed;bottom:24px;right:24px;padding:8px 16px;background:#1a1a1a;color:#fff;border-radius:8px;z-index:9999;";
@@ -747,18 +842,18 @@ function registerBuiltinEffects(app, navigate, getLive, rerender) {
 				kind: "ok",
 				value: null
 			};
-		}
+		})
 	};
 	app.effects.log = {
 		name: "log",
 		cap: "log.write",
-		invoke: async (input) => {
+		invoke: overridable("log.write", async (input) => {
 			console.log("[kumiki]", input);
 			return {
 				kind: "ok",
 				value: null
 			};
-		}
+		})
 	};
 }
 function buildPath(x) {
@@ -1215,10 +1310,8 @@ function applyResponsive(_el, raw, set) {
 		return;
 	}
 }
-let animationStylesInjected = false;
 function ensureAnimationStyles() {
-	if (animationStylesInjected) return;
-	animationStylesInjected = true;
+	if (findStyleNode("kumiki-animations")) return;
 	const css = `
 @keyframes kumiki-fade { from { opacity: 0 } to { opacity: 1 } }
 @keyframes kumiki-slide-up { from { transform: translateY(8px); opacity: 0 } to { transform: translateY(0); opacity: 1 } }
@@ -1234,7 +1327,7 @@ function ensureAnimationStyles() {
 	const style = document.createElement("style");
 	style.id = "kumiki-animations";
 	style.appendChild(document.createTextNode(css));
-	document.head.appendChild(style);
+	appendStyleNode(style);
 }
 function applyTransition(el, props) {
 	if (!props) return;
@@ -1278,15 +1371,32 @@ function motionCss(name, spec) {
 	return [`@keyframes ${cls} { from { ${from} } to { ${to} } }`, `.${cls} { animation-name: ${cls}; animation-duration: ${motionDuration(s.duration)}; animation-timing-function: ${easing}; animation-iteration-count: ${iteration}; animation-direction: ${direction}; animation-fill-mode: both; }`].join("\n");
 }
 /** Inject the app's motion keyframes + a `prefers-reduced-motion` guard at mount. */
+let currentStyleRoot = null;
+let currentStyleHost = null;
+/** Find a Kumiki style node by id within the active style root. */
+function findStyleNode(id) {
+	return (currentStyleRoot ?? document).getElementById(id);
+}
+/** Append a style node to the active style root (document head, or a shadow root). */
+function appendStyleNode(style) {
+	const root = currentStyleRoot ?? document;
+	const head = root.head;
+	if (head) head.appendChild(style);
+	else root.appendChild(style);
+}
+/** The element that carries body-level theme styles (background/fg/font). */
+function styleHostEl() {
+	return currentStyleHost ?? document.body;
+}
 function ensureMotionStyles(app) {
 	const motions = app.motions ?? {};
 	const rules = Object.entries(motions).map(([name, spec]) => motionCss(name, spec));
 	rules.push(`@media (prefers-reduced-motion: reduce) { .kumiki-motion, .kumiki-anim { animation: none !important } }`);
-	let style = document.getElementById("kumiki-motions");
+	let style = findStyleNode("kumiki-motions");
 	if (!style) {
 		style = document.createElement("style");
 		style.id = "kumiki-motions";
-		document.head.appendChild(style);
+		appendStyleNode(style);
 	}
 	style.textContent = rules.join("\n");
 }
@@ -1313,9 +1423,12 @@ function applyStateStyles(el, props) {
 		el.dataset.kumikiState = el.dataset.kumikiState ? `${el.dataset.kumikiState} ${id}` : id;
 		const decls = stateStyleDecls(sub);
 		if (!stateStylesEl) {
-			stateStylesEl = document.createElement("style");
-			stateStylesEl.id = "kumiki-state-styles";
-			document.head.appendChild(stateStylesEl);
+			stateStylesEl = findStyleNode("kumiki-state-styles");
+			if (!stateStylesEl) {
+				stateStylesEl = document.createElement("style");
+				stateStylesEl.id = "kumiki-state-styles";
+				appendStyleNode(stateStylesEl);
+			}
 		}
 		const selector = state === "hover" ? ":hover" : state === "focus" ? ":focus" : state === "active" ? ":active" : state === "disabled" ? ":disabled" : "[data-kumiki-selected]";
 		stateStylesEl.appendChild(document.createTextNode(`[data-kumiki-state~="${id}"]${selector} { ${decls} }\n`));
@@ -1351,12 +1464,13 @@ function applyThemeDefaults(app) {
 	const colors = theme.colors ?? {};
 	const typography = theme.typography ?? {};
 	const sizes = typography.size ?? {};
-	if (typeof colors.bg === "string") document.body.style.background = colors.bg;
-	if (typeof colors.fg === "string") document.body.style.color = colors.fg;
-	if (typeof typography.family === "string") document.body.style.fontFamily = typography.family;
-	if (typeof sizes.md === "string") document.body.style.fontSize = sizes.md;
-	if (typeof typography["line-height"] === "string") document.body.style.lineHeight = String(typography["line-height"]);
-	const prior = document.getElementById("kumiki-theme-base");
+	const host = styleHostEl();
+	if (typeof colors.bg === "string") host.style.background = colors.bg;
+	if (typeof colors.fg === "string") host.style.color = colors.fg;
+	if (typeof typography.family === "string") host.style.fontFamily = typography.family;
+	if (typeof sizes.md === "string") host.style.fontSize = sizes.md;
+	if (typeof typography["line-height"] === "string") host.style.lineHeight = String(typography["line-height"]);
+	const prior = findStyleNode("kumiki-theme-base");
 	if (prior) prior.remove();
 	const css = document.createElement("style");
 	css.id = "kumiki-theme-base";
@@ -1399,7 +1513,7 @@ function applyThemeDefaults(app) {
 }
 [data-kumiki-tile="markdown"] p { margin: 0 0 12px; }
 `));
-	document.head.appendChild(css);
+	appendStyleNode(css);
 }
 function themeShadow(theme, key) {
 	const shadow = theme.shadow;
@@ -1816,7 +1930,7 @@ const _stdlib = {
 		};
 	},
 	/**
-	* `.get` — the polymorphic unwrap for Option AND Result. Per spec/stdlib.md
+	* `.get` — the polymorphic unwrap for Option AND Result. Per docs/spec/stdlib.md
 	* §2.2 it PANICS on the empty case (`None` / `Err`); `Some(v)` / `Ok(v)`
 	* unwrap to `v`. A plain (non-variant) value passes through unchanged. (Before
 	* v0.3 this returned the value unchanged on the empty case, so `.get` and
@@ -2094,4 +2208,4 @@ const builtinEffects = {
 	}
 };
 //#endregion
-export { KumikiPanic, _stdlib, builtinEffects, mount, runScenario, smoke };
+export { KumikiPanic, _stdlib, builtinEffects, defineKumikiElement, mount, runScenario, smoke };

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@kumikijs/runtime",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Kumiki DOM runtime — mounts compiled Kumiki apps, dispatches effects, manages the signal graph.",
   "license": "Apache-2.0",