blend-native 0.0.1-beta.0

package/src/components/Alert/Alert.tsx

@@ -0,0 +1,167 @@
+import { forwardRef, useMemo } from 'react'
+import type { View as RNView } from 'react-native'
+import {
+    AlertV2ActionPosition,
+    AlertV2SubType,
+    AlertV2Type,
+    type AlertV2TokensType,
+} from '@juspay/blend-design-system/node'
+import { useNativeTokens } from '../../theme/useNativeTokens'
+import { Block } from '../../primitives/Block'
+import { Separator } from '../../primitives/Separator'
+import { Slot } from '../../primitives/Slot'
+import { buildAnnouncement } from '../../a11y/announcement'
+import { useLiveRegionAnnounce } from '../../a11y/useLiveRegion'
+import { AlertActions } from './AlertActions'
+import { AlertClose } from './AlertClose'
+import { AlertText } from './AlertText'
+import {
+    ALERT_FLEX_BOX,
+    getAlertLayout,
+    getCloseIconSize,
+    shouldShowSeparator,
+} from './alert.utils'
+import type { AlertNativeProps } from './alert.types'
+
+/**
+ * Alert — React Native implementation of web's `AlertV2`.
+ *
+ * Tokens resolve through `useNativeTokens('ALERTV2')`, so theme and per-slot
+ * overrides come from `BlendNativeProvider`.
+ *
+ * AlertV2's tokens contain no gradients, so this needs no native module beyond
+ * the icon set.
+ */
+const Alert = forwardRef<RNView, AlertNativeProps>(function Alert(
+    {
+        type = AlertV2Type.PRIMARY,
+        subType = AlertV2SubType.SUBTLE,
+        slot,
+        heading,
+        description,
+        actions,
+        closeButton = { show: true },
+        width,
+        maxWidth,
+        minWidth,
+        announce = true,
+        accessibilityLabel,
+        testID,
+        style,
+    },
+    ref
+) {
+    const tokens = useNativeTokens<AlertV2TokensType>('ALERTV2')
+
+    const position = actions?.position ?? AlertV2ActionPosition.BOTTOM
+    const layout = useMemo(() => getAlertLayout(position), [position])
+
+    const closeShown = Boolean(closeButton?.show)
+    const showSeparator = shouldShowSeparator(position, closeShown)
+
+    // Web hard-codes `aria-live="assertive"` + `aria-atomic`. Android reads the
+    // region itself via `accessibilityLiveRegion`; iOS has no live-region
+    // support, so the composed sentence is announced imperatively.
+    const announcement = useMemo(
+        () => buildAnnouncement(heading, description),
+        [heading, description]
+    )
+    useLiveRegionAnnounce(announcement, announce)
+
+    const hasText = Boolean(heading || description)
+
+    return (
+        <Block
+            ref={ref}
+            testID={testID}
+            // NOTE: `accessible` is deliberately NOT set here.
+            //
+            // In RN, marking a View as an accessibility element "groups its
+            // children into a single selectable component" — which on iOS makes
+            // the action links and the close button individually unreachable by
+            // VoiceOver. Web has no such problem: `role="alert"` does not affect
+            // whether nested buttons can be focused.
+            //
+            // `accessibilityRole="alert"` conveys the semantic without
+            // collapsing the subtree, and each child keeps its own label.
+            accessibilityRole="alert"
+            accessibilityLabel={accessibilityLabel}
+            accessibilityLiveRegion={announce ? 'assertive' : 'none'}
+            flexDirection="row"
+            alignItems="center"
+            width={width ?? tokens.width}
+            maxWidth={maxWidth ?? tokens.maxWidth}
+            minWidth={minWidth ?? tokens.minWidth}
+            border={String(tokens.border[type][subType])}
+            borderRadius={tokens.borderRadius}
+            backgroundColor={String(tokens.backgroundColor[type][subType])}
+            paddingTop={tokens.padding.top}
+            paddingBottom={tokens.padding.bottom}
+            paddingLeft={tokens.padding.left}
+            paddingRight={tokens.padding.right}
+            gap={tokens.gap[position]}
+            style={style}
+        >
+            {/* `ALERT_FLEX_BOX` sets flexShrink explicitly — Yoga defaults it
+                to 0 where CSS defaults it to 1, so without it these boxes size
+                to their content and a long description clips instead of
+                wrapping. */}
+            <Block
+                {...ALERT_FLEX_BOX}
+                flexDirection="row"
+                gap={tokens.mainContainer.gap}
+            >
+                {slot?.slot ? (
+                    <Slot
+                        maxHeight={slot.maxHeight ?? tokens.slot.maxHeight}
+                        hidden={hasText}
+                        testID={testID ? `${testID}-slot` : undefined}
+                    >
+                        {slot.slot}
+                    </Slot>
+                ) : null}
+
+                <Block
+                    {...ALERT_FLEX_BOX}
+                    flexDirection={layout.contentDirection}
+                    justifyContent={layout.contentJustify}
+                    alignItems={layout.contentAlign}
+                    gap={tokens.mainContainer.content.gap[position]}
+                >
+                    <AlertText
+                        heading={heading}
+                        description={description}
+                        type={type}
+                        tokens={tokens.mainContainer.content.textContainer}
+                    />
+                    <AlertActions
+                        actions={actions}
+                        type={type}
+                        tokens={tokens.mainContainer.content.actionContainer}
+                        testID={testID}
+                    />
+                </Block>
+            </Block>
+
+            {showSeparator ? (
+                <Separator
+                    testID={testID ? `${testID}-separator` : undefined}
+                />
+            ) : null}
+
+            {closeShown ? (
+                <AlertClose
+                    closeButton={closeButton}
+                    color={String(tokens.mainContainer.closeButton.color[type])}
+                    size={getCloseIconSize(tokens)}
+                    alignSelf={layout.closeAlign}
+                    testID={testID ? `${testID}-close` : undefined}
+                />
+            ) : null}
+        </Block>
+    )
+})
+
+Alert.displayName = 'Alert'
+
+export default Alert

package/src/components/Alert/AlertActions.tsx

@@ -0,0 +1,98 @@
+import { memo } from 'react'
+import type { AlertV2Type } from '@juspay/blend-design-system/node'
+import { Block } from '../../primitives/Block'
+import { Pressable } from '../../primitives/Pressable'
+import { Text } from '../../primitives/Text'
+import { getActionAccessibilityLabel } from './alert.utils'
+import type {
+    AlertActionTokens,
+    AlertActionVariantTokens,
+} from './alert.tokens'
+import type {
+    AlertAction,
+    AlertActions as AlertActionsConfig,
+} from './alert.types'
+
+/**
+ * `Alert`'s action row.
+ *
+ * These are **text links**, not `Button`s: web renders them as a bare
+ * `PrimitiveButton` with no border or background, so native composes
+ * `Pressable` + `Text` rather than reusing the `Button` component.
+ */
+
+type ActionLinkProps = {
+    action: AlertAction
+    type: AlertV2Type
+    tokens: AlertActionVariantTokens
+    testID?: string
+}
+
+function ActionLink({ action, type, tokens, testID }: ActionLinkProps) {
+    return (
+        <Pressable
+            onPress={action.onPress}
+            accessibilityRole="button"
+            accessibilityLabel={getActionAccessibilityLabel(
+                action.text,
+                action.accessibilityLabel
+            )}
+            testID={testID}
+            alignSelf="flex-start"
+        >
+            <Text
+                fontSize={tokens.fontSize}
+                fontWeight={tokens.fontWeight}
+                lineHeight={tokens.lineHeight}
+                color={String(tokens.color[type])}
+                // Web sets `white-space: nowrap`; the RN equivalent is a single
+                // line. `tail` makes an over-long label visibly truncated rather
+                // than silently clipped.
+                numberOfLines={1}
+                ellipsizeMode="tail"
+            >
+                {action.text}
+            </Text>
+        </Pressable>
+    )
+}
+
+export type AlertActionsProps = {
+    actions?: AlertActionsConfig
+    type: AlertV2Type
+    tokens: AlertActionTokens
+    testID?: string
+}
+
+function AlertActionsImpl({
+    actions,
+    type,
+    tokens,
+    testID,
+}: AlertActionsProps) {
+    if (!actions?.primaryAction && !actions?.secondaryAction) return null
+
+    return (
+        <Block flexDirection="row" alignItems="center" gap={tokens.gap}>
+            {actions.primaryAction ? (
+                <ActionLink
+                    action={actions.primaryAction}
+                    type={type}
+                    tokens={tokens.primaryAction}
+                    testID={testID ? `${testID}-primary-action` : undefined}
+                />
+            ) : null}
+            {actions.secondaryAction ? (
+                <ActionLink
+                    action={actions.secondaryAction}
+                    type={type}
+                    tokens={tokens.secondaryAction}
+                    testID={testID ? `${testID}-secondary-action` : undefined}
+                />
+            ) : null}
+        </Block>
+    )
+}
+
+export const AlertActions = memo(AlertActionsImpl)
+AlertActions.displayName = 'AlertActions'

package/src/components/Alert/AlertClose.tsx

@@ -0,0 +1,53 @@
+import { memo } from 'react'
+import type { ViewStyle } from 'react-native'
+import { X } from 'lucide-react-native'
+import { Pressable } from '../../primitives/Pressable'
+import { Slot } from '../../primitives/Slot'
+import type { AlertCloseButton } from './alert.types'
+
+/**
+ * `Alert`'s close affordance.
+ *
+ * Renders lucide's `X` by default; a consumer icon supplied via
+ * `closeButton.icon` goes through `Slot` so it is tinted the same way.
+ *
+ * The control is smaller than the 44pt minimum tap target, so it relies on the
+ * `hitSlop` `Pressable` applies automatically.
+ */
+
+export type AlertCloseProps = {
+    closeButton: AlertCloseButton
+    color: string
+    size: number
+    alignSelf: ViewStyle['alignSelf']
+    testID?: string
+}
+
+function AlertCloseImpl({
+    closeButton,
+    color,
+    size,
+    alignSelf,
+    testID,
+}: AlertCloseProps) {
+    return (
+        <Pressable
+            onPress={closeButton.onPress}
+            accessibilityRole="button"
+            accessibilityLabel={closeButton.accessibilityLabel ?? 'Close'}
+            testID={testID}
+            alignSelf={alignSelf}
+            alignItems="center"
+            justifyContent="center"
+        >
+            {closeButton.icon ? (
+                <Slot color={color}>{closeButton.icon}</Slot>
+            ) : (
+                <X size={size} color={color} />
+            )}
+        </Pressable>
+    )
+}
+
+export const AlertClose = memo(AlertCloseImpl)
+AlertClose.displayName = 'AlertClose'

package/src/components/Alert/AlertText.tsx

@@ -0,0 +1,58 @@
+import { memo } from 'react'
+import type { AlertV2Type } from '@juspay/blend-design-system/node'
+import { Block } from '../../primitives/Block'
+import { Text } from '../../primitives/Text'
+import type { AlertTextTokens } from './alert.tokens'
+
+/**
+ * The heading and description block of an `Alert`.
+ *
+ * `flexShrink` is explicit because Yoga defaults it to 0 where CSS defaults it
+ * to 1 — without it this box sizes to its text and a long description runs off
+ * the edge instead of wrapping.
+ */
+
+export type AlertTextProps = {
+    heading?: string
+    description?: string
+    type: AlertV2Type
+    tokens: AlertTextTokens
+}
+
+function AlertTextImpl({ heading, description, type, tokens }: AlertTextProps) {
+    if (!heading && !description) return null
+
+    return (
+        <Block
+            flexGrow={1}
+            flexShrink={1}
+            flexDirection="column"
+            gap={tokens.gap}
+        >
+            {heading ? (
+                <Text
+                    accessibilityRole="header"
+                    fontSize={tokens.heading.fontSize}
+                    fontWeight={tokens.heading.fontWeight}
+                    lineHeight={tokens.heading.lineHeight}
+                    color={String(tokens.heading.color[type])}
+                >
+                    {heading}
+                </Text>
+            ) : null}
+            {description ? (
+                <Text
+                    fontSize={tokens.description.fontSize}
+                    fontWeight={tokens.description.fontWeight}
+                    lineHeight={tokens.description.lineHeight}
+                    color={String(tokens.description.color[type])}
+                >
+                    {description}
+                </Text>
+            ) : null}
+        </Block>
+    )
+}
+
+export const AlertText = memo(AlertTextImpl)
+AlertText.displayName = 'AlertText'

package/src/components/Alert/alert.tokens.ts

@@ -0,0 +1,24 @@
+import type { AlertV2TokensType } from '@juspay/blend-design-system/node'
+
+/**
+ * Named aliases for AlertV2's deeply-nested token paths.
+ *
+ * The raw paths run five levels deep
+ * (`mainContainer.content.actionContainer.primaryAction.fontSize`), so spelling
+ * them out at each use site buried the prop types. These are type-only and
+ * erase completely.
+ */
+
+export type AlertTextTokens =
+    AlertV2TokensType['mainContainer']['content']['textContainer']
+
+export type AlertActionTokens =
+    AlertV2TokensType['mainContainer']['content']['actionContainer']
+
+export type AlertCloseTokens = AlertV2TokensType['mainContainer']['closeButton']
+
+/** One action's typography and per-type colour map. */
+export type AlertActionVariantTokens = AlertActionTokens['primaryAction']
+
+/** The shape shared by the heading and description token groups. */
+export type AlertTextVariantTokens = AlertTextTokens['heading']

package/src/components/Alert/alert.types.ts

@@ -0,0 +1,81 @@
+import type React from 'react'
+import type { GestureResponderEvent, ViewStyle } from 'react-native'
+import type {
+    AlertV2ActionPosition,
+    AlertV2SubType,
+    AlertV2Type,
+} from '@juspay/blend-design-system/node'
+
+/**
+ * Props for the native `Alert`.
+ *
+ * Mirrors web `AlertV2Props` (`packages/blend/lib/components/AlertV2/
+ * alertV2.types.ts`) with DOM-specific pieces replaced by RN equivalents:
+ *
+ * - `onClick` handlers become `onPress`, carrying a `GestureResponderEvent`.
+ * - `HTMLAttributes` passthrough becomes RN `View` props via `...rest`.
+ * - `width` / `maxWidth` / `minWidth` accept token strings or numbers and are
+ *   resolved by `parseSize`.
+ */
+
+export type AlertSlot = {
+    slot: React.ReactNode
+    /** Overrides the token-derived slot max height. */
+    maxHeight?: string | number
+}
+
+export type AlertAction = {
+    text: string
+    onPress?: (event: GestureResponderEvent) => void
+    /** Overrides the accessible name, which defaults to `<text> action`. */
+    accessibilityLabel?: string
+}
+
+export type AlertActions = {
+    /**
+     * `BOTTOM` stacks the actions under the text; `RIGHT` places them inline
+     * and enables the separator before the close button.
+     */
+    position?: AlertV2ActionPosition
+    primaryAction?: AlertAction
+    secondaryAction?: AlertAction
+}
+
+export type AlertCloseButton = {
+    show?: boolean
+    onPress?: (event: GestureResponderEvent) => void
+    /**
+     * Replaces the default lucide `X`. Tinted by `Slot` like any other icon,
+     * so a custom icon only needs to accept a `color` prop.
+     */
+    icon?: React.ReactNode
+    accessibilityLabel?: string
+}
+
+export type AlertNativeProps = {
+    type?: AlertV2Type
+    subType?: AlertV2SubType
+    slot?: AlertSlot
+    heading?: string
+    description?: string
+    actions?: AlertActions
+    closeButton?: AlertCloseButton
+
+    width?: string | number
+    maxWidth?: string | number
+    minWidth?: string | number
+
+    /**
+     * Announce the alert to assistive tech when it appears. Defaults to `true`,
+     * matching web's hard-coded `aria-live="assertive"`.
+     *
+     * Pass `false` for alerts that are part of a screen's initial content
+     * rather than a response to something the user did. Several alerts mounting
+     * at once each queue an announcement, so a static list of them talks over
+     * itself — the showcase in `apps/native-site` disables it for that reason.
+     */
+    announce?: boolean
+    accessibilityLabel?: string
+    testID?: string
+    style?: ViewStyle
+}

package/src/components/Alert/alert.utils.ts

@@ -0,0 +1,94 @@
+import {
+    AlertV2ActionPosition,
+    type AlertV2TokensType,
+} from '@juspay/blend-design-system/node'
+import type { ViewStyle } from 'react-native'
+
+/**
+ * Native Alert layout helpers.
+ *
+ * Web computes these inline in the JSX of `AlertV2.tsx`. Pulling them out
+ * makes the branching testable, and keeps the component readable given that
+ * one prop reshapes four layout values at once.
+ */
+
+/**
+ * Flex sizing shared by every box in Alert's row chain.
+ *
+ * `flexShrink` is explicit because **Yoga defaults it to 0 where CSS defaults
+ * it to 1**. Without it a flex child sizes to its content and refuses to
+ * narrow, so a long description runs off the right edge instead of wrapping.
+ *
+ * Exported as a constant rather than repeated inline so the invariant has one
+ * definition and can be asserted directly in tests.
+ */
+export const ALERT_FLEX_BOX = {
+    flexGrow: 1,
+    flexShrink: 1,
+} as const
+
+/** Fallback icon size when the close-button token cannot be parsed. */
+export const FALLBACK_CLOSE_ICON_SIZE = 16
+
+export type AlertLayout = {
+    /** Direction the text block and actions flow in. */
+    contentDirection: NonNullable<ViewStyle['flexDirection']>
+    contentJustify: NonNullable<ViewStyle['justifyContent']>
+    contentAlign: NonNullable<ViewStyle['alignItems']>
+    /** Vertical alignment of the close button against the content. */
+    closeAlign: NonNullable<ViewStyle['alignItems']>
+}
+
+/**
+ * Resolve the layout for an action position.
+ *
+ * `BOTTOM` stacks the actions beneath the text and pins the close button to
+ * the top; `RIGHT` runs everything on one line, vertically centred. Mirrors
+ * the `actionPlacementBottom` branches in web `AlertV2.tsx`.
+ */
+export function getAlertLayout(position: AlertV2ActionPosition): AlertLayout {
+    const isBottom = position === AlertV2ActionPosition.BOTTOM
+
+    return {
+        contentDirection: isBottom ? 'column' : 'row',
+        contentJustify: isBottom ? 'space-between' : 'flex-start',
+        contentAlign: isBottom ? 'flex-start' : 'center',
+        closeAlign: isBottom ? 'flex-start' : 'center',
+    }
+}
+
+/**
+ * Whether to render the divider between the actions and the close button.
+ *
+ * Web's condition is `position === RIGHT && closeButton.show` — the separator
+ * only makes sense when both sit on the same line. Extracted because the
+ * two-term condition is easy to get subtly wrong, and it has a truth table
+ * in the tests.
+ */
+export function shouldShowSeparator(
+    position: AlertV2ActionPosition,
+    closeButtonShown: boolean
+): boolean {
+    return position === AlertV2ActionPosition.RIGHT && closeButtonShown
+}
+
+/**
+ * Resolve the accessible name for an action.
+ * Mirrors web's `aria-label={`${action.text} action`}`.
+ */
+export function getActionAccessibilityLabel(
+    text: string,
+    override?: string
+): string {
+    return override ?? `${text} action`
+}
+
+/** Numeric size for the close icon, from the same token web uses. */
+export function getCloseIconSize(tokens: AlertV2TokensType): number {
+    const raw = tokens.mainContainer.closeButton.height
+    const parsed =
+        typeof raw === 'number' ? raw : Number.parseFloat(String(raw))
+    return Number.isFinite(parsed) && parsed > 0
+        ? parsed
+        : FALLBACK_CLOSE_ICON_SIZE
+}

package/src/components/Alert/index.ts

@@ -0,0 +1,21 @@
+export { default as Alert } from './Alert'
+export type {
+    AlertNativeProps,
+    AlertSlot,
+    AlertAction,
+    AlertActions,
+    AlertCloseButton,
+} from './alert.types'
+export {
+    getAlertLayout,
+    shouldShowSeparator,
+    getActionAccessibilityLabel,
+    getCloseIconSize,
+} from './alert.utils'
+export type { AlertLayout } from './alert.utils'
+export { ALERT_FLEX_BOX, FALLBACK_CLOSE_ICON_SIZE } from './alert.utils'
+export type {
+    AlertTextTokens,
+    AlertActionTokens,
+    AlertCloseTokens,
+} from './alert.tokens'