jfs-components 0.0.74 → 0.0.77

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

@@ -3,50 +3,55 @@ import { type ViewStyle, type StyleProp } from 'react-native';
 export type ActionFooterProps = {
     /**
      * Content to render inside the action footer slot.
-     * Typically includes IconButton and Button components.
+     * Typically includes `IconButton` and `Button` components.
+     * `IconButton` children keep their intrinsic square size; everything else
+     * is auto-stretched to share the remaining horizontal space equally.
      */
     children?: React.ReactNode;
     /**
      * Mode configuration passed to the token resolver.
-     * Pass the same modes to children components for consistent theming.
+     * Automatically merged into every slot child via {@link cloneChildrenWithModes}
+     * so callers don't have to thread modes down by hand.
      */
     modes?: Record<string, any>;
     /**
-     * Optional style overrides for the container
+     * Optional style overrides for the outer container.
      */
     style?: StyleProp<ViewStyle>;
     /**
-     * Accessibility label for the footer region
+     * Accessibility label for the footer region (announced for the toolbar).
      */
     accessibilityLabel?: string;
 };
 /**
- * ActionFooter component that provides a fixed footer container for action buttons.
+ * ActionFooter — a sticky bottom container for primary screen actions.
  *
- * This component is designed to hold action items like IconButton and Button components
- * at the bottom of a screen. It includes a shadow for visual separation from content above.
+ * Layout contract:
+ *   - The outer container stretches horizontally (`alignSelf: 'stretch'`) so
+ *     it fills the parent regardless of whether the parent is a flex column,
+ *     a ScrollView contentContainer, or a plain View.
+ *   - The inner slot is a single row sized by its tallest child. It does NOT
+ *     use `flex: 1` — that previously caused the row to collapse to zero on
+ *     the first Yoga pass on native, taking the button labels with it.
+ *   - `IconButton` children keep their intrinsic square size.
+ *   - Every other child is auto-stretched with the Yoga-safe stretch style
+ *     above so two `<Button>` siblings render at equal width on iOS, Android,
+ *     and Web.
  *
- * The `modes` prop is automatically passed to all slot children. If a child has its own
- * `modes` prop, it will be merged with the parent's modes (child modes take precedence).
- *
- * @component
- * @param {Object} props - Component props
- * @param {React.ReactNode} [props.children] - Action elements to display (e.g., IconButton, Button)
- * @param {Object} [props.modes={}] - Mode configuration for design tokens (automatically passed to children)
- * @param {Object} [props.style] - Optional style overrides
- * @param {string} [props.accessibilityLabel] - Accessibility label for the footer region
+ * The `modes` prop is automatically pushed down to every slot child via
+ * {@link cloneChildrenWithModes}; explicit child-level modes win over the
+ * parent's modes.
  *
  * @example
  * ```tsx
- * // Basic usage - modes are automatically passed to all children.
- * // Non-IconButton children (e.g., Button) are auto-stretched to fill.
  * <ActionFooter modes={modes}>
  *   <IconButton iconName="ic_split" />
- *   <Button label="Request" />
- *   <Button label="Pay" />
+ *   <Button label="Request" modes={{ AppearanceBrand: 'Secondary' }} />
+ *   <Button label="Pay" modes={{ AppearanceBrand: 'Primary' }} />
  * </ActionFooter>
  * ```
  */
 declare function ActionFooter({ children, modes, style, accessibilityLabel, }: ActionFooterProps): import("react/jsx-runtime").JSX.Element;
-export default ActionFooter;
+declare const _default: React.MemoExoticComponent<typeof ActionFooter>;
+export default _default;
 //# sourceMappingURL=ActionFooter.d.ts.map

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

@@ -27,8 +27,14 @@ export type AvatarProps = {
     accessibilityLabel?: string;
     onPress?: () => void;
     disabled?: boolean;
+    /**
+     * Explicit per-instance loading override. When `true`, renders a
+     * same-size circular skeleton instead of the avatar. Defaults to
+     * inheriting from the surrounding `<SkeletonGroup>`.
+     */
+    loading?: boolean;
 } & Omit<React.ComponentProps<typeof View>, 'style' | 'accessibilityRole' | 'accessibilityLabel'>;
-declare function Avatar({ monogram, style, modes, imageSource, accessibilityLabel: _accessibilityLabel, ...rest }: AvatarProps): import("react/jsx-runtime").JSX.Element;
+declare function Avatar({ monogram, style, modes, imageSource, accessibilityLabel: _accessibilityLabel, loading, ...rest }: AvatarProps): import("react/jsx-runtime").JSX.Element;
 declare const _default: React.MemoExoticComponent<typeof Avatar>;
 export default _default;
 //# sourceMappingURL=Avatar.d.ts.map

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

@@ -10,7 +10,13 @@ type BadgeProps = {
     accessibilityLabel?: string;
     style?: ViewStyle;
     labelStyle?: TextStyle;
+    /**
+     * Explicit per-instance loading override. When `true`, renders a
+     * badge-shaped skeleton placeholder instead of the badge. Defaults to
+     * inheriting from the surrounding `<SkeletonGroup>`.
+     */
+    loading?: boolean;
 } & Omit<React.ComponentProps<typeof View>, 'style' | 'accessibilityLabel' | 'accessibilityRole'>;
-declare function Badge({ label, modes, onPress, accessibilityLabel, style, labelStyle, ...rest }: BadgeProps): import("react/jsx-runtime").JSX.Element;
+declare function Badge({ label, modes, onPress, accessibilityLabel, style, labelStyle, loading, ...rest }: BadgeProps): import("react/jsx-runtime").JSX.Element;
 export default Badge;
 //# sourceMappingURL=Badge.d.ts.map

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

@@ -40,6 +40,13 @@ export type ButtonProps = SafePressableProps & {
      * Web-specific accessibility props (only used on web platform)
      */
     webAccessibilityProps?: WebAccessibilityProps;
+    /**
+     * Explicit per-instance loading override. When `true`, the button renders
+     * as a pill-shaped skeleton of the same size; when `false`, the
+     * surrounding `<SkeletonGroup>` is ignored. Defaults to inheriting from
+     * the group.
+     */
+    loading?: boolean;
 };
 /**
  * Button component that maps directly to the Figma design using design tokens.
@@ -76,7 +83,7 @@ export type ButtonProps = SafePressableProps & {
  *    advantage of this should pass stable `modes` (the default `EMPTY_MODES`
  *    is already stable) and stable callback props.
  */
-declare function ButtonImpl({ label, children, renderContent, leading, trailing, icon, modes, onPress, disabled, style, labelStyle, accessibilityLabel, accessibilityHint, accessibilityState, webAccessibilityProps, ...rest }: ButtonProps): import("react/jsx-runtime").JSX.Element;
+declare function ButtonImpl({ label, children, renderContent, leading, trailing, icon, modes, onPress, disabled, style, labelStyle, accessibilityLabel, accessibilityHint, accessibilityState, webAccessibilityProps, loading, ...rest }: ButtonProps): import("react/jsx-runtime").JSX.Element;
 declare const Button: React.MemoExoticComponent<typeof ButtonImpl>;
 export default Button;
 //# sourceMappingURL=Button.d.ts.map

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

@@ -54,8 +54,14 @@ type IconButtonProps = SafePressableProps & {
      * Web-specific accessibility props (only used on web platform)
      */
     webAccessibilityProps?: WebAccessibilityProps;
+    /**
+     * Explicit per-instance loading override. When `true`, renders a
+     * same-size pill-shaped skeleton instead of the button. Defaults to
+     * inheriting from the surrounding `<SkeletonGroup>`.
+     */
+    loading?: boolean;
 };
-declare function IconButton({ iconName, source, modes, onPress, disabled, style, accessibilityLabel, accessibilityHint, accessibilityState, webAccessibilityProps, isToggle, activeIcon, activeSource, inactiveIcon, inactiveSource, isActive, ...rest }: IconButtonProps): import("react/jsx-runtime").JSX.Element;
+declare function IconButton({ iconName, source, modes, onPress, disabled, style, accessibilityLabel, accessibilityHint, accessibilityState, webAccessibilityProps, isToggle, activeIcon, activeSource, inactiveIcon, inactiveSource, isActive, loading, ...rest }: IconButtonProps): import("react/jsx-runtime").JSX.Element;
 declare const _default: React.MemoExoticComponent<typeof IconButton>;
 export default _default;
 //# sourceMappingURL=IconButton.d.ts.map

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

@@ -38,8 +38,15 @@ export type ImageProps = {
     /** Hide from the a11y tree (e.g. when image is purely decorative). */
     accessibilityElementsHidden?: boolean | undefined;
     importantForAccessibility?: 'auto' | 'yes' | 'no' | 'no-hide-descendants' | undefined;
+    /**
+     * Explicit per-instance loading override. When `true`, the image renders as
+     * a skeleton placeholder at the same box size; when `false`, the
+     * surrounding `<SkeletonGroup>` is ignored. Defaults to inheriting from
+     * the group.
+     */
+    loading?: boolean | undefined;
 };
-declare function Image({ imageSource, ratio, resizeMode, width, height, borderRadius, style, accessibilityLabel, accessibilityElementsHidden, importantForAccessibility, }: ImageProps): import("react/jsx-runtime").JSX.Element;
+declare function Image({ imageSource, ratio, resizeMode, width, height, borderRadius, style, accessibilityLabel, accessibilityElementsHidden, importantForAccessibility, loading, }: ImageProps): import("react/jsx-runtime").JSX.Element;
 declare const _default: React.MemoExoticComponent<typeof Image>;
 export default _default;
 //# sourceMappingURL=Image.d.ts.map

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

@@ -0,0 +1,85 @@
+import React from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+/**
+ * A parsed Lottie animation. The JSON object you get from
+ * `require('./animation.json')` or `fetch().then(r => r.json())`. We keep the
+ * type intentionally loose because both `lottie-react-native` and `lottie-react`
+ * accept slightly different shapes — `LottiePlayer` narrows back to the
+ * platform-specific type internally.
+ */
+export type LottieAnimationSource = Record<string, unknown>;
+export type LottiePlayerProps = {
+    /**
+     * Parsed Lottie animation JSON. Use `require('./animation.json')` in React
+     * Native or `import animation from './animation.json'` on web.
+     *
+     * URI sources (`{ uri: '...' }`) are intentionally not accepted here — web
+     * Lottie players require the animation data to be pre-parsed. Fetch and
+     * parse the JSON yourself before passing it in if you need a remote source.
+     */
+    source: LottieAnimationSource;
+    /**
+     * Override the rendered size. Pass a number for a square box, or
+     * `{ width, height }` for non-square.
+     *
+     * When omitted, size is resolved from the `media/width` and `media/height`
+     * design tokens (default `117 × 117`). The `Media / Output` collection
+     * exposes `L | M | S` modes (117 / 70 / 20) — pass
+     * `modes={{ 'Media / Output': 'M' }}` to render at 70×70, etc.
+     */
+    size?: number | {
+        width: number;
+        height: number;
+    };
+    /** Play the animation on mount. Defaults to `true`. */
+    autoPlay?: boolean;
+    /** Loop the animation. Defaults to `true`. */
+    loop?: boolean;
+    /** Mode configuration for design-token theming. */
+    modes?: Record<string, any>;
+    /** Style overrides applied to the underlying view. */
+    style?: StyleProp<ViewStyle>;
+    /** Accessibility label. Lottie is decorative by default. */
+    accessibilityLabel?: string;
+    testID?: string;
+};
+/**
+ * Renders a Lottie animation using the consumer's installed
+ * `lottie-react-native` (native) or `lottie-react` (web) — both are declared
+ * as **optional peer dependencies** of `jfs-components`, so installing the
+ * library does not pull them in. Add the relevant package to your app only
+ * if you actually use `LottiePlayer`:
+ *
+ * ```sh
+ * # React Native (iOS / Android)
+ * npm install lottie-react-native
+ * cd ios && pod install
+ *
+ * # Web (or react-native-web)
+ * npm install lottie-react
+ * ```
+ *
+ * The web build (`LottiePlayer.web.tsx`) is picked automatically by Metro /
+ * webpack via platform extensions — same pattern as `MediaCard/GlassFill`.
+ *
+ * Token-driven sizing: when `size` is omitted, `LottiePlayer` reads
+ * `media/width` and `media/height` from the Figma variables resolver, so the
+ * animation matches the surrounding component's `Media / Output` mode
+ * automatically. This is the same sizing contract `PageHero` and
+ * `LottieIntroBlock` use for their `media` slots.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * import animation from './assets/loader.json';
+ *
+ * <LottiePlayer source={animation} />                    // 117 × 117 (default)
+ * <LottiePlayer source={animation} size={70} />          // 70 × 70
+ * <LottiePlayer source={animation} modes={{ 'Media / Output': 'S' }} />  // 20 × 20
+ * <PageHero media={<LottiePlayer source={animation} />} />
+ * ```
+ */
+declare function LottiePlayer({ source, size, autoPlay, loop, modes: propModes, style, accessibilityLabel, testID, }: LottiePlayerProps): import("react/jsx-runtime").JSX.Element;
+declare const _default: React.MemoExoticComponent<typeof LottiePlayer>;
+export default _default;
+//# sourceMappingURL=LottiePlayer.d.ts.map

package/lib/typescript/src/components/LottiePlayer/LottiePlayer.web.d.ts

@@ -0,0 +1,28 @@
+import React from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+export type LottieAnimationSource = Record<string, unknown>;
+export type LottiePlayerProps = {
+    source: LottieAnimationSource;
+    size?: number | {
+        width: number;
+        height: number;
+    };
+    autoPlay?: boolean;
+    loop?: boolean;
+    modes?: Record<string, any>;
+    style?: StyleProp<ViewStyle>;
+    accessibilityLabel?: string;
+    testID?: string;
+};
+/**
+ * Web build of `LottiePlayer` — picked automatically by webpack /
+ * Metro-for-web via the `.web.tsx` platform extension. Uses `lottie-react`
+ * (which wraps `lottie-web`) and renders a plain DOM container.
+ *
+ * Public API mirrors `LottiePlayer.tsx` (native). See that file for the
+ * documented prop reference and usage patterns.
+ */
+declare function LottiePlayer({ source, size, autoPlay, loop, modes: propModes, style, accessibilityLabel, testID, }: LottiePlayerProps): import("react/jsx-runtime").JSX.Element;
+declare const _default: React.MemoExoticComponent<typeof LottiePlayer>;
+export default _default;
+//# sourceMappingURL=LottiePlayer.web.d.ts.map

package/lib/typescript/src/components/LottiePlayer/loadNativeLottieView.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+import { type ViewStyle } from 'react-native';
+/** Props we forward to the underlying native Lottie view. */
+export type NativeLottieViewProps = {
+    source: Record<string, unknown>;
+    autoPlay?: boolean;
+    loop?: boolean;
+    style?: ViewStyle;
+};
+export declare function getNativeLottieView(): React.ComponentType<NativeLottieViewProps>;
+//# sourceMappingURL=loadNativeLottieView.d.ts.map

package/lib/typescript/src/components/LottiePlayer/loadWebLottieView.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+import type { CSSProperties } from 'react';
+/** Props we forward to the underlying web Lottie view. */
+export type WebLottieViewProps = {
+    animationData: Record<string, unknown>;
+    autoplay?: boolean;
+    loop?: boolean;
+    style?: CSSProperties;
+};
+export declare function getWebLottieView(): React.ComponentType<WebLottieViewProps>;
+//# sourceMappingURL=loadWebLottieView.d.ts.map

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

@@ -21,6 +21,23 @@ export type PageHeroProps = {
      * `modes` are automatically cascaded into this slot.
      */
     buttonSlot?: React.ReactNode;
+    /**
+     * Optional media element shown above the text block (eyebrow + headline).
+     *
+     * Intentionally typed as `React.ReactNode` so the consumer can bring any
+     * renderer they like — `<Image />`, `<IconCapsule />`, a Lottie player
+     * (`lottie-react-native` / `@lottiefiles/dotlottie-react`), an `<SvgXml />`
+     * from `react-native-svg`, a `<Video />` from `react-native-video`, a
+     * gradient view, or a custom illustration. The library deliberately does
+     * NOT wrap Lottie / video runtimes (they require native modules + pod
+     * autolinking on every consumer's app), so PageHero just allocates a
+     * token-sized container and lets the slot render whatever it wants.
+     *
+     * The slot is rendered inside a `width × height` box driven by
+     * `media/width` and `media/height` tokens (default 117×117). `modes` are
+     * automatically cascaded into the slot via `cloneChildrenWithModes`.
+     */
+    media?: React.ReactNode;
     /** Mode configuration for design-token theming. */
     modes?: Record<string, any>;
     /** Style overrides applied to the outer container. */
@@ -29,12 +46,14 @@ export type PageHeroProps = {
 };
 /**
  * PageHero displays a centered hero block typically used at the top of a page
- * or feature screen. It contains an eyebrow line, a large headline, an optional
- * supporting line (e.g. price/timeline), and an optional action button.
+ * or feature screen. It contains an optional media slot (illustration / image
+ * / Lottie / SVG / video — consumer's choice), an eyebrow line, a large
+ * headline, an optional supporting line (e.g. price / timeline), and an
+ * optional action button.
  *
  * All visual values are resolved from Figma design tokens via
- * `getVariableByName`. The button slot cascades the active `modes` to its
- * children through `cloneChildrenWithModes`.
+ * `getVariableByName`. Slots cascade the active `modes` to their children
+ * through `cloneChildrenWithModes`.
  *
  * @component
  * @example
@@ -45,9 +64,16 @@ export type PageHeroProps = {
  *   supportingText="₹999/year · ₹0 until 2027"
  *   buttonLabel="Renew for free"
  *   onButtonPress={() => navigate('Upgrade')}
+ *   media={
+ *     <Image
+ *       imageSource={require('./assets/upgrade.png')}
+ *       width={117}
+ *       height={117}
+ *     />
+ *   }
  * />
  * ```
  */
-declare function PageHero({ eyebrow, headline, supportingText, showSupportingText, buttonLabel, onButtonPress, showButton, buttonSlot, modes: propModes, style, testID, }: PageHeroProps): import("react/jsx-runtime").JSX.Element;
+declare function PageHero({ eyebrow, headline, supportingText, showSupportingText, buttonLabel, onButtonPress, showButton, buttonSlot, media, modes: propModes, style, testID, }: PageHeroProps): import("react/jsx-runtime").JSX.Element;
 export default PageHero;
 //# sourceMappingURL=PageHero.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

@@ -47,6 +47,7 @@ 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';

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-25T10:18:38.037Z
  */
 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