ngwr 15.0.1 → 15.2.0

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

@@ -1,4 +1,5 @@
 import * as i0 from "@angular/core";
+import { WrChartLegendItem } from "ngwr/charts/chart-legend";
 /**
  * @license
  *
@@ -9,7 +10,7 @@ import * as i0 from "@angular/core";
 interface WrMeterSegment {
   /** Label shown in the legend. */
   readonly label: string;
-  /** Magnitude — interpreted as a portion of the sum of all segments. */
+  /** Its share of the bar: of `max` when set, else of the sum of the segments shown. */
   readonly value: number;
   /** CSS color for the bar slice and legend swatch. Defaults to `--wr-color-primary` etc. */
   readonly color?: string;
@@ -17,7 +18,8 @@ interface WrMeterSegment {
 /**
  * Stacked-segment progress bar. Visualises a breakdown of a total —
  * disk usage, budget, vote share, etc. Each segment contributes a slice
- * proportional to its `value` relative to the sum (or the explicit `max`).
+ * proportional to its `value` relative to the sum of the segments shown (or the
+ * explicit `max`).
  *
  * @example
  * ```html
@@ -30,6 +32,9 @@ interface WrMeterSegment {
  * />
  * ```
  *
+ * The legend is a `ul[wr-chart-legend]` (`ngwr/charts/chart-legend`), and with
+ * `toggleableLegend` its rows show and hide their segments through `hiddenSegments`.
+ *
  * @see https://ngwr.dev/charts/meter-group
  */
 export declare class WrMeterGroup {
@@ -37,16 +42,41 @@ export declare class WrMeterGroup {
   readonly ariaLabel: import("@angular/core").InputSignal<string | null>;
   protected readonly resolvedAriaLabel: import("@angular/core").Signal<string>;
   /**
-   * The parts of the bar, in order. Values are summed and each segment is drawn
-   * as its share of that total, so they need not add up to anything in particular.
+   * The parts of the bar, in order. Each segment is drawn as its share of `max` when
+   * set, else of the sum of the segments shown, so they need not add up to anything in
+   * particular.
    */
   readonly segments: import("@angular/core").InputSignal<readonly WrMeterSegment[]>;
-  /** Explicit total. When `0` (default), `max = sum(values)`. @default 0 */
+  /** Explicit total, a capacity the segments fill. `0` (default) uses the sum of the segments shown. @default 0 */
   readonly max: import("@angular/core").InputSignalWithTransform<number, unknown>;
   /** Show the labelled legend under the bar. @default true */
   readonly showLegend: import("@angular/core").InputSignalWithTransform<boolean, any>;
   /** Show each segment's value in the legend, next to its label. @default true */
   readonly showValues: import("@angular/core").InputSignalWithTransform<boolean, any>;
+  /**
+   * Make each legend row a toggle button that shows and hides its segment, through
+   * `hiddenSegments`. A row is a `<button aria-pressed>`, pressed while its segment is
+   * shown, so the legend becomes one tab stop per segment. @default false
+   */
+  readonly toggleableLegend: import("@angular/core").InputSignalWithTransform<boolean, any>;
+  /**
+   * The positions in `segments` of the segments that are hidden. Positions rather than
+   * labels, since two segments may share a label. A toggleable legend writes it, and a
+   * host may bind it with or without one: `[(hiddenSegments)]`.
+   *
+   * A hidden segment is left out of the bar and out of the sum. With no `max`, the
+   * segments still shown share the whole bar between them, each at its share of their
+   * own total, as `wr-donut-chart`'s slices do: the bar is the whole of what it draws.
+   * An explicit `max` is a capacity rather than a sum, so it stays, and the hidden
+   * segment's share becomes empty track. Either way the bar announces the total of the
+   * segments shown (`aria-valuenow`, `aria-valuetext`), since that is what it draws, and
+   * the tooltip cannot open on a segment that is not drawn. The legend keeps the hidden
+   * segment's row, struck through and with its own value, so it can be shown again; the
+   * row says "hidden" to a screen reader as well, through `aria-pressed` on a toggle and
+   * a visually hidden word otherwise. A position past the end of `segments` is kept and
+   * ignored.
+   */
+  readonly hiddenSegments: import("@angular/core").ModelSignal<readonly number[]>;
   /**
    * 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
@@ -59,11 +89,8 @@ export declare class WrMeterGroup {
    * `aria-valuenow` stays a number.
    */
   readonly valueFormat: import("@angular/core").InputSignal<((value: number) => string) | null>;
-  private readonly locale;
+  /** Each value as the legend, the tooltip and the bar print it: never compact, in `LOCALE_ID` unless `valueFormat` is given. */
   private readonly numbers;
-  /** Below one, by significant digits, which keep 0.0004 from rounding to `0`. */
-  private readonly smallNumbers;
-  private formatValue;
   private readonly sliceEls;
   /**
    * A segment's contribution, floored at `0` and with anything non-finite read
@@ -72,6 +99,9 @@ export declare class WrMeterGroup {
    * asked for a width of `value * 100`%, while `aria-valuenow` announced `NaN`.
    */
   private static amount;
+  private readonly hidden;
+  /** What the segments still shown add up to (see `hiddenSegments`). */
+  private readonly shownSum;
   protected readonly resolvedMax: import("@angular/core").Signal<number>;
   /**
    * Sum of the segments, for `aria-valuenow`. `role="progressbar"` without it
@@ -88,14 +118,32 @@ export declare class WrMeterGroup {
    */
   protected readonly totalText: import("@angular/core").Signal<string>;
   protected readonly slices: import("@angular/core").Signal<{
+    index: number;
     label: string;
     text: string;
     color: string;
+    hidden: boolean;
     percent: number;
   }[]>;
+  /**
+   * The bands drawn, in order: every segment but the hidden ones. A hidden band is left
+   * out rather than drawn at zero width, since a zero band still lays its gap over the
+   * boundary and would leave a double one.
+   */
+  protected readonly bands: import("@angular/core").Signal<{
+    index: number;
+    label: string;
+    text: string;
+    color: string;
+    hidden: boolean;
+    percent: number;
+  }[]>;
+  /** The legend's rows: every segment, hidden ones included, with its value unless `showValues` is off. */
+  protected readonly legendItems: import("@angular/core").Signal<readonly WrChartLegendItem[]>;
   /**
    * One tooltip for the whole bar, pointing at the hovered band, with the value as
-   * the legend prints it.
+   * the legend prints it. Asked by the segment's own position, and the drawn bands are
+   * only the shown ones, so the band is found among them by that position.
    */
   protected readonly tip: import("ngwr/popover").WrChartTooltip;
   static ɵfac: i0.ɵɵFactoryDeclaration<WrMeterGroup, never>;
@@ -125,6 +173,16 @@ export declare class WrMeterGroup {
       "required": false;
       "isSignal": true;
     };
+    "toggleableLegend": {
+      "alias": "toggleableLegend";
+      "required": false;
+      "isSignal": true;
+    };
+    "hiddenSegments": {
+      "alias": "hiddenSegments";
+      "required": false;
+      "isSignal": true;
+    };
     "tooltip": {
       "alias": "tooltip";
       "required": false;
@@ -135,6 +193,8 @@ export declare class WrMeterGroup {
       "required": false;
       "isSignal": true;
     };
-  }, {}, never, never, true, never>;
+  }, {
+    "hiddenSegments": "hiddenSegmentsChange";
+  }, never, never, true, never>;
 }
 export type { WrMeterSegment };

package/types/ngwr-charts-radar-chart-testing.d.ts

@@ -0,0 +1,162 @@
+import { BaseHarnessFilters, ComponentHarness, HarnessPredicate } from "@angular/cdk/testing";
+import { WrChartLegendHarness } from "ngwr/charts/chart-legend/testing";
+import { WrRadarVariant } from "ngwr/charts/radar-chart";
+/** Narrows which `<wr-radar-chart>` a harness query matches. */
+interface WrRadarChartHarnessFilters extends BaseHarnessFilters {
+  /** Match the drawing's accessible name. */
+  readonly ariaLabel?: string | RegExp;
+  /** Match a chart with an axis of this name. */
+  readonly axisLabel?: string | RegExp;
+}
+/** One series' outline as {@link WrRadarChartHarness.getPolygons} reads it, in the order drawn. */
+interface WrRadarChartPolygon {
+  /** The stroke the component wrote: the series' colour. */
+  readonly color: string | null;
+  /** The outline's `stroke-dasharray`, `''` for a solid one. */
+  readonly dash: string;
+  /**
+   * Whether the outline closes through every axis. A series with a missing value is
+   * drawn open, across the gap, and is never filled. In the polar-area variant the
+   * outline is the silhouette round the wedges, which always closes, so this is always
+   * `true` there.
+   */
+  readonly closed: boolean;
+}
+/**
+ * One row of the chart's data table (`dataTable`): the axis it reads, as its row header,
+ * and one cell per series shown, in the order of the table's columns.
+ */
+interface WrRadarChartTableRow {
+  /** The row header — the axis' name. */
+  readonly header: string;
+  /** Each series' own value on that axis, written as the tooltip writes it; `''` where it is missing. */
+  readonly cells: readonly string[];
+}
+/**
+ * Test harness for `<wr-radar-chart>`.
+ *
+ * **The polygons' geometry is not read.** Where a vertex lands moves with the scale and
+ * the drawing's box, so this harness counts what was drawn and reads what is TEXT: the
+ * axis names, the ring values, the legend and the data table. Those are what a reader
+ * gets, and they are what breaks when the data wiring does. The one thing it does read off
+ * a path is whether the outline CLOSES ({@link getPolygons}): a series with a missing
+ * value is drawn open across the gap and never filled, and an outline closed across a
+ * value the series does not have is exactly the defect worth catching.
+ *
+ * **The tooltip cannot be opened from a spec.** It follows the pointer by its angle from
+ * the drawing's centre, measured off the drawing's box, which jsdom reports as 0×0 — so
+ * there is deliberately no `hoverAxis()`. The numbers it would show are in the data table
+ * (`dataTable`), which {@link getTableRows} reads, and which is where a screen reader
+ * finds them too.
+ *
+ * Labels are positioned by the stylesheet from numbers the component writes; with no
+ * layout in jsdom there is no method for where a label sits or whether it was ellipsised.
+ *
+ * @example
+ * ```ts
+ * const chart = await loader.getHarness(WrRadarChartHarness);
+ *
+ * expect(await chart.getAxisLabels()).toEqual(['Speed', 'Power', 'Range']);
+ * expect(await chart.getPolygonCount()).toBe(2);
+ * expect((await chart.getPolygons()).every(p => p.closed)).toBe(true);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+export declare class WrRadarChartHarness extends ComponentHarness {
+  static hostSelector: string;
+  /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+  static with(options?: WrRadarChartHarnessFilters): HarnessPredicate<WrRadarChartHarness>;
+  /**
+   * The drawing's accessible name — the only name it has. Read off the `<svg>`, which
+   * carries the `img` role, rather than off the surface round it: a name on the wrapper
+   * would take the axis names beside the drawing out of the accessibility tree.
+   */
+  getAccessibleName(): Promise<string | null>;
+  /**
+   * How the chart draws its series (`variant`): `'polygon'` or `'polar-area'`, read off
+   * the host's BEM modifier, which the component writes for either one.
+   *
+   * Throws when the host carries neither modifier rather than answering `'polygon'` by
+   * default: a chart that lost its variant binding would otherwise read as the default
+   * exactly when the binding is what broke.
+   */
+  getVariant(): Promise<WrRadarVariant>;
+  /** The axis names round the drawing, clockwise from twelve o'clock, as given — the full text, ellipsised or not. */
+  getAxisLabels(): Promise<string[]>;
+  /** The ring values beside the first axis, from the outer ring in. `[]` with `showGrid` off. */
+  getRingLabels(): Promise<string[]>;
+  /** Whether the web is drawn (`showGrid`): the rings and the spokes. */
+  hasGrid(): Promise<boolean>;
+  /**
+   * How many series outlines were drawn: one per series shown that has at least one
+   * value, and none at all with fewer than three axes. In the polar-area variant a
+   * series' outline is the one silhouette round its wedges, so this still counts series,
+   * not wedges.
+   *
+   * Worth comparing with the legend: both come from the same list, so a mismatch is a
+   * series filtered out of one of them. The difference by design is a series hidden
+   * through `hiddenSeries`, which keeps its legend row and draws no outline — the legend
+   * harness's `getHidden()` names those.
+   */
+  getPolygonCount(): Promise<number>;
+  /**
+   * Every outline drawn, in order: the colour and dash the component wrote on it, and
+   * whether it closes. Closed is read off the path's own closing command, which is what
+   * makes a browser close the shape. In the polar-area variant the outline is the
+   * silhouette round the series' wedges, which always closes, and a missing value is a
+   * missing wedge — which {@link getDotCount} and the data table show instead.
+   */
+  getPolygons(): Promise<WrRadarChartPolygon[]>;
+  /**
+   * How many polygons are filled (`fill`). Only a closed outline is ever filled, so with
+   * `fill` on this is the number of closed outlines in {@link getPolygons}; anything more
+   * is a fill drawn across a missing value. In the polar-area variant it is one per
+   * series drawn, each fill covering that series' wedges.
+   */
+  getAreaCount(): Promise<number>;
+  /** How many value dots were drawn across every series (`showDots`). A missing value has none. */
+  getDotCount(): Promise<number>;
+  /** Whether the legend is rendered (`showLegend`, and at least one series). */
+  hasLegend(): Promise<boolean>;
+  /**
+   * The legend, as a {@link WrChartLegendHarness}: each row's name, its key and its hidden
+   * state and, with `toggleableLegend`, the toggles that show and hide a series.
+   *
+   * Throws when the chart draws no legend (`showLegend` off, or no series) rather than
+   * answering with an empty one: {@link hasLegend} is the question for that.
+   */
+  getLegendHarness(): Promise<WrChartLegendHarness>;
+  /** Whether the hidden data table is rendered (`dataTable`). */
+  hasDataTable(): Promise<boolean>;
+  /**
+   * The data table's column headings: one per series shown, in order. Hidden series
+   * leave the table.
+   *
+   * Throws when the chart renders no table (`dataTable` off) rather than answering with
+   * no columns, which is also what a table of fully hidden series answers.
+   */
+  getTableColumns(): Promise<string[]>;
+  /**
+   * The data table's rows, one per axis: its name and each series' own value, as a screen
+   * reader walks them. A value outside a fixed `max` is drawn on the edge and tabulated as
+   * itself, and a missing one is `''`.
+   *
+   * Throws when the chart renders no table (`dataTable` off), for the reason
+   * {@link getTableColumns} gives.
+   */
+  getTableRows(): Promise<WrRadarChartTableRow[]>;
+  /**
+   * The drawing's diameter in pixels — `size` as the component wrote it — read off the
+   * `style` ATTRIBUTE of the surface.
+   *
+   * NOT `getCssValue()`, which is `getComputedStyle()`: a computed read answers from the
+   * LAID-OUT box, which agrees with the inline value in jsdom and disagrees in a browser,
+   * where the drawing shrinks in a narrow container and sub-pixel rounding moves the rest.
+   * A harness that answers differently in the two places it runs is worse than one that
+   * refuses.
+   */
+  getSize(): Promise<number>;
+  private assertDataTable;
+}
+export type { WrRadarChartHarnessFilters, WrRadarChartPolygon, WrRadarChartTableRow };