@tinvar/react 0.0.0-stage → 0.4.1

package/src/router.d.ts

@@ -0,0 +1,586 @@
+/** The client router: navigation, history, scroll and the wire protocol. */
+
+export declare const RSC_CONTENT_TYPE: 'text/x-component';
+export declare const ROUTE_TOKEN_HEADER: 'x-route-token';
+/** The page's live token on a payload; handed on in the `success` event's `liveToken`. */
+export declare const LIVE_TOKEN_HEADER: 'x-live-token';
+/** The `Purpose` a prefetch request is sent with. */
+export declare const PREFETCH_PURPOSE: 'prefetch';
+/** Marks a background request -- a poll -- so the server records no visit for it. */
+export declare const BACKGROUND_HEADER: 'x-background';
+/** Where an action's response lists the cache tags it invalidated. */
+export declare const INVALIDATED_TAGS_HEADER: 'x-invalidated-tags';
+/** Where a page's payload carries its history key, when its history is encrypted (ADR 0019). */
+export declare const HISTORY_KEY_HEADER: 'x-history-key';
+
+/** The tags an action's response names in `X-Invalidated-Tags`. */
+export declare function invalidatedTags(
+  source: Response | Headers | { headers?: Headers } | string | null | undefined,
+): string[];
+
+/**
+ * Flushes, from every router on the page, the prefetched pages an action's
+ * response says it invalidated. Hand every action response here once; no
+ * form needs to name a tag. Returns the tags it named.
+ */
+export declare function flushInvalidated(
+  source: Response | Headers | { headers?: Headers } | string | null | undefined,
+): string[];
+/**
+ * Ends the session on this client, for whatever heard a 401: the router given,
+ * or every router that is up, revokes what it holds, and the tab's
+ * remembered state is wiped either way. The caller makes the full page load.
+ */
+export declare function revokeSession(router?: { revoke(): void } | null): void;
+/**
+ * What logging out calls: clears the history of the router given, or of
+ * every router that is up -- everything remembered, for every entry of the
+ * tab, and the history key -- and wipes the tab's remembered state either
+ * way. The key itself rotates with the session's id (ADR 0019).
+ */
+export declare function clearHistory(router?: { clearHistory(): void } | null): void;
+/** How many X-Redirects one visit will follow before loading the document. */
+export declare const MAX_REDIRECTS: number;
+/** How long restoring a scroll position keeps trying while the page is too short to reach it, in ms. */
+export declare const SCROLL_RESTORE_MS: number;
+/**
+ * The attribute that marks an inner scroller whose position is kept with
+ * the window's: saved per history entry, put back on back and forward, reset
+ * on a visit unless `preserveScroll`. Regions are matched by document order.
+ */
+export declare const SCROLL_REGION_ATTRIBUTE: 'scroll-region';
+
+export declare class VisitCancelled extends Error {}
+
+/** A visit's `onError`, told the server answered a status that is not a page. */
+export declare class VisitHttpError extends Error {
+  readonly url: string;
+  readonly status: number;
+}
+
+/** A visit's `onError`, told no answer came; `cause` is what the fetch threw. */
+export declare class VisitNetworkError extends Error {
+  readonly url: string;
+}
+
+export interface VisitOptions {
+  method?: 'get';
+  /**
+   * The query: merged into the URL's query string, as Inertia deep-merges
+   * a GET's: a nested object merges into the fields the URL has under its
+   * key (`filter: { status }` replaces `filter[status]` and keeps
+   * `filter[sort]`), and any other value -- a list included -- replaces
+   * what the URL said under its name. The rest of the query is kept.
+   * Written as a form body is -- `tags[]`, `filter[status]`, booleans as 1
+   * and 0, null as an empty string; undefined takes the field out. A file
+   * throws: a visit is a GET.
+   */
+  data?: Record<string, unknown>;
+  replace?: boolean;
+  /**
+   * Keep the window and the `scroll-region` elements where they are rather
+   * than at the top. A function decides once the response is in, told what
+   * `preserveState`'s is.
+   */
+  preserveScroll?: boolean | ((page: PreservedPage) => boolean);
+  headers?: Record<string, string>;
+  /** A request the user did not trigger -- a poll, a prefetch. Never forces a reload. */
+  background?: boolean;
+  /**
+   * A partial reload of the segments these dot paths name: `'page'`,
+   * `'page.order'`, a layout's key such as `'shop'`, or `'shop.customer'`.
+   * The unit recomputed is the segment (ADR 0015).
+   */
+  only?: readonly string[];
+  /** A partial reload of every segment but those named whole here. */
+  except?: readonly string[];
+  /**
+   * Merged fields -- #[Merge] lists and Scroll pages, by dot path such as
+   * `'page.orders'` -- this response replaces rather than adds to: what a
+   * filter that changes the list asks for (X-Reset, ADR 0020).
+   */
+  reset?: readonly string[];
+  /**
+   * Fetch the URL without moving the address bar to it: no entry pushed or
+   * replaced. In the background, a partial payload of the page on screen
+   * fetched at another of its URLs -- a list's next page -- is merged into it.
+   */
+  preserveUrl?: boolean;
+  /** Cancels this visit, or this background request, and nothing else. */
+  signal?: AbortSignal;
+  /** False keeps the progress bar hidden for this visit. Background requests never show it. */
+  showProgress?: boolean;
+  /**
+   * Mount the page inside `document.startViewTransition()`, where the
+   * browser has it; a function is handed the ViewTransition. Without the
+   * API the page mounts as usual. Never for background requests. With a
+   * router given `prepare`, the transition holds the page for the commit
+   * alone, not while the payload is decoded.
+   */
+  viewTransition?: boolean | ((transition: ViewTransition) => void);
+  /**
+   * Whether the page's client components keep their state: reconciled with
+   * the page they replace (true), or mounted again (false), the page
+   * segment's -- or the segments a partial reload carries -- while layouts
+   * keep theirs. A function decides once the response is in. Defaults, as
+   * Inertia's: false for a visit that shows a whole page, true for
+   * reload(), a partial reload, a background request and an action's
+   * re-render (ADR 0045).
+   */
+  preserveState?: boolean | ((page: PreservedPage) => boolean);
+  /**
+   * Ask the server even when a prefetched copy of the page is kept. The
+   * visit after an action is made fresh: the action may have changed whose
+   * session this is.
+   */
+  fresh?: boolean;
+  /**
+   * Claim none of the #[Once] content this client keeps, so the server
+   * renders those fields again: for a live refresh, which says something
+   * the page read has changed.
+   */
+  refreshOnce?: boolean;
+  /**
+   * This visit's own `success`: the page was mounted. May return a promise,
+   * which the visit's `finish` -- and the promise visit() returns -- waits for.
+   */
+  onSuccess?: (page: PreservedPage) => unknown;
+  /**
+   * Each way this visit failed: the payload arrived and could not be
+   * rendered (handed what the mount threw), the server answered a status
+   * that is not a page (a VisitHttpError), or no answer came (a
+   * VisitNetworkError). May return a promise, waited for before the visit's
+   * `finish` and before the page is loaded as a document. Told, not asked:
+   * cancelling `error`, `httpException` or `networkError` is what stops the
+   * document load. A GET carries no validation errors.
+   */
+  onError?: (error: unknown) => unknown;
+  /**
+   * Show the layouts on screen, and a layout's loading boundary below them,
+   * while the page is fetched (ADR 0092): the boundary of the layout
+   * directly above the page given true, of the layout with that key given a
+   * string. Not for a page answered from the prefetch cache, a partial
+   * reload, a background request, or back and forward; a layout with no
+   * boundary makes it an ordinary visit.
+   */
+  instant?: boolean | string;
+}
+
+/** The page's view, on a payload; sent back as X-Page with a partial reload. */
+export declare const PAGE_HEADER: 'x-page';
+/** Marks a payload holding only what a partial reload recomputed. */
+export declare const PARTIAL_HEADER: 'x-partial';
+
+/**
+ * How long a prefetched page is used for: milliseconds, or `'30s'`, `'1m'`
+ * and the like; or `[fresh, stale]`, used while fresh and then, while a new
+ * copy is fetched behind it, until the second -- the whole lifetime.
+ */
+export type CacheFor = number | string | readonly [number | string, number | string];
+
+export interface PrefetchOptions {
+  /** 30 seconds unless given. */
+  cacheFor?: CacheFor;
+  /**
+   * What the page shows, as cache tags: an action whose response names one
+   * in `X-Invalidated-Tags` flushes it, and so does flushByCacheTags().
+   */
+  cacheTags?: string | readonly string[];
+  /** Only GET prefetches; any other method is ignored. */
+  method?: string;
+}
+
+/** Which page's history entry useRemember() writes to. */
+export interface RememberScope {
+  readonly entry: string | null;
+  readonly session: string | null;
+}
+
+/** What a `preserveState` function is told of the page that came back. */
+export interface PreservedPage {
+  url: string;
+  /** The page's view, as the server named it; null where it did not. */
+  view: string | null;
+  partial: boolean;
+}
+
+export interface Page {
+  url: string;
+  routeToken: string | null;
+  /** Aborts once a later navigation supersedes this one. */
+  signal: AbortSignal;
+  /** The payload is `{ segments }` from a partial reload, to merge into the page on screen. */
+  partial?: boolean;
+  /** False: commit it fresh, its page segment's components mounted again. See VisitOptions. */
+  preserveState?: boolean;
+}
+
+/** A payload decoded and ready to go on screen; see RouterOptions.prepare. */
+export interface PreparedPage {
+  /** Shows the page. Resolve only once it is COMMITTED, or the visit aborted. */
+  commit: () => Promise<void>;
+}
+
+export type RouterOptions = RouterMountOptions &
+  (
+    | {
+        /**
+         * Turns a payload into React elements; must use the app's own
+         * client bundle. Resolve only once the page is COMMITTED: the
+         * router scrolls, finds anchors and reports the page right after,
+         * and those all read the DOM.
+         */
+        mount: (stream: ReadableStream<Uint8Array>, page: Page) => void | Promise<void>;
+        prepare?: undefined;
+      }
+    | {
+        mount?: (stream: ReadableStream<Uint8Array>, page: Page) => void | Promise<void>;
+        /**
+         * The mount in two steps, as createPageRoot() hands it: decode the
+         * payload, then commit it. Preferred over `mount` where both are
+         * given: a view transition then holds the page for the commit
+         * alone. Resolves null when the visit was aborted while decoding.
+         */
+        prepare: (stream: ReadableStream<Uint8Array>, page: Page) => Promise<PreparedPage | null | undefined>;
+      }
+  );
+
+export interface RouterMountOptions {
+  /** This client's build, sent as X-Version. Read from the page metadata if omitted. */
+  version?: string;
+  fetch?: typeof fetch;
+  window?: Window;
+  initialRouteToken?: string | null;
+  /** The first page's view, sent as X-Page. Read from the page metadata if omitted. */
+  initialView?: string | null;
+  /** A full page load. Defaults to location.assign. */
+  hardNavigate?: (url: string) => void;
+  /**
+   * Where useRemember() keeps its values, by history entry, for one session:
+   * the tab's sessionStorage unless given; memory alone given null.
+   */
+  storage?: Storage | null;
+  /**
+   * Where resumable uploads are remembered, which the router purges of
+   * every other session's records: the page's IndexedDB store unless given.
+   */
+  resumeStore?: import('./upload.js').ResumeStore;
+  /**
+   * The first page's history key, which what it remembers is sealed with.
+   * Read from the page metadata if omitted; null for a page whose history
+   * is not encrypted (ADR 0019).
+   */
+  initialHistoryKey?: string | null;
+  /**
+   * The application's endpoints -- codegen's `endpoint` -- whose URLs are no
+   * page's (ADR 0074): a link to one is left to the browser, a visit to one
+   * is a full load, and none is fetched as a payload or prefetched.
+   */
+  endpoints?: { matches(url: URL | string): boolean };
+  /**
+   * Shows an instant visit's loading boundary and hands back what takes it
+   * away: createPageRoot()'s `instant`. Without it, an instant visit is an
+   * ordinary one.
+   */
+  instant?: (under: true | string) => (() => void) | null;
+}
+
+/**
+ * Cancelable events (before, location, httpException, networkError, error)
+ * are UI hooks, not security controls: any script on the page can cancel
+ * them, and the server enforces every rule regardless.
+ */
+export type RouterEvent =
+  | 'before'
+  | 'start'
+  | 'success'
+  | 'finish'
+  /**
+   * A page is shown: the first (`initial`, once `ready` has settled, or
+   * before any other event that comes first), one a visit mounted, or one
+   * back or forward arrived at.
+   */
+  | 'navigate'
+  | 'location'
+  | 'httpException'
+  | 'networkError'
+  /** The mount threw. Cancelable; otherwise the page is loaded as a document. */
+  | 'error'
+  /** An action flashed something; see Router.flash(). */
+  | 'flash'
+  /** A prefetch was sent. */
+  | 'prefetching'
+  /** A prefetched page arrived and is kept. */
+  | 'prefetched'
+  /** The session ended on this client (a 401, or revoke()): what else holds its data drops it. */
+  | 'revoke'
+  /** clearHistory() ran: what else holds the session's data drops it. */
+  | 'clearHistory'
+  /** The router started reading a visit's RSC payload. */
+  | 'streamStart'
+  /** A chunk of the payload arrived: its size, and how much has so far. Never the bytes. */
+  | 'streamChunk'
+  /**
+   * The payload is all in -- after `finish`, for a page that commits at its
+   * shell and streams the rest -- or, `interrupted`, never will be.
+   */
+  | 'streamEnd'
+  /** <Form>, useForm or useHttp sent an action. */
+  | 'actionStart'
+  /** An action's files are uploading: `progress` is how far, as the form's own is. */
+  | 'progress'
+  /** An action's answer came back and was applied to the page; `type` says what it was. */
+  | 'actionSettle';
+
+/** The first page, one a visit showed, or one back or forward arrived at. */
+export interface NavigateDetail {
+  url: string;
+  type: 'initial' | 'visit' | 'history';
+}
+
+/** What the RSC stream events say of the request. */
+export interface StreamDetail {
+  url: string;
+  /** A poll, a deferred refresh, a list's next page. */
+  background?: true;
+}
+
+export interface StreamChunkDetail extends StreamDetail {
+  /** This chunk's size in bytes. */
+  bytes: number;
+  /** Every chunk's so far, this one included. */
+  received: number;
+}
+
+export interface StreamEndDetail extends StreamDetail {
+  /** The payload's size in bytes, or as much of it as arrived. */
+  bytes: number;
+  /** It stopped before its end: superseded, cancelled, dropped, or not mounted. */
+  interrupted?: true;
+}
+
+export interface ActionDetail {
+  /** The action's name, as `@actions/*` names it. */
+  action: string;
+}
+
+export interface ActionProgressDetail extends ActionDetail {
+  progress: { loaded: number; total: number | undefined; percentage: number | undefined };
+}
+
+export interface ActionSettleDetail extends ActionDetail {
+  /**
+   * How it came back: the three error channels, a page that outlived its
+   * session, a cancel or a newer call, or `error` for something that threw
+   * on the way. A redirect is a success.
+   */
+  type: 'success' | 'validation' | 'http' | 'network' | 'expired' | 'cancelled' | 'error';
+  /** For `http`, the status. */
+  status?: number;
+}
+
+/** The detail each event carries, where it is typed. */
+export interface RouterEventDetails {
+  navigate: NavigateDetail;
+  streamStart: StreamDetail;
+  streamChunk: StreamChunkDetail;
+  streamEnd: StreamEndDetail;
+  actionStart: ActionDetail;
+  progress: ActionProgressDetail;
+  actionSettle: ActionSettleDetail;
+}
+
+/** An event's detail: typed for those RouterEventDetails names. */
+export type RouterEventDetail<E extends RouterEvent> = E extends keyof RouterEventDetails
+  ? RouterEventDetails[E]
+  : any;
+
+export interface Router {
+  /**
+   * Resolves once the visit is over, with whether a page was mounted: false
+   * when it failed, was cancelled or superseded, was not sent -- a
+   * background request while a visit is in flight -- or was answered with
+   * nothing to mount here.
+   */
+  visit(href: string, options?: VisitOptions): Promise<boolean>;
+  get(href: string, options?: VisitOptions): Promise<boolean>;
+  /**
+   * As visit(): with `background`, whether the page on screen was refreshed.
+   * Given the `routeToken` an action was sent with, it is refused, as
+   * applyPayload() is, once another page has been mounted or while a visit
+   * is in flight.
+   */
+  reload(options?: VisitOptions & { routeToken?: string | null }): Promise<boolean>;
+  /**
+   * Fetches a page ahead of a visit, with `Purpose: prefetch`, and keeps it
+   * for `cacheFor`. A visit to it within that time is answered from the
+   * cache, or waits for the prefetch if it is still in flight. GET only.
+   */
+  prefetch(href: string, options?: PrefetchOptions): Promise<void>;
+  /**
+   * Mounts a re-rendered payload of the page on screen -- an action's
+   * revalidation -- without a request: no history, no scroll, the route
+   * token kept, and never while a visit is in flight. Resolves once the page
+   * has committed, with whether it was mounted. Of `options`,
+   * `viewTransition`, `preserveState`, `onSuccess` and `onError` apply.
+   * Given the `routeToken` the action was sent with, it is refused once
+   * another page has been mounted since. Given the re-render's `liveToken`,
+   * the `success` event hands it on.
+   */
+  applyPayload(
+    payload: string | Uint8Array | ReadableStream<Uint8Array>,
+    options?: VisitOptions & { routeToken?: string | null; liveToken?: string | null },
+  ): Promise<boolean>;
+  /** Emits the `flash` event: to listeners, and as a native `tinvar:flash` CustomEvent. */
+  flash(flash: Record<string, unknown>, detail?: Record<string, unknown>): void;
+  /**
+   * Emits one of the forms layer's events -- `actionStart`, `progress`,
+   * `actionSettle` -- to listeners and as a native `tinvar:<name>`
+   * CustomEvent. What <Form>, useForm and useHttp call; any other name throws.
+   */
+  announce<E extends 'actionStart' | 'progress' | 'actionSettle'>(
+    name: E,
+    detail: RouterEventDetails[E],
+  ): void;
+  /** Forgets the prefetched copy of a page. */
+  flush(href: string): void;
+  /** Forgets every prefetched page. */
+  flushAll(): void;
+  /**
+   * Ends the session on this client, for a 401 the router did not hear
+   * itself: drops the route token, every prefetched page and everything
+   * remembered, stops what is in flight, and sends nothing more. The caller
+   * makes the full page load that must follow.
+   */
+  revoke(): void;
+  /**
+   * Wipes everything remembered, for every entry of the tab, and drops the
+   * history key, so nothing sealed with it opens in this document again.
+   * Nothing more is remembered on the page it is called on. What logging
+   * out calls; the key itself rotates with the session's id (ADR 0019).
+   */
+  clearHistory(): void;
+  /**
+   * Settles once what the first page's entry remembered has been read back:
+   * at once for an entry kept in the clear, after opening it for one kept
+   * sealed. Await it before hydrating, so components mount with it.
+   */
+  readonly ready: Promise<void>;
+  /** Forgets every prefetched page carrying one of these tags; returns how many. */
+  flushByCacheTags(tags: string | readonly string[]): number;
+  /**
+   * Forgets the prefetched pages an action's response says it invalidated,
+   * from its `X-Invalidated-Tags`. Returns the tags it named.
+   */
+  flushInvalidated(source: Response | Headers | { headers?: Headers } | string | null | undefined): string[];
+  /**
+   * The page a component mounting now belongs to, for what it remembers:
+   * the page being mounted while a visit mounts one, otherwise the page on
+   * screen. Opaque; useRemember() takes it once, as it mounts.
+   */
+  rememberScope(): RememberScope;
+  /** The value remembered under a key for a page, or undefined -- also when it was set under another session. */
+  remembered(key: string, scope?: RememberScope): unknown;
+  /**
+   * Remembers a value under a key on the page's history entry, bound to the
+   * session in force as it is set. Without a session nothing is remembered.
+   */
+  remember(key: string, value: unknown, scope?: RememberScope): void;
+  /**
+   * What a page kept of a #[Once] field, for <OnceSlot>: only for a page of
+   * the session it was kept under. `scope` defaults to rememberScope().
+   */
+  heldOnce(key: string, scope?: RememberScope): { content: unknown } | undefined;
+  /**
+   * X-Have-Shared with the once-shared values' holds kept under the page on
+   * screen's session, for a fragment request to claim them by (ADR 0074);
+   * empty when there are none.
+   */
+  sharedClaims(): Record<string, string>;
+  /** Whether a URL is one of the application's endpoints, which the router leaves to the browser (ADR 0074). */
+  isEndpoint(url: URL | string): boolean;
+  /** Keeps what a page rendered from a #[Once] field, for the session the page came with. */
+  holdOnce(
+    key: string,
+    content: unknown,
+    ttl: number | null,
+    tags: readonly string[],
+    scope?: RememberScope,
+    /** A once-shared value's signed hold, which claims it in X-Have-Shared (ADR 0065). */
+    hold?: string | null,
+  ): void;
+  /** Stops listing these once keys, or all of them, in X-Have-Once; the next response sends them fresh. */
+  flushOnce(keys?: string | readonly string[]): void;
+  /**
+   * Moves the address bar to another URL of the page on screen without a
+   * request, replacing the entry and keeping its state. Same origin only.
+   */
+  replaceUrl(href: string): boolean;
+  /**
+   * Records where a merged list on the page on screen is read to, on its
+   * history entry, with the scroll position. What <InfiniteScroll> calls as
+   * the reader scrolls.
+   */
+  saveScrollAnchor(id: string, anchor: ScrollAnchor): void;
+  /**
+   * Where a merged list was read to on the entry a back, a forward or a
+   * reload arrived at -- once; undefined after any other visit. Taking one
+   * in the window stops the router restoring the raw position; one in the
+   * `container` given stops it restoring that container, as a scroll region.
+   */
+  takeScrollAnchor(id: string, container?: Element | null): ScrollAnchor | undefined;
+  /** Cancels the visit (`sync`), background requests (`async`) and prefetches; all three by default. */
+  cancelAll(options?: { sync?: boolean; async?: boolean; prefetch?: boolean }): void;
+  /** Subscribes to an event; returns the unsubscribe function. Each is also a native `tinvar:<name>` CustomEvent. */
+  on<E extends RouterEvent>(name: E, fn: (event: CustomEvent<RouterEventDetail<E>>) => void): () => void;
+  /** The tokens an action sends so the mounted page can be re-rendered. */
+  routeTokens(): string[];
+  /** The view of the page on screen, where the server named it; null where it did not. */
+  currentView(): string | null;
+  destroy(): void;
+}
+
+/**
+ * Where a merged list was read to: the item at the top of what the reader
+ * saw, how far down the screen (or the list's scroll container) its top
+ * was, and the pages that were loaded.
+ */
+export interface ScrollAnchor {
+  /** The page the item came on. */
+  page: number;
+  /** The key it was rendered under, where the list could tell; null otherwise. */
+  key: string | null;
+  /** Its place among its page's items. */
+  index: number;
+  /** Its top, in pixels below the top of the window or the scroll container. */
+  top: number;
+  first: number;
+  last: number;
+  /** Whether the list scrolls with the window rather than a container of its own. */
+  window: boolean;
+}
+
+export declare const PAGE_METADATA_ID: 'tinvar-page';
+
+export interface PageMetadata {
+  url: string;
+  version: string;
+  routeToken: string | null;
+  /** Null where partial reloads are off. */
+  view: string | null;
+  /**
+   * The session's history key, for a page whose history is encrypted (ADR 0019); otherwise null.
+   * The router takes it out of the block once it has imported it: read after it starts, null.
+   */
+  historyKey: string | null;
+  /** What the page's reports are filed under: its route's name, or its view where it has none (ADR 0129). */
+  route: string | null;
+}
+
+/** The session binding a route token carries -- session hash, user hash, tenant, panel -- or null. Unverified. */
+export declare function bindingOf(token: string | null | undefined): string | null;
+
+/** The initial page metadata the renderer wrote, or null if absent or malformed. */
+export declare function readPageMetadata(doc?: Document): PageMetadata | null;
+
+export declare function createRouter(options: RouterOptions): Router;