@warp-drive-mirror/ember 5.8.0-alpha.30 → 5.8.0-alpha.32

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

@@ -0,0 +1,81 @@
+import type Owner from "@ember/owner";
+import Component from "@glimmer/component";
+import { type PromiseState } from "@warp-drive-mirror/core/reactive";
+import type { Awaitable } from "@warp-drive-mirror/core/request";
+export declare const and: (x: unknown, y: unknown) => boolean;
+interface ThrowSignature<E = Error | string | object> {
+	Args: {
+		error: E;
+	};
+}
+/**
+* The `<Throw />` component is used to throw an error in a template.
+*
+* That's all it does. So don't use it unless the application should
+* throw an error if it reaches this point in the template.
+*
+* ```gts
+* <Throw @error={{anError}} />
+* ```
+*
+* @category Components
+* @public
+*/ export declare class Throw<T> extends Component<ThrowSignature<T>> {
+	constructor(owner: Owner, args: ThrowSignature<T>["Args"]);
+}
+interface AwaitSignature<
+	T,
+	E = Error | string | object
+> {
+	Args: {
+		promise: Promise<T> | Awaitable<T, E>;
+	};
+	Blocks: {
+		pending: [];
+		error: [error: E];
+		success: [value: T];
+	};
+}
+/**
+* The `<Await />` component allow you to utilize reactive control flow
+* for asynchronous states in your application.
+*
+* Await is ideal for handling "boundaries", outside which some state is
+* still allowed to be unresolved and within which it MUST be resolved.
+*
+* ```gts
+* import { Await } from '@warp-drive-mirror/ember';
+*
+* <template>
+*   <Await @promise={{@request}}>
+*     <:pending>
+*       <Spinner />
+*     </:pending>
+*
+*     <:error as |error|>
+*       <ErrorForm @error={{error}} />
+*     </:error>
+*
+*     <:success as |result|>
+*       <h1>{{result.title}}</h1>
+*     </:success>
+*   </Await>
+* </template>
+* ```
+*
+* The `<Await />` component requires that error states are properly handled.
+*
+* If no error block is provided and the promise rejects, the error will
+* be thrown.
+*
+* @category Components
+* @public
+*/ export declare class Await<
+	T,
+	E
+> extends Component<AwaitSignature<T, E>> {
+	get state(): Readonly<PromiseState<T, E>>;
+	get error(): E;
+	get result(): T;
+}
+export {};

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

@@ -0,0 +1,289 @@
+import Component from "@glimmer/component";
+import type { ComponentLike } from "@glint/template";
+import type { RequestManager, Store } from "@warp-drive-mirror/core";
+import type { ContentFeatures, RecoveryFeatures, RequestArgs, RequestLoadingState, RequestState, RequestSubscription } from "@warp-drive-mirror/core/store/-private";
+import type { StructuredErrorDocument } from "@warp-drive-mirror/core/types/request";
+export { ContentFeatures, RecoveryFeatures };
+export interface EmberRequestArgs<
+	RT,
+	E
+> extends RequestArgs<RT, E> {
+	chrome?: ComponentLike<{
+		Blocks: {
+			default: [];
+		};
+		Args: {
+			state: RequestState | null;
+			features: ContentFeatures<RT>;
+		};
+	}>;
+}
+interface RequestSignature<
+	RT,
+	E
+> {
+	Args: EmberRequestArgs<RT, E>;
+	Blocks: {
+		/**
+		* The block to render when the component is idle and waiting to be given a request.
+		*
+		*/ idle: [];
+		/**
+		* The block to render when the request is loading.
+		*
+		*/ loading: [state: RequestLoadingState];
+		/**
+		* The block to render when the request was cancelled.
+		*
+		*/ cancelled: [error: StructuredErrorDocument<E>, 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: [error: StructuredErrorDocument<E>, features: RecoveryFeatures];
+		/**
+		* The block to render when the request succeeded.
+		*
+		*/ content: [value: RT, features: ContentFeatures<RT>];
+		always: [state: RequestState<RT, StructuredErrorDocument<E>>];
+	};
+}
+/**
+* The `<Request />` component is a powerful tool for managing data fetching and
+* state in your Ember 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.
+*
+* As with the `<Await />` component, if no error block is provided and the request
+* rejects, the error will be thrown. Cancellation errors are swallowed instead of
+* rethrown if no error block or cancellation block is present.
+*
+* ```gts
+* import { Request } from '@warp-drive-mirror/ember';
+*
+* <template>
+*   <Request @request={{@request}}>
+*     <:loading as |state|>
+*       <Spinner @percentDone={{state.completedRatio}} />
+*       <button {{on "click" state.abort}}>Cancel</button>
+*     </:loading>
+*
+*     <:error as |error state|>
+*       <ErrorForm @error={{error}} />
+*       <button {{on "click" state.retry}}>Retry</button>
+*     </:error>
+*
+*     <:content as |data state|>
+*       <h1>{{data.title}}</h1>
+*       {{#if state.isBackgroundReloading}}
+*         <SmallSpinner />
+*         <button {{on "click" state.abort}}>Cancel</button>
+*       {{else}}
+*         <button {{on "click" state.refresh}}>Refresh</button>
+*       {{/if}}
+*     </:content>
+*
+*     <:cancelled as |error state|>
+*       <h2>The Request was cancelled</h2>
+*       <button {{on "click" state.retry}}>Retry</button>
+*     </:cancelled>
+*
+*     <:idle>
+*       <button {{on "click" @kickOffRequest}}>Load Preview?</button>
+*     </:idle>
+*
+*   </Request>
+* </template>
+* ```
+*
+* ## Streaming Data
+*
+* The loading state exposes the download `ReadableStream` instance for consumption
+*
+* ```gts
+* import { Request } from '@warp-drive-mirror/ember';
+*
+* <template>
+*   <Request @request={{@request}}>
+*     <:loading as |state|>
+*       <Video @stream={{state.stream}} />
+*     </:loading>
+*
+*     <:error as |error|>
+*       <ErrorForm @error={{error}} />
+*     </:error>
+*   </Request>
+* </template>
+* ```
+*
+* ## Retry
+*
+* Cancelled and error'd requests may be retried by calling the `retry` method.
+*
+* Retry will restart the state progression, using the loading, error, cancelled,
+* and content blocks as appropriate.
+*
+* ## Reloading
+*
+* The `reload` method will force the request to be fully re-executed, bypassing
+* cache and restarting the state progression through the loading, error, and
+* content blocks as appropriate.
+*
+* Background reload (refresh) is a special substate of the content state that
+* allows you to refresh the request in the background. This is useful for when
+* you want to update the data in the background without blocking the UI.
+*
+* Reload and refresh are available as methods on the `content` state.
+*
+* ```gts
+* import { Request } from '@warp-drive-mirror/ember';
+*
+* <template>
+*   <Request @request={{@request}}>
+*     <:content as |data state|>
+*       <h1>{{data.title}}</h1>
+*       {{#if state.isBackgroundReloading}}
+*         <SmallSpinner />
+*         <button {{on "click" state.abort}}>Cancel</button>
+*       {{/if}}
+*
+*       <button {{on "click" state.refresh}}>Refresh</button>
+*       <button {{on "click" state.reload}}>Reload</button>
+*     </:content>
+*  </Request>
+* </template>
+* ```
+*
+* ## Advanced Reloading
+*
+* We can nest our usage of `<Request />` to handle more advanced
+* reloading scenarios.
+*
+* ```gts
+* import { Request } from '@warp-drive-mirror/ember';
+*
+* <template>
+*   <Request @request={{@request}}>
+*     <:cancelled>
+*       <h2>The Request Cancelled</h2>
+*     </:cancelled>
+*
+*     <:error as |error|>
+*       <ErrorForm @error={{error}} />
+*     </:error>
+*
+*     <:content as |result state|>
+*       <Request @request={{state.latestRequest}}>
+*         <!-- Handle Background Request -->
+*       </Request>
+*
+*       <h1>{{result.title}}</h1>
+*
+*       <button {{on "click" state.refresh}}>Refresh</button>
+*     </:content>
+*   </Request>
+* </template>
+* ```
+*
+* ## Autorefresh
+*
+* `<Request />` supports automatic refresh and reload under certain conditions.
+*
+* - `online`: This occurs when a browser window or tab comes back to the foreground
+*   after being backgrounded or when the network reports as being online after
+*   having been offline.
+* - `interval`: This occurs when a specified amount of time has passed.
+* - `invalid`: This occurs when the store emits a notification that the request
+*   has become invalid.
+*
+* You can specify when autorefresh should occur by setting the `autorefresh` arg
+* to `true` or a comma-separated list of the above values.
+*
+* A value of `true` is equivalent to `'online,invalid'`.
+*
+* By default, an autorefresh will only occur if the browser was backgrounded or
+* offline for more than 30s before coming back available. This amount of time can
+* be tweaked by setting the number of milliseconds via `@autorefreshThreshold`.
+*
+* This arg also controls the interval at which the request will be refreshed
+* if the `interval` autorefresh type is enabled.
+*
+* Finally, the behavior of the request initiated by autorefresh can be adjusted
+* by setting the `autorefreshBehavior` arg to `'refresh'`, `'reload'`, or `'policy'`.
+*
+* - `'refresh'`: Refresh the request in the background
+* - `'reload'`: Force a reload of the request
+* - `'policy'` (**default**): Let the store's configured CachePolicy decide whether to
+*    reload, refresh, or do nothing.
+*
+* More advanced refresh and reload behaviors can be created by passing the reload and
+* refresh actions into another component. For instance, refresh could be set up on a
+* timer or on a websocket subscription.
+*
+*
+* ```gts
+* import { Request } from '@warp-drive-mirror/ember';
+*
+* <template>
+*   <Request @request={{@request}}>
+*     <:content as |result state|>
+*       <h1>{{result.title}}</h1>
+*
+*       <Interval @period={{30_000}} @fn={{state.refresh}} />
+*       <Subscribe @channel={{@someValue}} @fn={{state.refresh}} />
+*     </:content>
+*   </Request>
+* </template>
+* ```
+*
+* If a matching request is refreshed or reloaded by any other component,
+* the `Request` component will react accordingly.
+*
+* ## Deduping
+*
+* The store dedupes requests by identity. If a request is made for the same identity
+* from multiple `<Request />` components, even if the request is not referentially the
+* same, only one actual request will be made.
+*
+* @category Components
+* @public
+*/ export declare class Request<
+	RT,
+	E
+> extends Component<RequestSignature<RT, E>> {
+	get store(): Store | RequestManager;
+	_state: RequestSubscription<RT, E> | null;
+	get state(): RequestSubscription<RT, E>;
+	/**
+	* The chrome component to use for rendering the request.
+	*
+	* @private
+	*/ get Chrome(): ComponentLike<{
+		Blocks: {
+			default: [];
+		};
+		Args: {
+			state: RequestState | null;
+			features: ContentFeatures<RT>;
+		};
+	}>;
+	willDestroy(): void;
+}

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

@@ -0,0 +1,8 @@
+/**
+* @module
+* @mergeModuleWith <project>
+*/
+export { Request, type ContentFeatures, type RecoveryFeatures } from "./-private/request.js";
+export { Await, Throw } from "./-private/await.js";
+export { getRequestState, createRequestSubscription, type RequestLoadingState, type RequestState } from "@warp-drive-mirror/core/store/-private";
+export { getPromiseState, type PromiseState } from "@warp-drive-mirror/core/reactive";

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

@@ -0,0 +1,6 @@
+import type { SignalHooks } from "@warp-drive-mirror/core/store/-private";
+export declare function buildSignalConfig(options: {
+	wellknown: {
+		Array: symbol | string;
+	};
+}): SignalHooks;