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

package/lib/tokens/unit.tokens.ts

@@ -0,0 +1,101 @@
+import type { CSSObject } from 'styled-components'
+
+type UnitType =
+    | CSSObject['width']
+    | CSSObject['height']
+    | CSSObject['gap']
+    | CSSObject['padding']
+    | CSSObject['margin']
+
+export type UnitTokensType = Readonly<{
+    0: UnitType
+    0.5: UnitType
+    1: UnitType
+    1.5: UnitType
+    2: UnitType
+    3: UnitType
+    4: UnitType
+    5: UnitType
+    6: UnitType
+    7: UnitType
+    8: UnitType
+    9: UnitType
+    10: UnitType
+    12: UnitType
+    14: UnitType
+    15: UnitType
+    16: UnitType
+    18: UnitType
+    18.5: UnitType
+    20: UnitType
+    22: UnitType
+    24: UnitType
+    28: UnitType
+    30: UnitType
+    32: UnitType
+    36: UnitType
+    40: UnitType
+    44: UnitType
+    48: UnitType
+    52: UnitType
+    56: UnitType
+    64: UnitType
+    80: UnitType
+    100: UnitType
+    120: UnitType
+    144: UnitType
+    150: UnitType
+    auto: UnitType
+    [key: string]: UnitType
+}>
+
+const unitTokens: UnitTokensType = {
+    0: '0px',
+    0.5: '0.5px',
+    1: '1px',
+    1.5: '1.5px',
+    2: '2px',
+    3: '3px',
+    4: '4px',
+    5: '5px',
+    6: '6px',
+    7: '7px',
+    8: '8px',
+    9: '9px',
+    10: '10px',
+    11: '11px',
+    12: '12px',
+    13: '13px',
+    14: '14px',
+    15: '15px',
+    16: '16px',
+    16.5: '16.5px',
+    18: '18px',
+    18.5: '18.5px',
+    20: '20px',
+    22: '22px',
+    24: '24px',
+    28: '28px',
+    30: '30px',
+    32: '32px',
+    36: '36px',
+    40: '40px',
+    42: '42px',
+    44: '44px',
+    48: '48px',
+    50: '50px',
+    52: '52px',
+    56: '56px',
+    64: '64px',
+    80: '80px',
+    100: '100px',
+    120: '120px',
+    144: '144px',
+    150: '150px',
+    190: '190px',
+    200: '200px',
+    350: '350px',
+    auto: 'auto',
+}
+
+export default unitTokens

package/lib/tokens/zIndex.tokens.ts

@@ -0,0 +1,25 @@
+import type { CSSObject } from 'styled-components'
+
+export type ZIndexTokensType = Readonly<{
+    0: CSSObject['zIndex']
+    9999: CSSObject['zIndex']
+    1000: CSSObject['zIndex']
+    1100: CSSObject['zIndex']
+    1200: CSSObject['zIndex']
+    101: CSSObject['zIndex']
+    [key: string]: CSSObject['zIndex']
+}>
+
+const zIndexTokens: ZIndexTokensType = {
+    0: 0,
+    10: 10,
+    99: 99,
+    100: 100,
+    101: 101,
+    9999: 9999,
+    1000: 1000,
+    1100: 1100,
+    1200: 1200,
+}
+
+export default zIndexTokens

package/lib/types/assets.d.ts

@@ -0,0 +1,24 @@
+declare module '*.png' {
+    const content: string
+    export default content
+}
+
+declare module '*.jpg' {
+    const content: string
+    export default content
+}
+
+declare module '*.jpeg' {
+    const content: string
+    export default content
+}
+
+declare module '*.svg' {
+    const content: string
+    export default content
+}
+
+declare module '*.gif' {
+    const content: string
+    export default content
+}

package/lib/utils/accessibility/aria-helpers.ts

@@ -0,0 +1,317 @@
+/**
+ * Shared ARIA attribute helpers for consistent accessibility across all components
+ *
+ * These utilities ensure consistent ARIA implementation following WCAG 2.2 Level AA standards
+ * and reduce code duplication across components.
+ */
+
+export type AriaAttributes = {
+    'aria-label'?: string
+    'aria-labelledby'?: string
+    'aria-describedby'?: string
+    'aria-expanded'?: boolean
+    'aria-selected'?: boolean
+    'aria-disabled'?: boolean
+    'aria-busy'?: boolean
+    'aria-invalid'?: boolean
+    'aria-required'?: boolean
+    'aria-controls'?: string
+    'aria-live'?: 'polite' | 'assertive' | 'off'
+    'aria-atomic'?: boolean
+    'aria-haspopup'?:
+        | 'true'
+        | 'false'
+        | 'menu'
+        | 'listbox'
+        | 'tree'
+        | 'grid'
+        | 'dialog'
+    'aria-modal'?: boolean
+    'aria-orientation'?: 'horizontal' | 'vertical'
+    role?: string
+}
+
+/**
+ * Generate ARIA attributes for button components
+ *
+ * @example
+ * ```tsx
+ * const ariaAttrs = getButtonAriaAttributes({
+ *     disabled: true,
+ *     loading: false,
+ *     ariaLabel: 'Close dialog'
+ * })
+ * <button {...ariaAttrs}>Close</button>
+ * ```
+ */
+export function getButtonAriaAttributes(props: {
+    disabled?: boolean
+    loading?: boolean
+    ariaLabel?: string
+    ariaLabelledBy?: string
+}): AriaAttributes {
+    const attrs: AriaAttributes = {}
+
+    if (props.disabled) {
+        attrs['aria-disabled'] = true
+    }
+
+    if (props.loading) {
+        attrs['aria-busy'] = true
+    }
+
+    if (props.ariaLabel) {
+        attrs['aria-label'] = props.ariaLabel
+    }
+
+    if (props.ariaLabelledBy) {
+        attrs['aria-labelledby'] = props.ariaLabelledBy
+    }
+
+    return attrs
+}
+
+/**
+ * Generate ARIA attributes for input components
+ *
+ * @example
+ * ```tsx
+ * const ariaAttrs = getInputAriaAttributes({
+ *     id: 'email-input',
+ *     labelId: 'email-label',
+ *     errorId: 'email-error',
+ *     hintId: 'email-hint',
+ *     required: true,
+ *     invalid: true
+ * })
+ * <input {...ariaAttrs} />
+ * ```
+ */
+export function getInputAriaAttributes(props: {
+    id: string
+    labelId?: string
+    errorId?: string
+    hintId?: string
+    required?: boolean
+    invalid?: boolean
+    describedBy?: string[]
+}): AriaAttributes {
+    const attrs: AriaAttributes = {}
+    const describedBy: string[] = []
+
+    if (props.labelId) {
+        attrs['aria-labelledby'] = props.labelId
+    }
+
+    if (props.errorId) {
+        describedBy.push(props.errorId)
+        attrs['aria-invalid'] = props.invalid ?? true
+    }
+
+    if (props.hintId) {
+        describedBy.push(props.hintId)
+    }
+
+    if (props.describedBy) {
+        describedBy.push(...props.describedBy)
+    }
+
+    if (describedBy.length > 0) {
+        attrs['aria-describedby'] = describedBy.join(' ')
+    }
+
+    if (props.required) {
+        attrs['aria-required'] = true
+    }
+
+    return attrs
+}
+
+/**
+ * Generate ARIA attributes for modal/dialog components
+ *
+ * @example
+ * ```tsx
+ * const ariaAttrs = getModalAriaAttributes({
+ *     id: 'dialog-1',
+ *     titleId: 'dialog-title',
+ *     descriptionId: 'dialog-description',
+ *     isAlert: false
+ * })
+ * <div role="dialog" {...ariaAttrs}>...</div>
+ * ```
+ */
+export function getModalAriaAttributes(props: {
+    id: string
+    titleId: string
+    descriptionId?: string
+    isAlert?: boolean
+}): AriaAttributes {
+    return {
+        role: props.isAlert ? 'alertdialog' : 'dialog',
+        'aria-modal': true,
+        'aria-labelledby': props.titleId,
+        ...(props.descriptionId && {
+            'aria-describedby': props.descriptionId,
+        }),
+    }
+}
+
+/**
+ * Generate ARIA attributes for dropdown/select components
+ *
+ * @example
+ * ```tsx
+ * const ariaAttrs = getDropdownAriaAttributes({
+ *     id: 'select-1',
+ *     isOpen: true,
+ *     triggerId: 'select-trigger',
+ *     menuId: 'select-menu'
+ * })
+ * <button {...ariaAttrs}>Select</button>
+ * ```
+ */
+export function getDropdownAriaAttributes(props: {
+    id: string
+    isOpen: boolean
+    triggerId: string
+    menuId: string
+    hasPopup?: 'listbox' | 'menu'
+}): AriaAttributes {
+    return {
+        'aria-expanded': props.isOpen,
+        'aria-controls': props.menuId,
+        'aria-haspopup': props.hasPopup || 'listbox',
+    }
+}
+
+/**
+ * Generate ARIA attributes for tab components
+ *
+ * @example
+ * ```tsx
+ * const ariaAttrs = getTabAriaAttributes({
+ *     id: 'tab-1',
+ *     panelId: 'panel-1',
+ *     selected: true
+ * })
+ * <button role="tab" {...ariaAttrs}>Tab 1</button>
+ * ```
+ */
+export function getTabAriaAttributes(props: {
+    id: string
+    panelId: string
+    selected: boolean
+    controls?: string
+}): AriaAttributes {
+    return {
+        role: 'tab',
+        'aria-selected': props.selected,
+        'aria-controls': props.panelId,
+        ...(props.controls && { 'aria-controls': props.controls }),
+    }
+}
+
+/**
+ * Generate ARIA attributes for tab panel components
+ *
+ * @example
+ * ```tsx
+ * const ariaAttrs = getTabPanelAriaAttributes({
+ *     id: 'panel-1',
+ *     tabId: 'tab-1',
+ *     labelledBy: 'tab-1-label'
+ * })
+ * <div role="tabpanel" {...ariaAttrs}>Panel content</div>
+ * ```
+ */
+export function getTabPanelAriaAttributes(props: {
+    id: string
+    tabId: string
+    labelledBy?: string
+}): AriaAttributes {
+    return {
+        role: 'tabpanel',
+        'aria-labelledby': props.labelledBy || props.tabId,
+    }
+}
+
+/**
+ * Generate ARIA attributes for accordion components
+ *
+ * @example
+ * ```tsx
+ * const ariaAttrs = getAccordionAriaAttributes({
+ *     headerId: 'accordion-header-1',
+ *     contentId: 'accordion-content-1',
+ *     expanded: false
+ * })
+ * <button {...ariaAttrs}>Accordion Header</button>
+ * ```
+ */
+export function getAccordionAriaAttributes(props: {
+    headerId: string
+    contentId: string
+    expanded: boolean
+}): AriaAttributes {
+    return {
+        role: 'button',
+        'aria-expanded': props.expanded,
+        'aria-controls': props.contentId,
+    }
+}
+
+/**
+ * Generate ARIA live region attributes for dynamic content
+ *
+ * @example
+ * ```tsx
+ * const ariaAttrs = getLiveRegionAriaAttributes({
+ *     live: 'assertive',
+ *     atomic: true
+ * })
+ * <div {...ariaAttrs}>Error message</div>
+ * ```
+ */
+export function getLiveRegionAriaAttributes(props: {
+    live?: 'polite' | 'assertive' | 'off'
+    atomic?: boolean
+}): AriaAttributes {
+    return {
+        'aria-live': props.live || 'polite',
+        'aria-atomic': props.atomic ?? true,
+    }
+}
+
+/**
+ * Generate unique IDs for ARIA relationships
+ *
+ * @example
+ * ```tsx
+ * const labelId = generateAriaId('label')
+ * const inputId = generateAriaId('input')
+ * ```
+ */
+export function generateAriaId(prefix: string): string {
+    return `${prefix}-${Math.random().toString(36).substring(2, 9)}`
+}
+
+/**
+ * Combine multiple ARIA attribute objects
+ * Later objects override earlier ones for conflicting keys
+ *
+ * @example
+ * ```tsx
+ * const baseAttrs = getButtonAriaAttributes({ disabled: true })
+ * const additionalAttrs = { 'aria-label': 'Custom label' }
+ * const merged = mergeAriaAttributes(baseAttrs, additionalAttrs)
+ * ```
+ */
+export function mergeAriaAttributes(
+    ...attrs: Array<AriaAttributes | undefined>
+): AriaAttributes {
+    return attrs.reduce<AriaAttributes>((acc, curr) => {
+        if (!curr) return acc
+        return { ...acc, ...curr }
+    }, {})
+}

package/lib/utils/accessibility/focus-helpers.ts

@@ -0,0 +1,226 @@
+/**
+ * Focus management helpers for accessibility
+ *
+ * These utilities ensure consistent focus management across all components,
+ * following WCAG 2.2 Level AA standards for keyboard navigation and focus visibility.
+ */
+
+/**
+ * Focus an element safely (handles cases where element might not exist)
+ *
+ * @example
+ * ```tsx
+ * const inputRef = useRef<HTMLInputElement>(null)
+ * safeFocus(inputRef.current)
+ * ```
+ */
+export function safeFocus(element: HTMLElement | null): void {
+    if (element && typeof element.focus === 'function') {
+        try {
+            element.focus()
+        } catch (error) {
+            // Silently handle focus errors (e.g., element not in DOM)
+            console.warn('Failed to focus element:', error)
+        }
+    }
+}
+
+/**
+ * Focus first focusable element in container
+ *
+ * @example
+ * ```tsx
+ * const containerRef = useRef<HTMLDivElement>(null)
+ * focusFirstFocusable(containerRef.current!)
+ * ```
+ */
+export function focusFirstFocusable(container: HTMLElement): void {
+    const focusableSelectors = [
+        'button:not([disabled])',
+        'a[href]',
+        'input:not([disabled])',
+        'select:not([disabled])',
+        'textarea:not([disabled])',
+        '[tabindex]:not([tabindex="-1"])',
+        '[contenteditable="true"]',
+    ].join(', ')
+
+    const firstFocusable =
+        container.querySelector<HTMLElement>(focusableSelectors)
+    safeFocus(firstFocusable)
+}
+
+/**
+ * Focus last focusable element in container
+ *
+ * @example
+ * ```tsx
+ * const containerRef = useRef<HTMLDivElement>(null)
+ * focusLastFocusable(containerRef.current!)
+ * ```
+ */
+export function focusLastFocusable(container: HTMLElement): void {
+    const focusableSelectors = [
+        'button:not([disabled])',
+        'a[href]',
+        'input:not([disabled])',
+        'select:not([disabled])',
+        'textarea:not([disabled])',
+        '[tabindex]:not([tabindex="-1"])',
+        '[contenteditable="true"]',
+    ].join(', ')
+
+    const focusables = Array.from(
+        container.querySelectorAll<HTMLElement>(focusableSelectors)
+    )
+
+    if (focusables.length > 0) {
+        safeFocus(focusables[focusables.length - 1])
+    }
+}
+
+/**
+ * Store and restore focus (for modals, dropdowns, etc.)
+ *
+ * @example
+ * ```tsx
+ * const focusManager = createFocusManager()
+ *
+ * // When opening modal
+ * focusManager.store()
+ * focusFirstFocusable(modalRef.current!)
+ *
+ * // When closing modal
+ * focusManager.restore()
+ * ```
+ */
+export function createFocusManager() {
+    let previousFocus: HTMLElement | null = null
+
+    return {
+        store: () => {
+            previousFocus = document.activeElement as HTMLElement
+        },
+        restore: () => {
+            if (previousFocus) {
+                safeFocus(previousFocus)
+                previousFocus = null
+            }
+        },
+        getStored: () => previousFocus,
+    }
+}
+
+/**
+ * Check if element is focusable
+ *
+ * @example
+ * ```tsx
+ * if (isFocusable(element)) {
+ *     element.focus()
+ * }
+ * ```
+ */
+export function isFocusable(element: HTMLElement): boolean {
+    const focusableSelectors = [
+        'button:not([disabled])',
+        'a[href]',
+        'input:not([disabled])',
+        'select:not([disabled])',
+        'textarea:not([disabled])',
+        '[tabindex]:not([tabindex="-1"])',
+        '[contenteditable="true"]',
+    ].join(', ')
+
+    return element.matches(focusableSelectors)
+}
+
+/**
+ * Get all focusable elements within a container
+ *
+ * @example
+ * ```tsx
+ * const focusables = getFocusableElements(containerRef.current!)
+ * focusables.forEach(el => console.log(el))
+ * ```
+ */
+export function getFocusableElements(container: HTMLElement): HTMLElement[] {
+    const focusableSelectors = [
+        'button:not([disabled])',
+        'a[href]',
+        'input:not([disabled])',
+        'select:not([disabled])',
+        'textarea:not([disabled])',
+        '[tabindex]:not([tabindex="-1"])',
+        '[contenteditable="true"]',
+    ].join(', ')
+
+    return Array.from(
+        container.querySelectorAll<HTMLElement>(focusableSelectors)
+    )
+}
+
+/**
+ * Check if focus is within a container
+ *
+ * @example
+ * ```tsx
+ * if (isFocusWithin(modalRef.current!)) {
+ *     // Focus is inside modal
+ * }
+ * ```
+ */
+export function isFocusWithin(container: HTMLElement): boolean {
+    const activeElement = document.activeElement
+    if (!activeElement) return false
+
+    return container.contains(activeElement)
+}
+
+/**
+ * Focus next focusable element in document order
+ *
+ * @example
+ * ```tsx
+ * focusNextFocusable(currentElement)
+ * ```
+ */
+export function focusNextFocusable(currentElement: HTMLElement): void {
+    const allFocusables = getFocusableElements(document.body)
+    const currentIndex = allFocusables.indexOf(currentElement)
+
+    if (currentIndex >= 0 && currentIndex < allFocusables.length - 1) {
+        safeFocus(allFocusables[currentIndex + 1])
+    }
+}
+
+/**
+ * Focus previous focusable element in document order
+ *
+ * @example
+ * ```tsx
+ * focusPreviousFocusable(currentElement)
+ * ```
+ */
+export function focusPreviousFocusable(currentElement: HTMLElement): void {
+    const allFocusables = getFocusableElements(document.body)
+    const currentIndex = allFocusables.indexOf(currentElement)
+
+    if (currentIndex > 0) {
+        safeFocus(allFocusables[currentIndex - 1])
+    }
+}
+
+/**
+ * Remove focus from element
+ *
+ * @example
+ * ```tsx
+ * removeFocus(element)
+ * ```
+ */
+export function removeFocus(element: HTMLElement): void {
+    if (document.activeElement === element) {
+        element.blur()
+    }
+}

package/lib/utils/accessibility/icon-helpers.ts

@@ -0,0 +1,25 @@
+import {
+    cloneElement,
+    isValidElement,
+    ReactNode,
+    type ReactElement,
+} from 'react'
+
+export function hasAccessibleLabel(slot: ReactElement): boolean {
+    const props = slot.props as Record<string, unknown>
+    return 'aria-label' in props || 'aria-labelledby' in props
+}
+
+export function addAccessibleAriaAttributes(slot: ReactNode): ReactNode {
+    if (!isValidElement(slot)) {
+        return slot
+    }
+
+    if (hasAccessibleLabel(slot)) {
+        return slot
+    }
+
+    return cloneElement(slot, {
+        'aria-hidden': 'true',
+    } as Record<string, unknown>)
+}