ngwr 15.2.0 → 15.3.0

package/types/ngwr-select-testing.d.ts

@@ -144,6 +144,15 @@ export declare class WrSelectHarness extends ComponentHarness {
   removeChip(label: string): Promise<void>;
   /** The "no results" message, or `null` when the panel is showing options. */
   getNoResultsText(): Promise<string | null>;
+  /** The error row's text after a failed load, retry label included, or `null` while there is none. */
+  getLoadErrorText(): Promise<string | null>;
+  /**
+   * Runs a failed load again: Enter in the field where the field names the error
+   * row as active, which works for a `wrSelectLoadError` template too, else a
+   * click on the default Try again button (under `freeText`, where Enter commits
+   * the text). Throws when no retry is on offer.
+   */
+  retryLoad(): Promise<void>;
   /** Whether the panel is showing its async loading row. */
   isLoading(): Promise<boolean>;
   /** Move keyboard focus to the select. */

package/types/ngwr-select.d.ts

@@ -118,6 +118,28 @@ interface WrSelectContext {
   /** Register an option; returns an unregister function. */
   registerOption(reg: WrSelectOptionRegistration): () => void;
 }
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+/** Template context of `<ng-template wrSelectLoadError>`. */
+interface WrSelectLoadErrorContext<E = unknown> {
+  /** What the loader threw or rejected with: `let-error`. */
+  readonly $implicit: E;
+  /** The query whose load failed. */
+  readonly query: string;
+  /**
+   * A retry is on offer: `retryable` is set and nothing else is in the panel. Draw
+   * the retry control only while it is, the way the default row does.
+   */
+  readonly canRetry: boolean;
+  /** Runs the load again for that query, while `canRetry` and no retry is in flight. */
+  readonly retry: () => void;
+  /** A retry is in flight, so the template can draw a loader. */
+  readonly retrying: boolean;
+}
 /**
  * Behavior mode for `<wr-select>`. The component is the unified
  * combobox primitive — every shape (single, multi, type-to-search,
@@ -145,6 +167,42 @@ type WrSelectTagValidator = (value: string, existing: readonly string[]) => bool
 type WrSelectSearchLoader<T> = (query: string) => Observable<readonly T[]> | Promise<readonly T[]> | readonly T[];
 /** Control size for `<wr-select>` — shares the `--wr-control-*` contract. */
 type WrSelectSize = 'sm' | 'md' | 'lg';
+/**
+ * Replaces what a failed `[loader]` shows in the panel: the message, the retry
+ * button, a loader while the retry runs, any text of the app's own. Declare it as
+ * a DIRECT child of `<wr-select>`. The context carries the error, the query that
+ * failed, `canRetry`, `retry()` and `retrying`.
+ *
+ * **It draws inside the error row, and that row is an option of the listbox**,
+ * since the panel element is the listbox and may own nothing else. So the
+ * template holds nothing focusable: a `<button>` inside an option is nested
+ * interactive content. Draw a retry the way the default does, a `<span>` with
+ * the `.wr-btn` classes and `(click)="retry()"`, inside `@if (canRetry)`. The
+ * select's `retryable` decides `canRetry`, and lets Enter in the field reach it.
+ *
+ * @example
+ * ```html
+ * <wr-select mode="search" retryable [loader]="search">
+ *   <ng-template wrSelectLoadError let-error let-canRetry="canRetry" let-retry="retry" let-retrying="retrying">
+ *     <p>Search is offline: {{ error.message }}</p>
+ *     @if (canRetry) {
+ *       <span class="wr-btn wr-btn--sm" (click)="retry()">{{ retrying ? 'Retrying…' : 'Retry' }}</span>
+ *     }
+ *   </ng-template>
+ * </wr-select>
+ * ```
+ */
+export declare class WrSelectLoadError<E = SafeAny> {
+  readonly template: TemplateRef<WrSelectLoadErrorContext<E>>;
+  /**
+   * Types the template's `let-` variables under `strictTemplates`. `E` defaults
+   * to `SafeAny` for the reason `WrOptionLeading` gives: nothing infers the error
+   * type, and narrowed to `unknown`, `error.message` would not compile.
+   */
+  static ngTemplateContextGuard<E>(_dir: WrSelectLoadError<E>, _ctx: unknown): _ctx is WrSelectLoadErrorContext<E>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<WrSelectLoadError<any>, never>;
+  static ɵdir: i0.ɵɵDirectiveDeclaration<WrSelectLoadError<any>, "ng-template[wrSelectLoadError]", never, {}, {}, never, never, true, never>;
+}
 interface SelectedChip {
   readonly value: unknown;
   readonly label: string;
@@ -430,8 +488,27 @@ export declare class WrSelect implements FormValueControl<unknown>, WrSelectCont
   readonly noResultsText: import("@angular/core").InputSignal<string | null>;
   /** Search mode: text shown while the async loader is in flight. Falls back to `select.loading`. */
   readonly loadingText: import("@angular/core").InputSignal<string | null>;
+  /**
+   * Search mode: text shown in place of the "no results" row when the async
+   * loader fails. Falls back to `select.loadError`.
+   */
+  readonly loadErrorText: import("@angular/core").InputSignal<string | null>;
+  /**
+   * Search mode: let a failed load be tried again, for the same query, while the
+   * panel has nothing else to offer. The error row draws a Try again button, and
+   * Enter in the field reaches it, except under `freeText`, where Enter still
+   * commits the typed text. Without it the row only reports the failure; the next keystroke
+   * tries again either way.
+   *
+   * @default false
+   */
+  readonly retryable: import("@angular/core").InputSignalWithTransform<boolean, any>;
+  /** Search mode: label of the retry action on the error row. Falls back to `select.retry`. */
+  readonly retryText: import("@angular/core").InputSignal<string | null>;
   protected readonly resolvedNoResults: import("@angular/core").Signal<string>;
   protected readonly resolvedLoading: import("@angular/core").Signal<string>;
+  protected readonly resolvedLoadError: import("@angular/core").Signal<string>;
+  protected readonly resolvedRetry: import("@angular/core").Signal<string>;
   /**
    * Debounced search query, gated to searchable selects. Emits on every settled
    * change — including the empty string when the field is cleared — so a
@@ -468,6 +545,19 @@ export declare class WrSelect implements FormValueControl<unknown>, WrSelectCont
   private readonly loaderLoading;
   /** Either flag shows the panel's progress row. @internal */
   protected readonly isLoading: import("@angular/core").Signal<boolean>;
+  /** The query whose load failed, until a load for another query starts or one succeeds. */
+  private readonly failedQuery;
+  /** What the failed load threw or rejected with. */
+  private readonly loadErrorValue;
+  /** A retry is in flight. The error row stays up for it, with a loader. */
+  protected readonly retrying: import("@angular/core").WritableSignal<boolean>;
+  /**
+   * The load for the query on screen failed. Keyed by the query, so a keystroke
+   * takes the error down at once, rather than when its debounced load starts.
+   */
+  protected readonly loadFailed: import("@angular/core").Signal<boolean>;
+  /** Asks the loader pipeline to run the current query again. */
+  private readonly retryRequests;
   /**
    * Tag mode: keys / characters that commit the current draft into a chip.
    * `'Enter'` is the key name; everything else is a literal character watched
@@ -748,6 +838,28 @@ export declare class WrSelect implements FormValueControl<unknown>, WrSelectCont
   protected readonly meetsMinChars: import("@angular/core").Signal<boolean>;
   /** Search mode: show "no results" when the panel has nothing to offer. */
   protected readonly hasNoResults: import("@angular/core").Signal<boolean>;
+  /** Search mode: the error row, in place of "no results", after a failed load and through its retry. */
+  protected readonly showLoadError: import("@angular/core").Signal<boolean>;
+  /** A `<ng-template wrSelectLoadError>` declared as a direct child, or `undefined`. */
+  protected readonly loadErrorTpl: import("@angular/core").Signal<WrSelectLoadError<any> | undefined>;
+  /** What `wrSelectLoadError` is handed. */
+  protected readonly loadErrorContext: import("@angular/core").Signal<{
+    $implicit: unknown;
+    query: string;
+    canRetry: boolean;
+    retry: () => void;
+    retrying: boolean;
+  }>;
+  /** One function for the context, gated the way the default button is. */
+  private readonly retryFn;
+  /**
+   * Search mode: the error row offers a retry. Only while nothing else is on
+   * offer, since the arrows walk the options and never reach this row; with
+   * options beside it, a retry by pointer alone would have no keyboard twin.
+   */
+  protected readonly retryOffered: import("@angular/core").Signal<boolean>;
+  /** Id of the error row, which `aria-activedescendant` names while it offers a retry. */
+  protected readonly retryRowId: string;
   /** Search mode: is this option hidden by the current query? @internal */
   private isOptionHidden;
   protected readonly panelTpl: import("@angular/core").Signal<TemplateRef<any>>;
@@ -844,6 +956,10 @@ export declare class WrSelect implements FormValueControl<unknown>, WrSelectCont
   private overlayRef;
   constructor();
   isSelected(value: unknown): boolean;
+  /** Runs the loader again for the query that failed, unless a retry is already in flight. @internal */
+  private retryLoad;
+  /** The retry button runs the load only while it is on offer. @internal */
+  protected onLoadErrorClick(): void;
   selectOption(value: unknown): void;
   /**
    * Adds a `<wr-option>` to the registry and returns its unregister function.
@@ -1021,6 +1137,21 @@ export declare class WrSelect implements FormValueControl<unknown>, WrSelectCont
       "required": false;
       "isSignal": true;
     };
+    "loadErrorText": {
+      "alias": "loadErrorText";
+      "required": false;
+      "isSignal": true;
+    };
+    "retryable": {
+      "alias": "retryable";
+      "required": false;
+      "isSignal": true;
+    };
+    "retryText": {
+      "alias": "retryText";
+      "required": false;
+      "isSignal": true;
+    };
     "loading": {
       "alias": "loading";
       "required": false;
@@ -1071,7 +1202,7 @@ export declare class WrSelect implements FormValueControl<unknown>, WrSelectCont
     "searchChange": "searchChange";
     "value": "valueChange";
     "touch": "touch";
-  }, ["defaultLeading", "projectedOptions"], ["*"], true, never>;
+  }, ["defaultLeading", "projectedOptions", "loadErrorTpl"], ["*"], true, never>;
 }
 /**
  * Single option inside a `<wr-select>`.
@@ -1323,4 +1454,4 @@ export declare class WrOptionLeading<T = SafeAny> {
  * @internal
  */
 export declare const WR_SELECT: InjectionToken<WrSelectContext>;
-export type { WrOptionLeadingContext, WrOptionLeadingPlacement, WrSelectContext, WrSelectMode, WrSelectSearchLoader, WrSelectSize, WrSelectTagValidator };
+export type { WrOptionLeadingContext, WrOptionLeadingPlacement, WrSelectContext, WrSelectLoadErrorContext, WrSelectMode, WrSelectSearchLoader, WrSelectSize, WrSelectTagValidator };

package/types/ngwr-sidebar.d.ts

@@ -1,6 +1,6 @@
 import * as i0 from "@angular/core";
-import { WrIconName } from "ngwr/icon";
 import { IsActiveMatchOptions } from "@angular/router";
+import { WrIconName } from "ngwr/icon";
 /**
  * What `[routerLinkActiveOptions]` accepts: the short form, or any subset of the
  * router's own match options (`paths`, `queryParams`, `matrixParams`, `fragment`).

package/types/ngwr-version.d.ts

@@ -15,7 +15,7 @@ import { InjectionToken } from "@angular/core";
  * Distinct from `Version` exported by `@angular/core`, which reports the
  * loaded Angular runtime version (e.g. `'22.0.0'`), not ngwr's.
  */
-export declare const NGWR_VERSION = "15.2.0";
+export declare const NGWR_VERSION = "15.3.0";
 /**
  * Injection token holding the ngwr library version string.
  *