react-stateshape 0.2.0

package/dist/index.mjs

@@ -0,0 +1,300 @@
+import { Route, State, URLState, compileURL, getNavigationOptions, isRouteEvent, isState, matchURL } from "stateshape";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+
+export * from "stateshape"
+
+const RouteContext = createContext(new Route(null, { autoStart: false }));
+
+function useLinkClick({ target, onClick }) {
+  let route = useContext(RouteContext);
+  return useCallback((event) => {
+    onClick?.(event);
+    if (!event.defaultPrevented && isRouteEvent(event) && (!target || target === "_self")) {
+      event.preventDefault();
+      route.navigate(getNavigationOptions(event.currentTarget));
+    }
+  }, [
+    route,
+    target,
+    onClick
+  ]);
+}
+
+const A = ({ children, ...props }) => {
+  let handleClick = useLinkClick(props);
+  return /* @__PURE__ */ jsx("a", {
+    ...props,
+    href: String(props.href),
+    onClick: handleClick,
+    children
+  });
+};
+
+const Area = ({ alt, ...props }) => {
+  let handleClick = useLinkClick(props);
+  return /* @__PURE__ */ jsx("area", {
+    ...props,
+    href: String(props.href),
+    onClick: handleClick,
+    alt
+  });
+};
+
+/**
+* A component providing a Route instance to the nested components.
+*/
+const RouteProvider = ({ href, children }) => {
+  let route = useMemo(() => {
+    if (href instanceof Route) return href;
+    else if (href === void 0 || typeof href === "string") return new Route(href);
+    else throw new Error("URLProvider's 'href' of unsupported type");
+  }, [href]);
+  useEffect(() => {
+    route.start();
+    return () => route.stop();
+  }, [route]);
+  return /* @__PURE__ */ jsx(RouteContext.Provider, {
+    value: route,
+    children
+  });
+};
+
+const TransientStateContext = createContext(/* @__PURE__ */ new Map());
+
+const TransientStateProvider = ({ value, children }) => {
+  let defaultValueRef = useRef(null);
+  let stateMap = useMemo(() => {
+    if (value instanceof Map) return value;
+    if (typeof value === "object" && value !== null) return new Map(Object.entries(value).map(([key, value]) => [key, new State(value)]));
+    if (defaultValueRef.current === null) defaultValueRef.current = /* @__PURE__ */ new Map();
+    return defaultValueRef.current;
+  }, [value]);
+  return /* @__PURE__ */ jsx(TransientStateContext.Provider, {
+    value: stateMap,
+    children
+  });
+};
+
+const URLContext = createContext(new URLState(null, { autoStart: false }));
+
+/**
+* A component providing a URL value to the nested components.
+*/
+const URLProvider = ({ href, children }) => {
+  let urlState = useMemo(() => {
+    if (href instanceof URLState) return href;
+    else if (href === void 0 || typeof href === "string") return new URLState(href);
+    else throw new Error("URLProvider's 'href' of unsupported type");
+  }, [href]);
+  useEffect(() => {
+    urlState.start();
+    return () => urlState.stop();
+  }, [urlState]);
+  return /* @__PURE__ */ jsx(URLContext.Provider, {
+    value: urlState,
+    children
+  });
+};
+
+const defaultRenderCallback = (render) => render();
+function useExternalState(state, callback = defaultRenderCallback, event) {
+  if (!isState(state)) throw new Error("'state' is not an instance of PortableState");
+  let [, setRevision] = useState(-1);
+  let setValue = useMemo(() => state.setValue.bind(state), [state]);
+  let initialStateRevision = useRef(state.revision);
+  let shouldUpdate = useRef(false);
+  useEffect(() => {
+    state.start();
+    if (callback === false) return;
+    shouldUpdate.current = true;
+    let render = () => {
+      if (shouldUpdate.current) setRevision(Math.random());
+    };
+    let resolvedCallback = typeof callback === "function" ? callback : defaultRenderCallback;
+    let unsubscribe = state.on(event ?? "update", (payload) => {
+      resolvedCallback(render, payload);
+    });
+    if (state.revision !== initialStateRevision.current) setRevision(Math.random());
+    return () => {
+      unsubscribe();
+      initialStateRevision.current = state.revision;
+      shouldUpdate.current = false;
+    };
+  }, [
+    state,
+    callback,
+    event
+  ]);
+  return [state.getValue(), setValue];
+}
+
+function useNavigationComplete(callback) {
+  let route = useContext(RouteContext);
+  useEffect(() => route.on("navigationcomplete", callback), [route, callback]);
+}
+
+function useNavigationStart(callback) {
+  let route = useContext(RouteContext);
+  useEffect(() => route.on("navigationstart", callback), [route, callback]);
+}
+
+function useRoute(callback) {
+  let route = useContext(RouteContext);
+  useExternalState(route, callback, "navigation");
+  return useMemo(() => ({
+    route,
+    at: route.at.bind(route)
+  }), [route]);
+}
+
+/**
+* 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"`.
+*/
+function useRouteLinks(containerRef, elements) {
+  let route = useContext(RouteContext);
+  useEffect(() => {
+    return route.observe(() => containerRef.current, elements);
+  }, [
+    route,
+    elements,
+    containerRef
+  ]);
+}
+
+/**
+* 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*).
+*/
+function useRouteState(url, options) {
+  let { route } = useRoute();
+  let getState = useCallback((href) => {
+    let resolvedHref = String(href ?? route.href);
+    return matchURL(url === void 0 ? resolvedHref : url, resolvedHref);
+  }, [url, route]);
+  let setState = useCallback((update) => {
+    let urlData = typeof update === "function" ? update(getState()) : update;
+    route.navigate({
+      ...options,
+      href: compileURL(url, urlData)
+    });
+  }, [
+    url,
+    route,
+    options,
+    getState
+  ]);
+  return [getState(), setState];
+}
+
+function createState(initial = true, pending = false, error) {
+  return {
+    initial,
+    pending,
+    error,
+    time: Date.now()
+  };
+}
+function useTransientState(state, action) {
+  let stateMap = useContext(TransientStateContext);
+  let stateRef = useRef(null);
+  let [stateItemInited, setStateItemInited] = useState(false);
+  let [actionState, setActionState] = useExternalState(useMemo(() => {
+    if (isState(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 trackableAction = useCallback((...args) => {
+    if (!action) throw new Error("A trackable action is only available when the hook's 'action' parameter is set");
+    let options = args.at(-1);
+    let originalArgs = args.slice(0, -1);
+    let result;
+    try {
+      result = action(...originalArgs);
+    } catch (error) {
+      setActionState((prevState) => ({
+        ...prevState,
+        ...createState(false, false, error)
+      }));
+      if (options?.throws) throw error;
+    }
+    if (result instanceof Promise) {
+      let delayedTracking = null;
+      if (!options?.silent) {
+        let delay = options?.delay;
+        if (delay === void 0) 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;
+      });
+    }
+    setActionState((prevState) => ({
+      ...prevState,
+      ...createState(false, false)
+    }));
+    return result;
+  }, [action, setActionState]);
+  return useMemo(() => {
+    let extendedActionState = {
+      ...actionState,
+      update: setActionState
+    };
+    return action ? [extendedActionState, trackableAction] : [extendedActionState];
+  }, [
+    action,
+    trackableAction,
+    actionState,
+    setActionState
+  ]);
+}
+
+function useURL(callback) {
+  return useExternalState(useContext(URLContext), callback, "navigation");
+}
+
+export { A, Area, RouteContext, RouteProvider, TransientStateContext, TransientStateProvider, URLContext, URLProvider, useExternalState, useLinkClick, useNavigationComplete, useNavigationStart, useRoute, useRouteLinks, useRouteState, useTransientState, useURL };

package/index.ts

@@ -0,0 +1,24 @@
+export * from "stateshape";
+export * from "./src/A.tsx";
+export * from "./src/Area.tsx";
+export * from "./src/RouteContext.ts";
+export * from "./src/RouteProvider.tsx";
+export * from "./src/TransientStateContext.ts";
+export * from "./src/TransientStateProvider.tsx";
+export * from "./src/types/AProps.ts";
+export * from "./src/types/AreaProps.ts";
+export * from "./src/types/EnhanceHref.ts";
+export * from "./src/types/LinkNavigationProps.ts";
+export * from "./src/types/RenderCallback.ts";
+export * from "./src/types/TransientState.ts";
+export * from "./src/URLContext.ts";
+export * from "./src/URLProvider.tsx";
+export * from "./src/useExternalState.ts";
+export * from "./src/useLinkClick.ts";
+export * from "./src/useNavigationComplete.ts";
+export * from "./src/useNavigationStart.ts";
+export * from "./src/useRoute.ts";
+export * from "./src/useRouteLinks.ts";
+export * from "./src/useRouteState.ts";
+export * from "./src/useTransientState.ts";
+export * from "./src/useURL.ts";

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "react-stateshape",
+  "version": "0.2.0",
+  "description": "Concise shared state management and routing in React apps",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "demo": "npx auxsrv tests/Shared_state_without_Context",
+    "preversion": "npx npm-run-all shape test",
+    "shape": "npx codeshape",
+    "t3": "npx auxsrv tests/Tic-tac-toe",
+    "test": "npx playwright test --project=chromium",
+    "typecheck": "npx codeshape --typecheck-only"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/axtk/react-stateshape.git"
+  },
+  "keywords": [
+    "state",
+    "state management",
+    "react state management",
+    "shared state",
+    "global state",
+    "routing",
+    "react router"
+  ],
+  "license": "MIT",
+  "author": "axtk",
+  "peerDependencies": {
+    "react": ">=16.8"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.58.2",
+    "@types/node": "^25.3.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "auxsrv": "^0.3.1",
+    "immer": "^11.1.4",
+    "react-dom": "^19.2.4",
+    "url-shape": "^1.3.13",
+    "zod": "^4.3.6"
+  },
+  "dependencies": {
+    "stateshape": "^0.2.0"
+  }
+}

package/src/A.tsx

@@ -0,0 +1,12 @@
+import type { AProps } from "./types/AProps.ts";
+import { useLinkClick } from "./useLinkClick.ts";
+
+export const A = ({ children, ...props }: AProps) => {
+  let handleClick = useLinkClick(props);
+
+  return (
+    <a {...props} href={String(props.href)} onClick={handleClick}>
+      {children}
+    </a>
+  );
+};

package/src/Area.tsx

@@ -0,0 +1,15 @@
+import type { AreaProps } from "./types/AreaProps.ts";
+import { useLinkClick } from "./useLinkClick.ts";
+
+export const Area = ({ alt, ...props }: AreaProps) => {
+  let handleClick = useLinkClick(props);
+
+  return (
+    <area
+      {...props}
+      href={String(props.href)}
+      onClick={handleClick}
+      alt={alt}
+    />
+  );
+};

package/src/RouteContext.ts

@@ -0,0 +1,6 @@
+import { createContext } from "react";
+import { Route } from "stateshape";
+
+export const RouteContext = createContext(
+  new Route(null, { autoStart: false }),
+);

package/src/RouteProvider.tsx

@@ -0,0 +1,30 @@
+import { type ReactNode, useEffect, useMemo } from "react";
+import { Route } from "stateshape";
+import { RouteContext } from "./RouteContext.ts";
+
+export type RouteProviderProps = {
+  href?: string | Route | undefined;
+  children?: ReactNode;
+};
+
+/**
+ * A component providing a Route instance to the nested components.
+ */
+export const RouteProvider = ({ href, children }: RouteProviderProps) => {
+  let route = useMemo(() => {
+    if (href instanceof Route) return href;
+    else if (href === undefined || typeof href === "string")
+      return new Route(href);
+    else throw new Error("URLProvider's 'href' of unsupported type");
+  }, [href]);
+
+  useEffect(() => {
+    route.start();
+
+    return () => route.stop();
+  }, [route]);
+
+  return (
+    <RouteContext.Provider value={route}>{children}</RouteContext.Provider>
+  );
+};

package/src/TransientStateContext.ts

@@ -0,0 +1,7 @@
+import { createContext } from "react";
+import type { State } from "stateshape";
+import type { TransientState } from "./types/TransientState.ts";
+
+export const TransientStateContext = createContext(
+  new Map<string, State<TransientState>>(),
+);

package/src/TransientStateProvider.tsx

@@ -0,0 +1,40 @@
+import { type ReactNode, useMemo, useRef } from "react";
+import { State } from "stateshape";
+import { TransientStateContext } from "./TransientStateContext.ts";
+import type { TransientState } from "./types/TransientState.ts";
+
+export type TransientStateProviderProps = {
+  value?:
+    | Record<string, TransientState>
+    | Map<string, State<TransientState>>
+    | null
+    | undefined;
+  children?: ReactNode;
+};
+
+export const TransientStateProvider = ({
+  value,
+  children,
+}: TransientStateProviderProps) => {
+  let defaultValueRef = useRef<Map<string, State<TransientState>> | null>(null);
+
+  let stateMap = useMemo(() => {
+    if (value instanceof Map) return value;
+
+    if (typeof value === "object" && value !== null)
+      return new Map(
+        Object.entries(value).map(([key, value]) => [key, new State(value)]),
+      );
+
+    if (defaultValueRef.current === null)
+      defaultValueRef.current = new Map<string, State<TransientState>>();
+
+    return defaultValueRef.current;
+  }, [value]);
+
+  return (
+    <TransientStateContext.Provider value={stateMap}>
+      {children}
+    </TransientStateContext.Provider>
+  );
+};

package/src/URLContext.ts

@@ -0,0 +1,6 @@
+import { createContext } from "react";
+import { URLState } from "stateshape";
+
+export const URLContext = createContext(
+  new URLState(null, { autoStart: false }),
+);

package/src/URLProvider.tsx

@@ -0,0 +1,28 @@
+import { type ReactNode, useEffect, useMemo } from "react";
+import { URLState } from "stateshape";
+import { URLContext } from "./URLContext.ts";
+
+export type URLProviderProps = {
+  href?: string | URLState | undefined;
+  children?: ReactNode;
+};
+
+/**
+ * A component providing a URL value to the nested components.
+ */
+export const URLProvider = ({ href, children }: URLProviderProps) => {
+  let urlState = useMemo(() => {
+    if (href instanceof URLState) return href;
+    else if (href === undefined || typeof href === "string")
+      return new URLState(href);
+    else throw new Error("URLProvider's 'href' of unsupported type");
+  }, [href]);
+
+  useEffect(() => {
+    urlState.start();
+
+    return () => urlState.stop();
+  }, [urlState]);
+
+  return <URLContext.Provider value={urlState}>{children}</URLContext.Provider>;
+};

package/src/types/AProps.ts

@@ -0,0 +1,6 @@
+import type { AnchorHTMLAttributes } from "react";
+import type { EnhanceHref } from "./EnhanceHref.ts";
+import type { LinkNavigationProps } from "./LinkNavigationProps.ts";
+
+export type AProps = EnhanceHref<AnchorHTMLAttributes<HTMLAnchorElement>> &
+  LinkNavigationProps;

package/src/types/AreaProps.ts

@@ -0,0 +1,6 @@
+import type { AreaHTMLAttributes } from "react";
+import type { EnhanceHref } from "./EnhanceHref.ts";
+import type { LinkNavigationProps } from "./LinkNavigationProps.ts";
+
+export type AreaProps = EnhanceHref<AreaHTMLAttributes<HTMLAreaElement>> &
+  LinkNavigationProps;

package/src/types/EnhanceHref.ts

@@ -0,0 +1,8 @@
+import type { LocationValue } from "stateshape";
+
+export type EnhanceHref<T extends { href?: string | undefined }> = Omit<
+  T,
+  "href"
+> & {
+  href?: LocationValue;
+};

package/src/types/LinkNavigationProps.ts

@@ -0,0 +1,8 @@
+import type { NavigationOptions } from "stateshape";
+
+export type LinkNavigationProps = {
+  "data-spa"?: NavigationOptions["spa"];
+  "data-history"?: NavigationOptions["history"];
+  "data-scroll"?: NavigationOptions["scroll"];
+  "data-id"?: NavigationOptions["id"];
+};

package/src/types/RenderCallback.ts

@@ -0,0 +1,4 @@
+export type RenderCallback<T> = (
+  render: () => void,
+  payload: T,
+) => boolean | undefined | void;

package/src/types/TransientState.ts

@@ -0,0 +1,6 @@
+export type TransientState = {
+  initial?: boolean | undefined;
+  pending?: boolean | undefined;
+  error?: unknown;
+  time?: number | undefined;
+};

package/src/useExternalState.ts

@@ -0,0 +1,76 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { isState, type State, type StatePayloadMap } from "stateshape";
+import type { RenderCallback } from "./types/RenderCallback.ts";
+
+export type SetExternalStateValue<
+  T,
+  P extends StatePayloadMap<T> = StatePayloadMap<T>,
+> = State<T, P>["setValue"];
+
+const defaultRenderCallback = (render: () => void) => render();
+
+export function useExternalState<T, P extends StatePayloadMap<T>>(
+  state: State<T, P>,
+  callback?: RenderCallback<P["update"]> | boolean,
+): [T, SetExternalStateValue<T, P>];
+
+export function useExternalState<
+  T,
+  P extends StatePayloadMap<T>,
+  E extends keyof P,
+>(
+  state: State<T, P>,
+  callback?: RenderCallback<P[E]> | boolean,
+  event?: E,
+): [T, SetExternalStateValue<T, P>];
+
+export function useExternalState<
+  T,
+  P extends StatePayloadMap<T>,
+  E extends string,
+>(
+  state: State<T, P>,
+  callback: RenderCallback<P[E]> | boolean = defaultRenderCallback,
+  event?: E,
+): [T, SetExternalStateValue<T, P>] {
+  if (!isState<T, P>(state))
+    throw new Error("'state' is not an instance of PortableState");
+
+  let [, setRevision] = useState(-1);
+
+  let setValue = useMemo(() => state.setValue.bind(state), [state]);
+  let initialStateRevision = useRef(state.revision);
+  let shouldUpdate = useRef(false);
+
+  useEffect(() => {
+    // Start the state if it's not started yet
+    state.start();
+
+    if (callback === false) return;
+
+    shouldUpdate.current = true;
+
+    let render = () => {
+      // Use `setRevision()` as long as the component is mounted
+      if (shouldUpdate.current) setRevision(Math.random());
+    };
+
+    let resolvedCallback =
+      typeof callback === "function" ? callback : defaultRenderCallback;
+
+    let unsubscribe = state.on(event ?? "update", (payload) => {
+      resolvedCallback(render, payload as P[E]);
+    });
+
+    if (state.revision !== initialStateRevision.current)
+      setRevision(Math.random());
+
+    return () => {
+      unsubscribe();
+      initialStateRevision.current = state.revision;
+      shouldUpdate.current = false;
+    };
+  }, [state, callback, event]);
+
+  return [state.getValue(), setValue];
+}

package/src/useLinkClick.ts

@@ -0,0 +1,29 @@
+import {
+  type MouseEvent as ReactMouseEvent,
+  useCallback,
+  useContext,
+} from "react";
+import { getNavigationOptions, isRouteEvent } from "stateshape";
+import { RouteContext } from "./RouteContext.ts";
+import type { AProps } from "./types/AProps.ts";
+import type { AreaProps } from "./types/AreaProps.ts";
+
+export function useLinkClick({ target, onClick }: AProps | AreaProps) {
+  let route = useContext(RouteContext);
+
+  return useCallback(
+    (event: ReactMouseEvent<HTMLAnchorElement & HTMLAreaElement>) => {
+      onClick?.(event);
+
+      if (
+        !event.defaultPrevented &&
+        isRouteEvent(event) &&
+        (!target || target === "_self")
+      ) {
+        event.preventDefault();
+        route.navigate(getNavigationOptions(event.currentTarget));
+      }
+    },
+    [route, target, onClick],
+  );
+}