mithril-lynx 0.0.1 → 0.0.2

package/README.md

@@ -206,11 +206,48 @@ Two tiers, matching the real complexity spread in Lynx's own `list` examples:
 
   **Deliberately out of scope for v1** (documented, not silently missing): deferred list items (ReactLynx's `defer`/`isReady` promise dance), `componentAtIndexes` batching, and independent per-item redraw after the initial bind — a bound cell's content is recomputed fresh from `renderItem(index)` only when native calls `componentAtIndex` for it (scroll-driven reuse), not automatically when app state changes.
 
+## Navigation
+
+`mithril-lynx/navigation`'s `createNavigator({ initial, initialAttrs? })` is a stack-based, in-memory screen navigator — deliberately **not** built on `m.route` (see "Known permanent gaps" below: Lynx pages have no URL/History API for `m.route` to hook into). Android's own Activity navigation doesn't need URLs either — it's a plain back-stack — so this is that idea directly, not a URL-shaped abstraction forced onto an environment with no URLs.
+
+```js
+import { createNavigator } from "mithril-lynx/navigation";
+import m from "mithril";
+
+const Home = {
+  view: (vnode) => m("view", { ontap: () => vnode.attrs.nav.push(Details, { id: 42 }) }, [
+    m("text", null, "Go to details"),
+  ]),
+};
+const Details = {
+  view: (vnode) => m("view", { ontap: () => vnode.attrs.nav.pop() }, [
+    m("text", null, "Details for #" + vnode.attrs.id + " — tap to go back"),
+  ]),
+};
+
+const nav = createNavigator({ initial: Home });
+shim.renderToPage(page, m(nav.Navigator)); // main-thread-owned mode
+```
+
+Every screen the navigator renders receives its own `attrs` plus a `nav` prop (`push`/`pop`/`replace`/`canGoBack`/`depth`), so screens don't need to import the navigator instance separately to navigate onward. Only the top of the stack is ever mounted — previous screens are torn down, not kept alive offscreen (matching how most single-activity/single-page navigators behave); a popped screen that needs to remember its own state should keep that state somewhere the app already owns (a module-level store, `background.js`'s data store, etc.), not rely on its own component instance surviving the pop.
+
+Built on `shim.redraw()` alone, so it works unmodified in all three rendering modes (main-thread-owned, data-channel, renderer) — `nav.push()`/`pop()`/`replace()` just trigger whichever redraw mechanism that mode already uses.
+
+**Deliberately out of scope for v1**: screen transition animations (left entirely to the app's own CSS/styling on whatever wraps `nav.Navigator`), and hardware back-button integration (no documented Lynx PAPI hook for it was found — wire a screen's own back-affordance to `nav.pop()` instead, as in the example above).
+
 ## Known permanent gaps
 
 - `m.trust` / innerHTML vnodes — no Lynx PAPI equivalent to raw innerHTML injection.
 - `m.route` — Lynx pages aren't URL-addressable the way DOM `history` is.
 
+## Known gap, not permanent
+
+- `m.request` — throws (`XMLHttpRequest is not defined`) rather than silently misbehaving: it's hard-wired to a real `XMLHttpRequest`, which doesn't exist in Lynx's JS runtime (neither the main-thread Lepus/QuickJS engine nor the background JS thread). Unlike `m.trust`/`m.route` above, this isn't structural — Lynx does have its own networking primitives — it just hasn't been wrapped in a `$window`-shaped compat layer yet. Use Lynx's own networking API directly (wrapped in a `Promise`, if desired) until this exists.
+
+## Rest of the public `m` API — what's actually used
+
+Beyond hyperscript (`m(...)`) itself, only `m.fragment` and `m.censor` are used as shipped from the real `mithril` package — both are pure data/diff logic with no DOM dependency, so they work unmodified. `m.render`, `m.mount`, and `m.redraw` are never called from the real package at all: `mithril-lynx` has its own equivalents (`shim.renderToPage()`/`shim.render()`/`shim.redraw()`, this README's own "Usage" sections) that target the Lynx Element PAPI instead of the DOM — calling the *real* `m.mount()`/`m.redraw()` does nothing here, since they're wired to `m.render()`'s own DOM-only render path, which this project's apps never invoke.
+
 ## Compat with the plain-JS ecosystem
 
 Mithril was never hooks-based, so — unlike React — there's no special rules-of-hooks compatibility story to build: `m.redraw()` after any state mutation already works with any plain-JS state library (a simple pub/sub store, streams, whatever). Nothing in this package needs to shim a specific state-management library for that reason; if something in the ecosystem doesn't work, it's not because of a hooks-equivalence gap.

package/navigation.d.ts

@@ -0,0 +1,35 @@
+// Ambient declaration for the ESM navigation.js (the file itself is not
+// type-checked; this describes its runtime export shape for TS consumers).
+
+import type { Component, ComponentTypes } from "mithril";
+
+export interface Nav {
+  /** Pushes a new screen onto the stack and redraws. */
+  push(component: ComponentTypes<any, any>, attrs?: Record<string, unknown>): void;
+  /** Replaces the current top screen without growing the stack, and redraws. */
+  replace(component: ComponentTypes<any, any>, attrs?: Record<string, unknown>): void;
+  /** Pops the top screen and redraws. Returns false (a no-op) at the root screen. */
+  pop(): boolean;
+  /** True if pop() would actually pop something (stack depth > 1). */
+  canGoBack(): boolean;
+  /** Current stack depth (1 at the root screen). */
+  depth(): number;
+}
+
+export interface Navigator extends Nav {
+  /** Mithril component that always renders whichever screen is on top of the stack. */
+  Navigator: Component;
+}
+
+export interface CreateNavigatorOptions {
+  /** The root screen, mounted first. */
+  initial: ComponentTypes<any, any>;
+  initialAttrs?: Record<string, unknown>;
+}
+
+/**
+ * Creates a stack-based, in-memory navigator (no m.route, no URLs — see
+ * navigation.js's header comment for why). Every screen the navigator
+ * renders receives its own attrs plus a `nav` prop shaped like {@link Nav}.
+ */
+export function createNavigator(options: CreateNavigatorOptions): Navigator;

package/navigation.js

@@ -0,0 +1,76 @@
+// navigation.js
+//
+// Stack-based, in-memory screen navigation (project plan follow-up, "basic
+// Activity" template support) — deliberately NOT built on m.route. Real
+// `m.route` is hard-wired to the browser's URL/History API (see README.md's
+// "Known permanent gaps"), which has no Lynx equivalent: a Lynx page has no
+// address bar, no back/forward, nothing URL-addressable. Android's own
+// Activity navigation doesn't need URLs either — it's a plain back-stack —
+// so this module ports that idea directly instead of forcing a URL-shaped
+// abstraction onto an environment that has no URLs.
+//
+// Only the top of the stack is ever mounted (previous screens are torn
+// down, not kept alive offscreen) — matching how most single-activity /
+// single-page navigators actually behave, and avoiding the cost of keeping
+// arbitrarily many past screens' DOM trees around. A popped screen that
+// needs to remember its own state should keep that state somewhere the app
+// already owns (a module-level store, background.js's data store, etc.),
+// not rely on the screen's own component instance surviving the pop.
+
+import shim from "./src/lynx-mithril-shim.js";
+import m from "mithril";
+
+/**
+ * Creates a navigator: a stack of {component, attrs} screens, plus a
+ * `Navigator` Mithril component that always renders whichever screen is on
+ * top. Every screen receives its own `attrs` PLUS a `nav` prop (this
+ * navigator's push/pop/replace/canGoBack), so screens don't need to import
+ * the navigator instance separately to navigate onward.
+ */
+export function createNavigator(options) {
+	const { initial, initialAttrs } = options;
+	if (initial == null) throw new Error("mithril-lynx/navigation: createNavigator() requires an `initial` screen");
+
+	const stack = [{ component: initial, attrs: initialAttrs }];
+
+	function top() {
+		return stack[stack.length - 1];
+	}
+
+	function push(component, attrs) {
+		stack.push({ component, attrs });
+		shim.redraw();
+	}
+
+	function replace(component, attrs) {
+		stack[stack.length - 1] = { component, attrs };
+		shim.redraw();
+	}
+
+	/** Returns false (a no-op) at the root screen, true otherwise. */
+	function pop() {
+		if (stack.length <= 1) return false;
+		stack.pop();
+		shim.redraw();
+		return true;
+	}
+
+	function canGoBack() {
+		return stack.length > 1;
+	}
+
+	function depth() {
+		return stack.length;
+	}
+
+	const nav = { push, pop, replace, canGoBack, depth };
+
+	const Navigator = {
+		view() {
+			const { component, attrs } = top();
+			return m(component, Object.assign({}, attrs, { nav }));
+		},
+	};
+
+	return Object.assign({ Navigator }, nav);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mithril-lynx",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Mithril.js rendered through Lynx's Element PAPI — a contract-complete port of mithril/render/render.js@2.3.8 to the Lynx main thread, packaged as a reusable framework.",
   "license": "MIT",
   "type": "module",
@@ -49,6 +49,10 @@
       "types": "./list.d.ts",
       "default": "./list.js"
     },
+    "./navigation": {
+      "types": "./navigation.d.ts",
+      "default": "./navigation.js"
+    },
     "./testing": {
       "types": "./testing.d.ts",
       "default": "./testing.js"
@@ -70,6 +74,8 @@
     "gesture.d.ts",
     "list.js",
     "list.d.ts",
+    "navigation.js",
+    "navigation.d.ts",
     "testing.js",
     "testing.d.ts",
     "CONTRACT.md"