@erquhart/heroui-native 1.0.0-beta.10.1

package/src/components/text-field/text-field.tsx

@@ -0,0 +1,375 @@
+import { forwardRef, useMemo } from 'react';
+import {
+  TextInput,
+  View,
+  type BlurEvent,
+  type FocusEvent,
+  type TextInput as TextInputType,
+} from 'react-native';
+import Animated from 'react-native-reanimated';
+import { HeroText } from '../../helpers/components';
+import { AnimationSettingsProvider } from '../../helpers/contexts/animation-settings-context';
+import { useThemeColor } from '../../helpers/theme';
+import type { TextRef, ViewRef } from '../../helpers/types/primitives';
+import { createContext, getElementByDisplayName } from '../../helpers/utils';
+import { ErrorView } from '../error-view';
+import {
+  useTextFieldDescriptionAnimation,
+  useTextFieldInputAnimation,
+  useTextFieldLabelAnimation,
+  useTextFieldRootAnimation,
+} from './text-field.animation';
+import { DISPLAY_NAME } from './text-field.constants';
+import textFieldStyles, { styleSheet } from './text-field.styles';
+import type {
+  TextFieldContextValue,
+  TextFieldDescriptionProps,
+  TextFieldErrorMessageProps,
+  TextFieldInputEndContentProps,
+  TextFieldInputProps,
+  TextFieldInputStartContentProps,
+  TextFieldLabelProps,
+  TextFieldRootProps,
+} from './text-field.types';
+
+const [TextFieldProvider, useTextField] = createContext<TextFieldContextValue>({
+  name: 'TextFieldContext',
+});
+
+const AnimatedText = Animated.createAnimatedComponent(HeroText);
+
+// --------------------------------------------------
+
+const TextFieldRoot = forwardRef<ViewRef, TextFieldRootProps>((props, ref) => {
+  const {
+    children,
+    className,
+    isDisabled = false,
+    isInvalid = false,
+    isRequired = false,
+    animation,
+    ...restProps
+  } = props;
+
+  const tvStyles = textFieldStyles.root({ isDisabled, className });
+
+  const { isAllAnimationsDisabled } = useTextFieldRootAnimation({ animation });
+
+  const contextValue = useMemo(
+    () => ({ isDisabled, isInvalid, isRequired }),
+    [isDisabled, isInvalid, isRequired]
+  );
+
+  const animationSettingsContextValue = useMemo(
+    () => ({
+      isAllAnimationsDisabled,
+    }),
+    [isAllAnimationsDisabled]
+  );
+
+  return (
+    <AnimationSettingsProvider value={animationSettingsContextValue}>
+      <TextFieldProvider value={contextValue}>
+        <View ref={ref} className={tvStyles} {...restProps}>
+          {children}
+        </View>
+      </TextFieldProvider>
+    </AnimationSettingsProvider>
+  );
+});
+
+// --------------------------------------------------
+
+const TextFieldLabel = forwardRef<TextRef, TextFieldLabelProps>(
+  (props, ref) => {
+    const {
+      children,
+      className,
+      classNames,
+      isInvalid: localIsInvalid,
+      animation,
+      ...restProps
+    } = props;
+
+    const {
+      isDisabled,
+      isInvalid: contextIsInvalid,
+      isRequired,
+    } = useTextField();
+
+    const isInvalid =
+      localIsInvalid !== undefined ? localIsInvalid : contextIsInvalid;
+
+    const tvStyles = textFieldStyles.label({ isDisabled, isInvalid });
+
+    const textStyles = tvStyles.text({
+      className: [className, classNames?.text],
+    });
+
+    const asteriskStyles = tvStyles.asterisk({
+      className: classNames?.asterisk,
+    });
+
+    const { entering, exiting } = useTextFieldLabelAnimation({ animation });
+
+    return (
+      <AnimatedText
+        key={isInvalid ? 'label-invalid' : 'label-valid'}
+        ref={ref}
+        entering={entering}
+        exiting={exiting}
+        className={textStyles}
+        {...restProps}
+      >
+        {children}
+        {isRequired && <HeroText className={asteriskStyles}> *</HeroText>}
+      </AnimatedText>
+    );
+  }
+);
+
+// --------------------------------------------------
+
+const TextFieldInput = forwardRef<TextInputType, TextFieldInputProps>(
+  (props, ref) => {
+    const {
+      children,
+      isInvalid: localIsInvalid,
+      className,
+      classNames,
+      style,
+      styles,
+      animation,
+      isAnimatedStyleActive = true,
+      onFocus,
+      onBlur,
+      ...restProps
+    } = props;
+
+    const { isInvalid: contextIsInvalid } = useTextField();
+
+    const isInvalid =
+      localIsInvalid !== undefined ? localIsInvalid : contextIsInvalid;
+
+    const startContent = getElementByDisplayName(
+      children,
+      DISPLAY_NAME.INPUT_START_CONTENT
+    );
+    const endContent = getElementByDisplayName(
+      children,
+      DISPLAY_NAME.INPUT_END_CONTENT
+    );
+
+    const [themeColorFieldPlaceholder, themeColorMuted] = useThemeColor([
+      'field-placeholder',
+      'muted',
+    ]);
+
+    const tvStyles = textFieldStyles.input({
+      isMultiline: Boolean(restProps.multiline),
+    });
+
+    const containerClassName = tvStyles.container({
+      className: [className, classNames?.container],
+    });
+
+    const inputStyles = tvStyles.input({ className: classNames?.input });
+
+    const {
+      animatedContainerStyle,
+      handleFocusAnimation,
+      handleBlurAnimation,
+    } = useTextFieldInputAnimation({
+      animation,
+      isInvalid,
+    });
+
+    const containerStyle = isAnimatedStyleActive
+      ? [animatedContainerStyle, styleSheet.borderCurve, style]
+      : [styleSheet.borderCurve, style];
+
+    const handleFocus = (e: FocusEvent) => {
+      handleFocusAnimation();
+      onFocus?.(e);
+    };
+
+    const handleBlur = (e: BlurEvent) => {
+      handleBlurAnimation();
+      onBlur?.(e);
+    };
+
+    return (
+      <Animated.View className={containerClassName} style={containerStyle}>
+        {startContent}
+        <TextInput
+          ref={ref}
+          className={inputStyles}
+          style={[styleSheet.borderCurve, styles?.input]}
+          placeholderTextColor={themeColorFieldPlaceholder}
+          selectionColor={themeColorMuted}
+          selectionHandleColor={themeColorMuted}
+          onFocus={handleFocus}
+          onBlur={handleBlur}
+          textAlignVertical={restProps.multiline ? 'top' : 'center'}
+          {...restProps}
+        />
+        {endContent}
+      </Animated.View>
+    );
+  }
+);
+
+// --------------------------------------------------
+
+const TextFieldInputStartContent = forwardRef<
+  ViewRef,
+  TextFieldInputStartContentProps
+>((props, ref) => {
+  const { children, className, ...restProps } = props;
+
+  const tvStyles = textFieldStyles.inputStartContent({ className });
+
+  return (
+    <View ref={ref} className={tvStyles} {...restProps}>
+      {children}
+    </View>
+  );
+});
+
+// --------------------------------------------------
+
+const TextFieldInputEndContent = forwardRef<
+  ViewRef,
+  TextFieldInputEndContentProps
+>((props, ref) => {
+  const { children, className, ...restProps } = props;
+
+  const tvStyles = textFieldStyles.inputEndContent({ className });
+
+  return (
+    <View ref={ref} className={tvStyles} {...restProps}>
+      {children}
+    </View>
+  );
+});
+
+// --------------------------------------------------
+
+const TextFieldDescription = forwardRef<TextRef, TextFieldDescriptionProps>(
+  (props, ref) => {
+    const {
+      isInvalid: localIsInvalid,
+      children,
+      className,
+      animation,
+      ...restProps
+    } = props;
+
+    const { isInvalid: contextIsInvalid } = useTextField();
+
+    const isInvalid =
+      localIsInvalid !== undefined ? localIsInvalid : contextIsInvalid;
+
+    const tvStyles = textFieldStyles.description({
+      className,
+    });
+
+    const { entering, exiting } = useTextFieldDescriptionAnimation({
+      animation,
+    });
+
+    if (isInvalid) return null;
+
+    return (
+      <AnimatedText
+        ref={ref}
+        entering={entering}
+        exiting={exiting}
+        className={tvStyles}
+        {...restProps}
+      >
+        {children}
+      </AnimatedText>
+    );
+  }
+);
+
+// --------------------------------------------------
+
+const TextFieldErrorMessage = forwardRef<TextRef, TextFieldErrorMessageProps>(
+  (props, ref) => {
+    const { isInvalid: contextIsInvalid } = useTextField();
+    const { className, isInvalid: localIsInvalid, ...restProps } = props;
+
+    const isInvalid =
+      localIsInvalid !== undefined ? localIsInvalid : contextIsInvalid;
+
+    const tvStyles = textFieldStyles.errorMessage({
+      className,
+    });
+
+    return (
+      <ErrorView
+        ref={ref}
+        isInvalid={isInvalid}
+        className={tvStyles}
+        {...restProps}
+      />
+    );
+  }
+);
+
+// --------------------------------------------------
+
+TextFieldRoot.displayName = DISPLAY_NAME.ROOT;
+TextFieldLabel.displayName = DISPLAY_NAME.LABEL;
+TextFieldInput.displayName = DISPLAY_NAME.INPUT;
+TextFieldInputStartContent.displayName = DISPLAY_NAME.INPUT_START_CONTENT;
+TextFieldInputEndContent.displayName = DISPLAY_NAME.INPUT_END_CONTENT;
+TextFieldDescription.displayName = DISPLAY_NAME.DESCRIPTION;
+TextFieldErrorMessage.displayName = DISPLAY_NAME.ERROR_MESSAGE;
+
+/**
+ * Compound TextField component with sub-components
+ *
+ * @component TextField - Main container that provides gap-1 spacing between children.
+ * Handles disabled state and validation state for the entire field.
+ *
+ * @component TextField.Label - Label with optional asterisk for required fields.
+ * Changes to danger color when field is invalid.
+ *
+ * @component TextField.Input - Input container with animated border and background.
+ * Supports start/end content slots and handles focus state animations.
+ * Border turns danger color when field is invalid.
+ *
+ * @component TextField.InputStartContent - Optional content at the start of the input.
+ * Use for icons or prefixes.
+ *
+ * @component TextField.InputEndContent - Optional content at the end of the input.
+ * Use for icons, suffixes, or action buttons.
+ *
+ * @component TextField.Description - Description text with muted styling.
+ * Hidden when field is invalid and error message is shown.
+ *
+ * @component TextField.ErrorMessage - Error message with danger styling.
+ * Shown with animation when field is invalid. Automatically populated from errorMessage prop.
+ *
+ * @see Full documentation: https://heroui.com/components/text-field
+ */
+const CompoundTextField = Object.assign(TextFieldRoot, {
+  /** @optional Label with asterisk support */
+  Label: TextFieldLabel,
+  /** @required Input container with focus animations */
+  Input: TextFieldInput,
+  /** @optional Start content for input */
+  InputStartContent: TextFieldInputStartContent,
+  /** @optional End content for input */
+  InputEndContent: TextFieldInputEndContent,
+  /** @optional Description or helper text */
+  Description: TextFieldDescription,
+  /** @optional Error message displayed when field is invalid */
+  ErrorMessage: TextFieldErrorMessage,
+});
+
+export default CompoundTextField;
+export { useTextField };

package/src/components/text-field/text-field.types.ts

@@ -0,0 +1,349 @@
+import type {
+  StyleProp,
+  TextInputProps,
+  TextProps,
+  TextStyle,
+  ViewProps,
+} from 'react-native';
+import type {
+  AnimatedProps,
+  EntryOrExitLayoutType,
+  WithTimingConfig,
+} from 'react-native-reanimated';
+import type { ElementSlots } from '../../helpers/theme/types';
+import type {
+  Animation,
+  AnimationRootDisableAll,
+  AnimationValue,
+} from '../../helpers/types/animation';
+import type { ErrorViewRootProps } from '../error-view';
+import type { InputSlots, LabelSlots } from './text-field.styles';
+
+/**
+ * Animation configuration for TextField Label component
+ */
+export type TextFieldLabelAnimation = Animation<{
+  entering?: AnimationValue<{
+    /**
+     * Custom entering animation for label
+     */
+    value?: EntryOrExitLayoutType;
+  }>;
+  exiting?: AnimationValue<{
+    /**
+     * Custom exiting animation for label
+     */
+    value?: EntryOrExitLayoutType;
+  }>;
+}>;
+
+/**
+ * Animation configuration for TextField Description component
+ */
+export type TextFieldDescriptionAnimation = Animation<{
+  entering?: AnimationValue<{
+    /**
+     * Custom entering animation for description
+     */
+    value?: EntryOrExitLayoutType;
+  }>;
+  exiting?: AnimationValue<{
+    /**
+     * Custom exiting animation for description
+     */
+    value?: EntryOrExitLayoutType;
+  }>;
+}>;
+
+/**
+ * Animation configuration for TextField Input component
+ */
+export type TextFieldInputAnimation = Animation<{
+  backgroundColor?: AnimationValue<{
+    /**
+     * Background color values for different states
+     * @default Uses theme colors (field, field-focus, field)
+     */
+    value?: {
+      /**
+       * Background color when input is blurred
+       * @default --colors-field
+       */
+      blur?: string;
+      /**
+       * Background color when input is focused
+       * @default --colors-field-focus
+       */
+      focus?: string;
+      /**
+       * Background color when input is invalid
+       * @default --colors-field (same as blur)
+       */
+      error?: string;
+    };
+  }>;
+  borderColor?: AnimationValue<{
+    /**
+     * Border color values for different states
+     * @default Uses theme colors (field-border, accent, danger)
+     */
+    value?: {
+      /**
+       * Border color when input is blurred
+       * @default --colors-field-border
+       */
+      blur?: string;
+      /**
+       * Border color when input is focused
+       * @default --colors-accent
+       */
+      focus?: string;
+      /**
+       * Border color when input is invalid
+       * @default --colors-danger
+       */
+      error?: string;
+    };
+  }>;
+  /**
+   * Animation timing configuration for focus/blur transitions
+   */
+  focus?: AnimationValue<{
+    /**
+     * Animation timing configuration
+     * @default { duration: 150, easing: Easing.out(Easing.ease) }
+     */
+    timingConfig?: WithTimingConfig;
+  }>;
+  /**
+   * Animation timing configuration for error state transitions
+   */
+  error?: AnimationValue<{
+    /**
+     * Animation timing configuration
+     * @default { duration: 150, easing: Easing.out(Easing.ease) }
+     */
+    timingConfig?: WithTimingConfig;
+  }>;
+}>;
+
+/**
+ * Props for the TextField.Root component
+ */
+export interface TextFieldRootProps extends ViewProps {
+  /**
+   * Children elements to be rendered inside the root container
+   */
+  children?: React.ReactNode;
+  /**
+   * Whether the entire text field is disabled
+   * @default false
+   */
+  isDisabled?: boolean;
+  /**
+   * Whether the text field is in an invalid state
+   * @default false
+   */
+  isInvalid?: boolean;
+  /**
+   * Whether the text field is required (shows asterisk in label)
+   * @default false
+   */
+  isRequired?: boolean;
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+  /**
+   * Animation configuration for text field root
+   * - `"disable-all"`: Disable all animations including children (cascades down to all child components)
+   * - `undefined`: Use default animations
+   */
+  animation?: AnimationRootDisableAll;
+}
+
+/**
+ * Props for the TextField.Label component
+ */
+export interface TextFieldLabelProps
+  extends Omit<AnimatedProps<TextProps>, 'entering' | 'exiting'> {
+  /**
+   * Whether the label is in an invalid state (overrides context)
+   * @default undefined - uses context value
+   */
+  isInvalid?: boolean;
+  /**
+   * Children elements to be rendered as the label text
+   */
+  children?: React.ReactNode;
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+  /**
+   * Additional CSS classes for different parts of the label
+   */
+  classNames?: ElementSlots<LabelSlots>;
+  /**
+   * Animation configuration for label
+   * - `false` or `"disabled"`: Disable all animations
+   * - `true` or `undefined`: Use default animations
+   * - `object`: Custom animation configuration
+   */
+  animation?: TextFieldLabelAnimation;
+}
+
+/**
+ * Props for the TextField.Input component
+ */
+export interface TextFieldInputProps extends TextInputProps {
+  /**
+   * Children elements to be rendered inside the input container
+   */
+  children?: React.ReactNode;
+  /**
+   * Whether the input is in an invalid state (overrides context)
+   * @default undefined - uses context value
+   */
+  isInvalid?: boolean;
+  /**
+   * Additional CSS classes
+   *
+   * @note The following style properties are occupied by animations and cannot be set via className:
+   * - `backgroundColor` - Animated for focus/blur and error state transitions (applied to container)
+   * - `borderColor` - Animated for focus/blur and error state transitions (applied to container)
+   *
+   * To customize these properties, use the `animation` prop:
+   * ```tsx
+   * <TextField.Input
+   *   animation={{
+   *     backgroundColor: { value: { blur: '#fff', focus: '#f0f0f0', error: '#fee' } },
+   *     borderColor: { value: { blur: '#ccc', focus: '#007AFF', error: '#ff0000' } }
+   *   }}
+   * />
+   * ```
+   *
+   * To completely disable animated styles and use your own via className or style prop, set `isAnimatedStyleActive={false}`.
+   */
+  className?: string;
+  /**
+   * Additional CSS classes for different parts of the input
+   *
+   * @note The `container` slot has the following animated properties that cannot be set via className:
+   * - `backgroundColor` - Animated for focus/blur and error state transitions
+   * - `borderColor` - Animated for focus/blur and error state transitions
+   *
+   * To customize these properties, use the `animation` prop:
+   * ```tsx
+   * <TextField.Input
+   *   classNames={{
+   *     container: "custom-class", // backgroundColor and borderColor cannot be overridden here
+   *     input: "custom-input-class"
+   *   }}
+   *   animation={{
+   *     backgroundColor: { value: { blur: '#fff', focus: '#f0f0f0', error: '#fee' } },
+   *     borderColor: { value: { blur: '#ccc', focus: '#007AFF', error: '#ff0000' } }
+   *   }}
+   * />
+   * ```
+   *
+   * To completely disable animated styles and use your own via className or style prop, set `isAnimatedStyleActive={false}`.
+   */
+  classNames?: ElementSlots<InputSlots>;
+  styles?: {
+    input?: StyleProp<TextStyle>;
+  };
+  /**
+   * Animation configuration for input focus/blur and error state transitions
+   * - `false` or `"disabled"`: Disable all animations
+   * - `true` or `undefined`: Use default animations
+   * - `object`: Custom animation configuration
+   */
+  animation?: TextFieldInputAnimation;
+  /**
+   * 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 the TextField.InputStartContent component
+ */
+export interface TextFieldInputStartContentProps extends ViewProps {
+  /**
+   * Children elements to be rendered at the start of the input
+   */
+  children?: React.ReactNode;
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+}
+
+/**
+ * Props for the TextField.InputEndContent component
+ */
+export interface TextFieldInputEndContentProps extends ViewProps {
+  /**
+   * Children elements to be rendered at the end of the input
+   */
+  children?: React.ReactNode;
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+}
+
+/**
+ * Props for the TextField.Description component
+ */
+export interface TextFieldDescriptionProps
+  extends Omit<AnimatedProps<TextProps>, 'entering' | 'exiting'> {
+  /**
+   * Children elements to be rendered as the description text
+   */
+  children?: React.ReactNode;
+  /**
+   * Whether the description is in an invalid state (overrides context)
+   * @default undefined - uses context value
+   */
+  isInvalid?: boolean;
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+  /**
+   * Animation configuration for description
+   * - `false` or `"disabled"`: Disable all animations
+   * - `true` or `undefined`: Use default animations
+   * - `object`: Custom animation configuration
+   */
+  animation?: TextFieldDescriptionAnimation;
+}
+
+/**
+ * Props for the TextField.ErrorMessage component
+ */
+export interface TextFieldErrorMessageProps extends ErrorViewRootProps {}
+
+/**
+ * Context value for the TextField component
+ */
+export interface TextFieldContextValue {
+  /**
+   * Whether the entire text field is disabled
+   */
+  isDisabled: boolean;
+  /**
+   * Whether the text field is in an invalid state
+   * @default false
+   */
+  isInvalid: boolean;
+  /**
+   * Whether the text field is required
+   */
+  isRequired: boolean;
+}