@adaptabletools/adaptable 23.0.0-canary.1 → 23.0.0-canary.10

package/src/Utilities/Helpers/StyledColumns/GradientStyleHelper.js

@@ -0,0 +1,247 @@
+import tinycolor from 'tinycolor2';
+import { convertAdaptableStyleToCSS } from '../StyleHelper';
+import { getAutoContrastTextColor, getVariableColor } from '../StyleHelper';
+import { clamp } from '../../Extensions/NumberExtensions';
+/**
+ * Default alpha at the **low** end of a Gradient range when `MinAlpha` is unset.
+ * Slightly above zero so the bottom-edge value of every range still shows its
+ * colour (rather than rendering fully transparent).
+ */
+export const DEFAULT_GRADIENT_MIN_ALPHA = 0.15;
+/**
+ * Default alpha at the **high** end of a Gradient range when `MaxAlpha` is unset.
+ */
+export const DEFAULT_GRADIENT_MAX_ALPHA = 1;
+export const hasGradientRangesConfigured = (gs) => !!(gs?.ZeroCentred || gs?.CellRanges?.length || gs?.ColumnComparison);
+const evenlySpacedValues = (min, max, count) => {
+    if (count <= 1) {
+        return [min];
+    }
+    const step = (max - min) / (count - 1);
+    return Array.from({ length: count }, (_, i) => min + step * i);
+};
+/** Number of sample cells shown in Gradient / Percent Bar style previews. */
+export const STYLED_COLUMN_PREVIEW_SAMPLE_COUNT = 6;
+/** Illustrative zero-centred scale endpoints for preview geometry. */
+export const ZERO_CENTRED_PREVIEW_SCALE_MIN = -20;
+export const ZERO_CENTRED_PREVIEW_SCALE_MAX = 20;
+/** @deprecated Use {@link getZeroCentredGradientPreviewValues} — kept for callers using endpoints. */
+export const ZERO_CENTRED_GRADIENT_PREVIEW_VALUES = evenlySpacedValues(ZERO_CENTRED_PREVIEW_SCALE_MIN, ZERO_CENTRED_PREVIEW_SCALE_MAX, STYLED_COLUMN_PREVIEW_SAMPLE_COUNT);
+export const getZeroCentredGradientPreviewValues = () => evenlySpacedValues(ZERO_CENTRED_PREVIEW_SCALE_MIN, ZERO_CENTRED_PREVIEW_SCALE_MAX, STYLED_COLUMN_PREVIEW_SAMPLE_COUNT);
+export function isDivergingZeroCellRanges(ranges) {
+    if (!ranges || ranges.length !== 2) {
+        return false;
+    }
+    const [a, b] = ranges;
+    return a.Max === 0 && b.Min === 0;
+}
+export function isZeroCentredGradientStyle(gs) {
+    return !!(gs.ZeroCentred || isDivergingZeroCellRanges(gs.CellRanges));
+}
+/**
+ * Sample cell values for gradient preview strips — spread across the effective scale.
+ */
+export const getGradientPreviewSampleValues = (styledColumn, api) => {
+    const gs = styledColumn.GradientStyle;
+    if (!gs || !hasGradientRangesConfigured(gs)) {
+        return [];
+    }
+    if (isZeroCentredGradientStyle(gs)) {
+        return getZeroCentredGradientPreviewValues();
+    }
+    if (gs.ColumnComparison) {
+        const min = Number(gs.ColumnComparison.MinValue);
+        const max = Number(gs.ColumnComparison.MaxValue);
+        if (!Number.isNaN(min) && !Number.isNaN(max)) {
+            return evenlySpacedValues(min, max, STYLED_COLUMN_PREVIEW_SAMPLE_COUNT);
+        }
+        return evenlySpacedValues(0, 100, STYLED_COLUMN_PREVIEW_SAMPLE_COUNT);
+    }
+    const column = styledColumn.ColumnId
+        ? api.columnApi.getColumnWithColumnId(styledColumn.ColumnId)
+        : undefined;
+    if (!column) {
+        return evenlySpacedValues(0, 100, STYLED_COLUMN_PREVIEW_SAMPLE_COUNT);
+    }
+    const colMin = api.styledColumnApi.internalApi.getMinValueForNumericColumn(column);
+    const colMax = api.styledColumnApi.internalApi.getMaxValueForNumericColumn(column);
+    if (colMin === colMax) {
+        return [colMin];
+    }
+    return evenlySpacedValues(colMin, colMax, STYLED_COLUMN_PREVIEW_SAMPLE_COUNT);
+};
+const getZeroCentredPreviewColors = (gradientStyle) => {
+    if (gradientStyle.ZeroCentred) {
+        return {
+            negative: gradientStyle.ZeroCentred.NegativeColor,
+            positive: gradientStyle.ZeroCentred.PositiveColor,
+        };
+    }
+    const ranges = gradientStyle.CellRanges;
+    if (isDivergingZeroCellRanges(ranges)) {
+        return {
+            negative: ranges[0].Color,
+            positive: ranges[1].Color,
+        };
+    }
+    return null;
+};
+/**
+ * Zero-centred preview uses a fixed -20…20 illustrative scale so negative
+ * colours always appear — independent of whether the column currently has
+ * negative values (Col-Min may be above zero today).
+ */
+const getZeroCentredGradientPreviewCellStyle = (cellValue, gradientStyle) => {
+    const colors = getZeroCentredPreviewColors(gradientStyle);
+    if (!colors) {
+        return {};
+    }
+    const previewMin = ZERO_CENTRED_PREVIEW_SCALE_MIN;
+    const previewMax = ZERO_CENTRED_PREVIEW_SCALE_MAX;
+    const syntheticRanges = [
+        { Min: previewMin, Max: 0, Color: colors.negative },
+        { Min: 0, Max: previewMax, Color: colors.positive },
+    ];
+    let matchingRange = null;
+    for (const range of syntheticRanges) {
+        const min = range.Min;
+        const max = range.Max;
+        if (cellValue >= min && cellValue <= max) {
+            matchingRange = range;
+            break;
+        }
+    }
+    if (!matchingRange) {
+        return {};
+    }
+    const min = matchingRange.Min;
+    const max = matchingRange.Max;
+    const reverseGradient = matchingRange.Min === previewMin && matchingRange.Max === 0;
+    const minAlphaBound = gradientStyle.MinAlpha ?? DEFAULT_GRADIENT_MIN_ALPHA;
+    const maxAlphaBound = gradientStyle.MaxAlpha ?? DEFAULT_GRADIENT_MAX_ALPHA;
+    const lo = Math.min(clamp(minAlphaBound, 0, 1), clamp(maxAlphaBound, 0, 1));
+    const hi = Math.max(clamp(minAlphaBound, 0, 1), clamp(maxAlphaBound, 0, 1));
+    const span = Math.abs(max - min);
+    let t = span === 0 ? 0.5 : (Number(cellValue) - min) / span;
+    t = clamp(t, 0, 1);
+    if (reverseGradient) {
+        t = 1 - t;
+    }
+    const alpha = Number((lo + t * (hi - lo)).toPrecision(4));
+    let style = {};
+    const preparedColor = getVariableColor(matchingRange.Color);
+    const bg = tinycolor(preparedColor).setAlpha(alpha);
+    style.backgroundColor = bg.toRgbString();
+    if (gradientStyle.AutoContrastText) {
+        style.color = getAutoContrastTextColor(preparedColor, alpha);
+    }
+    const autoContrastColor = gradientStyle.AutoContrastText && style.color ? style.color : undefined;
+    if (gradientStyle.Font) {
+        style = { ...style, ...convertAdaptableStyleToCSS(gradientStyle.Font) };
+    }
+    if (autoContrastColor) {
+        style.color = autoContrastColor;
+    }
+    if (gradientStyle.Font?.Alignment && gradientStyle.Font.Alignment !== 'Default') {
+        style.textAlign = gradientStyle.Font.Alignment.toLowerCase();
+    }
+    return style;
+};
+/**
+ * Cell CSS for gradient preview — mirrors `AgGridColumnAdapter.getStyledColumnStyle` gradient path.
+ */
+export const getGradientPreviewCellStyle = (cellValue, styledColumn, api, rowNode) => {
+    const gradientStyle = styledColumn.GradientStyle;
+    if (!gradientStyle || !hasGradientRangesConfigured(gradientStyle)) {
+        return {};
+    }
+    if (isZeroCentredGradientStyle(gradientStyle)) {
+        return getZeroCentredGradientPreviewCellStyle(cellValue, gradientStyle);
+    }
+    const column = styledColumn.ColumnId
+        ? api.columnApi.getColumnWithColumnId(styledColumn.ColumnId)
+        : undefined;
+    if (!column) {
+        return {};
+    }
+    const node = rowNode ?? api.gridApi?.getRowNodeForIndex(0) ?? null;
+    const internalApi = api.styledColumnApi.internalApi;
+    let style = {};
+    const min = internalApi.getNumericStyleMinValue(styledColumn, column, node, cellValue);
+    const max = internalApi.getNumericStyleMaxValue(styledColumn, column, node, cellValue);
+    let cellBackColor;
+    let reverseGradient = false;
+    if (gradientStyle.ColumnComparison) {
+        cellBackColor = gradientStyle.ColumnComparison.Color;
+    }
+    else {
+        const matchingRange = internalApi.findRangeForColumn(expandGradientCellRanges(gradientStyle), column, gradientStyleRangeLookupValueType(gradientStyle), cellValue);
+        if (matchingRange) {
+            cellBackColor = matchingRange.Color;
+            reverseGradient =
+                (!!gradientStyle.ZeroCentred && isNegativeZeroCentredBand(matchingRange)) ||
+                    !!matchingRange.ReverseGradient;
+        }
+    }
+    const minAlphaBound = gradientStyle.MinAlpha ?? DEFAULT_GRADIENT_MIN_ALPHA;
+    const maxAlphaBound = gradientStyle.MaxAlpha ?? DEFAULT_GRADIENT_MAX_ALPHA;
+    const lo = Math.min(clamp(minAlphaBound, 0, 1), clamp(maxAlphaBound, 0, 1));
+    const hi = Math.max(clamp(minAlphaBound, 0, 1), clamp(maxAlphaBound, 0, 1));
+    const span = Math.abs(max - min);
+    let t = span === 0 ? 0.5 : (Number(cellValue) - min) / span;
+    t = clamp(t, 0, 1);
+    if (reverseGradient) {
+        t = 1 - t;
+    }
+    const alpha = Number((lo + t * (hi - lo)).toPrecision(4));
+    if (cellBackColor) {
+        const preparedColor = getVariableColor(cellBackColor);
+        const bg = tinycolor(preparedColor).setAlpha(alpha);
+        style.backgroundColor = bg.toRgbString();
+        if (gradientStyle.AutoContrastText) {
+            style.color = getAutoContrastTextColor(preparedColor, alpha);
+        }
+    }
+    const autoContrastColor = gradientStyle.AutoContrastText && style.color ? style.color : undefined;
+    if (gradientStyle.Font) {
+        style = { ...style, ...convertAdaptableStyleToCSS(gradientStyle.Font) };
+    }
+    if (autoContrastColor) {
+        style.color = autoContrastColor;
+    }
+    if (gradientStyle.Font?.Alignment && gradientStyle.Font.Alignment !== 'Default') {
+        style.textAlign = gradientStyle.Font.Alignment.toLowerCase();
+    }
+    return style;
+};
+/**
+ * Effective cell ranges for gradient rendering / range lookup.
+ * When `ZeroCentred` is set, expands to the canonical Col-Min…0 and 0…Col-Max bands.
+ */
+export function expandGradientCellRanges(gs) {
+    if (gs.ZeroCentred) {
+        return [
+            { Min: 'Col-Min', Max: 0, Color: gs.ZeroCentred.NegativeColor },
+            { Min: 0, Max: 'Col-Max', Color: gs.ZeroCentred.PositiveColor },
+        ];
+    }
+    return gs.CellRanges;
+}
+/**
+ * Value type passed to `findRangeForColumn` / `getCellColorRangeMinValue` /
+ * `getCellColorRangeMaxValue` when resolving which gradient band a cell falls in.
+ *
+ * Zero-centred bands use numeric `0` as an **absolute** zero crossing between
+ * `Col-Min…0` and `0…Col-Max`. Under `RangeValueType: 'Percentage'`, numeric
+ * endpoints are interpreted as % positions along the column min–max span, so
+ * literal `0` wrongly becomes `Col-Min` and the negative band collapses to a
+ * single point — boundary cells (e.g. the column minimum) pick up the negative
+ * colour incorrectly. Zero-centred lookup must always use Number semantics.
+ */
+export function gradientStyleRangeLookupValueType(gs) {
+    return gs.ZeroCentred ? 'Number' : gs.RangeValueType ?? 'Number';
+}
+/** The negative half of a zero-centred gradient (darker toward Col-Min). */
+export function isNegativeZeroCentredBand(range) {
+    return range.Min === 'Col-Min' && range.Max === 0;
+}

package/src/Utilities/Helpers/{IconStylePresets.d.ts → StyledColumns/IconStyleHelper.d.ts}

@@ -1,4 +1,9 @@
-import { IconStyleBuiltInPreset, IconStyleMapping } from '../../AdaptableState/StyledColumnState';
+import { IconStyleBuiltInPreset, IconStyleMapping } from '../../../AdaptableState/StyledColumns/IconStyle';
+/**
+ * Icon Column Style resolves one key → glyph per scalar cell value; AdapTable
+ * array column types are not supported (use Badge Style for per-element visuals).
+ */
+export declare function isUnsupportedColumnDataTypeForIconStyle(dataType?: string): boolean;
 export declare const ICON_STYLE_PRESETS: Record<IconStyleBuiltInPreset, IconStyleMapping[]>;
 /** Returns a fresh copy of the mappings for a given preset. */
 export declare const getIconStylePresetMappings: (preset: IconStyleBuiltInPreset) => IconStyleMapping[];

package/src/Utilities/Helpers/{IconStylePresets.js → StyledColumns/IconStyleHelper.js}

@@ -1,3 +1,18 @@
+/**
+ * Icon Column Style resolves one key → glyph per scalar cell value; AdapTable
+ * array column types are not supported (use Badge Style for per-element visuals).
+ */
+export function isUnsupportedColumnDataTypeForIconStyle(dataType) {
+    switch (dataType) {
+        case 'textArray':
+        case 'numberArray':
+        case 'tupleArray':
+        case 'objectArray':
+            return true;
+        default:
+            return false;
+    }
+}
 /**
  * Built-in {@link IconStyle} mapping presets.
  *

package/src/Utilities/Helpers/StyledColumns/PercentBarStyleHelper.d.ts

@@ -0,0 +1,20 @@
+import { StyledColumn } from '../../../AdaptableState/StyledColumnState';
+import { PercentBarStyle } from '../../../AdaptableState/StyledColumns/PercentBarStyle';
+export declare const hasPercentBarRangesConfigured: (pb: PercentBarStyle | undefined) => boolean;
+/** Illustrative scale for preview — shows negatives when origin is Auto or Zero. */
+export declare const getPercentBarPreviewScale: (pb: PercentBarStyle) => {
+    min: number;
+    max: number;
+};
+export declare const getPercentBarPreviewSampleValues: (pb: PercentBarStyle) => number[];
+export type PercentBarPreviewGeometry = {
+    barLeftPercent: number;
+    barWidthPercent: number;
+    percentageValue: number;
+    barColor?: string;
+};
+export declare const getPercentBarPreviewGeometry: (numericValue: number, pb: PercentBarStyle, min: number, max: number) => PercentBarPreviewGeometry;
+export declare const formatPercentBarPreviewCellText: (numericValue: number, percentageValue: number, pb: PercentBarStyle) => string;
+export declare const getPercentBarPreviewTrackColor: (pb: PercentBarStyle) => string | undefined;
+export declare const getPercentBarPreviewResolvedBarColor: (color: string | undefined) => string | undefined;
+export declare const hasPercentBarStylePreview: (styledColumn: StyledColumn) => boolean;

package/src/Utilities/Helpers/StyledColumns/PercentBarStyleHelper.js

@@ -0,0 +1,138 @@
+import { getVariableColor } from '../StyleHelper';
+import { clamp } from '../../Extensions/NumberExtensions';
+import { STYLED_COLUMN_PREVIEW_SAMPLE_COUNT, ZERO_CENTRED_PREVIEW_SCALE_MAX, ZERO_CENTRED_PREVIEW_SCALE_MIN, } from './GradientStyleHelper';
+import { buildBarStyleCellTextLabels, joinBarStyleCellTextLabels } from './BarStylesHelper';
+const evenlySpacedValues = (min, max, count) => {
+    if (count <= 1) {
+        return [min];
+    }
+    const step = (max - min) / (count - 1);
+    return Array.from({ length: count }, (_, i) => min + step * i);
+};
+const toFraction = (value, min, max) => {
+    if (max === min) {
+        return 0;
+    }
+    return clamp((value - min) / (max - min), 0, 1);
+};
+const resolveOrigin = (percentBarStyle, cellValue, min, max) => {
+    const origin = percentBarStyle.Origin ?? 'Auto';
+    if (typeof origin === 'number') {
+        return origin;
+    }
+    if (origin === 'Zero') {
+        return 0;
+    }
+    if (origin === 'Min') {
+        return min;
+    }
+    if (min < 0 || max < 0 || cellValue < 0) {
+        return 0;
+    }
+    return min;
+};
+const columnComparisonUsesCentredAxis = (origin) => {
+    const o = origin ?? 'Auto';
+    if (typeof o === 'number') {
+        return false;
+    }
+    return o === 'Zero' || o === 'Auto';
+};
+const resolveRangeEndpoint = (endpoint, scaleMin, scaleMax) => {
+    if (endpoint === 'Col-Min') {
+        return scaleMin;
+    }
+    if (endpoint === 'Col-Max') {
+        return scaleMax;
+    }
+    if (typeof endpoint === 'number') {
+        return endpoint;
+    }
+    return scaleMin;
+};
+const getPreviewBarColor = (value, pb, scaleMin, scaleMax) => {
+    if (pb.ColumnComparison) {
+        return pb.ColumnComparison.Color;
+    }
+    for (const range of pb.CellRanges ?? []) {
+        const rMin = resolveRangeEndpoint(range.Min, scaleMin, scaleMax);
+        const rMax = resolveRangeEndpoint(range.Max, scaleMin, scaleMax);
+        if (value >= Math.min(rMin, rMax) && value <= Math.max(rMin, rMax)) {
+            return range.Color;
+        }
+    }
+    return pb.CellRanges?.[0]?.Color;
+};
+export const hasPercentBarRangesConfigured = (pb) => !!(pb?.CellRanges?.length || pb?.ColumnComparison);
+/** Illustrative scale for preview — shows negatives when origin is Auto or Zero. */
+export const getPercentBarPreviewScale = (pb) => {
+    const origin = pb.Origin ?? 'Auto';
+    if (origin === 'Zero' || origin === 'Auto') {
+        return { min: ZERO_CENTRED_PREVIEW_SCALE_MIN, max: ZERO_CENTRED_PREVIEW_SCALE_MAX };
+    }
+    return { min: 0, max: 100 };
+};
+export const getPercentBarPreviewSampleValues = (pb) => {
+    const { min, max } = getPercentBarPreviewScale(pb);
+    return evenlySpacedValues(min, max, STYLED_COLUMN_PREVIEW_SAMPLE_COUNT);
+};
+export const getPercentBarPreviewGeometry = (numericValue, pb, min, max) => {
+    let percentageValue = 0;
+    let barLeftPercent = 0;
+    let barWidthPercent = 0;
+    if (pb.ColumnComparison) {
+        const absMax = Math.abs(max);
+        percentageValue = absMax === 0 ? 0 : (numericValue / absMax) * 100;
+        const magnitude = Math.min(100, Math.abs(percentageValue));
+        const origin = pb.Origin ?? 'Auto';
+        const isCentred = columnComparisonUsesCentredAxis(origin);
+        if (isCentred) {
+            const halfWidth = magnitude / 2;
+            if (percentageValue >= 0) {
+                barLeftPercent = 50;
+                barWidthPercent = halfWidth;
+            }
+            else {
+                barLeftPercent = 50 - halfWidth;
+                barWidthPercent = halfWidth;
+            }
+        }
+        else {
+            barLeftPercent = 0;
+            barWidthPercent = magnitude;
+        }
+    }
+    else if (max === min) {
+        percentageValue = 0;
+        barLeftPercent = 0;
+        barWidthPercent = 0;
+    }
+    else {
+        percentageValue = ((clamp(numericValue, min, max) - min) / (max - min)) * 100;
+        const origin = resolveOrigin(pb, numericValue, min, max);
+        const valueFrac = toFraction(numericValue, min, max);
+        const originFrac = toFraction(origin, min, max);
+        const start = Math.min(valueFrac, originFrac);
+        const end = Math.max(valueFrac, originFrac);
+        barLeftPercent = start * 100;
+        barWidthPercent = (end - start) * 100;
+    }
+    return {
+        barLeftPercent,
+        barWidthPercent,
+        percentageValue,
+        barColor: getPreviewBarColor(numericValue, pb, min, max),
+    };
+};
+export const formatPercentBarPreviewCellText = (numericValue, percentageValue, pb) => {
+    const labels = buildBarStyleCellTextLabels(pb.CellTextProperties, Number.isInteger(numericValue) ? String(numericValue) : numericValue.toFixed(1), `${percentageValue.toFixed(0)}%`);
+    return joinBarStyleCellTextLabels(labels);
+};
+export const getPercentBarPreviewTrackColor = (pb) => {
+    if (pb.ColumnComparison) {
+        return pb.BackColor ?? undefined;
+    }
+    return pb.BackColor ?? undefined;
+};
+export const getPercentBarPreviewResolvedBarColor = (color) => (color ? getVariableColor(color) : undefined);
+export const hasPercentBarStylePreview = (styledColumn) => hasPercentBarRangesConfigured(styledColumn.PercentBarStyle);

package/src/Utilities/Helpers/StyledColumns/SparklineStyleHelper.d.ts

@@ -0,0 +1,7 @@
+import type { AgSparklineOptions } from 'ag-charts-types';
+/**
+ * AG Charts sparklines do not resolve Adaptable `var(--ab-color-*)` tokens.
+ * Resolve palette / theme CSS variables to concrete colours at render time so
+ * wizard previews and grid cells match the chosen Fill / Stroke values.
+ */
+export declare function resolveSparklineOptionsForRender(options: AgSparklineOptions): AgSparklineOptions;

package/src/Utilities/Helpers/StyledColumns/SparklineStyleHelper.js

@@ -0,0 +1,65 @@
+import { getVariableColor } from '../StyleHelper';
+const resolveCssColor = (color) => {
+    if (color == null || color === '') {
+        return color;
+    }
+    const resolved = getVariableColor(color);
+    return resolved || color;
+};
+const resolveHighlightStyle = (style) => {
+    if (!style) {
+        return style;
+    }
+    const resolved = { ...style };
+    if (style.fill != null) {
+        resolved.fill = resolveCssColor(style.fill);
+    }
+    if (style.stroke != null) {
+        resolved.stroke = resolveCssColor(style.stroke);
+    }
+    return resolved;
+};
+/**
+ * AG Charts sparklines do not resolve Adaptable `var(--ab-color-*)` tokens.
+ * Resolve palette / theme CSS variables to concrete colours at render time so
+ * wizard previews and grid cells match the chosen Fill / Stroke values.
+ */
+export function resolveSparklineOptionsForRender(options) {
+    const resolved = { ...options };
+    if ('fill' in options && options.fill != null) {
+        resolved.fill = resolveCssColor(options.fill);
+    }
+    if (options.stroke != null) {
+        resolved.stroke = resolveCssColor(options.stroke);
+    }
+    if (options.background?.fill != null) {
+        resolved.background = {
+            ...options.background,
+            fill: resolveCssColor(options.background.fill),
+        };
+    }
+    if ('marker' in options && options.marker) {
+        const marker = { ...options.marker };
+        if (marker.fill != null) {
+            marker.fill = resolveCssColor(marker.fill);
+        }
+        if (marker.stroke != null) {
+            marker.stroke = resolveCssColor(marker.stroke);
+        }
+        resolved.marker = marker;
+    }
+    if (options.highlight) {
+        resolved.highlight = {
+            ...options.highlight,
+            highlightedItem: resolveHighlightStyle(options.highlight.highlightedItem),
+            highlightedSeries: resolveHighlightStyle(options.highlight.highlightedSeries),
+        };
+    }
+    if (options.axis && typeof options.axis === 'object' && options.axis.stroke != null) {
+        resolved.axis = {
+            ...options.axis,
+            stroke: resolveCssColor(options.axis.stroke),
+        };
+    }
+    return resolved;
+}

package/src/Utilities/Helpers/StyledColumns/StyledColumnHelper.d.ts

@@ -0,0 +1,52 @@
+import type { IRowNode } from 'ag-grid-enterprise';
+import type { AdaptableApi } from '../../../Api/AdaptableApi';
+import type { StyledColumn } from '../../../AdaptableState/StyledColumnState';
+import type { RowScope } from '../../../AdaptableState/Common/RowScope';
+/**
+ * Row kinds used by {@link RowScope} and the Styled Column Scope wizard.
+ * All are available to all Styled Columns with exception of Sparkline (which is data rows only)
+ */
+export type StyledColumnRowKind = 'Data' | 'Group' | 'Summary' | 'Total';
+export declare const STYLED_COLUMN_ROW_KINDS: StyledColumnRowKind[];
+export declare const STYLED_COLUMN_ROW_KIND_EXCLUDE_KEY: Record<StyledColumnRowKind, keyof RowScope>;
+export declare const isStyledColumnRowKindSupported: (styledColumn: StyledColumn, kind: StyledColumnRowKind) => boolean;
+export declare const getStyledColumnRowKindDisabledReason: (styledColumn: StyledColumn, kind: StyledColumnRowKind) => string | undefined;
+/**
+ * Classifies the AG Grid row node into a single {@link StyledColumnRowKind}.
+ * Order matches {@link shouldRenderStyledColumnOnRow}: total before summary,
+ * summary before group.
+ */
+export declare const getStyledColumnRowKindForNode: (node: IRowNode, api: AdaptableApi) => StyledColumnRowKind;
+/**
+ * Forces `Exclude*` to `true` for row kinds that do not apply to the current
+ * Styled Column type, so persisted state cannot contradict the capability
+ * matrix. Returns `undefined` when no change is needed.
+ */
+export declare const sanitizeStyledColumnRowScope: (styledColumn: StyledColumn) => RowScope | undefined;
+/**
+ * Returns `true` when the Styled Column should render on the given row.
+ *
+ * Single source of truth consulted by every styled-column cell renderer
+ * (Badge / Icon / Rating / Percent Bar / Bullet Chart / Range Bar) and
+ * by `getStyledColumnStyle` (Gradient / Percent Bar cellStyle).
+ *
+ * Semantics:
+ *  - **Type capabilities** first: some types never target certain row kinds
+ *    (see {@link isStyledColumnRowKindSupported}). Unsupported kinds always
+ *    return `false` regardless of `RowScope`.
+ *  - When `StyledColumn.RowScope` is **set**, the explicit `Exclude*`
+ *    flags win. Unset flags default to "include" — i.e. `RowScope: {}`
+ *    means "render on every *supported* row kind".
+ *  - When `StyledColumn.RowScope` is **unset**, the historical per-type
+ *    default applies:
+ *      - Badge: render on every row kind (that the type supports).
+ *      - All other types: render on every row kind *except* group rows
+ *        (matches the hardcoded "isGroupRowNode → plain text" check that
+ *        every other styled-column renderer used to carry), again
+ *        intersected with type capabilities (e.g. Sparkline → data only).
+ *
+ * The per-type default lets us promote `RowScope` cleanly without
+ * altering existing user-visible behaviour: state that doesn't mention
+ * `RowScope` keeps rendering exactly as before.
+ */
+export declare const shouldRenderStyledColumnOnRow: (styledColumn: StyledColumn, node: IRowNode, api: AdaptableApi) => boolean;

package/src/{agGrid/cellRenderers/shouldRenderStyledColumnOnRow.js → Utilities/Helpers/StyledColumns/StyledColumnHelper.js}

@@ -1,4 +1,66 @@
-import { getStyledColumnRowKindForNode, isStyledColumnRowKindSupported, } from '../../Utilities/Helpers/styledColumnRowKindSupport';
+export const STYLED_COLUMN_ROW_KINDS = ['Data', 'Group', 'Summary', 'Total'];
+export const STYLED_COLUMN_ROW_KIND_EXCLUDE_KEY = {
+    Data: 'ExcludeDataRows',
+    Group: 'ExcludeGroupRows',
+    Summary: 'ExcludeSummaryRows',
+    Total: 'ExcludeTotalRows',
+};
+export const isStyledColumnRowKindSupported = (styledColumn, kind) => {
+    if (styledColumn.SparklineStyle) {
+        return kind === 'Data';
+    }
+    return true;
+};
+export const getStyledColumnRowKindDisabledReason = (styledColumn, kind) => {
+    if (isStyledColumnRowKindSupported(styledColumn, kind)) {
+        return undefined;
+    }
+    if (styledColumn.SparklineStyle) {
+        return 'Sparklines only apply to leaf data rows (cells with a numeric array of points).';
+    }
+    return undefined;
+};
+/**
+ * Classifies the AG Grid row node into a single {@link StyledColumnRowKind}.
+ * Order matches {@link shouldRenderStyledColumnOnRow}: total before summary,
+ * summary before group.
+ */
+export const getStyledColumnRowKindForNode = (node, api) => {
+    if (api.gridApi.isGrandTotalRowNode(node)) {
+        return 'Total';
+    }
+    if (api.gridApi.isSummaryNode(node)) {
+        return 'Summary';
+    }
+    if (api.gridApi.isGroupRowNode(node)) {
+        return 'Group';
+    }
+    return 'Data';
+};
+/**
+ * Forces `Exclude*` to `true` for row kinds that do not apply to the current
+ * Styled Column type, so persisted state cannot contradict the capability
+ * matrix. Returns `undefined` when no change is needed.
+ */
+export const sanitizeStyledColumnRowScope = (styledColumn) => {
+    const scope = styledColumn.RowScope;
+    if (!scope) {
+        return undefined;
+    }
+    let next = { ...scope };
+    let changed = false;
+    for (const kind of STYLED_COLUMN_ROW_KINDS) {
+        if (isStyledColumnRowKindSupported(styledColumn, kind)) {
+            continue;
+        }
+        const key = STYLED_COLUMN_ROW_KIND_EXCLUDE_KEY[kind];
+        if (next[key] !== true) {
+            next = { ...next, [key]: true };
+            changed = true;
+        }
+    }
+    return changed ? next : undefined;
+};
 /**
  * Returns `true` when the Styled Column should render on the given row.
  *
@@ -8,7 +70,7 @@ import { getStyledColumnRowKindForNode, isStyledColumnRowKindSupported, } from '
  *
  * Semantics:
  *  - **Type capabilities** first: some types never target certain row kinds
- *    (see `styledColumnRowKindSupport.ts`). Unsupported kinds always
+ *    (see {@link isStyledColumnRowKindSupported}). Unsupported kinds always
  *    return `false` regardless of `RowScope`.
  *  - When `StyledColumn.RowScope` is **set**, the explicit `Exclude*`
  *    flags win. Unset flags default to "include" — i.e. `RowScope: {}`

package/src/Utilities/Helpers/ThemeHelper.d.ts

@@ -0,0 +1,5 @@
+import { AdaptableTheme, SystemThemeEntry } from '../../AdaptableState/ThemeState';
+import { AdaptableLogger } from '../../agGrid/AdaptableLogger';
+export declare function isLegacySystemThemeObject(theme: SystemThemeEntry | AdaptableTheme): theme is AdaptableTheme;
+export declare function resolveSystemThemeDescription(name: string): string;
+export declare function systemThemeEntryToAdaptableTheme(theme: SystemThemeEntry | AdaptableTheme, logger?: AdaptableLogger): AdaptableTheme;