@globalpayments/vega 2.87.0-beta.1 → 2.88.0

package/dist/types/helpers/translation/interface.d.ts

@@ -130,6 +130,7 @@ export type StaticTranslationKey =
 	| 'Center Align'
 	| 'Right Align'
 	| 'Justified'
+	| 'Line Height'
 	| 'Bullets'
 	| 'Numbers'
 	| 'More Indent'
@@ -196,4 +197,12 @@ export type StaticTranslationKey =
 	| 'Color swatch'
 	| 'Color {0}'
 	| 'Apply'
-	| 'Enter color';
+	| 'Enter color'
+	// RTE Special characters extension
+	| 'Special Characters'
+	| 'All'
+	| 'Latin'
+	| 'Mathematical'
+	| 'Arrows'
+	| 'Currency'
+	| '(Optional)';

package/dist/types/types/components.type.d.ts

@@ -4,6 +4,16 @@
  *
  * Link https://github.com/ionic-team/stencil/pull/3710/files#diff-6d39068d58e561ccab3d0a266c838b1c1287fad54ef292183cc0f1871adde751R117-R118
  */
+export {
+	BackgroundColorsTokenType,
+	BorderColorsTokenType,
+	BordersTokenType,
+	BreakpointsTokenType,
+	ShadowsTokenType,
+	SpacingTokenType,
+	TextColorsTokenType,
+	TypographyTokenType,
+} from '../types/design-token.type';
 export {
 	BorderStyleType,
 	BoxDisplayType,
@@ -47,16 +57,6 @@ export {
 } from '../components/vega-app-header-button/types';
 export { VegaBannerActionButtonType, VegaBannerPropType } from '../components/vega-banner/types';
 export { VegaBarChartOptionsType } from '../components/vega-chart/vega-bar-chart/types';
-export {
-	BackgroundColorsTokenType,
-	BorderColorsTokenType,
-	BordersTokenType,
-	BreakpointsTokenType,
-	ShadowsTokenType,
-	SpacingTokenType,
-	TextColorsTokenType,
-	TypographyTokenType,
-} from '../types/design-token.type';
 export {
 	AlignSelfType,
 	FlexBasisType,
@@ -227,6 +227,7 @@ export {
 	VegaRichTextLinkEditorStatus,
 	VegaRTELinkEditorRecord,
 } from '../components/vega-rich-text-editor/vega-rich-text-link-editor/types';
+export { VegaRTESpecialCharacterCategory } from '../components/vega-rich-text-editor/extensions/special-characters/types';
 export { RTETableCellBlock } from '../components/vega-rich-text-editor/extensions/table/dto/table-cell-block';
 export { VegaSectionTitleSizeType } from '../components/vega-section-title/types';
 export { VegaSegmentControlVariant, VegaSegmentProps } from '../components/vega-segment-control/types';

package/dist/types/types/public-api.d.ts

@@ -4,6 +4,7 @@ export * from '../components/vega-calendar/types';
 export { VegaTableNode, VegaTableCellNode, VegaTableCreateElementFunction, VegaTableSorterType, VegaTableCellRenderFunction, VegaTableFormItemProps, VegaTableEditComponentProps, VegaTableCellFormItemRenderFunction, } from '../components/vega-table/interface';
 export { EvaluateResult, FormFieldStatusMeta, FormFieldValueType, } from '../helpers/validator/rules/form-field-validation-rule';
 export { VegaThemeOverrideColors, BrandOptions, NewBrandOptions } from '../helpers/theme/theme';
+export type { ActionColorAccessibilityResult } from '../helpers/theme/controllers/action-color-accessibility-validator';
 export { LogLevelType } from '../utils/log';
 export { VegaDialogOption } from '../helpers/dialog/vega-dialog-controller';
 export { NumberMaskConfig } from '../helpers/formatter/string-formatter/number-mask-strategy';

package/dist/types/vega-color-token-contrast-checker/src/check/checker.d.ts

@@ -0,0 +1,177 @@
+import { ColorSearchEngine } from './search';
+import { ColorContrastDetail, ContextSurface, ContrastResult, FixabilityRecord, TokenCheckConfig } from './token-checks';
+/**
+ * Minimum shape the checker assumes about the override-color input. The checker
+ * encapsulates everything actionColor-related (validation, suggestion search,
+ * patching) — consumers don't need to wire those callbacks themselves.
+ */
+export interface ActionColorInput {
+  actionColor?: string;
+}
+/**
+ * Shape returned by the consumer's `generateOverrideThemes` callback.
+ *
+ * Compatible with vega-stencil's `OverrideColor` (`{ name: string; value: Nullable<string> }`).
+ * `value` may be `undefined`/`null` when a token has no override for the supplied input —
+ * such entries are dropped from the resulting token map.
+ */
+export interface OverrideTokenEntry {
+  name: string;
+  value?: string | null;
+}
+/**
+ * Dependencies required by {@link VegaColorTokenContrastChecker}.
+ *
+ * Both inputs come from the consumer's design-system layer and stay outside this
+ * package because they reference theme-system internals (vega-design's
+ * `LightModeColorTokens` and vega-stencil's `VegaColorSchemaOverridingController`).
+ *
+ * @template TInput Shape of the override-color input. Must extend
+ *   {@link ActionColorInput} so the checker can operate on `actionColor`.
+ */
+export interface CheckerDeps<TInput extends ActionColorInput> {
+  /**
+   * Source-of-truth design-token values for the static (non-actionColor-derived)
+   * tokens the checker compares against. Format: `Record<tokenName, "r, g, b, a">`.
+   * In vega-stencil this is `LightModeColorTokens`, generated by vega-design.
+   */
+  fixedSurfaceTokens: Record<string, string>;
+  /**
+   * Produce the override-token list for an input. Each entry's `value` is a CSS
+   * `r g b / a` string (or `null`/`undefined` for "no override"). The checker
+   * collapses this list into the resolved token map internally.
+   *
+   * In vega-stencil this is bound to `VegaColorSchemaOverridingController.generateOverrideThemes`.
+   */
+  generateOverrideThemes: (input: TInput) => readonly OverrideTokenEntry[];
+}
+/** Result of {@link VegaColorTokenContrastChecker.validate}. */
+export interface ContrastCheckResult {
+  /** `true` when every fixable-by-actionColor token passes WCAG. */
+  isAccessible: boolean;
+  /** Failing tokens that can be resolved by changing `actionColor`. */
+  details: ColorContrastDetail[];
+  /**
+   * Closest accessible actionColor (by OKLab ΔE) for the suggestion search. Present
+   * only when the input had an `actionColor`; equals the input value when the input
+   * is already accessible.
+   */
+  suggestedActionColor?: string;
+  /** `true` when the input's `actionColor` is not a valid color string. */
+  invalidInput?: boolean;
+  /**
+   * Token-level patches for tokens whose formula hard-caps contrast below the WCAG
+   * threshold. Pass back to the override pipeline to apply repairs. Empty when none
+   * are needed.
+   */
+  contrastCapPatches: Record<string, string>;
+}
+/**
+ * WCAG 2.1 AA contrast checker for `actionColor`-driven theme overrides. Combines
+ * the static token-pair catalogue (generated at build time) with consumer-supplied
+ * design-token values and an override-themes generator, and exposes a single
+ * pre-bound instance ready for `validate(input)` / `computeContrastCapPatches(input)`.
+ *
+ * Stateless against per-call inputs; holds a process-lifetime fixability cache keyed
+ * by `(tokenName, pairedWith, compositedOn)` — that property depends only on the
+ * catalogue and the override formulas, not on the user's input, so it can be probed
+ * once.
+ *
+ * @template TInput Shape of the override-color input. In vega-stencil this is
+ *   `VegaThemeOverrideColors`; tests can use a stricter or looser shape.
+ */
+export declare class VegaColorTokenContrastChecker<TInput extends ActionColorInput> {
+  /** Static surfaces table, derived from {@link CheckerDeps.fixedSurfaceTokens}. */
+  readonly fixedSurfaces: Readonly<Record<string, ContextSurface>>;
+  /** Per-instance search engine, pre-bound to {@link fixedSurfaces}. */
+  readonly search: ColorSearchEngine;
+  private readonly deps;
+  private fixabilityCache;
+  private static readonly FIXABILITY_PROBE_COLORS;
+  constructor(deps: CheckerDeps<TInput>);
+  /**
+   * Build the resolved token map for an input by collapsing
+   * {@link CheckerDeps.generateOverrideThemes} into a `Map<tokenName, value>`,
+   * dropping entries with empty values.
+   *
+   * Public so tests can assert on the materialized map and so the wrapper can
+   * re-export it as a convenience helper.
+   *
+   * @param {TInput} input - Override-color payload.
+   * @returns {Map<string, string>} Token name → CSS `r g b / a` value.
+   */
+  buildTokenMap(input: TInput): Map<string, string>;
+  /**
+   * Validate overrides against WCAG 2.1 AA (light mode).
+   *
+   * @param {TInput} input - Override-color payload to validate.
+   * @returns {ContrastCheckResult} Accessibility result, including failing details and optional patches.
+   */
+  validate(input: TInput): ContrastCheckResult;
+  /**
+   * Produce contrast-cap patches for tokens whose formula caps contrast below threshold.
+   *
+   * Two-tier strategy (minimal impact first):
+   *   1. α-ascent: raise alpha to meet contrast (preserves brand hue).
+   *   2. RGB shift: closest opaque color satisfying ALL surfaces (linear scan).
+   *
+   * @param {TInput} input - Override-color payload (must include `actionColor`).
+   * @returns {Record<string, string>} Map of tokenName → patched CSS value; empty if no repair needed.
+   */
+  computeContrastCapPatches(input: TInput): Record<string, string>;
+  /**
+   * Compute contrast for a single check using the supplied token map.
+   *
+   * @param {TokenCheckConfig} check - Check configuration.
+   * @param {Map<string, string>} tokenMap - Resolved token map.
+   * @returns {ContrastResult | null} Contrast result or null when token/surface can't be resolved.
+   */
+  computeTokenContrast(check: TokenCheckConfig, tokenMap: Map<string, string>): ContrastResult | null;
+  /**
+   * Resolve a `pairedWith` name to a {@link ContextSurface} using this checker's
+   * static surface table.
+   *
+   * @param {string} pairedWith - Token name to resolve.
+   * @param {Map<string, string>} tokenMap - Resolved token map (dynamic lookup wins).
+   * @returns {ContextSurface | undefined} Resolved surface, or undefined.
+   */
+  resolvePairedSurface(pairedWith: string, tokenMap: Map<string, string>): ContextSurface | undefined;
+  /**
+   * Get the per-check fixability record (cached over the process lifetime).
+   *
+   * @param {TokenCheckConfig} config - Check configuration.
+   * @returns {FixabilityRecord} `{ fixable, maxContrast }`.
+   */
+  getFixabilityRecord(config: TokenCheckConfig): FixabilityRecord;
+  /**
+   * Collect failing fixable tokens under the supplied token map.
+   *
+   * @param {Map<string, string>} tokenMap - Resolved token map.
+   * @param {boolean} earlyExit - If true, return after first failure.
+   * @returns {ColorContrastDetail[]} Array of failing token detail entries.
+   */
+  collectFailures(tokenMap: Map<string, string>, earlyExit?: boolean): ColorContrastDetail[];
+  /**
+   * Fast check: all fixable tokens pass contrast under the supplied token map.
+   *
+   * @param {Map<string, string>} tokenMap - Resolved token map.
+   * @returns {boolean} True if all fixable tokens pass.
+   */
+  isAccessible(tokenMap: Map<string, string>): boolean;
+  /** Empty `actionColor` is allowed (means "no override"); when present it must be a valid color. */
+  private static isValidActionColor;
+  /** Produce a new input with a different `actionColor`, preserving every other field. */
+  private withActionColor;
+  private static fixabilityCacheKey;
+  private buildFixabilityCache;
+  /**
+   * Find the closest accessible actionColor (by OKLab ΔE) within ±5° hue tolerance.
+   *
+   * @param {TInput} input - Current override input.
+   * @param {string} actionColor - Current action color hex (already extracted by validate()).
+   * @returns {string | undefined} Suggested hex, or undefined if none feasible.
+   */
+  private findSuggestedActionColor;
+  /** Verify a candidate value passes all checks for a token. */
+  private verifyCandidateSatisfiesAll;
+}

package/dist/types/vega-color-token-contrast-checker/src/check/color-math.d.ts

@@ -0,0 +1,125 @@
+/** Returns true if the string is a valid 3- or 6-digit hex color (with optional `#`). */
+export declare function isValidHexColor(hex: string): boolean;
+/**
+ * Returns true if the string is a valid color in any supported format:
+ * hex (3/6 digits), rgb(), or rgba().
+ */
+export declare function isValidColor(color: string): boolean;
+export declare type RgbColor = {
+  r: number;
+  g: number;
+  b: number;
+};
+export declare type ParsedTokenValue = {
+  rgb: RgbColor;
+  a: number;
+};
+export declare type OklabColor = {
+  L: number;
+  a: number;
+  b: number;
+};
+/** OKLCH — cylindrical OKLab. `h` is in degrees. */
+export declare type OklchColor = {
+  L: number;
+  C: number;
+  h: number;
+};
+/**
+ * Calculate the contrast ratio between two colors per WCAG 2.0. The operation is
+ * symmetric, so callers don't need to sort the arguments.
+ *
+ * @param {RgbColor} a - First color.
+ * @param {RgbColor} b - Second color.
+ * @returns {number} WCAG contrast ratio.
+ * @see https://www.w3.org/TR/WCAG20/#contrast-ratiodef
+ */
+export declare function getContrastRatio(a: RgbColor, b: RgbColor): number;
+/**
+ * Composite a semi-transparent foreground color over an opaque background using the
+ * standard alpha compositing formula.
+ *
+ * @param {RgbColor} fg - Foreground color.
+ * @param {number} fgAlpha - Foreground alpha (0–1).
+ * @param {RgbColor} bg - Background color.
+ * @returns {RgbColor} Composited opaque color.
+ */
+export declare function alphaComposite(fg: RgbColor, fgAlpha: number, bg: RgbColor): RgbColor;
+/**
+ * Convert an RGB color to its hex string representation.
+ *
+ * @param {RgbColor} color - RGB color to convert.
+ * @returns {string} Hex color string with leading `#`.
+ */
+export declare function rgbToHex(color: RgbColor): string;
+/**
+ * Parse a 3- or 6-char hex string into an RGB triplet.
+ *
+ * Throws on malformed input rather than returning a silently-NaN-poisoned color — a bad
+ * hex here is a programmer error (invalid `actionColor` on `VegaThemeOverrideColors`) and
+ * a fail-fast surface is easier to debug than garbage-propagating contrast ratios.
+ *
+ * @param {string} hex - Hex color string (3 or 6 digits, optional `#` prefix).
+ * @returns {RgbColor} Parsed RGB triplet.
+ */
+export declare function hexToRgb(hex: string): RgbColor;
+/**
+ * Parse any supported color format (hex, rgb(), rgba()) into an RGB triplet.
+ *
+ * Throws on malformed input. Alpha from rgba() is discarded — actionColor is opaque.
+ *
+ * @param {string} color - Color string in hex, rgb(), or rgba() format.
+ * @returns {RgbColor} Parsed RGB triplet.
+ */
+export declare function parseColorToRgb(color: string): RgbColor;
+/**
+ * Format a token value back to the `r g b / a` shape consumed by the theme layer.
+ *
+ * @param {RgbColor} rgb - RGB color.
+ * @param {number} alpha - Alpha value (0–1).
+ * @returns {string} Formatted token value string.
+ */
+export declare function formatTokenValue(rgb: RgbColor, alpha: number): string;
+/**
+ * Inverse of {@link formatTokenValue}. Returns `null` on unparseable input.
+ *
+ * @param {string} value - Token value string in `r g b / a` format.
+ * @returns {ParsedTokenValue | null} Parsed result or null.
+ */
+export declare function parseTokenValue(value: string): ParsedTokenValue | null;
+/**
+ * Convert an RGB color to its OKLab representation.
+ *
+ * @param {RgbColor} rgb - RGB color to convert.
+ * @returns {OklabColor} OKLab color.
+ */
+export declare function rgbToOklab(rgb: RgbColor): OklabColor;
+/**
+ * Convert an OKLab color to its RGB representation.
+ *
+ * @param {OklabColor} lab - OKLab color to convert.
+ * @returns {RgbColor} RGB color.
+ */
+export declare function oklabToRgb(lab: OklabColor): RgbColor;
+/**
+ * Convert an OKLab color to its OKLCH (cylindrical) representation.
+ *
+ * @param {OklabColor} lab - OKLab color to convert.
+ * @returns {OklchColor} OKLCH color.
+ */
+export declare function oklabToOklch(lab: OklabColor): OklchColor;
+/**
+ * Convert an OKLCH color to its OKLab (Cartesian) representation.
+ *
+ * @param {OklchColor} lch - OKLCH color to convert.
+ * @returns {OklabColor} OKLab color.
+ */
+export declare function oklchToOklab(lch: OklchColor): OklabColor;
+/**
+ * Perceptual color distance in OKLab (Euclidean ΔE, since OKLab is designed to be uniform).
+ *
+ * @param {OklabColor} a - First OKLab color.
+ * @param {OklabColor} b - Second OKLab color.
+ * @returns {number} Euclidean distance in OKLab space.
+ */
+export declare function oklabDeltaE(a: OklabColor, b: OklabColor): number;

package/dist/types/vega-color-token-contrast-checker/src/check/contrast-check-strategy.d.ts

@@ -0,0 +1,38 @@
+import { ParsedTokenValue, RgbColor } from './color-math';
+/**
+ * Resolved paired surface — RGB color + alpha, used as the counterpart in contrast checks.
+ * Structurally identical to the `ContextSurface` exported from `token-checks.ts`.
+ */
+declare type ContextSurface = {
+  rgb: RgbColor;
+  a: number;
+};
+/** WCAG 2.1 AA minimum contrast ratio for normal-size text. */
+export declare const WCAG_AA_NORMAL_TEXT: number;
+/** WCAG 2.1 AA minimum contrast ratio for UI components and large text. */
+export declare const WCAG_AA_NON_TEXT_CONTRAST: number;
+/** Rendered foreground/background pair for a single check. */
+export declare type FgBgPair = {
+  fg: RgbColor;
+  bg: RgbColor;
+};
+/**
+ * Abstract strategy for computing the rendered fg/bg pair from a token and its paired surface.
+ * Each subclass implements the compositing logic specific to its WCAG check category.
+ */
+export declare abstract class ContrastCheckStrategy {
+  /** WCAG AA required contrast ratio for this check category. */
+  abstract readonly requiredRatio: number;
+  /**
+   * Compute the effective foreground and background colors for contrast measurement.
+   *
+   * @param {ParsedTokenValue} token - Parsed token value (rgb + alpha).
+   * @param {ContextSurface} paired - The paired surface resolved from the catalogue.
+   * @param {ContextSurface | undefined} compositedOn - Optional override composite surface.
+   * @returns {FgBgPair} Rendered foreground and background.
+   */
+  abstract computeFgBg(token: ParsedTokenValue, paired: ContextSurface, compositedOn?: ContextSurface): FgBgPair;
+}
+/** Strategy registry — maps check type to its strategy instance. */
+export declare const STRATEGY_MAP: Record<string, ContrastCheckStrategy>;
+export {};

package/dist/types/vega-color-token-contrast-checker/src/check/search.d.ts

@@ -0,0 +1,58 @@
+import { RgbColor } from './color-math';
+import { ContextSurface, TokenCheckConfig } from './token-checks';
+/**
+ * Search engine for finding perceptually-closest feasible colors in OKLCH space and
+ * resolving minimum-alpha / RGB-shift fixes for WCAG contrast requirements.
+ *
+ * The constructor takes the static `fixedSurfaces` table and the `bg-primary` RGB used
+ * as the underlying composite surface for semi-transparent paint. Both come from the
+ * design-token map supplied by the consumer.
+ */
+export declare class ColorSearchEngine {
+  private readonly fixedSurfaces;
+  private readonly lightBgPrimary;
+  constructor(fixedSurfaces: Readonly<Record<string, ContextSurface>>);
+  /** Binary-search iterations on L axis; 10 → ~0.001 precision. */
+  private static readonly SUGGESTION_SEARCH_ITERATIONS;
+  /** Hue offsets (degrees) sampled during search; ±5° preserves brand hue family. */
+  private static readonly SUGGESTION_HUE_OFFSETS_DEG;
+  /** Chroma multipliers sampled during search; allows modest saturation drift. */
+  private static readonly SUGGESTION_CHROMA_SCALES;
+  /** Chroma below which the origin is treated as achromatic (hue/chroma grid skipped). */
+  private static readonly ACHROMATIC_CHROMA_EPSILON;
+  /** Uniform L-axis steps for linear scan; 100 → 0.01 precision, enough for narrow bands. */
+  private static readonly L_SCAN_STEPS;
+  /** 2⁻⁷ ≈ 0.008 precision; matches 2-decimal output rounding. */
+  private static readonly ALPHA_ASCENT_ITERATIONS;
+  /**
+   * Find the closest feasible color (by OKLab ΔE) within a (hue ± 5°, chroma × 0.6–1.4) grid.
+   *
+   * @param {RgbColor} origin - Starting RGB color to search from.
+   * @param {Function} isFeasible - Predicate returning true if a candidate RGB meets constraints.
+   * @param {boolean} assumeMonotone - `true`: binary search on L (fast, monotone predicate required);
+   *   `false`: linear scan on L (handles internal-band feasibility).
+   * @returns {RgbColor | undefined} Closest feasible RGB, or `undefined` if none found in envelope.
+   */
+  searchClosestFeasibleInOklch(origin: RgbColor, isFeasible: (rgb: RgbColor) => boolean, assumeMonotone?: boolean): RgbColor | undefined;
+  /**
+   * Binary-search for the minimum alpha that makes composite contrast ≥ threshold.
+   * Result is ceil-rounded to 2 decimals. Returns `undefined` if α=1.0 still fails.
+   *
+   * @param {RgbColor} rgb - Token's base RGB color.
+   * @param {number} currentAlpha - Current alpha (lower bound for search).
+   * @param {TokenCheckConfig} checkConfig - Token check configuration (pairing, type, compositedOn).
+   * @param {number} threshold - Required WCAG contrast ratio.
+   * @param {Map<string, string>} tokenMap - Resolved token map for surface lookups.
+   * @returns {number | undefined} Minimum alpha (ceil-rounded), or `undefined` if infeasible.
+   */
+  findMinimumAlphaForContrast(rgb: RgbColor, currentAlpha: number, checkConfig: TokenCheckConfig, threshold: number, tokenMap: Map<string, string>): number | undefined;
+  /**
+   * Find the closest opaque RGB (by OKLab ΔE) satisfying WCAG threshold against all configs.
+   *
+   * @param {RgbColor} originalRgb - Starting RGB color.
+   * @param {TokenCheckConfig[]} configs - Token check configs (one per paired surface).
+   * @param {Map<string, string>} tokenMap - Resolved token map for surface lookups.
+   * @returns {RgbColor | undefined} Closest feasible RGB, or `undefined` if none found.
+   */
+  findRgbPatchForContrastAll(originalRgb: RgbColor, configs: TokenCheckConfig[], tokenMap: Map<string, string>): RgbColor | undefined;
+}

package/dist/types/vega-color-token-contrast-checker/src/check/token-checks.d.ts

@@ -0,0 +1,122 @@
+import { RgbColor } from './color-math';
+/**
+ * A paired-with surface — the color value the token's rendered output is compared
+ * against. Carries an alpha because some tokens (e.g. v2-new-brand `text-on-action` =
+ * `252,252,254,0.9`) are themselves semi-transparent and must be composited onto their
+ * own background before contrast is measured.
+ */
+export declare type ContextSurface = {
+  rgb: RgbColor;
+  a: number;
+};
+/** Static token catalogue entry — produced by the build-time generator. */
+export declare type TokenCheckConfig = {
+  tokenName: string;
+  /**
+   * Name of the token whose rendered surface this check is measured against. Resolved
+   * by {@link resolvePairedSurface} — actionColor-derived tokens are looked up in
+   * `tokenMap`; static design tokens fall through to the `fixedSurfaces` table.
+   */
+  pairedWith: string;
+  /**
+   * Contrast check category — determines which {@link ContrastCheckStrategy} handles the
+   * fg/bg computation and which WCAG AA threshold applies:
+   *  - `'bg-text'`: token is a background; paired text sits on top (4.5:1).
+   *  - `'text-bg'`: token is foreground text; paired surface is behind (4.5:1).
+   *  - `'non-text-contrast'`: token is a border/ring/UI element (3:1).
+   */
+  type: 'bg-text' | 'text-bg' | 'non-text-contrast';
+  /**
+   * Override the surface the token is alpha-composited onto when computing its rendered
+   * color. Normally a semi-transparent `non-text-contrast` token is composited onto its
+   * `pairedWith` surface. For box-shadow rings that paint *outside* an element (on the
+   * page background) but are compared against the element's fill, set this to
+   * `'bg-primary'` so the composite matches what the browser actually renders.
+   */
+  compositedOn?: string;
+};
+/** Detail type for failing tokens — used by the validator's public result. */
+export declare type ColorContrastDetail = {
+  tokenName: string;
+  contrastRatio: number;
+  requiredRatio: number;
+};
+/** Contrast computation result including rendered colors. */
+export declare type ContrastResult = {
+  fg: RgbColor;
+  bg: RgbColor;
+  contrastRatio: number;
+};
+/** Per-check fixability record. */
+export declare type FixabilityRecord = {
+  fixable: boolean;
+  maxContrast: number;
+};
+/**
+ * Names of the static design tokens that have no `overrideGetter` — the surfaces every
+ * actionColor-derived token may be paired with. Source-of-truth for which static tokens
+ * the checker must know about. Kept here (not in the consumer) so adding new pair targets
+ * is a one-line change in this package.
+ *
+ * Each entry's real SCSS consumer is documented in the catalogue's inline comment.
+ * `bg-action-tertiary` is α=0 (fully transparent) — composites collapse to `bg-primary`.
+ */
+export declare const FIXED_PAIRED_SURFACE_TOKENS: readonly string[];
+/**
+ * Parse the comma-separated `r, g, b, a` shape used by the generated `*-color-tokens.ts` files.
+ *
+ * @param {string} value - Comma-separated string in `"r, g, b, a"` format (e.g. `"252, 252, 254, 0.9"`).
+ * @returns {ContextSurface} Parsed {@link ContextSurface} with `rgb` and `a` fields.
+ * @throws {Error} If the string has fewer than 4 parts or contains non-numeric values.
+ */
+export declare function parseCommaTokenValue(value: string): ContextSurface;
+/**
+ * Build the fixed paired-surface table from the consumer's static design-token map.
+ *
+ * @param {Record<string, string>} designTokens - Source design tokens (token name → "r, g, b, a").
+ * @returns {Readonly<Record<string, ContextSurface>>} Frozen table for the checker.
+ */
+export declare function buildFixedPairedSurfaces(designTokens: Record<string, string>): Readonly<Record<string, ContextSurface>>;
+/**
+ * Resolve a `pairedWith` name to its rendered {@link ContextSurface}.
+ *
+ * Lookup order:
+ *  1. **`tokenMap` (actionColor-derived)** — covers every token that has an
+ *     `overrideGetter` and therefore depends on `actionColor`.
+ *  2. **`fixedSurfaces`** — covers the static design tokens that have no `overrideGetter`.
+ *
+ * @param {string} pairedWith - Token name to resolve.
+ * @param {Map<string, string>} tokenMap - Resolved token map for dynamic lookups.
+ * @param {Readonly<Record<string, ContextSurface>>} fixedSurfaces - Static surface table.
+ * @returns {ContextSurface | undefined} Resolved surface, or undefined if not found.
+ */
+export declare function resolvePairedSurface(pairedWith: string, tokenMap: Map<string, string>, fixedSurfaces: Readonly<Record<string, ContextSurface>>): ContextSurface | undefined;
+/**
+ * Resolve a paired surface to its rendered foreground RGB when it sits on top of `bg`.
+ * For opaque surfaces this is a no-op; for `text-on-action` (α<1) it performs the alpha
+ * composite the browser does at paint time, so the contrast ratio we compute matches
+ * what axe / Chrome DevTools see.
+ *
+ * @param {ContextSurface} surface - Surface to resolve.
+ * @param {RgbColor} bg - Background color for alpha compositing.
+ * @returns {RgbColor} Effective foreground RGB.
+ */
+export declare function effectiveFgRgb(surface: ContextSurface, bg: RgbColor): RgbColor;
+/**
+ * Return the WCAG AA required contrast ratio for a check type.
+ *
+ * @param {TokenCheckConfig['type']} type - Check type.
+ * @returns {number} Required contrast ratio.
+ */
+export declare function requiredRatioFor(type: TokenCheckConfig['type']): number;
+/**
+ * Compute the contrast ratio + rendered colors for a single token check under a given
+ * `actionColor`. Returns null when the token has no override value, the value can't be
+ * parsed, or the paired surface fails to resolve (catalogue typo).
+ *
+ * @param {TokenCheckConfig} checkConfig - Token check configuration.
+ * @param {Map<string, string>} tokenMap - Resolved token map for surface lookups.
+ * @param {Readonly<Record<string, ContextSurface>>} fixedSurfaces - Static surface table.
+ * @returns {ContrastResult | null} Contrast result or null.
+ */
+export declare function computeTokenContrast(checkConfig: TokenCheckConfig, tokenMap: Map<string, string>, fixedSurfaces: Readonly<Record<string, ContextSurface>>): ContrastResult | null;

package/dist/types/vega-color-token-contrast-checker/src/check/token-checks.generated.d.ts

@@ -0,0 +1,2 @@
+import type { TokenCheckConfig } from './token-checks';
+export declare const ACTION_COLOR_CHECKS: readonly TokenCheckConfig[];

package/dist/types/vega-color-token-contrast-checker/src/index.d.ts

@@ -0,0 +1,2 @@
+export { VegaColorTokenContrastChecker, ContrastCheckResult } from './check/checker';
+export { ColorContrastDetail } from './check/token-checks';

package/dist/vega/index.esm.js

@@ -1 +1 @@
-export{g as getCurrentBreakpoint}from"./p-49a2e141.js";export{L as LogUtility,s as setVegaLogLevel}from"./p-6e1ab235.js";export{d as formatAndValidBackgroundColor,e as formatAndValidBorderColor,g as formatAndValidBorderRadius,c as formatAndValidBreakpointSize,a as formatAndValidGap,h as formatAndValidPadding,f as formatAndValidResponsiveToken,b as formatAndValidShadow,i as formatAndValidTextColor}from"./p-19adf714.js";export{c as camelToDashCase}from"./p-02841589.js";export{d as BackgroundColorMap,a as BackgroundColors,e as BorderColorMap,b as BorderColors,B as BorderRadius,C as Colors,F as FillBackgroundColors,g as ShadowMap,f as Shadows,h as Spacing,S as StrokeBackgroundColors,c as TextColorMap,T as TextColors}from"./p-78ba7ca9.js";export{B as Breakpoints}from"./p-ed45b3b6.js";export{I as Icons,g as getIconFromToken}from"./p-16493e5b.js";export{b as Typography,a as TypographyKeys,T as TypographyUrls}from"./p-d884c644.js";export{d as BoxDisplay,e as BreakpointKeys,C as CssStates,F as FlexDirections}from"./p-d4ea8e22.js";export{F as FrameworkEnum,v as VegaEnvManager}from"./p-5f377954.js";export{A as ActionHandlerInterceptor,I as InsertNodeToNearestRootAction,o as RTELanguageToolbarButtonRenderer,m as RTETokenNode,n as RTETokenNodeRenderer,R as RTETokenToolbarButtonRenderer,b as VegaEventManager,V as VegaLoader,a as VegaNotify,j as VegaRTEExtension,k as VegaRTEExtensionRenderer,h as VegaRTEFunctionExtension,g as VegaRTELanguageExtension,i as VegaRTETableExtension,f as VegaRTETokenExtension,l as VegaRTEToolbarButtonRenderer,d as VegaSkeletonLoader,e as VegaTranslation,c as VegaZIndexManager,w as waitForVega}from"./p-32a0f887.js";export{F as FeatureFlag}from"./p-dcf162e9.js";export{V as VegaThemeManager}from"./p-0d97dcb9.js";export{V as VegaDialog}from"./p-b6be1f33.js";export{B as VegaJQueryDelegatedEventStrategy}from"./p-4dd02704.js";export{V as VegaIconManager}from"./p-1704ff25.js";export{V as ValidCreditCardNumberRule}from"./p-858ec529.js";import"./p-ec2a1d4c.js";export{s as VegaTranslationResourceEN}from"./p-0a261b66.js";export{s as setVegaNonce}from"./p-4866e390.js";export{g as ActionHandleStrategy,h as AppendChildrenAction,ab as CodeLanguage,o as CustomAttributeAnnotation,D as CustomClassAnnotation,z as CustomStyleAnnotation,I as InsertChildrenAfterAction,j as InsertChildrenBeforeAction,M as ModifyContentAction,l as ModifyContentActionType,f as RTEAnnotationStyle,d as RTEBlock,G as RTEDecoratorNode,p as RTEFilterStylesStrategy,i as RTENode,e as RTETextBlock,c as RTETextNode,n as RemoveChildrenAction,ac as VegaRTEDefaultTextStyleItems,V as VegaRTEPresetToolbarItems}from"./p-a2b8d49d.js";export{B as BlockToRTEBlockStrategyAbstract,a as ElementToDTOStrategy,I as InsertNewParagraphAction,b as RTEImageBlock,f as RTEImageNode,e as RTEListBlock,d as RTEListItemBlock,U as UpdateCursorPositionAction,V as VegaRTEContent,h as htmlElementToAnnotationGenerator}from"./p-e8ea3b16.js";export{G as GridColumns,a as GridRows}from"./p-b02b985d.js";export{C as CheckBoxRequiredRule}from"./p-590fd123.js";export{D as DateRequiredRule}from"./p-189d36ec.js";export{I as InputPhoneNumberRequiredRule}from"./p-07c2725a.js";export{I as InputRangeRequiredRule}from"./p-f396c69a.js";export{R as RequiredFieldRule}from"./p-280cbcdb.js";export{R as RichTextEditorRequiredRule}from"./p-042933f1.js";export{T as TimeRangeRequiredRule,a as TimeRequiredRule}from"./p-a0dd08b1.js";export{T as ToggleSwitchRequiredRule}from"./p-7c0b4c36.js";export{F as FileUploaderRequiredRule}from"./p-0bb860cc.js";export{R as RTERange}from"./p-72e2a587.js";import"./p-281fa1e0.js";import"./p-8b5d3a52.js";import"./p-9a6bd32c.js";import"./p-6a334573.js";import"./p-781fd6e0.js";import"./p-262ec334.js";import"./p-81dd00d0.js";import"./p-b75ee3ba.js";import"./p-b6c3ce6d.js";import"./p-a7b5f497.js";import"./p-724df1f5.js";import"./p-11e2dcf5.js";import"./p-2d0d575f.js";import"./p-331a62d5.js";import"./p-2927b7a1.js";import"./p-3a93730e.js";import"./p-77e64f26.js";import"./p-8aee6b74.js";import"./p-a528714c.js";import"./p-fb5ea4b2.js";import"./p-f0e828d8.js";import"./p-0c667d6a.js";import"./p-a841cf13.js";import"./p-1bc5b3bc.js";import"./p-982747ef.js";import"./p-abd7aeaa.js";import"./p-d27ae9ff.js";const r=["ring-input-focus","dark-ring-input-focus","ring-input-danger-focus","dark-ring-input-danger-focus","ring-action-focus","dark-ring-action-focus","ring-action-danger-focus","dark-ring-action-danger-focus"];export{r as Rings}
+export{g as getCurrentBreakpoint}from"./p-49a2e141.js";export{L as LogUtility,s as setVegaLogLevel}from"./p-6e1ab235.js";export{d as formatAndValidBackgroundColor,e as formatAndValidBorderColor,g as formatAndValidBorderRadius,c as formatAndValidBreakpointSize,a as formatAndValidGap,h as formatAndValidPadding,f as formatAndValidResponsiveToken,b as formatAndValidShadow,i as formatAndValidTextColor}from"./p-788ada42.js";export{c as camelToDashCase}from"./p-02841589.js";export{d as BackgroundColorMap,a as BackgroundColors,e as BorderColorMap,b as BorderColors,B as BorderRadius,C as Colors,F as FillBackgroundColors,g as ShadowMap,f as Shadows,h as Spacing,S as StrokeBackgroundColors,c as TextColorMap,T as TextColors}from"./p-f7ad9349.js";export{B as Breakpoints}from"./p-ed45b3b6.js";export{I as Icons,g as getIconFromToken}from"./p-16493e5b.js";export{b as Typography,a as TypographyKeys,T as TypographyUrls}from"./p-d884c644.js";export{d as BoxDisplay,e as BreakpointKeys,C as CssStates,F as FlexDirections}from"./p-d4ea8e22.js";export{F as FrameworkEnum,v as VegaEnvManager}from"./p-5f377954.js";export{A as ActionHandlerInterceptor,I as InsertNodeToNearestRootAction,y as RTELanguageToolbarButtonRenderer,v as RTETokenNode,x as RTETokenNodeRenderer,R as RTETokenToolbarButtonRenderer,b as VegaEventManager,V as VegaLoader,a as VegaNotify,h as VegaRTEDefaultLineHeightOptions,s as VegaRTEExtension,t as VegaRTEExtensionRenderer,i as VegaRTEFunctionExtension,g as VegaRTELanguageExtension,r as VegaRTELineHeightExtension,o as VegaRTESpecialCharactersArrows,p as VegaRTESpecialCharactersCurrency,l as VegaRTESpecialCharactersEssentials,k as VegaRTESpecialCharactersExtension,m as VegaRTESpecialCharactersLatin,n as VegaRTESpecialCharactersMathematical,q as VegaRTESpecialCharactersText,j as VegaRTETableExtension,f as VegaRTETokenExtension,u as VegaRTEToolbarButtonRenderer,d as VegaSkeletonLoader,e as VegaTranslation,c as VegaZIndexManager,w as waitForVega}from"./p-50958342.js";export{F as FeatureFlag}from"./p-dcf162e9.js";export{V as VegaThemeManager}from"./p-b857a661.js";export{V as VegaDialog}from"./p-b6be1f33.js";export{B as VegaJQueryDelegatedEventStrategy}from"./p-c84aa55a.js";export{V as VegaIconManager}from"./p-1704ff25.js";export{V as ValidCreditCardNumberRule}from"./p-c93dfe23.js";import"./p-ec2a1d4c.js";export{s as VegaTranslationResourceEN}from"./p-fea75b87.js";export{s as setVegaNonce}from"./p-4866e390.js";export{g as ActionHandleStrategy,h as AppendChildrenAction,ab as CodeLanguage,o as CustomAttributeAnnotation,E as CustomClassAnnotation,r as CustomStyleAnnotation,I as InsertChildrenAfterAction,j as InsertChildrenBeforeAction,M as ModifyContentAction,l as ModifyContentActionType,f as RTEAnnotationStyle,d as RTEBlock,G as RTEDecoratorNode,p as RTEFilterStylesStrategy,i as RTENode,e as RTETextBlock,c as RTETextNode,n as RemoveChildrenAction,ac as VegaRTEDefaultTextStyleItems,V as VegaRTEPresetToolbarItems}from"./p-3312e3dd.js";export{B as BlockToRTEBlockStrategyAbstract,a as ElementToDTOStrategy,I as InsertNewParagraphAction,b as RTEImageBlock,f as RTEImageNode,e as RTEListBlock,d as RTEListItemBlock,U as UpdateCursorPositionAction,V as VegaRTEContent,h as htmlElementToAnnotationGenerator}from"./p-30f76962.js";export{G as GridColumns,a as GridRows}from"./p-f0d70de3.js";export{C as CheckBoxRequiredRule}from"./p-590fd123.js";export{D as DateRequiredRule}from"./p-81d55efd.js";export{I as InputPhoneNumberRequiredRule}from"./p-07c2725a.js";export{I as InputRangeRequiredRule}from"./p-f396c69a.js";export{R as RequiredFieldRule}from"./p-280cbcdb.js";export{R as RichTextEditorRequiredRule}from"./p-cacec680.js";export{T as TimeRangeRequiredRule,a as TimeRequiredRule}from"./p-36e46c4f.js";export{T as ToggleSwitchRequiredRule}from"./p-7c0b4c36.js";export{F as FileUploaderRequiredRule}from"./p-0bb860cc.js";export{R as RTERange}from"./p-0b2ca33b.js";import"./p-0c460945.js";import"./p-8b5d3a52.js";import"./p-9a6bd32c.js";import"./p-6a334573.js";import"./p-781fd6e0.js";import"./p-262ec334.js";import"./p-81dd00d0.js";import"./p-b75ee3ba.js";import"./p-b6c3ce6d.js";import"./p-a7b5f497.js";import"./p-724df1f5.js";import"./p-11e2dcf5.js";import"./p-2d0d575f.js";import"./p-331a62d5.js";import"./p-05dc6718.js";import"./p-3a93730e.js";import"./p-77e64f26.js";import"./p-b565a6a5.js";import"./p-a528714c.js";import"./p-fb5ea4b2.js";import"./p-f0e828d8.js";import"./p-0c667d6a.js";import"./p-a841cf13.js";import"./p-1bc5b3bc.js";import"./p-1f563387.js";import"./p-982747ef.js";import"./p-abd7aeaa.js";import"./p-d27ae9ff.js";const N=["ring-input-focus","dark-ring-input-focus","ring-input-danger-focus","dark-ring-input-danger-focus","ring-action-focus","dark-ring-action-focus","ring-action-danger-focus","dark-ring-action-danger-focus"];export{N as Rings}