jfs-components 0.0.74 → 0.0.78

package/lib/typescript/src/components/Stepper/Step.d.ts

@@ -6,11 +6,14 @@ export type StepProps = {
     modes?: Record<string, any>;
     style?: ViewStyle;
     index?: number;
+    showLine?: boolean;
     connectorStyle?: ViewStyle;
     title?: string;
     supportingText?: string;
+    metaText?: string;
     subtitle?: boolean;
+    meta?: boolean;
     status?: StepStatus;
 };
-export declare function Step({ children, modes, style, index, connectorStyle, title, supportingText, subtitle, status, }: StepProps): import("react/jsx-runtime").JSX.Element;
+export declare function Step({ children, modes, style, index, showLine, connectorStyle, title, supportingText, metaText, subtitle, meta, status, }: StepProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=Step.d.ts.map

package/lib/typescript/src/components/Stepper/StepLabel.d.ts

@@ -2,8 +2,11 @@ import { type ViewStyle } from 'react-native';
 export type StepLabelProps = {
     title?: string;
     supportingText?: string;
+    metaText?: string;
+    subtitle?: boolean;
+    meta?: boolean;
     modes?: Record<string, any>;
     style?: ViewStyle;
 };
-export declare function StepLabel({ title, supportingText, modes, style, }: StepLabelProps): import("react/jsx-runtime").JSX.Element;
+export declare function StepLabel({ title, supportingText, metaText, subtitle, meta, modes, style, }: StepLabelProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=StepLabel.d.ts.map

package/lib/typescript/src/components/Stepper/Stepper.d.ts

@@ -3,7 +3,9 @@ import { type ViewStyle } from 'react-native';
 import { Step } from './Step';
 import { StepLabel } from './StepLabel';
 export { Step, StepLabel };
-type StepperProps = {
+export type { StepProps, StepStatus } from './Step';
+export type { StepLabelProps } from './StepLabel';
+export type StepperProps = {
     children?: React.ReactNode;
     modes?: Record<string, any>;
     style?: ViewStyle;

package/lib/typescript/src/components/SuggestiveSearch/SuggestiveSearch.d.ts

@@ -0,0 +1,123 @@
+import React from 'react';
+import { type StyleProp, type TextInputProps as RNTextInputProps, type TextStyle, type ViewStyle } from 'react-native';
+export type SuggestiveSearchOptionValue = string | number;
+export type SuggestiveSearchOption = {
+    /** Stable, unique value used to identify the suggestion. */
+    value: SuggestiveSearchOptionValue;
+    /** Human-readable label shown in the suggestion list and the input. */
+    label: string;
+    /** Whether the suggestion is non-selectable. */
+    disabled?: boolean;
+};
+/**
+ * Suggestions accept either a bare string (used as both value and label) or a
+ * full `{ value, label }` option object for richer data.
+ */
+export type SuggestiveSearchItem = string | SuggestiveSearchOption;
+export type SuggestiveSearchProps = {
+    /** Label rendered above the input. */
+    label?: string;
+    /** Placeholder text shown when the query is empty. */
+    placeholder?: string;
+    /**
+     * Suggestions to filter against the current query. May be bare strings or
+     * `{ value, label }` objects.
+     */
+    items?: SuggestiveSearchItem[];
+    /**
+     * Current query text (controlled). When `undefined` the component manages
+     * its own query state internally.
+     */
+    inputValue?: string;
+    /** Initial query text for uncontrolled mode. */
+    defaultInputValue?: string;
+    /** Called whenever the query text changes (typing or selection). */
+    onInputChange?: (text: string) => void;
+    /**
+     * Currently selected suggestion value (controlled). When `undefined` the
+     * component tracks the selection internally.
+     */
+    value?: SuggestiveSearchOptionValue | null;
+    /** Initial selected value for uncontrolled mode. */
+    defaultValue?: SuggestiveSearchOptionValue | null;
+    /** Called when a suggestion is chosen. */
+    onValueChange?: (value: SuggestiveSearchOptionValue | null, option?: SuggestiveSearchOption) => void;
+    /**
+     * Custom predicate deciding whether an option matches the current query.
+     * Defaults to a case-insensitive substring match on the label.
+     */
+    filter?: (query: string, option: SuggestiveSearchOption) => boolean;
+    /**
+     * Minimum number of characters required before suggestions are shown.
+     * @default 1
+     */
+    minChars?: number;
+    /** Caps the number of suggestions rendered. Defaults to no limit. */
+    maxResults?: number;
+    /**
+     * Highlights the matched substring of each suggestion in bold.
+     * @default true
+     */
+    highlightMatch?: boolean;
+    /**
+     * Message shown when the query has matched no suggestions. When omitted,
+     * the dropdown simply stays hidden on an empty result set.
+     */
+    emptyMessage?: string;
+    /** Custom renderer for a suggestion row (overrides the default label). */
+    renderItem?: (option: SuggestiveSearchOption, meta: {
+        query: string;
+        isSelected: boolean;
+    }) => React.ReactNode;
+    /** Controlled open state of the suggestion dropdown. */
+    open?: boolean;
+    /** Initial open state for uncontrolled mode. */
+    defaultOpen?: boolean;
+    /** Called whenever the open state changes. */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Maximum height of the suggestion list before it becomes scrollable.
+     * @default 240
+     */
+    menuMaxHeight?: number;
+    /**
+     * Vertical gap between the input and the suggestion dropdown.
+     * @default 6
+     */
+    menuOffset?: number;
+    /** Renders a required asterisk next to the label. */
+    isRequired?: boolean;
+    /** Disables interaction and dims the field. */
+    isDisabled?: boolean;
+    /** Marks the field as invalid and shows `errorMessage`. */
+    isInvalid?: boolean;
+    /** Renders the field as read-only (non-interactive, not dimmed). */
+    isReadOnly?: boolean;
+    /** Helper text displayed below the input. */
+    supportText?: string;
+    /** Replaces `supportText` when `isInvalid` is true. */
+    errorMessage?: string;
+    /** Modes for design token resolution. */
+    modes?: Record<string, any>;
+    /** Style overrides for the outermost wrapper. */
+    style?: StyleProp<ViewStyle>;
+    /** Style overrides for the input row. */
+    inputStyle?: StyleProp<ViewStyle>;
+    /** Style overrides for the input text. */
+    inputTextStyle?: StyleProp<TextStyle>;
+    /** Style overrides for the suggestion dropdown container. */
+    menuStyle?: StyleProp<ViewStyle>;
+    /** Accessibility label. Defaults to the visible label / placeholder. */
+    accessibilityLabel?: string;
+    /** Accessibility hint. */
+    accessibilityHint?: string;
+    /** Called when the input receives focus. */
+    onFocus?: RNTextInputProps['onFocus'];
+    /** Called when the input loses focus. */
+    onBlur?: RNTextInputProps['onBlur'];
+    /** Test identifier. */
+    testID?: string;
+};
+declare function SuggestiveSearch({ label, placeholder, items, inputValue, defaultInputValue, onInputChange, value, defaultValue, onValueChange, filter, minChars, maxResults, highlightMatch, emptyMessage, renderItem, open, defaultOpen, onOpenChange, menuMaxHeight, menuOffset, isRequired, isDisabled, isInvalid, isReadOnly, supportText, errorMessage, modes: propModes, style, inputStyle, inputTextStyle, menuStyle, accessibilityLabel, accessibilityHint, onFocus, onBlur, testID, }: SuggestiveSearchProps): import("react/jsx-runtime").JSX.Element;
+export default SuggestiveSearch;
+//# sourceMappingURL=SuggestiveSearch.d.ts.map

package/lib/typescript/src/components/Text/Text.d.ts

@@ -20,7 +20,26 @@ export type TextProps = {
     style?: StyleProp<TextStyle>;
     /** Number of lines to limit the text to. */
     numberOfLines?: number;
+    /**
+     * Explicit per-instance loading override. When `true`, this `Text` renders
+     * a skeleton placeholder regardless of any surrounding `<SkeletonGroup>`.
+     * When `false`, the surrounding group is ignored for this instance. When
+     * omitted, the surrounding group's `loading` flag wins.
+     */
+    loading?: boolean;
+    /**
+     * Optional width used while the skeleton is showing. Numbers are dp;
+     * `'100%'` (etc.) is a valid RN dimension. Defaults to a character-count
+     * heuristic based on the resolved font size and the supplied content.
+     */
+    skeletonWidth?: number | `${number}%`;
+    /**
+     * Optional explicit line count for the skeleton placeholder. Defaults to
+     * `numberOfLines ?? 1`. Useful when `numberOfLines` is intentionally
+     * unbounded but you want a sensible multi-line placeholder.
+     */
+    skeletonLines?: number;
 };
-declare function Text({ text, children, textAlign, modes, style, numberOfLines, }: TextProps): import("react/jsx-runtime").JSX.Element;
+declare function Text({ text, children, textAlign, modes, style, numberOfLines, loading, skeletonWidth, skeletonLines, }: TextProps): import("react/jsx-runtime").JSX.Element;
 export default Text;
 //# sourceMappingURL=Text.d.ts.map

package/lib/typescript/src/components/index.d.ts

@@ -24,9 +24,11 @@ export { default as Divider, type DividerProps, type DividerDirection } from './
 export { default as Drawer } from './Drawer/Drawer';
 export { default as Dropdown, DropdownItem, type DropdownProps, type DropdownItemProps } from './Dropdown/Dropdown';
 export { default as DropdownInput, type DropdownInputProps, type DropdownInputOption, type DropdownInputOptionValue } from './DropdownInput/DropdownInput';
+export { default as SuggestiveSearch, type SuggestiveSearchProps, type SuggestiveSearchOption, type SuggestiveSearchOptionValue, type SuggestiveSearchItem } from './SuggestiveSearch/SuggestiveSearch';
 export { default as CardCTA, type CardCTAProps, type CardCTAType } from './CardCTA/CardCTA';
 export { default as DebitCard, type DebitCardProps } from './DebitCard/DebitCard';
 export { default as FilterBar } from './FilterBar/FilterBar';
+export { default as FullscreenModal, type FullscreenModalProps } from './FullscreenModal/FullscreenModal';
 export { default as Form, type FormProps } from './Form/Form';
 export { useFormContext } from './Form/Form';
 export { default as FormField, type FormFieldProps, type FormFieldType } from './FormField/FormField';
@@ -47,9 +49,11 @@ export { default as LinearMeter, type LinearMeterProps } from './LinearMeter/Lin
 export { default as LinearProgress, type LinearProgressProps } from './LinearProgress/LinearProgress';
 export { default as ListGroup } from './ListGroup/ListGroup';
 export { default as LottieIntroBlock, type LottieIntroBlockProps } from './LottieIntroBlock/LottieIntroBlock';
+export { default as LottiePlayer, type LottiePlayerProps, type LottieAnimationSource } from './LottiePlayer/LottiePlayer';
 export { default as ListItem } from './ListItem/ListItem';
 export { default as MediaCard, type MediaCardProps } from './MediaCard/MediaCard';
 export { default as MerchantProfile, type MerchantProfileProps } from './MerchantProfile/MerchantProfile';
+export { default as MessageField, type MessageFieldProps, type MessageFieldState } from './MessageField/MessageField';
 export { default as MetricLegendItem, type MetricLegendItemProps } from './MetricLegendItem/MetricLegendItem';
 export { default as MoneyValue } from './MoneyValue/MoneyValue';
 export { default as NoteInput, type NoteInputProps } from './NoteInput/NoteInput';
@@ -59,9 +63,9 @@ export { default as Numpad, type NumpadProps, type NumpadKeyValue } from './Nump
 export { default as Title, type TitleProps } from './Title/Title';
 export { default as Screen, type ScreenProps } from './Screen/Screen';
 export { default as Section } from './Section/Section';
-export { default as Stepper } from './Stepper/Stepper';
-export { Step } from './Stepper/Step';
-export { StepLabel } from './Stepper/StepLabel';
+export { default as Stepper, type StepperProps } from './Stepper/Stepper';
+export { Step, type StepProps, type StepStatus } from './Stepper/Step';
+export { StepLabel, type StepLabelProps } from './Stepper/StepLabel';
 export { default as TextInput } from './TextInput/TextInput';
 export { default as StatusHero, type StatusHeroProps } from './StatusHero/StatusHero';
 export { default as ThreadHero, type ThreadHeroProps } from './ThreadHero/ThreadHero';
@@ -73,6 +77,7 @@ export { default as UpiHandle } from './UpiHandle/UpiHandle';
 export { default as VStack, type VStackProps } from './VStack/VStack';
 export { default as ChipGroup, type ChipGroupProps } from './ChipGroup/ChipGroup';
 export { default as EmptyState, type EmptyStateProps } from './EmptyState/EmptyState';
+export { default as ExpandableCheckbox, type ExpandableCheckboxProps } from './ExpandableCheckbox/ExpandableCheckbox';
 export { default as Accordion, type AccordionProps } from './Accordion/Accordion';
 export { default as AccordionCheckbox, type AccordionCheckboxProps } from './AccordionCheckbox/AccordionCheckbox';
 export { default as ActionTile, type ActionTileProps } from './ActionTile/ActionTile';

package/lib/typescript/src/icons/Icon.d.ts

@@ -18,6 +18,12 @@ type IconProps = AccessibilityProps & {
     size?: number;
     color?: string;
     style?: StyleProp<ViewStyle>;
+    /**
+     * Explicit per-instance loading override. When `true`, renders a square
+     * skeleton at the icon's size; when `false`, the surrounding
+     * `<SkeletonGroup>` is ignored. Defaults to inheriting from the group.
+     */
+    loading?: boolean;
 };
 /**
  * Generic Icon component.
@@ -43,6 +49,6 @@ type IconProps = AccessibilityProps & {
  * <Icon source={BrandLogo} size={24} color="red" />
  * ```
  */
-declare function Icon({ name, source, size, color, style, ...rest }: IconProps): import("react/jsx-runtime").JSX.Element;
+declare function Icon({ name, source, size, color, style, loading, ...rest }: IconProps): import("react/jsx-runtime").JSX.Element;
 export default Icon;
 //# sourceMappingURL=Icon.d.ts.map

package/lib/typescript/src/icons/registry.d.ts

@@ -4,7 +4,7 @@
  * Auto-generated from SVG files in src/icons/
  * DO NOT EDIT MANUALLY - Run "npm run icons:generate" to regenerate
  *
- * Generated: 2026-05-19T16:28:08.570Z
+ * Generated: 2026-05-29T10:37:24.494Z
  */
 export declare const iconRegistry: Record<string, {
     path: string;

package/lib/typescript/src/index.d.ts

@@ -3,4 +3,5 @@ export * as Icons from './icons';
 export * from './design-tokens';
 export * from './Containers';
 export * from './utils';
+export * from './skeleton';
 //# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,60 @@
+import React from 'react';
+import { type DimensionValue, type StyleProp, type ViewStyle } from 'react-native';
+import { type SkeletonKind } from './shimmer-tokens';
+export interface SkeletonProps {
+    /**
+     * Visual category — controls only the corner-radius token. Sizes are still
+     * supplied via `width`/`height`. Defaults to `'other'`.
+     */
+    kind?: SkeletonKind;
+    /** Width of the rectangular placeholder. Numbers are dp, strings are RN dimensions. */
+    width?: DimensionValue;
+    /** Height of the rectangular placeholder. */
+    height?: DimensionValue;
+    /**
+     * Optional style overrides merged onto the base layer (e.g. `marginTop`,
+     * `alignSelf`). Avoid `backgroundColor` and `borderRadius` here — use the
+     * design tokens instead so the system stays consistent.
+     */
+    style?: StyleProp<ViewStyle>;
+    /**
+     * Modes for token resolution (forwarded to `getVariableByName`). Most
+     * consumers can omit this — defaults work for every standard mode.
+     */
+    modes?: Record<string, any>;
+}
+/**
+ * Atomic skeleton placeholder. Renders a base rectangle (background colour +
+ * radius per kind) plus an animated overlay that produces the shimmer.
+ *
+ * Two visual modes share the same engine:
+ *
+ *   - Normal mode (gradient: true): a soft 135° band translates diagonally
+ *     across the box end-to-end. Its alpha inside the moving band varies
+ *     33% → 100% → 33% via gradient stops. The sawtooth clock travels from
+ *     fully off-screen (−overshoot) to fully off-screen (+overshoot) so the
+ *     transparent gradient tails clear the box before the loop resets.
+ *
+ *   - Reduced-motion mode (gradient: false): a solid white overlay covers the
+ *     box and pulses opacity 33% → 100% → 33% in place, with no translation,
+ *     ease-in-out timing and no stagger.
+ *
+ * Critical for cross-platform consistency:
+ *
+ *   - The SVG gradient uses `gradientUnits="userSpaceOnUse"` with absolute
+ *     pixel coordinates that have Δx === Δy. This guarantees the visual angle
+ *     is exactly 45° in screen pixels (= 135° CSS) on ANY aspect ratio. With
+ *     the default `objectBoundingBox` units, the gradient line is normalised
+ *     to the box and tilts off-angle on non-square boxes.
+ *
+ *   - The whole animated overlay sits inside a clipping parent (`overflow:
+ *     hidden` + `borderRadius`). Translating an `Animated.View` is GPU-cheap
+ *     on both iOS/Android (Reanimated UI thread) and on web (CSS transforms).
+ *
+ *   - The SVG `id` for the gradient is per-instance (`useId`) so multiple
+ *     skeletons on a web page don't collide on `url(#…)` resolution.
+ */
+declare function SkeletonImpl({ kind, width, height, style, modes, }: SkeletonProps): import("react/jsx-runtime").JSX.Element;
+declare const Skeleton: React.MemoExoticComponent<typeof SkeletonImpl>;
+export default Skeleton;
+//# sourceMappingURL=Skeleton.d.ts.map

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

@@ -0,0 +1,78 @@
+import { type ReactNode } from 'react';
+import { type SharedValue } from 'react-native-reanimated';
+/**
+ * Shape of the value carried by the SkeletonContext.
+ *
+ * The provider owns ONE Reanimated shared value per group; every child
+ * `<Skeleton>` reads it on the UI thread and computes its own opacity from
+ * `(clock + perItemPhaseOffset)`. That keeps per-skeleton work bounded to a
+ * single `useAnimatedStyle` and avoids per-block JS timers.
+ */
+export interface SkeletonContextValue {
+    /** Whether the surrounding group is currently in loading state. */
+    active: boolean;
+    /**
+     * Whether reduced-motion treatment should be applied. May be auto-detected
+     * from the OS or explicitly overridden via the `reducedMotion` prop on
+     * `<SkeletonGroup>`.
+     */
+    reducedMotion: boolean;
+    /**
+     * Shared phase value driven on the UI thread. Sawtooth: ramps linearly
+     * (or eased) from 0 -> 1 over one `SHIMMER.*.durationMs` period, then
+     * jumps back to 0 and repeats. Sawtooth is required so that the moving
+     * shimmer band sweeps from end to end at a constant heading and resets
+     * cleanly; a ping-pong clock would produce a discontinuity in
+     * `(clock + phaseOffset) % 1` at the apex, which translates to a visible
+     * jump in the band's position when stagger offsets are non-zero.
+     */
+    clock: SharedValue<number>;
+    /**
+     * Atomically registers a child skeleton and returns its registration index.
+     * The order is stable for the life of the parent group; the counter is held
+     * in a ref so React's render lifecycle doesn't reshuffle it.
+     */
+    nextIndex(): number;
+}
+export interface SkeletonGroupProps {
+    /** When true, descendant skeleton-aware primitives render placeholders. */
+    loading: boolean;
+    /**
+     * Override the auto-detected reduced-motion preference. Pass `undefined` to
+     * use the system value (default). Pass `true`/`false` to force.
+     */
+    reducedMotion?: boolean;
+    children?: ReactNode;
+}
+/**
+ * Provider that flips an entire subtree into "loading" mode and supplies the
+ * shared shimmer clock + stagger index source to every descendant skeleton.
+ *
+ * Usage:
+ *   ```tsx
+ *   <SkeletonGroup loading={!data}>
+ *     <Card>...JFS primitives auto-skeletonize...</Card>
+ *   </SkeletonGroup>
+ *   ```
+ *
+ * Nesting is supported — an inner `<SkeletonGroup>` fully overrides the
+ * outer one for its subtree (its own clock, its own index counter).
+ */
+export declare function SkeletonGroup({ loading, reducedMotion: reducedMotionOverride, children, }: SkeletonGroupProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Internal hook used by skeleton-aware primitives (and by `<Skeleton>`
+ * itself) to read the surrounding context.
+ *
+ * Always returns a non-null value: when called outside any provider, the
+ * returned object has `active: false` so the consumer falls through to its
+ * normal render path. The fallback clock is a no-op shared value so any
+ * direct `<Skeleton>` usage outside a group still has something safe to read.
+ */
+export declare function useSkeleton(): SkeletonContextValue;
+/**
+ * Convenience wrapper around `useSkeleton().nextIndex()` that pins the
+ * returned value across re-renders. Each `<Skeleton>` calls this once on
+ * mount; subsequent renders re-use the same index from the closure.
+ */
+export declare function useStaggerIndex(): number;
+//# sourceMappingURL=SkeletonGroup.d.ts.map

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

@@ -0,0 +1,5 @@
+export { default as Skeleton, type SkeletonProps } from './Skeleton';
+export { SkeletonGroup, useSkeleton, useStaggerIndex, type SkeletonGroupProps, type SkeletonContextValue, } from './SkeletonGroup';
+export { useReducedMotion } from './useReducedMotion';
+export { SHIMMER, SKELETON_TOKEN, SKELETON_FALLBACK, type SkeletonKind } from './shimmer-tokens';
+//# sourceMappingURL=index.d.ts.map

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.74",
+  "version": "0.0.78",
   "description": "React Native Jio Finance Components Library",
   "author": "sunshuaiqi@gmail.com",
   "license": "MIT",
@@ -94,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",