@praxiis/ui 0.0.1

package/src/primitives/inputs/TextInput/TextInput.helpers.ts

@@ -0,0 +1,206 @@
+/**
+ * TextInput Component Helpers
+ *
+ * Pure functions for computing TextInput sizes, styles, and mappings.
+ *
+ * ## Size Configuration
+ * | Size | Height | Font | Icon | Padding |
+ * |------|--------|------|------|---------|
+ * | sm   | 40px   | 14px | 18px | 12px    |
+ * | md   | 48px   | 16px | 20px | 16px    |
+ * | lg   | 56px   | 17px | 24px | 16px    |
+ *
+ * ## Text Variant Mapping
+ * | Input Size | Text Variant | Label Variant |
+ * |------------|--------------|---------------|
+ * | sm         | bodySmall    | labelSmall    |
+ * | md         | bodyMedium   | labelSmall    |
+ * | lg         | bodyLarge    | labelMedium   |
+ */
+
+import { IconSize } from "../../content/Icon";
+import { BaseThemeColor, RestyleColor } from "../../../types";
+import {
+  ResolveTextInputStyleParams,
+  TextInputSize,
+  TextInputSizeConfig,
+  TextInputStyleResult,
+  TextInputTextVariant,
+} from "./TextInput.types";
+
+/**
+ * TextInput size configuration mapping.
+ *
+ * Height follows a consistent scale:
+ * - sm: 40px - Compact forms
+ * - md: 48px - Default mobile size (meets 44px touch target)
+ * - lg: 56px - Tablets, emphasized inputs
+ */
+const TEXT_INPUT_SIZE_CONFIG: Record<TextInputSize, TextInputSizeConfig> = {
+  sm: {
+    height: 40,
+    paddingHorizontal: 12,
+    fontSize: 14,
+    iconSize: 18,
+  },
+  md: {
+    height: 48,
+    paddingHorizontal: 16,
+    fontSize: 16,
+    iconSize: 20,
+  },
+  lg: {
+    height: 56,
+    paddingHorizontal: 16,
+    fontSize: 17,
+    iconSize: 24,
+  },
+} as const;
+
+/**
+ * Text variant mapping for input text.
+ *
+ * - sm input → bodySmall text
+ * - md input → bodyMedium text
+ * - lg input → bodyLarge text
+ */
+const TEXT_INPUT_TEXT_VARIANTS: Record<TextInputSize, TextInputTextVariant> = {
+  sm: "bodySmall",
+  md: "bodyMedium",
+  lg: "bodyLarge",
+} as const;
+
+/**
+ * Text variant mapping for labels.
+ *
+ * - sm input → labelSmall label
+ * - md input → labelSmall label
+ * - lg input → labelMedium label
+ */
+const TEXT_INPUT_LABEL_VARIANTS: Record<TextInputSize, TextInputTextVariant> = {
+  sm: "labelSmall",
+  md: "labelSmall",
+  lg: "labelMedium",
+} as const;
+
+/**
+ * Icon size mapping - derives icon size from input size.
+ * Icons should match text size for visual balance.
+ *
+ * - sm input → sm icon (16px)
+ * - md input → md icon (20px)
+ * - lg input → lg icon (24px)
+ */
+const SIZE_TO_ICON_SIZE: Record<TextInputSize, IconSize> = {
+  sm: "sm",
+  md: "md",
+  lg: "lg",
+} as const;
+
+/**
+ * Get size configuration based on input size.
+ *
+ * @param size - The input size variant
+ * @returns Size configuration object
+ */
+export function getTextInputSizeConfig(size: TextInputSize): TextInputSizeConfig {
+  return TEXT_INPUT_SIZE_CONFIG[size] || TEXT_INPUT_SIZE_CONFIG.md;
+}
+
+/**
+ * Get text variant for input text based on size.
+ *
+ * @param size - The input size variant
+ * @returns Text variant key
+ */
+export function getTextInputTextVariant(size: TextInputSize): TextInputTextVariant {
+  return TEXT_INPUT_TEXT_VARIANTS[size] || TEXT_INPUT_TEXT_VARIANTS.md;
+}
+
+/**
+ * Get text variant for label based on size.
+ *
+ * @param size - The input size variant
+ * @returns Text variant key for label
+ */
+export function getTextInputLabelVariant(size: TextInputSize): TextInputTextVariant {
+  return TEXT_INPUT_LABEL_VARIANTS[size] || TEXT_INPUT_LABEL_VARIANTS.md;
+}
+
+/**
+ * Get icon size based on input size.
+ *
+ * @param size - The input size variant
+ * @returns Icon size key
+ */
+export function getTextInputIconSize(size: TextInputSize): IconSize {
+  return SIZE_TO_ICON_SIZE[size];
+}
+
+/**
+ * Get icon color based on error and focus states.
+ *
+ * @param hasError - Whether the input has an error
+ * @param isFocused - Whether the input is focused
+ * @param color - The primary color
+ * @returns Icon color key
+ */
+export function getTextInputIconColor(
+  hasError: boolean,
+  isFocused: boolean,
+  color: RestyleColor
+): RestyleColor {
+  if (hasError) {
+    return "feedbackError";
+  }
+  if (isFocused) {
+    return color;
+  }
+  return "textTertiary";
+}
+
+/**
+ * Resolve dynamic style properties for the input container.
+ *
+ * @param params - Style resolution parameters
+ * @returns Computed styles for the input container
+ */
+export function resolveTextInputStyle(
+  params: ResolveTextInputStyleParams
+): TextInputStyleResult {
+  const { variant, disabled, error, isFocused, color, theme } = params;
+
+  const hasError = !!error;
+
+  // Background color
+  let backgroundColor: string;
+  if (disabled) {
+    backgroundColor = theme.colors.interactiveDisabled;
+  } else if (variant === "filled") {
+    backgroundColor = theme.colors.backgroundSecondary;
+  } else {
+    backgroundColor = theme.colors.surfacePrimary;
+  }
+
+  // Border color
+  let borderColor: string;
+  if (disabled) {
+    borderColor = theme.colors.borderDefault;
+  } else if (hasError) {
+    borderColor = theme.colors.feedbackError;
+  } else if (isFocused) {
+    borderColor = theme.colors[color as BaseThemeColor];
+  } else {
+    borderColor = theme.colors.borderDefault;
+  }
+
+  // Border width
+  const borderWidth = isFocused ? 2 : 1;
+
+  return {
+    backgroundColor,
+    borderColor,
+    borderWidth,
+    opacity: 1,
+  };
+}

package/src/primitives/inputs/TextInput/TextInput.tsx

@@ -0,0 +1,392 @@
+/**
+ * TextInput Component
+ *
+ * @description Text entry field with labels and validation - Molecule
+ *
+ * TextInput combines multiple atoms (Icon, Text, Box) into a
+ * complete form field with label, input, helper text, and error states.
+ *
+ * ## Size Scale
+ * | Size | Height | Font | Icon | Padding |
+ * |------|--------|------|------|---------|
+ * | sm   | 40px   | 14px | 18px | 12px    |
+ * | md   | 48px   | 16px | 20px | 16px    |
+ * | lg   | 56px   | 17px | 24px | 16px    |
+ *
+ * ## Variants
+ * - `outlined`: Border with transparent/white background (default)
+ * - `filled`: Filled background with subtle border
+ * - `textarea`: Multi-line with configurable height
+ *
+ * ## Visual States
+ * - Default: Gray border
+ * - Focused: Colored border (2px), colored label
+ * - Error: Red border, red label, error message
+ * - Disabled: Reduced opacity (0.5)
+ *
+ * ## Features
+ * - Responsive size prop (phone/tablet breakpoints)
+ * - Optional left and right icons
+ * - Label with required indicator
+ * - Helper text and error states
+ * - Character count display
+ * - Full accessibility support
+ * - Textarea with cursor at top
+ *
+ * @performance
+ * - Wrapped with React.memo() to prevent unnecessary re-renders
+ * - Uses useMemo() for expensive calculations (style resolution, state-based colors)
+ * - Border width and color calculations cached per state change
+ * - Icon sizing optimized with lookup tables for instant resolution
+ *
+ * @see TextInput.types.ts - Type definitions
+ * @see TextInput.helpers.ts - Size and style functions
+ * @see TextInput.a11y.ts - Accessibility prop generation
+ *
+ * @example
+ * // Basic usage
+ * <TextInput label="Email" value={email} onChangeText={setEmail} />
+ *
+ * @example
+ * // With icons and validation
+ * <TextInput
+ *   label="Email"
+ *   value={email}
+ *   onChangeText={setEmail}
+ *   leftIconName="email"
+ *   rightIconName={isValid ? "check-circle" : undefined}
+ *   error={emailError}
+ *   helperText="Enter your email address"
+ *   required
+ * />
+ *
+ * @example
+ * // Textarea variant
+ * <TextInput
+ *   label="Description"
+ *   variant="textarea"
+ *   textareaHeight={120}
+ *   value={description}
+ *   onChangeText={setDescription}
+ * />
+ */
+
+import {
+  backgroundColor,
+  border,
+  createRestyleComponent,
+  layout,
+  spacing,
+  spacingShorthand,
+  useResponsiveProp,
+} from "@shopify/restyle";
+import React, { forwardRef, memo, useCallback, useMemo, useState } from "react";
+import {
+  NativeSyntheticEvent,
+  TextInput as RNTextInput,
+  TargetedEvent,
+  StyleSheet,
+} from "react-native";
+import { RestyleTheme, useRestyleTheme } from "../../../core/restyle";
+import { BaseThemeColor } from "../../../types";
+import { Icon } from "../../content/Icon";
+import { Box } from "../../layout";
+import { Text } from "../../typography";
+import {
+  getTextInputLabelVariant,
+  getTextInputSizeConfig,
+} from "./TextInput.helpers";
+import { BaseTextInputContainerProps, TextInputProps, TextInputSize } from "./TextInput.types";
+import { useTextInputLogic } from "./useTextInputLogic";
+
+/**
+ * Base container for the input field with Restyle support.
+ * @internal
+ */
+const BaseTextInputContainer = createRestyleComponent<
+  BaseTextInputContainerProps,
+  RestyleTheme
+>([backgroundColor, border, layout, spacing, spacingShorthand], Box);
+
+const TextInputComponent = forwardRef<RNTextInput, TextInputProps>(
+  function TextInputComponent({
+  label,
+  helperText,
+  error,
+  size = "md",
+  variant = "outlined",
+  leftIconName,
+  rightIconName,
+  disabled = false,
+  required = false,
+  showCharCount = false,
+  maxLength,
+  value = "",
+  color = "accentPrimary",
+  onFocus,
+  onBlur,
+  containerStyle,
+  inputContainerStyle,
+  testID,
+  accessibilityLabel,
+  accessibilityHint,
+  textareaHeight = 120,
+  // Extract BoxProps for outer container
+  margin,
+  marginTop,
+  marginBottom,
+  marginLeft,
+  marginRight,
+  marginHorizontal,
+  marginVertical,
+  padding,
+  paddingTop,
+  paddingBottom,
+  paddingLeft,
+  paddingRight,
+  paddingHorizontal,
+  paddingVertical,
+  flex,
+  flexGrow,
+  flexShrink,
+  width,
+  minWidth,
+  maxWidth,
+  ...rest
+}: TextInputProps, ref) {
+  const theme = useRestyleTheme();
+  const [isFocused, setIsFocused] = useState(false);
+
+  const {
+    isDisabled,
+    hasError,
+    opacity,
+    finalBackgroundColor,
+    finalBorderColor,
+    finalTextColor,
+    finalPlaceholderColor,
+    finalLabelColor,
+    borderWidth,
+    leftIconSize,
+    rightIconSize,
+    iconColor,
+    a11yProps,
+  } = useTextInputLogic({
+    variant,
+    size,
+    color,
+    disabled,
+    error,
+    isFocused,
+    leftIconName,
+    rightIconName,
+    label,
+    accessibilityLabel,
+    accessibilityHint,
+    required,
+  });
+
+  // Resolve responsive size value
+  const resolvedSize = (useResponsiveProp(size) ?? "md") as TextInputSize;
+
+  // Get size configuration for dimensions
+  const sizeConfig = getTextInputSizeConfig(resolvedSize);
+  const labelVariant = getTextInputLabelVariant(resolvedSize);
+
+  const handleFocus = useCallback(
+    (e: NativeSyntheticEvent<TargetedEvent>) => {
+      setIsFocused(true);
+      onFocus?.(e);
+    },
+    [onFocus],
+  );
+
+  const handleBlur = useCallback(
+    (e: NativeSyntheticEvent<TargetedEvent>) => {
+      setIsFocused(false);
+      onBlur?.(e);
+    },
+    [onBlur],
+  );
+
+  const charCount = typeof value === "string" ? value.length : 0;
+  const isTextarea = variant === "textarea";
+
+  const backgroundColorStyle = finalBackgroundColor === "transparent"
+    ? "transparent"
+    : theme.colors[finalBackgroundColor as BaseThemeColor];
+
+  const borderColorStyle = theme.colors[finalBorderColor as BaseThemeColor];
+
+  const textColorStyle = theme.colors[finalTextColor as BaseThemeColor];
+
+  const placeholderColorStyle = theme.colors[finalPlaceholderColor as BaseThemeColor];
+
+  // Calculate container height for textarea
+  const containerHeight = isTextarea ? textareaHeight : sizeConfig.height;
+
+  // Calculate padding for textarea (needs vertical padding)
+  const containerPadding = useMemo(() => {
+    if (isTextarea) {
+      return {
+        paddingHorizontal: sizeConfig.paddingHorizontal,
+        paddingVertical: theme.spacing.sm,
+      };
+    }
+    return {
+      paddingHorizontal: sizeConfig.paddingHorizontal,
+      paddingVertical: 0,
+    };
+  }, [isTextarea, sizeConfig.paddingHorizontal, theme.spacing.sm]);
+
+  return (
+    <Box
+      style={containerStyle}
+      testID={testID}
+      opacity={opacity}
+      margin={margin}
+      marginTop={marginTop}
+      marginBottom={marginBottom}
+      marginLeft={marginLeft}
+      marginRight={marginRight}
+      marginHorizontal={marginHorizontal}
+      marginVertical={marginVertical}
+      padding={padding}
+      paddingTop={paddingTop}
+      paddingBottom={paddingBottom}
+      paddingLeft={paddingLeft}
+      paddingRight={paddingRight}
+      paddingHorizontal={paddingHorizontal}
+      paddingVertical={paddingVertical}
+      flex={flex}
+      flexGrow={flexGrow}
+      flexShrink={flexShrink}
+      width={width}
+      minWidth={minWidth}
+      maxWidth={maxWidth}
+    >
+      {label && (
+        <Box marginBottom="xs" flexDirection="row" alignItems="center">
+          <Text variant={labelVariant} color={finalLabelColor as BaseThemeColor}>
+            {label}
+            {required && (
+              <Text variant={labelVariant} color="feedbackError">
+                {" *"}
+              </Text>
+            )}
+          </Text>
+        </Box>
+      )}
+
+      <BaseTextInputContainer
+        flexDirection={isTextarea ? "column" : "row"}
+        alignItems={isTextarea ? "flex-start" : "center"}
+        borderRadius="md"
+        style={[
+          {
+            height: containerHeight,
+            paddingHorizontal: containerPadding.paddingHorizontal,
+            paddingTop: containerPadding.paddingVertical,
+            paddingBottom: containerPadding.paddingVertical,
+            backgroundColor: backgroundColorStyle,
+            borderColor: borderColorStyle,
+            borderWidth: borderWidth,
+          },
+          inputContainerStyle,
+        ]}
+      >
+        {!isTextarea && leftIconName && leftIconSize && (
+          <Box marginRight="sm" alignItems="center" justifyContent="center">
+            <Icon
+              name={leftIconName}
+              size={leftIconSize}
+              color={iconColor}
+              accessibilityLabel={leftIconName}
+            />
+          </Box>
+        )}
+
+        <RNTextInput
+          ref={ref}
+          style={[
+            styles.input,
+            {
+              fontSize: sizeConfig.fontSize,
+              color: textColorStyle,
+              ...(isTextarea && {
+                textAlignVertical: "top", // Android: cursor starts at top
+                paddingTop: 0,
+                paddingBottom: 0,
+                flex: 1,
+                width: "100%",
+                minHeight:
+                  containerHeight -
+                  containerPadding.paddingVertical * 2 -
+                  borderWidth * 2,
+              }),
+            },
+          ]}
+          placeholderTextColor={placeholderColorStyle}
+          editable={!isDisabled}
+          value={value}
+          maxLength={maxLength}
+          multiline={isTextarea}
+          onFocus={handleFocus}
+          onBlur={handleBlur}
+          accessibilityLabel={a11yProps.accessibilityLabel}
+          accessibilityState={a11yProps.accessibilityState}
+          accessibilityHint={a11yProps.accessibilityHint}
+          {...rest}
+        />
+
+        {!isTextarea && rightIconName && rightIconSize && (
+          <Box marginLeft="sm" alignItems="center" justifyContent="center">
+            <Icon
+              name={rightIconName}
+              size={rightIconSize}
+              color={iconColor}
+              accessibilityLabel={rightIconName}
+            />
+          </Box>
+        )}
+      </BaseTextInputContainer>
+
+      {(helperText || error || showCharCount) && (
+        <Box
+          marginTop="xs"
+          flexDirection="row"
+          alignItems="center"
+          justifyContent="space-between"
+        >
+          <Box flex={1}>
+            {(error || helperText) && (
+              <Text
+                variant="caption"
+                color={hasError ? "feedbackError" : "textSecondary"}
+              >
+                {error || helperText}
+              </Text>
+            )}
+          </Box>
+
+          {showCharCount && maxLength && (
+            <Text variant="caption" color="textTertiary">
+              {charCount}/{maxLength}
+            </Text>
+          )}
+        </Box>
+      )}
+    </Box>
+  );
+});
+
+const styles = StyleSheet.create({
+  input: {
+    flex: 1,
+    padding: 0,
+    margin: 0,
+  },
+});
+
+export const TextInput = memo(TextInputComponent);
+TextInput.displayName = "TextInput";