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

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

@@ -0,0 +1,334 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mountBarStyleCellText = exports.formatBarStyleCellTextLayoutSummary = exports.getBarStyleCellTextSlotPresence = exports.resolveBarStyleCellTextSlots = exports.joinBarStyleCellTextLabels = exports.hasBarStyleCellTextLabels = exports.buildBarStyleCellTextLabels = exports.toggleBarStyleCellTextToken = exports.patchBarStyleCellTextPlacement = exports.setBarStyleCellTextPlacement = exports.mergeBarStyleCellTextProperties = exports.getActiveBarStyleCellTextTokens = exports.hasBarStyleCellTextConfigured = exports.resolveBarStyleCellTextLayout = void 0;
+/** Default placement applied to a value whose Horizontal/Vertical were omitted. */
+const DEFAULT_PLACEMENT = {
+    Horizontal: 'Left',
+    Vertical: 'Below',
+};
+const HORIZONTAL_VALUES = ['Left', 'Center', 'Right'];
+const VERTICAL_VALUES = ['Above', 'Below', 'Merged'];
+const isHorizontal = (value) => typeof value === 'string' && HORIZONTAL_VALUES.includes(value);
+const isVertical = (value) => typeof value === 'string' && VERTICAL_VALUES.includes(value);
+/** Normalise a placement, applying defaults for missing axes. */
+const sanitizePlacement = (placement) => ({
+    Horizontal: isHorizontal(placement?.Horizontal)
+        ? placement.Horizontal
+        : DEFAULT_PLACEMENT.Horizontal,
+    Vertical: isVertical(placement?.Vertical) ? placement.Vertical : DEFAULT_PLACEMENT.Vertical,
+});
+/** Returns a layout with only the values that are actually present, defaults filled in. */
+const sanitizeCellTextLayout = (layout) => {
+    const result = {};
+    if (layout?.CellValue) {
+        result.CellValue = sanitizePlacement(layout.CellValue);
+    }
+    if (layout?.PercentValue) {
+        result.PercentValue = sanitizePlacement(layout.PercentValue);
+    }
+    return result;
+};
+const resolveBarStyleCellTextLayout = (props) => sanitizeCellTextLayout(props?.CellTextLayout);
+exports.resolveBarStyleCellTextLayout = resolveBarStyleCellTextLayout;
+/** True when any value is configured for display. */
+const hasBarStyleCellTextConfigured = (props) => {
+    const layout = (0, exports.resolveBarStyleCellTextLayout)(props);
+    return Boolean(layout.CellValue || layout.PercentValue);
+};
+exports.hasBarStyleCellTextConfigured = hasBarStyleCellTextConfigured;
+/** Set of value tokens that currently have a placement. */
+const getActiveBarStyleCellTextTokens = (props) => {
+    const layout = (0, exports.resolveBarStyleCellTextLayout)(props);
+    const tokens = [];
+    if (layout.CellValue) {
+        tokens.push('CellValue');
+    }
+    if (layout.PercentValue) {
+        tokens.push('PercentageValue');
+    }
+    return tokens;
+};
+exports.getActiveBarStyleCellTextTokens = getActiveBarStyleCellTextTokens;
+const mergeBarStyleCellTextProperties = (current, patch) => {
+    const merged = { ...current, ...patch };
+    if (merged.CellTextLayout) {
+        merged.CellTextLayout = sanitizeCellTextLayout(merged.CellTextLayout);
+        if (!merged.CellTextLayout.CellValue && !merged.CellTextLayout.PercentValue) {
+            delete merged.CellTextLayout;
+        }
+    }
+    if (!merged.CellTextLayout) {
+        return undefined;
+    }
+    return merged;
+};
+exports.mergeBarStyleCellTextProperties = mergeBarStyleCellTextProperties;
+/**
+ * Set or clear a value's placement. Passing `placement: undefined` removes the value.
+ */
+const setBarStyleCellTextPlacement = (current, token, placement) => {
+    const layout = (0, exports.resolveBarStyleCellTextLayout)(current);
+    const next = { ...layout };
+    const key = token === 'CellValue' ? 'CellValue' : 'PercentValue';
+    if (placement) {
+        next[key] = sanitizePlacement(placement);
+    }
+    else {
+        delete next[key];
+    }
+    return (0, exports.mergeBarStyleCellTextProperties)(current, { CellTextLayout: next });
+};
+exports.setBarStyleCellTextPlacement = setBarStyleCellTextPlacement;
+/**
+ * Patch a single axis of a value's placement (creating the value with defaults if
+ * needed). Used by the wizard's placement pickers.
+ */
+const patchBarStyleCellTextPlacement = (current, token, patch) => {
+    const layout = (0, exports.resolveBarStyleCellTextLayout)(current);
+    const key = token === 'CellValue' ? 'CellValue' : 'PercentValue';
+    const existing = layout[key];
+    const nextPlacement = {
+        ...(existing ?? DEFAULT_PLACEMENT),
+        ...patch,
+    };
+    return (0, exports.setBarStyleCellTextPlacement)(current, token, nextPlacement);
+};
+exports.patchBarStyleCellTextPlacement = patchBarStyleCellTextPlacement;
+/**
+ * Toggle whether a value is displayed. When turning on a previously-hidden
+ * value we use the default placement (Left / Below).
+ */
+const toggleBarStyleCellTextToken = (current, token, show) => {
+    const layout = (0, exports.resolveBarStyleCellTextLayout)(current);
+    const key = token === 'CellValue' ? 'CellValue' : 'PercentValue';
+    if (show && !layout[key]) {
+        return {
+            CellTextProperties: (0, exports.setBarStyleCellTextPlacement)(current, token, DEFAULT_PLACEMENT),
+        };
+    }
+    if (!show && layout[key]) {
+        return {
+            CellTextProperties: (0, exports.setBarStyleCellTextPlacement)(current, token, undefined),
+        };
+    }
+    return { CellTextProperties: current };
+};
+exports.toggleBarStyleCellTextToken = toggleBarStyleCellTextToken;
+const buildBarStyleCellTextLabels = (props, cellValueLabel, percentageLabel) => {
+    const layout = (0, exports.resolveBarStyleCellTextLayout)(props);
+    const labels = {};
+    if (layout.CellValue && cellValueLabel != undefined) {
+        labels.cellValue = cellValueLabel;
+    }
+    if (layout.PercentValue && percentageLabel != undefined) {
+        labels.percentage = percentageLabel;
+    }
+    return labels;
+};
+exports.buildBarStyleCellTextLabels = buildBarStyleCellTextLabels;
+const hasBarStyleCellTextLabels = (labels) => Boolean(labels.cellValue || labels.percentage);
+exports.hasBarStyleCellTextLabels = hasBarStyleCellTextLabels;
+/** Join active labels with a space, Cell Value first then Percent Value. */
+const joinBarStyleCellTextLabels = (labels) => {
+    const parts = [];
+    if (labels.cellValue)
+        parts.push(labels.cellValue);
+    if (labels.percentage)
+        parts.push(labels.percentage);
+    return parts.join(' ');
+};
+exports.joinBarStyleCellTextLabels = joinBarStyleCellTextLabels;
+/**
+ * Resolve which placements are populated and what text goes in each cell of
+ * the 3 × 3 grid. Empty slots are omitted. Two values landing on the same
+ * (vertical, horizontal) slot are concatenated with a single space, Cell
+ * Value before Percent Value.
+ */
+const resolveBarStyleCellTextSlots = (props, labels) => {
+    const layout = (0, exports.resolveBarStyleCellTextLayout)(props);
+    // Iteration order matters when both values share a slot: Cell Value first,
+    // then Percent Value (matches the legacy "joined" behaviour).
+    const candidates = [];
+    if (layout.CellValue && labels.cellValue) {
+        candidates.push({
+            placement: sanitizePlacement(layout.CellValue),
+            text: labels.cellValue,
+        });
+    }
+    if (layout.PercentValue && labels.percentage) {
+        candidates.push({
+            placement: sanitizePlacement(layout.PercentValue),
+            text: labels.percentage,
+        });
+    }
+    const slotMap = new Map();
+    for (const { placement, text } of candidates) {
+        const key = `${placement.Vertical}|${placement.Horizontal}`;
+        const existing = slotMap.get(key);
+        if (existing) {
+            existing.parts.push(text);
+            existing.text = existing.parts.join(' ');
+        }
+        else {
+            slotMap.set(key, {
+                vertical: placement.Vertical,
+                horizontal: placement.Horizontal,
+                parts: [text],
+                text,
+            });
+        }
+    }
+    return Array.from(slotMap.values());
+};
+exports.resolveBarStyleCellTextSlots = resolveBarStyleCellTextSlots;
+const getBarStyleCellTextSlotPresence = (props) => {
+    const layout = (0, exports.resolveBarStyleCellTextLayout)(props);
+    const verticals = new Set();
+    if (layout.CellValue)
+        verticals.add(sanitizePlacement(layout.CellValue).Vertical);
+    if (layout.PercentValue)
+        verticals.add(sanitizePlacement(layout.PercentValue).Vertical);
+    return {
+        hasAbove: verticals.has('Above'),
+        hasBelow: verticals.has('Below'),
+        hasMerged: verticals.has('Merged'),
+    };
+};
+exports.getBarStyleCellTextSlotPresence = getBarStyleCellTextSlotPresence;
+// ---------------------------------------------------------------------------
+// Summary formatting
+// ---------------------------------------------------------------------------
+const HORIZONTAL_LABEL = {
+    Left: 'Left',
+    Center: 'Center',
+    Right: 'Right',
+};
+const VERTICAL_LABEL = {
+    Above: 'Above',
+    Below: 'Below',
+    Merged: 'Merged',
+};
+const formatTokenLabel = (token) => token === 'CellValue' ? 'Cell Value' : 'Percent Value';
+const formatPlacementSummary = (placement) => {
+    const { Horizontal, Vertical } = sanitizePlacement(placement);
+    return `${VERTICAL_LABEL[Vertical]}-${HORIZONTAL_LABEL[Horizontal]}`;
+};
+const formatBarStyleCellTextLayoutSummary = (layout) => {
+    const parts = [];
+    if (layout.CellValue) {
+        parts.push(`${formatTokenLabel('CellValue')}: ${formatPlacementSummary(layout.CellValue)}`);
+    }
+    if (layout.PercentValue) {
+        parts.push(`${formatTokenLabel('PercentageValue')}: ${formatPlacementSummary(layout.PercentValue)}`);
+    }
+    return parts.length ? parts.join('; ') : undefined;
+};
+exports.formatBarStyleCellTextLayoutSummary = formatBarStyleCellTextLayoutSummary;
+// ---------------------------------------------------------------------------
+// DOM mount
+// ---------------------------------------------------------------------------
+const HORIZONTAL_FLEX_JUSTIFY = {
+    Left: 'flex-start',
+    Center: 'center',
+    Right: 'flex-end',
+};
+const HORIZONTAL_TEXT_ALIGN = {
+    Left: 'left',
+    Center: 'center',
+    Right: 'right',
+};
+const createCellTextRow = (slots, textClassName, compact) => {
+    const row = document.createElement('div');
+    row.className = textClassName;
+    row.style.display = 'flex';
+    row.style.flexDirection = 'row';
+    row.style.alignItems = 'center';
+    row.style.width = '100%';
+    // When `Above` AND `Below` are both populated, two default-size text rows
+    // would squeeze the bar to 0 on a standard ~28-40px cell, so the caller
+    // asks for a compact band (smaller font + tighter line-height).
+    // Otherwise we render at the inherited cell font for legibility.
+    if (compact) {
+        row.style.fontSize = '0.75em';
+        row.style.lineHeight = '1';
+    }
+    else {
+        row.style.lineHeight = '1.2';
+    }
+    row.style.flex = '0 0 auto';
+    row.style.gap = '4px';
+    // Render fixed Left / Center / Right cells so spacing is stable even when
+    // only one or two slots are present.
+    for (const horizontal of HORIZONTAL_VALUES) {
+        const slot = slots.find((s) => s.horizontal === horizontal);
+        const cell = document.createElement('span');
+        cell.style.flex = '1';
+        cell.style.minWidth = '0';
+        cell.style.textAlign = HORIZONTAL_TEXT_ALIGN[horizontal];
+        cell.style.display = 'flex';
+        cell.style.justifyContent = HORIZONTAL_FLEX_JUSTIFY[horizontal];
+        cell.style.alignItems = 'center';
+        if (slot) {
+            cell.textContent = slot.text;
+        }
+        row.append(cell);
+    }
+    // Suppress the dummy row in the rare case where every slot for this band is
+    // empty (e.g. the only label is empty string). `String(...)` because text
+    // may arrive as a number when `params.formatValue` is undefined for a
+    // numeric column — `(11).length` is `undefined`, which would otherwise
+    // wrongly trip the empty-row branch.
+    if (!slots.some((s) => String(s.text ?? '').length)) {
+        row.style.display = 'none';
+    }
+    return row;
+};
+const mountBarStyleCellText = (args) => {
+    const { cellTextProperties, labels, wrapperEl, textClassName } = args;
+    if (!(0, exports.hasBarStyleCellTextConfigured)(cellTextProperties) || !(0, exports.hasBarStyleCellTextLabels)(labels)) {
+        return;
+    }
+    const slots = (0, exports.resolveBarStyleCellTextSlots)(cellTextProperties, labels);
+    if (!slots.length) {
+        return;
+    }
+    const mergedOverlayEl = args.mergedOverlayEl ?? wrapperEl;
+    const mergedPointerEventsNone = args.mergedPointerEventsNone ?? mergedOverlayEl === wrapperEl;
+    const slotsByVertical = {
+        Above: slots.filter((s) => s.vertical === 'Above'),
+        Below: slots.filter((s) => s.vertical === 'Below'),
+        Merged: slots.filter((s) => s.vertical === 'Merged'),
+    };
+    // Compact when Cell Value and Percent Value have *different* verticals
+    // (i.e. the two tokens claim two separate bands of vertical space). When
+    // they share a vertical band — or when only one token is configured —
+    // we have room for the full-size font.
+    const layout = (0, exports.resolveBarStyleCellTextLayout)(cellTextProperties);
+    const compact = Boolean(layout.CellValue &&
+        layout.PercentValue &&
+        sanitizePlacement(layout.CellValue).Vertical !==
+            sanitizePlacement(layout.PercentValue).Vertical);
+    if (slotsByVertical.Above.length) {
+        const row = createCellTextRow(slotsByVertical.Above, textClassName, compact);
+        wrapperEl.prepend(row);
+    }
+    if (slotsByVertical.Below.length) {
+        const row = createCellTextRow(slotsByVertical.Below, textClassName, compact);
+        wrapperEl.append(row);
+    }
+    if (slotsByVertical.Merged.length) {
+        const row = createCellTextRow(slotsByVertical.Merged, textClassName, compact);
+        row.style.position = 'absolute';
+        row.style.top = '50%';
+        row.style.transform = 'translateY(-50%)';
+        row.style.left = '0';
+        row.style.right = '0';
+        row.style.paddingLeft = '5px';
+        row.style.paddingRight = '5px';
+        if (mergedPointerEventsNone) {
+            row.style.pointerEvents = 'none';
+        }
+        mergedOverlayEl.append(row);
+    }
+};
+exports.mountBarStyleCellText = mountBarStyleCellText;

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

@@ -0,0 +1,54 @@
+import type { CSSProperties } from 'react';
+import type { IRowNode } from 'ag-grid-community';
+import { StyledColumn } from '../../../AdaptableState/StyledColumnState';
+import { CellColorRange, NumericStyledColumn } from '../../../AdaptableState/StyledColumns/Common/NumericStyledColumn';
+import { GradientStyle } from '../../../AdaptableState/StyledColumns/GradientStyle';
+import { AdaptableApi } from '../../../Api/AdaptableApi';
+/**
+ * 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 declare const DEFAULT_GRADIENT_MIN_ALPHA = 0.15;
+/**
+ * Default alpha at the **high** end of a Gradient range when `MaxAlpha` is unset.
+ */
+export declare const DEFAULT_GRADIENT_MAX_ALPHA = 1;
+export declare const hasGradientRangesConfigured: (gs: GradientStyle | undefined) => boolean;
+/** Number of sample cells shown in Gradient / Percent Bar style previews. */
+export declare const STYLED_COLUMN_PREVIEW_SAMPLE_COUNT = 6;
+/** Illustrative zero-centred scale endpoints for preview geometry. */
+export declare const ZERO_CENTRED_PREVIEW_SCALE_MIN = -20;
+export declare const ZERO_CENTRED_PREVIEW_SCALE_MAX = 20;
+/** @deprecated Use {@link getZeroCentredGradientPreviewValues} — kept for callers using endpoints. */
+export declare const ZERO_CENTRED_GRADIENT_PREVIEW_VALUES: readonly number[];
+export declare const getZeroCentredGradientPreviewValues: () => number[];
+export declare function isDivergingZeroCellRanges(ranges: CellColorRange[] | undefined): boolean;
+export declare function isZeroCentredGradientStyle(gs: GradientStyle): boolean;
+/**
+ * Sample cell values for gradient preview strips — spread across the effective scale.
+ */
+export declare const getGradientPreviewSampleValues: (styledColumn: StyledColumn, api: AdaptableApi) => number[];
+/**
+ * Cell CSS for gradient preview — mirrors `AgGridColumnAdapter.getStyledColumnStyle` gradient path.
+ */
+export declare const getGradientPreviewCellStyle: (cellValue: number, styledColumn: StyledColumn, api: AdaptableApi, rowNode?: IRowNode | null) => CSSProperties;
+/**
+ * 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 declare function expandGradientCellRanges(gs: GradientStyle): CellColorRange[] | undefined;
+/**
+ * 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 declare function gradientStyleRangeLookupValueType(gs: GradientStyle): NumericStyledColumn['RangeValueType'];
+/** The negative half of a zero-centred gradient (darker toward Col-Min). */
+export declare function isNegativeZeroCentredBand(range: CellColorRange): boolean;

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

@@ -0,0 +1,260 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getGradientPreviewCellStyle = exports.getGradientPreviewSampleValues = exports.getZeroCentredGradientPreviewValues = exports.ZERO_CENTRED_GRADIENT_PREVIEW_VALUES = exports.ZERO_CENTRED_PREVIEW_SCALE_MAX = exports.ZERO_CENTRED_PREVIEW_SCALE_MIN = exports.STYLED_COLUMN_PREVIEW_SAMPLE_COUNT = exports.hasGradientRangesConfigured = exports.DEFAULT_GRADIENT_MAX_ALPHA = exports.DEFAULT_GRADIENT_MIN_ALPHA = void 0;
+exports.isDivergingZeroCellRanges = isDivergingZeroCellRanges;
+exports.isZeroCentredGradientStyle = isZeroCentredGradientStyle;
+exports.expandGradientCellRanges = expandGradientCellRanges;
+exports.gradientStyleRangeLookupValueType = gradientStyleRangeLookupValueType;
+exports.isNegativeZeroCentredBand = isNegativeZeroCentredBand;
+const tslib_1 = require("tslib");
+const tinycolor2_1 = tslib_1.__importDefault(require("tinycolor2"));
+const StyleHelper_1 = require("../StyleHelper");
+const StyleHelper_2 = require("../StyleHelper");
+const NumberExtensions_1 = require("../../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).
+ */
+exports.DEFAULT_GRADIENT_MIN_ALPHA = 0.15;
+/**
+ * Default alpha at the **high** end of a Gradient range when `MaxAlpha` is unset.
+ */
+exports.DEFAULT_GRADIENT_MAX_ALPHA = 1;
+const hasGradientRangesConfigured = (gs) => !!(gs?.ZeroCentred || gs?.CellRanges?.length || gs?.ColumnComparison);
+exports.hasGradientRangesConfigured = hasGradientRangesConfigured;
+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. */
+exports.STYLED_COLUMN_PREVIEW_SAMPLE_COUNT = 6;
+/** Illustrative zero-centred scale endpoints for preview geometry. */
+exports.ZERO_CENTRED_PREVIEW_SCALE_MIN = -20;
+exports.ZERO_CENTRED_PREVIEW_SCALE_MAX = 20;
+/** @deprecated Use {@link getZeroCentredGradientPreviewValues} — kept for callers using endpoints. */
+exports.ZERO_CENTRED_GRADIENT_PREVIEW_VALUES = evenlySpacedValues(exports.ZERO_CENTRED_PREVIEW_SCALE_MIN, exports.ZERO_CENTRED_PREVIEW_SCALE_MAX, exports.STYLED_COLUMN_PREVIEW_SAMPLE_COUNT);
+const getZeroCentredGradientPreviewValues = () => evenlySpacedValues(exports.ZERO_CENTRED_PREVIEW_SCALE_MIN, exports.ZERO_CENTRED_PREVIEW_SCALE_MAX, exports.STYLED_COLUMN_PREVIEW_SAMPLE_COUNT);
+exports.getZeroCentredGradientPreviewValues = getZeroCentredGradientPreviewValues;
+function isDivergingZeroCellRanges(ranges) {
+    if (!ranges || ranges.length !== 2) {
+        return false;
+    }
+    const [a, b] = ranges;
+    return a.Max === 0 && b.Min === 0;
+}
+function isZeroCentredGradientStyle(gs) {
+    return !!(gs.ZeroCentred || isDivergingZeroCellRanges(gs.CellRanges));
+}
+/**
+ * Sample cell values for gradient preview strips — spread across the effective scale.
+ */
+const getGradientPreviewSampleValues = (styledColumn, api) => {
+    const gs = styledColumn.GradientStyle;
+    if (!gs || !(0, exports.hasGradientRangesConfigured)(gs)) {
+        return [];
+    }
+    if (isZeroCentredGradientStyle(gs)) {
+        return (0, exports.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, exports.STYLED_COLUMN_PREVIEW_SAMPLE_COUNT);
+        }
+        return evenlySpacedValues(0, 100, exports.STYLED_COLUMN_PREVIEW_SAMPLE_COUNT);
+    }
+    const column = styledColumn.ColumnId
+        ? api.columnApi.getColumnWithColumnId(styledColumn.ColumnId)
+        : undefined;
+    if (!column) {
+        return evenlySpacedValues(0, 100, exports.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, exports.STYLED_COLUMN_PREVIEW_SAMPLE_COUNT);
+};
+exports.getGradientPreviewSampleValues = getGradientPreviewSampleValues;
+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 = exports.ZERO_CENTRED_PREVIEW_SCALE_MIN;
+    const previewMax = exports.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 ?? exports.DEFAULT_GRADIENT_MIN_ALPHA;
+    const maxAlphaBound = gradientStyle.MaxAlpha ?? exports.DEFAULT_GRADIENT_MAX_ALPHA;
+    const lo = Math.min((0, NumberExtensions_1.clamp)(minAlphaBound, 0, 1), (0, NumberExtensions_1.clamp)(maxAlphaBound, 0, 1));
+    const hi = Math.max((0, NumberExtensions_1.clamp)(minAlphaBound, 0, 1), (0, NumberExtensions_1.clamp)(maxAlphaBound, 0, 1));
+    const span = Math.abs(max - min);
+    let t = span === 0 ? 0.5 : (Number(cellValue) - min) / span;
+    t = (0, NumberExtensions_1.clamp)(t, 0, 1);
+    if (reverseGradient) {
+        t = 1 - t;
+    }
+    const alpha = Number((lo + t * (hi - lo)).toPrecision(4));
+    let style = {};
+    const preparedColor = (0, StyleHelper_2.getVariableColor)(matchingRange.Color);
+    const bg = (0, tinycolor2_1.default)(preparedColor).setAlpha(alpha);
+    style.backgroundColor = bg.toRgbString();
+    if (gradientStyle.AutoContrastText) {
+        style.color = (0, StyleHelper_2.getAutoContrastTextColor)(preparedColor, alpha);
+    }
+    const autoContrastColor = gradientStyle.AutoContrastText && style.color ? style.color : undefined;
+    if (gradientStyle.Font) {
+        style = { ...style, ...(0, StyleHelper_1.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.
+ */
+const getGradientPreviewCellStyle = (cellValue, styledColumn, api, rowNode) => {
+    const gradientStyle = styledColumn.GradientStyle;
+    if (!gradientStyle || !(0, exports.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 ?? exports.DEFAULT_GRADIENT_MIN_ALPHA;
+    const maxAlphaBound = gradientStyle.MaxAlpha ?? exports.DEFAULT_GRADIENT_MAX_ALPHA;
+    const lo = Math.min((0, NumberExtensions_1.clamp)(minAlphaBound, 0, 1), (0, NumberExtensions_1.clamp)(maxAlphaBound, 0, 1));
+    const hi = Math.max((0, NumberExtensions_1.clamp)(minAlphaBound, 0, 1), (0, NumberExtensions_1.clamp)(maxAlphaBound, 0, 1));
+    const span = Math.abs(max - min);
+    let t = span === 0 ? 0.5 : (Number(cellValue) - min) / span;
+    t = (0, NumberExtensions_1.clamp)(t, 0, 1);
+    if (reverseGradient) {
+        t = 1 - t;
+    }
+    const alpha = Number((lo + t * (hi - lo)).toPrecision(4));
+    if (cellBackColor) {
+        const preparedColor = (0, StyleHelper_2.getVariableColor)(cellBackColor);
+        const bg = (0, tinycolor2_1.default)(preparedColor).setAlpha(alpha);
+        style.backgroundColor = bg.toRgbString();
+        if (gradientStyle.AutoContrastText) {
+            style.color = (0, StyleHelper_2.getAutoContrastTextColor)(preparedColor, alpha);
+        }
+    }
+    const autoContrastColor = gradientStyle.AutoContrastText && style.color ? style.color : undefined;
+    if (gradientStyle.Font) {
+        style = { ...style, ...(0, StyleHelper_1.convertAdaptableStyleToCSS)(gradientStyle.Font) };
+    }
+    if (autoContrastColor) {
+        style.color = autoContrastColor;
+    }
+    if (gradientStyle.Font?.Alignment && gradientStyle.Font.Alignment !== 'Default') {
+        style.textAlign = gradientStyle.Font.Alignment.toLowerCase();
+    }
+    return style;
+};
+exports.getGradientPreviewCellStyle = getGradientPreviewCellStyle;
+/**
+ * Effective cell ranges for gradient rendering / range lookup.
+ * When `ZeroCentred` is set, expands to the canonical Col-Min…0 and 0…Col-Max bands.
+ */
+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.
+ */
+function gradientStyleRangeLookupValueType(gs) {
+    return gs.ZeroCentred ? 'Number' : gs.RangeValueType ?? 'Number';
+}
+/** The negative half of a zero-centred gradient (darker toward Col-Min). */
+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,6 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ICON_STYLE_PRESET_DESCRIPTIONS = exports.ICON_STYLE_PRESET_LABELS = exports.getIconStylePresetMappings = exports.ICON_STYLE_PRESETS = void 0;
+exports.isUnsupportedColumnDataTypeForIconStyle = isUnsupportedColumnDataTypeForIconStyle;
+/**
+ * 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).
+ */
+function isUnsupportedColumnDataTypeForIconStyle(dataType) {
+    switch (dataType) {
+        case 'textArray':
+        case 'numberArray':
+        case 'tupleArray':
+        case 'objectArray':
+            return true;
+        default:
+            return false;
+    }
+}
 /**
  * Built-in {@link IconStyle} mapping presets.
  *