@erquhart/heroui-native 1.0.0-beta.10.1

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

@@ -0,0 +1,327 @@
+import { forwardRef, useMemo } from 'react';
+import { View } from 'react-native';
+import Animated from 'react-native-reanimated';
+
+import { AnimationSettingsProvider } from '../../helpers/contexts/animation-settings-context';
+import { useIsOnSurface } from '../../helpers/theme';
+import type { TextRef, ViewRef } from '../../helpers/types';
+import { childrenToString, createContext } from '../../helpers/utils';
+import * as RadioGroupPrimitives from '../../primitives/radio-group';
+import { ErrorView } from '../error-view';
+import { FormField } from '../form-field';
+import {
+  useRadioGroupIndicatorThumbAnimation,
+  useRadioGroupRootAnimation,
+} from './radio-group.animation';
+import { DEFAULT_HIT_SLOP, DISPLAY_NAME } from './radio-group.constants';
+import radioGroupStyles, { styleSheet } from './radio-group.styles';
+import type {
+  RadioGroupDescriptionProps,
+  RadioGroupErrorMessageProps,
+  RadioGroupIndicatorProps,
+  RadioGroupIndicatorThumbProps,
+  RadioGroupItemContextValue,
+  RadioGroupItemProps,
+  RadioGroupItemRenderProps,
+  RadioGroupLabelProps,
+  RadioGroupProps,
+} from './radio-group.types';
+
+const AnimatedRadioItem = Animated.createAnimatedComponent(
+  RadioGroupPrimitives.Item
+);
+
+const AnimatedRadioIndicator = Animated.createAnimatedComponent(
+  RadioGroupPrimitives.Indicator
+);
+
+const [RadioGroupItemProvider, useRadioGroupItem] =
+  createContext<RadioGroupItemContextValue>({
+    name: 'RadioGroupItemContext',
+  });
+
+const useRadioGroup = RadioGroupPrimitives.useRadioGroupContext;
+
+// --------------------------------------------------
+
+const RadioGroupRoot = forwardRef<
+  RadioGroupPrimitives.RootRef,
+  RadioGroupProps
+>((props, ref) => {
+  const { className, isInvalid = false, animation, ...restProps } = props;
+
+  const tvStyles = radioGroupStyles.root({
+    className,
+  });
+
+  const { isAllAnimationsDisabled } = useRadioGroupRootAnimation({
+    animation,
+  });
+
+  const animationSettingsContextValue = useMemo(
+    () => ({
+      isAllAnimationsDisabled,
+    }),
+    [isAllAnimationsDisabled]
+  );
+
+  return (
+    <AnimationSettingsProvider value={animationSettingsContextValue}>
+      <RadioGroupPrimitives.Root
+        ref={ref}
+        className={tvStyles}
+        isInvalid={isInvalid}
+        {...restProps}
+      />
+    </AnimationSettingsProvider>
+  );
+});
+
+// --------------------------------------------------
+
+const RadioGroupItem = forwardRef<
+  RadioGroupPrimitives.ItemRef,
+  RadioGroupItemProps
+>((props, ref) => {
+  const {
+    children,
+    value,
+    isDisabled,
+    isInvalid,
+    isOnSurface: isOnSurfaceProp,
+    className,
+    ...restProps
+  } = props;
+
+  const stringifiedChildren =
+    typeof children === 'function'
+      ? null
+      : childrenToString(children as React.ReactNode);
+
+  const {
+    value: groupValue,
+    isInvalid: groupIsInvalid,
+    isDisabled: groupIsDisabled,
+    isOnSurface: isOnSurfaceGroup,
+  } = useRadioGroup();
+
+  const isSelected = groupValue === value;
+
+  const isDisabledValue = isDisabled ?? groupIsDisabled ?? false;
+
+  const effectiveIsInvalid = isInvalid ?? groupIsInvalid ?? false;
+
+  const isOnSurfaceAutoDetected = useIsOnSurface();
+
+  const isOnSurface =
+    isOnSurfaceProp ?? isOnSurfaceGroup ?? isOnSurfaceAutoDetected;
+
+  const tvStyles = radioGroupStyles.item({
+    isDisabled: isDisabledValue,
+    className,
+  });
+
+  const renderProps: RadioGroupItemRenderProps = {
+    isSelected,
+    isDisabled: isDisabledValue,
+    isInvalid: effectiveIsInvalid,
+  };
+
+  const content = stringifiedChildren ? (
+    <>
+      <RadioGroupLabel>{stringifiedChildren}</RadioGroupLabel>
+      <RadioGroupIndicator />
+    </>
+  ) : typeof children === 'function' ? (
+    children(renderProps)
+  ) : (
+    children
+  );
+
+  const contextValue = useMemo(
+    () => ({
+      isSelected,
+      isDisabled: isDisabledValue,
+      isInvalid: effectiveIsInvalid,
+      isOnSurface,
+    }),
+    [isSelected, isDisabledValue, effectiveIsInvalid, isOnSurface]
+  );
+
+  return (
+    <RadioGroupItemProvider value={contextValue}>
+      <AnimatedRadioItem
+        ref={ref}
+        value={value}
+        className={tvStyles}
+        isDisabled={isDisabledValue}
+        hitSlop={props.hitSlop ?? DEFAULT_HIT_SLOP}
+        {...restProps}
+      >
+        {content}
+      </AnimatedRadioItem>
+    </RadioGroupItemProvider>
+  );
+});
+
+// --------------------------------------------------
+
+const RadioGroupIndicator = forwardRef<Animated.View, RadioGroupIndicatorProps>(
+  (props, ref) => {
+    const { children, className, style, ...restProps } = props;
+
+    const { isSelected, isInvalid, isOnSurface } = useRadioGroupItem();
+
+    const tvStyles = radioGroupStyles.itemIndicator({
+      isOnSurface,
+      isSelected,
+      isInvalid,
+      className,
+    });
+
+    return (
+      <AnimatedRadioIndicator
+        ref={ref}
+        className={tvStyles}
+        style={[styleSheet.borderCurve, style]}
+        {...restProps}
+      >
+        {children ?? <RadioGroupIndicatorThumb />}
+      </AnimatedRadioIndicator>
+    );
+  }
+);
+
+// --------------------------------------------------
+
+const RadioGroupIndicatorThumb = forwardRef<
+  View,
+  RadioGroupIndicatorThumbProps
+>((props, ref) => {
+  const {
+    className,
+    style,
+    animation,
+    isAnimatedStyleActive = true,
+    ...restProps
+  } = props;
+
+  const { isSelected, isOnSurface } = useRadioGroupItem();
+
+  const thumbClassName = radioGroupStyles.itemIndicatorThumb({
+    isOnSurface,
+    isSelected,
+    className,
+  });
+
+  const { rContainerStyle } = useRadioGroupIndicatorThumbAnimation({
+    animation,
+    isSelected,
+  });
+
+  const thumbStyle = isAnimatedStyleActive ? [rContainerStyle, style] : style;
+
+  return (
+    <Animated.View
+      ref={ref}
+      className={thumbClassName}
+      style={thumbStyle}
+      {...restProps}
+    />
+  );
+});
+
+// --------------------------------------------------
+
+const RadioGroupLabel = forwardRef<TextRef, RadioGroupLabelProps>(
+  (props, ref) => {
+    return <FormField.Label ref={ref} {...props} />;
+  }
+);
+
+// --------------------------------------------------
+
+const RadioGroupDescription = forwardRef<TextRef, RadioGroupDescriptionProps>(
+  (props, ref) => {
+    return <FormField.Description ref={ref} {...props} />;
+  }
+);
+
+// --------------------------------------------------
+
+const RadioGroupErrorMessage = forwardRef<ViewRef, RadioGroupErrorMessageProps>(
+  (props, ref) => {
+    const { className, ...restProps } = props;
+
+    const { isInvalid } = useRadioGroup();
+
+    const tvStyles = radioGroupStyles.errorMessage({
+      className,
+    });
+
+    return (
+      <ErrorView
+        ref={ref}
+        isInvalid={isInvalid}
+        className={tvStyles}
+        {...restProps}
+      />
+    );
+  }
+);
+
+RadioGroupRoot.displayName = DISPLAY_NAME.RADIO_GROUP_ROOT;
+RadioGroupItem.displayName = DISPLAY_NAME.RADIO_GROUP_ITEM;
+RadioGroupIndicator.displayName = DISPLAY_NAME.RADIO_GROUP_INDICATOR;
+RadioGroupIndicatorThumb.displayName = DISPLAY_NAME.RADIO_GROUP_INDICATOR_THUMB;
+RadioGroupLabel.displayName = DISPLAY_NAME.RADIO_GROUP_TITLE;
+RadioGroupDescription.displayName = DISPLAY_NAME.RADIO_GROUP_DESCRIPTION;
+RadioGroupErrorMessage.displayName = DISPLAY_NAME.RADIO_GROUP_ERROR_MESSAGE;
+
+/**
+ * Compound RadioGroup component with sub-components
+ *
+ * @component RadioGroup - Container that manages the selection state of RadioGroupItem components.
+ * Supports both horizontal and vertical orientations.
+ *
+ * @component RadioGroup.ErrorMessage - Error message displayed when radio group is invalid.
+ * Shown with animation below the radio group content. Takes full width when orientation is horizontal.
+ *
+ * @component RadioGroup.Item - Individual radio option within a RadioGroup. Must be used inside RadioGroup.
+ * Handles selection state and renders default indicator if no children provided. Animates border
+ * color based on selection state.
+ *
+ * @component RadioGroup.Indicator - Optional container for the radio circle. Renders default thumb
+ * if no children provided. Manages the visual selection state.
+ *
+ * @component RadioGroup.IndicatorThumb - Optional inner circle that appears when selected. Animates
+ * scale based on selection. Can be replaced with custom content.
+ *
+ * @component RadioGroup.Label - Optional text label for the radio option. Clickable by default and
+ * linked to the radio for accessibility.
+ *
+ * @component RadioGroup.Description - Optional secondary text below the label. Provides additional
+ * context about the radio option.
+ *
+ * Props flow from RadioGroup to RadioGroupItem to sub-components via context (color, value, isSelected).
+ * RadioGroup manages the overall selection state and orientation.
+ *
+ * @see Full documentation: https://heroui.com/components/radio-group
+ */
+const CompoundRadioGroup = Object.assign(RadioGroupRoot, {
+  /** @optional Error message displayed when radio group is invalid */
+  ErrorMessage: RadioGroupErrorMessage,
+  /** Individual radio option within a RadioGroup */
+  Item: RadioGroupItem,
+  /** @optional Custom radio indicator container */
+  Indicator: RadioGroupIndicator,
+  /** @optional Custom indicator thumb that appears when selected */
+  IndicatorThumb: RadioGroupIndicatorThumb,
+  /** @optional Clickable text label */
+  Label: RadioGroupLabel,
+  /** @optional Secondary descriptive text */
+  Description: RadioGroupDescription,
+});
+
+export default CompoundRadioGroup;
+export { useRadioGroup, useRadioGroupItem };

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

@@ -0,0 +1,152 @@
+import type { ViewProps } from 'react-native';
+import type { AnimatedProps, WithTimingConfig } from 'react-native-reanimated';
+import type {
+  Animation,
+  AnimationRootDisableAll,
+  AnimationValue,
+} from '../../helpers/types/animation';
+import type { ItemProps, RootProps } from '../../primitives/radio-group';
+import type { ErrorViewRootProps } from '../error-view/error-view.types';
+import type {
+  FormFieldDescriptionProps,
+  FormFieldLabelProps,
+} from '../form-field';
+
+/**
+ * Props for RadioGroup root component
+ */
+export interface RadioGroupProps extends Omit<RootProps, 'asChild'> {
+  /** Radio group content */
+  children?: React.ReactNode;
+  /** Custom class name */
+  className?: string;
+  /**
+   * Animation configuration for radio group
+   * - `"disable-all"`: Disable all animations including children
+   * - `undefined`: Use default animations
+   */
+  animation?: AnimationRootDisableAll;
+}
+
+/**
+ * Context values shared between RadioGroupItem compound components
+ */
+export interface RadioGroupItemContextValue {
+  /** Whether the radio item is selected */
+  isSelected: boolean;
+  /** Whether the radio item is disabled */
+  isDisabled?: boolean;
+  /** Whether the radio item is invalid */
+  isInvalid?: boolean;
+  /** Whether the radio item is on surface */
+  isOnSurface?: boolean;
+}
+
+/**
+ * Render function props for RadioGroupItem children
+ */
+export interface RadioGroupItemRenderProps {
+  /** Whether the radio item is selected */
+  isSelected: boolean;
+  /** Whether the radio item is disabled */
+  isDisabled: boolean;
+  /** Whether the radio item is invalid */
+  isInvalid: boolean;
+}
+
+/**
+ * Props for the RadioGroupItem component
+ */
+export interface RadioGroupItemProps extends Omit<ItemProps, 'children'> {
+  /** Radio item content, or a render function */
+  children?:
+    | React.ReactNode
+    | ((props: RadioGroupItemRenderProps) => React.ReactNode);
+  /** Whether the radio item is invalid @default false */
+  isInvalid?: boolean;
+  /** Whether the radio item is on surface */
+  isOnSurface?: boolean;
+  /** Custom class name */
+  className?: string;
+}
+
+/**
+ * Props for RadioGroup.Indicator component
+ */
+export interface RadioGroupIndicatorProps extends AnimatedProps<ViewProps> {
+  /** Indicator content */
+  children?: React.ReactNode;
+  /** Custom class name */
+  className?: string;
+}
+
+/**
+ * Animation configuration for RadioGroupIndicatorThumb component
+ */
+export type RadioGroupIndicatorThumbAnimation = Animation<{
+  scale?: AnimationValue<{
+    /**
+     * Scale values [unselected, selected]
+     * @default [1.5, 1]
+     */
+    value?: [number, number];
+    /**
+     * Animation timing configuration
+     * @default { duration: 300, easing: Easing.out(Easing.ease) }
+     */
+    timingConfig?: WithTimingConfig;
+  }>;
+}>;
+
+/**
+ * Props for RadioGroup.IndicatorThumb component
+ */
+export interface RadioGroupIndicatorThumbProps
+  extends Omit<AnimatedProps<ViewProps>, 'children'> {
+  /** Custom class name
+   *
+   * @note The following style properties are occupied by animations and cannot be set via className:
+   * - `transform` (specifically `scale`) - Animated for selection transitions (unselected: 1.5, selected: 1)
+   *
+   * To customize this property, use the `animation` prop:
+   * ```tsx
+   * <RadioGroup.IndicatorThumb
+   *   animation={{
+   *     scale: { value: [1.5, 1], timingConfig: { duration: 300, easing: Easing.out(Easing.ease) } }
+   *   }}
+   * />
+   * ```
+   *
+   * To completely disable animated styles and use your own via className or style prop, set `isAnimatedStyleActive={false}`.
+   */
+  className?: string;
+  /**
+   * Animation configuration
+   * - `false` or `"disabled"`: Disable all animations
+   * - `true` or `undefined`: Use default animations
+   * - `object`: Custom animation configuration
+   */
+  animation?: RadioGroupIndicatorThumbAnimation;
+  /**
+   * 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;
+}
+
+/**
+ * Props for RadioGroup.Label component
+ */
+export interface RadioGroupLabelProps extends FormFieldLabelProps {}
+
+/**
+ * Props for RadioGroup.Description component
+ */
+export interface RadioGroupDescriptionProps extends FormFieldDescriptionProps {}
+
+/**
+ * Props for RadioGroup.ErrorMessage component
+ */
+export interface RadioGroupErrorMessageProps extends ErrorViewRootProps {}

package/src/components/scroll-shadow/index.ts

@@ -0,0 +1,6 @@
+export { default as ScrollShadow } from './scroll-shadow';
+export type {
+  ScrollShadowOrientation,
+  ScrollShadowProps,
+  ScrollShadowVisibility,
+} from './scroll-shadow.types';

package/src/components/scroll-shadow/scroll-shadow.animation.ts

@@ -0,0 +1,132 @@
+import {
+  Extrapolation,
+  interpolate,
+  useAnimatedScrollHandler,
+  useAnimatedStyle,
+  useDerivedValue,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated';
+import { useCombinedAnimationDisabledState } from '../../helpers/hooks';
+import {
+  getAnimationValueProperty,
+  getIsAnimationDisabledValue,
+  getRootAnimationState,
+} from '../../helpers/utils/animation';
+import { SHADOW_EXIT_ANIMATION_DURATION } from './scroll-shadow.constants';
+import type {
+  ScrollShadowOrientation,
+  ScrollShadowRootAnimation,
+  ScrollShadowVisibility,
+} from './scroll-shadow.types';
+
+// --------------------------------------------------
+
+/**
+ * Animation hook for ScrollShadow root component
+ * Handles cascading animation disabled state and all animation logic
+ */
+export function useScrollShadowRootAnimation(options: {
+  animation: ScrollShadowRootAnimation | undefined;
+  orientation: ScrollShadowOrientation;
+  size: number;
+  visibility: ScrollShadowVisibility;
+  isEnabled: boolean;
+}) {
+  const { animation, orientation, size, visibility, isEnabled } = options;
+
+  const { animationConfig, isAnimationDisabled } =
+    getRootAnimationState(animation);
+
+  const isAllAnimationsDisabled = useCombinedAnimationDisabledState(animation);
+
+  const isAnimationDisabledValue = getIsAnimationDisabledValue({
+    isAnimationDisabled,
+    isAllAnimationsDisabled,
+  });
+
+  // Opacity animation values
+  const topOpacityValue = getAnimationValueProperty({
+    animationValue: animationConfig?.opacity,
+    property: 'value',
+    defaultValue: [0, 1] as [number, number],
+  });
+
+  // Reverse array for bottom shadow: [1, 0]
+  const bottomOpacityValue: [number, number] = [
+    topOpacityValue[1],
+    topOpacityValue[0],
+  ];
+
+  const scrollOffset = useSharedValue(0);
+  const contentSize = useSharedValue(0);
+  const containerSize = useSharedValue(0);
+
+  const localScrollHandler = useAnimatedScrollHandler({
+    onScroll: (event) => {
+      const offset =
+        orientation === 'vertical'
+          ? event.contentOffset.y
+          : event.contentOffset.x;
+      scrollOffset.set(offset);
+    },
+  });
+
+  const topShadowOpacity = useDerivedValue(() => {
+    if (isAnimationDisabledValue) {
+      return 1;
+    }
+
+    if (!isEnabled)
+      return withTiming(0, { duration: SHADOW_EXIT_ANIMATION_DURATION });
+    if (visibility === 'none')
+      return withTiming(0, { duration: SHADOW_EXIT_ANIMATION_DURATION });
+    if (visibility === 'bottom' || visibility === 'right')
+      return withTiming(0, { duration: SHADOW_EXIT_ANIMATION_DURATION });
+
+    return interpolate(
+      scrollOffset.get(),
+      [0, size / 4],
+      topOpacityValue,
+      Extrapolation.CLAMP
+    );
+  });
+
+  const bottomShadowOpacity = useDerivedValue(() => {
+    if (isAnimationDisabledValue) {
+      return 1;
+    }
+
+    if (!isEnabled)
+      return withTiming(0, { duration: SHADOW_EXIT_ANIMATION_DURATION });
+    if (visibility === 'none')
+      return withTiming(0, { duration: SHADOW_EXIT_ANIMATION_DURATION });
+    if (visibility === 'top' || visibility === 'left')
+      return withTiming(0, { duration: SHADOW_EXIT_ANIMATION_DURATION });
+
+    return interpolate(
+      scrollOffset.get() + containerSize.get(),
+      [contentSize.get() - size / 4, contentSize.get()],
+      bottomOpacityValue,
+      Extrapolation.CLAMP
+    );
+  });
+
+  const topShadowStyle = useAnimatedStyle(() => ({
+    opacity: topShadowOpacity.get(),
+  }));
+
+  const bottomShadowStyle = useAnimatedStyle(() => ({
+    opacity: bottomShadowOpacity.get(),
+  }));
+
+  return {
+    scrollOffset,
+    contentSize,
+    containerSize,
+    localScrollHandler,
+    topShadowStyle,
+    bottomShadowStyle,
+    isAllAnimationsDisabled,
+  };
+}

package/src/components/scroll-shadow/scroll-shadow.constants.ts

@@ -0,0 +1,21 @@
+/**
+ * Display name constants for ScrollShadow components
+ */
+export const SCROLL_SHADOW_DISPLAY_NAME = {
+  ROOT: 'HeroUINative.ScrollShadow',
+} as const;
+
+/**
+ * Default size for gradient shadows in pixels
+ */
+export const DEFAULT_SHADOW_SIZE = 50;
+
+/**
+ * Animation duration for shadow opacity transitions in milliseconds
+ */
+export const SHADOW_EXIT_ANIMATION_DURATION = 200;
+
+/**
+ * Default scroll event throttle for performance
+ */
+export const DEFAULT_SCROLL_EVENT_THROTTLE = 16;