ngwr 14.0.0 → 14.0.1

package/shiny-text/styles/_dark.scss

@@ -0,0 +1,20 @@
+// Dark theme.
+//
+// Keyed on `theme.dark-selector()`, never on a literal `[data-theme='dark']`.
+// The attribute is renameable — `@use 'ngwr' with ($theme-attribute: '…')`
+// alongside `provideWrTheme({ attribute: '…' })` — and a hand-written literal
+// misses the rename in both directions: this block stops firing under the
+// configured name, and it keeps firing under `data-theme`, which is the
+// attribute a foreign design system owns and the rename exists to escape.
+//
+// It lives outside the `styleUrl` closure for the same reason. A component
+// stylesheet is compiled when the LIBRARY is built, where `$theme-attribute` can
+// only ever be the default, and Angular appends that copy after the app's linked
+// sheet — so an inlined literal would not merely be dead, it would outrank the
+// correctly-named rule beside it.
+@use '../../theme/styles' as theme;
+
+#{theme.dark-selector()} .wr-shiny-text {
+  --wr-shiny-text-base: #b5b5b5;
+  --wr-shiny-text-shine: #ffffff;
+}

package/shiny-text/styles/_index.scss

@@ -11,5 +11,10 @@
 // box-sizing reset into the compiled component styles, which ng-packagr then
 // embeds in the FESM bundle as a string. `shiny-text.scss` forwards `_rules`
 // instead, so it carries this component's own CSS and nothing else.
+//
+// `_dark` is loaded from HERE for a second reason: its selector is built out of
+// `$theme-attribute`, which only a stylesheet compiled by the consuming app can
+// configure, so a copy inside the bundle could only ever carry the default name.
 @use '../../theme/styles';
 @forward 'rules';
+@forward 'dark';

package/shiny-text/styles/_rules.scss

@@ -95,7 +95,3 @@
   }
 }
 
-[data-theme='dark'] .wr-shiny-text {
-  --wr-shiny-text-base: #b5b5b5;
-  --wr-shiny-text-shine: #ffffff;
-}

package/spotlight-card/styles/_dark.scss

@@ -0,0 +1,21 @@
+// Dark theme: `--wr-color-on-surface-rgb` already flips to a light
+// value, so the default tint becomes a light beam on the navy surface — nudge
+// the alpha up a touch so it reads as bright as the classic spotlight.
+//
+// Keyed on `theme.dark-selector()`, never on a literal `[data-theme='dark']`.
+// The attribute is renameable — `@use 'ngwr' with ($theme-attribute: '…')`
+// alongside `provideWrTheme({ attribute: '…' })` — and a hand-written literal
+// misses the rename in both directions: this block stops firing under the
+// configured name, and it keeps firing under `data-theme`, which is the
+// attribute a foreign design system owns and the rename exists to escape.
+//
+// It lives outside the `styleUrl` closure for the same reason. A component
+// stylesheet is compiled when the LIBRARY is built, where `$theme-attribute` can
+// only ever be the default, and Angular appends that copy after the app's linked
+// sheet — so an inlined literal would not merely be dead, it would outrank the
+// correctly-named rule beside it.
+@use '../../theme/styles' as theme;
+
+#{theme.dark-selector()} .wr-spotlight-card {
+  --wr-spotlight-color: rgba(var(--wr-color-on-surface-rgb), 0.22);
+}

package/spotlight-card/styles/_index.scss

@@ -11,5 +11,10 @@
 // box-sizing reset into the compiled component styles, which ng-packagr then
 // embeds in the FESM bundle as a string. `spotlight-card.scss` forwards `_rules`
 // instead, so it carries this component's own CSS and nothing else.
+//
+// `_dark` is loaded from HERE for a second reason: its selector is built out of
+// `$theme-attribute`, which only a stylesheet compiled by the consuming app can
+// configure, so a copy inside the bundle could only ever carry the default name.
 @use '../../theme/styles';
 @forward 'rules';
+@forward 'dark';

package/spotlight-card/styles/_rules.scss

@@ -39,9 +39,3 @@
   }
 }
 
-// Dark mode: `--wr-color-on-surface-rgb` already flips to a light value, so the
-// default tint above becomes a light beam on the navy surface — nudge the
-// alpha up a touch so it reads as bright as the classic spotlight.
-[data-theme='dark'] .wr-spotlight-card {
-  --wr-spotlight-color: rgba(var(--wr-color-on-surface-rgb), 0.22);
-}

package/star-border/styles/_dark.scss

@@ -0,0 +1,21 @@
+// Dark theme.
+//
+// Keyed on `theme.dark-selector()`, never on a literal `[data-theme='dark']`.
+// The attribute is renameable — `@use 'ngwr' with ($theme-attribute: '…')`
+// alongside `provideWrTheme({ attribute: '…' })` — and a hand-written literal
+// misses the rename in both directions: this block stops firing under the
+// configured name, and it keeps firing under `data-theme`, which is the
+// attribute a foreign design system owns and the rename exists to escape.
+//
+// It lives outside the `styleUrl` closure for the same reason. A component
+// stylesheet is compiled when the LIBRARY is built, where `$theme-attribute` can
+// only ever be the default, and Angular appends that copy after the app's linked
+// sheet — so an inlined literal would not merely be dead, it would outrank the
+// correctly-named rule beside it.
+@use '../../theme/styles' as theme;
+
+#{theme.dark-selector()} .wr-star-border {
+  --wr-star-border-color: #ffffff;
+  --wr-star-border-stop: 10%;
+  --wr-star-border-opacity: 0.7;
+}

package/star-border/styles/_index.scss

@@ -11,5 +11,10 @@
 // box-sizing reset into the compiled component styles, which ng-packagr then
 // embeds in the FESM bundle as a string. `star-border.scss` forwards `_rules`
 // instead, so it carries this component's own CSS and nothing else.
+//
+// `_dark` is loaded from HERE for a second reason: its selector is built out of
+// `$theme-attribute`, which only a stylesheet compiled by the consuming app can
+// configure, so a copy inside the bundle could only ever carry the default name.
 @use '../../theme/styles';
 @forward 'rules';
+@forward 'dark';

package/star-border/styles/_rules.scss

@@ -82,11 +82,6 @@
   }
 }
 
-[data-theme='dark'] .wr-star-border {
-  --wr-star-border-color: #ffffff;
-  --wr-star-border-stop: 10%;
-  --wr-star-border-opacity: 0.7;
-}
 
 @keyframes wr-star-border-bottom {
   0% {

package/theme/styles/_colors.scss

@@ -8,6 +8,38 @@
 //   @use 'ngwr/theme/styles/colors' with (
 //     $base-colors: (primary: #...)
 //   );
+//
+// **This is the LIGHT palette, and configuring it does not reach the dark
+// theme.** `_dark.scss` re-tunes the intents by hand for the dark canvas and
+// hard-codes what it lands on, so an app that seeds an indigo `primary` here
+// gets indigo in light and the shipped `#3567ff` in dark, with nothing said
+// about it — which is exactly how it reads as a bug rather than a boundary.
+//
+// It is a boundary, and the deriving is what could not be shipped. The dark
+// intents are not the light ones lightened: `success` and `danger` are moved
+// 33% and 21% to clear the black/white flip point on a dark ground, `warning`
+// is deliberately left alone because white cannot reach it at any tone worth
+// shipping, and `primary` is deepened until its label can go white — a
+// direction no formula would take on its own. A `color.scale()` applied to an
+// arbitrary seed reproduces none of that; what it reproduces is the class of
+// failure the hand-tuning exists to prevent, silently, in the theme where
+// nobody looks first. Deriving the dark palette from the seed would trade a
+// visible wrong colour for an invisible failing contrast ratio, and that is
+// the worse of the two.
+//
+// So carry a rebrand across yourself, with the same arithmetic the light
+// palette uses. `rebrand()` below is that arithmetic:
+//
+//   @use 'ngwr/theme' as theme;
+//
+//   @include theme.dark {
+//     @include theme.rebrand((primary: #818cf8));
+//   }
+//
+// Pick the dark seed for the dark canvas rather than reusing the light one, and
+// measure it — `pnpm check:contrast` in this repo, axe or any contrast checker
+// in yours. `contrast()` is exported for the same reason: it tells you which
+// label a candidate fill will get before you ship it.
 
 // Five intents are deliberately deeper than their "brand" tone, and the reason is
 // arithmetic rather than taste. `_contrast()` picks whichever of black / white
@@ -319,6 +351,76 @@ $contrast-light: #ffffff !default;
   --wr-color-dark-ink: var(--wr-color-dark);
 }
 
+/// Re-emit an intent's WHOLE token set on the current selector, from one seed.
+///
+/// `$colors` is a map of intent name to base colour, keyed by the same nine
+/// names as `$base-colors`. Anything else is an `@error`: a typo would otherwise
+/// emit a family of `--wr-color-brnad-*` properties that resolve for nothing.
+///
+/// **This is the supported way to recolour a SUBTREE, and hand-writing the three
+/// obvious properties is not.** Setting `--wr-color-primary`, its `-rgb` and its
+/// `-contrast` on a `.marketing` wrapper looks like it should be enough, and the
+/// guide used to say so. It is not, for two separate reasons, and each hits a
+/// different half of the set:
+///
+/// - `-dark`, `-darker`, `-light` and `-lighter` are `color.adjust()` — Sass
+///   arithmetic, resolved when the stylesheet is COMPILED. No runtime value can
+///   feed them, so a pink subtree kept a blue `:hover`, which is `-dark`.
+/// - `-soft`, `-soft-border`, `-soft-contrast`, `-active` and `-ink` are written
+///   in terms of `var()`, which is the mechanism that lets them re-derive — but
+///   a custom property's references are substituted ON THE ELEMENT THAT DECLARES
+///   IT, and these are declared at `:root`. What inherits into the subtree is
+///   the substituted literal, so an outlined button inside a pink section drew a
+///   pink border around blue text: `-ink` had been frozen two levels up. It is
+///   the same trap `derived()` documents for a scoped dark block, arriving by a
+///   different door.
+///
+/// So the mixin does both halves: it recomputes the four shades and the contrast
+/// pick in Sass, then re-includes `derived()` so every composed token resolves
+/// against the bases on THIS element.
+///
+/// ```scss
+/// @use 'ngwr/theme' as theme;
+///
+/// .marketing {
+///   @include theme.rebrand((primary: #be123c));
+/// }
+/// ```
+///
+/// It is compile-time, so the seed has to be known when the app's stylesheet is
+/// built. For a colour chosen at runtime — a tenant, a builder, a preset picked
+/// from a registry — reach for `wrThemeTokens()` from `ngwr/theme` instead; it
+/// is the same recipe in TypeScript.
+///
+/// The dark theme needs the same treatment and does not get it for free: see the
+/// note on `$base-colors` for why compile-time configuration is light-only, and
+/// wrap this in `theme.dark` to carry a rebrand across.
+@mixin rebrand($colors) {
+  @each $name, $base in $colors {
+    @if not map.has-key($base-colors, $name) {
+      @error 'rebrand(): unknown intent `#{$name}`. Expected one of: #{map.keys($base-colors)}.';
+    }
+
+    --wr-color-#{$name}: #{$base};
+    --wr-color-#{$name}-rgb: #{_rgb-channels($base)};
+    --wr-color-#{$name}-contrast: #{_contrast($base)};
+    --wr-color-#{$name}-dark: #{color.adjust($base, $lightness: -5%)};
+    --wr-color-#{$name}-darker: #{color.adjust($base, $lightness: -10%)};
+    // unused-ok: `-light` and `-lighter`, for the reason their `:root` twins
+    // carry — hover and active DEEPEN an intent, so the catalog reads `-dark` /
+    // `-darker` and never these two, and a shade set with holes in it is worse
+    // than one half of which is for consumers. They are here rather than only
+    // there because a rebrand has to emit the SAME set the `:root` loop does: a
+    // subtree that redefines four shades out of six leaves a consumer's own
+    // `var(--wr-color-primary-lighter)` on the page palette, which is the
+    // half-recoloured subtree this mixin exists to end.
+    --wr-color-#{$name}-light: #{color.adjust($base, $lightness: 5%)};
+    --wr-color-#{$name}-lighter: #{color.adjust($base, $lightness: 10%)};
+  }
+
+  @include derived;
+}
+
 :root {
   // Declared here so the light token set also claims the light UA scheme.
   // Without it the browser fell back to the OS preference, and an app running

package/theme/styles/_focus.scss

@@ -18,6 +18,35 @@
   box-shadow: 0 0 0 var(--wr-focus-ring-offset) var(--wr-focus-ring-halo);
 }
 
+// Button — `wr-btn`, `button[wr-btn]` and `a[wr-btn]` all carry `.wr-btn` on the
+// element that takes focus, so one rule covers all three forms, and with them
+// every control BUILT out of a button: the pagination page cells and its prev /
+// next arrows are `<wr-btn>` elements with a `.wr-pagination__*` class beside
+// this one.
+//
+// It was missing until v14.1, and the button is the widest hole that could have
+// been left: `--wr-focus-ring-*` is documented as "retheme the ring once and
+// every control follows", and rethemed the ring on nine components while the
+// most-used control in the catalog kept the UA outline — which no token
+// reaches, does not honour `--wr-focus-ring-width`, and renders differently in
+// every browser. The rule sits here rather than in `button/styles` because this
+// file IS the ring's home; a second hand-rolled copy is what the mixin exists to
+// prevent.
+//
+// Safe as an OUTSET ring: `.wr-btn` sets no `overflow`, and the one place
+// buttons are packed edge to edge — `.wr-btn-group` — already raises the focused
+// segment with `z-index: 1`, so the ring paints over its neighbours instead of
+// under them.
+.wr-btn:focus-visible {
+  @include focus-ring;
+}
+
+// Table column-sort control — a bare `<button>` inside `.wr-table__th-inner`,
+// with no focus style of its own.
+.wr-table__sort-btn:focus-visible {
+  @include focus-ring;
+}
+
 // Tabs — `.wr-tabs__strip` is `overflow-y: hidden` (to suppress a stray
 // vertical scrollbar) and its box is exactly the tab's height, so an outset
 // ring loses both horizontal strokes and renders as two disconnected bars.
@@ -102,7 +131,8 @@
   @include focus-ring;
 }
 
-// Pagination ellipsis is non-interactive; page buttons inherit wr-btn focus.
+// Pagination ellipsis is non-interactive; page buttons take the `.wr-btn` rule
+// at the top of this file, since that is what they are.
 
 // Dropdown menu items
 .wr-dropdown-item:focus-visible {

package/tilt-card/styles/_dark.scss

@@ -0,0 +1,21 @@
+// Dark theme.
+//
+// Keyed on `theme.dark-selector()`, never on a literal `[data-theme='dark']`.
+// The attribute is renameable — `@use 'ngwr' with ($theme-attribute: '…')`
+// alongside `provideWrTheme({ attribute: '…' })` — and a hand-written literal
+// misses the rename in both directions: this block stops firing under the
+// configured name, and it keeps firing under `data-theme`, which is the
+// attribute a foreign design system owns and the rename exists to escape.
+//
+// It lives outside the `styleUrl` closure for the same reason. A component
+// stylesheet is compiled when the LIBRARY is built, where `$theme-attribute` can
+// only ever be the default, and Angular appends that copy after the app's linked
+// sheet — so an inlined literal would not merely be dead, it would outrank the
+// correctly-named rule beside it.
+@use '../../theme/styles' as theme;
+
+#{theme.dark-selector()} .wr-tilt-glare {
+  --wr-tilt-glare-color: rgb(255 255 255 / 25%);
+
+  mix-blend-mode: overlay;
+}

package/tilt-card/styles/_index.scss

@@ -11,5 +11,10 @@
 // box-sizing reset into the compiled component styles, which ng-packagr then
 // embeds in the FESM bundle as a string. `tilt-card.scss` forwards `_rules`
 // instead, so it carries this component's own CSS and nothing else.
+//
+// `_dark` is loaded from HERE for a second reason: its selector is built out of
+// `$theme-attribute`, which only a stylesheet compiled by the consuming app can
+// configure, so a copy inside the bundle could only ever carry the default name.
 @use '../../theme/styles';
 @forward 'rules';
+@forward 'dark';

package/tilt-card/styles/_rules.scss

@@ -33,8 +33,3 @@
   mix-blend-mode: multiply;
 }
 
-[data-theme='dark'] .wr-tilt-glare {
-  --wr-tilt-glare-color: rgb(255 255 255 / 25%);
-
-  mix-blend-mode: overlay;
-}

package/types/ngwr-button.d.ts

@@ -65,6 +65,16 @@ type WrButtonIconPosition = 'start' | 'end';
  * every child — child `[shape]` inputs are ignored so the group reads as
  * one coherent control.
  *
+ * **Inside a `<form>`, use the native form.** `<wr-btn>` is a custom element
+ * carrying `role="button"`, and no custom element submits a form — the platform
+ * submits for `<button>`, `<input type="submit">` and `<input type="image">`
+ * and nothing else. That is why there is no `type` input: it would look like it
+ * worked. Implicit submission (Enter in a text field) does not reach it either.
+ *
+ * ```html
+ * <button wr-btn type="submit" color="primary">Save</button>
+ * ```
+ *
  * @see https://ngwr.dev/reference/components/button
  */
 declare class WrButton {
@@ -162,6 +172,39 @@ declare class WrButton {
      * `pointer-events: none`.
      */
     protected onHostKeydown(event: KeyboardEvent): void;
+    private readonly injector;
+    /**
+     * Whether this button is the one the caret was on, so it can be handed back
+     * the focus that goes missing while it is off.
+     *
+     * A control that becomes `disabled` while focused stops being a focusable
+     * area, and the browser runs the unfocusing steps: nothing else is nominated,
+     * so the caret lands on `<body>`. With `disabledWhenLoading` on by default
+     * that happens on EVERY async button — a keyboard user presses Enter on
+     * "Save" and the next Tab restarts from the top of the document, while a
+     * screen-reader user is told neither that the wait began nor that it ended,
+     * because the element they were on has left the a11y tree. The `<wr-btn>`
+     * element form loses its `tabindex` instead of gaining `disabled` and is
+     * unfocused for the same reason.
+     *
+     * Deliberately NOT keyed on reading `activeElement` when `isOff()` flips: an
+     * effect in this component's own view runs AFTER the parent has applied this
+     * directive's host bindings, so by then the attribute has landed and the
+     * browser has already moved the caret — the read would answer `<body>` on
+     * every real browser and the button on jsdom, which is the worst of both.
+     *
+     * The flag is written by the focus listeners instead, and a `blur` fired
+     * WHILE off keeps it set rather than clearing it: that blur is the browser
+     * taking the caret away, not the user leaving. A browser that fires no blur
+     * on disable at all is covered too — the flag simply stays as `focus` left it,
+     * and the `<body>` test below is what decides whether the focus is orphaned.
+     */
+    private hadFocus;
+    /** @internal Host `focus` — see `hadFocus`. */
+    protected onHostFocus(): void;
+    /** @internal Host `blur` — see `hadFocus`. */
+    protected onHostBlur(): void;
+    constructor();
     protected readonly classes: _angular_core.Signal<string>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrButton, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrButton, "wr-btn, button[wr-btn], a[wr-btn]", never, { "color": { "alias": "color"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "shape": { "alias": "shape"; "required": false; "isSignal": true; }; "icon": { "alias": "icon"; "required": false; "isSignal": true; }; "iconPosition": { "alias": "iconPosition"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "outlined": { "alias": "outlined"; "required": false; "isSignal": true; }; "block": { "alias": "block"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "disabledWhenLoading": { "alias": "disabledWhenLoading"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;

package/types/ngwr-dropdown.d.ts

@@ -80,14 +80,30 @@ declare class WrDropdown {
     private readonly destroyRef;
     /** @internal Public so host bindings can read it. */
     readonly isOpen: _angular_core.WritableSignal<boolean>;
+    /** The id used only when the consumer's element carries none of its own. */
+    private readonly fallbackId;
     /**
      * Id the menu names itself after. The trigger is the CONSUMER's own element, so
      * an `id` they already put there wins: overwriting it broke `<label for>`,
      * `document.getElementById` and any `aria-labelledby` aimed at that button from
      * elsewhere in their app. The generated one is only a fallback so the menu has
      * something to reference.
+     *
+     * A GETTER, read fresh by the host binding on every pass, rather than a field
+     * resolved in the constructor. A static `id="…"` is on the element before a
+     * directive is instantiated and so was already honoured; a BOUND `[id]` is
+     * not — it lands with the rest of the template's bindings, which run before
+     * host bindings but after construction, so the constructor read an empty
+     * string, fell through to the fallback, and the host binding then wrote that
+     * fallback over the value the template had just set. Everything bound was
+     * lost — `[id]`, `[attr.id]` and an interpolated `id="dd-{{ n }}"` alike —
+     * while the static form survived, which is the shape that makes it look like
+     * a naming convention rather than a defect.
+     *
+     * `.id` rather than `getAttribute`: it is always a string, and an empty one is
+     * no id at all, so it falls through to the fallback.
      */
-    protected readonly triggerId: string;
+    protected get triggerId(): string;
     private overlayRef;
     constructor();
     /** Open the menu. */

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

@@ -169,8 +169,9 @@ declare class WrFormFieldHarness extends ContentContainerComponentHarness {
      *
      * `null` does not mean the consumer set no hint: the error block takes the
      * hint's slot outright, so a field with a visible message has no hint in the DOM
-     * at all. Note also that the hint carries no id and is NOT referenced by the
-     * control's `aria-describedby` — see {@link getAnnouncedDescription}.
+     * at all — which is also why the hint's id stops being published at the same
+     * moment. Whether the CONTROL announces it is a separate question, and one this
+     * harness answers through {@link getAnnouncedDescription}.
      */
     getHint(): Promise<string | null>;
     /**
@@ -243,11 +244,16 @@ declare class WrFormFieldHarness extends ContentContainerComponentHarness {
     /**
      * The ids the projected control names in `aria-describedby`, in order.
      *
-     * The field points this at the error block and nothing else — the hint has no
-     * id — so an empty list while a hint is showing is correct rather than a bug.
-     * That is not an oversight to fix from a harness either: `[wrInput]` derives
-     * `aria-invalid` from the same signal, so describing the hint would announce
-     * every hinted field as invalid.
+     * Which id that is depends on the CONTROL, not on the field, and the answer is
+     * worth knowing before reading a result. A control that composes the pair with
+     * `useFormFieldAria()` names the error block while one is showing and the hint
+     * otherwise. A control that reads the field's `describedBy` on its own — the
+     * `[wrInput]` directive, `wr-segmented` and `wr-slider` — names the error block
+     * and nothing else, so an empty list beside a visible hint is that control's
+     * answer rather than a broken field.
+     *
+     * The two are separate because folding the hint into the one signal announced
+     * every hinted field as invalid: those three derive `aria-invalid` from it.
      */
     getDescribedByIds(): Promise<string[]>;
     /**

package/types/ngwr-form.d.ts

@@ -66,6 +66,20 @@ interface WrFormFieldContext {
     readonly errorKeys: Signal<readonly string[]>;
     /** Id of the element listing the visible messages, or `null` when there are none. */
     readonly describedBy: Signal<string | null>;
+    /**
+     * Id of the field's hint, or `null` when it is showing none — including while
+     * an error has replaced it, since the two never render together and an
+     * `aria-describedby` naming an absent element is an author error.
+     *
+     * Separate from {@link describedBy} rather than folded into it because the two
+     * carry different weight: a control keyed `aria-invalid` on "the field is
+     * describing me" would announce itself invalid for a plain hint. Compose the
+     * pair with `useFormFieldAria()` instead of reading either one directly.
+     *
+     * Optional so an app that provides its own `WR_FORM_FIELD` keeps compiling; a
+     * field without it simply describes nothing but its errors.
+     */
+    readonly hintId?: Signal<string | null>;
 }
 /** Present only inside a `<wr-form-field>`; inject with `{ optional: true }`. */
 declare const WR_FORM_FIELD: InjectionToken<WrFormFieldContext>;
@@ -187,6 +201,20 @@ declare class WrFormField implements WrFormFieldContext {
     readonly errorKeys: _angular_core.Signal<readonly string[]>;
     /** @internal Read by the projected control so a screen reader is pointed at the message. */
     readonly describedBy: _angular_core.Signal<string | null>;
+    /**
+     * @internal Read by the projected control so the hint is announced with the field.
+     *
+     * The hint used to carry no id at all, so the only thing `aria-describedby`
+     * could ever name was the error block: the sentence explaining what to type was
+     * on screen and reached a screen-reader user through no path whatsoever, and
+     * the one gate that could have said so does not exist — axe has no rule that
+     * visible help text must be programmatically associated.
+     *
+     * `null` while an error is showing, because the template swaps the hint out for
+     * the message; publishing the id anyway would point every control at an element
+     * that had just left the document.
+     */
+    readonly hintId: _angular_core.Signal<string | null>;
     /**
      * Render a catalog message for any error the markup does not already answer.
      *
@@ -223,24 +251,31 @@ declare class WrFormField implements WrFormFieldContext {
 
 /** What {@link useFormFieldAria} hands a control to bind on its own element. */
 interface WrFormFieldAria {
-    /** Id of the field's message block, or `null` when it is showing none. */
+    /**
+     * Id of the field's message block while it is showing one, of its hint
+     * otherwise, and `null` when it is showing neither.
+     */
     readonly describedBy: Signal<string | null>;
-    /** `'true'` while the field is showing a message, `null` otherwise. */
+    /** `'true'` while the field has a validation error, `null` otherwise. */
     readonly ariaInvalid: Signal<'true' | null>;
 }
 /**
- * The two attributes that make a `<wr-form-field>`'s visible error reach a
- * screen reader — bind both on whichever element carries the control's role.
+ * The two attributes that make a `<wr-form-field>`'s visible text — its error
+ * message, or its hint — reach a screen reader. Bind both on whichever element
+ * carries the control's role.
  *
- * Without them the messages the field renders are visible and nothing else: the
- * control announces itself as valid, and the message is associated with nothing.
- * No automated gate catches that — axe has no rule that a visible error must be
- * programmatically associated with its control — so this helper exists to make
- * the wiring one line per control rather than three, and the specs are the gate.
+ * Without them the copy the field renders is visible and nothing else: the
+ * control announces itself as valid, and the text is associated with nothing.
+ * No automated gate catches that — axe has no rule that a visible error or hint
+ * must be programmatically associated with its control — so this helper exists
+ * to make the wiring one line per control rather than three, and the specs are
+ * the gate.
  *
- * `aria-invalid` is keyed on the message EXISTING rather than on `errorKeys()`,
- * because the field only publishes an id once it is showing something —
- * announcing "invalid" while pointing at nothing is worse than staying quiet.
+ * The field renders an error OR a hint, never both, so `describedBy` names
+ * whichever is on screen and `aria-invalid` is keyed SEPARATELY, on the field's
+ * `errorKeys()`. Deriving it from `describedBy` instead — which is what every
+ * control did while a hint had no id to name — makes a field with a plain hint
+ * announce its control as invalid the moment the hint becomes describable.
  *
  * Must be called from an injection context (a field initialiser or a
  * constructor). Returns inert signals outside a `<wr-form-field>`.

package/types/ngwr-input.d.ts

@@ -66,8 +66,9 @@ declare class WrInput {
      * invisible to a screen reader, which never learns the field is invalid or
      * what the message says.
      */
-    protected readonly ariaInvalid: _angular_core.Signal<"true" | null>;
+    private readonly fieldAria;
     protected readonly describedBy: _angular_core.Signal<string | null>;
+    protected readonly ariaInvalid: _angular_core.Signal<"true" | null>;
     /**
      * Control size. Unset, it falls back to
      * `provideWrConfig({ input: { size } })`. @default 'md'

package/types/ngwr-rating.d.ts

@@ -4,8 +4,13 @@ import { FormValueControl } from '@angular/forms/signals';
 
 /**
  * Star rating input. Click or hover to set a value; supports half-star
- * increments via `step="0.5"`. Value is `number | null` (clamped to
- * `[0, count]`).
+ * increments via `step="0.5"`. Value is `number | null`.
+ *
+ * `[0, count]` bounds what this control's OWN edits produce — a click, an arrow
+ * key, `End`. A value written from outside is displayed and announced clamped
+ * (a slider cannot report an `aria-valuenow` past its own `aria-valuemax`) and
+ * left in the model as it stands, the same rule `wr-slider` and
+ * `wr-input-number` follow.
  *
  * A signal-forms native control: it implements `FormValueControl<number | null>`,
  * so `[formField]` binds straight to its `value` model — no
@@ -68,8 +73,25 @@ declare class WrRating implements FormValueControl<number | null> {
      * an error message on an element nobody could focus.
      */
     protected readonly focusable: _angular_core.Signal<boolean>;
-    /** What we actually render — hover wins while hovering. */
+    /**
+     * What we actually render — hover wins while hovering.
+     *
+     * Clamped, because there is no such thing as drawing six stars in a row of
+     * five, and the same number is what `aria-valuenow` reports: a `role="slider"`
+     * whose value sits outside its own min / max is an invalid slider whatever the
+     * model holds. The MODEL is left alone — see the note above `fillFor` for why
+     * the clamp is not written back.
+     */
     protected readonly displayValue: _angular_core.Signal<number>;
+    /**
+     * What the slider REPORTS, and where the arrows start from.
+     *
+     * Deliberately not `displayValue`: a hover preview is a pointer affordance and
+     * must not be announced as the current value, and an arrow press after a hover
+     * has to step from the committed number rather than from wherever the mouse
+     * happened to rest.
+     */
+    protected readonly announcedValue: _angular_core.Signal<number>;
     protected readonly slots: _angular_core.Signal<number[]>;
     /**
      * Reading direction, for the two places it changes the answer: the arrows and
@@ -84,7 +106,6 @@ declare class WrRating implements FormValueControl<number | null> {
     /** The surrounding `<wr-form-field>`'s error state. @internal */
     protected readonly fieldAria: ngwr_form.WrFormFieldAria;
     protected readonly classes: _angular_core.Signal<string>;
-    constructor();
     /** Fill ratio for slot `i` in `[0, 1]` — drives the CSS clip width. */
     protected fillFor(i: number): number;
     protected onSlotMove(event: MouseEvent, index: number): void;

package/types/ngwr-segmented.d.ts

@@ -141,6 +141,7 @@ declare class WrSegmented<T = unknown> implements FormValueControl<T | null> {
      * because the field only publishes an id once it is showing something — announcing
      * "invalid" while pointing at nothing is worse than staying quiet.
      */
+    private readonly fieldAria;
     protected readonly describedBy: _angular_core.Signal<string | null>;
     protected readonly ariaInvalid: _angular_core.Signal<"true" | null>;
     /** Index of the selected option, or `-1` when nothing is selected. */