@nifrajs/web 5.5.1 → 5.6.0

package/src/islands-swap.ts

@@ -0,0 +1,283 @@
+/**
+ * @nifrajs/web/islands/swap - refresh one region of a server-rendered page from a plain link or form,
+ * without a full reload and without a client router.
+ *
+ *   <form action="/hotels" data-swap="replace:results"><input name="q"></form>
+ *   <ul data-swap-slot="results">...</ul>
+ *   <a href="/hotels?page=2" data-swap="append:results">More</a>
+ *
+ * The request is the one the link or form makes anyway, plus an `x-nifra-swap: <slot>` header. The
+ * server runs the page as usual and answers with that slot's HTML alone (`slot()` in
+ * `@nifrajs/web-vanilla`), so the fragment is a slice of the real page. Any other answer - a redirect,
+ * another origin, a page without that slot - loads the URL normally. Only GET requests are enhanced:
+ * a POST form submits natively, so the browser applies its response's security policy and scripts,
+ * and the form is never sent twice.
+ */
+
+import { mountIsland } from "./internal/island-mount.ts"
+import type { IslandEnhancer } from "./islands.ts"
+import { SWAP_HEADER } from "./render-seam.ts"
+
+/** Where `enableSwap` looks for links, forms, slots and islands. */
+export interface SwapOptions {
+  /** Default `document`. */
+  readonly root?: Document | Element
+}
+
+const MODE = /^(replace|append):([A-Za-z][\w-]{0,63})$/
+const SLOTS = "[data-swap-slot]:not([data-island-ignore],[data-island-ignore] *)"
+const HISTORY_KEY = "nifraSwap"
+
+// A control named like a DOM method shadows it on its form (`<input name="closest">`).
+const attr = (el: Element, name: string): string | null =>
+  Element.prototype.getAttribute.call(el, name)
+
+const here = (): string => location.pathname + location.search
+
+/** The slot names a history entry's swaps changed, from the first one in this tab up to it. */
+const swappedIn = (state: unknown): string[] => {
+  const names: unknown =
+    typeof state === "object" && state !== null ? Reflect.get(state, HISTORY_KEY) : undefined
+  return Array.isArray(names) ? names.filter((name) => typeof name === "string") : []
+}
+
+/**
+ * Mount the page's islands, as `mountIslands` does, and make every `data-swap` link and GET form under
+ * `root` refresh its slot in place. Call it instead of `mountIslands`.
+ *
+ * - `data-swap="replace:<slot>"` replaces the content of the `data-swap-slot="<slot>"` element;
+ *   `append:<slot>` adds to it, and a link or form inside that slot is spent: the slot's child holding
+ *   it is removed when the next content arrives, so a "more" link at the end of a list gives way to
+ *   the next page and its own "more" link.
+ * - A replacing GET pushes its URL, so a filtered list survives reload and can be shared; back and
+ *   forward fetch the slots again for the URL they land on.
+ * - The islands inside a slot mount with it and unmount when it is replaced.
+ * - While a slot loads it carries `aria-busy="true"`; a newer swap of the same slot cancels the
+ *   older one. When the request fails, the page stays as it is and the link or form gets
+ *   `data-swap-error`.
+ *
+ * Nothing inside a `data-island-ignore` element swaps. Returns a disposer that removes the listeners,
+ * cancels pending swaps and unmounts every island.
+ */
+export function enableSwap(
+  // `never` admits an enhancer of any props type, as in `mountIslands`.
+  enhancers: Readonly<Record<string, IslandEnhancer<never>>>,
+  options: SwapOptions = {},
+): () => void {
+  const root: ParentNode & Node = options.root ?? document
+  const stops = new Map<Node, () => void>()
+  const pending = new Map<Element, AbortController>()
+  let swapped = swappedIn(history.state)
+  let shown = here()
+
+  const islands = "[data-island]:not([data-island-ignore],[data-island-ignore] *)"
+  const attach = (scope: ParentNode & Node): void => {
+    const mount = (el: HTMLElement): void => {
+      const stop = mountIsland(el, enhancers)
+      if (stop !== undefined) stops.set(el, stop)
+    }
+    if (scope instanceof HTMLElement && scope.matches(islands)) mount(scope)
+    for (const el of scope.querySelectorAll<HTMLElement>(islands)) if (scope.contains(el)) mount(el)
+  }
+  const release = (scope: Node): void => {
+    const cleanups: Array<() => void> = []
+    for (const [node, stop] of stops)
+      if (scope.contains(node)) {
+        stops.delete(node)
+        cleanups.push(stop)
+      }
+    // Cleanup may itself detach descendants, so collect every owner before stopping any of them.
+    for (const stop of cleanups) stop()
+  }
+  // The server answers with the first slot of a name in the page, so the client takes the first too.
+  const slotNamed = (name: string): Element | undefined => {
+    for (const slot of root.querySelectorAll(SLOTS))
+      if (slot.getAttribute("data-swap-slot") === name) return slot
+    return undefined
+  }
+
+  const put = (slot: Element, html: string, append: boolean, source: Element | undefined): void => {
+    const template = document.createElement("template")
+    // Parsed inert: scripts in it never run, as for any HTML set this way.
+    template.innerHTML = html
+    const focused = slot.contains(document.activeElement)
+    if (append) {
+      for (const child of [...slot.children])
+        if (child === source || (source !== undefined && child.contains(source))) {
+          release(child)
+          slot.removeChild(child)
+        }
+      slot.append(template.content)
+    } else {
+      release(slot)
+      slot.replaceChildren(template.content)
+    }
+    attach(slot)
+    if (focused && !slot.contains(document.activeElement) && slot instanceof HTMLElement) {
+      if (!slot.hasAttribute("tabindex")) slot.tabIndex = -1
+      slot.focus({ preventScroll: true })
+    }
+  }
+
+  const swap = async (
+    slot: Element,
+    name: string,
+    append: boolean,
+    url: URL,
+    source?: Element,
+  ): Promise<void> => {
+    pending.get(slot)?.abort()
+    const abort = new AbortController()
+    pending.set(slot, abort)
+    slot.setAttribute("aria-busy", "true")
+    try {
+      const response = await fetch(url, {
+        cache: "no-store",
+        headers: { [SWAP_HEADER]: name },
+        signal: abort.signal,
+        redirect: "manual",
+      })
+      const load = (): void => {
+        if (source === undefined) location.reload()
+        else location.assign(response.redirected ? response.url : url)
+      }
+      if (
+        response.type !== "basic" ||
+        !response.headers.get("content-type")?.startsWith("text/html")
+      ) {
+        load()
+        return
+      }
+      // A slot answer joins this document, so this document's CSP governs it, whatever headers the
+      // fetch carried; anything that is not one loads as its own document under its own policy.
+      if (response.headers.get(SWAP_HEADER) !== name) {
+        load()
+        return
+      }
+      const html = await response.text()
+      if (!slot.isConnected) return
+      try {
+        put(slot, html, append, source)
+      } catch {
+        // Trusted Types without a default policy refuses the HTML before the slot changes.
+        load()
+        return
+      }
+      if (!append && source !== undefined) {
+        if (!swapped.includes(name)) swapped = [...swapped, name]
+        history.pushState({ [HISTORY_KEY]: swapped }, "", url)
+        shown = url.pathname + url.search
+      }
+    } catch {
+      if (abort.signal.aborted) return
+      // Back or forward left the URL ahead of the page: show what the URL shows.
+      if (source === undefined) location.reload()
+      else Element.prototype.setAttribute.call(source, "data-swap-error", "")
+    } finally {
+      if (pending.get(slot) === abort) {
+        pending.delete(slot)
+        slot.removeAttribute("aria-busy")
+      }
+    }
+  }
+
+  const start = (event: Event, source: Element, url: URL): void => {
+    const mode = MODE.exec(attr(source, "data-swap") ?? "")
+    const name = mode?.[2]
+    if (
+      name === undefined ||
+      url.origin !== location.origin ||
+      Element.prototype.closest.call(source, "[data-island-ignore]") !== null
+    )
+      return
+    const slot = slotNamed(name)
+    if (slot === undefined) return
+    event.preventDefault()
+    Element.prototype.removeAttribute.call(source, "data-swap-error")
+    void swap(slot, name, mode?.[1] === "append", url, source)
+  }
+
+  const onClick = (event: Event): void => {
+    if (!(event instanceof MouseEvent) || event.defaultPrevented || event.button !== 0) return
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return
+    const link = event.target instanceof Element ? event.target.closest("a[data-swap]") : null
+    if (!(link instanceof HTMLAnchorElement) || !link.hasAttribute("href")) return
+    const target = link.getAttribute("target")
+    if ((target !== null && target !== "" && target !== "_self") || link.hasAttribute("download"))
+      return
+    const url = new URL(link.href)
+    // An in-page anchor keeps its native jump.
+    if (url.hash !== "" && url.pathname + url.search === here()) return
+    start(event, link, url)
+  }
+
+  const onSubmit = (event: Event): void => {
+    const form = event.target
+    if (
+      !(event instanceof SubmitEvent) ||
+      event.defaultPrevented ||
+      !(form instanceof HTMLFormElement) ||
+      attr(form, "data-swap") === null
+    )
+      return
+    const submitter = event.submitter
+    // The button that submitted can override the form's method, action, target and encoding.
+    const pick = (name: string): string | null =>
+      submitter?.hasAttribute(`form${name}`)
+        ? submitter.getAttribute(`form${name}`)
+        : attr(form, name)
+    // An empty method is a GET, as for the browser.
+    const method = (pick("method") || "get").toUpperCase()
+    const target = pick("target")
+    const enctype = pick("enctype")?.toLowerCase()
+    if (
+      method !== "GET" ||
+      (target !== null && target !== "" && target !== "_self") ||
+      enctype === "text/plain"
+    )
+      return
+    const action = pick("action")
+    const url = new URL(action === null || action === "" ? location.href : action, document.baseURI)
+    const data = new FormData(form, submitter)
+    const fields = new URLSearchParams()
+    for (const [key, value] of data)
+      fields.append(key, typeof value === "string" ? value : value.name)
+    url.search = fields.toString()
+    start(event, form, url)
+  }
+
+  const onPopState = (event: PopStateEvent): void => {
+    if (here() === shown) return
+    shown = here()
+    const reached = swappedIn(event.state)
+    // Every slot a swap changed between the entry left and the one reached is in the later one's list.
+    const names = new Set([...swapped, ...reached])
+    swapped = reached
+    const targets: Array<[string, Element]> = []
+    for (const name of names) {
+      const slot = slotNamed(name)
+      if (slot === undefined) {
+        location.reload()
+        return
+      }
+      targets.push([name, slot])
+    }
+    for (const [name, slot] of targets) void swap(slot, name, false, new URL(location.href))
+  }
+
+  const listen = (method: "addEventListener" | "removeEventListener"): void => {
+    root[method]("click", onClick)
+    root[method]("submit", onSubmit)
+  }
+
+  attach(root)
+  listen("addEventListener")
+  window.addEventListener("popstate", onPopState)
+  return () => {
+    listen("removeEventListener")
+    window.removeEventListener("popstate", onPopState)
+    for (const abort of pending.values()) abort.abort()
+    for (const stop of stops.values()) stop()
+    stops.clear()
+  }
+}

package/src/islands.ts

@@ -1,27 +1,52 @@
 /**
- * @nifrajs/web/islands - the framework-agnostic islands client runtime.
+ * @nifrajs/web/islands - the islands client runtime: interactivity for server-rendered pages without a
+ * framework runtime.
  *
- * An "island" is a server-rendered `<nifra-island>` element whose interactivity is mounted by a small
- * **plain-DOM** enhancer instead of a framework runtime. On a route that opts out of full-document
- * hydration (`export const hydrate = false`), the page ships **zero** framework JS; only the island
- * bundle (this runtime + your enhancers) loads. This variant ships ~99% less client JS than full
- * React hydration on a mostly-static page - the framework runtime is the cost, and islands skip it
- * entirely here.
+ * An island is a server-rendered element marked `data-island="<id>"`. Its interactivity is mounted by
+ * an enhancer instead of hydration, so on a route with `export const hydrate = false` the page ships
+ * no framework JS; only the island bundle (this runtime + your enhancers) loads via `islandScripts`.
  *
- * Server side: render the marker with `@nifrajs/web-react`'s `<Island>` (or any framework's host element
- * `<nifra-island data-id data-strategy data-props>`). Props are JSON-encoded inline in `data-props`
- * (attribute-escaped by the framework) - no central registry, so concurrent SSR renders never share
- * state. Client side: bundle one entry that calls `mountIslands({ <id>: enhancer })` and load it via
- * the route's `islandScripts`.
+ * Two tiers, one mount:
+ *   - `defineIsland((el, props) => cleanup)` - plain DOM code. The default.
+ *   - `bindIsland(({ state, onDispose }) => handlers)` - signals the markup binds by name through a
+ *     closed set of `data-bind-*` attributes. No expression language: names only.
+ * `signal`/`computed`/`effect`, a keyed `bindList` and an async `resource` work inside either tier;
+ * whatever an enhancer creates stops when its island unmounts.
+ *
+ * Server side: `<div data-island="counter" data-island-props="${islandProps({ start: 0 })}">`, or
+ * `@nifrajs/web-react`'s `<Island>`. Optional `data-island-strategy` (`load` | `idle` | `visible` |
+ * `media`, with `data-island-media`). Props travel as JSON in the attribute - no central registry, so
+ * concurrent SSR renders never share state. Nothing inside a `data-island-ignore` element mounts or
+ * binds: render user HTML there.
  */
 
-import {
+import { bindScope } from "./internal/island-bindings.ts"
+import { mountIsland } from "./internal/island-mount.ts"
+import { owned } from "./internal/island-owner.ts"
+import { type Signal, signal } from "./internal/island-signals.ts"
+import { PAGE_HIDE_EVENT, PAGE_SHOW_EVENT } from "./internal/page-events.ts"
+
+export {
   type IslandStrategy,
   MAX_MEDIA_QUERY_LENGTH,
   scheduleTrigger,
 } from "@nifrajs/island-trigger"
-
-export { type IslandStrategy, MAX_MEDIA_QUERY_LENGTH, scheduleTrigger }
+export {
+  type BindListOptions,
+  bindList,
+  type ListContainer,
+  type ListNode,
+} from "./internal/island-list.ts"
+export { type Resource, type ResourceState, resource } from "./internal/island-resource.ts"
+export {
+  batch,
+  type Computed,
+  computed,
+  effect,
+  type Signal,
+  signal,
+  untrack,
+} from "./internal/island-signals.ts"
 
 /** Optional teardown an enhancer returns (remove listeners/observers); run on `dispose()`. */
 export type IslandCleanup = () => void
@@ -36,7 +61,7 @@ export type IslandEnhancer<P = unknown> = (el: HTMLElement, props: P) => IslandC
 
 /**
  * Author a typed enhancer. Pure identity at runtime (zero cost, tree-shaken away) - its only job is
- * to pin the `data-props` shape so `el` and `props` are typed inside the body and the enhancer is
+ * to pin the props shape so `el` and `props` are typed inside the body and the enhancer is
  * assignable to `mountIslands`. Prefer this over an inline arrow whenever an island reads props:
  *
  *   const counter = defineIsland<{ start: number }>((el, props) => {
@@ -48,78 +73,150 @@ export type IslandEnhancer<P = unknown> = (el: HTMLElement, props: P) => IslandC
  *   })
  *   mountIslands({ counter })
  *
- * The props type is a contract, not a validator - `data-props` is JSON authored by your own SSR, so
- * it is trusted framing, not user input. Keep the enhancer body imperative: read the DOM, wire
- * listeners, return cleanup. No hidden reactivity to get wrong.
+ * The props type is a contract, not a validator - `data-island-props` is JSON authored by your own
+ * SSR, so it is trusted framing, not user input. Keep the enhancer body imperative: read the DOM,
+ * wire listeners, return cleanup.
  */
 export function defineIsland<P = unknown>(enhancer: IslandEnhancer<P>): IslandEnhancer<P> {
   return enhancer
 }
 
-/** Parse an island's inline `data-props` JSON; malformed/absent → `undefined` (never throws). */
-function readProps(el: HTMLElement): unknown {
-  const raw = el.dataset.props
-  if (raw === undefined || raw === "") return undefined
-  try {
-    return JSON.parse(raw)
-  } catch {
-    return undefined
+const onPage = (type: string, el: Element, callback: () => void): (() => void) => {
+  if (typeof document === "undefined") return () => {}
+  const listener = (event: Event): void => {
+    if (event.target instanceof Node && event.target.contains(el)) callback()
+  }
+  document.addEventListener(type, listener)
+  return () => document.removeEventListener(type, listener)
+}
+
+/**
+ * Run `callback` each time the `keepAlive` page `el` renders in is hidden behind another page, just
+ * before it leaves the document. An island in a kept page stays mounted, and its timers and window
+ * listeners keep running, while the page is hidden: pause them here. Returns its removal - hand it back
+ * as part of the enhancer's cleanup. Never runs outside a kept page.
+ *
+ *   const clock = defineIsland((el) => {
+ *     let timer = setInterval(tick, 1000)
+ *     const hide = onPageHide(el, () => clearInterval(timer))
+ *     const show = onPageShow(el, () => { timer = setInterval(tick, 1000) })
+ *     return () => { hide(); show(); clearInterval(timer) }
+ *   })
+ */
+export function onPageHide(el: Element, callback: () => void): () => void {
+  return onPage(PAGE_HIDE_EVENT, el, callback)
+}
+
+/** Run `callback` each time the `keepAlive` page `el` renders in is shown again; returns its removal. */
+export function onPageShow(el: Element, callback: () => void): () => void {
+  return onPage(PAGE_SHOW_EVENT, el, callback)
+}
+
+/** What a `bindIsland` setup receives. */
+export interface BindIslandContext<P> {
+  /** The island's host element. */
+  readonly root: HTMLElement
+  /** The parsed `data-island-props`, or `undefined` when absent or malformed. */
+  readonly props: P | undefined
+  /**
+   * The signal the markup binds as `key`, seeded from `props[key]` when present, else `fallback`.
+   * Each key returns the same signal across calls.
+   */
+  state<T>(key: string, fallback: T): Signal<T>
+  /**
+   * Run `fn` when the island unmounts - for timers, requests and listeners the setup starts. Called
+   * after the island unmounted (say, once an awaited request settles), it runs `fn` at once.
+   */
+  onDispose(fn: () => void): void
+}
+
+/**
+ * The binding tier: `setup` creates the island's state and returns the event handlers its markup
+ * names; the island's `data-bind-*` attributes then bind them.
+ *
+ *   data-bind-text="count"   data-bind-show="open"   data-bind-class="active:open"
+ *   data-bind-attr="aria-expanded:open"   data-bind-value="query"   data-bind-on="click:add"
+ *
+ * Attribute values are signal and handler names, never code; an unknown name warns once and the
+ * server-rendered content stays as it is. A binding belongs to its nearest island.
+ *
+ * A setup or binding that throws stops everything the island started before the error reaches
+ * `mountIslands`. On unmount every cleanup runs; one that throws is logged and the rest still run.
+ */
+export function bindIsland<P = Record<string, unknown>>(
+  setup: (ctx: BindIslandContext<P>) => Record<string, (event: Event) => void> | void,
+): IslandEnhancer<P> {
+  return (root, props) => {
+    const stops: Array<() => void> = []
+    let live = true
+    const seeded: Record<string, unknown> = typeof props === "object" && props !== null ? props : {}
+    // No prototype: a state key like `constructor` is an entry like any other.
+    const signals: Record<string, Signal<unknown>> = Object.create(null)
+    const ctx: BindIslandContext<P> = {
+      root,
+      props,
+      state<T>(key: string, fallback: T): Signal<T> {
+        signals[key] ??= signal(Object.hasOwn(seeded, key) ? seeded[key] : fallback)
+        // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: each key's signal is created once, from this call's type
+        return signals[key] as Signal<T>
+      },
+      onDispose: (fn) => {
+        if (live) stops.push(fn)
+        else fn()
+      },
+    }
+    const dispose = (): void => {
+      live = false
+      for (let stop = stops.pop(); stop !== undefined; stop = stops.pop()) {
+        try {
+          stop()
+        } catch (err) {
+          console.error("[nifra/islands] cleanup failed:", err)
+        }
+      }
+    }
+    try {
+      // Owned, so a binding whose first run throws is registered before it throws.
+      owned(stops, () => bindScope(root, { signals, handlers: setup(ctx) ?? {} }, stops))
+    } catch (err) {
+      dispose()
+      throw err
+    }
+    return dispose
   }
 }
 
 /**
- * Find every `<nifra-island data-id>` under `root` (default `document`) and enhance each with the
- * matching enhancer, honoring its `data-strategy`. An island whose `id` has no enhancer is left as
- * inert SSR HTML (forward-compatible). An enhancer that throws is isolated - it never blocks the
- * others (each island is independent). Returns a disposer that cancels pending triggers and runs every
- * enhancer's cleanup (call it on soft-nav teardown; harmless if your app never navigates).
+ * The `data-island-props` value for `props`: JSON. Emit it through an escaping renderer into a quoted
+ * attribute (`data-island-props="${...}"`): unquoted, a space in the JSON ends the value and the rest
+ * parses as attributes.
+ */
+export function islandProps(props: Record<string, unknown>): string {
+  return JSON.stringify(props)
+}
+
+/**
+ * Find every `[data-island]` element under `root` (default `document`) and enhance each with the
+ * matching enhancer, honoring its `data-island-strategy`. An island whose id has no enhancer, or that
+ * is already mounted, is left alone, so calling again after a soft navigation mounts only new hosts.
+ * An enhancer that throws is isolated - it never blocks the others. Every effect, list binding and
+ * resource an enhancer creates is owned by its island. Returns a disposer that cancels pending
+ * triggers and tears down every island it mounted (call it on soft-nav teardown).
  */
 export function mountIslands(
-  enhancers: Readonly<Record<string, IslandEnhancer>>,
+  // `never` admits an enhancer of any props type: each one's props are its own island's JSON.
+  enhancers: Readonly<Record<string, IslandEnhancer<never>>>,
   options: { readonly root?: ParentNode } = {},
 ): () => void {
-  const root = options.root ?? document
   const disposers: Array<() => void> = []
-  for (const el of root.querySelectorAll<HTMLElement>("nifra-island[data-id]")) {
-    const id = el.dataset.id
-    if (id === undefined) continue
-    const enhancer = enhancers[id]
-    if (enhancer === undefined) continue // no enhancer for this id → leave it as inert SSR markup
-    const props = readProps(el)
-    const strategyAttr = el.dataset.strategy
-    const strategy: IslandStrategy | undefined =
-      strategyAttr === "idle" || strategyAttr === "visible" || strategyAttr === "load"
-        ? strategyAttr
-        : strategyAttr === "media" &&
-            el.dataset.media !== undefined &&
-            el.dataset.media.length > 0 &&
-            el.dataset.media.length <= MAX_MEDIA_QUERY_LENGTH
-          ? { media: el.dataset.media }
-          : strategyAttr === undefined
-            ? "load"
-            : undefined
-    // Invalid media markers remain inert rather than silently becoming eager. Their SSR content stays
-    // usable, and untrusted HTML cannot turn an oversized query into an unexpected trigger.
-    if (strategy === undefined) continue
-    const run = (): void => {
-      try {
-        const cleanup = enhancer(el, props)
-        if (typeof cleanup === "function") disposers.push(cleanup)
-      } catch (err) {
-        // One island's failure must not take down the others; surface it without throwing.
-        console.error(`[nifra/islands] enhancer "${id}" failed:`, err)
-      }
-    }
-    disposers.push(scheduleTrigger(strategy, run, { target: el }))
+  for (const el of (options.root ?? document).querySelectorAll<HTMLElement>(
+    "[data-island]:not([data-island-ignore],[data-island-ignore] *)",
+  )) {
+    const dispose = mountIsland(el, enhancers)
+    if (dispose !== undefined) disposers.push(dispose)
   }
   return () => {
-    for (const dispose of disposers) {
-      try {
-        dispose()
-      } catch {
-        // best-effort teardown - a failing cleanup must not block the rest
-      }
-    }
+    for (const dispose of disposers.splice(0)) dispose()
   }
 }