module@warp-drive/ember

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.

What it exports

The main entry point, @warp-drive/ember, provides the request and promise control-flow components and their function forms:

• <Request /> renders a request's idle, loading, content, error and cancelled states, with refresh and autorefresh controls.
• <Await /> does the same for a plain promise.
• getRequestState and getPromiseState, re-exported from @warp-drive/core/reactive, expose the same reactive state to JavaScript.

Paginate reactively

⚠️ Experimental, use at your own risk

The pagination components have not been through an RFC and may change or be removed in a minor release. Read the Experiments guide before depending on them.

The @warp-drive/ember/experiments entry point provides the components for paginated collections:

• <Paginate /> monitors the request that loads a collection's first page and yields a pagination state for navigating its pages, in either paged or infinite mode.
• <EachLink /> yields the numbered, first/prev/next/last page links for a paged collection.

They build on the framework-agnostic primitives published from @warp-drive/experiments/pagination, such as getPaginationState, which is equally usable directly in JavaScript.

Using in .hbs files

The components and reactive utilities this library exports are intended for use with gjs/gts (Ember's Template Tag Format.

To use them in handlebars (.hbs) files, your app should re-export them.

Definition

app/components/await.ts

export { Await as default } from '@warp-drive/ember';

Usage

app/templates/application.hbs

<Await @promise={{this.getTheData}}></Await>

Usage

app/templates/users.hbs

<Paginate @request={{this.usersRequest}}>
  <:content as |pages|>
    <EachLink @pages={{pages}} as |state|>
      {{#each state.links as |link|}}
        <button {{on "click" link.setActive}}>{{link.text}}</button>
      {{/each}}
    </EachLink>
  </:content>
</Paginate>

:::

This approach allows renaming them to avoid conflicts just by using a different filename if desired:

app/components/warp-drive-await.ts

export { Await as default } from '@warp-drive/ember';

hbs

<WarpDriveAwait @promise={{this.getTheData}}></WarpDriveAwait>

Guides

• Installation: install @warp-drive/ember and add the @warp-drive/ember/install import to your app and tests.
• Setup: configure the build plugin in ember-cli-build and create a Store.
• Reactivity: how WarpDrive uses your framework's signals.
• Making Requests: make a request with <Request /> or getRequestState.
• Reactive Control Flow: render a request's loading, error and content states.
• Async as Reactive State: derive a promise's state with getPromiseState and <Await />.
• Testing: mock your app's requests in tests with holodeck.
• Pagination: the experimental <Paginate /> and <EachLink /> components.

Components

• Await
• Request
• Throw

Other

• experiments
• install
• EmberRequestArgs
• RequestSignature