Merge pull request #2899 from innovaccer/develop

Develop

Author: anuradha9712

.cursor/rules/wcag-a11y-audit-report.mdc

@@ -1,7 +1,6 @@
 ---
 alwaysApply: true
 ---
-
 Use these sources as the primary references:
 - [a11y-context/wcag-as-json.json](mdc:a11y-context/wcag-as-json.json) for the full WCAG 2.2 success criteria set.
 - [wcag-audit-patterns.md](mdc:.cursor/rules/wcag-audit-patterns.md) for audit methodology.

.vscode/settings.json

@@ -6,6 +6,6 @@
     "typescriptreact",
   ],
   "editor.codeActionsOnSave": {
-    "source.fixAll.eslint": true,
+    "source.fixAll.eslint": "explicit"
   },
 }

CLAUDE.md

@@ -0,0 +1,186 @@
+# AGENTS
+
+This file defines the working conventions for `design-system`.
+Follow these instructions for every pull request.
+
+---
+
+## Environment & Tooling
+- **Node/NPM:** Node ≥20.15.0 and npm ≥10.7.0.
+- **Dependency manager:** Use `npm` with the committed `package-lock.json`.
+
+---
+
+## Design Tokens (MANDATORY)
+Design tokens are the source of truth for colors, spacing, radius, elevation, etc.
+
+- **Token sources:**
+  - Raw tokens: `css/src/tokens/index.css`
+  - Token mappings & variables: `css/src/variables/index.css`
+- **Usage:**
+  - Reference tokens through CSS variables (e.g., `var(--primary)`, `var(--border-radius-10)`, `var(--shadow-m)`) & only use tokens defined in `css/src/variables/index.css` files as css variables.
+  - Do not hard-code hex values, pixel sizes, or box-shadow rules outside the token files.
+  - Add or modify tokens only within the token files.
+
+---
+
+## Design System Components (MANDATORY)
+Always use existing design system components before creating new ones or using native HTML elements.
+
+- **Component library:** `core/components/`
+- **Available atoms:** Avatar, AvatarGroup, Badge, Breadcrumbs, Button, Caption, Card, Checkbox, Chip, ChipGroup, Divider, Dropdown, Flex, Heading, HelpText, Icon, Input, Label, Legend, Link, LinkButton, Message, Meter, Paragraph, Pills, ProgressBar, ProgressRing, Radio, Row, Column, SegmentedControl, Slider, Spinner, StatusHint, Subheading, SwitchInput, Text, Textarea, Toast, and more.
+- **Available molecules:** Chat, ChatMessage, ChipInput, Dialog, Dropzone, EditableChipInput, EditableDropdown, EditableInput, EmptyState, FileList, FileUploader, FullscreenModal, InputMask, KeyValuePair, Modal, Pagination, Placeholder, Popover, Sidesheet, Stepper, Tabs, Tooltip, VerificationCodeInput, and more.
+- **Available organisms:** Calendar, ChoiceList, Combobox, DatePicker, DateRangePicker, Grid, HorizontalNav, InlineMessage, List, Listbox, Menu, Navigation, PageHeader, Select, Table, TextField, TimePicker, VerticalNav, and more.
+- **Rules:**
+  - Import from the component's `index.tsx` (e.g., `import { Button } from '@/core/components/atoms/button'`).
+  - Extend existing components via props rather than wrapping with custom HTML.
+  - Do not replicate functionality already covered by an existing component.
+  - When a component doesn't exist yet, follow the component layout structure below and build it from atomic components upward.
+
+---
+
+## Code Style & Structure
+- **Languages:** TypeScript & React only.
+- **File naming:** PascalCase for component files; use `.tsx` for components.
+- **Component layout:**
+  ````
+
+  core/
+    ├── index.tsx                        # Export Components
+    ├── index.type.tsx                   # Export Components Props/Types
+    ├── components/{atoms|molecules|organisms}/ComponentName/
+          	├── index.tsx                 # Component Main entry file
+           ├── {ComponentName}.tsx       # Component Implementation
+           ├── __tests__/                # Component Unit Tests
+           ├── __stories__/              # Storybook stories
+
+  ````
+- **Types:** Props interfaces named `[ComponentName]Props` extending `BaseProps`. Capitalize type aliases (e.g., `Appearance`, `Size`).
+- **Exports:** Named export of components from `index.tsx`; export props from `index.type.tsx`.
+- **Testing:** Jest & React Testing Library is used for unit testing and coverage.
+- Snapshots and unit tests are written in [COMPONENT_NAME].test.tsx file inside the __tests__ folder.
+
+---
+
+## Styling
+- CSS Module has been used to define the class names.
+- Create a CSS file inside **css** directory with the file extension `module.css` (e.g avatar.module.css)
+- Use **ClassNames**, a utility for conditionally joining CSS classNames together.
+- Follow the **BEM Convention** & use CSS Modules for naming CSS classes.
+
+---
+
+## Quality Checks (run before committing)
+1. `npm run lint:check` – ESLint for TS/JS.
+2. `npm run prettier:check` – Prettier for CSS.
+3. `npm run lint:types` – TypeScript type check.
+4. `npm test` – Jest unit tests (update tests alongside source changes).
+
+---
+
+## Commit & Branch Conventions
+- **Conventional Commits:** `type(component): message`
+  - Valid types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`
+- Keep commits focused; prefer a single commit per PR.
+- Branch names should reflect the work (e.g., `feat-button`, `fix-modal-height`).
+
+---
+
+## Documentation & Stories
+- Update or add Storybook stories for any visual or API change.
+- Update Markdown docs in `docs/` when behavior or usage changes.
+- Add/modify Figma files in `figma/` and connect via `figma-code-connect` for new components.
+
+---
+
+## Accessibility (WCAG 2.2 AA — MANDATORY)
+All components must meet WCAG 2.2 AA. Treat WCAG as a hard requirement, not a guideline.
+
+### A11y References
+- Audit process: `.cursor/rules/wcag-a11y-audit-report.mdc`
+- Audit patterns: `.cursor/rules/wcag-audit-patterns.md`
+- Guidelines: `.cursor/rules/vercel-a11y-guidelines.mdc`, `.cursor/rules/web-interface-a11y-guidelines.mdc`
+- WCAG source data: `a11y-context/wcag-as-json.json`
+
+### Semantic HTML & ARIA
+- MUST: Use native semantics (`<button>`, `<a>`, `<label>`, `<table>`) before ARIA.
+- MUST: `<button>` for actions; `<a>`/`<Link>` for navigation — never `<div onClick>`.
+- MUST: Icon-only buttons must have a descriptive `aria-label`.
+- MUST: Decorative icons/images must have `aria-hidden="true"` / `alt=""`.
+- MUST: All images need `alt` text (empty string if purely decorative).
+- MUST: Custom widgets must have correct ARIA roles, states, and properties (`aria-expanded`, `aria-checked`, `aria-selected`, etc.).
+- MUST: Form inputs need `<label>` (via `htmlFor`) or `aria-label`/`aria-labelledby`.
+- MUST: Status/error messages use `role="alert"` or `aria-live="polite"` as appropriate.
+- MUST: No duplicate `id` attributes in the DOM.
+
+### Keyboard Navigation
+- MUST: All interactive elements are fully keyboard accessible.
+- MUST: Keyboard interactions follow [WAI-ARIA APG patterns](https://www.w3.org/WAI/ARIA/apg/patterns/).
+- MUST: No keyboard traps (unless intentional modal trapping per APG).
+- MUST: Focus is managed correctly — trap in modals, return focus on close.
+- MUST: Tab order is logical and matches visual order.
+
+### Focus Visibility
+- MUST: Visible focus ring on all interactive elements using `:focus-visible`.
+- NEVER: `outline: none` / `outline-none` without a visible focus replacement.
+- MUST: Focus indicators meet 3:1 contrast ratio against adjacent colors.
+- MUST: Focused elements are not obscured by sticky headers or overlays (WCAG 2.4.11).
+
+### Color & Contrast
+- MUST: Text contrast ≥ 4.5:1 (normal); ≥ 3:1 (large text ≥18pt or 14pt bold).
+- MUST: UI component boundaries and icons ≥ 3:1 contrast ratio.
+- MUST: Color is never the only means of conveying information (use icons, text, or patterns as redundant cues).
+- MUST: Error states use more than color alone.
+
+### Touch & Target Size
+- MUST: Interactive hit targets ≥ 24×24 px (mobile ≥ 44×44 px); expand hit area with padding if visual size is smaller.
+- MUST: `touch-action: manipulation` to prevent double-tap zoom delay.
+- MUST: No dead zones on checkboxes/radios — label and control share one hit target.
+
+### Motion & Animation
+- MUST: Honor `prefers-reduced-motion` — provide reduced variant or disable animation entirely.
+- MUST: Animate only compositor-friendly properties (`transform`, `opacity`).
+- NEVER: `transition: all` — list properties explicitly.
+- MUST: Animations are interruptible and respond to user input.
+
+### Content Handling
+- MUST: Text containers handle long content (`truncate`, `line-clamp`, `break-words`).
+- MUST: Flex children need `min-w-0` to allow text truncation.
+- MUST: Handle empty states — no broken UI for empty strings or arrays.
+- MUST: Locale-aware dates/times/numbers (`Intl.DateTimeFormat`, `Intl.NumberFormat`).
+
+### Per-Component Audit (when building or modifying components)
+For each component, validate:
+1. HTML structure and heading hierarchy.
+2. ARIA roles, states, and properties.
+3. Keyboard interactions and event handlers.
+4. Color contrast of all visual states (default, hover, focus, active, disabled, error).
+5. Touch target sizes.
+6. Focus handling (visibility, order, trap/return).
+7. Screen reader announcements for dynamic content.
+8. `prefers-reduced-motion` support for any animations.
+
+### Anti-patterns (always flag and fix)
+- `user-scalable=no` or `maximum-scale=1` disabling zoom.
+- `onPaste` with `preventDefault` blocking paste.
+- `outline: none` without focus-visible replacement.
+- `<div>` or `<span>` with click handlers instead of `<button>`.
+- Icon buttons without `aria-label`.
+- Images without `alt` attribute.
+- Form inputs without associated labels.
+- Hardcoded color values outside token files (contrast cannot be verified programmatically).
+
+### Resolving Lint Warnings
+- Resolve all `jsx-a11y` ESLint warnings before committing.
+- Run `npm run lint:check` and fix every a11y violation reported.
+
+---
+
+## Review & Misc
+- Avoid committing generated artifacts (`dist/`, `.lib/`) or build output.
+- Add yourself to contributors via `all-contributors` when appropriate.
+- PRs should include a clear description, pass all CI checks, and request review when ready.
+
+---
+
+Adhering to these guidelines keeps the design system consistent, accessible, and maintainable.

core/accessibility/utils/__tests__/isSpaceKey.test.tsx

@@ -2,35 +2,43 @@
 import isSpaceKey from '../isSpaceKey';
 
 describe('isSpaceKey', () => {
-  test('returns true if the space key is pressed', () => {
-    // Create a mock React keyboard event with 'Space' as the key
+  test('returns true for space character (modern browsers)', () => {
+    const spaceKeyEvent = {
+      key: ' ',
+    } as React.KeyboardEvent;
+
+    expect(isSpaceKey(spaceKeyEvent)).toBe(true);
+  });
+
+  test('returns true for "Space" key value', () => {
     const spaceKeyEvent = {
       key: 'Space',
     } as React.KeyboardEvent;
 
-    // Assert that isSpaceKey returns true for the space key event
+    expect(isSpaceKey(spaceKeyEvent)).toBe(true);
+  });
+
+  test('returns true for "Spacebar" key value (legacy browsers)', () => {
+    const spaceKeyEvent = {
+      key: 'Spacebar',
+    } as React.KeyboardEvent;
+
     expect(isSpaceKey(spaceKeyEvent)).toBe(true);
   });
 
   test('returns false if any other key is pressed', () => {
-    // Create a mock React keyboard event with a non-space key
     const enterKeyEvent = {
       key: 'Enter',
     } as React.KeyboardEvent;
 
-    // Assert that isSpaceKey returns false for a non-space key event
     expect(isSpaceKey(enterKeyEvent)).toBe(false);
   });
 
   test('returns false if the key is undefined', () => {
-    // Create a mock React keyboard event with an undefined key
     const undefinedKeyEvent = {
       key: undefined,
     } as unknown as React.KeyboardEvent;
 
-    // Assert that isSpaceKey returns false for an undefined key event
     expect(isSpaceKey(undefinedKeyEvent)).toBe(false);
   });
-
-  // Add more test cases if you want to cover more scenarios, such as empty string, null, etc.
 });

core/accessibility/utils/__tests__/useAccessibilityProps.test.tsx

@@ -42,13 +42,31 @@ describe('useAccessibilityProps', () => {
     }
   });
 
-  test('role, tabIndex and aria-label are set correctly', () => {
-    const { getByRole } = render(<TestComponent role="button" tabIndex={-1} aria-label="test label" />);
+  test('role, tabIndex and aria-label are set correctly when onClick is provided', () => {
+    const onClick = jest.fn();
+    const { getByRole } = render(
+      <TestComponent onClick={onClick} role="button" tabIndex={-1} aria-label="test label" />
+    );
     const element = getByRole('button');
     expect(element).toHaveAttribute('tabIndex', '-1');
     expect(element).toHaveAttribute('aria-label', 'test label');
   });
 
+  test('does not add interactive props when onClick is not provided (avoids nested button/link)', () => {
+    const { container } = render(<TestComponent role="button" tabIndex={-1} aria-label="test label" />);
+    const element = container.firstChild as HTMLElement;
+    expect(element).not.toHaveAttribute('role');
+    expect(element).not.toHaveAttribute('tabindex');
+  });
+
+  test('preserves non-interactive ARIA props when onClick is not provided', () => {
+    const { container } = render(<TestComponent aria-label="Message sent" aria-labelledby="id" aria-hidden={true} />);
+    const element = container.firstChild as HTMLElement;
+    expect(element).toHaveAttribute('aria-label', 'Message sent');
+    expect(element).toHaveAttribute('aria-labelledby', 'id');
+    expect(element).toHaveAttribute('aria-hidden', 'true');
+  });
+
   test('No trigger for callback on event of not allowed aria roles', () => {
     const onClick = jest.fn();
     const { getByRole } = render(<TestComponent onClick={onClick} role="tooltip" aria-label="test label" />);

core/accessibility/utils/isSpaceKey.ts

@@ -1,5 +1,5 @@
 import React from 'react';
 
-const isSpaceKey = (e: React.KeyboardEvent) => e.key === 'Space';
+const isSpaceKey = (e: React.KeyboardEvent) => e.key === ' ' || e.key === 'Space' || e.key === 'Spacebar';
 
 export default isSpaceKey;

core/accessibility/utils/useAccessibilityProps.ts

@@ -9,6 +9,9 @@ interface IProps {
   role?: AriaRoleType;
   tabIndex?: number;
   'aria-label'?: React.AriaAttributes['aria-label'];
+  'aria-labelledby'?: React.AriaAttributes['aria-labelledby'];
+  'aria-describedby'?: React.AriaAttributes['aria-describedby'];
+  'aria-hidden'?: React.AriaAttributes['aria-hidden'];
 }
 
 const allowed: Record<string, Set<KeyboardEventKeyType>> = {
@@ -30,28 +33,37 @@ const isKeyboardInteractionAllowed = (role: AriaRoleType, key: KeyboardEventKeyT
 };
 
 const useAccessibilityProps = ({ onClick, onKeyDown, role = 'button', tabIndex, ...rest }: IProps) => {
+  // Only add interactive props when onClick is provided.
+  if (!onClick) {
+    const {
+      'aria-label': ariaLabel,
+      'aria-labelledby': ariaLabelledBy,
+      'aria-describedby': ariaDescribedBy,
+      'aria-hidden': ariaHidden,
+    } = rest;
+    return {
+      ...(ariaLabel != null && { 'aria-label': ariaLabel }),
+      ...(ariaLabelledBy != null && { 'aria-labelledby': ariaLabelledBy }),
+      ...(ariaDescribedBy != null && { 'aria-describedby': ariaDescribedBy }),
+      ...(ariaHidden != null && { 'aria-hidden': ariaHidden }),
+    };
+  }
   return {
-    ...(onClick
-      ? {
-          onClick: onClick,
-          role: role,
-          tabIndex: tabIndex || 0,
-          'aria-label': rest['aria-label'],
-          onKeyDown: (e: React.SyntheticEvent<HTMLElement>) => {
-            if (onKeyDown) {
-              onKeyDown(e as React.KeyboardEvent<HTMLElement>);
-              return;
-            }
-            const key = (e as React.KeyboardEvent<HTMLElement>).key;
-            if (isKeyboardInteractionAllowed(role, key)) {
-              if (onClick) {
-                e.preventDefault();
-                onClick(e as React.MouseEvent<HTMLElement>);
-              }
-            }
-          },
-        }
-      : { role, tabIndex, 'aria-label': rest['aria-label'] }),
+    onClick: onClick,
+    role: role,
+    tabIndex: tabIndex ?? 0,
+    'aria-label': rest['aria-label'],
+    onKeyDown: (e: React.SyntheticEvent<HTMLElement>) => {
+      if (onKeyDown) {
+        onKeyDown(e as React.KeyboardEvent<HTMLElement>);
+        return;
+      }
+      const key = (e as React.KeyboardEvent<HTMLElement>).key;
+      if (isKeyboardInteractionAllowed(role, key)) {
+        e.preventDefault();
+        onClick(e as React.MouseEvent<HTMLElement>);
+      }
+    },
   };
 };
 

core/ai-components/AIResponse/ChatButton.tsx

@@ -1,22 +1,12 @@
 import * as React from 'react';
-import classNames from 'classnames';
 import { ButtonProps } from '@/index.type';
 import { Button } from '@/index';
-import styles from '@css/ai-components/chat.module.css';
 
 type ChatButtonType = Omit<ButtonProps, 'size' | 'largeIcon' | 'appearance'>;
 
 export const ChatButton = (props: ChatButtonType) => {
   const { className, selected, ...rest } = props;
 
-  const chatButtonClassNames = classNames(
-    {
-      [styles['AIResponse-button']]: true,
-      [styles['AIResponse-button--selected']]: selected,
-    },
-    className
-  );
-
   return (
     <Button
       data-test="DesignSystem-AIResponse-Button"
@@ -25,7 +15,7 @@ export const ChatButton = (props: ChatButtonType) => {
       size="tiny"
       largeIcon={true}
       appearance="transparent"
-      className={chatButtonClassNames}
+      className={className}
     />
   );
 };