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

package/lib/components/AvatarV2/avatarV2.tokens.ts

@@ -0,0 +1,93 @@
+import type { CSSObject } from 'styled-components'
+import { AvatarV2Size, AvatarV2Shape, AvatarV2Status } from './avatarV2.types'
+import type { FoundationTokenType } from '../../tokens/theme.token'
+import { type BreakpointType } from '../../breakpoints/breakPoints'
+import { Theme } from '../../context/theme.enum'
+import { getAvatarV2DarkTokens } from './avatarV2.dark.tokens'
+import { getAvatarV2LightTokens } from './avatarV2.light.tokens'
+
+export type AvatarV2TokensType = {
+    gap: CSSObject['gap']
+    container: {
+        backgroundColor: CSSObject['backgroundColor']
+        width: {
+            [key in AvatarV2Size]: CSSObject['width']
+        }
+        height: {
+            [key in AvatarV2Size]: CSSObject['height']
+        }
+        borderRadius: {
+            [key in AvatarV2Shape]: CSSObject['borderRadius']
+        }
+        image: {
+            border: CSSObject['border']
+        }
+        fallbackText: {
+            border: CSSObject['border']
+            fontSize: {
+                [key in AvatarV2Size]: CSSObject['fontSize']
+            }
+            fontWeight: {
+                [key in AvatarV2Size]: CSSObject['fontWeight']
+            }
+            lineHeight: {
+                [key in AvatarV2Size]: CSSObject['lineHeight']
+            }
+            color: CSSObject['color']
+        }
+
+        status: {
+            width: {
+                [key in AvatarV2Size]: CSSObject['width']
+            }
+            height: {
+                [key in AvatarV2Size]: CSSObject['height']
+            }
+            border: {
+                [key in AvatarV2Size]: CSSObject['border']
+            }
+            borderRadius: CSSObject['borderRadius']
+            backgroundColor: {
+                [key in AvatarV2Status]: CSSObject['backgroundColor']
+            }
+            boxShadow: CSSObject['boxShadow']
+            position: {
+                [key in AvatarV2Shape]: {
+                    [key in AvatarV2Size]: {
+                        top?: CSSObject['top']
+                        right?: CSSObject['right']
+                        bottom?: CSSObject['bottom']
+                        left?: CSSObject['left']
+                    }
+                }
+            }
+        }
+    }
+
+    slot: {
+        height: CSSObject['height']
+        width: CSSObject['width']
+    }
+}
+
+export type ResponsiveAvatarV2Tokens = {
+    [key in keyof BreakpointType]: AvatarV2TokensType
+}
+
+/**
+ * Get AvatarV2 tokens based on theme
+ *
+ * @param foundationToken - The foundation theme tokens
+ * @param theme - The current theme (light or dark)
+ * @returns Responsive AvatarV2 tokens
+ */
+export const getAvatarV2Tokens = (
+    foundationToken: FoundationTokenType,
+    theme: Theme | string = Theme.LIGHT
+): ResponsiveAvatarV2Tokens => {
+    if (theme === Theme.DARK || theme === 'dark') {
+        return getAvatarV2DarkTokens(foundationToken)
+    }
+
+    return getAvatarV2LightTokens(foundationToken)
+}

package/lib/components/AvatarV2/avatarV2.types.ts

@@ -0,0 +1,96 @@
+import type { HTMLAttributes, ReactNode, ReactElement } from 'react'
+import { CSSObject } from 'styled-components'
+
+export enum AvatarV2Size {
+    SM = 'sm',
+    REGULAR = 'regular',
+    MD = 'md',
+    LG = 'lg',
+    XL = 'xl',
+}
+
+export enum AvatarV2Shape {
+    CIRCULAR = 'circular',
+    ROUNDED = 'rounded',
+}
+
+export enum AvatarV2StatusPosition {
+    TOP_RIGHT = 'topRight',
+    BOTTOM_RIGHT = 'bottomRight',
+    TOP_LEFT = 'topLeft',
+    BOTTOM_LEFT = 'bottomLeft',
+}
+
+export enum AvatarV2Status {
+    NONE = 'none',
+    ONLINE = 'online',
+    OFFLINE = 'offline',
+    AWAY = 'away',
+    BUSY = 'busy',
+}
+
+export enum AvatarV2Variant {
+    IMAGE = 'image',
+    TEXT = 'text',
+    ICON = 'icon',
+}
+
+export type AvatarV2SkeletonConfig = {
+    show: boolean
+    variant?: 'pulse' | 'wave'
+}
+
+export type AvatarV2StatusConfig = {
+    type: AvatarV2Status
+    position?: AvatarV2StatusPosition
+}
+
+export type AvatarV2Dimensions = {
+    width?: CSSObject['width']
+    height?: CSSObject['height']
+}
+
+export type AvatarV2Props = {
+    src?: string
+    alt?: string
+    fallbackText?: string
+    size?: AvatarV2Size
+    shape?: AvatarV2Shape
+    status?: AvatarV2StatusConfig
+    leftSlot?: ReactElement
+    rightSlot?: ReactElement
+    skeleton?: AvatarV2SkeletonConfig
+    backgroundColor?: string
+    disabled?: boolean
+    onImageError?: (error: Error) => void
+    onImageLoad?: () => void
+} & Omit<
+    React.HTMLAttributes<HTMLDivElement>,
+    'children' | 'className' | 'style'
+> &
+    AvatarV2Dimensions
+
+export type AvatarV2ImageProps = {
+    src: string
+    alt: string
+    onError: () => void
+    onLoad?: () => void
+}
+
+export type AvatarV2FallbackProps = {
+    children: ReactNode
+    backgroundColor?: string
+}
+
+export type AvatarV2StatusIndicatorProps = {
+    status: AvatarV2Status
+    position: AvatarV2StatusPosition
+    size: AvatarV2Size
+}
+
+export type AvatarV2GroupProps = {
+    avatars: Omit<AvatarV2Props, 'leadingSlot' | 'trailingSlot'>[]
+    max?: number
+    size?: AvatarV2Size
+    spacing?: 'tight' | 'normal' | 'loose'
+} & Omit<HTMLAttributes<HTMLDivElement>, 'children'>

package/lib/components/AvatarV2/avatarV2.utils.ts

@@ -0,0 +1,223 @@
+import type { ReactNode } from 'react'
+import {
+    AvatarV2Status,
+    AvatarV2StatusPosition,
+    AvatarV2Shape,
+    AvatarV2Size,
+} from './avatarV2.types'
+import type { AvatarV2TokensType } from './avatarV2.tokens'
+
+export const DEFAULT_AVATAR_ALT = 'Avatar'
+export const DEFAULT_FALLBACK_COLOR = '#94A3B8'
+export const MAX_INITIALS_LENGTH = 2
+export const DEFAULT_POSITION = { top: '0', right: '0', bottom: '0' } as const
+
+const AVATAR_COLOR_PALETTE: readonly string[] = [
+    '#FF6B6B', // Red
+    '#4ECDC4', // Teal
+    '#45B7D1', // Sky Blue
+    '#FFA07A', // Light Salmon
+    '#98D8C8', // Mint
+    '#F7DC6F', // Yellow
+    '#BB8FCE', // Purple
+    '#85C1E2', // Light Blue
+    '#F8B739', // Orange
+    '#52B788', // Green
+    '#E85D75', // Pink
+    '#6C5CE7', // Indigo
+    '#00B894', // Emerald
+    '#FDCB6E', // Amber
+    '#E17055', // Terra Cotta
+    '#74B9FF', // Blue
+    '#A29BFE', // Lavender
+    '#FD79A8', // Rose
+    '#00CEC9', // Cyan
+    '#FF7675', // Coral
+] as const
+
+const KEYBOARD_KEYS = {
+    ENTER: 'Enter',
+    SPACE: ' ',
+}
+
+const SYNTHETIC_EVENT_DEFAULTS = {
+    BUTTON: 0,
+    BUTTONS: 0,
+    CLIENT_X: 0,
+    CLIENT_Y: 0,
+    PAGE_X: 0,
+    PAGE_Y: 0,
+    SCREEN_X: 0,
+    SCREEN_Y: 0,
+    MOVEMENT_X: 0,
+    MOVEMENT_Y: 0,
+    EVENT_PHASE: 0,
+    IS_TRUSTED: false,
+    BUBBLES: true,
+    CANCELABLE: true,
+    DEFAULT_PREVENTED: false,
+    TYPE: 'click',
+}
+
+const TEXT_PATTERNS = {
+    WHITESPACE: /\s+/g,
+    CAPITAL_LETTERS: /([A-Z])/g,
+}
+
+export function getInitialsFromText(text?: string): string {
+    if (!text || text.trim() === '') {
+        return ''
+    }
+
+    return text
+        .trim()
+        .split(TEXT_PATTERNS.WHITESPACE)
+        .map((word) => word.charAt(0).toUpperCase())
+        .slice(0, MAX_INITIALS_LENGTH)
+        .join('')
+}
+
+export function sanitizeTextForLabel(text: string): string {
+    if (!text) {
+        return ''
+    }
+    return text.trim().replace(TEXT_PATTERNS.WHITESPACE, ' ')
+}
+
+export function renderFallbackContent(
+    fallbackText?: string,
+    alt?: string
+): ReactNode {
+    if (fallbackText !== undefined) {
+        if (typeof fallbackText === 'string') {
+            return fallbackText.substring(0, MAX_INITIALS_LENGTH).toUpperCase()
+        }
+        return fallbackText
+    }
+    return getInitialsFromText(alt)
+}
+
+function hashString(str: string): number {
+    let hash = 0
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i)
+        hash = (hash << 5) - hash + char
+        hash = hash & hash
+    }
+    return Math.abs(hash)
+}
+
+export function getColorFromText(text: string): string {
+    if (!text || text.trim() === '') {
+        return DEFAULT_FALLBACK_COLOR
+    }
+
+    const normalizedText = text.trim().toLowerCase()
+    const hash = hashString(normalizedText)
+    const colorIndex = hash % AVATAR_COLOR_PALETTE.length
+
+    return AVATAR_COLOR_PALETTE[colorIndex]
+}
+
+export function getAccessibleLabel(
+    alt: string,
+    fallbackText: string | undefined,
+    status: string
+): string {
+    const name =
+        alt ||
+        (typeof fallbackText === 'string' ? fallbackText : DEFAULT_AVATAR_ALT)
+    const sanitizedName = sanitizeTextForLabel(name)
+
+    if (!status || status === AvatarV2Status.NONE) {
+        return sanitizedName
+    }
+
+    const statusText = status
+        .replace(TEXT_PATTERNS.CAPITAL_LETTERS, ' $1')
+        .trim()
+        .toLowerCase()
+
+    return `${sanitizedName}, ${statusText}`
+}
+
+export function getAriaLiveValue(status: string): 'polite' | undefined {
+    if (status && status !== AvatarV2Status.NONE) {
+        return 'polite'
+    }
+    return undefined
+}
+
+export function getStatusPositionStyles(
+    position: AvatarV2StatusPosition,
+    size: AvatarV2Size,
+    shape: AvatarV2Shape,
+    tokens: AvatarV2TokensType
+): { top?: string; right?: string; bottom?: string; left?: string } {
+    const basePosition =
+        tokens.container.status.position[shape]?.[size] || DEFAULT_POSITION
+
+    const top = basePosition.top?.toString()
+    const right = basePosition.right?.toString()
+    const bottom = basePosition.bottom?.toString()
+
+    switch (position) {
+        case AvatarV2StatusPosition.TOP_RIGHT:
+            return { top, right }
+        case AvatarV2StatusPosition.TOP_LEFT:
+            return { top, left: right }
+        case AvatarV2StatusPosition.BOTTOM_RIGHT:
+            return { bottom, right }
+        case AvatarV2StatusPosition.BOTTOM_LEFT:
+            return { bottom, left: right }
+        default:
+            return { top, right }
+    }
+}
+export function createKeyboardHandler(
+    onClick: ((event: React.MouseEvent<HTMLDivElement>) => void) | undefined
+) {
+    if (!onClick) {
+        return undefined
+    }
+
+    return (e: React.KeyboardEvent<HTMLDivElement>) => {
+        if (e.key === KEYBOARD_KEYS.ENTER || e.key === KEYBOARD_KEYS.SPACE) {
+            e.preventDefault()
+            e.stopPropagation()
+
+            const syntheticEvent = {
+                ...e,
+                currentTarget: e.currentTarget,
+                target: e.target,
+                button: SYNTHETIC_EVENT_DEFAULTS.BUTTON,
+                buttons: SYNTHETIC_EVENT_DEFAULTS.BUTTONS,
+                clientX: SYNTHETIC_EVENT_DEFAULTS.CLIENT_X,
+                clientY: SYNTHETIC_EVENT_DEFAULTS.CLIENT_Y,
+                pageX: SYNTHETIC_EVENT_DEFAULTS.PAGE_X,
+                pageY: SYNTHETIC_EVENT_DEFAULTS.PAGE_Y,
+                screenX: SYNTHETIC_EVENT_DEFAULTS.SCREEN_X,
+                screenY: SYNTHETIC_EVENT_DEFAULTS.SCREEN_Y,
+                relatedTarget: null,
+                movementX: SYNTHETIC_EVENT_DEFAULTS.MOVEMENT_X,
+                movementY: SYNTHETIC_EVENT_DEFAULTS.MOVEMENT_Y,
+                nativeEvent: e.nativeEvent,
+                bubbles: SYNTHETIC_EVENT_DEFAULTS.BUBBLES,
+                cancelable: SYNTHETIC_EVENT_DEFAULTS.CANCELABLE,
+                defaultPrevented: SYNTHETIC_EVENT_DEFAULTS.DEFAULT_PREVENTED,
+                eventPhase: SYNTHETIC_EVENT_DEFAULTS.EVENT_PHASE,
+                isTrusted: SYNTHETIC_EVENT_DEFAULTS.IS_TRUSTED,
+                timeStamp: Date.now(),
+                type: SYNTHETIC_EVENT_DEFAULTS.TYPE,
+            } as unknown as React.MouseEvent<HTMLDivElement>
+
+            onClick(syntheticEvent)
+        }
+    }
+}
+
+export function isInteractive(
+    onClick: ((event: React.MouseEvent<HTMLDivElement>) => void) | undefined
+): boolean {
+    return onClick !== undefined
+}

package/lib/components/AvatarV2/index.ts

@@ -0,0 +1,15 @@
+export { default as AvatarV2 } from './AvatarV2'
+export type {
+    AvatarV2Props,
+    AvatarV2SkeletonConfig,
+    AvatarV2StatusConfig,
+} from './avatarV2.types'
+export {
+    AvatarV2Size,
+    AvatarV2Shape,
+    AvatarV2Status,
+    AvatarV2StatusPosition,
+    AvatarV2Variant,
+} from './avatarV2.types'
+export * from './avatarV2.tokens'
+export * from './avatarV2.utils'

package/lib/components/Badge/Badge.tsx

@@ -0,0 +1,169 @@
+import { forwardRef, useMemo } from 'react'
+import { useResponsiveTokens } from '../../hooks/useResponsiveTokens'
+import Block from '../Primitives/Block/Block'
+import Text from '../Text/Text'
+import { filterBlockedProps } from '../../utils/prop-helpers'
+import { BadgeColor, BadgeProps, BadgeSize } from './Badge.types'
+import { BadgeTokensType } from './badge.tokens'
+import {
+    formatCount,
+    getAccessibleLabel,
+    getPositionStyles,
+} from './badge.utils'
+
+const BadgeContent = forwardRef<
+    HTMLSpanElement,
+    Omit<BadgeProps, 'position' | 'offset'>
+>(
+    (
+        {
+            count,
+            maxCount = 99,
+            size = BadgeSize.MD,
+            color = BadgeColor.ALERT,
+            text,
+            showBadge = true,
+            showZero = false,
+            ...rest
+        },
+        ref
+    ) => {
+        const tokens = useResponsiveTokens<BadgeTokensType>('BADGE')
+        const filteredRest = filterBlockedProps(rest)
+
+        // Hide badge when count is 0 and showZero is false
+        const effectiveShowBadge = useMemo(() => {
+            if (!showBadge) return false
+            if (count === 0 && !showZero) return false
+            return true
+        }, [showBadge, count, showZero])
+
+        const displayText = useMemo(() => {
+            if (text) return text
+            if (count !== undefined) return formatCount(count, maxCount)
+            return ''
+        }, [count, maxCount, text])
+
+        // Determine if this should be a dot (no content) or pill (has content)
+        const hasContent = displayText !== ''
+
+        if (!effectiveShowBadge) return null
+
+        const ariaLabel = getAccessibleLabel(
+            count,
+            text,
+            maxCount,
+            effectiveShowBadge
+        )
+
+        if (!hasContent) {
+            return (
+                <Block
+                    // Block is typed as HTMLDivElement but renders as span via `as` prop.
+                    // Cast is intentional — ref still points to the correct DOM node at runtime.
+                    ref={ref as React.Ref<HTMLDivElement>}
+                    as="span"
+                    role="status"
+                    aria-label={ariaLabel}
+                    data-badge="dot"
+                    display="inline-block"
+                    width={tokens.dot.width[size]}
+                    height={tokens.dot.height[size]}
+                    backgroundColor={tokens.backgroundColor[color]}
+                    borderRadius={tokens.dot.borderRadius}
+                    {...filteredRest}
+                />
+            )
+        }
+
+        return (
+            <Block
+                // Block is typed as HTMLDivElement but renders as span via `as` prop.
+                // Cast is intentional — ref still points to the correct DOM node at runtime.
+                ref={ref as React.Ref<HTMLDivElement>}
+                as="span"
+                role="status"
+                aria-label={ariaLabel}
+                data-badge="pill"
+                data-content={displayText}
+                display="inline-flex"
+                alignItems="center"
+                justifyContent="center"
+                minWidth={tokens.pill.minWidth[size]}
+                height={tokens.pill.height[size]}
+                paddingLeft={tokens.pill.paddingLeft[size]}
+                paddingRight={tokens.pill.paddingRight[size]}
+                backgroundColor={tokens.backgroundColor[color]}
+                borderRadius={tokens.pill.borderRadius[size]}
+                {...filteredRest}
+            >
+                <Text
+                    as="span"
+                    data-id={displayText}
+                    color={tokens.text.color}
+                    fontSize={tokens.text.fontSize[size]}
+                    fontWeight={tokens.text.fontWeight}
+                    lineHeight={tokens.text.lineHeight[size]}
+                >
+                    {displayText}
+                </Text>
+            </Block>
+        )
+    }
+)
+
+BadgeContent.displayName = 'BadgeContent'
+
+const Badge = forwardRef<HTMLSpanElement, BadgeProps>((props, ref) => {
+    const tokens = useResponsiveTokens<BadgeTokensType>('BADGE')
+
+    // If no children, render standalone badge
+    if (props.children === undefined) {
+        const { size = BadgeSize.MD, ...rest } = props
+        const filteredRest = filterBlockedProps(rest)
+        return <BadgeContent ref={ref} size={size} {...filteredRest} />
+    }
+
+    // If children provided, wrap with relative positioning
+    const {
+        children,
+        size = BadgeSize.MD,
+        position = 'top-right',
+        offset,
+        isCircular = false,
+        ...rest
+    } = props
+    const filteredRest = filterBlockedProps(rest)
+
+    // Determine if this should be a dot (no content) or pill (has content) for positioning
+    const hasContent =
+        filteredRest.count !== undefined ||
+        (filteredRest.text !== undefined && filteredRest.text !== '')
+    const positionStyles = getPositionStyles(
+        position,
+        size,
+        tokens,
+        offset,
+        hasContent,
+        isCircular
+    )
+
+    return (
+        <Block
+            as="span"
+            display="inline-flex"
+            position="relative"
+            data-badge-wrapper="true"
+            data-circular={isCircular}
+        >
+            {children}
+            <Block as="span" position="absolute" {...positionStyles}>
+                <BadgeContent ref={ref} size={size} {...filteredRest} />
+            </Block>
+        </Block>
+    )
+})
+
+Badge.displayName = 'Badge'
+
+export default Badge

package/lib/components/Badge/Badge.types.ts

@@ -0,0 +1,47 @@
+import type { ReactElement } from 'react'
+
+export enum BadgeColor {
+    ALERT = 'alert',
+    NEUTRAL = 'neutral',
+    WARNING = 'warning',
+    PRIMARY = 'primary',
+    SUCCESS = 'success',
+}
+
+export enum BadgeSize {
+    SM = 'sm',
+    MD = 'md',
+    LG = 'lg',
+}
+
+export type BadgePosition =
+    | 'top-right'
+    | 'top-left'
+    | 'bottom-right'
+    | 'bottom-left'
+
+type BaseBadgeProps = {
+    count?: number
+    maxCount?: number
+    size?: BadgeSize
+    color?: BadgeColor
+    text?: string
+    showBadge?: boolean
+    showZero?: boolean
+} & Omit<
+    React.HTMLAttributes<HTMLSpanElement>,
+    'size' | 'className' | 'style' | 'children'
+>
+
+type StandaloneBadgeProps = BaseBadgeProps & {
+    children?: undefined
+}
+
+type PositionedBadgeProps = BaseBadgeProps & {
+    children: ReactElement
+    position?: BadgePosition
+    offset?: [number, number]
+    isCircular?: boolean
+}
+
+export type BadgeProps = StandaloneBadgeProps | PositionedBadgeProps