@adaptabletools/adaptable/src/AdaptableState/StyledColumns/BulletChartStyle.d.ts

Powerful AG Grid extension which provides advanced, cutting-edge functionality to meet all DataGrid requirements

import { CellFontStyle } from '../Common/AdaptableStyle';
import { BarStyleCellTextProperties } from './Common/BarStyleProperties';
import { BarStyleMarker } from './Common/BarStyleProperties';
import { CellTextOptions } from './Common/CellTextOptions';
import { NumericStyledColumn } from './Common/NumericStyledColumn';
/**
 * Style used to display a Bullet Chart in a Styled Column.
 *
 * A Bullet Chart shows three things in a single cell:
 *   1. the actual cell value, as a horizontal bar (the "feature measure")
 *   2. a target value, as a marker on the bar (the "comparative measure")
 *   3. optional qualitative bands behind the bar (e.g. poor / ok / good),
 *      defined via the inherited `CellRanges` property
 *
 * Note: Unlike `PercentBarStyle.CellRanges` (which colour the bar based on
 * the cell value), `BulletChartStyle.CellRanges` colour the *background*
 * bands and are drawn unconditionally to provide the qualitative scale.
 */
export interface BulletChartStyle extends NumericStyledColumn {
    /**
     * Target value(s) rendered as marker(s) on the bar, plus the chart-level
     * default marker style. Per-target overrides are possible via the
     * {@link BulletChartTargetDefinition} object form.
     */
    TargetProperties?: BulletChartTargetProperties;
    /**
     * Visual properties of the actual (foreground) bar — colour and thickness.
     */
    Bar?: BulletChartBarProperties;
    /**
     * Orientation of the chart.
     *
     * - `'Horizontal'` (default) - bands and bar run left-to-right; markers
     *   are vertical lines / shapes positioned along the x-axis.
     * - `'Vertical'` - bands and bar run bottom-to-top; markers are
     *   horizontal lines / shapes positioned along the y-axis.
     *
     * Note: vertical bullet charts need a tall row height to be readable
     * (we recommend at least 60px). AG Grid row height is a per-grid setting
     * (`gridOptions.rowHeight` or `getRowHeight`).
     *
     * @defaultValue 'Horizontal'
     */
    Orientation?: 'Horizontal' | 'Vertical';
    /**
     * Background colour for the chart area when no `CellRanges` are supplied.
     */
    BackColor?: string;
    /**
     * Origin of the actual bar.
     *
     * - `'Auto'` (default) - the bar grows from the left edge unless any cell
     *   value or range endpoint is negative, in which case it grows from `0`
     * - `'Zero'` - the bar always grows from `0` (centred axis); positive
     *   values extend right, negative values extend left
     * - any number - the bar grows from that fixed origin
     *
     * @defaultValue 'Auto'
     */
    Origin?: 'Auto' | 'Zero' | number;
    /**
     * Optional cell-text overlay configuration.
     */
    CellTextProperties?: BarStyleCellTextProperties;
    /**
     * Tooltip content - same tokens (`'CellValue'`, `'PercentageValue'`) as
     * Percent Bar.
     */
    ToolTipText?: CellTextOptions;
    /**
     * Optional cell-text styling (colour, weight, font, alignment, …) applied
     * by the Bullet Chart renderer to the optional `CellText` overlay.
     *
     * When set, this property "claims" the Font slice for the column: any
     * Format Column matching this column has its Font properties stripped.
     * When unset, Format Column Font properties inherit through normally.
     */
    Font?: CellFontStyle;
}
/**
 * Visual properties of the foreground bar in a Bullet Chart.
 */
export interface BulletChartBarProperties {
    /**
     * Colour of the actual (foreground) bar drawn on top of any bands.
     *
     * @defaultValue 'var(--ab-color-primary)'
     */
    Color?: string;
    /**
     * Height of the actual bar in px (the bands sit a few px taller behind it).
     *
     * For vertical orientation this is interpreted as the bar's *width*
     * (i.e. its short axis); the long axis stretches to fit the cell.
     *
     * @defaultValue 8
     */
    Height?: number;
}
/**
 * Target configuration for a Bullet Chart — the resolved target value(s)
 * plus the chart-level default marker style.
 */
export interface BulletChartTargetProperties {
    /**
     * Target value(s) rendered as marker(s) on the bar.
     *
     * Each Target can be:
     *  - `number` - a fixed target value
     *  - `string` - a column id; the row's value in that column is used as the target
     *  - `'Col-Avg'` | `'Col-Median'` - computed across visible rows
     *
     * Pass an array to render multiple targets (e.g. primary + stretch goal).
     */
    Target?: BulletChartTarget | BulletChartTarget[];
    /**
     * Visual style of the target marker(s).
     *
     * When `Target` is an array, this style applies to all markers; pass a
     * `Target` object with its own `Marker` property to override per-marker.
     */
    Marker?: BarStyleMarker;
}
/**
 * A single Bullet Chart target. Either a primitive resolvable value (number /
 * column id / `Col-Avg` / `Col-Median`) or a richer object that lets a single
 * target override the default marker styling.
 */
export type BulletChartTarget = number | string | 'Col-Avg' | 'Col-Median' | BulletChartTargetDefinition;
/**
 * Object form of a Bullet Chart target, used when a single target needs to
 * override the chart-level marker styling.
 */
export interface BulletChartTargetDefinition {
    /**
     * Resolvable value: number, column id, `Col-Avg` or `Col-Median`.
     */
    Value: number | string | 'Col-Avg' | 'Col-Median';
    /**
     * Per-target marker override. Falls back to `BulletChartTargetProperties.Marker`.
     */
    Marker?: BarStyleMarker;
    /**
     * Optional label displayed in the tooltip alongside the marker value.
     */
    Label?: string;
}