@erquhart/heroui-native 1.0.0-beta.10.1

package/src/components/pressable-feedback/pressable-feedback.animation.ts

@@ -0,0 +1,380 @@
+import { useCallback } from 'react';
+import type { GestureResponderEvent } from 'react-native';
+import {
+  Easing,
+  interpolate,
+  useAnimatedReaction,
+  useAnimatedStyle,
+  useDerivedValue,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated';
+import { useUniwind } from 'uniwind';
+import { useAnimationSettings } from '../../helpers/contexts';
+import { useCombinedAnimationDisabledState } from '../../helpers/hooks';
+import { createContext } from '../../helpers/utils';
+import {
+  getAnimationState,
+  getAnimationValueMergedConfig,
+  getAnimationValueProperty,
+  getIsAnimationDisabledValue,
+  getRootAnimationState,
+} from '../../helpers/utils/animation';
+import {
+  BASE_RIPPLE_PROGRESS_DURATION,
+  BASE_RIPPLE_PROGRESS_DURATION_MIN,
+} from './pressable-feedback.constants';
+import type {
+  PressableFeedbackHighlightAnimation,
+  PressableFeedbackRippleAnimation,
+  PressableFeedbackRootAnimation,
+  PressableFeedbackRootAnimationContextValue,
+} from './pressable-feedback.types';
+
+const [
+  PressableFeedbackRootAnimationProvider,
+  usePressableFeedbackRootAnimationContext,
+] = createContext<PressableFeedbackRootAnimationContextValue>({
+  name: 'PressableFeedbackRootAnimationContext',
+});
+
+export {
+  PressableFeedbackRootAnimationProvider,
+  usePressableFeedbackRootAnimationContext,
+};
+
+// --------------------------------------------------
+
+/**
+ * Animation hook for PressableFeedback root component
+ * Handles scale animation only
+ */
+export function usePressableFeedbackRootAnimation(options: {
+  animation?: PressableFeedbackRootAnimation;
+}) {
+  const { animation } = options;
+
+  const { animationConfig, isAnimationDisabled } =
+    getRootAnimationState(animation);
+
+  const isAllAnimationsDisabled = useCombinedAnimationDisabledState(animation);
+
+  const isAnimationDisabledValue = getIsAnimationDisabledValue({
+    isAnimationDisabled,
+    isAllAnimationsDisabled,
+  });
+
+  // Scale animation values
+  const scaleValue = getAnimationValueProperty({
+    animationValue: animationConfig?.scale,
+    property: 'value',
+    defaultValue: 0.985,
+  });
+
+  const scaleTimingConfig = getAnimationValueMergedConfig({
+    animationValue: animationConfig?.scale,
+    property: 'timingConfig',
+    defaultValue: { duration: 300, easing: Easing.out(Easing.ease) },
+  });
+
+  const ignoreScaleCoefficient = getAnimationValueProperty({
+    animationValue: animationConfig?.scale,
+    property: 'ignoreScaleCoefficient',
+    defaultValue: false,
+  });
+
+  // Shared values
+  const isPressed = useSharedValue(false);
+  const scale = useSharedValue(0);
+  const containerWidth = useSharedValue(0);
+  const containerHeight = useSharedValue(0);
+
+  const adjustedScaleValue = useDerivedValue(() => {
+    // Calculate scale coefficient to maintain consistent scale effect across different sizes
+    // Can be disabled by setting ignoreScaleCoefficient to true
+    const coefficient = ignoreScaleCoefficient
+      ? 1
+      : containerWidth.get() > 0
+        ? 300 / containerWidth.get()
+        : 1;
+    return 1 - (1 - scaleValue) * coefficient;
+  });
+
+  const animationOnPressIn = useCallback(() => {
+    isPressed.set(true);
+    scale.set(withTiming(1, scaleTimingConfig));
+  }, [isPressed, scale, scaleTimingConfig]);
+
+  const animationOnPressOut = useCallback(() => {
+    isPressed.set(false);
+    scale.set(withTiming(0, scaleTimingConfig));
+  }, [isPressed, scale, scaleTimingConfig]);
+
+  const rContainerStyle = useAnimatedStyle(() => {
+    if (isAnimationDisabledValue) {
+      return {
+        transform: [
+          {
+            scale: 1,
+          },
+        ],
+      };
+    }
+
+    return {
+      transform: [
+        {
+          scale: interpolate(
+            scale.get(),
+            [0, 1],
+            [1, adjustedScaleValue.get()]
+          ),
+        },
+      ],
+    };
+  });
+
+  return {
+    rContainerStyle,
+    isAllAnimationsDisabled,
+    animationOnPressIn,
+    animationOnPressOut,
+    isPressed,
+    containerWidth,
+    containerHeight,
+  };
+}
+
+// --------------------------------------------------
+
+/**
+ * Animation hook for PressableFeedback highlight overlay
+ * Handles opacity and background color animations for the highlight effect
+ */
+export function usePressableFeedbackHighlightAnimation(options: {
+  animation?: PressableFeedbackHighlightAnimation;
+}) {
+  const { animation } = options;
+
+  const { theme } = useUniwind();
+
+  const { isAllAnimationsDisabled } = useAnimationSettings();
+
+  const { isPressed } = usePressableFeedbackRootAnimationContext();
+
+  const { animationConfig, isAnimationDisabled } = getAnimationState(animation);
+
+  const isAnimationDisabledValue = getIsAnimationDisabledValue({
+    isAnimationDisabled,
+    isAllAnimationsDisabled,
+  });
+
+  // Background color
+  const defaultColor = theme === 'dark' ? '#d4d4d8' : '#3f3f46';
+
+  const backgroundColor = getAnimationValueProperty({
+    animationValue: animationConfig?.backgroundColor,
+    property: 'value',
+    defaultValue: defaultColor,
+  });
+
+  // Opacity animation
+  const opacityValue = getAnimationValueProperty({
+    animationValue: animationConfig?.opacity,
+    property: 'value',
+    defaultValue: [0, 0.1] as [number, number],
+  });
+
+  const opacityTimingConfig = getAnimationValueMergedConfig({
+    animationValue: animationConfig?.opacity,
+    property: 'timingConfig',
+    defaultValue: { duration: 200 },
+  });
+
+  const rContainerStyle = useAnimatedStyle(() => {
+    if (isAnimationDisabledValue) {
+      return {};
+    }
+
+    return {
+      backgroundColor,
+      opacity: withTiming(
+        isPressed.get() ? opacityValue[1] : opacityValue[0],
+        opacityTimingConfig
+      ),
+    };
+  });
+
+  return {
+    rContainerStyle,
+  };
+}
+
+// --------------------------------------------------
+
+/**
+ * Animation hook for PressableFeedback ripple effect
+ * Handles ripple circle animation with radial gradient
+ */
+export function usePressableFeedbackRippleAnimation(options: {
+  animation?: PressableFeedbackRippleAnimation;
+}) {
+  const { animation } = options;
+
+  const { theme } = useUniwind();
+
+  const { isAllAnimationsDisabled } = useAnimationSettings();
+
+  const { containerWidth, containerHeight } =
+    usePressableFeedbackRootAnimationContext();
+
+  const pressedCenterX = useSharedValue(0);
+  const pressedCenterY = useSharedValue(0);
+  const rippleProgress = useSharedValue(0);
+  const isPressed = useSharedValue(false);
+
+  const { animationConfig, isAnimationDisabled } = getAnimationState(animation);
+
+  const isAnimationDisabledValue = getIsAnimationDisabledValue({
+    isAnimationDisabled,
+    isAllAnimationsDisabled,
+  });
+
+  const rippleProgressBaseDuration = getAnimationValueProperty({
+    animationValue: animationConfig?.progress,
+    property: 'baseDuration',
+    defaultValue: BASE_RIPPLE_PROGRESS_DURATION,
+  });
+
+  const ignoreDurationCoefficient = getAnimationValueProperty({
+    animationValue: animationConfig?.progress,
+    property: 'ignoreDurationCoefficient',
+    defaultValue: false,
+  });
+
+  const rippleProgressMinBaseDuration = getAnimationValueProperty({
+    animationValue: animationConfig?.progress,
+    property: 'minBaseDuration',
+    defaultValue: BASE_RIPPLE_PROGRESS_DURATION_MIN,
+  });
+
+  // Calculate duration coefficient based on diagonal to maintain consistent ripple speed
+  const durationCoefficient = useDerivedValue(() => {
+    if (ignoreDurationCoefficient) return 1;
+
+    const baseDiagonal = 450;
+    const currentDiagonal = Math.sqrt(
+      containerWidth.get() ** 2 + containerHeight.get() ** 2
+    );
+    return currentDiagonal > 0 ? currentDiagonal / baseDiagonal : 1;
+  });
+
+  // Touch handlers for ripple
+  const animationOnTouchStart = useCallback(
+    (event: GestureResponderEvent) => {
+      isPressed.set(true);
+      pressedCenterX.set(event.nativeEvent.locationX);
+      pressedCenterY.set(event.nativeEvent.locationY);
+      rippleProgress.set(0);
+    },
+    [isPressed, pressedCenterX, pressedCenterY, rippleProgress]
+  );
+
+  useAnimatedReaction(
+    () => isPressed.get(),
+    (isPressedValue) => {
+      if (isPressedValue && rippleProgress.get() === 0) {
+        const adjustedDuration = Math.min(
+          Math.max(
+            rippleProgressBaseDuration * durationCoefficient.get(),
+            rippleProgressMinBaseDuration
+          ),
+          rippleProgressBaseDuration * 2
+        );
+        rippleProgress.set(withTiming(1, { duration: adjustedDuration }));
+      }
+    }
+  );
+
+  const animationOnTouchEnd = useCallback(() => {
+    isPressed.set(false);
+    const adjustedDuration = Math.min(
+      Math.max(
+        rippleProgressBaseDuration * durationCoefficient.get(),
+        rippleProgressMinBaseDuration
+      ),
+      rippleProgressBaseDuration * 2
+    );
+    rippleProgress.set(withTiming(2, { duration: adjustedDuration }));
+  }, [
+    isPressed,
+    rippleProgress,
+    durationCoefficient,
+    rippleProgressBaseDuration,
+    rippleProgressMinBaseDuration,
+  ]);
+
+  // Background color
+  const defaultColor = theme === 'dark' ? '#d4d4d8' : '#3f3f46';
+
+  const backgroundColor = getAnimationValueProperty({
+    animationValue: animationConfig?.backgroundColor,
+    property: 'value',
+    defaultValue: defaultColor,
+  });
+
+  // Opacity animation
+  const opacityValue = getAnimationValueProperty({
+    animationValue: animationConfig?.opacity,
+    property: 'value',
+    defaultValue: [0, 0.1, 0] as [number, number, number],
+  });
+
+  // Scale animation
+  const scaleValue = getAnimationValueProperty({
+    animationValue: animationConfig?.scale,
+    property: 'value',
+    defaultValue: [0, 1, 1] as [number, number, number],
+  });
+
+  const rContainerStyle = useAnimatedStyle(() => {
+    if (isAnimationDisabledValue) {
+      return {};
+    }
+
+    const circleRadius =
+      Math.sqrt(containerWidth.get() ** 2 + containerHeight.get() ** 2) * 1.25;
+
+    const translateX = pressedCenterX.get() - circleRadius;
+    const translateY = pressedCenterY.get() - circleRadius;
+
+    return {
+      width: circleRadius * 2,
+      height: circleRadius * 2,
+      borderRadius: circleRadius,
+      opacity: interpolate(
+        rippleProgress.get(),
+        [0, 1, 2],
+        [opacityValue[0], opacityValue[1], opacityValue[2]]
+      ),
+      transform: [
+        { translateX },
+        { translateY },
+        {
+          scale: interpolate(
+            rippleProgress.get(),
+            [0, 1, 2],
+            [scaleValue[0], scaleValue[1], scaleValue[2]]
+          ),
+        },
+      ],
+    };
+  });
+
+  return {
+    rContainerStyle,
+    backgroundColor,
+    animationOnTouchStart,
+    animationOnTouchEnd,
+  };
+}

package/src/components/pressable-feedback/pressable-feedback.constants.ts

@@ -0,0 +1,11 @@
+/**
+ * Display names for PressableFeedback components
+ */
+export const DISPLAY_NAME = {
+  ROOT: 'HeroUINative.PressableFeedback.Root',
+  HIGHLIGHT: 'HeroUINative.PressableFeedback.Highlight',
+  RIPPLE: 'HeroUINative.PressableFeedback.Ripple',
+} as const;
+
+export const BASE_RIPPLE_PROGRESS_DURATION = 1000;
+export const BASE_RIPPLE_PROGRESS_DURATION_MIN = 750;

package/src/components/pressable-feedback/pressable-feedback.md

@@ -0,0 +1,246 @@
+# PressableFeedback
+
+Container component that provides visual feedback for press interactions with automatic scale animation.
+
+## Imports
+
+Note: Before importing this component, ensure you have completed the setup as per the [Quick Start guide](../../../README.md).
+
+```tsx
+import { PressableFeedback } from 'heroui-native';
+```
+
+## Usage
+
+### Basic Usage
+
+The PressableFeedback component wraps content to provide press feedback effects. By default, it applies a subtle scale animation when pressed.
+
+```tsx
+<PressableFeedback>...</PressableFeedback>
+```
+
+### Highlight Effect
+
+Add a highlight overlay component for iOS-style feedback effect. The highlight uses the root's press state from context.
+
+```tsx
+<PressableFeedback>
+  <PressableFeedback.Highlight />
+  ...
+</PressableFeedback>
+```
+
+### Ripple Effect
+
+Add a ripple overlay component for Android-style feedback effect that emanates from the press point.
+
+```tsx
+<PressableFeedback>
+  <PressableFeedback.Ripple />
+  ...
+</PressableFeedback>
+```
+
+### Custom Scale Animation
+
+Customize or disable the default scale animation on press.
+
+```tsx
+<PressableFeedback
+  animation={{
+    scale: {
+      value: 0.9,
+      timingConfig: { duration: 150 },
+    },
+  }}
+>
+  ...
+</PressableFeedback>
+```
+
+### Custom Highlight Animation
+
+Configure highlight overlay opacity and background color.
+
+```tsx
+<PressableFeedback>
+  <PressableFeedback.Highlight
+    animation={{
+      opacity: { value: [0, 0.2] },
+      backgroundColor: { value: '#3b82f6' },
+    }}
+  />
+  ...
+</PressableFeedback>
+```
+
+### Custom Ripple Animation
+
+Configure ripple effect color, opacity, and duration.
+
+```tsx
+<PressableFeedback>
+  <PressableFeedback.Ripple
+    animation={{
+      backgroundColor: { value: '#ec4899' },
+      opacity: { value: [0, 0.1, 0] },
+      progress: { baseDuration: 600 },
+    }}
+  />
+  ...
+</PressableFeedback>
+```
+
+## Example
+
+```tsx
+import { PressableFeedback, Card, Button } from 'heroui-native';
+import { Image } from 'expo-image';
+import { LinearGradient } from 'expo-linear-gradient';
+import { StyleSheet, View } from 'react-native';
+
+export default function PressableFeedbackExample() {
+  return (
+    <PressableFeedback className="w-full aspect-square rounded-3xl">
+      <Card className="flex-1">
+        <Image
+          source={{
+            uri: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/neo2.jpeg',
+          }}
+          style={StyleSheet.absoluteFill}
+          contentFit="cover"
+        />
+        <LinearGradient
+          colors={['rgba(0,0,0,0.1)', 'rgba(0,0,0,0.4)']}
+          style={StyleSheet.absoluteFill}
+        />
+        <PressableFeedback.Ripple
+          animation={{
+            backgroundColor: { value: 'white' },
+            opacity: { value: [0, 0.3, 0] },
+          }}
+        />
+        <View className="flex-1 gap-4" pointerEvents="box-none">
+          <Card.Body className="flex-1" pointerEvents="none">
+            <Card.Title className="text-base text-zinc-50 uppercase mb-0.5">
+              Neo
+            </Card.Title>
+            <Card.Description className="text-zinc-50 font-medium text-base">
+              Home robot
+            </Card.Description>
+          </Card.Body>
+          <Card.Footer className="gap-3">
+            <View className="flex-row items-center justify-between">
+              <View pointerEvents="none">
+                <Text className="text-base text-white">Available soon</Text>
+                <Text className="text-base text-zinc-300">Get notified</Text>
+              </View>
+              <Button size="sm" className="bg-white">
+                <Button.Label className="text-black">Notify me</Button.Label>
+              </Button>
+            </View>
+          </Card.Footer>
+        </View>
+      </Card>
+    </PressableFeedback>
+  );
+}
+```
+
+## API Reference
+
+### PressableFeedback
+
+| prop                    | type                             | default | description                                                  |
+| ----------------------- | -------------------------------- | ------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode`                | -       | Content to be wrapped with press feedback                    |
+| `isDisabled`            | `boolean`                        | `false` | Whether the pressable component is disabled                  |
+| `className`             | `string`                         | -       | Additional CSS classes                                       |
+| `animation`             | `PressableFeedbackRootAnimation` | -       | Animation configuration for scale animation only             |
+| `isAnimatedStyleActive` | `boolean`                        | `true`  | Whether animated styles (react-native-reanimated) are active |
+| `...AnimatedProps`      | `AnimatedProps<PressableProps>`  | -       | All Reanimated Animated Pressable props are supported        |
+
+#### PressableFeedbackRootAnimation
+
+Animation configuration for PressableFeedback root component (scale only). 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                             |
+| `scale.value`                  | `number`                                | `0.985`                                              | Scale value when pressed (automatically adjusted based on container width) |
+| `scale.timingConfig`           | `WithTimingConfig`                      | `{ duration: 300, easing: Easing.out(Easing.ease) }` | Animation timing configuration                                             |
+| `scale.ignoreScaleCoefficient` | `boolean`                               | `false`                                              | Ignore automatic scale coefficient and use the scale value directly        |
+
+### PressableFeedback.Highlight
+
+| prop                    | type                                  | default | description                                                  |
+| ----------------------- | ------------------------------------- | ------- | ------------------------------------------------------------ |
+| `className`             | `string`                              | -       | Additional CSS classes                                       |
+| `animation`             | `PressableFeedbackHighlightAnimation` | -       | Animation configuration for highlight overlay                |
+| `isAnimatedStyleActive` | `boolean`                             | `true`  | Whether animated styles (react-native-reanimated) are active |
+| `style`                 | `ViewStyle`                           | -       | Additional styles                                            |
+| `...AnimatedProps`      | `AnimatedProps<ViewProps>`            | -       | All Reanimated Animated View props are supported             |
+
+#### PressableFeedbackHighlightAnimation
+
+Animation configuration for highlight overlay. Can be:
+
+- `false` or `"disabled"`: Disable highlight animations
+- `"disable-all"`: Disable all animations including children
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                    | type                          | default             | description                           |
+| ----------------------- | ----------------------------- | ------------------- | ------------------------------------- |
+| `state`                 | `'disabled' \| boolean`       | -                   | Disable animations while customizing properties |
+| `opacity.value`         | `[number, number]`            | `[0, 0.1]`          | Opacity values [unpressed, pressed]   |
+| `opacity.timingConfig`  | `WithTimingConfig`            | `{ duration: 200 }` | Animation timing configuration        |
+| `backgroundColor.value` | `string`                      | Theme-aware gray    | Background color of highlight overlay |
+
+### PressableFeedback.Ripple
+
+| prop                    | type                                     | default | description                                                  |
+| ----------------------- | ---------------------------------------- | ------- | ------------------------------------------------------------ |
+| `className`             | `string`                                 | -       | Additional CSS classes for container slot                    |
+| `classNames`            | `ElementSlots<RippleSlots>`              | -       | Additional CSS classes for slots (container, ripple)         |
+| `containerStyle`        | `ViewStyle`                              | -       | Style for the container slot                                 |
+| `rippleStyle`           | `ViewStyle`                              | -       | Style for the ripple slot                                    |
+| `animation`             | `PressableFeedbackRippleAnimation`       | -       | Animation configuration for ripple overlay                   |
+| `isAnimatedStyleActive` | `boolean`                                | `true`  | Whether animated styles (react-native-reanimated) are active |
+| `...ViewProps`          | `Omit<ViewProps, 'style'>`               | -       | All View props except style are supported                    |
+
+#### PressableFeedbackRippleAnimation
+
+Animation configuration for ripple overlay. Can be:
+
+- `false` or `"disabled"`: Disable ripple animations
+- `"disable-all"`: Disable all animations including children
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                                 | type                          | default                 | description                                                                  |
+| ------------------------------------ | ----------------------------- | ----------------------- | ---------------------------------------------------------------------------- |
+| `state`                              | `'disabled' \| boolean`       | -                       | Disable animations while customizing properties                              |
+| `backgroundColor.value`               | `string`                      | Computed based on theme | Background color of ripple effect                                            |
+| `progress.baseDuration`              | `number`                      | `1000`                  | Base duration for ripple progress (automatically adjusted based on diagonal) |
+| `progress.minBaseDuration`           | `number`                      | `750`                   | Minimum base duration for the ripple progress animation                      |
+| `progress.ignoreDurationCoefficient` | `boolean`                     | `false`                 | Ignore automatic duration coefficient and use base duration directly         |
+| `opacity.value`                      | `[number, number, number]`    | `[0, 0.1, 0]`           | Opacity values [start, peak, end] for ripple animation                       |
+| `opacity.timingConfig`               | `WithTimingConfig`            | `{ duration: 200 }`     | Animation timing configuration                                               |
+| `scale.value`                        | `[number, number, number]`    | `[0, 1, 1]`             | Scale values [start, peak, end] for ripple animation                         |
+| `scale.timingConfig`                 | `WithTimingConfig`            | `{ duration: 200 }`     | Animation timing configuration                                               |
+
+#### ElementSlots<RippleSlots>
+
+Additional CSS classes for ripple slots:
+
+| slot        | description                                                                                                         |
+| ----------- | ------------------------------------------------------------------------------------------------------------------- |
+| `container` | Outer container slot (`absolute inset-0`) - styles can be fully customized                                          |
+| `ripple`    | Inner ripple slot (`absolute top-0 left-0 rounded-full`) - has animated properties that cannot be set via className |