ngwr 14.3.1 → 14.4.0

package/theme/styles/_contrast.scss

@@ -0,0 +1,136 @@
+// `prefers-contrast: more` for the whole token layer.
+//
+// Why this lives in one file, next to `_motion.scss` and for the same reason:
+// the thing being answered is a request the USER made of the operating system,
+// about the page as a whole, and a component cannot answer it on its own. Every
+// declaration below is a token, so a component that reads the tokens — which is
+// all of them — comes along without being edited.
+//
+// What "more contrast" is being read to mean here, since the media query says
+// nothing about how much: **AAA where the role is text (7:1), and the WCAG
+// 1.4.11 bar where the role is a boundary (3:1)**. Those are the two numbers
+// the default palette deliberately does not meet, each for a recorded reason.
+//
+// THE DE-EMPHASIS TIER IS WHAT HIGH CONTRAST SPENDS. `--wr-color-text-faint`
+// and `--wr-color-text-muted` are the muted ink at 0.6 and 0.95 alpha, and
+// under this query both go to 1.0 and collapse onto the deepened role. That is
+// not a shortcut: 7:1 is UNREACHABLE at any alpha in the light theme, because
+// the base itself only reaches 5.35:1 — the alpha is not the lever, the base
+// is. Keeping a visibly fainter tier at 7:1 would need a base of `#353c46`,
+// which measures 11.13:1 on its own and is no longer a muted role at all. A
+// reader who asked for more contrast is asking for the tiers to close up.
+//
+// A LIVE DEFECT THIS EXPOSED, and it is not fixed here. At the default 0.6,
+// `text-faint` measures **2.43:1** in light and 3.46:1 in dark, and its three
+// consumers are an `input-otp` `::placeholder` (text, 1.4.3) plus the textarea
+// resize grip and the avatar spinner (graphics, 1.4.11 → 3:1). All three fail
+// today, in the DEFAULT theme, where `_colors.scss` calls them "decorative by
+// design" — a resize affordance and a loading indicator are not decorative.
+// High contrast repairs them incidentally; the default still needs a decision.
+//
+// TWO BLOCKS, NOT ONE, and this is the part that would silently half-work. A
+// `@media { :root { … } }` resolves its `var()` references against the element
+// it declares on, so a single `:root` block freezes LIGHT values into any
+// subtree-scoped `[data-theme='dark']`. The dark half has to be declared on the
+// dark selector itself.
+//
+// Every figure in the comments below is WCAG relative-luminance arithmetic on
+// solid colours, which reproduces what axe measures. Figures involving an alpha
+// composite are marked as such — those carry ±0.05 and the browser is the
+// authority. `pnpm check:contrast --contrast=more` is that authority.
+
+@use 'sass:map';
+@use 'colors';
+@use 'dark';
+
+/// The `-ink` shares under high contrast.
+///
+/// `-ink` is text by definition, so the target moves from the default 5.0:1 to
+/// AAA 7:1 — measured, as the default shares are, against the intent's own
+/// `-soft` tint rather than the plain canvas, because the tint is the darker of
+/// the two backgrounds `-ink` is documented for and therefore the binding one.
+///
+/// Each share is the MOST saturated value that still reaches 7:1 in BOTH
+/// themes, so the binding theme decides it. Dark binds for six of the seven;
+/// `warning` is the exception and binds on light, where white cannot reach it
+/// at any tone worth shipping.
+$ink-mix-more: (
+  primary: 53%,
+  secondary: 47%,
+  success: 55%,
+  warning: 36%,
+  danger: 53%,
+  info: 54%,
+  medium: 57%,
+) !default;
+
+@media (prefers-contrast: more) {
+  :root {
+    // 8.16:1 on the page, 7.07:1 on `#ebeff4` — the lightest surface the
+    // library paints, and the reference the rest of the theme layer solves
+    // against. The default `#5f6c7d` reaches 5.35 and 4.63 respectively.
+    --wr-color-muted-text: #47505d;
+    --wr-color-muted-text-rgb: 71, 80, 93;
+
+    // The de-emphasis tier closes up — see the note at the top of this file.
+    --wr-color-text-muted: rgba(var(--wr-color-muted-text-rgb), 1);
+    // unused-ok: the library paints with nothing at the faint strength any
+    // more — see the note at its declaration in `_colors.scss`. The override
+    // stays so a CONSUMER using the tier is carried into high contrast too.
+    --wr-color-text-faint: rgba(var(--wr-color-muted-text-rgb), 1);
+
+    // 3.47:1 on the page and 3.00:1 on `#ebeff4`, against the default
+    // `#cbd5e1`'s 1.48:1. This is the value AGENTS.md already records as the
+    // honest one, and the reason it is not the default is recorded there too:
+    // the token carries 103 declarations, only 15 of which are control
+    // boundaries that 1.4.11 reaches, and darkening all 103 was refused on how
+    // it looks. Under an explicit request for more contrast that trade flips —
+    // the reader has said which side they want.
+    --wr-color-outline: #718cad;
+    --wr-color-outline-rgb: 113, 140, 173;
+
+    @each $name, $share in $ink-mix-more {
+      --wr-color-#{$name}-ink: color-mix(in srgb, var(--wr-color-#{$name}) #{$share}, var(--wr-color-dark));
+    }
+  }
+
+  #{dark.dark-selector()} {
+    // 8.30:1 on the dark canvas. Dark needed far less than light — the default
+    // `#9aa6b8` already reaches 7.64 there and only misses on `fill-strong`,
+    // the harshest surface the library paints, which this closes.
+    --wr-color-muted-text: #a2adbe;
+    --wr-color-muted-text-rgb: 162, 173, 190;
+
+    --wr-color-text-muted: rgba(var(--wr-color-muted-text-rgb), 1);
+    // unused-ok: the library paints with nothing at the faint strength any
+    // more — see the note at its declaration in `_colors.scss`. The override
+    // stays so a CONSUMER using the tier is carried into high contrast too.
+    --wr-color-text-faint: rgba(var(--wr-color-muted-text-rgb), 1);
+
+    // 3.56:1 on the dark canvas, against the default `#262f44`'s 1.41:1.
+    --wr-color-outline: #566b9b;
+    --wr-color-outline-rgb: 86, 107, 155;
+
+    @each $name, $share in $ink-mix-more {
+      --wr-color-#{$name}-ink: color-mix(in srgb, var(--wr-color-#{$name}) #{$share}, var(--wr-color-dark));
+    }
+  }
+}
+
+// Adding a tenth intent to `$base-colors` without a share here would leave it
+// on its default ink under high contrast — a silent hole rather than a build
+// error, which is the failure this repo keeps finding in its own claims. So the
+// two lists are held together at COMPILE time.
+//
+// `light` and `dark` are excluded on both sides for the reason `_colors.scss`
+// records: `light` is a surface tone with no darkening that stays recognisable
+// AND readable, and `dark` already IS the ink.
+@each $name, $seed in colors.$base-colors {
+  @if $name != 'light' and $name != 'dark' {
+    @if not map.has-key($ink-mix-more, $name) {
+      @error 'No high-contrast ink share for intent `#{$name}`. Add one to ' +
+        '`$ink-mix-more` in theme/styles/_contrast.scss, derived at 7:1 against ' +
+        'that intent\'s own `-soft` tint in whichever theme binds.';
+    }
+  }
+}

package/theme/styles/_index.scss

@@ -2,6 +2,7 @@
 @forward 'colors';
 @forward 'variables';
 @forward 'dark';
+@forward 'contrast';
 @forward 'focus';
 @forward 'mixins';
 @forward 'motion';

package/theme/styles/_mixins.scss

@@ -5,15 +5,22 @@
 //   .thing { @include wr.smooth-br(0.625rem); }
 
 /// Smooth border-radius — opts into the native `corner-shape: squircle`
-/// CSS spec (Chrome 145+) when the browser supports it, otherwise
-/// falls back to a plain `border-radius`.
+/// when the browser supports it, and falls back to a plain
+/// `border-radius` when it does not.
 ///
-/// **Experimental.** `corner-shape` is a draft CSS specification; the
-/// property name, value space, and metrics may change before it
-/// stabilises. Components are free to swap this mixin out for plain
-/// `border-radius` at any time. For a deterministic squircle that
-/// works across browsers, prefer the `[wrSquircle]` directive — it
-/// uses a `clip-path` superellipse instead of relying on `corner-shape`.
+/// **This is the one place that describes the support picture, on
+/// purpose.** Six files used to name a Chrome version in a comment, all
+/// six naming the wrong one — the property shipped four releases before
+/// the number they quoted. A version in a comment is a claim nobody
+/// re-checks, so the comments elsewhere now say "where supported" and
+/// point here.
+///
+/// Where it stands: Chromium has shipped it since 139, WebKit has it in
+/// Technology Preview, Gecko does not have it yet. That is why the
+/// `@supports` guard below is the contract rather than a courtesy — a
+/// browser without the property gets the rounded corner it would have
+/// had anyway, and nothing an app relies on changes. There is no state
+/// in which a consumer has to do something about this.
 ///
 /// `corner-shape: squircle` renders a continuous-curvature corner (iOS /
 /// macOS style) instead of a circular arc. The squircle reads as

package/timeline/styles/_index.scss

@@ -40,21 +40,48 @@
     z-index: 1;
   }
 
+  // Each intent gets a SILHOUETTE, because the dot is an empty 12px span with
+  // no glyph and nothing beside it that names the state: `title` and `time` are
+  // both optional, so an item written as `<wr-timeline-item color="danger">`
+  // may carry no text of its own at all. Colour cannot do the work here —
+  // success, danger and medium sit within 1.006:1 of each other in dark and
+  // 1.006:1 in light, and success against danger is 1.004:1.
+  //
+  // The shapes follow the vocabulary the library already uses: a triangle is a
+  // warning in `wr-alert` and `wr-result`, so it is a warning here. The base
+  // dot stays a plain circle on purpose — it means "no intent given", and the
+  // quietest shape is the right one for it.
   &--success &__dot {
+    // A filled block: finished.
+    border-radius: 2px;
     background: var(--wr-color-success);
   }
 
   &--warning &__dot {
+    clip-path: polygon(50% 0%, 100% 100%, 0% 100%);
+    border-radius: 0;
     background: var(--wr-color-warning);
   }
 
   &--danger &__dot {
+    // A diamond — the loudest silhouette at this size, and unmistakable
+    // against the square and the triangle above it.
+    rotate: 45deg;
+    border-radius: 2px;
     background: var(--wr-color-danger);
   }
 
+  // color-ok: `background: transparent` plus an inset ring makes this dot
+  // HOLLOW — a silhouette, like the three above it. Both declarations happen
+  // to be colour-valued, which is the one shape this gate cannot read.
   &--medium &__dot {
+    // Hollow, which reads as the quiet one. The second shadow keeps the 2px
+    // surface halo every dot carries, so the ring does not swallow it.
     // The `color="medium"` INTENT, not the muted-text role — keep the literal.
-    background: var(--wr-color-medium);
+    background: transparent;
+    box-shadow:
+      inset 0 0 0 2px var(--wr-color-medium),
+      0 0 0 2px var(--wr-color-surface);
   }
 
   &__body {

package/toast/styles/_index.scss

@@ -155,6 +155,17 @@ $toast-colors: (
   animation: wr-toast-in 0.18s ease-out;
   overflow: hidden;
 
+  // The status glyph. Sized off the title's line box so it reads as part of the
+  // first line rather than floating above it, and inked with the accent the
+  // type already carries — the SHAPE is the channel, the colour reinforces it.
+  &__icon {
+    flex: 0 0 auto;
+    width: 1.125rem;
+    height: 1.125rem;
+    margin-block-start: 0.0625rem;
+    color: var(--wr-toast-accent);
+  }
+
   &__body {
     flex: 1 1 auto;
     min-width: 0;

package/tree/styles/_index.scss

@@ -24,6 +24,9 @@
     cursor: pointer;
     user-select: none;
     outline: 0;
+    // Positioning context for the `--active` cursor bar below. Nothing inside
+    // a row is absolutely positioned, so this establishes one for that alone.
+    position: relative;
     transition:
       background var(--wr-transition-base),
       color var(--wr-transition-base);
@@ -32,8 +35,13 @@
       background: var(--wr-color-hover);
     }
 
+    // A selected row had nothing but the tint, and `wr-tree` — unlike its
+    // sibling data view `wr-table` — ships NO checkbox mode, so in
+    // `selectionMode="multiple"` any number of rows were marked by a 1.17:1
+    // wash and nothing else. The weight is what a reader without hue has.
     &--selected {
       background: var(--wr-color-primary-soft);
+      font-weight: var(--wr-font-weight-medium);
       // Text on the `-soft` tint: `-ink`. Bare measured 4.19:1 light / 3.63:1 dark.
       color: var(--wr-color-primary-ink);
     }
@@ -50,9 +58,24 @@
     }
 
     // Active-descendant cursor when virtualized — focus lives on the list
-    // container, so the "current" row is shown by tint rather than a focus ring.
+    // container, so the "current" row cannot use the focus ring.
+    //
+    // The tint alone was the byte-identical declaration `:hover` uses above,
+    // which made the keyboard cursor indistinguishable from a mouse resting on
+    // another row. The bar is what separates them, and it is a shape rather
+    // than a colour so a selected row (also a tint) stays distinct too.
     &--active {
       background: var(--wr-color-hover);
+
+      &::before {
+        content: '';
+        position: absolute;
+        inset-block: 0;
+        inset-inline-start: 0;
+        width: 2px;
+        border-radius: inherit;
+        background: var(--wr-color-primary);
+      }
     }
   }
 
@@ -205,6 +228,9 @@
     }
   }
 
+  // color-ok: opening attaches the panel and flips the chevron 180deg, so the
+  // state is a thing appearing and a glyph rotating; this only tints the edge
+  // underneath both.
   &--open &__trigger {
     border-color: var(--wr-color-primary);
     box-shadow: 0 0 0 3px rgba(var(--wr-color-primary-rgb), 0.15);

package/types/ngwr-badge.d.ts

@@ -12,7 +12,7 @@ import * as _angular_core from '@angular/core';
  * - `rounded` (default) — small radius, matches the rest of the form vocabulary.
  * - `pill` — fully rounded ends; common for count chips and status pills.
  * - `squircle` — iOS-style continuous-curvature corners via the
- *   `corner-shape: squircle` CSS spec (Chrome 145+, falls back to a
+ *   `corner-shape: squircle` CSS spec (where supported, falls back to a
  *   plain rounded corner elsewhere).
  */
 type WrBadgeShape = 'rounded' | 'pill' | 'squircle';

package/types/ngwr-bar-chart-testing.d.ts

@@ -77,7 +77,17 @@ declare class WrBarChartHarness extends ComponentHarness {
     getBarCount(): Promise<number>;
     /** Whether the values are printed above the bars (`showValues`). */
     hasValues(): Promise<boolean>;
-    /** The plot's height in pixels, as the component writes it inline. */
+    /**
+     * The plot's height in pixels, read off the `style` ATTRIBUTE.
+     *
+     * NOT `getCssValue()`, which is `getComputedStyle()` — the same rule this
+     * file's class note already states and this method alone broke. A computed
+     * read answers from the LAID-OUT box, so it agrees with the inline value in
+     * jsdom (which lays nothing out and echoes the declaration) and disagrees in a
+     * browser, where sub-pixel rounding turns a declared 240 into 239.5. A harness
+     * that answers differently in the two places it runs is worse than one that
+     * refuses.
+     */
     getPlotHeight(): Promise<number>;
 }
 

package/types/ngwr-button.d.ts

@@ -24,7 +24,7 @@ type WrButtonSize = 'sm' | 'md' | 'lg';
  * - `rounded` (default) — small radius, matches the rest of the form vocabulary.
  * - `pill` — fully rounded ends; ideal for solitary CTAs.
  * - `squircle` — iOS-style continuous-curvature corners via the
- *   `corner-shape: squircle` CSS spec (Chrome 145+, falls back to a
+ *   `corner-shape: squircle` CSS spec (where supported, falls back to a
  *   plain rounded corner elsewhere). For a deterministic
  *   clip-path-based squircle that works across browsers, wrap the
  *   button in `[wrSquircle]` instead.

package/types/ngwr-calendar-heatmap-testing.d.ts

@@ -36,9 +36,14 @@ interface WrCalendarHeatmapCell {
  *
  * **Every square is `aria-hidden`, and that is the design.** The grid is one
  * `role="img"` with a name; a year of individually announced days would be unusable
- * with a screen reader. What each square carries instead is a `title` — its ISO date
- * and value — which is the only text a spec can read, and what
- * {@link getCells} parses.
+ * with a screen reader. What each square carries instead is `data-date` and
+ * `data-value`, which is what {@link getCells} reads.
+ *
+ * NOT the `title`, which it used to parse. The tooltip is human-facing text now
+ * — the date formatted for the reader's locale, the count through
+ * `Intl.NumberFormat`, and the sentence composed in the catalog — so parsing it
+ * would have made every assertion here depend on the locale the suite happens to
+ * run under, and on wording a translator is free to change.
  *
  * **Four of the seven weekday labels are blank on purpose**: seven do not fit beside
  * a grid this dense. {@link getWeekdayLabels} returns them as they are, empties
@@ -61,8 +66,8 @@ declare class WrCalendarHeatmapHarness extends ComponentHarness {
     /**
      * Every square, from its tooltip and its grid placement.
      *
-     * The `title` is `"<iso>: <value>"`, which is the component's own format and the
-     * only text on a square — everything else about it is colour.
+     * Read from `data-date` / `data-value`, which the component writes for exactly
+     * this. Everything else about a square is colour.
      */
     getCells(): Promise<WrCalendarHeatmapCell[]>;
     /** The value a given ISO date's square reports, or `null` when that day is not drawn. */

package/types/ngwr-calendar-heatmap.d.ts

@@ -8,6 +8,8 @@ interface WrHeatmapDatum {
 
 interface Cell {
     readonly iso: string;
+    /** The day as the reader's locale writes it — see `cellTitle`. */
+    readonly date: Date;
     readonly value: number;
     readonly intensity: number;
     readonly week: number;
@@ -34,6 +36,26 @@ declare class WrCalendarHeatmap {
      */
     readonly ariaLabel: _angular_core.InputSignal<string | null>;
     protected readonly resolvedAriaLabel: _angular_core.Signal<string>;
+    private readonly cellText;
+    /**
+     * A cell's tooltip, with both halves formatted and the sentence in the catalog.
+     *
+     * It used to be `` `${cell.iso}: ${cell.value}` `` — a raw ISO date beside an
+     * unformatted number, joined by a hard-coded `': '`. Three things were wrong
+     * at once and none of them are visible from the template: `2026-09-10` is not
+     * how most of the world writes a date, `1234` is not how every locale groups
+     * digits (`ar-SA` does not even use these ones), and the separator and order
+     * were frozen into a shape a translator could not reach.
+     *
+     * Both halves go through `Intl` on the SAME locale the rest of the component
+     * resolves — `WR_DATE_LOCALE`, which since v14 follows Angular's `LOCALE_ID`.
+     * The key ships as `{{date}}: {{count}}` everywhere, so nothing reorders today
+     * and every locale can.
+     */
+    protected cellTitle(cell: {
+        readonly date: Date;
+        readonly value: number;
+    }): string;
     /** Last day to render. @default today */
     readonly endDate: _angular_core.InputSignal<string | Date | null>;
     /** Number of weeks (columns) to render. @default 53 */

package/types/ngwr-calendar.d.ts

@@ -170,7 +170,28 @@ declare class WrCalendar {
     protected next(): void;
     /** Header label click — zooms out (`day → month → year`). No-op at year view. */
     protected onLabelClick(): void;
+    /**
+     * Picking a month drops to the day grid — and takes real focus with it.
+     *
+     * The `@switch (viewMode())` in the template destroys the chip that holds DOM
+     * focus, so without the two lines below `document.activeElement` became
+     * `<body>`: the ring appeared on the new view and focus did not, the arrow
+     * keys went dead (the keydown handler is a HOST binding, so nothing reaches
+     * the component from `<body>`), and the next Tab restarted from the top of the
+     * document — out of the calendar entirely. It is the same trap the two
+     * keyboard paths in this file already fix, and for the same reason
+     * `afterNextRender` rather than `queueMicrotask`: under zoneless CD the
+     * microtask runs before the new view is in the DOM.
+     *
+     * `focusedDate` has to move too, and that half is easy to miss. The grid marks
+     * its focusable cell by comparing against `focusedDate`, not `viewDate`, so
+     * choosing a DIFFERENT month rendered a grid with no `--focused` cell and no
+     * `tabindex="0"` at all — unreachable by keyboard from either direction. The
+     * day is preserved when the month already holds it and otherwise falls to the
+     * first, which is where `viewDate` lands anyway.
+     */
     protected onMonthSelect(monthIdx: number): void;
+    /** Year → month view, with the same focus restoration; the landing view is chips. */
     protected onYearSelect(year: number): void;
     /**
      * Switch views and drop the chip ring with them.

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

@@ -56,21 +56,25 @@ interface WrCascaderOptionHarnessFilters extends BaseHarnessFilters {
  *
  * An option is either a BRANCH (it has children, so clicking it opens the next
  * column) or a LEAF (clicking it commits the whole path and closes the panel).
- * {@link hasChildren} is the only way to tell them apart, and it reads the
- * chevron the template draws for branches — the option carries no
- * `aria-haspopup` / `aria-expanded`, so a screen-reader user is told nothing
- * about a branch either. Reported here rather than papered over.
+ * {@link hasChildren} reads the chevron the template draws for branches;
+ * {@link isExpanded} reads the state that same branch announces. The two are
+ * not one question — a branch always HAS children and is expanded only while
+ * the column to its right is showing them.
+ *
+ * The panel is a `role="tree"` and an option is a `treeitem`. It was a `menu`
+ * of `menuitem`s until the roles were corrected, and this class documented that
+ * a branch announced nothing at all; both are historical now.
  *
  * @see https://ngwr.dev/guides/testing
  */
 declare class WrCascaderOptionHarness extends ComponentHarness {
-    /** The `<li role="menuitem">` a column renders per option. */
+    /** The `<li role="treeitem">` a column renders per option. */
     static hostSelector: string;
     /** Build a predicate that narrows the query. */
     static with(options?: WrCascaderOptionHarnessFilters): HarnessPredicate<WrCascaderOptionHarness>;
     /** The option's label, trimmed. The branch chevron contributes no text. */
     getText(): Promise<string>;
-    /** The role the option announces — `menuitem`. */
+    /** The role the option announces — `treeitem`. */
     getRole(): Promise<string | null>;
     /** Whether the option refuses selection, from the state a screen reader is given. */
     isDisabled(): Promise<boolean>;
@@ -79,11 +83,40 @@ declare class WrCascaderOptionHarness extends ComponentHarness {
      * whose children the column to the right is showing, or the committed segment
      * at this level.
      *
-     * Read from the `--active` modifier because nothing else says it: the option
-     * has no `aria-selected` and no `aria-expanded`, so the class is both the
-     * whole visual answer and the only one available.
+     * Read from the `--active` modifier, and NOT the same question as
+     * {@link isSelected}: this one tracks where the user has navigated, that one
+     * tracks what they committed. They agree only once a leaf is picked, and a
+     * harness that collapsed them would hide exactly the divergence it exists to
+     * catch.
      */
     isActive(): Promise<boolean>;
+    /**
+     * Whether this option is the committed choice, or `null` when it is not a
+     * choice at all.
+     *
+     * `null` — the attribute absent — for a branch while `changeOnSelect` is off,
+     * because such a branch genuinely cannot be chosen. Answering a plausible
+     * `false` there would report an unselectable row as merely unselected, which
+     * is the distinction the attribute exists to carry.
+     */
+    isSelected(): Promise<boolean | null>;
+    /**
+     * Whether this branch's children are the column to its right, or `null` for a
+     * leaf.
+     *
+     * `null` rather than `false`, and the difference is the whole point: a leaf
+     * does not have a collapsed subtree, it has none. `aria-expanded="false"` on
+     * one would state that a subtree exists and is shut.
+     */
+    isExpanded(): Promise<boolean | null>;
+    /**
+     * The option's depth, 1-based — its `aria-level`.
+     *
+     * Worth reading in a spec rather than trusting: the columns are DOM SIBLINGS,
+     * so nothing about the markup's shape carries depth. Every option would be
+     * level 1 if this attribute were dropped, and no gate would say so.
+     */
+    getLevel(): Promise<number | null>;
     /** Whether the option opens a deeper level rather than ending the path. */
     hasChildren(): Promise<boolean>;
     /**
@@ -117,10 +150,10 @@ declare class WrCascaderOptionHarness extends ComponentHarness {
      * This is the component's entire keyboard model — the columns bind
      * `keydown.enter` / `keydown.space` per option and nothing else, so there are
      * no arrow keys to walk levels with. A keyboard user reaches the option they
-     * want with Tab and presses Enter — and Tab is a long way round: the panel is a
-     * portal in the overlay container at the end of the document, and nothing moves
-     * focus into it on open, so the first option is not the next stop after the
-     * trigger.
+     * want with Tab and presses Enter. Opening the panel does move focus into it —
+     * `focusPanelOption()` lands on the active option, or the first enabled one —
+     * so the walk starts there rather than from the trigger; this JSDoc claimed
+     * the opposite for a while and was simply wrong.
      */
     selectByKeyboard(): Promise<void>;
     /**
@@ -165,11 +198,11 @@ declare class WrCascaderOptionHarness extends ComponentHarness {
  * @see https://ngwr.dev/guides/testing
  */
 declare class WrCascaderColumnHarness extends ComponentHarness {
-    /** The `<ul role="menu">` the panel renders per level. */
+    /** The `<ul role="group">` the panel renders per level, inside the `tree`. */
     static hostSelector: string;
     /** Build a predicate that narrows the query. */
     static with(options?: WrCascaderColumnHarnessFilters): HarnessPredicate<WrCascaderColumnHarness>;
-    /** The role the column announces — `menu`. */
+    /** The role the column announces — `group`, inside the panel's `tree`. */
     getRole(): Promise<string | null>;
     /** The options this level offers, in order. */
     getOptions(filters?: WrCascaderOptionHarnessFilters): Promise<WrCascaderOptionHarness[]>;
@@ -269,9 +302,16 @@ declare class WrCascaderHarness extends ComponentHarness {
      * nothing selected and no placeholder would otherwise have no name at all.
      */
     getAccessibleName(): Promise<string | null>;
-    /** The kind of popup the trigger promises via `aria-haspopup` — `menu`. */
+    /**
+     * The kind of popup the trigger promises via `aria-haspopup` — `tree`.
+     *
+     * Worth pinning rather than assuming: a combobox's popup may be a listbox, a
+     * tree, a grid or a dialog and nothing else, and this one said `menu` for a
+     * long time. `menu` is a valid token for the global `aria-haspopup`, so axe
+     * reports nothing either way — an assertion here is the only guard there is.
+     */
     getPopupRole(): Promise<string | null>;
-    /** The role the panel announces — `menu`, matching what the trigger promised. */
+    /** The role the panel announces — `tree`, matching what the trigger promised. */
     getPanelRole(): Promise<string | null>;
     /**
      * The id the trigger publishes as `aria-controls`.
@@ -368,6 +408,23 @@ declare class WrCascaderHarness extends ComponentHarness {
      * rendered at all in either case (nor while disabled).
      */
     clear(): Promise<void>;
+    /**
+     * Clear from the keyboard — Backspace on the closed trigger.
+     *
+     * The × {@link clear} clicks is a `tabindex="-1"` span inside the trigger, so no
+     * key can ever reach it; Backspace on the trigger is its keyboard twin, and the
+     * route a keyboard-only user actually has. Prefer this one in a spec that cares
+     * about that user — {@link clear} proves the pointer path and nothing more.
+     *
+     * The component honours the key only on the CLOSED trigger, so an open panel
+     * is closed first with Escape — the step a keyboard user takes too. Sending
+     * Backspace into an open panel and returning would be a plausible nothing.
+     *
+     * Does nothing, rather than throwing, when there is nothing to clear, `clearable`
+     * is off, or the cascader is disabled or read-only: that silence IS the
+     * component's contract, so a spec asserts it on the value.
+     */
+    clearByKeyboard(): Promise<void>;
     /** Move keyboard focus to the trigger. */
     focus(): Promise<void>;
     /** Take focus off the trigger, which is what makes a bound form field touched. */

package/types/ngwr-cascader.d.ts

@@ -148,6 +148,34 @@ declare class WrCascader<T = string> implements FormValueControl<unknown> {
     protected onOptionClick(colIndex: number, opt: WrCascaderOption<T>, event: Event): void;
     protected clearSelection(event: Event): void;
     protected isActiveAt(colIndex: number, value: T): boolean;
+    /**
+     * Whether this option is the committed choice — `null` when it is not a
+     * choice at all.
+     *
+     * Two questions the panel has to keep apart, and `--active` answers only the
+     * first: `activePath()` is where the user has NAVIGATED to, `path()` is what
+     * they have COMMITTED. They agree once a leaf is picked and diverge for the
+     * whole walk down.
+     *
+     * `null` — the attribute absent — on a branch while `changeOnSelect` is off,
+     * because such a branch genuinely cannot be chosen; ARIA reads a missing
+     * `aria-selected` as "not selectable", which is exactly true here. That makes
+     * this binding the first expression the `changeOnSelect` contract has ever had
+     * in ARIA, in both directions.
+     */
+    protected isSelectedAt(colIndex: number, opt: WrCascaderOption<T>): boolean | null;
+    /** Stable id for one option — what a column's `aria-labelledby` points at. */
+    protected optionId(colIndex: number, optIndex: number): string;
+    /** Stable id for one column — what an expanded branch's `aria-controls` points at. */
+    protected columnId(colIndex: number): string;
+    /**
+     * The option whose children a column holds, by id — its accessible name.
+     *
+     * The columns are DOM SIBLINGS, so nothing in the markup says the second one
+     * belongs to "Europe". Column 0 has no parent and stays unnamed; the tree
+     * itself already carries the control's name.
+     */
+    protected parentOptionId(colIndex: number): string | null;
     private pathsEqual;
     private openOverlay;
     /**

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

@@ -61,7 +61,18 @@ declare class WrCheckboxHarness extends ComponentHarness {
      */
     isIndeterminate(): Promise<boolean>;
     isDisabled(): Promise<boolean>;
-    /** The group identity — `checkboxValue`, not the form value. */
+    /**
+     * The group identity — `checkboxValue`, not the form value.
+     *
+     * Read off the host's `data-checkbox-value`, which the component reflects for
+     * exactly this. It used to read `value` from the inner `<input>`, an attribute
+     * nothing writes, so it answered `null` for every checkbox whatever its
+     * identity — the shape these harnesses are not allowed to have.
+     *
+     * `null` still means one honest thing: no identity, or an identity that is not
+     * a primitive. An object or an array has no attribute form, and a harness
+     * cannot reach a TypeScript value the DOM never carried.
+     */
     getCheckboxValue(): Promise<string | null>;
     /** Flip the box. A disabled checkbox does not move; assert rather than assume. */
     toggle(): Promise<void>;