ngwr 14.5.0 → 14.6.0

package/table/styles/_index.scss

@@ -389,6 +389,14 @@
     padding: 0;
     cursor: pointer;
     color: inherit;
+    // The indicator inside is a bare `.wr-icon__svg`, which is `1em`, and a
+    // `<button>` does not inherit its font-size: it takes the browser's control
+    // font (about 13.33px) unless the app resets it. So the same glyph measured
+    // 13.33px on a page with no reset and 12px under `ngwr/reset`, which sets
+    // `font: inherit`. Inheriting the size makes `1em` the header's own text in
+    // every app. `--wr-icon-size` cannot do this job — only a `<wr-icon>` host
+    // reads it, and the rule here used to set it for nothing.
+    font-size: inherit;
     line-height: 0;
   }
 
@@ -741,21 +749,35 @@
 
 .wr-table-sort {
   display: inline-flex;
-  --wr-icon-size: 0.875rem;
+  // Unsorted is the flat line the template draws, at full strength in the muted
+  // role — the same ink as the filter funnel beside it. It used to be the sort
+  // ARROW at half opacity, which is how an unsorted column came to read as
+  // "sorted ascending, dimmed". The glyph carries the state now, so the opacity
+  // has no job left, and dropping it is what lifts the indicator over the 3:1 a
+  // graphic that identifies a control is held to. Measured on the header's own
+  // background in Chromium, after the colour transition settled: from 1.98:1 to
+  // 4.78:1 in light (`#5f6c7d` on `#eff2f6`) and from 2.74:1 to 7.04:1 in dark
+  // (`#9aa6b8` on `#131a2b`). An SVG stroke is invisible to axe, so re-measure
+  // by hand if this ink or the header fill ever moves.
   color: var(--wr-color-on-surface-muted);
-  transition:
-    transform var(--wr-transition-base),
-    color var(--wr-transition-base);
-  opacity: 0.5;
-
-  &--asc {
-    opacity: 1;
+  // Only the colour eases back to unsorted. A transition is taken from the
+  // state being ENTERED, so leaving `--desc` for the base would otherwise spin
+  // the flat line from 180deg to 0 — motion with no direction to report. The
+  // turn between the two arrows still animates, since both modifiers carry it.
+  transition: color var(--wr-transition-base);
+
+  // The template swaps the glyph — a flat line while unsorted, an arrow here
+  // (table-sort.ts) — so the state reads from the shape, and the primary ink
+  // only says which column is the sorted one.
+  &--asc,
+  &--desc {
     color: var(--wr-color-primary);
+    transition:
+      transform var(--wr-transition-base),
+      color var(--wr-transition-base);
   }
 
   &--desc {
-    opacity: 1;
-    color: var(--wr-color-primary);
     transform: rotate(180deg);
   }
 }
@@ -781,7 +803,13 @@
     padding: 0;
     cursor: pointer;
     color: inherit;
-    --wr-icon-size: 0.875rem;
+    // The funnel is the same bare `1em` svg as the sort indicator beside it, in
+    // the same kind of `<button>`, so it inherits the header's font-size for the
+    // same reason (see `.wr-table__sort-btn`). The size only, not the `font`
+    // shorthand: that would also bring the header's 1.25rem line-height, and the
+    // count pill beside the funnel — 10px type with no line-height of its own —
+    // grows from 12px to 20px tall under it.
+    font-size: inherit;
   }
 
   &__count {
@@ -855,7 +883,6 @@
     border-radius: var(--wr-border-radius-sm);
     border: 1px solid var(--wr-color-outline);
     color: transparent;
-    --wr-icon-size: 0.75rem;
     transition: var(--wr-transition-base);
   }
 

package/types/ngwr-avatar.d.ts

@@ -40,19 +40,25 @@ type WrAvatarSize = number | `${number}` | `${number}px` | `${number}rem`;
 /**
  * Image avatar with configurable corner treatment.
  *
- * A spinner is shown while the image loads, then crossfades in.
+ * Projected content (typically initials) is the FALLBACK: it shows with no
+ * `url`, while the image loads and after it fails, and leaves the paint once the
+ * image has loaded. It is projected into a `.wr-avatar__content` wrapper, so a
+ * `wr-avatar > …` child selector no longer reaches it. While it is there, no
+ * spinner is drawn over it; with nothing projected, the spinner marks the
+ * loading state instead. See `alt` for what a screen reader hears.
  *
  * @example
  * ```html
  * <wr-avatar url="/me.png" alt="Roman" size="3rem" shape="circle" />
- * <wr-avatar url="/me.png" alt="Roman" [size]="48" />
+ * <wr-avatar [url]="photo" alt="Roman Khegay" [size]="48">RK</wr-avatar>
  * ```
  *
  * @see https://ngwr.dev/reference/components/avatar
  */
 declare class WrAvatar {
     /**
-     * Image URL. When unset, only projected content (e.g. initials) renders.
+     * Image URL. Projected content (e.g. initials) shows while it is unset,
+     * loading or broken, and gives way once the image has loaded.
      *
      * @default null
      */
@@ -61,6 +67,11 @@ declare class WrAvatar {
      * Alt text for the image. Falls back to `avatar.alt`, then `'Avatar'` — pass
      * the person's name where you have it, since that is what a reader wants.
      *
+     * With an `alt`, projected initials are hidden from assistive technology while
+     * an image is in play, so the name is announced once. Without one, the image
+     * carries only the generic name, so the initials stay announced beside it —
+     * visually hidden once it has loaded, never dropped.
+     *
      * @default null
      */
     readonly alt: _angular_core.InputSignal<string | null>;
@@ -85,8 +96,30 @@ declare class WrAvatar {
      * worth showing instead.
      */
     protected readonly failed: _angular_core.WritableSignal<boolean>;
+    private readonly img;
     constructor();
+    /**
+     * A prerendered `<img>` starts loading when the browser parses the HTML, and
+     * `(load)` / `(error)` are only attached at hydration — so on a slow bundle the
+     * image settles first, both events go nowhere, and the avatar sits on its
+     * fallback over a photo it already has (or names a broken image it never
+     * learns about). Only the FIRST render can race: every later `<img>` is
+     * created on the client with its listeners in place before `src` is set.
+     */
+    private adoptSettledImage;
     protected readonly resolved: _angular_core.Signal<ResolvedCssSize>;
+    /**
+     * Whether the projected fallback is `aria-hidden`: an `<img>` is in the DOM
+     * (loading or loaded) AND the consumer named it. Then the image's `alt` owns
+     * the name, announced once and unchanged at the moment the photo arrives.
+     * Without a real `alt` the image is only "Avatar", and hiding the initials
+     * would drop the one thing that says who this is.
+     *
+     * The stylesheet keys on the same attribute once `--loaded`: a hidden fallback
+     * leaves the paint through `visibility`, a named-by-initials one is clipped and
+     * stays in the accessibility tree. While loading it is painted either way.
+     */
+    protected readonly fallbackHidden: _angular_core.Signal<boolean>;
     protected readonly cssSize: _angular_core.Signal<string>;
     protected readonly pxSize: _angular_core.Signal<number | null>;
     protected readonly classes: _angular_core.Signal<string>;

package/types/ngwr-i18n-en.d.ts

@@ -1,16 +1,27 @@
 import { WrI18nCatalog } from 'ngwr/i18n';
 
 /**
- * Base English catalog for ngwr built-in component strings. Spread this
- * into your root catalog or pass it to `provideWrI18nStaticLoader`.
+ * Base English catalog for ngwr built-in component strings. Register it with
+ * `provideWrI18nBaseCatalogs` and keep only your own keys in the loader.
+ *
+ * Do not spread it into your own catalog. A spread is shallow, so any namespace
+ * you share with ngwr, e.g. `common`, `validation`, `table`, keeps only the keys
+ * of the side spread last, and the other side's keys stop resolving with nothing
+ * logged: ngwr's components fall back to their English defaults, and a `wrT`
+ * read of a lost key renders the raw key under the default missing handler. A
+ * base catalog is looked up key by key underneath yours, so both halves of a
+ * shared namespace resolve.
  *
  * @example
  * ```ts
+ * import { provideWrI18n, provideWrI18nBaseCatalogs, provideWrI18nStaticLoader } from 'ngwr/i18n';
  * import { wrEn } from 'ngwr/i18n/en';
  *
- * provideWrI18nStaticLoader({
- *   en: { ...wrEn, app: { title: 'My app' } },
- * });
+ * providers: [
+ *   provideWrI18n(),
+ *   provideWrI18nBaseCatalogs({ en: wrEn }),
+ *   provideWrI18nStaticLoader({ en: { app: { title: 'My app' } } }),
+ * ]
  * ```
  */
 declare const wrEn: WrI18nCatalog;

package/types/ngwr-i18n.d.ts

@@ -403,6 +403,15 @@ declare function provideWrI18n(options?: ProvideWrI18nOptions): EnvironmentProvi
 /**
  * Provide a static loader — catalogs already in memory.
  *
+ * A loader serves only the catalog you pass it, and ngwr registers none of its
+ * own. Pass only your own keys here and register ngwr's catalogs with
+ * {@link provideWrI18nBaseCatalogs} — not `{ ...wrRu, ...yours }`. A spread is
+ * shallow, so any namespace you share with ngwr, e.g. `common`, `validation`,
+ * `table`, keeps only the keys of the side spread last, and the other side's
+ * keys stop resolving with nothing logged: ngwr's components fall back to their
+ * English defaults, and a `wrT` read of a lost key renders the raw key under the
+ * default missing handler.
+ *
  * @param catalogs Root catalogs keyed by locale.
  * @param scopes Optional per-scope catalogs served to `registerScope(name)`.
  */
@@ -428,6 +437,10 @@ declare function provideWrI18nStaticLoader(catalogs: WrI18nStaticCatalogs, scope
  *
  * Pass only the locales you ship — the ones you leave out stay out of the
  * bundle. Your own keys always win; this is a floor, not an override.
+ *
+ * Use it instead of spreading `wrRu` into your own catalog, too: the lookup
+ * walks these key by key after the loader's catalog misses, so a namespace both
+ * define keeps both halves, where a shallow spread keeps only one.
  */
 declare function provideWrI18nBaseCatalogs(catalogs: WrI18nBaseCatalogs): Provider;
 /** Provide an HTTP loader — catalogs fetched from URLs. Requires `provideHttpClient`. */

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

@@ -72,9 +72,10 @@ interface WrCropWindowBox {
  * arrives on the `(cropped)` output, which emits a `Blob` after each drag end or
  * each run of arrow keys, and a consumer who wants a one-off read calls `toBlob()` /
  * `toDataUrl()` — or `cropRect()` for the geometry — on the component through a
- * `viewChild`. An output and three instance members: component API rather than DOM,
- * so all of it is outside what a harness can reach at all, which is worth knowing
- * rather than discovering.
+ * `viewChild`. The same goes for `(loadError)` and `status()`, which is why
+ * {@link isFailed} reads the failure off the host class instead. Outputs and instance
+ * members are component API rather than DOM, so all of it is outside what a harness
+ * can reach at all, which is worth knowing rather than discovering.
  *
  * @example
  * ```ts
@@ -127,6 +128,27 @@ declare class WrImageCropperHarness extends ComponentHarness {
      * a zero-sized image.
      */
     dispatchImageLoad(): Promise<void>;
+    /**
+     * Fire the image's `error` event — what a browser does with a source it cannot
+     * decode, and the only way to get one in a unit test, where nothing is decoded.
+     *
+     * Afterwards {@link isFailed} is `true` and the component has emitted
+     * `(loadError)`; a spec that wants the payload binds that output on its host.
+     */
+    dispatchImageError(): Promise<void>;
+    /**
+     * Whether the browser failed to decode the current source.
+     *
+     * Read off the `wr-image-cropper--failed` host modifier — the part of the failure
+     * the DOM shows. It is a third answer beside {@link isEmpty} and {@link isReady},
+     * not a combination of them: a failed cropper has a `src` (so it is not empty) and
+     * no crop window (so it is not ready), which is also exactly what a cropper still
+     * LOADING looks like. Asking those two would call a broken image a slow one.
+     *
+     * The component renders no message for it, so there is no text to read here; the
+     * host's own message is the host's to assert.
+     */
+    isFailed(): Promise<boolean>;
     /**
      * Where the crop window sits over the displayed image, in CSS pixels.
      *

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>;
@@ -98,6 +158,13 @@ declare class WrImageCropper {
     private startPointer;
     private startRect;
     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 +180,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.
      *
@@ -176,11 +255,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. */