@tinvar/react 0.0.0-stage → 0.4.0

package/src/layout-props.d.ts

@@ -0,0 +1,30 @@
+/** What a page root keeps of the values pages hand their layouts. */
+export interface LayoutPropsStore {
+  read(layout: string | undefined): Record<string, unknown>;
+  set(layout: string | undefined, props: Record<string, unknown>): void;
+  mark(): number;
+  dropBefore(mark: number): void;
+  subscribe(listener: () => void): () => void;
+  version(): number;
+}
+
+/** @internal The page root's store; createPageRoot() makes one for its life. */
+export declare function createLayoutPropsStore(): LayoutPropsStore;
+
+/**
+ * In a layout's client component: what the page on screen set for this
+ * layout -- by its key -- or for every layout, over `defaults`. The defaults
+ * alone outside a page root, and on the server.
+ */
+export declare function useLayoutProps<P extends Record<string, unknown>>(defaults: P, layout?: string): P;
+
+/**
+ * The setter a page's client component hands its layouts values with,
+ * kept until a whole page is shown (ADR 0092). Merged with what was set
+ * before; undefined takes a value back. Call it from an effect or an event
+ * handler, not while rendering. Does nothing outside a page root.
+ */
+export declare function useSetLayoutProps(): <P extends Record<string, unknown>>(
+  props: Partial<P>,
+  layout?: string,
+) => void;

package/src/layout-props.js

@@ -0,0 +1,143 @@
+'use client';
+
+// setLayoutProps: client-side state a page hands the layouts around it.
+//
+// tinvar-spec.md, "What not to port": "Keep typed layout props and
+// `setLayoutProps` for client-side layout state." Inertia's persistent
+// layouts are client components a page passes props to. Here a layout is a
+// server component, drawn from its own loader's data, and nothing on the
+// client can give it props (ADR 0052: the client holds no props to patch).
+// What a page can reach is the layout's client components -- a header's
+// title slot, a sidebar's open section -- so that is what this carries: a
+// page's client component sets values with the setter useSetLayoutProps()
+// hands it, and a layout's client component reads them with
+// useLayoutProps(), over defaults of its own (ADR 0092).
+//
+// The values belong to the page that set them. The page root keeps them,
+// one store for its life, and drops what was set before a whole page is
+// shown -- a visit, back or forward -- as Inertia resets layout props on
+// navigation; a partial reload keeps them. Never a module-level store: in
+// the server's render of a document, one store would be every request's,
+// and a value one visitor's page set would be read by another's layout.
+// Outside a page root -- that server render -- a setter does nothing and a
+// layout reads its defaults, which is also what the browser hydrates with.
+
+import { useCallback, useContext, useSyncExternalStore } from 'react';
+import { SegmentContext } from './segment.js';
+
+/** Every layout's values, as opposed to one layout's by its key. */
+const EVERY_LAYOUT = '';
+
+/**
+ * What the page root keeps: values by layout key, each value with the
+ * number of the change that set it.
+ *
+ * @typedef {{
+ *   read: (layout: string | undefined) => Record<string, unknown>,
+ *   set: (layout: string | undefined, props: Record<string, unknown>) => void,
+ *   mark: () => number,
+ *   dropBefore: (mark: number) => void,
+ *   subscribe: (listener: () => void) => () => void,
+ *   version: () => number,
+ * }} LayoutPropsStore
+ */
+
+/** @returns {LayoutPropsStore} */
+export function createLayoutPropsStore() {
+  /** @type {Map<string, Map<string, { value: unknown, at: number }>>} */
+  const layouts = new Map();
+  const listeners = new Set();
+  let changes = 0;
+  let version = 0;
+
+  function changed() {
+    version++;
+    for (const listener of [...listeners]) listener();
+  }
+
+  return {
+    read(layout) {
+      /** @type {Record<string, unknown>} */
+      const out = {};
+      for (const key of layout === undefined ? [EVERY_LAYOUT] : [EVERY_LAYOUT, layout]) {
+        for (const [name, { value }] of layouts.get(key) ?? []) out[name] = value;
+      }
+      return out;
+    },
+
+    set(layout, props) {
+      if (props === null || typeof props !== 'object' || Array.isArray(props)) {
+        throw new TypeError('[tinvar] setLayoutProps() takes an object of props.');
+      }
+      const key = layout ?? EVERY_LAYOUT;
+      const values = layouts.get(key) ?? new Map();
+      const at = ++changes;
+      for (const [name, value] of Object.entries(props)) {
+        // Undefined takes a value back, and the layout's default shows.
+        if (value === undefined) values.delete(name);
+        else values.set(name, { value, at });
+      }
+      layouts.set(key, values);
+      changed();
+    },
+
+    mark() {
+      return changes;
+    },
+
+    dropBefore(mark) {
+      let dropped = false;
+      for (const values of layouts.values()) {
+        for (const [name, { at }] of values) {
+          if (at <= mark) {
+            values.delete(name);
+            dropped = true;
+          }
+        }
+      }
+      if (dropped) changed();
+    },
+
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+
+    version() {
+      return version;
+    },
+  };
+}
+
+const NO_STORE = () => () => {};
+const NOTHING_SET = () => 0;
+
+/**
+ * The values the page on screen set for this layout -- or for every
+ * layout -- over `defaults`. In a layout's client component.
+ *
+ * @template {Record<string, unknown>} P
+ * @param {P} defaults
+ * @param {string} [layout] the layout's key; without one, only what was set for every layout
+ * @returns {P}
+ */
+export function useLayoutProps(defaults, layout) {
+  const store = useContext(SegmentContext)?.layoutProps ?? null;
+  useSyncExternalStore(store?.subscribe ?? NO_STORE, store?.version ?? NOTHING_SET, NOTHING_SET);
+
+  return store === null ? defaults : /** @type {P} */ ({ ...defaults, ...store.read(layout) });
+}
+
+/**
+ * The setter a page's client component hands its layouts values with:
+ * `setLayoutProps({ title })` for every layout, or `setLayoutProps({ open:
+ * 'filters' }, 'shop')` for the layout with that key. Merged with what was
+ * set before; undefined takes a value back. Kept until a whole page is
+ * shown. Call it from an effect or an event handler, not while rendering.
+ *
+ * @returns {(props: Record<string, unknown>, layout?: string) => void}
+ */
+export function useSetLayoutProps() {
+  const store = useContext(SegmentContext)?.layoutProps ?? null;
+  return useCallback((props, layout) => store?.set(layout, props), [store]);
+}

package/src/link-click.d.ts

@@ -0,0 +1,3 @@
+export declare function shouldIntercept(event: MouseEvent, anchor: HTMLAnchorElement): boolean;
+/** The URL a plain click on this link would make a client visit to, or null when the browser would handle it. */
+export declare function visitTarget(anchor: HTMLAnchorElement): URL | null;

package/src/link-click.js

@@ -0,0 +1,68 @@
+// Which clicks on a link the router takes over, and which it leaves alone.
+//
+// A link that is handled in place must still behave as a link everywhere the
+// user expects a link: a middle click, a modifier click, a "download" or a
+// target opens what it always opened. The router takes over only the plain
+// primary click that would have replaced this page with another page of
+// this application -- every other case is the browser's.
+
+/**
+ * @param {MouseEvent} event
+ * @param {HTMLAnchorElement} anchor
+ * @returns {boolean} whether the router should make this visit
+ */
+export function shouldIntercept(event, anchor) {
+  // Something else -- the app's own onClick -- has already decided.
+  if (event.defaultPrevented) return false;
+
+  // Primary button, no modifiers: anything else opens a tab, a window, a
+  // download or a context menu.
+  if (event.button !== 0) return false;
+  if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return false;
+
+  return visitTarget(anchor) !== null;
+}
+
+/**
+ * The URL a plain click on this link would make a client visit to, or null
+ * when the click would be the browser's. What a prefetch asks for too: a
+ * page fetched for a link the router would never follow is a page nobody
+ * can be shown.
+ *
+ * @param {HTMLAnchorElement} anchor
+ * @returns {URL | null}
+ */
+export function visitTarget(anchor) {
+  // Keywords match case-insensitively; " _self" with a space is a named
+  // window, as browsers treat it.
+  const target = anchor.getAttribute('target');
+  if (target && target.toLowerCase() !== '_self') return null;
+  if (anchor.hasAttribute('download')) return null;
+
+  const win = anchor.ownerDocument.defaultView;
+  if (!win) return null;
+
+  // From the attribute against the element's base URI, not `.href`: on an
+  // SVG <a> that is an SVGAnimatedString, which stringified to a junk
+  // same-origin path and passed the origin check whatever it linked to.
+  const raw = anchor.getAttribute('href');
+  if (raw === null) return null;
+
+  let url;
+  try {
+    url = new URL(raw, anchor.baseURI);
+  } catch {
+    return null;
+  }
+
+  // Another origin, or not a place at all (mailto:, tel:): an ordinary link.
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return null;
+  if (url.origin !== win.location.origin) return null;
+
+  // Only the fragment differs: the browser jumps to it within the page,
+  // and the router's popstate handling already treats that as a scroll.
+  const here = new URL(win.location.href);
+  if (url.hash && url.pathname === here.pathname && url.search === here.search) return null;
+
+  return url;
+}

package/src/link.d.ts

@@ -0,0 +1,63 @@
+import type { AnchorHTMLAttributes, ComponentType, MouseEventHandler, ReactNode } from 'react';
+import type { CacheFor, Router, VisitOptions } from './router';
+
+/** When a link prefetches: resting the pointer on it, pressing it, or as soon as it is on screen. */
+export type PrefetchMode = 'hover' | 'click' | 'mount';
+
+/** How long the pointer rests on a link before it is prefetched, in ms. */
+export declare const HOVER_DELAY_MS: number;
+
+export interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
+  href: string;
+  replace?: boolean;
+  /** Keep the window and the scroll regions where they are; a function decides once the response is in. */
+  preserveScroll?: VisitOptions['preserveScroll'];
+  /** A partial reload of the segments these dot paths name; see VisitOptions. */
+  only?: readonly string[];
+  /** A partial reload of every segment but those named. */
+  except?: readonly string[];
+  /** Keep the page's client components' state; a visit mounts the next page fresh unless told so. */
+  preserveState?: VisitOptions['preserveState'];
+  /** Mount the next page inside a view transition, where the browser has them. */
+  viewTransition?: VisitOptions['viewTransition'];
+  /**
+   * Show the layouts on screen and a layout's loading boundary while the
+   * page is fetched: the one above the page given true, or the layout with
+   * this key's (ADR 0092). See VisitOptions.
+   */
+  instant?: VisitOptions['instant'];
+  /** `true` is `'hover'`. Only links the router would follow are prefetched. */
+  prefetch?: boolean | PrefetchMode | readonly PrefetchMode[];
+  /** How long the prefetched page is used for; 30 seconds unless given. */
+  cacheFor?: CacheFor;
+  /** Tags for the prefetched page: an action invalidating one flushes it. */
+  cacheTags?: string | readonly string[];
+  /**
+   * Rendered in place of the <a>, given the href, the handlers and
+   * data-loading -- a design system's styled link. It must render an <a>
+   * that takes those props.
+   */
+  as?:
+    | 'a'
+    | ComponentType<{
+        href: string;
+        onClick?: MouseEventHandler<HTMLAnchorElement>;
+        onMouseEnter?: MouseEventHandler<HTMLAnchorElement>;
+        onMouseLeave?: MouseEventHandler<HTMLAnchorElement>;
+        onMouseDown?: MouseEventHandler<HTMLAnchorElement>;
+        'data-loading'?: string;
+        children?: ReactNode;
+      }>;
+}
+
+/** An <a href> that makes a client visit on a plain click. */
+export declare function Link(props: LinkProps): ReactNode;
+
+/** Makes a router available to every <Link> and useRouter() below it. */
+export declare function RouterProvider(props: { router: Router; children?: ReactNode }): ReactNode;
+
+/** The router from the nearest RouterProvider; throws without one. */
+export declare function useRouter(): Router;
+
+/** The router from the nearest RouterProvider, or null without one -- a server render. */
+export declare function useOptionalRouter(): Router | null;

package/src/link.js

@@ -0,0 +1,274 @@
+'use client';
+
+// <Link> and the context that gives it a router.
+//
+// tinvar-spec.md, "Client router and components": "`<Link>`: `href` takes a
+// string or a generated typed route; ... `data-loading` while in flight;
+// `replace`, `preserveState`, `preserveScroll` ... `only`, `viewTransition`."
+// This is the GET core: href, replace, preserveState, preserveScroll,
+// only and except, data-loading, prefetch and viewTransition. Pages are GET
+// only, so a link is never a <button>; typed routes build on it.
+//
+// It renders a real <a href>. Without JavaScript, or without a router above
+// it, it is an ordinary link and the server renders the next page; with one,
+// a plain click becomes a client visit. Which clicks count is link-click.js.
+//
+// `as` renders another component in place of the <a> -- a design system's
+// styled link -- with the same href, handlers and data-loading. It must
+// render an <a> that takes those props: the click rules read the element the
+// handler is on, and only an anchor has the href they resolve.
+
+import { createContext, createElement, useContext, useEffect, useRef, useState } from 'react';
+import { shouldIntercept, visitTarget } from './link-click.js';
+
+const RouterContext = createContext(null);
+
+/**
+ * How long the pointer rests on a link before it is prefetched. "`<Link
+ * prefetch>` on hover (75 ms default)": long enough that sweeping the
+ * pointer across a page of links fetches none of them.
+ */
+export const HOVER_DELAY_MS = 75;
+
+/** @typedef {'hover' | 'click' | 'mount'} PrefetchMode */
+
+const MODES = new Set(['hover', 'click', 'mount']);
+
+/**
+ * Makes a router available to every <Link> and useRouter() below it.
+ *
+ * @param {{ router: import('./router.js').Router | object, children?: unknown }} props
+ */
+export function RouterProvider({ router, children }) {
+  return createElement(RouterContext.Provider, { value: router }, children);
+}
+
+/** The router from the nearest RouterProvider. */
+export function useRouter() {
+  const router = useContext(RouterContext);
+  if (router === null) {
+    throw new Error('[tinvar:client] useRouter() needs a <RouterProvider> above it.');
+  }
+  return router;
+}
+
+/**
+ * The router from the nearest RouterProvider, or null where there is none
+ * -- a server render, or a test.
+ */
+export function useOptionalRouter() {
+  return useContext(RouterContext);
+}
+
+/**
+ * When a link prefetches: `true` is on hover; otherwise one mode or several.
+ *
+ * @param {boolean | PrefetchMode | readonly PrefetchMode[] | undefined} prefetch
+ * @returns {Set<PrefetchMode>}
+ */
+function modesOf(prefetch) {
+  if (prefetch === true) return new Set(['hover']);
+  const listed = typeof prefetch === 'string' ? [prefetch] : Array.isArray(prefetch) ? prefetch : [];
+  return new Set(listed.filter((mode) => MODES.has(mode)));
+}
+
+/**
+ * Whether a link goes to one of the application's endpoints, by the table
+ * the router was given (ADR 0074). A router without one -- or a stand-in
+ * object without the method -- knows of none.
+ *
+ * @param {unknown} router
+ * @param {HTMLAnchorElement} anchor
+ */
+function isEndpointLink(router, anchor) {
+  const check = /** @type {{ isEndpoint?: (url: URL) => boolean } | null} */ (router)?.isEndpoint;
+  if (typeof check !== 'function') return false;
+  const url = visitTarget(anchor);
+  return url !== null && check.call(router, url);
+}
+
+/**
+ * @param {{
+ *   href: string,
+ *   replace?: boolean,
+ *   preserveScroll?: import('./router.js').VisitOptions['preserveScroll'],
+ *   preserveState?: import('./router.js').VisitOptions['preserveState'],
+ *   only?: readonly string[],
+ *   except?: readonly string[],
+ *   viewTransition?: import('./router.js').VisitOptions['viewTransition'],
+ *   instant?: boolean | string,
+ *   prefetch?: boolean | PrefetchMode | readonly PrefetchMode[],
+ *   cacheFor?: import('./router.js').PrefetchOptions['cacheFor'],
+ *   cacheTags?: string | readonly string[],
+ *   as?: string | Function,
+ *   onClick?: (event: MouseEvent) => void,
+ *   onMouseEnter?: (event: MouseEvent) => void,
+ *   onMouseLeave?: (event: MouseEvent) => void,
+ *   onMouseDown?: (event: MouseEvent) => void,
+ *   children?: unknown,
+ *   [attribute: string]: unknown,
+ * }} props
+ */
+export function Link({
+  href,
+  replace,
+  preserveScroll,
+  preserveState,
+  only,
+  except,
+  viewTransition,
+  instant,
+  prefetch,
+  cacheFor,
+  cacheTags,
+  as = 'a',
+  onClick,
+  onMouseEnter,
+  onMouseLeave,
+  onMouseDown,
+  children,
+  ...attributes
+}) {
+  const router = useContext(RouterContext);
+  const [loading, setLoading] = useState(false);
+  const modes = modesOf(prefetch);
+  const canPrefetch = typeof router?.prefetch === 'function';
+
+  // The visit usually replaces the page this link is on; its promise
+  // settles after the link has gone.
+  const live = useRef(true);
+
+  // Only the latest click's visit clears data-loading: a second click
+  // supersedes the first, whose visit then settles while the second is
+  // still in flight.
+  const latest = useRef(0);
+
+  /** The pending hover prefetch, if the pointer is resting on the link. */
+  const hover = useRef(/** @type {ReturnType<typeof setTimeout> | null} */ (null));
+  const cancelHover = () => {
+    if (hover.current !== null) clearTimeout(hover.current);
+    hover.current = null;
+  };
+
+  useEffect(() => {
+    live.current = true;
+    return () => {
+      live.current = false;
+      cancelHover();
+    };
+  }, []);
+
+  // "mount": as soon as the link is on screen. Resolved the way a click
+  // would resolve it, against <base>, with the link's own target and
+  // download attributes -- a link the router would not follow is not
+  // fetched either.
+  const onMount = canPrefetch && modes.has('mount');
+  const cacheKey = JSON.stringify([cacheFor ?? null, cacheTags ?? null]);
+  const { target, download } = attributes;
+  useEffect(() => {
+    if (!onMount) return;
+    const probe = document.createElement('a');
+    probe.setAttribute('href', href);
+    if (typeof target === 'string') probe.setAttribute('target', target);
+    if (download !== undefined && download !== false) probe.setAttribute('download', '');
+    const url = visitTarget(probe);
+    if (url) prefetchUrl(url);
+    // cacheFor and cacheTags by value: a literal array is a new object on
+    // every render.
+  }, [onMount, router, href, target, download, cacheKey]);
+
+  /** @param {URL} url */
+  function prefetchUrl(url) {
+    // A prefetch is a guess. One that fails is a visit that asks the server
+    // itself, never an error to report from a hover.
+    router.prefetch(url.href, { cacheFor, cacheTags }).catch(() => {});
+  }
+
+  /** @param {HTMLAnchorElement} anchor */
+  function prefetchAnchor(anchor) {
+    const url = visitTarget(anchor);
+    if (url) prefetchUrl(url);
+  }
+
+  function handleMouseEnter(event) {
+    onMouseEnter?.(event);
+    if (!canPrefetch || !modes.has('hover')) return;
+
+    const anchor = event.currentTarget;
+    cancelHover();
+    hover.current = setTimeout(() => {
+      hover.current = null;
+      prefetchAnchor(anchor);
+    }, HOVER_DELAY_MS);
+  }
+
+  function handleMouseLeave(event) {
+    onMouseLeave?.(event);
+    cancelHover();
+  }
+
+  function handleMouseDown(event) {
+    onMouseDown?.(event);
+    if (!canPrefetch || !modes.has('click')) return;
+
+    // "click" is the press of the click that is about to follow -- so not a
+    // middle or modified press, which opens a tab the router never sees.
+    const native = event.nativeEvent ?? event;
+    if (native.button !== 0 || native.metaKey || native.ctrlKey || native.shiftKey || native.altKey) return;
+    prefetchAnchor(event.currentTarget);
+  }
+
+  function handleClick(event) {
+    // The app's own handler runs first and may claim the click.
+    onClick?.(event);
+
+    if (router === null) return;
+    if (!shouldIntercept(event.nativeEvent, event.currentTarget)) return;
+    // A link to an endpoint -- a receipt, a JSON reading -- is no page:
+    // the browser follows it, as it would with no router at all (ADR 0074).
+    if (isEndpointLink(router, event.currentTarget)) return;
+
+    // The visit is happening now; a hover prefetch due after it is not.
+    cancelHover();
+
+    event.preventDefault();
+    // The URL the browser would have gone to -- resolved against <base>, as
+    // the click rules resolved it -- not the raw prop, which the router
+    // would resolve against the address bar instead. `only` and `except`
+    // make it a partial reload; a malformed path throws here, at the link
+    // that names it, before the link shows as loading.
+    const visiting = router.visit(event.currentTarget.href, {
+      replace,
+      preserveScroll,
+      preserveState,
+      viewTransition,
+      ...(only !== undefined ? { only } : {}),
+      ...(except !== undefined ? { except } : {}),
+      ...(instant !== undefined && instant !== false ? { instant } : {}),
+    });
+    setLoading(true);
+    const click = ++latest.current;
+    visiting
+      // visit() reports failures as events and is not meant to reject; if it
+      // ever does, the link still stops loading rather than leaking an
+      // unhandled rejection.
+      .catch(() => {})
+      .finally(() => {
+        if (live.current && click === latest.current) setLoading(false);
+      });
+  }
+
+  return createElement(
+    as,
+    {
+      ...attributes,
+      href,
+      onClick: handleClick,
+      onMouseEnter: handleMouseEnter,
+      onMouseLeave: handleMouseLeave,
+      onMouseDown: handleMouseDown,
+      'data-loading': loading ? '' : undefined,
+    },
+    children,
+  );
+}

package/src/live.d.ts

@@ -0,0 +1,65 @@
+/** Live updates: the page and its <Deferred> boundaries, fetched again when what they read changes. */
+
+import type { Router } from './router.js';
+
+export declare const SUBSCRIBE_PATH: '/_live/subscribe';
+export declare const LIVE_BLOCK_ID: 'tinvar-live';
+export declare const DEBOUNCE_MS: number;
+export declare const MAX_WAIT_MS: number;
+export declare const RECONNECT_MS: number;
+export declare const MAX_RECONNECT_MS: number;
+export declare const STABLE_MS: number;
+export declare const RENEW_BEFORE_MS: number;
+export declare const MAX_TOKENS: number;
+export declare const TRADE_TIMEOUT_MS: number;
+
+/**
+ * Listens for changes to what a boundary's render read; `refresh` is called
+ * when one of its tags is invalidated. Returns the unsubscribe.
+ */
+export declare function subscribeLive(token: string | null | undefined, refresh: () => void): () => void;
+
+/**
+ * Listens to a channel with the token its subscription was answered with;
+ * `message` is called with each message, and `gap` after a gap in the
+ * stream, when messages may have been missed. `renew` asks for the
+ * subscription again when its token ran out unrenewed, answering with the
+ * new token or null. Returns the unsubscribe.
+ */
+export declare function subscribeChannel(
+  token: string | null | undefined,
+  message: (message: unknown) => void,
+  gap?: () => void,
+  renew?: () => Promise<string | null>,
+): () => void;
+
+/** The live token at the end of a document, or null. */
+export declare function readLiveToken(doc?: Document): string | null;
+
+/** The topics a live token names, each with the segments that read it ('*': the page as a whole). */
+export declare function topicsOf(token: string): Map<string, string[]>;
+
+export interface LiveOptions {
+  router: Pick<Router, 'on' | 'reload' | 'routeTokens' | 'flushByCacheTags' | 'revoke'>;
+  fetch?: typeof fetch;
+  document?: Document;
+  /** The full page load a 401 calls for. */
+  hardNavigate?: (url: string) => void;
+  now?: () => number;
+  random?: () => number;
+  /** The first page's live token; read from the document if omitted. */
+  initialToken?: string | null;
+}
+
+export interface Live {
+  start(): void;
+  stop(): void;
+  /** Drops every token held and closes the stream: client-held data. */
+  purge(): void;
+  /** Whether a stream is open on the hub. */
+  readonly connected: boolean;
+  /** The topics the open stream was granted, space-separated. */
+  readonly listening: string;
+}
+
+export declare function createLive(options: LiveOptions): Live;