mithril-lynx 2.6.0 → 3.0.0

package/src/patch-protocol.js

@@ -13,6 +13,23 @@
 // main-thread side by `applyPatch()` (see backends/papi-backend.js), so
 // nodes never need to be looked up by anything other than that integer.
 
+/**
+ * The wire protocol version, prepended to every patch by
+ * `sendPatchToMainThread()` and validated (then stripped) by the main
+ * thread before any op is interpreted. The two bundles are normally built
+ * from the same source, but a partial HMR or a cached main-thread bundle
+ * could otherwise re-interpret a reordered opcode silently — a version
+ * mismatch throws instead of corrupting the mirrored id space.
+ *
+ * The value is deliberately outside the opcode range (0x4d4c was "ML"
+ * in ASCII; bumped to 0x4d4d in 3.0.0, when the Op.CreateList /
+ * Op.SetListItems list protocol was replaced by plain `list`/`list-item`
+ * elements, and to 0x4d4e, also in 3.0.0, when Op.InvokeUIMethod /
+ * Op.SetInputValue were added) so a versioned array can never be misread as an op sequence if
+ * it is ever fed to `applyPatch()` without the strip.
+ */
+export const PROTOCOL_VERSION = 0x4d4e;
+
 export const Op = Object.freeze({
 	CreateElement: 0,
 	CreateElementNS: 1,
@@ -42,20 +59,38 @@ export const Op = Object.freeze({
 	// background-thread side.
 	SetGestureDetector: 14, // id, gestureId, gestureType, arenaPolicy
 	RemoveGestureDetector: 15, // id, gestureId
-	// A native virtualized list — see docs/native-papi/papi-06-virtualized-lists.md
-	// in mithril-lynx-ui for the full design. Each list item is rendered on
-	// the BACKGROUND thread, through the app's own real render pass
-	// (list-cell.js), same as everything else in the tree — the main thread
-	// never runs renderItem() itself, only replays the ops that rendering
-	// already produced (apply-patch.js's Op.CreateList case + list-support.js).
-	CreateList: 16, // id, scrollOrientation, listType, spanCount
-	SetListItems: 17, // id, cellsJSON — cellsJSON = JSON.stringify(cells), cells: Array<{ typeKey, containerId, ops, rootChildIds }>, one entry per current item, computed by list-cell.js's renderListCell(). `ops` is a flat op array in this SAME encoding, scoped to `containerId` as its root parent id.
+	// Calls a native UI method (`focus`, `getValue`, `scrollTo`, …) through
+	// the main-thread `__InvokeUIMethod` PAPI — the path ReactLynx's
+	// main-thread `Element.invoke()` uses. Deferred until after the patch's
+	// `__FlushElementTree()`, so an element created by the same patch
+	// already exists natively. callbackId 0 = no result wanted; otherwise
+	// the result comes back as an INVOKE_RESULT_EVENT forwarded event.
+	InvokeUIMethod: 16, // id, method, params, callbackId
+	// `value` of an <input>/<textarea>: a `setValue` UI method call guarded
+	// by `seq`, the number of native `input` events the background had seen
+	// for this field when it computed the value. The main thread drops it
+	// when the user has typed since (a newer `input` event is in flight and
+	// will re-render) — see apply-patch.js.
+	SetInputValue: 17, // id, value, seq
 });
 
+/** The reserved forwarded-event type that carries an Op.InvokeUIMethod
+ * result (`{ callbackId, code, data }`) back to the background thread, over
+ * the same channel as native events. Never an element's own event type. */
+export const INVOKE_RESULT_EVENT = "mithrilLynx:invokeResult";
+
+/** Tags whose `value` is a native UI method call (Op.SetInputValue) rather
+ * than an attribute. */
+export const FORM_FIELD_TAGS = Object.freeze(["input", "textarea"]);
+
 /**
  * Encodes one op onto a flat ops array. Kept as a tiny helper (not a class)
  * so the hot path (called on every attribute/child mutation during a real
  * Mithril diff) is just array pushes — no object allocation per op.
+ * @param {unknown[]} ops - The flat ops array to append to.
+ * @param {number} opcode - One of the `Op` codes.
+ * @param {...unknown} args - The op's arguments (see `OP_ARITY`).
+ * @returns {void}
  */
 export function pushOp(ops, opcode, ...args) {
 	ops.push(opcode, ...args);
@@ -65,8 +100,7 @@ export function pushOp(ops, opcode, ...args) {
 // for walking a flat ops array without re-interpreting it (apply-patch.js's
 // own switch increments `i` inline instead of using this table, since it
 // also needs to look at individual arg values as it goes; this exists for
-// callers that only need to skip/scan, e.g. list-cell.js's
-// findTopLevelChildIds(), which never applies the ops itself).
+// callers that only need to skip/scan an ops array without applying it).
 export const OP_ARITY = Object.freeze({
 	[Op.CreateElement]: 2, // tag, id
 	[Op.CreateElementNS]: 3, // ns, tag, id
@@ -84,13 +118,18 @@ export const OP_ARITY = Object.freeze({
 	[Op.RemoveEvent]: 2, // id, type
 	[Op.SetGestureDetector]: 4, // id, gestureId, gestureType, arenaPolicy
 	[Op.RemoveGestureDetector]: 2, // id, gestureId
-	[Op.CreateList]: 4, // id, scrollOrientation, listType, spanCount
-	[Op.SetListItems]: 2, // id, cellsJSON
+	[Op.InvokeUIMethod]: 4, // id, method, params, callbackId
+	[Op.SetInputValue]: 3, // id, value, seq
 });
 
 /** Walks a flat ops array, calling `visit(opcode, args)` once per op — args
  * is the plain slice of that op's own arguments (not including the opcode
- * itself). Throws on an unknown opcode rather than silently desyncing. */
+ * itself). Throws on an unknown opcode rather than silently desyncing.
+ * @param {unknown[]} ops - A flat ops array.
+ * @param {(opcode: number, args: unknown[]) => void} visit - Called once per op with its arguments.
+ * @returns {void}
+ * @throws {Error} On an unknown opcode.
+ */
 export function forEachOp(ops, visit) {
 	for (let i = 0; i < ops.length; ) {
 		const opcode = ops[i++];

package/src/reload/version.js

@@ -13,16 +13,25 @@
 
 let version = 0;
 
+/**
+ * @returns {number} The current reload version.
+ */
 export function getReloadVersion() {
 	return version;
 }
 
+/**
+ * @returns {number} The new reload version, after incrementing.
+ */
 export function increaseReloadVersion() {
 	return ++version;
 }
 
 /** True if a patch stamped with `patchVersion` is stale and must be
- * dropped without being applied — the ENTIRE guard, one comparison. */
+ * dropped without being applied — the ENTIRE guard, one comparison.
+ * @param {*} patchVersion - The version stamped on a patch.
+ * @returns {boolean} `true` when `patchVersion` is a number older than the current version.
+ */
 export function isStaleVersion(patchVersion) {
 	return typeof patchVersion === "number" && patchVersion < version;
 }

package/src/request.d.ts

@@ -10,6 +10,8 @@ export interface RequestOptions<T = any> {
 	serialize?: (data: unknown) => string;
 	deserialize?: (data: unknown) => unknown;
 	extract?: (response: unknown, options: RequestOptions<T>) => unknown;
+	/** A constructor applied to the response: per element when the response
+	 * is an array (matching real `m.request`), otherwise to the whole result. */
 	type?: new (data: any) => T;
 	background?: boolean;
 	// Present on the real m.request signature but confirmed unsupported —

package/src/request.js

@@ -32,6 +32,12 @@ const UNSUPPORTED = [
 	["withCredentials", (o) => o.withCredentials === true],
 ];
 
+/**
+ * Throws if `options` uses an option Lynx's fetch cannot honor.
+ * @param {Object} options - The request options.
+ * @returns {void}
+ * @throws {Error} If an unsupported option (`config`, `async: false`, `user`, `password`, `withCredentials`) is present.
+ */
 function checkUnsupported(options) {
 	for (const [name, matches] of UNSUPPORTED) {
 		if (matches(options)) {
@@ -44,6 +50,12 @@ function checkUnsupported(options) {
 	}
 }
 
+/**
+ * Case-insensitive own-property check for a header name.
+ * @param {Object<string, string>} headers - The headers object.
+ * @param {string} name - The lowercase header name to look for.
+ * @returns {boolean}
+ */
 function hasHeader(headers, name) {
 	for (const key in headers) {
 		if (Object.prototype.hasOwnProperty.call(headers, key) && key.toLowerCase() === name) return true;
@@ -51,6 +63,12 @@ function hasHeader(headers, name) {
 	return false;
 }
 
+/**
+ * Wraps response data in `Type` instances, per item for arrays.
+ * @param {*} data - The response data.
+ * @param {Function} [Type] - A constructor; when not a function, `data` is returned unchanged.
+ * @returns {*} The wrapped data.
+ */
 function applyType(data, Type) {
 	if (typeof Type !== "function") return data;
 	if (Array.isArray(data)) return data.map((item) => new Type(item));
@@ -63,10 +81,18 @@ function applyType(data, Type) {
  *   so importing this file never requires `lynx` to already exist) —
  *   same pattern route.js uses for `renderApp`. Tests inject a fake here
  *   instead of hitting a real network.
+ * @returns {(url: string|Object, options?: Object) => Promise<*>} A `request` function shaped like `m.request`; its promise has an extra `abort()` method.
  */
 export function createRequestor(fetchImpl) {
 	const doFetch = fetchImpl || ((url, init) => lynx.fetch(url, init));
 
+	/**
+	 * Performs a request and redraws when it settles (unless `options.background` is `true`).
+	 * @param {string|Object} url - The URL, or an options object containing `url`.
+	 * @param {Object} [options] - `m.request`-style options (`method`, `params`, `body`, `headers`, `serialize`, `deserialize`, `extract`, `type`, `responseType`, `timeout`, `signal`, `background`).
+	 * @returns {Promise<*> & {abort: () => void}} Resolves with the (typed) response data; rejects with an `Error` carrying `code` and `response` for non-OK statuses.
+	 * @throws {Error} Synchronously, for unsupported options or a `FormData` body.
+	 */
 	return function request(url, options) {
 		if (typeof url !== "string") {
 			options = url;
@@ -112,9 +138,17 @@ export function createRequestor(fetchImpl) {
 		// controller so a caller-provided signal and our timeout can both
 		// trigger the same abort.
 		const ctrl = new AbortController();
+		// Stored so the listener can be detached on settle (see detachSignal
+		// below) — a long-lived shared AbortSignal would otherwise accumulate
+		// one dead closure per request.
+		/**
+		 * Aborts the internal controller when the caller's signal aborts.
+		 * @returns {void}
+		 */
+		const abortHandler = () => ctrl.abort();
 		if (options.signal) {
 			if (options.signal.aborted) ctrl.abort();
-			else options.signal.addEventListener("abort", () => ctrl.abort());
+			else options.signal.addEventListener("abort", abortHandler);
 		}
 		let timeoutId;
 		if (options.timeout) {
@@ -123,6 +157,10 @@ export function createRequestor(fetchImpl) {
 				: setTimeout;
 			timeoutId = schedule(() => ctrl.abort(), options.timeout);
 		}
+		/**
+		 * Cancels the pending timeout, if any.
+		 * @returns {void}
+		 */
 		function clearRequestTimeout() {
 			if (timeoutId == null) return;
 			const clear = typeof lynx !== "undefined" && typeof lynx.clearTimeout === "function"
@@ -138,8 +176,10 @@ export function createRequestor(fetchImpl) {
 
 			if (typeof options.extract === "function") {
 				// Matches real m.request: extract() bypasses the status check
-				// entirely — it decides success/failure itself.
-				return options.extract(response, options);
+				// entirely — it decides success/failure itself. `type` is still
+				// applied afterwards, exactly as upstream does (extract does NOT
+				// skip the type constructor).
+				return applyType(options.extract(response, options), options.type);
 			}
 
 			const ok = response.ok || response.status === 304;
@@ -156,12 +196,28 @@ export function createRequestor(fetchImpl) {
 			});
 		});
 
+		// Detach the caller's signal listener once this request settles, so a
+		// long-lived shared AbortSignal doesn't accumulate a dead closure per
+		// request. Done inside the settled handlers (rather than a separate
+		// `.then`) so an ignored rejection still surfaces as unhandled.
+		/**
+		 * Detaches the abort listener from the caller's signal.
+		 * @returns {void}
+		 */
+		const detachSignal = () => {
+			if (options.signal && !options.signal.aborted) {
+				options.signal.removeEventListener("abort", abortHandler);
+			}
+		};
+
 		const result = promise.then(
 			(value) => {
+				detachSignal();
 				if (options.background !== true) sharedRedraw();
 				return value;
 			},
 			(error) => {
+				detachSignal();
 				clearRequestTimeout();
 				if (options.background !== true) sharedRedraw();
 				throw error;

package/src/route.d.ts

@@ -1,4 +1,14 @@
-import type { Component } from "mithril";
+/**
+ * Minimal Mithril-style component type. Declared locally because this
+ * package's runtime peer is `mithril-runtime`, which ships no TypeScript
+ * types of its own; the previous `import type { Component } from "mithril"`
+ * depended on an undeclared module. `view`'s return is typed `any` so
+ * `route.Link` stays assignable to a caller's own `m()` typed against
+ * `@types/mithril`.
+ */
+export interface Component<Attrs = unknown> {
+	view(vnode: { attrs: Attrs; children?: unknown }): any;
+}
 
 export interface RouteResolver {
 	onmatch?(args: Record<string, string>, requestedPath: string, route: string): unknown;
@@ -11,17 +21,51 @@ export interface RouteLinkAttrs {
 	params?: Record<string, unknown>;
 	options?: { replace?: boolean };
 	disabled?: boolean;
-	ontap?: (e: unknown) => unknown;
+	ontap?: ((e: unknown) => unknown) | { handleEvent(e: unknown): void };
 	[key: string]: unknown;
 }
 
+export interface RouteSetOptions {
+	/** Overwrite the current history entry instead of pushing a new one. */
+	replace?: boolean;
+	/** Merged into the route's params; restored by back()/forward(). */
+	state?: Record<string, unknown>;
+	/** Accepted for m.route compatibility; ignored (no title bar). */
+	title?: string;
+}
+
+export interface ListenBackButtonOptions {
+	/** Global event the host sends when back is pressed. @defaultValue "mithrilLynx:back" */
+	eventName?: string;
+	/** Called with canGoBack() right away and whenever it changes — e.g. to
+	 * enable/disable the host's OnBackPressedCallback through a native module. */
+	onCanGoBackChange?: (canGoBack: boolean) => void;
+}
+
 export interface Route {
+	/** `defaultRoute` is required: Lynx has no URL to start from. */
 	(defaultRoute: string, routes: Record<string, unknown | RouteResolver>): void;
-	set(path: string, data?: unknown, options?: { replace?: boolean }): void;
+	/** Updates the history now; the new screen resolves on the next microtask
+	 * (like m.route), so get() returns the previous path until then. */
+	set(path: string, data?: unknown, options?: RouteSetOptions): void;
+	/** The current path, decoded. */
 	get(): string | undefined;
+	/** Returns the named route parameter (with `key`), or the whole params
+	 * object (without). Typed `unknown` because the value can be a string
+	 * (path params), a string|boolean (query params — `"true"`/`"false"` are
+	 * coerced), or anything passed as `data` to `set(path, data)`; the common
+	 * path-param case is always a string. */
 	param(key?: string): unknown;
-	back(): void;
-	forward(): void;
+	/** Walks back one entry; returns `false` (without navigating) at the top
+	 * of the history stack so a back affordance can disable itself. */
+	back(): boolean;
+	/** Walks forward one entry; returns `false` (without navigating) at the
+	 * end of the history stack so a forward affordance can disable itself. */
+	forward(): boolean;
+	/** Whether back() would navigate. */
+	canGoBack(): boolean;
+	/** Opt-in Android back button bridge (see ROUTE.md). Returns a function that stops listening. */
+	listenBackButton(options?: ListenBackButtonOptions): () => void;
 	prefix: string;
 	SKIP: unknown;
 	Link: Component<RouteLinkAttrs>;
@@ -29,5 +73,8 @@ export interface Route {
 
 export function createRoute(): Route;
 
+/** Default event name listened to by `route.listenBackButton()`. */
+export declare const BACK_EVENT_NAME: string;
+
 declare const route: Route;
 export default route;