ngwr 14.7.0 → 14.9.0

package/theme/styles/_colors.scss

@@ -212,14 +212,14 @@ $contrast-light: #ffffff !default;
   --wr-color-fill: rgba(var(--wr-color-light-rgb), 0.3);
   --wr-color-fill-strong: rgba(var(--wr-color-light-rgb), 0.55);
 
-  // De-emphasized text — the muted ink dimmed to two canonical strengths so
-  // labels / captions / placeholders read consistently. One place each.
-  // Only the full-opacity token above is AA-safe for body text; these two are
-  // decorative by design (0.85 reaches ~3.5:1, 0.6 ~2.3:1 on a light surface).
-  // 0.95, not 0.85: the role itself is 5.35:1 on the light surface, but wrapping
-  // it at 0.85 composited to #778291 — 3.90:1, under the AA bar. 0.95 is the
-  // most softening that still clears it (4.81), which leaves this token barely
-  // distinguishable from the flat role it wraps.
+  // De-emphasized text — the muted ink at two strengths, and only the first is
+  // text. `-text-muted` is 0.95, not 0.85: the role itself is 5.35:1 on the
+  // light surface, but wrapping it at 0.85 composited to #778291 — 3.90:1,
+  // under the AA bar. 0.95 is the most softening that still clears it (4.81),
+  // which leaves this token barely distinguishable from the flat role it wraps.
+  // Every library rule that read it was a placeholder, and those read
+  // `--wr-color-placeholder` now; it stays for the muted labels a consumer
+  // writes. `-text-faint` is below every bar — see its marker.
   --wr-color-text-muted: rgba(var(--wr-color-muted-text-rgb), 0.95);
   // unused-ok: the library paints with nothing at this strength any more, and
   // that is the finding rather than an oversight. It had exactly three
@@ -227,11 +227,14 @@ $contrast-light: #ffffff !default;
   // spinner — and all three were FAILING: 2.43:1 in light, against 4.5:1 for
   // placeholder text and 3:1 for an interactive affordance and a status
   // indicator. "Decorative by design" was true of the token and not of any of
-  // the three, so they moved to `-text-muted` and `-on-surface-muted`. The tier
-  // stays published because a custom property is public API and a consumer may
-  // have genuinely decorative text; the library, it turns out, has none. Note
-  // that no gate reports the shortfall: axe has no non-text-contrast rule, and
-  // `check:contrast` gates on route counts.
+  // the three, so the grip and the spinner moved to `-on-surface-muted` and the
+  // placeholder to `--wr-color-placeholder`. The tier stays published because a
+  // custom property is public API and a consumer may have genuinely decorative
+  // text; the library, it turns out, has none. No gate reports a GRAPHIC at
+  // this strength — axe has no non-text-contrast rule. A placeholder painted
+  // with it fails `check:contrast`'s probe only where the probe can reach one,
+  // an at-rest `::placeholder`; every other placeholder rule is held to
+  // `--wr-color-placeholder` at the source, by `theme/styles.spec.ts`.
   --wr-color-text-faint: rgba(var(--wr-color-muted-text-rgb), 0.6);
 
   // Semantic role aliases over the flipping neutrals — prefer these in new code
@@ -257,6 +260,29 @@ $contrast-light: #ffffff !default;
   --wr-color-on-surface-muted: var(--wr-color-muted-text);
   --wr-color-on-surface-muted-rgb: var(--wr-color-muted-text-rgb);
 
+  // Placeholder text — its own role because placeholders are where the catalog
+  // kept inventing strengths: four of them, down to `rgba(…, 0.7)` on
+  // `[wrInput]` and `wr-textarea` at 2.91:1 in light, and the table filter's
+  // search on the browser's own #757575 at 4.08:1 in dark. A placeholder is
+  // TEXT, so 1.4.3 asks 4.5:1, and the muted role is the only value that holds
+  // on both backgrounds a field paints — 5.34:1 on the surface and 4.76:1 on the
+  // `--wr-color-fill` of a readonly `[wrInput]` (7.63 / 7.03 in dark, and 8.16 /
+  // 8.30 under `prefers-contrast: more`, where the muted base is what deepens).
+  // No softer tier fits under it: 4.5:1 needs 0.93 alpha on white and 0.98 on
+  // the readonly fill. The price is that an empty READONLY `[wrInput]` paints its
+  // placeholder in the colour a readonly value takes; `-text-muted` would keep
+  // them apart and fails there at 4.29. Written as the role rather than a
+  // literal, so dark and high contrast follow it on their own, and with no
+  // `-rgb` twin on purpose — an alpha over the muted channel is the defect this
+  // replaced. What measures it is narrower than "every placeholder":
+  // `check:contrast` swaps in each `::placeholder` a page shows at rest, plain
+  // `color-contrast` reads the select, cascader and tree triggers (text spans),
+  // and nothing painted reaches the command palette's or the table filter's,
+  // which exist only inside an overlay. `theme/styles.spec.ts` covers all of
+  // them the other way — every placeholder rule reads this token — so the
+  // unmeasured ones sit at the measured value.
+  --wr-color-placeholder: var(--wr-color-on-surface-muted);
+
   // Solid hairline / divider colour. Distinct from `--wr-color-border` above,
   // which is deliberately translucent (`light` at 50%) so it reads on any
   // surface — `outline` is the opaque one components actually draw 1px rules

package/theme/styles/_contrast.scss

@@ -20,13 +20,15 @@
 // 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.
+// WHAT THIS ONCE REPAIRED BY ACCIDENT. At the default 0.6, `text-faint`
+// measures **2.43:1** in light and 3.46:1 in dark, and this block used to be
+// the only thing lifting its three consumers — 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 left the tier in the DEFAULT theme: the placeholder
+// for `--wr-color-placeholder`, the two graphics for `-on-surface-muted`. So the
+// faint override below carries a consumer's own use of the tier and nothing of
+// the library's. `--wr-color-placeholder` needs no line of its own here: it IS
+// the muted role, so the deepened base carries it to 8.16:1 and 8.30:1.
 //
 // TWO BLOCKS, NOT ONE, and this is the part that would silently half-work. A
 // `@media { :root { … } }` resolves its `var()` references against the element

package/toast/styles/_index.scss

@@ -249,6 +249,10 @@ $toast-colors: (
     animation-play-state: paused;
   }
 
+  // color-ok: every type draws its own glyph in toast-item.html — a check in a
+  // broken circle, a triangle, an octagon, an `i`, the shapes `wr-alert` uses —
+  // and the host announces it as `role="alert"` or `"status"`. The accent only
+  // inks the edge, the glyph and the countdown.
   @each $variant, $color in $toast-colors {
     &--#{$variant} {
       --wr-toast-accent: var(--wr-color-#{$color});

package/toolbar/styles/_index.scss

@@ -33,7 +33,9 @@
   &__zone {
     display: flex;
     align-items: center;
-    gap: 0.5rem;
+    // Density-aware: `touch` widens it so adjacent controls do not crowd a
+    // fingertip, `sm` tightens it. `md` resolves to the 8px it always was.
+    gap: calc(0.5rem * var(--wr-density-gap, 1));
     min-width: 0;
 
     &:empty {
@@ -74,6 +76,38 @@
   }
 }
 
+// The documented zone shape is ONE wrapper around the controls —
+// `<div wrToolbarEnd><wr-btn>…</wr-btn><wr-btn>…</wr-btn></div>` — and the zone's
+// `gap` spaces the zone's CHILDREN, which is that wrapper alone, so the buttons
+// inside it met edge to edge (0px, measured in Chromium). A BARE wrapper is laid
+// out the way the zone is, taking the zone's own gap through `inherit`, so both
+// shapes — one wrapper, or the attribute on each control — space the same and a
+// density change moves them together. It wraps, as the inline flow it replaces
+// did, so a stacked `responsive` zone still folds its controls onto a second
+// row, now with the gap between the rows as well. What BARE excludes, and why:
+//
+// - A `class` or a `style`. Zero specificity alone does not keep a consumer's
+//   layout: ngwr ships unlayered CSS, and unlayered CSS beats every cascade
+//   layer whatever its specificity, so a Tailwind v4 `hidden`, `grid` or `gap-4`
+//   on the wrapper lost to this rule and a hidden wrapper came back. A wrapper
+//   with a class or a style is the consumer's, and nothing here touches it — not
+//   `display`, not `align-items`, not `flex-wrap`. An EMPTY one still counts as
+//   bare, because `class=""` / `style=""` is what a `[class.x]` / `[style.x]`
+//   binding leaves behind when it switches off, and the same state must not lay
+//   out two ways.
+// - Anything but a `div`. A control projected directly is already a child of the
+//   zone and spaced by its gap, and must not become a flex container itself.
+//   Running text belongs in a `<span>` or a `<p>`, which stay in inline flow: in
+//   a bare `<div>` its words and links would become separate flex items.
+// - `[hidden]`. An author rule outranks the user agent's
+//   `[hidden] { display: none }` at any specificity.
+:where(.wr-toolbar__zone > div:not([hidden], [class]:not([class='']), [style]:not([style='']))) {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: inherit;
+}
+
 // Responsive toolbars stack their zones when the bar is too narrow for a row.
 @container wr-toolbar (max-width: 32rem) {
   .wr-toolbar--responsive .wr-toolbar__zone {

package/tree/styles/_index.scss

@@ -177,15 +177,51 @@
     --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.
+    // Trigger width floor, the same contract as `--wr-select-min-width`.
+    // Despite the name it is a DEFAULT width rather than a minimum: an explicit
+    // `width`, `width: 100%` in a narrow parent, a `minmax(0, 1fr)` cell and a
+    // shrinking flex item all win over it (see `::after` below). Set it to 0 to
+    // size a bare trigger to its content alone. This hook is the only way to
+    // lower it: a `min-width` on `.wr-tree__trigger`, the override that did it
+    // before the hook existed, no longer reaches the floor.
     --wr-tree-trigger-min-width: 12rem;
 
-    display: inline-flex;
+    // One column that shrinks to whatever the layout gives it and, left to size
+    // itself, grows to the widest thing in it — the trigger's content or the
+    // floor. The floor used to be a `min-width` on the trigger, which no width
+    // on the host could beat: `style="width: 6rem"` drew a 192px trigger in a
+    // 96px host, and in a 200px flex row beside a 120px sibling the tree
+    // overflowed the row by 120px. `minmax(0, …)` also drops the label's text
+    // from the host's min-content, so it shrinks as a flex item the way
+    // `[wrInput]` does and the label truncates instead.
+    display: inline-grid;
+    grid-template-columns: minmax(0, 1fr);
+    // The spacer below lands in a row of its own, and it must be a FIXED 0
+    // rather than an implicit `auto` one: a grid shares height beyond its
+    // content among its auto rows, so a host stretched by a taller flex or grid
+    // row, or given a `height`, drew a 45px trigger in a 60px host with an empty
+    // band beneath it.
+    grid-template-rows: auto 0;
     vertical-align: middle;
 
+    // The floor as a zero-height spacer in the same column. A grid track's
+    // max-content is its widest item, so a host sized to its content is at
+    // least `--wr-tree-trigger-min-width` wide; `max-width: 100%` is ignored
+    // while that size is being worked out and applies once the column exists,
+    // so a narrower host caps the spacer instead of the spacer stretching the
+    // host. `flex: 0 0 0` keeps it from taking room beside the trigger if a
+    // consumer turns the host into a flex container (the floor is then inert,
+    // never in the way). In overlay mode the template renders exactly one
+    // element into the host — the trigger — so this is the column's only other
+    // item, and the zero row is the spacer's.
+    &::after {
+      content: '';
+      flex: 0 0 0;
+      width: var(--wr-tree-trigger-min-width);
+      max-width: 100%;
+      height: 0;
+    }
+
     &.wr-tree--disabled {
       --wr-tree-trigger-color: var(--wr-color-on-surface-muted);
       --wr-tree-trigger-bg: var(--wr-color-fill);
@@ -197,7 +233,10 @@
     align-items: center;
     gap: 0.5rem;
     width: 100%;
-    min-width: var(--wr-tree-trigger-min-width);
+    // Not the floor — that lives on the host, where a width can beat it. Zero
+    // lets the trigger follow the host down and the label's ellipsis take the
+    // difference.
+    min-width: 0;
     appearance: none;
     background: var(--wr-tree-trigger-bg);
     color: var(--wr-tree-trigger-color);
@@ -245,7 +284,7 @@
   }
 
   &__placeholder {
-    color: var(--wr-color-text-muted);
+    color: var(--wr-color-placeholder);
   }
 
   &__chevron {

package/types/ngwr-badge.d.ts

@@ -40,9 +40,10 @@ type WrBadgeSize = 'sm' | 'md' | 'lg';
 type WrTagIconPosition = 'start' | 'end';
 
 /**
- * Lean status chip — color, size, rounded/pill. Use for short labels
- * and counts (e.g. "ONLINE", "3 unread", "v2.1"). Reach for `<wr-tag>`
- * when you need icons, loading state, or outlined / transparent styles.
+ * Lean chip — color, size, rounded/pill. Use for short labels and counts
+ * (e.g. "ONLINE", "3 unread", "v2.1"), where the words say the state and the
+ * colour decorates it. Reach for `<wr-tag>` when you need icons, loading
+ * state, or outlined / transparent styles.
  *
  * @example
  * ```html
@@ -55,7 +56,12 @@ type WrTagIconPosition = 'start' | 'end';
  */
 declare class WrBadge {
     /**
-     * Color variant. Maps to `--wr-color-*` CSS variables from the theme.
+     * Color variant. Maps to `--wr-color-*` CSS variables from the theme. It is
+     * decoration or category, never the state on its own: six of the nine intents
+     * share one lightness and `success` against `danger` is 1.004:1, so the label
+     * has to say the state (`Offline`, not a red `Status`). A badge draws no
+     * icon — when a chip must stand for a status without words, use `<wr-tag>`
+     * with its `icon` input.
      *
      * @default 'primary'
      */
@@ -101,14 +107,23 @@ declare class WrBadge {
  */
 declare class WrTag {
     /**
-     * Color variant.
+     * Color variant — decoration or category, never the state on its own. The
+     * label carries the state (`Failed`, not a red `Build`): six of the nine
+     * intents share one lightness and `success` against `danger` is 1.004:1, so a
+     * reader who cannot separate red from green cannot tell those two tags
+     * apart, and `primary` and `info` are the same blue to everyone. When a tag has to stand
+     * for a status by itself, give it an `icon` as well — register one with
+     * `provideWrIcons(lucideIcons({ 'octagon-alert': OctagonAlert }))`, then write
+     * `<wr-tag color="danger" icon="octagon-alert">Failed</wr-tag>`.
      *
      * @default 'primary'
      */
     readonly color: _angular_core.InputSignal<"primary" | "secondary" | "success" | "warning" | "danger" | "info" | "light" | "medium" | "dark">;
     /**
-     * Icon name shown alongside the content. The icon is replaced by a
-     * spinner when `loading` is true.
+     * Icon name shown alongside the content — the one channel besides the label
+     * that a tag has, so the one to reach for when colour is carrying a status.
+     * Nothing ships built in: register the name through `provideWrIcons` first.
+     * The icon is replaced by a spinner when `loading` is true.
      *
      * @default null
      */

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

@@ -1,3 +1,4 @@
+import * as ngwr_popover from 'ngwr/popover';
 import * as _angular_core from '@angular/core';
 
 /** One bar's worth of data. */
@@ -32,6 +33,12 @@ declare class WrBarChart {
     readonly height: _angular_core.InputSignalWithTransform<number, unknown>;
     /** Explicit max value. `0` = auto. @default 0 */
     readonly max: _angular_core.InputSignalWithTransform<number, unknown>;
+    /**
+     * Show a tooltip with the bar's label and value on hover. Pointer only — the
+     * column's accessible name already carries both. @default true
+     */
+    readonly tooltip: _angular_core.InputSignalWithTransform<boolean, any>;
+    private readonly barEls;
     /**
      * A datum's value, with anything non-finite read as `0`.
      *
@@ -55,8 +62,19 @@ declare class WrBarChart {
          */
         name: string;
     }[]>;
+    /**
+     * One tooltip for the whole chart, with the value exactly as it is printed above
+     * the bar. It points at the top edge of the BAR — above it, below it when there is
+     * no room — rather than at the column, which is the full height of the plot and
+     * would put the chip above every bar alike. A bar with nothing to draw (zero, a
+     * negative value) keeps its 1px floor on the baseline, so its chip points there.
+     *
+     * The bar is the anchor element itself, so an open chip follows it through the
+     * height transition a data change starts.
+     */
+    protected readonly tip: ngwr_popover.WrChartTooltip;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrBarChart, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrBarChart, "wr-bar-chart", never, { "data": { "alias": "data"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "showValues": { "alias": "showValues"; "required": false; "isSignal": true; }; "height": { "alias": "height"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrBarChart, "wr-bar-chart", never, { "data": { "alias": "data"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "showValues": { "alias": "showValues"; "required": false; "isSignal": true; }; "height": { "alias": "height"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "tooltip": { "alias": "tooltip"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 export { WrBarChart };

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

@@ -1,3 +1,4 @@
+import * as ngwr_popover from 'ngwr/popover';
 import * as _angular_core from '@angular/core';
 
 interface WrHeatmapDatum {
@@ -70,6 +71,13 @@ declare class WrCalendarHeatmap {
     readonly emptyColor: _angular_core.InputSignal<string>;
     /** Show the weekday + month labels around the grid. @default true */
     readonly showLabels: _angular_core.InputSignalWithTransform<boolean, any>;
+    /**
+     * Show a tooltip with the day and its count on hover. It is the sentence the
+     * square's `title` carried, so the `title` is written only while this is off —
+     * or the browser would open a second copy a moment later. @default true
+     */
+    readonly tooltip: _angular_core.InputSignalWithTransform<boolean, any>;
+    private readonly daysEl;
     private readonly locale;
     /**
      * Weekday names from the locale rather than a hard-coded English list — the row order is
@@ -84,10 +92,30 @@ declare class WrCalendarHeatmap {
         week: number;
     }[]>;
     protected readonly columnCount: _angular_core.Signal<number>;
+    /** Each day's position in `cells()`, for the square the pointer lands on. */
+    private readonly indexByIso;
+    /**
+     * One tooltip for the whole year, pointing at the hovered day: above its square,
+     * below it when there is no room above, and slid along the viewport edge for the
+     * first and last weeks with the arrow still on the square. A listener on the grid
+     * rather than one per square: a year is 371 of them.
+     *
+     * The box is the square's LAYOUT box rather than its client rect. The hovered square
+     * grows by `:hover` over a transition, and a rect read part way through it would
+     * move the chip by up to a fifth of a square depending on when it was measured;
+     * the scale is centred, so the layout box is the rect's centre and the square's
+     * own size.
+     */
+    protected readonly tip: ngwr_popover.WrChartTooltip;
+    /**
+     * Which square the pointer is on, from a `mousemove` on the grid. Over the gap
+     * between two squares it is on none, and the tooltip starts to leave.
+     */
+    protected onCellsPointer(event: MouseEvent): void;
     protected colorFor(intensity: number): string;
     protected opacityFor(intensity: number): number;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrCalendarHeatmap, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrCalendarHeatmap, "wr-calendar-heatmap", never, { "data": { "alias": "data"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "endDate": { "alias": "endDate"; "required": false; "isSignal": true; }; "weeks": { "alias": "weeks"; "required": false; "isSignal": true; }; "cellSize": { "alias": "cellSize"; "required": false; "isSignal": true; }; "cellGap": { "alias": "cellGap"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "emptyColor": { "alias": "emptyColor"; "required": false; "isSignal": true; }; "showLabels": { "alias": "showLabels"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrCalendarHeatmap, "wr-calendar-heatmap", never, { "data": { "alias": "data"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "endDate": { "alias": "endDate"; "required": false; "isSignal": true; }; "weeks": { "alias": "weeks"; "required": false; "isSignal": true; }; "cellSize": { "alias": "cellSize"; "required": false; "isSignal": true; }; "cellGap": { "alias": "cellGap"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "emptyColor": { "alias": "emptyColor"; "required": false; "isSignal": true; }; "showLabels": { "alias": "showLabels"; "required": false; "isSignal": true; }; "tooltip": { "alias": "tooltip"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 export { WrCalendarHeatmap };

package/types/ngwr-checkbox.d.ts

@@ -111,6 +111,8 @@ declare class WrCheckbox implements FormCheckboxControl {
      * only and controlled: set it yourself for a parent "select all" whose
      * children are partly checked, and clear it on the next toggle. Takes visual
      * precedence over `checked`; the native input reports `aria-checked="mixed"`.
+     * A click the host does not answer still toggles `checked` underneath, and the
+     * dash and the mixed state both stay until the binding turns `false`.
      *
      * @default false
      */

package/types/ngwr-config.d.ts

@@ -64,6 +64,18 @@ interface WrControlDefaults {
 interface WrConfig {
     readonly button?: Pick<WrControlDefaults, 'size'>;
     readonly checkbox?: Pick<WrControlDefaults, 'size'>;
+    /**
+     * Defaults for `<wr-editor>`.
+     *
+     * `format` passes the test a config key has to pass: what an app STORES —
+     * HTML, markdown or the document as JSON — is decided once, by its backend,
+     * not per field. Spelled as a literal union rather than imported from
+     * `ngwr/editor`, for the reason `markdown.linkTarget` is: that entry point
+     * imports this one, and ng-packagr refuses the cycle.
+     */
+    readonly editor?: {
+        readonly format?: 'html' | 'markdown' | 'json';
+    };
     readonly input?: WrControlDefaults;
     readonly inputNumber?: WrControlDefaults;
     readonly inputOtp?: Pick<WrControlDefaults, 'size'>;