@arcgis/charts-components 5.0.0-next.14 → 5.0.0-next.141

package/dist/model/box-plot-model/box-plot-model.d.ts

@@ -1,237 +1,215 @@
-import { ChartConfig, XYChartTypes } from '../../utils';
-import { Color, RESTSimpleLineSymbolStyle, WebChart, WebChartDataFilters } from '../../spec';
-import { ChartModel } from '../chart-model/chart-model';
-import { ModelParams } from '../interfaces/chart-interfaces';
-import { ModelTypes, BoxPlotDataSortingKinds } from '../interfaces/common';
-import { ModelWithColorMatch, ModelWithDataLabels, ModelWithLegend, ModelWithMultiAxes, ModelWithRotation, ModelWithTooltips, ModelWithYGuides } from '../mixins';
-export declare class BoxPlotModel extends ChartModel {
-    /**
-     * Current configuration used for the box plot chart.
-     */
-    protected _config: ChartConfig<typeof ModelTypes.BoxPlot, WebChart>;
-    protected _chartType: XYChartTypes;
-    /**
-     * Internal storage of the category field for the chart.
-     * @category Protected
-     */
-    protected _category: string;
-    /**
-     * Internal storage of the split-by field for the chart.
-     * @category Protected
-     */
-    protected _splitByField: string;
-    /**
-     * Internal storage of the numeric fields for the chart.
-     * @category Protected
-     */
-    protected _numericFields: string[];
-    /**
-     * The previous mean lines box color. We save this so that we can recover the color previously set if the user toggles mean lines off and then back on.
-     * @category Private
-     */
-    private previousMeanLinesBoxColor;
-    setup(params: ModelParams<ChartConfig<typeof ModelTypes.BoxPlot>>): Promise<void>;
-    /**
-     * The category field for the box plot.
-     */
-    get category(): string;
-    set category(newCategory: string);
-    /**
-     * The numeric fields array for the box plot.
-     */
-    get numericFields(): string[];
-    set numericFields(newNumericFields: string[] | string);
-    /**
-     * The split-by field for the box plot.
-     */
-    get splitByField(): string;
-    set splitByField(newSplitByField: string);
-    /**
-     * Whether outliers are shown.
-     */
-    get showOutliers(): boolean;
-    set showOutliers(newShowOutliersState: boolean);
-    /**
-     * Whether values are standardized as z-scores.
-     */
-    get standardizeValues(): boolean;
-    set standardizeValues(newStandardizeValuesState: boolean);
-    /**
-     * Gets the sort order of the box plot data.
-     * @returns {"xAxisAsc" | "xAxisDesc"| "meanAsc" | "meanDesc" | "medianAsc" | "medianDesc" | "customSort"}
-     */
-    getSortOrder(): BoxPlotDataSortingKinds;
-    /**
-     * Sets the sort order of the box plot data.
-     * @param {"xAxisAsc" | "xAxisDesc"| "meanAsc" | "meanDesc" | "medianAsc" | "medianDesc" | "customSort"} newSortOrder The new sort order.
-     * @param {string[]} orderByList The new list of category's values for custom sort.
-     */
-    setSortOrder(newSortOrder: BoxPlotDataSortingKinds, orderByList?: string[]): void;
-    /**
-     * Gets the list of the category values for the chart.
-     * @returns {string[]}
-     */
-    getCustomSortValues(): Promise<string[]>;
-    /**
-     * Sets the data filter for the bar chart.
-     * @param {WebChartDataFilters | undefined} newDataFilter The new data filter.
-     */
-    setDataFilters(newDataFilter: WebChartDataFilters | undefined): Promise<void>;
-    /**
-     * The list of category's values for custom sort
-     */
-    get orderByList(): string[];
-    set orderByList(newOrderByList: string[]);
-    /**
-     * Updates the series based on the layer filter.
-     * @async **This method is `async` and must be awaited for the changes to take effect.*
-     */
-    updateSeriesFromLayerFilter(): Promise<void>;
-    /**
-     * Whether mean lines are shown.
-     */
-    get showMeanLines(): boolean | undefined;
-    set showMeanLines(newShowMeanLines: boolean | undefined);
-    /**
-     * The color of the boxes when showing mean lines. Only applicable when mean lines are shown.
-     */
-    get meanLinesBoxColor(): Color | undefined;
-    set meanLinesBoxColor(newColor: Color | undefined);
-    /**
-     * Sets up the local props based on the current config.
-     * @category Protected
-     */
-    protected setupLocalProps(): void;
-    protected generateDefaultConfig(): Omit<typeof this._config, "iLayer">;
-    /**
-     * Resets the config to the default config
-     */
-    resetConfig(): void;
-    /**
-     * Determines if we can rebuild the series synchronously.
-     * We can call the build new series function synchronously when either is true:
-     * - there is no split-by field
-     * - there are multiple numeric fields
-     * @category Protected
-     */
-    protected canUseSynchronousSeriesRebuild(): boolean;
-    /**
-     * Processes the series rebuild.
-     * If multiple async setters are called in succession, this function will only rebuild the series once after all setters have been called.
-     * @category Protected
-     * @async
-     */
-    protected processSeriesRebuild(): Promise<void>;
-    /**
-     * Gets the properties needed to build a new series array.
-     */
-    private getBuildNewSeriesProps;
-    /**
-     * Gets the name of the series based on the series index. If the index is out of bounds, it will return `undefined`.
-     * @param {number} seriesIndex The index of the series.
-     * @returns {string | undefined}
-     */
-    getSeriesName(seriesIndex: number): string | undefined;
-    /**
-     * Sets name of the series based on the series index.
-     * @param {string} newName The new name for the series.
-     * @param {number} seriesIndex The index of the series.
-     */
-    setSeriesName(newName: string, seriesIndex: number): void;
-    /**
-     * Gets the color of the series based on the series index. If the index is out of bounds, it will return `undefined`.
-     * @param {number} seriesIndex The index of the series.
-     * @returns {Color | undefined}
-     */
-    getSeriesColor(seriesIndex: number): Color | undefined;
-    /**
-     * Sets the color of the series based on the series index.
-     * @param {Color | undefined} newColor The new color for the series.
-     * @param {number} seriesIndex The index of the series.
-     */
-    setSeriesColor(newColor: Color | undefined, seriesIndex: number): void;
-    /**
-     * Gets the line style of the series based on the series index. If the index is out of bounds, it will return `undefined`.
-     *
-     * **Only applicable when mean lines are shown.**
-     *
-     * @param {number} seriesIndex The index of the series.
-     * @returns {RESTSimpleLineSymbolStyle | undefined}
-     */
-    getSeriesLineStyle(seriesIndex: number): RESTSimpleLineSymbolStyle | undefined;
-    /**
-     * Sets the line style of the series based on the series index.
-     *
-     * **Only applicable when mean lines are shown.**
-     *
-     * @param {RESTSimpleLineSymbolStyle | undefined} newStyle The new style for the series.
-     * @param {number} seriesIndex The index of the series.
-     */
-    setSeriesLineStyle(newStyle: RESTSimpleLineSymbolStyle | undefined, seriesIndex: number): void;
-    /**
-     * Gets the line width of the series based on the series index. If the index is out of bounds, it will return `undefined`.
-     *
-     * **Only applicable when mean lines are shown.**
-     *
-     * @param {number} seriesIndex The index of the series.
-     * @returns {number | undefined}
-     */
-    getSeriesLineWidth(seriesIndex: number): number | undefined;
-    /**
-     * Sets the line width of the series based on the series index.
-     *
-     * **Only applicable when mean lines are shown.**
-     *
-     * @param {number | undefined} newWidth The new width for the series.
-     * @param {number} seriesIndex The index of the series.
-     */
-    setSeriesLineWidth(newWidth: number | undefined, seriesIndex: number): void;
-    /**
-     * The order of the series array by returning an array of series ids.
-     */
-    get orderOfSeries(): string[];
-    set orderOfSeries(newOrder: string[]);
-    /**
-     * Moves a series from one index in the series array to another.
-     * @param {number} fromIndex Index to move the series from.
-     * @param {number} toIndex Index to move the series to.
-     */
-    moveSeries(fromIndex: number, toIndex: number): void;
-    /**
-     * The index of the box plot series in the series array in config object when show mean is true.
-     * **Note:** There is only one box plot series when show mean is true. The function returns '-1' if show mean is false.
-     */
-    get boxPlotSeriesIndexWhenMeanLinesShown(): number;
-    /**
-     * Move the custom sort values in-place for the order by list in the config.
-     * **Note:** This method should be only used when the sort order is set to `BoxPlotDataSortingKinds.customSort`.
-     * @param {number} fromIndex The index to move the custom sort item from.
-     * @param {number} toIndex The index to move the category item to.
-     */
-    moveCustomSortValuesInOrderByList(fromIndex: number, toIndex: number): void;
-    /**
-     * Generate the proper chart title given the current config.
-     */
-    generateChartTitle(): string;
-    /**
-     * Generate the proper x-axis title given the current config.
-     *
-     * @returns {string}
-     */
-    generateXAxisTitle(): string;
-    /**
-     * Generate the proper y-axis title given the current config.
-     */
-    generateYAxisTitle(): string;
-    /**
-     * Resets the series styling to the default styling.
-     */
-    resetSeriesStyling(): void;
-    /**
-     * Returns whether the series styling is able to be reset.
-     * @returns {boolean}
-     */
-    resetAvailable(): boolean;
-}
-export interface BoxPlotModel extends ModelWithMultiAxes, ModelWithLegend, ModelWithTooltips, ModelWithColorMatch, ModelWithRotation, ModelWithDataLabels, ModelWithYGuides {
+import type { ChartModel } from "../chart-model/chart-model.js";
+import type { ModelParams } from "../interfaces/chart-interfaces.js";
+import type { ModelTypes, BoxPlotDataSortingKinds } from "../interfaces/common.js";
+import type { WithAxisLabelsSymbol } from "../properties/axes/axis-labels-symbol.js";
+import type { WithAxisLinesSymbol } from "../properties/axes/axis-lines-symbol.js";
+import type { WithXBounds } from "../properties/axes/x-axis/x-bounds.js";
+import type { WithXAxisLabelsVisibility } from "../properties/axes/x-axis/x-axis-labels-visibility.js";
+import type { WithXAxisTitleSymbol } from "../properties/axes/x-axis/x-axis-title-symbol.js";
+import type { WithXAxisTitleText } from "../properties/axes/x-axis/x-axis-title-text.js";
+import type { WithXAxisTitleVisibility } from "../properties/axes/x-axis/x-axis-title-visibility.js";
+import type { WithGenerateXAxisTitle } from "../properties/axes/x-axis/generate-x-axis-title.js";
+import type { WithColorMatch } from "../properties/color-match.js";
+import type { WithRotatedState } from "../properties/rotated-state.js";
+import type { WithDataLabelsVisibility } from "../properties/data-labels/data-labels-visibility.js";
+import type { WithDataLabelsSymbol } from "../properties/data-labels/data-labels-symbol.js";
+import type { MixinInstances } from "../shared/utils.js";
+import type { WebChart, WebChartDataFilters } from "../../spec/web-chart.js";
+import type { Color } from "../../spec/rest-js-types.js";
+import type { RESTSimpleLineSymbolStyle } from "../../spec/rest-js-object-literals.js";
+import type { ChartConfig } from "../../utils/types/index.js";
+import type { XYChartTypes } from "../../utils/misc/index.js";
+import type { ModelWithMultiAxes as ModelWithMultiAxes2 } from "../mixins/model-with-multi-axes.js";
+import type { ModelWithLegend as ModelWithLegend2 } from "../mixins/model-with-legend.js";
+import type { ModelWithTooltips as ModelWithTooltips2 } from "../mixins/model-with-tooltips.js";
+import type { ModelWithYGuides as ModelWithYGuides2 } from "../mixins/model-with-y-guides.js";
+
+export class BoxPlotModel extends ChartModel {
+  /** Internal storage of the category field for the chart. */
+  protected _category: string;
+  protected _chartType: XYChartTypes;
+  /** Current configuration used for the box plot chart. */
+  protected _config: ChartConfig<typeof ModelTypes.BoxPlot, WebChart>;
+  /** Internal storage of the numeric fields for the chart. */
+  protected _numericFields: string[];
+  /**
+   * Internal storage of the split-by field for the chart.
+   *
+   * @default ""
+   */
+  protected _splitByField: string;
+  /**
+   * The index of the box plot series in the series array in config object when show mean is true.
+   *
+   * **Note**: There is only one box plot series when show mean is true. The function returns '-1' if show mean is false.
+   */
+  get boxPlotSeriesIndexWhenMeanLinesShown(): number;
+  /** The category field for the box plot. */
+  accessor category: string;
+  /** The color of the boxes when showing mean lines. Only applicable when mean lines are shown. */
+  accessor meanLinesBoxColor: Color | undefined;
+  /** The numeric fields array for the box plot. */
+  get numericFields(): string[];
+  set numericFields(value: string[] | string);
+  /** The list of category's values for custom sort */
+  accessor orderByList: string[];
+  /** The order of the series array by returning an array of series ids. */
+  accessor orderOfSeries: string[];
+  /** Whether mean lines are shown. */
+  accessor showMeanLines: boolean | undefined;
+  /** Whether outliers are shown. */
+  accessor showOutliers: boolean;
+  /** The split-by field for the box plot. */
+  accessor splitByField: string;
+  /** Whether values are standardized as z-scores. */
+  accessor standardizeValues: boolean;
+  /**
+   * Determines if we can rebuild the series synchronously.
+   * We can call the build new series function synchronously when either is true:
+   * - there is no split-by field
+   * - there are multiple numeric fields
+   */
+  protected canUseSynchronousSeriesRebuild(): boolean;
+  /** Generate the proper chart title given the current config. */
+  generateChartTitle(): string;
+  protected generateDefaultConfig(): Omit<ChartConfig<"boxPlot", WebChart>, "iLayer">;
+  /** Generate the proper y-axis title given the current config. */
+  generateYAxisTitle(): string;
+  /** Gets the list of the category values for the chart. */
+  getCustomSortValues(): Promise<string[]>;
+  /**
+   * Gets the color of the series based on the series index. If the index is out of bounds, it will return `undefined`.
+   *
+   * @param seriesIndex - The index of the series.
+   */
+  getSeriesColor(seriesIndex: number): Color | undefined;
+  /**
+   * Gets the line style of the series based on the series index. If the index is out of bounds, it will return `undefined`.
+   *
+   * **Note**: Only applicable when mean lines are shown.
+   *
+   * @param seriesIndex - The index of the series.
+   */
+  getSeriesLineStyle(seriesIndex: number): RESTSimpleLineSymbolStyle | undefined;
+  /**
+   * Gets the line width of the series based on the series index. If the index is out of bounds, it will return `undefined`.
+   *
+   * **Note**: Only applicable when mean lines are shown.
+   *
+   * @param seriesIndex - The index of the series.
+   */
+  getSeriesLineWidth(seriesIndex: number): number | undefined;
+  /**
+   * Gets the name of the series based on the series index. If the index is out of bounds, it will return `undefined`.
+   *
+   * @param seriesIndex - The index of the series.
+   */
+  getSeriesName(seriesIndex: number): string | undefined;
+  /** Gets the sort order of the box plot data. */
+  getSortOrder(): BoxPlotDataSortingKinds;
+  /**
+   * Move the custom sort values in-place for the order by list in the config.
+   *
+   * **Note**: This method should be only used when the sort order is set to `BoxPlotDataSortingKinds.customSort`.
+   *
+   * @param fromIndex - The index to move the custom sort item from.
+   * @param toIndex - The index to move the category item to.
+   */
+  moveCustomSortValuesInOrderByList(fromIndex: number, toIndex: number): void;
+  /**
+   * Moves a series from one index in the series array to another.
+   *
+   * @param fromIndex - Index to move the series from.
+   * @param toIndex - Index to move the series to.
+   */
+  moveSeries(fromIndex: number, toIndex: number): void;
+  /**
+   * Processes the series rebuild.
+   * If multiple async setters are called in succession, this function will only rebuild the series once after all setters have been called.
+   *
+   * @async
+   */
+  protected processSeriesRebuild(): Promise<void>;
+  /** Returns whether the series styling is able to be reset. */
+  resetAvailable(): boolean;
+  /** Resets the config to the default config */
+  resetConfig(): void;
+  /** Resets the series styling to the default styling. */
+  resetSeriesStyling(): void;
+  /**
+   * Sets the data filter for the bar chart.
+   *
+   * @param newDataFilter - The new data filter.
+   */
+  setDataFilters(newDataFilter: WebChartDataFilters | undefined): Promise<void>;
+  /**
+   * Sets the color of the series based on the series index.
+   *
+   * @param newColor - The new color for the series.
+   * @param seriesIndex - The index of the series.
+   */
+  setSeriesColor(newColor: Color | undefined, seriesIndex: number): void;
+  /**
+   * Sets the line style of the series based on the series index.
+   *
+   * **Note**: Only applicable when mean lines are shown.
+   *
+   * @param newStyle - The new style for the series.
+   * @param seriesIndex - The index of the series.
+   */
+  setSeriesLineStyle(newStyle: RESTSimpleLineSymbolStyle | undefined, seriesIndex: number): void;
+  /**
+   * Sets the line width of the series based on the series index.
+   *
+   * **Note**: Only applicable when mean lines are shown.
+   *
+   * @param newWidth - The new width for the series.
+   * @param seriesIndex - The index of the series.
+   */
+  setSeriesLineWidth(newWidth: number | undefined, seriesIndex: number): void;
+  /**
+   * Sets name of the series based on the series index.
+   *
+   * @param newName - The new name for the series.
+   * @param seriesIndex - The index of the series.
+   */
+  setSeriesName(newName: string, seriesIndex: number): void;
+  /**
+   * Sets the sort order of the box plot data.
+   *
+   * @param newSortOrder - The new sort order.
+   * @param orderByList - The new list of category's values for custom sort.
+   */
+  setSortOrder(newSortOrder: BoxPlotDataSortingKinds, orderByList?: string[]): void;
+  /** @param params */
+  setup(params: ModelParams<ChartConfig<typeof ModelTypes.BoxPlot>>): Promise<void>;
+  /** Sets up the local props based on the current config. */
+  protected setupLocalProps(): void;
+  /**
+   * Updates the series based on the layer filter.
+   *
+   * @async **This method is `async` and must be awaited for the changes to take effect.*
+   */
+  updateSeriesFromLayerFilter(): Promise<void>;
 }
+
+export interface BoxPlotModel extends MixinInstances<typeof boxPlotMixins> {}
+
+export const boxPlotMixins: readonly [
+    typeof ModelWithMultiAxes2,
+    typeof ModelWithLegend2,
+    typeof ModelWithTooltips2,
+    typeof WithColorMatch,
+    typeof WithRotatedState,
+    typeof WithDataLabelsVisibility,
+    typeof WithDataLabelsSymbol,
+    typeof ModelWithYGuides2,
+    typeof WithXAxisTitleText,
+    typeof WithXAxisLabelsVisibility,
+    typeof WithXAxisTitleVisibility,
+    typeof WithXBounds,
+    typeof WithXAxisTitleSymbol,
+    typeof WithAxisLabelsSymbol,
+    typeof WithAxisLinesSymbol,
+    typeof WithGenerateXAxisTitle
+];

package/dist/model/chart-model/chart-model-base.d.ts

@@ -0,0 +1,80 @@
+import type { ModelParams } from "../interfaces/chart-interfaces.js";
+import type { LayerInfo, ModelTypes } from "../interfaces/common.js";
+import type { ChartModel } from "./chart-model.js";
+import type { ChartConfig } from "../../utils/types/index.js";
+import type { CommonStrings } from "../../utils/localization/interfaces.js";
+import type { ChartTypes } from "../../utils/misc/index.js";
+
+export abstract class ChartModelBase extends EventTarget {
+  /** Chart type. */
+  protected _chartType: ChartTypes;
+  /** Current configuration used for the chart. */
+  protected _config: ChartConfig;
+  /**
+   * Whether or not an async series update is currently in progress.
+   *
+   * @default false
+   */
+  protected asyncConfigUpdateInProgress: boolean;
+  /**
+   * Promise that resolves when the setup process is complete.
+   *
+   * **Note:** This promise does not need to be awaited if the `setup` method has already been awaited. It is simply provided as a way to await the setup process from other functions if needed to avoid race conditions.
+   */
+  asyncUpdatesPromise: Promise<void>;
+  /** The chart type. */
+  get chartType(): ChartTypes;
+  /** Common strings used in the model. */
+  protected commonStrings: CommonStrings;
+  /** Data store object that can be used to store any data needed for the chart. */
+  dataStore: any;
+  /** List of setters (either props or methods) that have been changed and will require an async series rebuild. */
+  protected dirtyAsyncSetters: string[];
+  /** Emits a config update event. */
+  protected emitConfigUpdate: (setterName: string) => void;
+  /**
+   * Guards a setter from being called while an async config update is in progress so that the value being set is not overwritten by the async config update.
+   *
+   * @param setter - The setter callback to call after setup or async config update is finished.
+   */
+  protected guardSetterFromAsyncOverwrite: (setter: (() => Promise<void>) | (() => void)) => Promise<void>;
+  /** Grouping of layer-related properties to be passed to external function more compactly. */
+  protected layerInfo: LayerInfo;
+  /**
+   * Number of pending async updates.
+   *
+   * @default 0
+   */
+  protected pendingUpdates: number;
+  /** Function that resolves the setup promise. */
+  protected resolveSetup?: () => void;
+  /** Manually unblock the async guard to allow queued config updates to proceed. */
+  protected finishAsyncUpdate(): void;
+  /** Generate the proper chart title from the current config. */
+  abstract generateChartTitle(): string;
+  /** A function that generates the default config object when creating a new chart. */
+  protected abstract generateDefaultConfig(): Omit<ChartConfig, "iLayer">;
+  /**
+   * Checks if the current chart model is for the same chart as another chart model.
+   *
+   * @param otherModel - The other chart model to compare to.
+   */
+  isSameChartAs(otherModel: ChartModel | undefined): boolean;
+  /**
+   * A function that loads the config based on the provided props.
+   *
+   * @param params - The layer to be used as the data source for the chart.
+   */
+  protected loadConfigFromLayer<T extends ModelTypes>(params: ModelParams<ChartConfig<T>>): Promise<void>;
+  /**
+   * Completes the async setup process for the chart model. Must be called before using the model.
+   *
+   * @param params - The parameters to be used to set up the chart model.
+   * @async **This method is `async` and must be awaited for the changes to take effect.**
+   */
+  abstract setup(params: ModelParams<ChartConfig>): Promise<void>;
+  /** Manually block the async guard to queue up config updates until unblocked. */
+  protected startAsyncUpdate(): void;
+  /** Can be awaited to allow any pending async updates to complete. */
+  update(): Promise<void>;
+}