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

package/src/internals/utils/getRuleErrorInfo.test.ts

@@ -0,0 +1,59 @@
+beforeEach(() => {
+  jest.resetModules();
+  jest.clearAllMocks();
+  // @ts-ignore
+  global.__DEV__ = true;
+});
+
+describe('getAMARuleErrorInfo', () => {
+  it('returns message, url, and severity for a known rule', () => {
+    jest.doMock('./rules', () => ({
+      RULES_HELP: {
+        NO_ACCESSIBILITY_LABEL: {
+          message: 'Missing label',
+          url: '/guidelines/accessibility-label',
+          severity: 'Critical',
+          issue: 'Missing accessibility label',
+          howToFix: 'Add a label',
+        },
+      },
+    }));
+
+    const { getAMARuleErrorInfo } = require('./getRuleErrorInfo');
+    const result = getAMARuleErrorInfo({ rule: 'NO_ACCESSIBILITY_LABEL', viewId: 1 });
+
+    expect(result.message).toBe('Missing label');
+    expect(result.url).toContain('/guidelines/accessibility-label');
+    expect(result.severity).toBe('Critical');
+  });
+
+  it('appends extra to message when provided', () => {
+    jest.doMock('./rules', () => ({
+      RULES_HELP: {
+        CONTRAST_FAILED: {
+          message: 'Low contrast',
+          url: '/guidelines/contrast',
+          severity: 'Serious',
+          issue: 'Contrast issue',
+          howToFix: 'Fix contrast',
+        },
+      },
+    }));
+
+    const { getAMARuleErrorInfo } = require('./getRuleErrorInfo');
+    const result = getAMARuleErrorInfo({ rule: 'CONTRAST_FAILED', viewId: 2, extra: '(#fff vs #eee)' });
+
+    expect(result.message).toBe('Low contrast: (#fff vs #eee)');
+  });
+
+  it('throws when rule help is missing', () => {
+    jest.doMock('./rules', () => ({
+      RULES_HELP: {},
+    }));
+
+    const { getAMARuleErrorInfo } = require('./getRuleErrorInfo');
+    expect(() => getAMARuleErrorInfo({ rule: 'UNKNOWN_RULE', viewId: 3 })).toThrow(
+      'Missing rule help: UNKNOWN_RULE',
+    );
+  });
+});

package/src/internals/utils/getRuleErrorInfo.ts

@@ -0,0 +1,26 @@
+import { AmaError } from '../types';
+import { RULES_HELP } from './rules';
+
+export type A11ySeverity = 'Serious' | 'Critical' | 'Warning';
+
+export const getAMARuleErrorInfo = __DEV__
+  ? (issue: AmaError) => {
+      const ruleHelp = RULES_HELP![issue.rule];
+
+      if (!ruleHelp) {
+        console.error(`Missing rule help: ${issue.rule}`);
+
+        throw new Error(`Missing rule help: ${issue.rule}`);
+      }
+
+      let message = ruleHelp.message;
+
+      if (issue.extra) {
+        message += ': ' + issue.extra;
+      }
+
+      const url = `https://nearform.com/open-source/react-native-ama/${ruleHelp.url}`;
+
+      return { message, url, severity: ruleHelp.severity };
+    }
+  : null;

package/src/internals/utils/ignoreContrastCheck.test.ts

@@ -0,0 +1,34 @@
+beforeEach(() => {
+  jest.resetModules();
+  jest.clearAllMocks();
+  // @ts-ignore
+  global.__DEV__ = true;
+});
+
+describe('shouldIgnoreContrastCheckForDisabledElement', () => {
+  it('returns the project config override when set', () => {
+    jest.doMock('../config', () => ({
+      __esModule: true,
+      default: { rules: { IGNORE_CONTRAST_FOR_DISABLED_ELEMENTS: true } },
+    }));
+    jest.doMock('./rules', () => ({
+      IGNORE_CONTRAST_FOR_DISABLED_ELEMENTS: false,
+    }));
+
+    const { shouldIgnoreContrastCheckForDisabledElement } = require('./ignoreContrastCheck');
+    expect(shouldIgnoreContrastCheckForDisabledElement()).toBe(true);
+  });
+
+  it('falls back to the default rule value when config has no override', () => {
+    jest.doMock('../config', () => ({
+      __esModule: true,
+      default: { rules: {} },
+    }));
+    jest.doMock('./rules', () => ({
+      IGNORE_CONTRAST_FOR_DISABLED_ELEMENTS: false,
+    }));
+
+    const { shouldIgnoreContrastCheckForDisabledElement } = require('./ignoreContrastCheck');
+    expect(shouldIgnoreContrastCheckForDisabledElement()).toBe(false);
+  });
+});

package/src/internals/utils/ignoreContrastCheck.ts

@@ -0,0 +1,11 @@
+import projectRules from '../config';
+import { IGNORE_CONTRAST_FOR_DISABLED_ELEMENTS } from './rules';
+
+export const shouldIgnoreContrastCheckForDisabledElement = __DEV__
+  ? () => {
+      return (
+        projectRules?.rules?.IGNORE_CONTRAST_FOR_DISABLED_ELEMENTS ||
+        IGNORE_CONTRAST_FOR_DISABLED_ELEMENTS
+      );
+    }
+  : null;

package/src/internals/utils/interpolateAnimation.test.ts

@@ -0,0 +1,176 @@
+import { MOTION_ANIMATIONS } from './constants';
+import { interpolateAnimationStates } from './interpolateAnimationStates';
+
+describe('interpolateAnimationStates', () => {
+  describe('Given isReduceMotionEnabled is false', () => {
+    it('Then interpolate the animation using the "normal progress" Animated.Value', () => {
+      const [fakeProgress, interpolate] = createFakeProgress();
+      const [reduceMotionProgress, reduceMotionInterpolate] =
+        createFakeProgress();
+
+      const output = interpolateAnimationStates(
+        {
+          left: 100,
+          opacity: 1,
+        },
+        { left: 0, opacity: 0 },
+        false,
+        fakeProgress,
+        reduceMotionProgress,
+      );
+
+      expect(interpolate).toHaveBeenNthCalledWith(1, {
+        inputRange: [0, 1],
+        outputRange: [100, 0],
+      });
+
+      expect(interpolate).toHaveBeenNthCalledWith(2, {
+        inputRange: [0, 1],
+        outputRange: [1, 0],
+      });
+
+      expect(reduceMotionInterpolate).not.toHaveBeenCalled();
+
+      expect(output).toEqual({
+        left: 'done',
+        opacity: 'done',
+        __hasOnlyMotionAnimation: false,
+      });
+    });
+
+    it('Then interpolate arrays correctly', () => {
+      const [fakeProgress, interpolate] = createFakeProgress();
+      const [reduceMotionProgress, reduceMotionInterpolate] =
+        createFakeProgress();
+
+      const output = interpolateAnimationStates(
+        {
+          transform: [{ translateX: 200 }],
+          opacity: 1,
+        },
+        {
+          transform: [{ translateX: 42 }],
+          opacity: 0,
+        },
+        false,
+        fakeProgress,
+        reduceMotionProgress,
+      );
+
+      expect(interpolate).toHaveBeenNthCalledWith(1, {
+        inputRange: [0, 1],
+        outputRange: [200, 42],
+      });
+
+      expect(interpolate).toHaveBeenNthCalledWith(2, {
+        inputRange: [0, 1],
+        outputRange: [1, 0],
+      });
+
+      expect(reduceMotionInterpolate).not.toHaveBeenCalled();
+
+      expect(output).toEqual({
+        opacity: 'done',
+        transform: [{ translateX: 'done' }],
+        __hasOnlyMotionAnimation: false,
+      });
+    });
+  });
+
+  describe('Given isReduceMotionEnabled is true', () => {
+    it.each(MOTION_ANIMATIONS)(
+      'Then interpolate the motion animations using the "reduceMotionProgress" Animated.Value',
+      motionAnimationKey => {
+        const [fakeProgress, normalInterpolate] = createFakeProgress();
+        const [reduceMotionProgress, reduceMotionInterpolate] =
+          createFakeProgress();
+
+        const initialState: Record<string, any> = {};
+        const finalState: Record<string, any> = {};
+
+        initialState[motionAnimationKey] = 142;
+        finalState[motionAnimationKey] = 42;
+
+        const output = interpolateAnimationStates(
+          {
+            ...initialState,
+            opacity: 0,
+          },
+          { ...finalState, opacity: 1 },
+          true,
+          fakeProgress,
+          reduceMotionProgress,
+        );
+
+        expect(normalInterpolate).toHaveBeenCalledTimes(1);
+        expect(normalInterpolate).toHaveBeenCalledWith({
+          inputRange: [0, 1],
+          outputRange: [0, 1],
+        });
+
+        expect(reduceMotionInterpolate).toHaveBeenCalledTimes(1);
+        expect(reduceMotionInterpolate).toHaveBeenCalledWith({
+          inputRange: [0, 1],
+          outputRange: [142, 42],
+        });
+
+        const expectedOutput: Record<string, any> = {
+          opacity: 'done',
+          __hasOnlyMotionAnimation: false,
+        };
+        expectedOutput[motionAnimationKey] = 'done';
+
+        expect(output).toEqual(expectedOutput);
+      },
+    );
+
+    it('Then interpolate arrays correctly', () => {
+      const [fakeProgress, normalInterpolate] = createFakeProgress();
+      const [reduceMotionProgress, reduceMotionInterpolate] =
+        createFakeProgress();
+
+      const output = interpolateAnimationStates(
+        {
+          transform: [{ translateX: 200 }],
+          opacity: 1,
+        },
+        {
+          transform: [{ translateX: 42 }],
+          opacity: 0,
+        },
+        true,
+        fakeProgress,
+        reduceMotionProgress,
+      );
+
+      expect(normalInterpolate).toHaveBeenCalledTimes(1);
+      expect(normalInterpolate).toHaveBeenCalledWith({
+        inputRange: [0, 1],
+        outputRange: [1, 0],
+      });
+
+      expect(reduceMotionInterpolate).toHaveBeenCalledTimes(1);
+      expect(reduceMotionInterpolate).toHaveBeenCalledWith({
+        inputRange: [0, 1],
+        outputRange: [200, 42],
+      });
+
+      expect(output).toEqual({
+        opacity: 'done',
+        transform: [{ translateX: 'done' }],
+        __hasOnlyMotionAnimation: false,
+      });
+    });
+  });
+});
+
+const createFakeProgress = () => {
+  const interpolateMock = jest.fn().mockReturnValue('done');
+
+  return [
+    {
+      interpolate: interpolateMock,
+    } as any,
+    interpolateMock,
+  ];
+};

package/src/internals/utils/interpolateAnimationStates.ts

@@ -0,0 +1,55 @@
+import type { Animated, ViewStyle } from 'react-native';
+import { MOTION_ANIMATIONS } from './constants';
+
+export const interpolateAnimationStates = (
+  from: Record<string, any>,
+  to: Record<string, any>,
+  isReduceMotionEnabled: boolean,
+  progressValue: Animated.Value,
+  reduceMotionProgressValue: Animated.Value,
+): Record<string, any> => {
+  return Object.keys(from).reduce(
+    (outputAnimation, key) => {
+      const isMotionAnimation = MOTION_ANIMATIONS.includes(
+        key as keyof ViewStyle,
+      );
+      const progressKey =
+        isReduceMotionEnabled && isMotionAnimation
+          ? reduceMotionProgressValue
+          : progressValue;
+
+      if (Array.isArray(from[key])) {
+        outputAnimation[key] = from[key].map(
+          (animationObject: Record<string, any>, index: number) => {
+            const { __hasOnlyMotionAnimation, ...style } =
+              interpolateAnimationStates(
+                animationObject,
+                to[key][index],
+                isReduceMotionEnabled,
+                progressValue,
+                reduceMotionProgressValue,
+              );
+
+            outputAnimation.__hasOnlyMotionAnimation =
+              outputAnimation.__hasOnlyMotionAnimation &&
+              __hasOnlyMotionAnimation;
+
+            return style;
+          },
+        );
+      } else {
+        outputAnimation[key] = progressKey.interpolate({
+          inputRange: [0, 1],
+          // @ts-ignore
+          outputRange: [from[key], to[key]],
+        });
+
+        outputAnimation.__hasOnlyMotionAnimation =
+          outputAnimation.__hasOnlyMotionAnimation && isMotionAnimation;
+      }
+
+      return outputAnimation;
+    },
+    { __hasOnlyMotionAnimation: true } as Record<string, any>,
+  );
+};

package/src/internals/utils/isA11yLabelAllowed.test.ts

@@ -0,0 +1,39 @@
+beforeEach(() => {
+  jest.resetModules();
+  jest.clearAllMocks();
+  // @ts-ignore
+  global.__DEV__ = true;
+});
+
+describe('isAccessibilityLabelAllowed', () => {
+  const setupMock = (uppercaseMinLength: number, exceptions: string[] = []) => {
+    jest.doMock('../config', () => ({
+      __esModule: true,
+      default: { uppercaseMinLength, accessibilityLabelExceptions: exceptions },
+    }));
+  };
+
+  it('allows label shorter than uppercaseMinLength', () => {
+    setupMock(4);
+    const { isAccessibilityLabelAllowed } = require('./isA11yLabelAllowed');
+    expect(isAccessibilityLabelAllowed('OK')).toBe(true);
+  });
+
+  it('disallows label at or above uppercaseMinLength', () => {
+    setupMock(4);
+    const { isAccessibilityLabelAllowed } = require('./isA11yLabelAllowed');
+    expect(isAccessibilityLabelAllowed('LONG')).toBe(false);
+  });
+
+  it('allows label that is in the exceptions list', () => {
+    setupMock(4, ['FAQ']);
+    const { isAccessibilityLabelAllowed } = require('./isA11yLabelAllowed');
+    expect(isAccessibilityLabelAllowed('FAQ')).toBe(true);
+  });
+
+  it('disallows label that is not in exceptions and exceeds min length', () => {
+    setupMock(4, ['FAQ']);
+    const { isAccessibilityLabelAllowed } = require('./isA11yLabelAllowed');
+    expect(isAccessibilityLabelAllowed('LONG')).toBe(false);
+  });
+});

package/src/internals/utils/isA11yLabelAllowed.ts

@@ -0,0 +1,10 @@
+import projectRules from '../config';
+
+export const isAccessibilityLabelAllowed = __DEV__
+  ? (accessibilityLabel: string) => {
+      return (
+        accessibilityLabel.length < projectRules.uppercaseMinLength ||
+        projectRules?.accessibilityLabelExceptions?.includes(accessibilityLabel)
+      );
+    }
+  : null;

package/src/internals/utils/isRuleDisabled.test.ts

@@ -0,0 +1,35 @@
+beforeEach(() => {
+  jest.resetModules();
+  jest.clearAllMocks();
+  // @ts-ignore
+  global.__DEV__ = true;
+});
+
+describe('isRuleDisabled', () => {
+  it('returns true when the rule action is PLEASE_FORGIVE_ME', () => {
+    jest.doMock('./getRuleAction', () => ({
+      getRuleAction: () => 'PLEASE_FORGIVE_ME',
+    }));
+
+    const { isRuleDisabled } = require('./isRuleDisabled');
+    expect(isRuleDisabled({ rule: 'CONTRAST_FAILED', viewId: 1 })).toBe(true);
+  });
+
+  it('returns false when the rule action is MUST', () => {
+    jest.doMock('./getRuleAction', () => ({
+      getRuleAction: () => 'MUST',
+    }));
+
+    const { isRuleDisabled } = require('./isRuleDisabled');
+    expect(isRuleDisabled({ rule: 'NO_ACCESSIBILITY_LABEL', viewId: 1 })).toBe(false);
+  });
+
+  it('returns false when the rule action is SHOULD', () => {
+    jest.doMock('./getRuleAction', () => ({
+      getRuleAction: () => 'SHOULD',
+    }));
+
+    const { isRuleDisabled } = require('./isRuleDisabled');
+    expect(isRuleDisabled({ rule: 'CONTRAST_FAILED_AAA', viewId: 1 })).toBe(false);
+  });
+});

package/src/internals/utils/isRuleDisabled.ts

@@ -0,0 +1,10 @@
+import { AmaError } from '../types';
+import { getRuleAction } from './getRuleAction';
+
+export const isRuleDisabled = __DEV__
+  ? (error: AmaError) => {
+    const action = getRuleAction?.(error.rule);
+
+    return action && action === 'PLEASE_FORGIVE_ME';
+  }
+  : null;

package/src/internals/utils/logError.test.ts

@@ -0,0 +1,148 @@
+beforeEach(() => {
+  jest.resetModules();
+  jest.clearAllMocks();
+  // @ts-ignore
+  global.__DEV__ = true;
+});
+
+describe('logError', () => {
+  it('calls logger.error for a MUST rule', () => {
+    const loggerError = jest.fn();
+    const loggerWarn = jest.fn();
+
+    jest.doMock('./logger', () => ({
+      __esModule: true,
+      default: { log: jest.fn(), warn: loggerWarn, error: loggerError },
+    }));
+    jest.doMock('./getRuleAction', () => ({
+      getRuleAction: () => 'MUST',
+    }));
+    jest.doMock('./rules', () => ({
+      RULES_HELP: {
+        NO_ACCESSIBILITY_LABEL: {
+          message: 'Missing label',
+          url: '/guidelines/accessibility-label',
+          severity: 'Critical',
+        },
+      },
+    }));
+
+    const { logError } = require('./logError');
+    logError({ rule: 'NO_ACCESSIBILITY_LABEL', viewId: 1 });
+
+    expect(loggerError).toHaveBeenCalledTimes(1);
+    expect(loggerWarn).not.toHaveBeenCalled();
+  });
+
+  it('calls logger.error for a MUST_NOT rule', () => {
+    const loggerError = jest.fn();
+    const loggerWarn = jest.fn();
+
+    jest.doMock('./logger', () => ({
+      __esModule: true,
+      default: { log: jest.fn(), warn: loggerWarn, error: loggerError },
+    }));
+    jest.doMock('./getRuleAction', () => ({
+      getRuleAction: () => 'MUST_NOT',
+    }));
+    jest.doMock('./rules', () => ({
+      RULES_HELP: {
+        NO_UPPERCASE_TEXT: {
+          message: 'Avoid uppercase',
+          url: '/guidelines/text',
+          severity: 'Serious',
+        },
+      },
+    }));
+
+    const { logError } = require('./logError');
+    logError({ rule: 'NO_UPPERCASE_TEXT', viewId: 2 });
+
+    expect(loggerError).toHaveBeenCalledTimes(1);
+    expect(loggerWarn).not.toHaveBeenCalled();
+  });
+
+  it('calls logger.warn for a SHOULD rule', () => {
+    const loggerError = jest.fn();
+    const loggerWarn = jest.fn();
+
+    jest.doMock('./logger', () => ({
+      __esModule: true,
+      default: { log: jest.fn(), warn: loggerWarn, error: loggerError },
+    }));
+    jest.doMock('./getRuleAction', () => ({
+      getRuleAction: () => 'SHOULD',
+    }));
+    jest.doMock('./rules', () => ({
+      RULES_HELP: {
+        CONTRAST_FAILED_AAA: {
+          message: 'Low contrast AAA',
+          url: '/guidelines/contrast',
+          severity: 'Serious',
+        },
+      },
+    }));
+
+    const { logError } = require('./logError');
+    logError({ rule: 'CONTRAST_FAILED_AAA', viewId: 3 });
+
+    expect(loggerWarn).toHaveBeenCalledTimes(1);
+    expect(loggerError).not.toHaveBeenCalled();
+  });
+
+  it('includes the label in the log when provided', () => {
+    const loggerError = jest.fn();
+
+    jest.doMock('./logger', () => ({
+      __esModule: true,
+      default: { log: jest.fn(), warn: jest.fn(), error: loggerError },
+    }));
+    jest.doMock('./getRuleAction', () => ({
+      getRuleAction: () => 'MUST',
+    }));
+    jest.doMock('./rules', () => ({
+      RULES_HELP: {
+        NO_ACCESSIBILITY_LABEL: {
+          message: 'Missing label',
+          url: '/guidelines/accessibility-label',
+          severity: 'Critical',
+        },
+      },
+    }));
+
+    const { logError } = require('./logError');
+    logError({ rule: 'NO_ACCESSIBILITY_LABEL', viewId: 5, label: 'Submit' });
+
+    expect(loggerError).toHaveBeenCalledWith(
+      expect.stringContaining('Submit'),
+    );
+  });
+
+  it('includes extra in the message when provided', () => {
+    const loggerError = jest.fn();
+
+    jest.doMock('./logger', () => ({
+      __esModule: true,
+      default: { log: jest.fn(), warn: jest.fn(), error: loggerError },
+    }));
+    jest.doMock('./getRuleAction', () => ({
+      getRuleAction: () => 'MUST',
+    }));
+    jest.doMock('./rules', () => ({
+      RULES_HELP: {
+        NO_ACCESSIBILITY_LABEL: {
+          message: 'Missing label',
+          url: '/guidelines/accessibility-label',
+          severity: 'Critical',
+        },
+      },
+    }));
+
+    const { logError } = require('./logError');
+    logError({ rule: 'NO_ACCESSIBILITY_LABEL', viewId: 6, extra: 'extra info' });
+
+    expect(loggerError).toHaveBeenCalledWith(
+      expect.stringContaining('extra info'),
+    );
+  });
+});

package/src/internals/utils/logError.ts

@@ -0,0 +1,41 @@
+import { AmaError } from '../types';
+import { getRuleAction } from './getRuleAction';
+import logger from './logger';
+import { RULES_HELP } from './rules';
+
+const getAMARuleErrorInfo = __DEV__
+  ? ({ rule, extra }: AmaError) => {
+    const ruleHelp = RULES_HELP![rule];
+
+    let message = ruleHelp.message;
+
+    if (extra) {
+      message += ': ' + extra;
+    }
+
+    const url = `https://nearform.com/open-source/react-native-ama/${ruleHelp.url}`;
+
+    return { message, url, severity: ruleHelp.severity };
+  }
+  : null;
+
+export const logError = __DEV__
+  ? (issue: AmaError) => {
+    const action = getRuleAction?.(issue.rule);
+    const log =
+      action === 'MUST' || action === 'MUST_NOT'
+        ? logger?.error
+        : logger?.warn;
+
+    const { message, url } = getAMARuleErrorInfo?.(issue) ?? {};
+
+    log?.(
+      `${issue.rule}
+        Component: ${issue.label || '--- NO LABEL FOUND ---'} (#${issue.viewId})
+
+        ${message}
+
+        Learn about: ${url}\n`,
+    );
+  }
+  : null;