@farm.js/islx 0.0.0-stage → 0.0.2

package/dist/_chunks/handle-C0N9ZyNV.d.mts

@@ -0,0 +1,35 @@
+/** React's form state: the result, the hook it belongs to, the action id, its bound count. */
+type ReactFormState = [state: unknown, key: string, referenceId: string, boundCount: number];
+interface ActionErrorOutcome {
+  /** Send the browser here: a 303 for forms, `{"redirect"}` for calls. */
+  redirect?: string;
+  /** Answer with this status (and no details). */
+  status?: number;
+}
+interface HandleActionOptions {
+  /** Origins or hosts, besides the request's own, that may post actions: `*.example.com`. */
+  allowedOrigins?: readonly string[];
+  /** The largest body accepted, in bytes. Default 1 MB. */
+  bodySizeLimit?: number;
+  /**
+   * Runs the action, so the framework can give it the request's context (cookies, headers,
+   * an abort signal).
+   */
+  run?<T>(request: Request, action: () => Promise<T>): Promise<T>;
+  /**
+   * Maps an error the action threw to a redirect or a status: the framework's `redirect()` and
+   * `notFound()`. Anything unmapped is a 500, logged with `onError`.
+   */
+  mapError?(error: unknown): ActionErrorOutcome | undefined;
+  /**
+   * Renders the page after a form posted from a `useActionState` hook, with the action's result
+   * as React's `formState` (`renderToReadableStream(…, { formState })`, and the same to
+   * `hydrateRoot`). Without it, the form redirects back and the result is not shown.
+   */
+  renderFormState?(formState: ReactFormState, request: Request): Response | Promise<Response>;
+  /** Reports an action that failed. Default `console.error`. */
+  onError?(error: unknown): void;
+}
+/** Runs the server action a request posts, or returns null when it posts none. */
+declare function handleAction(request: Request, options?: HandleActionOptions): Promise<Response | null>;
+export { handleAction as i, HandleActionOptions as n, ReactFormState as r, ActionErrorOutcome as t };

package/dist/_chunks/hooks-3VZV8f_d.d.mts

@@ -0,0 +1,30 @@
+import { t as ActionErrorOutcome } from "./handle-C0N9ZyNV.mjs";
+
+// src/server/hooks.d.ts
+
+interface ActionInfo {
+  request: Request;
+  /** The action's id. */
+  id: string;
+  /** Its export name, or the inline function's name. */
+  name: string;
+  /** Its module, from the app root. */
+  module: string;
+}
+interface ServerHooks {
+  /**
+   * Wraps every action: check the caller, rate-limit, log, time. Call `run` to run the action,
+   * and return what it returns; throw to refuse (`actionError` maps the error to a response).
+   */
+  action?(info: ActionInfo, run: () => Promise<unknown>): Promise<unknown>;
+  /** Maps an error an action threw to a redirect or a status: a framework's `redirect()`. */
+  actionError?(error: unknown, info: ActionInfo): ActionErrorOutcome | undefined;
+  /** Reports an action that failed with an error nothing mapped. */
+  error?(error: unknown, info: ActionInfo): void;
+}
+/** Types an app's server hooks. */
+declare function defineServerHooks(hooks: ServerHooks): ServerHooks;
+/** Installs the app's hooks; the plugin's server runtime calls it. */
+declare function setServerHooks(hooks: ServerHooks | undefined): void;
+declare function getServerHooks(): ServerHooks;
+export { setServerHooks as a, getServerHooks as i, ServerHooks as n, defineServerHooks as r, ActionInfo as t };

package/dist/_chunks/hooks-De0gNpOn.d.mts

@@ -0,0 +1,64 @@
+import { n as IslandStrategy } from "./schedule-Dw14dW0H.mjs";
+
+// src/client/hooks.d.ts
+
+interface ClientHookEvents {
+  /** Before the next page is fetched. `preventDefault()` stays on this page. */
+  navigate: {
+    url: URL;
+    from: URL;
+    kind: "link" | "history" | "code";
+  };
+  /** The next page is in place. */
+  navigated: {
+    url: URL;
+    duration: number;
+  };
+  /** A navigation fell back to loading the page the ordinary way. */
+  navigateError: {
+    url: URL;
+    reason: string;
+  };
+  /** An island became interactive: `duration` runs from scheduling to React's first commit. */
+  hydrate: {
+    element: Element;
+    src: string;
+    export: string;
+    strategy: IslandStrategy;
+    duration: number;
+  };
+  /** An island failed; its server HTML was restored. */
+  islandError: {
+    element: Element;
+    src: string;
+    export: string;
+    error: unknown;
+  };
+  /** A server action call starts. `name` is the export (or inline function) name when known. */
+  action: {
+    id: string;
+    name?: string;
+  };
+  /** A server action call finished. */
+  actionEnd: {
+    id: string;
+    name?: string;
+    ok: boolean;
+    duration: number;
+    redirect?: string;
+    error?: unknown;
+  };
+}
+type ClientHookEvent<Name extends keyof ClientHookEvents> = ClientHookEvents[Name] & {
+  /** Only `navigate` can be cancelled. */
+  preventDefault(): void;
+  readonly defaultPrevented: boolean;
+};
+type ClientHooks = { [Name in keyof ClientHookEvents]?: (event: ClientHookEvent<Name>) => void };
+/** Types an app's hooks module. */
+declare function defineClientHooks(hooks: ClientHooks): ClientHooks;
+/** Installs the app's hooks; the plugin's browser entry calls it. */
+declare function setClientHooks(hooks: ClientHooks | undefined): void;
+/** The DOM event name of a hook: `navigateError` → `f:navigate-error`. */
+declare function hookEventName(name: keyof ClientHookEvents): string;
+export { hookEventName as a, defineClientHooks as i, ClientHookEvents as n, setClientHooks as o, ClientHooks as r, ClientHookEvent as t };

package/dist/_chunks/prehydration-B1GLTLdk.mjs

@@ -0,0 +1,36 @@
+// src/client/prehydration.ts
+/**
+* Holding interactions that happen before the islx script has run. An inline script in the page
+* captures a click or a submit on an island that has not hydrated (it is prevented and queued),
+* and announces a pointerdown or a focus (which go through). The runtime then hydrates those
+* islands first and replays what was held.
+*
+* The script is inlined into every page, so it stays hand-minified and imports nothing.
+*/
+/** Where the inline script queues held interactions: `{ target, kind }`. */
+const PENDING_INTERACTIONS = "__islxPending";
+/** The DOM event the script dispatches for each interaction it sees. */
+const INTERACTION_EVENT = "f:island-interaction";
+/** Elements whose click is held and replayed rather than merely observed. */
+const REPLAYABLE_SELECTOR = "button,[role=\"button\"],input[type=\"button\"],input[type=\"submit\"],input[type=\"reset\"]";
+/** The inline script's source (no `<script>` tag): pass it to the page's head or bootstrap. */
+const PREHYDRATION_SCRIPT = `(function(){if(window.${PENDING_INTERACTIONS})return;var q=window.${PENDING_INTERACTIONS}=[];function island(n){var i=n&&n.closest&&n.closest("f-island");return i&&!i.hasAttribute("hydrated")?i:null}function tell(t,k){document.dispatchEvent(new CustomEvent("${INTERACTION_EVENT}",{detail:{target:t,kind:k}}))}function hold(e,t,k){if(!q.some(function(p){return p.target===t})){q.push({target:t,kind:k});tell(t,k)}e.preventDefault();e.stopImmediatePropagation()}document.addEventListener("click",function(e){if(e.defaultPrevented||e.button!==0||e.metaKey||e.altKey||e.ctrlKey||e.shiftKey)return;var t=e.target&&e.target.closest&&e.target.closest(${JSON.stringify(REPLAYABLE_SELECTOR)});if(!t||t.closest("a[href]")||!island(t))return;hold(e,t,"click")},true);document.addEventListener("submit",function(e){var f=e.target;if(e.defaultPrevented||!f||f.nodeName!=="FORM"||!island(f))return;hold(e,f,"submit")},true);function seen(e){if(island(e.target))tell(e.target,null)}document.addEventListener("pointerdown",seen,true);document.addEventListener("focusin",seen,true)})();`;
+/** Takes the interactions the inline script held inside `container`, oldest first. */
+function takePendingInteractions(container) {
+	const queue = globalThis[PENDING_INTERACTIONS];
+	if (!Array.isArray(queue)) return [];
+	const taken = [];
+	for (let index = queue.length - 1; index >= 0; index--) {
+		const item = queue[index];
+		if (!(item?.target instanceof Element) || !container.contains(item.target)) continue;
+		queue.splice(index, 1);
+		taken.unshift(item);
+	}
+	return taken;
+}
+/** Whether the inline script holds an interaction inside `container`. */
+function hasPendingInteraction(container) {
+	const queue = globalThis[PENDING_INTERACTIONS];
+	return Array.isArray(queue) && queue.some((item) => item?.target instanceof Element && container.contains(item.target));
+}
+export { hasPendingInteraction as a, REPLAYABLE_SELECTOR as i, PENDING_INTERACTIONS as n, takePendingInteractions as o, PREHYDRATION_SCRIPT as r, INTERACTION_EVENT as t };

package/dist/_chunks/schedule-BFoGKRrU.mjs

@@ -0,0 +1,216 @@
+import { a as hasPendingInteraction, o as takePendingInteractions, t as INTERACTION_EVENT } from "./prehydration-B1GLTLdk.mjs";
+import { m as HYDRATED_ATTRIBUTE } from "./wire-CXOodE06.mjs";
+// src/client/schedule.ts
+/**
+* When an island hydrates. Renderer-neutral: every adapter schedules through this.
+*
+* - `load`: as soon as the runtime starts (the default).
+* - `idle`: when the browser is idle, or after 2 seconds.
+* - `visible`: when the island comes within 200px of the viewport.
+* - `interaction`: on the first click, submit, pointerdown or focus inside it. A click or a
+*   submit is held while the island's code loads, then replayed on the hydrated island, so the
+*   user's first action is not lost.
+*
+* Until it hydrates, an island is its server HTML: links and native forms keep working.
+*/
+const ISLAND_STRATEGIES = [
+	"load",
+	"idle",
+	"visible",
+	"interaction"
+];
+function isIslandStrategy(value) {
+	return ISLAND_STRATEGIES.includes(value);
+}
+/** Elements whose click is held and replayed rather than merely observed. */
+const REPLAYABLE = "button,[role=\"button\"],input[type=\"button\"],input[type=\"submit\"],input[type=\"reset\"]";
+function whenIdle(callback) {
+	const scope = window;
+	if (typeof scope.requestIdleCallback === "function") {
+		const handle = scope.requestIdleCallback(callback, { timeout: 2e3 });
+		return () => scope.cancelIdleCallback?.(handle);
+	}
+	const handle = window.setTimeout(callback, 1);
+	return () => window.clearTimeout(handle);
+}
+const visibility = /* @__PURE__ */ new WeakMap();
+/** One observer per document, shared by every island; targets are released once they fire. */
+function whenVisible(document, targets, start) {
+	let registry = visibility.get(document);
+	if (!registry) {
+		const subscriptions = /* @__PURE__ */ new Map();
+		registry = {
+			observer: new IntersectionObserver((entries) => {
+				const pending = /* @__PURE__ */ new Set();
+				for (const entry of entries) if (entry.isIntersecting) for (const callback of subscriptions.get(entry.target) ?? []) pending.add(callback);
+				for (const callback of pending) callback();
+			}, { rootMargin: "200px" }),
+			targets: subscriptions
+		};
+		visibility.set(document, registry);
+	}
+	const current = registry;
+	for (const target of targets) {
+		let callbacks = current.targets.get(target);
+		if (!callbacks) {
+			callbacks = /* @__PURE__ */ new Set();
+			current.targets.set(target, callbacks);
+			current.observer.observe(target);
+		}
+		callbacks.add(start);
+	}
+	let active = true;
+	return () => {
+		if (!active) return;
+		active = false;
+		for (const target of targets) {
+			const callbacks = current.targets.get(target);
+			callbacks?.delete(start);
+			if (callbacks?.size === 0) {
+				current.targets.delete(target);
+				current.observer.unobserve(target);
+			}
+		}
+		if (current.targets.size === 0) {
+			current.observer.disconnect();
+			visibility.delete(document);
+		}
+	};
+}
+/**
+* Replays a held interaction. `requestSubmit()` dispatches a real submit event, so handlers bound
+* during hydration see it and validation runs; `form.submit()` would bypass both.
+*/
+function replay({ target, kind }) {
+	if (kind === "submit") {
+		const form = target;
+		if (typeof form.requestSubmit === "function") form.requestSubmit();
+		else target.dispatchEvent(new Event("submit", {
+			bubbles: true,
+			cancelable: true
+		}));
+		return;
+	}
+	const clickable = target;
+	if (typeof clickable.click === "function") clickable.click();
+	else target.dispatchEvent(new MouseEvent("click", {
+		bubbles: true,
+		cancelable: true
+	}));
+}
+function finish(container, held) {
+	const interactions = /* @__PURE__ */ new Map();
+	if (held) interactions.set(held.target, held);
+	for (const pending of takePendingInteractions(container)) if (pending.kind) interactions.set(pending.target, {
+		target: pending.target,
+		kind: pending.kind
+	});
+	if (!container.isConnected) return;
+	container.setAttribute(HYDRATED_ATTRIBUTE, "");
+	for (const interaction of interactions.values()) window.setTimeout(() => {
+		if (container.isConnected && interaction.target.isConnected && container.contains(interaction.target)) replay(interaction);
+	}, 0);
+}
+/** Runs `hydrate` when the island's strategy says; resolves with its result, or undefined if aborted. */
+function scheduleHydration({ container, strategy, signal, hydrate }) {
+	const resolved = strategy ?? "load";
+	if (signal?.aborted) return Promise.resolve(void 0);
+	if (resolved === "load") return Promise.resolve().then(() => signal?.aborted ? void 0 : hydrate()).then((value) => {
+		if (signal?.aborted) return void 0;
+		finish(container, null);
+		return value;
+	});
+	return new Promise((resolve, reject) => {
+		let started = false;
+		let cancelled = false;
+		let held = null;
+		const triggers = /* @__PURE__ */ new Set();
+		const captures = /* @__PURE__ */ new Set();
+		let removeAbort = null;
+		const cleanupTriggers = () => {
+			for (const dispose of triggers) dispose();
+			triggers.clear();
+		};
+		const cleanup = () => {
+			cleanupTriggers();
+			for (const dispose of captures) dispose();
+			captures.clear();
+			removeAbort?.();
+			removeAbort = null;
+		};
+		const start = () => {
+			if (started || cancelled) return;
+			started = true;
+			cleanupTriggers();
+			Promise.resolve().then(hydrate).then((value) => {
+				cleanup();
+				if (cancelled || signal?.aborted) return;
+				finish(container, held);
+				resolve(value);
+			}, (error) => {
+				cleanup();
+				reject(error);
+			});
+		};
+		if (signal) {
+			const abort = () => {
+				cancelled = true;
+				cleanup();
+				resolve(void 0);
+			};
+			signal.addEventListener("abort", abort, { once: true });
+			removeAbort = () => signal.removeEventListener("abort", abort);
+		}
+		if (hasPendingInteraction(container)) return start();
+		const onAnnounced = (event) => {
+			const detail = event.detail;
+			if (detail?.target instanceof Element && container.contains(detail.target)) start();
+		};
+		document.addEventListener(INTERACTION_EVENT, onAnnounced);
+		captures.add(() => document.removeEventListener(INTERACTION_EVENT, onAnnounced));
+		if (resolved === "idle") {
+			triggers.add(whenIdle(start));
+			return;
+		}
+		if (resolved === "visible") {
+			if (typeof IntersectionObserver !== "function") return start();
+			const targets = container.getClientRects().length > 0 ? [container] : Array.from(container.children);
+			if (targets.length === 0) return start();
+			triggers.add(whenVisible(container.ownerDocument, targets, start));
+			return;
+		}
+		const hold = (event, target, kind) => {
+			held ??= {
+				target,
+				kind
+			};
+			event.preventDefault();
+			event.stopImmediatePropagation();
+			start();
+		};
+		const onClick = (event) => {
+			const mouse = event;
+			const target = event.target instanceof Element ? event.target.closest(REPLAYABLE) : null;
+			if (!target || !container.contains(target) || target.closest("a[href]") || mouse.button !== 0 || mouse.metaKey || mouse.altKey || mouse.ctrlKey || mouse.shiftKey) return;
+			hold(event, target, "click");
+		};
+		const onSubmit = (event) => {
+			const form = event.target;
+			if (!(form instanceof Element) || form.nodeName !== "FORM") return;
+			if (!container.contains(form) || event.defaultPrevented) return;
+			hold(event, form, "submit");
+		};
+		const onActivate = (event) => {
+			if (event.target instanceof Element && container.contains(event.target)) start();
+		};
+		const listen = (type, handler) => {
+			document.addEventListener(type, handler, true);
+			captures.add(() => document.removeEventListener(type, handler, true));
+		};
+		listen("click", onClick);
+		listen("submit", onSubmit);
+		listen("pointerdown", onActivate);
+		listen("focusin", onActivate);
+	});
+}
+export { isIslandStrategy as n, scheduleHydration as r, ISLAND_STRATEGIES as t };

package/dist/_chunks/schedule-Dw14dW0H.d.mts

@@ -0,0 +1,17 @@
+type IslandStrategy = "load" | "idle" | "visible" | "interaction";
+declare const ISLAND_STRATEGIES: readonly IslandStrategy[];
+declare function isIslandStrategy(value: unknown): value is IslandStrategy;
+interface ScheduleOptions<T> {
+  container: Element;
+  strategy?: IslandStrategy | null;
+  signal?: AbortSignal;
+  hydrate(): T | Promise<T>;
+}
+/** Runs `hydrate` when the island's strategy says; resolves with its result, or undefined if aborted. */
+declare function scheduleHydration<T>({
+  container,
+  strategy,
+  signal,
+  hydrate
+}: ScheduleOptions<T>): Promise<T | undefined>;
+export { scheduleHydration as a, isIslandStrategy as i, IslandStrategy as n, ScheduleOptions as r, ISLAND_STRATEGIES as t };