@warp-drive-mirror/react 5.8.0-alpha.3 → 5.8.0-alpha.32

package/README.md

@@ -1,25 +1,46 @@
 <p align="center">
   <img
     class="project-logo"
-    src="./logos/NCC-1701-a-blue.svg#gh-light-mode-only"
+    src="./logos/logo-yellow-slab.svg"
     alt="WarpDrive"
-    width="120px"
-    title="WarpDrive" />
-  <img
-    class="project-logo"
-    src="./logos/NCC-1701-a.svg#gh-dark-mode-only"
-    alt="WarpDrive"
-    width="120px"
-    title="WarpDrive" />
+    width="180px"
+    title="WarpDrive"
+    />
 </p>
 
-<h3 align="center">:electron: Components, Hooks and Utilities for using <em style="color: lightgreen">Warp</em><strong style="color: magenta">Drive</strong> with <strong style="color: lightblue">React</strong></h3>
+![NPM Stable Version](https://img.shields.io/npm/v/ember-data/latest?label=version&style=flat&color=fdb155)
+![NPM Downloads](https://img.shields.io/npm/dm/ember-data.svg?style=flat&color=fdb155)
+![License](https://img.shields.io/github/license/warp-drive-data/warp-drive.svg?style=flat&color=fdb155)
+[![EmberJS Discord Community Server](https://img.shields.io/badge/EmberJS-grey?logo=discord&logoColor=fdb155)](https://discord.gg/zT3asNS
+)
+[![WarpDrive Discord Server](https://img.shields.io/badge/WarpDrive-grey?logo=discord&logoColor=fdb155)](https://discord.gg/PHBbnWJx5S
+)
+
+<h3 align="center">Signals Integration and Component API for using <em>Warp</em><strong>Drive</strong> with <strong style="color: lightblue">React</strong></h3>
+
+***Warp*Drive** makes it easy to build scalable, fast, feature
+rich applications &mdash; letting you ship better experiences more quickly without re-architecting your app or API. ***Warp*Drive** is:
+
+- 🌌 Seamless Reactivity in any Framework
+- ⚡️ Committed to Best-In-Class Performance
+- 💚 Typed
+- ⚛️ Works with any API
+- 🌲 Focused on being as tiny as possible
+- 🚀 SSR Ready
+- 🐹 Built with ♥️ by [Ember](https://emberjs.com)
+
+<br>
+<br>
+
+*Get Started* → [Guides](https://warp-drive.io/guides/)
+
+<br>
 
 ---
 
-```sh
-pnpm install @warp-drive-mirror/react
-```
+<br>
+
+# @warp-drive-mirror/react
 
 **Tagged Releases**
 
@@ -44,7 +65,7 @@ This library provides reactive utilities for working with promises and requests,
     img.project-logo {
        padding: 0 5em 1em 5em;
        width: 100px;
-       border-bottom: 2px solid #0969da;
+       border-bottom: 2px solid #bbb;
        margin: 0 auto;
        display: block;
      }
@@ -60,7 +81,7 @@ This library provides reactive utilities for working with promises and requests,
       display: inline-block;
       padding: .2rem 0;
       color: #000;
-      border-bottom: 3px solid #0969da;
+      border-bottom: 3px solid #bbb;
     }
 
     details > details {

package/dist/unpkg/dev/declarations/-private/reactive-context.d.ts

@@ -0,0 +1,18 @@
+import { Signal } from "signal-polyfill";
+import { type JSX, type ReactNode, type Context } from "react";
+export declare function useWatcher(): {
+	watcher: Signal.subtle.Watcher;
+} | null;
+/**
+* @category Contexts
+*/
+export declare const WatcherContext: Context<{
+	watcher: Signal.subtle.Watcher;
+} | null>;
+/**
+*
+* @category Components
+*/
+export declare function ReactiveContext({ children }: {
+	children: ReactNode;
+}): JSX.Element;

package/dist/unpkg/dev/declarations/-private/request.d.ts

@@ -0,0 +1,141 @@
+import { RequestArgs, type ContentFeatures, type RecoveryFeatures, type RequestLoadingState, type RequestState } from "@warp-drive-mirror/core/store/-private";
+import type { StructuredErrorDocument } from "@warp-drive-mirror/core/types/request";
+import { JSX, ReactNode } from "react";
+interface ChromeComponentProps<RT> {
+	children: ReactNode;
+	state: RequestState | null;
+	features: ContentFeatures<RT>;
+}
+export 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>;
+	}>;
+}
+export 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
+*/
+export declare function Request<
+	RT,
+	E
+>($props: RequestProps<RT, E>): JSX.Element;
+export {};

package/dist/unpkg/dev/declarations/-private/store-provider.d.ts

@@ -0,0 +1,19 @@
+import { Store } from "@warp-drive-mirror/core";
+import { JSX, ReactNode } from "react";
+/**
+* @category Hooks
+*/
+export declare function useStore(): Store;
+type WithExistingStore = {
+	store: Store;
+	children: ReactNode;
+};
+type WithNewStore = {
+	Store: typeof Store;
+	children: ReactNode;
+};
+/**
+* @category Components
+*/
+export declare function StoreProvider($props: WithExistingStore | WithNewStore): JSX.Element;
+export {};

package/dist/unpkg/dev/declarations/index.d.ts

@@ -0,0 +1,7 @@
+/**
+* @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";

package/dist/unpkg/dev/declarations/install.d.ts

@@ -0,0 +1,3 @@
+import { type HooksOptions, type SignalHooks } from "@warp-drive-mirror/core/configure";
+export declare function settled(): Promise<void>;
+export declare function buildSignalConfig(options: HooksOptions): SignalHooks;

package/dist/unpkg/dev/index.js

@@ -0,0 +1,274 @@
+import { R as ReactiveContext } from "./reactive-context-ClTRYXie.js";
+export { W as WatcherContext } from "./reactive-context-ClTRYXie.js";
+import '@warp-drive-mirror/core';
+import { useMemo, createContext, use, useRef, useEffect } from 'react';
+import { macroCondition, getGlobalConfig } from '@embroider/macros';
+import { jsx, Fragment } from 'react/jsx-runtime';
+import { DISPOSE, createRequestSubscription, signal } from '@warp-drive-mirror/core/store/-private';
+import '@warp-drive-mirror/core/request';
+const StoreContext = /*#__PURE__*/createContext(null);
+
+/**
+ * @category Hooks
+ */
+function useStore() {
+  const store = use(StoreContext);
+  macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+    if (!test) {
+      throw new Error("No Store provided via context. Please ensure you are using <StoreProvider> to provide a Store instance.");
+    }
+  })(store) : {};
+  return store;
+}
+/**
+ * @category Components
+ */
+function StoreProvider($props) {
+  const store = useMemo(() => "store" in $props ? $props.store : new $props.Store(), ["store" in $props ? $props.store : $props.Store]);
+  return /*#__PURE__*/jsx(StoreContext, {
+    value: store,
+    children: $props.children
+  });
+}
+const deferred = /* @__PURE__ */new WeakMap();
+function deferDecorator(proto, prop, desc) {
+  let map = deferred.get(proto);
+  if (!map) {
+    map = /* @__PURE__ */new Map();
+    deferred.set(proto, map);
+  }
+  map.set(prop, desc);
+}
+function findDeferredDecorator(target, prop) {
+  var _a;
+  let cursor = target.prototype;
+  while (cursor) {
+    let desc = (_a = deferred.get(cursor)) == null ? void 0 : _a.get(prop);
+    if (desc) {
+      return desc;
+    }
+    cursor = cursor.prototype;
+  }
+}
+function decorateFieldV2(prototype, prop, decorators, initializer) {
+  let desc = {
+    configurable: true,
+    enumerable: true,
+    writable: true,
+    initializer: null
+  };
+  if (initializer) {
+    desc.initializer = initializer;
+  }
+  for (let decorator of decorators) {
+    desc = decorator(prototype, prop, desc) || desc;
+  }
+  if (desc.initializer === void 0) {
+    Object.defineProperty(prototype, prop, desc);
+  } else {
+    deferDecorator(prototype, prop, desc);
+  }
+}
+function initializeDeferredDecorator(target, prop) {
+  let desc = findDeferredDecorator(target.constructor, prop);
+  if (desc) {
+    Object.defineProperty(target, prop, {
+      enumerable: desc.enumerable,
+      configurable: desc.configurable,
+      writable: desc.writable,
+      value: desc.initializer ? desc.initializer.call(target) : void 0
+    });
+  }
+}
+const IdleBlockMissingError = new Error("No idle block provided for <Request> component, and no query or request was provided.");
+class ReactiveArgs {
+  static {
+    decorateFieldV2(this.prototype, "request", [signal]);
+  }
+  #request = (initializeDeferredDecorator(this, "request"), void 0);
+  static {
+    decorateFieldV2(this.prototype, "query", [signal]);
+  }
+  #query = (initializeDeferredDecorator(this, "query"), void 0);
+  static {
+    decorateFieldV2(this.prototype, "autorefresh", [signal]);
+  }
+  #autorefresh = (initializeDeferredDecorator(this, "autorefresh"), void 0);
+  static {
+    decorateFieldV2(this.prototype, "autorefreshThreshold", [signal]);
+  }
+  #autorefreshThreshold = (initializeDeferredDecorator(this, "autorefreshThreshold"), void 0);
+  static {
+    decorateFieldV2(this.prototype, "autorefreshBehavior", [signal]);
+  }
+  #autorefreshBehavior = (initializeDeferredDecorator(this, "autorefreshBehavior"), void 0);
+}
+const DefaultChrome = ({
+  children
+}) => {
+  return /*#__PURE__*/jsx(Fragment, {
+    children: children
+  });
+};
+function Throw({
+  error
+}) {
+  throw error;
+}
+
+/**
+ * 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
+ */
+function Request($props) {
+  return /*#__PURE__*/jsx(ReactiveContext, {
+    children: /*#__PURE__*/jsx(InternalRequest, {
+      ...$props
+    })
+  });
+}
+function isStrictModeRender() {
+  const count = useRef(0);
+
+  // in debug we need to skip every second invocation
+  if (macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG)) {
+    if (count.current++ % 2 === 1) {
+      return true;
+    }
+  }
+  return false;
+}
+function InternalRequest($props) {
+  const isStrict = isStrictModeRender();
+  const store = $props.store ?? useStore();
+  const Chrome = $props.chrome ?? DefaultChrome;
+  const sink = useRef(null);
+  const args = useRef(null);
+  if (!args.current) {
+    args.current = new ReactiveArgs();
+  }
+  Object.assign(args.current, $props);
+  if (sink.current && (sink.current.store !== store || $props.subscription)) {
+    sink.current[DISPOSE]();
+    sink.current = null;
+  }
+  if (!sink.current && !$props.subscription) {
+    sink.current = createRequestSubscription(store, args.current);
+  }
+  const initialized = useRef(null);
+  const effect = () => {
+    if (sink.current && (!initialized.current || initialized.current.disposable !== sink.current)) {
+      initialized.current = {
+        disposable: sink.current,
+        dispose: () => {
+          sink.current?.[DISPOSE]();
+          initialized.current = null;
+          sink.current = null;
+        }
+      };
+    }
+    return sink.current ? initialized.current.dispose : undefined;
+  };
+  let maybeEffect = effect;
+  if (macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG)) {
+    if (isStrict) {
+      maybeEffect = () => {
+        if (initialized.current) {
+          return effect();
+        }
+        return () => {
+          // initialize our actual effect
+          effect();
+          // in strict mode we don't want to run the teardown
+          // for the second invocation
+        };
+      };
+    }
+  }
+  useEffect(maybeEffect, [sink.current]);
+  const state = $props.subscription ?? sink.current;
+  const slots = $props.states;
+  return /*#__PURE__*/jsx(Chrome, {
+    state: state.isIdle ? null : state.reqState,
+    features: state.contentFeatures,
+    children:
+    // prettier-ignore
+    state.isIdle && slots.idle ? /*#__PURE__*/jsx(slots.idle, {}) : state.isIdle ? /*#__PURE__*/jsx(Throw, {
+      error: IdleBlockMissingError
+    }) : state.reqState.isLoading ? slots.loading ? /*#__PURE__*/jsx(slots.loading, {
+      state: state.reqState.loadingState
+    }) : '' : state.reqState.isCancelled && slots.cancelled ? /*#__PURE__*/jsx(slots.cancelled, {
+      error: state.reqState.reason,
+      features: state.errorFeatures
+    }) : state.reqState.isError && slots.error ? /*#__PURE__*/jsx(slots.error, {
+      error: state.reqState.reason,
+      features: state.errorFeatures
+    }) : state.reqState.isSuccess ? slots.content ? /*#__PURE__*/jsx(slots.content, {
+      result: state.reqState.value,
+      features: state.contentFeatures
+    }) : /*#__PURE__*/jsx(Throw, {
+      error: new Error('No content block provided for <Request> component.')
+    }) : !state.reqState.isCancelled ? /*#__PURE__*/jsx(Throw, {
+      error: state.reqState.reason
+    }) : '' // never
+  });
+}
+export { ReactiveContext, Request, StoreProvider, Throw, useStore };

package/dist/unpkg/dev/install.js

@@ -0,0 +1,104 @@
+import { use } from 'react';
+import { Signal } from 'signal-polyfill';
+import { setupSignals } from '@warp-drive-mirror/core/configure';
+import { W as WatcherContext } from "./reactive-context-ClTRYXie.js";
+import { macroCondition, getGlobalConfig } from '@embroider/macros';
+
+/**
+ * {@include ./install.md}
+ * @module
+ */
+
+function tryConsumeContext(signal) {
+  // eslint-disable-next-line no-console
+  const logError = console.error;
+  try {
+    // eslint-disable-next-line no-console
+    console.error = () => {};
+    // ensure signals are watched by our closest watcher
+    const watcher = use(WatcherContext);
+    // eslint-disable-next-line no-console
+    console.error = logError;
+    watcher?.watcher.watch(signal);
+    if (macroCondition(getGlobalConfig().WarpDriveMirror.activeLogging.LOG_REACT_SIGNAL_INTEGRATION)) {
+      if (getGlobalConfig().WarpDriveMirror.debug.LOG_REACT_SIGNAL_INTEGRATION || globalThis.getWarpDriveRuntimeConfig().debug.LOG_REACT_SIGNAL_INTEGRATION) {
+        // eslint-disable-next-line no-console
+        console.log(`[WarpDrive] Consumed Context Signal`, signal, watcher);
+      }
+    }
+  } catch {
+    // eslint-disable-next-line no-console
+    console.error = logError;
+    // if we are not in a React context, we will Error
+    // so we just ignore it.
+    if (macroCondition(getGlobalConfig().WarpDriveMirror.activeLogging.LOG_REACT_SIGNAL_INTEGRATION)) {
+      if (getGlobalConfig().WarpDriveMirror.debug.LOG_REACT_SIGNAL_INTEGRATION || globalThis.getWarpDriveRuntimeConfig().debug.LOG_REACT_SIGNAL_INTEGRATION) {
+        // eslint-disable-next-line no-console
+        console.log(`[WarpDrive] No Context Available To Consume Signal`, signal);
+      }
+    }
+  }
+}
+let pending;
+async function settled() {
+  if (macroCondition(getGlobalConfig().WarpDriveMirror.env.TESTING)) {
+    // in testing mode we provide a test waiter integration
+    if (!pending || !pending.length) return;
+    const current = pending ?? [];
+    pending = [];
+    await Promise.allSettled(current);
+    await Promise.resolve();
+    await Promise.resolve();
+    await Promise.resolve();
+    return settled();
+  }
+}
+function buildSignalConfig(options) {
+  return {
+    createSignal: (obj, key) => new Signal.State(macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? {
+      obj,
+      key
+    } : null, {
+      equals: () => false
+    }),
+    notifySignal: signal => {
+      if (macroCondition(getGlobalConfig().WarpDriveMirror.activeLogging.LOG_REACT_SIGNAL_INTEGRATION)) {
+        if (getGlobalConfig().WarpDriveMirror.debug.LOG_REACT_SIGNAL_INTEGRATION || globalThis.getWarpDriveRuntimeConfig().debug.LOG_REACT_SIGNAL_INTEGRATION) {
+          if (Signal.subtle.hasSinks(signal)) {
+            // eslint-disable-next-line no-console
+            console.log(`[WarpDrive] Notifying Signal`, signal);
+          } else {
+            // eslint-disable-next-line no-console
+            console.log(`[WarpDrive] Notified Signal That Has No Watcher`, signal);
+          }
+        }
+      }
+      signal.set(signal.get());
+    },
+    consumeSignal: signal => {
+      tryConsumeContext(signal);
+      void signal.get();
+    },
+    createMemo: (object, key, fn) => {
+      const memo = new Signal.Computed(fn);
+      return () => {
+        tryConsumeContext(memo);
+        return memo.get();
+      };
+    },
+    waitFor: promise => {
+      if (macroCondition(getGlobalConfig().WarpDriveMirror.env.TESTING)) {
+        pending = pending || [];
+        const newPromise = promise.finally(() => {
+          pending = pending.filter(p => p !== newPromise);
+        });
+        pending.push(newPromise);
+        return newPromise;
+      }
+      return promise;
+    },
+    willSyncFlushWatchers: () => false
+  };
+}
+setupSignals(buildSignalConfig);
+export { buildSignalConfig, settled };