@erquhart/heroui-native 1.0.0-beta.10.1

package/src/components/scroll-shadow/scroll-shadow.md

@@ -0,0 +1,191 @@
+# ScrollShadow
+
+Adds dynamic gradient shadows to scrollable content based on scroll position and overflow.
+
+## Imports
+
+Note: Before importing this component, ensure you have completed the setup as per the [Quick Start guide](../../../README.md).
+
+```tsx
+import { ScrollShadow } from 'heroui-native';
+```
+
+## Usage
+
+### Basic Usage
+
+Wrap any scrollable component to automatically add edge shadows.
+
+```tsx
+<ScrollShadow LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+```
+
+### Horizontal Scrolling
+
+The component auto-detects horizontal scrolling from the child's `horizontal` prop.
+
+```tsx
+<ScrollShadow LinearGradientComponent={LinearGradient}>
+  <FlatList horizontal data={data} renderItem={...} />
+</ScrollShadow>
+```
+
+### Custom Shadow Size
+
+Control the gradient shadow height/width with the `size` prop.
+
+```tsx
+<ScrollShadow size={100} LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+```
+
+### Visibility Control
+
+Specify which shadows to display using the `visibility` prop.
+
+```tsx
+<ScrollShadow visibility="top" LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+
+<ScrollShadow visibility="bottom" LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+
+<ScrollShadow visibility="none" LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+```
+
+### Custom Shadow Color
+
+Override the default shadow color which uses the theme's background.
+
+```tsx
+<ScrollShadow color="#ffffff" LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+```
+
+### With Custom Scroll Handler
+
+**Important:** ScrollShadow internally converts the child to a Reanimated animated component. If you need to use the `onScroll` prop, you must use `useAnimatedScrollHandler` from react-native-reanimated.
+
+```tsx
+import { LinearGradient } from 'expo-linear-gradient';
+import Animated, { useAnimatedScrollHandler } from 'react-native-reanimated';
+
+const scrollHandler = useAnimatedScrollHandler({
+  onScroll: (event) => {
+    console.log(event.contentOffset.y);
+  },
+});
+
+<ScrollShadow LinearGradientComponent={LinearGradient}>
+  <Animated.ScrollView onScroll={scrollHandler}>...</Animated.ScrollView>
+</ScrollShadow>;
+```
+
+## Example
+
+```tsx
+import { ScrollShadow, Surface } from 'heroui-native';
+import { LinearGradient } from 'expo-linear-gradient';
+import { FlatList, ScrollView, Text, View } from 'react-native';
+
+export default function ScrollShadowExample() {
+  const horizontalData = Array.from({ length: 10 }, (_, i) => ({
+    id: i,
+    title: `Card ${i + 1}`,
+  }));
+
+  return (
+    <View className="flex-1 bg-background">
+      <Text className="px-5 py-3 text-lg font-semibold">Horizontal List</Text>
+      <ScrollShadow LinearGradientComponent={LinearGradient}>
+        <FlatList
+          data={horizontalData}
+          horizontal
+          renderItem={({ item }) => (
+            <Surface variant="2" className="w-32 h-24 justify-center px-4">
+              <Text>{item.title}</Text>
+            </Surface>
+          )}
+          showsHorizontalScrollIndicator={false}
+          contentContainerClassName="p-5 gap-4"
+        />
+      </ScrollShadow>
+
+      <Text className="px-5 py-3 text-lg font-semibold">Vertical Content</Text>
+      <ScrollShadow
+        size={80}
+        className="h-48"
+        LinearGradientComponent={LinearGradient}
+      >
+        <ScrollView
+          contentContainerClassName="p-5"
+          showsVerticalScrollIndicator={false}
+        >
+          <Text className="mb-4 text-2xl font-bold">Long Content</Text>
+          <Text className="mb-4 text-base leading-6">
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+            eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
+            ad minim veniam, quis nostrud exercitation ullamco laboris.
+          </Text>
+          <Text className="mb-4 text-base leading-6">
+            Sed ut perspiciatis unde omnis iste natus error sit voluptatem
+            accusantium doloremque laudantium, totam rem aperiam, eaque ipsa
+            quae ab illo inventore veritatis et quasi architecto beatae vitae.
+          </Text>
+        </ScrollView>
+      </ScrollShadow>
+    </View>
+  );
+}
+```
+
+## API Reference
+
+### ScrollShadow
+
+| prop                      | type                                                                   | default      | description                                                                                                     |
+| ------------------------- | ---------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------- |
+| `children`                | `React.ReactElement`                                                   | -            | The scrollable component to enhance with shadows. Must be a single React element (ScrollView, FlatList, etc.)   |
+| `LinearGradientComponent` | `ComponentType<LinearGradientProps>`                                   | **required** | LinearGradient component from any compatible library (expo-linear-gradient, react-native-linear-gradient, etc.) |
+| `size`                    | `number`                                                               | `50`         | Size (height/width) of the gradient shadow in pixels                                                            |
+| `orientation`             | `'horizontal' \| 'vertical'`                                           | auto-detect  | Orientation of the scroll shadow. If not provided, will auto-detect from child's `horizontal` prop              |
+| `visibility`              | `'auto' \| 'top' \| 'bottom' \| 'left' \| 'right' \| 'both' \| 'none'` | `'auto'`     | Visibility mode for the shadows. 'auto' shows shadows based on scroll position and content overflow             |
+| `color`                   | `string`                                                               | theme color  | Custom color for the gradient shadow. If not provided, uses the theme's background color                        |
+| `isEnabled`               | `boolean`                                                              | `true`       | Whether the shadow effect is enabled                                                                            |
+| `animation`               | `ScrollShadowRootAnimation`                                            | -            | Animation configuration                                                                                         |
+| `className`               | `string`                                                               | -            | Additional CSS classes to apply to the container                                                                |
+| `...ViewProps`            | `ViewProps`                                                            | -            | All standard React Native View props are supported                                                              |
+
+#### ScrollShadowRootAnimation
+
+Animation configuration for ScrollShadow 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                             |
+| `opacity.value` | `[number, number]`                      | `[0, 1]` | Opacity values [initial, active]. For bottom/right shadow, this is reversed |
+
+### LinearGradientProps
+
+The `LinearGradientComponent` prop expects a component that accepts these props:
+
+| prop        | type                              | description                                                        |
+| ----------- | --------------------------------- | ------------------------------------------------------------------ |
+| `colors`    | `any`                             | Array of colors for the gradient                                   |
+| `locations` | `any` (optional)                  | Array of numbers defining the location of each gradient color stop |
+| `start`     | `any` (optional)                  | Start point of the gradient (e.g., `{ x: 0, y: 0 }`)               |
+| `end`       | `any` (optional)                  | End point of the gradient (e.g., `{ x: 1, y: 0 }`)                 |
+| `style`     | `StyleProp<ViewStyle>` (optional) | Style to apply to the gradient view                                |

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

@@ -0,0 +1,47 @@
+import { StyleSheet } from 'react-native';
+import { tv } from 'tailwind-variants';
+
+/**
+ * ScrollShadow component styles using tailwind-variants
+ */
+export const scrollShadowStyles = tv({
+  base: '',
+});
+
+/**
+ * Native styles for properties not supported by NativeWind
+ */
+export const nativeStyles = StyleSheet.create({
+  topShadow: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    zIndex: 10,
+    pointerEvents: 'none',
+  },
+  bottomShadow: {
+    position: 'absolute',
+    bottom: 0,
+    left: 0,
+    right: 0,
+    zIndex: 10,
+    pointerEvents: 'none',
+  },
+  leftShadow: {
+    position: 'absolute',
+    top: 0,
+    bottom: 0,
+    left: 0,
+    zIndex: 10,
+    pointerEvents: 'none',
+  },
+  rightShadow: {
+    position: 'absolute',
+    top: 0,
+    bottom: 0,
+    right: 0,
+    zIndex: 10,
+    pointerEvents: 'none',
+  },
+});

package/src/components/scroll-shadow/scroll-shadow.tsx

@@ -0,0 +1,246 @@
+import {
+  cloneElement,
+  createElement,
+  forwardRef,
+  isValidElement,
+  type ComponentType,
+} from 'react';
+import { StyleSheet, View, type LayoutChangeEvent } from 'react-native';
+import Animated, { useComposedEventHandler } from 'react-native-reanimated';
+import { colorKit, useThemeColor } from '../../helpers/theme';
+import { easeGradient } from '../../helpers/utils';
+import { useScrollShadowRootAnimation } from './scroll-shadow.animation';
+import {
+  DEFAULT_SCROLL_EVENT_THROTTLE,
+  DEFAULT_SHADOW_SIZE,
+  SCROLL_SHADOW_DISPLAY_NAME,
+} from './scroll-shadow.constants';
+import { nativeStyles, scrollShadowStyles } from './scroll-shadow.styles';
+import type { ScrollShadowProps } from './scroll-shadow.types';
+
+/**
+ * Cache for animated components to prevent remounting on every render.
+ * Using WeakMap ensures components are garbage collected when no longer referenced.
+ */
+const animatedComponentCache = new WeakMap<
+  ComponentType<any>,
+  ComponentType<any>
+>();
+
+/**
+ * Gets or creates a cached animated component for the given component type.
+ * This prevents creating new component types on every render, which would cause
+ * React to treat them as different components and trigger unmount/remount cycles.
+ *
+ * @param ComponentType - The original component type to create an animated version of
+ * @returns The cached animated component type
+ */
+function getAnimatedComponent(
+  ComponentType: ComponentType<any>
+): ComponentType<any> {
+  let cached = animatedComponentCache.get(ComponentType);
+  if (!cached) {
+    try {
+      cached = Animated.createAnimatedComponent(ComponentType);
+      animatedComponentCache.set(ComponentType, cached);
+    } catch (error) {
+      throw new Error(
+        `ScrollShadow: Failed to create animated component: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  return cached;
+}
+
+const ScrollShadowRoot = forwardRef<View, ScrollShadowProps>((props, ref) => {
+  const {
+    children,
+    size = DEFAULT_SHADOW_SIZE,
+    orientation: orientationProp,
+    visibility = 'auto',
+    color,
+    isEnabled = true,
+    className,
+    style,
+    LinearGradientComponent,
+    animation,
+    ...restProps
+  } = props;
+
+  const themeColorBackground = useThemeColor('background');
+  const shadowColor = color || themeColorBackground;
+
+  const containerStyles = scrollShadowStyles({ className });
+
+  const childHorizontal =
+    children?.props &&
+    typeof children?.props === 'object' &&
+    'horizontal' in children.props
+      ? children.props.horizontal
+      : false;
+  const orientation =
+    orientationProp || (childHorizontal ? 'horizontal' : 'vertical');
+
+  // Get all animation logic from root hook
+  const {
+    contentSize,
+    containerSize,
+    localScrollHandler,
+    topShadowStyle,
+    bottomShadowStyle,
+  } = useScrollShadowRootAnimation({
+    animation,
+    orientation,
+    size,
+    visibility,
+    isEnabled,
+  });
+
+  const onContentSizeChange = (w: number, h: number) => {
+    const contentDimension = orientation === 'vertical' ? h : w;
+    contentSize.set(contentDimension);
+    (children as any).props?.onContentSizeChange?.(w, h);
+  };
+
+  const onLayout = (event: LayoutChangeEvent) => {
+    const { width, height } = event.nativeEvent.layout;
+    const containerDimension = orientation === 'vertical' ? height : width;
+    containerSize.set(containerDimension);
+    (children as any).props?.onLayout?.(event);
+  };
+
+  const outerScrollHandler = (children as any).props?.onScroll;
+  const handlers = outerScrollHandler
+    ? [localScrollHandler, outerScrollHandler]
+    : [localScrollHandler];
+
+  const onScroll = useComposedEventHandler(handlers);
+
+  const scrollEventThrottle =
+    (children as any).props?.scrollEventThrottle ||
+    DEFAULT_SCROLL_EVENT_THROTTLE;
+
+  if (!isValidElement(children)) {
+    return null;
+  }
+
+  const isAnimatedComponent =
+    (children.type as any)?.displayName?.includes('AnimatedComponent') ||
+    (children.type as any)?.__isAnimatedComponent;
+
+  const enhancedChild = isAnimatedComponent
+    ? cloneElement(children as any, {
+        onContentSizeChange,
+        onLayout,
+        scrollEventThrottle,
+        onScroll,
+      })
+    : createElement(getAnimatedComponent(children.type as any), {
+        ...(children as any).props,
+        onContentSizeChange,
+        onLayout,
+        scrollEventThrottle,
+        onScroll,
+      });
+
+  const { colors: topLeftColors, locations: topLeftLocations } = easeGradient({
+    colorStops: {
+      0: {
+        color: colorKit.setAlpha(shadowColor, 1).hex(),
+      },
+      1: {
+        color: colorKit.setAlpha(shadowColor, 0).hex(),
+      },
+    },
+  });
+
+  const { colors: bottomRightColors, locations: bottomRightLocations } =
+    easeGradient({
+      colorStops: {
+        0: {
+          color: colorKit.setAlpha(shadowColor, 0).hex(),
+        },
+        1: {
+          color: colorKit.setAlpha(shadowColor, 1).hex(),
+        },
+      },
+    });
+
+  return (
+    <View ref={ref} className={containerStyles} style={style} {...restProps}>
+      {enhancedChild}
+
+      {/* Top/Left Shadow */}
+      {orientation === 'vertical' ? (
+        <Animated.View
+          style={[nativeStyles.topShadow, { height: size }, topShadowStyle]}
+        >
+          <LinearGradientComponent
+            colors={topLeftColors}
+            locations={topLeftLocations}
+            style={StyleSheet.absoluteFill}
+          />
+        </Animated.View>
+      ) : (
+        <Animated.View
+          style={[nativeStyles.leftShadow, { width: size }, topShadowStyle]}
+        >
+          <LinearGradientComponent
+            colors={topLeftColors}
+            locations={topLeftLocations}
+            start={{ x: 0, y: 0 }}
+            end={{ x: 1, y: 0 }}
+            style={StyleSheet.absoluteFill}
+          />
+        </Animated.View>
+      )}
+
+      {/* Bottom/Right Shadow */}
+      {orientation === 'vertical' ? (
+        <Animated.View
+          style={[
+            nativeStyles.bottomShadow,
+            { height: size },
+            bottomShadowStyle,
+          ]}
+        >
+          <LinearGradientComponent
+            colors={bottomRightColors}
+            locations={bottomRightLocations}
+            style={StyleSheet.absoluteFill}
+          />
+        </Animated.View>
+      ) : (
+        <Animated.View
+          style={[nativeStyles.rightShadow, { width: size }, bottomShadowStyle]}
+        >
+          <LinearGradientComponent
+            colors={bottomRightColors}
+            locations={bottomRightLocations}
+            start={{ x: 0, y: 0 }}
+            end={{ x: 1, y: 0 }}
+            style={StyleSheet.absoluteFill}
+          />
+        </Animated.View>
+      )}
+    </View>
+  );
+});
+
+ScrollShadowRoot.displayName = SCROLL_SHADOW_DISPLAY_NAME.ROOT;
+
+/**
+ * Compound ScrollShadow component
+ *
+ * @component ScrollShadow - Main container that wraps any scrollable component and adds
+ * dynamic gradient shadows at the edges. Automatically detects scroll position and content
+ * overflow to show/hide shadows intelligently.
+ *
+ * The component intercepts scroll events from the child scrollable component and manages
+ * shadow visibility based on scroll position and content size. Supports both vertical
+ * and horizontal orientations.
+ *
+ * @see Full documentation: https://heroui.com/components/scroll-shadow
+ */
+
+export default ScrollShadowRoot;

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

@@ -0,0 +1,121 @@
+import type { ComponentType } from 'react';
+import type { ViewProps } from 'react-native';
+import type {
+  AnimationRoot,
+  AnimationValue,
+} from '../../helpers/types/animation';
+
+/**
+ * Orientation of the scroll shadow
+ * @default 'vertical'
+ */
+export type ScrollShadowOrientation = 'horizontal' | 'vertical';
+
+/**
+ * Visibility mode for the scroll shadows
+ * - 'auto': Shows shadows based on scroll position and content overflow
+ * - 'top': Only shows top shadow (for vertical) or left shadow (for horizontal)
+ * - 'bottom': Only shows bottom shadow (for vertical) or right shadow (for horizontal)
+ * - 'left': Only shows left shadow (for horizontal orientation)
+ * - 'right': Only shows right shadow (for horizontal orientation)
+ * - 'both': Always shows both shadows
+ * - 'none': Hides all shadows
+ * @default 'auto'
+ */
+export type ScrollShadowVisibility =
+  | 'auto'
+  | 'top'
+  | 'bottom'
+  | 'left'
+  | 'right'
+  | 'both'
+  | 'none';
+
+export interface LinearGradientProps {
+  colors: any;
+  locations?: any;
+  start?: any;
+  end?: any;
+  style?: any;
+}
+
+export type LinearGradientComponent = ComponentType<LinearGradientProps>;
+
+/**
+ * Animation configuration for ScrollShadow root component
+ */
+export type ScrollShadowRootAnimation = AnimationRoot<{
+  /**
+   * Opacity animation configuration
+   */
+  opacity?: AnimationValue<{
+    /**
+     * Opacity values [initial, active]
+     * - First value (0): Initial opacity when shadow is not visible
+     * - Second value (1): Active opacity when shadow is visible
+     * For bottom/right shadow, this array is reversed: [1, 0]
+     * @default [0, 1]
+     */
+    value?: [number, number];
+  }>;
+}>;
+
+/**
+ * Props for the ScrollShadow component
+ */
+export interface ScrollShadowProps extends ViewProps {
+  /**
+   * The scrollable component to enhance with shadows
+   * Must be a single React element (ScrollView, FlatList, etc.)
+   */
+  children: React.ReactElement;
+
+  /**
+   * Size (height/width) of the gradient shadow in pixels
+   * @default 50
+   */
+  size?: number;
+
+  /**
+   * Orientation of the scroll shadow
+   * If not provided, will auto-detect from child's `horizontal` prop
+   * @default 'vertical' or auto-detected from child
+   */
+  orientation?: ScrollShadowOrientation;
+
+  /**
+   * Visibility mode for the shadows
+   * @default 'auto'
+   */
+  visibility?: ScrollShadowVisibility;
+
+  /**
+   * Custom color for the gradient shadow
+   * If not provided, uses the theme's background color
+   */
+  color?: string;
+
+  /**
+   * Whether the shadow effect is enabled
+   * @default true
+   */
+  isEnabled?: boolean;
+
+  /**
+   * Additional CSS classes to apply to the container
+   */
+  className?: string;
+
+  /**
+   * LinearGradient component to use for rendering shadows
+   * Compatible with expo-linear-gradient, react-native-linear-gradient, etc.
+   * Required for the component to render shadows
+   */
+  LinearGradientComponent: LinearGradientComponent;
+
+  /**
+   * Animation configuration for scroll shadow
+   * @default undefined
+   */
+  animation?: ScrollShadowRootAnimation;
+}

package/src/components/select/index.ts

@@ -0,0 +1,25 @@
+export {
+  default as Select,
+  useSelect,
+  useSelectAnimation,
+  useSelectItem,
+} from './select';
+export type {
+  SelectAlign,
+  SelectCloseIconProps,
+  SelectCloseProps,
+  SelectContentProps,
+  SelectItemDescriptionProps,
+  SelectItemIndicatorIconProps,
+  SelectItemIndicatorProps,
+  SelectItemLabelProps,
+  SelectItemProps,
+  SelectListLabelProps,
+  SelectOverlayProps,
+  SelectPlacement,
+  SelectPortalProps,
+  SelectRootProps,
+  SelectTriggerProps,
+  SelectTriggerRef,
+  SelectValueProps,
+} from './select.types';

package/src/components/select/select.animation.ts

@@ -0,0 +1,9 @@
+import { createContext } from '../../helpers/utils';
+import type { SelectAnimationContextValue } from './select.types';
+
+const [SelectAnimationProvider, useSelectAnimation] =
+  createContext<SelectAnimationContextValue>({
+    name: 'SelectAnimationContext',
+  });
+
+export { SelectAnimationProvider, useSelectAnimation };

package/src/components/select/select.constants.ts

@@ -0,0 +1,37 @@
+/**
+ * Display names for the Select components
+ */
+export const DISPLAY_NAME = {
+  ROOT: 'HeroUINative.Select.Root',
+  TRIGGER: 'HeroUINative.Select.Trigger',
+  VALUE: 'HeroUINative.Select.Value',
+  PORTAL: 'HeroUINative.Select.Portal',
+  OVERLAY: 'HeroUINative.Select.Overlay',
+  CONTENT: 'HeroUINative.Select.Content',
+  ITEM: 'HeroUINative.Select.Item',
+  ITEM_LABEL: 'HeroUINative.Select.ItemLabel',
+  ITEM_DESCRIPTION: 'HeroUINative.Select.ItemDescription',
+  ITEM_INDICATOR: 'HeroUINative.Select.ItemIndicator',
+  LIST_LABEL: 'HeroUINative.Select.ListLabel',
+  CLOSE: 'HeroUINative.Select.Close',
+};
+
+/**
+ * Default offset from trigger element
+ */
+export const DEFAULT_OFFSET = 8;
+
+/**
+ * Default alignment offset
+ */
+export const DEFAULT_ALIGN_OFFSET = 0;
+
+/**
+ * Default screen edge insets
+ */
+export const DEFAULT_INSETS = {
+  top: 12,
+  bottom: 12,
+  left: 12,
+  right: 12,
+};