blend-native 0.0.1-beta.0 → 0.0.1-beta.2

package/src/components/Avatar/Avatar.tsx

@@ -0,0 +1,225 @@
+import { forwardRef, useEffect, useState } from 'react'
+import { Image, View } from 'react-native'
+import type { View as RNView } from 'react-native'
+import {
+    AvatarV2Shape,
+    AvatarV2Size,
+    AvatarV2Status,
+    AvatarV2StatusPosition,
+    getColorFromText,
+} from '@juspay/blend-design-system/node'
+import type { AvatarV2TokensType } from '@juspay/blend-design-system/node'
+import { useNativeTokens } from '../../theme/useNativeTokens'
+import {
+    parseBorder,
+    parseBorderRadius,
+    parseBoxShadow,
+    parseDimension,
+    parseSize,
+} from '../../adapters/cssStringAdapter'
+import Text from '../../primitives/Text'
+import { Skeleton } from '../Skeleton'
+import type { AvatarNativeProps } from './avatar.types'
+import {
+    getAvatarAccessibleLabel,
+    getInitials,
+    resolveStatusPosition,
+} from './avatar.utils'
+
+/**
+ * Avatar — the native port of web's `AvatarV2`.
+ *
+ * RN `Image` with the same fallback pipeline: a load error (reset when
+ * `src` changes, web parity) swaps in initials over the shared
+ * hash-palette color, so both platforms render the same fallback for the
+ * same name. The status dot is a token-positioned absolute view, hidden
+ * from assistive tech with the status folded into the accessible name.
+ */
+const Avatar = forwardRef<RNView, AvatarNativeProps>(function Avatar(
+    {
+        src,
+        alt,
+        fallbackText,
+        size = AvatarV2Size.MD,
+        shape = AvatarV2Shape.CIRCULAR,
+        status,
+        leftSlot,
+        rightSlot,
+        skeleton,
+        backgroundColor,
+        width,
+        height,
+        onImageError,
+        accessibilityLabel,
+        testID,
+        style,
+    },
+    ref
+) {
+    const tokens = useNativeTokens<AvatarV2TokensType>('AVATARV2')
+
+    const [imageError, setImageError] = useState(false)
+    // Retry when the source changes after a failure — web parity.
+    useEffect(() => setImageError(false), [src])
+    const hasImage = Boolean(src) && !imageError
+
+    const resolvedWidth =
+        parseSize(width) ??
+        parseSize(tokens.container.width[size] as string | number) ??
+        40
+    const resolvedHeight =
+        parseSize(height) ??
+        parseSize(tokens.container.height[size] as string | number) ??
+        40
+    const radius =
+        parseBorderRadius(
+            tokens.container.borderRadius[shape] as string | number
+        ) ?? 9999
+    const radiusStyle =
+        typeof radius === 'number' ? { borderRadius: radius } : radius
+
+    const statusType = status?.type ?? AvatarV2Status.NONE
+    const showStatus =
+        status !== undefined && statusType !== AvatarV2Status.NONE
+
+    const label =
+        accessibilityLabel ??
+        getAvatarAccessibleLabel(alt, showStatus ? statusType : undefined)
+
+    if (skeleton?.show) {
+        return (
+            <Skeleton
+                width={resolvedWidth}
+                height={resolvedHeight}
+                shape={shape === AvatarV2Shape.CIRCULAR ? 'circle' : 'rounded'}
+                variant={skeleton.variant}
+                testID={testID}
+            />
+        )
+    }
+
+    const slotted = Boolean(leftSlot || rightSlot)
+
+    const container = (
+        <View
+            ref={slotted ? undefined : ref}
+            accessible
+            accessibilityRole="image"
+            accessibilityLabel={label}
+            testID={testID}
+            style={[
+                {
+                    width: resolvedWidth,
+                    height: resolvedHeight,
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    backgroundColor: hasImage
+                        ? String(tokens.container.backgroundColor)
+                        : (backgroundColor ??
+                          getColorFromText(fallbackText ?? alt ?? '')),
+                    ...radiusStyle,
+                },
+                slotted ? undefined : style,
+            ]}
+        >
+            {hasImage ? (
+                <Image
+                    source={{ uri: src as string }}
+                    resizeMode="cover"
+                    onError={() => {
+                        setImageError(true)
+                        onImageError?.()
+                    }}
+                    style={{ width: '100%', height: '100%', ...radiusStyle }}
+                    testID={testID ? `${testID}-image` : undefined}
+                />
+            ) : (
+                <Text
+                    fontSize={
+                        tokens.container.fallbackText.fontSize[size] as
+                            | string
+                            | number
+                    }
+                    fontWeight={
+                        tokens.container.fallbackText.fontWeight[size] as
+                            | string
+                            | number
+                    }
+                    color={String(tokens.container.fallbackText.color)}
+                    aria-hidden
+                    testID={testID ? `${testID}-fallback` : undefined}
+                >
+                    {getInitials(fallbackText, alt)}
+                </Text>
+            )}
+            {showStatus && (
+                <View
+                    accessible={false}
+                    importantForAccessibility="no-hide-descendants"
+                    accessibilityElementsHidden
+                    testID={testID ? `${testID}-status` : undefined}
+                    style={[
+                        {
+                            position: 'absolute',
+                            width:
+                                parseDimension(
+                                    tokens.container.status.width[size] as
+                                        | string
+                                        | number
+                                ) ?? 8,
+                            height:
+                                parseDimension(
+                                    tokens.container.status.height[size] as
+                                        | string
+                                        | number
+                                ) ?? 8,
+                            borderRadius: 9999,
+                            backgroundColor: String(
+                                tokens.container.status.backgroundColor[
+                                    statusType
+                                ]
+                            ),
+                            ...parseBorder(
+                                String(tokens.container.status.border[size])
+                            ),
+                            ...(parseBoxShadow(
+                                String(tokens.container.status.boxShadow)
+                            ) ?? {}),
+                        },
+                        resolveStatusPosition(
+                            tokens,
+                            shape,
+                            size,
+                            status?.position ??
+                                AvatarV2StatusPosition.BOTTOM_RIGHT
+                        ),
+                    ]}
+                />
+            )}
+        </View>
+    )
+
+    if (!slotted) return container
+
+    return (
+        <View
+            ref={ref}
+            style={[
+                {
+                    flexDirection: 'row',
+                    alignItems: 'center',
+                    gap: parseDimension(tokens.gap as string | number) ?? 8,
+                },
+                style,
+            ]}
+        >
+            {leftSlot}
+            {container}
+            {rightSlot}
+        </View>
+    )
+})
+
+Avatar.displayName = 'Avatar'
+
+export default Avatar

package/src/components/Avatar/avatar.types.ts

@@ -0,0 +1,56 @@
+import type React from 'react'
+import type { StyleProp, ViewStyle } from 'react-native'
+import type {
+    AvatarV2Shape,
+    AvatarV2Size,
+    AvatarV2Status,
+    AvatarV2StatusPosition,
+    SkeletonVariant,
+} from '@juspay/blend-design-system/node'
+
+/**
+ * Props for the native `Avatar` — the port of web's `AvatarV2`.
+ *
+ * DOM pieces swapped for RN ones: the `<img>` becomes RN `Image` with its
+ * error event driving the initials fallback, and the fallback color comes
+ * from the same hash palette (`getColorFromText`, imported from `/node` so
+ * both platforms hash identically).
+ *
+ * Deliberately omitted rather than accepted-and-ignored (the `skeleton`
+ * precedent — a compile error, not a no-op):
+ *
+ * - Interactive click/keyboard behaviour — web's core AvatarV2 has no
+ *   `onClick` prop either (it arrives via the HTMLAttributes spread);
+ *   wrap in a `Pressable` when needed.
+ * - `onImageLoad` — RN's load event carries no web-compatible payload;
+ *   add when a consumer needs it.
+ */
+export type AvatarStatus = {
+    type: AvatarV2Status
+    position?: AvatarV2StatusPosition
+}
+
+export type AvatarNativeProps = {
+    /** Image URI. On load failure the initials fallback renders. */
+    src?: string
+    /** Accessible name, and the source of the fallback initials. */
+    alt?: string
+    /** Overrides the initials derived from `alt` (first two characters). */
+    fallbackText?: string
+    size?: AvatarV2Size
+    shape?: AvatarV2Shape
+    status?: AvatarStatus
+    leftSlot?: React.ReactNode
+    rightSlot?: React.ReactNode
+    skeleton?: { show: boolean; variant?: SkeletonVariant }
+    /** Overrides the hash-palette fallback background. */
+    backgroundColor?: string
+    /** Override the size tokens (web's AvatarV2Dimensions). */
+    width?: string | number
+    height?: string | number
+    /** Called when the image fails and the fallback takes over. */
+    onImageError?: () => void
+    accessibilityLabel?: string
+    testID?: string
+    style?: StyleProp<ViewStyle>
+}

package/src/components/Avatar/avatar.utils.ts

@@ -0,0 +1,70 @@
+import type { ViewStyle } from 'react-native'
+import {
+    AvatarV2Status,
+    AvatarV2StatusPosition,
+    getInitialsFromText,
+} from '@juspay/blend-design-system/node'
+import type {
+    AvatarV2Shape,
+    AvatarV2Size,
+    AvatarV2TokensType,
+} from '@juspay/blend-design-system/node'
+import { parseDimension } from '../../adapters/cssStringAdapter'
+
+/**
+ * Corner offsets for the status dot. The tokens carry per-shape/size
+ * `{ top, right, bottom }` offsets (fractional and negative px strings —
+ * `parseDimension` handles both); web derives `left` by reusing `right`,
+ * mirrored here.
+ */
+export function resolveStatusPosition(
+    tokens: AvatarV2TokensType,
+    shape: AvatarV2Shape,
+    size: AvatarV2Size,
+    position: AvatarV2StatusPosition
+): ViewStyle {
+    const offsets = tokens.container.status.position[shape]?.[size] ?? {}
+    const top = parseDimension(offsets.top as string | number | undefined)
+    const right = parseDimension(offsets.right as string | number | undefined)
+    const bottom = parseDimension(offsets.bottom as string | number | undefined)
+
+    switch (position) {
+        case AvatarV2StatusPosition.TOP_RIGHT:
+            return { top, right }
+        case AvatarV2StatusPosition.TOP_LEFT:
+            return { top, left: right }
+        case AvatarV2StatusPosition.BOTTOM_LEFT:
+            return { bottom, left: right }
+        case AvatarV2StatusPosition.BOTTOM_RIGHT:
+        default:
+            return { bottom, right }
+    }
+}
+
+/**
+ * Web's `renderFallbackContent` text branch: an explicit `fallbackText`
+ * wins (first two characters), otherwise initials derive from `alt` via
+ * the shared `/node` helper so both platforms agree.
+ */
+export function getInitials(
+    fallbackText: string | undefined,
+    alt: string | undefined
+): string {
+    if (fallbackText !== undefined) {
+        return fallbackText.substring(0, 2).toUpperCase()
+    }
+    return getInitialsFromText(alt)
+}
+
+/**
+ * Web's `getAccessibleLabel`: the name plus the status, so "Jane Doe,
+ * online" reads in one announcement.
+ */
+export function getAvatarAccessibleLabel(
+    alt: string | undefined,
+    status: AvatarV2Status | undefined
+): string {
+    const name = alt?.trim() || 'Avatar'
+    if (!status || status === AvatarV2Status.NONE) return name
+    return `${name}, ${status}`
+}

package/src/components/Avatar/index.ts

@@ -0,0 +1,7 @@
+export { default as Avatar } from './Avatar'
+export type { AvatarNativeProps, AvatarStatus } from './avatar.types'
+export {
+    getInitials,
+    getAvatarAccessibleLabel,
+    resolveStatusPosition,
+} from './avatar.utils'

package/src/components/Badge/Badge.tsx

@@ -0,0 +1,183 @@
+import { useMemo, useState } from 'react'
+import { View } from 'react-native'
+import type { LayoutChangeEvent } from 'react-native'
+import {
+    BadgeColor,
+    BadgeSize,
+    type BadgeTokensType,
+} from '@juspay/blend-design-system/node'
+import { useNativeTokens } from '../../theme/useNativeTokens'
+import {
+    parseBorderRadius,
+    parseDimension,
+} from '../../adapters/cssStringAdapter'
+import Block from '../../primitives/Block'
+import Text from '../../primitives/Text'
+import type { BadgeNativeProps } from './badge.types'
+import {
+    formatCount,
+    getBadgeAccessibleLabel,
+    resolvePositionInsets,
+} from './badge.utils'
+
+/**
+ * Badge — the native port of web's `Badge`.
+ *
+ * A dot (no count/text) or a pill (count/text), standalone or hung off a
+ * child's corner. Web overlays the child with CSS
+ * `transform: translate(±50%, ±50%)`; RN cannot translate by own-size
+ * percentages, so `resolvePositionInsets` folds the same overhang into
+ * edge insets (documented divergence, see `badge.utils.ts`).
+ */
+export function Badge({
+    count,
+    maxCount = 99,
+    size = BadgeSize.MD,
+    color = BadgeColor.ALERT,
+    text,
+    showBadge = true,
+    showZero = false,
+    position = 'top-right',
+    offset,
+    isCircular = false,
+    accessibilityLabel,
+    testID,
+    style,
+    children,
+}: BadgeNativeProps) {
+    const tokens = useNativeTokens<BadgeTokensType>('BADGE')
+
+    // The circular overlay places the badge on the child's 45°
+    // circumference — a percentage of the wrapper's own size, measurable
+    // only post-layout, so the wrapper reports it through `onLayout`.
+    // Declared at the top: the standalone branch returns early below, and a
+    // hook after an early return breaks the hook order (the playground
+    // toggles between the two shapes).
+    const [parentSize, setParentSize] = useState<{
+        width: number
+        height: number
+    } | null>(null)
+    const onWrapperLayout = (event: LayoutChangeEvent) => {
+        const { width, height } = event.nativeEvent.layout
+        setParentSize((prev) =>
+            prev && prev.width === width && prev.height === height
+                ? prev
+                : { width, height }
+        )
+    }
+
+    // Hide badge when count is 0 and showZero is false — web parity.
+    const effectiveShowBadge = showBadge && !(count === 0 && !showZero)
+
+    const displayText =
+        text ?? (count !== undefined ? formatCount(count, maxCount) : '')
+    const hasContent = displayText !== ''
+
+    const label =
+        accessibilityLabel ??
+        getBadgeAccessibleLabel(count, text, maxCount, effectiveShowBadge)
+
+    const dotOrPill = useMemo(() => {
+        if (!effectiveShowBadge) return null
+
+        if (!hasContent) {
+            const radius = parseBorderRadius(
+                tokens.dot.borderRadius as string | number
+            )
+            const radiusStyle =
+                typeof radius === 'number' ? { borderRadius: radius } : radius
+            return (
+                <View
+                    accessible={false}
+                    importantForAccessibility="no-hide-descendants"
+                    accessibilityElementsHidden
+                    testID={testID ? `${testID}-dot` : undefined}
+                    style={{
+                        width: parseDimension(
+                            tokens.dot.width[size] as string | number
+                        ),
+                        height: parseDimension(
+                            tokens.dot.height[size] as string | number
+                        ),
+                        backgroundColor: String(tokens.backgroundColor[color]),
+                        ...radiusStyle,
+                    }}
+                />
+            )
+        }
+
+        return (
+            <Block
+                accessible
+                accessibilityRole="text"
+                accessibilityLabel={label}
+                testID={testID}
+                minWidth={tokens.pill.minWidth[size] as string | number}
+                height={tokens.pill.height[size] as string | number}
+                paddingLeft={tokens.pill.paddingLeft[size] as string | number}
+                paddingRight={tokens.pill.paddingRight[size] as string | number}
+                backgroundColor={String(tokens.backgroundColor[color])}
+                borderRadius={tokens.pill.borderRadius[size] as string | number}
+                alignItems="center"
+                justifyContent="center"
+                style={style}
+            >
+                <Text
+                    fontSize={tokens.text.fontSize[size] as string | number}
+                    fontWeight={tokens.text.fontWeight as string | number}
+                    lineHeight={tokens.text.lineHeight[size] as string | number}
+                    color={String(tokens.text.color)}
+                    testID={testID ? `${testID}-text` : undefined}
+                >
+                    {displayText}
+                </Text>
+            </Block>
+        )
+    }, [
+        effectiveShowBadge,
+        hasContent,
+        tokens,
+        size,
+        color,
+        label,
+        testID,
+        style,
+        displayText,
+    ])
+
+    // Standalone badge (no children).
+    if (children === undefined) return dotOrPill
+
+    // Wrapped: badge hung off the child's corner.
+    const insets = resolvePositionInsets(position, size, tokens, {
+        customOffset: offset,
+        hasContent,
+        isCircular,
+        parentSize: parentSize ?? undefined,
+    })
+
+    return (
+        <View
+            style={[{ alignSelf: 'center' }, style]}
+            onLayout={isCircular ? onWrapperLayout : undefined}
+        >
+            {children}
+            {effectiveShowBadge && (
+                <View
+                    pointerEvents="none"
+                    accessible={false}
+                    importantForAccessibility="no-hide-descendants"
+                    accessibilityElementsHidden
+                    style={{ position: 'absolute', ...insets }}
+                    testID={testID ? `${testID}-anchor` : undefined}
+                >
+                    {dotOrPill}
+                </View>
+            )}
+        </View>
+    )
+}
+
+Badge.displayName = 'Badge'
+
+export default Badge

package/src/components/Badge/badge.types.ts

@@ -0,0 +1,54 @@
+import type React from 'react'
+import type { StyleProp, ViewStyle } from 'react-native'
+import type {
+    BadgeColor,
+    BadgePosition,
+    BadgeSize,
+} from '@juspay/blend-design-system/node'
+
+/**
+ * Props for the native `Badge` — the port of web's `Badge` (V1 generation).
+ *
+ * Renders a dot (no count/text) or a pill (count/text), either standalone
+ * or — when `children` is supplied — absolutely positioned over the child's
+ * corner, like an unread counter on an Avatar.
+ *
+ * Deliberately omitted rather than accepted-and-ignored:
+ *
+ * - The DOM `HTMLAttributes` spread web's `BaseBadgeProps` carries — RN
+ *   Views have no `onMouseEnter`/`aria-*` passthroughs; `accessibilityLabel`
+ *   and `testID` cover the native equivalents.
+ *
+ * Positioning divergence (documented): web hangs the badge half its size
+ * past the corner via CSS `transform: translate(±50%, ±50%)`. RN has no
+ * percentage translate against own-size, so native computes the same
+ * overhang as **edge insets** — see `resolvePositionInsets`.
+ */
+export type BadgeBaseProps = {
+    /** Count to display. Overflows `maxCount` as `"99+"`. */
+    count?: number
+    /** Cap before the count renders as `"{maxCount}+"`. Defaults to 99. */
+    maxCount?: number
+    size?: BadgeSize
+    color?: BadgeColor
+    /** Overrides the count as the pill's content. */
+    text?: string
+    /** Force-hide the badge. */
+    showBadge?: boolean
+    /** Render even when `count` is 0. */
+    showZero?: boolean
+}
+
+export type BadgeNativeProps = BadgeBaseProps & {
+    /** Provide to hang the badge off the child's corner instead. */
+    children?: React.ReactNode
+    /** Corner to hang the badge off. Only meaningful with `children`. */
+    position?: BadgePosition
+    /** Extra `[x, y]` shift from the corner, in points. */
+    offset?: [number, number]
+    /** Treat the child as circular: badge sits on the 45° circumference. */
+    isCircular?: boolean
+    accessibilityLabel?: string
+    testID?: string
+    style?: StyleProp<ViewStyle>
+}