react-stateshape 0.2.0

package/src/useNavigationComplete.ts

@@ -0,0 +1,11 @@
+import { useContext, useEffect } from "react";
+import type { EventCallback, NavigationOptions } from "stateshape";
+import { RouteContext } from "./RouteContext.ts";
+
+export function useNavigationComplete(
+  callback: EventCallback<NavigationOptions>,
+) {
+  let route = useContext(RouteContext);
+
+  useEffect(() => route.on("navigationcomplete", callback), [route, callback]);
+}

package/src/useNavigationStart.ts

@@ -0,0 +1,9 @@
+import { useContext, useEffect } from "react";
+import type { EventCallback, NavigationOptions } from "stateshape";
+import { RouteContext } from "./RouteContext.ts";
+
+export function useNavigationStart(callback: EventCallback<NavigationOptions>) {
+  let route = useContext(RouteContext);
+
+  useEffect(() => route.on("navigationstart", callback), [route, callback]);
+}

package/src/useRoute.ts

@@ -0,0 +1,19 @@
+import { useContext, useMemo } from "react";
+import type { NavigationOptions } from "stateshape";
+import { RouteContext } from "./RouteContext.ts";
+import type { RenderCallback } from "./types/RenderCallback.ts";
+import { useExternalState } from "./useExternalState.ts";
+
+export function useRoute(callback?: RenderCallback<NavigationOptions>) {
+  let route = useContext(RouteContext);
+
+  useExternalState(route, callback, "navigation");
+
+  return useMemo(
+    () => ({
+      route,
+      at: route.at.bind(route),
+    }),
+    [route],
+  );
+}

package/src/useRouteLinks.ts

@@ -0,0 +1,22 @@
+import { type RefObject, useContext, useEffect } from "react";
+import type { ContainerElement, Route } from "stateshape";
+import { RouteContext } from "./RouteContext.ts";
+
+/**
+ * Converts plain HTML links to SPA route links.
+ *
+ * @param containerRef - A React Ref pointing to a container element.
+ * @param elements - An optional selector, or an HTML element, or a
+ * collection thereof, specifying the links inside the container to
+ * be converted to SPA route links. Default: `"a, area"`.
+ */
+export function useRouteLinks(
+  containerRef: RefObject<ContainerElement>,
+  elements?: Parameters<Route["observe"]>[1],
+): void {
+  let route = useContext(RouteContext);
+
+  useEffect(() => {
+    return route.observe(() => containerRef.current, elements);
+  }, [route, elements, containerRef]);
+}

package/src/useRouteState.ts

@@ -0,0 +1,56 @@
+import { useCallback } from "react";
+import {
+  compileURL,
+  type LocationValue,
+  type MatchState,
+  matchURL,
+  type NavigationOptions,
+  type URLData,
+} from "stateshape";
+import { useRoute } from "./useRoute.ts";
+
+export type SetRouteState<T extends LocationValue> = (
+  update: URLData<T> | ((state: MatchState<T>) => URLData<T>),
+) => void;
+
+/**
+ * Reads and sets URL parameters in a way similar to React's `useState()`.
+ * This hooks returns `[state, setState]`, where `state` contains path
+ * placeholder parameters and query parameters, `{ params?, query? }`.
+ *
+ * Note that the path placeholders, `params`, are only available if the
+ * `url` parameter is an output of a typed URL builder (like the one
+ * produced with *url-shape*).
+ */
+export function useRouteState<T extends LocationValue>(
+  url?: T,
+  options?: Omit<NavigationOptions, "href">,
+): [MatchState<T>, SetRouteState<T>] {
+  let { route } = useRoute();
+
+  let getState = useCallback(
+    (href?: T) => {
+      let resolvedHref = String(href ?? route.href);
+
+      return matchURL<T>(
+        url === undefined ? (resolvedHref as T) : url,
+        resolvedHref,
+      );
+    },
+    [url, route],
+  );
+
+  let setState = useCallback<SetRouteState<T>>(
+    (update) => {
+      let urlData = typeof update === "function" ? update(getState()) : update;
+
+      route.navigate({
+        ...options,
+        href: compileURL(url, urlData),
+      });
+    },
+    [url, route, options, getState],
+  );
+
+  return [getState(), setState];
+}

package/src/useTransientState.ts

@@ -0,0 +1,191 @@
+import { useCallback, useContext, useMemo, useRef, useState } from "react";
+import { isState, State } from "stateshape";
+import { TransientStateContext } from "./TransientStateContext.ts";
+import type { TransientState } from "./types/TransientState.ts";
+import {
+  type SetExternalStateValue,
+  useExternalState,
+} from "./useExternalState.ts";
+
+function createState(
+  initial = true,
+  pending = false,
+  error?: unknown,
+): TransientState {
+  return {
+    initial,
+    pending,
+    error,
+    time: Date.now(),
+  };
+}
+
+export type TransientStateOptions = {
+  /**
+   * Whether to track the action state silently (e.g. with a background
+   * action or an optimistic update).
+   *
+   * When set to `true`, the state's `pending` property doesn't switch
+   * to `true` in the pending state.
+   */
+  silent?: boolean;
+  /**
+   * Delays switching the action state's `pending` property to `true`
+   * in the pending state by the given number of milliseconds.
+   *
+   * Use case: to avoid flashing a process indicator if the action is
+   * likely to complete by the end of a short delay.
+   */
+  delay?: number;
+  /**
+   * Allows the async action to reject explicitly, along with exposing
+   * the action state's `error` property that goes by default.
+   */
+  throws?: boolean;
+};
+
+export type ControllableTransientState = TransientState & {
+  update: SetExternalStateValue<TransientState>;
+};
+
+/**
+ * The hook's `state` parameter is a unique string key or an instance of
+ * `State`. Providing a string key or a `State` instance allows to share the
+ * action state across multiple components. If the key is omitted or set to
+ * `null`, the action state stays locally scoped to the component where the
+ * hook is used.
+ */
+export function useTransientState<F extends (...args: unknown[]) => unknown>(
+  state: string | State<TransientState> | null,
+  action: F,
+): [
+  ControllableTransientState,
+  (...args: [...Parameters<F>, TransientStateOptions?]) => ReturnType<F>,
+];
+
+export function useTransientState(
+  state: string | State<TransientState> | null,
+): [ControllableTransientState];
+
+export function useTransientState<F extends (...args: unknown[]) => unknown>(
+  state: string | State<TransientState> | null,
+  action?: F,
+): [
+  ControllableTransientState,
+  ((...args: [...Parameters<F>, TransientStateOptions?]) => ReturnType<F>)?,
+] {
+  let stateMap = useContext(TransientStateContext);
+  let stateRef = useRef<State<TransientState> | null>(null);
+  let [stateItemInited, setStateItemInited] = useState(false);
+
+  let resolvedState = useMemo(() => {
+    if (isState<TransientState>(state)) return state;
+
+    if (typeof state === "string") {
+      let stateItem = stateMap.get(state);
+
+      if (!stateItem) {
+        stateItem = new State(createState());
+        stateMap.set(state, stateItem);
+
+        if (!stateItemInited) setStateItemInited(true);
+      }
+
+      return stateItem;
+    }
+
+    if (!stateRef.current) stateRef.current = new State(createState());
+
+    return stateRef.current;
+  }, [state, stateMap, stateItemInited]);
+
+  let [actionState, setActionState] = useExternalState(resolvedState);
+
+  let trackableAction = useCallback(
+    (...args: [...Parameters<F>, TransientStateOptions?]) => {
+      if (!action)
+        throw new Error(
+          "A trackable action is only available when the hook's 'action' parameter is set",
+        );
+
+      let options = args.at(-1) as TransientStateOptions | undefined;
+      let originalArgs = args.slice(0, -1) as Parameters<F>;
+      let result: unknown;
+
+      try {
+        result = action(...originalArgs);
+      } catch (error) {
+        setActionState((prevState) => ({
+          ...prevState,
+          ...createState(false, false, error),
+        }));
+
+        if (options?.throws) throw error;
+      }
+
+      if (result instanceof Promise) {
+        let delayedTracking: ReturnType<typeof setTimeout> | null = null;
+
+        if (!options?.silent) {
+          let delay = options?.delay;
+
+          if (delay === undefined)
+            setActionState((prevState) => ({
+              ...prevState,
+              ...createState(false, true),
+            }));
+          else
+            delayedTracking = setTimeout(() => {
+              setActionState((prevState) => ({
+                ...prevState,
+                ...createState(false, true),
+              }));
+
+              delayedTracking = null;
+            }, delay);
+        }
+
+        return result
+          .then((value) => {
+            if (delayedTracking !== null) clearTimeout(delayedTracking);
+
+            setActionState((prevState) => ({
+              ...prevState,
+              ...createState(false, false),
+            }));
+
+            return value;
+          })
+          .catch((error) => {
+            if (delayedTracking !== null) clearTimeout(delayedTracking);
+
+            setActionState((prevState) => ({
+              ...prevState,
+              ...createState(false, false, error),
+            }));
+
+            if (options?.throws) throw error;
+          }) as ReturnType<F>;
+      }
+
+      setActionState((prevState) => ({
+        ...prevState,
+        ...createState(false, false),
+      }));
+
+      return result as ReturnType<F>;
+    },
+    [action, setActionState],
+  );
+
+  return useMemo(() => {
+    let extendedActionState = {
+      ...actionState,
+      update: setActionState,
+    };
+
+    return action
+      ? [extendedActionState, trackableAction]
+      : [extendedActionState];
+  }, [action, trackableAction, actionState, setActionState]);
+}

package/src/useURL.ts

@@ -0,0 +1,9 @@
+import { useContext } from "react";
+import type { NavigationOptions } from "stateshape";
+import type { RenderCallback } from "./types/RenderCallback.ts";
+import { URLContext } from "./URLContext.ts";
+import { useExternalState } from "./useExternalState.ts";
+
+export function useURL(callback?: RenderCallback<NavigationOptions>) {
+  return useExternalState(useContext(URLContext), callback, "navigation");
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "include": ["./index.ts", "./playwright.config.ts", "./tests", "./src"],
+  "compilerOptions": {
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "lib": ["ESNext", "DOM"],
+    "target": "esnext",
+    "outDir": "dist",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "jsx": "react-jsx",
+    "allowImportingTsExtensions": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true
+  }
+}