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

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

import { AdaptableIcon } from '../Common/AdaptableIcon';
import { CellBoxStyle, CellFontStyle } from '../Common/AdaptableStyle';
/**
 * Built-in mapping presets for Icons (Flags, Currencies, Trend, Status)
 */
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 IconFallbackProperties.Icon}.
 */
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;
/**
 * Fallback settings for {@link IconStyle} — what the renderer draws when
 * no mapping matches the cell value (`Mode`), and the icon used when
 * `Mode === 'Icon'` (`Icon`).
 */
export interface IconFallbackProperties {
    /**
     * Behaviour when no mapping matches the cell value (Hide, ShowText, Icon).
     *
     * @defaultValue `'Hide'`
     */
    Mode?: IconStyleFallback;
    /**
     * Icon used when `Mode: 'Icon'` (ignored otherwise).
     */
    Icon?: IconStyleSpec;
}
/**
 * Companion text settings for {@link IconStyle} — what to render alongside
 * a matched icon (`CellText`) and where it sits relative to the icon
 * (`CellTextPosition`).
 */
export interface IconCellTextProperties {
    /**
     * Text to render alongside a matched icon (CellValue and/or the matched
     * mapping's Description).
     */
    CellText?: ('CellValue' | 'IconDescription')[];
    /**
     * Where the cell text sits relative to the icon (Before, After, Above, Below).
     *
     * @defaultValue `'After'`
     */
    CellTextPosition?: 'Before' | 'After' | 'Above' | 'Below';
}
/**
 * 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;
    /**
     * Behaviour when no mapping matches the cell value, plus the icon used
     * by `Mode: 'Icon'`.
     *
     * Defaults to `{ Mode: 'Hide' }` when omitted.
     */
    FallbackProperties?: IconFallbackProperties;
    /**
     * Companion text to render alongside a matched icon (Cell Value and/or
     * the matched mapping's Description) and where it sits relative to the
     * icon (Before / After / Above / Below).
     *
     * Mirrors the `CellTextProperties` grouping used by `PercentBarStyle`,
     * `BulletChartStyle` and `RangeBarStyle` for consistency.
     */
    CellTextProperties?: IconCellTextProperties;
    /**
     * 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;
}