@powerportalspro/react-charts 5.0.0-beta.1

package/dist/index.d.cts

@@ -0,0 +1,352 @@
+import { DataPoint, ChartDataset as ChartDataset$1, PowerPortalsProClient, ChartData, ChartDataRequest, ChartDateGrouping, ChartLinkedEntity, AggregateType } from '@powerportalspro/core';
+export { AggregateChartConfig, AggregateType, BaseDataPoint, ChartData, ChartDataRequest, ChartDataResponse, ChartDateGrouping, ChartLinkedEntity, DataPoint, DataverseDataPoint, JoinOperator } from '@powerportalspro/core';
+import { RefAttributes, ReactElement } from 'react';
+
+/**
+ * Display-only type / enum definitions for the React Charts wrapper.
+ * Wire-shape types (ChartData, ChartDataset, DataPoint, DataverseDataPoint,
+ * ChartLinkedEntity, ChartDateGrouping, AggregateType, JoinOperator) are
+ * generated from OpenAPI and re-exported from `@powerportalspro/core` —
+ * this file holds only the Chart.js-presentation enums that don't cross
+ * the wire.
+ */
+
+/**
+ * Dataset of chart data points. Generic over `TPoint` so consumers can
+ * carry a custom DataPoint subtype through to the click handler.
+ *
+ * Defaults to the built-in {@link DataPoint} union — when the consumer
+ * doesn't specialize the generic, calls look exactly like before
+ * (no `<…>` required). When they DO want richer click context, they
+ * extend {@link BaseDataPoint} and parameterize:
+ *
+ * ```ts
+ * interface SalesDataPoint extends BaseDataPoint {
+ *   region: string;
+ *   orderCount: number;
+ * }
+ *
+ * const datasets: ChartDataset<SalesDataPoint>[] = [{
+ *   label: 'Sales',
+ *   data: [{ value: 65, region: 'North', orderCount: 12 }],
+ * }];
+ *
+ * <FluentUIChart<SalesDataPoint>
+ *   datasets={datasets}
+ *   onElementClick={(a) => a.dataPoint?.region}
+ * />
+ * ```
+ *
+ * Mirrors Blazor's `List<DataPoint>` polymorphism — the underlying
+ * Chart.js layer accepts arbitrary object fields on each data point and
+ * passes them straight through to the click handler.
+ */
+type ChartDataset<TPoint = DataPoint> = Omit<ChartDataset$1, 'data'> & {
+    data?: TPoint[];
+};
+/** Chart types supported by the underlying Chart.js library. */
+declare const ChartType: {
+    /** Bar chart (`'bar'`). */
+    readonly Bar: "bar";
+    /** Line chart (`'line'`). */
+    readonly Line: "line";
+    /** Pie chart (`'pie'`). */
+    readonly Pie: "pie";
+    /** Doughnut chart (`'doughnut'`). */
+    readonly Doughnut: "doughnut";
+    /** Polar area chart (`'polarArea'`). */
+    readonly PolarArea: "polarArea";
+    /** Radar chart (`'radar'`). */
+    readonly Radar: "radar";
+    /** Bubble chart (`'bubble'`). */
+    readonly Bubble: "bubble";
+    /** Scatter chart (`'scatter'`). */
+    readonly Scatter: "scatter";
+    /** Funnel chart (via the `chartjs-chart-funnel` plugin, type `'funnel'`). */
+    readonly Funnel: "funnel";
+};
+type ChartType = (typeof ChartType)[keyof typeof ChartType];
+/**
+ * Placement of the chart legend, or `Hidden` to suppress it entirely. Maps
+ * directly to Chart.js's lowercase legend position string.
+ */
+declare const ChartLegendPosition: {
+    readonly Top: "top";
+    readonly Bottom: "bottom";
+    readonly Left: "left";
+    readonly Right: "right";
+    /** Legend is not rendered. */
+    readonly Hidden: "hidden";
+};
+type ChartLegendPosition = (typeof ChartLegendPosition)[keyof typeof ChartLegendPosition];
+/**
+ * Chart.js `indexAxis` value — `'x'` for vertical bar / line charts and
+ * `'y'` for horizontal bars / funnels. Most consumers should set
+ * {@link ChartOrientation} on a component instead of touching this directly.
+ */
+declare const ChartIndexAxis: {
+    readonly X: "x";
+    readonly Y: "y";
+};
+type ChartIndexAxis = (typeof ChartIndexAxis)[keyof typeof ChartIndexAxis];
+/**
+ * Caller-facing chart orientation. Maps to the underlying Chart.js
+ * `indexAxis` via {@link toIndexAxis}: `Vertical` → `'x'`, `Horizontal` →
+ * `'y'`. Funnel charts default to `Horizontal` for a top-down funnel.
+ */
+declare const ChartOrientation: {
+    readonly Vertical: "vertical";
+    readonly Horizontal: "horizontal";
+};
+type ChartOrientation = (typeof ChartOrientation)[keyof typeof ChartOrientation];
+/** Maps a {@link ChartOrientation} to the Chart.js {@link ChartIndexAxis}. */
+declare function toIndexAxis(orientation: ChartOrientation): ChartIndexAxis;
+/**
+ * Theme and formatting overrides forwarded to Chart.js. Fields left
+ * `undefined` are not applied — the underlying Chart.js defaults stand.
+ */
+interface ChartTheme {
+    /** Color for legend labels, axis ticks, and the title. */
+    textColor?: string;
+    /** Color for axis gridlines and borders. */
+    gridColor?: string;
+    /** Prefix prepended to every Y-axis tick label and tooltip value (e.g. `"$"`). */
+    yAxisPrefix?: string;
+    /** Suffix appended to every Y-axis tick label and tooltip value (e.g. `"%"`). */
+    yAxisSuffix?: string;
+    /** Prefix prepended to every X-axis tick label (e.g. `"Q"`). */
+    xAxisPrefix?: string;
+    /** Suffix appended to every X-axis tick label. */
+    xAxisSuffix?: string;
+    /** Chart title text displayed above the chart. */
+    title?: string;
+    /**
+     * Stack datasets on top of each other instead of side-by-side. Applies to
+     * bar and line charts.
+     */
+    stacked?: boolean;
+    /** Legend placement or `Hidden`. When omitted, Chart.js's default is used. */
+    legendPosition?: ChartLegendPosition;
+    /** Whether chart animations are enabled. Defaults to `true`. */
+    enableAnimation?: boolean;
+    /**
+     * Category-axis direction — usually set indirectly via the caller-facing
+     * {@link ChartOrientation}. Funnel charts default to `'y'`.
+     */
+    indexAxis?: ChartIndexAxis;
+}
+/**
+ * Payload describing a single click on a rendered chart element. Generic
+ * over `TPoint` so consumers using a custom DataPoint subtype see their
+ * extra fields on `dataPoint` without a cast.
+ */
+interface ChartClickEventArgs<TPoint = DataPoint> {
+    /** Zero-based dataset index that contains the clicked element. */
+    datasetIndex: number;
+    /** Zero-based point index within its dataset. */
+    dataIndex: number;
+    /** Category label of the clicked element (e.g. `"January"`) or empty. */
+    label: string;
+    /** Numeric value of the clicked data point. */
+    value: number;
+    /** Label of the dataset the clicked element belongs to. */
+    datasetLabel: string;
+    /**
+     * The original data-point object backing the clicked element. Typed as
+     * the dataset's `TPoint` so a `ChartDataset<MyPoint>` flows through to
+     * `MyPoint` here. With the default {@link DataPoint} union, discriminate
+     * via the `$type` field or `'record' in dataPoint` to recover
+     * DataverseDataPoint context. `undefined` only when the indices from
+     * Chart.js no longer line up with the current datasets (rare race
+     * during a data swap).
+     */
+    dataPoint?: TPoint;
+}
+
+/**
+ * Base `<Chart>` React component — direct Chart.js wrapper, mirrors the
+ * Blazor `Chart.razor` API surface (Type, Labels, Datasets, Width, Height,
+ * Theme, OnElementClick + `exportAsImage`).
+ *
+ * Owns the Chart.js instance via a canvas ref; React's render is just the
+ * outer container + `<canvas>`. Chart lifecycle is driven by an effect that
+ * reads the props snapshot. The component pre-empts re-renders triggered
+ * by unrelated parent updates by reference-checking labels/datasets/theme
+ * before destroying the underlying Chart.js instance — the same
+ * "destroy + recreate is expensive" optimization the Blazor component
+ * uses (each re-create restarts the entry animation).
+ */
+
+/** Imperative handle exposed to callers via `ref` on `<Chart>`. */
+interface ChartHandle {
+    /**
+     * Exports the chart as a PNG data URI
+     * (`"data:image/png;base64,…"`). Returns `null` when the chart hasn't
+     * been rendered yet (typically the first paint).
+     */
+    exportAsImage(): string | null;
+}
+/**
+ * Props accepted by `<Chart>`. Generic over `TPoint` — the type carried
+ * through the dataset's `data` array and back out on `onElementClick`.
+ * Defaults to {@link DataPoint}, so callers that don't extend the built-in
+ * DataPoint shape never need to mention the generic.
+ */
+interface ChartProps<TPoint = DataPoint> {
+    /** Chart type. Defaults to `ChartType.Bar`. */
+    type?: ChartType;
+    /** Category labels rendered along the primary axis. */
+    labels: string[];
+    /** Datasets to plot. */
+    datasets: ChartDataset<TPoint>[];
+    /** Optional CSS width applied to the outer container. */
+    width?: string;
+    /** Optional CSS height applied to the outer container. Defaults to `'400px'`. */
+    height?: string;
+    /** Theme overrides forwarded to Chart.js. */
+    theme?: ChartTheme;
+    /** Fires when the user clicks on a rendered chart element. */
+    onElementClick?: (args: ChartClickEventArgs<TPoint>) => void;
+}
+declare const Chart: <TPoint = DataPoint>(props: ChartProps<TPoint> & RefAttributes<ChartHandle>) => ReactElement | null;
+
+/**
+ * Base chart data source. Builds a {@link ChartDataRequest} from the
+ * configured properties and dispatches it through the server-side
+ * `IChartService` via {@link PowerPortalsProClient.loadChartAsync}.
+ * The server owns FetchXML construction and record shaping — this class
+ * is a thin client over the typed request shape.
+ *
+ * Mirrors `PowerPortalsPro.Web.Blazor.Charts.Components.DataverseChartDataSource`
+ * on the Blazor side; both feed the same endpoint.
+ */
+
+/**
+ * Configuration accepted by {@link DataverseChartDataSource}. Subclasses
+ * carry their own subset and forward what they need to the base constructor.
+ */
+interface DataverseChartDataSourceOptions {
+    /**
+     * FetchXML to send to the server. Subclasses leave this blank and
+     * override `configureRequest` to set a different input mode.
+     */
+    fetchXml?: string;
+    /** Result column name to read chart labels from (X axis). */
+    labelColumn?: string;
+    /** Result column name to read numeric values from. */
+    valueColumn?: string;
+    /**
+     * Optional result column name used to split rows into multiple
+     * datasets. When set, rows sharing the same series value form one
+     * dataset.
+     */
+    seriesColumn?: string;
+    /**
+     * Optional label applied to the single emitted dataset when
+     * {@link seriesColumn} isn't set. Multi-series queries use the
+     * formatted series value as the dataset label and ignore this.
+     */
+    singleSeriesLabel?: string;
+}
+declare class DataverseChartDataSource {
+    fetchXml?: string;
+    labelColumn: string;
+    valueColumn: string;
+    seriesColumn?: string;
+    singleSeriesLabel: string;
+    constructor(options?: DataverseChartDataSourceOptions);
+    /**
+     * Builds a {@link ChartDataRequest} from this instance's properties
+     * and POSTs it via `client.loadChartAsync`. Subclasses inject the
+     * input mode via {@link configureRequest}.
+     */
+    loadAsync(client: PowerPortalsProClient, signal?: AbortSignal): Promise<ChartData>;
+    /**
+     * Sets the input mode (FetchXml / ViewId / Aggregate) on the request.
+     * Base implementation sets `fetchXml`; subclasses override to use
+     * ViewId or Aggregate config instead.
+     */
+    protected configureRequest(request: ChartDataRequest): void;
+}
+
+/**
+ * Loads chart data from a saved Dataverse view. Caller still picks which
+ * of the view's columns map to labels / values via `labelColumn` /
+ * `valueColumn`; this class just sets the request's `viewId` input mode.
+ *
+ * Mirrors `PowerPortalsPro.Web.Blazor.Charts.Components.ViewDataverseChartDataSource`.
+ */
+
+interface ViewDataverseChartDataSourceOptions extends DataverseChartDataSourceOptions {
+    /** Dataverse saved-view id. Server fetches its FetchXML on every load. */
+    viewId?: string;
+}
+declare class ViewDataverseChartDataSource extends DataverseChartDataSource {
+    viewId?: string;
+    constructor(options?: ViewDataverseChartDataSourceOptions);
+    protected configureRequest(request: ChartDataRequest): void;
+}
+
+/**
+ * Aggregate chart data source. Builds an {@link AggregateChartConfig}
+ * from typed properties and sends it through the server-side endpoint.
+ * The server constructs the FetchXML (including link-entity trees,
+ * combined date groupings, and view-filter merging) and shapes the
+ * response.
+ *
+ * Mirrors `PowerPortalsPro.Web.Blazor.Charts.Components.AggregateDataverseChartDataSource`.
+ */
+
+/** Caller-supplied configuration. Mirrors the Blazor property surface. */
+interface AggregateDataverseChartDataSourceOptions extends Omit<DataverseChartDataSourceOptions, 'fetchXml' | 'labelColumn' | 'valueColumn'> {
+    /** Dataverse table to query (e.g. `"opportunity"`). */
+    tableName: string;
+    /** Column to group by — becomes the chart's X-axis labels. */
+    groupByColumn: string;
+    /** Date bucketing for `groupByColumn` when it's a datetime column. */
+    groupByDateGrouping?: ChartDateGrouping;
+    /** Linked entity chain when `groupByColumn` lives on a related table. */
+    groupByLinkedEntity?: ChartLinkedEntity;
+    /**
+     * Secondary date grouping applied to the same column as `groupByColumn`
+     * (year-over-year charts). When set, the server emits a second
+     * `groupby` on the same column and uses its result as the series
+     * discriminator.
+     */
+    seriesDateGrouping?: ChartDateGrouping;
+    /** Linked entity chain for `seriesColumn` when it lives on a related table. */
+    seriesLinkedEntity?: ChartLinkedEntity;
+    /** Column to aggregate (sum / count / etc.). */
+    aggregateColumn: string;
+    /** Aggregate function. Defaults to `AggregateType.Sum`. */
+    aggregate?: AggregateType;
+    /** Optional saved-view id whose filters are merged into the generated query. */
+    viewId?: string;
+    /** Optional raw `<filter>...</filter>` fragment injected into the query. */
+    filterXml?: string;
+    /** Optional row cap. */
+    top?: number;
+}
+declare class AggregateDataverseChartDataSource extends DataverseChartDataSource {
+    tableName: string;
+    groupByDateGrouping: ChartDateGrouping;
+    groupByLinkedEntity?: ChartLinkedEntity;
+    seriesDateGrouping: ChartDateGrouping;
+    seriesLinkedEntity?: ChartLinkedEntity;
+    aggregate: AggregateType;
+    viewId?: string;
+    filterXml?: string;
+    top?: number;
+    constructor(options: AggregateDataverseChartDataSourceOptions);
+    /** Caller-friendly alias for `labelColumn` (kept in sync via getter/setter). */
+    get groupByColumn(): string;
+    set groupByColumn(value: string);
+    /** Caller-friendly alias for `valueColumn`. */
+    get aggregateColumn(): string;
+    set aggregateColumn(value: string);
+    protected configureRequest(request: ChartDataRequest): void;
+}
+
+declare const VERSION = "0.1.0";
+
+export { AggregateDataverseChartDataSource, type AggregateDataverseChartDataSourceOptions, Chart, type ChartClickEventArgs, type ChartDataset, type ChartHandle, ChartIndexAxis, ChartLegendPosition, ChartOrientation, type ChartProps, type ChartTheme, ChartType, DataverseChartDataSource, type DataverseChartDataSourceOptions, VERSION, ViewDataverseChartDataSource, type ViewDataverseChartDataSourceOptions, toIndexAxis };