ag-charts-community/dist/types/src/chart/legend/legendDatum.d.ts

Advanced Charting / Charts supporting Javascript / Typescript / React / Angular / Vue

import { type ColorScaleState, type GradientColorStop, type NormalisedTextOrSegments, type PluginModuleInstance } from 'ag-charts-core';
import type { AgChartLegendListeners, AgColorScaleColorStop, AgMarkerShape } from 'ag-charts-types';
import type { ColorScale } from '../../scale/colorScale';
import type { Scene } from '../../scene/scene';
import type { FormatManager, GlobalContextFormatter } from '../formatter/formatManager';
import type { LegendSymbolOptions } from './legendSymbol';
export interface ChartLegend extends PluginModuleInstance {
    attachLegend(scene: Scene): void;
    destroy(): void;
    data: any;
    listeners?: AgChartLegendListeners;
    pagination?: {
        currentPage: number;
        setPage: (pageNumber: number) => void;
    };
}
export type ChartLegendType = 'category' | 'gradient';
export type ChartLegendDatum<T extends ChartLegendType> = T extends 'category' ? CategoryLegendDatum : T extends 'gradient' ? GradientLegendDatum : never;
export interface BaseChartLegendDatum {
    legendType: ChartLegendType;
    seriesId: string;
    enabled: boolean;
    hideInLegend?: boolean;
}
export interface CategoryLegendDatum extends BaseChartLegendDatum {
    legendType: 'category';
    id: string;
    itemId: string | number;
    datum?: any;
    symbol: LegendSymbolOptions;
    /** Optional deduplication id - used to coordinate synced toggling of multiple items. */
    legendItemName?: string;
    label: {
        text: NormalisedTextOrSegments;
    };
    skipAnimations?: boolean;
    isFixed?: boolean;
    hideToggleOtherSeries?: true;
    /**
     * When true, hovering or clicking this legend item must not drive the series highlight.
     * Used by discrete colour-scale bin items whose `itemId` is a bin index, not a datum index,
     * so feeding it through the highlight pipeline would either un-highlight everything
     * (heatmap/map series) or throw (hierarchy series whose `datumIndex` is a path array).
     */
    suppressHighlight?: true;
}
interface FormatterBoundSeries {
    /** ID of the series for values on the related axis. */
    seriesId: string;
    /** Key used by the series for values on the related axis. */
    key: string;
    /** Optional name used by the series for values on the related axis. */
    name?: string;
}
export interface GradientLegendNamedLabel {
    /** Normalised position [0, 1] along the gradient bar. */
    position: number;
    /** Display label for this position. */
    label: string;
}
export interface GradientLegendDatum extends BaseChartLegendDatum {
    legendType: 'gradient';
    enabled: boolean;
    seriesId: string;
    series: FormatterBoundSeries[];
    colorStops: GradientColorStop[];
    axisDomain: [number, number];
    namedLabels?: GradientLegendNamedLabel[];
    /** When true, render as a separate gradient bar even when other gradient datums exist. */
    showSeparately?: boolean;
}
/**
 * Builds a gradient legend datum from a configured ColorScale, deriving
 * normalised colour stops from its domain/range/mode. Takes the concrete
 * `ColorScale` so the visible slice of the gradient can be sampled at
 * the display-domain edges via `colorScale.convert()`.
 */
export declare function buildGradientLegendDatum(colorScale: ColorScale, fills: AgColorScaleColorStop[], seriesId: string, enabled: boolean, series: FormatterBoundSeries[]): GradientLegendDatum;
/**
 * Context required to format discrete-bin colour-scale legend labels through
 * the chart-level `formatter.color` pipeline. Built once per legend update by
 * the caller (the series), then handed to `buildColorCategoryLegendData`.
 */
export interface ColorScaleLegendFormatterContext {
    formatManager: FormatManager;
    formatInContext: GlobalContextFormatter;
    /** The colour-key of the series, surfaced to user formatters as `params.key`. */
    key: string | undefined;
    /** The legendItemName of the series, surfaced to user formatters as `params.legendItemName`. */
    legendItemName: string | undefined;
    /** The series formatter-context (`series.getFormatterContext('color')`), surfaced as `params.boundSeries`. */
    boundSeries: FormatterBoundSeries[];
}
/**
 * Minimal shape any colour-scale series exposes that lets us pull together a
 * `ColorScaleLegendFormatterContext` without the caller hand-packing the same
 * five fields at every site. Defined structurally so it composes with both
 * community and enterprise `Series` subclasses without an import cycle.
 */
interface ColorScaleSeries {
    readonly properties: {
        colorKey?: string;
        legendItemName?: string;
    };
    readonly ctx: {
        formatManager: FormatManager;
    };
    callWithContext: GlobalContextFormatter;
    getFormatterContext(property: 'color'): FormatterBoundSeries[];
}
/**
 * Pulls together the formatter context for a colour-scale legend from a
 * series instance. Used by every series that supports
 * `colorScale.mode === 'discrete'`. Replaces the previous per-call-site
 * boilerplate that packed the same five fields by hand.
 */
export declare function colorScaleLegendFormatterContext(series: ColorScaleSeries): ColorScaleLegendFormatterContext;
/**
 * Builds category legend data for a discrete colour scale, deriving bin
 * boundaries on the fly from the ColorScale's domain/range state. Bin labels
 * are formatted through the chart-level formatter pipeline supplied by
 * `formatterContext` (see `ColorScaleLegendFormatterContext`).
 */
export declare function buildColorCategoryLegendData(colorScale: ColorScaleState, fills: AgColorScaleColorStop[], seriesId: string, enabled: boolean, formatterContext: ColorScaleLegendFormatterContext, shape?: AgMarkerShape): CategoryLegendDatum[];
export {};