ngwr 14.7.0 → 14.9.0

package/types/ngwr-markdown.d.ts

@@ -475,7 +475,11 @@ declare function parseMarkdown(source: string, options?: WrMarkdownParseOptions)
  *
  * Whitespace and control characters are stripped before the scheme is read,
  * because `java\nscript:` and `java script:` are the same URL to a browser and
- * different strings to a naive check.
+ * different strings to a naive check. So are character references:
+ * `javascript:` has no scheme to this check, but a CommonMark renderer
+ * decodes it in a destination, so any markdown the URL is written into — an
+ * editor's output, say — hands a browser `javascript:`. The scheme is read from
+ * the decoded form; what comes back is still the URL as written.
  */
 declare function safeMarkdownUrl(raw: string, kind: 'link' | 'image'): string | null;
 /** Inline markdown to nodes. */
@@ -483,6 +487,61 @@ declare function parseInlines(source: string, options?: WrMarkdownParseOptions):
 /** Text content of an inline tree — for `alt` and for heading slugs. */
 declare function plainText(inlines: readonly WrMarkdownInline[]): string;
 
+/**
+ * @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
+ */
+
+/**
+ * A block tree back to markdown — the inverse of {@link parseMarkdown}.
+ *
+ * **Written against this library's parser, not against CommonMark.** The two
+ * disagree in places (no setext headings, no indented code, no entities, a
+ * simplified reading of emphasis), and a serializer that escapes for the wrong
+ * dialect writes text that comes back as something else. So every escape here is
+ * derived from a question `parseMarkdown` actually asks — several of them by
+ * calling the parser's own predicates — and the spec holds the pair to one
+ * property: `parseMarkdown(serializeMarkdown(tree))` returns `tree`.
+ *
+ * **What markdown cannot say is normalised, never guessed at.** The output is the
+ * nearest document this dialect can express, and reading it back gives a tree
+ * that serializes to the same string. The losses, all of them structural:
+ *
+ * - Whitespace at the edges of a paragraph, heading or cell is dropped, and so is
+ *   whitespace just inside `**` / `*` / `~~` — a delimiter next to a space is not
+ *   a delimiter. A soft line break inside a text node becomes a space, and a hard
+ *   break at the very end of a block (a trailing `\` stays literal) is dropped;
+ *   inside a heading or a table cell every hard break becomes a space.
+ * - An empty paragraph, an empty list and a table with no header cell vanish.
+ * - Two adjacent lists of the same kind merge on the way back — there is no
+ *   raw-HTML comment to put between them. A single-item list with one block
+ *   cannot be loose, and a loose list nested in a tight one loosens it. Nesting
+ *   deeper than the parser's twelve levels reads back as text.
+ * - Inline marks are rewritten in one canonical nesting — link outside strong
+ *   outside strikethrough outside emphasis — which is also how a mark SET, the
+ *   shape an editor holds, becomes a tree. An image carries no emphasis (none of
+ *   it paints on an image); where an emphasis run touches a strong one and
+ *   neither can switch to `_`, the emphasis is dropped rather than written as
+ *   markup that reads back as literal asterisks.
+ * - A link or image whose URL `safeMarkdownUrl` refuses is written as its text,
+ *   exactly as the renderer would show it. A destination is percent-encoded
+ *   where this parser cannot carry a character (`<`, `>`, an unbalanced
+ *   parenthesis, a `\` it would read as an escape — and `[`, `]`, a backtick for
+ *   an image inside a link label), loses a tab or line break the way a browser's
+ *   URL parser does, a title that cannot be delimited is dropped, and a link
+ *   whose label is too long for the parser's label cap is written as plain text.
+ * - A fence's info string keeps its first word, lowercased, and `closed` is not
+ *   written: a serialized fence is always closed. A tab that indents a line reads
+ *   back as four spaces, as the parser expands it. Heading ids are the parser's,
+ *   recomputed on the way back.
+ *
+ * @param blocks a block tree, typically from {@link parseMarkdown} or an editor
+ * @returns markdown, with no trailing newline; `''` for an empty tree
+ */
+declare function serializeMarkdown(blocks: readonly WrMarkdownBlock[]): string;
+
 /**
  * @license
  *
@@ -541,5 +600,5 @@ declare function provideWrMarkdownHighlighter(highlighter: WrMarkdownHighlighter
  */
 declare const WR_MARKDOWN_HIGHLIGHTER: InjectionToken<WrMarkdownHighlighter | null>;
 
-export { WR_MARKDOWN_HIGHLIGHTER, WrMarkdown, WrMarkdownHighlight, parseInlines, parseMarkdown, plainText, provideWrMarkdownHighlighter, safeMarkdownUrl };
+export { WR_MARKDOWN_HIGHLIGHTER, WrMarkdown, WrMarkdownHighlight, parseInlines, parseMarkdown, plainText, provideWrMarkdownHighlighter, safeMarkdownUrl, serializeMarkdown };
 export type { WrHighlightLine, WrHighlightSpan, WrMarkdownAlign, WrMarkdownBlock, WrMarkdownCell, WrMarkdownHighlighter, WrMarkdownInline, WrMarkdownListItem, WrMarkdownParseOptions };

package/types/ngwr-meter-group-testing.d.ts

@@ -33,8 +33,9 @@ interface WrMeterGroupSlice {
  * Test harness for `<wr-meter-group>` — one bar divided into labelled bands.
  *
  * **The bar is a single `progressbar`, and its value is the TOTAL.** The bands
- * themselves announce nothing: they carry a `title` for a mouse and their share as an
- * inline width, and the legend is where their labels and values are readable. So a
+ * themselves announce nothing: they carry a hover tooltip (or, with `tooltip` off, a
+ * `title`) for a mouse and their share as an inline width, and the legend is where
+ * their labels and values are readable. So a
  * spec that wants "how much of each" reads {@link getSlices} for the shares or
  * {@link getLegendLabels} / {@link getLegendValues} for what is printed, and one that
  * wants "how full" reads {@link getValue}.

package/types/ngwr-meter-group.d.ts

@@ -1,3 +1,4 @@
+import * as ngwr_popover from 'ngwr/popover';
 import * as _angular_core from '@angular/core';
 
 /**
@@ -45,6 +46,13 @@ declare class WrMeterGroup {
     readonly showLegend: _angular_core.InputSignalWithTransform<boolean, any>;
     /** Show each segment's value in the legend, next to its label. @default true */
     readonly showValues: _angular_core.InputSignalWithTransform<boolean, any>;
+    /**
+     * Show a tooltip with the segment's label and value on hover. It replaces the
+     * band's `title`, which 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 sliceEls;
     /**
      * A segment's contribution, floored at `0` and with anything non-finite read
      * as `0`. One `NaN` used to poison the whole bar: the sum is `NaN` as soon as
@@ -67,8 +75,13 @@ declare class WrMeterGroup {
         color: string;
         percent: number;
     }[]>;
+    /**
+     * One tooltip for the whole bar, pointing at the hovered band, with the value as
+     * the legend prints it.
+     */
+    protected readonly tip: ngwr_popover.WrChartTooltip;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrMeterGroup, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrMeterGroup, "wr-meter-group", never, { "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "segments": { "alias": "segments"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "showLegend": { "alias": "showLegend"; "required": false; "isSignal": true; }; "showValues": { "alias": "showValues"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrMeterGroup, "wr-meter-group", never, { "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "segments": { "alias": "segments"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "showLegend": { "alias": "showLegend"; "required": false; "isSignal": true; }; "showValues": { "alias": "showValues"; "required": false; "isSignal": true; }; "tooltip": { "alias": "tooltip"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 export { WrMeterGroup };

package/types/ngwr-page-header.d.ts

@@ -6,6 +6,14 @@ import * as _angular_core from '@angular/core';
  * side), `[wrPageHeaderExtra]` (bottom row of tags / metadata). Title +
  * subtitle come from inputs.
  *
+ * A bare `<div>` wrapper in the actions slot, one with no `class` and no
+ * `style`, is laid out as a wrapping row with the actions region's own gap, so
+ * the buttons inside it are spaced exactly like buttons projected one by one.
+ * The gap follows `--wr-density-gap`. Give the wrapper a class or a style and
+ * its layout is yours: the header sets nothing on it. The extra row spaces its
+ * own children and leaves a wrapper alone, since that is where metadata prose
+ * goes, so project tags through an `<ng-container>` as below.
+ *
  * @example
  * ```html
  * <wr-page-header title="Settings" subtitle="Manage your workspace">
@@ -14,10 +22,10 @@ import * as _angular_core from '@angular/core';
  *     <button wr-btn>Invite</button>
  *     <button wr-btn color="primary">Save</button>
  *   </div>
- *   <div wrPageHeaderExtra>
+ *   <ng-container wrPageHeaderExtra>
  *     <wr-tag>v2.4</wr-tag>
  *     <wr-tag color="success">Stable</wr-tag>
- *   </div>
+ *   </ng-container>
  * </wr-page-header>
  * ```
  *

package/types/ngwr-popover.d.ts

@@ -1,7 +1,79 @@
 import * as _angular_core from '@angular/core';
-import { TemplateRef } from '@angular/core';
+import { Signal, TemplateRef } from '@angular/core';
 import { BooleanInput } from '@angular/cdk/coercion';
 
+/**
+ * @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 a chart's hover tooltip says about one section.
+ *
+ * @internal
+ */
+interface WrChartTooltipDatum {
+    /** The series or category name. Omitted where `value` is already a whole sentence. */
+    readonly label?: string;
+    /** The value, formatted the way the chart already prints it. */
+    readonly value: string;
+    /** The section's own paint, drawn as a swatch. Omitted where colour says nothing. */
+    readonly color?: string;
+}
+/**
+ * Where the tooltip for one section points, and what it says.
+ *
+ * @internal
+ */
+interface WrChartTooltipTarget {
+    readonly datum: WrChartTooltipDatum;
+    /**
+     * What the chip points at: an element, or a box in viewport pixels for a section
+     * that is not one — a zero-size point on a donut's arc. The chip sits on `side` of
+     * it with its arrow on the middle of that edge, and flips for room. Point at the
+     * section itself, not at something near it: the arrow is what tells a reader which
+     * of forty squares the chip is about. `null` while the element is not rendered —
+     * the tooltip stays closed rather than pointing at nothing.
+     */
+    readonly anchor: Element | {
+        readonly x: number;
+        readonly y: number;
+        readonly width?: number;
+        readonly height?: number;
+    } | null;
+    /**
+     * Which PHYSICAL side of the anchor the chip goes, before a flip for room — the
+     * side the section faces. A chart's geometry does not mirror with `direction`, so
+     * neither does this: `right` is the right in RTL too. `top` and `bottom` flip to
+     * each other; `left` and `right` try above and below rather than the far side,
+     * which is the chart itself. @default 'top'
+     */
+    readonly side?: 'top' | 'bottom' | 'left' | 'right';
+}
+/**
+ * The handle {@link useChartTooltip} returns to a chart.
+ *
+ * @internal
+ */
+interface WrChartTooltip {
+    /** The section the tooltip is showing, or `null`. Always `null` while the chart opted out. */
+    readonly active: Signal<number | null>;
+    /**
+     * The pointer is over section `index`. Switches straight to it when another is up —
+     * unless the pointer is between that one's anchor and its chip, on its way onto the
+     * chip, where the switch waits out the same grace as `leave`.
+     */
+    enter(index: number): void;
+    /**
+     * The pointer left the sections. Hides after a short grace period, so a pointer
+     * can cross the gap onto the tooltip — WCAG 1.4.13 (Hoverable) — and so moving
+     * between two sections through a gap does not blink it.
+     */
+    leave(event?: MouseEvent): void;
+}
+
 /**
  * @license
  *
@@ -11,6 +83,85 @@ import { BooleanInput } from '@angular/cdk/coercion';
 
 type WrPopoverPosition = 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end';
 
+/**
+ * @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
+ */
+
+/**
+ * A hover tooltip for a chart's sections, with ONE overlay per chart.
+ *
+ * **Why not `[wrPopover] mode="tooltip"` on every section.** It fits the look
+ * and not the shape. A year of `wr-calendar-heatmap` is 371 days, and a directive
+ * per day is 371 focus monitors and 371 overlays-in-waiting for a tooltip only
+ * one of them can show; and most sections are not an element a directive could
+ * point at — a donut's slice is a `<path>` whose box is most of the ring, a
+ * sparkline's point is a coordinate. So the chart says which section is under
+ * the pointer and where to point, and this owns the single overlay, the timers
+ * and the teardown. What IS shared with the directive is everything a reader
+ * sees: the `.wr-tooltip` chip, its arrow, the placements with their flip, and
+ * Escape.
+ *
+ * **The chip points AT the section it describes**, with its arrow on the anchor:
+ * above a heatmap's day, above a bar's top edge, off the outside of a donut's arc.
+ * The arrow is placed from a measurement rather than centred, because the chip is
+ * not always centred on its anchor — `withPush` slides it along the viewport edge
+ * for the first and last week of a year — and an arrow at the chip's middle would
+ * then point at a neighbour. The measurement is written to
+ * `--wr-chart-tooltip-arrow` on the chip, and the stylesheet puts the arrow there.
+ *
+ * **A chip at its section sits over the sections beside it**, and it is hoverable
+ * (below), so the way onto it can cross another section: straight up from a heatmap
+ * day runs through the day above. Switching the moment that day reported itself
+ * would move the chip away from a pointer on its way to it — WCAG 1.4.13 with extra
+ * steps. So the strip between the anchor and the chip is a bridge: another section
+ * reported from inside it waits out the same grace a leave does, a pointer still
+ * closing in on the chip starts that grace again however slowly it moves, and
+ * landing on the chip cancels the switch. Anywhere else a new section switches at
+ * once, so scanning a row of days does not lag. The cost is in the other direction: a
+ * pointer that keeps on going up a heatmap's column is moving onto the chip, so it
+ * passes over it and the days under it read out only once it comes out the far side.
+ *
+ * **Why an overlay and not a positioned child, the way `wr-line-chart` draws its
+ * own.** A child is clipped by every `overflow` between it and the page, and a
+ * chart sits inside those constantly: `wr-calendar-heatmap` IS a scroll
+ * container, and a sparkline in a `wr-table` cell sits under two more.
+ *
+ * **Pointer only, deliberately.** No section of any chart is a tab stop, and
+ * this does not make one — a year of days in the tab order would be the defect.
+ * The pane is `aria-hidden`: every value it shows is already the section's
+ * accessible name or the chart's own, and an orphan tooltip nothing describes
+ * reads as a stray line at the end of the document. It is never the only way to
+ * a value.
+ *
+ * SSR-safe: nothing here touches the DOM until a pointer event has moved a
+ * section, and the render effect that opens the overlay never runs on a server.
+ *
+ * Call from an injection context — a chart's field initialiser.
+ *
+ * @param enabled The chart's `tooltip` input. Turning it off closes an open tooltip.
+ * @param resolve What to show for section `index`, and where. It runs after
+ *   render, so it may read the DOM the section just drew; the signals it reads
+ *   are tracked, so a data change under an open tooltip re-reads it, and a
+ *   section that no longer exists (`null`) closes it. It runs again whenever the
+ *   chart may have moved under an open chip — a scroll anywhere, a viewport
+ *   resize, the chart or its anchor element changing size.
+ * @param sectionAt For a chart whose sections are chosen by POSITION rather than by
+ *   element — a sparkline picks the point nearest the pointer's x, anywhere over the
+ *   drawing — the section at a viewport point, or `null` off the drawing. The chip
+ *   points at the point from inside the drawing, so without this a pointer scrubbing
+ *   above the line lands on the chip and the chart stops hearing it: measured in
+ *   Chromium, a scrub along the top of a sparkline showed 9 of its 12 values. Asked on
+ *   every pointer event while a chip is up, wherever the pointer is over the chart or its
+ *   own chip; straight up from a point onto its chip stays on that point, so the chip is
+ *   still hoverable. Anywhere else the chip closes after the usual grace.
+ *
+ * @internal
+ */
+declare function useChartTooltip(enabled: Signal<boolean>, resolve: (index: number) => WrChartTooltipTarget | null, sectionAt?: (x: number, y: number) => number | null): WrChartTooltip;
+
 declare class WrPopover {
     /**
      * Content to render inside the panel.
@@ -150,5 +301,5 @@ declare class WrPopover {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<WrPopover, "[wrPopover]", ["wrPopover"], { "content": { "alias": "wrPopover"; "required": true; "isSignal": true; }; "mode": { "alias": "mode"; "required": false; "isSignal": true; }; "trigger": { "alias": "trigger"; "required": false; "isSignal": true; }; "position": { "alias": "position"; "required": false; "isSignal": true; }; "showDelay": { "alias": "showDelay"; "required": false; "isSignal": true; }; "hideDelay": { "alias": "hideDelay"; "required": false; "isSignal": true; }; "responsive": { "alias": "responsive"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, { "opened": "opened"; "closed": "closed"; }, never, never, true, never>;
 }
 
-export { WrPopover };
-export type { WrPopoverPosition };
+export { WrPopover, useChartTooltip };
+export type { WrChartTooltip, WrChartTooltipDatum, WrChartTooltipTarget, WrPopoverPosition };

package/types/ngwr-sidebar.d.ts

@@ -36,6 +36,13 @@ declare function isGroup(entry: WrSidebarEntry): entry is WrSidebarGroup;
  * `WrSidebarItem`s (direct links) or `WrSidebarGroup`s (expand to reveal
  * child items). Active route auto-expands its containing group.
  *
+ * The host pads its rows by `--wr-sidebar-padding` (`0.5rem`), so a hovered or
+ * active row's tint stays off the edge of whatever holds the nav, a bordered
+ * card or a `<wr-layout-sider>`, which pads nothing itself. Where the container
+ * already supplies the inset, set the hook to `0` on the sidebar, not on the
+ * container: the host declares its own default, which shadows an inherited one
+ * (`.my-panel .wr-sidebar { --wr-sidebar-padding: 0 }`, or inline).
+ *
  * @example
  * ```html
  * <wr-sidebar [entries]="[

package/types/ngwr-sparkline.d.ts

@@ -1,3 +1,4 @@
+import * as ngwr_popover from 'ngwr/popover';
 import * as _angular_core from '@angular/core';
 
 /**
@@ -36,9 +37,24 @@ declare class WrSparkline {
     readonly width: _angular_core.InputSignal<string>;
     /** CSS height. @default '2rem' */
     readonly height: _angular_core.InputSignal<string>;
+    /**
+     * Show a tooltip with the value of the point nearest the pointer, marking that
+     * point, and named by `ariaLabel` when one is given. Pointer only. @default true
+     */
+    readonly tooltip: _angular_core.InputSignalWithTransform<boolean, any>;
+    private readonly svg;
+    private readonly marker;
     private readonly vbW;
     private readonly vbH;
     private readonly padding;
+    /**
+     * The data as drawn. Non-finite values are dropped rather than scaled: every
+     * `min`/`max` comparison against a NaN is false, so it survived into the scale and
+     * `toFixed(2)` wrote the literal text `NaN` into the path `d` — invalid geometry,
+     * and the line vanishes. The tooltip reads this list too, so the value it shows is
+     * the one under the point it marks.
+     */
+    private readonly values;
     /** Mapped `{ x, y }` points for the path. */
     protected readonly points: _angular_core.Signal<readonly {
         x: number;
@@ -51,8 +67,34 @@ declare class WrSparkline {
         y: number;
     } | null>;
     protected readonly viewBox: string;
+    /**
+     * One tooltip, pointing at the hovered point: above its marker, below it when there
+     * is no room. The marker is the anchor element itself, drawn for the point the
+     * tooltip reads — it renders before this runs, since both follow `tip.active()`.
+     *
+     * The chip sits INSIDE the drawing, over the stretch of line above the marker, so the
+     * helper is also told which point any spot over the drawing reads: a pointer scrubbing
+     * along the top of a sparkline would otherwise land on the chip and stop there.
+     */
+    protected readonly tip: ngwr_popover.WrChartTooltip;
+    /**
+     * The marker's place, as percentages of the box the drawing stretches to. An
+     * element rather than a `<circle>`: the drawing stretches to any box with
+     * `preserveAspectRatio="none"`, which would squash a circle into an ellipse.
+     */
+    protected readonly markerAt: _angular_core.Signal<{
+        x: number;
+        y: number;
+    } | null>;
+    protected onPointerMove(event: MouseEvent): void;
+    /**
+     * The point nearest the pointer, along x only — the points are evenly spaced, so
+     * that is a rounding rather than a search. A box with no width (nothing laid out
+     * yet) answers nothing rather than a NaN index.
+     */
+    private indexAt;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrSparkline, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrSparkline, "wr-sparkline", never, { "data": { "alias": "data"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "strokeWidth": { "alias": "strokeWidth"; "required": false; "isSignal": true; }; "showArea": { "alias": "showArea"; "required": false; "isSignal": true; }; "showTip": { "alias": "showTip"; "required": false; "isSignal": true; }; "width": { "alias": "width"; "required": false; "isSignal": true; }; "height": { "alias": "height"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrSparkline, "wr-sparkline", never, { "data": { "alias": "data"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "strokeWidth": { "alias": "strokeWidth"; "required": false; "isSignal": true; }; "showArea": { "alias": "showArea"; "required": false; "isSignal": true; }; "showTip": { "alias": "showTip"; "required": false; "isSignal": true; }; "width": { "alias": "width"; "required": false; "isSignal": true; }; "height": { "alias": "height"; "required": false; "isSignal": true; }; "tooltip": { "alias": "tooltip"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 export { WrSparkline };

package/types/ngwr-toolbar.d.ts

@@ -4,6 +4,13 @@ import * as i0 from '@angular/core';
  * Action bar with three named zones — `[wrToolbarStart]`,
  * `[wrToolbarCenter]`, `[wrToolbarEnd]`. Use any one or all three.
  *
+ * A bare `<div>` wrapper in a zone, one with no `class` and no `style`, is laid
+ * out as a wrapping row with the zone's own gap, so the controls inside it are
+ * spaced exactly like controls projected one by one. The gap follows
+ * `--wr-density-gap`. Give the wrapper a class or a style and its layout is
+ * yours: the toolbar sets nothing on it. Put running text in a `<span>` or a
+ * `<p>`, which stay in inline flow.
+ *
  * @example
  * ```html
  * <wr-toolbar>

package/types/ngwr-typography.d.ts

@@ -39,6 +39,10 @@ declare class WrTypography {
     /**
      * Color tone. `null` (default) keeps the variant's own color — the base
      * dark for headings/body, medium for lead/caption, primary for links.
+     * Emphasis only: a tone never carries a state on its own. Six of the nine
+     * intents share one lightness, and `success` against `danger` is 1.05:1 as
+     * text, so the words have to name the state (`500 Server Error`, not a red
+     * `Request`) — or reach for `<wr-alert>`, which draws a glyph per type.
      */
     readonly tone: _angular_core.InputSignal<WrTypographyTone | null>;
     /** Horizontal alignment. */

package/types/ngwr-version.d.ts

@@ -16,7 +16,7 @@ import { InjectionToken } from '@angular/core';
  * Distinct from `Version` exported by `@angular/core`, which reports the
  * loaded Angular runtime version (e.g. `'22.0.0'`), not ngwr's.
  */
-declare const NGWR_VERSION = "14.7.0";
+declare const NGWR_VERSION = "14.9.0";
 
 /**
  * @license

package/typography/styles/_index.scss

@@ -186,21 +186,37 @@
   }
 
   // Tones
+  // color-ok: a text ROLE, not a state — body copy. Like every tone it is
+  // emphasis only, and the words carry whatever state there is.
   &--tone-dark {
     color: var(--wr-color-on-surface);
   }
+  // color-ok: a text ROLE, not a state — muted prose rather than body copy.
+  // Like every tone it is emphasis only.
   &--tone-medium {
     color: var(--wr-color-on-surface-muted);
   }
+  // color-ok: emphasis only, never the sole carrier of a state — the words
+  // carry it, as "500 Server Error" does, because `success` against `danger` is
+  // 1.05:1 as text in light.
   &--tone-primary {
     color: var(--wr-color-primary-ink);
   }
+  // color-ok: emphasis only, never the sole carrier of a state — the words
+  // carry it, as "500 Server Error" does, because `success` against `danger` is
+  // 1.05:1 as text in light.
   &--tone-success {
     color: var(--wr-color-success-ink);
   }
+  // color-ok: emphasis only, never the sole carrier of a state — the words
+  // carry it, as "500 Server Error" does, because `success` against `danger` is
+  // 1.05:1 as text in light.
   &--tone-warning {
     color: var(--wr-color-warning-ink);
   }
+  // color-ok: emphasis only, never the sole carrier of a state — the words
+  // carry it, as "500 Server Error" does, because `success` against `danger` is
+  // 1.05:1 as text in light.
   &--tone-danger {
     color: var(--wr-color-danger-ink);
   }