@juspay/blend-design-system 0.0.37-beta.8 → 0.0.37

package/lib/components/CardV2/CardV2Components.tsx

@@ -0,0 +1,297 @@
+import { useId } from 'react'
+import { useResponsiveTokens } from '../../hooks/useResponsiveTokens'
+import Block from '../Primitives/Block/Block'
+import ButtonV2 from '../ButtonV2/ButtonV2'
+import type { CardV2TokensType } from './cardV2.tokens'
+import { useCardV2Context } from './CardV2Context'
+import {
+    CardV2Orientation,
+    type CardV2ActionsProps,
+    type CardV2BodyProps,
+    type CardV2FooterProps,
+    type CardV2HeaderProps,
+    type CardV2MediaProps,
+    type CardV2MetaProps,
+    type CardV2SectionProps,
+} from './cardV2.types'
+import { renderCardV2Text, toCardV2ActionArray } from './CardV2.utils'
+
+const useCardV2SectionContext = () => {
+    const context = useCardV2Context()
+    const responsiveTokens = useResponsiveTokens<CardV2TokensType>('CARDV2')
+    const fallbackId = useId()
+
+    return {
+        tokens: context?.tokens ?? responsiveTokens,
+        centered: context?.centered ?? false,
+        scrollable: context?.scrollable ?? false,
+        ids: context?.ids ?? {
+            eyebrow: `${fallbackId}-card-eyebrow`,
+            title: `${fallbackId}-card-title`,
+            subtitle: `${fallbackId}-card-subtitle`,
+            description: `${fallbackId}-card-description`,
+        },
+    }
+}
+
+export const CardV2Meta = ({
+    title,
+    truncateTitle,
+    subtitle,
+    eyebrow,
+    centered,
+}: CardV2MetaProps) => {
+    const { tokens, centered: contextCentered, ids } = useCardV2SectionContext()
+    const isCentered = centered ?? contextCentered
+
+    if (!eyebrow && !title && !subtitle) return null
+
+    return (
+        <Block
+            display="flex"
+            flexDirection="column"
+            gap={tokens.header.gap}
+            minWidth={0}
+            alignItems={isCentered ? 'center' : undefined}
+            data-element="card-meta"
+        >
+            {renderCardV2Text({
+                value: eyebrow,
+                id: ids.eyebrow,
+                as: 'p',
+                styles: tokens.header.eyebrow as React.CSSProperties,
+                dataElement: 'card-eyebrow',
+            })}
+            {renderCardV2Text({
+                value: title,
+                id: ids.title,
+                as: 'h2',
+                styles: tokens.header.title as React.CSSProperties,
+                dataElement: 'card-title',
+                truncate: truncateTitle,
+            })}
+            {renderCardV2Text({
+                value: subtitle,
+                id: ids.subtitle,
+                as: 'p',
+                styles: tokens.header.subtitle as React.CSSProperties,
+                dataElement: 'card-subtitle',
+            })}
+        </Block>
+    )
+}
+
+export const CardV2Header = ({
+    title,
+    truncateTitle,
+    subtitle,
+    eyebrow,
+    leadingSlot,
+    trailingSlot,
+    centered,
+}: CardV2HeaderProps) => {
+    const { tokens, centered: contextCentered, ids } = useCardV2SectionContext()
+    const isCentered = centered ?? contextCentered
+    const hasHeader = Boolean(
+        leadingSlot || eyebrow || title || subtitle || trailingSlot
+    )
+
+    if (!hasHeader) return null
+
+    return (
+        <Block
+            data-element="card-header"
+            display="flex"
+            flexDirection={isCentered ? 'column' : 'row'}
+            alignItems={isCentered ? 'center' : 'flex-start'}
+            justifyContent={isCentered ? 'center' : 'space-between'}
+            gap={tokens.header.gap}
+            width="100%"
+            role="group"
+            aria-labelledby={title ? ids.title : undefined}
+        >
+            <Block
+                display="flex"
+                flexDirection={isCentered ? 'column' : 'row'}
+                alignItems={isCentered ? 'center' : 'flex-start'}
+                gap={tokens.header.gap}
+                minWidth={0}
+                flexGrow={1}
+                justifyContent={isCentered ? 'center' : undefined}
+                alignSelf={isCentered ? 'center' : undefined}
+                width={isCentered ? '100%' : undefined}
+            >
+                {leadingSlot && <Block flexShrink={0}>{leadingSlot}</Block>}
+                <CardV2Meta
+                    eyebrow={eyebrow}
+                    title={title}
+                    truncateTitle={truncateTitle}
+                    subtitle={subtitle}
+                    centered={isCentered}
+                />
+            </Block>
+            {trailingSlot && (
+                <Block
+                    flexShrink={0}
+                    alignSelf={isCentered ? 'center' : undefined}
+                >
+                    {trailingSlot}
+                </Block>
+            )}
+        </Block>
+    )
+}
+
+export const CardV2Media = ({
+    children,
+    orientation,
+    width,
+    height,
+    minHeight,
+}: CardV2MediaProps) => {
+    const { tokens, centered } = useCardV2SectionContext()
+    const isHorizontal = orientation === CardV2Orientation.HORIZONTAL
+
+    if (!children) return null
+
+    return (
+        <Block
+            data-element="card-media"
+            display="flex"
+            alignItems="center"
+            alignSelf={centered ? 'center' : 'flex-start'}
+            justifyContent="center"
+            flexShrink={0}
+            width={width ?? (isHorizontal ? tokens.media.width : '100%')}
+            height={height ?? tokens.media.height}
+            minHeight={
+                minHeight ?? (isHorizontal ? undefined : tokens.media.minHeight)
+            }
+            borderRadius={tokens.media.borderRadius}
+            backgroundColor={tokens.media.backgroundColor}
+            overflow="hidden"
+        >
+            {children}
+        </Block>
+    )
+}
+
+export const CardV2Actions = ({ actions, centered }: CardV2ActionsProps) => {
+    const { tokens, centered: contextCentered } = useCardV2SectionContext()
+    const isCentered = centered ?? contextCentered
+    const actionItems = toCardV2ActionArray(actions)
+
+    if (actionItems.length === 0) return null
+
+    return (
+        <Block
+            display="flex"
+            flexWrap="wrap"
+            justifyContent={isCentered ? 'center' : 'flex-start'}
+            gap={tokens.actions.gap}
+            data-element="card-actions"
+        >
+            {actionItems.map((action, index) => (
+                <ButtonV2
+                    key={`${action.text ?? action['aria-label'] ?? 'action'}-${index}`}
+                    {...action}
+                />
+            ))}
+        </Block>
+    )
+}
+
+export const CardV2Content = ({ children }: CardV2SectionProps) => {
+    const { centered } = useCardV2SectionContext()
+
+    if (!children) return null
+
+    return (
+        <Block
+            data-element="card-content"
+            width="100%"
+            display={centered ? 'flex' : undefined}
+            justifyContent={centered ? 'center' : undefined}
+        >
+            {children}
+        </Block>
+    )
+}
+
+export const CardV2Body = ({
+    description,
+    actions,
+    centered,
+    scrollable,
+    children,
+}: CardV2BodyProps) => {
+    const {
+        tokens,
+        centered: contextCentered,
+        scrollable: contextScrollable,
+        ids,
+    } = useCardV2SectionContext()
+    const isCentered = centered ?? contextCentered
+    const isScrollable = scrollable ?? contextScrollable
+    const hasBody = Boolean(description || children || actions)
+
+    if (!hasBody) return null
+
+    return (
+        <Block
+            data-element="card-body"
+            display="flex"
+            flexDirection="column"
+            gap={tokens.body.gap}
+            width="100%"
+            minHeight={0}
+            overflowY={isScrollable ? 'auto' : undefined}
+            overflowX={isScrollable ? 'hidden' : undefined}
+            alignItems={isCentered ? 'center' : undefined}
+            textAlign={isCentered ? 'center' : undefined}
+            role="group"
+            aria-describedby={description ? ids.description : undefined}
+        >
+            {renderCardV2Text({
+                value: description,
+                id: ids.description,
+                as: 'p',
+                styles: tokens.body.description as React.CSSProperties,
+                dataElement: 'card-description',
+            })}
+            <CardV2Content>{children}</CardV2Content>
+            <CardV2Actions actions={actions} centered={isCentered} />
+        </Block>
+    )
+}
+
+export const CardV2Footer = ({
+    children,
+    actions,
+    centered,
+    divider = false,
+}: CardV2FooterProps) => {
+    const { tokens, centered: contextCentered } = useCardV2SectionContext()
+    const isCentered = centered ?? contextCentered
+    const hasFooter = Boolean(children || actions)
+
+    if (!hasFooter) return null
+
+    return (
+        <Block
+            data-element="card-footer"
+            data-divider={divider || undefined}
+            display="flex"
+            flexWrap="wrap"
+            alignItems="center"
+            justifyContent={isCentered ? 'center' : 'space-between'}
+            gap={tokens.footer.gap}
+            width="100%"
+            paddingTop={divider ? tokens.footer.paddingTop : undefined}
+            borderTop={divider ? tokens.footer.borderTop : undefined}
+        >
+            {children && <Block>{children}</Block>}
+            <CardV2Actions actions={actions} centered={isCentered} />
+        </Block>
+    )
+}

package/lib/components/CardV2/CardV2Context.tsx

@@ -0,0 +1,18 @@
+import { createContext, useContext } from 'react'
+import type { CardV2TokensType } from './cardV2.tokens'
+
+export type CardV2ContextValue = {
+    tokens: CardV2TokensType
+    centered: boolean
+    scrollable: boolean
+    ids: {
+        eyebrow: string
+        title: string
+        subtitle: string
+        description: string
+    }
+}
+
+export const CardV2Context = createContext<CardV2ContextValue | null>(null)
+
+export const useCardV2Context = () => useContext(CardV2Context)

package/lib/components/CardV2/CardV2Skeleton.tsx

@@ -0,0 +1,40 @@
+import { useResponsiveTokens } from '../../hooks/useResponsiveTokens'
+import Block from '../Primitives/Block/Block'
+import Skeleton from '../Skeleton/Skeleton'
+import type { CardV2TokensType } from './cardV2.tokens'
+import { useCardV2Context } from './CardV2Context'
+import type { CardV2SkeletonProps } from './cardV2.types'
+
+export type CardV2SkeletonComponentProps = {
+    skeleton?: CardV2SkeletonProps
+}
+
+const CardV2Skeleton = ({ skeleton }: CardV2SkeletonComponentProps) => {
+    const context = useCardV2Context()
+    const responsiveTokens = useResponsiveTokens<CardV2TokensType>('CARDV2')
+    const tokens = context?.tokens ?? responsiveTokens
+
+    return (
+        <Block display="flex" flexDirection="column" gap={tokens.layout.gap}>
+            <Skeleton
+                variant={skeleton?.variant}
+                width={skeleton?.width ?? '100%'}
+                height={skeleton?.height ?? '160px'}
+                shape="rounded"
+            />
+            <Block
+                display="flex"
+                flexDirection="column"
+                gap={tokens.header.gap}
+            >
+                <Skeleton width="40%" height="18px" shape="rounded" />
+                <Skeleton width="70%" height="24px" shape="rounded" />
+                <Skeleton width="55%" height="18px" shape="rounded" />
+            </Block>
+            <Skeleton width="100%" height="18px" shape="rounded" />
+            <Skeleton width="84%" height="18px" shape="rounded" />
+        </Block>
+    )
+}
+
+export default CardV2Skeleton

package/lib/components/CardV2/accessibility/CardV2AccessibilityReport.ts

@@ -0,0 +1,284 @@
+import type { AccessibilityReport } from '../../StatCard/accessibility/StatCardAccessibilityReport'
+
+export const cardV2AccessibilityReport: AccessibilityReport = {
+    componentName: 'CardV2',
+    wcagVersion: '2.1',
+    reportDate: new Date().toISOString().split('T')[0],
+    conformanceLevel: 'Level AA',
+    overallStatus: 'partial',
+    summary:
+        'CardV2 is a composable grouping surface with prop-based and compound APIs. The component supports semantic regions, generated accessible names and descriptions, keyboard-focusable interactive cards, selected/pressed state semantics, accessible action buttons through ButtonV2, and consumer-owned media alternatives. Automated axe tests cover default, media/action, compound, and interactive selected cards. Manual verification is still required for token contrast across light/dark themes and for consumer-provided media content.',
+    criteria: [
+        {
+            id: '1.1.1',
+            level: 'A',
+            title: 'Non-text Content',
+            status: 'compliant',
+            description:
+                'All non-text content that is part of the component must have a text alternative or be hidden when decorative.',
+            implementation:
+                'CardV2 media, leadingSlot, and trailingSlot are consumer-owned React nodes. The component preserves supplied image alt text and supports decorative icons via aria-hidden on consumer content. Action icons are rendered through ButtonV2 and can receive aria-label.',
+            testResults:
+                'Automated tests verify CardV2 with accessible image media and icon-only actions has no axe violations.',
+            notes: 'Consumers must provide alt text for informative media or empty alt text/aria-hidden for decorative media.',
+        },
+        {
+            id: '1.3.1',
+            level: 'A',
+            title: 'Info and Relationships',
+            status: 'compliant',
+            description:
+                'Information, structure, and relationships conveyed visually can be programmatically determined.',
+            implementation:
+                'The root uses role="region" by default. Title, subtitle, and description receive generated IDs. Root aria-labelledby points to the title when present, and aria-describedby points to description or subtitle. Header and body sections use role="group" where appropriate.',
+            testResults:
+                'Automated tests verify aria-labelledby and aria-describedby are wired to generated IDs.',
+        },
+        {
+            id: '1.3.2',
+            level: 'A',
+            title: 'Meaningful Sequence',
+            status: 'compliant',
+            description:
+                'Content is presented in a meaningful DOM and reading sequence.',
+            implementation:
+                'Prop composition renders media, header, body, and footer in visual reading order. Compound composition preserves consumer-provided DOM order while sharing context and tokens.',
+            testResults: 'Verified by render tests for prop and compound APIs.',
+        },
+        {
+            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:
+                'CardV2 supports vertical and horizontal orientations and responsive sm/lg token sets.',
+            testResults:
+                'Automated tests cover horizontal cards with accessible media.',
+        },
+        {
+            id: '1.4.3',
+            level: 'AA',
+            title: 'Contrast (Minimum)',
+            status: 'unsure',
+            description:
+                'Text and images of text have sufficient contrast against their backgrounds.',
+            implementation:
+                'CardV2 typography and surfaces use theme tokens for light and dark modes.',
+            testResults:
+                'UNSURE: Requires manual contrast verification across all variants, states, and themes.',
+            notes: 'Verify title, subtitle, description, borders, focus rings, and selected states in light and dark themes.',
+        },
+        {
+            id: '1.4.4',
+            level: 'AA',
+            title: 'Resize Text',
+            status: 'compliant',
+            description:
+                'Text can be resized up to 200 percent without loss of content or functionality.',
+            implementation:
+                'The layout uses flex containers, minWidth=0 where text can shrink, and optional truncateTitle for constrained titles.',
+            testResults:
+                'Automated render tests cover long wrapping titles and truncateTitle behavior.',
+        },
+        {
+            id: '1.4.10',
+            level: 'AA',
+            title: 'Reflow',
+            status: 'compliant',
+            description:
+                'Content can reflow without requiring two-dimensional scrolling at common viewport sizes.',
+            implementation:
+                'Cards support width constraints, horizontal/vertical orientation, wrapping action rows, and responsive token compaction.',
+            testResults:
+                'Demo and tests cover narrow cards, horizontal cards, and long content.',
+        },
+        {
+            id: '1.4.11',
+            level: 'AA',
+            title: 'Non-text Contrast',
+            status: 'unsure',
+            description:
+                'UI component boundaries, focus indicators, and graphical states have sufficient contrast.',
+            implementation:
+                'Borders, selected state, hover state, and focus-visible outline use theme tokens.',
+            testResults:
+                'UNSURE: Requires manual token contrast verification across variants and themes.',
+        },
+        {
+            id: '2.1.1',
+            level: 'A',
+            title: 'Keyboard',
+            status: 'compliant',
+            description:
+                'All functionality is operable through a keyboard interface.',
+            implementation:
+                'Interactive cards receive role="button" and tabIndex=0 by default. Actions are rendered through ButtonV2 and remain keyboard reachable.',
+            testResults:
+                'Automated tests verify interactive role, tabIndex, and reachable footer/body actions.',
+        },
+        {
+            id: '2.4.3',
+            level: 'A',
+            title: 'Focus Order',
+            status: 'compliant',
+            description:
+                'Focusable components receive focus in an order that preserves meaning and operability.',
+            implementation:
+                'DOM order follows media, header, body, actions, and footer order for prop composition. Compound composition preserves consumer-defined order.',
+            testResults:
+                'Verified structurally through render tests and ButtonV2 keyboard behavior.',
+        },
+        {
+            id: '2.4.6',
+            level: 'AA',
+            title: 'Headings and Labels',
+            status: 'compliant',
+            description: 'Headings and labels describe topic or purpose.',
+            implementation:
+                'Title renders as h2 by default through CardV2Meta. aria-labelledby points to title when available; aria-label is used only when no title is present.',
+            testResults:
+                'Automated tests verify aria-label and aria-labelledby are not set together for titled cards.',
+        },
+        {
+            id: '2.4.7',
+            level: 'AA',
+            title: 'Focus Visible',
+            status: 'compliant',
+            description: 'Keyboard-operable UI has a visible focus indicator.',
+            implementation:
+                'The root applies tokenized focus-visible outline. ButtonV2 actions provide their own focus treatment.',
+            testResults:
+                'Axe tests pass for interactive selected cards. Manual visual verification recommended for theme contrast.',
+        },
+        {
+            id: '2.5.8',
+            level: 'AA',
+            title: 'Target Size (Minimum)',
+            status: 'compliant',
+            description:
+                'Pointer targets are at least 24 by 24 CSS pixels or have equivalent spacing.',
+            implementation:
+                'Action controls are rendered through ButtonV2 sizing. Interactive root cards are large surfaces by design.',
+            testResults:
+                'Verified by component composition and ButtonV2 target sizing.',
+        },
+        {
+            id: '3.2.1',
+            level: 'A',
+            title: 'On Focus',
+            status: 'compliant',
+            description:
+                'Receiving focus does not initiate a change of context.',
+            implementation:
+                'CardV2 focus styles are visual only; no behavior is triggered by focus.',
+            testResults: 'Verified by implementation review.',
+        },
+        {
+            id: '4.1.2',
+            level: 'A',
+            title: 'Name, Role, Value',
+            status: 'compliant',
+            description:
+                'UI components expose appropriate name, role, and state.',
+            implementation:
+                'Root cards expose region or button roles. Titled cards use aria-labelledby. Interactive selected cards use aria-pressed. aria-selected is only emitted for roles that support it.',
+            testResults:
+                'Automated tests and axe checks cover root roles, labels, descriptions, pressed state, and selected-state constraints.',
+        },
+    ],
+    strengths: [
+        'Clear generated ID relationships for title, subtitle, and description.',
+        'No conflicting aria-label when aria-labelledby is available.',
+        'Interactive selected cards use aria-pressed for button semantics.',
+        'Selected aria state is limited to roles that support aria-selected.',
+        'Compound API preserves consumer DOM order and semantic control.',
+        'Axe coverage exists for default, media/action, compound, and interactive cards.',
+    ],
+    recommendations: [
+        'Manually verify light and dark token contrast for every variant and state.',
+        'Require consumers to provide accessible names for informative custom media and icon-only slots.',
+        'Use CardV2 as a region only when the grouped content is meaningful enough to appear as a landmark-like region.',
+        'Prefer explicit role overrides when rendering CardV2 inside list, grid, tab, or option collections.',
+        'Keep nested interactive controls out of cards with root-level click handlers unless event behavior is intentionally managed.',
+    ],
+    wcagVersions: {
+        '2.0': [
+            '1.1.1',
+            '1.3.1',
+            '1.3.2',
+            '1.4.3',
+            '2.1.1',
+            '2.4.3',
+            '2.4.6',
+            '2.4.7',
+            '3.2.1',
+            '4.1.2',
+        ],
+        '2.1': ['1.3.4', '1.4.10', '1.4.11'],
+        '2.2': ['2.5.8'],
+    },
+    testMethodology: {
+        automated: [
+            'Vitest and React Testing Library render tests.',
+            'jest-axe checks for default, media/action, compound, and interactive selected examples.',
+            'ARIA relationship assertions for root, title, subtitle, and description.',
+        ],
+        manual: [
+            'Keyboard navigation through interactive card roots and nested actions.',
+            'Screen reader review of titled, untitled, compound, and media-rich cards.',
+            'Light/dark contrast verification for text, borders, focus, selected, and hover states.',
+            'Responsive visual review across narrow and wide viewports.',
+        ],
+        verificationTools: [
+            'jest-axe',
+            'React Testing Library',
+            'Storybook accessibility addon',
+            'WebAIM Contrast Checker',
+            'VoiceOver, NVDA, or equivalent screen reader',
+        ],
+        wcagLevels: {
+            A: ['1.1.1', '1.3.1', '1.3.2', '2.1.1', '2.4.3', '3.2.1', '4.1.2'],
+            AA: [
+                '1.3.4',
+                '1.4.3',
+                '1.4.4',
+                '1.4.10',
+                '1.4.11',
+                '2.4.6',
+                '2.4.7',
+                '2.5.8',
+            ],
+            AAA: [],
+        },
+    },
+    accessibilityBestPractices: {
+        semanticGrouping: {
+            status: 'compliant',
+            implementation:
+                'Root role defaults to region and can be overridden for list/grid/tab/option contexts.',
+            verification: 'Render tests verify default and custom root roles.',
+        },
+        accessibleNaming: {
+            status: 'compliant',
+            implementation:
+                'Title-driven cards use aria-labelledby; custom aria-label is reserved for cards without titles.',
+            verification:
+                'Accessibility tests verify aria-label and aria-labelledby behavior.',
+        },
+        stateSemantics: {
+            status: 'compliant',
+            implementation:
+                'Interactive selected cards use aria-pressed; aria-selected is limited to supported roles.',
+            verification: 'Axe checks pass for interactive selected cards.',
+        },
+        consumerMedia: {
+            status: 'unsure',
+            implementation:
+                'Media is consumer-owned and can be accessible or decorative depending on supplied markup.',
+            verification:
+                'Consumers must verify alt text or aria-hidden on media content.',
+        },
+    },
+}

package/lib/components/CardV2/accessibility/index.ts

@@ -0,0 +1 @@
+export { cardV2AccessibilityReport } from './CardV2AccessibilityReport'