@tinvar/react 0.0.0-stage → 0.4.1

package/src/use-http.js

@@ -0,0 +1,248 @@
+'use client';
+
+// useHttp: an action or a query, called from a component without moving the
+// page.
+//
+// tinvar-spec.md, "Forms and mutations": "`useHttp` calls queries and
+// actions without navigating (search-as-you-type). Keep three error
+// channels: 422 -> `errors`, other statuses -> `onHttpException`,
+// connectivity -> `onNetworkError`."
+//
+// The answer is the caller's to use: a query's result, an action's value.
+// Nothing is mounted and no redirect is followed -- an action's redirect is
+// handed back as `redirect` -- but what an action changed still reaches the
+// router: prefetched pages are dropped, and its flash is announced, since
+// neither moves the page -- and so is the call itself, its `actionStart`
+// and `actionSettle`, as a form's is.
+//
+// Each call replaces the one in flight. Typing "sh", "sho", "shop" sends
+// three searches; only the answer to "shop" lands, and the other two are
+// cancelled rather than left to arrive late and overwrite it.
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { actionName, actionUrl } from './action.js';
+import { firstMessages, useFormSession, useOptionalRouter } from './form.js';
+import { revalidateDeferred } from './deferred-revalidation.js';
+import {
+  announceAction,
+  announceFlash,
+  assignLocation,
+  endSession,
+  flushAfterAction,
+} from './router-hooks.js';
+import { call, resultOf } from './submit.js';
+import { invalidatedTags } from './router.js';
+import { send } from './transport.js';
+
+export const QUERY_PREFIX = '/_query/';
+const EMPTY = Object.freeze({});
+
+/**
+ * A reference to a PHP #[Query], for useHttp: `query('products.search')`.
+ * Server components call queries over the render's socket instead.
+ *
+ * @param {string} name
+ */
+export function query(name) {
+  if (typeof name !== 'string' || name === '') throw new TypeError('[tinvar] A query is its name.');
+  return Object.freeze({ query: name, url: QUERY_PREFIX + encodeURIComponent(name) });
+}
+
+/**
+ * What an action call's `actionSettle` says of its answer, as a form's
+ * submission says it: a redirect is a success, and a status other than 422
+ * is `http`, with the status.
+ *
+ * @param {import('./transport.js').Outcome} outcome
+ * @returns {{ type: string, status?: number }}
+ */
+function settledAs(outcome) {
+  if (outcome.type === 'redirect' || outcome.type === 'location') return { type: 'success' };
+  if (outcome.type === 'http') return { type: 'http', status: outcome.status };
+  return { type: outcome.type };
+}
+
+/**
+ * @typedef {import('./action.js').ActionTarget | { readonly query: string }} HttpTarget
+ *
+ * @typedef {{
+ *   onSuccess?: (value: unknown) => void,
+ *   onError?: (errors: Record<string, string[]>) => void,
+ *   onHttpException?: (failure: import('./submit.js').HttpFailure) => void,
+ *   onNetworkError?: (error: unknown) => void,
+ *   onCancel?: () => void,
+ *   onFinish?: () => void,
+ *   headers?: Record<string, string>,
+ * }} HttpCallbacks
+ */
+
+/**
+ * @param {HttpTarget} target
+ * @param {HttpCallbacks} [defaults] callbacks every call runs, before its own
+ */
+export function useHttp(target, defaults = {}) {
+  const router = useOptionalRouter();
+  const session = useFormSession();
+  const [result, setResult] = useState(/** @type {unknown} */ (undefined));
+  const [errors, setErrors] = useState(/** @type {Record<string, string>} */ (EMPTY));
+  const [processing, setProcessing] = useState(false);
+  const [wasSuccessful, setWasSuccessful] = useState(false);
+  const inFlight = useRef(/** @type {AbortController | null} */ (null));
+
+  const latest = useRef({ target, defaults, router, session });
+  latest.current = { target, defaults, router, session };
+
+  useEffect(() => () => inFlight.current?.abort(), []);
+
+  const cancel = useCallback(() => inFlight.current?.abort(), []);
+
+  const run = useCallback(
+    /**
+     * @param {Record<string, unknown>} [args]
+     * @param {HttpCallbacks} [own]
+     */
+    async (args = {}, own = {}) => {
+      const { target: to, defaults: base, router: r, session: s } = latest.current;
+      const each = (/** @type {keyof HttpCallbacks} */ name, /** @type {unknown[]} */ ...values) => {
+        call(/** @type {any} */ (base[name]), ...values);
+        call(/** @type {any} */ (own[name]), ...values);
+      };
+
+      inFlight.current?.abort();
+      const controller = new AbortController();
+      inFlight.current = controller;
+      const current = () => inFlight.current === controller;
+      setProcessing(true);
+
+      const isQuery = typeof to === 'object' && to !== null && 'query' in to;
+      // An action call is announced through the router, as a form's is: its
+      // `actionStart`, its upload's `progress`, and its `actionSettle`. A
+      // query changes nothing, and is not.
+      const action = isQuery ? null : actionName(/** @type {any} */ (to));
+      if (action !== null) announceAction(r, 'actionStart', { action });
+      const outcome = await send({
+        url: isQuery ? QUERY_PREFIX + encodeURIComponent(to.query) : actionUrl(/** @type {any} */ (to)),
+        // A query takes its arguments under `args`, as the endpoint reads
+        // them; an action takes its input as the body.
+        data: isQuery ? { args } : args,
+        headers: { ...base.headers, ...own.headers },
+        signal: controller.signal,
+        onUploadProgress:
+          action === null ? undefined : (progress) => announceAction(r, 'progress', { action, progress }),
+      });
+
+      try {
+        if (!current()) {
+          // Replaced by a later call, whose answer is the one that counts.
+          if (outcome.type === 'cancelled') each('onCancel');
+          return { type: 'cancelled' };
+        }
+        inFlight.current = null;
+        setProcessing(false);
+
+        switch (outcome.type) {
+          case 'success': {
+            let value;
+            if (isQuery) {
+              value = outcome.body?.value ?? null;
+            } else {
+              const answered = resultOf(outcome.body);
+              value = answered.value;
+              flushAfterAction(r, outcome.headers);
+              // The page stays, and so do its fragments: one that read a tag
+              // the action invalidated is fetched again, as after a form's.
+              if (invalidatedTags(outcome.headers).length > 0) revalidateDeferred();
+              if (Object.keys(answered.flash).length > 0) {
+                s?.setFlash(answered.flash);
+                announceFlash(r, answered.flash, actionName(/** @type {any} */ (to)));
+              }
+            }
+            setResult(value);
+            setErrors(EMPTY);
+            setWasSuccessful(true);
+            each('onSuccess', value);
+            return { type: 'success', value };
+          }
+
+          case 'redirect':
+          case 'location':
+            // Not followed: that would be navigating. The caller decides.
+            if (!isQuery) flushAfterAction(r, outcome.headers);
+            setErrors(EMPTY);
+            setWasSuccessful(true);
+            each('onSuccess', { redirect: outcome.location });
+            return { type: 'success', value: undefined, redirect: outcome.location };
+
+          case 'validation':
+            setErrors(firstMessages(outcome.errors));
+            setWasSuccessful(false);
+            each('onError', outcome.errors);
+            return { type: 'validation', errors: outcome.errors };
+
+          case 'http': {
+            const failure = {
+              status: outcome.status,
+              code: outcome.code,
+              reference: outcome.reference,
+              retryAfter: outcome.retryAfter,
+              body: outcome.body,
+            };
+            setWasSuccessful(false);
+            each('onHttpException', failure);
+            // The one status that moves the page: the session is over, and
+            // a call that must not navigate still may not leave the page up
+            // under it -- nor what it remembered in the tab's storage. See
+            // endSession().
+            if (outcome.status === 401) endSession(r, s?.hardNavigate ?? assignLocation);
+            return { type: 'http', failure };
+          }
+
+          case 'network':
+            setWasSuccessful(false);
+            each('onNetworkError', outcome.error);
+            return { type: 'network', error: outcome.error };
+
+          case 'expired': {
+            // Refused twice for its token. A form answers that by loading
+            // the page again; a call that must not move the page reports
+            // it, and the caller decides.
+            const failure = {
+              status: 419,
+              code: 'page_expired',
+              reference: null,
+              retryAfter: null,
+              body: null,
+            };
+            setWasSuccessful(false);
+            each('onHttpException', failure);
+            return { type: 'http', failure };
+          }
+
+          default:
+            each('onCancel');
+            return { type: 'cancelled' };
+        }
+      } finally {
+        // How the call came back, whatever this hook made of it: a newer
+        // call superseding it does not change what the action did.
+        if (action !== null) announceAction(r, 'actionSettle', { action, ...settledAs(outcome) });
+        each('onFinish');
+      }
+    },
+    [],
+  );
+
+  return useMemo(
+    () => ({
+      call: run,
+      result,
+      errors,
+      hasErrors: Object.keys(errors).length > 0,
+      processing,
+      wasSuccessful,
+      cancel,
+      clearErrors: () => setErrors(EMPTY),
+    }),
+    [run, result, errors, processing, wasSuccessful, cancel],
+  );
+}

package/src/use-inbox.d.ts

@@ -0,0 +1,41 @@
+import type { InboxClient, InboxEntry, NotificationChannel, NotificationPreference } from './inbox.js';
+
+export interface UseInboxOptions<T extends string = string> {
+  /** Entries a page holds: 1 to 50, 20 by default. */
+  limit?: number;
+  /** Called for each entry that arrives while mounted: a toast, a sound. */
+  onEntry?: (entry: InboxEntry<T>) => void;
+  /** Listen on the inbox's personal channel; true by default. */
+  live?: boolean;
+}
+
+export interface UseInbox<T extends string = string> {
+  entries: InboxEntry<T>[];
+  unread: number;
+  loading: boolean;
+  error: unknown;
+  hasMore: boolean;
+  loadMore(): Promise<void>;
+  markRead(ids: string[]): Promise<void>;
+  markAllRead(): Promise<void>;
+  refresh(): Promise<void>;
+}
+
+/** Reads the user's inbox while the component is mounted, live. */
+export declare function useInbox<T extends string>(
+  client: InboxClient<T>,
+  options?: UseInboxOptions<T>,
+): UseInbox<T>;
+
+export interface UseNotificationPreferences<T extends string = string> {
+  types: NotificationPreference<T>[];
+  loading: boolean;
+  error: unknown;
+  /** Saves one switch; resolves to whether the shop saved it. */
+  choose(type: T, channel: NotificationChannel, enabled: boolean): Promise<boolean>;
+}
+
+/** Which channels the user gets for each kind of notification, and a way to change one. */
+export declare function useNotificationPreferences<T extends string>(
+  client: InboxClient<T>,
+): UseNotificationPreferences<T>;

package/src/use-inbox.js

@@ -0,0 +1,201 @@
+'use client';
+
+// useInbox and useNotificationPreferences: a component reading the user's
+// inbox while it is mounted (ADR 0155).
+//
+//   const { entries, unread, markRead } = useInbox(inbox.customer);
+//
+// Reads the first page when it mounts, and listens on the inbox's personal
+// channel: an entry that arrives goes on top and is counted, ids another
+// tab marked read are shown read, and a gap in the stream -- messages the
+// hub kept none of -- reads the first page again. Marking read updates the
+// count at once and takes the server's answer as the truth.
+//
+// Hand it a client that stays the same between renders -- the `inbox` codegen
+// exports, or one made outside the component: a new one each render reads
+// the feed again each render.
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+/**
+ * @typedef {import('./inbox.js').inboxClient} InboxClientFactory
+ * @typedef {ReturnType<InboxClientFactory>} InboxClient
+ * @typedef {{ id: string, type: string, title: string, body: string, url: string | null, createdAt: string, readAt: string | null }} Entry
+ */
+
+/**
+ * @param {InboxClient} client
+ * @param {{ limit?: number, onEntry?: (entry: Entry) => void, live?: boolean }} [options]
+ */
+export function useInbox(client, options = {}) {
+  const limit = options.limit ?? 20;
+  const live = options.live ?? true;
+  const [entries, setEntries] = useState(/** @type {Entry[]} */ ([]));
+  const [unread, setUnread] = useState(0);
+  const [next, setNext] = useState(/** @type {string | null} */ (null));
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(/** @type {unknown} */ (null));
+  const onEntry = useRef(options.onEntry);
+  onEntry.current = options.onEntry;
+  const shown = useRef(entries);
+  shown.current = entries;
+
+  const refresh = useCallback(async () => {
+    setLoading(true);
+    try {
+      const page = await client.page({ limit });
+      setEntries(page.entries);
+      setUnread(page.unread);
+      setNext(page.next);
+      setError(null);
+    } catch (e) {
+      setError(e);
+    } finally {
+      setLoading(false);
+    }
+  }, [client, limit]);
+
+  useEffect(() => {
+    void refresh();
+    if (!live) return undefined;
+
+    return client.listen(
+      (/** @type {any} */ update) => {
+        if (update === null || typeof update !== 'object') return;
+        if (typeof update.unread === 'number') setUnread(update.unread);
+        const entry = update.entry;
+        if (entry && typeof entry.id === 'string') {
+          setEntries((held) => (held.some((e) => e.id === entry.id) ? held : [entry, ...held]));
+          onEntry.current?.(entry);
+        }
+        const now = new Date().toISOString();
+        if (update.allRead === true) {
+          setEntries((held) => held.map((e) => (e.readAt === null ? { ...e, readAt: now } : e)));
+        } else if (Array.isArray(update.read) && update.read.length > 0) {
+          const read = new Set(update.read);
+          setEntries((held) =>
+            held.map((e) => (e.readAt === null && read.has(e.id) ? { ...e, readAt: now } : e)),
+          );
+        }
+      },
+      { onGap: () => void refresh() },
+    );
+  }, [client, live, refresh]);
+
+  const loadMore = useCallback(async () => {
+    if (next === null) return;
+    try {
+      const page = await client.page({ before: next, limit });
+      setEntries((held) => [...held, ...page.entries.filter((e) => !held.some((h) => h.id === e.id))]);
+      setUnread(page.unread);
+      setNext(page.next);
+    } catch (e) {
+      setError(e);
+    }
+  }, [client, next, limit]);
+
+  const markRead = useCallback(
+    async (/** @type {string[]} */ ids) => {
+      if (ids.length === 0) return;
+      const now = new Date().toISOString();
+      const marking = new Set(ids);
+      // Counted down at once by those shown unread, as markAllRead() counts
+      // to zero; the server's count replaces it when it answers.
+      const counted = shown.current.filter((e) => e.readAt === null && marking.has(e.id)).length;
+      if (counted > 0) setUnread((was) => Math.max(0, was - counted));
+      setEntries((held) =>
+        held.map((e) => (e.readAt === null && marking.has(e.id) ? { ...e, readAt: now } : e)),
+      );
+      try {
+        setUnread((await client.markRead(ids)).unread);
+      } catch (e) {
+        setError(e);
+        void refresh();
+      }
+    },
+    [client, refresh],
+  );
+
+  const markAllRead = useCallback(async () => {
+    const now = new Date().toISOString();
+    setEntries((held) => held.map((e) => (e.readAt === null ? { ...e, readAt: now } : e)));
+    setUnread(0);
+    try {
+      setUnread((await client.markAllRead()).unread);
+    } catch (e) {
+      setError(e);
+      void refresh();
+    }
+  }, [client, refresh]);
+
+  return {
+    entries,
+    unread,
+    loading,
+    error,
+    hasMore: next !== null,
+    loadMore,
+    markRead,
+    markAllRead,
+    refresh,
+  };
+}
+
+/**
+ * Which channels the user gets for each kind of notification, and a way to
+ * change one: written at once, the server's answer taken as the truth.
+ *
+ * @param {InboxClient} client
+ */
+export function useNotificationPreferences(client) {
+  const [types, setTypes] = useState(/** @type {any[]} */ ([]));
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(/** @type {unknown} */ (null));
+
+  useEffect(() => {
+    let current = true;
+    client
+      .preferences()
+      .then((answer) => {
+        if (current) setTypes(answer.types);
+      })
+      .catch((e) => {
+        if (current) setError(e);
+      })
+      .finally(() => {
+        if (current) setLoading(false);
+      });
+    return () => {
+      current = false;
+    };
+  }, [client]);
+
+  const choose = useCallback(
+    async (/** @type {string} */ type, /** @type {string} */ channel, /** @type {boolean} */ enabled) => {
+      setTypes((held) =>
+        held.map((t) =>
+          t.type !== type
+            ? t
+            : {
+                ...t,
+                enabled: enabled
+                  ? [...new Set([...t.enabled, channel])]
+                  : t.enabled.filter((/** @type {string} */ c) => c !== channel),
+              },
+        ),
+      );
+      try {
+        setTypes((await client.choose([{ type, channel, enabled }])).types);
+        setError(null);
+        return true;
+      } catch (e) {
+        setError(e);
+        setTypes((await client.preferences().catch(() => ({ types: [] }))).types);
+        return false;
+      }
+    },
+    [client],
+  );
+
+  return { types, loading, error, choose };
+}

package/src/use-remember.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Client component state kept on the history entry, so back and forward
+ * bring it back -- debounced, because browsers rate-limit replaceState.
+ * Bound to the session it was set under: read back only under that session,
+ * and not remembered at all without one.
+ */
+export declare function useRemember<T>(
+  initial: T | (() => T),
+  key: string,
+): [T, (next: T | ((current: T) => T)) => void];

package/src/use-remember.js

@@ -0,0 +1,132 @@
+'use client';
+
+// useRemember: client component state that back and forward bring back.
+//
+// tinvar-spec.md, "Client router and components": "`useRemember(initial,
+// key)` for client component state across back/forward, debounced because
+// browsers rate-limit `replaceState`."
+//
+// The value lives in the router's record for the page the component belongs
+// to, and the router writes it onto that page's history entry -- debounced
+// with the scroll position, and at once before a visit leaves the entry.
+// What is remembered is client-held data: each value is bound to the session
+// it was set under, read back only under that session, and not remembered
+// at all where there is none (see the router's rememberValue()).
+
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { useOptionalRouter } from './link.js';
+
+const subscribeToNothing = () => () => {};
+const onClient = () => true;
+const onServer = () => false;
+
+/**
+ * @internal Whether this render may show what was remembered: false on the
+ * server and while hydrating, true for every render after, and from the
+ * first for a component that mounts on the client.
+ *
+ * What is remembered lives in the tab's storage, which the server never
+ * sees. A document loaded again -- a reload, a back that missed the
+ * browser's cache -- is rendered by the server with each initial value, and
+ * a hydration that rendered the remembered one instead did not match it:
+ * React threw the server's HTML away and rendered the page again. React
+ * renders with the server's snapshot while hydrating, and again with this
+ * one once it has, so the remembered value shows straight after.
+ */
+export function useHydrated() {
+  return useSyncExternalStore(subscribeToNothing, onClient, onServer);
+}
+
+/**
+ * @internal Whether a component kept across a navigation -- in a layout both
+ * pages share -- may carry what it holds from the page it was on to the
+ * next. Within one session only: what it shows was set under that session.
+ * And never from a page whose history is encrypted to one that is not --
+ * an `#[EncryptHistory(false)]` page in the same session: that page has no
+ * key, so what was typed under encryption would be written to the tab's
+ * storage in the clear (ADR 0019). useRemember() and useForm() alike start
+ * again from what they were given instead.
+ *
+ * @param {import('./router.js').RememberScope} from
+ * @param {import('./router.js').RememberScope} to
+ */
+export function carries(from, to) {
+  const sealed = (/** @type {{ key?: unknown }} */ scope) => scope.key !== null && scope.key !== undefined;
+  return (
+    /** @type {{ session?: unknown }} */ (from).session ===
+      /** @type {{ session?: unknown }} */ (to).session &&
+    (!sealed(from) || sealed(to))
+  );
+}
+
+/**
+ * @template T
+ * @param {T | (() => T)} initial used when nothing was remembered
+ * @param {string} key unique among the useRemember() calls on one page
+ * @returns {[T, (next: T | ((current: T) => T)) => void]}
+ */
+export function useRemember(initial, key) {
+  const router = useOptionalRouter();
+  const canRemember = typeof router?.rememberScope === 'function';
+
+  // The page this component mounted on: while a visit is mounting a page,
+  // that page, so a component on it never reads -- or writes -- the entry
+  // being left.
+  const scope = useRef(/** @type {import('./router.js').RememberScope | null} */ (null));
+  if (scope.current === null && canRemember) scope.current = router.rememberScope();
+
+  const initialRef = useRef(initial);
+  initialRef.current = initial;
+  const fresh = () => {
+    const start = initialRef.current;
+    return typeof start === 'function' ? /** @type {() => T} */ (start)() : start;
+  };
+
+  const [value, setValue] = useState(() => {
+    const kept = scope.current === null ? undefined : router.remembered(key, scope.current);
+    return kept !== undefined ? /** @type {T} */ (kept) : fresh();
+  });
+  // The initial value until hydration is done; see useHydrated().
+  const hydrated = useHydrated();
+
+  const latest = useRef(value);
+  latest.current = value;
+
+  useEffect(() => {
+    if (canRemember && scope.current !== null) router.remember(key, value, scope.current);
+  }, [canRemember, router, key, value]);
+
+  // A component kept across a navigation -- in a layout both pages share --
+  // belongs to the new page from then on. Back or forward to an entry that
+  // remembered a value brings that value back; a visit carries the current
+  // value onto the new entry -- within one session, and never from an
+  // encrypted page to one that is not (carries()). Otherwise nothing the
+  // component holds goes with it: it starts again from `initial`, and the
+  // old value is never remembered on the new page.
+  useEffect(() => {
+    if (!canRemember) return undefined;
+    return router.on('navigate', (event) => {
+      const next = router.rememberScope();
+      const previous = scope.current;
+      if (next === previous) return;
+      scope.current = next;
+
+      const kept =
+        /** @type {{ type?: string }} */ (event.detail).type === 'history'
+          ? router.remembered(key, next)
+          : undefined;
+
+      if (previous === null || !carries(previous, next)) {
+        setValue(kept !== undefined ? /** @type {T} */ (kept) : fresh());
+        return;
+      }
+
+      if (kept !== undefined) setValue(/** @type {T} */ (kept));
+      else router.remember(key, latest.current, next);
+    });
+  }, [canRemember, router, key]);
+
+  const set = useCallback((/** @type {T | ((current: T) => T)} */ next) => setValue(next), []);
+
+  return [hydrated ? value : fresh(), set];
+}

package/src/when-mounted.d.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from 'react';
+
+export interface WhenMountedProps {
+  /** Rendered on the server and while the page hydrates, in place of the children. */
+  fallback?: ReactNode;
+  /** Rendered in the browser alone: code that needs `window` as it renders. */
+  children?: ReactNode;
+}
+
+/**
+ * A client-only boundary: the fallback on the server and while hydrating,
+ * the children once mounted -- from the first render for a boundary that
+ * mounts after hydration.
+ */
+export declare function WhenMounted(props: WhenMountedProps): ReactNode;

package/src/when-mounted.js

@@ -0,0 +1,27 @@
+'use client';
+
+// <WhenMounted>: a client-only boundary.
+//
+// tinvar-spec.md, "Client router and components": "`<WhenMounted
+// fallback>` (Inertia v3.8.0+) as a client-only boundary for code that
+// needs `window`." What is inside renders in the browser alone: a map, a
+// chart reading the viewport, anything that reads `localStorage` as it
+// renders. The server renders the fallback, and so does the browser while
+// it hydrates -- the HTML the server sent must be what hydration finds, or
+// React throws it away and renders the page again. The children follow at
+// once.
+//
+// Read through useSyncExternalStore, as useHydrated() is, not a state set in
+// an effect: a boundary that mounts on the client after hydration -- on the
+// next page of a client visit, in a dialog opened later -- renders its
+// children from its first render, with no flash of the fallback and no
+// second render to get there.
+
+import { useHydrated } from './use-remember.js';
+
+/**
+ * @param {{ fallback?: unknown, children?: unknown }} props
+ */
+export function WhenMounted({ fallback = null, children = null }) {
+  return useHydrated() ? children : fallback;
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.