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

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

import { CellBoxStyle } from '../Common/AdaptableStyle';
import { CellTextOptions } from './Common/CellTextOptions';
/**
 * 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;
}