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

package/src/internals/useAMADev.ts

@@ -0,0 +1,17 @@
+import type { RefObject } from 'react';
+import type { AmaError, AmaRule } from './types';
+
+export type UseAMADevValue = {
+  issues: AmaError[];
+  trackError: (rule: AmaRule, ref?: RefObject<any>) => void;
+};
+
+export type UseAMADev = () => UseAMADevValue;
+
+type UseAMADevModule = {
+  useAMADev: UseAMADev | null;
+};
+
+export const useAMADev: UseAMADev | null = __DEV__
+  ? (require('./useAMADev.dev') as UseAMADevModule).useAMADev
+  : null;

package/src/internals/useAMADevNodeChecks.dev.ts

@@ -0,0 +1,178 @@
+import type { AmaNode, AmaNodes } from '../ReactNativeAma.types';
+import { checkTextInputs } from './checks/checkTextInput';
+import { performChecks } from './checks/performChecks';
+import projectRules from './config';
+import type { AmaError } from './types';
+import { amaClearHighlight } from './utils/amaClearHighlight';
+import { amaHighlightComponent } from './utils/amaHighlightComponent';
+import { logFoundIssues } from './utils/logFoundIssues';
+
+type HighlightedIssues = Record<number, number>;
+
+type RunNodeChecksOptions = {
+  nodesToCheck: AmaNodes;
+  previousNodeIssues: AmaError[];
+  jsFailedChecks: AmaError[];
+  highlightedIssues: HighlightedIssues;
+};
+
+type RunNodeChecks = (options: RunNodeChecksOptions) => AmaError[];
+type CollectNodeIssues = (nodesToCheck: AmaNodes) => AmaError[];
+type GetNodeIssueState = (
+  currentIssues: AmaError[],
+  nodeIssues: AmaError[],
+  nodesToCheck: AmaNodes
+) => AmaError[];
+type IsHeaderNode = (node: AmaNode) => boolean;
+type ClearFixedNodeIssues = (
+  previousNodeIssues: AmaError[],
+  nodeIssues: AmaError[],
+  jsIssues: AmaError[]
+) => void;
+type SyncHighlightedIssues = (
+  nodeIssues: AmaError[],
+  jsFailedChecks: AmaError[],
+  highlightedIssues: HighlightedIssues
+) => void;
+type GroupIssuesByViewId = (issues: AmaError[]) => Record<number, AmaError[]>;
+type SortIssuesByViewId = (issues: AmaError[]) => AmaError[];
+type KeepNoStateHandledOrKeyboardTrapIssuesStillInView = (
+  issues: AmaError[],
+  nodesInView: Record<number, AmaNode>
+) => AmaError[];
+
+export const runNodeChecks: RunNodeChecks | null = __DEV__
+  ? ({ nodesToCheck, previousNodeIssues, jsFailedChecks, highlightedIssues }) => {
+      const nodeIssues = collectNodeIssues?.(nodesToCheck) ?? [];
+
+      if (previousNodeIssues.length) {
+        clearFixedNodeIssues?.(previousNodeIssues, nodeIssues, jsFailedChecks);
+      }
+
+      logFoundIssues?.(nodeIssues);
+      syncHighlightedIssues?.(nodeIssues, jsFailedChecks, highlightedIssues);
+
+      return nodeIssues;
+    }
+  : null;
+
+export const collectNodeIssues: CollectNodeIssues | null = __DEV__
+  ? (nodesToCheck) => {
+      const nodes = Object.values(nodesToCheck);
+      let hasAtLeastOneHeader = false;
+      let hasTextInput = false;
+      const nodeIssues: AmaError[] = [];
+
+      for (const node of nodes) {
+        if (node.type === 'TextInput') {
+          hasTextInput = true;
+        }
+
+        if (!hasAtLeastOneHeader && isHeaderNode?.(node)) {
+          hasAtLeastOneHeader = true;
+        }
+
+        nodeIssues.push(...performChecks(node));
+      }
+
+      if (hasTextInput && projectRules.checks.forms) {
+        nodeIssues.push(...checkTextInputs(nodes));
+      }
+
+      if (!hasAtLeastOneHeader) {
+        nodeIssues.push({ rule: 'NO_HEADER_FOUND', viewId: -1 });
+      }
+
+      return nodeIssues;
+    }
+  : null;
+
+export const getNodeIssueState: GetNodeIssueState | null = __DEV__
+  ? (currentIssues, nodeIssues, nodesToCheck) => {
+      const issuesToKeep =
+        keepNoStateHandledOrKeyboardTrapIssuesStillInView?.(
+          currentIssues,
+          nodesToCheck
+        ) ?? [];
+
+      return [
+        ...issuesToKeep,
+        ...(sortIssuesByViewId?.(nodeIssues) ?? nodeIssues),
+      ];
+    }
+  : null;
+
+const isHeaderNode: IsHeaderNode | null = __DEV__
+  ? (node) =>
+      node.type === 'Text' &&
+      (node.traits?.includes('header') || node.ariaRole === 'header')
+  : null;
+
+const clearFixedNodeIssues: ClearFixedNodeIssues | null = __DEV__
+  ? (previousNodeIssues, nodeIssues, jsIssues) => {
+      const fixedIssues = previousNodeIssues.filter(
+        (issue) =>
+          nodeIssues.find((item) => item.viewId === issue.viewId) ===
+            undefined && issue.rule !== 'NO_ACCESSIBILITY_STATE_SET'
+      );
+
+      for (const issue of fixedIssues) {
+        amaClearHighlight?.(issue);
+
+        const jsIndex = jsIssues.findIndex(
+          (item) => item.viewId === issue.viewId && item.rule === issue.rule
+        );
+        if (jsIndex >= 0) {
+          jsIssues.splice(jsIndex, 1);
+        }
+      }
+    }
+  : null;
+
+const syncHighlightedIssues: SyncHighlightedIssues | null = __DEV__
+  ? (nodeIssues, jsFailedChecks, highlightedIssues) => {
+      const issuesByViewId =
+        groupIssuesByViewId?.([...nodeIssues, ...jsFailedChecks]) ?? {};
+
+      for (const viewIdStr of Object.keys(issuesByViewId)) {
+        const viewId = Number(viewIdStr);
+        const issuesForView = issuesByViewId[viewId];
+
+        if (highlightedIssues[viewId] !== issuesForView.length) {
+          amaHighlightComponent?.(issuesForView);
+          highlightedIssues[viewId] = issuesForView.length;
+        }
+      }
+    }
+  : null;
+
+const groupIssuesByViewId: GroupIssuesByViewId | null = __DEV__
+  ? (issues) => {
+      return issues.reduce((groupedIssues, issue) => {
+        if (issue.viewId >= 0) {
+          if (!groupedIssues[issue.viewId]) {
+            groupedIssues[issue.viewId] = [];
+          }
+          groupedIssues[issue.viewId].push(issue);
+        }
+
+        return groupedIssues;
+      }, {} as Record<number, AmaError[]>);
+    }
+  : null;
+
+const sortIssuesByViewId: SortIssuesByViewId | null = __DEV__
+  ? (issues) => [...issues].sort((a, b) => a.viewId - b.viewId)
+  : null;
+
+const keepNoStateHandledOrKeyboardTrapIssuesStillInView: KeepNoStateHandledOrKeyboardTrapIssuesStillInView | null =
+  __DEV__
+    ? (issues, nodesInView) => {
+        return issues.filter(
+          (item) =>
+            (item.rule === 'NO_ACCESSIBILITY_STATE_SET' ||
+              item.rule === 'NO_KEYBOARD_TRAP') &&
+            nodesInView[item.viewId]
+        );
+      }
+    : null;

package/src/internals/useAMADevUiInteraction.dev.ts

@@ -0,0 +1,164 @@
+import type {
+  AmaNode,
+  AmaUiSnapshot,
+  AmaUiSnapshotKeys,
+  AmaUiSnapshotsData,
+} from '../ReactNativeAma.types';
+import type { AmaError } from './types';
+import { amaClearHighlight } from './utils/amaClearHighlight';
+import { amaHighlightComponent } from './utils/amaHighlightComponent';
+
+const A11Y_STATE_KEYS: AmaUiSnapshotKeys[] = [
+  'parentId',
+  'isChecked',
+  'isBusy',
+  'isSelected',
+  'isDisabled',
+  'isExpanded',
+];
+
+type GetItemsWithNoStateUpdated = (
+  data: AmaUiSnapshotsData,
+  nodesInView: Record<number, AmaNode>
+) => Set<number>;
+
+type SyncUiInteractionIssues = (
+  prevIssues: AmaError[],
+  itemsToFlag: number[],
+  rootTag: number
+) => AmaError[];
+type ClearNoStateIssueForRoot = (
+  issues: AmaError[],
+  rootTag: number
+) => AmaError[];
+type NonNullableValue = <T>(value: T) => value is NonNullable<T>;
+
+export const getItemsWithNoStateUpdated: GetItemsWithNoStateUpdated | null =
+  __DEV__
+    ? (data, nodesInView) => {
+        const viewsBefore = data.before;
+        const viewsAfter = data.afterSettled ?? data.after;
+        const issues: Set<number> = new Set();
+        const afterKeys = Object.keys(viewsAfter).map(Number);
+
+        if (
+          !afterKeys.includes(data.rootTag) ||
+          data.beforeModalVisible !== data.afterModalVisible
+        ) {
+          return issues;
+        }
+
+        // The tapped element is no longer in the UI, usually after navigation.
+        if (!nodesInView[data.rootTag]) {
+          return issues;
+        }
+
+        let hasSomethingChanged = false;
+        for (const tagId of afterKeys) {
+          const snapBefore = viewsBefore[tagId];
+          const snapAfter = viewsAfter[tagId];
+
+          if (!snapBefore) {
+            hasSomethingChanged = true;
+
+            continue;
+          }
+
+          const subKeys = (
+            Object.keys(snapAfter) as Array<keyof AmaUiSnapshot>
+          ).filter((key) => key !== 'parentId');
+
+          for (const subKey of subKeys) {
+            const hasPropertyChanged =
+              !A11Y_STATE_KEYS.includes(subKey) &&
+              snapBefore[subKey] !== snapAfter[subKey];
+
+            if (hasPropertyChanged) {
+              hasSomethingChanged = true;
+
+              break;
+            }
+          }
+        }
+
+        if (hasSomethingChanged) {
+          const parentId = data.rootTag;
+          const after = data.after[parentId];
+          const settled = data.afterSettled?.[parentId];
+          const before = data.before[parentId];
+
+          const hasStateChanged = A11Y_STATE_KEYS.some(
+            (key) =>
+              before[key] !== after[key] ||
+              (settled && before[key] !== settled[key])
+          );
+
+          if (parentId && !hasStateChanged) {
+            issues.add(parentId);
+          }
+        }
+
+        return issues;
+      }
+    : null;
+
+export const syncUiInteractionIssues: SyncUiInteractionIssues | null = __DEV__
+  ? (prevIssues, itemsToFlag, rootTag) => {
+      if (itemsToFlag.length === 0) {
+        return clearNoStateIssueForRoot?.(prevIssues, rootTag) ?? prevIssues;
+      }
+
+      const newIssues = itemsToFlag
+        .map((viewId) => {
+          const found = prevIssues.find(
+            (item) =>
+              item.viewId === viewId &&
+              item.rule === 'NO_ACCESSIBILITY_STATE_SET'
+          );
+
+          if (found) {
+            return null;
+          }
+
+          const issue: AmaError = {
+            rule: 'NO_ACCESSIBILITY_STATE_SET',
+            viewId,
+          };
+
+          amaHighlightComponent?.(issue);
+
+          return issue;
+        })
+        .filter(
+          (issue): issue is AmaError => nonNullable?.(issue) ?? false
+        );
+
+      if (newIssues.length === 0) {
+        return prevIssues;
+      }
+
+      return [...prevIssues, ...newIssues];
+    }
+  : null;
+
+const clearNoStateIssueForRoot: ClearNoStateIssueForRoot | null = __DEV__
+  ? (issues, rootTag) => {
+      const issueIndex = issues.findIndex(
+        (item) =>
+          item.viewId === rootTag && item.rule === 'NO_ACCESSIBILITY_STATE_SET'
+      );
+
+      if (issueIndex < 0) {
+        return issues;
+      }
+
+      amaClearHighlight?.(issues[issueIndex]);
+
+      return issues.filter((_, index) => index !== issueIndex);
+    }
+  : null;
+
+const nonNullable: NonNullableValue | null = __DEV__
+  ? <T>(value: T): value is NonNullable<T> =>
+      value !== null && value !== undefined
+  : null;

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

@@ -0,0 +1,21 @@
+beforeEach(() => {
+  jest.resetModules();
+  jest.clearAllMocks();
+  // @ts-ignore
+  global.__DEV__ = true;
+});
+
+describe('amaClearHighlight', () => {
+  it('calls ReactNativeAmaModule.clearHighlight with the viewId', () => {
+    const clearHighlight = jest.fn();
+    jest.doMock('../../ReactNativeAmaModule', () => ({
+      __esModule: true,
+      default: { clearHighlight },
+    }));
+
+    const { amaClearHighlight } = require('./amaClearHighlight');
+    amaClearHighlight({ rule: 'NO_ACCESSIBILITY_LABEL', viewId: 42 });
+
+    expect(clearHighlight).toHaveBeenCalledWith(42);
+  });
+});

package/src/internals/utils/amaClearHighlight.ts

@@ -0,0 +1,8 @@
+import ReactNativeAmaModule from '../../ReactNativeAmaModule';
+import { AmaError } from '../types';
+
+export const amaClearHighlight = __DEV__
+  ? (issue: AmaError) => {
+      ReactNativeAmaModule.clearHighlight(issue.viewId);
+    }
+  : null;

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

@@ -0,0 +1,74 @@
+beforeEach(() => {
+  jest.resetModules();
+  jest.clearAllMocks();
+  // @ts-ignore
+  global.__DEV__ = true;
+});
+
+describe('amaHighlightComponent', () => {
+  const setupMocks = (highlightMock = jest.fn().mockResolvedValue({ x: 0 })) => {
+    jest.doMock('../../ReactNativeAmaModule', () => ({
+      __esModule: true,
+      default: { highlight: highlightMock },
+    }));
+    jest.doMock('../config', () => ({
+      __esModule: true,
+      default: { highlight: { mode: 'border' }, rules: {} },
+    }));
+    jest.doMock('./rules', () => ({
+      RULES_HELP: {
+        NO_ACCESSIBILITY_LABEL: { severity: 'Critical' },
+        CONTRAST_FAILED: { severity: 'Serious' },
+        CONTRAST_FAILED_AAA: { severity: 'Warning' },
+      },
+      AMA_COLORS: { Critical: '#f00', Serious: '#2563EB', Warning: '#2563EB' },
+    }));
+    return highlightMock;
+  };
+
+  it('returns null for an empty issues array', async () => {
+    setupMocks();
+    const { amaHighlightComponent } = require('./amaHighlightComponent');
+    const result = await amaHighlightComponent([]);
+    expect(result).toBeNull();
+  });
+
+  it('calls highlight with the first issue viewId and highest severity color', async () => {
+    const highlightMock = setupMocks();
+    const { amaHighlightComponent } = require('./amaHighlightComponent');
+
+    await amaHighlightComponent([
+      { rule: 'NO_ACCESSIBILITY_LABEL', viewId: 10 },
+      { rule: 'CONTRAST_FAILED', viewId: 10 },
+    ]);
+
+    expect(highlightMock).toHaveBeenCalledWith(10, 'border', '#f00', 2);
+  });
+
+  it('uses Warning color when only warning-severity issues are present', async () => {
+    const highlightMock = setupMocks();
+    const { amaHighlightComponent } = require('./amaHighlightComponent');
+
+    await amaHighlightComponent([{ rule: 'CONTRAST_FAILED_AAA', viewId: 5 }]);
+
+    expect(highlightMock).toHaveBeenCalledWith(5, 'border', '#2563EB', 1);
+  });
+
+  it('accepts a single issue object (non-array)', async () => {
+    const highlightMock = setupMocks();
+    const { amaHighlightComponent } = require('./amaHighlightComponent');
+
+    await amaHighlightComponent({ rule: 'CONTRAST_FAILED', viewId: 7 });
+
+    expect(highlightMock).toHaveBeenCalledWith(7, 'border', '#2563EB', 1);
+  });
+
+  it('uses the mode argument over the config default', async () => {
+    const highlightMock = setupMocks();
+    const { amaHighlightComponent } = require('./amaHighlightComponent');
+
+    await amaHighlightComponent([{ rule: 'CONTRAST_FAILED', viewId: 3 }], 'background');
+
+    expect(highlightMock).toHaveBeenCalledWith(3, 'background', '#2563EB', 1);
+  });
+});

package/src/internals/utils/amaHighlightComponent.ts

@@ -0,0 +1,46 @@
+import ReactNativeAmaModule from '../../ReactNativeAmaModule';
+import projectRules, { HighlightMode } from '../config';
+import { AmaError } from '../types';
+import { AMA_COLORS, RULES_HELP, A11ySeverity } from './rules';
+
+// Severity priority: Critical > Serious > Warning
+const SEVERITY_PRIORITY: Record<A11ySeverity, number> = {
+  Critical: 3,
+  Serious: 2,
+  Warning: 1,
+};
+
+const getHighestSeverityColor = (issues: AmaError[]): string => {
+  let highestPriority = 0;
+  let highestSeverity: A11ySeverity = 'Warning';
+
+  for (const issue of issues) {
+    const severity = RULES_HELP?.[issue.rule]?.severity ?? 'Critical';
+    const priority = SEVERITY_PRIORITY[severity];
+    if (priority > highestPriority) {
+      highestPriority = priority;
+      highestSeverity = severity;
+    }
+  }
+
+  return AMA_COLORS[highestSeverity];
+};
+
+export const amaHighlightComponent = __DEV__
+  ? async (issues: AmaError | AmaError[], mode?: HighlightMode) => {
+    const issuesArray = Array.isArray(issues) ? issues : [issues];
+    if (issuesArray.length === 0) {return null;}
+
+    const viewId = issuesArray[0].viewId;
+    const color = getHighestSeverityColor(issuesArray);
+    const issueCount = issuesArray.length;
+
+    return ReactNativeAmaModule.highlight(
+      viewId,
+      mode ?? projectRules.highlight?.mode ?? 'both',
+      color,
+      issueCount,
+    );
+  }
+  : null;
+

package/src/internals/utils/constants.ts

@@ -0,0 +1,33 @@
+import type { ViewStyle } from 'react-native';
+
+export type MotionAnimationKey = Partial<keyof ViewStyle> | 'scale';
+
+export const MOTION_ANIMATIONS: MotionAnimationKey[] = [
+  'left',
+  'bottom',
+  'top',
+  'right',
+  'transform',
+  'translateX',
+  'translateY',
+  'scaleX',
+  'scaleY',
+  'scale',
+  'width',
+  'height',
+  'padding',
+  'paddingBottom',
+  'paddingLeft',
+  'paddingRight',
+  'paddingTop',
+  'paddingVertical',
+  'paddingHorizontal',
+  'margin',
+  'marginBottom',
+  'marginLeft',
+  'marginRight',
+  'marginTop',
+  'marginHorizontal',
+  'marginVertical',
+  'rotation',
+];

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

@@ -0,0 +1,99 @@
+/**
+ * Tests the __DEV__ = false branch for modules that export null when not in dev mode.
+ * Each test uses jest.resetModules + __DEV__ = false to hit the null branch.
+ */
+
+describe('dev mode null exports', () => {
+  beforeEach(() => {
+    jest.resetModules();
+  });
+
+  afterEach(() => {
+    // @ts-ignore
+    global.__DEV__ = true;
+  });
+
+  it('logError is null when __DEV__ is false', () => {
+    // @ts-ignore
+    global.__DEV__ = false;
+    const { logError } = require('./logError');
+    expect(logError).toBeNull();
+  });
+
+  it('isRuleDisabled is null when __DEV__ is false', () => {
+    // @ts-ignore
+    global.__DEV__ = false;
+    const { isRuleDisabled } = require('./isRuleDisabled');
+    expect(isRuleDisabled).toBeNull();
+  });
+
+  it('getRuleAction is null when __DEV__ is false', () => {
+    // @ts-ignore
+    global.__DEV__ = false;
+    const { getRuleAction } = require('./getRuleAction');
+    expect(getRuleAction).toBeNull();
+  });
+
+  it('getAMARuleErrorInfo is null when __DEV__ is false', () => {
+    // @ts-ignore
+    global.__DEV__ = false;
+    const { getAMARuleErrorInfo } = require('./getRuleErrorInfo');
+    expect(getAMARuleErrorInfo).toBeNull();
+  });
+
+  it('shouldIgnoreContrastCheckForDisabledElement is null when __DEV__ is false', () => {
+    // @ts-ignore
+    global.__DEV__ = false;
+    const { shouldIgnoreContrastCheckForDisabledElement } = require('./ignoreContrastCheck');
+    expect(shouldIgnoreContrastCheckForDisabledElement).toBeNull();
+  });
+
+  it('isAccessibilityLabelAllowed is null when __DEV__ is false', () => {
+    // @ts-ignore
+    global.__DEV__ = false;
+    const { isAccessibilityLabelAllowed } = require('./isA11yLabelAllowed');
+    expect(isAccessibilityLabelAllowed).toBeNull();
+  });
+
+  it('amaClearHighlight is null when __DEV__ is false', () => {
+    // @ts-ignore
+    global.__DEV__ = false;
+    const { amaClearHighlight } = require('./amaClearHighlight');
+    expect(amaClearHighlight).toBeNull();
+  });
+
+  it('amaHighlightComponent is null when __DEV__ is false', () => {
+    // @ts-ignore
+    global.__DEV__ = false;
+    const { amaHighlightComponent } = require('./amaHighlightComponent');
+    expect(amaHighlightComponent).toBeNull();
+  });
+
+  it('logger is null when __DEV__ is false', () => {
+    // @ts-ignore
+    global.__DEV__ = false;
+    const logger = require('./logger').default;
+    expect(logger).toBeNull();
+  });
+
+  it('LOGGER_RULES is null when __DEV__ is false', () => {
+    // @ts-ignore
+    global.__DEV__ = false;
+    const { LOGGER_RULES } = require('./rules');
+    expect(LOGGER_RULES).toBeNull();
+  });
+
+  it('RULES_HELP is null when __DEV__ is false', () => {
+    // @ts-ignore
+    global.__DEV__ = false;
+    const { RULES_HELP } = require('./rules');
+    expect(RULES_HELP).toBeNull();
+  });
+
+  it('useAMADev is null when __DEV__ is false', () => {
+    // @ts-ignore
+    global.__DEV__ = false;
+    const { useAMADev } = require('../useAMADev');
+    expect(useAMADev).toBeNull();
+  });
+});

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

@@ -0,0 +1,18 @@
+import { getErrorColor } from './getErrorColor';
+
+describe('getErrorColor', () => {
+  it('returns the Critical color for a Critical severity rule', () => {
+    const color = getErrorColor('NO_ACCESSIBILITY_LABEL');
+    expect(color).toBe('#f00');
+  });
+
+  it('returns the Serious color for a Serious severity rule', () => {
+    const color = getErrorColor('CONTRAST_FAILED');
+    expect(color).toBe('#2563EB');
+  });
+
+  it('returns the Critical color (fallback) for an unknown rule', () => {
+    const color = getErrorColor('UNKNOWN_RULE' as any);
+    expect(color).toBe('#f00');
+  });
+});

package/src/internals/utils/getErrorColor.ts

@@ -0,0 +1,8 @@
+import { AmaRule } from '../types';
+import { AMA_COLORS, RULES_HELP } from './rules';
+
+export const getErrorColor = (rule: AmaRule) => {
+  const theRule = RULES_HELP?.[rule];
+
+  return AMA_COLORS[theRule?.severity ?? 'Critical'];
+};

package/src/internals/utils/getRuleAction.ts

@@ -0,0 +1,13 @@
+import projectRules from '../config';
+import { AmaRule, AmaRuleAction } from '../types';
+import canRuleBeOverridden, { LOGGER_RULES } from './rules';
+
+export const getRuleAction = __DEV__
+  ? (rule: AmaRule): AmaRuleAction => {
+    const customRule = canRuleBeOverridden?.(rule)
+      ? projectRules?.rules?.[rule]
+      : undefined;
+
+    return customRule || LOGGER_RULES![rule];
+  }
+  : null;