@adaptabletools/adaptable 22.1.1 → 23.0.0-canary.1

package/src/AdaptableState/StyledColumnState.d.ts

@@ -1,5 +1,6 @@
 import { BaseState } from './BaseState';
-import { AdaptablePredicate, AdaptableStyle, AdaptableBooleanQuery, AdaptableIcon } from '../types';
+import { AdaptablePredicate, AdaptableBooleanQuery, AdaptableIcon } from '../types';
+import { CellBoxStyle, CellFontStyle } from './Common/AdaptableStyle';
 import { TypeHint } from './Common/Types';
 import { RowScope } from './Common/RowScope';
 import { AgSparklineOptions } from 'ag-charts-types';
@@ -9,18 +10,26 @@ import { SuspendableObject } from './Common/SuspendableObject';
  */
 export interface StyledColumnState extends BaseState {
     /**
-     * Collection of Special Column Styles
+     * Collection of Styled Columns
      */
     StyledColumns?: StyledColumn[];
 }
 /**
- * Object used in Special Column Style function
+ * Core Styled Column object
  */
 export interface StyledColumn extends SuspendableObject {
     /**
-     * Column being styled
+     * Unique Name of Styled Column - used to identify it in Adaptable UI and APIs
+     */
+    Name: string;
+    /**
+     * Id of Column being styled
      */
     ColumnId: string;
+    /**
+     * Which rows will render the Styled Column (data / group / summary total)
+     */
+    RowScope?: RowScope;
     /**
      * Styles a numeric column with a Gradient
      */
@@ -37,6 +46,22 @@ export interface StyledColumn extends SuspendableObject {
      * Displays cell values in Column as a Badge
      */
     BadgeStyle?: BadgeStyle;
+    /**
+     * Styles a numeric column with single-row Bullet Chart, showing value as bar, target as marker and optional bands behind bar
+     */
+    BulletChartStyle?: BulletChartStyle;
+    /**
+     * Styles a numeric column as a Rating - row of icons filled according to cell value
+     */
+    RatingStyle?: RatingStyle;
+    /**
+     * Styles a numeric column as Range Bar - track showing where cell value sits between Min and Max
+     */
+    RangeBarStyle?: RangeBarStyle;
+    /**
+     * Styles a column where each cell displays an icon looked up from a list of key → icon mappings
+     */
+    IconStyle?: IconStyle;
 }
 /**
  * Style used to display Percent Bars in Special Column Style
@@ -47,10 +72,14 @@ export interface PercentBarStyle extends NumericStyledColumn {
      */
     CellText?: CellTextOptions;
     /**
-     * Position of text in Cell relative to Percent Bar, "Above", "Below" or "Merged"
+     * Position of Cell text relative to Percent Bar, "Above", "Below" or "Merged"
      * @defaultValue Below
      */
     CellTextPosition?: 'Above' | 'Below' | 'Merged';
+    /**
+     * Horizontal alignment of the Percent Bar cell text (`CellText`).
+     */
+    CellTextAlignment?: 'Auto' | 'Left' | 'Right' | 'Center';
     /**
      * Whether Tooltip shows Cell Value, Percent Value, both or none
      */
@@ -60,6 +89,16 @@ export interface PercentBarStyle extends NumericStyledColumn {
      * @defaultValue undefined
      */
     BackColor?: string;
+    /**
+     * Origin of the bar - i.e. the value the bar grows from Auto, Zero, Min or fixed number
+     *
+     * @defaultValue 'Auto'
+     */
+    Origin?: 'Auto' | 'Zero' | 'Min' | number;
+    /**
+     * Optional cell-text styling applied to `CellText` overlay
+     */
+    Font?: CellFontStyle;
 }
 /**
  * Base type for Numeric Styled Columns (i.e. Gradient and Percent Bar)
@@ -80,28 +119,79 @@ export interface NumericStyledColumn {
     RangeValueType?: RangeValueType;
 }
 /**
- * Used to display Gradient Styles in Special Column Style
+ * Colours for a zero-centred diverging gradient: negative and positive bands that meet at `0`
+ */
+export interface GradientZeroCentredColors {
+    /**
+     * Colour applied to negative cell values (`Col-Min`…`0`)
+     */
+    NegativeColor: string;
+    /**
+     * Colour applied to positive cell values (`0`…`Col-Max`)
+     */
+    PositiveColor: string;
+}
+/**
+ * Used to display Gradient Styles
  */
 export interface GradientStyle extends NumericStyledColumn {
+    /**
+     * Zero-centred diverging gradient (`Col-Min`…`0` and `0`…`Col-Max`
+     */
+    ZeroCentred?: GradientZeroCentredColors;
+    /**
+     * Alpha (0–1) at **low** end of the matched range’s scale
+     *
+     * @defaultValue 0.15 (faint at range min)
+     */
+    MinAlpha?: number;
+    /**
+     * Alpha (0–1) at  **high** end of the matched range’s scale
+     * @defaultValue 1 (fully opaque at range max)
+     */
+    MaxAlpha?: number;
+    /**
+     * When true, sets cell `color` from tinted background so text stays readable
+     */
+    AutoContrastText?: boolean;
+    /**
+     * Optional AG Grid tooltip content: cell value and/or position along the range scale (%)
+     */
+    ToolTipText?: CellTextOptions;
+    /**
+     * Optional cell-text styling applied by Gradient renderer **on top of** gradient background tint
+     */
+    Font?: CellFontStyle;
 }
 /**
- * Defines which Colours to show in Gradient and Percent Bar Styles
+ * Symbolic range endpoints that resolve to a value computed across column's visible rows (rather than hard-coded number): Col-Min, Col-Max, Col-Avg, Col-Median
+ */
+export type DynamicRangeEndpoint = 'Col-Min' | 'Col-Max' | 'Col-Avg' | 'Col-Median';
+/**
+ * Defines Colours to show in Gradient, Percent Bar and Bullet Chart Styles
  */
 export interface CellColorRange {
     /**
-     * Start number of Range
+     * Start of Range, can be literal number or DynamicRangeEndpoint
      */
-    Min: number | 'Col-Min';
+    Min: number | DynamicRangeEndpoint;
     /**
-     * End number of Range
+     * End of Range, can be literal number or DynamicRangeEndpoint
      */
-    Max: number | 'Col-Max';
+    Max: number | DynamicRangeEndpoint;
     /**
      * Cell colour to use for values that fall inside Range
      */
     Color: string;
     /**
-     * Reverses the Gradient so the lower the cell value the darker the colour
+     * Reverses the alpha ramp **within this range only** — values at the *low*
+     * end render saturated, values at the *high* end render faint.
+     *
+     * Useful as a Gradient Style option when the natural reading is
+     * "lower-is-darker" (e.g. lower trade IDs are older / more important, so
+     * deserve more visual emphasis than newer ones).
+     *
+     * Only honoured by Gradient Style.
      */
     ReverseGradient?: boolean;
 }
@@ -137,12 +227,132 @@ export type RangeValueType = 'Number' | 'Percentage';
 /**
  * Style to show for a Sparkline Column
  */
-export type SparklineStyle = {
+export interface SparklineStyle {
     /**
      * AG Grid Sparkline Options
      */
     options?: AgSparklineOptions;
-};
+    /**
+     * Optional cell box styling (background colour, border, border radius)
+     * applied to the cell behind the sparkline chart.
+     *
+     * When set, this property "claims" the Cell slice for the column: any
+     * Format Column matching this column has its Cell-box properties stripped.
+     * When unset, Format Column Cell properties inherit through normally —
+     * useful for letting a row's themed background show through behind the
+     * sparkline.
+     */
+    Cell?: CellBoxStyle;
+}
+/**
+ * Icon used by a Rating Style
+ */
+export type RatingIconShape = 'Star' | 'Heart' | 'Circle' | 'Thumb';
+/**
+ * Styles a numeric column as a row of icons whose fill represents the
+ * cell value on a 0..`Max` scale.
+ *
+ * Conceptually similar to a Percent Bar but with a discrete, instantly
+ * legible visual idiom (★★★☆☆) commonly used for ratings, satisfaction
+ * scores and review-style cells.
+ *
+ * The cell value is clamped to `[0, Max]`. When `AllowHalf` is true (the
+ * default) the icon at the boundary is rendered with a partial fill that
+ * matches the fractional part of the value; otherwise the value is
+ * rounded to the nearest whole icon.
+ */
+export interface RatingStyle {
+    /**
+     * Number of icons per cell **and** the upper bound of the rating scale,
+     * in the **same numeric units as the cell value**.
+     *
+     * The renderer clamps the cell value to `[0, Max]` and maps that number
+     * directly to filled icons (e.g. `Max: 5` and value `4` → four units of
+     * fill across five icons — roughly four stars, not “4 out of 10 scaled
+     * to five stars”). Values above `Max` show as fully filled; values below
+     * `0` show as empty.
+     *
+     * To show a 1–10 score as five stars, use a calculated column (e.g.
+     * `value / 2`) or set `Max` to match your data range (e.g. `Max: 10`
+     * for ten icons), unless a future `ScaleMin` / `ScaleMax` option is added.
+     *
+     * @defaultValue 5
+     */
+    Max?: number;
+    /**
+     * Icon used for each rating mark.
+     *
+     * @defaultValue 'Star'
+     */
+    Icon?: RatingIconShape;
+    /**
+     * Fill colour for the active (filled) portion of the rating.
+     *
+     * @defaultValue 'var(--ab-color-warn, #f5a623)' — a warm amber that
+     * reads well on both light and dark themes.
+     */
+    FilledColor?: string;
+    /**
+     * Outline / fill colour for the inactive portion of the rating.
+     *
+     * Drawn as a subtle background icon so the user can see the maximum
+     * possible rating at a glance even when the cell value is low.
+     *
+     * @defaultValue a low-opacity tint of the current text colour.
+     */
+    EmptyColor?: string;
+    /**
+     * Icon size in pixels (each icon is square). The renderer keeps the
+     * row of icons vertically centred regardless of cell height.
+     *
+     * @defaultValue 14
+     */
+    Size?: number;
+    /**
+     * Pixel gap between adjacent icons.
+     *
+     * @defaultValue 2
+     */
+    Gap?: number;
+    /**
+     * Controls **partial icons** for fractional values after clamping to
+     * `[0, Max]` — not scaling between different ranges (e.g. 10-point vs
+     * 5-star).
+     *
+     * When `true`, the decimal part fills part of the next icon (e.g. `3.5`
+     * with `Max: 5` → three full icons + one half-filled + one empty).
+     * When `false`, the clamped value is rounded with `Math.round` before
+     * drawing, so only whole icons appear.
+     *
+     * @defaultValue true
+     */
+    AllowHalf?: boolean;
+    /**
+     * When `true`, the numeric cell value is also displayed alongside the
+     * icons (e.g. `★★★★☆ 4.2`). Useful when precise scores matter beyond
+     * the visual approximation.
+     *
+     * @defaultValue false
+     */
+    ShowValue?: boolean;
+    /**
+     * Optional AG Grid tooltip content — `CellValue` and/or `PercentageValue`.
+     * `PercentageValue` is the clamped cell value as a percent of `Max`
+     * (`clamp(value, 0, Max) / Max`, same scale as the icon fill).
+     */
+    ToolTipText?: CellTextOptions;
+    /**
+     * Optional cell box styling (background colour, border, border radius)
+     * applied to the cell behind the rating icons.
+     *
+     * When set, this property "claims" the Cell slice for the column: any
+     * Format Column matching this column has its Cell-box properties stripped
+     * (so a Format Column `BackColor` cannot tint the cell behind a Rating).
+     * When unset, Format Column Cell properties inherit through normally —
+     * useful for tinting a row of stars to match a Format Column theme.
+     */
+    Cell?: CellBoxStyle;
+}
 /**
  * Predicates available when creating a Badge Style Rule
  */
@@ -157,6 +367,50 @@ export type SystemBadgeStylePredicateIds = SystemBadgeStylePredicateId[];
 export interface BadgeStylePredicate extends AdaptablePredicate {
     PredicateId: TypeHint<string, SystemBadgeStylePredicateId>;
 }
+/**
+ * Visual styling applied to a single Badge "pill" (subset of `AdaptableStyle`)
+ */
+export interface BadgePillStyle {
+    /** Pill background colour. */
+    BackColor?: string;
+    /** Pill text/icon colour. */
+    ForeColor?: string;
+    /** Pill border colour (a subtle 1px border is drawn when set). */
+    BorderColor?: string;
+    /** Whether the pill text is bold. */
+    FontWeight?: 'Normal' | 'Bold';
+    /** Whether the pill text is italic. */
+    FontStyle?: 'Normal' | 'Italic';
+    /** Optional decoration (underline / line-through / overline). */
+    TextDecoration?: 'None' | 'Underline' | 'Overline' | 'LineThrough';
+}
+/**
+ * Visual shape of a Badge; convenience shorthand that resolves to a border radius without having to pick a pixel value
+ */
+export type BadgeShape = 'Pill' | 'Rounded' | 'Square';
+/**
+ * Density preset that controls inner padding (and therefore overall height)
+ * for *all* badges in a column. Applied at the {@link BadgeStyle} level so
+ * a single column reads as one consistent label set.
+ *
+ * - `'Compact'` - tight padding for dense grids
+ * - `'Normal'` - default; balanced padding (matches pre-existing look)
+ * - `'Comfortable'` - looser padding for low-density / large-font grids
+ */
+export type BadgeDensity = 'Compact' | 'Normal' | 'Comfortable';
+/**
+ * How adjacent badges in an array-column cell should lay out when the cell
+ * is too narrow to fit them on one line.
+ *
+ * - `'Truncate'` - default; badges sit on a single line and the cell clips
+ *   anything that overflows (legacy behaviour).
+ * - `'Wrap'` - badges wrap onto subsequent lines; row height grows to fit.
+ *   AG Grid `rowHeight` / `getRowHeight` should be tall enough to host the
+ *   wrapped badges; consider `autoRowHeight` on the column.
+ * - `'Scroll'` - badges stay on one line and the cell becomes
+ *   horizontally scrollable.
+ */
+export type BadgeOverflowMode = 'Truncate' | 'Wrap' | 'Scroll';
 /**
  * Defines a Badge Style
  */
@@ -167,9 +421,20 @@ export interface BadgeStyleDefinition {
     Predicate?: BadgeStylePredicate;
     Expression?: AdaptableBooleanQuery;
     /**
-     * Style for the Badge
+     * Style for the Badge **pill** (cut-down — see {@link BadgePillStyle}).
+     *
+     * Corner radius is **not** here: use {@link BadgeStyleDefinition.Shape}.
+     * Cell-row alignment is **not** here: use `BadgeStyle.Cell` /
+     * `BadgeStyle.Font.Alignment` at the column level.
      */
-    Style?: AdaptableStyle;
+    PillStyle?: BadgePillStyle;
+    /**
+     * Visual shape of the badge. Owns the pill's corner radius — there is
+     * no `BorderRadius` on `PillStyle`.
+     *
+     * @defaultValue 'Rounded'
+     */
+    Shape?: BadgeShape;
     /**
      * Icon to display in Badge
      */
@@ -178,6 +443,12 @@ export interface BadgeStyleDefinition {
      * Position of Icon in the Badge - 'Start' or 'End'
      */
     IconPosition?: 'Start' | 'End';
+    /**
+     * Pixel gap between the icon and the badge text. Falls back to the badge
+     * `Density` preset when omitted; ignored when there is no icon or when
+     * {@link IconOnly} is `true`.
+     */
+    IconGap?: number;
     /**
      * Only show an Icon and no Cell text
      */
@@ -192,7 +463,460 @@ export interface BadgeStyle {
      */
     Badges?: BadgeStyleDefinition[];
     /**
-     * Which types of Rows should contain a Badge (data, grouped, summary)
+     * Density preset shared by every badge in the column - controls inner padding.
+     *
+     * @defaultValue 'Normal'
      */
-    RowScope?: RowScope;
+    Density?: BadgeDensity;
+    /**
+     * Pixel gap between adjacent badges in array-column cells
+     *
+     * @defaultValue 4
+     */
+    Spacing?: number;
+    /**
+     * How badges lay out in array-column cells where space is tight
+     *
+     * @defaultValue 'Truncate'
+     */
+    OverflowMode?: BadgeOverflowMode;
+    /**
+     * Optional cell-box styling applied to grid cell **behind** the badges.   *
+     */
+    Cell?: CellBoxStyle;
+    /**
+     * Optional column-level Font (only Alignment is meaningful for Badge cells)
+     *
+     */
+    Font?: CellFontStyle;
+}
+/**
+ * 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.
+     *
+     * 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.
+     */
+    TargetMarker?: BulletChartTargetMarker;
+    /**
+     * Colour of the actual (foreground) bar drawn on top of the bands.
+     *
+     * @defaultValue 'var(--ab-color-primary)'
+     */
+    BarColor?: 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
+     */
+    BarHeight?: number;
+    /**
+     * 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;
+    /**
+     * Whether the cell shows Cell Value, Percent Value, both, or none.
+     */
+    CellText?: CellTextOptions;
+    /**
+     * Position of cell text relative to the chart - `'Above'`, `'Below'` or `'Merged'`.
+     *
+     * @defaultValue 'Below'
+     */
+    CellTextPosition?: 'Above' | 'Below' | 'Merged';
+    /**
+     * 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;
+}
+/**
+ * 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 `BulletChartStyle.TargetMarker`.
+     */
+    Marker?: BulletChartTargetMarker;
+    /**
+     * Optional label displayed in the tooltip alongside the marker value.
+     */
+    Label?: string;
+}
+/**
+ * Visual style of a Bullet Chart target marker.
+ */
+export interface BulletChartTargetMarker {
+    /**
+     * Marker shape.
+     *
+     * @defaultValue 'Line'
+     */
+    Shape?: 'Line' | 'Triangle' | 'Dot' | 'Diamond';
+    /**
+     * Marker colour. Defaults to the current text colour.
+     *
+     * @defaultValue 'var(--ab-color-text)'
+     */
+    Color?: string;
+    /**
+     * Line thickness (for `Shape: 'Line'`) or shape size in px.
+     */
+    Size?: number;
+}
+/**
+ * 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 drawn as a *second* marker on the track
+     * (e.g. previous close, target, midpoint). Same value forms as `Min` /
+     * `Max`. Leave unset to draw only the cell-value marker.
+     */
+    Reference?: RangeBarBound;
+    /**
+     * Visual style of the cell-value marker.
+     *
+     * @defaultValue `{ Shape: 'Diamond', Color: 'var(--ab-color-accent)', Size: 8 }`
+     */
+    Marker?: RangeBarMarker;
+    /**
+     * Visual style of the reference marker (only used when `Reference` is set).
+     *
+     * @defaultValue `{ Shape: 'Line', Color: 'var(--ab-color-foreground)', Size: 2 }`
+     */
+    ReferenceMarker?: RangeBarMarker;
+    /**
+     * 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 `OutOfRangeColor`
+     * - `'Overflow'` — draw the marker outside the track at its true position
+     * - `'Hide'` — omit the cell-value marker entirely
+     *
+     * @defaultValue `'Clamp'`
+     */
+    OutOfRangeMode?: 'Clamp' | 'Overflow' | 'Hide';
+    /**
+     * Marker colour override applied when the cell value is out of range
+     * (only used with `OutOfRangeMode: 'Clamp'`). Useful to draw attention
+     * to "off-scale" rows.
+     */
+    OutOfRangeColor?: string;
+    /**
+     * Track colour (the line representing the `[Min, Max]` interval).
+     *
+     * @defaultValue 'var(--ab-color-foreground, #999)' at low alpha
+     */
+    TrackColor?: string;
+    /**
+     * Track thickness in px (the *short* axis — height in horizontal,
+     * width in vertical).
+     *
+     * @defaultValue 4
+     */
+    TrackHeight?: number;
+    /**
+     * Background colour for the chart area when no `CellRanges` are supplied.
+     */
+    BackColor?: string;
+    /**
+     * Orientation of the range bar.
+     *
+     * @defaultValue `'Horizontal'`
+     */
+    Orientation?: 'Horizontal' | 'Vertical';
+    /**
+     * Whether the cell shows Cell Value, Percent Value, both, or none.
+     */
+    CellText?: CellTextOptions;
+    /**
+     * Position of cell text relative to the range bar — `'Above'`, `'Below'`
+     * or `'Merged'`.
+     *
+     * @defaultValue `'Below'`
+     */
+    CellTextPosition?: 'Above' | 'Below' | 'Merged';
+    /**
+     * Tooltip content — same tokens (`'CellValue'`, `'PercentageValue'`)
+     * as Percent Bar / Bullet Chart.
+     */
+    ToolTipText?: CellTextOptions;
+}
+/**
+ * Resolvable value used by a Range Bar's `Min`, `Max` or `Reference`.
+ *
+ * - `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;
+/**
+ * Visual style of a Range Bar marker (cell value or reference).
+ */
+export interface RangeBarMarker {
+    /**
+     * Marker shape.
+     *
+     * @defaultValue `'Diamond'` for the cell-value marker, `'Line'` for the
+     *   reference marker.
+     */
+    Shape?: 'Line' | 'Triangle' | 'Dot' | 'Diamond';
+    /**
+     * Marker colour.
+     */
+    Color?: string;
+    /**
+     * Line thickness (for `Shape: 'Line'`) or shape size in px.
+     */
+    Size?: number;
+}
+/**
+ * Built-in mapping presets that {@link IconStyle.Preset} can seed from.
+ *
+ * Each preset is just a list of key → icon mappings; once the preset is
+ * applied in the wizard the mappings are stored on `IconStyle.Mappings`
+ * and can be edited / extended like any other mapping.
+ *
+ * - `'Flags'` — common ISO 3166 alpha-2 / country names → emoji flag.
+ * - `'Currencies'` — common ISO 4217 codes → issuing country flag (each
+ *    currency gets a unique glyph, unlike currency symbols where USD /
+ *    AUD / CAD all share `$`).
+ * - `'Trend'` — `'Up' | 'Down' | 'Flat'` (and `'Buy' | 'Sell' | 'Hold'`) →
+ *    arrow icons.
+ * - `'Status'` — `'Pass' | 'Warn' | 'Fail'` (and a few common synonyms) →
+ *    coloured circles / traffic-light style.
+ */
+export type IconStyleBuiltInPreset = 'Flags' | 'Currencies' | 'Trend' | 'Status';
+/**
+ * How the cell value should be matched against {@link IconStyleMapping.Key}.
+ *
+ * - `'Exact'` (default) — strict `===` equality. Numbers, booleans and
+ *   strings are matched as-is; useful when keys are tightly controlled.
+ * - `'CaseInsensitive'` — string keys are matched case-insensitively
+ *   (cell value and key are both lowercased before comparison). Useful
+ *   for free-typed columns where the same logical value can appear as
+ *   `'GBP'` or `'gbp'`.
+ */
+export type IconStyleMatchMode = 'Exact' | 'CaseInsensitive';
+/**
+ * Behaviour when the cell value does not match any mapping key.
+ *
+ * - `'Hide'` (default) — render nothing.
+ * - `'ShowText'` — render the raw cell value (so the cell still shows
+ *   *something* meaningful instead of an empty cell).
+ * - `'Icon'` — render a fallback icon defined by
+ *   {@link IconStyle.FallbackIcon}.
+ */
+export type IconStyleFallback = 'Hide' | 'ShowText' | 'Icon';
+/**
+ * What the renderer draws for a single matched mapping.
+ *
+ * - An {@link AdaptableIcon} — a system icon (`{ name: 'flag' }`), a URL
+ *   (`{ src: '/img/us.svg' }`) or an HTML element / fragment.
+ * - A plain `string` — rendered verbatim, intended for emoji glyphs
+ *   (e.g. `'🇺🇸'`, `'$'`, `'⬆'`). Strings are *not* HTML-parsed so they
+ *   are safe to author from data sources.
+ */
+export type IconStyleSpec = AdaptableIcon | string;
+/**
+ * One mapping in an {@link IconStyle} — `Key` is matched against the
+ * cell's raw value, `Icon` is what gets drawn when it matches.
+ */
+export interface IconStyleMapping {
+    /**
+     * Cell value that triggers this mapping. Compared using the parent
+     * {@link IconStyle.MatchMode} (defaults to strict equality).
+     *
+     * Booleans and numbers are accepted to support typed columns (e.g.
+     * `Key: true` for an `isLive` flag, `Key: 0` for a status code).
+     */
+    Key: string | number | boolean;
+    /**
+     * Icon to render when `Key` matches the cell value.
+     *
+     * See {@link IconStyleSpec} — accepts an `AdaptableIcon` (system /
+     * URL / element) or a plain string for emoji.
+     */
+    Icon: IconStyleSpec;
+    /**
+     * Optional human-readable description of this mapping (e.g. the full
+     * country name when `Key` is an ISO code). Surfaced in the tooltip and
+     * by the wizard's mappings list.
+     */
+    Description?: string;
+}
+/**
+ * Renders cell values as icons by looking up the cell value in a list of key → icon mappings; designed for one-glyph-per-cell visual recognition
+ */
+export interface IconStyle {
+    /**
+     * Custom mappings for style (layered on top of a preset); leave undefined to use preset as-is
+     */
+    Mappings?: IconStyleMapping[];
+    /**
+     * Built-in mappings to use for the Icon Style
+     */
+    Preset?: IconStyleBuiltInPreset;
+    /**
+     * How `Key` is compared with the cell value (Exact or Case Insensitive)
+     *
+     * @defaultValue `'Exact'`
+     */
+    MatchMode?: IconStyleMatchMode;
+    /**
+     * What to render when **no** mapping matches the cell value (Hide, ShowText, Icon)
+     *
+     * @defaultValue `'Hide'`
+     */
+    Fallback?: IconStyleFallback;
+    /**
+     * Icon used by `Fallback: 'Icon'` (ignored otherwise)
+     */
+    FallbackIcon?: IconStyleSpec;
+    /**
+     * Text to render alongside a matched icon (CellValue or IconDescription)
+     */
+    CellText?: ('CellValue' | 'IconDescription')[];
+    /**
+     * Where the cell text sits relative to the icon (Before, After, Above, Below)
+     *
+     * @defaultValue `'After'`
+     */
+    CellTextPosition?: 'Before' | 'After' | 'Above' | 'Below';
+    /**
+     * Pixel size of icon glyph (square)
+     *
+     * @defaultValue `18`
+     */
+    Size?: number;
+    /**
+     * Pixel gap between the icon and the cell text (when shown).
+     *
+     * @defaultValue `4`
+     */
+    Gap?: number;
+    /**
+     * Tooltip content: `CellValue` (raw cell value) or `IconDescription` (matched mapping's `Description`)
+     */
+    ToolTipText?: ('CellValue' | 'IconDescription')[];
+    /**
+     * Optional cell-text styling applied to the companion text
+     */
+    Font?: CellFontStyle;
+    /**
+     * Optional stying (background / border / radius) for Cell behind the Icon
+     */
+    Cell?: CellBoxStyle;
 }