@juspay/blend-design-system 0.0.37-beta.2 → 0.0.37-beta.4

package/lib/components/Inputs/NumberInput/accessibility/NumberInputAccessibilityReport.ts

@@ -0,0 +1,333 @@
+/**
+ * NumberInput Component Accessibility Report Data
+ * WCAG 2.0, 2.1, 2.2 (Level A, AA, AAA) Compliance Analysis
+ *
+ * Note: Items marked with "unsure" require manual verification
+ * Color contrast ratios should be verified using actual color values from theme tokens
+ */
+
+import type { AccessibilityReport } from '../../../Button/accessibility/ButtonAccessibilityReport'
+
+export const numberInputAccessibilityReport: AccessibilityReport = {
+    componentName: 'NumberInput',
+    wcagVersion: '2.2',
+    reportDate: new Date().toISOString().split('T')[0],
+    conformanceLevel: 'Level AA',
+    overallStatus: 'partial',
+    summary:
+        'The NumberInput component demonstrates strong compliance with WCAG 2.0, 2.1, and 2.2 standards at Level A and AA. Critical accessibility features are implemented including proper label association, keyboard navigation, error identification, ARIA attributes, focus management, and accessible numeric steppers. The component uses semantic HTML (<input type="number">), unique IDs for label/error associations, aria-describedby for linking hints and errors, and aria-label for stepper controls. Some contrast ratios require manual verification. This report evaluates criteria from WCAG 2.0, 2.1, and 2.2 guidelines. The component fully meets Level A requirements, fully meets Level AA requirements (with some items requiring verification), and partially meets Level AAA requirements. Currently compliant AAA criteria include 2.1.3 Keyboard (No Exception), 3.2.5 Change on Request, and 1.4.8 Visual Presentation. Non-compliant AAA criteria include 1.4.6 Contrast (Enhanced), which requires a 7:1 contrast ratio. To achieve full AAA compliance, text and border colors need to be adjusted to meet 7:1 contrast ratio (currently designed for AA standard of 4.5:1).',
+    criteria: [
+        {
+            id: '1.3.1',
+            level: 'A',
+            title: 'Info and Relationships',
+            status: 'compliant',
+            description:
+                'Information, structure, and relationships conveyed through presentation can be programmatically determined.',
+            implementation:
+                'Uses semantic HTML <input type="number"> element. Label association via <label htmlFor={inputId}>. Error messages linked via aria-describedby={errorId}. Hint text linked via aria-describedby={hintId}. Required state via aria-required. Error state via aria-invalid. Unique IDs generated via useId() hook.',
+            testResults:
+                'Verified: Proper semantic structure and ARIA relationships. Label association, error linking, and hint linking confirmed in NumberInput.tsx and InputFooter.tsx.',
+        },
+        {
+            id: '1.3.5',
+            level: 'AA',
+            title: 'Identify Input Purpose',
+            status: 'compliant',
+            description:
+                'The purpose of each input field can be programmatically determined when the field serves a purpose identified in the Input Purposes for User Interface Components section.',
+            implementation:
+                'Supports name attribute for input purpose identification. Uses type="number" with min, max, and step attributes to define numeric purpose and constraints. Supports autocomplete for numeric flows such as one-time codes (OTP).',
+            testResults:
+                'Verified: name, type, min, max, step, and autocomplete attributes supported. Implementation confirmed in NumberInput.tsx and NumberInput.accessibility.test.tsx.',
+        },
+        {
+            id: '1.4.3',
+            level: 'AA',
+            title: 'Contrast (Minimum)',
+            status: 'unsure',
+            description:
+                'Text and images of text have a contrast ratio of at least 4.5:1 for normal text, 3:1 for large text.',
+            implementation:
+                'NumberInput reuses the same input container tokens as TextInput for text color, borders, and disabled states. Text and borders are designed to meet AA contrast, but exact ratios depend on theme token values.',
+            testResults:
+                'UNSURE: Requires manual contrast ratio calculation similar to TextInput. Input text, error messages, hint text, and borders must be verified using a contrast checker. Disabled text and subtle borders require special attention.',
+            notes: 'Contrast ratios must be verified using tools like WebAIM Contrast Checker or Colour Contrast Analyser. Disabled states and subtle borders may not meet contrast requirements. Current implementation targets AA standard (4.5:1). For AAA compliance, contrast ratio must be 7:1.',
+        },
+        {
+            id: '1.4.6',
+            level: 'AAA',
+            title: 'Contrast (Enhanced)',
+            status: 'non-compliant',
+            description:
+                'Text and images of text have a contrast ratio of at least 7:1 for normal text, 4.5:1 for large text.',
+            implementation:
+                'NumberInput text and borders are designed for AA contrast (4.5:1 per WCAG 1.4.3), reused from TextInput/field tokens.',
+            testResults:
+                'NON-COMPLIANT: Current color combinations are designed for AA standard (4.5:1 per WCAG 1.4.3) and do not meet AAA requirement (7:1 per WCAG 1.4.6). To achieve AAA compliance, text and border color combinations must be redesigned to meet 7:1 contrast ratio.',
+            notes: 'This is a Level AAA criterion per WCAG 1.4.6. The component meets AA standard but not AAA. Manual contrast verification is required if AAA is a target.',
+        },
+        {
+            id: '1.4.8',
+            level: 'AAA',
+            title: 'Visual Presentation',
+            status: 'compliant',
+            description:
+                'Blocks of text can be presented without loss of content or functionality when text spacing and zoom are adjusted.',
+            implementation:
+                'NumberInput respects browser/system text size settings. Text uses relative units via tokens. Layout uses flexbox and responsive design, allowing text to scale up to 200% without loss of functionality.',
+            testResults:
+                'COMPLIANT: Input text scales properly with browser zoom up to 200%. Layout remains functional at all zoom levels. Verified through manual resizing in TextInput and shared field patterns.',
+        },
+        {
+            id: '2.1.1',
+            level: 'A',
+            title: 'Keyboard',
+            status: 'compliant',
+            description:
+                'All functionality of the content is operable through a keyboard interface without requiring specific timings for individual keystrokes.',
+            implementation:
+                'All numeric input functionality is available via keyboard. Users can tab to the field, type numbers, and use arrow keys and stepper buttons (with Enter/Space) depending on browser support. Disabled inputs are excluded from tab order.',
+            testResults:
+                'Verified: Full keyboard support for focus and input. Focus and disabled behavior covered in NumberInput.accessibility.test.tsx.',
+        },
+        {
+            id: '2.1.3',
+            level: 'AAA',
+            title: 'Keyboard (No Exception)',
+            status: 'compliant',
+            description:
+                'All functionality of the content is operable through a keyboard interface without requiring specific timings for individual keystrokes.',
+            implementation:
+                'Numeric value changes can be made entirely via keyboard (typing, arrow keys/steppers). No mouse-only interactions are required. Disabled state prevents interaction and is communicated programmatically.',
+            testResults:
+                'COMPLIANT: All functionality is keyboard accessible without timing constraints. Verified via keyboard-focused tests and browser behavior for <input type="number">.',
+        },
+        {
+            id: '2.4.3',
+            level: 'A',
+            title: 'Focus Order',
+            status: 'compliant',
+            description:
+                'If a Web page can be navigated sequentially and the navigation sequences affect meaning or operation, focusable components receive focus in an order that preserves meaning and operability.',
+            implementation:
+                'NumberInput participates in normal tab order. When multiple NumberInput fields are present, focus order follows DOM order. Disabled fields are not focusable.',
+            testResults:
+                'Verified: Focus order remains logical in NumberInput.accessibility.test.tsx when multiple fields and a submit button are rendered.',
+        },
+        {
+            id: '2.4.7',
+            level: 'AA',
+            title: 'Focus Visible',
+            status: 'unsure',
+            description:
+                'Any keyboard operable user interface has a mode of operation where the keyboard focus indicator is visible.',
+            implementation:
+                'Focus indicators are rendered via _focus styles on the underlying PrimitiveInput (border and box-shadow). Design mirrors TextInput focus styles.',
+            testResults:
+                'UNSURE: Focus indicators are visible but contrast ratios of focus outlines and borders require manual verification. Same caveats as TextInput.',
+            notes: 'Manual testing with keyboard-only navigation and contrast checkers is required to ensure focus indicators are sufficiently visible in all themes.',
+        },
+        {
+            id: '2.5.8',
+            level: 'AA',
+            title: 'Target Size (Minimum)',
+            status: 'compliant',
+            description:
+                'The size of the target for pointer inputs is at least 24 by 24 CSS pixels.',
+            implementation:
+                'NumberInput fields and stepper buttons are sized via tokens to meet or exceed 24x24px. Stepper buttons use explicit dimensions and are designed as standard clickable controls with adequate padding.',
+            testResults:
+                'COMPLIANT: Input fields naturally exceed 24x24px minimum. Stepper buttons are designed to meet AA target size requirements. Exact pixel measurements should be verified with DevTools if needed.',
+        },
+        {
+            id: '3.2.1',
+            level: 'A',
+            title: 'On Focus',
+            status: 'compliant',
+            description:
+                'When any user interface component receives focus, it does not initiate a change of context.',
+            implementation:
+                'Focusing the NumberInput does not cause navigation, submission, or other context changes. Optional onFocus callback is developer-controlled and not used internally for navigation.',
+            testResults:
+                'Verified: No unexpected context changes on focus. Focus tests in NumberInput.accessibility.test.tsx confirm predictable behavior.',
+        },
+        {
+            id: '3.2.2',
+            level: 'A',
+            title: 'On Input',
+            status: 'compliant',
+            description:
+                'Changing the setting of any user interface component does not automatically cause a change of context unless the user has been advised of the behavior before using the component.',
+            implementation:
+                'Changing the numeric value only calls onChange; it does not automatically submit forms or navigate. Any such behavior is left to consuming applications.',
+            testResults:
+                'Verified: Value changes are local to the component and do not trigger navigation or form submission by default.',
+        },
+        {
+            id: '3.2.5',
+            level: 'AAA',
+            title: 'Change on Request',
+            status: 'compliant',
+            description:
+                'Changes of context are initiated only by user request or a mechanism is available to turn off such changes.',
+            implementation:
+                'All context changes related to NumberInput require explicit user action (typing, clicking steppers). The component does not trigger context changes automatically.',
+            testResults:
+                'COMPLIANT: No automatic context changes. All interactions are user-initiated.',
+        },
+        {
+            id: '3.3.1',
+            level: 'A',
+            title: 'Error Identification',
+            status: 'compliant',
+            description:
+                'If an input error is automatically detected, the item that is in error is identified and the error is described to the user in text.',
+            implementation:
+                'Error state is exposed via error prop and errorMessage. Error messages are rendered under the field via InputFooter with role="alert" and aria-live="polite" and linked via aria-describedby.',
+            testResults:
+                'Verified: Errors are visually and programmatically identified. Tests cover out-of-range values (e.g., age beyond min/max).',
+        },
+        {
+            id: '3.3.2',
+            level: 'A',
+            title: 'Labels or Instructions',
+            status: 'compliant',
+            description:
+                'Labels or instructions are provided when content requires user input.',
+            implementation:
+                'Label provides main description. Sublabel provides contextual instructions (e.g., "Before taxes and deductions"). Hint text explains constraints (e.g., min/max ranges). Help icon hints can be added via shared label utilities.',
+            testResults:
+                'Verified: Label, sublabel, and hint text are rendered and accessible in NumberInput.accessibility.test.tsx.',
+        },
+        {
+            id: '3.3.3',
+            level: 'AA',
+            title: 'Error Suggestion',
+            status: 'compliant',
+            description:
+                'If an input error is automatically detected and suggestions for correction are known, then the suggestions are provided to the user.',
+            implementation:
+                'Error messages are customizable and can include explicit guidance such as "Enter a value between 0 and 100". Example usage is demonstrated in accessibility tests.',
+            testResults:
+                'Verified: Error suggestions are supported and tested (e.g., percentage range guidance).',
+        },
+        {
+            id: '3.3.7',
+            level: 'A',
+            title: 'Redundant Entry',
+            status: 'compliant',
+            description:
+                'Information previously entered by or provided to the user that is required to be entered again is auto-populated or selectable.',
+            implementation:
+                'Supports autocomplete for reducing redundant numeric entry where applicable (e.g., one-time codes). Browser can auto-fill numeric fields when appropriate.',
+            testResults:
+                'Verified: Autocomplete attribute supported and tested (e.g., autoComplete="one-time-code").',
+        },
+        {
+            id: '4.1.2',
+            level: 'A',
+            title: 'Name, Role, Value',
+            status: 'compliant',
+            description:
+                'For all user interface components, the name and role can be programmatically determined; states, properties, and values can be set and notified to assistive technologies.',
+            implementation:
+                'Uses semantic <input type="number"> with implicit role="spinbutton" in many ATs. Accessible name comes from <label>. States and properties include disabled, required/aria-required, aria-invalid, aria-describedby. Stepper buttons use aria-label to expose their function.',
+            testResults:
+                'Verified: Name, role, and value are correctly exposed. aria-* attributes are present and tested in NumberInput.accessibility.test.tsx.',
+        },
+    ],
+    strengths: [
+        'Semantic <input type="number"> implementation with spinbutton semantics in assistive technologies',
+        'Proper label association via <label htmlFor={inputId}> and unique ID generation with useId()',
+        'Error messages linked via aria-describedby and announced via role="alert" and aria-live="polite"',
+        'Hint text and sublabels provide additional context for numeric constraints',
+        'Keyboard operability for both text entry and steppers, including disabled state handling',
+        'Numeric constraints communicated via min, max, and step attributes',
+        'Stepper buttons have explicit aria-labels describing increase/decrease actions',
+        'Target sizes for input and steppers are designed to meet WCAG 2.5.8 Level AA',
+        'Supports autocomplete for reducing redundant numeric entry where appropriate',
+        'Predictable behavior with no unexpected context changes on focus or input',
+    ],
+    recommendations: [
+        'VERIFY: Color contrast ratios for numeric text, borders, and error messages using WebAIM Contrast Checker or similar tool',
+        'VERIFY: Focus indicator contrast ratios meet 3:1 requirement against the input background, especially around steppers',
+        'VERIFY: Disabled state contrast ratios meet minimum readability requirements',
+        'Consider documenting numeric-specific guidance (e.g., how to expose min/max ranges and units in labels or hint text)',
+        'For AAA compliance (WCAG 1.4.6), adjust text and border colors to achieve 7:1 contrast where possible',
+        'Add documentation examples showing how to localize number formats and labels',
+        'Ensure steppers remain sufficiently large and well-spaced on touch devices, especially in dense layouts',
+        'Encourage teams to validate numeric error messages for clarity (e.g., including acceptable ranges and units)',
+    ],
+    wcagVersions: {
+        '2.0': [
+            'All relevant Level A and AA criteria from WCAG 2.0 are evaluated for numeric form fields',
+            'WCAG 2.0 provides the foundational form and error handling requirements reused here',
+        ],
+        '2.1': [
+            'WCAG 2.1 adds criteria related to input purpose, reflow, and pointer inputs that impact NumberInput',
+            'New Level A/AA criteria such as 1.3.5, 1.4.10, 1.4.11, 2.5.3, and 2.5.4 are considered via shared field patterns',
+        ],
+        '2.2': [
+            'WCAG 2.2 adds criteria related to target size (2.5.8) and redundant entry (3.3.7) that are explicitly addressed',
+            'NumberInput aligns with WCAG 2.2 by supporting large enough targets and autocomplete where appropriate',
+        ],
+    },
+    testMethodology: {
+        automated: [
+            'jest-axe (axe-core integration) for automated accessibility testing',
+            'axe-core validation: ensure no accessibility violations using axe(container).toHaveNoViolations()',
+            'Test file: packages/blend/__tests__/components/Inputs/NumberInput.accessibility.test.tsx (24 tests)',
+            'Semantic validation of <input type="number"> as a spinbutton in assistive technologies',
+            'ARIA attribute validation: aria-required, aria-invalid, aria-describedby, aria-label on steppers',
+            'Keyboard operability tests: focusability, disabled behavior, and change handling',
+            'Form integration checks for name, min, max, step, and autocomplete attributes',
+        ],
+        manual: [
+            'REQUIRED: Color contrast verification for numeric text, hint text, error text, and borders using WebAIM Contrast Checker or CCA',
+            'REQUIRED: Focus indicator visibility and contrast verification, especially when steppers appear adjacent to the field',
+            'Screen reader testing with NVDA/JAWS/VoiceOver to confirm spinbutton announcements, label reading, and error messages',
+            'Keyboard-only navigation testing: tab through numeric fields and verify focus order and steppers are reachable',
+            'Touch target measurement for steppers and fields using browser DevTools (ensure ≥24x24px per WCAG 2.5.8)',
+            'Verification of numeric constraints announcements (e.g., min/max) depending on AT/browser support',
+        ],
+        verificationTools: [
+            'WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/',
+            'Colour Contrast Analyser (CCA): https://www.tpgi.com/color-contrast-checker/',
+            'axe DevTools Browser Extension',
+            'WAVE Browser Extension',
+            'Lighthouse Accessibility Audit',
+            'NVDA, JAWS, and VoiceOver screen readers',
+            'Keyboard-only navigation testing',
+            'Browser DevTools for measuring target sizes and inspecting ARIA attributes',
+        ],
+        wcagLevels: {
+            A: [
+                '1.3.1 Info and Relationships',
+                '2.1.1 Keyboard',
+                '2.4.3 Focus Order',
+                '3.2.1 On Focus',
+                '3.2.2 On Input',
+                '3.3.1 Error Identification',
+                '3.3.2 Labels or Instructions',
+                '3.3.3 Error Suggestion',
+                '3.3.7 Redundant Entry (WCAG 2.2)',
+                '4.1.2 Name, Role, Value',
+            ],
+            AA: [
+                '1.3.5 Identify Input Purpose',
+                '1.4.3 Contrast (Minimum)',
+                '1.4.11 Non-text Contrast (shared with field styling, verification required)',
+                '1.4.12 Text Spacing (inherited from text field patterns)',
+                '2.4.7 Focus Visible',
+                '2.5.8 Target Size (Minimum) (WCAG 2.2)',
+            ],
+            AAA: [
+                '1.4.6 Contrast (Enhanced) - currently non-compliant, designed for AA 4.5:1 per WCAG 1.4.3',
+                '1.4.8 Visual Presentation - component respects browser/system text size and color settings',
+                '2.1.3 Keyboard (No Exception) - all functionality keyboard accessible without timing requirements',
+                '3.2.5 Change on Request - all context changes require explicit user action',
+            ],
+        },
+    },
+}

package/lib/components/Inputs/NumberInput/index.ts

@@ -0,0 +1,3 @@
+export { default as NumberInput } from './NumberInput'
+export * from './numberInput.tokens'
+export * from './types'