pageturn 0.1.1 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # pageturn
 
+## 1.0.0
+
+### Major Changes
+
+- f3ef048: pageturn 1.0: the public API is stable. What a site imports, the marks on `<html>` and
+  their custom properties, the events, and the behaviour written in `docs/contract.md` now
+  follow semantic versioning: a minor or patch release never breaks them. Nothing changes
+  from 0.2.0 in what pageturn does.
+
+## 0.2.0
+
+### Minor Changes
+
+- f03333d: Warnings in development: in the build package.json's `development` condition serves,
+  pageturn says in the console why a move did not play (no head script, reduced motion, a
+  client router with no adapter, a return by Back with no animation, a router's own view
+  transition alongside pageturn's). Production builds carry none of it.
+- f03333d: Next.js: `pageturn/next` plays pageturn's moves on the App Router. Its `Link` (as
+  `next/link`) and `usePageturnRouter()` (as `useRouter()`) play the leave before the router
+  navigates, and `<Pageturn />` in the root layout says when each page is in the DOM. On
+  any client router, the page reached is now recorded where the router shows it, base path
+  and trailing slash included, so a return by Back finds its `returnAs` there too.
+- f03333d: Nuxt: the `pageturn/nuxt` module puts the head script in every page, adds the stylesheet,
+  and plays pageturn's moves on Nuxt's navigations (`<NuxtLink>`, `navigateTo()`, Back and
+  Forward), the page reached arriving once Nuxt's `<Suspense>` has resolved.
+- 3b16406: Only `decline()` declines: a move's `leave` or a morph's `ends` that answers `false`, the
+  form from before `decline()`, now declines nothing (the types already refused it). Return
+  `turn.decline()` or `decline()` instead.
+- f03333d: React Router: `pageturnMiddleware` on the root route and `usePageturn()` in the root
+  layout play pageturn's moves on React Router's navigations (`<Link>`, `navigate()`, Back
+  and Forward), the route's loaders running during the leave. `react` and `react-router`
+  are optional peer dependencies, used by this adapter only.
+- f03333d: SvelteKit: `pageturn/sveltekit` plays pageturn's moves on SvelteKit's own navigations
+  (links, `goto()`, Back and Forward), and `pageturn/sveltekit/server` puts the head script
+  in every page. Every module of pageturn can now be imported on a server, where it does
+  nothing: a framework's layouts run there too.
+- f03333d: Turbo: `pageturn/turbo` plays pageturn's moves on Turbo Drive's visits (links, forms,
+  `Turbo.visit()`, Back and Forward), holding Turbo's render until the leave has ended. On
+  a page Turbo has cached, the preview is not shown under the leave.
+- f03333d: Vue Router: `pageturn/vue` plays pageturn's moves on the router's navigations
+  (`<RouterLink>`, `router.push()`, Back and Forward). On any client router, a navigation
+  to a place in the same page plays no move, and one started from code plays the default
+  move rather than asking each move's `match`.
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -30,7 +30,8 @@ goes wrong, you get an ordinary page load.
   classic script 4.2 kB. Nothing moves under `prefers-reduced-motion`, and no other host
   is contacted.
 
-> **Status:** not published yet. What pageturn does in every situation is in
+> **Status:** stable. The public API follows semantic versioning: a minor or patch
+> release never breaks it. What pageturn does in every situation is in
 > [docs/contract.md](docs/contract.md).
 
 ## Contents
@@ -89,6 +90,153 @@ first in every page's `<head>`, so your own inline scripts can read
 The integration ships only what these options use. Your own scripts import from
 `pageturn/core` (see [Entries](#entries)).
 
+### SvelteKit
+
+```js
+// src/hooks.server.js: the head script first in every page
+import { pageturnHandle } from "pageturn/sveltekit/server";
+export const handle = pageturnHandle();
+```
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script>
+  import "pageturn/pageturn.css";
+  import { beforeNavigate, onNavigate } from "$app/navigation";
+  import { pageturn } from "pageturn/sveltekit";
+
+  pageturn({ beforeNavigate, onNavigate });
+</script>
+```
+
+SvelteKit's own navigations then play the same moves: links, `goto()`, Back and Forward.
+The leave plays while SvelteKit loads the next page's data, and SvelteKit waits for it
+before it updates the page. A link SvelteKit leaves to the browser
+(`data-sveltekit-reload`) is a real navigation, and plays its move too. With
+`pageturn/no-native.css` or your own CSS, `pageturnHandle({ native: false })`. Under a
+Content-Security-Policy, add `headScriptHash` from `pageturn/head` to `kit.csp`. Turn off
+any SvelteKit view-transition recipe: two systems animating one swap is the likeliest
+bug.
+
+### Rails, with Turbo
+
+```html
+<!-- In the layout's <head>: the head script, then the stylesheet -->
+<script src="/pageturn/head.js"></script>
+<link rel="stylesheet" href="/pageturn/pageturn.css">
+```
+
+```js
+// app/javascript/application.js
+import "@hotwired/turbo-rails";
+import "pageturn/turbo";
+```
+
+Turbo Drive's visits then play the same moves: links, forms, `Turbo.visit()`, Back and
+Forward. The leave plays while Turbo fetches the page, and Turbo holds its render until
+it has ended. On a page Turbo has cached, its preview is not shown under the leave: the
+page arrives once, from its real render. A link Turbo leaves to the browser
+(`data-turbo="false"`) is a real navigation, with its move. Copy `head.js` and the
+stylesheet from `node_modules/pageturn/dist/` (or inline `headScript` from
+`pageturn/head`), and remove Turbo's `view-transition` meta tag where pageturn plays.
+
+### Vue Router
+
+```js
+// main.js, before the app mounts
+import "pageturn/pageturn.css";
+import { pageturn } from "pageturn/vue";
+pageturn(router);
+```
+
+```html
+<!-- index.html, first in <head> -->
+<script src="/pageturn/head.js"></script>
+```
+
+The router's navigations then play the same moves: `<RouterLink>`, `router.push()`,
+Back and Forward. The leave starts with the navigation, and the router waits for it once
+the route's components have loaded. A navigation a guard aborts puts the page back. A
+`#place` in the same route plays no move. With Nuxt, use [`pageturn/nuxt`](#nuxt) rather
+than calling this yourself.
+
+### Nuxt
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["pageturn/nuxt"], // or [["pageturn/nuxt", { css: "no-native" }]]
+});
+```
+
+The module puts the head script first in every page, adds the stylesheet (`css`:
+`true`, `"no-native"` or `false`), and plays the same moves on Nuxt's navigations:
+`<NuxtLink>`, `navigateTo()`, Back and Forward. The page reached arrives once Nuxt's
+`<Suspense>` has resolved (`page:finish`). Turn off `experimental.viewTransition` and any
+`pageTransition` where pageturn plays.
+
+### React Router
+
+```jsx
+import { pageturnMiddleware, usePageturn } from "pageturn/react-router";
+
+const router = createBrowserRouter([
+  { path: "/", Component: Root, middleware: [pageturnMiddleware], children },
+]);
+
+function Root() {
+  usePageturn();
+  return <Outlet />;
+}
+```
+
+With the stylesheet imported once and the head script first in the document's `<head>`.
+React Router 7.9 or later, with data routers (`createBrowserRouter`) or framework mode.
+The middleware starts the leave as the navigation does, runs the route's loaders
+meanwhile, and lets the router commit when both are done; the hook says when the route
+reached is in the DOM. `<Link>`, `navigate()`, Back and Forward play the same moves. A
+`<Link reloadDocument>` is a real navigation, with its move. Leave out React Router's
+`viewTransition` where pageturn plays.
+
+### Next.js (App Router)
+
+```jsx
+// app/layout.jsx
+import { coreHeadScript } from "pageturn/head";
+import { Pageturn } from "pageturn/next";
+import "pageturn/no-native.css";
+
+export default function Layout({ children }) {
+  return (
+    <html>
+      <head>
+        <script dangerouslySetInnerHTML={{ __html: coreHeadScript }} />
+      </head>
+      <body>
+        <Pageturn />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+```jsx
+import { Link, usePageturnRouter } from "pageturn/next";
+
+<Link href="/work">Work</Link>;              // as next/link
+const router = usePageturnRouter();               // as useRouter()
+router.push("/work");
+```
+
+Next's router cannot wait for a leave, so pageturn's `Link` stops its navigation, plays
+the leave while the page is prefetched, then asks the router again; `usePageturnRouter()`
+does the same from code. `<Pageturn />` says when each page is in the DOM. Back and
+Forward, a plain `next/link` and a bare `router.push` still work: the page arrives (under
+its `returnAs` on Back), with no leave. Put the head script in a plain inline `<script>`:
+`next/script`'s `beforeInteractive` runs it too late, from Next's own code. Next.js 16 or
+later; leave out its experimental view transitions where pageturn plays.
+
 ### Plain HTML, any server
 
 ```html
@@ -682,6 +830,13 @@ scroll layer to stop):
 | `pageturn/morph` | One element from a page to the next. See [docs/morph.md](docs/morph.md) |
 | `pageturn/morph/markup` | The morph from `data-turn-morph`. Imported for its effect |
 | `pageturn/router` | The engine for client routers' navigations, which adapters drive. See [docs/router.md](docs/router.md) |
+| `pageturn/sveltekit` | The SvelteKit adapter: `pageturn({ beforeNavigate, onNavigate })`, with the kernel |
+| `pageturn/sveltekit/server` | `pageturnHandle()`: the head script in every page SvelteKit renders |
+| `pageturn/turbo` | The Turbo Drive adapter, with the kernel. Imported for its effect |
+| `pageturn/vue` | The Vue Router adapter: `pageturn(router)`, with the kernel |
+| `pageturn/nuxt` | The Nuxt module: the head script, the stylesheet, and the Vue Router adapter on Nuxt's router |
+| `pageturn/react-router` | The React Router adapter: `pageturnMiddleware` and `usePageturn()`, with the kernel |
+| `pageturn/next` | The Next.js App Router adapter: `Link`, `usePageturnRouter()` and `<Pageturn />`, with the kernel |
 | `pageturn/testing` | For browser tests of a morph: the layer's parts by name, a travel held at a time or at its end |
 | `pageturn/astro` | The Astro integration |
 
@@ -691,6 +846,21 @@ And the files of `dist/` for a page with no bundler: `pageturn.css` or `no-nativ
 A site that turns prefetch off and writes its own moves imports `pageturn/core` only. The
 kernel needs the head script: without it, it does nothing, and links navigate normally.
 
+### Warnings in development
+
+While you develop, pageturn says in the console why a move did not play, once each:
+
+- the head script is missing from the page;
+- `prefers-reduced-motion` is on, so nothing plays;
+- a client router took a link and no adapter tells pageturn about it;
+- a page returned to by Back under its `returnAs` has no animation of its own, so it
+  shows at once (Back cannot play a leave, which reads as a flash);
+- a router plays its own view transition while pageturn plays a move.
+
+They come from the build package.json's `development` condition serves, which Vite,
+webpack and the frameworks on them pick while developing. A production build, and the
+files of `dist/` loaded as they are, carry none of it.
+
 ### Content-Security-Policy
 
 - `script-src 'self'`: load `pageturn.js` as a file, or use `head: "external"` in Astro.
@@ -724,10 +894,11 @@ checked by hand before each release ([docs/release-checklist.md](docs/release-ch
 
 ## Questions
 
-**Does it work with Next.js, Nuxt, SvelteKit?** Not yet on the links their router
-handles: those do not load a page. `pageturn/router` is the engine for them, with the
-same moves and CSS; the adapters that connect each router are not written yet
-([docs/router.md](docs/router.md)).
+**Does it work with Next.js, Nuxt, SvelteKit?** Yes, with an adapter for each:
+[SvelteKit](#sveltekit), [Turbo](#rails-with-turbo), [Vue Router](#vue-router),
+[Nuxt](#nuxt), [React Router](#react-router) and [Next.js](#nextjs-app-router), all on
+`pageturn/router` ([docs/router.md](docs/router.md)). pageturn can be imported where a
+framework renders on the server: it does nothing there.
 
 **What if JavaScript fails, or the next page is slow?** The click is a real navigation.
 A leave that throws or takes too long navigates anyway. A page that does not come in

package/dist/astro.js

@@ -109,7 +109,5 @@ function pageturn(options = {}) {
   };
 }
 export {
-  HEAD_SCRIPT_PATH,
-  MORPH_HEAD_SCRIPT_PATH,
   pageturn as default
 };

package/dist/chunks/chunk-3ABPYO7H.js

@@ -0,0 +1,43 @@
+import {
+  startNavigation
+} from "./chunk-BOM5VXA5.js";
+import {
+  inBrowser
+} from "./chunk-AEOAXMU3.js";
+
+// src/vue/vue.ts
+function pageturn(router, options = {}) {
+  if (!inBrowser) return () => {
+  };
+  let current = null, popped = !1, cancel = () => {
+    current?.cancelled(), current = null;
+  }, stops = [
+    // Back and Forward: the router's history says so before its guards run.
+    router.options.history.listen((_to, _from, info) => {
+      popped = info.type === "pop";
+    }),
+    router.beforeEach((to, from) => {
+      let via = popped ? "history" : "link";
+      popped = !1, from.matched.length !== 0 && (current = startNavigation({ to: router.resolve(to).href, via }));
+    }),
+    router.beforeResolve(() => current?.left),
+    router.afterEach((_to, _from, failure) => {
+      let turn = current;
+      if (current = null, !turn) return;
+      if (failure) {
+        turn.cancelled();
+        return;
+      }
+      let swap = () => turn.swapped();
+      options.whenShown ? options.whenShown(swap) : queueMicrotask(swap);
+    }),
+    router.onError(cancel)
+  ];
+  return () => {
+    for (let stop of stops) stop();
+  };
+}
+
+export {
+  pageturn
+};

package/dist/chunks/chunk-6FXXBNAF.js

@@ -0,0 +1,197 @@
+import {
+  STORE_VERSION,
+  choose,
+  followArrival,
+  leave,
+  stopFollowing,
+  tellArrival,
+  turnOf
+} from "./chunk-JHM7F4CH.js";
+import {
+  inBrowser,
+  reducesMotion
+} from "./chunk-AEOAXMU3.js";
+import {
+  registry
+} from "./chunk-YAL4MNCU.js";
+
+// src/kernel/kernel.ts
+var store, current = null, stuckTimer;
+function install() {
+  if (!inBrowser) return;
+  let published = window.pageturn?.j;
+  registry.g || published?.m !== STORE_VERSION || (store = published, registry.g = !0, addEventListener("click", putClickLast, !0), addEventListener("pointerdown", pressed, !0), addEventListener("pagehide", pageHidden, !0), addEventListener("pageshow", pageShown), followArrival());
+}
+function putClickLast() {
+  removeEventListener("click", clicked), addEventListener("click", clicked);
+}
+function linkIn(event) {
+  for (let target of event.composedPath()) {
+    if (target instanceof HTMLAnchorElement)
+      return target.hasAttribute("href") ? target : null;
+    if (target instanceof SVGAElement) return null;
+  }
+  return null;
+}
+function isEditable(event) {
+  let [target] = event.composedPath();
+  return target instanceof HTMLElement && target.isContentEditable;
+}
+function destinationOf(link) {
+  let target = link.target || document.querySelector("base[target]")?.getAttribute("target");
+  if (target && target !== "_self" || link.hasAttribute("download"))
+    return null;
+  let to = new URL(link.href), isThisPage = to.pathname === location.pathname && to.search === location.search;
+  return to.origin === location.origin && !isThisPage ? to : null;
+}
+function prefetch(to) {
+  registry.settings.prefetch && registry.u?.(to);
+}
+function pressed(event) {
+  if (event.button !== 0 || isEditable(event)) return;
+  let link = linkIn(event), to = link && destinationOf(link);
+  to && prefetch(to);
+}
+function clicked(event) {
+  if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey || isEditable(event))
+    return;
+  let link = linkIn(event), to = link && destinationOf(link);
+  if (!link || !to) return;
+  if (current) {
+    event.preventDefault();
+    return;
+  }
+  if (store.n(), event.detail === 0 && prefetch(to), reducesMotion()) return;
+  let { a: native } = registry, visit = {
+    link,
+    via: "link",
+    from: new URL(location.href),
+    to,
+    canHandOver: store.q()
+  }, name = choose(visit);
+  if (name === null) {
+    native?.c(null);
+    return;
+  }
+  let turn = turnOf(visit, name);
+  if (!document.dispatchEvent(
+    new CustomEvent("pageturn:leaving", { cancelable: !0, detail: turn })
+  )) {
+    native?.c(null);
+    return;
+  }
+  if (name === registry.settings.defaultMove && !registry.b.get(name)?.leave && native?.v(name, to))
+    return;
+  event.preventDefault();
+  let playing = { turn };
+  current = playing, leave(turn, (played) => {
+    playing.turn = played;
+  }).then((handover) => depart(playing, handover));
+}
+function depart(playing, handover) {
+  if (current !== playing || playing.handover !== void 0) return;
+  let { turn } = playing;
+  playing.handover = handover, handover && handover.arriveAs !== null && store.h(
+    {
+      move: handover.arriveAs ?? turn.move,
+      data: handover.data ?? null,
+      from: location.pathname,
+      at: Date.now()
+    },
+    turn.to
+  ), playing.entry = handover?.returnAs ? {
+    move: turn.move,
+    to: turn.to.pathname,
+    returnAs: handover.returnAs,
+    remember: handover.remember ?? null
+  } : null, store.i(playing.entry), registry.a?.c(null), location.assign(turn.to.href), stuckTimer = setTimeout(
+    () => endWithoutDeparture(playing, "stuck"),
+    registry.settings.stuckTimeout
+  );
+}
+function endWithoutDeparture(playing, reason) {
+  if (current !== playing) return;
+  current = null, clearTimeout(stuckTimer), registry.a?.c(void 0), delete document.documentElement.dataset.turnLeaving;
+  let stay = { reason, handover: playing.handover ?? null };
+  try {
+    registry.b.get(playing.turn.move)?.stay?.(playing.turn, stay);
+  } catch (error) {
+    reportError(error);
+  }
+  document.dispatchEvent(
+    new CustomEvent("pageturn:stayed", {
+      detail: { turn: playing.turn, stay }
+    })
+  );
+}
+function pageHidden() {
+  clearTimeout(stuckTimer), stopFollowing();
+  let { e: report } = registry;
+  if (!report && !window.pageturn?.arrival) return;
+  let data = null;
+  try {
+    data = report?.({ decline: () => registry.f }) ?? null;
+  } catch (error) {
+    reportError(error);
+  }
+  let isNone = data === registry.f;
+  store.p({
+    from: location.pathname,
+    at: Date.now(),
+    data: isNone ? null : data,
+    ...isNone ? { none: !0 } : {}
+  });
+}
+function pageShown(event) {
+  if (!event.persisted) return;
+  registry.a?.c(void 0);
+  let playing = current, published = window.pageturn;
+  if (!published) return;
+  let entry = playing ? playing.entry ?? null : store.r(), arrival2 = store.s(entry, store.o());
+  published.arrival = arrival2, arrival2 && (published.t?.(arrival2), published.k?.skipTransition(), followArrival()), playing && endWithoutDeparture(playing, "returned"), arrival2 && tellArrival(arrival2);
+}
+
+// src/kernel/core.ts
+function defineMove(name, move) {
+  let stored = move;
+  registry.b.set(name, stored);
+  let reached = inBrowser ? window.pageturn?.arrival : null;
+  return reached?.move === name && stored.arrive && queueMicrotask(() => {
+    registry.b.get(name) === stored && tellArrival(reached);
+  }), () => {
+    registry.b.get(name) === stored && registry.b.delete(name);
+  };
+}
+function chooseMove(chooser) {
+  let stored = chooser;
+  return registry.d.push(stored), () => {
+    let index = registry.d.indexOf(stored);
+    index >= 0 && registry.d.splice(index, 1);
+  };
+}
+function arrival() {
+  return inBrowser && window.pageturn?.arrival || null;
+}
+function endArrival(move) {
+  inBrowser && window.pageturn?.endArrival(move);
+}
+function whenLeft(report) {
+  let stored = report;
+  return registry.e = stored, () => {
+    registry.e === stored && (registry.e = null);
+  };
+}
+function configure(settings) {
+  for (let [key, value] of Object.entries(settings))
+    value !== void 0 && Object.assign(registry.settings, { [key]: value });
+}
+install();
+
+export {
+  defineMove,
+  chooseMove,
+  arrival,
+  endArrival,
+  whenLeft,
+  configure
+};

package/dist/chunks/chunk-AEOAXMU3.js

@@ -0,0 +1,33 @@
+// src/common/page.ts
+var inBrowser = typeof document < "u", navigationEntry = () => performance.getEntriesByType("navigation")[0];
+function afterDomContentLoaded(run) {
+  let entry = navigationEntry();
+  (entry ? entry.domContentLoadedEventStart > 0 : document.readyState !== "loading") ? run() : document.addEventListener("DOMContentLoaded", run, { once: !0 });
+}
+var reduced;
+function reducesMotion() {
+  return reduced ??= matchMedia("(prefers-reduced-motion: reduce)"), reduced.matches;
+}
+function notShownAnew() {
+  window.pageturn && (window.pageturn.l = !0), delete document.documentElement.dataset.turnEntering;
+}
+var FOCUS_BACK = /* @__PURE__ */ Symbol.for("pageturn.focusBack"), shared = globalThis;
+function giveFocusTo(element, options) {
+  shared[FOCUS_BACK] = element;
+  try {
+    element.focus(options);
+  } finally {
+    delete shared[FOCUS_BACK];
+  }
+}
+var isFocusGivenBack = (element) => shared[FOCUS_BACK] === element;
+
+export {
+  inBrowser,
+  navigationEntry,
+  afterDomContentLoaded,
+  reducesMotion,
+  notShownAnew,
+  giveFocusTo,
+  isFocusGivenBack
+};