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

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

import { BarStyleCellTextProperties } from './Common/BarStyleProperties';
import { BarStyleMarker } from './Common/BarStyleProperties';
import { CellTextOptions } from './Common/CellTextOptions';
import { DynamicRangeEndpoint, NumericStyledColumn } from './Common/NumericStyledColumn';
/**
 * Resolvable value used by a Range Bar's `Min`, `Max` or `Reference.Value`.
 *
 * - `number` — a hard-coded value
 * - `string` — a column id; the row's value in that column is used
 * - `'Col-Min' | 'Col-Max' | 'Col-Avg' | 'Col-Median'` — a column-wide
 *   aggregate computed across visible rows
 */
export type RangeBarBound = number | string | DynamicRangeEndpoint;
/**
 * Configures a Range Bar Styled Column.
 *
 * A Range Bar shows where a row's value sits inside a per-row (or
 * column-wide) numeric range. The range endpoints (`Min` / `Max`) are
 * resolved per row — they can be hard-coded numbers, the value of another
 * column on the same row, or a column-wide aggregate (`Col-Min`, `Col-Max`,
 * `Col-Avg`, `Col-Median`).
 *
 * Common scenarios:
 *  - Stock price relative to its 52-week low / 52-week high
 *  - Today's value relative to bid / ask quotes
 *  - Forecast within an upper / lower confidence interval
 *  - Measured value within an SLA `[lowerBound, upperBound]`
 *
 * Visually the cell renders as a thin track between `Min` and `Max`, with
 * a marker at the cell value. An optional `Reference` value renders as a
 * second marker (e.g. previous close, target, midpoint).
 *
 * Background bands (`CellRanges`) are drawn behind the track using the same
 * conventions as Bullet Chart, and are useful for qualitative scales such
 * as poor / acceptable / good (or red / amber / green SLA bands).
 */
export interface RangeBarStyle extends NumericStyledColumn {
    /**
     * Lower bound of the track for each row.
     *
     * Can be:
     *  - `number` — a fixed lower bound shared by every row
     *  - `string` — a column id; the row's value in that column is used
     *  - `'Col-Min' | 'Col-Max' | 'Col-Avg' | 'Col-Median'` — a column-wide
     *    aggregate computed across the visible rows
     */
    Min: RangeBarBound;
    /**
     * Upper bound of the track for each row.
     *
     * See `Min` for the supported value forms.
     */
    Max: RangeBarBound;
    /**
     * Optional reference value (e.g. previous close, target, midpoint) drawn
     * as a *second* marker on the track, together with its marker styling.
     * Leave unset to draw only the cell-value marker.
     */
    Reference?: RangeBarReferenceProperties;
    /**
     * Visual style of the cell-value marker.
     *
     * @defaultValue `{ Shape: 'Diamond', Color: 'var(--ab-color-accent)', Size: 8 }`
     */
    Marker?: BarStyleMarker;
    /**
     * Behaviour when the cell value falls outside `[Min, Max]`, plus the
     * optional marker colour override used by `Mode: 'Clamp'`.
     *
     * Defaults to `{ Mode: 'Clamp' }` when omitted.
     */
    OutOfRange?: RangeBarOutOfRangeProperties;
    /**
     * Visual properties of the track (the line representing the `[Min, Max]`
     * interval).
     */
    Track?: RangeBarTrackProperties;
    /**
     * Background colour for the chart area when no `CellRanges` are supplied.
     */
    BackColor?: string;
    /**
     * Orientation of the range bar.
     *
     * @defaultValue `'Horizontal'`
     */
    Orientation?: 'Horizontal' | 'Vertical';
    /**
     * Optional cell-text overlay configuration.
     */
    CellTextProperties?: BarStyleCellTextProperties;
    /**
     * Tooltip content — same tokens (`'CellValue'`, `'PercentageValue'`)
     * as Percent Bar / Bullet Chart.
     */
    ToolTipText?: CellTextOptions;
}
/**
 * Optional reference value drawn as a *second* marker on a Range Bar track,
 * together with its marker styling.
 */
export interface RangeBarReferenceProperties {
    /**
     * Resolvable reference value (number / column id / `'Col-Min' | 'Col-Max'
     * | 'Col-Avg' | 'Col-Median'`). Same forms as `RangeBarStyle.Min` / `Max`.
     */
    Value: RangeBarBound;
    /**
     * Visual style of the reference marker.
     *
     * @defaultValue `{ Shape: 'Line', Color: 'var(--ab-color-foreground)', Size: 2 }`
     */
    Marker?: BarStyleMarker;
}
/**
 * Out-of-range behaviour for a Range Bar.
 */
export interface RangeBarOutOfRangeProperties {
    /**
     * Behaviour when the cell value falls outside `[Min, Max]`.
     *
     * - `'Clamp'` (default) — clamp the marker to the nearest end of the
     *   track and (optionally) re-colour it via `Color`
     * - `'Overflow'` — draw the marker outside the track at its true position
     * - `'Hide'` — omit the cell-value marker entirely
     *
     * @defaultValue `'Clamp'`
     */
    Mode?: 'Clamp' | 'Overflow' | 'Hide';
    /**
     * Marker colour override applied when the cell value is out of range
     * (only used with `Mode: 'Clamp'`). Useful to draw attention to
     * "off-scale" rows.
     */
    Color?: string;
}
/**
 * Visual properties of the Range Bar track (the line representing the
 * `[Min, Max]` interval).
 */
export interface RangeBarTrackProperties {
    /**
     * Track colour.
     *
     * @defaultValue 'var(--ab-color-foreground, #999)' at low alpha
     */
    Color?: string;
    /**
     * Track thickness in px (the *short* axis — height in horizontal,
     * width in vertical).
     *
     * @defaultValue 4
     */
    Height?: number;
}