@erquhart/heroui-native 1.0.0-beta.10.1

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

@@ -0,0 +1,94 @@
+import React, { useMemo, type PropsWithChildren } from 'react';
+
+import { View } from 'react-native';
+import { createContext } from '../../helpers/utils';
+import Skeleton from '../skeleton/skeleton';
+import { DISPLAY_NAME } from './skeleton-group.constants';
+import { skeletonGroupStyles } from './skeleton-group.styles';
+import type {
+  SkeletonGroupContextValue,
+  SkeletonGroupItemProps,
+  SkeletonGroupRootProps,
+} from './skeleton-group.types';
+
+const [SkeletonGroupProvider, useSkeletonGroupContext] =
+  createContext<SkeletonGroupContextValue>({
+    name: 'SkeletonGroupContext',
+    errorMessage:
+      'useSkeletonGroupContext: must be used within a SkeletonGroup',
+  });
+
+// --------------------------------------------------
+
+const SkeletonGroupRoot: React.FC<PropsWithChildren<SkeletonGroupRootProps>> = (
+  props
+) => {
+  const {
+    children,
+    className,
+    style,
+    isSkeletonOnly = false,
+    ...restProps
+  } = props;
+
+  const containerStyles = skeletonGroupStyles({ className });
+
+  const contextValue = useMemo<SkeletonGroupContextValue>(
+    () => ({
+      ...restProps,
+    }),
+    [restProps]
+  );
+
+  if (isSkeletonOnly && !restProps.isLoading) {
+    return null;
+  }
+
+  return (
+    <SkeletonGroupProvider value={contextValue}>
+      <View className={containerStyles} style={style}>
+        {children}
+      </View>
+    </SkeletonGroupProvider>
+  );
+};
+
+// --------------------------------------------------
+
+const SkeletonGroupItem: React.FC<SkeletonGroupItemProps> = (props) => {
+  const context = useSkeletonGroupContext();
+
+  const itemProps = {
+    ...context,
+    ...props,
+  };
+
+  return <Skeleton {...itemProps} />;
+};
+
+// --------------------------------------------------
+
+SkeletonGroupRoot.displayName = DISPLAY_NAME.SKELETON_GROUP_ROOT;
+SkeletonGroupItem.displayName = DISPLAY_NAME.SKELETON_GROUP_ITEM;
+
+/**
+ * Compound SkeletonGroup component for managing multiple skeleton loading states
+ *
+ * @component SkeletonGroup - Root container that provides centralized control for all skeleton items.
+ * Passes isLoading, variant, and animation to child items via context.
+ *
+ * @component SkeletonGroup.Item - Individual skeleton item that inherits props from the parent group.
+ * Can override group props with its own props for specific customization.
+ *
+ * Props flow from SkeletonGroup to Items via context (isLoading, variant, animation).
+ * Items can override any inherited prop by passing their own values.
+ *
+ * @see Full documentation: https://heroui.com/components/skeleton-group
+ */
+const SkeletonGroup = Object.assign(SkeletonGroupRoot, {
+  /** @optional Individual skeleton item that inherits group settings */
+  Item: SkeletonGroupItem,
+});
+
+export default SkeletonGroup;
+export { useSkeletonGroupContext };

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

@@ -0,0 +1,28 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { SkeletonProps } from '../skeleton/skeleton.types';
+
+/**
+ * Props for the SkeletonGroup root component
+ */
+export interface SkeletonGroupRootProps extends Omit<SkeletonProps, 'style'> {
+  /**
+   * When true, hides the entire group when isLoading is false.
+   * Use this to prevent layout issues when skeleton contains wrapper elements.
+   * @default false
+   */
+  isSkeletonOnly?: boolean;
+  /**
+   * Style for the skeleton group container
+   */
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Context value for SkeletonGroup provider
+ */
+export interface SkeletonGroupContextValue extends SkeletonGroupRootProps {}
+
+/**
+ * Props for the SkeletonGroup.Item component
+ */
+export interface SkeletonGroupItemProps extends SkeletonProps {}

package/src/components/spinner/index.ts

@@ -0,0 +1,9 @@
+export { default as Spinner } from './spinner';
+export type {
+  SpinnerColor,
+  SpinnerContextValue,
+  SpinnerIconProps,
+  SpinnerIndicatorProps,
+  SpinnerProps,
+  SpinnerSize,
+} from './spinner.types';

package/src/components/spinner/spinner-icon.tsx

@@ -0,0 +1,49 @@
+import Svg, { Defs, G, LinearGradient, Path, Stop } from 'react-native-svg';
+import { DISPLAY_NAME } from './spinner.constants';
+import type { SpinnerIconProps } from './spinner.types';
+
+export function SpinnerIcon(props: SpinnerIconProps) {
+  const { width = 24, height = 24, color = 'currentColor' } = props;
+
+  return (
+    <Svg width={width} height={height} viewBox="0 0 24 24">
+      <Defs>
+        <LinearGradient
+          id="mingcuteLoadingFill0"
+          x1="50%"
+          x2="50%"
+          y1="5.271%"
+          y2="91.793%"
+        >
+          <Stop offset="0%" stopColor={color} />
+          <Stop offset="100%" stopColor={color} stopOpacity={0.55} />
+        </LinearGradient>
+        <LinearGradient
+          id="mingcuteLoadingFill1"
+          x1="50%"
+          x2="50%"
+          y1="15.24%"
+          y2="87.15%"
+        >
+          <Stop offset="0%" stopColor={color} stopOpacity={0} />
+          <Stop offset="100%" stopColor={color} stopOpacity={0.55} />
+        </LinearGradient>
+      </Defs>
+      <G fill="none">
+        <Path d="m12.593 23.258l-.011.002l-.071.035l-.02.004l-.014-.004l-.071-.035q-.016-.005-.024.005l-.004.01l-.017.428l.005.02l.01.013l.104.074l.015.004l.012-.004l.104-.074l.012-.016l.004-.017l-.017-.427q-.004-.016-.017-.018m.265-.113l-.013.002l-.185.093l-.01.01l-.003.011l.018.43l.005.012l.008.007l.201.093q.019.005.029-.008l.004-.014l-.034-.614q-.005-.018-.02-.022m-.715.002a.02.02 0 0 0-.027.006l-.006.014l-.034.614q.001.018.017.024l.015-.002l.201-.093l.01-.008l.004-.011l.017-.43l-.003-.012l-.01-.01z" />
+        <Path
+          d="M8.749.021a1.5 1.5 0 0 1 .497 2.958A7.5 7.5 0 0 0 3 10.375a7.5 7.5 0 0 0 7.5 7.5v3c-5.799 0-10.5-4.7-10.5-10.5C0 5.23 3.726.865 8.749.021"
+          fill="url(#mingcuteLoadingFill0)"
+          transform="translate(1.5 1.625)"
+        />
+        <Path
+          d="M15.392 2.673a1.5 1.5 0 0 1 2.119-.115A10.48 10.48 0 0 1 21 10.375c0 5.8-4.701 10.5-10.5 10.5v-3a7.5 7.5 0 0 0 5.007-13.084a1.5 1.5 0 0 1-.115-2.118"
+          fill="url(#mingcuteLoadingFill1)"
+          transform="translate(1.5 1.625)"
+        />
+      </G>
+    </Svg>
+  );
+}
+
+SpinnerIcon.displayName = DISPLAY_NAME.ICON;

package/src/components/spinner/spinner.animation.ts

@@ -0,0 +1,150 @@
+import { useEffect, useMemo } from 'react';
+import {
+  cancelAnimation,
+  Easing,
+  useAnimatedStyle,
+  useSharedValue,
+  withRepeat,
+  withSequence,
+  withTiming,
+} from 'react-native-reanimated';
+import { useAnimationSettings } from '../../helpers/contexts';
+import { useCombinedAnimationDisabledState } from '../../helpers/hooks';
+import {
+  getAnimationState,
+  getAnimationValueProperty,
+  getIsAnimationDisabledValue,
+  getRootAnimationState,
+} from '../../helpers/utils/animation';
+import {
+  DEFAULT_ROTATION_DURATION,
+  DEFAULT_SPINNER_INDICATOR_ENTERING,
+  DEFAULT_SPINNER_INDICATOR_EXITING,
+} from './spinner.constants';
+import type {
+  SpinnerIndicatorAnimation,
+  SpinnerRootAnimation,
+} from './spinner.types';
+
+// --------------------------------------------------
+
+/**
+ * Animation hook for Spinner root component
+ * Handles entering and exiting animations for the spinner container
+ */
+export function useSpinnerRootAnimation(options: {
+  animation: SpinnerRootAnimation | undefined;
+}) {
+  const { animation } = options;
+
+  const { animationConfig, isAnimationDisabled } =
+    getRootAnimationState(animation);
+
+  const isAllAnimationsDisabled = useCombinedAnimationDisabledState(animation);
+
+  const isAnimationDisabledValue = getIsAnimationDisabledValue({
+    isAnimationDisabled,
+    isAllAnimationsDisabled,
+  });
+
+  // Entering animation
+  const enteringValue = getAnimationValueProperty({
+    animationValue: animationConfig?.entering,
+    property: 'value',
+    defaultValue: DEFAULT_SPINNER_INDICATOR_ENTERING,
+  });
+
+  // Exiting animation
+  const exitingValue = getAnimationValueProperty({
+    animationValue: animationConfig?.exiting,
+    property: 'value',
+    defaultValue: DEFAULT_SPINNER_INDICATOR_EXITING,
+  });
+
+  return {
+    entering: isAnimationDisabledValue ? undefined : enteringValue,
+    exiting: isAnimationDisabledValue ? undefined : exitingValue,
+    isAllAnimationsDisabled,
+  };
+}
+
+// --------------------------------------------------
+
+/**
+ * Animation hook for Spinner Indicator component
+ * Handles rotation animation for the spinner indicator
+ */
+export function useSpinnerIndicatorAnimation(options: {
+  animation: SpinnerIndicatorAnimation | undefined;
+  isLoading: boolean;
+}) {
+  const { animation, isLoading } = options;
+
+  // Read from global animation context (always available in compound parts)
+  const { isAllAnimationsDisabled } = useAnimationSettings();
+
+  const { animationConfig, isAnimationDisabled } = getAnimationState(animation);
+
+  const isAnimationDisabledValue = getIsAnimationDisabledValue({
+    isAnimationDisabled,
+    isAllAnimationsDisabled,
+  });
+
+  // Rotation animation configuration
+  const rotationSpeed = getAnimationValueProperty({
+    animationValue: animationConfig?.rotation,
+    property: 'speed',
+    defaultValue: 1.1,
+  });
+
+  const rotationEasing = getAnimationValueProperty({
+    animationValue: animationConfig?.rotation,
+    property: 'easing',
+    defaultValue: Easing.linear,
+  });
+
+  const rotationTimingConfig = useMemo(() => {
+    return {
+      duration: DEFAULT_ROTATION_DURATION / rotationSpeed,
+      easing: rotationEasing,
+    };
+  }, [rotationSpeed, rotationEasing]);
+
+  const rotation = useSharedValue(0);
+
+  useEffect(() => {
+    if (isLoading) {
+      if (isAnimationDisabledValue) {
+        rotation.set(0);
+      } else {
+        rotation.set(
+          withRepeat(
+            withSequence(withTiming(360, rotationTimingConfig)),
+            -1,
+            false
+          )
+        );
+      }
+    } else {
+      rotation.set(withTiming(0, { duration: 300 }));
+    }
+
+    return () => {
+      cancelAnimation(rotation);
+    };
+  }, [isLoading, isAnimationDisabledValue, rotation, rotationTimingConfig]);
+
+  const rContainerStyle = useAnimatedStyle(() => {
+    return {
+      transform: [
+        {
+          rotate: `${rotation.get()}deg`,
+        },
+      ],
+    };
+  });
+
+  return {
+    rContainerStyle,
+  };
+}

package/src/components/spinner/spinner.constants.ts

@@ -0,0 +1,36 @@
+import { Easing, FadeIn, FadeOut } from 'react-native-reanimated';
+
+/**
+ * Display names for Spinner components
+ */
+export const DISPLAY_NAME = {
+  ROOT: 'HeroUINative.Spinner.Root',
+  INDICATOR: 'HeroUINative.Spinner.Indicator',
+  ICON: 'HeroUINative.Spinner.Icon',
+} as const;
+
+/**
+ * Default animation duration for spinner rotation (in milliseconds)
+ */
+export const DEFAULT_ROTATION_DURATION = 1000;
+
+/**
+ * Size mappings for spinner icon dimensions
+ */
+export const SPINNER_SIZE_MAP = {
+  sm: 16,
+  md: 24,
+  lg: 32,
+} as const;
+
+/**
+ * Default entering animation configuration for spinner indicator
+ */
+export const DEFAULT_SPINNER_INDICATOR_ENTERING = FadeIn.duration(200).easing(
+  Easing.out(Easing.ease)
+);
+
+/**
+ * Default exiting animation configuration for spinner indicator
+ */
+export const DEFAULT_SPINNER_INDICATOR_EXITING = FadeOut.duration(100);

package/src/components/spinner/spinner.md

@@ -0,0 +1,199 @@
+# Spinner
+
+Displays an animated loading indicator.
+
+## Imports
+
+Note: Before importing this component, ensure you have completed the setup as per the [Quick Start guide](../../../README.md).
+
+```tsx
+import { Spinner } from 'heroui-native';
+```
+
+## Usage
+
+### Basic Usage
+
+The Spinner component displays a rotating loading indicator.
+
+```tsx
+<Spinner />
+```
+
+### Sizes
+
+Control the spinner size with the `size` prop.
+
+```tsx
+<Spinner size="sm" />
+<Spinner size="md" />
+<Spinner size="lg" />
+```
+
+### Colors
+
+Use predefined color variants or custom colors.
+
+```tsx
+<Spinner color="default" />
+<Spinner color="success" />
+<Spinner color="warning" />
+<Spinner color="danger" />
+<Spinner color="#8B5CF6" />
+```
+
+### Loading State
+
+Control the visibility of the spinner with the `isLoading` prop.
+
+```tsx
+<Spinner isLoading={true} />
+<Spinner isLoading={false} />
+```
+
+### Animation Speed
+
+Customize the rotation speed using the `animation` prop on the Indicator component.
+
+```tsx
+<Spinner>
+  <Spinner.Indicator animation={{ rotation: { speed: 0.5 } }} />
+</Spinner>
+
+<Spinner>
+  <Spinner.Indicator animation={{ rotation: { speed: 2 } }} />
+</Spinner>
+```
+
+### Custom Icon
+
+Replace the default spinner icon with custom content.
+
+```tsx
+const themeColorForeground = useThemeColor('foreground')
+
+<Spinner>
+  <Spinner.Indicator>
+    <Ionicons name="refresh" size={24} color={themeColorForeground} />
+  </Spinner.Indicator>
+</Spinner>
+
+<Spinner>
+  <Spinner.Indicator>
+    <Text>⏳</Text>
+  </Spinner.Indicator>
+</Spinner>
+```
+
+## Example
+
+```tsx
+import { Spinner } from 'heroui-native';
+import { Ionicons } from '@expo/vector-icons';
+import React from 'react';
+import { Text, TouchableOpacity, View } from 'react-native';
+
+export default function SpinnerExample() {
+  const [isLoading, setIsLoading] = React.useState(true);
+
+  return (
+    <View className="gap-4 p-4 bg-background">
+      <View className="flex-row items-center gap-2 p-4 rounded-lg bg-stone-200">
+        <Spinner size="sm" color="default" />
+        <Text className="text-stone-500">Loading content...</Text>
+      </View>
+
+      <View className="items-center p-8 rounded-2xl bg-stone-200">
+        <Spinner size="lg" color="success" isLoading={isLoading} />
+        <Text className="text-stone-500 mt-4">Processing...</Text>
+        <TouchableOpacity onPress={() => setIsLoading(!isLoading)}>
+          <Text className="text-primary mt-2 text-sm">
+            {isLoading ? 'Tap to stop' : 'Tap to start'}
+          </Text>
+        </TouchableOpacity>
+      </View>
+
+      <View className="flex-row gap-4 items-center justify-center">
+        <Spinner size="md" color="#EC4899">
+          <Spinner.Indicator animation={{ rotation: { speed: 0.7 } }}>
+            <Ionicons name="refresh" size={24} color="#EC4899" />
+          </Spinner.Indicator>
+        </Spinner>
+      </View>
+    </View>
+  );
+}
+```
+
+## Anatomy
+
+```tsx
+<Spinner>
+  <Spinner.Indicator>...</Spinner.Indicator>
+</Spinner>
+```
+
+- **Spinner**: Main container that controls loading state, size, and color. Renders a default animated indicator if no children provided.
+- **Spinner.Indicator**: Optional sub-component for customizing animation configuration and icon appearance. Accepts custom children to replace the default icon.
+
+## API Reference
+
+### Spinner
+
+| prop           | type                                                        | default     | description                                        |
+| -------------- | ----------------------------------------------------------- | ----------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode`                                           | `undefined` | Content to render inside the spinner               |
+| `size`         | `'sm' \| 'md' \| 'lg'`                                      | `'md'`      | Size of the spinner                                |
+| `color`        | `'default' \| 'success' \| 'warning' \| 'danger' \| string` | `'default'` | Color theme of the spinner                         |
+| `isLoading`    | `boolean`                                                   | `true`      | Whether the spinner is loading                     |
+| `className`    | `string`                                                    | `undefined` | Custom class name for the spinner                  |
+| `animation`    | `SpinnerRootAnimation`                                      | -           | Animation configuration                            |
+| `...ViewProps` | `ViewProps`                                                 | -           | All standard React Native View props are supported |
+
+#### SpinnerRootAnimation
+
+Animation configuration for Spinner 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`<br/>`.duration(200)`<br/>`.easing(Easing.out(Easing.ease))` | Custom entering animation                       |
+| `exiting.value`  | `EntryOrExitLayoutType`                  | `FadeOut`<br/>`.duration(100)`                                       | Custom exiting animation                        |
+
+### Spinner.Indicator
+
+| prop                    | type                        | default     | description                                                  |
+| ----------------------- | --------------------------- | ----------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode`           | `undefined` | Content to render inside the indicator                       |
+| `iconProps`             | `SpinnerIconProps`          | `undefined` | Props for the default icon                                   |
+| `className`             | `string`                    | `undefined` | Custom class name for the indicator element                  |
+| `animation`             | `SpinnerIndicatorAnimation` | -           | Animation configuration                                      |
+| `isAnimatedStyleActive` | `boolean`                   | `true`      | Whether animated styles (react-native-reanimated) are active |
+| `...Animated.ViewProps` | `Animated.ViewProps`        | -           | All Reanimated Animated.View props are supported             |
+
+#### SpinnerIndicatorAnimation
+
+Animation configuration for Spinner.Indicator component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop              | type                         | default         | description                                     |
+| ----------------- | ---------------------------- | --------------- | ----------------------------------------------- |
+| `state`           | `'disabled' \| boolean`      | -               | Disable animations while customizing properties |
+| `rotation.speed`  | `number`                     | `1.1`           | Rotation speed multiplier                       |
+| `rotation.easing` | `WithTimingConfig['easing']` | `Easing.linear` | Animation easing configuration                  |
+
+### SpinnerIconProps
+
+| prop     | type               | default          | description        |
+| -------- | ------------------ | ---------------- | ------------------ |
+| `width`  | `number \| string` | `24`             | Width of the icon  |
+| `height` | `number \| string` | `24`             | Height of the icon |
+| `color`  | `string`           | `'currentColor'` | Color of the icon  |

package/src/components/spinner/spinner.styles.ts

@@ -0,0 +1,46 @@
+import { tv } from 'tailwind-variants';
+import { combineStyles } from '../../helpers/theme/utils/combine-styles';
+
+const root = tv({
+  base: 'items-center justify-center',
+  variants: {
+    size: {
+      sm: 'size-4',
+      md: 'size-6',
+      lg: 'size-8',
+    },
+  },
+  defaultVariants: {
+    size: 'md',
+  },
+});
+
+/**
+ * Indicator style definition
+ *
+ * @note ANIMATED PROPERTIES (cannot be set via className):
+ * The following property is animated and cannot be overridden using Tailwind classes:
+ * - `transform` (specifically `rotate`) - Animated for continuous rotation animation
+ *
+ * To customize this property, use the `animation` prop on `Spinner.Indicator`:
+ * ```tsx
+ * <Spinner.Indicator
+ *   animation={{
+ *     rotation: { speed: 1.1, easing: Easing.linear }
+ *   }}
+ * />
+ * ```
+ *
+ * To completely disable animated styles and apply your own via className or style prop,
+ * set `isAnimatedStyleActive={false}` on `Spinner.Indicator`.
+ */
+const indicator = tv({
+  base: 'size-full items-center justify-center',
+});
+
+const spinnerStyles = combineStyles({
+  root,
+  indicator,
+});
+
+export default spinnerStyles;