@pie-lib/delivery-events-svelte 0.1.1-next.1 → 0.2.0-next.2

package/dist/delivery-element.d.ts

@@ -0,0 +1,47 @@
+export interface DeliveryElementOptions<Model, Session> {
+    /**
+     * Whether `session` is a complete response to `model`. It is the `complete`
+     * flag of every `model-set` and `session-changed` the element dispatches, which
+     * is what a player gates the item's answered state on.
+     */
+    isComplete(model: Model | undefined, session: Session | undefined): boolean;
+}
+/**
+ * The delivery custom element a player mounts: it owns the session the player
+ * hands it and announces every change to it.
+ */
+export interface DeliveryElement<Model = unknown, Session = unknown> extends HTMLElement {
+    model: Model | undefined;
+    /** The session object the player set, with every update written into it. */
+    session: Session | undefined;
+    /**
+     * The component's `onSessionChange` prop, which it calls with each update:
+     * writes the update and dispatches `session-changed`.
+     */
+    onSessionChange: (session: Session) => void;
+    /** `isComplete` for the current model and session. A subclass adds its own conditions here. */
+    isComplete(): boolean;
+    /**
+     * Writes `next` into the player's session and hands the component `next`,
+     * a fresh reference its `$derived` reads re-run on. Dispatches nothing.
+     */
+    writeSession(next: Session): void;
+    dispatchSessionChanged(): void;
+}
+export type DeliveryElementConstructor<Model = unknown, Session = unknown> = new () => DeliveryElement<Model, Session>;
+/**
+ * The delivery custom element for `Component`, a Svelte component compiled
+ * with `customElement` that declares `model`, `session` and an
+ * `onSessionChange` callback prop.
+ *
+ * The session contract lives here, once, for every Svelte element: the update
+ * is written into the object the player handed the element (`writeSessionInPlace`),
+ * and `session-changed` and `model-set` are dispatched under the tag the player
+ * registered the element with, carrying `complete` from `options.isComplete`.
+ *
+ * `onSessionChange` is an ordinary prop of the component, which the element
+ * assigns in its constructor through the accessor Svelte generates for it; a
+ * component mounted with `mount()` takes it like any other prop. A subclass
+ * assigns its own callback props the same way.
+ */
+export declare function defineDeliveryElement<Model = unknown, Session = unknown>(Component: object, options: DeliveryElementOptions<Model, Session>): DeliveryElementConstructor<Model, Session>;

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 /**
  * @pie-lib/delivery-events-svelte
  *
- * Shared host/session bridge utilities for Svelte delivery custom elements.
+ * The delivery custom element shell and session write-through for Svelte elements.
  */
-export * from './session-bridge.js';
+export * from './delivery-element.js';
+export * from './write-session-in-place.js';
 export { ModelSetEvent, SessionChangedEvent } from '@pie-element/shared-player-events';

package/dist/index.js

@@ -1,3 +1,4 @@
-import { forwardSessionChange as e, resolveDeliveryHost as t, writeSessionInPlace as n } from "./index2.js";
-import { ModelSetEvent as r, SessionChangedEvent as i } from "@pie-element/shared-player-events";
-export { r as ModelSetEvent, i as SessionChangedEvent, e as forwardSessionChange, t as resolveDeliveryHost, n as writeSessionInPlace };
+import { writeSessionInPlace as e } from "./index2.js";
+import { defineDeliveryElement as t } from "./index3.js";
+import { ModelSetEvent as n, SessionChangedEvent as r } from "@pie-element/shared-player-events";
+export { n as ModelSetEvent, r as SessionChangedEvent, t as defineDeliveryElement, e as writeSessionInPlace };

package/dist/index2.js

@@ -1,50 +1,17 @@
-import { SessionChangedEvent as e } from "@pie-element/shared-player-events";
-//#region src/session-bridge.ts
-var t = (e) => {
-	let t = e;
-	return t ? typeof t.onSessionChange == "function" || typeof t.onAudioStarted == "function" || typeof t.onAudioEnded == "function" : !1;
-};
-function n(e) {
-	if (e.parentElement) return e.parentElement;
-	let t = e.getRootNode();
-	return t instanceof ShadowRoot ? t.host : null;
-}
-function r(e, r = {}) {
-	let i = r.hostPredicate ?? t, a = e;
-	for (; a;) {
-		if (i(a)) return a;
-		a = n(a);
-	}
-	return null;
-}
-function i(e) {
+//#region src/write-session-in-place.ts
+function e(e) {
 	return !!e && typeof e == "object" && !Array.isArray(e);
 }
-function a(e, t) {
-	if (e === t) return e;
-	if (!i(e) || !i(t) || Object.isFrozen(e) || !Object.isExtensible(e)) return t;
+function t(t, n) {
+	if (t === n) return t;
+	if (!e(t) || !e(n) || Object.isFrozen(t) || !Object.isExtensible(t)) return n;
 	try {
-		for (let n of Object.keys(e)) n in t || delete e[n];
-		Object.assign(e, t);
+		for (let e of Object.keys(t)) e in n || delete t[e];
+		Object.assign(t, n);
 	} catch {
-		return t;
+		return n;
 	}
-	return e;
-}
-var o = {}, s = /* @__PURE__ */ new WeakSet();
-function c(e) {
-	let t = e ?? o;
-	if (s.has(t)) return;
-	s.add(t);
-	let n = e ? `above <${e.tagName.toLowerCase()}>` : "for an update with no source element";
-	console.warn(`[session-bridge] no delivery host ${n}; the session change was not forwarded to the player`);
-}
-function l({ sourceEl: t, complete: n, session: i }) {
-	let o = r(t);
-	if (!o) return c(t), null;
-	if (typeof o.onSessionChange == "function") return o.onSessionChange(i), o;
-	let s = a(o.session, i);
-	return s !== o.session && (o.session = s), o.dispatchEvent(new e(o.tagName.toLowerCase(), n)), o;
+	return t;
 }
 //#endregion
-export { l as forwardSessionChange, r as resolveDeliveryHost, a as writeSessionInPlace };
+export { t as writeSessionInPlace };

package/dist/index3.js

@@ -0,0 +1,42 @@
+import { writeSessionInPlace as e } from "./index2.js";
+import { ModelSetEvent as t, SessionChangedEvent as n } from "@pie-element/shared-player-events";
+//#region src/delivery-element.ts
+function r(r, i) {
+	let a = r.element;
+	if (!a) throw TypeError("defineDeliveryElement: the component was not compiled with `customElement`");
+	class o extends a {
+		#e;
+		#t;
+		constructor() {
+			super(), this.onSessionChange = (e) => {
+				this.writeSession(e), this.dispatchSessionChanged();
+			};
+		}
+		set model(e) {
+			this.#e = e, super.model = e, queueMicrotask(() => {
+				this.dispatchEvent(new t(this.tagName.toLowerCase(), this.isComplete(), this.#e !== void 0));
+			});
+		}
+		get model() {
+			return this.#e;
+		}
+		set session(e) {
+			this.#t = e, super.session = e, this.dispatchSessionChanged();
+		}
+		get session() {
+			return this.#t;
+		}
+		isComplete() {
+			return i.isComplete(this.#e, this.#t);
+		}
+		writeSession(t) {
+			this.#t = e(this.#t, t), super.session = t;
+		}
+		dispatchSessionChanged() {
+			this.dispatchEvent(new n(this.tagName.toLowerCase(), this.isComplete()));
+		}
+	}
+	return o;
+}
+//#endregion
+export { r as defineDeliveryElement };

package/dist/write-session-in-place.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Assign a delivery update into the session object the player owns, keeping the
+ * reference.
+ *
+ * A player hands the element a session object and reads the learner's response
+ * back off that same object: `pie-player` pushes its entry into the host's own
+ * `session.data` array, and `pie-item-player`'s renderer forwards the array it
+ * holds rather than `element.session`. An element that only replaces its own
+ * reference leaves the player's entry at its load-time value, so the forwarded
+ * container compares equal to the previous one and normalizes to
+ * `intent: "metadata-only"` with `session: null` - the element reports a change
+ * and the response never arrives. The React elements mutate the session they
+ * were given (`updateSessionValue`); this is that contract for the Svelte
+ * elements, which additionally hand their component a fresh reference so
+ * `$derived` reads of `props.session` still re-run.
+ *
+ * Keys absent from `next` are removed, so clearing a response clears it on the
+ * player's object too. Anything that is not a plain object on both sides is
+ * returned as the replacement it already was, and so is a frozen or sealed
+ * target: writing into one throws in strict mode, which would take the
+ * learner's update with it before the element ever stored it.
+ */
+export declare function writeSessionInPlace(target: unknown, next: unknown): unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pie-lib/delivery-events-svelte",
-  "version": "0.1.1-next.1",
+  "version": "0.2.0-next.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pie-framework/pie-elements-ng.git",

package/dist/session-bridge.d.ts

@@ -1,58 +0,0 @@
-export type DeliveryHostElement = HTMLElement & {
-    session?: unknown;
-    onSessionChange?: (session: unknown) => void;
-    onAudioStarted?: () => void;
-    onAudioEnded?: () => void;
-};
-type HostPredicate = (node: unknown) => boolean;
-export interface ResolveDeliveryHostOptions {
-    hostPredicate?: HostPredicate;
-}
-/**
- * Walk up the DOM from a source element and find the nearest delivery host wrapper.
- * The walk continues from a shadow root to its host, so a wrapper that renders the
- * element inside its own shadow root is still found.
- *
- * There is no lookup by tag name: a player registers the element under a tag it
- * chooses (versioned, e.g. `simple-cloze--version-0-2-0`), so the element cannot
- * know it, and a document-wide query could reach a different instance.
- */
-export declare function resolveDeliveryHost(sourceEl?: HTMLElement | null, options?: ResolveDeliveryHostOptions): DeliveryHostElement | null;
-/**
- * Assign a delivery update into the session object the player owns, keeping the
- * reference.
- *
- * A player hands the element a session object and reads the learner's response
- * back off that same object: `pie-player` pushes its entry into the host's own
- * `session.data` array, and `pie-item-player`'s renderer forwards the array it
- * holds rather than `element.session`. An element that only replaces its own
- * reference leaves the player's entry at its load-time value, so the forwarded
- * container compares equal to the previous one and normalizes to
- * `intent: "metadata-only"` with `session: null` - the element reports a change
- * and the response never arrives. The React elements mutate the session they
- * were given (`updateSessionValue`); this is that contract for the Svelte
- * elements, which additionally hand their component a fresh reference so
- * `$derived` reads of `props.session` still re-run.
- *
- * Keys absent from `next` are removed, so clearing a response clears it on the
- * player's object too. Anything that is not a plain object on both sides is
- * returned as the replacement it already was, and so is a frozen or sealed
- * target: writing into one throws in strict mode, which would take the
- * learner's update with it before the element ever stored it.
- */
-export declare function writeSessionInPlace(target: unknown, next: unknown): unknown;
-export interface ForwardSessionChangeOptions {
-    sourceEl?: HTMLElement | null;
-    complete: boolean;
-    session: unknown;
-}
-/**
- * Forward a delivery session update using the host callback when available.
- * If no callback is exposed, write the update into the host's session, as
- * `writeSessionInPlace` does for a wrapper, and dispatch the canonical
- * session-changed metadata event, named for the tag the host was registered
- * under: the event carries no session, so a player reads the response off it.
- * Returns `null`, and warns, when the source element has no delivery host.
- */
-export declare function forwardSessionChange({ sourceEl, complete, session, }: ForwardSessionChangeOptions): DeliveryHostElement | null;
-export {};