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

package/src/Utilities/Helpers/{ScheduleHelper.js → Scheduling/ScheduleHelper.js}

@@ -1,5 +1,5 @@
 import { parseExpression } from 'cron-parser';
-import StringExtensions from '../Extensions/StringExtensions';
+import StringExtensions from '../../Extensions/StringExtensions';
 const WEEKDAY_TO_CRON = {
     Sunday: 0,
     Monday: 1,
@@ -187,6 +187,8 @@ export function getScheduleDescription(schedule) {
         }
         case 'monthly':
             return `Monthly on day ${dayOfMonth} ${time}`;
+        case 'custom':
+            return schedule.CronExpression?.trim() || 'Custom Cron';
         default:
             return `${schedule.CronExpression ?? 'Custom'} ${time}`;
     }

package/src/Utilities/Helpers/{ScheduleJobManager.d.ts → Scheduling/ScheduleJobManager.d.ts}

@@ -1,4 +1,4 @@
-import { Schedule } from '../../AdaptableState/Common/Schedule';
+import { Schedule } from '../../../AdaptableState/Common/Schedule';
 export interface ScheduleJobManagerConfig<T> {
     getActiveItems: () => T[];
     getSchedule: (item: T) => Schedule | undefined;

package/src/Utilities/Helpers/{ScheduleJobRunner.d.ts → Scheduling/ScheduleJobRunner.d.ts}

@@ -1,4 +1,4 @@
-import { Schedule } from '../../AdaptableState/Common/Schedule';
+import { Schedule } from '../../../AdaptableState/Common/Schedule';
 export interface ScheduleJob {
     cancel: () => void;
 }

package/src/Utilities/Helpers/{ScheduledAlertHelper.d.ts → Scheduling/ScheduledAlertHelper.d.ts}

@@ -1,4 +1,4 @@
-import { AlertButtonForm, AlertDefinition, RuleAlertProperties, RuleBasedAlertDefinition, ScheduledAlertDefinition } from '../../AdaptableState/AlertState';
+import { AlertButtonForm, AlertDefinition, RuleAlertProperties, RuleBasedAlertDefinition, ScheduledAlertDefinition } from '../../../AdaptableState/AlertState';
 export declare function isScheduledAlertDefinition(alert: AlertDefinition | undefined | null): alert is ScheduledAlertDefinition;
 export declare function isRuleBasedAlertDefinition(alert: AlertDefinition | undefined | null): alert is RuleBasedAlertDefinition;
 export declare function getRuleAlertProperties(alert: AlertDefinition | undefined | null): RuleAlertProperties | undefined;

package/src/Utilities/Helpers/{ScheduledAlertHelper.js → Scheduling/ScheduledAlertHelper.js}

@@ -1,7 +1,7 @@
-import ObjectFactory from '../ObjectFactory';
-import { EMPTY_STRING } from '../Constants/GeneralConstants';
-import { ALERT_DEFAULT_MESSAGE_TYPE } from '../Constants/ObjectDefaultConstants';
-import { createUuid } from '../../AdaptableState/Uuid';
+import ObjectFactory from '../../ObjectFactory';
+import { EMPTY_STRING } from '../../Constants/GeneralConstants';
+import { ALERT_DEFAULT_MESSAGE_TYPE } from '../../Constants/ObjectDefaultConstants';
+import { createUuid } from '../../../AdaptableState/Uuid';
 export function isScheduledAlertDefinition(alert) {
     return alert != null && 'Schedule' in alert;
 }

package/src/Utilities/Helpers/{ScheduledJobsMiddlewareHelper.d.ts → Scheduling/ScheduledJobsMiddlewareHelper.d.ts}

@@ -1,3 +1,3 @@
-import { IAdaptable } from '../../AdaptableInterfaces/IAdaptable';
+import { IAdaptable } from '../../../AdaptableInterfaces/IAdaptable';
 export declare function refreshScheduledAlertJobs(adaptable: IAdaptable): void;
 export declare function refreshScheduledReportJobs(adaptable: IAdaptable): void;

package/src/Utilities/Helpers/{ScheduledJobsMiddlewareHelper.js → Scheduling/ScheduledJobsMiddlewareHelper.js}

@@ -1,4 +1,4 @@
-import * as ModuleConstants from '../Constants/ModuleConstants';
+import * as ModuleConstants from '../../Constants/ModuleConstants';
 export function refreshScheduledAlertJobs(adaptable) {
     const alertModule = adaptable.adaptableModules.get(ModuleConstants.AlertModuleId);
     alertModule?.setUpScheduledAlertJobs?.();

package/src/Utilities/Helpers/{ScheduledReportHelper.d.ts → Scheduling/ScheduledReportHelper.d.ts}

@@ -1,4 +1,4 @@
-import { ExportState, ReportNameType, ReportSchedule } from '../../AdaptableState/ExportState';
+import { ExportState, ReportNameType, ReportSchedule } from '../../../AdaptableState/ExportState';
 export declare function reportScheduleToSchedule(reportSchedule: {
     ReportName?: string;
     ScheduleType?: string;

package/src/Utilities/Helpers/{ScheduledReportHelper.js → Scheduling/ScheduledReportHelper.js}

@@ -1,4 +1,4 @@
-import { createUuid } from '../../AdaptableState/Uuid';
+import { createUuid } from '../../../AdaptableState/Uuid';
 export function reportScheduleToSchedule(reportSchedule) {
     const { ReportName: reportName, ScheduleType: _scheduleType, ...schedule } = reportSchedule;
     return {

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

@@ -0,0 +1,5 @@
+import { AdaptableApi } from '../../Api/AdaptableApi';
+import { SettingsPanelNavigation, SettingsPanelNavigationGroup, SettingsPanelOptions } from '../../AdaptableOptions/SettingsPanelOptions';
+export declare const DEFAULT_SETTINGS_PANEL_NAVIGATION_GROUPS: SettingsPanelNavigationGroup[];
+export declare const buildDefaultSettingsPanelNavigation: (customPanelNames?: string[]) => SettingsPanelNavigation;
+export declare const resolveSettingsPanelNavigation: (api: AdaptableApi, settingsPanelOptions: SettingsPanelOptions) => SettingsPanelNavigation;

package/src/Utilities/Helpers/SettingsPanelHelper.js

@@ -0,0 +1,61 @@
+export const DEFAULT_SETTINGS_PANEL_NAVIGATION_GROUPS = [
+    {
+        label: 'Grid & UI',
+        items: ['GridInfo', 'ColumnInfo', 'Dashboard', 'ToolPanel', 'StatusBar', 'Theme'],
+    },
+    {
+        label: 'Layout',
+        items: ['Layout', 'CalculatedColumn', 'CustomSort', 'Charting'],
+    },
+    {
+        label: 'Formatting',
+        items: ['FormatColumn', 'StyledColumn', 'FlashingCell'],
+    },
+    {
+        label: 'Filtering & Search',
+        items: ['QuickSearch', 'GridFilter', 'ColumnFilter', 'DataSet', 'NamedQuery'],
+    },
+    {
+        label: 'Notes & Annotations',
+        items: ['Alert', 'Note', 'Comment', 'FreeTextColumn', 'SystemStatus'],
+    },
+    {
+        label: 'Export & Import',
+        items: ['Export', 'DataImport'],
+    },
+    {
+        label: 'ֵEditing',
+        items: ['PlusMinus', 'Shortcut', 'DataChangeHistory'],
+    },
+    {
+        label: 'Administration',
+        items: ['TeamSharing', 'StateManagement'],
+    },
+];
+export const buildDefaultSettingsPanelNavigation = (customPanelNames = []) => {
+    const groups = DEFAULT_SETTINGS_PANEL_NAVIGATION_GROUPS.map((group) => ({
+        label: group.label,
+        items: [...group.items],
+    }));
+    if (customPanelNames.length) {
+        groups.push({
+            label: 'Custom Panels',
+            items: [...customPanelNames],
+        });
+    }
+    return { groups };
+};
+const cloneSettingsPanelNavigation = (navigation) => ({
+    groups: navigation.groups.map((group) => ({
+        label: group.label,
+        items: [...group.items],
+    })),
+});
+export const resolveSettingsPanelNavigation = (api, settingsPanelOptions) => {
+    const defaultNavigation = buildDefaultSettingsPanelNavigation(settingsPanelOptions.customSettingsPanels?.map((panel) => panel.name) ?? []);
+    if (!settingsPanelOptions.navigation) {
+        return defaultNavigation;
+    }
+    const context = api.internalApi.buildBaseContext();
+    return settingsPanelOptions.navigation(context, cloneSettingsPanelNavigation(defaultNavigation));
+};

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

@@ -48,3 +48,21 @@ export declare const toStyle: (style?: AdaptableStyle) => {
     borderStyle: string;
 };
 export declare const getVariableColor: (variable: string) => string;
+/**
+ * Default surface colour assumed to sit *behind* a semi-transparent cell tint
+ * when computing auto-contrast text. Gradient cells paint a base colour at a
+ * value-driven alpha, so the colour the user actually perceives is that tint
+ * composited over the grid cell background (white in the default light theme).
+ */
+export declare const DEFAULT_CELL_SURFACE_COLOR = "#ffffff";
+/**
+ * Picks a readable text colour (near-black or white) for a cell whose
+ * background is `baseColor` painted at `alpha` over `surfaceColor`.
+ *
+ * The tint must be composited over the surface *before* measuring luminance:
+ * `tinycolor.getLuminance()` ignores the alpha channel, so measuring the raw
+ * base colour would yield the same result for a faint cell and a fully-opaque
+ * one — making auto-contrast text identical on every row instead of adapting
+ * per cell.
+ */
+export declare const getAutoContrastTextColor: (baseColor: string, alpha: number, surfaceColor?: string) => string;

package/src/Utilities/Helpers/StyleHelper.js

@@ -1,3 +1,4 @@
+import tinycolor from 'tinycolor2';
 import { EnumExtensions } from '../Extensions/EnumExtensions';
 /**
  * Keys belonging to the "Font" slice (text rendering + alignment).
@@ -215,3 +216,29 @@ export const getVariableColor = (variable) => {
     }
     return getComputedStyle(document.documentElement).getPropertyValue(match[1]).trim();
 };
+/**
+ * Default surface colour assumed to sit *behind* a semi-transparent cell tint
+ * when computing auto-contrast text. Gradient cells paint a base colour at a
+ * value-driven alpha, so the colour the user actually perceives is that tint
+ * composited over the grid cell background (white in the default light theme).
+ */
+export const DEFAULT_CELL_SURFACE_COLOR = '#ffffff';
+/**
+ * Luminance above which a (composited, opaque) background is considered "light"
+ * enough to need dark text.
+ */
+const AUTO_CONTRAST_LUMINANCE_THRESHOLD = 0.45;
+/**
+ * Picks a readable text colour (near-black or white) for a cell whose
+ * background is `baseColor` painted at `alpha` over `surfaceColor`.
+ *
+ * The tint must be composited over the surface *before* measuring luminance:
+ * `tinycolor.getLuminance()` ignores the alpha channel, so measuring the raw
+ * base colour would yield the same result for a faint cell and a fully-opaque
+ * one — making auto-contrast text identical on every row instead of adapting
+ * per cell.
+ */
+export const getAutoContrastTextColor = (baseColor, alpha, surfaceColor = DEFAULT_CELL_SURFACE_COLOR) => {
+    const composited = tinycolor.mix(surfaceColor, baseColor, alpha * 100);
+    return composited.getLuminance() > AUTO_CONTRAST_LUMINANCE_THRESHOLD ? '#111111' : '#ffffff';
+};

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

@@ -0,0 +1,63 @@
+import { BarStyleCellTextHorizontalAlignment, BarStyleCellTextLayout, BarStyleCellTextPlacement, BarStyleCellTextProperties, BarStyleCellTextVerticalAlignment } from '../../../AdaptableState/StyledColumns/Common/BarStyleProperties';
+import { CellTextOption, CellTextOptions } from '../../../AdaptableState/StyledColumns/Common/CellTextOptions';
+export type BarStyleCellTextLabels = {
+    cellValue?: string;
+    percentage?: string;
+};
+export declare const resolveBarStyleCellTextLayout: (props: BarStyleCellTextProperties | undefined) => BarStyleCellTextLayout;
+/** True when any value is configured for display. */
+export declare const hasBarStyleCellTextConfigured: (props: BarStyleCellTextProperties | undefined) => boolean;
+/** Set of value tokens that currently have a placement. */
+export declare const getActiveBarStyleCellTextTokens: (props: BarStyleCellTextProperties | undefined) => CellTextOptions;
+export declare const mergeBarStyleCellTextProperties: (current: BarStyleCellTextProperties | undefined, patch: Partial<BarStyleCellTextProperties>) => BarStyleCellTextProperties | undefined;
+/**
+ * Set or clear a value's placement. Passing `placement: undefined` removes the value.
+ */
+export declare const setBarStyleCellTextPlacement: (current: BarStyleCellTextProperties | undefined, token: CellTextOption, placement: BarStyleCellTextPlacement | undefined) => BarStyleCellTextProperties | undefined;
+/**
+ * Patch a single axis of a value's placement (creating the value with defaults if
+ * needed). Used by the wizard's placement pickers.
+ */
+export declare const patchBarStyleCellTextPlacement: (current: BarStyleCellTextProperties | undefined, token: CellTextOption, patch: Partial<BarStyleCellTextPlacement>) => BarStyleCellTextProperties | undefined;
+/**
+ * Toggle whether a value is displayed. When turning on a previously-hidden
+ * value we use the default placement (Left / Below).
+ */
+export declare const toggleBarStyleCellTextToken: (current: BarStyleCellTextProperties | undefined, token: CellTextOption, show: boolean) => {
+    CellTextProperties: BarStyleCellTextProperties | undefined;
+};
+export declare const buildBarStyleCellTextLabels: (props: BarStyleCellTextProperties | undefined, cellValueLabel: string | undefined, percentageLabel: string | undefined) => BarStyleCellTextLabels;
+export declare const hasBarStyleCellTextLabels: (labels: BarStyleCellTextLabels) => boolean;
+/** Join active labels with a space, Cell Value first then Percent Value. */
+export declare const joinBarStyleCellTextLabels: (labels: BarStyleCellTextLabels) => string;
+export type BarStyleCellTextSlotEntry = {
+    vertical: BarStyleCellTextVerticalAlignment;
+    horizontal: BarStyleCellTextHorizontalAlignment;
+    /** Labels in render order (Cell Value first, then Percent Value). */
+    parts: string[];
+    /** The joined text, ready to render. */
+    text: string;
+};
+/**
+ * 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.
+ */
+export declare const resolveBarStyleCellTextSlots: (props: BarStyleCellTextProperties | undefined, labels: BarStyleCellTextLabels) => BarStyleCellTextSlotEntry[];
+export type BarStyleCellTextSlotPresence = {
+    hasAbove: boolean;
+    hasBelow: boolean;
+    hasMerged: boolean;
+};
+export declare const getBarStyleCellTextSlotPresence: (props: BarStyleCellTextProperties | undefined) => BarStyleCellTextSlotPresence;
+export declare const formatBarStyleCellTextLayoutSummary: (layout: BarStyleCellTextLayout) => string | undefined;
+export type MountBarStyleCellTextArgs = {
+    wrapperEl: HTMLElement;
+    mergedOverlayEl?: HTMLElement;
+    textClassName: string;
+    cellTextProperties?: BarStyleCellTextProperties;
+    labels: BarStyleCellTextLabels;
+    mergedPointerEventsNone?: boolean;
+};
+export declare const mountBarStyleCellText: (args: MountBarStyleCellTextArgs) => void;

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

@@ -0,0 +1,317 @@
+/** 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;
+};
+export const resolveBarStyleCellTextLayout = (props) => sanitizeCellTextLayout(props?.CellTextLayout);
+/** True when any value is configured for display. */
+export const hasBarStyleCellTextConfigured = (props) => {
+    const layout = resolveBarStyleCellTextLayout(props);
+    return Boolean(layout.CellValue || layout.PercentValue);
+};
+/** Set of value tokens that currently have a placement. */
+export const getActiveBarStyleCellTextTokens = (props) => {
+    const layout = resolveBarStyleCellTextLayout(props);
+    const tokens = [];
+    if (layout.CellValue) {
+        tokens.push('CellValue');
+    }
+    if (layout.PercentValue) {
+        tokens.push('PercentageValue');
+    }
+    return tokens;
+};
+export 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;
+};
+/**
+ * Set or clear a value's placement. Passing `placement: undefined` removes the value.
+ */
+export const setBarStyleCellTextPlacement = (current, token, placement) => {
+    const layout = resolveBarStyleCellTextLayout(current);
+    const next = { ...layout };
+    const key = token === 'CellValue' ? 'CellValue' : 'PercentValue';
+    if (placement) {
+        next[key] = sanitizePlacement(placement);
+    }
+    else {
+        delete next[key];
+    }
+    return mergeBarStyleCellTextProperties(current, { CellTextLayout: next });
+};
+/**
+ * Patch a single axis of a value's placement (creating the value with defaults if
+ * needed). Used by the wizard's placement pickers.
+ */
+export const patchBarStyleCellTextPlacement = (current, token, patch) => {
+    const layout = resolveBarStyleCellTextLayout(current);
+    const key = token === 'CellValue' ? 'CellValue' : 'PercentValue';
+    const existing = layout[key];
+    const nextPlacement = {
+        ...(existing ?? DEFAULT_PLACEMENT),
+        ...patch,
+    };
+    return setBarStyleCellTextPlacement(current, token, nextPlacement);
+};
+/**
+ * Toggle whether a value is displayed. When turning on a previously-hidden
+ * value we use the default placement (Left / Below).
+ */
+export const toggleBarStyleCellTextToken = (current, token, show) => {
+    const layout = resolveBarStyleCellTextLayout(current);
+    const key = token === 'CellValue' ? 'CellValue' : 'PercentValue';
+    if (show && !layout[key]) {
+        return {
+            CellTextProperties: setBarStyleCellTextPlacement(current, token, DEFAULT_PLACEMENT),
+        };
+    }
+    if (!show && layout[key]) {
+        return {
+            CellTextProperties: setBarStyleCellTextPlacement(current, token, undefined),
+        };
+    }
+    return { CellTextProperties: current };
+};
+export const buildBarStyleCellTextLabels = (props, cellValueLabel, percentageLabel) => {
+    const layout = resolveBarStyleCellTextLayout(props);
+    const labels = {};
+    if (layout.CellValue && cellValueLabel != undefined) {
+        labels.cellValue = cellValueLabel;
+    }
+    if (layout.PercentValue && percentageLabel != undefined) {
+        labels.percentage = percentageLabel;
+    }
+    return labels;
+};
+export const hasBarStyleCellTextLabels = (labels) => Boolean(labels.cellValue || labels.percentage);
+/** Join active labels with a space, Cell Value first then Percent Value. */
+export const joinBarStyleCellTextLabels = (labels) => {
+    const parts = [];
+    if (labels.cellValue)
+        parts.push(labels.cellValue);
+    if (labels.percentage)
+        parts.push(labels.percentage);
+    return parts.join(' ');
+};
+/**
+ * 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.
+ */
+export const resolveBarStyleCellTextSlots = (props, labels) => {
+    const layout = 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());
+};
+export const getBarStyleCellTextSlotPresence = (props) => {
+    const layout = 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'),
+    };
+};
+// ---------------------------------------------------------------------------
+// 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]}`;
+};
+export 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;
+};
+// ---------------------------------------------------------------------------
+// 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;
+};
+export const mountBarStyleCellText = (args) => {
+    const { cellTextProperties, labels, wrapperEl, textClassName } = args;
+    if (!hasBarStyleCellTextConfigured(cellTextProperties) || !hasBarStyleCellTextLabels(labels)) {
+        return;
+    }
+    const slots = 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 = 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);
+    }
+};

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;