jfs-components 0.0.73 → 0.0.77

package/lib/typescript/src/skeleton/shimmer-tokens.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Single source of truth for the skeleton shimmer behaviour spec.
+ *
+ * The two modes mirror the documented design behaviour:
+ *
+ *   Normal:
+ *     - 1.5s linear sawtooth cycle (band sweeps end-to-end then resets)
+ *     - 135° gradient (top-left -> bottom-right), fixed angle on any aspect
+ *       ratio via SVG userSpaceOnUse coordinates
+ *     - Band alpha animates 33% -> 100% -> 33% across the band core;
+ *       transparent fades at the gradient edges hide the sawtooth reset
+ *     - 50–100ms per-item stagger
+ *
+ *   Reduced motion (system-level OS toggle):
+ *     - 3.0s ease-in-out cycle
+ *     - No translation — solid white overlay opacity pulses 33% -> 100% in
+ *       place (`opacityRange` below is consumed in this path)
+ *     - No gradient
+ *     - No stagger
+ *
+ * Centralising the spec here keeps `Skeleton.tsx` purely presentational and
+ * lets us tune the behaviour in one place if design ever updates it.
+ */
+export type SkeletonKind = 'text' | 'image' | 'badge' | 'other';
+export interface ShimmerModeSpec {
+    durationMs: number;
+    /** Per-item delay range. Min/max in milliseconds. */
+    staggerMsRange: readonly [number, number];
+    gradient: boolean;
+    /** Opacity range applied to the moving "blob" overlay. */
+    opacityRange: readonly [number, number];
+}
+export declare const SHIMMER: {
+    readonly normal: {
+        durationMs: number;
+        staggerMsRange: readonly [50, 100];
+        gradient: true;
+        opacityRange: readonly [0.33, 1];
+    };
+    readonly reduced: {
+        durationMs: number;
+        staggerMsRange: readonly [0, 0];
+        gradient: false;
+        opacityRange: readonly [0.33, 1];
+    };
+    /**
+     * Gradient angle in degrees, measured the CSS way: 0deg points "up", 90deg
+     * "right", 135deg therefore points down-right (top-left corner to
+     * bottom-right corner).
+     */
+    readonly gradientAngleDeg: 135;
+    /**
+     * Hard cap on the cumulative stagger delay so very long lists don't drift
+     * out forever; the wave wraps after this many ms.
+     */
+    readonly maxStaggerMs: 600;
+};
+/**
+ * Token names — referenced via `getVariableByName(...)` so the existing
+ * design-token resolver does its job (caching, mode resolution, etc.).
+ *
+ * The four tokens already live in the Figma export at
+ * `src/design-tokens/Coin Variables-variables-full.json`:
+ *
+ *   - `bg/defaultSkeleton`              -> base color for every skeleton block
+ *   - `cornerRadius/defaultSkeleton`    -> text & "other" (pill: 9999)
+ *   - `cornerRadius/imageSkeleton`      -> images (10)
+ *   - `cornerRadius/badgeSkeleton`      -> badges (4)
+ */
+export declare const SKELETON_TOKEN: {
+    readonly background: "bg/defaultSkeleton";
+    readonly radius: {
+        text: string;
+        image: string;
+        badge: string;
+        other: string;
+    };
+};
+/**
+ * Fallback constants used when the token resolver is unavailable (tests,
+ * SSR, etc.). Match the current Figma values.
+ */
+export declare const SKELETON_FALLBACK: {
+    readonly backgroundColor: "rgb(245, 245, 246)";
+    readonly radius: {
+        text: number;
+        image: number;
+        badge: number;
+        other: number;
+    };
+};
+/**
+ * Compute a stable per-item delay from a 0-based registration index.
+ *
+ * We pick the midpoint of the documented range (75ms) so the cascade is
+ * deterministic for snapshot tests and visually identical between renders.
+ * The total delay is then wrapped at `maxStaggerMs` so deep lists don't
+ * drift past the cap.
+ */
+export declare function staggerDelayMs(index: number, mode: ShimmerModeSpec): number;
+/** One stop on the moving shimmer gradient (offset 0–1 along the 135° axis). */
+export interface ShimmerGradientStop {
+    offset: number;
+    opacity: number;
+}
+/**
+ * Gradient stops for the normal-mode moving band. The peak sits at 0.5; fully
+ * transparent tails at 0 and 1. The 0.30 / 0.70 stops mark where the band
+ * reaches the documented 33 % alpha.
+ */
+export declare const SHIMMER_GRADIENT_STOPS: readonly ShimmerGradientStop[];
+/** Offset (0–1) of the brightest point on the gradient line. */
+export declare function gradientPeakOffset(stops?: readonly ShimmerGradientStop[]): number;
+/**
+ * How far the gradient extends from the peak to a fully transparent stop,
+ * expressed as a fraction of the gradient line (0–1). With the default stops
+ * this is 0.5 (peak at 0.5, transparent at 0 and 1).
+ *
+ * This value drives the overshoot: the band must travel this fraction of a
+ * full corner-to-corner sweep *beyond* each corner so the soft transparent
+ * tails fully clear the box before the sawtooth reset.
+ */
+export declare function gradientTransparentExtent(stops?: readonly ShimmerGradientStop[]): number;
+export interface ShimmerMotionGeometry {
+    /** Square overlay side length (gradient is painted on this). */
+    overlaySize: number;
+    /** Padding to centre the overlay on the box. */
+    padX: number;
+    padY: number;
+    /** Translation (k, k) when the band is fully off-screen before entry. */
+    kStart: number;
+    /** Translation (k, k) when the band is fully off-screen after exit. */
+    kEnd: number;
+    /**
+     * Normalised overshoot on each side of the corner-to-corner sweep. A value
+     * of 0.5 means the travel extends 50 % past each corner; at reset the
+     * clock jumps from `1 + overshoot` to `-overshoot` while the box still
+     * shows only the base skeleton colour.
+     */
+    overshootFraction: number;
+    /** k distance from peak-at-TL to peak-at-BR. */
+    cornerTravelK: number;
+    /** k distance from peak to fully transparent tail on the gradient. */
+    fadeBeyondPeakK: number;
+}
+/**
+ * Derive the moving-shimmer geometry from box size, overlay size, and the
+ * gradient stop layout.
+ *
+ * Coordinate model (135° / down-right):
+ *   - Peak stripe world diagonal sum: (W + H) / 2 + 2k
+ *   - Gradient offset 0 → 1 spans 2 × overlaySize in diagonal-sum units
+ *   - Transparent tail beyond peak: fadeExtent × 2 × overlaySize / 2
+ *     = fadeExtent × overlaySize in k units
+ *
+ * The sawtooth clock maps linearly kStart → kEnd so t = 0 and t = 1 both
+ * land with the entire gradient outside the box — no jitter on reset.
+ */
+export declare function computeShimmerMotion(width: number, height: number, overlaySize: number, stops?: readonly ShimmerGradientStop[]): ShimmerMotionGeometry | null;
+//# sourceMappingURL=shimmer-tokens.d.ts.map

package/lib/typescript/src/skeleton/useReducedMotion.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Cross-platform "prefers reduced motion" hook.
+ *
+ *  - Native: reads `AccessibilityInfo.isReduceMotionEnabled()` and subscribes
+ *    to `reduceMotionChanged` events so the value stays live as the user
+ *    toggles the OS setting.
+ *  - Web: uses `window.matchMedia('(prefers-reduced-motion: reduce)')`,
+ *    subscribing to its `change` event.
+ *  - Anywhere either API is missing: returns `false` (no reduction).
+ *
+ * The hook never throws — every native API access is defensively guarded so
+ * the skeleton system stays safe in tests, SSR, and constrained sandboxes.
+ */
+export declare function useReducedMotion(): boolean;
+//# sourceMappingURL=useReducedMotion.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jfs-components",
-  "version": "0.0.73",
+  "version": "0.0.77",
   "description": "React Native Jio Finance Components Library",
   "author": "sunshuaiqi@gmail.com",
   "license": "MIT",
@@ -36,8 +36,6 @@
     "storybook-web": "storybook dev -p 6006",
     "build:storybook-web": "storybook build",
     "deploy:storybook": "vercel --prod",
-    "example": "yarn --cwd example start",
-    "example:install": "yarn --cwd example install",
     "postinstall": "patch-package",
     "icons:generate": "node scripts/generate-icon-registry.js",
     "prepare": "bob build",
@@ -96,9 +94,19 @@
   },
   "peerDependencies": {
     "@react-native-community/blur": ">=4.4.0",
+    "lottie-react": ">=2.4.0",
+    "lottie-react-native": ">=7.0.0",
     "react": "*",
     "react-native": "*"
   },
+  "peerDependenciesMeta": {
+    "lottie-react": {
+      "optional": true
+    },
+    "lottie-react-native": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@babel/core": "^7.28.5",
     "@babel/parser": "^7.28.5",

package/src/components/AccountCard/AccountCard.tsx

@@ -0,0 +1,376 @@
+import React, { useCallback, useMemo, useRef } from 'react'
+import {
+    Image as RNImage,
+    Platform,
+    Pressable,
+    Text,
+    View,
+    type ImageSourcePropType,
+    type ImageStyle,
+    type PressableStateCallbackType,
+    type StyleProp,
+    type TextStyle,
+    type ViewStyle,
+} from 'react-native'
+import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
+import { EMPTY_MODES, cloneChildrenWithModes } from '../../utils/react-utils'
+import Icon from '../../icons/Icon'
+
+const IS_IOS = Platform.OS === 'ios'
+const PRESS_DELAY = IS_IOS ? 130 : 0
+const DEFAULT_IMAGE_RATIO = 125 / 82
+
+const pressedOverlayStyle: ViewStyle = { opacity: 0.7 }
+
+// Default modes for the "Add" placeholder icon (`iconButton/*` tokens).
+// Caller-supplied `modes` are merged on top so every key here can be overridden.
+const ADD_ICON_DEFAULT_MODES: Readonly<Record<string, any>> = Object.freeze({
+    AppearanceBrand: 'Secondary',
+    Emphasis: 'Low',
+    "Button / Size": "M",
+})
+
+export type AccountCardState = 'connected' | 'add'
+
+export type AccountCardProps = {
+    /**
+     * Visual variant of the card.
+     *  - `'connected'` (default): renders a card preview image, a `title` and a
+     *    `subtitle` below it (e.g. account name + masked number).
+     *  - `'add'`: renders an empty placeholder field with a centred `+` icon
+     *    and only the `title`. Use this for the "Add new account" affordance
+     *    that pairs with a list of connected `AccountCard`s.
+     */
+    state?: AccountCardState
+    /** Title rendered below the image / placeholder. */
+    title?: string
+    /**
+     * Subtitle rendered below the title (e.g. masked account number).
+     * Only displayed when `state === 'connected'`.
+     */
+    subtitle?: string
+    /**
+     * Card preview image. Only used when `state === 'connected'` and
+     * `cardSlot` is not provided. Accepts a URL string or any
+     * `ImageSourcePropType` (e.g. `require('./card.png')`).
+     */
+    imageSource?: ImageSourcePropType | string
+    /**
+     * Aspect ratio (width / height) of the image / placeholder area.
+     * Defaults to the Figma reference ratio (`125 / 82` ≈ `1.524`).
+     */
+    imageRatio?: number
+    /**
+     * Override the entire image / placeholder area with a custom node
+     * (e.g. a smaller `DebitCard`, a brand logo, a remote image).
+     * Receives `modes` automatically through `cloneChildrenWithModes`.
+     */
+    cardSlot?: React.ReactNode
+    /**
+     * Icon name shown inside the "Add" placeholder. Defaults to `'ic_add'`.
+     * Only used when `state === 'add'`.
+     */
+    addIcon?: string
+    /**
+     * Press handler. Applied to the whole card so the entire surface is a
+     * single touch target — particularly important for the `'add'` state,
+     * which behaves like a button.
+     */
+    onPress?: () => void
+    /** Disable interaction (also dims the card). */
+    disabled?: boolean
+    /** Design token modes (e.g. `{ 'Color Mode': 'Light' }`). */
+    modes?: Record<string, any>
+    /** Container style override. */
+    style?: StyleProp<ViewStyle>
+    /** Accessibility label (defaults to `title`). */
+    accessibilityLabel?: string
+    /** Accessibility hint forwarded to the underlying `Pressable`. */
+    accessibilityHint?: string
+}
+
+const toNumber = (value: unknown, fallback: number): number => {
+    if (typeof value === 'number') return Number.isFinite(value) ? value : fallback
+    if (typeof value === 'string') {
+        const parsed = Number(value)
+        return Number.isFinite(parsed) ? parsed : fallback
+    }
+    return fallback
+}
+
+const toFontWeight = (
+    value: unknown,
+    fallback: TextStyle['fontWeight']
+): TextStyle['fontWeight'] => {
+    if (typeof value === 'number') return String(value) as TextStyle['fontWeight']
+    if (typeof value === 'string') return value as TextStyle['fontWeight']
+    return fallback
+}
+
+const normalizeImageSource = (
+    src: AccountCardProps['imageSource']
+): ImageSourcePropType | undefined => {
+    if (src == null) return undefined
+    if (typeof src === 'string') return { uri: src }
+    return src
+}
+
+/**
+ * `AccountCard` — a compact card preview used to represent a linked
+ * financial account in lists / grids.
+ *
+ * Two visual states are supported via the `state` prop:
+ *
+ *  1. `'connected'` (default): renders a small card-art preview, a bold
+ *     `title` and a regular-weight `subtitle` (e.g. masked account number).
+ *  2. `'add'`: renders a soft-tinted placeholder field with a centred `+`
+ *     icon and the `title` underneath, intended as the "add new account"
+ *     entry-point at the end of a list of connected accounts.
+ *
+ * All values resolve through the `accountCard/*` design tokens with
+ * sensible Figma defaults so the card renders correctly out of the box.
+ *
+ * @component
+ * @param {AccountCardProps} props
+ */
+function AccountCard({
+    state = 'connected',
+    title = 'Personal account',
+    subtitle = '**** 5651',
+    imageSource,
+    imageRatio = DEFAULT_IMAGE_RATIO,
+    cardSlot,
+    addIcon = 'ic_add',
+    onPress,
+    disabled = false,
+    modes = EMPTY_MODES,
+    style,
+    accessibilityLabel,
+    accessibilityHint,
+}: AccountCardProps) {
+    const iconModes = useMemo(
+        () =>
+            modes === EMPTY_MODES
+                ? ADD_ICON_DEFAULT_MODES
+                : { ...ADD_ICON_DEFAULT_MODES, ...modes },
+        [modes],
+    )
+
+    // ---- Tokens ---------------------------------------------------------
+    const gap = toNumber(getVariableByName('accountCard/gap', modes), 8)
+    const textWrapGap = toNumber(getVariableByName('accountCard/textWrap/gap', modes), 0)
+
+    const titleColor =
+        (getVariableByName('accountCard/title/foreground', modes) as string | null) ?? '#0d0d0f'
+    const titleFontFamily =
+        (getVariableByName('accountCard/title/fontFamily', modes) as string | null) ?? 'JioType Var'
+    const titleFontSize = toNumber(getVariableByName('accountCard/title/fontSize', modes), 12)
+    const titleLineHeight = toNumber(getVariableByName('accountCard/title/lineHeight', modes), 16)
+    const titleFontWeight = toFontWeight(
+        getVariableByName('accountCard/title/fontWeight', modes),
+        '700'
+    )
+
+    const subtitleColor =
+        (getVariableByName('accountCard/subtitle/foreground', modes) as string | null) ?? '#24262b'
+    const subtitleFontFamily =
+        (getVariableByName('accountCard/subtitle/fontFamily', modes) as string | null) ??
+        'JioType Var'
+    const subtitleFontSize = toNumber(
+        getVariableByName('accountCard/subtitle/fontSize', modes),
+        12
+    )
+    const subtitleLineHeight = toNumber(
+        getVariableByName('accountCard/subtitle/lineHeight', modes),
+        16
+    )
+    const subtitleFontWeight = toFontWeight(
+        getVariableByName('accountCard/subtitle/fontWeight', modes),
+        '400'
+    )
+
+    const addFieldRadius = toNumber(
+        getVariableByName('accountCard/addItemField/radius', modes),
+        8
+    )
+    const addFieldBg =
+        (getVariableByName('accountCard/addItemField/bg', modes) as string | null) ?? '#ede8ff'
+
+    const addIconColor =
+        (getVariableByName('iconButton/icon/color', iconModes) as string | null) ?? '#5d00b5'
+    const addIconSize = toNumber(getVariableByName('iconButton/icon/size', iconModes), 16)
+
+    // ---- Styles ---------------------------------------------------------
+    const titleStyle: TextStyle = {
+        color: titleColor,
+        fontFamily: titleFontFamily,
+        fontSize: titleFontSize,
+        lineHeight: titleLineHeight,
+        fontWeight: titleFontWeight,
+        width: '100%',
+    }
+
+    const subtitleStyle: TextStyle = {
+        color: subtitleColor,
+        fontFamily: subtitleFontFamily,
+        fontSize: subtitleFontSize,
+        lineHeight: subtitleLineHeight,
+        fontWeight: subtitleFontWeight,
+        width: '100%',
+    }
+
+    const imageBoxStyle: ViewStyle = {
+        width: '100%',
+        aspectRatio: imageRatio,
+        overflow: 'hidden',
+    }
+
+    // RN's `<Image>` accepts `ImageStyle`, which has a narrower `overflow`
+    // union than `ViewStyle`. Build the image-only style separately so the
+    // shared box dimensions can be reused without a cast.
+    const imageStyle: ImageStyle = {
+        width: '100%',
+        aspectRatio: imageRatio,
+    }
+
+    const addFieldStyle: ViewStyle = {
+        ...imageBoxStyle,
+        backgroundColor: addFieldBg,
+        borderRadius: addFieldRadius,
+        alignItems: 'center',
+        justifyContent: 'center',
+    }
+
+    // ---- Image / placeholder area --------------------------------------
+    const renderCardArea = (): React.ReactNode => {
+        if (cardSlot !== undefined && cardSlot !== null) {
+            const processed = cloneChildrenWithModes(cardSlot, modes)
+            return (
+                <View style={imageBoxStyle} pointerEvents="box-none">
+                    {processed.length === 1 ? processed[0] : processed}
+                </View>
+            )
+        }
+
+        if (state === 'add') {
+            return (
+                <View style={addFieldStyle} accessibilityElementsHidden importantForAccessibility="no">
+                    <Icon name={addIcon} size={addIconSize} color={addIconColor} />
+                </View>
+            )
+        }
+
+        const normalized = normalizeImageSource(imageSource)
+        if (normalized) {
+            return (
+                <RNImage
+                    source={normalized}
+                    style={imageStyle}
+                    resizeMode="cover"
+                    accessibilityElementsHidden
+                    importantForAccessibility="no"
+                />
+            )
+        }
+
+        return <View style={imageBoxStyle} />
+    }
+
+    // ---- Pressable wiring ----------------------------------------------
+    // Keep React state out of the press path. `Pressable`'s style callback
+    // applies the pressed visual without a re-render.
+    const userHandlersRef = useRef<{
+        onPressIn?: (e: any) => void
+        onPressOut?: (e: any) => void
+    }>({})
+
+    const handlePressIn = useCallback((e: any) => {
+        userHandlersRef.current.onPressIn?.(e)
+    }, [])
+    const handlePressOut = useCallback((e: any) => {
+        userHandlersRef.current.onPressOut?.(e)
+    }, [])
+
+    const containerStyle: ViewStyle = useMemo(
+        () => ({
+            width: '100%',
+            flexDirection: 'column',
+            alignItems: 'flex-start',
+            gap,
+            opacity: disabled ? 0.5 : 1,
+        }),
+        [gap, disabled]
+    )
+
+    const pressableStyle = useCallback(
+        ({ pressed }: PressableStateCallbackType): StyleProp<ViewStyle> => [
+            containerStyle,
+            style,
+            pressed && !disabled && onPress ? pressedOverlayStyle : null,
+        ],
+        [containerStyle, style, disabled, onPress]
+    )
+
+    const showSubtitle = state === 'connected' && subtitle != null && subtitle !== ''
+
+    const a11yRole = onPress ? 'button' : undefined
+    const a11yLabel = accessibilityLabel ?? title
+
+    const content = (
+        <>
+            {renderCardArea()}
+            {(title != null && title !== '') || showSubtitle ? (
+                <View
+                    style={{
+                        width: '100%',
+                        flexDirection: 'column',
+                        alignItems: 'flex-start',
+                        gap: textWrapGap,
+                    }}
+                >
+                    {title != null && title !== '' ? (
+                        <Text style={titleStyle} numberOfLines={1}>
+                            {title}
+                        </Text>
+                    ) : null}
+                    {showSubtitle ? (
+                        <Text style={subtitleStyle} numberOfLines={1}>
+                            {subtitle}
+                        </Text>
+                    ) : null}
+                </View>
+            ) : null}
+        </>
+    )
+
+    if (!onPress) {
+        return (
+            <View
+                accessibilityLabel={a11yLabel}
+                accessibilityHint={accessibilityHint}
+                style={[containerStyle, style]}
+            >
+                {content}
+            </View>
+        )
+    }
+
+    return (
+        <Pressable
+            accessibilityRole={a11yRole}
+            accessibilityLabel={a11yLabel}
+            accessibilityHint={accessibilityHint}
+            accessibilityState={{ disabled }}
+            onPress={disabled ? undefined : onPress}
+            disabled={disabled}
+            onPressIn={handlePressIn}
+            onPressOut={handlePressOut}
+            unstable_pressDelay={PRESS_DELAY}
+            style={pressableStyle}
+        >
+            {content}
+        </Pressable>
+    )
+}
+
+export default React.memo(AccountCard)