@erquhart/heroui-native 1.0.0-beta.10.1

package/src/helpers/types/primitives.ts

@@ -0,0 +1,146 @@
+import type { Pressable, Text, View, ViewStyle } from 'react-native';
+
+// Base utility types
+
+/**
+ * Component props with optional asChild prop for polymorphic components
+ * Allows components to render as different elements when asChild is true
+ */
+type ComponentPropsWithAsChild<T extends React.ElementType<any>> =
+  React.ComponentPropsWithoutRef<T> & { asChild?: boolean };
+
+// Ref types
+
+/**
+ * Reference type for React Native View component
+ * Used for forwarding refs to View elements
+ */
+type ViewRef = React.ComponentRef<typeof View>;
+
+/**
+ * Reference type for React Native Pressable component
+ * Used for forwarding refs to Pressable elements
+ */
+type PressableRef = React.ComponentRef<typeof Pressable>;
+
+/**
+ * Reference type for React Native Text component
+ * Used for forwarding refs to Text elements
+ */
+type TextRef = React.ComponentRef<typeof Text>;
+
+// Slottable component props
+
+/**
+ * View component props with asChild support for slot composition
+ * Enables View components to be used with the Slot pattern
+ */
+type SlottableViewProps = ComponentPropsWithAsChild<typeof View>;
+
+/**
+ * Pressable component props with asChild support for slot composition
+ * Enables Pressable components to be used with the Slot pattern
+ */
+type SlottablePressableProps = ComponentPropsWithAsChild<typeof Pressable>;
+
+/**
+ * Text component props with asChild support for slot composition
+ * Enables Text components to be used with the Slot pattern
+ */
+type SlottableTextProps = ComponentPropsWithAsChild<typeof Text>;
+
+/**
+ * Interface for components that can be force mounted even when normally hidden
+ */
+interface ForceMountable {
+  /**
+   * Whether to force mount the component in the DOM
+   * Useful for animation purposes when component needs to be present but hidden
+   */
+  forceMount?: true | undefined;
+}
+
+/**
+ * Interface for defining spacing/padding from screen edges
+ */
+interface Insets {
+  /**
+   * Distance from the top edge in pixels
+   */
+  top?: number;
+  /**
+   * Distance from the bottom edge in pixels
+   */
+  bottom?: number;
+  /**
+   * Distance from the left edge in pixels
+   */
+  left?: number;
+  /**
+   * Distance from the right edge in pixels
+   */
+  right?: number;
+}
+
+/**
+ * Props for components that need to be positioned relative to a trigger element
+ * Certain props are only available on the native version of the component.
+ * @docs For the web version, see the Radix documentation https://www.radix-ui.com/primitives
+ */
+interface PositionedContentProps {
+  /**
+   * Whether to force mount the component in the DOM
+   */
+  forceMount?: true | undefined;
+  /**
+   * Custom styles to apply to the positioned content
+   */
+  style?: ViewStyle;
+  /**
+   * Offset along the alignment axis in pixels
+   */
+  alignOffset?: number;
+  /**
+   * Screen edge insets to respect when positioning
+   */
+  insets?: Insets;
+  /**
+   * Whether to automatically adjust position to avoid screen edges
+   * @default true
+   */
+  avoidCollisions?: boolean;
+  /**
+   * Alignment relative to the trigger element
+   * @default 'start'
+   */
+  align?: 'start' | 'center' | 'end';
+  /**
+   * Preferred placement of the trigger element to position against
+   * @default 'bottom'
+   */
+  placement?: 'top' | 'bottom' | 'left' | 'right';
+  /**
+   * Offset from the trigger element in pixels
+   * @default 0
+   */
+  offset?: number;
+  /**
+   * Whether to disable the automatic positioning styles
+   * Useful when you want to handle positioning manually
+   * @default false
+   */
+  disablePositioningStyle?: boolean;
+}
+
+export type {
+  ComponentPropsWithAsChild,
+  ForceMountable,
+  Insets,
+  PositionedContentProps,
+  PressableRef,
+  SlottablePressableProps,
+  SlottableTextProps,
+  SlottableViewProps,
+  TextRef,
+  ViewRef,
+};

package/src/helpers/utils/animation.ts

@@ -0,0 +1,266 @@
+import type {
+  Animation,
+  AnimationRoot,
+  AnimationValue,
+} from '../types/animation';
+
+/**
+ * Check if the entire animation is disabled
+ * @param animation - Animation configuration
+ * @returns true if animation is disabled
+ */
+export function isAnimationDisabled<TConfig extends Record<string, any>>(
+  animation: Animation<TConfig> | AnimationRoot<TConfig> | undefined
+): boolean {
+  // Check top-level disabled values
+  if (animation === false || animation === 'disabled') {
+    return true;
+  }
+
+  // Check state property in config objects
+  if (
+    typeof animation === 'object' &&
+    animation !== null &&
+    'state' in animation
+  ) {
+    const state = animation.state;
+    return state === false || state === 'disabled';
+  }
+
+  return false;
+}
+
+/**
+ * Check if root animation should cascade disable to all children
+ * @param animation - Root animation configuration
+ * @returns true if all animations should be disabled (including children)
+ */
+export function shouldDisableAll<TConfig extends Record<string, any>>(
+  animation: AnimationRoot<TConfig> | undefined
+): boolean {
+  // Check top-level disable-all value
+  if (animation === 'disable-all') {
+    return true;
+  }
+
+  // Check state property in config objects
+  if (
+    typeof animation === 'object' &&
+    animation !== null &&
+    'state' in animation
+  ) {
+    const state = animation.state;
+    return state === 'disable-all';
+  }
+
+  return false;
+}
+
+/**
+ * Get animation state including config and disabled status
+ * @param animation - Animation configuration
+ * @returns Object with animationConfig and isAnimationDisabled
+ */
+export function getAnimationState<TConfig extends Record<string, any>>(
+  animation: Animation<TConfig> | undefined
+): {
+  animationConfig: TConfig | undefined;
+  isAnimationDisabled: boolean;
+} {
+  const isDisabled = isAnimationDisabled(animation);
+  // Always extract config when it's an object, regardless of disabled state
+  // This allows users to customize colors/properties even when animations are disabled
+  const config =
+    typeof animation === 'object' && animation !== null
+      ? (animation as TConfig)
+      : undefined;
+
+  return {
+    animationConfig: config,
+    isAnimationDisabled: isDisabled,
+  };
+}
+
+/**
+ * Get root animation state including config, disabled status, and cascade flag
+ * @param animation - Root animation configuration
+ * @returns Object with animationConfig, isAnimationDisabled, and isAllAnimationsDisabled
+ */
+export function getRootAnimationState<TConfig extends Record<string, any>>(
+  animation: AnimationRoot<TConfig> | undefined
+): {
+  animationConfig: TConfig | undefined;
+  isAnimationDisabled: boolean;
+  isAllAnimationsDisabled: boolean;
+} {
+  const shouldCascade = shouldDisableAll(animation);
+  const isDisabled = isAnimationDisabled(animation) || shouldCascade;
+  // Always extract config when it's an object, regardless of disabled state
+  // This allows users to customize colors/properties even when animations are disabled
+  const config =
+    typeof animation === 'object' && animation !== null
+      ? (animation as TConfig)
+      : undefined;
+
+  return {
+    animationConfig: config,
+    isAnimationDisabled: isDisabled,
+    isAllAnimationsDisabled: shouldCascade,
+  };
+}
+
+/**
+ * Get animation value property or return default
+ * Extracts a property from the animation value config object
+ *
+ * @param options - Object containing animationValue, property, and defaultValue
+ * @param options.animationValue - The animation value configuration
+ * @param options.property - Property name to extract
+ * @param options.defaultValue - Default value if property is not found
+ * @returns The property value or default (never undefined)
+ *
+ * @example
+ * const scaleValue = getAnimationValueProperty({
+ *   animationValue: animation?.scale,
+ *   property: 'value',
+ *   defaultValue: 0.95
+ * });
+ */
+export function getAnimationValueProperty<
+  TConfig extends Record<string, any>,
+  K extends keyof TConfig,
+  D extends NonNullable<TConfig[K]>,
+>(options: {
+  animationValue: AnimationValue<TConfig> | undefined;
+  property: K;
+  defaultValue: D;
+}): NonNullable<TConfig[K]> {
+  // If animation value is undefined, return default
+  if (options.animationValue === undefined) {
+    return options.defaultValue;
+  }
+
+  // Return the property value if it exists, otherwise return default
+  return (options.animationValue[options.property] ??
+    options.defaultValue) as NonNullable<TConfig[K]>;
+}
+
+/**
+ * Get animation value merged config or return default
+ * Merges the animation value config with defaults, useful when you need multiple properties
+ *
+ * @param options - Object containing animationValue, property, and defaultValue
+ * @param options.animationValue - The animation value configuration
+ * @param options.property - Property name to extract from the config
+ * @param options.defaultValue - Default configuration object
+ * @returns The merged config object or default
+ *
+ * @example
+ * const scaleConfig = getAnimationValueMergedConfig({
+ *   animationValue: animation?.scale,
+ *   property: 'timingConfig',
+ *   defaultValue: { duration: 150 }
+ * });
+ */
+export function getAnimationValueMergedConfig<
+  TConfig extends Record<string, any>,
+  K extends keyof TConfig,
+>(options: {
+  animationValue: AnimationValue<TConfig> | undefined;
+  property: K;
+  defaultValue: TConfig[K];
+}): TConfig[K] {
+  // If animation value is undefined, return default
+  if (options.animationValue === undefined) {
+    return options.defaultValue;
+  }
+
+  const value = options.animationValue[options.property];
+
+  // If the specific property value is undefined or not an object, return default
+  if (value === undefined || typeof value !== 'object') {
+    return options.defaultValue;
+  }
+
+  // Merge with defaults to ensure all properties exist
+  return { ...options.defaultValue, ...value };
+}
+
+/**
+ * Determine if animations should be disabled based on disabled flags
+ * Priority: isAllAnimationsDisabled > isAnimationDisabled
+ *
+ * @param options - Object containing isAnimationDisabled and isAllAnimationsDisabled
+ * @param options.isAnimationDisabled - Whether animation is explicitly disabled
+ * @param options.isAllAnimationsDisabled - Whether all animations should be disabled (cascading from root/global)
+ * @returns true if animations should be disabled, false otherwise
+ *
+ * @example
+ * const isDisabled = getIsAnimationDisabledValue({
+ *   isAnimationDisabled: false,
+ *   isAllAnimationsDisabled: true
+ * });
+ * // Returns: true (all animations disabled takes priority)
+ */
+export function getIsAnimationDisabledValue(options: {
+  isAnimationDisabled: boolean;
+  isAllAnimationsDisabled: boolean | undefined;
+}): boolean {
+  const { isAnimationDisabled: isDisabled, isAllAnimationsDisabled } = options;
+
+  // First priority: if all animations are disabled, return true
+  if (isAllAnimationsDisabled === true) {
+    return true;
+  }
+
+  // Second priority: if this animation is disabled, return true
+  if (isDisabled) {
+    return true;
+  }
+
+  // Default: animations are enabled
+  return false;
+}
+
+/**
+ * Combine global, parent, and own animation disabled states
+ * Priority: Global > Parent > Own (global wins if enabled)
+ *
+ * @param options - Object containing globalIsAllAnimationsDisabled, parentIsAllAnimationsDisabled, and ownIsAllAnimationsDisabled
+ * @param options.globalIsAllAnimationsDisabled - Whether global provider has disable-all (from GlobalAnimationSettingsProvider)
+ * @param options.parentIsAllAnimationsDisabled - Whether parent context has disable-all (from AnimationSettingsContext)
+ * @param options.ownIsAllAnimationsDisabled - Whether own animation prop has disable-all
+ * @returns Combined isAllAnimationsDisabled value (global || parent || own)
+ *
+ * @example
+ * const combined = getCombinedAnimationDisabledState({
+ *   globalIsAllAnimationsDisabled: true,
+ *   parentIsAllAnimationsDisabled: false,
+ *   ownIsAllAnimationsDisabled: false
+ * });
+ * // Returns: true (global wins)
+ */
+export function getCombinedAnimationDisabledState(options: {
+  globalIsAllAnimationsDisabled?: boolean;
+  parentIsAllAnimationsDisabled: boolean | undefined;
+  ownIsAllAnimationsDisabled: boolean;
+}): boolean {
+  const {
+    globalIsAllAnimationsDisabled,
+    parentIsAllAnimationsDisabled,
+    ownIsAllAnimationsDisabled,
+  } = options;
+
+  // Global always wins if it has disable-all
+  if (globalIsAllAnimationsDisabled === true) {
+    return true;
+  }
+
+  // Parent wins if it has disable-all
+  if (parentIsAllAnimationsDisabled === true) {
+    return true;
+  }
+
+  // Otherwise use own value
+  return ownIsAllAnimationsDisabled;
+}

package/src/helpers/utils/children-to-string.ts

@@ -0,0 +1,78 @@
+import { Children, isValidElement, type ReactNode } from 'react';
+import type { SharedValue } from 'react-native-reanimated';
+
+/**
+ * Converts React children to a string representation.
+ * Handles cases where children might be an array of mixed types (strings, numbers, variables).
+ *
+ * @param children - React children that might be string, number, array, or React elements
+ * @returns A string representation of the children or null if not convertible
+ */
+export function childrenToString(
+  children: ReactNode | SharedValue<ReactNode>
+): string | null {
+  // Handle null/undefined
+  if (children == null) {
+    return null;
+  }
+
+  // Handle string directly
+  if (typeof children === 'string') {
+    return children;
+  }
+
+  // Handle number
+  if (typeof children === 'number') {
+    return String(children);
+  }
+
+  // Handle boolean (usually we don't want to render true/false as text)
+  if (typeof children === 'boolean') {
+    return null;
+  }
+
+  // Handle array of children (e.g., {someVar} text)
+  if (Array.isArray(children)) {
+    const stringified = children
+      .map((child) => {
+        // Recursively handle each child
+        if (typeof child === 'string' || typeof child === 'number') {
+          return String(child);
+        }
+        // Skip React elements, booleans, null, undefined
+        if (
+          isValidElement(child) ||
+          child == null ||
+          typeof child === 'boolean'
+        ) {
+          return '';
+        }
+        return String(child);
+      })
+      .join('');
+
+    return stringified || null;
+  }
+
+  // Handle React fragments and other iterable children
+  try {
+    const childArray = Children.toArray(children as ReactNode);
+    if (childArray.length > 0) {
+      return childrenToString(childArray);
+    }
+  } catch {
+    // Not iterable or other error, return null
+  }
+
+  return null;
+}
+
+/**
+ * Checks if React children can be converted to a string.
+ *
+ * @param children - React children to check
+ * @returns True if children can be converted to string, false otherwise
+ */
+export function isStringifiableChildren(children: ReactNode): boolean {
+  return childrenToString(children) !== null;
+}

package/src/helpers/utils/create-context.ts

@@ -0,0 +1,60 @@
+import * as React from 'react';
+
+export interface CreateContextOptions {
+  /**
+   * If `true`, React will throw if context is `null` or `undefined`
+   * In some cases, you might want to support nested context, so you can set it to `false`
+   */
+  strict?: boolean;
+  /**
+   * Error message to throw if the context is `undefined`
+   */
+  errorMessage?: string;
+  /**
+   * The display name of the context
+   */
+  name?: string;
+}
+
+export type CreateContextReturn<T> = [
+  React.Provider<T>,
+  () => T,
+  React.Context<T>,
+];
+
+/**
+ * Creates a named context, provider, and hook.
+ *
+ * @param options create context options
+ */
+export function createContext<ContextType>(options: CreateContextOptions = {}) {
+  const {
+    strict = true,
+    errorMessage = 'useContext: `context` is undefined. Seems you forgot to wrap component within the Provider',
+    name,
+  } = options;
+
+  const Context = React.createContext<ContextType | undefined>(undefined);
+
+  Context.displayName = name;
+
+  function useContext() {
+    const context = React.useContext(Context);
+
+    if (!context && strict) {
+      const error = new Error(errorMessage);
+
+      error.name = 'ContextError';
+      Error.captureStackTrace?.(error, useContext);
+      throw error;
+    }
+
+    return context;
+  }
+
+  return [
+    Context.Provider,
+    useContext,
+    Context,
+  ] as CreateContextReturn<ContextType>;
+}

package/src/helpers/utils/ease-gradient/create-interpolation.ts

@@ -0,0 +1,35 @@
+/**
+ * Easing gradient utilities for React Native
+ *
+ * Original source: https://github.com/phamfoo/react-native-easing-gradient
+ * Author: @phamfoo
+ * License: MIT
+ *
+ * This code has been adapted for use in HeroUI Native with modifications
+ * for TypeScript compatibility and integration with the animation system.
+ */
+
+import { Animated } from 'react-native';
+// @ts-expect-error
+const AnimatedInterpolation = Animated.Interpolation;
+
+type ColorInterpolateFunction = (input: number) => string;
+
+function createInterpolation(
+  config: Animated.InterpolationConfigType
+): ColorInterpolateFunction {
+  if (AnimatedInterpolation.__createInterpolation) {
+    return AnimatedInterpolation.__createInterpolation(config);
+  }
+
+  return (input) => {
+    const interpolation = new AnimatedInterpolation(
+      { __getValue: () => input },
+      config
+    );
+
+    return interpolation.__getValue();
+  };
+}
+
+export { createInterpolation };

package/src/helpers/utils/ease-gradient/index.ts

@@ -0,0 +1,97 @@
+/**
+ * Easing gradient utilities for React Native
+ *
+ * Original source: https://github.com/phamfoo/react-native-easing-gradient
+ * Author: @phamfoo
+ * License: MIT
+ *
+ * This code has been adapted for use in HeroUI Native with modifications
+ * for TypeScript compatibility and integration with the animation system.
+ */
+
+import { Easing, type EasingFunction } from 'react-native';
+import { createInterpolation } from './create-interpolation';
+
+interface ColorStops {
+  [location: number]: {
+    color: string;
+    easing?: EasingFunction;
+  };
+}
+
+interface GradientParams {
+  colorStops: ColorStops;
+  extraColorStopsPerTransition?: number;
+  easing?: EasingFunction;
+}
+
+const easeInOut = Easing.bezier(0.42, 0, 0.58, 1);
+
+function easeGradient({
+  colorStops,
+  easing = easeInOut,
+  extraColorStopsPerTransition = 12,
+}: GradientParams): {
+  colors: [string, string, ...string[]];
+  locations: [number, number, ...number[]];
+} {
+  const colors: string[] = [];
+  const locations: number[] = [];
+
+  const initialLocations = Object.keys(colorStops)
+    .map((key) => Number(key))
+    .sort();
+
+  const totalColorStops = initialLocations.length;
+
+  for (
+    let currentStopIndex = 0;
+    currentStopIndex < totalColorStops - 1;
+    currentStopIndex++
+  ) {
+    const startLocation = initialLocations[currentStopIndex];
+    const endLocation = initialLocations[currentStopIndex + 1];
+
+    if (startLocation === undefined || endLocation === undefined) {
+      continue;
+    }
+
+    const startStop = colorStops[startLocation];
+    const endStop = colorStops[endLocation];
+
+    if (!startStop || !endStop) {
+      continue;
+    }
+
+    const startColor = startStop.color;
+    const endColor = endStop.color;
+    const currentEasing = startStop.easing ?? easing;
+
+    const colorScale = createInterpolation({
+      inputRange: [0, 1],
+      outputRange: [startColor, endColor],
+      easing: currentEasing,
+    });
+
+    const currentTransitionLength = endLocation - startLocation;
+    const stepSize = 1 / (extraColorStopsPerTransition + 1);
+
+    for (
+      let stepIndex = 0;
+      stepIndex <= extraColorStopsPerTransition + 1;
+      stepIndex++
+    ) {
+      const progress = stepIndex * stepSize;
+      const color = colorScale(progress);
+      colors.push(color);
+      locations.push(startLocation + currentTransitionLength * progress);
+    }
+  }
+
+  return {
+    colors: colors as [string, string, ...string[]],
+    locations: locations as [number, number, ...number[]],
+  };
+}
+
+export { easeGradient };

package/src/helpers/utils/get-element-by-display-name.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+import type { ReactChild } from '../types';
+
+export const getElementByDisplayName = (
+  children: React.ReactNode,
+  displayName: string
+): ReactChild | undefined => {
+  const element = React.Children.toArray(children).find(
+    (child) =>
+      React.isValidElement(child) &&
+      (child.type as any)?.displayName === displayName
+  );
+
+  return element;
+};