@react-native-ama/core 1.2.1 → 2.0.0-beta.0

package/src/internals/checks/checkContrast.test.ts

@@ -0,0 +1,278 @@
+import type { AmaNode } from '../../ReactNativeAma.types';
+import { checkContrast } from './checkContrast';
+
+jest.mock('../utils/ignoreContrastCheck', () => ({
+  shouldIgnoreContrastCheckForDisabledElement: jest.fn(() => false),
+}));
+
+jest.mock('../utils/getRuleAction', () => ({
+  getRuleAction: jest.fn(() => 'SHOULD'),
+}));
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  const { getRuleAction } = require('../utils/getRuleAction');
+  getRuleAction.mockReturnValue('SHOULD');
+
+  const { shouldIgnoreContrastCheckForDisabledElement } = require('../utils/ignoreContrastCheck');
+  shouldIgnoreContrastCheckForDisabledElement.mockReturnValue(false);
+});
+
+// Contrast ratios (verified against WCAG algorithm):
+// #000000 on #FFFFFF = 21.00:1
+// #595959 on #FFFFFF =  7.00:1  (passes AAA normal: >=7.0)
+// #606060 on #FFFFFF =  6.29:1  (fails AAA normal, passes AA)
+// #757575 on #FFFFFF =  4.61:1  (fails AAA normal, passes AA)
+// #777777 on #FFFFFF =  4.48:1  (fails AA normal)
+// #909090 on #FFFFFF =  3.19:1  (fails AAA large: <4.5, passes AA large: >=3.0)
+// #949494 on #FFFFFF =  3.03:1  (fails AAA large, passes AA large)
+// #959595 on #FFFFFF =  2.99:1  (fails AA large: <3.0)
+
+describe('checkContrast', () => {
+  const createNode = (overrides: Partial<AmaNode> = {}): AmaNode => ({
+    type: 'Text',
+    viewId: 1,
+    bounds: [0, 0, 100, 100],
+    content: 'Test content',
+    fg: '#000000',
+    bg: '#FFFFFF',
+    fontSize: 16,
+    isBold: false,
+    isEnabled: true,
+    isAccessible: true,
+    hasOnSubmitEditing: false,
+    ...overrides,
+  });
+
+  describe('Color conversion and contrast calculation', () => {
+    it('passes with high contrast black on white (21:1 ratio)', () => {
+      expect(checkContrast(createNode({ fg: '#000000', bg: '#FFFFFF' }))).toBeNull();
+    });
+
+    it('passes with white on black', () => {
+      expect(checkContrast(createNode({ fg: '#FFFFFF', bg: '#000000' }))).toBeNull();
+    });
+
+    it('handles shorthand hex colors (#FFF)', () => {
+      expect(checkContrast(createNode({ fg: '#000', bg: '#FFF' }))).toBeNull();
+    });
+
+    it('handles hex colors without # prefix', () => {
+      expect(checkContrast(createNode({ fg: '000000', bg: 'FFFFFF' }))).toBeNull();
+    });
+  });
+
+  describe('WCAG AA compliance (normal text)', () => {
+    it('fails AA with contrast ratio below 4.5:1 for normal text', () => {
+      // #777777 on white = 4.48:1 — fails AA
+      const { getRuleAction } = require('../utils/getRuleAction');
+      getRuleAction.mockReturnValue('PLEASE_FORGIVE_ME');
+
+      const node = createNode({ fg: '#777777', bg: '#FFFFFF', fontSize: 16 });
+      const result = checkContrast(node);
+      expect(result).toMatchObject({ rule: 'CONTRAST_FAILED', viewId: 1 });
+      expect(result?.extra).toContain('4.5');
+    });
+
+    it('passes AA with contrast ratio >=4.5:1 for normal text (reports AAA failure)', () => {
+      // #757575 on white = 4.61:1 — passes AA, fails AAA (< 7.0)
+      const node = createNode({ fg: '#757575', bg: '#FFFFFF', fontSize: 16 });
+      const result = checkContrast(node);
+      expect(result).toMatchObject({ rule: 'CONTRAST_FAILED_AAA' });
+    });
+  });
+
+  describe('WCAG AAA compliance', () => {
+    it('fails AAA with contrast ratio below 7:1 for normal text', () => {
+      // #606060 on white = 6.29:1 — passes AA, fails AAA
+      const node = createNode({ fg: '#606060', bg: '#FFFFFF', fontSize: 16 });
+      const result = checkContrast(node);
+      expect(result).toMatchObject({ rule: 'CONTRAST_FAILED_AAA', viewId: 1 });
+      expect(result?.extra).toContain('7');
+    });
+
+    it('passes AAA with 7:1 contrast ratio for normal text', () => {
+      // #595959 on white = exactly 7.00:1 — passes AAA
+      const node = createNode({ fg: '#595959', bg: '#FFFFFF', fontSize: 16 });
+      expect(checkContrast(node)).toBeNull();
+    });
+  });
+
+  describe('Large text rules', () => {
+    it('treats 18pt text as large — AAA requires 4.5:1 for large text', () => {
+      // #909090 on white = 3.19:1 — passes large AA (>=3.0), fails large AAA (< 4.5)
+      const node = createNode({ fg: '#909090', bg: '#FFFFFF', fontSize: 18 });
+      const result = checkContrast(node);
+      expect(result).toMatchObject({ rule: 'CONTRAST_FAILED_AAA' });
+      expect(result?.extra).toContain('4.5');
+    });
+
+    it('treats 14pt bold text as large', () => {
+      // #949494 on white = 3.03:1 — passes large AA (>=3.0), fails large AAA (< 4.5)
+      const node = createNode({ fg: '#949494', bg: '#FFFFFF', fontSize: 14, isBold: true });
+      const result = checkContrast(node);
+      expect(result).toMatchObject({ rule: 'CONTRAST_FAILED_AAA' });
+    });
+
+    it('does not treat 14pt non-bold text as large (uses normal text thresholds)', () => {
+      // #949494 = 3.03:1 — fails normal AA (<4.5), and with AAA disabled, returns CONTRAST_FAILED
+      const { getRuleAction } = require('../utils/getRuleAction');
+      getRuleAction.mockReturnValue('PLEASE_FORGIVE_ME');
+
+      const node = createNode({ fg: '#949494', bg: '#FFFFFF', fontSize: 14, isBold: false });
+      const result = checkContrast(node);
+      expect(result).toMatchObject({ rule: 'CONTRAST_FAILED' });
+    });
+
+    it('fails AA for large text with contrast below 3:1', () => {
+      // #959595 on white = 2.99:1 — fails large AA (<3.0)
+      const { getRuleAction } = require('../utils/getRuleAction');
+      getRuleAction.mockReturnValue('PLEASE_FORGIVE_ME');
+
+      const node = createNode({ fg: '#959595', bg: '#FFFFFF', fontSize: 18 });
+      const result = checkContrast(node);
+      expect(result).toMatchObject({ rule: 'CONTRAST_FAILED' });
+      expect(result?.extra).toContain('3.0');
+    });
+  });
+
+  describe('Edge cases and validation', () => {
+    it('returns null when foreground color is missing', () => {
+      expect(checkContrast(createNode({ fg: undefined }))).toBeNull();
+    });
+
+    it('returns null when background color is missing', () => {
+      expect(checkContrast(createNode({ bg: undefined }))).toBeNull();
+    });
+
+    it('returns null when content is missing (icon-only buttons)', () => {
+      expect(checkContrast(createNode({ content: undefined }))).toBeNull();
+    });
+
+    it('returns null when content is empty string', () => {
+      expect(checkContrast(createNode({ content: '' }))).toBeNull();
+    });
+
+    it('handles unknown/invalid hex color for foreground gracefully', () => {
+      // Invalid hex → luminance 0 → very high contrast with white → passes or fails depending on bg
+      // 'invalid' gives luminance 0, white gives 1.0, contrast = 21:1 → passes
+      // This verifies we don't throw on invalid input
+      expect(() => checkContrast(createNode({ fg: 'invalid', bg: '#FFFFFF' }))).not.toThrow();
+    });
+
+    it('handles unknown/invalid hex color for background gracefully', () => {
+      expect(() => checkContrast(createNode({ fg: '#000000', bg: 'invalid' }))).not.toThrow();
+    });
+  });
+
+  describe('Disabled element handling', () => {
+    it('checks contrast for disabled elements when ignore setting is false', () => {
+      const { shouldIgnoreContrastCheckForDisabledElement } = require('../utils/ignoreContrastCheck');
+      shouldIgnoreContrastCheckForDisabledElement.mockReturnValue(false);
+
+      const { getRuleAction } = require('../utils/getRuleAction');
+      getRuleAction.mockReturnValue('PLEASE_FORGIVE_ME');
+
+      // #777777 = 4.48:1 — fails AA for normal text
+      const node = createNode({ isEnabled: false, fg: '#777777', bg: '#FFFFFF', fontSize: 16 });
+      expect(checkContrast(node)).not.toBeNull();
+    });
+
+    it('skips contrast check for disabled elements when ignore setting is true', () => {
+      const { shouldIgnoreContrastCheckForDisabledElement } = require('../utils/ignoreContrastCheck');
+      shouldIgnoreContrastCheckForDisabledElement.mockReturnValue(true);
+
+      const node = createNode({ isEnabled: false, fg: '#777777', bg: '#FFFFFF', fontSize: 16 });
+      expect(checkContrast(node)).toBeNull();
+    });
+  });
+
+  describe('Error message formatting', () => {
+    it('includes foreground and background colors in error message', () => {
+      const { getRuleAction } = require('../utils/getRuleAction');
+      getRuleAction.mockReturnValue('PLEASE_FORGIVE_ME');
+
+      // #777777 = 4.48:1 — fails AA
+      const node = createNode({ fg: '#777777', bg: '#FFFFFF', fontSize: 16 });
+      const result = checkContrast(node);
+      expect(result?.extra).toContain('#777777');
+      expect(result?.extra).toContain('#FFFFFF');
+    });
+
+    it('includes calculated contrast ratio in error message', () => {
+      const { getRuleAction } = require('../utils/getRuleAction');
+      getRuleAction.mockReturnValue('PLEASE_FORGIVE_ME');
+
+      const node = createNode({ fg: '#777777', bg: '#FFFFFF', fontSize: 16 });
+      const result = checkContrast(node);
+      expect(result?.extra).toMatch(/\d+\.\d{2}/);
+    });
+
+    it('includes required contrast ratio in error message', () => {
+      const { getRuleAction } = require('../utils/getRuleAction');
+      getRuleAction.mockReturnValue('PLEASE_FORGIVE_ME');
+
+      const node = createNode({ fg: '#777777', bg: '#FFFFFF', fontSize: 16 });
+      const result = checkContrast(node);
+      expect(result?.extra).toContain('4.5');
+    });
+
+    it('includes ariaLabel in error when present', () => {
+      const { getRuleAction } = require('../utils/getRuleAction');
+      getRuleAction.mockReturnValue('PLEASE_FORGIVE_ME');
+
+      const node = createNode({ fg: '#777777', bg: '#FFFFFF', fontSize: 16, ariaLabel: 'Test button' });
+      const result = checkContrast(node);
+      expect(result?.label).toBe('Test button');
+    });
+
+    it('includes viewId in error', () => {
+      const { getRuleAction } = require('../utils/getRuleAction');
+      getRuleAction.mockReturnValue('PLEASE_FORGIVE_ME');
+
+      const node = createNode({ fg: '#777777', bg: '#FFFFFF', fontSize: 16, viewId: 12345 });
+      const result = checkContrast(node);
+      expect(result?.viewId).toBe(12345);
+    });
+  });
+
+  describe('AAA config-driven behavior', () => {
+    it('reports AAA failure when AAA check is enabled', () => {
+      const { getRuleAction } = require('../utils/getRuleAction');
+      getRuleAction.mockReturnValue('SHOULD');
+
+      // #606060 on white = 6.29:1 — passes AA, fails AAA
+      const node = createNode({ fg: '#606060', bg: '#FFFFFF', fontSize: 16 });
+      const result = checkContrast(node);
+      expect(result).toMatchObject({ rule: 'CONTRAST_FAILED_AAA' });
+    });
+
+    it('does not report AAA failure when AAA check is disabled', () => {
+      const { getRuleAction } = require('../utils/getRuleAction');
+      getRuleAction.mockReturnValue('PLEASE_FORGIVE_ME');
+
+      // #606060 on white = 6.29:1 — passes AA, so no error when AAA disabled
+      const node = createNode({ fg: '#606060', bg: '#FFFFFF', fontSize: 16 });
+      expect(checkContrast(node)).toBeNull();
+    });
+
+    it('reports AA failure regardless of AAA config', () => {
+      const { getRuleAction } = require('../utils/getRuleAction');
+      getRuleAction.mockReturnValue('PLEASE_FORGIVE_ME');
+
+      // #777777 on white = 4.48:1 — fails AA
+      const node = createNode({ fg: '#777777', bg: '#FFFFFF', fontSize: 16 });
+      const result = checkContrast(node);
+      expect(result).toMatchObject({ rule: 'CONTRAST_FAILED' });
+    });
+
+    it('returns null when contrast passes AA and AAA is disabled', () => {
+      const { getRuleAction } = require('../utils/getRuleAction');
+      getRuleAction.mockReturnValue('PLEASE_FORGIVE_ME');
+
+      // #757575 on white = 4.61:1 — passes AA
+      const node = createNode({ fg: '#757575', bg: '#FFFFFF', fontSize: 16 });
+      expect(checkContrast(node)).toBeNull();
+    });
+  });
+});

package/src/internals/checks/checkContrast.ts

@@ -0,0 +1,109 @@
+import { AmaNode } from '../../ReactNativeAma.types';
+import { AmaError } from '../types';
+import { shouldIgnoreContrastCheckForDisabledElement } from '../utils/ignoreContrastCheck';
+import { getRuleAction } from '../utils/getRuleAction';
+
+function hexToRgb(hex: string) {
+  if (!hex || typeof hex !== 'string') {
+    return null;
+  }
+
+  const shorthandRegex = /^#?([a-f\d])([a-f\d])([a-f\d])$/i;
+  hex = hex.replace(shorthandRegex, (_, r, g, b) => r + r + g + g + b + b);
+
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+  return result
+    ? {
+      r: parseInt(result[1], 16),
+      g: parseInt(result[2], 16),
+      b: parseInt(result[3], 16),
+    }
+    : null;
+}
+
+function getLuminance(hex: string) {
+  const rgb = hexToRgb(hex);
+  if (!rgb) {
+    return 0;
+  }
+
+  const [r, g, b] = [rgb.r, rgb.g, rgb.b].map((v) => {
+    v /= 255; // Normalize to 0-1 range
+    return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+  });
+
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+function getContrastRatio(fgHex: string, bgHex: string) {
+  const lum1 = getLuminance(fgHex);
+  const lum2 = getLuminance(bgHex);
+
+  const lighter = Math.max(lum1, lum2);
+  const darker = Math.min(lum1, lum2);
+
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+export const checkContrast = (node: AmaNode): AmaError | null => {
+  const { fg, bg, fontSize, isBold, isEnabled } = node;
+
+  if (!isEnabled && shouldIgnoreContrastCheckForDisabledElement?.()) {
+    return null;
+  }
+
+  /**
+   * We need to skip node without content as it might be an icon only Button.
+   * In this case we can't perform a contrast check as is hard to perform
+   * a contrast check on SVGs
+   */
+  if (
+    !fg ||
+    !bg ||
+    !node.content ||
+    node.type === 'TextInput' ||
+    !node.isAccessible
+  ) {
+    return null;
+  }
+
+  const contrastRatio = getContrastRatio(fg, bg);
+
+  // Determine if the text is "large" according to WCAG standards.
+  // 18pt is considered large, or 14pt if bold.
+  const isLargeText =
+    fontSize && (fontSize >= 18 || (fontSize >= 14 && isBold));
+
+  const requiredRatioAA = isLargeText ? 3.0 : 4.5;
+  const requiredRatioAAA = isLargeText ? 4.5 : 7.0;
+
+  const passesAA = contrastRatio >= requiredRatioAA;
+  const passesAAA = contrastRatio >= requiredRatioAAA;
+
+  const aaaAction = getRuleAction?.('CONTRAST_FAILED_AAA');
+  const shouldCheckAAA = aaaAction && aaaAction !== 'PLEASE_FORGIVE_ME';
+
+  if (!passesAAA && shouldCheckAAA) {
+    return {
+      label: node.ariaLabel,
+      viewId: node.viewId,
+      rule: 'CONTRAST_FAILED_AAA',
+      extra: `The color contrast between the foreground (${fg}) and background (${bg}) is ${contrastRatio.toFixed(
+        2
+      )}, which is below the required minimum of ${requiredRatioAAA}.`,
+    };
+  }
+
+  if (!passesAA) {
+    return {
+      label: node.ariaLabel,
+      viewId: node.viewId,
+      rule: 'CONTRAST_FAILED',
+      extra: `The color contrast between the foreground (${fg}) and background (${bg}) is ${contrastRatio.toFixed(
+        2
+      )}, which is below the required minimum of ${requiredRatioAA}.`,
+    };
+  }
+
+  return null;
+};

package/src/internals/checks/checkImageAlt.test.ts

@@ -0,0 +1,125 @@
+import type { AmaNode } from '../../ReactNativeAma.types';
+import { checkImageAlt } from './checkImageAlt';
+
+describe('checkImageAlt', () => {
+    const createNode = (overrides: Partial<AmaNode> = {}): AmaNode => ({
+        type: 'Image',
+        viewId: 1,
+        bounds: [0, 0, 100, 100],
+        hasOnSubmitEditing: false,
+        ...overrides,
+    });
+
+    describe('Image components with missing alt text', () => {
+        it('returns error when Image has no ariaLabel', () => {
+            const node = createNode({
+                type: 'Image',
+                ariaLabel: undefined,
+                isAccessible: true,
+            });
+
+            const result = checkImageAlt(node);
+            expect(result).toMatchObject({
+                rule: 'IMAGE_MISSING_ALT_TEXT',
+                viewId: 1,
+            });
+        });
+
+        it('returns error when Image has empty string ariaLabel', () => {
+            const node = createNode({
+                type: 'Image',
+                ariaLabel: '',
+                isAccessible: true,
+            });
+
+            const result = checkImageAlt(node);
+            expect(result).toMatchObject({
+                rule: 'IMAGE_MISSING_ALT_TEXT',
+                viewId: 1,
+            });
+        });
+
+        it('returns error when Image has no isAccessible prop (defaults to accessible)', () => {
+            const node = createNode({
+                type: 'Image',
+                ariaLabel: undefined,
+            });
+
+            const result = checkImageAlt(node);
+            expect(result).toMatchObject({
+                rule: 'IMAGE_MISSING_ALT_TEXT',
+                viewId: 1,
+            });
+        });
+    });
+
+    describe('Image components with valid alt text', () => {
+        it('returns null when Image has valid ariaLabel', () => {
+            const node = createNode({
+                type: 'Image',
+                ariaLabel: 'Product photo',
+                isAccessible: true,
+            });
+
+            const result = checkImageAlt(node);
+            expect(result).toBeNull();
+        });
+
+        it('returns null when Image has descriptive ariaLabel', () => {
+            const node = createNode({
+                type: 'Image',
+                ariaLabel: 'Icon for settings menu',
+            });
+
+            const result = checkImageAlt(node);
+            expect(result).toBeNull();
+        });
+    });
+
+    describe('Non-accessible images', () => {
+        it('returns null when Image is marked non-accessible (decorative)', () => {
+            const node = createNode({
+                type: 'Image',
+                ariaLabel: undefined,
+                isAccessible: false,
+            });
+
+            const result = checkImageAlt(node);
+            expect(result).toBeNull();
+        });
+
+        it('returns null when decorative image with empty ariaLabel', () => {
+            const node = createNode({
+                type: 'Image',
+                ariaLabel: '',
+                isAccessible: false,
+            });
+
+            const result = checkImageAlt(node);
+            expect(result).toBeNull();
+        });
+    });
+
+    describe('Error details', () => {
+        it('includes correct viewId in error', () => {
+            const node = createNode({
+                type: 'Image',
+                viewId: 99999,
+                ariaLabel: undefined,
+            });
+
+            const result = checkImageAlt(node);
+            expect(result?.viewId).toBe(99999);
+        });
+
+        it('includes correct rule in error', () => {
+            const node = createNode({
+                type: 'Image',
+                ariaLabel: undefined,
+            });
+
+            const result = checkImageAlt(node);
+            expect(result?.rule).toBe('IMAGE_MISSING_ALT_TEXT');
+        });
+    });
+});

package/src/internals/checks/checkImageAlt.ts

@@ -0,0 +1,23 @@
+import { AmaNode } from '../../ReactNativeAma.types';
+import { AmaError } from '../types';
+
+export const checkImageAlt = (node: AmaNode): AmaError | null => {
+    if (node.type !== 'Image') {
+        return null;
+    }
+
+    if (node.isAccessible === false) {
+        return null;
+    }
+
+    const { ariaLabel } = node;
+
+    if (!ariaLabel?.trim()) {
+        return {
+            rule: 'IMAGE_MISSING_ALT_TEXT',
+            viewId: node.viewId,
+        };
+    }
+
+    return null;
+};