ngwr 14.5.1 → 14.7.0

package/types/ngwr-image-cropper.d.ts

@@ -18,6 +18,45 @@ interface WrCropRect {
 type WrCropHandle = 'move' | 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw';
 /** Supported output MIME types for {@link WrImageCropper.toBlob}. */
 type WrImageOutputType = 'image/png' | 'image/jpeg' | 'image/webp';
+/**
+ * Where the cropper's source stands.
+ *
+ * - `empty` — no `src`, so the placeholder is showing.
+ * - `loading` — a `src` has been handed to the `<img>` and the browser has not
+ *   answered yet.
+ * - `loaded` — the image decoded. The crop window opens once it also has a
+ *   measured size, which in a browser is the same moment.
+ * - `failed` — the browser could not decode it (a renamed `.heic`, a truncated
+ *   file, a URL that 404s). `(loadError)` fired with the details.
+ */
+type WrImageCropperStatus = 'empty' | 'loading' | 'loaded' | 'failed';
+/**
+ * The payload of `(loadError)` — plain strings and numbers, so it can be logged,
+ * sent to an error tracker or put into a store as it is.
+ *
+ * The browser's `error` event carries no reason at all, so none is invented here:
+ * what the source DECLARED is the most a host has to work with, and for the common
+ * case (a phone photo in a format this browser cannot decode) `type` and `name`
+ * are what tell the two apart from a broken upload.
+ */
+interface WrImageLoadError {
+    /**
+     * The URL the `<img>` was given — the `src` string itself, or the object URL
+     * made for a `File` / `Blob`. An object URL is revoked as soon as `src` changes,
+     * so it identifies the attempt rather than being something to fetch later.
+     */
+    readonly url: string;
+    /** `File.name` for a `File` source; `null` for a `Blob` or a string. */
+    readonly name: string | null;
+    /**
+     * The MIME type a `File` / `Blob` declares — `''` when it declares none, and
+     * `null` for a string source. A `File`'s type comes from its extension, so a
+     * renamed file declares the type of the name it was given.
+     */
+    readonly type: string | null;
+    /** Size in bytes for a `File` / `Blob`; `null` for a string source. */
+    readonly size: number | null;
+}
 
 interface RectPx {
     x: number;
@@ -37,12 +76,18 @@ interface RectPx {
  * freshly-rendered `Blob` of the cropped region. For one-off reads use
  * `toBlob()` / `toDataUrl()`.
  *
+ * A source the browser cannot decode fires `(loadError)` once, sets `status()` to
+ * `'failed'` and puts `wr-image-cropper--failed` on the host. The component renders
+ * no message of its own for it — what went wrong and what to do next is the host's
+ * to say.
+ *
  * @example
  * ```html
  * <wr-image-cropper
  *   [src]="file"
  *   [aspectRatio]="1"
  *   (cropped)="onBlob($event)"
+ *   (loadError)="onUnreadable($event)"
  * />
  * ```
  *
@@ -61,8 +106,23 @@ declare class WrImageCropper {
     readonly outputType: _angular_core.InputSignal<WrImageOutputType>;
     /** JPEG / WebP quality for `(cropped)` in [0, 1]. @default 0.92 */
     readonly outputQuality: _angular_core.InputSignal<number>;
+    /**
+     * Longest side of the exported image, in pixels — for `(cropped)`, `toBlob()` and
+     * `toDataUrl()` alike. A crop larger than this is scaled down to fit, keeping its
+     * aspect ratio; a smaller one is exported as it is, never upscaled. The crop itself
+     * — `cropRect()`, in source pixels — is not affected. `null` (or anything that is
+     * not a positive number) exports at the source image's own resolution.
+     * @default null
+     */
+    readonly maxOutputSize: _angular_core.InputSignalWithTransform<number | null, unknown>;
     /** Emits a Blob after each drag end. */
     readonly cropped: _angular_core.OutputEmitterRef<Blob>;
+    /**
+     * Fires once when the browser cannot decode the current `src` — a format it does
+     * not support, a broken file, a URL that fails. Nothing is rendered for it; show
+     * your own message. A new `src` clears the failure.
+     */
+    readonly loadError: _angular_core.OutputEmitterRef<WrImageLoadError>;
     protected readonly imgEl: _angular_core.Signal<ElementRef<HTMLImageElement>>;
     /** Resolved object URL for `src` (so File / Blob render in `<img>`). */
     protected readonly emptyText: _angular_core.Signal<string>;
@@ -97,7 +157,20 @@ declare class WrImageCropper {
     private active;
     private startPointer;
     private startRect;
+    /** The element the live drag set pointer capture on, so the end releases that one. */
+    private captureTarget;
+    /** The pointer the live drag belongs to. Every other pointer's events are ignored. */
+    private pointerId;
+    /** How far past each side of the crop the live resize was pressed — see `onPointerMove`. */
+    private overhang;
     private readonly destroyRef;
+    private readonly statusState;
+    /**
+     * Where the source stands: `'empty'`, `'loading'`, `'loaded'` or `'failed'`. Reset
+     * to `'loading'` (or `'empty'`) whenever `src` changes, so a failure never outlives
+     * the source that caused it.
+     */
+    readonly status: _angular_core.Signal<WrImageCropperStatus>;
     /** Resolved crop rect in natural (source) pixel coordinates. */
     readonly cropRect: _angular_core.Signal<WrCropRect>;
     constructor();
@@ -113,6 +186,18 @@ declare class WrImageCropper {
      */
     private resetGeometry;
     protected onImageLoad(): void;
+    /**
+     * The `<img>` could not decode its source.
+     *
+     * Before this handler existed a failed decode left the component exactly as it
+     * looks while loading — an image with no size, no crop window, nothing emitted —
+     * so a host had no way to tell "still decoding" from "never going to", and a user
+     * who picked a `.heic` the browser cannot read saw an empty box and no reason.
+     *
+     * Once per source: `status` is reset by a new `src` and by nothing else, so a
+     * second `error` for the same source says nothing new and is not re-emitted.
+     */
+    protected onImageError(): void;
     /**
      * Keep `display` on the box the image is actually rendered at.
      *
@@ -138,8 +223,50 @@ declare class WrImageCropper {
     private initialCrop;
     protected readonly handles: readonly WrCropHandle[];
     protected onPointerDown(handle: WrCropHandle, event: PointerEvent): void;
+    /**
+     * A resize ENDS when the pointer leaves the image, exactly as `pointerup` would end it:
+     * the move that carried it out is applied — clamped to the image like any other — and
+     * then the drag is over. Nothing after that resumes it or changes the crop, pointer
+     * back over the image or not, until a new `pointerdown`. A move drag is not affected:
+     * its size is fixed, so it simply rests against the edge.
+     *
+     * The move that leaves is applied rather than dropped because pointer moves are
+     * SAMPLES. Dropped, a quick drag toward a corner would stop wherever its last sample
+     * inside happened to fall — a single move from a handle to past the image would change
+     * nothing at all — and even a slow one would stop a fraction of a pixel short of the
+     * edge. A drag that leaves across one edge still ends there: heading for a corner at a
+     * slant that crosses the bottom first, the crop's right edge stays where it was then.
+     *
+     * "The image" is the `<img>`'s own box — the bounds `applyMove` / `applyResize` clamp
+     * the crop to — with its edges counting as inside, since the crop may reach them. The
+     * box is re-measured on every move and compared with `clientX` / `clientY`: both are
+     * viewport coordinates, so a scroll mid-drag cannot put them out of step. The moves
+     * outside reach this handler at all only because the drag holds pointer capture.
+     *
+     * One allowance, fixed at `pointerdown`: the box is widened on each side by however far
+     * past that side of the CROP the press landed — at most as far as the pressed handle
+     * reaches past it. Half of an edge handle, and three quarters of a corner handle, lies
+     * outside the crop, so a press there already has the pointer ahead of the edge it drags.
+     * Measured without the allowance, that pointer would leave the image while the crop was
+     * still short of the image's edge by the same distance, with nothing able to close the
+     * gap; and a handle resting on the image's edge, pressed on its outer part, would begin
+     * its drag already outside. A press on a handle's inner part widens nothing.
+     */
     protected onPointerMove(event: PointerEvent): void;
+    /**
+     * Ends the drag — for `pointerup`, `pointercancel`, a capture lost to something else,
+     * and a resize whose pointer left the image. Once per drag: the capture released here
+     * fires `lostpointercapture` afterwards, and by then there is nothing left to end.
+     *
+     * Only for the pointer that started it. A second finger is refused a drag of its own at
+     * `pointerdown`, but its moves and its lifting reach these handlers all the same, and
+     * would otherwise drive or end the first finger's drag.
+     */
     protected onPointerUp(event: PointerEvent): void;
+    /** How far past each side of the crop window the pointer is, in CSS pixels. */
+    private pastCrop;
+    /** Whether the pointer is on the image, edges and the press's `overhang` included. */
+    private withinImage;
     /** Whether a key has moved the crop since the last `keyup`. */
     private keyboardDirty;
     /**
@@ -176,11 +303,18 @@ declare class WrImageCropper {
     toDataUrl(type?: WrImageOutputType, quality?: number): string;
     /** Re-emit the crop without waiting for a drag (e.g. after a programmatic change). */
     refresh(): Promise<void>;
+    /**
+     * The exported image's pixel size: the crop in source pixels, scaled down so its
+     * longer side fits `maxOutputSize`. `Math.min(1, …)` is the never-upscale rule — a
+     * crop already inside the cap keeps its own size, which is also the whole of the
+     * uncapped path.
+     */
+    private outputSize;
     private toCanvas;
     private emitCropped;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrImageCropper, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrImageCropper, "wr-image-cropper", never, { "src": { "alias": "src"; "required": false; "isSignal": true; }; "aspectRatio": { "alias": "aspectRatio"; "required": false; "isSignal": true; }; "minWidth": { "alias": "minWidth"; "required": false; "isSignal": true; }; "minHeight": { "alias": "minHeight"; "required": false; "isSignal": true; }; "outputType": { "alias": "outputType"; "required": false; "isSignal": true; }; "outputQuality": { "alias": "outputQuality"; "required": false; "isSignal": true; }; }, { "cropped": "cropped"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrImageCropper, "wr-image-cropper", never, { "src": { "alias": "src"; "required": false; "isSignal": true; }; "aspectRatio": { "alias": "aspectRatio"; "required": false; "isSignal": true; }; "minWidth": { "alias": "minWidth"; "required": false; "isSignal": true; }; "minHeight": { "alias": "minHeight"; "required": false; "isSignal": true; }; "outputType": { "alias": "outputType"; "required": false; "isSignal": true; }; "outputQuality": { "alias": "outputQuality"; "required": false; "isSignal": true; }; "maxOutputSize": { "alias": "maxOutputSize"; "required": false; "isSignal": true; }; }, { "cropped": "cropped"; "loadError": "loadError"; }, never, never, true, never>;
 }
 
 export { WrImageCropper };
-export type { WrCropHandle, WrCropRect, WrImageOutputType };
+export type { WrCropHandle, WrCropRect, WrImageCropperStatus, WrImageLoadError, WrImageOutputType };

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

@@ -51,8 +51,25 @@ declare class WrOptionHarness extends ComponentHarness {
     static hostSelector: string;
     /** Build a predicate that narrows the query. */
     static with(options?: WrOptionHarnessFilters): HarnessPredicate<WrOptionHarness>;
-    /** The option's label, trimmed. */
+    /**
+     * The option's text as drawn, trimmed — without its leading visual.
+     *
+     * A `wrOptionLeading` template renders INSIDE the row, so reading the whole
+     * host would hand back an avatar's initials as the first word of the name. It
+     * is excluded here for the same reason the select excludes it from the label.
+     *
+     * This is the drawn text, not the `label` input: an option whose `label` is
+     * shorter than what it draws still answers with what it draws. What the select
+     * REPORTS for it is on the select harness, as `getValueText()` or
+     * `getChipLabels()`.
+     */
     getText(): Promise<string>;
+    /**
+     * Whether the row is drawing a leading visual right now. Reads the slot the
+     * select renders the template into, so it answers `false` for an option that
+     * declares a template while the panel is closed — which is the contract.
+     */
+    hasLeading(): Promise<boolean>;
     /** Whether the option is currently selected. */
     isSelected(): Promise<boolean>;
     /** Whether the option refuses selection. */

package/types/ngwr-select.d.ts

@@ -39,6 +39,25 @@ 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';
+/**
+ * Where a `wrOptionLeading` template is being drawn:
+ *
+ * - `'option'` — the row in the open panel.
+ * - `'chip'` — a selected chip on a `mode="multi"` trigger.
+ * - `'value'` — the selected value on a single-mode trigger: beside the label on
+ *   a button trigger, and before the input on a search-shaped one while that
+ *   input is showing the label. One placement rather than two, because it is one
+ *   surface — the same size is right on both, and splitting it would ask every
+ *   consumer to name a case they do not have.
+ */
+type WrOptionLeadingPlacement = 'option' | 'chip' | 'value';
+/** Template context of `<ng-template wrOptionLeading>`. */
+interface WrOptionLeadingContext<T = unknown> {
+    /** The option's value — `let-value`. */
+    readonly $implicit: T;
+    /** Where this copy is drawn, so one template can size itself per surface. */
+    readonly placement: WrOptionLeadingPlacement;
+}
 
 /**
  * @license
@@ -67,6 +86,13 @@ interface WrSelectOptionRegistration {
      * registration that cannot supply an element simply keeps its place.
      */
     readonly host?: HTMLElement;
+    /**
+     * The option's own `wrOptionLeading` template, when it declares one. Chips
+     * look it up by value, since a chip is drawn by the select and not by the
+     * option. Optional, like `host`: a registration without one falls back to the
+     * select's default template.
+     */
+    readonly leading?: Signal<TemplateRef<WrOptionLeadingContext> | null>;
 }
 /**
  * Contract a `<wr-option>` uses to talk to its parent `<wr-select>`.
@@ -103,6 +129,17 @@ interface WrSelectContext {
      * `[serverSearch]`), in which case options must NOT self-hide.
      */
     readonly clientFilter: Signal<boolean>;
+    /**
+     * Whether the panel is open. An option draws its leading visual only while it
+     * is, because projected options exist — detached — for the whole life of the
+     * select, and a template instantiated there would be every avatar at once.
+     */
+    readonly panelOpen: Signal<boolean>;
+    /**
+     * The select-wide `wrOptionLeading` template — one declared as a direct child
+     * of `<wr-select>` — or `null`. An option with a template of its own ignores it.
+     */
+    readonly optionLeading: Signal<TemplateRef<WrOptionLeadingContext> | null>;
     /** Is the given option value currently selected? Handles both single and multi. */
     isSelected(value: unknown): boolean;
     /**
@@ -125,6 +162,8 @@ declare const WR_SELECT: InjectionToken<WrSelectContext>;
 interface SelectedChip {
     readonly value: unknown;
     readonly label: string;
+    /** The leading template this chip draws, or `null`. */
+    readonly leading: TemplateRef<WrOptionLeadingContext> | null;
 }
 /**
  * Combobox primitive. Renders a button that opens a CDK overlay
@@ -514,6 +553,61 @@ declare class WrSelect implements FormValueControl<unknown>, WrSelectContext {
     /** Id of the active option (for `aria-activedescendant`). */
     readonly activeOptionId: _angular_core.Signal<string | null>;
     protected readonly open: _angular_core.WritableSignal<boolean>;
+    /** WrSelectContext — whether the panel is open. Options gate their leading visual on it. */
+    readonly panelOpen: _angular_core.Signal<boolean>;
+    /**
+     * A `<ng-template wrOptionLeading>` declared as a DIRECT child of the select —
+     * `descendants: false`, so an option's own template is never mistaken for the
+     * select-wide default.
+     */
+    private readonly defaultLeading;
+    /**
+     * WrSelectContext — the select-wide leading template, or `null`. The only
+     * way to give a leading visual to the rows the select draws itself (`[options]`,
+     * `[loader]` results, virtual rows), and the default for projected options that
+     * declare none of their own.
+     */
+    readonly optionLeading: _angular_core.Signal<TemplateRef<WrOptionLeadingContext<unknown>> | null>;
+    /**
+     * The leading template for a value: the registered option's (its own, or the
+     * default it resolved to), else the select-wide default for a value with no
+     * registered option — a virtual row, or one a loader has since dropped.
+     */
+    private leadingFor;
+    /**
+     * The leading visual beside the selected value on a single-mode BUTTON trigger
+     * — one instance, for the one selected value. A search-shaped trigger draws the
+     * same visual through {@link searchLeading}, on a narrower condition.
+     */
+    protected readonly selectedLeading: _angular_core.Signal<TemplateRef<WrOptionLeadingContext<unknown>> | null>;
+    /**
+     * The same visual on a SEARCH-shaped trigger (`mode="search"`, a searchable
+     * single), drawn before the input — the surface an assignee picker actually
+     * uses, and the one that lost its avatar the moment the trigger became a field.
+     *
+     * The condition is {@link searchShowsValue} rather than `hasSelection()`, and
+     * the two part company on every open panel: focusing the field replaces the
+     * label with the live query, which starts empty, so what is on screen is the
+     * placeholder. An avatar left standing there names a value the field no longer
+     * shows, and then sits in front of whatever the user types next — the visual
+     * would be answering a different question from the text beside it. It comes
+     * back with the label, which is one signal flipping rather than two things
+     * kept in step: committing a choice clears the query and closes the panel.
+     *
+     * Nothing is instantiated for a search select with no selection, panel open or
+     * shut — `selectedLabel()` is `null` there, and this returns `null` with it.
+     *
+     * The COST of that rule, stated because it is a consumer's to weigh: stepping
+     * aside is a destroy, so opening the picker and dismissing it unchanged
+     * re-creates the visual — a template built on an `<img>` re-mounts once per
+     * round trip, and re-requests unless the cache answers. Kept rather than
+     * traded for a hidden-but-alive node: the panel's own rows already create and
+     * destroy one apiece on the same gesture, so holding this one back buys a
+     * fraction of that, and a node retained while it must not be seen is a second
+     * piece of state to keep in step with the field. Pinned in `option.spec.ts`
+     * ("re-creates it after a round trip"), so a future change here has to say so.
+     */
+    protected readonly searchLeading: _angular_core.Signal<TemplateRef<WrOptionLeadingContext<unknown>> | null>;
     /**
      * Trigger label for single mode. Multi reads `selectedChips` instead.
      *
@@ -686,6 +780,26 @@ declare class WrSelect implements FormValueControl<unknown>, WrSelectContext {
     protected onSearchFocus(): void;
     protected onSearchBlur(): void;
     protected onSearchKey(event: KeyboardEvent): void;
+    /**
+     * Whether the search field is showing the SELECTED VALUE rather than a query.
+     * `searchDisplay` takes its text off this, and `searchLeading` the visual that
+     * goes before it, so the two can never disagree about which of the two things
+     * the field is holding.
+     *
+     * FOCUS as well as open, and that second term is the whole `[minChars]` story.
+     * Backspacing under the threshold closes the panel, and falling back to the
+     * selected label the moment `open()` goes false rewrote the field out from
+     * under someone who was still typing — "sma" -> "sm" showed an empty box.
+     *
+     * A NON-EMPTY query, though: picking an option clears it and leaves focus in
+     * the field, and there the label is what belongs on screen.
+     *
+     * Only the search-shaped trigger reads it. A searchable MULTI binds its input
+     * to `searchQuery()` directly and shows its selection as chips, which carry
+     * their own leading visuals whatever the field holds.
+     * @internal
+     */
+    protected readonly searchShowsValue: _angular_core.Signal<boolean>;
     /**
      * Display text for the search input. Shows the selected option's
      * label when collapsed, or the live query while typing / panel open.
@@ -768,19 +882,25 @@ declare class WrSelect implements FormValueControl<unknown>, WrSelectContext {
     private openOverlay;
     private closeOverlay;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrSelect, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrSelect, "wr-select", never, { "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "clearLabel": { "alias": "clearLabel"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "rounded": { "alias": "rounded"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "responsive": { "alias": "responsive"; "required": false; "isSignal": true; }; "mode": { "alias": "mode"; "required": false; "isSignal": true; }; "searchable": { "alias": "searchable"; "required": false; "isSignal": true; }; "searchQuery": { "alias": "searchQuery"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "required": false; "isSignal": true; }; "displayWith": { "alias": "displayWith"; "required": false; "isSignal": true; }; "loader": { "alias": "loader"; "required": false; "isSignal": true; }; "serverSearch": { "alias": "serverSearch"; "required": false; "isSignal": true; }; "debounceMs": { "alias": "debounceMs"; "required": false; "isSignal": true; }; "minChars": { "alias": "minChars"; "required": false; "isSignal": true; }; "freeText": { "alias": "freeText"; "required": false; "isSignal": true; }; "virtualScroll": { "alias": "virtualScroll"; "required": false; "isSignal": true; }; "rowHeight": { "alias": "rowHeight"; "required": false; "isSignal": true; }; "viewportHeight": { "alias": "viewportHeight"; "required": false; "isSignal": true; }; "overscan": { "alias": "overscan"; "required": false; "isSignal": true; }; "noResultsText": { "alias": "noResultsText"; "required": false; "isSignal": true; }; "loadingText": { "alias": "loadingText"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "separators": { "alias": "separators"; "required": false; "isSignal": true; }; "allowDuplicates": { "alias": "allowDuplicates"; "required": false; "isSignal": true; }; "validate": { "alias": "validate"; "required": false; "isSignal": true; }; "clearable": { "alias": "clearable"; "required": false; "isSignal": true; }; "maxItems": { "alias": "maxItems"; "required": false; "isSignal": true; }; "maxTagCount": { "alias": "maxTagCount"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "searchQuery": "searchQueryChange"; "searchChange": "searchChange"; "value": "valueChange"; "touch": "touch"; }, ["projectedOptions"], ["*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrSelect, "wr-select", never, { "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "clearLabel": { "alias": "clearLabel"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "rounded": { "alias": "rounded"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "responsive": { "alias": "responsive"; "required": false; "isSignal": true; }; "mode": { "alias": "mode"; "required": false; "isSignal": true; }; "searchable": { "alias": "searchable"; "required": false; "isSignal": true; }; "searchQuery": { "alias": "searchQuery"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "required": false; "isSignal": true; }; "displayWith": { "alias": "displayWith"; "required": false; "isSignal": true; }; "loader": { "alias": "loader"; "required": false; "isSignal": true; }; "serverSearch": { "alias": "serverSearch"; "required": false; "isSignal": true; }; "debounceMs": { "alias": "debounceMs"; "required": false; "isSignal": true; }; "minChars": { "alias": "minChars"; "required": false; "isSignal": true; }; "freeText": { "alias": "freeText"; "required": false; "isSignal": true; }; "virtualScroll": { "alias": "virtualScroll"; "required": false; "isSignal": true; }; "rowHeight": { "alias": "rowHeight"; "required": false; "isSignal": true; }; "viewportHeight": { "alias": "viewportHeight"; "required": false; "isSignal": true; }; "overscan": { "alias": "overscan"; "required": false; "isSignal": true; }; "noResultsText": { "alias": "noResultsText"; "required": false; "isSignal": true; }; "loadingText": { "alias": "loadingText"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "separators": { "alias": "separators"; "required": false; "isSignal": true; }; "allowDuplicates": { "alias": "allowDuplicates"; "required": false; "isSignal": true; }; "validate": { "alias": "validate"; "required": false; "isSignal": true; }; "clearable": { "alias": "clearable"; "required": false; "isSignal": true; }; "maxItems": { "alias": "maxItems"; "required": false; "isSignal": true; }; "maxTagCount": { "alias": "maxTagCount"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "searchQuery": "searchQueryChange"; "searchChange": "searchChange"; "value": "valueChange"; "touch": "touch"; }, ["defaultLeading", "projectedOptions"], ["*"], true, never>;
 }
 
 /**
  * Single option inside a `<wr-select>`.
  *
- * The option's display label is taken from its projected text content;
- * the form value is its `value` input.
+ * The option's display label is taken from its projected text content — or
+ * from `label`, when that is set — and the form value is its `value` input. A
+ * leading visual goes in an `<ng-template wrOptionLeading>`, which keeps it out
+ * of the label and uninstantiated while the panel is closed.
  *
  * @example
  * ```html
  * <wr-option value="sm">Small</wr-option>
  * <wr-option [value]="42">Forty-two</wr-option>
+ * <wr-option [value]="p.id" [label]="p.name">
+ *   <ng-template wrOptionLeading><wr-avatar shape="circle" size="1.5rem">{{ p.initials }}</wr-avatar></ng-template>
+ *   {{ p.name }}
+ * </wr-option>
  * ```
  */
 declare class WrOption {
@@ -788,10 +908,40 @@ declare class WrOption {
     readonly value: _angular_core.InputSignal<unknown>;
     /** Disable this option. @default false */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, any>;
+    /**
+     * The text the select reports for this option — the trigger label, the chip,
+     * the chip's remove label and the search filter all read it. Unset (or empty),
+     * the option's own text is used, as it always was.
+     *
+     * Set it when the row shows more than the name: a projected email under a
+     * person, a count beside a category. It does NOT rename the row itself — the
+     * option's accessible name stays the text it draws, since a screen reader user
+     * browsing the list should hear what a sighted one reads there.
+     *
+     * @default null
+     */
+    readonly label: _angular_core.InputSignal<string | null>;
     /** Stable id used for `aria-activedescendant`. */
     readonly id: string;
     private readonly host;
     private readonly parent;
+    /** This option's own `<ng-template wrOptionLeading>`, if it declares one. */
+    private readonly ownLeading;
+    /**
+     * The leading template that applies to this option: its own, else the
+     * select-wide default. Registered with the parent so a chip can draw it.
+     */
+    private readonly leading;
+    /**
+     * The leading template to draw in THIS row right now — `null` while the panel
+     * is closed. A projected option is created with the page and lives, detached,
+     * for as long as the select does, so gating on the template alone would
+     * instantiate every row's avatar the moment the page renders. An option with
+     * no parent select has no panel to wait for.
+     */
+    protected readonly rowLeading: Signal<TemplateRef<WrOptionLeadingContext<unknown>> | null>;
+    /** The wrapper the leading visual renders into — skipped when reading the text. */
+    private readonly leadingSlot;
     /**
      * The option's own text, as a signal — the parent's trigger label and the
      * client-side filter both read it from here.
@@ -815,7 +965,12 @@ declare class WrOption {
      * @internal
      */
     private readonly labelText;
-    private readonly label;
+    /**
+     * `label` when set, otherwise the option's own text. What the parent reads.
+     * Not `??`: an EMPTY label falls back too, since a blank trigger or a nameless
+     * chip is never what a `[label]="person.name"` on a missing name meant.
+     */
+    private readonly resolvedLabel;
     /**
      * @internal — true when this option is currently selected. Works for
      * both single and multi-select parents via `WrSelectContext.isSelected`.
@@ -825,7 +980,8 @@ declare class WrOption {
     protected readonly active: Signal<boolean>;
     /**
      * @internal — searchable selects only. True when the parent has a query that
-     * the option's text content does not match (case-insensitive substring).
+     * the option's label does not match (case-insensitive substring) — `label`
+     * when set, the option's text otherwise, and never its leading visual.
      * Hidden options stay in the DOM so registration order survives but
      * collapse via CSS.
      */
@@ -834,13 +990,20 @@ declare class WrOption {
     constructor();
     /**
      * Read the projected text back off the DOM. Setting the same string again is
-     * a signal no-op, so the render hook costs a `textContent` read and nothing
-     * else on the passes where nothing moved.
+     * a signal no-op, so the render hook costs a short walk over the host's
+     * children and nothing else on the passes where nothing moved.
+     *
+     * A walk rather than the host's `textContent`, because the leading visual
+     * renders INSIDE the host while the panel is open: a `textContent` read turned
+     * an avatar's initials into the first word of the label, so the chip and the
+     * search filter read "ХР Хегай Роман". Only text and element children count —
+     * a comment's `textContent` is its data, and Angular anchors every
+     * `<ng-template>` with one.
      */
     private syncLabel;
     protected onClick(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrOption, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrOption, "wr-option", never, { "value": { "alias": "value"; "required": true; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrOption, "wr-option", never, { "value": { "alias": "value"; "required": true; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; }, {}, ["ownLeading"], ["*"], true, never>;
 }
 
 /**
@@ -866,5 +1029,70 @@ declare class WrOptionGroup {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrOptionGroup, "wr-option-group", never, { "label": { "alias": "label"; "required": true; "isSignal": true; }; }, {}, never, ["*"], true, never>;
 }
 
-export { WR_SELECT, WrOption, WrOptionGroup, WrSelect };
-export type { WrSelectContext, WrSelectMode, WrSelectSearchLoader, WrSelectSize, WrSelectTagValidator };
+/**
+ * @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
+ */
+
+/**
+ * A leading visual — an avatar, an icon, a colour dot — drawn before an
+ * option's label, and kept out of that label.
+ *
+ * It is a TEMPLATE, and that is the point. Projected `<wr-option>` children are
+ * created as soon as the page renders, panel open or not, so an avatar written
+ * straight into each option is 200 components and 200 image requests for an
+ * assignee picker nobody has opened. A template is only instantiated where it is
+ * drawn:
+ *
+ * - in an option row, while the panel is OPEN — destroyed again when it closes,
+ *   and under `virtualScroll` only for the rows in the rendered window;
+ * - in a selected chip on a `mode="multi"` trigger, one per visible chip;
+ * - beside the selected value on a single-mode BUTTON trigger — one copy;
+ * - before the input on a SEARCH-shaped trigger (`mode="search"`, a searchable
+ *   single), while that input is showing the selected label. It goes beside the
+ *   field rather than into it — an `<input>` holds a string — and it steps aside
+ *   while a query is on screen, panel open or half-typed, because the value it
+ *   names is not what the field is showing then. Picking an option brings it
+ *   back with the label. Stepping aside is a DESTROY, like a closing panel's
+ *   rows, so an `<img>`-backed visual re-mounts once per open-and-dismiss.
+ *
+ * Every copy sits in an `aria-hidden` wrapper and is skipped when the option's
+ * text is read, so the trigger label, the chip, the search filter and the
+ * option's accessible name all stay the option's words — never "ХР Хегай Роман".
+ * Anything the visual says has to be said by the label as well.
+ *
+ * Two places to declare it. Inside a `<wr-option>` it belongs to that option.
+ * As a DIRECT child of `<wr-select>` it is the default for every row, which is the
+ * only way to reach rows the select draws itself — `[options]`, `[loader]`
+ * results and virtual rows. An option's own template wins over the select's.
+ *
+ * @example
+ * ```html
+ * <wr-select mode="multi" placeholder="Assignees" [(value)]="assignees">
+ *   @for (p of people; track p.id) {
+ *     <wr-option [value]="p.id">
+ *       <ng-template wrOptionLeading let-placement="placement">
+ *         <wr-avatar shape="circle" [size]="placement === 'chip' ? 16 : 24" [url]="p.photo">{{ p.initials }}</wr-avatar>
+ *       </ng-template>
+ *       {{ p.name }}
+ *     </wr-option>
+ *   }
+ * </wr-select>
+ * ```
+ */
+declare class WrOptionLeading {
+    readonly template: TemplateRef<WrOptionLeadingContext<unknown>>;
+    /**
+     * Types the template's `let-` variables under `strictTemplates`. Without it
+     * `let-placement` is `any`, and indexing a `Record<WrOptionLeadingPlacement, …>`
+     * with it — the obvious way to size one visual per surface — does not compile.
+     */
+    static ngTemplateContextGuard(_dir: WrOptionLeading, _ctx: unknown): _ctx is WrOptionLeadingContext;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrOptionLeading, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<WrOptionLeading, "ng-template[wrOptionLeading]", never, {}, {}, never, never, true, never>;
+}
+
+export { WR_SELECT, WrOption, WrOptionGroup, WrOptionLeading, WrSelect };
+export type { WrOptionLeadingContext, WrOptionLeadingPlacement, WrSelectContext, WrSelectMode, WrSelectSearchLoader, WrSelectSize, WrSelectTagValidator };

package/types/ngwr-version.d.ts

@@ -16,7 +16,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.
  */
-declare const NGWR_VERSION = "14.5.1";
+declare const NGWR_VERSION = "14.7.0";
 
 /**
  * @license