@forgeroute/ui 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeroute/ui",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "peerDependencies": {
     "@angular/common": ">=22.0.0",
     "@angular/core": ">=22.0.0",

package/types/forgeroute-ui-charts.d.ts

@@ -1,4 +1,37 @@
 import * as i0 from "@angular/core";
+/**
+ * A darker shade (each channel x 0.8) of a hex (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`) or comma-separated `rgb()` / `rgba()` colour,
+ * returned as `rgb(r, g, b)` or `rgba(r, g, b, a)`. Returns `null` for anything else (named colours, `var(--x)`, `hsl()`, out-of-range
+ * channels, malformed text) because those can't be computed without a browser.
+ */
+declare function darkenColor(input: string): string | null;
+/** How the chart writes numbers: one for value labels and tooltips, one for the y axis ticks. */
+interface ValueFormatter {
+  value: (n: number) => string;
+  tick: (n: number) => string;
+}
+type BarChartValueFormat = 'number' | 'currency' | 'percent';
+/** One series of a grouped / stacked bar chart: its legend name, one value per label, and optional colours (any CSS colour). */
+interface BarChartSeries {
+  name: string;
+  values: number[];
+  color?: string;
+  hoverColor?: string;
+}
+/**
+ * Default series colours of a multi-series chart (cycled). Same values as the pie chart's palette (kept as a local copy so a bar-only
+ * app never pulls the pie chart's chart.js parts into its bundle); each has at least 3:1 contrast against white.
+ */
+declare const BAR_CHART_SERIES_PALETTE: readonly string[];
+/** A multi-series chart draws value labels only up to this many bars in total (labels x series); denser groups overlap. */
+declare const BAR_CHART_MAX_GROUPED_VALUE_LABELS = 24;
+/** A series after clean-up: trimmed or fallback name, colours resolved, exactly one number per label. */
+interface ResolvedSeries {
+  name: string;
+  data: number[];
+  color: string;
+  hover: string;
+}
 /**
  * Bar chart of one series (e.g. calls per day). Pass the category `labels` and the matching `values`.
  *
@@ -10,6 +43,54 @@ import * as i0 from "@angular/core";
  * - With an `ariaLabel` the chart is an image for assistive tech (`role="img"` + that label; without a label no role is set, as an
  *   unnamed image is an accessibility error); render the same figures as text next to it
  *   (e.g. a visually hidden list) when the exact values matter.
+ * - Per-bar colours: `colors` gives bar i the colour `colors[i]` (any CSS colour, passed through untouched). Bars without an entry
+ *   (list shorter than the bars, or a blank/whitespace entry) use `color`; extra entries are ignored. With no `colors` every bar uses
+ *   `color` exactly as before. Colours are decorative only: never rely on colour alone, the values are always available as the
+ *   value labels and tooltips (and in your own text alternative).
+ *
+ *   <ui-bar-chart [labels]="['New', 'Won', 'Lost']" [values]="[4, 2, 1]" [colors]="['#3b82f6', '#16a34a', '#dc2626']" />
+ *
+ * - Number format: `valueFormat` ('number' default | 'currency' | 'percent') writes the value labels, the tooltip and the y axis ticks.
+ *   'number' is the original behaviour (raw numbers, whole-number ticks, "<value> <unit>" tooltip); `currency`, `locale` and `decimals`
+ *   are ignored for it.
+ *
+ *   <ui-bar-chart [labels]="months" [values]="revenue" valueFormat="currency" ariaLabel="Revenue by month" />
+ *   <ui-bar-chart [labels]="months" [values]="revenue" valueFormat="currency" currency="EUR" locale="de-DE" [decimals]="0" />
+ *   <ui-bar-chart [labels]="months" [values]="rates" valueFormat="percent" />
+ *
+ *   - 'currency': `$1,234.50` (`currency` ISO 4217, default USD; `locale` default en-US). Zero is `$0.00`, negatives `-$5.00`.
+ *     Default decimals are the currency's own (2 for USD). Axis ticks are not forced to whole numbers (values may be fractional);
+ *     with no `decimals` a whole-number tick drops its cents (`$500`) and a fractional one keeps them (`$0.50`); an explicit `decimals`
+ *     is used for every tick.
+ *   - 'percent': the values are ALREADY percentages on the 0-100 scale, not fractions: 12.5 is `12.5%`, 100 is `100%`. Default is up
+ *     to 1 decimal (12 -> `12%`, 12.5 -> `12.5%`); `decimals` fixes the number of decimals (0 -> `13%`). Ticks use the same format.
+ *   - The tooltip of 'currency' / 'percent' is just the formatted figure (`$1,234.50`, `12.5%`); `unitSingular` / `unitPlural` are
+ *     ignored. With 'number' the unit text is unchanged.
+ *   - `decimals` (integer, clamped to 0-6; null or non-numeric = format default). An invalid `currency` or `locale` never throws:
+ *     it falls back to USD / en-US. NaN and Infinity read as "NaN" / "Infinity" in the tooltip and get no value label.
+ *   - `ariaLabel` is never formatted by the chart: if the description carries figures, format them in the host.
+ *
+ * - Hover: a bar with its own colour darkens it (see `darkenColor`: hex or comma-separated rgb()/rgba() get a shade 20% darker; a
+ *   named colour, `var(--x)` or other unparseable value stays unchanged on hover). Bars using the fallback `color` use `hoverColor`.
+ * - Several series (grouped or stacked): pass `series` (it takes precedence over `values`, `color`, `hoverColor` and `colors`, which are
+ *   ignored). Every series shares `labels`; bars of one label sit side by side (`stacked` = true piles them up instead).
+ *
+ *   <ui-bar-chart [labels]="months"
+ *                 [series]="[{ name: 'Income', values: income, color: '#22c55e' }, { name: 'Expenses', values: expenses, color: '#ef4444' }]"
+ *                 valueFormat="currency" ariaLabel="Income and expenses by month" />
+ *
+ *   - A series has `name` (blank = "Series N"), `values` (one per label: missing = 0, extra ignored, a non-number reads as 0; NaN and
+ *     Infinity are kept as in a single series), optional `color` (default: `BAR_CHART_SERIES_PALETTE`, cycled) and `hoverColor`
+ *     (default: a darker shade of the colour, see `darkenColor`; unparseable colours keep the colour on hover).
+ *   - Legend: an HTML list below the chart (swatch + name, hidden from assistive tech, wraps on phones), shown for any non-empty
+ *     `series` while `showLegend` is true (default). A single-series chart (`values`) never shows one.
+ *   - Tooltip: "<series name>: <value>" with the same `valueFormat` / unit rules as above (units per value for 'number').
+ *   - Value labels: each bar's value above it (`showValues`), only while labels x series <= 24 bars (`BAR_CHART_MAX_GROUPED_VALUE_LABELS`)
+ *     and never when `stacked` (the segments would overlap their labels). Tooltips and the hidden list always carry the values.
+ *   - Accessibility: the chart wrapper is unchanged (`role="img"` + `ariaLabel`); additionally a visually hidden list holds one entry per
+ *     label and series ("Jan, Income: $100.00"), label by label, written as plain text.
+ *   - Changing `series`, `stacked` or the formats at runtime updates the same chart; going back to no `series` restores the single-series chart.
+ *
  * - Height is `height` px (shorter on phones: 200px up to 768px wide, 160px up to 480px wide, when the default 240 is used);
  *   the width follows the container. Needs the optional peer dependency `chart.js` (>= 4).
  */
@@ -20,7 +101,9 @@ export declare class BarChartComponent {
   readonly values: import("@angular/core").InputSignal<number[]>;
   /** Bar colour (any CSS colour). */
   readonly color: import("@angular/core").InputSignal<string>;
-  /** Bar colour while hovered. */
+  /** Colour per bar by index (any CSS colour); missing or blank entries fall back to `color`, extra entries are ignored. Decorative only. */
+  readonly colors: import("@angular/core").InputSignal<string[]>;
+  /** Hover colour of the bars that use `color` (bars with their own `colors` entry get a darker shade of it). */
   readonly hoverColor: import("@angular/core").InputSignal<string>;
   /** Chart height in px. */
   readonly height: import("@angular/core").InputSignal<number>;
@@ -32,17 +115,48 @@ export declare class BarChartComponent {
   readonly unitSingular: import("@angular/core").InputSignal<string>;
   /** Tooltip unit for any other value (e.g. "calls"). */
   readonly unitPlural: import("@angular/core").InputSignal<string>;
+  /** How numbers are written on the value labels, tooltip and y axis: 'number' (default, raw numbers), 'currency' or 'percent' (values on the 0-100 scale). */
+  readonly valueFormat: import("@angular/core").InputSignal<BarChartValueFormat>;
+  /** ISO 4217 currency code for `valueFormat="currency"` (default USD; an invalid code falls back to USD). */
+  readonly currency: import("@angular/core").InputSignal<string>;
+  /** BCP 47 locale for 'currency' / 'percent' (default en-US; an invalid tag falls back to en-US). */
+  readonly locale: import("@angular/core").InputSignal<string>;
+  /** Fixed number of decimals for 'currency' / 'percent' (integer 0-6). null = the format's default. Ignored for 'number'. */
+  readonly decimals: import("@angular/core").InputSignal<number | null>;
+  /** Several series sharing `labels` (grouped side by side, or stacked). Non-empty = takes precedence over `values`, `color`, `hoverColor` and `colors`. Default: none (single series). */
+  readonly series: import("@angular/core").InputSignal<BarChartSeries[]>;
+  /** Multi-series only: true stacks the series on top of each other instead of grouping them side by side. */
+  readonly stacked: import("@angular/core").InputSignal<boolean>;
+  /** Multi-series only: show the HTML legend below the chart (a single series never has one). */
+  readonly showLegend: import("@angular/core").InputSignal<boolean>;
   private readonly canvas;
   private readonly zone;
   private chart;
+  private numberTickCallback;
+  /** Whether the chart currently holds grouped datasets (null = not created yet). */
+  private multiMode;
+  /** null for 'number' (original behaviour); otherwise the formatters, rebuilt only when an input changes. */
+  protected readonly formatter: import("@angular/core").Signal<ValueFormatter | null>;
+  /** The `series` input cleaned up for drawing; empty = single-series mode. */
+  protected readonly resolvedSeries: import("@angular/core").Signal<ResolvedSeries[]>;
+  protected readonly legendVisible: import("@angular/core").Signal<boolean>;
+  /** Visually hidden text of a multi-series chart: one entry per label and series, label by label. */
+  protected readonly srRows: import("@angular/core").Signal<string[]>;
   private readonly tooltipText;
-  protected readonly series: import("@angular/core").Signal<{
+  protected readonly model: import("@angular/core").Signal<{
+    groups: ResolvedSeries[];
+    stacked: boolean;
     labels: string[];
     data: number[];
     color: string;
+    colors: string[];
     hoverColor: string;
     showValues: boolean;
+    formatter: ValueFormatter | null;
   }>;
+  /** Fill and hover colours: single values when no `colors` are set (unchanged behaviour), otherwise one entry per bar. */
+  private static fills;
+  private static groupDataset;
   constructor();
   static ɵfac: i0.ɵɵFactoryDeclaration<BarChartComponent, never>;
   static ɵcmp: i0.ɵɵComponentDeclaration<BarChartComponent, "ui-bar-chart", never, {
@@ -61,6 +175,11 @@ export declare class BarChartComponent {
       "required": false;
       "isSignal": true;
     };
+    "colors": {
+      "alias": "colors";
+      "required": false;
+      "isSignal": true;
+    };
     "hoverColor": {
       "alias": "hoverColor";
       "required": false;
@@ -91,5 +210,172 @@ export declare class BarChartComponent {
       "required": false;
       "isSignal": true;
     };
+    "valueFormat": {
+      "alias": "valueFormat";
+      "required": false;
+      "isSignal": true;
+    };
+    "currency": {
+      "alias": "currency";
+      "required": false;
+      "isSignal": true;
+    };
+    "locale": {
+      "alias": "locale";
+      "required": false;
+      "isSignal": true;
+    };
+    "decimals": {
+      "alias": "decimals";
+      "required": false;
+      "isSignal": true;
+    };
+    "series": {
+      "alias": "series";
+      "required": false;
+      "isSignal": true;
+    };
+    "stacked": {
+      "alias": "stacked";
+      "required": false;
+      "isSignal": true;
+    };
+    "showLegend": {
+      "alias": "showLegend";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/** Built-in slice colours (cycled). Every colour has at least 3:1 contrast against white and against a light page grey (#f7f7f5). */
+declare const PIE_CHART_PALETTE: readonly string[];
+/** One drawn slice. `index` is the position in the input `labels`, so colours stay stable when another slice drops to 0. */
+interface PieSlice {
+  index: number;
+  label: string;
+  value: number;
+  percent: string;
+  color: string;
+}
+/** "62.5%", "100%", "<0.1%" (a non-zero share that rounds to nothing). Rounded to 1 decimal. */
+declare function formatPercent(value: number, total: number): string;
+/**
+ * Pie or doughnut chart of one series (e.g. payments by method).
+ *
+ *   <ui-pie-chart [labels]="['Card', 'Cash']" [values]="[5, 3]" [doughnut]="true" centerLabel="Payments" centerValue="8"
+ *                 ariaLabel="Payments by method" unitSingular="payment" unitPlural="payments" />
+ *
+ * - Values must be finite and non-negative; anything else counts as 0. Slices with 0 are not drawn and not in the legend.
+ *   Extra labels without a value count as 0; extra values without a label are ignored.
+ * - Empty or all-zero data shows a neutral grey ring with "No data" (no tooltip).
+ * - The tooltip reads "<value> <unit> (<share>)" (`unitSingular` for exactly 1, `unitPlural` otherwise; no unit = just the number;
+ *   `showPercent=false` drops the share). The legend is real HTML below the chart and wraps on phones.
+ * - With an `ariaLabel` the chart is an image for assistive tech (`role="img"` + label). A visually hidden list next to it always
+ *   gives every slice's label, value and share (plus the centre text), because an image hides its children.
+ * - Animation is off when the user prefers reduced motion. Height as ui-bar-chart: `height` px, default 240 shrinks to 200px up
+ *   to 768px wide and 160px up to 480px wide. Needs the optional peer dependency `chart.js` (>= 4).
+ * - No click output: a slice is not keyboard reachable, so selecting is left to a list or table next to the chart.
+ */
+export declare class PieChartComponent {
+  /** Slice names. */
+  readonly labels: import("@angular/core").InputSignal<string[]>;
+  /** Slice values, in the order of `labels`. */
+  readonly values: import("@angular/core").InputSignal<number[]>;
+  /** true = ring with a centre hole instead of a full pie. */
+  readonly doughnut: import("@angular/core").InputSignal<boolean>;
+  /** Per-slice CSS colours (cycled when shorter than the labels). Default: the built-in palette. */
+  readonly colors: import("@angular/core").InputSignal<string[]>;
+  /** Chart height in px (legend not included). */
+  readonly height: import("@angular/core").InputSignal<number>;
+  /** Spoken description of the chart. */
+  readonly ariaLabel: import("@angular/core").InputSignal<string>;
+  /** Show the legend below the chart. */
+  readonly showLegend: import("@angular/core").InputSignal<boolean>;
+  /** Show each slice's share in the tooltip, the legend and the hidden list. */
+  readonly showPercent: import("@angular/core").InputSignal<boolean>;
+  /** Tooltip unit for exactly 1 (e.g. "payment"). */
+  readonly unitSingular: import("@angular/core").InputSignal<string>;
+  /** Tooltip unit for any other value (e.g. "payments"). */
+  readonly unitPlural: import("@angular/core").InputSignal<string>;
+  /** Doughnut only: small text in the hole (e.g. "Total"). */
+  readonly centerLabel: import("@angular/core").InputSignal<string>;
+  /** Doughnut only: large text in the hole (e.g. "128"). */
+  readonly centerValue: import("@angular/core").InputSignal<string>;
+  private readonly canvas;
+  private readonly zone;
+  private readonly browser;
+  private chart;
+  /** Drawn slices (value > 0) with their colour and share. */
+  protected readonly slices: import("@angular/core").Signal<PieSlice[]>;
+  protected readonly isEmpty: import("@angular/core").Signal<boolean>;
+  protected readonly showCenter: import("@angular/core").Signal<boolean>;
+  /** "<value> <unit>" (`unitSingular` for exactly 1, `unitPlural` otherwise; no unit = just the number). */
+  protected readonly valueText: (value: number) => string;
+  private readonly tooltipText;
+  private readonly chartData;
+  constructor();
+  static ɵfac: i0.ɵɵFactoryDeclaration<PieChartComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<PieChartComponent, "ui-pie-chart", never, {
+    "labels": {
+      "alias": "labels";
+      "required": false;
+      "isSignal": true;
+    };
+    "values": {
+      "alias": "values";
+      "required": false;
+      "isSignal": true;
+    };
+    "doughnut": {
+      "alias": "doughnut";
+      "required": false;
+      "isSignal": true;
+    };
+    "colors": {
+      "alias": "colors";
+      "required": false;
+      "isSignal": true;
+    };
+    "height": {
+      "alias": "height";
+      "required": false;
+      "isSignal": true;
+    };
+    "ariaLabel": {
+      "alias": "ariaLabel";
+      "required": false;
+      "isSignal": true;
+    };
+    "showLegend": {
+      "alias": "showLegend";
+      "required": false;
+      "isSignal": true;
+    };
+    "showPercent": {
+      "alias": "showPercent";
+      "required": false;
+      "isSignal": true;
+    };
+    "unitSingular": {
+      "alias": "unitSingular";
+      "required": false;
+      "isSignal": true;
+    };
+    "unitPlural": {
+      "alias": "unitPlural";
+      "required": false;
+      "isSignal": true;
+    };
+    "centerLabel": {
+      "alias": "centerLabel";
+      "required": false;
+      "isSignal": true;
+    };
+    "centerValue": {
+      "alias": "centerValue";
+      "required": false;
+      "isSignal": true;
+    };
   }, {}, never, never, true, never>;
-}
+}
+export type { BarChartSeries, BarChartValueFormat };