blend-native 0.0.1-beta.0

package/src/primitives/Slot.tsx

@@ -0,0 +1,94 @@
+import React, { memo } from 'react'
+import { View, StyleSheet, type ViewStyle } from 'react-native'
+import { parseSize } from '../adapters/cssStringAdapter'
+import { tintSlot } from './tintSlot'
+
+export { tintSlot }
+
+/**
+ * Leading / trailing icon slot.
+ *
+ * Shared by `Button` and `Tag`, both of which need identical behaviour and
+ * both of which previously got it wrong in the same three ways:
+ *
+ * 1. **Tinting.** On web, components pass `color` to `Block`, which maps to
+ *    CSS `color`, and SVG icons pick it up through `currentColor`. The native
+ *    `Block` mapped `color` to `backgroundColor`, so the same call painted a
+ *    solid rectangle *behind* the icon and never tinted the icon at all. RN
+ *    has no `currentColor`, so the tint has to be handed to the element
+ *    explicitly — that is what this component does.
+ * 2. **Per-slot `maxHeight`.** `leftSlot.maxHeight` / `rightSlot.maxHeight`
+ *    are part of the web prop contract and were ignored.
+ * 3. **Screen readers.** Web marks slots `aria-hidden` when the component
+ *    also renders text, so the icon is not announced separately from the
+ *    label. Native rendered them as visible accessibility nodes.
+ */
+
+export type SlotProps = {
+    /** The icon element to render. */
+    children?: React.ReactNode
+    /**
+     * Colour to tint the icon with. Passed to the child as `color` (and
+     * `fill`, which `react-native-svg` elements use).
+     */
+    color?: string
+    /**
+     * Max height for the icon box. Accepts token strings (`"16px"`),
+     * percentages (`"100%"`, used by Button's inline subType), or numbers.
+     */
+    maxHeight?: string | number
+    /**
+     * Hide from screen readers. Should be `true` whenever the parent also
+     * renders a text label, matching web's `aria-hidden`.
+     */
+    hidden?: boolean
+    style?: ViewStyle
+    testID?: string
+}
+
+function SlotImpl({
+    children,
+    color,
+    maxHeight,
+    hidden = false,
+    style,
+    testID,
+}: SlotProps) {
+    if (!children) return null
+
+    const resolved: ViewStyle = { ...baseStyle.slot }
+    const size = parseSize(maxHeight)
+    if (size !== undefined) resolved.maxHeight = size
+
+    return (
+        <View
+            style={StyleSheet.flatten([resolved, style])}
+            testID={testID}
+            // Matches web's `aria-hidden` on slots that accompany text: the
+            // icon should not be announced as a separate element, and the
+            // parent already carries the accessible name.
+            accessible={hidden ? false : undefined}
+            importantForAccessibility={
+                hidden ? 'no-hide-descendants' : undefined
+            }
+            accessibilityElementsHidden={hidden || undefined}
+        >
+            {tintSlot(children, color)}
+        </View>
+    )
+}
+
+/** Memoised — see the note on `Block`. */
+export const Slot = memo(SlotImpl)
+Slot.displayName = 'Slot'
+
+const baseStyle = StyleSheet.create({
+    slot: {
+        flexDirection: 'row',
+        alignItems: 'center',
+        justifyContent: 'center',
+        flexShrink: 0,
+    },
+})
+
+export default Slot

package/src/primitives/Text.tsx

@@ -0,0 +1,98 @@
+import React, { memo, useContext } from 'react'
+import {
+    Text as RNText,
+    StyleSheet,
+    type TextProps as RNTextProps,
+    type TextStyle,
+} from 'react-native'
+import { parseDimension } from '../adapters/cssStringAdapter'
+import { resolveFontWeight } from './textStyle'
+import { BlendNativeThemeContext } from '../theme/BlendNativeProvider'
+import type { NativeFontRole } from '../theme/fonts'
+
+/**
+ * Native `Text` — renders a RN `Text` from token-driven style props.
+ *
+ * Mirrors the web `Text` component's API (`fontSize`, `fontWeight`, `color`,
+ * `lineHeight`, `textAlign`) but accepts CSS-string values directly from
+ * Blend tokens and translates them to `TextStyle` numbers.
+ *
+ * **Font family** comes from the provider's resolved role map (web has CSS
+ * inheritance; RN does not, so the provider is the inheritance mechanism).
+ * Defaults to the `body` role; `fontRole` picks another role and an explicit
+ * `fontFamily` wins outright.
+ *
+ * **Font scaling** is deliberately left ON (RN's default). The package policy
+ * is to respect OS Dynamic Type and let controls grow — components size with
+ * `minHeight`, never a fixed `height`, so scaled text expands the control
+ * instead of clipping. Consumers needing a cap can pass RN's own
+ * `maxFontSizeMultiplier` through `...rest`.
+ */
+
+export type BlendTextProps = {
+    children?: React.ReactNode
+    /** CSS string like `"14px"` or a number. */
+    fontSize?: string | number
+    /** CSS font-weight keyword or number (`"500"`, `500`, `"bold"`). */
+    fontWeight?: string | number
+    color?: string
+    /** CSS line-height like `"20px"` or a number. */
+    lineHeight?: string | number
+    textAlign?: 'left' | 'right' | 'center' | 'justify'
+    /**
+     * Explicit font family. Overrides the provider's role map; rarely needed
+     * outside consumer escape hatches.
+     */
+    fontFamily?: string
+    /** Which provider font role to use when `fontFamily` is not given. */
+    fontRole?: NativeFontRole
+    /** Set true to hide from screen readers (web `aria-hidden`). */
+    'aria-hidden'?: boolean
+    /** Flex display — web `Text` is sometimes `inline`; on RN Text is always inline. */
+    as?: string
+} & Omit<RNTextProps, 'style'> & {
+        style?: TextStyle
+    }
+
+function TextImpl({
+    children,
+    fontSize,
+    fontWeight,
+    color,
+    lineHeight,
+    textAlign,
+    fontFamily,
+    fontRole = 'body',
+    style,
+    ...rest
+}: BlendTextProps) {
+    const { fontFamily: familyMap } = useContext(BlendNativeThemeContext)
+    // `null` in the map means "leave the platform font" — emit nothing.
+    const resolvedFamily = fontFamily ?? familyMap[fontRole] ?? undefined
+
+    const resolved: TextStyle = {
+        fontSize: parseDimension(fontSize),
+        fontWeight: resolveFontWeight(fontWeight),
+        color,
+        lineHeight: parseDimension(lineHeight),
+        textAlign,
+        fontFamily: resolvedFamily,
+    }
+
+    const flat = StyleSheet.flatten([baseStyle.text, resolved, style])
+    return (
+        <RNText style={flat} {...rest}>
+            {children}
+        </RNText>
+    )
+}
+
+/** Memoised — see the note on `Block`. */
+export const Text = memo(TextImpl)
+Text.displayName = 'Text'
+
+const baseStyle = StyleSheet.create({
+    text: {},
+})
+
+export default Text

package/src/primitives/pressFeedback.ts

@@ -0,0 +1,78 @@
+import type { ViewStyle } from 'react-native'
+
+/**
+ * Press feedback is platform-idiomatic, not uniform.
+ *
+ * Web scales the surface by `0.99`, and that reads correctly on iOS where a
+ * subtle depress is the convention. Android users expect a **ripple**, and a
+ * scale transform there looks like a bug. Applying both would double the
+ * feedback.
+ *
+ * The decision lives here — a leaf module with no `react-native` value import
+ * — so it is unit-testable outside a renderer, the same split as
+ * `theme/breakpoint.ts`, `primitives/touchTarget.ts` and the shadow handling
+ * in `adapters/surfaceStyle.ts`. `Pressable` passes the real `Platform.OS`.
+ */
+
+export type PressFeedbackPlatform =
+    | 'ios'
+    | 'android'
+    | 'web'
+    | 'windows'
+    | 'macos'
+
+export type AndroidRipple = {
+    color: string
+    borderless: boolean
+}
+
+export type PressFeedback = {
+    /** Passed to RN's `android_ripple`; `undefined` off Android. */
+    androidRipple?: AndroidRipple
+    /** Style merged in while pressed; empty on Android, where the ripple carries it. */
+    pressedTransform: ViewStyle
+}
+
+/**
+ * Ripple colour used when neither the caller nor the active-state token
+ * supplies one. Low-alpha black is Android's own default for light surfaces.
+ */
+export const DEFAULT_RIPPLE_COLOR = 'rgba(0, 0, 0, 0.12)'
+
+export function resolvePressFeedback(
+    platform: PressFeedbackPlatform,
+    options: {
+        /** Explicit ripple colour from the caller. */
+        rippleColor?: string
+        /** Active-state background token, used when no explicit colour is set. */
+        activeBackgroundColor?: string
+        rippleBorderless?: boolean
+        pressedScale?: number
+    } = {}
+): PressFeedback {
+    const {
+        rippleColor,
+        activeBackgroundColor,
+        rippleBorderless = false,
+        pressedScale = 0.99,
+    } = options
+
+    if (platform === 'android') {
+        return {
+            androidRipple: {
+                color:
+                    rippleColor ??
+                    activeBackgroundColor ??
+                    DEFAULT_RIPPLE_COLOR,
+                borderless: rippleBorderless,
+            },
+            // The ripple is the feedback; scaling as well would double it.
+            pressedTransform: {},
+        }
+    }
+
+    return {
+        androidRipple: undefined,
+        pressedTransform: { transform: [{ scale: pressedScale }] },
+    }
+}

package/src/primitives/textStyle.ts

@@ -0,0 +1,24 @@
+import type { TextStyle } from 'react-native'
+
+/**
+ * Shared text-style resolution for `Text` and `PrimitiveInput`.
+ *
+ * Leaf module with only a type import from `react-native`, so it stays
+ * vitest-testable — the `theme/breakpoint.ts` pattern.
+ */
+
+/**
+ * Resolve a CSS font-weight value to a RN-compatible `TextStyle['fontWeight']`.
+ * RN accepts `'normal' | 'bold' | '100'..'900'` (as string or number).
+ */
+export function resolveFontWeight(
+    w: string | number | undefined
+): TextStyle['fontWeight'] {
+    if (w === undefined) return undefined
+    if (typeof w === 'number') return String(w) as TextStyle['fontWeight']
+    // Token values are numeric strings like `"500"`.
+    if (/^\d+$/.test(w)) return w as TextStyle['fontWeight']
+    const lower = w.toLowerCase()
+    if (lower === 'normal' || lower === 'bold') return lower
+    return undefined
+}

package/src/primitives/tintSlot.ts

@@ -0,0 +1,44 @@
+import { cloneElement, isValidElement } from 'react'
+import type { ReactNode, ReactElement } from 'react'
+
+/**
+ * Icon tinting.
+ *
+ * Kept in its own leaf module — importing nothing from `react-native` — so it
+ * stays unit-testable outside a renderer, the same split as
+ * `theme/breakpoint.ts` and `primitives/touchTarget.ts`.
+ */
+
+/**
+ * Props an icon element may accept for tinting.
+ *
+ * `color` is the channel every mainstream RN icon library understands —
+ * `lucide-react-native`, `phosphor-react-native`, `react-native-vector-icons`
+ * — and is what `Slot` sets.
+ *
+ * `fill` is deliberately NOT set. Lucide renders stroke-based artwork with
+ * `fill: "none"`, and its `Icon` spreads unknown props over both the root
+ * `Svg` and every child path *after* those defaults, so supplying a `fill`
+ * overrides `"none"` and floods the glyph solid — an outlined X becomes a
+ * filled block. Artwork that genuinely needs a fill should set it itself.
+ */
+type TintableProps = { color?: string }
+
+/**
+ * Apply a tint to an icon element.
+ *
+ * Only sets `color`, and only when the element has not set it explicitly —
+ * an icon rendered as `<Icon color="red" />` keeps red. Non-element children
+ * (a bare string, a number, `null`) are returned untouched.
+ */
+export function tintSlot(
+    node: ReactNode,
+    color: string | undefined
+): ReactNode {
+    if (!color || !isValidElement(node)) return node
+
+    const element = node as ReactElement<TintableProps>
+    if (element.props.color !== undefined) return node
+
+    return cloneElement(element, { color })
+}

package/src/primitives/touchTarget.ts

@@ -0,0 +1,72 @@
+/**
+ * Minimum tap-target policy.
+ *
+ * Kept in its own leaf module — importing nothing from `react-native` — so it
+ * stays unit-testable outside a renderer. (RN's entrypoint ships Flow syntax
+ * that non-Metro bundlers cannot parse, so any module that value-imports it is
+ * unusable from a plain Node test runner. Same split as `theme/breakpoint.ts`.)
+ */
+
+/** Inset applied to each edge of the touch region. */
+export type HitSlop = {
+    top: number
+    bottom: number
+    left: number
+    right: number
+}
+
+/**
+ * Apple's Human Interface Guidelines minimum tappable size, in points. Also
+ * clears Material's 48dp target once RN's density conversion is applied.
+ */
+export const MIN_TOUCH_TARGET = 44
+
+/**
+ * Slop needed to bring a rendered control up to the minimum tap target.
+ *
+ * Design-system controls are frequently smaller than the guideline by intent —
+ * an `xs` Tag is 20pt tall — so the fix is to widen the *touch* region rather
+ * than the control. Returns `undefined` when the control already complies (or
+ * when the minimum is disabled with `0`), so no `hitSlop` prop is emitted.
+ *
+ * ```
+ * resolveHitSlop(120, 48) -> undefined          // already compliant
+ * resolveHitSlop(60, 20)  -> { top: 12, bottom: 12, left: 0, right: 0 }
+ * resolveHitSlop(24, 24)  -> { top: 10, bottom: 10, left: 10, right: 10 }
+ * ```
+ */
+export function resolveHitSlop(
+    width: number,
+    height: number,
+    minTouchTarget: number = MIN_TOUCH_TARGET
+): HitSlop | undefined {
+    if (!minTouchTarget) return undefined
+
+    const horizontal = Math.max(0, (minTouchTarget - width) / 2)
+    const vertical = Math.max(0, (minTouchTarget - height) / 2)
+    if (horizontal === 0 && vertical === 0) return undefined
+
+    return {
+        top: vertical,
+        bottom: vertical,
+        left: horizontal,
+        right: horizontal,
+    }
+}
+
+/**
+ * Whether two slop values are equivalent.
+ *
+ * Lets callers skip a state update when a re-measure produces the same result,
+ * which keeps a control that never needed slop from re-rendering at all.
+ */
+export function sameHitSlop(a?: HitSlop, b?: HitSlop): boolean {
+    if (a === b) return true
+    if (!a || !b) return false
+    return (
+        a.top === b.top &&
+        a.bottom === b.bottom &&
+        a.left === b.left &&
+        a.right === b.right
+    )
+}

package/src/theme/BlendNativeProvider.tsx

@@ -0,0 +1,147 @@
+import React, { createContext, useMemo } from 'react'
+import { useColorScheme } from 'react-native'
+import {
+    BREAKPOINTS,
+    FOUNDATION_THEME,
+    Theme,
+    type BreakpointType,
+} from '@juspay/blend-design-system/node'
+import type { NativeComponentTokenOverrides } from './nativeTokenRegistry'
+import { PortalArea } from '../overlay/portal'
+import { ToastOutlet } from '../overlay/toast/ToastOutlet'
+import {
+    resolveFontFamilies,
+    type NativeFontFamilies,
+    type NativeFontFamilyOption,
+} from './fonts'
+import {
+    resolveThemeSetting,
+    SYSTEM_THEME,
+    type NativeThemeSetting,
+} from './systemTheme'
+
+/**
+ * Theme context for `blend-native`.
+ *
+ * Replaces the per-component `theme` prop the package shipped with. A prop
+ * meant no app-wide dark mode (every call site had to thread it), no nested
+ * theme scopes, and — most importantly — no `componentTokens` overrides,
+ * which is a first-class feature of web Blend that native consumers simply
+ * did not have.
+ *
+ * Mirrors web's `ThemeProvider` API (`{ theme, componentTokens,
+ * foundationTokens }`) so the two platforms are configured the same way, and
+ * like web it is optional: components fall back to these defaults when no
+ * provider is mounted.
+ *
+ * Two native-only additions:
+ *
+ * - `theme="system"` follows the OS appearance via `useColorScheme`,
+ *   re-rendering when the user flips light/dark. The sentinel is resolved
+ *   *before* the value enters context, so consumers only ever see a concrete
+ *   theme.
+ * - `fontFamily` resolves one font family per role (see `theme/fonts.ts`) —
+ *   RN's replacement for web's CSS font inheritance.
+ */
+
+export type BlendNativeThemeValue = {
+    theme: Theme | string
+    componentTokens: NativeComponentTokenOverrides
+    foundationTokens: typeof FOUNDATION_THEME
+    breakpoints: BreakpointType
+    /** Resolved family per role; `null` leaves the platform font. */
+    fontFamily: NativeFontFamilies
+}
+
+const EMPTY_OVERRIDES: NativeComponentTokenOverrides = {}
+
+export const DEFAULT_NATIVE_THEME: BlendNativeThemeValue = {
+    theme: Theme.LIGHT,
+    componentTokens: EMPTY_OVERRIDES,
+    foundationTokens: FOUNDATION_THEME,
+    breakpoints: BREAKPOINTS,
+    fontFamily: resolveFontFamilies(FOUNDATION_THEME),
+}
+
+export const BlendNativeThemeContext =
+    createContext<BlendNativeThemeValue>(DEFAULT_NATIVE_THEME)
+
+export type BlendNativeProviderProps = {
+    children?: React.ReactNode
+    /**
+     * `'light' | 'dark' | 'system'`. Defaults to light. `'system'` follows
+     * the OS appearance setting.
+     */
+    theme?: NativeThemeSetting
+    /**
+     * Partial per-slot token overrides, deep-merged onto the active theme's
+     * defaults. Supply only the paths you want to change — every untouched
+     * path keeps its light/dark value.
+     */
+    componentTokens?: NativeComponentTokenOverrides
+    /** Override foundation tokens (colours, spacing, radii, ...). */
+    foundationTokens?: typeof FOUNDATION_THEME
+    /** Override breakpoint thresholds. */
+    breakpoints?: BreakpointType
+    /**
+     * Font families per role. Defaults to the foundation `font.family`
+     * tokens; pass `'system'` for platform fonts, or a partial map to
+     * override/disable individual roles. See `theme/fonts.ts`.
+     */
+    fontFamily?: NativeFontFamilyOption
+}
+
+export function BlendNativeProvider({
+    children,
+    theme = Theme.LIGHT,
+    componentTokens = EMPTY_OVERRIDES,
+    foundationTokens = FOUNDATION_THEME,
+    breakpoints = BREAKPOINTS,
+    fontFamily,
+}: BlendNativeProviderProps) {
+    // Subscribed unconditionally (hooks must be), but only `theme="system"`
+    // reads it — an explicit theme is unaffected by OS appearance changes.
+    const colorScheme = useColorScheme()
+    const resolvedTheme = resolveThemeSetting(theme, colorScheme)
+
+    // Memoised on the same keys web's `initTokens` uses: objects by
+    // reference (they are module-scope singletons in practice), theme by
+    // value. Keeps the context value stable so a re-render of the provider's
+    // parent does not invalidate every consumer's token memo.
+    const value = useMemo<BlendNativeThemeValue>(
+        () => ({
+            theme: resolvedTheme,
+            componentTokens,
+            foundationTokens,
+            breakpoints,
+            fontFamily: resolveFontFamilies(foundationTokens, fontFamily),
+        }),
+        [
+            resolvedTheme,
+            componentTokens,
+            foundationTokens,
+            breakpoints,
+            fontFamily,
+        ]
+    )
+
+    return (
+        <BlendNativeThemeContext.Provider value={value}>
+            {/* Portal layers render after (above) the app's children — mount
+                the provider at a screen-filling root so overlays cover the
+                screen. See overlay/portal.tsx. The toast outlet subscribes
+                to the imperative showToast queue and renders nothing while
+                it is empty. */}
+            <PortalArea>
+                {children}
+                <ToastOutlet />
+            </PortalArea>
+        </BlendNativeThemeContext.Provider>
+    )
+}
+
+BlendNativeProvider.displayName = 'BlendNativeProvider'
+
+export { SYSTEM_THEME }
+
+export default BlendNativeProvider

package/src/theme/breakpoint.ts

@@ -0,0 +1,38 @@
+import {
+    BREAKPOINTS,
+    type BreakpointType,
+} from '@juspay/blend-design-system/node'
+
+/**
+ * Pure breakpoint resolution.
+ *
+ * Kept in its own leaf module — importing nothing from `react-native` — so it
+ * stays testable and reusable outside a React render. `useNativeBreakpoint`
+ * layers the `useWindowDimensions` subscription on top.
+ *
+ * (React Native's entrypoint ships Flow syntax that non-Metro bundlers cannot
+ * parse, so any module that value-imports it is unusable from a plain Node
+ * test runner. Splitting the logic out is the same pattern the web package
+ * uses for `shared/datetime/timeCore.ts`.)
+ */
+
+export type NativeBreakpoint = keyof BreakpointType
+
+/**
+ * Resolve a viewport width to a Blend breakpoint label.
+ *
+ * Mirrors web's `useBreakPoints` exactly, including its quirk: **only**
+ * 320–1023 maps to `'sm'`; everything else — including widths below 320 —
+ * returns `'lg'`. Reproduced deliberately so a given width resolves to the
+ * same tokens on both platforms.
+ *
+ * Thresholds come from `BREAKPOINTS` in the web package rather than being
+ * duplicated, so retuning them stays a one-line change in one place.
+ */
+export function resolveBreakpoint(
+    width: number,
+    breakpoints: BreakpointType = BREAKPOINTS
+): NativeBreakpoint {
+    if (width >= breakpoints.sm && width < breakpoints.lg) return 'sm'
+    return 'lg'
+}

package/src/theme/fonts.ts

@@ -0,0 +1,63 @@
+import { FOUNDATION_THEME } from '@juspay/blend-design-system/node'
+
+/**
+ * Font-family policy.
+ *
+ * Web never applies Blend's font tokens — components inherit whatever face the
+ * host document loads (`fontFamily: 'inherit'` in the primitives), and the
+ * consuming app supplies InterDisplay via `@font-face`. React Native has no
+ * inheritance and no `@font-face`, so the provider is the inheritance
+ * mechanism: it resolves one family per role and `Text` applies it.
+ *
+ * Defaults come from the foundation tokens (`font.family`), so out of the box
+ * native asks for the same faces the design system names. A consumer that has
+ * not loaded those fonts sees the platform fallback (plus a dev warning on
+ * iOS) — load them with `expo-font` or native assets, or opt out:
+ *
+ * - `fontFamily="system"` — platform fonts everywhere, no families applied.
+ * - `fontFamily={{ mono: 'JetBrainsMono' }}` — override one role, keep the
+ *   token defaults for the rest.
+ * - `fontFamily={{ body: null }}` — disable one role only.
+ *
+ * Kept as a leaf module with no `react-native` value import so it stays
+ * testable under plain vitest — the same constraint as `theme/breakpoint.ts`.
+ */
+
+export type NativeFontRole = 'display' | 'body' | 'heading' | 'mono'
+
+/** One resolved family per role; `null` means "leave the platform font". */
+export type NativeFontFamilies = Record<NativeFontRole, string | null>
+
+/** What `BlendNativeProvider` accepts for its `fontFamily` prop. */
+export type NativeFontFamilyOption =
+    | 'system'
+    | Partial<Record<NativeFontRole, string | null>>
+
+const ROLES: NativeFontRole[] = ['display', 'body', 'heading', 'mono']
+
+/**
+ * Resolve the provider's `fontFamily` option against the active foundation
+ * tokens. Pure; called once per provider render.
+ */
+export function resolveFontFamilies(
+    foundationTokens: typeof FOUNDATION_THEME = FOUNDATION_THEME,
+    option?: NativeFontFamilyOption
+): NativeFontFamilies {
+    const resolved = {} as NativeFontFamilies
+
+    for (const role of ROLES) {
+        if (option === 'system') {
+            resolved[role] = null
+            continue
+        }
+        const override = option?.[role]
+        if (override !== undefined) {
+            resolved[role] = override
+            continue
+        }
+        const token = foundationTokens.font?.family?.[role]
+        resolved[role] = token !== undefined ? String(token) : null
+    }
+
+    return resolved
+}