@warp-drive-mirror/react 5.9.0-beta.0 → 5.9.0-beta.1

package/declarations/index.d.ts

@@ -1,7 +1,180 @@
+import { Signal } from "signal-polyfill";
+import { Context, JSX, ReactNode } from "react";
+import { RequestLoadingState, RequestState } from "@warp-drive-mirror/core/reactive";
+import { ContentFeatures, RecoveryFeatures, RequestArgs } from "@warp-drive-mirror/core/signals/-leaked";
+import { Store } from "@warp-drive-mirror/core";
+import { StructuredErrorDocument } from "@warp-drive-mirror/core/types/request";
+//#region src/-private/reactive-context.d.ts
 /**
-* @module
-* @mergeModuleWith <project>
-*/
-export { ReactiveContext, WatcherContext } from "./-private/reactive-context.js";
-export { StoreProvider, useStore } from "./-private/store-provider.js";
-export { Request, Throw } from "./-private/request.js";
+ * @category Contexts
+ */
+declare const WatcherContext: Context<{
+  /**
+   * The `Signal.subtle.Watcher` used to observe signal changes for the nearest {@link ReactiveContext}.
+   */
+  watcher: Signal.subtle.Watcher;
+} | null>;
+/**
+ *
+ * @category Components
+ */
+declare function ReactiveContext({ children }: {
+  children: ReactNode;
+}): JSX.Element;
+//#endregion
+//#region src/-private/store-provider.d.ts
+/**
+ * @category Hooks
+ */
+declare function useStore(): Store;
+type WithExistingStore = {
+  store: Store;
+  children: ReactNode;
+};
+type WithNewStore = {
+  Store: typeof Store;
+  children: ReactNode;
+};
+/**
+ * @category Components
+ */
+declare function StoreProvider($props: WithExistingStore | WithNewStore): JSX.Element;
+//#endregion
+//#region src/-private/request.d.ts
+interface ChromeComponentProps<RT> {
+  children: ReactNode;
+  state: RequestState | null;
+  features: ContentFeatures<RT>;
+}
+interface RequestProps<RT, E> extends RequestArgs<RT, E> {
+  chrome?: React.FC<ChromeComponentProps<RT>>;
+  states: RequestStates<RT, E>;
+}
+interface RequestStates<RT, E> {
+  /**
+   * The block to render when the component is idle and waiting to be given a request.
+   *
+   */
+  idle?: React.FC<{}>;
+  /**
+   * The block to render when the request is loading.
+   *
+   */
+  loading?: React.FC<{
+    state: RequestLoadingState;
+  }>;
+  /**
+   * The block to render when the request was cancelled.
+   *
+   */
+  cancelled?: React.FC<{
+    /**
+     * The Error the request rejected with.
+     */
+    error: StructuredErrorDocument<E>;
+    /**
+     * Utilities to assist in recovering from the error.
+     */
+    features: RecoveryFeatures;
+  }>;
+  /**
+   * The block to render when the request failed. If this block is not provided,
+   * the error will be rethrown.
+   *
+   * Thus it is required to provide an error block and proper error handling if
+   * you do not want the error to crash the application.
+   */
+  error: React.FC<{
+    /**
+     * The Error the request rejected with.
+     */
+    error: StructuredErrorDocument<E>;
+    /**
+     * Utilities to assist in recovering from the error.
+     */
+    features: RecoveryFeatures;
+  }>;
+  /**
+   * The block to render when the request succeeded.
+   *
+   */
+  content: React.FC<{
+    result: RT;
+    features: ContentFeatures<RT>;
+  }>;
+}
+/**
+ * Throws the given error. Used internally to rethrow request errors that
+ * are not otherwise handled by a provided error/cancelled block.
+ *
+ * @private
+ */
+declare function Throw({ error }: {
+  error: Error;
+}): never;
+/**
+ * The `<Request />` component is a powerful tool for managing data fetching and
+ * state in your React application. It provides a declarative approach to reactive
+ * control-flow for managing requests and state in your application.
+ *
+ * The `<Request />` component is ideal for handling "boundaries", outside which some
+ * state is still allowed to be unresolved and within which it MUST be resolved.
+ *
+ * ## Request States
+ *
+ * `<Request />` has five states, only one of which will be active and rendered at a time.
+ *
+ * - `idle`: The component is waiting to be given a request to monitor
+ * - `loading`: The request is in progress
+ * - `error`: The request failed
+ * - `content`: The request succeeded
+ * - `cancelled`: The request was cancelled
+ *
+ * Additionally, the `content` state has a `refresh` method that can be used to
+ * refresh the request in the background, which is available as a sub-state of
+ * the `content` state.
+ *
+ * ### Example Usage
+ *
+ * ```tsx
+ * import { Request } from "@warp-drive-mirror/react";
+ *
+ * export function UserPreview($props: { id: string | null }) {
+ *   return (
+ *    <Request
+ *       query={findRecord('user', $props.id)}
+ *       states={{
+ *         idle: () => <div>Waiting for User Selection</div>,
+ *         loading: ({ state }) => <div>Loading user data...</div>,
+ *         cancelled: ({ error, features }) => (
+ *           <div>
+ *             <p>Request Cancelled</p>
+ *             <p><button onClick={features.retry}>Start Again?</button></p>
+ *           </div>
+ *         ),
+ *         error: ({ error, features }) => (
+ *           <div>
+ *             <p>Error: {error.message}</p>
+ *             <p><button onClick={features.retry}>Try Again?</button></p>
+ *           </div>
+ *         ),
+ *         content: ({ result, features }) => (
+ *           <div>
+ *            <h2>User Details</h2>
+ *            <p>ID: {result.id}</p>
+ *            <p>Name: {result.name}</p>
+ *          </div>
+ *        ),
+ *      }}
+ *    />
+ *   );
+ * }
+ *
+ * ```
+ *
+ * @category Components
+ */
+declare function Request<RT, E>($props: RequestProps<RT, E>): JSX.Element;
+//#endregion
+export { ReactiveContext, Request, StoreProvider, Throw, WatcherContext, useStore };
+//# sourceMappingURL=index.d.ts.map

package/declarations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/-private/reactive-context.tsx","../src/-private/store-provider.tsx","../src/-private/request.tsx"],"mappings":";;;;;;;;;;cA+Ia,gBAAgB;;;;EAI3B,SAAS,OAAO,OAAO;;;;;;iBAST,kBAAkB;EAAc,UAAU;IAAc,IAAI;;;;;;iBChJ5D,YAAY;KASvB;EAAsB,OAAO;EAAO,UAAU;;KAC9C;EAAiB,cAAc;EAAO,UAAU;;;;;iBAKrC,cAAc,QAAQ,oBAAoB,eAAe,IAAI;;;UCQnE,qBAAqB;EAC7B,UAAU;EACV,OAAO;EACP,UAAU,gBAAgB;;UAOX,aAAa,IAAI,WAAW,YAAY,IAAI;EAC3D,SAAS,MAAM,GAAG,qBAAqB;EAEvC,QAAQ,cAAc,IAAI;;UAGlB,cAAc,IAAI;;;;;EAK1B,OAAO,MAAM;;;;;EAMb,UAAU,MAAM;IAAK,OAAO;;;;;;EAM5B,YAAY,MAAM;;;;IAIhB,OAAO,wBAAwB;;;;IAI/B,UAAU;;;;;;;;;EAUZ,OAAO,MAAM;;;;IAIX,OAAO,wBAAwB;;;;IAI/B,UAAU;;;;;;EAOZ,SAAS,MAAM;IAAK,QAAQ;IAAI,UAAU,gBAAgB;;;;;;;;;iBAS5C,QAAQ;EAAW,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkE1B,QAAQ,IAAI,GAAG,QAAQ,aAAa,IAAI,KAAK,IAAI"}

package/declarations/install.d.ts

@@ -1,3 +1,21 @@
-import { type HooksOptions, type SignalHooks } from "@warp-drive-mirror/core/configure";
-export declare function settled(): Promise<void>;
-export declare function buildSignalConfig(options: HooksOptions): SignalHooks;
+import { HooksOptions, SignalHooks } from "@warp-drive-mirror/core/configure";
+//#region src/install.d.ts
+/**
+ * Resolves once all pending requests started via WarpDrive's React signal
+ * integration have settled. Only tracks requests while `TESTING` is enabled;
+ * a no-op otherwise.
+ *
+ * @public
+ */
+declare function settled(): Promise<void>;
+/**
+ * Builds the {@link SignalHooks} implementation backed by the
+ * [Signal Polyfill](https://github.com/proposal-signals/signal-polyfill),
+ * used to wire WarpDrive's reactivity primitives into React.
+ *
+ * @public
+ */
+declare function buildSignalConfig(options: HooksOptions): SignalHooks;
+//#endregion
+export { buildSignalConfig, settled };
+//# sourceMappingURL=install.d.ts.map

package/declarations/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","names":[],"sources":["../src/install.ts"],"mappings":";;;;;;;;;iBAiDsB,WAAW;;;;;;;;iBAsBjB,kBAAkB,SAAS,eAAe"}