ngwr 12.1.0 → 13.0.0

package/theme/styles/_motion.scss

@@ -0,0 +1,94 @@
+// `prefers-reduced-motion` for the always-on chrome.
+//
+// Why this lives in the theme layer rather than in each component. The
+// animation catalogue (`ngwr/glitch-text`, `ngwr/gradient-text`, …) guards
+// itself, component by component — those are opt-in effects, and each one knows
+// what its own stillness should look like. The ten blocks below are the
+// opposite: chrome nobody opted into. A spinner and a skeleton animate on
+// essentially every page of every app, and four of the animations here never
+// stop at all (`wr-spinner-rotate`, `wr-spinner-dash`, `wr-skeleton-shimmer`,
+// `wr-card-spin`, `wr-lightbox-shimmer`), which is the case vestibular guidance
+// is most emphatic about. Collecting them in one place is what makes the set
+// reviewable — the gap this closes existed because nine separate stylesheets
+// each forgot, and nine separate stylesheets can each forget again.
+//
+// **Every declaration here is `!important`, and that is structural rather than
+// lazy.** The theme layer is loaded first — `styles.scss` forwards it before any
+// component, and a standalone `@use 'ngwr/spinner'` pulls it in ahead of the
+// spinner's own rules — so at equal specificity the component always wins on
+// source order. `!important` is the only lever a stylesheet that must come first
+// has. `.wr-overlay-sheet` needs one more: its animation is itself `!important`
+// (it has to beat four components' panel sizing), so the class is doubled here
+// to out-specify it.
+//
+// What reduced motion MEANS is decided per animation, not globally:
+//
+//   - An ENTER animation is removed. The panel still arrives, it just does not
+//     travel to get there. Every keyframe set below animates from a transparent,
+//     offset or scaled-down state TO the element's resting one, with no
+//     `forwards`, so removing it lands on exactly the frame the animation was
+//     heading for. Nothing in the library waits on `animationend`, so nothing
+//     is left un-dismissed.
+//   - A decorative INFINITE loop is removed outright — a skeleton's shimmer and
+//     a lightbox's shimmer say nothing the static placeholder does not.
+//   - A SPINNER is slowed, not stopped. Its rotation IS the message: a frozen
+//     spinner does not read as "reduced motion", it reads as "hung". So the
+//     rotation stays at half speed and the pulsing arc — the part that carries
+//     no information — is frozen at a fixed sweep. Same call Bootstrap makes,
+//     and the same reading as WCAG 2.3.3, which is about non-essential motion.
+//   - The TOAST progress bar is deliberately left alone. It is a countdown: it
+//     is the only thing on screen saying how long is left before the toast
+//     leaves, and freezing it would not remove information, it would state a
+//     falsehood — a full bar that never drains. It is also 2px tall and moves
+//     along one axis at constant speed, the mildest shape motion sensitivity
+//     takes. If that trade is ever revisited, revisit it here.
+
+@media (prefers-reduced-motion: reduce) {
+  // Overlay enter choreography — dialog, dropdown, popconfirm, toast, lightbox
+  // viewer, and all four drawer edges.
+  .wr-dialog-panel,
+  .wr-dropdown-menu,
+  .wr-popconfirm-overlay > .wr-popconfirm,
+  .wr-toast,
+  .wr-lightbox-viewer,
+  .wr-drawer__panel--left,
+  .wr-drawer__panel--right,
+  .wr-drawer__panel--top,
+  .wr-drawer__panel--bottom {
+    animation: none !important;
+  }
+
+  // The responsive bottom sheet, which slides a full panel height up the
+  // screen — the largest single translation the library performs. Doubled
+  // class: `overlay/styles/_index.scss` sets this animation `!important`, and it
+  // is loaded after this file.
+  .wr-overlay-sheet.wr-overlay-sheet {
+    animation: none !important;
+  }
+
+  // Decorative loading shimmers. Both ride a pseudo-element whose resting
+  // position is off-screen or at its gradient origin, so stopping them leaves a
+  // plain tinted placeholder rather than a half-drawn band.
+  .wr-skeleton--animated::after,
+  .wr-lightbox--loading::after {
+    animation: none !important;
+  }
+
+  // Spinners. The rotation survives at half speed; the arc stops pulsing and
+  // holds the sweep the dash animation spends most of its cycle at, so the
+  // shape stays a recognisable spinner instead of collapsing to the 1-unit dot
+  // its first keyframe starts from.
+  .wr-spinner svg {
+    animation-duration: 4s !important;
+  }
+
+  .wr-spinner__path {
+    animation: none !important;
+    stroke-dasharray: 90, 150 !important;
+    stroke-dashoffset: 0 !important;
+  }
+
+  .wr-card__spinner {
+    animation-duration: 1.4s !important;
+  }
+}

package/tilt-card/styles/_index.scss

@@ -1,45 +1,15 @@
-// Pull the whole theme so a standalone `@use 'ngwr/<name>'` brings in every
-// design token this stylesheet references. Sass deduplicates `@use` per
-// compilation, so the umbrella sheet still emits the theme only once.
-@use '../../theme/styles' as theme;
-
-// 3D mouse-tilt card. The transform is set imperatively by `[wrTilt]`,
-// so this stylesheet just covers the card chrome + the optional glare
-// overlay that the directive appends when `[glare]="true"`.
-
-.wr-tilt-card {
-  display: block;
-  position: relative;
-  padding: 1.5rem;
-  border-radius: 0.75rem;
-  border: 1px solid var(--wr-color-outline);
-  background: var(--wr-color-surface);
-  color: var(--wr-color-on-surface);
-  box-shadow: 0 1px 2px rgba(var(--wr-color-backdrop-rgb), 0.06);
-  // Card itself doesn't need overflow:hidden by default — the directive
-  // toggles overflow when glare is enabled. Authors can opt in.
-  transform-style: preserve-3d;
-  transition: transform 0.15s ease-out;
-}
-
-// Glare overlay (appended by `[wrTilt]` when `[glare]="true"`)
-// Lives in this package so the visual lives with the card chrome.
-.wr-tilt-glare {
-  position: absolute;
-  inset: 0;
-  pointer-events: none;
-  // Light surfaces: glare reads as a soft moving shade. Dark theme flips
-  // to the classic white sheen below.
-  background: radial-gradient(
-    circle at var(--wr-tilt-glare-x, 50%) var(--wr-tilt-glare-y, 50%),
-    var(--wr-tilt-glare-color, rgba(var(--wr-color-on-surface-rgb), 0.12)),
-    transparent 60%
-  );
-  mix-blend-mode: multiply;
-}
-
-[data-theme='dark'] .wr-tilt-glare {
-  --wr-tilt-glare-color: rgb(255 255 255 / 25%);
-
-  mix-blend-mode: overlay;
-}
+// Public Sass entry for `@use 'ngwr/tilt-card'`.
+//
+// Pulls the whole theme so a standalone import still brings in every design
+// token these rules reference, then loads the rules themselves from `_rules`.
+//
+// The split is what keeps the token layer out of the JavaScript bundle.
+// `tilt-card.scss` is the component's `styleUrl`, and a component stylesheet is
+// its OWN Sass compilation — `@use` only deduplicates within one. So while the
+// umbrella sheet emits the theme once, forwarding it from here would inline a
+// second, byte-identical copy of `:root`, `[data-theme='dark']` and the
+// 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.
+@use '../../theme/styles';
+@forward 'rules';

package/tilt-card/styles/_rules.scss

@@ -0,0 +1,40 @@
+// 3D mouse-tilt card. The transform is set imperatively by `[wrTilt]`,
+// so this stylesheet just covers the card chrome + the optional glare
+// overlay that the directive appends when `[glare]="true"`.
+
+.wr-tilt-card {
+  display: block;
+  position: relative;
+  padding: 1.5rem;
+  border-radius: 0.75rem;
+  border: 1px solid var(--wr-color-outline);
+  background: var(--wr-color-surface);
+  color: var(--wr-color-on-surface);
+  box-shadow: 0 1px 2px rgba(var(--wr-color-backdrop-rgb), 0.06);
+  // Card itself doesn't need overflow:hidden by default — the directive
+  // toggles overflow when glare is enabled. Authors can opt in.
+  transform-style: preserve-3d;
+  transition: transform 0.15s ease-out;
+}
+
+// Glare overlay (appended by `[wrTilt]` when `[glare]="true"`)
+// Lives in this package so the visual lives with the card chrome.
+.wr-tilt-glare {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  // Light surfaces: glare reads as a soft moving shade. Dark theme flips
+  // to the classic white sheen below.
+  background: radial-gradient(
+    circle at var(--wr-tilt-glare-x, 50%) var(--wr-tilt-glare-y, 50%),
+    var(--wr-tilt-glare-color, rgba(var(--wr-color-on-surface-rgb), 0.12)),
+    transparent 60%
+  );
+  mix-blend-mode: multiply;
+}
+
+[data-theme='dark'] .wr-tilt-glare {
+  --wr-tilt-glare-color: rgb(255 255 255 / 25%);
+
+  mix-blend-mode: overlay;
+}

package/tilt-card/tilt-card.scss

@@ -1 +1 @@
-@forward './styles';
+@forward './styles/rules';

package/tree/styles/_index.scss

@@ -122,6 +122,15 @@
     white-space: nowrap;
   }
 
+  // A read-only tree still expands, still takes focus and still submits its
+  // value, so it keeps the visual and only stops inviting the click that would
+  // change the selection. The trigger is covered by the same rule in combobox
+  // mode, where the whole panel is refused.
+  &--readonly &__row,
+  &--readonly &__trigger {
+    cursor: default;
+  }
+
   &--disabled {
     opacity: var(--wr-disabled-opacity);
     pointer-events: none;
@@ -145,6 +154,11 @@
     --wr-tree-trigger-font-size: var(--wr-control-font-size-md);
     --wr-tree-trigger-line-height: var(--wr-control-line-height-md);
     --wr-tree-panel-max-height: 18rem;
+    // Trigger width floor — hooked for the same reason as `--wr-select-min-width`:
+    // in a narrow grid column the literal wins over `minmax(0, 1fr)` and the
+    // trigger overhangs its cell, and the only escape was overriding
+    // `.wr-tree__trigger` from outside. Set it to 0 to defer to the layout.
+    --wr-tree-trigger-min-width: 12rem;
 
     display: inline-flex;
     vertical-align: middle;
@@ -160,7 +174,7 @@
     align-items: center;
     gap: 0.5rem;
     width: 100%;
-    min-width: 12rem;
+    min-width: var(--wr-tree-trigger-min-width);
     appearance: none;
     background: var(--wr-tree-trigger-bg);
     color: var(--wr-tree-trigger-color);
@@ -270,7 +284,10 @@
     // Roomier on the label side, tighter where the remove (×) sits.
     padding-block: 0.125rem;
     padding-inline: 0.5rem 0.25rem;
-    border-radius: 999px;
+    // Not a pill: a chip is a shape nested INSIDE the trigger, so it repeats the
+    // trigger's own corner instead of deciding one for itself — and an override
+    // of `--wr-tree-trigger-radius` carries the chips with it.
+    border-radius: var(--wr-tree-trigger-radius);
     background: var(--wr-color-primary-soft);
     // The chip wraps a label, so this paints text on the chip's own tint.
     color: var(--wr-color-primary-ink);
@@ -292,7 +309,12 @@
     justify-content: center;
     width: 1rem;
     height: 1rem;
-    border-radius: 999px;
+    // Concentric with the chip: inset from the chip's edge by its 2px block
+    // padding, and an inner corner only nests cleanly when it is the outer
+    // corner minus that inset. `max()` keeps the value legal for a consumer who
+    // sets `--wr-tree-trigger-radius: 0` — a negative radius invalidates the
+    // whole declaration.
+    border-radius: max(0px, calc(var(--wr-tree-trigger-radius) - 2px));
     cursor: pointer;
     transition: background 0.12s ease;
 

package/types/ngwr-cascader.d.ts

@@ -1,3 +1,4 @@
+import * as ngwr_form from 'ngwr/form';
 import * as _angular_core from '@angular/core';
 import { TemplateRef } from '@angular/core';
 import { FormValueControl } from '@angular/forms/signals';
@@ -73,6 +74,21 @@ declare class WrCascader<T = string> implements FormValueControl<unknown> {
      * @default false
      */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, any>;
+    /**
+     * Refuse changes while the trigger stays focusable and the path still submits.
+     * Bound automatically from the field's readonly state when used with
+     * `[formField]`.
+     *
+     * The panel is where every edit happens, so a read-only cascader simply does
+     * not open — there is nothing to browse that is not already on the trigger —
+     * and the clear button goes away with it. Mirrored as `aria-readonly`, which
+     * role `combobox` supports.
+     *
+     * @default false
+     */
+    readonly readonly: _angular_core.InputSignalWithTransform<boolean, any>;
+    /** The surrounding `<wr-form-field>`'s error state. @internal */
+    protected readonly fieldAria: ngwr_form.WrFormFieldAria;
     /** Control size — shares the `--wr-control-*` contract. @default 'md' */
     readonly size: _angular_core.InputSignal<WrCascaderSize>;
     /** Show a clear-all (×) button on the trigger when a path is selected. @default true */
@@ -143,7 +159,7 @@ declare class WrCascader<T = string> implements FormValueControl<unknown> {
     private focusPanelOption;
     private closeOverlay;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrCascader<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrCascader<any>, "wr-cascader", never, { "clearLabel": { "alias": "clearLabel"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "required": true; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "clearable": { "alias": "clearable"; "required": false; "isSignal": true; }; "changeOnSelect": { "alias": "changeOnSelect"; "required": false; "isSignal": true; }; "separator": { "alias": "separator"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "touch": "touch"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrCascader<any>, "wr-cascader", never, { "clearLabel": { "alias": "clearLabel"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "required": true; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "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; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "clearable": { "alias": "clearable"; "required": false; "isSignal": true; }; "changeOnSelect": { "alias": "changeOnSelect"; "required": false; "isSignal": true; }; "separator": { "alias": "separator"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "touch": "touch"; }, never, never, true, never>;
 }
 
 export { WrCascader };

package/types/ngwr-checkbox.d.ts

@@ -1,6 +1,7 @@
 import * as _angular_core from '@angular/core';
 import { InjectionToken, Signal } from '@angular/core';
 import { FormCheckboxControl, FormValueControl } from '@angular/forms/signals';
+import * as ngwr_form from 'ngwr/form';
 
 /**
  * Two-state checkbox.
@@ -35,7 +36,8 @@ import { FormCheckboxControl, FormValueControl } from '@angular/forms/signals';
 type WrCheckboxSize = 'sm' | 'md' | 'lg';
 declare class WrCheckbox implements FormCheckboxControl {
     /**
-     * Stable id used to associate the native input with its label.
+     * Stable id used to associate the native input with its label. Lands on the
+     * inner `<input>`; the host never keeps it.
      *
      * @default Randomly generated
      */
@@ -70,6 +72,18 @@ declare class WrCheckbox implements FormCheckboxControl {
      * @default false
      */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, any>;
+    /**
+     * Refuse edits while staying focusable and submittable. Bound automatically
+     * from the field's readonly state when used with `[formField]`.
+     *
+     * A native `<input type="checkbox">` ignores the `readonly` attribute, so this
+     * cancels the click's activation behaviour instead — which covers Space too,
+     * since a checkbox turns Space into a click — and mirrors the state as
+     * `aria-readonly`, which role `checkbox` supports.
+     *
+     * @default false
+     */
+    readonly readonly: _angular_core.InputSignalWithTransform<boolean, any>;
     /**
      * Control size — shares the `--wr-control-*` contract. Unset falls back to the
      * `checkbox.size` app default from `provideWrConfig()`. @default 'md'
@@ -96,11 +110,28 @@ declare class WrCheckbox implements FormCheckboxControl {
     protected readonly isChecked: _angular_core.Signal<boolean>;
     /** Effective disabled — the `disabled` input wins, then the group. */
     protected readonly effectiveDisabled: _angular_core.Signal<boolean>;
+    /** Effective readonly — this box's own `readonly` input, or the group's. */
+    protected readonly effectiveReadonly: _angular_core.Signal<boolean>;
+    /**
+     * The surrounding `<wr-form-field>`'s error state, mirrored onto the native
+     * input. Inside a `<wr-checkbox-group>` the GROUP is the bound control and
+     * carries the state, so a grouped box shields itself and stays silent — nine
+     * boxes each announcing the group's one error is noise, not information.
+     */
+    private readonly fieldAria;
+    protected readonly ariaInvalid: _angular_core.Signal<"true" | null>;
+    protected readonly describedBy: _angular_core.Signal<string | null>;
     protected readonly classes: _angular_core.Signal<string>;
+    /**
+     * Cancel the toggle while readonly. `change` never fires for a click whose
+     * default was prevented, so this is the only guard the pointer and Space
+     * paths need; `onInputChange` keeps its own for a synthetic `change`.
+     */
+    protected onInputClick(event: Event): void;
     protected onInputChange(event: Event): void;
     protected onInputBlur(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrCheckbox, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrCheckbox, "wr-checkbox", never, { "id": { "alias": "id"; "required": false; "isSignal": true; }; "checkboxValue": { "alias": "checkboxValue"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "checked": { "alias": "checked"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "icon": { "alias": "icon"; "required": false; "isSignal": true; }; "indeterminate": { "alias": "indeterminate"; "required": false; "isSignal": true; }; }, { "checked": "checkedChange"; "touch": "touch"; }, never, ["*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrCheckbox, "wr-checkbox", never, { "id": { "alias": "id"; "required": false; "isSignal": true; }; "checkboxValue": { "alias": "checkboxValue"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "checked": { "alias": "checked"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "icon": { "alias": "icon"; "required": false; "isSignal": true; }; "indeterminate": { "alias": "indeterminate"; "required": false; "isSignal": true; }; }, { "checked": "checkedChange"; "touch": "touch"; }, never, ["*"], true, never>;
 }
 
 /**
@@ -133,6 +164,8 @@ interface WrCheckboxGroupContext {
     blurred(): void;
     /** Whether the entire group is disabled. */
     readonly isDisabled: Signal<boolean>;
+    /** Whether the entire group refuses edits while staying focusable. */
+    readonly isReadonly: Signal<boolean>;
 }
 /**
  * Token a `<wr-checkbox>` injects to read selection state from — and
@@ -169,6 +202,19 @@ declare class WrCheckboxGroup implements FormValueControl<unknown[]>, WrCheckbox
      * @default false
      */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, any>;
+    /**
+     * Refuse edits on every child while they stay focusable and the value still
+     * submits. Bound automatically from the field's readonly state when used with
+     * `[formField]`.
+     *
+     * No `aria-readonly` on the host: role `group` does not support it (the state
+     * is not global), so each child box mirrors its own instead.
+     *
+     * @default false
+     */
+    readonly readonly: _angular_core.InputSignalWithTransform<boolean, any>;
+    /** The surrounding `<wr-form-field>`'s error state. @internal */
+    protected readonly fieldAria: ngwr_form.WrFormFieldAria;
     /** The checked items' values. Bound by `[formField]`, or two-way via `[(value)]`. */
     readonly value: _angular_core.ModelSignal<unknown[]>;
     /** Emitted when a child toggles so a bound field can mark itself touched. */
@@ -176,12 +222,14 @@ declare class WrCheckboxGroup implements FormValueControl<unknown[]>, WrCheckbox
     private readonly selected;
     /** Effective disabled state (WrCheckboxGroupContext). */
     readonly isDisabled: _angular_core.Signal<boolean>;
+    /** Effective readonly state (WrCheckboxGroupContext). */
+    readonly isReadonly: _angular_core.Signal<boolean>;
     isSelected(value: unknown): boolean;
     toggle(value: unknown): void;
     /** @internal A child checkbox lost focus — see {@link WrCheckboxGroupContext.blurred}. */
     blurred(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrCheckboxGroup, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrCheckboxGroup, "wr-checkbox-group", never, { "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "touch": "touch"; }, never, ["*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrCheckboxGroup, "wr-checkbox-group", never, { "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "touch": "touch"; }, never, ["*"], true, never>;
 }
 
 export { WR_CHECKBOX_GROUP, WrCheckbox, WrCheckboxGroup };

package/types/ngwr-color-picker.d.ts

@@ -1,3 +1,4 @@
+import * as ngwr_form from 'ngwr/form';
 import * as _angular_core from '@angular/core';
 import { FormValueControl } from '@angular/forms/signals';
 import { WrSegmentedOption } from 'ngwr/segmented';
@@ -196,6 +197,23 @@ declare class WrColorPicker implements FormValueControl<string> {
     readonly alpha: _angular_core.InputSignalWithTransform<boolean, any>;
     /** Disable interaction. @default false */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, any>;
+    /**
+     * Refuse changes while every surface stays focusable and the colour still
+     * submits. Bound automatically from the field's readonly state when used with
+     * `[formField]`.
+     *
+     * The two sliders keep their tab stop and keep announcing `aria-valuenow` —
+     * they simply do not move — the hex / channel fields take the native
+     * `readonly` attribute, and the swatches go inert. Switching TABS still works:
+     * that changes which notation is displayed, not the colour. `aria-readonly` is
+     * mirrored on the sliders, which support it; the saturation surface is a
+     * `role="group"`, which does not, so it carries nothing.
+     *
+     * @default false
+     */
+    readonly readonly: _angular_core.InputSignalWithTransform<boolean, any>;
+    /** The surrounding `<wr-form-field>`'s error state. @internal */
+    protected readonly fieldAria: ngwr_form.WrFormFieldAria;
     /**
      * Format the control writes into `value`. See {@link WrColorFormat} — all
      * three are accepted on the way in whichever one is set. @default 'hex'
@@ -283,7 +301,7 @@ declare class WrColorPicker implements FormValueControl<string> {
     /** Push an RGB triple into the HSV source of truth. */
     private applyRgb;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrColorPicker, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrColorPicker, "wr-color-picker", never, { "alpha": { "alias": "alpha"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "format": { "alias": "format"; "required": false; "isSignal": true; }; "swatches": { "alias": "swatches"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "touch": "touch"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrColorPicker, "wr-color-picker", never, { "alpha": { "alias": "alpha"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "format": { "alias": "format"; "required": false; "isSignal": true; }; "swatches": { "alias": "swatches"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "touch": "touch"; }, never, never, true, never>;
 }
 
 /**

package/types/ngwr-file-upload.d.ts

@@ -1,3 +1,4 @@
+import * as ngwr_form from 'ngwr/form';
 import * as _angular_core from '@angular/core';
 import { ElementRef } from '@angular/core';
 import { FormValueControl } from '@angular/forms/signals';
@@ -57,6 +58,22 @@ declare class WrFileUpload implements FormValueControl<File | readonly File[] |
      * @default false
      */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, any>;
+    /**
+     * Refuse changes to the selection while the zone stays focusable and the files
+     * still submit. Bound automatically from the field's readonly state when used
+     * with `[formField]`.
+     *
+     * The zone stops opening the picker, a drop is refused and the per-file remove
+     * buttons go inert — but the list stays readable, which is the point. No
+     * `aria-readonly`: the zone is a `role="button"`, and ARIA does not define the
+     * state for that role, so `aria-disabled` would be the only mirror available
+     * and it would say the wrong thing.
+     *
+     * @default false
+     */
+    readonly readonly: _angular_core.InputSignalWithTransform<boolean, any>;
+    /** The surrounding `<wr-form-field>`'s error state. @internal */
+    protected readonly fieldAria: ngwr_form.WrFormFieldAria;
     /** Primary call-to-action label. Falls back to `fileUpload.browse`. */
     readonly pickLabel: _angular_core.InputSignal<string | null>;
     /** Secondary instruction below the CTA. Falls back to `fileUpload.dropZone`. */
@@ -98,7 +115,7 @@ declare class WrFileUpload implements FormValueControl<File | readonly File[] |
     private reject;
     private emit;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrFileUpload, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrFileUpload, "wr-file-upload", never, { "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "accept": { "alias": "accept"; "required": false; "isSignal": true; }; "maxSize": { "alias": "maxSize"; "required": false; "isSignal": true; }; "maxFiles": { "alias": "maxFiles"; "required": false; "isSignal": true; }; "showList": { "alias": "showList"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "pickLabel": { "alias": "pickLabel"; "required": false; "isSignal": true; }; "dropLabel": { "alias": "dropLabel"; "required": false; "isSignal": true; }; "dropZoneLabel": { "alias": "dropZoneLabel"; "required": false; "isSignal": true; }; "removeFileLabel": { "alias": "removeFileLabel"; "required": false; "isSignal": true; }; "helperText": { "alias": "helperText"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "rejected": "rejected"; "touch": "touch"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrFileUpload, "wr-file-upload", never, { "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "accept": { "alias": "accept"; "required": false; "isSignal": true; }; "maxSize": { "alias": "maxSize"; "required": false; "isSignal": true; }; "maxFiles": { "alias": "maxFiles"; "required": false; "isSignal": true; }; "showList": { "alias": "showList"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "pickLabel": { "alias": "pickLabel"; "required": false; "isSignal": true; }; "dropLabel": { "alias": "dropLabel"; "required": false; "isSignal": true; }; "dropZoneLabel": { "alias": "dropZoneLabel"; "required": false; "isSignal": true; }; "removeFileLabel": { "alias": "removeFileLabel"; "required": false; "isSignal": true; }; "helperText": { "alias": "helperText"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "rejected": "rejected"; "touch": "touch"; }, never, never, true, never>;
 }
 
 export { WrFileUpload };

package/types/ngwr-form.d.ts

@@ -214,6 +214,55 @@ declare class WrFormField implements WrFormFieldContext {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrFormField, "wr-form-field", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "optional": { "alias": "optional"; "required": false; "isSignal": true; }; "optionalLabel": { "alias": "optionalLabel"; "required": false; "isSignal": true; }; "controlId": { "alias": "controlId"; "required": false; "isSignal": true; }; "autoErrors": { "alias": "autoErrors"; "required": false; "isSignal": true; }; }, {}, ["ngControl", "projectedErrors"], ["*", "wr-form-error"], true, never>;
 }
 
+/**
+ * @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
+ */
+
+/** 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. */
+    readonly describedBy: Signal<string | null>;
+    /** `'true'` while the field is showing a message, `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.
+ *
+ * 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.
+ *
+ * `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.
+ *
+ * Must be called from an injection context (a field initialiser or a
+ * constructor). Returns inert signals outside a `<wr-form-field>`.
+ *
+ * Pass `skipSelf` from a COMPOSITE control — one whose own template renders
+ * other ngwr controls. Such a component shields its subtree by re-providing
+ * `WR_FORM_FIELD` as `null`, or the inner parts each announce the outer field's
+ * error as their own; a component sees its own providers, so it has to read the
+ * real field from one level up.
+ *
+ * @example
+ * ```ts
+ * protected readonly fieldAria = useFormFieldAria();
+ * ```
+ * ```html
+ * <input [attr.aria-invalid]="fieldAria.ariaInvalid()" [attr.aria-describedby]="fieldAria.describedBy()" />
+ * ```
+ */
+declare function useFormFieldAria(options?: {
+    readonly skipSelf?: boolean;
+}): WrFormFieldAria;
+
 /**
  * @license
  *
@@ -275,5 +324,5 @@ declare function provideWrFormErrors(messages?: WrFormErrorMessages): Environmen
  */
 declare const WR_FORM_ERROR_FALLBACKS: WrFormErrorMessages;
 
-export { WR_FORM_ERRORS, WR_FORM_ERROR_FALLBACKS, WR_FORM_FIELD, WrFormError, WrFormField, WrFormItem, provideWrFormErrors };
-export type { WrFormErrorContext, WrFormErrorMessage, WrFormErrorMessages, WrFormFieldContext };
+export { WR_FORM_ERRORS, WR_FORM_ERROR_FALLBACKS, WR_FORM_FIELD, WrFormError, WrFormField, WrFormItem, provideWrFormErrors, useFormFieldAria };
+export type { WrFormErrorContext, WrFormErrorMessage, WrFormErrorMessages, WrFormFieldAria, WrFormFieldContext };

package/types/ngwr-input-otp.d.ts

@@ -1,3 +1,4 @@
+import * as ngwr_form from 'ngwr/form';
 import * as _angular_core from '@angular/core';
 import { ElementRef } from '@angular/core';
 import { FormValueControl } from '@angular/forms/signals';
@@ -72,6 +73,27 @@ declare class WrInputOtp implements FormValueControl<string> {
      * @default false
      */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, any>;
+    /**
+     * Refuse edits while every box stays focusable and the code still submits.
+     * Bound automatically from the field's readonly state when used with
+     * `[formField]`.
+     *
+     * Each box is a real text input, so this is the native `readonly` attribute —
+     * arrow keys, Home / End and selection keep working, which is the whole
+     * difference from `disabled`. Paste is cancelled too, since a `paste` still
+     * reaches a read-only input even though typing does not.
+     *
+     * @default false
+     */
+    readonly readonly: _angular_core.InputSignalWithTransform<boolean, any>;
+    /**
+     * The surrounding `<wr-form-field>`'s error state — bound per BOX rather than
+     * on the `role="group"` host, because the box is what takes focus and a reader
+     * queries the focused element.
+     *
+     * @internal
+     */
+    protected readonly fieldAria: ngwr_form.WrFormFieldAria;
     /** Character shown in empty cells. @default '•' */
     readonly placeholder: _angular_core.InputSignal<string>;
     /** The entered code. Bound by `[formField]`, or two-way via `[(value)]`. */
@@ -116,7 +138,7 @@ declare class WrInputOtp implements FormValueControl<string> {
      */
     private inlineKey;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrInputOtp, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrInputOtp, "wr-input-otp", never, { "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "length": { "alias": "length"; "required": false; "isSignal": true; }; "mode": { "alias": "mode"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "mask": { "alias": "mask"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "completed": "completed"; "touch": "touch"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrInputOtp, "wr-input-otp", never, { "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "length": { "alias": "length"; "required": false; "isSignal": true; }; "mode": { "alias": "mode"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "mask": { "alias": "mask"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "completed": "completed"; "touch": "touch"; }, never, never, true, never>;
 }
 
 export { WrInputOtp };

package/types/ngwr-knob.d.ts

@@ -1,3 +1,4 @@
+import * as ngwr_form from 'ngwr/form';
 import * as _angular_core from '@angular/core';
 import { FormValueControl } from '@angular/forms/signals';
 
@@ -54,6 +55,19 @@ declare class WrKnob implements FormValueControl<number> {
     readonly touch: _angular_core.OutputEmitterRef<void>;
     private dragging;
     protected readonly interactive: _angular_core.Signal<boolean>;
+    /**
+     * Whether the control keeps its tab stop — `disabled` only, never `readonly`.
+     *
+     * The two states differ precisely here: a disabled control leaves the tab
+     * order, a read-only one stays in it and keeps announcing `aria-valuenow`,
+     * because a keyboard user still has to be able to READ a value they cannot
+     * change. Driving `tabindex` off `interactive()` collapsed that distinction
+     * and made `readonly()` unreachable — with an `aria-describedby` pointing at
+     * an error message on an element nobody could focus.
+     */
+    protected readonly focusable: _angular_core.Signal<boolean>;
+    /** The surrounding `<wr-form-field>`'s error state. @internal */
+    protected readonly fieldAria: ngwr_form.WrFormFieldAria;
     protected readonly classes: _angular_core.Signal<string>;
     protected readonly cx = 50;
     protected readonly cy = 50;