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

package/lib/components/Popover/accessibility/PopoverAccessibilityReport.ts

@@ -0,0 +1,353 @@
+/**
+ * Popover 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 popoverAccessibilityReport: AccessibilityReport = {
+    componentName: 'Popover',
+    wcagVersion: '2.2',
+    reportDate: new Date().toISOString().split('T')[0],
+    conformanceLevel: 'Level AA',
+    overallStatus: 'partial',
+    summary:
+        'The Popover component demonstrates strong compliance with WCAG 2.0, 2.1, and 2.2 standards at Level A and AA. The component provides comprehensive accessibility features including proper ARIA attributes (role="dialog" when modal, aria-labelledby, aria-describedby), keyboard navigation (Tab, Shift+Tab, Escape), focus management (focus trap in modal mode, focus return), and screen reader support. Popover content is properly labeled, focus is trapped within the popover when in modal mode, and focus returns to the trigger element when closed. Decorative icons and close buttons are properly accessible. The component supports both non-modal (default) and modal modes, with appropriate ARIA attributes for each. Mobile support is provided via MobilePopover (Drawer) component. 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: 1.4.8 Visual Presentation, 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, text and background colors need to be adjusted to meet 7:1 contrast ratio (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. Decorative icons must be marked as such.',
+            implementation:
+                'Close button icon has aria-label="Close popover". Popover heading and description provide accessible text content. Decorative elements are properly hidden. Confirmed in Popover.tsx, PopoverHeader.tsx, and MobilePopover.tsx.',
+            testResults:
+                'Verified: Close button has accessible label. Popover text content provides accessible alternatives. Implementation confirmed in Popover.tsx and Popover.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:
+                'Popover has role="dialog" when asModal={true}. Heading is linked via aria-labelledby. Description is linked via aria-describedby when present. Popover structure maintains logical relationships. Confirmed in Popover.tsx.',
+            testResults:
+                'Verified: Proper semantic structure and ARIA relationships. Role assignment and heading/description relationships confirmed in Popover.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:
+                'Popover content follows logical reading order: header (heading, description, close button) → body content → footer (actions). DOM order matches visual order. Confirmed in Popover.tsx.',
+            testResults:
+                'Verified: Logical sequence maintained in component implementation.',
+        },
+        {
+            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:
+                'Popover functionality does not rely solely on shape, size, or visual location. Text labels provide context. Close button has aria-label. Action buttons have text labels.',
+            testResults: 'Verified: Not dependent on sensory characteristics.',
+        },
+        {
+            id: '1.3.4',
+            level: 'AA',
+            title: 'Orientation',
+            status: 'compliant',
+            description:
+                'Content does not restrict its view and operation to a single display orientation.',
+            implementation:
+                'Popover works in both portrait and landscape orientations. MobilePopover provides drawer-style popover for mobile devices. Responsive design adapts to different screen sizes and orientations.',
+            testResults: 'Verified: Component functions in all orientations.',
+        },
+        {
+            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:
+                'Popover text uses theme colors. Heading, description, and body text colors vary. Background colors from popover tokens. Contrast ratios should be verified using actual color values from theme tokens.',
+            testResults:
+                'UNSURE: Requires manual contrast ratio calculation. Popover text and background color combinations should be verified using WebAIM Contrast Checker or similar tool. VERIFICATION REQUIRED.',
+            notes: 'Contrast ratios must be verified using tools like WebAIM Contrast Checker. 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:
+                'Popover text and backgrounds are designed for AA contrast (4.5:1 per WCAG 1.4.3), reused from theme 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 colors need to be adjusted to provide higher contrast ratios.',
+            notes: 'This is a Level AAA criterion per WCAG 1.4.6. Current implementation 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:
+                'Popover respects browser/system text size settings. Text uses relative units via tokens. Layout uses flexbox, allowing text to scale up to 200% without loss of functionality. Popover content scrolls appropriately at all zoom levels.',
+            testResults:
+                'COMPLIANT: Popover text scales properly with browser zoom up to 200%. Layout remains functional at all zoom levels. Popover content scrolls correctly. Verified through manual resizing.',
+        },
+        {
+            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:
+                'Popover is fully keyboard accessible. Tab/Shift+Tab navigation within popover. Escape key closes popover. Enter/Space activate buttons. Focus is trapped within popover when asModal={true}. All functionality available via keyboard. Confirmed in Popover.tsx.',
+            testResults:
+                'COMPLIANT: Full keyboard operability. Tab, Shift+Tab, Escape, Enter, Space keys all work correctly. No timing requirements. Verified in Popover.accessibility.test.tsx.',
+        },
+        {
+            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.',
+            implementation:
+                'Focus is trapped within popover when asModal={true} (intentional). Escape key or action buttons allow closing popover and returning focus. Focus returns to trigger element when popover closes. No permanent keyboard trap. Confirmed in Popover.tsx.',
+            testResults:
+                'COMPLIANT: Focus trap is intentional when modal mode is enabled and can be escaped via Escape key or action buttons. Focus returns to trigger when popover closes.',
+        },
+        {
+            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 popover functionality is fully keyboard accessible without timing requirements. Tab navigation, Escape key, Enter, Space all work without timing constraints. No mouse-dependent functionality. Confirmed in Popover.tsx.',
+            testResults:
+                'COMPLIANT: Full keyboard operability without exceptions. Tab, Shift+Tab, Escape, Enter, Space keys all work correctly. No timing requirements. No mouse-only functionality.',
+            notes: 'This is Level AAA enhancement of WCAG 2.1.1. The Popover component already meets this requirement as all functionality is keyboard accessible without timing constraints.',
+        },
+        {
+            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:
+                'Focus moves to first focusable element when popover opens (in modal mode). Focus order within popover is logical: close button → content → action buttons. Focus wraps from last to first element on Tab, and from first to last on Shift+Tab. Confirmed in Popover.tsx.',
+            testResults:
+                'COMPLIANT: Logical focus order maintained. Focus moves to first element on open (modal mode), wraps correctly. Verified in Popover.accessibility.test.tsx.',
+        },
+        {
+            id: '2.4.6',
+            level: 'AA',
+            title: 'Headings and Labels',
+            status: 'compliant',
+            description: 'Headings and labels describe topic or purpose.',
+            implementation:
+                'Popover heading clearly describes the popover purpose. Action buttons have clear text labels. Close button has aria-label="Close popover".',
+            testResults:
+                'Verified: Popover heading and labels clearly describe purpose.',
+        },
+        {
+            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 within popover have visible focus indicators. Focus indicators provided by browser default or custom styles. Focus remains visible during keyboard navigation.',
+            testResults:
+                'COMPLIANT: Focus indicators are visible on all focusable elements. Verified in Popover.accessibility.test.tsx.',
+        },
+        {
+            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:
+                'Close button meets 24x24px minimum. Action buttons meet minimum size requirements. All interactive elements within popover meet Level AA requirement.',
+            testResults:
+                'COMPLIANT: All interactive elements meet Level AA requirement (24x24px minimum per WCAG 2.5.8). Verified in Popover.accessibility.test.tsx.',
+            notes: 'This is a Level AA criterion per WCAG 2.5.8. For AAA compliance (WCAG 2.5.5), target size must be 44x44px minimum.',
+        },
+        {
+            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 popover does not cause unexpected context changes. Popover opening is user-initiated. No automatic form submission or navigation. Confirmed in Popover.tsx.',
+            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 popover elements does not cause unexpected context changes. Popover closing is user-initiated (Escape, action buttons, outside click when not modal). No automatic form submission or navigation. Confirmed in Popover.tsx.',
+            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:
+                'Popover opening/closing is initiated by user action (button click, Escape key, action buttons, outside click when not modal). No automatic context changes. Confirmed in Popover.tsx.',
+            testResults:
+                'COMPLIANT: All context changes are user-initiated. Popover behavior is predictable and user-controlled.',
+        },
+        {
+            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:
+                'Popover has role="dialog" when asModal={true}. Heading provides accessible name via aria-labelledby. Description provides description via aria-describedby when present. Close button has aria-label. Action buttons have accessible names via text. States (open/closed) are programmatically determinable. Confirmed in Popover.tsx.',
+            testResults:
+                'COMPLIANT: Proper role, name, and value. ARIA relationships established. States programmatically determinable.',
+        },
+    ],
+    strengths: [
+        'Proper ARIA attributes (role="dialog" when modal, aria-labelledby, aria-describedby)',
+        'Focus management: focus trap when modal mode enabled, focus return when closed',
+        'Full keyboard accessibility (Tab, Shift+Tab, Escape, Enter, Space)',
+        'Screen reader support with proper role and labeling',
+        'Focus wraps correctly from last to first and first to last (in modal mode)',
+        'Proper handling of close button with aria-label',
+        'Mobile support with MobilePopover drawer-style component',
+        'Flexible positioning (top, right, bottom, left)',
+        'Works in all orientations',
+        'Text scales properly with browser zoom',
+        'Portal rendering ensures proper DOM hierarchy',
+        'Escape key to close',
+        'Action buttons with clear labels',
+        'Support for both modal and non-modal modes',
+        'Collision detection and automatic repositioning',
+    ],
+    recommendations: [
+        'Verify color contrast ratios using WebAIM Contrast Checker for all popover 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 popover content updates',
+        'Document popover best practices for content authors (clear headings, concise content)',
+        'Consider adding focus trap configuration options for advanced use cases',
+        'Verify that aria-controls references are properly handled (Radix Popover manages this automatically)',
+    ],
+    wcagVersions: {
+        '2.0': [
+            '1.1.1',
+            '1.3.1',
+            '1.3.2',
+            '1.3.3',
+            '1.4.3',
+            '1.4.6',
+            '1.4.8',
+            '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',
+            'Popover.accessibility.test.tsx with 40+ comprehensive test cases',
+            'Storybook a11y addon for interactive accessibility checks',
+            'Chromatic visual regression testing for popover 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 (in modal mode)',
+            'Focus return verification',
+            'Touch target size measurement using browser DevTools',
+            'Zoom testing up to 200%',
+            'Orientation testing (portrait/landscape)',
+            'Mobile device testing with MobilePopover',
+            'Positioning and collision detection testing',
+        ],
+        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)',
+                '2.4.6 Headings and Labels',
+                '2.4.7 Focus Visible',
+                '2.5.8 Target Size (Minimum)',
+            ],
+            AAA: [
+                '1.4.6 Contrast (Enhanced)',
+                '1.4.8 Visual Presentation',
+                '2.1.3 Keyboard (No Exception)',
+                '3.2.5 Change on Request',
+            ],
+        },
+    },
+}

package/lib/components/Popover/index.ts

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

package/lib/components/Popover/popover.animations.ts

@@ -0,0 +1,125 @@
+import { css } from 'styled-components'
+
+const easing = 'cubic-bezier(0.16, 1, 0.3, 1)'
+
+export const popoverContentAnimations = css`
+    transform-origin: var(--radix-popper-transform-origin);
+    will-change: opacity, transform;
+
+    &[data-side='bottom'][data-state='open'] {
+        animation: slideInFromTop 400ms ${easing};
+    }
+    &[data-side='bottom'][data-state='closed'] {
+        animation: slideOutToTop 300ms ${easing};
+    }
+
+    &[data-side='top'][data-state='open'] {
+        animation: slideInFromBottom 400ms ${easing};
+    }
+    &[data-side='top'][data-state='closed'] {
+        animation: slideOutToBottom 300ms ${easing};
+    }
+
+    &[data-side='right'][data-state='open'] {
+        animation: slideInFromLeft 400ms ${easing};
+    }
+    &[data-side='right'][data-state='closed'] {
+        animation: slideOutToLeft 300ms ${easing};
+    }
+
+    &[data-side='left'][data-state='open'] {
+        animation: slideInFromRight 400ms ${easing};
+    }
+    &[data-side='left'][data-state='closed'] {
+        animation: slideOutToRight 300ms ${easing};
+    }
+
+    /* Shadcn-style keyframes with zoom + slide + fade */
+    @keyframes slideInFromTop {
+        from {
+            opacity: 0;
+            transform: translateY(-8px) scale(0.95);
+        }
+        to {
+            opacity: 1;
+            transform: translateY(0) scale(1);
+        }
+    }
+
+    @keyframes slideOutToTop {
+        from {
+            opacity: 1;
+            transform: translateY(0) scale(1);
+        }
+        to {
+            opacity: 0;
+            transform: translateY(-8px) scale(0.95);
+        }
+    }
+
+    @keyframes slideInFromBottom {
+        from {
+            opacity: 0;
+            transform: translateY(8px) scale(0.95);
+        }
+        to {
+            opacity: 1;
+            transform: translateY(0) scale(1);
+        }
+    }
+
+    @keyframes slideOutToBottom {
+        from {
+            opacity: 1;
+            transform: translateY(0) scale(1);
+        }
+        to {
+            opacity: 0;
+            transform: translateY(8px) scale(0.95);
+        }
+    }
+
+    @keyframes slideInFromLeft {
+        from {
+            opacity: 0;
+            transform: translateX(-8px) scale(0.95);
+        }
+        to {
+            opacity: 1;
+            transform: translateX(0) scale(1);
+        }
+    }
+
+    @keyframes slideOutToLeft {
+        from {
+            opacity: 1;
+            transform: translateX(0) scale(1);
+        }
+        to {
+            opacity: 0;
+            transform: translateX(-8px) scale(0.95);
+        }
+    }
+
+    @keyframes slideInFromRight {
+        from {
+            opacity: 0;
+            transform: translateX(8px) scale(0.95);
+        }
+        to {
+            opacity: 1;
+            transform: translateX(0) scale(1);
+        }
+    }
+
+    @keyframes slideOutToRight {
+        from {
+            opacity: 1;
+            transform: translateX(0) scale(1);
+        }
+        to {
+            opacity: 0;
+            transform: translateX(8px) scale(0.95);
+        }
+    }
+`