@coze-arch/cli 0.0.1-alpha.3002ee → 0.0.1-alpha.3260db

package/lib/__templates__/expo/client/heroui/components/control-field/control-field.md

@@ -0,0 +1,241 @@
+# ControlField
+
+A field component that combines a label, description (or other content), and a control component (Switch, Checkbox, or Radio) into a single pressable area.
+
+## Import
+
+```tsx
+import { ControlField } from '@/heroui';
+```
+
+## Anatomy
+
+```tsx
+<ControlField>
+  <Label>...</Label>
+  <Description>...</Description>
+  <ControlField.Indicator>...</ControlField.Indicator>
+  <FieldError>...</FieldError>
+</ControlField>
+```
+
+- **ControlField**: Root container that manages layout and state propagation
+- **Label**: Primary text label for the control (from [Label](../label/label.md) component)
+- **Description**: Secondary descriptive helper text (from [Description](../description/description.md) component)
+- **ControlField.Indicator**: Container for the form control component ([Switch](../switch/switch.md), [Checkbox](../checkbox/checkbox.md), [Radio](../radio/radio.md))
+- **FieldError**: Validation error message display (from [FieldError](../field-error/field-error.md) component)
+
+## Usage
+
+### Basic Usage
+
+ControlField wraps form controls to provide consistent layout and state management.
+
+```tsx
+<ControlField isSelected={value} onSelectedChange={setValue}>
+  <Label className="flex-1">Label text</Label>
+  <ControlField.Indicator />
+</ControlField>
+```
+
+### With Description
+
+Add helper text below the label using the Description component.
+
+```tsx
+<ControlField isSelected={value} onSelectedChange={setValue}>
+  <View className="flex-1">
+    <Label>Enable notifications</Label>
+    <Description>
+      Receive push notifications about your account activity
+    </Description>
+  </View>
+  <ControlField.Indicator />
+</ControlField>
+```
+
+### With Error Message
+
+Display validation errors using the ErrorMessage component.
+
+```tsx
+<ControlField
+  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">
+      <Label>I agree to the terms</Label>
+      <Description>
+        By checking this box, you agree to our Terms of Service
+      </Description>
+    </View>
+    <ControlField.Indicator variant="checkbox" />
+  </View>
+  <FieldError>This field is required</FieldError>
+</ControlField>
+```
+
+### Disabled State
+
+Control interactivity with the disabled prop.
+
+```tsx
+<ControlField isSelected={value} onSelectedChange={setValue} isDisabled>
+  <View className="flex-1">
+    <Label>Disabled field</Label>
+    <Description>This field is disabled</Description>
+  </View>
+  <ControlField.Indicator />
+</ControlField>
+```
+
+### Disabling All Animations
+
+Disable all animations including children by using `"disable-all"`. This cascades down to all child components.
+
+```tsx
+<ControlField
+  isSelected={value}
+  onSelectedChange={setValue}
+  animation="disable-all"
+>
+  <View className="flex-1">
+    <Label>Label text</Label>
+    <Description>Description text</Description>
+  </View>
+  <ControlField.Indicator />
+</ControlField>
+```
+
+## Example
+
+```tsx
+import {
+  Checkbox,
+  Description,
+  FieldError,
+  ControlField,
+  Label,
+  Switch,
+} from '@/heroui';
+import React from 'react';
+import { ScrollView, View } from 'react-native';
+
+export default function ControlFieldExample() {
+  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">
+        <ControlField
+          isSelected={notifications}
+          onSelectedChange={setNotifications}
+        >
+          <View className="flex-1">
+            <Label>Enable notifications</Label>
+            <Description>
+              Receive push notifications about your account activity
+            </Description>
+          </View>
+          <ControlField.Indicator />
+        </ControlField>
+
+        <ControlField
+          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">
+              <Label>I agree to the terms and conditions</Label>
+              <Description>
+                By checking this box, you agree to our Terms of Service
+              </Description>
+            </View>
+            <ControlField.Indicator className="mt-0.5">
+              <Checkbox />
+            </ControlField.Indicator>
+          </View>
+          <FieldError>This field is required</FieldError>
+        </ControlField>
+
+        <ControlField isSelected={newsletter} onSelectedChange={setNewsletter}>
+          <View className="flex-1">
+            <Label>Subscribe to newsletter</Label>
+          </View>
+          <ControlField.Indicator>
+            <Checkbox color="warning" />
+          </ControlField.Indicator>
+        </ControlField>
+      </View>
+    </ScrollView>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/(home)/components/control-field.tsx>).
+
+## API Reference
+
+### ControlField
+
+| prop              | type                                                                       | default     | description                                                                               |
+| ----------------- | -------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| children          | `React.ReactNode \| ((props: ControlFieldRenderProps) => 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                                                       |
+| isRequired        | `boolean`                                                                  | `false`     | Whether the form control is required                                                      |
+| 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                                            |
+
+### Label
+
+The `Label` component automatically consumes form state (`isDisabled`, `isInvalid`) from the ControlField context.
+
+**Note**: For complete prop documentation, see the [Label component documentation](../label/label.md).
+
+### Description
+
+The `Description` component automatically consumes form state (`isDisabled`, `isInvalid`) from the ControlField context.
+
+**Note**: For complete prop documentation, see the [Description component documentation](../description/description.md).
+
+### ControlField.Indicator
+
+| prop         | type                                | default    | description                                                |
+| ------------ | ----------------------------------- | ---------- | ---------------------------------------------------------- |
+| children     | `React.ReactNode`                   | -          | Control component to render (Switch, Checkbox, Radio)      |
+| variant      | `'checkbox' \| 'radio' \| '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 ControlField context if they are not already present on the child component. When using the `radio` variant, the Radio component renders in standalone mode (outside of a RadioGroup).
+
+### FieldError
+
+The `FieldError` component automatically consumes form state (`isInvalid`) from the ControlField context.
+
+**Note**: For complete prop documentation, see the [FieldError component documentation](../field-error/field-error.md). The error message visibility is controlled by the `isInvalid` state of the parent ControlField.
+
+## Hooks
+
+### useControlField
+
+**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/lib/__templates__/expo/client/heroui/components/control-field/control-field.styles.ts

@@ -0,0 +1,15 @@
+import { tv } from 'tailwind-variants';
+import { combineStyles } from '../../helpers/internal/utils';
+
+const root = tv({
+  base: 'flex-row items-center gap-3',
+});
+
+const indicator = tv({
+  base: '',
+});
+
+export const controlFieldClassNames = combineStyles({
+  root,
+  indicator,
+});

package/lib/__templates__/expo/client/heroui/components/control-field/control-field.tsx

@@ -0,0 +1,245 @@
+import React, { cloneElement, forwardRef, useCallback, useMemo } from 'react';
+import { Pressable, View, type GestureResponderEvent } from 'react-native';
+import { hasProp } from '../../helpers/internal/utils';
+
+import { useSharedValue } from 'react-native-reanimated';
+import {
+  AnimationSettingsProvider,
+  FormFieldProvider,
+} from '../../helpers/internal/contexts';
+import type { PressableRef } from '../../helpers/internal/types';
+import { Checkbox } from '../checkbox';
+import { Radio } from '../radio';
+import { Switch } from '../switch';
+import { useControlFieldRootAnimation } from './control-field.animation';
+import { DISPLAY_NAME } from './control-field.constants';
+import { ControlFieldProvider, useControlField } from './control-field.context';
+import { controlFieldClassNames } from './control-field.styles';
+import type {
+  ControlFieldContextValue,
+  ControlFieldIndicatorProps,
+  ControlFieldProps,
+  ControlFieldRenderProps,
+} from './control-field.types';
+
+// --------------------------------------------------
+
+const ControlField = forwardRef<PressableRef, ControlFieldProps>(
+  (props, ref) => {
+    const {
+      children,
+      className,
+      isSelected,
+      onSelectedChange,
+      isDisabled = false,
+      isInvalid = false,
+      isRequired = false,
+      onPressIn,
+      onPressOut,
+      animation,
+      ...restProps
+    } = props;
+
+    const renderProps: ControlFieldRenderProps = useMemo(
+      () => ({
+        isSelected,
+        isDisabled: isDisabled ?? false,
+        isInvalid: isInvalid ?? false,
+      }),
+      [isSelected, isDisabled, isInvalid]
+    );
+
+    const content =
+      typeof children === 'function' ? children(renderProps) : children;
+
+    const rootClassName = controlFieldClassNames.root({
+      className,
+    });
+
+    const { isAllAnimationsDisabled } = useControlFieldRootAnimation({
+      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: ControlFieldContextValue = useMemo(
+      () => ({
+        isSelected,
+        onSelectedChange,
+        isDisabled,
+        isInvalid,
+        isPressed,
+      }),
+      [isSelected, onSelectedChange, isDisabled, isInvalid, isPressed]
+    );
+
+    const formFieldContextValue = useMemo(
+      () => ({
+        isDisabled: isDisabled ?? false,
+        isInvalid: isInvalid ?? false,
+        isRequired: isRequired ?? false,
+        hasFieldPadding: false,
+      }),
+      [isDisabled, isInvalid, isRequired]
+    );
+
+    return (
+      <AnimationSettingsProvider value={animationSettingsContextValue}>
+        <FormFieldProvider value={formFieldContextValue}>
+          <ControlFieldProvider value={contextValue}>
+            <Pressable
+              ref={ref}
+              className={rootClassName}
+              onPress={handlePress}
+              onPressIn={handlePressIn}
+              onPressOut={handlePressOut}
+              disabled={isDisabled}
+              {...restProps}
+            >
+              {content}
+            </Pressable>
+          </ControlFieldProvider>
+        </FormFieldProvider>
+      </AnimationSettingsProvider>
+    );
+  }
+);
+
+// --------------------------------------------------
+
+const ControlFieldIndicator = forwardRef<View, ControlFieldIndicatorProps>(
+  (props, ref) => {
+    const { children, className, variant = 'switch', ...restProps } = props;
+    const { isSelected, onSelectedChange, isDisabled, isInvalid } =
+      useControlField();
+
+    const indicatorClassName = controlFieldClassNames.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}
+          />
+        );
+      }
+
+      if (variant === 'radio') {
+        return (
+          <Radio
+            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={indicatorClassName} {...restProps}>
+        {enhancedChildren}
+      </View>
+    );
+  }
+);
+
+// --------------------------------------------------
+
+ControlField.displayName = DISPLAY_NAME.CONTROL_FIELD;
+ControlFieldIndicator.displayName = DISPLAY_NAME.CONTROL_FIELD_INDICATOR;
+
+/**
+ * Compound ControlField component with sub-components
+ *
+ * @component ControlField - Wrapper that provides consistent layout and interaction for form controls.
+ * Handles press events to toggle selection state and manages disabled states.
+ *
+ * @component ControlField.Indicator - Container for the control component (Switch, Checkbox, Radio).
+ * Automatically passes down isSelected, onSelectedChange, isDisabled, and isInvalid props.
+ *
+ * Props flow from ControlField to sub-components via context.
+ */
+const CompoundControlField = Object.assign(ControlField, {
+  /** @optional Container for control component */
+  Indicator: ControlFieldIndicator,
+});
+
+export { useControlField } from './control-field.context';
+export default CompoundControlField;

package/lib/__templates__/expo/client/heroui/components/control-field/control-field.types.ts

@@ -0,0 +1,67 @@
+import type { PressableProps, ViewProps } from 'react-native';
+import type { SharedValue } from 'react-native-reanimated';
+import type { AnimationRootDisableAll } from '../../helpers/internal/types';
+
+/**
+ * Render function props for control field children
+ */
+export type ControlFieldRenderProps = Pick<
+  ControlFieldProps,
+  'isSelected' | 'isDisabled' | 'isInvalid'
+>;
+
+/**
+ * ControlField component props
+ */
+export interface ControlFieldProps extends Omit<PressableProps, 'children'> {
+  /** Content to render inside the form control, or a render function */
+  children?:
+    | React.ReactNode
+    | ((props: ControlFieldRenderProps) => React.ReactNode);
+
+  /** Custom class name for the root element */
+  className?: string;
+
+  /** Whether the control is selected/checked @default undefined */
+  isSelected?: boolean;
+
+  /** Whether the form control is disabled @default false */
+  isDisabled?: boolean;
+
+  /** Whether the form control is invalid @default false */
+  isInvalid?: boolean;
+
+  /** Whether the form control is required @default false */
+  isRequired?: boolean;
+
+  /** Callback when selection state changes */
+  onSelectedChange?: (isSelected: boolean) => void;
+
+  /** Animation configuration. Use `"disable-all"` to disable all animations including children */
+  animation?: AnimationRootDisableAll;
+}
+
+/**
+ * Props for the ControlFieldIndicator component
+ */
+export interface ControlFieldIndicatorProps extends ViewProps {
+  /** Control component to render (Switch, Checkbox) */
+  children?: React.ReactNode;
+
+  /** Custom class name for the indicator element */
+  className?: string;
+
+  /** Variant of the control to render when no children provided @default 'switch' */
+  variant?: 'checkbox' | 'radio' | 'switch';
+}
+
+/**
+ * Context value for form control components
+ */
+export interface ControlFieldContextValue
+  extends Pick<
+    ControlFieldProps,
+    'isSelected' | 'onSelectedChange' | 'isDisabled' | 'isInvalid'
+  > {
+  isPressed: SharedValue<boolean>;
+}

package/lib/__templates__/expo/client/heroui/components/control-field/index.ts

@@ -0,0 +1,6 @@
+export { default as ControlField, useControlField } from './control-field';
+export { controlFieldClassNames } from './control-field.styles';
+export type {
+  ControlFieldIndicatorProps,
+  ControlFieldProps,
+} from './control-field.types';

package/lib/__templates__/expo/client/heroui/components/description/description.animation.ts

@@ -0,0 +1,53 @@
+import { useCombinedAnimationDisabledState } from '../../helpers/internal/hooks';
+import {
+  getAnimationValueProperty,
+  getIsAnimationDisabledValue,
+  getRootAnimationState,
+} from '../../helpers/internal/utils';
+import {
+  ENTERING_ANIMATION_CONFIG,
+  EXITING_ANIMATION_CONFIG,
+} from './description.constants';
+import type { DescriptionAnimation } from './description.types';
+
+// --------------------------------------------------
+
+/**
+ * Animation hook for Description component
+ * Handles entering and exiting animations for the description text
+ */
+export function useDescriptionAnimation(options: {
+  animation: DescriptionAnimation | undefined;
+  hideOnInvalid: boolean;
+}) {
+  const { animation, hideOnInvalid } = options;
+
+  const { animationConfig, isAnimationDisabled } =
+    getRootAnimationState(animation);
+
+  const isAllAnimationsDisabled = useCombinedAnimationDisabledState(animation);
+
+  const isAnimationDisabledValue = getIsAnimationDisabledValue({
+    isAnimationDisabled,
+    isAllAnimationsDisabled,
+  });
+
+  const enteringValue = getAnimationValueProperty({
+    animationValue: animationConfig?.entering,
+    property: 'value',
+    defaultValue: ENTERING_ANIMATION_CONFIG,
+  });
+
+  const exitingValue = getAnimationValueProperty({
+    animationValue: animationConfig?.exiting,
+    property: 'value',
+    defaultValue: EXITING_ANIMATION_CONFIG,
+  });
+
+  return {
+    entering:
+      isAnimationDisabledValue || !hideOnInvalid ? undefined : enteringValue,
+    exiting:
+      isAnimationDisabledValue || !hideOnInvalid ? undefined : exitingValue,
+  };
+}

package/lib/__templates__/expo/client/heroui/components/description/description.constants.ts

@@ -0,0 +1,30 @@
+import { Easing, FadeIn, FadeOut } from 'react-native-reanimated';
+
+/**
+ * Display names for Description components
+ */
+export const DISPLAY_NAME = {
+  DESCRIPTION: 'HeroUINative.Description',
+} as const;
+
+/**
+ * Animation duration for description transitions
+ */
+export const ANIMATION_DURATION = 150;
+
+/**
+ * Animation easing function for description transitions
+ */
+export const ANIMATION_EASING = Easing.out(Easing.ease);
+
+/**
+ * Animation configuration for entering transitions
+ */
+export const ENTERING_ANIMATION_CONFIG =
+  FadeIn.duration(ANIMATION_DURATION).easing(ANIMATION_EASING);
+
+/**
+ * Animation configuration for exiting transitions
+ */
+export const EXITING_ANIMATION_CONFIG =
+  FadeOut.duration(ANIMATION_DURATION).easing(ANIMATION_EASING);