@sinequa/atomic-angular 1.17.0 → 2.0.0

package/types/sinequa-atomic-angular-charts.d.ts

@@ -0,0 +1,462 @@
+import * as i0 from "@angular/core";
+import { InputSignal, Signal } from "@angular/core";
+import { ChartConfiguration, Plugin } from "chart.js";
+import { AggregationLike } from "@sinequa/atomic-angular";
+/**
+ * The Chart.js canvas, and the whole of its lifecycle.
+ *
+ * Every chart in this entry point is built on this one component. Chart.js has no Angular binding,
+ * so the integration work is entirely the canvas lifecycle — and that is where every bug lives.
+ * Four rules, all of them enforced here so no caller has to think about them:
+ *
+ *   1. **Create after the first render.** A canvas created during construction has no layout and
+ *      Chart.js measures it as 0x0. `afterNextRender` is the zoneless-safe hook.
+ *   2. **Always destroy.** Chart.js attaches a `ResizeObserver` and global listeners; leaking an
+ *      instance leaks both.
+ *   3. **Rebuild when `type` changes.** Chart.js cannot swap controller on a live instance.
+ *   4. **Rebuild when the theme changes.** `Chart.defaults` is read at construction time only, so
+ *      `update()` would leave the axes in the previous colour.
+ *
+ * Rules 3 and 4 are why this component owns an `effect()` — the only one in the entry point.
+ * Everything else is `computed()`.
+ *
+ * Named `ChartCanvas` rather than `Chart` deliberately: this file imports `Chart` from `chart.js`.
+ *
+ * **The host must have a resolved height.** The canvas fills its host and Chart.js sizes itself from
+ * the canvas' parent box, so put it in a container with a height (`class="h-80"`). A blank chart is
+ * nearly always this.
+ */
+export declare class ChartCanvasComponent {
+  cn: import("cn").CnFunction;
+  /**
+   * Extra classes for the host element.
+   * @default ""
+   */
+  readonly class: InputSignal<string>;
+  /**
+   * The Chart.js configuration. Rebuilt automatically when its `type` changes.
+   *
+   * Explicitly annotated, like `plugins` below, and for a second reason on top of portability: an
+   * inferred type is emitted into the .d.ts with the default type arguments already expanded, which
+   * freezes the union of known chart types at the moment THIS entry point was compiled. A caller in
+   * another entry point that augments `chart.js` — `/charts/heatmap` registers the `matrix`
+   * controller — would then be handing over a `ChartConfiguration` that no longer matches. Keeping
+   * the annotation keeps the name in the .d.ts, so it re-resolves in the caller's own context.
+   */
+  readonly config: InputSignal<ChartConfiguration>;
+  /**
+   * Local plugins, kept separate from `config.plugins` for readability. Build them once, outside any
+   * `computed()`: a plugin holding drag state would lose it on every recompute.
+   * @default []
+   */
+  readonly plugins: InputSignal<Plugin[]>;
+  private readonly canvas;
+  private readonly destroyRef;
+  private readonly theme;
+  private chart?;
+  private currentType?;
+  private currentDark?;
+  constructor();
+  /**
+   * `responsive` and `maintainAspectRatio: false` are forced here: together they make the chart
+   * follow its container instead of a fixed 2:1 ratio, and no caller should have to remember them.
+   */
+  private withDefaults;
+  static ɵfac: i0.ɵɵFactoryDeclaration<ChartCanvasComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<ChartCanvasComponent, "ChartCanvas, chart-canvas, chartcanvas", never, {
+    "class": {
+      "alias": "class";
+      "required": false;
+      "isSignal": true;
+    };
+    "config": {
+      "alias": "config";
+      "required": true;
+      "isSignal": true;
+    };
+    "plugins": {
+      "alias": "plugins";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/**
+ * Registers the Chart.js controllers, scales and elements the charts need.
+ *
+ * Chart.js 4 ships nothing by default. This is idempotent on purpose: it is called from the
+ * constructor of every `<ChartCanvas>`, so it must be safe to call many times. Registering from a
+ * component rather than from application bootstrap keeps the entry point self-contained — an
+ * application that never imports `@sinequa/atomic-angular/charts` never runs this, and never needs
+ * `chart.js` installed.
+ */
+export declare function setupCharts(): void;
+/**
+ * Applies theme-dependent defaults: axis and legend text colour, and grid line colour.
+ *
+ * These read *semantic* galactik tokens, not primitive ramps — semantic tokens are exactly the ones
+ * `galactik-tokens-dark.css` reassigns under `:root.dark`, so the chart chrome follows the theme
+ * while series colours (built from primitives) keep their identity.
+ *
+ * Chart.js reads `Chart.defaults` when an instance is CONSTRUCTED, never afterwards. Calling
+ * `chart.update()` after a theme switch therefore leaves the axes in the previous colour — the
+ * instance has to be destroyed and rebuilt. `<ChartCanvas>` does exactly that.
+ */
+export declare function applyChartTheme(): void;
+/**
+ * Dark mode, exposed as a signal.
+ *
+ * galactik switches theme through a `dark` class on the document root (`:root.dark`), so this
+ * observes the DOM rather than depending on a particular store. That keeps the charts usable in any
+ * host application, whatever drives its theme.
+ *
+ * A canvas cannot react to a CSS class on its own: `<ChartCanvas>` reads this signal and rebuilds
+ * its Chart.js instance when it flips. See `applyChartTheme`.
+ */
+export declare class ChartThemeService {
+  private readonly dark;
+  /** `true` when the document root carries the `dark` class. Updates on its own. */
+  readonly isDark: Signal<boolean>;
+  constructor();
+  static ɵfac: i0.ɵɵFactoryDeclaration<ChartThemeService, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+/**
+ * Creates the brush plugin.
+ *
+ * @param onSelect called on mouse release with the first and last category LABELS covered by the
+ *                 drag. Labels (not pixels, not dates) because the timeline uses a `category` axis:
+ *                 what the caller gets back is exactly what it put into `data.labels`.
+ */
+export declare function createTimelineBrushPlugin(onSelect: (from: string, to: string) => void): Plugin;
+/** A click on an axis label: which axis, which category index, and the label as it was drawn. */
+export interface AxisLabelHit {
+  readonly axis: "x" | "y";
+  /** Index of the category on that axis, i.e. its position in the scale's labels. */
+  readonly index: number;
+  readonly label: string;
+}
+/**
+ * Makes axis labels clickable — SBA v2's `axisClicked`, on a canvas.
+ *
+ * On a DOM chart (`<Heatmap>`) an axis label is a `<button>` and this is free. On a canvas it is
+ * painted pixels, so the hit test has to be written. Three things make it work, and each of them is
+ * a failure mode of the naive version:
+ *
+ *   1. **`options.onClick` cannot do this.** Chart.js only calls it when the pointer is inside
+ *      `chartArea` (`Chart#_handleEvent`), and axis labels are outside it by construction. A
+ *      plugin's `afterEvent` sees every event on the canvas, in or out of the area.
+ *   2. **No `options.events` change is needed**, unlike the timeline brush: `click`, `mousemove`
+ *      and `mouseout` are already in the Chart.js default list — only `mousedown`/`mouseup` are not.
+ *   3. **Hit-test the scale's own box** (`scale.left/top/right/bottom`), not a band derived from
+ *      `chartArea`. It is exactly the strip Chart.js reserved for that axis, the two axis boxes
+ *      never overlap, and the corner between them — which belongs to neither — is excluded for free.
+ *
+ * Generic: any chart with a category axis can use it, not just the heatmap.
+ *
+ * @param onSelect called on a click over an axis label.
+ * @param axes which axes react. Defaults to both.
+ */
+export declare function createAxisClickPlugin(onSelect: (hit: AxisLabelHit) => void, axes?: ReadonlyArray<"x" | "y">): Plugin;
+/**
+ * The date masks Sinequa uses for time aggregations. The mask is configured server-side on the
+ * aggregation and tells you the width of one bucket.
+ */
+export type TimelineMask = "YYYY" | "YYYY-MM" | "YYYY-WW" | "YYYY-MM-DD" | "YYYY-MM-DD-hh" | "YYYY-MM-DD-hh-mm";
+/** One input series, before the shared axis is built. */
+export interface TimelineSeriesInput {
+  readonly label: string;
+  /** Only primary series determine the extent of the axis; secondary ones are just plotted on it. */
+  readonly primary?: boolean;
+  /** Aggregation whose items are date buckets: `value` is the bucket key, `count` the measure. */
+  readonly aggregation: AggregationLike | undefined;
+  /** Read this operator result instead of `count` (e.g. "avg" for a response-time curve). */
+  readonly weightField?: string;
+}
+/** One output series, aligned on the shared axis: `values[i]` belongs to `labels[i]`. */
+export interface TimelineSeries {
+  readonly label: string;
+  readonly primary: boolean;
+  readonly values: Array<number | null>;
+}
+export interface TimelineData {
+  readonly labels: string[];
+  readonly series: TimelineSeries[];
+}
+export interface TimelineOptions {
+  /** Bucket width. Without it, no gap filling happens: the axis is just the keys that exist. */
+  readonly mask?: TimelineMask;
+  /** Safety valve for generated buckets. A one-minute mask over a year would produce ~525 600. */
+  readonly maxBuckets?: number;
+}
+/**
+ * Builds a shared category axis and aligns every series onto it.
+ *
+ * The gap filling is the point. Without it, three days with no activity are not drawn as a flat
+ * line at zero -- they simply do not exist, and the line jumps straight from one populated day to
+ * the next, silently misrepresenting the data. SBA v2 did this in createDatapoints(); the comment
+ * there drew it as:
+ *
+ *   aggregation: [    # #         # # #   #     # #       # # #    ]
+ *   series:      [  0 # # 0     0 # # # 0 # 0 0 # # 0   0 # # # 0  ]
+ */
+export declare function buildTimeline(inputs: readonly TimelineSeriesInput[], options?: TimelineOptions): TimelineData;
+/**
+ * Parses a Sinequa bucket key: "2026", "2026-01", "2026-01-13", "2026-01-13 14:00:00", ...
+ *
+ * Everything is read in LOCAL time, including date-only keys. This is deliberate: `new Date("2026-01-13")`
+ * is parsed as UTC by the specification, while `new Date(2026, 0, 13)` is local. Mixing the two puts
+ * the generated buckets half a day out of step with the parsed ones near a DST boundary.
+ */
+export declare function parseBucketDate(key: string): Date | null;
+/** A candidate aggregation for adaptive resolution. */
+export interface ResolutionCandidate<T> {
+  readonly mask: TimelineMask;
+  /**
+   * Widest range, in months, this candidate should serve. Use -1 for "no limit".
+   * Mirrors SBA v2's maxNMonths.
+   */
+  readonly maxMonths: number;
+  readonly value: T;
+}
+/**
+ * Picks the finest resolution that still covers the requested range.
+ *
+ * This is what keeps a timeline usable across scales: a daily aggregation over twenty years is
+ * 7 300 points, unreadable and slow, while a yearly aggregation over one month is a single dot.
+ * SBA v2 called this "combined aggregations". Feed it the range currently displayed (after a brush
+ * selection, say) and re-fetch with the aggregation it returns.
+ */
+export declare function pickResolution<T>(candidates: readonly ResolutionCandidate<T>[], rangeMonths: number): ResolutionCandidate<T> | undefined;
+/** Whole months between two dates, for feeding pickResolution(). */
+export declare function monthsBetween(from: Date, to: Date): number;
+/** The chart types this component supports. A narrow union keeps `strictTemplates` useful. */
+export type AggregationChartType = "bar" | "pie" | "doughnut";
+/**
+ * A Sinequa aggregation rendered as a bar, pie or doughnut chart.
+ *
+ * Note what this component does **not** do:
+ *
+ *   - **it does not fetch.** It takes an `Aggregation` as an input, like `<Aggregation>` in
+ *     controlled mode. Feed it from `AggregationsStore`, from `QueryService.search()` or from
+ *     `fetchQuery()` — the component does not care, and stays testable without a server.
+ *   - **it does not transform.** `toSeries()` does that, as a pure function.
+ *   - **it does not touch the canvas.** `<ChartCanvas>` owns the Chart.js lifecycle.
+ *
+ * What is left is one `computed()` building a `ChartConfiguration`. That is the whole component.
+ */
+export declare class AggregationChartComponent {
+  cn: import("cn").CnFunction;
+  /**
+   * Extra classes for the host element.
+   * @default ""
+   */
+  readonly class: import("@angular/core").InputSignal<string>;
+  /**
+   * The aggregation to render.
+   * @default undefined
+   */
+  readonly aggregation: import("@angular/core").InputSignal<AggregationLike | undefined>;
+  /**
+   * Chart type.
+   * @default "bar"
+   */
+  readonly type: import("@angular/core").InputSignal<AggregationChartType>;
+  /**
+   * Dataset label, shown in the legend and the tooltip.
+   * @default ""
+   */
+  readonly label: import("@angular/core").InputSignal<string>;
+  /**
+   * Number of items kept, largest first. Charts stop being readable long before the data runs out.
+   * @default 10
+   */
+  readonly limit: import("@angular/core").InputSignal<number>;
+  /**
+   * Plot each item as a share of the total instead of a raw count.
+   * @default false
+   */
+  readonly asPercentage: import("@angular/core").InputSignal<boolean>;
+  /**
+   * Read `operatorResults[weightField]` instead of `count` — for an average response time, say.
+   * @default undefined
+   */
+  readonly weightField: import("@angular/core").InputSignal<string | undefined>;
+  /**
+   * Text shown when there is nothing to display.
+   * @default "No data"
+   */
+  readonly emptyLabel: import("@angular/core").InputSignal<string>;
+  /**
+   * Emitted with the label of the clicked slice. Wire it to `AggregationsService.toFilter()` and
+   * `QueryParamsStore.updateFilter()` to turn this chart into a facet.
+   */
+  readonly itemSelected: import("@angular/core").OutputEmitterRef<string>;
+  /** Resolved after the first render: `getComputedStyle` is useless before styles have applied. */
+  private readonly palette;
+  constructor();
+  private readonly series;
+  protected readonly isEmpty: import("@angular/core").Signal<boolean>;
+  protected readonly config: import("@angular/core").Signal<ChartConfiguration<keyof import("chart.js").ChartTypeRegistry, (number | [number, number] | import("chart.js").Point | import("chart.js").BubbleDataPoint | null)[], unknown>>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<AggregationChartComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<AggregationChartComponent, "AggregationChart, aggregation-chart, aggregationchart", never, {
+    "class": {
+      "alias": "class";
+      "required": false;
+      "isSignal": true;
+    };
+    "aggregation": {
+      "alias": "aggregation";
+      "required": false;
+      "isSignal": true;
+    };
+    "type": {
+      "alias": "type";
+      "required": false;
+      "isSignal": true;
+    };
+    "label": {
+      "alias": "label";
+      "required": false;
+      "isSignal": true;
+    };
+    "limit": {
+      "alias": "limit";
+      "required": false;
+      "isSignal": true;
+    };
+    "asPercentage": {
+      "alias": "asPercentage";
+      "required": false;
+      "isSignal": true;
+    };
+    "weightField": {
+      "alias": "weightField";
+      "required": false;
+      "isSignal": true;
+    };
+    "emptyLabel": {
+      "alias": "emptyLabel";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "itemSelected": "itemSelected";
+  }, never, never, true, never>;
+}
+/** A brushed range, expressed with the same bucket labels the caller supplied. */
+export interface TimelineRange {
+  readonly from: string;
+  readonly to: string;
+}
+/**
+ * A time series with drag-to-select range selection, on Chart.js, with no d3.
+ *
+ * The d3 timeline this replaces was ~800 lines. The mapping:
+ *
+ * | d3 | here |
+ * |---|---|
+ * | `d3.curveStep` | `stepped: "middle"` |
+ * | `d3.area()` | `fill: true` + `withAlpha(colour, 0.18)` |
+ * | `d3.scaleUtc` + axis | a `category` axis over labels resolved in `timeline-data.ts` |
+ * | `d3.brushX` | `createTimelineBrushPlugin()`, ~60 lines |
+ * | `d3.bisector` tooltip | `interaction: { mode: "index", intersect: false }` |
+ * | gap filling, resolution picking | pure functions in `timeline-data.ts` |
+ *
+ * The real gain is not the removed dependency: it is that all the time-axis logic became pure and
+ * testable instead of being welded to the rendering.
+ *
+ * **A `category` axis, never `time`.** Chart.js can do a real time axis, but only with a date
+ * adapter, which this library does not ship. Setting `scales.x.type = "time"` without one compiles
+ * perfectly and then throws at runtime.
+ *
+ * **`(rangeSelected)` only reports.** If the host does nothing with it, you drag, the rectangle
+ * appears, it vanishes, and nothing moves — the component is fine, the loop is simply not closed.
+ * Keep a stack of ranges: a drag pushes one (zoom in), a control pops it (zoom out).
+ */
+export declare class AggregationTimelineComponent {
+  cn: import("cn").CnFunction;
+  /**
+   * Extra classes for the host element.
+   * @default ""
+   */
+  readonly class: import("@angular/core").InputSignal<string>;
+  /**
+   * The series to plot. Each carries an aggregation whose items are date buckets.
+   * @default []
+   */
+  readonly series: import("@angular/core").InputSignal<readonly TimelineSeriesInput[]>;
+  /**
+   * Bucket width. Without it there is no gap filling: empty buckets are skipped rather than drawn
+   * flat at zero, which silently misrepresents the data.
+   * @default "YYYY-MM-DD"
+   */
+  readonly mask: import("@angular/core").InputSignal<TimelineMask | undefined>;
+  /**
+   * Enable the drag-to-select brush.
+   * @default true
+   */
+  readonly enableSelection: import("@angular/core").InputSignal<boolean>;
+  /**
+   * Render every second series dashed — the "previous period" convention.
+   * @default false
+   */
+  readonly dashSecondary: import("@angular/core").InputSignal<boolean>;
+  /**
+   * Text shown when there is nothing to display.
+   * @default "No data"
+   */
+  readonly emptyLabel: import("@angular/core").InputSignal<string>;
+  /** Emitted on mouse release with the first and last bucket labels covered by the drag. */
+  readonly rangeSelected: import("@angular/core").OutputEmitterRef<TimelineRange>;
+  /**
+   * Built ONCE, as a field, never inside a `computed()`.
+   *
+   * The brush keeps its drag state in a closure. Rebuilding it mid-drag would hand Chart.js a fresh
+   * object with empty state and cancel the selection — producing a brush that "sometimes does not
+   * work", which is worse than one that never does.
+   */
+  private readonly brush;
+  /** Resolved after the first render: `getComputedStyle` is useless before styles have applied. */
+  private readonly palette;
+  constructor();
+  protected readonly plugins: Signal<Plugin[]>;
+  private readonly timeline;
+  protected readonly isEmpty: Signal<boolean>;
+  protected readonly config: Signal<ChartConfiguration<keyof import("chart.js").ChartTypeRegistry, (number | [number, number] | import("chart.js").Point | import("chart.js").BubbleDataPoint | null)[], unknown>>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<AggregationTimelineComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<AggregationTimelineComponent, "AggregationTimeline, aggregation-timeline, aggregationtimeline", never, {
+    "class": {
+      "alias": "class";
+      "required": false;
+      "isSignal": true;
+    };
+    "series": {
+      "alias": "series";
+      "required": false;
+      "isSignal": true;
+    };
+    "mask": {
+      "alias": "mask";
+      "required": false;
+      "isSignal": true;
+    };
+    "enableSelection": {
+      "alias": "enableSelection";
+      "required": false;
+      "isSignal": true;
+    };
+    "dashSecondary": {
+      "alias": "dashSecondary";
+      "required": false;
+      "isSignal": true;
+    };
+    "emptyLabel": {
+      "alias": "emptyLabel";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "rangeSelected": "rangeSelected";
+  }, never, never, true, never>;
+}