react-statepod 0.4.0

package/dist/index.cjs

@@ -0,0 +1,324 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let statepod = require("statepod");
+let react = require("react");
+let react_jsx_runtime = require("react/jsx-runtime");
+
+const RouteContext = (0, react.createContext)(new statepod.Route(null, { autoStart: false }));
+
+const defaultRenderCallback = (render) => render();
+function useExternalState(state, callback = defaultRenderCallback, event) {
+  if (!(0, statepod.isState)(state)) throw new TypeError("'state' is not an instance of State");
+  let [, setRevision] = (0, react.useState)(-1);
+  let setValue = (0, react.useMemo)(() => state.setValue.bind(state), [state]);
+  let initialStateRevision = (0, react.useRef)(state.revision);
+  let shouldUpdate = (0, react.useRef)(false);
+  (0, react.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) render();
+    return () => {
+      unsubscribe();
+      initialStateRevision.current = state.revision;
+      shouldUpdate.current = false;
+    };
+  }, [
+    state,
+    callback,
+    event
+  ]);
+  return [state.getValue(), setValue];
+}
+
+function useRoute(callback) {
+  let route = (0, react.useContext)(RouteContext);
+  useExternalState(route, callback, "navigation");
+  return (0, react.useMemo)(() => ({
+    route,
+    at: route.at.bind(route)
+  }), [route]);
+}
+
+function useLinkProps({ href, target, onClick, ...props }) {
+  let { at, route } = useRoute();
+  let handleClick = (0, react.useCallback)((event) => {
+    onClick?.(event);
+    if (!event.defaultPrevented && (0, statepod.isRouteEvent)(event) && (!target || target === "_self")) {
+      event.preventDefault();
+      route.navigate((0, statepod.getNavigationOptions)(event.currentTarget));
+    }
+  }, [
+    route,
+    target,
+    onClick
+  ]);
+  return {
+    ...props,
+    href: href && String(href),
+    target,
+    onClick: handleClick,
+    "data-active": at(href, true)
+  };
+}
+
+const A = ({ children, ...props }) => {
+  return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("a", {
+    ...useLinkProps(props),
+    children
+  });
+};
+
+const Area = ({ alt, ...props }) => {
+  return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("area", {
+    ...useLinkProps(props),
+    alt
+  });
+};
+
+/**
+* A component providing a Route instance to the nested components.
+*/
+const RouteProvider = ({ href, children }) => {
+  let route = (0, react.useMemo)(() => {
+    if (href instanceof statepod.Route) return href;
+    else if (href === void 0 || typeof href === "string") return new statepod.Route(href);
+    else throw new Error("URLProvider's 'href' of unsupported type");
+  }, [href]);
+  (0, react.useEffect)(() => {
+    route.start();
+    return () => route.stop();
+  }, [route]);
+  return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(RouteContext.Provider, {
+    value: route,
+    children
+  });
+};
+
+const TransientStateContext = (0, react.createContext)(/* @__PURE__ */ new Map());
+
+const TransientStateProvider = ({ value, children }) => {
+  let defaultValueRef = (0, react.useRef)(null);
+  let stateMap = (0, react.useMemo)(() => {
+    if (value instanceof Map) return value;
+    if (typeof value === "object" && value !== null) return new Map(Object.entries(value).map(([key, value]) => [key, new statepod.State(value)]));
+    if (defaultValueRef.current === null) defaultValueRef.current = /* @__PURE__ */ new Map();
+    return defaultValueRef.current;
+  }, [value]);
+  return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(TransientStateContext.Provider, {
+    value: stateMap,
+    children
+  });
+};
+
+const URLContext = (0, react.createContext)(new statepod.URLState(null, { autoStart: false }));
+
+/**
+* A component providing a URL value to the nested components.
+*/
+const URLProvider = ({ href, children }) => {
+  let urlState = (0, react.useMemo)(() => {
+    if (href instanceof statepod.URLState) return href;
+    else if (href === void 0 || typeof href === "string") return new statepod.URLState(href);
+    else throw new Error("URLProvider's 'href' of unsupported type");
+  }, [href]);
+  (0, react.useEffect)(() => {
+    urlState.start();
+    return () => urlState.stop();
+  }, [urlState]);
+  return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(URLContext.Provider, {
+    value: urlState,
+    children
+  });
+};
+
+function useNavigationComplete(callback) {
+  let route = (0, react.useContext)(RouteContext);
+  (0, react.useEffect)(() => route.on("navigationcomplete", callback), [route, callback]);
+}
+
+function useNavigationStart(callback) {
+  let route = (0, react.useContext)(RouteContext);
+  (0, react.useEffect)(() => route.on("navigationstart", callback), [route, callback]);
+}
+
+/**
+* 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 = (0, react.useContext)(RouteContext);
+  (0, react.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 = (0, react.useCallback)((href) => {
+    let resolvedHref = String(href ?? route.href);
+    return (0, statepod.matchURL)(url === void 0 ? resolvedHref : url, resolvedHref);
+  }, [url, route]);
+  let setState = (0, react.useCallback)((update) => {
+    let urlData = typeof update === "function" ? update(getState()) : update;
+    route.navigate({
+      ...options,
+      href: (0, statepod.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 = (0, react.useContext)(TransientStateContext);
+  let stateRef = (0, react.useRef)(null);
+  let [stateItemInited, setStateItemInited] = (0, react.useState)(false);
+  let [actionState, setActionState] = useExternalState((0, react.useMemo)(() => {
+    if ((0, statepod.isState)(state)) return state;
+    if (typeof state === "string") {
+      let stateItem = stateMap.get(state);
+      if (!stateItem) {
+        stateItem = new statepod.State(createState());
+        stateMap.set(state, stateItem);
+        if (!stateItemInited) setStateItemInited(true);
+      }
+      return stateItem;
+    }
+    if (!stateRef.current) stateRef.current = new statepod.State(createState());
+    return stateRef.current;
+  }, [
+    state,
+    stateMap,
+    stateItemInited
+  ]));
+  let trackableAction = (0, react.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 (0, react.useMemo)(() => {
+    let extendedActionState = {
+      ...actionState,
+      update: setActionState
+    };
+    return action ? [extendedActionState, trackableAction] : [extendedActionState];
+  }, [
+    action,
+    trackableAction,
+    actionState,
+    setActionState
+  ]);
+}
+
+function useURL(callback) {
+  return useExternalState((0, react.useContext)(URLContext), callback, "navigation");
+}
+
+exports.A = A;
+exports.Area = Area;
+exports.RouteContext = RouteContext;
+exports.RouteProvider = RouteProvider;
+exports.TransientStateContext = TransientStateContext;
+exports.TransientStateProvider = TransientStateProvider;
+exports.URLContext = URLContext;
+exports.URLProvider = URLProvider;
+exports.useExternalState = useExternalState;
+exports.useLinkProps = useLinkProps;
+exports.useNavigationComplete = useNavigationComplete;
+exports.useNavigationStart = useNavigationStart;
+exports.useRoute = useRoute;
+exports.useRouteLinks = useRouteLinks;
+exports.useRouteState = useRouteState;
+exports.useTransientState = useTransientState;
+exports.useURL = useURL;
+Object.keys(statepod).forEach(function(k) {
+  if (k !== "default" && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+    enumerable: true,
+    get: function() {
+      return statepod[k];
+    }
+  });
+});

package/dist/index.d.ts

@@ -0,0 +1,171 @@
+import * as statepod from "statepod";
+import { ContainerElement, EventCallback, LocationValue, MatchState, NavigationOptions, Route, State, StatePayloadMap, URLData, URLState } from "statepod";
+import * as react from "react";
+import { AnchorHTMLAttributes, AreaHTMLAttributes, MouseEvent, ReactNode, RefObject } from "react";
+export * from "statepod";
+
+type EnhanceHref<T extends {
+  href?: string | undefined;
+}> = Omit<T, "href"> & {
+  href?: LocationValue;
+};
+
+type LinkNavigationProps = {
+  "data-spa"?: NavigationOptions["spa"];
+  "data-history"?: NavigationOptions["history"];
+  "data-scroll"?: NavigationOptions["scroll"];
+  "data-id"?: NavigationOptions["id"];
+};
+
+type AProps = EnhanceHref<AnchorHTMLAttributes<HTMLAnchorElement>> & LinkNavigationProps;
+
+declare const A: ({
+  children,
+  ...props
+}: AProps) => react.JSX.Element;
+
+type AreaProps = EnhanceHref<AreaHTMLAttributes<HTMLAreaElement>> & LinkNavigationProps;
+
+declare const Area: ({
+  alt,
+  ...props
+}: AreaProps) => react.JSX.Element;
+
+declare const RouteContext: react.Context<Route>;
+
+type RouteProviderProps = {
+  href?: string | Route | undefined;
+  children?: ReactNode;
+};
+/**
+ * A component providing a Route instance to the nested components.
+ */
+declare const RouteProvider: ({
+  href,
+  children
+}: RouteProviderProps) => react.JSX.Element;
+
+type TransientState = {
+  initial?: boolean | undefined;
+  pending?: boolean | undefined;
+  error?: unknown;
+  time?: number | undefined;
+};
+
+declare const TransientStateContext: react.Context<Map<string, State<TransientState, statepod.StatePayloadMap<TransientState>>>>;
+
+type TransientStateProviderProps = {
+  value?: Record<string, TransientState> | Map<string, State<TransientState>> | null | undefined;
+  children?: ReactNode;
+};
+declare const TransientStateProvider: ({
+  value,
+  children
+}: TransientStateProviderProps) => react.JSX.Element;
+
+type RenderCallback<T> = (render: () => void, payload: T) => boolean | undefined | void;
+
+declare const URLContext: react.Context<URLState<statepod.URLStatePayloadMap>>;
+
+type URLProviderProps = {
+  href?: string | URLState | undefined;
+  children?: ReactNode;
+};
+/**
+ * A component providing a URL value to the nested components.
+ */
+declare const URLProvider: ({
+  href,
+  children
+}: URLProviderProps) => react.JSX.Element;
+
+type SetExternalStateValue<T, P extends StatePayloadMap<T> = StatePayloadMap<T>> = State<T, P>["setValue"];
+declare function useExternalState<T, P extends StatePayloadMap<T>>(state: State<T, P>, callback?: RenderCallback<P["update"]> | boolean): [T, SetExternalStateValue<T, P>];
+declare 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>];
+
+declare function useLinkProps<T extends AProps | AreaProps>({
+  href,
+  target,
+  onClick,
+  ...props
+}: T): Omit<T, "href" | "target" | "onClick"> & {
+  href: string | undefined;
+  target: string | (string & {}) | undefined;
+  onClick: (event: MouseEvent<HTMLAnchorElement & HTMLAreaElement>) => void;
+  "data-active": boolean | undefined;
+};
+
+declare function useNavigationComplete(callback: EventCallback<NavigationOptions>): void;
+
+declare function useNavigationStart(callback: EventCallback<NavigationOptions>): void;
+
+declare function useRoute(callback?: RenderCallback<NavigationOptions>): {
+  route: statepod.Route;
+  at: {
+    <P extends statepod.LocationPattern>(urlPattern: P): boolean;
+    <P extends statepod.LocationPattern, X>(urlPattern: P, x: X | statepod.MatchHandler<P, X>): X | undefined;
+    <P extends statepod.LocationPattern, X, Y>(urlPattern: P, x: X | statepod.MatchHandler<P, X>, y: Y | statepod.MatchHandler<P, Y>): X | Y;
+  };
+};
+
+/**
+ * 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"`.
+ */
+declare function useRouteLinks(containerRef: RefObject<ContainerElement>, elements?: Parameters<Route["observe"]>[1]): void;
+
+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*).
+ */
+declare function useRouteState<T extends LocationValue>(url?: T, options?: Omit<NavigationOptions, "href">): [MatchState<T>, SetRouteState<T>];
+
+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;
+};
+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.
+ */
+declare function useTransientState<F extends (...args: unknown[]) => unknown>(state: string | State<TransientState> | null, action: F): [ControllableTransientState, (...args: [...Parameters<F>, TransientStateOptions?]) => ReturnType<F>];
+declare function useTransientState(state: string | State<TransientState> | null): [ControllableTransientState];
+
+declare function useURL(callback?: RenderCallback<NavigationOptions>): [string, (update: string | statepod.StateUpdate<string>) => void];
+
+export { A, AProps, Area, AreaProps, ControllableTransientState, EnhanceHref, LinkNavigationProps, RenderCallback, RouteContext, RouteProvider, RouteProviderProps, SetExternalStateValue, SetRouteState, TransientState, TransientStateContext, TransientStateOptions, TransientStateProvider, TransientStateProviderProps, URLContext, URLProvider, URLProviderProps, useExternalState, useLinkProps, useNavigationComplete, useNavigationStart, useRoute, useRouteLinks, useRouteState, useTransientState, useURL };