@erquhart/heroui-native 1.0.0-beta.10.1

package/src/components/form-field/form-field.animation.ts

@@ -0,0 +1,18 @@
+import { useCombinedAnimationDisabledState } from '../../helpers/hooks';
+import type { AnimationRootDisableAll } from '../../helpers/types/animation';
+
+/**
+ * Animation hook for FormField root component
+ * Handles root-level animation configuration and provides context for child components
+ */
+export function useFormFieldRootAnimation(options: {
+  animation: AnimationRootDisableAll | undefined;
+}) {
+  const { animation } = options;
+
+  const isAllAnimationsDisabled = useCombinedAnimationDisabledState(animation);
+
+  return {
+    isAllAnimationsDisabled,
+  };
+}

package/src/components/form-field/form-field.constants.ts

@@ -0,0 +1,10 @@
+/**
+ * Display names for FormField components
+ */
+export const DISPLAY_NAME = {
+  FORM_FIELD: 'HeroUINative.FormField',
+  FORM_FIELD_LABEL: 'HeroUINative.FormField.Label',
+  FORM_FIELD_DESCRIPTION: 'HeroUINative.FormField.Description',
+  FORM_FIELD_INDICATOR: 'HeroUINative.FormField.Indicator',
+  FORM_FIELD_ERROR_MESSAGE: 'HeroUINative.FormField.ErrorMessage',
+} as const;

package/src/components/form-field/form-field.context.ts

@@ -0,0 +1,13 @@
+import { createContext } from '../../helpers/utils';
+import type { FormFieldContextValue } from './form-field.types';
+
+/**
+ * FormField context provider and hook
+ * Extracted to separate file to avoid circular dependencies with Checkbox/Switch animation files
+ */
+const [FormFieldProvider, useFormField] = createContext<FormFieldContextValue>({
+  name: 'FormFieldContext',
+  strict: false,
+});
+
+export { FormFieldProvider, useFormField };

package/src/components/form-field/form-field.md

@@ -0,0 +1,243 @@
+# FormField
+
+Provides consistent layout and interaction for form controls with label, description, and error handling. Perfect for Switch and Checkbox components when you want the entire field to be pressable.
+
+## Imports
+
+Note: Before importing this component, ensure you have completed the setup as per the [Quick Start guide](../../../README.md).
+
+```tsx
+import { FormField } from 'heroui-native';
+```
+
+## Usage
+
+### Basic Usage
+
+FormField wraps form controls to provide consistent layout and state management.
+
+```tsx
+<FormField isSelected={value} onSelectedChange={setValue}>
+  <View className="flex-1">
+    <FormField.Label>Label text</FormField.Label>
+  </View>
+  <FormField.Indicator />
+</FormField>
+```
+
+### With Description
+
+Add helper text below the label using the Description component.
+
+```tsx
+<FormField isSelected={value} onSelectedChange={setValue}>
+  <View className="flex-1">
+    <FormField.Label>Enable notifications</FormField.Label>
+    <FormField.Description>
+      Receive push notifications about your account activity
+    </FormField.Description>
+  </View>
+  <FormField.Indicator />
+</FormField>
+```
+
+### With Error Message
+
+Display validation errors using the ErrorMessage component.
+
+```tsx
+<FormField
+  isSelected={value}
+  onSelectedChange={setValue}
+  isInvalid={!value}
+  className="flex-col items-start gap-1"
+>
+  <View className="flex-row items-center gap-2">
+    <View className="flex-1">
+      <FormField.Label>I agree to the terms</FormField.Label>
+      <FormField.Description>
+        By checking this box, you agree to our Terms of Service
+      </FormField.Description>
+    </View>
+    <FormField.Indicator variant="checkbox" />
+  </View>
+  <FormField.ErrorMessage>This field is required</FormField.ErrorMessage>
+</FormField>
+```
+
+### Disabled State
+
+Control interactivity with the disabled prop.
+
+```tsx
+<FormField isSelected={value} onSelectedChange={setValue} isDisabled>
+  <View className="flex-1">
+    <FormField.Label>Disabled field</FormField.Label>
+    <FormField.Description>This field is disabled</FormField.Description>
+  </View>
+  <FormField.Indicator />
+</FormField>
+```
+
+### Disabling All Animations
+
+Disable all animations including children by using `"disable-all"`. This cascades down to all child components.
+
+```tsx
+<FormField
+  isSelected={value}
+  onSelectedChange={setValue}
+  animation="disable-all"
+>
+  <View className="flex-1">
+    <FormField.Label>Label text</FormField.Label>
+    <FormField.Description>Description text</FormField.Description>
+  </View>
+  <FormField.Indicator />
+</FormField>
+```
+
+## Example
+
+```tsx
+import { Checkbox, FormField, Switch } from 'heroui-native';
+import React from 'react';
+import { ScrollView, View } from 'react-native';
+
+export default function FormFieldExample() {
+  const [notifications, setNotifications] = React.useState(false);
+  const [terms, setTerms] = React.useState(false);
+  const [newsletter, setNewsletter] = React.useState(true);
+
+  return (
+    <ScrollView className="bg-background p-4">
+      <View className="gap-4">
+        <FormField
+          isSelected={notifications}
+          onSelectedChange={setNotifications}
+        >
+          <View className="flex-1">
+            <FormField.Label>Enable notifications</FormField.Label>
+            <FormField.Description>
+              Receive push notifications about your account activity
+            </FormField.Description>
+          </View>
+          <FormField.Indicator />
+        </FormField>
+
+        <FormField
+          isSelected={terms}
+          onSelectedChange={setTerms}
+          isInvalid={!terms}
+          className="flex-col items-start gap-1"
+        >
+          <View className="flex-row items-center gap-2">
+            <View className="flex-1">
+              <FormField.Label>
+                I agree to the terms and conditions
+              </FormField.Label>
+              <FormField.Description>
+                By checking this box, you agree to our Terms of Service
+              </FormField.Description>
+            </View>
+            <FormField.Indicator className="mt-0.5">
+              <Checkbox />
+            </FormField.Indicator>
+          </View>
+          <FormField.ErrorMessage>
+            This field is required
+          </FormField.ErrorMessage>
+        </FormField>
+
+        <FormField isSelected={newsletter} onSelectedChange={setNewsletter}>
+          <View className="flex-1">
+            <FormField.Label>Subscribe to newsletter</FormField.Label>
+          </View>
+          <FormField.Indicator>
+            <Checkbox color="warning" />
+          </FormField.Indicator>
+        </FormField>
+      </View>
+    </ScrollView>
+  );
+}
+```
+
+## Anatomy
+
+```tsx
+<FormField>
+  <FormField.Label>...</FormField.Label>
+  <FormField.Description>...</FormField.Description>
+  <FormField.Indicator>...</FormField.Indicator>
+  <FormField.ErrorMessage>...</FormField.ErrorMessage>
+</FormField>
+```
+
+- **FormField**: Root container that manages layout and state propagation
+- **FormField.Label**: Primary text label for the control
+- **FormField.Description**: Secondary descriptive helper text
+- **FormField.Indicator**: Container for the form control component (Switch, Checkbox)
+- **FormField.ErrorMessage**: Validation error message display
+
+## API Reference
+
+### FormField
+
+| prop              | type                                                                    | default     | description                                                                               |
+| ----------------- | ----------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| children          | `React.ReactNode \| ((props: FormFieldRenderProps) => React.ReactNode)` | -           | Content to render inside the form control, or a render function                           |
+| isSelected        | `boolean`                                                               | `undefined` | Whether the control is selected/checked                                                   |
+| isDisabled        | `boolean`                                                               | `false`     | Whether the form control is disabled                                                      |
+| isInvalid         | `boolean`                                                               | `false`     | Whether the form control is invalid                                                       |
+| className         | `string`                                                                | -           | Custom class name for the root element                                                    |
+| onSelectedChange  | `(isSelected: boolean) => void`                                         | -           | Callback when selection state changes                                                     |
+| animation         | `"disable-all" \| undefined`                                            | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children |
+| ...PressableProps | `PressableProps`                                                        | -           | All React Native Pressable props are supported                                            |
+
+### FormField.Label
+
+| prop         | type              | default | description                               |
+| ------------ | ----------------- | ------- | ----------------------------------------- |
+| children     | `React.ReactNode` | -       | Label text content                        |
+| className    | `string`          | -       | Custom class name for the label element   |
+| ...TextProps | `TextProps`       | -       | All React Native Text props are supported |
+
+### FormField.Description
+
+| prop         | type              | default | description                                   |
+| ------------ | ----------------- | ------- | --------------------------------------------- |
+| children     | `React.ReactNode` | -       | Description text content                      |
+| className    | `string`          | -       | Custom class name for the description element |
+| ...TextProps | `TextProps`       | -       | All React Native Text props are supported     |
+
+### FormField.Indicator
+
+| prop         | type                     | default    | description                                                |
+| ------------ | ------------------------ | ---------- | ---------------------------------------------------------- |
+| children     | `React.ReactNode`        | -          | Control component to render (Switch, Checkbox)             |
+| variant      | `'checkbox' \| 'switch'` | `'switch'` | Variant of the control to render when no children provided |
+| className    | `string`                 | -          | Custom class name for the indicator element                |
+| ...ViewProps | `ViewProps`              | -          | All React Native View props are supported                  |
+
+**Note**: When children are provided, the component automatically passes down `isSelected`, `onSelectedChange`, `isDisabled`, and `isInvalid` props from the FormField context if they are not already present on the child component.
+
+### FormField.ErrorMessage
+
+FormField.ErrorMessage extends all props from [ErrorView](../error-view/error-view.md) component.
+
+**Note**: The `isInvalid` prop is automatically passed from the FormField context. The error message visibility is controlled by the `isInvalid` state of the parent FormField.
+
+## Hooks
+
+### useFormField
+
+**Returns:**
+
+| property           | type                                           | description                                    |
+| ------------------ | ---------------------------------------------- | ---------------------------------------------- |
+| `isSelected`       | `boolean \| undefined`                         | Whether the control is selected/checked        |
+| `onSelectedChange` | `((isSelected: boolean) => void) \| undefined` | Callback when selection state changes          |
+| `isDisabled`       | `boolean`                                      | Whether the form control is disabled           |
+| `isInvalid`        | `boolean`                                      | Whether the form control is invalid            |
+| `isPressed`        | `SharedValue<boolean>`                         | Reanimated shared value indicating press state |

package/src/components/form-field/form-field.styles.ts

@@ -0,0 +1,40 @@
+import { tv } from 'tailwind-variants';
+import { combineStyles } from '../../helpers/theme/utils/combine-styles';
+
+const root = tv({
+  base: 'flex-row items-center gap-3',
+  variants: {
+    isDisabled: {
+      true: 'opacity-disabled pointer-events-none',
+    },
+  },
+  defaultVariants: {
+    isDisabled: false,
+  },
+});
+
+const title = tv({
+  base: 'text-base font-medium text-foreground',
+});
+
+const description = tv({
+  base: 'text-sm text-muted',
+});
+
+const indicator = tv({
+  base: '',
+});
+
+const errorMessage = tv({
+  base: '',
+});
+
+const formFieldStyles = combineStyles({
+  root,
+  title,
+  description,
+  indicator,
+  errorMessage,
+});
+
+export default formFieldStyles;

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

@@ -0,0 +1,301 @@
+import React, { cloneElement, forwardRef, useCallback, useMemo } from 'react';
+import {
+  Pressable,
+  Text as RNText,
+  View,
+  type GestureResponderEvent,
+} from 'react-native';
+import { hasProp } from '../../helpers/utils';
+
+import { useSharedValue } from 'react-native-reanimated';
+import { HeroText } from '../../helpers/components/hero-text';
+import { AnimationSettingsProvider } from '../../helpers/contexts/animation-settings-context';
+import type { PressableRef } from '../../helpers/types';
+import type { ViewRef } from '../../helpers/types/primitives';
+import { Checkbox } from '../checkbox';
+import { ErrorView } from '../error-view';
+import type { ErrorViewRootProps } from '../error-view/error-view.types';
+import { Switch } from '../switch';
+import { useFormFieldRootAnimation } from './form-field.animation';
+import { DISPLAY_NAME } from './form-field.constants';
+import { FormFieldProvider, useFormField } from './form-field.context';
+import formFieldStyles from './form-field.styles';
+import type {
+  FormFieldContextValue,
+  FormFieldDescriptionProps,
+  FormFieldIndicatorProps,
+  FormFieldLabelProps,
+  FormFieldProps,
+  FormFieldRenderProps,
+} from './form-field.types';
+
+// --------------------------------------------------
+
+const FormField = forwardRef<PressableRef, FormFieldProps>((props, ref) => {
+  const {
+    children,
+    className,
+    isSelected,
+    onSelectedChange,
+    isDisabled = false,
+    isInvalid = false,
+    onPressIn,
+    onPressOut,
+    animation,
+    ...restProps
+  } = props;
+
+  const renderProps: FormFieldRenderProps = useMemo(
+    () => ({
+      isSelected,
+      isDisabled: isDisabled ?? false,
+      isInvalid: isInvalid ?? false,
+    }),
+    [isSelected, isDisabled, isInvalid]
+  );
+
+  const content =
+    typeof children === 'function' ? children(renderProps) : children;
+
+  const tvStyles = formFieldStyles.root({
+    isDisabled,
+    className,
+  });
+
+  const { isAllAnimationsDisabled } = useFormFieldRootAnimation({
+    animation,
+  });
+
+  const animationSettingsContextValue = useMemo(
+    () => ({
+      isAllAnimationsDisabled,
+    }),
+    [isAllAnimationsDisabled]
+  );
+
+  const isPressed = useSharedValue<boolean>(false);
+
+  const handlePress = (e: GestureResponderEvent) => {
+    if (!isDisabled && onSelectedChange && isSelected !== undefined) {
+      onSelectedChange(!isSelected);
+
+      if (props.onPress && typeof props.onPress === 'function') {
+        props.onPress(e);
+      }
+    }
+  };
+
+  const handlePressIn = useCallback(
+    (e: GestureResponderEvent) => {
+      isPressed.set(true);
+      if (onPressIn && typeof onPressIn === 'function') {
+        onPressIn(e);
+      }
+    },
+    [isPressed, onPressIn]
+  );
+
+  const handlePressOut = useCallback(
+    (e: GestureResponderEvent) => {
+      isPressed.set(false);
+      if (onPressOut && typeof onPressOut === 'function') {
+        onPressOut(e);
+      }
+    },
+    [isPressed, onPressOut]
+  );
+
+  const contextValue: FormFieldContextValue = useMemo(
+    () => ({
+      isSelected,
+      onSelectedChange,
+      isDisabled,
+      isInvalid,
+      isPressed,
+    }),
+    [isSelected, onSelectedChange, isDisabled, isInvalid, isPressed]
+  );
+
+  return (
+    <AnimationSettingsProvider value={animationSettingsContextValue}>
+      <FormFieldProvider value={contextValue}>
+        <Pressable
+          ref={ref}
+          className={tvStyles}
+          onPress={handlePress}
+          onPressIn={handlePressIn}
+          onPressOut={handlePressOut}
+          disabled={isDisabled}
+          {...restProps}
+        >
+          {content}
+        </Pressable>
+      </FormFieldProvider>
+    </AnimationSettingsProvider>
+  );
+});
+
+// --------------------------------------------------
+
+const FormFieldLabel = forwardRef<RNText, FormFieldLabelProps>((props, ref) => {
+  const { children, className, ...restProps } = props;
+
+  const tvStyles = formFieldStyles.title({
+    className,
+  });
+
+  return (
+    <HeroText ref={ref} className={tvStyles} {...restProps}>
+      {children}
+    </HeroText>
+  );
+});
+
+// --------------------------------------------------
+
+const FormFieldDescription = forwardRef<RNText, FormFieldDescriptionProps>(
+  (props, ref) => {
+    const { children, className, ...restProps } = props;
+
+    const tvStyles = formFieldStyles.description({
+      className,
+    });
+
+    return (
+      <HeroText ref={ref} className={tvStyles} {...restProps}>
+        {children}
+      </HeroText>
+    );
+  }
+);
+
+// --------------------------------------------------
+
+const FormFieldIndicator = forwardRef<View, FormFieldIndicatorProps>(
+  (props, ref) => {
+    const { children, className, variant = 'switch', ...restProps } = props;
+    const { isSelected, onSelectedChange, isDisabled, isInvalid } =
+      useFormField();
+
+    const tvStyles = formFieldStyles.indicator({
+      className,
+    });
+
+    const enhancedChildren = useMemo(() => {
+      if (children) {
+        if (typeof children !== 'object') return children;
+
+        const child = children as React.ReactElement;
+
+        return cloneElement(child, {
+          // Only pass props from context if child doesn't already have them
+          ...(isSelected !== undefined &&
+            !hasProp(child, 'isSelected') && { isSelected }),
+          ...(onSelectedChange &&
+            !hasProp(child, 'onSelectedChange') && { onSelectedChange }),
+          ...(isDisabled !== undefined &&
+            !hasProp(child, 'isDisabled') && { isDisabled }),
+          ...(isInvalid !== undefined &&
+            !hasProp(child, 'isInvalid') && { isInvalid }),
+        });
+      }
+
+      // Render default component based on variant when no children provided
+      if (variant === 'checkbox') {
+        return (
+          <Checkbox
+            isSelected={isSelected}
+            onSelectedChange={onSelectedChange}
+            isDisabled={isDisabled}
+            isInvalid={isInvalid}
+          />
+        );
+      }
+
+      return (
+        <Switch
+          isSelected={isSelected}
+          onSelectedChange={onSelectedChange}
+          isDisabled={isDisabled}
+        />
+      );
+    }, [
+      children,
+      variant,
+      isSelected,
+      onSelectedChange,
+      isDisabled,
+      isInvalid,
+    ]);
+
+    return (
+      <View ref={ref} className={tvStyles} {...restProps}>
+        {enhancedChildren}
+      </View>
+    );
+  }
+);
+
+// --------------------------------------------------
+
+const FormFieldErrorMessage = forwardRef<ViewRef, ErrorViewRootProps>(
+  (props, ref) => {
+    const { isInvalid } = useFormField();
+    const { className, ...restProps } = props;
+
+    const tvStyles = formFieldStyles.errorMessage({
+      className,
+    });
+
+    return (
+      <ErrorView
+        ref={ref}
+        isInvalid={isInvalid}
+        className={tvStyles}
+        {...restProps}
+      />
+    );
+  }
+);
+
+// --------------------------------------------------
+
+FormField.displayName = DISPLAY_NAME.FORM_FIELD;
+FormFieldLabel.displayName = DISPLAY_NAME.FORM_FIELD_LABEL;
+FormFieldDescription.displayName = DISPLAY_NAME.FORM_FIELD_DESCRIPTION;
+FormFieldIndicator.displayName = DISPLAY_NAME.FORM_FIELD_INDICATOR;
+FormFieldErrorMessage.displayName = DISPLAY_NAME.FORM_FIELD_ERROR_MESSAGE;
+
+/**
+ * Compound FormField component with sub-components
+ *
+ * @component FormField - Wrapper that provides consistent layout and interaction for form controls.
+ * Handles press events to toggle selection state and manages disabled states.
+ *
+ * @component FormField.Label - Primary text label for the form control. Renders as
+ * Text component when children is a string.
+ *
+ * @component FormField.Description - Secondary descriptive text. Renders as Text
+ * component when children is a string.
+ *
+ * @component FormField.Indicator - Container for the control component (Switch, Checkbox).
+ * Automatically passes down isSelected, onSelectedChange, isDisabled, and isInvalid props.
+ *
+ * @component FormField.ErrorMessage - Error message displayed when field is invalid.
+ * Shown with animation below the form field content.
+ *
+ * Props flow from FormField to sub-components via context.
+ */
+const CompoundFormField = Object.assign(FormField, {
+  /** @optional Primary text label */
+  Label: FormFieldLabel,
+  /** @optional Secondary descriptive text */
+  Description: FormFieldDescription,
+  /** @optional Container for control component */
+  Indicator: FormFieldIndicator,
+  /** @optional Error message displayed when field is invalid */
+  ErrorMessage: FormFieldErrorMessage,
+});
+
+export { useFormField } from './form-field.context';
+export default CompoundFormField;