ngwr 14.5.1 → 14.6.0

package/types/ngwr-select.d.ts

@@ -39,6 +39,21 @@ 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 button trigger.
+ */
+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 +82,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 +125,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 +158,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 +549,33 @@ 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. The search-shaped triggers do not
+     * draw one: their selection is an `<input>`'s text, which cannot hold markup.
+     */
+    protected readonly selectedLeading: _angular_core.Signal<TemplateRef<WrOptionLeadingContext<unknown>> | null>;
     /**
      * Trigger label for single mode. Multi reads `selectedChips` instead.
      *
@@ -768,19 +830,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 +856,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 +913,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 +928,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 +938,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 +977,65 @@ 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. The
+ *   search-shaped triggers (`mode="search"`, `[searchable]`) do not draw it: their
+ *   selection is the text of an `<input>`, which cannot hold markup.
+ *
+ * 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.6.0";
 
 /**
  * @license