ngwr 15.0.1 → 15.2.0

package/types/ngwr-charts-core.d.ts

@@ -0,0 +1,391 @@
+import * as i0 from "@angular/core";
+import { Signal } from "@angular/core";
+/**
+ * @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
+ */
+/**
+ * The figures behind a chart, as {@link WrChartTable} renders them for assistive
+ * technology: a caption, a row of column headings, and the rows in groups.
+ *
+ * Every string arrives written: a value as the chart prints it, a heading as the
+ * chart names it. The table formats nothing and translates nothing.
+ *
+ * @internal
+ */
+interface WrChartTableData {
+  /** What the table is: the chart's accessible name, rendered as the `<caption>`. */
+  readonly caption: string;
+  /**
+   * The heading of the row headers' column: what one row is — a day, a point, an
+   * axis. Omitted or empty, that cell is an empty `<td>` rather than a `<th>` with
+   * no name. The group headers' column, when there is one, is never headed.
+   */
+  readonly corner?: string;
+  /** One heading per value column, in the order of every row's `cells`. */
+  readonly columns: readonly string[];
+  /**
+   * The rows, one `<tbody>` per group. A chart with one set of rows — x labels down,
+   * series across — passes a single group with no `header`; a scatter passes a group
+   * per series, headed by the series' name.
+   */
+  readonly groups: readonly WrChartTableGroup[];
+}
+/**
+ * One `<tbody>` of a {@link WrChartTableData}.
+ *
+ * @internal
+ */
+interface WrChartTableGroup {
+  /**
+   * Names the group, as a `<th scope="rowgroup">` in a leading column that spans the
+   * group's rows, so it heads every cell of the group. Once any group has a header the
+   * table carries that column, and a group without one leaves its cell there empty.
+   */
+  readonly header?: string;
+  /** The group's rows, in order. A group with none renders nothing. */
+  readonly rows: readonly WrChartTableRow[];
+}
+/**
+ * One row of a {@link WrChartTableGroup}.
+ *
+ * @internal
+ */
+interface WrChartTableRow {
+  /** What the row is, rendered as its `<th scope="row">`. */
+  readonly header: string;
+  /**
+   * One value per column, written the way the chart prints it. A value the series
+   * does not have — a gap in a line — is the chart's to write, as an empty string for
+   * an empty cell or as its own word.
+   */
+  readonly cells: readonly 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 marker shape, in the order the charts hand them out. Every shape has the
+ * same AREA as the circle at the same size, so no series looks heavier than
+ * another for its shape alone.
+ *
+ * @internal
+ */
+type WrChartMarkerShape = 'circle' | 'square' | 'triangle' | 'diamond' | 'cross' | 'triangle-down';
+/**
+ * How far a marker reaches from its centre, in px, before any stroke.
+ *
+ * @internal
+ */
+interface WrChartMarkerExtent {
+  /** From the centre up to the marker's top. */
+  readonly top: number;
+  /** From the centre down to the marker's bottom. */
+  readonly bottom: number;
+  /** From the centre to either side: every shape is symmetric about its vertical. */
+  readonly side: number;
+  /** From the centre to the marker's farthest point: the circle that holds it. */
+  readonly radius: number;
+}
+/**
+ * A value axis snapped to a readable step.
+ *
+ * @internal
+ */
+interface WrChartAxis {
+  /** The bottom of the axis, a whole multiple of `step`. */
+  readonly min: number;
+  /** The top of the axis, a whole multiple of `step`, above the data. */
+  readonly max: number;
+  /** The gap between two ticks: 1, 2, 2.5 or 5 times a power of ten. */
+  readonly step: number;
+  /**
+   * Every tick from the top down, the order a y axis reads, rounded to two digits past
+   * the step's leading one (at least six fraction digits), so a decimal step does not
+   * drift and a fine one is written exactly.
+   */
+  readonly ticks: readonly number[];
+}
+/**
+ * How {@link WrChartAxis} is fitted to the data.
+ *
+ * @internal
+ */
+interface WrChartAxisOptions {
+  /**
+   * Stretch the range to zero, on whichever side of it the data lies: the
+   * baseline an area fills to, or a radar's centre. @default false
+   */
+  readonly includeZero?: boolean;
+  /**
+   * Keep data off BOTH frames. By default only the top is lifted a step when the
+   * peak lands on it, which is what a chart with a baseline wants; a scale with no
+   * baseline (a scatter's x and y) lifts the bottom too. A flat range is centred:
+   * its value becomes the middle of three ticks, a round step on either side.
+   * @default false
+   */
+  readonly symmetric?: boolean;
+  /** How many gaps the axis aims for. @default 4 */
+  readonly tickCount?: number;
+}
+/**
+ * The number writers one chart shares between its axis, its labels and its
+ * tooltip, all in `LOCALE_ID` unless the chart's `valueFormat` is given.
+ *
+ * Every method reads the format signal when it is called, so a `computed` that
+ * calls one follows `valueFormat`.
+ *
+ * @internal
+ */
+interface WrChartNumbers<A extends readonly unknown[] = []> {
+  /**
+   * A value written in full, never compact: the tooltip, a legend value, an
+   * accessible name. Up to three fraction digits, and below one three significant
+   * digits rather than three fraction digits, which would write 0.0004 as `0`. Not
+   * the exact figure — 1.08345 is `1.083` — so a chart that has to write one to a
+   * known precision asks {@link exact}.
+   */
+  value(value: number, ...args: A): string;
+  /**
+   * A value printed in a tight space, such as above a bar: compact from a
+   * thousand up (`1.2K`), and below a thousand exactly as {@link value} writes it,
+   * since compact rounding would print 12.5 as `13`.
+   */
+  label(value: number, ...args: A): string;
+  /**
+   * An axis' tick labels, decided for the AXIS rather than one tick at a time:
+   * each tick compact to exactly the significant digits `step` needs, unless that
+   * makes the longest label longer than writing every tick in full.
+   */
+  ticks(values: readonly number[], step: number, ...args: A): string[];
+  /**
+   * A value written in full to at most `fractionDigits` fraction digits (0 to 20),
+   * trailing zeros dropped: a figure whose precision the chart knows — its axis step,
+   * a price's tick size — where {@link value} would round it to three. Through
+   * `valueFormat` when one is set, which is given `args` as every method gives them.
+   */
+  exact(value: number, fractionDigits: number, ...args: A): string;
+}
+/**
+ * A value axis for data running from `min` to `max`, SNAPPED to a readable step —
+ * and the snapping is the point.
+ *
+ * The line chart's axis used to be "the data's max plus 10%, divided into four",
+ * which lands on a round number almost never: seven integers between 3 and 35 gave
+ * an axis reading 38.2 / 28.7 / 19.1 / 9.6 / 0. A chart's axis is the one part of it
+ * a reader is supposed to do arithmetic against.
+ *
+ * So the step is rounded UP to the nearest 1, 2, 2.5 or 5 times a power of ten —
+ * the conventional nice-number ladder — and the bounds are then snapped outward to
+ * whole multiples of it. The same 3..35 reads 0 / 10 / 20 / 30 / 40. Snapping
+ * outward replaces the old 10% padding, and where the peak still lands exactly on
+ * the top it is lifted a step, since a line that ends on the frame reads as clipped.
+ * `symmetric` does the same at the bottom.
+ *
+ * A flat range has no span to divide, so it is given its own magnitude as one (or 1,
+ * at zero). With `symmetric` it is centred instead: the value is the middle of three
+ * ticks, a round step on either side, whatever `tickCount` asks for. Non-finite
+ * bounds, the `Math.min()` / `Math.max()` of no data, give the empty frame from 0 to
+ * 1. Bounds handed in the wrong order are swapped.
+ *
+ * The line chart's own rule, which floors its axis at zero and never lifts it to
+ * zero from below, is `chartAxis(Math.min(0, min), max)`: an all-negative series
+ * keeps an axis that ends just above its peak. `includeZero` is the other reading,
+ * zero inside the range on either side, which an area needs for its baseline.
+ *
+ * @internal
+ */
+export declare function chartAxis(min: number, max: number, options?: WrChartAxisOptions): WrChartAxis;
+/**
+ * The figures a chart draws, as a table that only assistive technology reaches.
+ *
+ * A chart's drawing is one named `role="img"`, and `img` makes everything inside it
+ * presentational: the name is announced and the numbers are nowhere a screen reader
+ * can walk. This renders them as a real `<table>` — a caption, column headers, row
+ * headers, and a `<tbody>` per group headed by a `<th scope="rowgroup">` down its rows
+ * — so a reader can move cell by cell and hear each value with its row and column.
+ *
+ * **Beside the image, never inside it.** Inside, `img` would hide it with the rest of
+ * the drawing. A chart renders `<wr-chart-table>` as a sibling of the element that
+ * carries `role="img"`, and only while its `dataTable` input asks for it. **The chart's
+ * host has to be positioned** (`position: relative`): the table is out of flow, and
+ * against a static host it resolves to an ancestor outside the chart and keeps its place
+ * in an unpositioned scroller's content, which grew one page by 1600px of blank scroll.
+ *
+ * **Hidden by clipping, not by `display` or `hidden`**, which would take it out of the
+ * accessibility tree as well: the host is clipped to nothing and taken out of flow, so
+ * it costs the chart no layout and still reads in full. The table inside keeps its own
+ * layout, because a `<table>` will not shrink to a clip box of its own — it grows to
+ * fit its cells whatever its width says. Nothing in it is focusable, so no tab stop
+ * lands on something that cannot be seen.
+ *
+ * No ids: the headers are tied to their cells by `scope`, which needs none, and an id
+ * minted on the server would not match the client's.
+ *
+ * @example
+ * ```html
+ * <div class="wr-line-chart__plot" role="img" [attr.aria-label]="label()">…</div>
+ * @if (dataTable()) {
+ *   <wr-chart-table [data]="table()" />
+ * }
+ * ```
+ *
+ * @internal
+ */
+export declare class WrChartTable {
+  /** The caption, the column headings and the rows, every string already written. */
+  readonly data: import("@angular/core").InputSignal<WrChartTableData>;
+  /** Whether any group is headed, which gives every row a leading group column. */
+  protected readonly hasGroupHeaders: import("@angular/core").Signal<boolean>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<WrChartTable, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<WrChartTable, "wr-chart-table", never, {
+    "data": {
+      "alias": "data";
+      "required": true;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/**
+ * A marker shape per series, so points are told apart by SHAPE and not only by
+ * hue — the dash list's job, for a chart that draws points rather than lines.
+ *
+ * The circle comes first for the reason the solid dash does: a single-series chart
+ * has nothing to tell apart. The order then alternates corners and points, so two
+ * neighbouring series never differ by a rotation alone (a square beside a diamond
+ * is the pair a small marker blurs into one).
+ *
+ * @internal
+ */
+export declare const CHART_MARKERS: readonly WrChartMarkerShape[];
+/**
+ * The marker shape for the series at `index`, wrapping past the end.
+ *
+ * @internal
+ */
+export declare function chartMarker(index: number): WrChartMarkerShape;
+/**
+ * The SVG path `d` of a marker centred on the origin, as large as a circle of
+ * radius `r` — every shape has that circle's area, so a triangle reaches past it
+ * and a square stays inside it, and the eye weighs them the same.
+ *
+ * Drawn about the origin so a chart can place it with a `transform`, or inside a
+ * nested `<svg x y overflow="visible">`, and size it in pixels whatever the plot's
+ * own scale. A non-finite or negative `r` draws nothing rather than a path of
+ * `NaN`.
+ *
+ * @internal
+ */
+export declare function chartMarkerPath(shape: WrChartMarkerShape, r: number): string;
+/**
+ * How far the marker {@link chartMarkerPath} draws at `r` reaches from its centre,
+ * in px, before any stroke: up, down, to either side, and to its farthest corner.
+ *
+ * Every shape has the circle's AREA, so `r` is not how far a marker reaches: a
+ * triangle's point stands 1.56 r above its centroid, a diamond's tips 1.25 r out
+ * and a cross's corners 1.24 r, while a square's sides sit 0.89 r in. A box, a hit
+ * area or a margin sized by `r` alone cuts the tips off. A non-finite or negative
+ * `r` reaches nowhere, as it draws nothing.
+ *
+ * @internal
+ */
+export declare function chartMarkerExtent(shape: WrChartMarkerShape, r: number): WrChartMarkerExtent;
+/**
+ * The number writers of one chart: its axis ticks, the labels it prints in tight
+ * spaces, and the figures of its tooltip and its accessible names — every one
+ * through the chart's `valueFormat` when it has one, else through `Intl` in
+ * `locale`.
+ *
+ * Seven charts kept their own copy of the `Intl` half until 15.1, each with the
+ * same two formatters and the same `formatValue`, and the line chart a second,
+ * axis-wide copy for its ticks. The rules are theirs, unchanged:
+ *
+ * - `value` is never compact, and is `Intl`'s default otherwise: up to three
+ *   fraction digits, and below one three SIGNIFICANT digits, since three fraction
+ *   digits write a reading of 0.0004 as `0`. It is not the exact figure: 1.08345
+ *   is `1.083`, and an axis stepping by 0.00025 is finer than it. A chart that has
+ *   to write a figure to a known precision asks `exact`.
+ * - `label` is compact from a thousand up, where a bar is too narrow for
+ *   `1,234,567`, and below a thousand it is `value`: compact rounding would print
+ *   12.5 as `13`, and there is nothing to abbreviate.
+ * - `ticks` is decided for the AXIS. Compact, through `Intl` (`1.2K`, `3.4M`,
+ *   `4 Mio.`, `5 тыс.`), with each tick to exactly the significant digits the step
+ *   needs — a fixed count printed 1250 beside 1000 as `1.3k` and `1k` on an axis
+ *   stepping by 250. And when abbreviating would make the labels LONGER (a fine
+ *   step on large numbers, where `-1.025K` is wider than `-1,025`) the whole axis
+ *   is written in full instead, so no axis mixes `-1K` with `-1,025`. Written in
+ *   full, a tick has as many fraction digits as the step's last digit needs, however
+ *   fine: they stopped at six, so an axis stepping by 2.5e-7 printed `0.000013` twice.
+ * - `exact` writes a figure to a precision the chart decides — the step of its axis,
+ *   a price's tick size — never compact, through `valueFormat` when there is one.
+ *
+ * `valueFormat` takes whatever extra arguments the chart passes it, so a chart can
+ * tell its formatter which axis a number is for while a `(value) => string`
+ * written for another chart still fits. Call in an injection context: `locale`
+ * defaults to `LOCALE_ID`.
+ *
+ * @internal
+ */
+export declare function useChartNumbers<A extends readonly unknown[] = []>(valueFormat: Signal<((value: number, ...args: A) => string) | null | undefined>, locale?: string): WrChartNumbers<A>;
+/**
+ * @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
+ */
+/**
+ * Default series colours, in order: what a series, a slice or a segment with no
+ * `color` of its own takes.
+ *
+ * Four intents and the neutral role, and `info` is deliberately absent: it is the
+ * same blue as `primary` to every reader (1.061:1 apart in light, 1.004:1 in
+ * dark, and the same hue), so two adjacent series would be one series with a
+ * seam. The neutral closes the list because it is the one tone here that no
+ * intent is near — it used to be the `medium` intent, which v15 removed, and the
+ * role resolves to the same step of the gray ramp.
+ *
+ * The four that sit within 1.061:1 of each other are told apart by hue alone,
+ * which is why a chart that draws lines pairs each with a dash
+ * (`CHART_DASHES`) and one that draws points with a shape (`CHART_MARKERS`).
+ *
+ * The line chart, the donut chart and the meter group each kept an identical
+ * copy of this list until 15.1.
+ *
+ * @internal
+ */
+export declare const CHART_PALETTE: readonly string[];
+/**
+ * The palette colour for the series at `index`, wrapping past the end.
+ *
+ * @internal
+ */
+export declare function chartColor(index: number): string;
+/**
+ * A dash pattern per series, so lines are told apart by SHAPE and not only by hue.
+ *
+ * The default palette's colours sit within about 1.06:1 of each other in relative
+ * luminance, which means a reader with red-green colour blindness sees several of
+ * these strokes as one grey. A legend that pairs a coloured square with a name
+ * does not rescue it: matching the square to the line is exactly the step that
+ * needs hue. Distinguishing series by dash is the standard remedy and the only one
+ * that survives greyscale, printing and a monochrome display.
+ *
+ * The FIRST entry is solid on purpose. A single-series chart is the common case
+ * and there is nothing to tell apart in it; the patterns only appear once a second
+ * series does. Each value is an SVG `stroke-dasharray`, `''` meaning none.
+ *
+ * @internal
+ */
+export declare const CHART_DASHES: readonly string[];
+/**
+ * The dash pattern for the series at `index`, wrapping past the end.
+ *
+ * @internal
+ */
+export declare function chartDash(index: number): string;
+export type { WrChartAxis, WrChartAxisOptions, WrChartMarkerExtent, WrChartMarkerShape, WrChartNumbers, WrChartTableData, WrChartTableGroup, WrChartTableRow };

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

@@ -1,4 +1,5 @@
 import { BaseHarnessFilters, ComponentHarness, HarnessPredicate } from "@angular/cdk/testing";
+import { WrChartLegendHarness } from "ngwr/charts/chart-legend/testing";
 /** Narrows which `<wr-donut-chart>` a harness query matches. */
 interface WrDonutChartHarnessFilters extends BaseHarnessFilters {
   /** Match the chart's accessible name. */
@@ -27,7 +28,9 @@ interface WrDonutChartLegendEntry {
  *
  * {@link getSliceCount} is therefore the one thing the ring answers: how many
  * wedges were drawn. Compare it with the legend's length to catch a slice that was
- * filtered out of one and not the other.
+ * filtered out of one and not the other — apart from a slice hidden through
+ * `hiddenSegments`, which keeps its legend row and draws no wedge by design;
+ * {@link getLegendHarness} says which rows those are.
  *
  * @example
  * ```ts
@@ -49,15 +52,35 @@ export declare class WrDonutChartHarness extends ComponentHarness {
   static with(options?: WrDonutChartHarnessFilters): HarnessPredicate<WrDonutChartHarness>;
   /** The name the ring announces — the whole chart's, since the slices announce nothing. */
   getAccessibleName(): Promise<string | null>;
-  /** How many wedges were drawn. */
+  /**
+   * How many wedges were drawn. A hidden slice draws none. The invisible hover target a
+   * sliver gets over the ring (`.wr-donut-chart__hit`) is not a wedge and is not counted.
+   */
   getSliceCount(): Promise<number>;
+  /**
+   * Whether the chart is a pie (`pie`), read off its `wr-donut-chart--pie` modifier.
+   * Not whether the slices reach the centre — a `thickness` of 0 does that too, and keeps
+   * the centre text — since a path's `d` is not read, for the reason given in the class
+   * note. A pie renders no centre text: {@link getCenterValue} and {@link getCenterLabel}
+   * answer `null` for it whatever was bound.
+   */
+  isPie(): Promise<boolean>;
   /** Whether the legend is rendered (`showLegend`, and at least one slice). */
   hasLegend(): Promise<boolean>;
-  /** The legend rows in order — the only textual form the data has. */
+  /**
+   * The legend as a {@link WrChartLegendHarness}: each row's key and its hidden state
+   * and, with `toggleableLegend`, the toggles that show and hide a slice. Not the same
+   * thing as {@link getLegend}, which reads the rows' text and stays as it was.
+   *
+   * Throws when the chart draws no legend (`showLegend` off, or no segments) rather
+   * than answering with an empty one: {@link hasLegend} is the question for that.
+   */
+  getLegendHarness(): Promise<WrChartLegendHarness>;
+  /** The legend rows in order — the only textual form the data has. Hidden slices included. */
   getLegend(): Promise<WrDonutChartLegendEntry[]>;
-  /** The big number in the middle, or `null` when the chart has none. */
+  /** The big number in the middle, or `null` when the chart has none — a pie never has. */
   getCenterValue(): Promise<string | null>;
-  /** The caption under the centre value, or `null`. */
+  /** The caption under the centre value, or `null` — a pie never has one. */
   getCenterLabel(): Promise<string | null>;
   /**
    * The chart's outer size in pixels, read off the `style` ATTRIBUTE.

package/types/ngwr-charts-donut-chart.d.ts

@@ -1,12 +1,20 @@
 import * as i0 from "@angular/core";
+import { WrChartLegendItem } from "ngwr/charts/chart-legend";
+/** One slice of a `<wr-donut-chart>`: a name, a value, and optionally its own colour. */
 interface WrDonutSegment {
+  /** The slice's name, in the legend and the tooltip. */
   readonly label: string;
+  /**
+   * The slice's size, as its share of the segments shown. A negative value, or one that is
+   * not a finite number, draws no slice and takes no share; the legend keeps its row with
+   * the segment's own figure — none for a value that is not a number.
+   */
   readonly value: number;
+  /** Any CSS colour, `var(--wr-…)` included. Left out, the slice takes the next palette colour. */
   readonly color?: string;
 }
 /**
- * Donut chart. Set `thickness` to 0 for a solid pie. Optional center
- * text via inputs.
+ * Donut chart, and with `pie` a pie chart. Optional center text via inputs.
  *
  * @example
  * ```html
@@ -14,8 +22,13 @@ interface WrDonutSegment {
  *   { label: 'Used', value: 60 },
  *   { label: 'Free', value: 40 }
  * ]" centerLabel="Disk" centerValue="60%" />
+ *
+ * <wr-donut-chart [segments]="segments" pie />
  * ```
  *
+ * The legend is a `ul[wr-chart-legend]` (`ngwr/charts/chart-legend`), and with
+ * `toggleableLegend` its rows show and hide their slices through `hiddenSegments`.
+ *
  * @see https://ngwr.dev/charts/donut-chart
  */
 export declare class WrDonutChart {
@@ -27,24 +40,70 @@ export declare class WrDonutChart {
   /**
    * Accessible name of the drawing. The arcs carry no text and the legend is optional, so
    * with `showLegend: false` this and the centre text are the whole of what a screen reader
-   * gets. Falls back to `donutChart.label`.
+   * gets. Falls back to `donutChart.label`, or to `donutChart.pieLabel` with `pie`.
    */
   readonly ariaLabel: import("@angular/core").InputSignal<string | null>;
+  private readonly donutLabel;
+  private readonly pieLabel;
   protected readonly resolvedAriaLabel: import("@angular/core").Signal<string>;
   /** Diameter in CSS pixels. @default 200 */
   readonly size: import("@angular/core").InputSignalWithTransform<number, unknown>;
-  /** Inner-ring thickness as a percent of radius (0–100). `0` = solid pie. @default 30 */
+  /**
+   * Inner-ring thickness as a percent of radius (0–100). `0` fills to the centre, and
+   * keeps the centre text; `pie` ignores it. @default 30
+   */
   readonly thickness: import("@angular/core").InputSignalWithTransform<number, unknown>;
+  /**
+   * Draw a pie chart: every slice fills to the centre, whatever `thickness` says, and
+   * the host takes the `wr-donut-chart--pie` modifier. A pie has no hole to print in, so
+   * `centerValue` and `centerLabel` are not rendered. Everything else is the donut's: the
+   * slices run clockwise from twelve o'clock, with the same gap between them, the legend
+   * and its toggle, and the tooltip — which in a pie also opens from a wider, invisible
+   * target over a slice too thin to point at (see `tooltip`). The drawing's name falls
+   * back to `donutChart.pieLabel`. @default false
+   */
+  readonly pie: import("@angular/core").InputSignalWithTransform<boolean, any>;
   /** Show the legend under the chart. @default true */
   readonly showLegend: import("@angular/core").InputSignalWithTransform<boolean, any>;
-  /** Bold value text in the center. */
+  /**
+   * Make each legend row a toggle button that shows and hides its slice, through
+   * `hiddenSegments`. A row is a `<button aria-pressed>`, pressed while its slice is
+   * shown, so the legend becomes one tab stop per slice. @default false
+   */
+  readonly toggleableLegend: import("@angular/core").InputSignalWithTransform<boolean, any>;
+  /**
+   * The positions in `segments` of the slices that are hidden. Positions rather than
+   * labels, since two slices may share a label. A toggleable legend writes it, and a
+   * host may bind it with or without one: `[(hiddenSegments)]`.
+   *
+   * A hidden slice is left out of the ring, and the slices still shown RE-NORMALISE:
+   * they share the whole ring between them, each at its share of their own total. A
+   * donut reads as the parts of the whole it draws, so leaving the hidden slice's arc
+   * as a gap would show a whole that no longer adds up, and turning a slice off is how
+   * a reader asks "of the rest, how much is each?". The tooltip cannot open on a slice
+   * that is not drawn. The legend keeps the hidden slice'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. The
+   * centre text is printed as given, so a host that writes a total there works it out
+   * from this list. A position past the end of `segments` is kept and ignored.
+   */
+  readonly hiddenSegments: import("@angular/core").ModelSignal<readonly number[]>;
+  /** Bold value text in the center. Not rendered with `pie`, which has no hole to hold it. */
   readonly centerValue: import("@angular/core").InputSignal<string>;
-  /** Smaller label under the value. */
+  /** Smaller label under the value. Not rendered with `pie`, which has no hole to hold it. */
   readonly centerLabel: import("@angular/core").InputSignal<string>;
+  /** Whether the centre text renders: some is given, and there is a hole to print it in. */
+  protected readonly showCenter: import("@angular/core").Signal<boolean>;
   /**
    * Show a tooltip with the slice's label and value on hover. Pointer only — the
    * legend prints the same numbers, and with `showLegend` off `ariaLabel` is where
-   * to say them. @default true
+   * to say them. With `pie`, a slice too thin to land a pointer on, a sliver of a few
+   * degrees, is hovered over a wider strip than it draws, through an invisible
+   * `.wr-donut-chart__hit` over the pie: widened toward 12px of outer arc (15° on a chart
+   * under about 92px) out of what the wider slices beside it can spare, each of which keeps
+   * that much of its own. A sliver whose neighbours are slivers too, or have little to
+   * spare, gets a narrower target or none, and is read in the legend. The ring draws no
+   * such target. @default true
    */
   readonly tooltip: import("@angular/core").InputSignalWithTransform<boolean, any>;
   /**
@@ -52,14 +111,13 @@ export declare class WrDonutChart {
    * in `LOCALE_ID`. The centre text is printed as given.
    */
   readonly valueFormat: import("@angular/core").InputSignal<((value: number) => string) | null>;
-  private readonly locale;
+  /** Each value as the legend and the tooltip print it: exact, 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 hidden;
   private readonly svg;
   private readonly outerR;
   protected readonly innerR: import("@angular/core").Signal<number>;
+  /** The sum the ring is divided by: the slices still shown (see `hiddenSegments`). */
   protected readonly total: import("@angular/core").Signal<number>;
   /**
    * Resolved slices ready for the template — each carries its arc path.
@@ -74,10 +132,47 @@ export declare class WrDonutChart {
     value: number;
     text: string;
     color: string;
+    hidden: boolean;
     path: string;
     percent: number;
+    startAngle: number;
+    endAngle: number;
     midAngle: number;
   }[]>;
+  /**
+   * In a pie, a wider hover target for every slice too thin to land a pointer on: an
+   * invisible wedge over the slice, drawn above the pie, widened toward `HIT_PX` of outer
+   * arc (`MAX_HIT_ANGLE` at most, which binds below about 92px) out of the wider slices
+   * beside it.
+   *
+   * A wider slice gives away only what it can spare: it keeps `HIT_PX` of outer arc of its
+   * own (the same `MAX_HIT_ANGLE` cap), however many slivers reach into it, so a slice
+   * that was easy to point at stays easy, and its middle, where its own chip points, is
+   * never covered. Two slivers reaching into one slice from either side split what it
+   * spares. A sliver asks half its shortfall of each wider neighbour, or all of it of the
+   * only one; what one side cannot give, the other gives if it can. Between two slivers
+   * side by side the boundary stays their shared edge, so of a run of slivers only the two
+   * at its ends grow, and the legend is where the rest are read — as it is for a sliver
+   * whose neighbours have little to spare, which gets the narrower target they leave it.
+   * A slice that draws nothing — a zero, or a hidden slice — has nothing to point at and
+   * gets no target, and nor does one with no wider neighbour.
+   *
+   * Pie only, and only while the tooltip is on, which is all it is for: the ring draws
+   * exactly what it drew before `pie` existed. The wedge is filled with nothing and
+   * hit-tested through `pointer-events="fill"`, which reads its interior whatever its
+   * paint and never its unpainted stroke, so its edges are the ones computed here; it
+   * paints in no theme and in no forced-colors palette.
+   */
+  protected readonly hits: import("@angular/core").Signal<{
+    index: number;
+    path: string;
+  }[]>;
+  /**
+   * The legend's rows: every slice, hidden ones included, each with its own figure — a
+   * negative one included, which draws no slice — and no value at all for a segment whose
+   * value is not a number.
+   */
+  protected readonly legendItems: import("@angular/core").Signal<readonly WrChartLegendItem[]>;
   /**
    * One tooltip for the whole chart, pointing at the hovered slice: at the middle of
    * its OUTER arc, on the side that part of the ring faces — above for a slice whose
@@ -116,11 +211,26 @@ export declare class WrDonutChart {
       "required": false;
       "isSignal": true;
     };
+    "pie": {
+      "alias": "pie";
+      "required": false;
+      "isSignal": true;
+    };
     "showLegend": {
       "alias": "showLegend";
       "required": false;
       "isSignal": true;
     };
+    "toggleableLegend": {
+      "alias": "toggleableLegend";
+      "required": false;
+      "isSignal": true;
+    };
+    "hiddenSegments": {
+      "alias": "hiddenSegments";
+      "required": false;
+      "isSignal": true;
+    };
     "centerValue": {
       "alias": "centerValue";
       "required": false;
@@ -141,6 +251,8 @@ export declare class WrDonutChart {
       "required": false;
       "isSignal": true;
     };
-  }, {}, never, never, true, never>;
+  }, {
+    "hiddenSegments": "hiddenSegmentsChange";
+  }, never, never, true, never>;
 }
 export type { WrDonutSegment };