@warp-drive/core 5.9.0-beta.1 → 5.9.0-beta.2

package/dist/signals/-leaked.d.ts

@@ -0,0 +1,1060 @@
+import { Ct as ReactiveDocument, Xn as StructuredErrorDocument, Y as Store, a as notifyInternalSignal, c as AutorefreshBehaviorCombos, d as RecoveryFeatures, f as RequestArgs, g as RequestLoadingState, i as makeInitializer, l as ContentFeatures, m as SubscriptionArgs, n as WarpDriveSignal, nr as Future, o as peekInternalSignal, or as RequestManager, r as getOrCreateInternalSignal, s as withSignalStore, t as SignalStore, u as DISPOSE } from "../internal-DtWOpxrR.js";
+import { o as waitFor } from "../configure-B_F639tN.js";
+//#region src/signals/page-cache.d.ts
+/**
+ * Extracts the `data` member of a document type, or the document type itself
+ * when it has no `data` member.
+ */
+type ContentData<RT> = RT extends {
+  data: infer D;
+} ? D : RT;
+/**
+ * The element type of a collection document's `data` array — the item type an
+ * infinite view renders. See {@link PaginationState.data}.
+ */
+type ContentItem<RT> = ContentData<RT> extends readonly (infer I)[] ? I : ContentData<RT>;
+/**
+ * A single page of a paginated collection: its request, its loaded document, and
+ * its links to neighboring pages in the shared page graph.
+ *
+ * Pages are yielded to consumers as `Readonly<PageCache>` — through
+ * {@link PaginationState.activePage}, {@link PaginationState.pages}, and the
+ * relational getters below — to read a page's data and request status when
+ * building pagination UIs:
+ *
+ * ```ts
+ * const page = paginationState.activePage;
+ *
+ * if (page?.isLoading) {
+ *   // show a spinner
+ * } else if (page?.isError) {
+ *   // show page.reason
+ * } else {
+ *   // render page.data
+ * }
+ * ```
+ *
+ * @since 5.9.0
+ * @public
+ * @hideconstructor
+ */
+declare class PageCache<RT = unknown, E = unknown> {
+  /**
+   * The request that loaded (or is loading) this page, or `null` if the page is
+   * known from links but was never requested. Wrap it in a `<Request>` component
+   * to render the page's loading, error, and content states.
+   */
+  request: Future<RT> | null;
+  /** The `self` link of this page — the URL that identifies it in the collection. */
+  selfLink: string | null;
+  /** The `prev` link of this page, or `null` at the start of the collection. */
+  prevLink: string | null;
+  /** The `next` link of this page, or `null` at the end of the collection. */
+  nextLink: string | null;
+  /** The `first` link of the collection, when the response exposed one. */
+  firstLink: string | null;
+  /** The `last` link of the collection, when the response exposed one. */
+  lastLink: string | null;
+  /**
+   * The 1-based page number, or `0` when unknown (for example cursor-based
+   * pagination, where pages have no ordinal position). Derived from the
+   * collection's {@link PageHints}.
+   */
+  pageNumber: number;
+  constructor(manager: PaginationCache<RT, E>, url: string);
+  /**
+   * The document this page's request resolved to, or `null` while it has not
+   * resolved.
+   */
+  get value(): RT | null;
+  /**
+   * The `data` member of the loaded document — the page's items — or `null`
+   * while the page has not loaded.
+   */
+  get data(): ContentData<RT> | null;
+  /**
+   * Whether a request has ever been issued for this page. `false` for pages that
+   * are known only from links.
+   */
+  get isRequested(): boolean;
+  /** Whether this page's request has settled (successfully or with an error). */
+  get isLoaded(): boolean;
+  /** Whether this page's request is currently in flight. */
+  get isLoading(): boolean;
+  /** Whether this page's request resolved successfully. */
+  get isSuccess(): boolean;
+  /** Whether this page's request was cancelled (aborted). */
+  get isCancelled(): boolean;
+  /** Whether this page's request rejected with an error. */
+  get isError(): boolean;
+  /** The error this page's request rejected with, or `null` if it did not reject. */
+  get reason(): StructuredErrorDocument<E> | null;
+  /** The page at this page's `prev` link, or `null` at the start of the collection. */
+  get prev(): PageCache<RT, E> | null;
+  /** The page at this page's `next` link, or `null` at the end of the collection. */
+  get next(): PageCache<RT, E> | null;
+  /** The first page of the collection, when the response exposed a `first` link. */
+  get first(): PageCache<RT, E> | null;
+  /** The last page of the collection, when the response exposed a `last` link. */
+  get last(): PageCache<RT, E> | null;
+}
+//#endregion
+//#region src/signals/pagination-cache.d.ts
+/**
+ * A hint function for extracting the `currentPage` and `totalPages` from a loaded
+ * document, for when the response does not expose these values through the
+ * default `meta` locations. Provided by the consumer via `<Paginate />`'s
+ * `@pageHints` arg:
+ *
+ * ```gts
+ * <Paginate @pageHints={{...}} />
+ * ```
+ *
+ * Since these values are attached to the shared {@link PaginationCache}, the hint is
+ * a property of the *collection*, not the component. Every `<Paginate />` sharing a
+ * collection must provide the same function reference — define it once at module
+ * scope and import it everywhere.
+ *
+ * @since 5.9.0
+ * @public
+ */
+interface PageHints {
+  (document: ReactiveDocument<unknown>): {
+    currentPage: number;
+    totalPages: number;
+  };
+}
+/**
+ * The default {@link PageHints}. Reads `currentPage`/`page` and `totalPages` from the
+ * document `meta`, matching the behavior used before `pageHints` was configurable.
+ * Used whenever the consumer does not provide a `pageHints` function.
+ *
+ * @since 5.9.0
+ * @public
+ */
+declare const defaultPageHints: PageHints;
+/**
+ * The global, shared cache for a paginated collection. Keyed by the collection's
+ * `first` (or `self`) link, so that multiple components paging the same collection
+ * share loaded pages, the page graph, and `totalPages`.
+ *
+ * This holds only shared, request-agnostic data. Per-component state (the active
+ * page, navigation) lives on {@link PaginationState}, which is the API consumers
+ * interact with — the cache itself is plumbing shared between the pagination
+ * classes.
+ *
+ * @since 5.9.0
+ * @public
+ * @hideconstructor
+ */
+declare class PaginationCache<RT = unknown, E = unknown> {
+  /**
+   * The total number of pages in the collection, or `0` when unknown. Consumers
+   * should read this via {@link PaginationState.totalPages}.
+   */
+  totalPages: number;
+  constructor(key: string);
+  /**
+   * Every page known to the shared graph, in order — loaded pages and pages
+   * known only from links — across all components sharing the collection.
+   *
+   * This is the whole-collection view. For the run a single component is
+   * viewing, use {@link PaginationState.pages}.
+   *
+   * ```ts
+   * const cache = getPaginationCache(firstLink);
+   * for (const page of cache.pages) {
+   *   // page.isLoaded, page.pageNumber, page.data, ...
+   * }
+   * ```
+   */
+  get pages(): Iterable<Readonly<PageCache<RT, E>>>;
+  /**
+   * The items of every loaded page in the shared graph, flattened into one
+   * contiguous iterable in page order. Pages that are known but not loaded
+   * contribute nothing.
+   *
+   * This is the whole-collection view. For the run a single component is
+   * viewing, use {@link PaginationState.data}.
+   */
+  get data(): Iterable<ContentItem<RT>>;
+}
+/**
+ * Get the shared {@link PaginationCache} for a given cache key (the collection's
+ * `first` or `self` link). Returns the same instance for the same key for the
+ * lifetime of the module.
+ *
+ * @since 5.9.0
+ * @public
+ */
+declare function getPaginationCache<RT, E>(key: string): PaginationCache<RT, E>;
+/**
+ * Clears the module-level pagination cache used by {@link getPaginationCache}.
+ * Primarily intended for test isolation, since the cache is keyed by url and
+ * otherwise persists for the lifetime of the module.
+ *
+ * @since 5.9.0
+ * @public
+ */
+declare function clearPaginationCache(): void;
+//#endregion
+//#region src/signals/pagination-state.d.ts
+/**
+ * The two navigation surfaces a `<Paginate />` component can drive. Selecting
+ * one (via the component's `@mode` arg) narrows the yielded state so the two
+ * APIs cannot be mixed:
+ *
+ * - `'paged'` — single-page view, see {@link PagedPaginationState}.
+ * - `'infinite'` — accumulated view, see {@link InfinitePaginationState}.
+ */
+type PaginateMode = "paged" | "infinite";
+/**
+ * The part of a {@link PaginationState} available to both navigation surfaces.
+ */
+interface SharedPaginationState<RT = unknown, E = unknown> {
+  /** See {@link PaginationState.totalPages}. */
+  readonly totalPages: number;
+  /** See {@link PaginationState.adoptPage}. */
+  adoptPage(request: Future<RT>): Promise<RT | null>;
+}
+/**
+ * The paged (single-page view) surface of a {@link PaginationState}: render
+ * {@link PaginationState.activePageRequest | activePageRequest}, navigate with
+ * {@link PaginationState.loadPage | loadPage}. This is what the `<Paginate />`
+ * component yields in `'paged'` mode (the default).
+ */
+interface PagedPaginationState<RT = unknown, E = unknown> extends SharedPaginationState<RT, E> {
+  /** See {@link PaginationState.activePage}. */
+  readonly activePage: Readonly<PageCache<RT, E>> | null;
+  /** See {@link PaginationState.activePageRequest}. */
+  readonly activePageRequest: Future<RT> | null;
+  /** See {@link PaginationState.loadPage}. */
+  loadPage: (url: string) => Promise<RT | null>;
+}
+/**
+ * The infinite (accumulated view) surface of a {@link PaginationState}: render
+ * {@link PaginationState.data | data}, grow it with
+ * {@link PaginationState.loadNext | loadNext}/{@link PaginationState.loadPrev | loadPrev}.
+ * This is what the `<Paginate />` component yields in `'infinite'` mode.
+ */
+interface InfinitePaginationState<RT = unknown, E = unknown> extends SharedPaginationState<RT, E> {
+  /** See {@link PaginationState.data}. */
+  readonly data: Iterable<ContentItem<RT>>;
+  /** See {@link PaginationState.pages}. */
+  readonly pages: Iterable<Readonly<PageCache<RT, E>>>;
+  /** See {@link PaginationState.hasNext}. */
+  readonly hasNext: boolean;
+  /** See {@link PaginationState.hasPrevious}. */
+  readonly hasPrevious: boolean;
+  /** See {@link PaginationState.nextRequest}. */
+  readonly nextRequest: Future<RT> | null;
+  /** See {@link PaginationState.previousRequest}. */
+  readonly previousRequest: Future<RT> | null;
+  /** See {@link PaginationState.loadNext}. */
+  loadNext: () => Promise<RT | null>;
+  /** See {@link PaginationState.loadPrev}. */
+  loadPrev: () => Promise<RT | null>;
+}
+/**
+ * Resolves a {@link PaginateMode} to the surface it exposes, so a component
+ * generic over the mode can yield only that surface.
+ */
+type PaginationStateFor<RT = unknown, E = unknown, M extends PaginateMode = "paged"> = M extends "infinite" ? InfinitePaginationState<RT, E> : PagedPaginationState<RT, E>;
+/**
+ * The per-component, local pagination state. It houses the state that is unique
+ * to a single component instance — the active page and navigation — while
+ * referencing a shared {@link PaginationCache} for the page graph and data.
+ *
+ * This is the object yielded by the `<Paginate />` component, narrowed by the
+ * component's `@mode` arg to one of its two navigation surfaces so the two
+ * APIs cannot be mixed:
+ *
+ * - **Paged** (`@mode="paged"`, the default): {@link PagedPaginationState} —
+ *   render {@link activePageRequest}, navigate with {@link loadPage} (what the
+ *   numbered/relational links call). Reads {@link activePage}.
+ * - **Infinite** (`@mode="infinite"`): {@link InfinitePaginationState} — render
+ *   {@link data}, wrap {@link nextRequest}/{@link previousRequest} in `<Request>`
+ *   for loading state, and grow the view with {@link loadNext}/{@link loadPrev}.
+ *
+ * Both surfaces read the same shared page graph; the mode only selects which
+ * API is exposed.
+ *
+ * Instances are created via {@link getPaginationState} (or by the `<Paginate />`
+ * component on your behalf), never constructed directly.
+ *
+ * @since 5.9.0
+ * @public
+ * @hideconstructor
+ */
+declare class PaginationState<RT = unknown, E = unknown> implements PagedPaginationState<RT, E>, InfinitePaginationState<RT, E> {
+  /**
+   * The page the paged surface is currently showing. Starts at the page this
+   * component first loaded and moves whenever {@link loadPage} runs (for
+   * example a numbered link is clicked).
+   */
+  activePage: Readonly<PageCache<RT, E>> | null;
+  constructor(request: Future<RT>, pageHints?: PageHints);
+  /**
+   * The request for the {@link activePage}, for the paged surface to render. This
+   * is what a single-page view wraps in a `<Request>` to show the active page's
+   * loading, error, and content states:
+   *
+   * ```gts
+   * <Paginate @request={{this.request}}>
+   *   <:content as |pages|>
+   *     <Request @request={{pages.activePageRequest}}>
+   *       <:content as |result|>
+   *         {{#each result.data as |item|}}...{{/each}}
+   *       </:content>
+   *     </Request>
+   *   </:content>
+   * </Paginate>
+   * ```
+   */
+  get activePageRequest(): Future<RT> | null;
+  /**
+   * The total number of pages in the collection, or `0` when it is unknown (for
+   * example a cursor-based collection that reports no total).
+   *
+   * ```gts
+   * <p>Page {{pages.activePage.pageNumber}} of {{pages.totalPages}}</p>
+   * ```
+   */
+  get totalPages(): number;
+  /**
+   * The pages of the run this component is viewing, from the backward frontier
+   * to the forward frontier inclusive, in order. Part of the infinite surface:
+   * it is the same run as {@link data}, yielding the {@link PageCache} objects
+   * instead of their flattened items — use it when the UI needs per-page
+   * boundaries or request states.
+   *
+   * Grows as {@link loadNext}/{@link loadPrev} extend the frontier. Scoped to
+   * this component's frontier (not the shared cache), so components paging the
+   * same collection to different extents each see only what they have scrolled
+   * through. For every page known to the whole collection, see
+   * {@link PaginationCache.pages}.
+   */
+  get pages(): Iterable<Readonly<PageCache<RT, E>>>;
+  /**
+   * The accumulated items across the loaded run, from the backward frontier to
+   * the forward frontier inclusive — the single set an infinite collection renders.
+   * Grows as {@link loadNext}/{@link loadPrev} extend the frontier. Scoped to this
+   * component's frontier (not the shared cache), so components paging the same
+   * collection to different extents each see only what they have scrolled through.
+   *
+   * The flattened items of {@link pages}, as one contiguous iterable. For the
+   * items of every loaded page in the whole collection, see
+   * {@link PaginationCache.data}.
+   *
+   * ```gts
+   * <Paginate @request={{this.request}} @mode="infinite">
+   *   <:content as |pages features|>
+   *     {{#each pages.data as |item|}}...{{/each}}
+   *     {{#if pages.hasNext}}
+   *       <button {{on "click" features.loadNext}}>Load more</button>
+   *     {{/if}}
+   *   </:content>
+   * </Paginate>
+   * ```
+   */
+  get data(): Iterable<ContentItem<RT>>;
+  /**
+   * Whether a page exists after the forward frontier — i.e. there is more to load
+   * going forward. Use to hide the trailing load-more sentinel at end-of-list:
+   *
+   * ```gts
+   * {{#if pages.hasNext}}
+   *   <button {{on "click" features.loadNext}}>Load more</button>
+   * {{/if}}
+   * ```
+   */
+  get hasNext(): boolean;
+  /**
+   * Whether a page exists before the backward frontier.
+   */
+  get hasPrevious(): boolean;
+  /**
+   * The request for the page just after the forward frontier, for the infinite
+   * surface. `null` until {@link loadNext} fires it (so a `<Request>` wrapping it
+   * renders its idle block), the in-flight `Future` while that page loads, then
+   * `null` again once the frontier advances onto it. Also `null` at end-of-list.
+   *
+   * ```gts
+   * {{#if pages.hasNext}}
+   *   <Request @request={{pages.nextRequest}}>
+   *     <:idle><button {{on "click" features.loadNext}}>Load more</button></:idle>
+   *     <:loading><Spinner /></:loading>
+   *   </Request>
+   * {{/if}}
+   * ```
+   */
+  get nextRequest(): Future<RT> | null;
+  /**
+   * The request for the page just before the backward frontier. Mirror of
+   * {@link nextRequest} for {@link loadPrev}.
+   */
+  get previousRequest(): Future<RT> | null;
+  /**
+   * Adopts an externally-issued request into this pagination, making its page
+   * the {@link activePage} — the programmatic entry point for route-driven
+   * navigation when managing a `PaginationState` directly (the `<Paginate />`
+   * component uses the same mechanism for a changed `@request` arg).
+   *
+   * Awaits the request and verifies that its document is a page of this
+   * state's collection (same `first` — or `self` — link). On a match, the
+   * page is loaded (a page already in the shared cache is reused) and — once
+   * its request settles — committed: it becomes the active page, and the
+   * infinite surface's run is kept coherent (a page already inside the run
+   * leaves it untouched, an adjacent page extends it, a disjoint page resets
+   * the run to the adopted page). The commit happens only after the page has
+   * loaded, so the previous page stays active — and rendered — while the
+   * adoption resolves. Returns the page's document.
+   *
+   * Concurrent calls race safely: the latest call wins. An earlier in-flight
+   * adoption is superseded and commits nothing, and a {@link loadPage}
+   * navigation also supersedes a pending adoption (the user's click is the
+   * newer intent).
+   *
+   * Returns `null` — leaving the state untouched — whenever the adoption does
+   * not commit:
+   *
+   * - the request (or its page's load) rejected
+   * - the document is a page of a *different* collection
+   * - this state has not finished setting up its own collection yet
+   * - the call was superseded by a newer navigation
+   *
+   * ```ts
+   * const pages = getPaginationState(initialRequest);
+   * // later, e.g. in a route model hook reacting to a ?page= param:
+   * const adopted = await pages.adoptPage(store.request(query));
+   * if (adopted === null) {
+   *   // not part of this collection — start a fresh pagination
+   * }
+   * ```
+   *
+   * It is a stable reference, so it is safe to pass around as an "action" or
+   * "event" handler.
+   */
+  adoptPage: (request: Future<RT>) => Promise<RT | null>;
+  /**
+   * Extends the backward frontier by one page, prepending it to {@link data}.
+   * The frontier advances only once the page has loaded, so
+   * {@link previousRequest} tracks the in-flight page meanwhile. Returns the
+   * loaded value, or `null` when there is no previous page or the load fails.
+   *
+   * On failure the frontier stays put and {@link previousRequest} keeps
+   * resolving to the failed page, so a wrapping `<Request>` renders its error
+   * block. Calling again retries: the failed page is re-requested with a
+   * forced reload.
+   *
+   * In templates it is also available as the `loadPrev` content feature
+   * ({@link InfinitePaginationContentFeatures.loadPrev}) yielded by
+   * `<Paginate />`; the two are the same function.
+   *
+   * It is a stable reference, so it is safe to pass around as an "action" or
+   * "event" handler.
+   */
+  loadPrev: () => Promise<RT | null>;
+  /**
+   * Extends the forward frontier by one page, appending it to {@link data}.
+   * Mirror of {@link loadPrev}.
+   *
+   * In templates it is also available as the `loadNext` content feature
+   * ({@link InfinitePaginationContentFeatures.loadNext}) yielded by
+   * `<Paginate />`; the two are the same function.
+   *
+   * ```gts
+   * <button {{on "click" pages.loadNext}}>Load more</button>
+   * ```
+   */
+  loadNext: () => Promise<RT | null>;
+  /**
+   * Loads a specific page by its URL and makes it the {@link activePage},
+   * requesting it first if it is not already loaded. This is the paged surface's
+   * navigation entry point, called by the numbered and relational links.
+   *
+   * In templates it is also available as the `loadPage` content feature
+   * ({@link PagedPaginationContentFeatures.loadPage}) yielded by `<Paginate />`;
+   * the two are the same function.
+   *
+   * It is a stable reference, so it is safe to pass around as an "action" or
+   * "event" handler. Returns the page's value, or `null` if it has none or
+   * the load fails.
+   *
+   * On failure the page stays active and {@link activePageRequest} resolves to
+   * it, so a wrapping `<Request>` renders its error block. Calling again (for
+   * example clicking the page's link a second time) retries: the failed page
+   * is re-requested with a forced reload.
+   *
+   * ```gts
+   * <EachLink @pages={{pages}}>
+   *   <:link as |link|>
+   *     <button {{on "click" (fn features.loadPage link.url)}}>{{link.text}}</button>
+   *   </:link>
+   * </EachLink>
+   * ```
+   */
+  loadPage: (url: string) => Promise<RT | null>;
+}
+/**
+ * Get the {@link PaginationState} for a given request. Returns the same instance
+ * for the same request future, so that repeated calls (e.g. in a template, or
+ * alongside the `<Paginate />` component using the same request) share the same
+ * local pagination state. Keyed by request identity, just like
+ * {@link getRequestState}.
+ *
+ * ```ts
+ * const future = store.request(query);
+ * const pages = getPaginationState(future);
+ *
+ * await future;
+ * pages.totalPages; // now known, if the response exposed it
+ * await pages.loadNext();
+ * ```
+ *
+ * @since 5.9.0
+ * @public
+ */
+declare function getPaginationState<RT, E>(request: Future<RT>, pageHints?: PageHints): PaginationState<RT, E>;
+//#endregion
+//#region src/signals/pagination-links.d.ts
+/**
+ * A single numbered link, e.g. page `3`. Loads its page and makes it active when
+ * {@link setActive} runs. Carries its {@link index} and its
+ * {@link distanceFromActiveIndex} so a UI can style links by how far they sit
+ * from the current page.
+ *
+ * ```gts
+ * <EachLink @pages={{pages}} as |state|>
+ *   {{#each state.links as |link|}}
+ *     {{#if link.isReal}}
+ *       <button class={{if link.isCurrent "active"}} {{on "click" link.setActive}}>
+ *         {{link.text}}
+ *       </button>
+ *     {{/if}}
+ *   {{/each}}
+ * </EachLink>
+ * ```
+ *
+ * @since 5.9.0
+ * @public
+ * @hideconstructor
+ */
+declare class RealPaginationLink {
+  readonly isReal: true;
+  readonly url: string;
+  readonly index: number;
+  readonly isCurrent: boolean;
+  readonly distanceFromActiveIndex: number;
+  constructor(url: string, index: number, activeIndex: number, loadPage: (url: string) => Promise<unknown>);
+  get text(): string;
+  /**
+   * Loads this link's page and makes it the active page on the associated
+   * {@link PaginationState}. It is a stable reference, so it is safe to pass
+   * around as an "action" or "event" handler:
+   *
+   * ```gts
+   * <button {{on "click" link.setActive}}>{{link.text}}</button>
+   * ```
+   */
+  setActive: () => Promise<unknown>;
+}
+/**
+ * A stand-in for a run of pages that have not been loaded yet, rendered as an
+ * ellipsis between numbered links. It covers an {@link indexRange} rather than a
+ * single page and has no page to navigate to.
+ *
+ * ```gts
+ * <EachLink @pages={{pages}} as |state|>
+ *   {{#each state.links as |link|}}
+ *     {{#unless link.isReal}}
+ *       <span title="{{link.rangeSize}} more pages">{{link.text}}</span>
+ *     {{/unless}}
+ *   {{/each}}
+ * </EachLink>
+ * ```
+ *
+ * @since 5.9.0
+ * @public
+ * @hideconstructor
+ */
+declare class PlaceholderPaginationLink {
+  readonly isReal: false;
+  /**
+   * The inclusive `[start, end]` page-number range of not-yet-loaded pages this
+   * placeholder stands in for.
+   */
+  indexRange: [start: number, end: number];
+  text: string;
+  constructor(index: [start: number, end: number], activeIndex: number);
+  /** The number of pages this placeholder covers. */
+  get rangeSize(): number;
+  /**
+   * The distance between the active page and the nearest edge of this
+   * placeholder's index range.
+   */
+  get distanceFromActiveIndex(): number;
+}
+/**
+ * A relational (`first`/`prev`/`next`/`last`) navigation link, relative to the
+ * active page. Unlike {@link RealPaginationLink} these carry no ordinal index —
+ * they are the only links available for cursor-based pagination, where pages are
+ * chained purely by opaque relational links with no page number or total. They
+ * are also available in numbered pagination as a convenience.
+ *
+ * ```gts
+ * <EachLink @pages={{pages}} as |state|>
+ *   {{#if state.prev}}<button {{on "click" state.prev.setActive}}>Previous</button>{{/if}}
+ *   {{#if state.next}}<button {{on "click" state.next.setActive}}>Next</button>{{/if}}
+ * </EachLink>
+ * ```
+ *
+ * @since 5.9.0
+ * @public
+ * @hideconstructor
+ */
+declare class RelationalPaginationLink {
+  readonly isReal: true;
+  readonly rel: "first" | "prev" | "next" | "last";
+  readonly url: string;
+  /**
+   * Whether this link points at the page that is already active — for example
+   * the `first` link while the first page is being viewed. Useful for
+   * disabling the control.
+   */
+  readonly isCurrent: boolean;
+  constructor(rel: "first" | "prev" | "next" | "last", url: string, isCurrent: boolean, loadPage: (url: string) => Promise<unknown>);
+  get text(): string;
+  /**
+   * Loads this link's page and makes it the active page on the associated
+   * {@link PaginationState}. It is a stable reference, so it is safe to pass
+   * around as an "action" or "event" handler:
+   *
+   * ```gts
+   * <button {{on "click" link.setActive}}>{{link.text}}</button>
+   * ```
+   */
+  setActive: () => Promise<unknown>;
+}
+/**
+ * A member of {@link PaginationLinks.links}: either a numbered
+ * {@link RealPaginationLink} or a {@link PlaceholderPaginationLink} standing in
+ * for a gap. Discriminate with {@link RealPaginationLink.isReal | isReal}:
+ *
+ * ```ts
+ * for (const link of links.links) {
+ *   if (link.isReal) {
+ *     // numbered link: link.index, link.setActive
+ *   } else {
+ *     // gap: link.indexRange
+ *   }
+ * }
+ * ```
+ */
+type PaginationLink = RealPaginationLink | PlaceholderPaginationLink;
+/**
+ * The reactive set of navigation links derived from a {@link PaginationState}.
+ * Where `PaginationState` tracks which pages are loaded and which one is active,
+ * `PaginationLinks` turns that page graph into the links a UI renders to move
+ * between pages.
+ *
+ * It provides two kinds of link:
+ *
+ * - {@link links}: the numbered links, with {@link PlaceholderPaginationLink}
+ *   placeholders standing in for gaps of not-yet-loaded pages. Only numbered
+ *   collections (where the server exposes page numbers) produce these.
+ * - {@link prev} and {@link next}: the relational links for the active page.
+ *   Available in both numbered and cursor-based pagination, and the only links a
+ *   cursor-based collection has.
+ * - {@link first} and {@link last}: the relational links to the collection's
+ *   edges, when the response exposes them. Usually present on every page —
+ *   including the edge page itself, where the link's
+ *   {@link RelationalPaginationLink.isCurrent | isCurrent} is `true`.
+ *
+ * Every link updates as pages load and as the active page changes, since they
+ * read straight from the state's shared page graph. To get the links for a
+ * state, use {@link getPaginationLinks}.
+ *
+ * See also:
+ * - {@link RealPaginationLink}
+ * - {@link PlaceholderPaginationLink}
+ * - {@link RelationalPaginationLink}
+ *
+ * @since 5.9.0
+ * @public
+ * @hideconstructor
+ */
+declare class PaginationLinks<RT = unknown, E = unknown> {
+  constructor(paginationState: PagedPaginationState<RT, E>);
+  /**
+   * The relational `first` link of the collection, or `null` when the active
+   * page's response did not expose one. Unlike {@link prev}/{@link next} it is
+   * usually present on every page — including the first page itself, where the
+   * link's {@link RelationalPaginationLink.isCurrent | isCurrent} is `true`
+   * (useful for disabling the control).
+   */
+  get first(): RelationalPaginationLink | null;
+  /**
+   * The relational `prev` link for the active page, or `null` at the start of the
+   * collection. Available in both numbered and cursor pagination.
+   */
+  get prev(): RelationalPaginationLink | null;
+  /**
+   * The relational `next` link for the active page, or `null` at the end of the
+   * collection. Available in both numbered and cursor pagination.
+   */
+  get next(): RelationalPaginationLink | null;
+  /**
+   * The relational `last` link of the collection, or `null` when the active
+   * page's response did not expose one. Mirror of {@link first} for the end of
+   * the collection.
+   */
+  get last(): RelationalPaginationLink | null;
+  /**
+   * The numbered links and placeholders, derived from the shared page graph.
+   *
+   * Only produced for numbered pagination (where the server exposes page numbers).
+   * Cursor-based collections have no page numbers, so this is empty — use
+   * {@link prev}/{@link next} for cursor navigation.
+   */
+  get links(): PaginationLink[];
+}
+/**
+ * Get the {@link PaginationLinks} for a given {@link PaginationState}. Returns
+ * the same instance for the same state, so repeated calls (for example a
+ * `<Paginate />` component and a separate links component reading the same state)
+ * share one set of links. Keyed by state identity, the same way
+ * {@link getPaginationState} is keyed by request and {@link getRequestState} by
+ * future.
+ *
+ * ```ts
+ * const links = getPaginationLinks(paginationState);
+ *
+ * for (const link of links.links) {
+ *   if (link.isReal) {
+ *     // render a numbered link, using link.setActive as the click handler
+ *   } else {
+ *     // render an ellipsis for the gap link.indexRange covers
+ *   }
+ * }
+ * ```
+ *
+ * @since 5.9.0
+ * @public
+ */
+declare function getPaginationLinks<RT, E>(state: PagedPaginationState<RT, E>): Readonly<PaginationLinks<RT, E>>;
+//#endregion
+//#region src/signals/pagination-subscription.d.ts
+interface ErrorFeatures {
+  isHidden: boolean;
+  isOnline: boolean;
+  retry: () => Promise<void>;
+}
+/**
+ * The content features available in both pagination modes: the state and
+ * controls of the initial request.
+ */
+interface SharedPaginationContentFeatures<RT> {
+  isOnline: boolean;
+  isHidden: boolean;
+  isRefreshing: boolean;
+  /**
+   * Whether a changed `@request` arg is currently resolving against the
+   * loaded collection — e.g. a route-driven navigation (browser back button).
+   * The existing content stays rendered while this is `true`; once the
+   * request resolves it either becomes the active page (same collection) or
+   * the component resets to the new collection.
+   */
+  isNavigating: boolean;
+  refresh: () => Promise<void>;
+  reload: () => Promise<void>;
+  abort?: () => void;
+  latestRequest?: Future<RT>;
+}
+/**
+ * The content features yielded in `'paged'` mode: navigation happens by
+ * loading a specific page.
+ */
+interface PagedPaginationContentFeatures<RT> extends SharedPaginationContentFeatures<RT> {
+  loadPage: (url: string) => Promise<RT | null>;
+}
+/**
+ * The content features yielded in `'infinite'` mode: navigation happens by
+ * extending the loaded run at either end.
+ */
+interface InfinitePaginationContentFeatures<RT> extends SharedPaginationContentFeatures<RT> {
+  loadNext: () => Promise<RT | null>;
+  loadPrev: () => Promise<RT | null>;
+}
+/**
+ * The full set of content features a {@link PaginationSubscription} builds —
+ * both modes' surfaces. The `<Paginate />` component narrows this to one mode
+ * via {@link PaginationContentFeaturesFor} before yielding.
+ */
+type PaginationContentFeatures<RT> = PagedPaginationContentFeatures<RT> & InfinitePaginationContentFeatures<RT>;
+/**
+ * Resolves a {@link PaginateMode} to the content features it exposes. Mirror of
+ * {@link PaginationStateFor}.
+ */
+type PaginationContentFeaturesFor<RT = unknown, M extends PaginateMode = "paged"> = M extends "infinite" ? InfinitePaginationContentFeatures<RT> : PagedPaginationContentFeatures<RT>;
+interface PaginationSubscriptionArgs<RT, E> extends SubscriptionArgs<RT, E> {
+  /**
+   * A function to extract the `currentPage` and `totalPages` from a loaded document
+   * when they are not available in the default `meta` locations. Must be the same
+   * reference across all `<Paginate />` components sharing a collection.
+   */
+  pageHints?: PageHints;
+}
+interface PaginateArgs<RT, E> extends PaginationSubscriptionArgs<RT, E> {
+  /**
+   * Which navigation surface the component yields: `'paged'` (the default) or
+   * `'infinite'`. Type-only — it narrows the yielded state and features so the
+   * two surfaces cannot be mixed, and is never read at runtime.
+   */
+  mode?: PaginateMode;
+  subscription?: PaginationSubscription<RT, E>;
+  /**
+   * The store instance to use for making requests. If contexts are available,
+   * the component will default to using the `store` on the context.
+   *
+   * This is required if the store is not available via context or should be
+   * different from the store provided via context.
+   *
+   */
+  store?: Store | RequestManager;
+}
+interface PaginationSubscription<RT, E> {
+  /**
+   * The method to call when the component this subscription is attached to
+   * unmounts.
+   */
+  [DISPOSE](): void;
+}
+/**
+ * Lifecycle glue for the `<Paginate />` component. Owns the initial
+ * {@link RequestSubscription} (loading/error state, autorefresh, disposal) and
+ * the per-component {@link PaginationState} that it hands to the component.
+ *
+ * @since 5.9.0
+ * @public
+ * @hideconstructor
+ */
+declare class PaginationSubscription<RT, E> {
+  /**
+   * The Store this subscription subscribes to or the RequestManager
+   * which issues this request.
+   */
+  store: Store | RequestManager;
+  constructor(store: Store | RequestManager, args: PaginationSubscriptionArgs<RT, E>);
+  /**
+   * The per-component pagination state yielded to the component.
+   *
+   * Keyed to the request that started the collection, not the current
+   * `@request` arg: when the arg changes, the existing state keeps rendering
+   * while {@link _resolveNavigation} resolves the new request in the
+   * background. A request that resolves to a page of the same collection is
+   * adopted into this state as the new active page (route-driven navigation,
+   * e.g. the browser back button); one that resolves to a different
+   * collection swaps in a fresh state (a true reset).
+   *
+   * A background `refresh` does not swap the request, so the pagination
+   * state is stable across refreshes.
+   */
+  get paginationState(): PaginationState<RT, E>;
+  /**
+   * Whether there is no request or query to monitor, so the component has
+   * nothing to load.
+   */
+  get isIdle(): boolean;
+  /**
+   * Whether the collection is still blocking-loading: no {@link PaginationState}
+   * has finished setting up yet. Only the very first page load (or the reset
+   * to a different collection) blocks here — extending the collection with
+   * `loadNext`/`loadPrev` does not, and neither does a changed `@request` arg
+   * while a collection is already on screen (that is {@link isNavigating}).
+   *
+   * Remains `true` for the moment between the request resolving and the
+   * {@link paginationState} finishing its setup from the response, so that
+   * {@link isSuccess} consumers never see a success state with an empty
+   * pagination surface.
+   */
+  get isLoading(): boolean;
+  /**
+   * Whether a changed `@request` arg is resolving while a collection is
+   * already on screen — route-driven navigation, e.g. the browser back
+   * button. The content stays rendered (see {@link isSuccess}); consumers can
+   * use this to show a lightweight navigation indicator, the same way a
+   * `loadPage` call surfaces through the active page's request state.
+   */
+  get isNavigating(): boolean;
+  /**
+   * The {@link RequestLoadingState} for the initial request, for building UIs
+   * that respond to download progress.
+   */
+  get loadingState(): RequestLoadingState;
+  /**
+   * Whether the component has a set-up {@link paginationState} to render and
+   * the current request did not fail. Stays `true` while a changed `@request`
+   * arg resolves ({@link isNavigating}), so the existing content keeps
+   * rendering instead of falling back to a blocking loading state.
+   */
+  get isSuccess(): boolean;
+  /**
+   * Whether the initial request was cancelled (aborted).
+   */
+  get isCancelled(): boolean;
+  /**
+   * Whether the initial request rejected with an error.
+   */
+  get isError(): boolean;
+  /**
+   * The error the initial request rejected with, or `null` if it did not reject.
+   */
+  get reason(): StructuredErrorDocument<E> | null;
+  /**
+   * Error features to yield to the error slot of a component
+   */
+  get errorFeatures(): ErrorFeatures;
+  /**
+   * Content features to yield to the content slot of a component
+   */
+  get contentFeatures(): PaginationContentFeatures<RT>;
+}
+/**
+ * Creates the {@link PaginationSubscription} a `<Paginate />` component uses to
+ * manage its request lifecycle and pagination state. Pass the result back into
+ * the component via `@subscription` to manage the lifecycle externally.
+ *
+ * ```ts
+ * const subscription = createPaginationSubscription(store, { request });
+ *
+ * subscription.paginationState; // the per-component PaginationState
+ * subscription[DISPOSE](); // tear down when the owning component unmounts
+ * ```
+ *
+ * @since 5.9.0
+ * @public
+ */
+declare function createPaginationSubscription<RT, E>(store: Store | RequestManager, args: PaginationSubscriptionArgs<RT, E>): PaginationSubscription<RT, E>;
+//#endregion
+//#region src/signals/pagination-links-subscription.d.ts
+interface PaginationLinksSubscription<RT, E> {
+  /**
+   * The method to call when the component this subscription is attached to
+   * unmounts.
+   */
+  [DISPOSE](): void;
+}
+interface PaginationLinksSubscriptionArgs<RT, E> {
+  pages: PagedPaginationState<RT, E>;
+}
+/**
+ * The framework-agnostic core of a pagination links component (for example the
+ * `<EachLink />` component of `@warp-drive/ember`): it owns the component
+ * lifecycle, while the links themselves live on the {@link PaginationLinks}
+ * it exposes.
+ *
+ * Given the {@link PagedPaginationState} a `<Paginate />` component is driving,
+ * {@link paginationLinks} derives that state's `PaginationLinks` — the numbered
+ * links (with placeholders for gaps) and the relational
+ * `first`/`prev`/`next`/`last` links a component yields for the consumer to
+ * render. All of them read from the same shared page graph as the
+ * `<Paginate />` component, so they stay in sync as pages load and the active
+ * page changes.
+ *
+ * @since 5.9.0
+ * @public
+ * @hideconstructor
+ */
+declare class PaginationLinksSubscription<RT, E> {
+  constructor(args: PaginationLinksSubscriptionArgs<RT, E>);
+  /**
+   * The {@link PaginationLinks} derived from the {@link PagedPaginationState}
+   * passed as an arg — the surface a links component yields to its consumer:
+   * the numbered {@link PaginationLinks.links | links} (empty for cursor-based
+   * collections) and the relational {@link PaginationLinks.first | first}/
+   * {@link PaginationLinks.prev | prev}/{@link PaginationLinks.next | next}/
+   * {@link PaginationLinks.last | last} links.
+   *
+   * Recomputes when the `pages` arg changes, so a component whose pagination
+   * resets to a different collection derives fresh links automatically.
+   */
+  get paginationLinks(): Readonly<PaginationLinks<RT, E>>;
+}
+/**
+ * Creates the {@link PaginationLinksSubscription} a links component (such as
+ * `<EachLink />`) uses to derive its links from a {@link PagedPaginationState}.
+ *
+ * ```ts
+ * const subscription = createPaginationLinksSubscription({ pages: paginationState });
+ *
+ * subscription.paginationLinks; // the derived PaginationLinks
+ * subscription[DISPOSE](); // tear down when the owning component unmounts
+ * ```
+ *
+ * @since 5.9.0
+ * @public
+ */
+declare function createPaginationLinksSubscription<RT, E>(args: PaginationLinksSubscriptionArgs<RT, E>): PaginationLinksSubscription<RT, E>;
+//#endregion
+//#region src/signals/reactivity/signal.d.ts
+/**
+ * Creates a signal for the key/object pairing and subscribes to the signal.
+ *
+ * Use when you need to ensure a signal exists and is subscribed to.
+ *
+ * @private
+ */
+declare function entangleSignal<T extends object>(signals: SignalStore, obj: T, key: string | symbol, initialValue: unknown): WarpDriveSignal;
+/**
+ * define an enumerable signal property.
+ *
+ * Akin to Object.defineProperty.
+ *
+ * The signal will be lazily created when accessed and scoped to the
+ * instance of the object.
+ *
+ * @private
+ */
+declare function defineSignal<T extends object>(obj: T, key: string, v?: unknown): void;
+/**
+ * Define a non-enumerable signal property.
+ *
+ * @private
+ */
+declare function defineNonEnumerableSignal<T extends object>(obj: T, key: string, v?: unknown): void;
+interface DecoratorPropertyDescriptor extends PropertyDescriptor {
+  initializer?: () => unknown;
+}
+/**
+ * Decorator version of creating a signal.
+ */
+declare function signal<T extends object, K extends keyof T & string>(target: T, key: K, descriptor?: DecoratorPropertyDescriptor): void;
+/**
+ * Decorator version of creating a memoized getter
+ */
+declare function memoized<T extends object, K extends keyof T & string>(target: T, key: K, descriptor: PropertyDescriptor): PropertyDescriptor;
+/**
+ * Decorator version of creating a gate.
+ *
+ * @private
+ */
+declare function gate<T extends object, K extends keyof T & string>(_target: T, key: K, desc: PropertyDescriptor): PropertyDescriptor;
+/**
+ * Defines a reactive "gated" property on `obj` using `desc` as its
+ * getter/setter descriptor.
+ *
+ * Unlike a signal defined with {@link defineSignal}, a gated property's
+ * consumers are not notified when the property is set, since its update
+ * is expected to be controlled externally (for instance, by a signal it
+ * derives its value from) unless the descriptor opts into being locally
+ * managed.
+ *
+ * Akin to `Object.defineProperty`.
+ *
+ * @private
+ */
+declare function defineGate<T extends object>(obj: T, key: string, desc: PropertyDescriptor): void;
+//#endregion
+export { type AutorefreshBehaviorCombos, type ContentFeatures, DISPOSE, type InfinitePaginationContentFeatures, type InfinitePaginationState, type PageCache, type PageHints, type PagedPaginationContentFeatures, type PagedPaginationState, type PaginateArgs, type PaginateMode, type PaginationCache, type PaginationContentFeatures, type PaginationContentFeaturesFor, type PaginationLink, type PaginationLinks, type PaginationLinksSubscription, type PaginationState, type PaginationStateFor, type PaginationSubscription, type PlaceholderPaginationLink, type RealPaginationLink, type RecoveryFeatures, type RelationalPaginationLink, type RequestArgs, type SharedPaginationContentFeatures, type SharedPaginationState, type SignalStore, type SubscriptionArgs, clearPaginationCache, createPaginationLinksSubscription, createPaginationSubscription, defaultPageHints, defineGate, defineNonEnumerableSignal, defineSignal, entangleSignal, gate, getOrCreateInternalSignal, getPaginationCache, getPaginationLinks, getPaginationState, makeInitializer, memoized, notifyInternalSignal, peekInternalSignal, signal, waitFor, withSignalStore };
+//# sourceMappingURL=-leaked.d.ts.map