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

package/lib/components/Drawer/accessibility/DrawerAccessibilityReport.ts

@@ -0,0 +1,394 @@
+/**
+ * Drawer Component Accessibility Report Data
+ * WCAG 2.1 Level AA Compliance Analysis
+ *
+ * Note: Items marked with "unsure" require manual verification
+ * Color contrast ratios verified using actual color values from theme tokens
+ */
+
+import type { AccessibilityReport } from '../../StatCard/accessibility/StatCardAccessibilityReport'
+
+export const drawerAccessibilityReport: AccessibilityReport = {
+    componentName: 'Drawer',
+    wcagVersion: '2.1',
+    reportDate: new Date().toISOString().split('T')[0],
+    conformanceLevel: 'Level AA',
+    overallStatus: 'partial',
+    summary:
+        'The Drawer component demonstrates strong compliance with WCAG 2.1 Level AA standards. All critical accessibility features are implemented including keyboard navigation, screen reader support, proper ARIA attributes, semantic structure, and focus management. The component uses role="dialog" and aria-modal="true" for proper dialog semantics. DrawerTitle and DrawerDescription are automatically connected via aria-labelledby and aria-describedby. Focus is trapped within the drawer when open and returns to the trigger when closed. All interactive elements are keyboard accessible (Tab, Shift+Tab, Escape, Enter, Space). The component supports multiple directions (top, bottom, left, right) and maintains accessibility across all configurations. Decorative elements like the drag handle are properly marked with aria-hidden="true". Screen reader announcements are provided for state changes. 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: 2.1.3 Keyboard (No Exception), 3.2.5 Change on Request. Non-compliant AAA criteria: 1.4.6 Contrast (Enhanced) - requires 7:1 contrast ratio. To achieve full AAA compliance, contrast ratios need to meet AAA standard of 7:1 (currently designed for AA standard of 4.5:1).',
+    criteria: [
+        {
+            id: '1.1.1',
+            level: 'A',
+            title: 'Non-text Content',
+            status: 'compliant',
+            description:
+                'All non-text content has text alternatives. Icons and decorative elements are properly labeled or hidden.',
+            implementation:
+                'Decorative icons (e.g., close button icons) are marked with aria-hidden="true". The drag handle is marked with aria-hidden="true" as it is decorative. DrawerTitle and DrawerDescription provide accessible text content. All interactive elements have accessible names via text or aria-label.',
+            testResults:
+                'Verified: All decorative elements properly hidden. Text content accessible. Icons properly handled. Implementation confirmed in DrawerBase.tsx and Drawer.accessibility.test.tsx.',
+        },
+        {
+            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:
+                'Drawer has role="dialog" and aria-modal="true". DrawerTitle is automatically linked via aria-labelledby. DrawerDescription is automatically linked via aria-describedby when present. DrawerContent maintains proper semantic structure with header, body, and footer sections. All ARIA relationships are programmatically determinable via DrawerAccessibilityContext.',
+            testResults:
+                'Verified: Proper semantic structure and ARIA relationships. Title and description automatically connected. Confirmed in DrawerBase.tsx and Drawer.accessibility.test.tsx.',
+        },
+        {
+            id: '1.3.2',
+            level: 'A',
+            title: 'Meaningful Sequence',
+            status: 'compliant',
+            description:
+                'When the sequence in which content is presented affects its meaning, a correct reading sequence can be programmatically determined.',
+            implementation:
+                'DOM order matches visual order: header (title, description) → body content → footer (actions). Drawer structure maintains meaningful sequence for assistive technologies. Content follows logical reading order.',
+            testResults:
+                'Verified: DOM order matches visual order. Logical sequence maintained. Confirmed in Drawer.accessibility.test.tsx.',
+        },
+        {
+            id: '1.3.3',
+            level: 'A',
+            title: 'Sensory Characteristics',
+            status: 'compliant',
+            description:
+                'Instructions provided for understanding and operating content do not rely solely on sensory characteristics.',
+            implementation:
+                'Information is conveyed through text and ARIA attributes, not solely by visual cues like color or position. Drawer trigger has accessible name. Close button has aria-label. All interactive elements have text labels or aria-label.',
+            testResults:
+                'Verified: Not dependent on sensory characteristics. Text labels and ARIA attributes provide sufficient context. Confirmed in Drawer.accessibility.test.tsx.',
+        },
+        {
+            id: '1.3.4',
+            level: 'AAA',
+            title: 'Orientation',
+            status: 'compliant',
+            description:
+                'Content does not restrict its view and operation to a single display orientation.',
+            implementation:
+                'The Drawer component is designed to be responsive and adapts to different screen orientations without loss of information or functionality. It supports multiple directions (top, bottom, left, right) and uses responsive design patterns which inherently support various layouts.',
+            testResults:
+                'Verified: Component adapts to different orientations. Works in both portrait and landscape. Confirmed in Storybook visual tests and responsive design implementation.',
+        },
+        {
+            id: '1.4.3',
+            level: 'AA',
+            title: 'Contrast (Minimum)',
+            status: 'unsure',
+            description:
+                'The visual presentation of text and images of text has a contrast ratio of at least 4.5:1.',
+            implementation:
+                'Text and background colors are chosen from the design system tokens, which aim for WCAG AA contrast ratios. However, specific combinations need to be verified with final rendered colors.',
+            testResults:
+                'Verification Required: Manual check of all color combinations in rendered output using contrast checker tools.',
+            notes: 'Designed for AA (4.5:1). AAA (7:1) is not met by default.',
+        },
+        {
+            id: '1.4.4',
+            level: 'AA',
+            title: 'Resize Text',
+            status: 'compliant',
+            description:
+                'Text can be resized without loss of content or functionality, up to 200 percent.',
+            implementation:
+                'Drawer uses relative units and responsive design. Text scales properly with browser zoom. Content remains accessible and functional at 200% zoom. Drawer adapts to content size changes.',
+            testResults:
+                'Verified: Text resizes without loss of functionality. Tested up to 200% zoom. Confirmed in browser zoom testing.',
+        },
+        {
+            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:
+                'Drawer text and backgrounds are designed for AA contrast (4.5:1 per WCAG 1.4.3), reused from theme tokens.',
+            testResults:
+                'NON-COMPLIANT: Current design targets AA standard (4.5:1). To achieve AAA compliance, contrast ratio must be 7:1 for normal text. VERIFICATION REQUIRED: Manual contrast ratio calculation using WebAIM Contrast Checker.',
+            notes: 'For AAA compliance, text and background colors need to be adjusted to meet 7:1 contrast ratio.',
+        },
+        {
+            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:
+                'Drawer trigger is keyboard accessible. Drawer can be opened with Enter/Space on trigger. Drawer can be closed with Escape key. All interactive elements within drawer are keyboard accessible (Tab, Shift+Tab, Enter, Space). Focus management ensures keyboard navigation works correctly.',
+            testResults:
+                'COMPLIANT: All functionality keyboard accessible. Verified in Drawer.accessibility.test.tsx with comprehensive keyboard navigation tests.',
+        },
+        {
+            id: '2.1.2',
+            level: 'A',
+            title: 'No Keyboard Trap',
+            status: 'compliant',
+            description:
+                'If keyboard focus can be moved to a component of the page using a keyboard interface, then focus can be moved away from that component using only a keyboard interface, and if it requires more than unmodified arrow or tab keys or other standard exit methods, the user is advised of the method to move focus away.',
+            implementation:
+                'Focus is trapped within drawer when open (intentional for modal behavior). Focus can be moved away by closing drawer (Escape key, close button, backdrop click). Focus returns to trigger when drawer closes. No keyboard trap issues.',
+            testResults:
+                'COMPLIANT: Focus trap is intentional and user can exit via Escape or close button. Focus returns to trigger. Verified in Drawer.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:
+                'All drawer functionality is keyboard accessible without exception. No mouse-only interactions. All features work with keyboard only.',
+            testResults:
+                'COMPLIANT: All functionality keyboard accessible without exception. Verified in Drawer.accessibility.test.tsx.',
+        },
+        {
+            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:
+                'Tab order follows DOM order: trigger → drawer content (header → body → footer). Logical focus order maintained. Focus trap ensures focus stays within drawer when open.',
+            testResults:
+                'COMPLIANT: Logical focus order maintained. Verified in Drawer.accessibility.test.tsx.',
+        },
+        {
+            id: '2.4.6',
+            level: 'AA',
+            title: 'Headings and Labels',
+            status: 'compliant',
+            description: 'Headings and labels describe topic or purpose.',
+            implementation:
+                'DrawerTitle provides clear heading. DrawerDescription provides context. All interactive elements have descriptive labels (text or aria-label). Buttons have accessible names.',
+            testResults:
+                'COMPLIANT: Headings and labels are descriptive. Verified in Drawer.accessibility.test.tsx.',
+        },
+        {
+            id: '2.4.7',
+            level: 'AA',
+            title: 'Focus Visible',
+            status: 'compliant',
+            description:
+                'Any keyboard operable user interface has a mode of operation where the keyboard focus indicator is visible.',
+            implementation:
+                'All focusable elements have visible focus indicators. Focus rings are provided by the design system. Focus is clearly visible during keyboard navigation.',
+            testResults:
+                'COMPLIANT: Focus indicators are visible. Verified in Drawer.accessibility.test.tsx and Chromatic visual regression tests.',
+        },
+        {
+            id: '2.5.8',
+            level: 'AA',
+            title: 'Target Size (Minimum)',
+            status: 'compliant',
+            description:
+                'Targets have an area of at least 24 by 24 CSS pixels, except where the target is available through an equivalent link or control on the same page that is at least 24 by 24 CSS pixels.',
+            implementation:
+                'All interactive elements meet minimum touch target size of 24x24px. Buttons and interactive controls are sized appropriately. Drag handle is decorative and not an interactive target.',
+            testResults:
+                'COMPLIANT: Interactive elements meet minimum size requirements. Verified in Drawer.accessibility.test.tsx.',
+        },
+        {
+            id: '3.2.1',
+            level: 'A',
+            title: 'On Focus',
+            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:
+                'Focusing elements within drawer does not cause unexpected context changes. Drawer opening is user-initiated. No automatic form submission or navigation.',
+            testResults:
+                'COMPLIANT: Focus does not cause unexpected context changes.',
+        },
+        {
+            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:
+                'Interacting with drawer elements does not cause unexpected context changes. Drawer closing is user-initiated (Escape, close button, backdrop click). No automatic form submission or navigation.',
+            testResults:
+                'COMPLIANT: Input does not cause unexpected context changes.',
+        },
+        {
+            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:
+                'Drawer opening/closing is initiated by user action (button click, Escape key, close button, backdrop click). No automatic context changes. Drawer state changes only on user request.',
+            testResults:
+                'COMPLIANT: All context changes are user-initiated. Drawer behavior is predictable and user-controlled. Verified in Drawer.accessibility.test.tsx.',
+        },
+        {
+            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 programmatically; and notification of changes to these items is available to user agents, including assistive technologies.',
+            implementation:
+                'Drawer has role="dialog" and aria-modal="true". DrawerTitle provides accessible name via aria-labelledby. DrawerDescription provides description via aria-describedby when present. Close button has aria-label. Trigger button has accessible name. States (open/closed) are programmatically determinable. Screen reader announcements provided for state changes.',
+            testResults:
+                'COMPLIANT: Proper role, name, and value. ARIA relationships established. States programmatically determinable. Verified in Drawer.accessibility.test.tsx.',
+        },
+    ],
+    strengths: [
+        'Proper ARIA attributes (role="dialog", aria-modal="true", aria-labelledby, aria-describedby)',
+        'Automatic ID generation and ARIA attribute wiring for DrawerTitle and DrawerDescription',
+        'Focus management: focus trap when open, focus return when closed',
+        'Full keyboard accessibility (Tab, Shift+Tab, Escape, Enter, Space)',
+        'Screen reader support with proper role and labeling',
+        'Screen reader announcements for state changes',
+        'Support for multiple directions (top, bottom, left, right) with maintained accessibility',
+        'Proper handling of decorative elements (drag handle) with aria-hidden',
+        'Responsive design adapts to different screen sizes and orientations',
+        'Portal rendering ensures proper DOM hierarchy',
+        'Backdrop click to close (configurable)',
+        'Escape key to close',
+        'Action buttons with clear labels',
+        'Semantic HTML structure (header, body, footer)',
+        'Accessible trigger and close buttons',
+    ],
+    recommendations: [
+        'Verify color contrast ratios using WebAIM Contrast Checker for all drawer text/background combinations',
+        'For AAA compliance, adjust text colors to meet 7:1 contrast ratio requirement',
+        'Ensure all interactive elements meet minimum touch target size (24x24px for AA, 44x44px for AAA)',
+        'Test with multiple screen readers (VoiceOver, NVDA, JAWS) to verify announcements',
+        'Consider adding aria-live regions for dynamic drawer content updates',
+        'Document drawer best practices for content authors (clear titles, concise descriptions)',
+        'Test drawer behavior with different directions (top, bottom, left, right) in various screen sizes',
+    ],
+    wcagVersions: {
+        '2.0': [
+            '1.1.1',
+            '1.3.1',
+            '1.3.2',
+            '1.3.3',
+            '1.4.3',
+            '1.4.6',
+            '2.1.1',
+            '2.1.2',
+            '2.4.3',
+            '2.4.6',
+            '2.4.7',
+            '3.2.1',
+            '3.2.2',
+            '4.1.2',
+        ],
+        '2.1': ['1.3.4', '2.1.3', '2.5.8', '3.2.5'],
+        '2.2': [],
+    },
+    testMethodology: {
+        automated: [
+            'jest-axe for automated accessibility violation detection',
+            'Drawer.accessibility.test.tsx with 24 comprehensive test cases',
+            'Storybook a11y addon for interactive accessibility checks',
+            'Chromatic visual regression testing for drawer states',
+        ],
+        manual: [
+            'Keyboard navigation testing (Tab, Shift+Tab, Escape)',
+            'Screen reader testing with VoiceOver (macOS) and NVDA (Windows)',
+            'Color contrast verification using WebAIM Contrast Checker',
+            'Focus indicator visibility testing',
+            'Focus trap verification',
+            'Focus return verification',
+            'Touch target size measurement using browser DevTools',
+            'Zoom testing up to 200%',
+            'Orientation testing (portrait/landscape)',
+            'Testing with different drawer directions (top, bottom, left, right)',
+        ],
+        verificationTools: [
+            'WebAIM Contrast Checker',
+            'axe DevTools',
+            'WAVE (Web Accessibility Evaluation Tool)',
+            'Lighthouse accessibility audit',
+            'Browser DevTools accessibility panel',
+        ],
+        wcagLevels: {
+            A: [
+                '1.1.1 Non-text Content',
+                '1.3.1 Info and Relationships',
+                '1.3.2 Meaningful Sequence',
+                '1.3.3 Sensory Characteristics',
+                '2.1.1 Keyboard',
+                '2.1.2 No Keyboard Trap',
+                '2.4.3 Focus Order',
+                '3.2.1 On Focus',
+                '3.2.2 On Input',
+                '4.1.2 Name, Role, Value',
+            ],
+            AA: [
+                '1.3.4 Orientation',
+                '1.4.3 Contrast (Minimum)',
+                '1.4.4 Resize Text',
+                '2.4.6 Headings and Labels',
+                '2.4.7 Focus Visible',
+                '2.5.8 Target Size (Minimum)',
+            ],
+            AAA: [
+                '1.4.6 Contrast (Enhanced)',
+                '2.1.3 Keyboard (No Exception)',
+                '3.2.5 Change on Request',
+            ],
+        },
+    },
+    accessibilityBestPractices: {
+        'Interactive controls are keyboard focusable': {
+            status: 'compliant',
+            implementation:
+                'All interactive elements (trigger, close button, action buttons) are keyboard focusable using Tab and Shift+Tab. All elements within drawer are keyboard accessible.',
+            verification:
+                'Verified: All interactive elements are keyboard focusable. Tested in Drawer.accessibility.test.tsx.',
+        },
+        'Interactive elements indicate their purpose and state': {
+            status: 'compliant',
+            implementation:
+                'Drawer has role="dialog" with aria-modal="true" indicating its purpose. DrawerTitle provides accessible name via aria-labelledby. DrawerDescription provides context via aria-describedby. Close button has aria-label. Trigger button has accessible name.',
+            verification:
+                'Verified: All interactive elements have proper roles and labels. Drawer properly labeled. Tested in Drawer.accessibility.test.tsx.',
+        },
+        'The page has a logical tab order': {
+            status: 'compliant',
+            implementation:
+                'Tab order follows DOM order: trigger → drawer content (header → body → footer). Focus trap ensures focus stays within drawer when open.',
+            verification:
+                'Verified: Tab order follows DOM order. Focus trap works correctly. Tested in Drawer.accessibility.test.tsx.',
+        },
+        'Visual order on the page follows DOM order': {
+            status: 'compliant',
+            implementation:
+                'Visual order matches DOM order. Drawer structure: header → body → footer. Content flows logically.',
+            verification:
+                'Verified: Visual order matches DOM order. Confirmed in Drawer.accessibility.test.tsx.',
+        },
+        'Focus is managed appropriately': {
+            status: 'compliant',
+            implementation:
+                'Focus is trapped within drawer when open. Focus returns to trigger when drawer closes. Focus management handled by Vaul library with proper ARIA attributes.',
+            verification:
+                'Verified: Focus trap works correctly. Focus returns to trigger. Tested in Drawer.accessibility.test.tsx.',
+        },
+        'Screen reader announcements are provided': {
+            status: 'compliant',
+            implementation:
+                'Screen reader announcements provided when drawer opens. DrawerTitle and DrawerDescription are announced via aria-labelledby and aria-describedby. State changes are announced.',
+            verification:
+                'Verified: Screen reader announcements work correctly. Tested with VoiceOver and NVDA.',
+        },
+    },
+}

package/lib/components/Drawer/components/Drawer.css

@@ -0,0 +1,21 @@
+[data-vaul-drawer][data-vaul-drawer-direction='bottom']::after {
+    display: none;
+}
+
+.drawer-content > .drawer-body:last-child {
+    border-bottom-left-radius: inherit;
+    border-bottom-right-radius: inherit;
+}
+
+[data-vaul-drawer-direction='top'] .drawer-content > .drawer-body:last-child {
+    border-top-left-radius: inherit;
+    border-top-right-radius: inherit;
+}
+
+[data-vaul-drawer-direction='left'] .drawer-content > .drawer-body:last-child {
+    border-bottom-left-radius: inherit;
+}
+
+[data-vaul-drawer-direction='right'] .drawer-content > .drawer-body:last-child {
+    border-bottom-right-radius: inherit;
+}