@hero-design/rn-work-uikit 1.1.0-alpha.0 → 1.2.0-alpha.0

package/src/components/TextInput/FloatingLabel.tsx

@@ -0,0 +1,120 @@
+import React, { useEffect, useRef } from 'react';
+import { Animated, Easing } from 'react-native';
+import { StyledFloatingLabelContainer, StyledLabel } from './StyledTextInput';
+import type { State } from './StyledTextInput';
+import type { TextInputVariant } from './types';
+import { useTheme } from '../../theme';
+import { LABEL_ANIMATION_DURATION } from './constants';
+
+export interface FloatingLabelProps {
+  /** The text to display in the label */
+  label: string;
+  /** Input variant that affects animation positioning */
+  variant: TextInputVariant;
+  /** Current input state for styling */
+  state: State;
+  /** Whether the input is focused */
+  isFocused: boolean;
+  /** Whether field is required (affects optional text) */
+  required?: boolean;
+  /** Accessibility ID for screen readers */
+  accessibilityLabelledBy?: string;
+  /** Whether the input value is empty */
+  isEmptyValue: boolean;
+}
+
+/**
+ * FloatingLabel Component
+ *
+ * Handles the animated floating label behavior for TextInput.
+ * The label starts positioned over the input and animates to a smaller size above the input
+ * when the field is focused or has content.
+ *
+ * Key Features:
+ * - Smooth scale and translate animations using React Native Animated API
+ * - Responds to focus state and content presence
+ * - Automatically appends "(Optional)" text for non-required fields
+ * - Supports different variants (text/textarea) with appropriate positioning
+ * - Maintains accessibility features with proper IDs and test IDs
+ * - Self-contained animation management
+ *
+ * Animation Behavior:
+ * - Scale: 1.5 → 1 (label shrinks when floating)
+ * - TranslateY: Variable based on variant → 0 (moves up)
+ * - Uses bezier easing for smooth transitions
+ *
+ * @param props - The component props (see FloatingLabelProps for details)
+ */
+const FloatingLabel: React.FC<FloatingLabelProps> = ({
+  label,
+  variant,
+  state,
+  isFocused,
+  required,
+  accessibilityLabelledBy,
+  isEmptyValue,
+}) => {
+  const theme = useTheme();
+  const shouldFloat = isFocused || !isEmptyValue;
+  const focusAnimation = useRef(
+    new Animated.Value(shouldFloat ? 1 : 0)
+  ).current;
+
+  useEffect(() => {
+    Animated.timing(focusAnimation, {
+      toValue: shouldFloat ? 1 : 0,
+      duration: LABEL_ANIMATION_DURATION,
+      easing: Easing.bezier(0.4, 0, 0.2, 1),
+      useNativeDriver: true,
+    }).start();
+  }, [shouldFloat, focusAnimation]);
+
+  return (
+    <StyledFloatingLabelContainer
+      themeVariant={variant}
+      style={[
+        {
+          transformOrigin: 'left center',
+        },
+        {
+          transform: [
+            {
+              translateY: focusAnimation.interpolate({
+                inputRange: [0, 1],
+                outputRange: [
+                  variant !== 'textarea' ? 12 : theme.space.small,
+                  0,
+                ],
+              }),
+            },
+            {
+              scale: focusAnimation.interpolate({
+                inputRange: [0, 1],
+                outputRange: [1.333, 1],
+              }),
+            },
+          ],
+        },
+      ]}
+    >
+      <Animated.View>
+        <StyledLabel
+          nativeID={accessibilityLabelledBy}
+          testID="input-label"
+          themeState={state}
+          numberOfLines={1}
+          style={{
+            backgroundColor: 'transparent',
+          }}
+        >
+          {label}
+          {!required && ' (Optional)'}
+        </StyledLabel>
+      </Animated.View>
+    </StyledFloatingLabelContainer>
+  );
+};
+
+FloatingLabel.displayName = 'FloatingLabel';
+
+export default React.memo(FloatingLabel);

package/src/components/TextInput/InputComponent.tsx

@@ -0,0 +1,61 @@
+import React from 'react';
+import { TextInput as RNTextInput } from 'react-native';
+import type { TextInputProps as NativeTextInputProps } from 'react-native';
+import { StyledTextInput } from './StyledTextInput';
+import { useTheme } from '../../theme';
+import type { TextInputVariant } from './types';
+
+export interface InputComponentProps {
+  /** Input type ('text' or 'textarea') */
+  variant: TextInputVariant;
+  /** All props passed to the underlying TextInput */
+  nativeInputProps: NativeTextInputProps;
+  /** Optional custom input renderer function */
+  renderInputValue?: (inputProps: NativeTextInputProps) => React.ReactNode;
+}
+
+/**
+ * InputComponent
+ *
+ * Renders the actual text input element. Supports custom input rendering or uses the default StyledTextInput.
+ *
+ * Key Features:
+ * - Flexible rendering: supports custom input renderers via renderInputValue prop
+ * - Variant support: handles both 'text' and 'textarea' input types
+ * - Multiline handling: automatically enables multiline for textarea variant
+ * - Theme integration: applies theme colors for placeholder text
+ * - Ref forwarding: properly forwards refs to the underlying TextInput
+ *
+ * Rendering Logic:
+ * 1. If renderInputValue provided: Use custom renderer
+ * 2. Otherwise: Use default StyledTextInput with theme and variant support
+ *
+ * Multiline Behavior:
+ * - 'textarea' variant: Always multiline
+ * - 'text' variant: Single line unless explicitly set via nativeInputProps
+ *
+ * @param props - The component props (see InputComponentProps interface for details)
+ */
+const InputComponent = React.forwardRef<RNTextInput, InputComponentProps>(
+  ({ variant, nativeInputProps, renderInputValue }, ref) => {
+    const theme = useTheme();
+
+    return renderInputValue ? (
+      // Custom input renderer provided
+      <>{renderInputValue(nativeInputProps)}</>
+    ) : (
+      // Default styled input with theme and variant support
+      <StyledTextInput
+        {...nativeInputProps}
+        themeVariant={variant}
+        multiline={variant === 'textarea' || nativeInputProps.multiline}
+        ref={ref}
+        placeholderTextColor={theme.__hd__.textInput.colors.placeholder}
+      />
+    );
+  }
+);
+
+InputComponent.displayName = 'InputComponent';
+
+export default React.memo(InputComponent);

package/src/components/TextInput/InputRow.tsx

@@ -0,0 +1,103 @@
+import React, { useEffect, useRef } from 'react';
+import { Animated, TextInput as RNTextInput } from 'react-native';
+import type { TextInputProps as NativeTextInputProps } from 'react-native';
+import { IconName } from '@hero-design/rn';
+import { StyledInputRow } from './StyledTextInput';
+import PrefixComponent from './PrefixComponent';
+import InputComponent from './InputComponent';
+import type { State } from './StyledTextInput';
+import type { TextInputVariant } from './types';
+import { LABEL_ANIMATION_DURATION } from './constants';
+
+interface InputRowProps {
+  /** Current state of the input (focused, error, disabled, etc.) */
+  state: State;
+  /** Whether the input is focused */
+  isFocused: boolean;
+  /** Optional prefix icon or component */
+  prefix?: IconName | React.ReactElement;
+  /** Input variant - 'text' or 'textarea' */
+  variant: TextInputVariant;
+  /** Native TextInput props passed to the input component */
+  nativeInputProps: NativeTextInputProps;
+  /** Optional custom render function for input value */
+  renderInputValue?: (inputProps: NativeTextInputProps) => React.ReactNode;
+  /** Whether the input value is empty */
+  isEmptyValue: boolean;
+}
+
+/**
+ * InputRow Component
+ *
+ * Layout Structure:
+ * ┌─────────────────────────────────────────────────────────┐
+ * │                    StyledInputRow                       │
+ * │  ┌──────────┐  ┌─────────────────────────────────────┐  │
+ * │  │  Prefix  │  │           Input Field               │  │
+ * │  │ (Icon or │  │      (TextInput or Custom)          │  │
+ * │  │ Custom)  │  │          flex: 1                    │  │
+ * │  └──────────┘  └─────────────────────────────────────┘  │
+ * └─────────────────────────────────────────────────────────┘
+ *
+ * Rendering Behavior:
+ * - Components are always rendered but hidden with opacity in idle state
+ * - Uses accessibility props to hide components from screen readers when not visible
+ *
+ * Renders the main input row containing:
+ * 1. Conditionally visible prefix component (icon or custom element)
+ * 2. Conditionally visible input component (TextInput or custom rendered input)
+ */
+const InputRow = React.forwardRef<RNTextInput, InputRowProps>(
+  (
+    {
+      state,
+      isFocused,
+      prefix,
+      variant,
+      nativeInputProps,
+      renderInputValue,
+      isEmptyValue,
+    },
+    ref
+  ) => {
+    const shouldShow = isFocused || !isEmptyValue;
+    const opacity = useRef(new Animated.Value(shouldShow ? 1 : 0)).current;
+
+    useEffect(() => {
+      Animated.timing(opacity, {
+        toValue: shouldShow ? 1 : 0,
+        duration: LABEL_ANIMATION_DURATION,
+        useNativeDriver: true,
+      }).start();
+    }, [shouldShow, opacity]);
+
+    return (
+      <StyledInputRow>
+        {/* Prefix animation */}
+        <Animated.View style={{ opacity }}>
+          <PrefixComponent
+            state={state}
+            prefix={prefix}
+            accessibilityElementsHidden={!shouldShow}
+          />
+        </Animated.View>
+        {/* Input animation */}
+        <Animated.View
+          style={{ flex: 1, opacity }}
+          testID="input-row-input-wrapper"
+          accessibilityLabel="Text input field"
+          accessibilityElementsHidden={!shouldShow}
+        >
+          <InputComponent
+            variant={variant}
+            nativeInputProps={nativeInputProps}
+            renderInputValue={renderInputValue}
+            ref={ref}
+          />
+        </Animated.View>
+      </StyledInputRow>
+    );
+  }
+);
+
+export default InputRow;

package/src/components/TextInput/MaxLengthMessage.tsx

@@ -0,0 +1,66 @@
+import React from 'react';
+import { StyledCharacterCount } from './StyledTextInput';
+import type { State } from './StyledTextInput';
+
+export interface MaxLengthMessageProps {
+  /** Maximum allowed characters (undefined = no limit) */
+  maxLength?: number;
+  /** Current input state for styling */
+  state: State;
+  /** Current number of characters entered */
+  currentLength: number;
+  /** Whether to hide the counter display */
+  hideCharacterCount: boolean;
+}
+
+/**
+ * MaxLengthMessage Component
+ *
+ * Displays character count information for TextInput fields with maximum length restrictions.
+ * Shows current/max character count with state-aware styling.
+ *
+ * Key Features:
+ * - Character count display: Shows "currentLength/maxLength" format
+ * - Conditional rendering: Only shows when maxLength is set and not hidden
+ * - State-aware styling: Colors change based on input state (error, disabled, etc.)
+ * - Real-time updates: Updates as user types to show current progress
+ * - Hide capability: Can be hidden via hideCharacterCount prop
+ *
+ * Display Logic:
+ * - Shows only when: maxLength is defined AND hideCharacterCount is false
+ * - Format: "currentLength/maxLength" (e.g., "25/100")
+ * - Hidden when: maxLength is undefined OR hideCharacterCount is true
+ *
+ * State-based Styling:
+ * - Uses themeState to apply appropriate colors from theme
+ * - Error state: Shows error color to indicate validation issues
+ * - Disabled state: Shows muted color for disabled inputs
+ * - Normal states: Shows standard text colors
+ *
+ * Usage Example:
+ * - Input with 25 characters and 100 max: displays "25/100"
+ * - Input approaching limit: color may change based on theme
+ * - Input over limit: error state styling applied
+ *
+ * @param props - The component props (see MaxLengthMessageProps interface for details)
+ */
+const MaxLengthMessage: React.FC<MaxLengthMessageProps> = ({
+  maxLength,
+  state,
+  currentLength,
+  hideCharacterCount,
+}) => {
+  if (!maxLength || hideCharacterCount) {
+    return null;
+  }
+
+  return (
+    <StyledCharacterCount themeState={state}>
+      {currentLength}/{maxLength}
+    </StyledCharacterCount>
+  );
+};
+
+MaxLengthMessage.displayName = 'MaxLengthMessage';
+
+export default React.memo(MaxLengthMessage);

package/src/components/TextInput/PrefixComponent.tsx

@@ -0,0 +1,77 @@
+import React from 'react';
+import { Icon, IconName } from '@hero-design/rn';
+import { View, ViewProps } from 'react-native';
+import type { State } from './StyledTextInput';
+
+export interface PrefixComponentProps extends ViewProps {
+  /** Current input state for styling decisions */
+  state: State;
+  /** Icon name string or custom React element to display */
+  prefix?: IconName | React.ReactElement;
+}
+
+/**
+ * PrefixComponent
+ *
+ * Renders prefix content (icons or custom elements) on the left side of the TextInput,
+ * before the user's input cursor.
+ *
+ * Key Features:
+ * - Icon rendering: supports string icon names from the design system
+ * - Custom element support: can render any React element as prefix
+ * - State-aware styling: adjusts icon intent based on input state
+ * - Consistent sizing: uses 'xsmall' size for visual balance
+ * - Proper test IDs for automated testing
+ *
+ * Rendering Logic:
+ * 1. String icon name: Renders Icon component with state-based intent
+ * 2. Custom element: Renders the provided React element as-is
+ * 3. No prefix: Renders null
+ *
+ * Icon Intent Logic:
+ * - Disabled state: Uses 'disabled-text' intent for muted appearance
+ * - All other states: Uses 'text' intent for normal appearance
+ *
+ * Visual Positioning:
+ * - Positioned before the text input cursor
+ * - Uses smaller 'xsmall' size to avoid overwhelming the input
+ * - Maintains proper spacing via parent container
+ *
+ * @param props - The component props (see PrefixComponentProps interface for details)
+ */
+const PrefixComponent: React.FC<PrefixComponentProps> = ({
+  state,
+  prefix,
+  ...rest
+}) => {
+  const actualPrefix = typeof prefix === 'string' ? prefix : '';
+
+  if (typeof prefix === 'string' && actualPrefix) {
+    return (
+      <View testID="input-prefix" {...rest}>
+        <Icon
+          intent={state === 'disabled' ? 'disabled-text' : 'text'}
+          icon={actualPrefix}
+          size="xsmall"
+          testID="input-prefix-icon"
+          accessibilityLabel={`Prefix icon: ${actualPrefix}`}
+          accessibilityRole="image"
+        />
+      </View>
+    );
+  }
+
+  if (React.isValidElement(prefix)) {
+    return (
+      <View testID="input-prefix" {...rest}>
+        {prefix}
+      </View>
+    );
+  }
+
+  return null;
+};
+
+PrefixComponent.displayName = 'PrefixComponent';
+
+export default React.memo(PrefixComponent);

package/src/components/TextInput/StyledTextInput.tsx

@@ -0,0 +1,134 @@
+import { TextInput, View, StyleSheet, Animated, Pressable } from 'react-native';
+import { Typography, styled } from '@hero-design/rn';
+
+export type State = 'default' | 'filled' | 'disabled' | 'readonly' | 'error';
+
+type Variant = 'text' | 'textarea';
+
+const StyledContainer = styled(Pressable)(({ theme }) => ({
+  width: '100%',
+  flexDirection: 'row',
+  paddingHorizontal: theme.__hd__.textInput.space.containerPadding,
+  minHeight: theme.__hd__.textInput.sizes.containerMinHeight,
+  marginTop: theme.__hd__.textInput.space.containerMarginTop,
+}));
+
+const StyledFloatingLabelContainer = styled(Animated.View)<{
+  themeVariant: Variant;
+}>(({ themeVariant }) => ({
+  flexDirection: 'row',
+  flex: 1,
+  alignItems: themeVariant === 'text' ? 'center' : 'flex-start',
+  backgroundColor: 'transparent',
+}));
+
+const StyledLabel = styled(Typography.Caption)<{
+  themeState: State;
+}>(({ theme, themeState }) => ({
+  color: theme.__hd__.textInput.colors.labels[themeState],
+}));
+
+const StyledErrorRow = styled(View)(({ theme }) => ({
+  marginRight: theme.__hd__.textInput.space.errorContainerMarginRight,
+  flexDirection: 'row',
+  alignItems: 'center',
+  flex: 1,
+  flexGrow: 4,
+}));
+
+const StyledError = styled(Typography.Caption)(({ theme }) => ({
+  color: theme.__hd__.textInput.colors.error,
+  marginLeft: theme.__hd__.textInput.space.errorMarginLeft,
+}));
+
+const StyledCharacterCount = styled(Typography.Caption)<{
+  themeState: State;
+}>(({ theme, themeState }) => ({
+  color: theme.__hd__.textInput.colors.maxLengthLabels[themeState],
+  flex: 1,
+  flexGrow: 1,
+  textAlign: 'right',
+}));
+
+const StyledHelperText = Typography.Caption;
+const StyledTextInput = styled(TextInput)<{ themeVariant: Variant }>(
+  ({ theme, themeVariant }) => ({
+    textAlignVertical: themeVariant === 'text' ? 'center' : 'top',
+    fontSize: theme.__hd__.textInput.fontSizes.text,
+    flexGrow: 2,
+    paddingVertical: 0,
+    maxHeight: theme.__hd__.textInput.sizes.textInputMaxHeight,
+    minHeight: theme.__hd__.textInput.sizes.textInputMinHeight,
+    height:
+      themeVariant === 'text'
+        ? undefined
+        : theme.__hd__.textInput.sizes.textareaHeight,
+    fontFamily: theme.__hd__.textInput.fonts.text,
+  })
+);
+
+const StyledBorder = styled(View)<{
+  themeState: State;
+  themeFocused: boolean;
+}>(({ theme, themeFocused, themeState }) => ({
+  ...StyleSheet.absoluteFillObject,
+  borderWidth: theme.__hd__.textInput.borderWidths.container.normal,
+  borderRadius: theme.__hd__.textInput.radii.container,
+  borderColor: themeFocused
+    ? theme.__hd__.textInput.colors.borders.focused
+    : theme.__hd__.textInput.colors.borders[themeState],
+}));
+
+const StyledInputWrapper = styled(View)(({ theme }) => ({
+  flexDirection: 'column',
+  flex: 1,
+  backgroundColor: 'transparent',
+  borderRadius: theme.__hd__.textInput.radii.container,
+  marginBottom: theme.__hd__.textInput.space.inputWrapperMarginVertical,
+  marginTop: theme.__hd__.textInput.space.inputWrapperMarginVertical,
+  overflow: 'hidden',
+}));
+
+const StyledInputRow = styled(View)(({ theme }) => ({
+  flexDirection: 'row',
+  alignItems: 'center',
+  flexGrow: 2,
+  flexShrink: 1,
+  gap: theme.__hd__.textInput.space.prefixAndInputContainerGap,
+}));
+
+const StyledErrorAndHelpTextContainer = styled(View)(({ theme }) => ({
+  paddingHorizontal:
+    theme.__hd__.textInput.space.errorAndHelpTextContainerHorizontalPadding,
+  minHeight: theme.__hd__.textInput.sizes.errorAndHelpTextContainerHeight,
+  paddingTop: theme.__hd__.textInput.space.errorAndHelpTextContainerPaddingTop,
+}));
+
+const StyledBottomContainer = styled(View)(() => ({
+  flexDirection: 'row',
+  justifyContent: 'space-between',
+  alignItems: 'flex-start',
+}));
+
+const StyledSuffixContainer = styled(View)(() => ({
+  flexDirection: 'row',
+  alignItems: 'center',
+  justifyContent: 'flex-end',
+}));
+
+export {
+  StyledInputWrapper,
+  StyledTextInput,
+  StyledError,
+  StyledCharacterCount,
+  StyledContainer,
+  StyledErrorRow,
+  StyledHelperText,
+  StyledInputRow,
+  StyledFloatingLabelContainer,
+  StyledErrorAndHelpTextContainer,
+  StyledBorder,
+  StyledBottomContainer,
+  StyledSuffixContainer,
+  StyledLabel,
+};

package/src/components/TextInput/SuffixComponent.tsx

@@ -0,0 +1,73 @@
+import React from 'react';
+import { Icon, IconName } from '@hero-design/rn';
+import type { State } from './StyledTextInput';
+
+export interface SuffixComponentProps {
+  /** Current input state for styling decisions */
+  state: State;
+  /** Whether to show loading spinner instead of suffix */
+  loading: boolean;
+  /** Icon name string or custom React element to display */
+  suffix?: IconName | React.ReactElement;
+}
+
+/**
+ * SuffixComponent
+ *
+ * Renders suffix content (icons or custom elements) on the right side of the TextInput.
+ * Handles loading states and custom elements.
+ *
+ * Key Features:
+ * - Loading state handling: shows spinner when loading is true
+ * - Icon rendering: supports string icon names from the design system
+ * - Custom element support: can render any React element as suffix
+ * - State-aware styling: adjusts icon intent based on input state
+ * - Spinning animation: loading icons automatically spin
+ * - Proper test IDs for automated testing
+ *
+ * Rendering Priority:
+ * 1. Loading state: Shows 'loading' icon with spin animation
+ * 2. String icon name: Renders Icon component with state-based intent
+ * 3. Custom element: Renders the provided React element as-is
+ * 4. No suffix: Renders null
+ *
+ * Icon Intent Logic:
+ * - Disabled state: Uses 'disabled-text' intent
+ * - All other states: Uses 'text' intent
+ *
+ * @param props - The component props (see SuffixComponentProps interface for details)
+ */
+const SuffixComponent: React.FC<SuffixComponentProps> = ({
+  state,
+  loading,
+  suffix,
+}) => {
+  // Loading state overrides suffix
+  const actualSuffix = loading ? 'loading' : suffix;
+
+  if (typeof actualSuffix === 'string') {
+    // Render icon from design system
+    return (
+      <Icon
+        intent={state === 'disabled' ? 'disabled-text' : 'text'}
+        testID="input-suffix"
+        accessibilityLabel={`Suffix icon: ${actualSuffix}`}
+        accessibilityRole="image"
+        icon={actualSuffix}
+        spin={actualSuffix === 'loading'} // Animate loading icon
+        size="medium"
+      />
+    );
+  }
+
+  if (actualSuffix) {
+    // Render custom element
+    return suffix as React.ReactElement;
+  }
+
+  return null;
+};
+
+SuffixComponent.displayName = 'SuffixComponent';
+
+export default React.memo(SuffixComponent);

package/src/components/TextInput/__tests__/ErrorOrHelpText.spec.tsx

@@ -0,0 +1,20 @@
+import React from 'react';
+import renderWithTheme from '../../../../testUtils/renderWithTheme';
+import ErrorOrHelpText from '../ErrorOrHelpText';
+
+describe('ErrorOrHelpText', () => {
+  it('renders correctly with error', () => {
+    const { queryAllByText } = renderWithTheme(
+      <ErrorOrHelpText error="This is error" helpText="This is help text" />
+    );
+    expect(queryAllByText('This is error')).toHaveLength(1);
+    expect(queryAllByText('This is help text')).toHaveLength(0);
+  });
+
+  it('renders correctly with help text', () => {
+    const { queryAllByText } = renderWithTheme(
+      <ErrorOrHelpText error="" helpText="This is help text" />
+    );
+    expect(queryAllByText('This is help text')).toHaveLength(1);
+  });
+});