@warp-drive/react 5.7.0-alpha.31

package/LICENSE.md

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2017-2025 Ember.js and contributors
+Copyright (c) 2011-2017 Tilde, Inc. and contributors
+Copyright (c) 2011 LivingSocial Inc.
+
+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,96 @@
+<p align="center">
+  <img
+    class="project-logo"
+    src="./logos/NCC-1701-a-blue.svg#gh-light-mode-only"
+    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" />
+</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>
+
+---
+
+```sh
+pnpm install @warp-drive/react
+```
+
+**Tagged Releases**
+
+- ![NPM Canary Version](https://img.shields.io/npm/v/%40warp-drive%2Freact/canary?label=@canary&color=FFBF00)
+- ![NPM Beta Version](https://img.shields.io/npm/v/%40warp-drive%2Freact/bet?label=@beta&color=ff00ff)
+- ![NPM Stable Version](https://img.shields.io/npm/v/%40warp-drive%2Freact/latest?label=@latest&color=90EE90)
+- ![NPM LTS Version](https://img.shields.io/npm/v/%40warp-drive%2Freact/lts?label=@lts&color=0096FF)
+- ![NPM LTS-4-12 Version](https://img.shields.io/npm/v/%40warp-drive%2Freact/lts-4-12?label=@lts-4-12&color=bbbbbb)
+
+## About
+
+This library provides reactive utilities for working with promises and requests, building over these primitives to provide functions and components that enable you to build robust performant apps with elegant control flow
+
+---
+
+### ♥️ Credits
+
+ <details>
+   <summary>Brought to you with ♥️ love by <a href="https://emberjs.com" title="EmberJS">🐹 Ember</a></summary>
+
+  <style type="text/css">
+    img.project-logo {
+       padding: 0 5em 1em 5em;
+       width: 100px;
+       border-bottom: 2px solid #0969da;
+       margin: 0 auto;
+       display: block;
+     }
+    details > summary {
+      font-size: 1.1rem;
+      line-height: 1rem;
+      margin-bottom: 1rem;
+    }
+    details {
+      font-size: 1rem;
+    }
+    details > summary strong {
+      display: inline-block;
+      padding: .2rem 0;
+      color: #000;
+      border-bottom: 3px solid #0969da;
+    }
+
+    details > details {
+      margin-left: 2rem;
+    }
+    details > details > summary {
+      font-size: 1rem;
+      line-height: 1rem;
+      margin-bottom: 1rem;
+    }
+    details > details > summary strong {
+      display: inline-block;
+      padding: .2rem 0;
+      color: #555;
+      border-bottom: 2px solid #555;
+    }
+    details > details {
+      font-size: .85rem;
+    }
+
+    @media (prefers-color-scheme: dark) {
+      details > summary strong {
+        color: #fff;
+      }
+    }
+    @media (prefers-color-scheme: dark) {
+      details > details > summary strong {
+        color: #afaba0;
+      border-bottom: 2px solid #afaba0;
+      }
+    }
+  </style>
+</details>

package/addon-main.cjs

@@ -0,0 +1,5 @@
+'use strict';
+
+const { addonShim } = require('@warp-drive/core/addon-shim.cjs');
+
+module.exports = addonShim(__dirname);

package/declarations/-private/reactive-context.d.ts

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

package/declarations/-private/request.d.ts

@@ -0,0 +1,140 @@
+import { RequestArgs, type ContentFeatures, type RecoveryFeatures, type RequestLoadingState, type RequestState } from "@warp-drive/core/store/-private";
+import type { StructuredErrorDocument } from "@warp-drive/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/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>
+*        ),
+*      }}
+*    />
+*   );
+* }
+*
+* ```
+*
+*/
+export declare function Request<
+	RT,
+	E
+>($props: RequestProps<RT, E>): JSX.Element;
+export {};

package/declarations/-private/store-provider.d.ts

@@ -0,0 +1,7 @@
+import { Store } from "@warp-drive/core";
+import { JSX, ReactNode } from "react";
+export declare function useStore(): Store;
+export declare function StoreProvider($props: {
+	Store: Store;
+	children: ReactNode;
+}): JSX.Element;

package/declarations/index.d.ts

@@ -0,0 +1,9 @@
+/**
+* React-specific reactivity integration, components
+* and hooks for WarpDrive.
+*
+* @module
+*/
+export { ReactiveContext } from "./-private/reactive-context.js";
+export { StoreProvider, useStore } from "./-private/store-provider.js";
+export { Request, Throw } from "./-private/request.js";

package/declarations/install.d.ts

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

package/dist/index.js

@@ -0,0 +1,265 @@
+import { R as ReactiveContext } from "./reactive-context-zIDLf-L0.js";
+import { Store } from '@warp-drive/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/core/store/-private';
+import '@warp-drive/core/request';
+const StoreContext = /*#__PURE__*/createContext(null);
+function useStore() {
+  const store = use(StoreContext);
+  macroCondition(getGlobalConfig().WarpDrive.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;
+}
+function StoreProvider($props) {
+  const store = useMemo(() => new 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/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>
+ *        ),
+ *      }}
+ *    />
+ *   );
+ * }
+ *
+ * ```
+ *
+ */
+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().WarpDrive.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().WarpDrive.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/install.js

@@ -0,0 +1,115 @@
+import { use } from 'react';
+import { Signal } from 'signal-polyfill';
+import { setupSignals } from '@warp-drive/core/configure';
+import { W as WatcherContext } from "./reactive-context-zIDLf-L0.js";
+import { macroCondition, getGlobalConfig } from '@embroider/macros';
+
+/**
+ * Unlike reactive frameworks, React does not have the ability to support
+ * fine-grained reactivity. However, we can approximate it to "good enough"
+ * granularity by keeping track of signals used within a specific context.
+ *
+ * React also does not have a built-in way to memoize functions the way that
+ * reactive frameworks do, but by building overtop of other Signal libraries
+ * we can provide this.
+ *
+ * Due to the above limitations, @warp-drive/react/install is built
+ * overtop @warp-drive/tc39-proposal-signals/install.
+ *
+ * The TC39 Watcher especially is valuable here, as it allows us to subscribe to changes
+ * to the dependency graph of a memo and not just a signal.
+ */
+
+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().WarpDrive.activeLogging.LOG_REACT_SIGNAL_INTEGRATION)) {
+      if (getGlobalConfig().WarpDrive.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().WarpDrive.activeLogging.LOG_REACT_SIGNAL_INTEGRATION)) {
+      if (getGlobalConfig().WarpDrive.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().WarpDrive.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().WarpDrive.env.DEBUG) ? {
+      obj,
+      key
+    } : null, {
+      equals: () => false
+    }),
+    notifySignal: signal => {
+      if (macroCondition(getGlobalConfig().WarpDrive.activeLogging.LOG_REACT_SIGNAL_INTEGRATION)) {
+        if (getGlobalConfig().WarpDrive.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().WarpDrive.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 };