@erquhart/heroui-native 1.0.0-beta.10.1

package/src/components/skeleton/skeleton.tsx

@@ -0,0 +1,183 @@
+import React, {
+  useCallback,
+  useMemo,
+  useState,
+  type PropsWithChildren,
+} from 'react';
+import {
+  StyleSheet,
+  useWindowDimensions,
+  type LayoutChangeEvent,
+} from 'react-native';
+import Animated, { useSharedValue } from 'react-native-reanimated';
+
+import { AnimationSettingsProvider } from '../../helpers/contexts/animation-settings-context';
+
+import LinearGradientComponent from './linear-gradient';
+import {
+  SkeletonAnimationProvider,
+  useSkeletonAnimation,
+  useSkeletonPulseAnimation,
+  useSkeletonRootAnimation,
+  useSkeletonShimmerAnimation,
+} from './skeleton.animation';
+import { DISPLAY_NAME } from './skeleton.constants';
+import styleSheet, { nativeStyles } from './skeleton.styles';
+import type { SkeletonProps } from './skeleton.types';
+
+// --------------------------------------------------
+
+const ShimmerAnimation: React.FC<{
+  animation: SkeletonProps['animation'];
+  isAnimatedStyleActive?: boolean;
+}> = ({ animation, isAnimatedStyleActive = true }) => {
+  const { rContainerStyle, gradientColors } = useSkeletonShimmerAnimation({
+    animation,
+  });
+
+  const shimmerStyle = isAnimatedStyleActive
+    ? [StyleSheet.absoluteFill, nativeStyles.borderCurve, rContainerStyle]
+    : [StyleSheet.absoluteFill, nativeStyles.borderCurve];
+
+  return (
+    <Animated.View style={shimmerStyle}>
+      <LinearGradientComponent colors={gradientColors} />
+    </Animated.View>
+  );
+};
+
+// --------------------------------------------------
+
+const PulseAnimation: React.FC<
+  PropsWithChildren<{
+    animation: SkeletonProps['animation'];
+    isAnimatedStyleActive?: boolean;
+  }>
+> = ({ children, animation, isAnimatedStyleActive = true }) => {
+  const { variant } = useSkeletonAnimation();
+
+  const { rContainerStyle } = useSkeletonPulseAnimation({
+    animation,
+  });
+
+  if (variant === 'pulse') {
+    const pulseStyle = isAnimatedStyleActive ? rContainerStyle : undefined;
+    return <Animated.View style={pulseStyle}>{children}</Animated.View>;
+  }
+
+  return children;
+};
+
+// --------------------------------------------------
+
+const Skeleton: React.FC<SkeletonProps> = (props) => {
+  const {
+    children,
+    isLoading = true,
+    variant = 'shimmer',
+    animation,
+    isAnimatedStyleActive = true,
+    className,
+    style,
+    ...restProps
+  } = props;
+
+  const [componentWidth, setComponentWidth] = useState(0);
+  const [offset, setOffset] = useState(0);
+
+  const progress = useSharedValue(0);
+
+  const { width: screenWidth } = useWindowDimensions();
+
+  const { isAllAnimationsDisabled, entering, exiting } =
+    useSkeletonRootAnimation({
+      animation,
+      isLoading,
+      variant,
+      progress,
+    });
+
+  const tvStyles = styleSheet.skeleton({ className });
+
+  const handleLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      if (componentWidth === 0) {
+        const { width, x } = event.nativeEvent.layout;
+        setComponentWidth(width);
+        setOffset(x);
+      }
+    },
+    [componentWidth]
+  );
+
+  const animationContextValue = useMemo(
+    () => ({
+      isLoading,
+      variant,
+      progress,
+      componentWidth,
+      offset,
+      screenWidth,
+    }),
+    [isLoading, variant, progress, componentWidth, offset, screenWidth]
+  );
+
+  const animationSettingsContextValue = useMemo(
+    () => ({
+      isAllAnimationsDisabled,
+    }),
+    [isAllAnimationsDisabled]
+  );
+
+  if (!isLoading) {
+    return (
+      <Animated.View key="content" entering={entering} exiting={exiting}>
+        {children}
+      </Animated.View>
+    );
+  }
+
+  return (
+    <AnimationSettingsProvider value={animationSettingsContextValue}>
+      <SkeletonAnimationProvider value={animationContextValue}>
+        <PulseAnimation
+          animation={animation}
+          isAnimatedStyleActive={isAnimatedStyleActive}
+        >
+          <Animated.View
+            key="skeleton"
+            entering={entering}
+            exiting={exiting}
+            onLayout={handleLayout}
+            style={[nativeStyles.borderCurve, style]}
+            className={tvStyles}
+            {...restProps}
+          >
+            {variant === 'shimmer' && componentWidth > 0 && (
+              <ShimmerAnimation
+                animation={animation}
+                isAnimatedStyleActive={isAnimatedStyleActive}
+              />
+            )}
+          </Animated.View>
+        </PulseAnimation>
+      </SkeletonAnimationProvider>
+    </AnimationSettingsProvider>
+  );
+};
+
+// --------------------------------------------------
+
+Skeleton.displayName = DISPLAY_NAME.SKELETON;
+
+/**
+ * Skeleton component for displaying loading placeholders
+ *
+ * @component Skeleton - Animated loading placeholder that can display shimmer or pulse effects.
+ * Shows skeleton state when isLoading is true, otherwise displays children content.
+ * Supports customizable animations through the animation prop with shimmer and pulse configurations.
+ * Shape and size are controlled via className for maximum flexibility.
+ *
+ * @see Full documentation: https://heroui.com/components/skeleton
+ */
+export default Skeleton;

package/src/components/skeleton/skeleton.types.ts

@@ -0,0 +1,191 @@
+import type { ViewProps } from 'react-native';
+import type {
+  AnimatedProps,
+  EasingFunction,
+  EntryOrExitLayoutType,
+  SharedValue,
+} from 'react-native-reanimated';
+import type { Animation, AnimationRoot } from '../../helpers/types';
+
+/**
+ * Skeleton animation type - defines the animation style
+ */
+export type SkeletonAnimation = 'shimmer' | 'pulse' | 'none';
+
+/**
+ * Shimmer animation configuration for Skeleton root component
+ */
+export type SkeletonShimmerAnimation = Animation<{
+  /**
+   * Animation duration in milliseconds
+   * @default 1500
+   */
+  duration?: number;
+  /**
+   * Speed multiplier for the animation
+   * @default 1
+   */
+  speed?: number;
+  /**
+   * Highlight color for the shimmer effect
+   */
+  highlightColor?: string;
+  /**
+   * Easing function for the animation
+   */
+  easing?: EasingFunction;
+}>;
+
+/**
+ * Pulse animation configuration for Skeleton root component
+ */
+export type SkeletonPulseAnimation = Animation<{
+  /**
+   * Animation duration in milliseconds
+   * @default 1000
+   */
+  duration?: number;
+  /**
+   * Minimum opacity value
+   * @default 0.5
+   */
+  minOpacity?: number;
+  /**
+   * Maximum opacity value
+   * @default 1
+   */
+  maxOpacity?: number;
+  /**
+   * Easing function for the animation
+   */
+  easing?: EasingFunction;
+}>;
+
+/**
+ * Animation configuration for Skeleton root component
+ */
+export type SkeletonRootAnimation = AnimationRoot<{
+  entering?: Animation<{
+    /**
+     * Custom entering animation for skeleton
+     */
+    value?: EntryOrExitLayoutType;
+  }>;
+  /**
+   * Exiting animation for the skeleton
+   */
+  exiting?: Animation<{
+    /**
+     * Custom exiting animation for skeleton
+     */
+    value?: EntryOrExitLayoutType;
+  }>;
+  /**
+   * Shimmer animation configuration
+   */
+  shimmer?: SkeletonShimmerAnimation;
+  /**
+   * Pulse animation configuration
+   */
+  pulse?: SkeletonPulseAnimation;
+  /**
+   * Entering animation for the skeleton
+   */
+}>;
+
+/**
+ * Props for the main Skeleton component
+ */
+export interface SkeletonProps extends AnimatedProps<ViewProps> {
+  /**
+   * Child components to show when not loading
+   */
+  children?: React.ReactNode;
+
+  /**
+   * Whether the skeleton is currently loading
+   * @default true
+   */
+  isLoading?: boolean;
+
+  /**
+   * Animation variant
+   * @default 'shimmer'
+   */
+  variant?: SkeletonAnimation;
+
+  /**
+   * Animation configuration
+   */
+  animation?: SkeletonRootAnimation;
+
+  /**
+   * Whether animated styles (react-native-reanimated) are active
+   * When `false`, the animated style is removed and you can implement custom logic
+   * This prop should only be used when you want to write custom styling logic instead of the default animated styles
+   * @default true
+   */
+  isAnimatedStyleActive?: boolean;
+
+  /**
+   * Additional CSS classes for styling
+   *
+   * @note The following style properties are occupied by animations and cannot be set via className:
+   * - `opacity` - Animated for pulse variant transitions (min: 0.5, max: 1)
+   *
+   * The shimmer variant uses an internal overlay with `transform` (translateX) animation, which doesn't affect the className prop.
+   *
+   * To customize these properties, use the `animation` prop:
+   * ```tsx
+   * <Skeleton
+   *   variant="pulse"
+   *   animation={{
+   *     pulse: { minOpacity: 0.5, maxOpacity: 1, duration: 1000, easing: Easing.inOut(Easing.ease) }
+   *   }}
+   * />
+   * ```
+   *
+   * For shimmer variant:
+   * ```tsx
+   * <Skeleton
+   *   variant="shimmer"
+   *   animation={{
+   *     shimmer: { duration: 1500, speed: 1, highlightColor: '#ffffff', easing: Easing.linear }
+   *   }}
+   * />
+   * ```
+   *
+   * To completely disable animated styles and use your own via className or style prop, set `isAnimatedStyleActive={false}`.
+   */
+  className?: string;
+}
+
+/**
+ * Context value for skeleton animation provider
+ */
+export interface SkeletonAnimationContextValue {
+  /**
+   * Whether the skeleton is currently loading
+   */
+  isLoading: boolean;
+  /**
+   * Animation variant
+   */
+  variant: SkeletonAnimation;
+  /**
+   * Shared animation progress value
+   */
+  progress: SharedValue<number>;
+  /**
+   * Component width for shimmer calculation
+   */
+  componentWidth: number;
+  /**
+   * Component offset for shimmer calculation
+   */
+  offset: number;
+  /**
+   * Screen width for animation calculation
+   */
+  screenWidth: number;
+}

package/src/components/skeleton-group/index.ts

@@ -0,0 +1,6 @@
+export { default as SkeletonGroup } from './skeleton-group';
+export type {
+  SkeletonGroupContextValue,
+  SkeletonGroupItemProps,
+  SkeletonGroupRootProps,
+} from './skeleton-group.types';

package/src/components/skeleton-group/skeleton-group.constants.ts

@@ -0,0 +1,7 @@
+/**
+ * Display names for SkeletonGroup components
+ */
+export const DISPLAY_NAME = {
+  SKELETON_GROUP_ROOT: 'HeroUINative.SkeletonGroup.Root',
+  SKELETON_GROUP_ITEM: 'HeroUINative.SkeletonGroup.Item',
+};

package/src/components/skeleton-group/skeleton-group.md

@@ -0,0 +1,247 @@
+# SkeletonGroup
+
+Coordinates multiple skeleton loading placeholders with centralized animation control.
+
+## Imports
+
+Note: Before importing this component, ensure you have completed the setup as per the [Quick Start guide](../../../README.md).
+
+```tsx
+import { SkeletonGroup } from 'heroui-native';
+```
+
+## Usage
+
+### Basic Usage
+
+The SkeletonGroup component manages multiple skeleton items with shared loading state and animation.
+
+```tsx
+<SkeletonGroup isLoading={isLoading}>
+  <SkeletonGroup.Item className="h-4 w-full rounded-md" />
+  <SkeletonGroup.Item className="h-4 w-3/4 rounded-md" />
+  <SkeletonGroup.Item className="h-4 w-1/2 rounded-md" />
+</SkeletonGroup>
+```
+
+### With Container Layout
+
+Use className on the group to control layout of skeleton items.
+
+```tsx
+<SkeletonGroup isLoading={isLoading} className="flex-row items-center gap-3">
+  <SkeletonGroup.Item className="h-12 w-12 rounded-lg" />
+  <View className="flex-1 gap-1.5">
+    <SkeletonGroup.Item className="h-4 w-full rounded-md" />
+    <SkeletonGroup.Item className="h-3 w-2/3 rounded-md" />
+  </View>
+</SkeletonGroup>
+```
+
+### With isSkeletonOnly for Pure Skeleton Layouts
+
+Use `isSkeletonOnly` when the group contains only skeleton placeholders with layout wrappers (like View) that have no content to render in the loaded state. This prop hides the entire group when `isLoading` is false, preventing empty containers from affecting your layout.
+
+```tsx
+<SkeletonGroup
+  isLoading={isLoading}
+  isSkeletonOnly // Hides entire group when isLoading is false
+  className="flex-row items-center gap-3"
+>
+  <SkeletonGroup.Item className="h-12 w-12 rounded-lg" />
+  {/* This View is only for layout, no content */}
+  <View className="flex-1 gap-1.5">
+    <SkeletonGroup.Item className="h-4 w-full rounded-md" />
+    <SkeletonGroup.Item className="h-3 w-2/3 rounded-md" />
+  </View>
+</SkeletonGroup>
+```
+
+### With Animation Variants
+
+Control animation style for all items in the group.
+
+```tsx
+<SkeletonGroup isLoading={isLoading} variant="pulse">
+  <SkeletonGroup.Item className="h-10 w-10 rounded-full" />
+  <SkeletonGroup.Item className="h-4 w-32 rounded-md" />
+  <SkeletonGroup.Item className="h-3 w-24 rounded-md" />
+</SkeletonGroup>
+```
+
+### With Custom Animation Configuration
+
+Configure shimmer or pulse animations for the entire group.
+
+```tsx
+<SkeletonGroup
+  isLoading={isLoading}
+  variant="shimmer"
+  animation={{
+    shimmer: {
+      duration: 2000,
+      highlightColor: 'rgba(59, 130, 246, 0.3)',
+    },
+  }}
+>
+  <SkeletonGroup.Item className="h-16 w-full rounded-lg" />
+  <SkeletonGroup.Item className="h-4 w-3/4 rounded-md" />
+</SkeletonGroup>
+```
+
+### With Enter/Exit Animations
+
+Apply Reanimated transitions when the group appears or disappears.
+
+```tsx
+<SkeletonGroup
+  entering={FadeInLeft}
+  exiting={FadeOutRight}
+  isLoading={isLoading}
+  className="w-full gap-2"
+>
+  <SkeletonGroup.Item className="h-4 w-full rounded-md" />
+  <SkeletonGroup.Item className="h-4 w-3/4 rounded-md" />
+</SkeletonGroup>
+```
+
+## Example
+
+```tsx
+import { Card, SkeletonGroup, Avatar } from 'heroui-native';
+import { useState } from 'react';
+import { Text, View, Image } from 'react-native';
+
+export default function SkeletonGroupExample() {
+  const [isLoading, setIsLoading] = useState(true);
+
+  return (
+    <SkeletonGroup isLoading={isLoading}>
+      <Card className="p-4">
+        <Card.Header>
+          <View className="flex-row items-center gap-3 mb-4">
+            <SkeletonGroup.Item className="h-10 w-10 rounded-full">
+              <Avatar size="sm" alt="Avatar">
+                <Avatar.Image
+                  source={{ uri: 'https://i.pravatar.cc/150?img=4' }}
+                />
+                <Avatar.Fallback />
+              </Avatar>
+            </SkeletonGroup.Item>
+
+            <View className="flex-1 gap-1">
+              <SkeletonGroup.Item className="h-3 w-32 rounded-md">
+                <Text className="font-semibold text-foreground">John Doe</Text>
+              </SkeletonGroup.Item>
+              <SkeletonGroup.Item className="h-3 w-24 rounded-md">
+                <Text className="text-sm text-muted">@johndoe</Text>
+              </SkeletonGroup.Item>
+            </View>
+          </View>
+
+          <View className="mb-4 gap-1.5">
+            <SkeletonGroup.Item className="h-4 w-full rounded-md">
+              <Text className="text-base text-foreground">
+                This is the first line of the post content.
+              </Text>
+            </SkeletonGroup.Item>
+            <SkeletonGroup.Item className="h-4 w-full rounded-md">
+              <Text className="text-base text-foreground">
+                Second line with more interesting content to read.
+              </Text>
+            </SkeletonGroup.Item>
+            <SkeletonGroup.Item className="h-4 w-2/3 rounded-md">
+              <Text className="text-base text-foreground">
+                Last line is shorter.
+              </Text>
+            </SkeletonGroup.Item>
+          </View>
+        </Card.Header>
+
+        <SkeletonGroup.Item className="h-48 w-full rounded-lg">
+          <View className="h-48 bg-surface-tertiary rounded-lg overflow-hidden">
+            <Image
+              source={{
+                uri: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/backgrounds/cards/car1.jpg',
+              }}
+              className="h-full w-full"
+            />
+          </View>
+        </SkeletonGroup.Item>
+      </Card>
+    </SkeletonGroup>
+  );
+}
+```
+
+## Anatomy
+
+```tsx
+<SkeletonGroup>
+  <SkeletonGroup.Item />
+</SkeletonGroup>
+```
+
+- **SkeletonGroup**: Root container that provides centralized control for all skeleton items
+- **SkeletonGroup.Item**: Individual skeleton item that inherits props from the parent group
+
+## API Reference
+
+### SkeletonGroup
+
+| prop                    | type                             | default     | description                                                            |
+| ----------------------- | -------------------------------- | ----------- | ---------------------------------------------------------------------- |
+| `children`              | `React.ReactNode`                | -           | SkeletonGroup.Item components and layout elements                      |
+| `isLoading`             | `boolean`                        | `true`      | Whether the skeleton items are currently loading                       |
+| `isSkeletonOnly`        | `boolean`                        | `false`     | Hides entire group when isLoading is false (for skeleton-only layouts) |
+| `variant`               | `'shimmer' \| 'pulse' \| 'none'` | `'shimmer'` | Animation variant for all items in the group                           |
+| `animation`             | `SkeletonRootAnimation`          | -           | Animation configuration                                                |
+| `className`             | `string`                         | -           | Additional CSS classes for the group container                         |
+| `style`                 | `StyleProp<ViewStyle>`           | -           | Custom styles for the group container                                  |
+| `...Animated.ViewProps` | `AnimatedProps<ViewProps>`       | -           | All Reanimated Animated.View props are supported                       |
+
+#### SkeletonRootAnimation
+
+Animation configuration for SkeletonGroup component. Can be:
+
+- `false` or `"disabled"`: Disable only root animations
+- `"disable-all"`: Disable all animations including children
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                     | type                                    | default                     | description                            |
+| ------------------------ | --------------------------------------- | --------------------------- | -------------------------------------- |
+| `state`                  | `'disabled' \| 'disable-all' \| boolean` | -                          | Disable animations while customizing properties |
+| `entering.value`         | `EntryOrExitLayoutType`                 | `FadeIn`                    | Custom entering animation              |
+| `exiting.value`          | `EntryOrExitLayoutType`                 | `FadeOut`                   | Custom exiting animation               |
+| `shimmer.duration`       | `number`                                | `1500`                      | Animation duration in milliseconds     |
+| `shimmer.speed`          | `number`                                | `1`                         | Speed multiplier for the animation     |
+| `shimmer.highlightColor` | `string`                                | -                           | Highlight color for the shimmer effect |
+| `shimmer.easing`         | `EasingFunction`                        | `Easing.linear`             | Easing function for the animation      |
+| `pulse.duration`         | `number`                                | `1000`                      | Animation duration in milliseconds     |
+| `pulse.minOpacity`       | `number`                                | `0.5`                       | Minimum opacity value                  |
+| `pulse.maxOpacity`       | `number`                                | `1`                         | Maximum opacity value                  |
+| `pulse.easing`           | `EasingFunction`        | `Easing.inOut(Easing.ease)` | Easing function for the animation      |
+
+### SkeletonGroup.Item
+
+| prop                    | type                             | default   | description                                                         |
+| ----------------------- | -------------------------------- | --------- | ------------------------------------------------------------------- |
+| `children`              | `React.ReactNode`                | -         | Content to show when not loading                                    |
+| `isLoading`             | `boolean`                        | inherited | Whether the skeleton is currently loading (overrides group setting) |
+| `variant`               | `'shimmer' \| 'pulse' \| 'none'` | inherited | Animation variant (overrides group setting)                         |
+| `animation`             | `SkeletonRootAnimation`          | inherited | Animation configuration (overrides group setting)                   |
+| `className`             | `string`                         | -         | Additional CSS classes for styling the item                         |
+| `...Animated.ViewProps` | `AnimatedProps<ViewProps>`       | -         | All Reanimated Animated.View props are supported                    |
+
+## Important Notes
+
+### Props Inheritance
+
+SkeletonGroup.Item components inherit all animation-related props from their parent SkeletonGroup:
+
+- `isLoading`
+- `variant`
+- `animation`
+
+Individual items can override any inherited prop by providing their own value.

package/src/components/skeleton-group/skeleton-group.styles.ts

@@ -0,0 +1,8 @@
+import { tv } from 'tailwind-variants';
+
+/**
+ * SkeletonGroup component styles using tailwind-variants
+ */
+export const skeletonGroupStyles = tv({
+  base: '',
+});