react-statepod 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Alexander Tkačenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,514 @@
+# react-statepod
+
+A shared state management and routing lib for React apps. Under the hood, routing is shared state management, too, with the shared data being the URL.
+
+<details>
+<summary>Why think of another state management lib and how it compares to others</summary><br>
+
+With several options available, state management in React apps still feels more cumbersome than it could be. With the React's local state mental model in mind, we might expect that a shared state management lib—
+
+(1) has a simple API introducing a minimal set of entities,<br>
+(2) requires minimal changes to move local state to shared state,<br>
+(3) straightforwardly supports SSR without workaround APIs.
+
+The popular approaches to state management seem to depart from at least one of these points:
+
+Apparently focusing on other aspects, **Redux Toolkit** and **MobX** don't fulfill any of the points listed above by bringing in their own mental models of shared state management with an inventory of new concepts and approaches.
+
+**Zustand** does have a simple and minimalist API (point (1) fulfilled), but it's not quite similar to the React's state API, which leads to significant code rewrites while migrating from local state to shared state (so simplicity alone is not sufficient, point (2) unfulfilled). The Zustand's SSR setup requires that the default React store setup be transitioned to vanilla stores<sup>[[1](https://github.com/pmndrs/zustand/tree/main#react-context)]</sup>, which adds another state management pattern to the code and yet another sizable migration rewrite (point (3) unmet). Also, subjectively, Zustand introduces patterns that look unidiomatic in React, like calling methods on Zustand's store hooks (`useXStore.subscribe()`)<sup>[[2](https://github.com/pmndrs/zustand/tree/main#transient-updates-for-often-occurring-state-changes)]</sup>.
+
+With a useState-like API, **Jotai** is the closest match (points (1) and (2) fulfilled). Still, Jotai requires a workaround API, a special hook, to set up SSR<sup>[[3](https://jotai.org/docs/utilities/ssr)]</sup> (point (3) unmet). Also, subjectively, the Jotai's core `atom()` function with its elaborate capabilities is an overkill for state management that looks hard to tree-shake.
+
+The `useExternalState()` hook of `react-statepod` is an attempt to come up with a mostly self-explanatory lightweight useState-like approach to shared state management by focusing on the three points listed above. The lib's other hooks are built around the common practical use cases for `useExternalState()`.
+
+</details>
+
+---
+
+Contents: [useExternalState](#useexternalstate) · [useRoute](#useroute) · [useNavigationStart / useNavigationComplete](#usenavigationstart--usenavigationcomplete) · [useRouteState](#useroutestate) · [Type-safe routes](#type-safe-routes) · [useTransientState](#usetransientstate) · [Annotated examples](#annotated-examples) · [Internals](#internals)
+
+## useExternalState
+
+This hook is focused on simplicity of both setting up shared state from scratch and migrating from local state. The equally common latter scenario is often missed out with commonly used approaches resulting in sizable code rewrites.
+
+### Shared state
+
+Move local state to the full-fledged shared state with minimal paradigm shift and minimal code changes:
+
+```diff
++ import { State, useExternalState } from "react-statepod";
++
++ const counterState = new State(0);
+
+  const Counter = () => {
+-   const [counter, setCounter] = useState(0);
++   const [counter, setCounter] = useExternalState(counterState);
+
+    const handleClick = () => setCounter((value) => value + 1);
+
+    return <button onClick={handleClick}>+ {counter}</button>;
+  };
+
+  const ResetButton = () => {
+-   const [, setCounter] = useState(0);
++   const [, setCounter] = useExternalState(counterState);
+
+    const handleClick = () => setCounter(0);
+
+    return <button onClick={handleClick}>×</button>;
+  };
+
+  const App = () => <><Counter/>{" "}<ResetButton/></>;
+```
+
+### Sharing state via Context
+
+With SSR, it's common practice to put shared values into React Context rather than module-level variables to avoid cross-request data sharing. The same applies to external state. Provide external state to multiple components via React Context like any data in a React app:
+
+```diff
+- const counterState = new State(0);
++ const AppContext = createContext(new State(0));
+```
+
+```diff
+- const [counter, setCounter] = useExternalState(counterState);
++ const [counter, setCounter] = useExternalState(useContext(AppContext));
+```
+
+```jsx
+const App = () => (
+  <AppContext.Provider value={new State(42)}>
+    <PlusButton/>{" "}<Display/>
+  </AppContext.Provider>
+);
+```
+
+⬥ Like any data in a React app, the external state can also be split across multiple instances of `State` and multiple Contexts to maintain clearer semantic boundaries and more targeted data update subscriptions.
+
+⬥ Note that updating the `State` value doesn't change the instance's reference sitting in the React Context and therefore doesn't cause updates of the entire Context. Only the components subscribed to updates of the particular `State` instance by means of `useExternalState(state)` will be notified to re-render.
+
+### Filtering state updates
+
+⬥ One way of reducing re-renders in response to state changes is having multiple tightly scoped `State` instances in the app instead of having a larger chunk of disparate data in a single `State`. Yet another way is using the optional render callback of `useExternalState(state, callback)` for more fine-grained control over component's re-renders within a state subscription:
+
+```js
+const itemState = new State({/* A map of `<id>: <item>` */});
+
+// Renders a specific item from `itemState`
+const ItemCard = ({ id }) => {
+  const [items, setItems] = useExternalState(itemState, (render, { current, previous }) => {
+    // Assuming that the items have a `timestamp` property, re-render
+    // `ItemCard` only if the relevant item's `timestamp` has increased
+    if (current[id].timestamp > previous[id].timestamp) render();
+  });
+
+  // ...
+};
+```
+
+⬥ Use the optional `false` parameter in `useExternalState(state, false)` to tell the hook not to subscribe the component to tracking the external state updates altogether. A use case for it is when a component makes use of the external state value setter without using the state value itself. The `false` parameter could have been used in the `ResetButton` in the first example above, but in many cases with lightweight component renders it might be unnecessary, since React automatically skips updating the DOM when there are no changes.
+
+⬥ Splitting the app data into multiple `State` instances and the `useExternalState()`'s render callback serve a similar purpose as state slices and selectors adopted by some state management libs to offer fine-grained control over re-renders. A subtle difference in these approaches is that the state splitting and the render callback are more imperative and explicit about the conditions of re-renders than the state slices and selectors.
+
+### Integration with Immer
+
+Immer can be used with state setters returned from `useExternalState()` just the same way as [with `useState()`](https://immerjs.github.io/immer/example-setstate#usestate--immer) to facilitate deeply nested data changes.
+
+### Persistence across page reloads
+
+Replace `State` with `PersistentState` as shown below to get the state data synced to the specified `key` in `localStorage` and restored on page reload. After a persistent state is created, use it with `useExternalState(state)` the same way as `State` instances.
+
+```js
+import { PersistentState } from "react-statepod";
+
+const counterState = new PersistentState(0, { key: "counter" });
+```
+
+⬥ Set `options.session` to `true` in `new PersistentState(value, options)` to use `sessionStorage`.
+
+⬥ Set `options.serialize()` and `options.deserialize()` to override the default data transform behavior, including filtering and rearranging the data (it's `JSON.stringify()` and `JSON.parse()` by default).
+
+⬥ Set up interaction with a custom storage by setting `{ read(), write(value)? }` as `options` in `new PersistentState(value, options)`.
+
+⬥ `PersistentState` skips interaction with the browser storage in non-browser environments, which makes it usable with SSR. One way to avoid mismatch errors while hydrating SSR content based on a persisent state restored in the browser is using client-side rendering detection utilities such as [`react-clientside`](https://www.npmjs.com/package/react-clientside).
+
+## useRoute
+
+Use this hook for URL-based rendering and SPA navigation, which boil down to accessing and changing the current URL treated as shared state under the hood.
+
+### URL-based rendering
+
+URL-based rendering with `at(url, x, y?)` shown below works similarly to conditional rendering with the ternary operator `atURL ? x : y`. It's equally applicable to props and components:
+
+```jsx
+import { useRoute } from "react-statepod";
+
+const App = () => {
+  const { at } = useRoute();
+
+  return (
+    <header className={at("/", "full", "compact")}>
+      <h1>App</h1>
+    </header>
+    {at("/", <Intro/>)}
+    {at(/^\/sections\/(?<id>\d+)\/?$/, ({ params }) => <Section id={params.id}/>)}
+  );
+};
+```
+
+⬥ `params` in dynamic values (as in `({ params }) => <Section id={params.id}/>` above) contains the URL pattern's capturing groups.
+
+⬥ Use `at(url)` as a shorthand for `at(url, true, false)`. Example: `<Component isOpen={at("/")}/>`.
+
+⬥ By default, `useRoute` makes use of the browser's URL, if it's available. Otherwise, use `<RouteProvider href={url}>` to set a specific URL value. Common use cases: SSR and tests. A less common use case: custom routing behavior, including custom non-URL-based routing ([example](https://codesandbox.io/p/sandbox/tykt44?file=%252Fsrc%252FApp.tsx)).
+
+⬥ See also the [Type-safe routes](#type-safe-routes) section.
+
+⬥ Routing with `react-statepod` is based on the core idea behind all approaches to route-based rendering: conditional rendering based on the URL. Unlike component-, config-, or file-based approaches, the `react-statepod`'s imperative approach sticks to this core idea without additional abstraction layers and specific relations between routes (like layout nesting or parameter inheritance) offering full explicit control over route-based rendering.
+
+### SPA navigation
+
+The shape of the SPA navigation API is largely aligned with the similar built-in browser APIs (but still compatible with SSR):
+
+```diff
++ import { A, useRoute } from "react-statepod";
+
+  const UserNav = ({ signedIn }) => {
++   const { route } = useRoute();
+
+    const handleClick = () => {
+-     window.location.href = signedIn ? "/profile" : "/login";
++     route.href = signedIn ? "/profile" : "/login";
+    };
+
+    return (
+      <nav>
+-       <a href="/">Home</a>
++       <A href="/">Home</A>
+        <button onClick={handleClick}>Profile</button>
+      </nav>
+    );
+  };
+```
+
+⬥ `<A>` and `<Area>` are the two kinds of SPA route link components available out of the box. They have the same props and semantics as the corresponding HTML link elements `<a>` and `<area>`.
+
+⬥ The `route` object returned from `useRoute()` exposes an API resembling the built-in APIs of `window.location` and `history` carried over to SPA navigation: `.assign(url)`, `.replace(url)`, `.reload()`, `.href`, `.pathname`, `.search`, `.hash`, `.back()`, `.forward()`, `.go(delta)`.
+
+⬥ `route.navigate(options)` combines and extends `route.assign(url)` and `route.replace(url)` serving as a handy drop-in replacement for the similar `window.location` methods:
+
+```js
+route.navigate({ href: "/intro", history: "replace", scroll: "off" });
+```
+
+⬥ Tweak link components by adding a relevant combination of the optional `data-` props corresponding to the `options` of `route.navigate(options)`:
+
+```jsx
+<A href="/intro">Intro</A>
+<A href="/intro" data-history="replace">Intro</A>
+<A href="/intro" data-scroll="off">Intro</A>
+<A href="/intro" data-spa="off">Intro</A>
+```
+
+Using HTML link attributes as SPA link component props makes link components easily interchangeable with HTML links and more familiar without prior knowledge.
+
+⬥ Link components also automatically receive the `data-active="true"` prop whenever their `href` prop matches the current URL, which can be used for additional styling.
+
+⬥ Use the optional `callback` parameter of `useRoute(callback?)` for more fine-grained control over the component rendering in response to URL changes. This callback receives the `render` function as a parameter that should be called at some point. Use cases for this render callback include, for example, activating animated view transitions ([example](https://codesandbox.io/p/sandbox/w4q95n?file=%252Fsrc%252FApp.tsx)) or (less likely in regular circumstances) skipping re-renders for certain URL changes.
+
+## useNavigationStart / useNavigationComplete
+
+These hooks set up optional actions to be done before and after a SPA navigation occurs respectively. Such intermediate actions are also known as routing middleware.
+
+Some common examples of what can be handled with the routing middleware include redirecting to another URL, preventing navigation with unsaved user input, setting the page title based on the current URL:
+
+```jsx
+import { useNavigationComplete, useNavigationStart } from "react-statepod";
+
+function setTitle({ href }) {
+  document.title = href === "/intro" ? "Intro" : "App";
+}
+
+const App = () => {
+  const { route } = useRoute();
+  const [hasUnsavedChanges, setUnsavedChanges] = useState(false);
+
+  const handleNavigationStart = useCallback(({ href }) => {
+    if (hasUnsavedChanges)
+      return false; // Preventing navigation
+
+    if (href === "/") {
+      route.href = "/intro"; // SPA redirection
+      return false;
+    }
+  }, [hasUnsavedChanges, route]);
+
+  useNavigationStart(handleNavigationStart);
+  useNavigationComplete(setTitle);
+
+  // ...
+};
+```
+
+⬥ The object parameter of the hooks' callbacks has the shape of the `route.navigate()`'s options, including `href` and `referrer`, the navigation destination and initial URLs.
+
+⬥ The callback of both hooks is first called when the component gets mounted if the route is already in the navigation-complete state.
+
+## useRouteState
+
+When it's necessary to put a portion of the app's state to the URL, use this hook to manage URL parameters as state in a `useState`-like manner. Use the React's state mental model and migrate from local state without major code rewrites:
+
+```diff
++ import { useRouteState } from "react-statepod";
+
+  const App = () => {
+-   const [{ coords }, setState] = useState({ coords: { x: 0, y: 0 } });
++   const [{ query }, setState] = useRouteState("/");
+
+    const setPosition = () => {
+      setState(state => ({
+        ...state,
+-       coords: {
++       query: {
+          x: Math.random(),
+          y: Math.random(),
+        },
+      });
+    };
+
+    return (
+      <>
+        <h1>Shape</h1>
+-       <Shape x={coords.x} y={coords.y}/>
++       <Shape x={query.x} y={query.y}/>
+        <p><button onClick={setPosition}>Move</button></p>
+      </>
+    );
+  };
+```
+
+⬥ `useRouteState(url, options?)` has an optional second parameter in the shape of the `route.navigate()`'s options. Pass `{ scroll: "off" }` as `options` to opt out from the default scroll-to-the-top behavior when the URL changes.
+
+⬥ See also the [Type-safe routes](#type-safe-routes) section.
+
+## Type-safe routes
+
+When it comes to accessing parameters extracted from a URL pattern, by default the parameters are typed as `Record<string, string | undefined>`, which quite literally represents a map containing portions of a string URL.
+
+```tsx
+const { at } = useRoute();
+
+at(/^\/sections\/(?<id>\d+)\/?$/, ({ params }) => <Section id={params.id}/>)
+                                  // ^ Record<string, string | undefined>
+
+const [state, setState] = useRouteState("/");
+    // ^ { query: Record<string, string | undefined> }
+```
+
+Optionally, more specific type-aware parsing of URL parameters can be achieved by replacing string and RegExp URL patterns with URL patterns produced by a schema-based URL builder, like with `url-shape` and `zod` or a [similar tool](https://standardschema.dev/schema#what-schema-libraries-implement-the-spec):
+
+```ts
+import { createURLBuilder } from "url-shape";
+import { z } from "zod"; // Or another Standard Schema-compliant lib
+
+// Get a type-aware URL builder `url()` based on a URL schema
+export const url = createURLBuilder({
+  "/sections/:id": z.object({
+    // URL path placeholder parameters
+    params: z.object({ id: z.coerce.number() }),
+  }),
+  "/": z.object({
+    // URL query (or search) parameters
+    query: z.optional(z.object({ x: z.coerce.number(), y: z.coerce.number() })),
+  }),
+});
+```
+
+The type-aware URL builder `url(pattern, options?)` provides hints about the types of the parsed URL parameters and helps avoid typos and type mismatches:
+
+```tsx
+const { at } = useRoute();
+
+at(url("/sections/:id"), ({ params }) => <Section id={params.id}/>)
+                         // ^ { id: number }
+
+const [state, setState] = useRouteState(url("/"));
+    // ^ { query?: { x: number, y: number } }
+
+<A href={url("/sections/:id", { id: 1 })}>Section 1</A>
+                           // ^ { id: number }
+```
+
+The URL schema as shown above doesn't have to cover the entire app. This approach allows for incremental or partial adoption of type-safe routing, where needed.
+
+On the other hand, once the entire app is covered with type-safe routes, we might want to avoid future use of relaxed typing with string and RegExp URL patterns. This can be achieved by adding the following type declaration that effectively disallows string and RegExp URL patterns:
+
+```ts
+declare module "react-statepod" {
+  interface URLConfig {
+    strict: true;
+  }
+}
+```
+
+### Nested routes
+
+All routes are handled independently, so type-safe nested routes don't require special handling and don't maintain implicit relations with their parent routes. It also means that nested routes don't inherit their parent route parameters by default. Relations between routes (also beyond the direct inheritance of parameters) can be pretty straightforwardly defined at the URL schema level without imposing implicit constraints, which could be hard to work around.
+
+```ts
+import { createURLBuilder } from "url-shape";
+import { z } from "zod";
+
+const sectionParams = z.object({
+  sectionId: z.coerce.number(),
+});
+
+export const url = createURLBuilder({
+  "/sections/:sectionId": z.object({
+    params: sectionParams,
+  }),
+  "/sections/:sectionId/stories/:storyId": z.object({
+    params: z.object({
+      ...sectionParams.shape, // Shared URL parameters
+      storyId: z.coerce.number(),
+    }),
+  }),
+});
+```
+
+## useTransientState
+
+Use this hook to track an async action's state, whether it's pending, successfully completed, or failed, without affecting the application's data management.
+
+In the example below, storing and rendering the essential app data (`items`) and the happy path scenario remain unaffected. The loading and error state handling works like a decoupled scaffolding to the main scenario. (`items` are stored in local state here, but any other state used by the app can be there instead.)
+
+```diff
++ import { useTransientState } from "react-statepod";
+- import { fetchItems } from "./fetchItems.js";
++ import { fetchItems as fetchItemsOriginal } from "./fetchItems.js";
+
+  export const ItemList = () => {
+    const [items, setItems] = useState([]);
++   const [state, fetchItems] = useTransientState("items", fetchItemsOriginal);
+
+    useEffect(() => {
+      // The fetched items can be stored with any approach to app state
+      fetchItems().then(setItems);
+    }, [fetchItems]);
+
++   if (state.initial || state.pending) return <p>Loading...</p>;
++   if (state.error) return <p>An error occurred</p>;
+
+    return <ul>{items.map(/* ... */)}</ul>;
+  };
+```
+
+```diff
++ import { useTransientState } from "react-statepod";
+
+- export const Status = ({ state }) => {
++ export const Status = () => {
++   const [state] = useTransientState("items");
+
+    if (state.initial) return null;
+    if (state.pending) return <>Busy</>;
+    if (state.error) return <>Error</>;
+
+    return <>OK</>;
+  };
+```
+
+### Shared and local async action state
+
+Use a string key with `useTransientState(key, action?)` to access the same action state from multiple components (as in `ItemList` and `Status` above). Pass `null` as the key to have the action state scoped locally to the component where the hook is used.
+
+### Silent pending state
+
+Use case: background actions or optimistic updates.
+
+Set `{ silent: true }` as the last parameter of the trackable action returned from the `useTransientState` hook to prevent the `pending` property from switching to `true` in the pending state.
+
+```js
+const [state, fetchItems] = useTransientState(fetchItemsOriginal);
+    // ^ `state.pending` remains `false` in the silent mode
+
+fetchItems({ silent: true })
+```
+
+### Delayed pending state
+
+Use case: Avoid flashing a process indicator when the action is likely to complete in a short while by delaying the pending state.
+
+```js
+const [state, fetchItems] = useTransientState(fetchItemsOriginal);
+    // ^ `state.pending` remains `false` during the delay
+
+fetchItems({ delay: 500 }) // in milliseconds
+```
+
+### Custom rejection handler
+
+Allow the trackable action to reject explicitly with `{ throws: true }` as the last parameter, along with exposing `state.error` returned from `useTransientState` that goes by default.
+
+```js
+const [state, fetchItems] = useTransientState(fetchItemsOriginal);
+
+fetchItems({ throws: true }).catch(handleError)
+```
+
+### Action state provider
+
+`<TransientStateProvider>` creates an isolated instance of initial shared async action state. Its prime use cases are SSR and tests. It isn't required with client-side rendering, but it can be used to separate action states of larger self-contained portions of an app.
+
+```jsx
+import { TransientStateProvider } from "react-statepod";
+
+<TransientStateProvider>
+  <App/>
+</TransientStateProvider>
+```
+
+Use the provider to set up a specific initial async action state when required:
+
+```jsx
+const initialState = {
+  "fetch-items": { initial: false, pending: true },
+};
+
+<TransientStateProvider value={initialState}>
+  <App/>
+</TransientStateProvider>
+```
+
+⬥ With an explicit value or without, the `<TransientStateProvider>`'s nested components will only respond to updates in the particular action state they subscribed to by means of `useTransientState`.
+
+## Annotated examples
+
+Shared state
+
+- [Shared state without Context](https://codesandbox.io/p/sandbox/gxkn85?file=%252Fsrc%252FApp.tsx), counter app, useExternalState
+- [Shared state with Context](https://codesandbox.io/p/sandbox/9mpfsf?file=%252Fsrc%252FApp.tsx), counter app, useExternalState, React Context
+- [Shared state with Immer](https://codesandbox.io/p/sandbox/gv4rgw?file=%252Fsrc%252FApp.tsx), counter app, useExternalState, Immer
+
+Routing
+
+- [URL-based rendering](https://codesandbox.io/p/sandbox/2nv8ck?file=%252Fsrc%252FApp.tsx), useRoute, link component
+- [Type-safe URL-based rendering](https://codesandbox.io/p/sandbox/tltq5r?file=%252Fsrc%252FApp.tsx), useRoute, url-shape, zod
+- [URL parameters as state](https://codesandbox.io/p/sandbox/6rp4sy?file=%252Fsrc%252FApp.tsx), useRouteState
+- [Type-safe URL parameters as state](https://codesandbox.io/p/sandbox/6ck4qz?file=%252Fsrc%252FShapeSection.tsx), useRouteState, url-shape, zod
+- [Type-safe nested routes](https://codesandbox.io/p/sandbox/pv9rgh?file=%252Fsrc%252FApp.tsx), useRoute, url-shape, zod
+- [Unknown routes](https://codesandbox.io/p/sandbox/jnngqt?file=%252Fsrc%252FApp.tsx), useRoute
+- [Lazy routes](https://codesandbox.io/p/sandbox/qw5r6g?file=%252Fsrc%252FApp.tsx), useRoute, React Suspense, React.lazy
+- [View transitions](https://codesandbox.io/p/sandbox/w4q95n?file=%252Fsrc%252FApp.tsx), useRoute, View Transition API
+- [Custom routing based on text input](https://codesandbox.io/p/sandbox/tykt44?file=%252Fsrc%252FApp.tsx), Route, RouteProvider, useRoute
+- [Converting links in HTML content to SPA links](https://codesandbox.io/p/sandbox/7pfjc7?file=%252Fsrc%252FApp.tsx), useRouteLinks
+
+Async action state
+
+- [Shared async action state](https://codesandbox.io/p/sandbox/x9d2c9?file=%252Fsrc%252FItemList.tsx), useTransientState
+
+Find also the code of these examples in the repo's [`tests`](https://github.com/axtk/react-statepod/tree/main/tests) directory.
+
+## Internals
+
+[`statepod`](https://www.npmjs.com/package/statepod)