@idealyst/components 1.2.105 → 1.2.107

package/src/TextInput/TextInput.native.tsx

@@ -6,6 +6,7 @@ import { TextInputProps } from './types';
 import { textInputStyles } from './TextInput.styles';
 import { getNativeFormAccessibilityProps } from '../utils/accessibility';
 import type { IdealystElement } from '../utils/refTypes';
+import Text from '../Text';
 
 // Inner TextInput component that can be memoized to prevent re-renders
 // for Android secure text entry
@@ -68,6 +69,9 @@ const TextInput = React.forwardRef<IdealystElement, TextInputProps>(({
   size = 'md',
   type = 'outlined',
   hasError = false,
+  error,
+  helperText,
+  label,
   // Spacing variants from FormInputStyleProps
   margin,
   marginVertical,
@@ -91,6 +95,12 @@ const TextInput = React.forwardRef<IdealystElement, TextInputProps>(({
   const [isFocused, setIsFocused] = useState(false);
   const [isPasswordVisible, setIsPasswordVisible] = useState(false);
 
+  // Derive hasError from error prop or hasError boolean
+  const computedHasError = Boolean(error) || hasError;
+
+  // Determine if we need a wrapper (when label, error, or helperText is present)
+  const needsWrapper = Boolean(label) || Boolean(error) || Boolean(helperText);
+
   // Track if this is a secure field that needs Android workaround
   const isSecureField = inputMode === 'password' || secureTextEntry;
   const needsAndroidSecureWorkaround = Platform.OS === 'android' && isSecureField && !isPasswordVisible;
@@ -160,12 +170,13 @@ const TextInput = React.forwardRef<IdealystElement, TextInputProps>(({
 
   // Generate native accessibility props
   const nativeA11yProps = useMemo(() => {
-    // Derive invalid state from hasError or explicit accessibilityInvalid
-    const isInvalid = accessibilityInvalid ?? hasError;
+    // Derive invalid state from computedHasError or explicit accessibilityInvalid
+    const isInvalid = accessibilityInvalid ?? computedHasError;
+    const computedLabel = accessibilityLabel ?? label ?? placeholder;
 
     return getNativeFormAccessibilityProps({
-      accessibilityLabel,
-      accessibilityHint,
+      accessibilityLabel: computedLabel,
+      accessibilityHint: accessibilityHint ?? (error || helperText),
       accessibilityDisabled: accessibilityDisabled ?? disabled,
       accessibilityHidden,
       accessibilityRole: accessibilityRole ?? 'textbox',
@@ -174,14 +185,18 @@ const TextInput = React.forwardRef<IdealystElement, TextInputProps>(({
     });
   }, [
     accessibilityLabel,
+    label,
+    placeholder,
     accessibilityHint,
+    error,
+    helperText,
     accessibilityDisabled,
     disabled,
     accessibilityHidden,
     accessibilityRole,
     accessibilityRequired,
     accessibilityInvalid,
-    hasError,
+    computedHasError,
   ]);
 
   // Determine the textContentType for iOS AutoFill
@@ -224,7 +239,7 @@ const TextInput = React.forwardRef<IdealystElement, TextInputProps>(({
     size,
     type,
     focused: isFocused,
-    hasError,
+    hasError: computedHasError,
     disabled,
     margin,
     marginVertical,
@@ -232,11 +247,19 @@ const TextInput = React.forwardRef<IdealystElement, TextInputProps>(({
   });
 
   // Compute dynamic styles - call as functions for theme reactivity
-  const containerStyle = (textInputStyles.container as any)({ type, focused: isFocused, hasError, disabled });
+  const containerStyle = (textInputStyles.container as any)({ type, focused: isFocused, hasError: computedHasError, disabled });
   const leftIconContainerStyle = (textInputStyles.leftIconContainer as any)({});
   const rightIconContainerStyle = (textInputStyles.rightIconContainer as any)({});
   const passwordToggleStyle = (textInputStyles.passwordToggle as any)({});
 
+  // Wrapper, label, and footer styles
+  const wrapperStyle = (textInputStyles.wrapper as any)({});
+  const labelStyle = (textInputStyles.label as any)({ disabled });
+  const footerStyle = (textInputStyles.footer as any)({});
+  const helperTextStyle = (textInputStyles.helperText as any)({ hasError: computedHasError });
+
+  const showFooter = Boolean(error) || Boolean(helperText);
+
   // Helper to render left icon
   const renderLeftIcon = () => {
     if (!leftIcon) return null;
@@ -275,44 +298,104 @@ const TextInput = React.forwardRef<IdealystElement, TextInputProps>(({
     return null;
   };
 
+  // If no wrapper needed, return flat input container
+  if (!needsWrapper) {
+    return (
+      <View style={[containerStyle, style]} testID={testID} nativeID={id}>
+        {/* Left Icon */}
+        {leftIcon && (
+          <View style={leftIconContainerStyle}>
+            {renderLeftIcon()}
+          </View>
+        )}
+
+        {/* Input */}
+        <InnerRNTextInput
+          inputRef={ref}
+          value={value}
+          onChangeText={handleChangeText}
+          isAndroidSecure={needsAndroidSecureWorkaround}
+          inputStyle={inputStyle}
+          textInputProps={textInputProps}
+        />
+
+        {/* Right Icon or Password Toggle */}
+        {shouldShowPasswordToggle ? (
+          <TouchableOpacity
+            style={passwordToggleStyle}
+            onPress={togglePasswordVisibility}
+            disabled={disabled}
+            accessibilityLabel={isPasswordVisible ? 'Hide password' : 'Show password'}
+          >
+            <MaterialDesignIcons
+              name={isPasswordVisible ? 'eye-off' : 'eye'}
+              size={iconSize}
+              color={iconColor}
+            />
+          </TouchableOpacity>
+        ) : rightIcon ? (
+          <View style={rightIconContainerStyle}>
+            {renderRightIcon()}
+          </View>
+        ) : null}
+      </View>
+    );
+  }
+
+  // With wrapper for label/error/helperText
   return (
-    <View style={[containerStyle, style]} testID={testID} nativeID={id}>
-      {/* Left Icon */}
-      {leftIcon && (
-        <View style={leftIconContainerStyle}>
-          {renderLeftIcon()}
-        </View>
+    <View style={[wrapperStyle, style]} testID={testID} nativeID={id}>
+      {label && (
+        <Text style={labelStyle}>{label}</Text>
       )}
 
-      {/* Input */}
-      <InnerRNTextInput
-        inputRef={ref}
-        value={value}
-        onChangeText={handleChangeText}
-        isAndroidSecure={needsAndroidSecureWorkaround}
-        inputStyle={inputStyle}
-        textInputProps={textInputProps}
-      />
+      <View style={containerStyle}>
+        {/* Left Icon */}
+        {leftIcon && (
+          <View style={leftIconContainerStyle}>
+            {renderLeftIcon()}
+          </View>
+        )}
+
+        {/* Input */}
+        <InnerRNTextInput
+          inputRef={ref}
+          value={value}
+          onChangeText={handleChangeText}
+          isAndroidSecure={needsAndroidSecureWorkaround}
+          inputStyle={inputStyle}
+          textInputProps={textInputProps}
+        />
 
-      {/* Right Icon or Password Toggle */}
-      {shouldShowPasswordToggle ? (
-        <TouchableOpacity
-          style={passwordToggleStyle}
-          onPress={togglePasswordVisibility}
-          disabled={disabled}
-          accessibilityLabel={isPasswordVisible ? 'Hide password' : 'Show password'}
-        >
-          <MaterialDesignIcons
-            name={isPasswordVisible ? 'eye-off' : 'eye'}
-            size={iconSize}
-            color={iconColor}
-          />
-        </TouchableOpacity>
-      ) : rightIcon ? (
-        <View style={rightIconContainerStyle}>
-          {renderRightIcon()}
+        {/* Right Icon or Password Toggle */}
+        {shouldShowPasswordToggle ? (
+          <TouchableOpacity
+            style={passwordToggleStyle}
+            onPress={togglePasswordVisibility}
+            disabled={disabled}
+            accessibilityLabel={isPasswordVisible ? 'Hide password' : 'Show password'}
+          >
+            <MaterialDesignIcons
+              name={isPasswordVisible ? 'eye-off' : 'eye'}
+              size={iconSize}
+              color={iconColor}
+            />
+          </TouchableOpacity>
+        ) : rightIcon ? (
+          <View style={rightIconContainerStyle}>
+            {renderRightIcon()}
+          </View>
+        ) : null}
+      </View>
+
+      {showFooter && (
+        <View style={footerStyle}>
+          <View style={{ flex: 1 }}>
+            {error && <Text style={helperTextStyle}>{error}</Text>}
+            {!error && helperText && <Text style={helperTextStyle}>{helperText}</Text>}
+          </View>
         </View>
-      ) : null}
+      )}
     </View>
   );
 });

package/src/TextInput/TextInput.styles.tsx

@@ -75,15 +75,6 @@ export const textInputStyles = defineStyle('TextInput', (theme: Theme) => ({
                 height: theme.sizes.$input.height,
                 paddingHorizontal: theme.sizes.$input.paddingHorizontal,
             },
-            margin: {
-                margin: theme.sizes.$view.padding,
-            },
-            marginVertical: {
-                marginVertical: theme.sizes.$view.padding,
-            },
-            marginHorizontal: {
-                marginHorizontal: theme.sizes.$view.padding,
-            },
         },
         _web: {
             boxSizing: 'border-box',
@@ -208,6 +199,53 @@ export const textInputStyles = defineStyle('TextInput', (theme: Theme) => ({
             },
         },
     }),
+
+    wrapper: (_props: TextInputDynamicProps) => ({
+        display: 'flex' as const,
+        flexDirection: 'column' as const,
+        gap: 4,
+        variants: {
+            margin: {
+                margin: theme.sizes.$view.padding,
+            },
+            marginVertical: {
+                marginVertical: theme.sizes.$view.padding,
+            },
+            marginHorizontal: {
+                marginHorizontal: theme.sizes.$view.padding,
+            },
+        },
+    }),
+
+    label: (_props: TextInputDynamicProps) => ({
+        fontSize: 14,
+        fontWeight: '500' as const,
+        color: theme.colors.text.primary,
+        variants: {
+            disabled: {
+                true: { opacity: 0.5 },
+                false: { opacity: 1 },
+            },
+        },
+    }),
+
+    helperText: (_props: TextInputDynamicProps) => ({
+        fontSize: 12,
+        variants: {
+            hasError: {
+                true: { color: theme.intents.danger.primary },
+                false: { color: theme.colors.text.secondary },
+            },
+        },
+    }),
+
+    footer: (_props: TextInputDynamicProps) => ({
+        display: 'flex' as const,
+        flexDirection: 'row' as const,
+        justifyContent: 'space-between' as const,
+        alignItems: 'center' as const,
+        gap: 4,
+    }),
 }));
 
 // Legacy export for backwards compatibility

package/src/TextInput/TextInput.web.tsx

@@ -6,7 +6,7 @@ import { isIconName } from '../Icon/icon-resolver';
 import useMergeRefs from '../hooks/useMergeRefs';
 import { textInputStyles } from './TextInput.styles';
 import { TextInputProps } from './types';
-import { getWebFormAriaProps } from '../utils/accessibility';
+import { getWebFormAriaProps, combineIds, generateAccessibilityId } from '../utils/accessibility';
 import type { IdealystElement } from '../utils/refTypes';
 import { flattenStyle } from '../utils/flattenStyle';
 
@@ -31,6 +31,9 @@ const TextInput = React.forwardRef<IdealystElement, TextInputProps>(({
   size = 'md',
   type = 'outlined',
   hasError = false,
+  error,
+  helperText,
+  label,
   // Spacing variants from FormInputStyleProps
   margin,
   marginVertical,
@@ -65,6 +68,18 @@ const TextInput = React.forwardRef<IdealystElement, TextInputProps>(({
   const isPasswordField = inputMode === 'password' || secureTextEntry;
   const shouldShowPasswordToggle = isPasswordField && (showPasswordToggle !== false);
 
+  // Derive hasError from error prop or hasError boolean
+  const computedHasError = Boolean(error) || hasError;
+
+  // Determine if we need a wrapper (when label, error, or helperText is present)
+  const needsWrapper = Boolean(label) || Boolean(error) || Boolean(helperText);
+
+  // Generate unique IDs for accessibility
+  const inputId = useMemo(() => id || generateAccessibilityId('textinput'), [id]);
+  const errorId = useMemo(() => `${inputId}-error`, [inputId]);
+  const helperId = useMemo(() => `${inputId}-helper`, [inputId]);
+  const labelId = useMemo(() => label ? `${inputId}-label` : undefined, [inputId, label]);
+
   // Get theme for icon sizes and colors
   const { theme } = useUnistyles();
   const iconSize = theme.sizes.input[size].iconSize;
@@ -138,7 +153,7 @@ const TextInput = React.forwardRef<IdealystElement, TextInputProps>(({
     size,
     type,
     focused: isFocused,
-    hasError,
+    hasError: computedHasError,
     disabled,
     margin,
     marginVertical,
@@ -146,19 +161,34 @@ const TextInput = React.forwardRef<IdealystElement, TextInputProps>(({
   });
 
   // Get web props for all styled elements (all styles are dynamic functions)
-  const dynamicContainerStyle = (textInputStyles.container as any)({ type, focused: isFocused, hasError, disabled });
-  const {ref: containerStyleRef, ...containerProps} = getWebProps([dynamicContainerStyle, flattenStyle(style)]);
+  const dynamicContainerStyle = (textInputStyles.container as any)({ type, focused: isFocused, hasError: computedHasError, disabled });
+  const {ref: containerStyleRef, ...containerProps} = getWebProps([dynamicContainerStyle, !needsWrapper && flattenStyle(style)].filter(Boolean));
   const leftIconContainerProps = getWebProps([(textInputStyles.leftIconContainer as any)({})]);
   const rightIconContainerProps = getWebProps([(textInputStyles.rightIconContainer as any)({})]);
   const passwordToggleProps = getWebProps([(textInputStyles.passwordToggle as any)({})]);
 
+  // Wrapper, label, and footer styles
+  const wrapperStyleComputed = (textInputStyles.wrapper as any)({});
+  const labelStyleComputed = (textInputStyles.label as any)({ disabled });
+  const footerStyleComputed = (textInputStyles.footer as any)({});
+  const helperTextStyleComputed = (textInputStyles.helperText as any)({ hasError: computedHasError });
+
+  const wrapperProps = getWebProps([wrapperStyleComputed, flattenStyle(style)]);
+  const labelProps = getWebProps([labelStyleComputed]);
+  const footerProps = getWebProps([footerStyleComputed]);
+  const helperTextProps = getWebProps([helperTextStyleComputed]);
+
   // Get input props
   const inputWebProps = getWebProps([(textInputStyles.input as any)({})]);
 
   // Generate accessibility props
   const ariaProps = useMemo(() => {
-    // Derive invalid state from hasError or explicit accessibilityInvalid
-    const isInvalid = accessibilityInvalid ?? hasError;
+    // Derive invalid state from computedHasError or explicit accessibilityInvalid
+    const isInvalid = accessibilityInvalid ?? computedHasError;
+    const describedByIds = combineIds(
+      accessibilityDescribedBy,
+      error ? errorId : helperText ? helperId : undefined
+    );
 
     return getWebFormAriaProps({
       accessibilityLabel,
@@ -166,8 +196,8 @@ const TextInput = React.forwardRef<IdealystElement, TextInputProps>(({
       accessibilityDisabled: accessibilityDisabled ?? disabled,
       accessibilityHidden,
       accessibilityRole: accessibilityRole ?? 'textbox',
-      accessibilityLabelledBy,
-      accessibilityDescribedBy,
+      accessibilityLabelledBy: accessibilityLabelledBy ?? labelId,
+      accessibilityDescribedBy: describedByIds,
       accessibilityControls,
       accessibilityExpanded,
       accessibilityPressed,
@@ -175,7 +205,7 @@ const TextInput = React.forwardRef<IdealystElement, TextInputProps>(({
       accessibilityHasPopup,
       accessibilityRequired,
       accessibilityInvalid: isInvalid,
-      accessibilityErrorMessage,
+      accessibilityErrorMessage: accessibilityErrorMessage ?? (error ? errorId : undefined),
       accessibilityAutoComplete,
     });
   }, [
@@ -186,7 +216,12 @@ const TextInput = React.forwardRef<IdealystElement, TextInputProps>(({
     accessibilityHidden,
     accessibilityRole,
     accessibilityLabelledBy,
+    labelId,
     accessibilityDescribedBy,
+    error,
+    errorId,
+    helperText,
+    helperId,
     accessibilityControls,
     accessibilityExpanded,
     accessibilityPressed,
@@ -194,7 +229,7 @@ const TextInput = React.forwardRef<IdealystElement, TextInputProps>(({
     accessibilityHasPopup,
     accessibilityRequired,
     accessibilityInvalid,
-    hasError,
+    computedHasError,
     accessibilityErrorMessage,
     accessibilityAutoComplete,
   ]);
@@ -257,57 +292,134 @@ const TextInput = React.forwardRef<IdealystElement, TextInputProps>(({
 
   const containerRef = useRef<HTMLDivElement>(null);
 
-    const handleContainerPress = (e: React.MouseEvent<HTMLDivElement>) => {
+  const handleContainerPress = (e: React.MouseEvent<HTMLDivElement>) => {
     e.preventDefault();
     e.stopPropagation();
     containerRef.current?.focus();
-  }
+  };
 
   const mergedContainerRef = useMergeRefs(containerRef, containerStyleRef);
 
+  const showFooter = Boolean(error) || Boolean(helperText);
+
+  // If no wrapper needed, return flat input container
+  if (!needsWrapper) {
+    return (
+      <div onClick={handleContainerPress} ref={mergedContainerRef} {...containerProps} id={id} data-testid={testID}>
+        {/* Left Icon */}
+        {leftIcon && (
+          <span {...leftIconContainerProps}>
+            {renderLeftIcon()}
+          </span>
+        )}
+
+        {/* Input */}
+        <input
+          {...inputWebProps}
+          {...ariaProps}
+          id={inputId}
+          ref={mergedInputRef}
+          type={getInputType()}
+          value={value}
+          onClick={handlePress}
+          onChange={handleChange}
+          onFocus={handleFocus}
+          onBlur={handleBlur}
+          onKeyDown={handleKeyDown}
+          placeholder={placeholder}
+          disabled={disabled}
+          autoCapitalize={autoCapitalize}
+        />
+
+        {/* Right Icon or Password Toggle */}
+        {shouldShowPasswordToggle ? (
+          <button
+            {...passwordToggleProps}
+            onClick={togglePasswordVisibility}
+            disabled={disabled}
+            aria-label={isPasswordVisible ? 'Hide password' : 'Show password'}
+            type="button"
+            tabIndex={-1}
+          >
+            {renderPasswordToggleIcon()}
+          </button>
+        ) : rightIcon ? (
+          <span {...rightIconContainerProps}>
+            {renderRightIcon()}
+          </span>
+        ) : null}
+      </div>
+    );
+  }
+
+  // With wrapper for label/error/helperText
   return (
-    <div onClick={handleContainerPress} ref={mergedContainerRef} {...containerProps} id={id} data-testid={testID}>
-      {/* Left Icon */}
-      {leftIcon && (
-        <span {...leftIconContainerProps}>
-          {renderLeftIcon()}
-        </span>
+    <div {...wrapperProps} id={id} data-testid={testID}>
+      {label && (
+        <label {...labelProps} id={labelId} htmlFor={inputId}>{label}</label>
       )}
 
-      {/* Input */}
-      <input
-        {...inputWebProps}
-        {...ariaProps}
-        ref={mergedInputRef}
-        type={getInputType()}
-        value={value}
-        onClick={handlePress}
-        onChange={handleChange}
-        onFocus={handleFocus}
-        onBlur={handleBlur}
-        onKeyDown={handleKeyDown}
-        placeholder={placeholder}
-        disabled={disabled}
-        autoCapitalize={autoCapitalize}
-      />
-
-      {/* Right Icon or Password Toggle */}
-      {shouldShowPasswordToggle ? (
-        <button
-          {...passwordToggleProps}
-          onClick={togglePasswordVisibility}
+      <div onClick={handleContainerPress} ref={mergedContainerRef} {...containerProps}>
+        {/* Left Icon */}
+        {leftIcon && (
+          <span {...leftIconContainerProps}>
+            {renderLeftIcon()}
+          </span>
+        )}
+
+        {/* Input */}
+        <input
+          {...inputWebProps}
+          {...ariaProps}
+          id={inputId}
+          ref={mergedInputRef}
+          type={getInputType()}
+          value={value}
+          onClick={handlePress}
+          onChange={handleChange}
+          onFocus={handleFocus}
+          onBlur={handleBlur}
+          onKeyDown={handleKeyDown}
+          placeholder={placeholder}
           disabled={disabled}
-          aria-label={isPasswordVisible ? 'Hide password' : 'Show password'}
-          type="button"
-          tabIndex={-1}
-        >
-          {renderPasswordToggleIcon()}
-        </button>
-      ) : rightIcon ? (
-        <span {...rightIconContainerProps}>
-          {renderRightIcon()}
-        </span>
-      ) : null}
+          autoCapitalize={autoCapitalize}
+        />
+
+        {/* Right Icon or Password Toggle */}
+        {shouldShowPasswordToggle ? (
+          <button
+            {...passwordToggleProps}
+            onClick={togglePasswordVisibility}
+            disabled={disabled}
+            aria-label={isPasswordVisible ? 'Hide password' : 'Show password'}
+            type="button"
+            tabIndex={-1}
+          >
+            {renderPasswordToggleIcon()}
+          </button>
+        ) : rightIcon ? (
+          <span {...rightIconContainerProps}>
+            {renderRightIcon()}
+          </span>
+        ) : null}
+      </div>
+
+      {showFooter && (
+        <div {...footerProps}>
+          <div style={{ flex: 1 }}>
+            {error && (
+              <span {...helperTextProps} id={errorId} role="alert">
+                {error}
+              </span>
+            )}
+            {!error && helperText && (
+              <span {...helperTextProps} id={helperId}>
+                {helperText}
+              </span>
+            )}
+          </div>
+        </div>
+      )}
     </div>
   );
 });

package/src/TextInput/types.ts

@@ -167,10 +167,25 @@ export interface TextInputProps extends FormInputStyleProps, FormAccessibilityPr
 
   /**
    * Whether the input has an error state
-   * @deprecated Use intent="danger" instead
+   * @deprecated Use error prop or intent="danger" instead
    */
   hasError?: boolean;
 
+  /**
+   * Error message to display below the input. When set, the input shows error styling.
+   */
+  error?: string;
+
+  /**
+   * Helper text to display below the input. Hidden when error is set.
+   */
+  helperText?: string;
+
+  /**
+   * Label text to display above the input
+   */
+  label?: string;
+
   /**
    * Called when the user submits the input (presses Enter on web, or the return key on mobile).
    * Use this for form submission or moving to the next field.

package/src/index.native.ts

@@ -119,6 +119,9 @@ export * from './Platform/types';
 export { Keyboard } from './Keyboard';
 export * from './Keyboard/types';
 
+export { default as Form, useForm } from './Form';
+export * from './Form/types';
+
 export type { ButtonProps } from './Button/types';
 export type { IconButtonProps } from './IconButton/types';
 export type { TextProps } from './Text/types';
@@ -165,6 +168,22 @@ export type {
   KeyboardSubscription,
   KeyboardStatic,
 } from './Keyboard/types';
+export type {
+  FormProps,
+  UseFormOptions,
+  UseFormReturn,
+  FormValues,
+  FormErrors,
+  FormTextInputProps,
+  FormTextAreaProps,
+  FormSelectProps,
+  FormCheckboxProps,
+  FormRadioGroupProps,
+  FormSwitchProps,
+  FormSliderProps,
+  FormFieldProps,
+  FieldRenderProps,
+} from './Form/types';
 
 // Event utilities
 export * from './utils/events';