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

package/src/internals/components/AMARuleError.tsx

@@ -0,0 +1,225 @@
+/* eslint-disable react-native/no-inline-styles */
+import React, { ReactNode } from 'react';
+import { Pressable, ScrollView, StyleSheet, Text, View } from 'react-native';
+import { AmaError } from '../types';
+import { A11ySeverity } from '../utils/getRuleErrorInfo';
+import { RULES_HELP } from '../utils/rules';
+
+const SEVERITIES: { [key in A11ySeverity]: string } | null = __DEV__
+  ? {
+      Serious: 'Serious',
+      Critical: 'Critical',
+      Warning: 'Warning',
+    }
+  : null;
+
+const REGEX_MARKDOWN = /(`[^`]+`|\*\*[^*]+\*\*)/g;
+
+export const AMARuleError = __DEV__
+  ? ({
+      issue,
+      maxHeight,
+      onClose,
+    }: {
+      issue: AmaError;
+      onClose: () => void;
+      maxHeight: number;
+    }) => {
+      const ruleHelp = RULES_HELP![issue.rule];
+      const COLOR_TOKEN_REGEX = /(\(#[0-9A-Fa-f]{3,8}\))/g;
+
+      const renderMarkdown = (text: string) => {
+        const parts = text.split(REGEX_MARKDOWN);
+
+        return parts.map((part, index) => {
+          if (part.startsWith('`') && part.endsWith('`') && Code) {
+            return <Code key={index}>{part.slice(1, -1)}</Code>;
+          }
+
+          if (part.startsWith('**') && part.endsWith('**')) {
+            return (
+              <Text key={index} style={[styles?.text, styles?.bold]}>
+                {part.slice(2, -2)}
+              </Text>
+            );
+          }
+
+          return (
+            <Text key={index} style={styles?.text}>
+              {part}
+            </Text>
+          );
+        });
+      };
+
+      const renderHowToFix = (text: string | string[]) => {
+        if (typeof text === 'string') {
+          return <Text style={styles?.text}>{renderMarkdown(text)}</Text>;
+        }
+
+        return (
+          <View>
+            {text.map((value, index) => {
+              return (
+                <Text key={index} style={styles!.text}>
+                  {renderMarkdown(value)}
+                </Text>
+              );
+            })}
+          </View>
+        );
+      };
+
+      const renderTextWithColorSwatches = (text: string) => {
+        const parts = text.split(COLOR_TOKEN_REGEX);
+
+        return parts.map((part, index) => {
+          if (part.startsWith('(#') && part.endsWith(')')) {
+            const color = part.slice(1, -1);
+
+            return (
+              <React.Fragment key={index}>
+                <Text
+                  style={styles?.text}
+                  importantForAccessibility="no-hide-descendants"
+                  accessibilityElementsHidden
+                >
+                  (
+                </Text>
+                <Text
+                  style={styles!.swatchFrame}
+                  importantForAccessibility="no-hide-descendants"
+                  accessibilityElementsHidden
+                >
+                  <Text
+                    style={[styles!.swatchGlyph, { color }]}
+                    importantForAccessibility="no-hide-descendants"
+                    accessibilityElementsHidden
+                  >
+                    ■
+                  </Text>
+                </Text>
+                <Text
+                  style={styles?.text}
+                  importantForAccessibility="no-hide-descendants"
+                  accessibilityElementsHidden
+                  accessible={false}
+                >
+                  {` ${color}`}
+                </Text>
+                <Text
+                  style={styles?.text}
+                  importantForAccessibility="no-hide-descendants"
+                  accessibilityElementsHidden
+                >
+                  )
+                </Text>
+              </React.Fragment>
+            );
+          }
+
+          return (
+            <Text key={index} style={styles?.text}>
+              {part}
+            </Text>
+          );
+        });
+      };
+
+      return (
+        <ScrollView style={{ maxHeight, flex: 1, width: '100%', padding: 12 }}>
+          <View style={styles!.row}>
+            <Text style={styles!.bold} aria-role="header">
+              {SEVERITIES![ruleHelp.severity]}:
+            </Text>
+            <Text style={styles!.flex}>{ruleHelp.issue}</Text>
+            <Pressable
+              hitSlop={{ left: 18, top: 18, bottom: 18, right: 18 }}
+              role="button"
+              aria-label="Close Error information"
+              onPress={onClose}
+            >
+              <Text> ✖ </Text>
+            </Pressable>
+          </View>
+
+          <Text style={[styles!.bold, styles?.full]} aria-role="header">
+            Why this matters:
+          </Text>
+          <View style={[styles!.row, styles?.column]}>
+            <Text style={styles?.text}>{ruleHelp.message}</Text>
+            {issue.extra ? (
+              <View style={styles!.extraInline}>
+                {renderTextWithColorSwatches(String(issue.extra))}
+              </View>
+            ) : null}
+          </View>
+          <Text style={[styles!.bold, styles?.full]} aria-role="header">
+            How to fix:
+          </Text>
+          <View style={styles!.row}>{renderHowToFix(ruleHelp.howToFix)}</View>
+        </ScrollView>
+      );
+    }
+  : null;
+
+const Code = __DEV__
+  ? ({ children }: { children: ReactNode }) => {
+      const code =
+        typeof children === 'string' ? children.replace(/`/g, '') : children;
+
+      return <Text style={styles!.code}> {code} </Text>;
+    }
+  : null;
+
+const styles = __DEV__
+  ? StyleSheet.create({
+      row: {
+        flexDirection: 'row',
+        alignContent: 'center',
+        alignItems: 'center',
+        fontSize: 14,
+        width: '100%',
+        marginBottom: 12,
+        flex: 1,
+      },
+      bold: {
+        fontSize: 14,
+        fontWeight: 600,
+        paddingRight: 12,
+      },
+      full: {
+        width: '100%',
+        marginBottom: 4,
+      },
+      text: {
+        lineHeight: 18,
+        paddingBottom: 4,
+      },
+      column: {
+        flexDirection: 'column',
+      },
+      flex: {
+        flex: 1,
+      },
+      code: {
+        backgroundColor: '#333',
+        color: '#fff',
+      },
+      extraInline: {
+        flexDirection: 'row',
+        flexWrap: 'wrap',
+        alignItems: 'center',
+      },
+      swatchFrame: {
+        backgroundColor: '#000',
+        paddingHorizontal: 2,
+        marginHorizontal: 2,
+        lineHeight: 14,
+      },
+      swatchGlyph: {
+        fontSize: 11,
+        lineHeight: 14,
+      },
+    })
+  : null;

package/src/internals/config.ts

@@ -0,0 +1,58 @@
+import logger from './utils/logger';
+import { AmaRule, AmaRuleAction } from './utils/rules';
+
+export const NON_OVERRIDABLE_RULES: string[] | undefined = __DEV__
+  ? [
+    'NO_ACCESSIBILITY_ROLE',
+    'NO_ACCESSIBILITY_LABEL',
+    'NO_KEYBOARD_TRAP',
+    'NO_UNDEFINED',
+    'INPUT_HAS_NO_VISIBLE_LABEL',
+    'FLATLIST_NO_COUNT_IN_PLURAL_MESSAGE',
+    'BOTTOM_SHEET_CLOSE_ACTION',
+    'INCOMPATIBLE_ACCESSIBILITY_STATE',
+    'INCOMPATIBLE_ACCESSIBILITY_ROLE',
+  ]
+  : undefined;
+
+export type HighlightMode = 'border' | 'background' | 'both';
+export type LogMode = 'always' | 'inspect';
+
+export type AmaProjectConfig = {
+  rules: Record<
+    | Partial<AmaRule>
+    | 'CONTRAST_CHECKER_MAX_DEPTH'
+    | 'IGNORE_CONTRAST_FOR_DISABLED_ELEMENTS',
+    AmaRuleAction
+  > | null;
+  accessibilityLabelExceptions: string[];
+  highlight: {
+    mode: HighlightMode;
+    borderWidth?: number;
+    gap?: number;
+  };
+  log: LogMode;
+  uppercaseMinLength: number;
+  longNumberMinLength: number;
+  checks: {
+    ui: boolean;
+    forms: boolean;
+    delay: number;
+  };
+};
+
+const defaultRules: AmaProjectConfig = require('./../../ama.config.json');
+let projectRules = defaultRules;
+
+try {
+  // look upwards to user's project root
+  const userDefinedRules: Partial<AmaProjectConfig> = require('./../../../../ama.config.json');
+  projectRules = Object.assign(projectRules, userDefinedRules);
+
+  logger?.log("Using project's config file");
+} catch (_) {
+  logger?.log('Project config not found, using default one!');
+}
+
+logger?.log(JSON.stringify(projectRules, null, 2));
+export default projectRules;

package/src/internals/types.ts

@@ -0,0 +1,11 @@
+import { AmaRule, AmaRuleAction } from './utils/rules';
+export type { AmaRule, AmaRuleAction };
+
+export type Position = [number, number, number, number];
+
+export type AmaError = {
+  rule: AmaRule;
+  extra?: any;
+  label?: string;
+  viewId: number;
+};

package/src/internals/useAMADev.dev.ts

@@ -0,0 +1,153 @@
+import { useEffect, useRef, useState } from 'react';
+import type { RefObject } from 'react';
+import { DevSettings } from 'react-native';
+import type { AmaNodes, AmaUiSnapshotsData } from '../ReactNativeAma.types';
+import ReactNativeAmaModule from '../ReactNativeAmaModule';
+import projectRules from './config';
+import type { AmaError, AmaRule } from './types';
+import type { UseAMADev } from './useAMADev';
+import { getNodeIssueState, runNodeChecks } from './useAMADevNodeChecks.dev';
+import {
+  getItemsWithNoStateUpdated,
+  syncUiInteractionIssues,
+} from './useAMADevUiInteraction.dev';
+import { amaClearHighlight } from './utils/amaClearHighlight';
+import { logError } from './utils/logError';
+import logger from './utils/logger';
+
+const startAMA = __DEV__
+  ? () => {
+      logger?.log(
+        '👀 Start Monitoring 👀: ' + JSON.stringify(projectRules.checks)
+      );
+
+      ReactNativeAmaModule.start({
+        ...projectRules.checks,
+        borderWidth: projectRules.highlight?.borderWidth,
+        gap: projectRules.highlight?.gap,
+      });
+    }
+  : null;
+
+export const useAMADev: UseAMADev | null = __DEV__
+  ? () => {
+      const isMonitoring = useRef(true);
+      const lastNodesChecked = useRef<AmaNodes>({});
+      const previousNodeIssues = useRef<AmaError[]>([]);
+      const jsFailedChecks = useRef<AmaError[]>([]);
+      const highlightedIssues = useRef<Record<number, number>>({});
+      const issuesRef = useRef<AmaError[]>([]);
+      const [issues, setIssues] = useState<AmaError[]>([]);
+
+      useEffect(() => {
+        issuesRef.current = issues;
+      }, [issues]);
+
+      const checkNodes = (nodesToCheck: AmaNodes) => {
+        lastNodesChecked.current = nodesToCheck;
+
+        const nodeIssues =
+          runNodeChecks?.({
+            nodesToCheck,
+            previousNodeIssues: previousNodeIssues.current,
+            jsFailedChecks: jsFailedChecks.current,
+            highlightedIssues: highlightedIssues.current,
+          }) ?? [];
+
+        setIssues(
+          (currentIssues) =>
+            getNodeIssueState?.(currentIssues, nodeIssues, nodesToCheck) ??
+            currentIssues
+        );
+        previousNodeIssues.current = nodeIssues;
+      };
+
+      const checkResultUiInteraction = (data?: AmaUiSnapshotsData) => {
+        if (!data) {
+          return;
+        }
+
+        const itemsToFlag = Array.from(
+          getItemsWithNoStateUpdated?.(data, lastNodesChecked.current) ?? []
+        );
+
+        setIssues(
+          (prevIssues) =>
+            syncUiInteractionIssues?.(prevIssues, itemsToFlag, data.rootTag) ??
+            prevIssues
+        );
+      };
+
+      const stopAMA = () => {
+        logger?.log('[React Native AMA]: 🙈 Stop Monitoring 🙈');
+
+        for (const issue of issuesRef.current) {
+          amaClearHighlight?.(issue);
+        }
+
+        highlightedIssues.current = {};
+        ReactNativeAmaModule.stop();
+      };
+
+      useEffect(() => {
+        startAMA?.();
+
+        const amaOnNodesListener = ReactNativeAmaModule.addListener(
+          'onAmaNodes',
+          checkNodes
+        );
+        const amaOnUiInteraction = ReactNativeAmaModule.addListener(
+          'onUIInteraction',
+          checkResultUiInteraction
+        );
+
+        return () => {
+          stopAMA();
+
+          amaOnNodesListener.remove();
+          amaOnUiInteraction.remove();
+        };
+      }, []);
+
+      const toggleReactNativeAMA = () => {
+        if (isMonitoring.current) {
+          stopAMA();
+          setIssues([]);
+        } else {
+          startAMA?.();
+        }
+
+        isMonitoring.current = !isMonitoring.current;
+      };
+
+      const trackError = (rule: AmaRule, ref?: RefObject<any>) => {
+        const viewId = ref?.current?.__nativeTag ?? -1;
+        const issue: AmaError = { rule, viewId };
+
+        logError?.(issue);
+
+        const alreadyTracked = jsFailedChecks.current.some(
+          (item) => item.viewId === viewId && item.rule === rule
+        );
+
+        if (!alreadyTracked) {
+          jsFailedChecks.current.push(issue);
+          setIssues((currentIssues) => [...currentIssues, issue]);
+          checkNodes(lastNodesChecked.current);
+        }
+      };
+
+      useEffect(() => {
+        DevSettings.addMenuItem(
+          'Toggle React Native AMA',
+          toggleReactNativeAMA
+        );
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+      }, []);
+
+      return {
+        issues,
+        trackError,
+      };
+    }
+  : null;

package/src/internals/useAMADev.test.ts

@@ -0,0 +1,260 @@
+import { renderHook, act } from '@testing-library/react-native';
+import projectRules from './config';
+
+let mockStart: jest.Mock;
+let mockStop: jest.Mock;
+let mockHighlight: jest.Mock;
+let mockClearHighlight: jest.Mock;
+let mockAddListener: jest.Mock;
+let onAmaNodesCallback: ((data: any) => void) | null = null;
+let onUIInteractionCallback: ((data: any) => void) | null = null;
+
+jest.mock('../ReactNativeAmaModule', () => {
+  mockStart = jest.fn();
+  mockStop = jest.fn();
+  mockHighlight = jest.fn().mockResolvedValue([0, 0, 100, 50]);
+  mockClearHighlight = jest.fn();
+  mockAddListener = jest.fn().mockImplementation((event: string, cb: any) => {
+    if (event === 'onAmaNodes') {
+      onAmaNodesCallback = cb;
+    } else if (event === 'onUIInteraction') {
+      onUIInteractionCallback = cb;
+    }
+    return { remove: jest.fn() };
+  });
+
+  return {
+    __esModule: true,
+    default: {
+      start: (...args: any[]) => mockStart(...args),
+      stop: (...args: any[]) => mockStop(...args),
+      highlight: (...args: any[]) => mockHighlight(...args),
+      clearHighlight: (...args: any[]) => mockClearHighlight(...args),
+      addListener: (...args: any[]) => mockAddListener(...args),
+    },
+  };
+});
+
+jest.mock('./utils/logFoundIssues', () => ({
+  logFoundIssues: jest.fn(),
+}));
+
+jest.mock('./utils/amaClearHighlight', () => ({
+  amaClearHighlight: jest.fn(),
+}));
+
+const makeNode = (overrides = {}) => ({
+  type: 'Text',
+  viewId: 1,
+  traits: ['header'],
+  ariaRole: 'header',
+  ariaLabel: 'Title',
+  ...overrides,
+});
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  onAmaNodesCallback = null;
+  onUIInteractionCallback = null;
+  // @ts-ignore
+  global.__DEV__ = true;
+});
+
+afterEach(() => {
+  projectRules.rules = {} as typeof projectRules.rules;
+});
+
+describe('useAMADev', () => {
+  it('starts AMA monitoring on mount', () => {
+    const { useAMADev } = require('./useAMADev');
+    renderHook(() => useAMADev!());
+    expect(mockStart).toHaveBeenCalledTimes(1);
+  });
+
+  it('registers onAmaNodes and onUIInteraction listeners', () => {
+    const { useAMADev } = require('./useAMADev');
+    renderHook(() => useAMADev!());
+    expect(mockAddListener).toHaveBeenCalledWith('onAmaNodes', expect.any(Function));
+    expect(mockAddListener).toHaveBeenCalledWith('onUIInteraction', expect.any(Function));
+  });
+
+  it('stops AMA monitoring on unmount', () => {
+    const { useAMADev } = require('./useAMADev');
+    const { unmount } = renderHook(() => useAMADev!());
+    unmount();
+    expect(mockStop).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns empty issues initially', () => {
+    const { useAMADev } = require('./useAMADev');
+    const { result } = renderHook(() => useAMADev!());
+    expect(result.current.issues).toEqual([]);
+  });
+
+  it('adds NO_HEADER_FOUND issue when no header node is present', async () => {
+    const { useAMADev } = require('./useAMADev');
+    const { result } = renderHook(() => useAMADev!());
+
+    await act(async () => {
+      onAmaNodesCallback?.({ 1: makeNode({ type: 'View', traits: [], ariaRole: 'button' }) });
+    });
+
+    expect(result.current.issues).toContainEqual(
+      expect.objectContaining({ rule: 'NO_HEADER_FOUND' }),
+    );
+  });
+
+  it('does not add NO_HEADER_FOUND when a header node is present', async () => {
+    const { useAMADev } = require('./useAMADev');
+    const { result } = renderHook(() => useAMADev!());
+
+    await act(async () => {
+      onAmaNodesCallback?.({ 1: makeNode({ type: 'Text', ariaRole: 'header' }) });
+    });
+
+    const headerIssues = result.current.issues.filter(
+      (i: any) => i.rule === 'NO_HEADER_FOUND',
+    );
+    expect(headerIssues).toHaveLength(0);
+  });
+
+  it('highlights a component when a Pressable has no accessibility label', async () => {
+    const { useAMADev } = require('./useAMADev');
+    renderHook(() => useAMADev!());
+
+    await act(async () => {
+      onAmaNodesCallback?.({
+        1: makeNode({ type: 'Text', ariaRole: 'header', viewId: 1 }),
+        42: {
+          type: 'Pressable',
+          viewId: 42,
+          traits: ['button'],
+          ariaRole: 'button',
+          ariaLabel: undefined,
+          width: 50,
+          height: 50,
+        },
+      });
+    });
+
+    expect(mockHighlight).toHaveBeenCalledWith(42, expect.any(String), expect.any(String), expect.any(Number));
+  });
+
+  it('handles checkResultUiInteraction with no data gracefully', async () => {
+    const { useAMADev } = require('./useAMADev');
+    renderHook(() => useAMADev!());
+
+    await act(async () => {
+      onUIInteractionCallback?.(undefined);
+    });
+
+    expect(mockHighlight).not.toHaveBeenCalled();
+  });
+
+  it('clears highlights for fixed issues when new check has fewer problems', async () => {
+    const { amaClearHighlight } = require('./utils/amaClearHighlight');
+    const { useAMADev } = require('./useAMADev');
+    renderHook(() => useAMADev!());
+
+    const badPressable = {
+      type: 'Pressable',
+      viewId: 99,
+      traits: ['button'],
+      ariaRole: 'button',
+      ariaLabel: undefined,
+      width: 50,
+      height: 50,
+    };
+
+    await act(async () => {
+      onAmaNodesCallback?.({
+        1: makeNode({ type: 'Text', ariaRole: 'header', viewId: 1 }),
+        99: badPressable,
+      });
+    });
+
+    expect(mockHighlight).toHaveBeenCalled();
+
+    await act(async () => {
+      onAmaNodesCallback?.({
+        1: makeNode({ type: 'Text', ariaRole: 'header', viewId: 1 }),
+        99: { ...badPressable, ariaLabel: 'Fixed label' },
+      });
+    });
+
+    expect(amaClearHighlight).toHaveBeenCalled();
+  });
+
+  it('checkResultUiInteraction flags NO_ACCESSIBILITY_STATE_SET when state did not change after tap', async () => {
+    const { useAMADev } = require('./useAMADev');
+    const { result } = renderHook(() => useAMADev!());
+
+    await act(async () => {
+      onAmaNodesCallback?.({
+        1: makeNode({ type: 'Text', ariaRole: 'header', viewId: 1 }),
+        100: makeNode({ type: 'Pressable', viewId: 100, ariaRole: 'button', ariaLabel: 'Toggle', traits: ['button'] }),
+      });
+    });
+
+    const snapshot = { label: 'Toggle', role: 'button', isChecked: false, isBusy: false, isSelected: false, isDisabled: false, isExpanded: false, parentId: 0 };
+
+    await act(async () => {
+      onUIInteractionCallback?.({
+        rootTag: 100,
+        beforeModalVisible: false,
+        afterModalVisible: false,
+        before: { 100: { ...snapshot, label: 'Toggle changed' } },
+        after: { 100: snapshot },
+        afterSettled: { 100: snapshot },
+      });
+    });
+
+    expect(result.current.issues.some((i: any) => i.rule === 'NO_ACCESSIBILITY_STATE_SET')).toBe(true);
+  });
+
+  it('checkResultUiInteraction clears NO_ACCESSIBILITY_STATE_SET when state did change', async () => {
+    const { useAMADev } = require('./useAMADev');
+    const { result } = renderHook(() => useAMADev!());
+
+    await act(async () => {
+      onAmaNodesCallback?.({
+        1: makeNode({ type: 'Text', ariaRole: 'header', viewId: 1 }),
+        100: makeNode({ type: 'Pressable', viewId: 100, ariaRole: 'button', ariaLabel: 'Toggle', traits: ['button'] }),
+      });
+    });
+
+    const snapshot = { label: 'Toggle', role: 'button', isChecked: false, isBusy: false, isSelected: false, isDisabled: false, isExpanded: false, parentId: 0 };
+
+    await act(async () => {
+      onUIInteractionCallback?.({
+        rootTag: 100,
+        beforeModalVisible: false,
+        afterModalVisible: false,
+        before: { 100: { ...snapshot, isChecked: false, label: 'changed' } },
+        after: { 100: { ...snapshot, isChecked: true } },
+        afterSettled: { 100: { ...snapshot, isChecked: true } },
+      });
+    });
+
+    expect(result.current.issues.some((i: any) => i.rule === 'NO_ACCESSIBILITY_STATE_SET')).toBe(false);
+  });
+
+  it('checkResultUiInteraction does nothing when rootTag is not in afterKeys', async () => {
+    const { useAMADev } = require('./useAMADev');
+    const { result } = renderHook(() => useAMADev!());
+
+    await act(async () => {
+      onUIInteractionCallback?.({
+        rootTag: 999,
+        beforeModalVisible: false,
+        afterModalVisible: false,
+        before: {},
+        after: { 1: { label: 'btn' } },
+        afterSettled: null,
+      });
+    });
+
+    expect(result.current.issues.some((i: any) => i.rule === 'NO_ACCESSIBILITY_STATE_SET')).toBe(false);
+  });
+
+});