@t8/react-pending 1.0.26 → 1.0.27

package/README.md

@@ -83,7 +83,7 @@ Omit the custom string key parameter of `usePendingState()` to scope the pending
 + let [state, withState] = usePendingState(); // local
 ```
 
-## Silent tracking of background and optimistic updates
+## Silent tracking of background actions and optimistic updates
 
 ```diff
 - withState(fetchItems())
@@ -96,7 +96,7 @@ Omit the custom string key parameter of `usePendingState()` to scope the pending
 
 ```diff
 - withState(fetchItems())
-+ withState(fetchItems(), { delay: 500 })
++ withState(fetchItems(), { delay: 500 }) // in milliseconds
 ```
 
 🔹 Use case: avoiding flashing a process indicator when the action is likely to complete by the end of a short delay.
@@ -121,7 +121,7 @@ Omit the custom string key parameter of `usePendingState()` to scope the pending
 + </PendingStateProvider>
 ```
 
-🔹 `<PendingStateProvider>` creates an isolated instance of initial shared action state. Prime use cases: tests, SSR. It isn't required with client-side rendering, but it can be used to separate action states of larger self-contained portions of a web app.
+🔹 `<PendingStateProvider>` creates an isolated instance of initial shared action state. 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 a web app.
 
 ## Providing custom initial pending&nbsp;state
 

package/dist/index.d.ts

@@ -14,26 +14,42 @@ export type PendingStateProviderProps = {
 };
 export declare const PendingStateProvider: ({ value, children, }: PendingStateProviderProps) => import("react/jsx-runtime").JSX.Element;
 export type WithStateOptions = {
+  /**
+   * Whether to track the action state silently (e.g. with a background
+   * action or an optimistic update).
+   *
+   * When set to `true`, the state's `complete` property doesn't switch
+   * to `false` in the pending state.
+   */
   silent?: boolean;
-  throws?: boolean;
+  /**
+   * Delays switching the action state's `complete` property to `false`
+   * 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;
 };
 /**
- * Returns an array containing `[state, withState, setState]`:
- * - `state` reflects the state of a value passed to `withState()`;
- * - `withState(value, [options])` enables the tracking of the state
- * of `value`; setting the options to `{silent: true}` prevents
- * `withState()` from updating the state while `value` is pending
- * (e.g. for background or optimistic updates);
- * - `setState()` to directly update the state.
- */
-export declare function usePendingState(
-/**
- * A unique store key or a store. Providing a store key or a
- * shared store allows to share the state across multiple
+ * Returns an instance of pending state and the functions to update it.
+ *
+ * @param store - A unique store key or a store. Providing a store
+ * key or a shared store allows to share the state across multiple
  * components.
+ *
+ * @returns `[state, withState, setState]`, where
+ * - `state` is the current value of the pending state;
+ * - `withState(action, options?)` reads and tracks the pending state
+ * of `action`;
+ * - `setState(update)` can update the pending state value directly.
  */
-store?: string | Store<PendingState> | null): [
+export declare function usePendingState(store?: string | Store<PendingState> | null): [
   PendingState,
   <T>(value: T) => T,
   SetStoreState<PendingState>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t8/react-pending",
-  "version": "1.0.26",
+  "version": "1.0.27",
   "description": "Concise async action state tracking for React apps",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/usePendingState.ts

@@ -17,26 +17,43 @@ function createState(
 }
 
 export type WithStateOptions = {
+  /**
+   * Whether to track the action state silently (e.g. with a background
+   * action or an optimistic update).
+   *
+   * When set to `true`, the state's `complete` property doesn't switch
+   * to `false` in the pending state.
+   */
   silent?: boolean;
-  throws?: boolean;
+  /**
+   * Delays switching the action state's `complete` property to `false`
+   * 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;
 };
 
 /**
- * Returns an array containing `[state, withState, setState]`:
- * - `state` reflects the state of a value passed to `withState()`;
- * - `withState(value, [options])` enables the tracking of the state
- * of `value`; setting the options to `{silent: true}` prevents
- * `withState()` from updating the state while `value` is pending
- * (e.g. for background or optimistic updates);
- * - `setState()` to directly update the state.
+ * Returns an instance of pending state and the functions to update it.
+ *
+ * @param store - A unique store key or a store. Providing a store
+ * key or a shared store allows to share the state across multiple
+ * components.
+ *
+ * @returns `[state, withState, setState]`, where
+ * - `state` is the current value of the pending state;
+ * - `withState(action, options?)` reads and tracks the pending state
+ * of `action`;
+ * - `setState(update)` can update the pending state value directly.
  */
 export function usePendingState(
-  /**
-   * A unique store key or a store. Providing a store key or a
-   * shared store allows to share the state across multiple
-   * components.
-   */
   store?: string | Store<PendingState> | null,
 ): [PendingState, <T>(value: T) => T, SetStoreState<PendingState>] {
   let storeMap = useContext(PendingStateContext);