@coze-arch/cli 0.0.10 → 0.0.11

package/lib/__templates__/expo/client/heroui/components/field-error/field-error.animation.ts

@@ -0,0 +1,50 @@
+import { useCombinedAnimationDisabledState } from '../../helpers/internal/hooks';
+import {
+  getAnimationValueProperty,
+  getIsAnimationDisabledValue,
+  getRootAnimationState,
+} from '../../helpers/internal/utils';
+import {
+  ENTERING_ANIMATION_CONFIG,
+  EXITING_ANIMATION_CONFIG,
+} from './field-error.constants';
+import type { FieldErrorRootAnimation } from './field-error.types';
+
+// --------------------------------------------------
+
+/**
+ * Animation hook for FieldError root component
+ * Handles entering and exiting animations for error messages
+ */
+export function useFieldErrorRootAnimation(options: {
+  animation: FieldErrorRootAnimation | undefined;
+}) {
+  const { animation } = 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 ? undefined : enteringValue,
+    exiting: isAnimationDisabledValue ? undefined : exitingValue,
+  };
+}

package/lib/__templates__/expo/client/heroui/components/field-error/field-error.constants.ts

@@ -0,0 +1,31 @@
+import { Easing, FadeIn, FadeOut } from 'react-native-reanimated';
+
+/**
+ * Display names for the FieldError component parts
+ */
+export const DISPLAY_NAME = {
+  ROOT: 'HeroUINative.FieldError',
+};
+
+/**
+ * Animation duration for focus/blur transitions
+ */
+export const ANIMATION_DURATION = 150;
+
+/**
+ * Animation easing function for focus/blur transitions
+ */
+export const ANIMATION_EASING = Easing.out(Easing.ease);
+
+/**
+ * Default entering animation configuration
+ */
+export const ENTERING_ANIMATION_CONFIG =
+  FadeIn.duration(ANIMATION_DURATION).easing(ANIMATION_EASING);
+
+/**
+ * Default exiting animation configuration
+ */
+export const EXITING_ANIMATION_CONFIG = FadeOut.duration(
+  ANIMATION_DURATION / 1.5
+).easing(ANIMATION_EASING);

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

@@ -0,0 +1,204 @@
+# FieldError
+
+Displays validation error message content with smooth animations.
+
+## Import
+
+```tsx
+import { FieldError } from '@/heroui';
+```
+
+## Anatomy
+
+```tsx
+<FieldError>Error message content</FieldError>
+```
+
+- **FieldError**: Main container that displays error messages with smooth animations. Accepts string children which are automatically wrapped with Text component, or custom React components for more complex layouts. Controls visibility through the `isInvalid` prop and supports custom entering/exiting animations.
+
+## Usage
+
+### Basic Usage
+
+The FieldError component displays error messages when validation fails.
+
+```tsx
+<FieldError isInvalid={true}>This field is required</FieldError>
+```
+
+### Controlled Visibility
+
+Control when the error appears using the `isInvalid` prop. When used inside a form field component (like TextField), FieldError automatically consumes the form-item-state context.
+
+```tsx
+const [isInvalid, setIsInvalid] = useState(false);
+
+<FieldError isInvalid={isInvalid}>
+  Please enter a valid email address
+</FieldError>;
+```
+
+### With Form Fields
+
+FieldError automatically consumes form state from TextField via the form-item-state context.
+
+```tsx
+import { FieldError, Label, TextField } from '@/heroui';
+
+<TextField isRequired isInvalid={true}>
+  <Label>Email</Label>
+  <Input placeholder="Enter your email" />
+  <FieldError>Please enter a valid email address</FieldError>
+</TextField>;
+```
+
+### Custom Content
+
+Pass custom React components as children instead of strings.
+
+```tsx
+<FieldError isInvalid={true}>
+  <View className="flex-row items-center">
+    <Icon name="alert-circle" />
+    <Text className="ml-2 text-danger">Invalid input</Text>
+  </View>
+</FieldError>
+```
+
+### Custom Animations
+
+Override default entering and exiting animations using the `animation` prop.
+
+```tsx
+import { SlideInDown, SlideOutUp } from 'react-native-reanimated';
+
+<FieldError
+  isInvalid={true}
+  animation={{
+    entering: { value: SlideInDown.duration(200) },
+    exiting: { value: SlideOutUp.duration(150) },
+  }}
+>
+  Field validation failed
+</FieldError>;
+```
+
+Disable animations entirely:
+
+```tsx
+<FieldError isInvalid={true} animation={false}>
+  Field validation failed
+</FieldError>
+```
+
+### Custom Styling
+
+Apply custom styles to the container and text elements.
+
+```tsx
+<FieldError
+  isInvalid={true}
+  className="mt-2"
+  classNames={{
+    container: 'bg-danger/10 p-2 rounded',
+    text: 'text-xs font-medium',
+  }}
+>
+  Password must be at least 8 characters
+</FieldError>
+```
+
+### Custom Text Props
+
+Pass additional props to the Text component when children is a string.
+
+```tsx
+<FieldError
+  isInvalid={true}
+  textProps={{
+    numberOfLines: 1,
+    ellipsizeMode: 'tail',
+    style: { letterSpacing: 0.5 },
+  }}
+>
+  This is a very long error message that might need to be truncated
+</FieldError>
+```
+
+## Example
+
+```tsx
+import { Description, FieldError, Label, TextField } from '@/heroui';
+import { useState } from 'react';
+import { View } from 'react-native';
+
+export default function FieldErrorExample() {
+  const [email, setEmail] = useState('');
+  const [isInvalid, setIsInvalid] = useState(false);
+
+  const isValidEmail = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+
+  const handleBlur = () => {
+    setIsInvalid(email !== '' && !isValidEmail);
+  };
+
+  return (
+    <View className="p-4">
+      <TextField isInvalid={isInvalid}>
+        <Label>Email Address</Label>
+        <Input
+          placeholder="Enter your email"
+          value={email}
+          onChangeText={setEmail}
+          onBlur={handleBlur}
+          keyboardType="email-address"
+          autoCapitalize="none"
+        />
+        <Description>We'll use this to contact you</Description>
+        <FieldError>Please enter a valid email address</FieldError>
+      </TextField>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/(home)/components/field-error.tsx>).
+
+## API Reference
+
+### FieldError
+
+| prop                   | type                                          | default     | description                                                                                                                                   |
+| ---------------------- | --------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children`             | `React.ReactNode`                             | `undefined` | The content of the error field. String children are wrapped with Text                                                                         |
+| `isInvalid`            | `boolean`                                     | `undefined` | Controls the visibility of the error field (overrides form-item-state context). When used inside TextField, automatically consumes form state |
+| `animation`            | `FieldErrorRootAnimation`                     | -           | Animation configuration                                                                                                                       |
+| `className`            | `string`                                      | `undefined` | Additional CSS classes for the container                                                                                                      |
+| `classNames`           | `ElementSlots<FieldErrorSlots>`               | `undefined` | Additional CSS classes for different parts of the component                                                                                   |
+| `styles`               | `{ container?: ViewStyle; text?: TextStyle }` | `undefined` | Styles for different parts of the field error                                                                                                 |
+| `textProps`            | `TextProps`                                   | `undefined` | Additional props to pass to the Text component when children is a string                                                                      |
+| `...AnimatedViewProps` | `AnimatedProps<ViewProps>`                    | -           | All Reanimated Animated.View props are supported                                                                                              |
+
+**classNames prop:** `ElementSlots<FieldErrorSlots>` provides type-safe CSS classes for different parts of the field error component. Available slots: `container`, `text`.
+
+#### `styles`
+
+| prop        | type        | description                 |
+| ----------- | ----------- | --------------------------- |
+| `container` | `ViewStyle` | Styles for the container    |
+| `text`      | `TextStyle` | Styles for the text content |
+
+#### FieldErrorRootAnimation
+
+Animation configuration for field error root component. Can be:
+
+- `false` or `"disabled"`: Disable only root animations
+- `"disable-all"`: Disable all animations including children
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop             | type                                     | default                                                               | description                                     |
+| ---------------- | ---------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------- |
+| `state`          | `'disabled' \| 'disable-all' \| boolean` | -                                                                     | Disable animations while customizing properties |
+| `entering.value` | `EntryOrExitLayoutType`                  | `FadeIn`<br/>`.duration(150)`<br/>`.easing(Easing.out(Easing.ease))`  | Custom entering animation for field error       |
+| `exiting.value`  | `EntryOrExitLayoutType`                  | `FadeOut`<br/>`.duration(100)`<br/>`.easing(Easing.out(Easing.ease))` | Custom exiting animation for field error        |

package/lib/__templates__/expo/client/heroui/components/field-error/field-error.styles.ts

@@ -0,0 +1,23 @@
+import { tv } from 'tailwind-variants';
+import { combineStyles } from '../../helpers/internal/utils';
+
+const root = tv({
+  slots: {
+    container: '',
+    text: 'text-sm text-danger',
+  },
+  variants: {
+    isInsideField: {
+      true: {
+        container: 'px-1.5',
+        text: '',
+      },
+    },
+  },
+});
+
+export const fieldErrorClassNames = combineStyles({
+  root,
+});
+
+export type FieldErrorSlots = keyof ReturnType<typeof root>;

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

@@ -0,0 +1,91 @@
+import { forwardRef } from 'react';
+import Animated from 'react-native-reanimated';
+import { HeroText } from '../../helpers/internal/components';
+import { useFormField } from '../../helpers/internal/contexts';
+import type { ViewRef } from '../../helpers/internal/types';
+import { childrenToString } from '../../helpers/internal/utils';
+import { useFieldErrorRootAnimation } from './field-error.animation';
+import { DISPLAY_NAME } from './field-error.constants';
+import { fieldErrorClassNames } from './field-error.styles';
+import type { FieldErrorRootProps } from './field-error.types';
+
+// --------------------------------------------------
+
+const FieldErrorRoot = forwardRef<ViewRef, FieldErrorRootProps>(
+  (props, ref) => {
+    const {
+      children,
+      className,
+      classNames,
+      style,
+      styles,
+      textProps,
+      isInvalid: localIsInvalid,
+      animation,
+      ...restProps
+    } = props;
+
+    const formField = useFormField();
+
+    // Merge form field state with local props (local takes precedence)
+    const isInvalid =
+      localIsInvalid !== undefined
+        ? localIsInvalid
+        : (formField?.isInvalid ?? false);
+
+    const isInsideField = formField?.hasFieldPadding ?? false;
+
+    const { container, text } = fieldErrorClassNames.root({
+      isInsideField,
+    });
+
+    const containerClassName = container({
+      className: [className, classNames?.container],
+    });
+
+    const textClassName = text({
+      className: [classNames?.text, textProps?.className],
+    });
+
+    const { entering, exiting } = useFieldErrorRootAnimation({ animation });
+
+    if (!isInvalid) return null;
+
+    const stringifiedChildren = childrenToString(children);
+    const renderedChildren = stringifiedChildren ? (
+      <HeroText className={textClassName} style={styles?.text} {...textProps}>
+        {stringifiedChildren}
+      </HeroText>
+    ) : (
+      children
+    );
+
+    return (
+      <Animated.View
+        ref={ref}
+        entering={entering}
+        exiting={exiting}
+        className={containerClassName}
+        style={[style, styles?.container]}
+        {...restProps}
+      >
+        {renderedChildren}
+      </Animated.View>
+    );
+  }
+);
+
+// --------------------------------------------------
+
+FieldErrorRoot.displayName = DISPLAY_NAME.ROOT;
+
+/**
+ * FieldError component for displaying validation errors
+ *
+ * @component FieldError - Error message container with entering/exiting animations.
+ * Automatically wraps string children with Text component.
+ * Hidden when isInvalid is false.
+ */
+const FieldError = FieldErrorRoot;
+
+export default FieldError;

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

@@ -0,0 +1,79 @@
+import type { TextProps, TextStyle, ViewProps, ViewStyle } from 'react-native';
+import type {
+  AnimatedProps,
+  EntryOrExitLayoutType,
+} from 'react-native-reanimated';
+import type {
+  AnimationRoot,
+  AnimationValue,
+  ElementSlots,
+} from '../../helpers/internal/types';
+import type { FieldErrorSlots } from './field-error.styles';
+
+/**
+ * Animation configuration for FieldError root component
+ */
+export type FieldErrorRootAnimation = AnimationRoot<{
+  entering?: AnimationValue<{
+    /**
+     * Custom entering animation for field error
+     */
+    value?: EntryOrExitLayoutType;
+  }>;
+  exiting?: AnimationValue<{
+    /**
+     * Custom exiting animation for field error
+     */
+    value?: EntryOrExitLayoutType;
+  }>;
+}>;
+
+/**
+ * Props for the FieldError root component
+ */
+export interface FieldErrorRootProps
+  extends Omit<AnimatedProps<ViewProps>, 'entering' | 'exiting'> {
+  /**
+   * The content of the error field
+   * When passed as string, it will be wrapped with Text component
+   */
+  children?: React.ReactNode;
+
+  /**
+   * Controls the visibility of the error field (overrides context)
+   * When false, the field error is hidden
+   * @default undefined - uses form-item-state context value
+   */
+  isInvalid?: boolean;
+
+  /**
+   * Additional CSS class for styling
+   */
+  className?: string;
+
+  /**
+   * Additional CSS classes for different parts of the component
+   */
+  classNames?: ElementSlots<FieldErrorSlots>;
+
+  /**
+   * Styles for different parts of the field error
+   */
+  styles?: {
+    container?: ViewStyle;
+    text?: TextStyle;
+  };
+
+  /**
+   * Additional props to pass to the Text component when children is a string
+   */
+  textProps?: TextProps;
+
+  /**
+   * Animation configuration for field error
+   * - `false` or `"disabled"`: Disable all animations
+   * - `true` or `undefined`: Use default animations
+   * - `object`: Custom animation configuration
+   */
+  animation?: FieldErrorRootAnimation;
+}

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

@@ -0,0 +1,3 @@
+export { default as FieldError } from './field-error';
+export { fieldErrorClassNames } from './field-error.styles';
+export type { FieldErrorRootProps } from './field-error.types';

package/lib/__templates__/expo/client/heroui/components/input/index.ts

@@ -0,0 +1,3 @@
+export { default as Input } from './input';
+export { inputClassNames } from './input.styles';
+export type { InputProps } from './input.types';

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

@@ -0,0 +1,6 @@
+/**
+ * Display name for Input component
+ */
+export const DISPLAY_NAME = {
+  INPUT: 'HeroUINative.Input',
+} as const;

package/lib/__templates__/expo/client/heroui/components/input/input.md

@@ -0,0 +1,193 @@
+# Input
+
+A text input component with styled border and background for collecting user input.
+
+## Import
+
+```tsx
+import { Input } from '@/heroui';
+```
+
+## Usage
+
+### Basic Usage
+
+Input can be used standalone or within a TextField component.
+
+```tsx
+import { Input } from '@/heroui';
+
+<Input placeholder="Enter your email" />;
+```
+
+### Within TextField
+
+Input works seamlessly with TextField for complete form structure.
+
+```tsx
+import { Input, Label, TextField } from '@/heroui';
+
+<TextField>
+  <Label>Email</Label>
+  <Input placeholder="Enter your email" />
+</TextField>;
+```
+
+### With Validation
+
+Display error state when the input is invalid.
+
+```tsx
+import { FieldError, Input, Label, TextField } from '@/heroui';
+
+<TextField isRequired isInvalid={true}>
+  <Label>Email</Label>
+  <Input placeholder="Enter your email" />
+  <FieldError>Please enter a valid email</FieldError>
+</TextField>;
+```
+
+### With Local Invalid State Override
+
+Override the context's invalid state for the input.
+
+```tsx
+import { FieldError, Input, Label, TextField } from '@/heroui';
+
+<TextField isInvalid={true}>
+  <Label isInvalid={false}>Email</Label>
+  <Input placeholder="Enter your email" isInvalid={false} />
+  <FieldError>Email format is incorrect</FieldError>
+</TextField>;
+```
+
+### Disabled State
+
+Disable the input to prevent interaction.
+
+```tsx
+import { Input, Label, TextField } from '@/heroui';
+
+<TextField isDisabled>
+  <Label>Disabled Field</Label>
+  <Input placeholder="Cannot edit" value="Read only value" />
+</TextField>;
+```
+
+### With Variant
+
+Use different variants to style the input based on context.
+
+```tsx
+import { Input, Label, TextField } from '@/heroui';
+
+<TextField>
+  <Label>Primary Variant</Label>
+  <Input placeholder="Primary style" variant="primary" />
+</TextField>
+
+<TextField>
+  <Label>Secondary Variant</Label>
+  <Input placeholder="Secondary style" variant="secondary" />
+</TextField>
+```
+
+### Custom Styling
+
+Customize the input appearance using className.
+
+```tsx
+import { Input, Label, TextField } from '@/heroui';
+
+<TextField>
+  <Label>Custom Styled</Label>
+  <Input
+    placeholder="Custom colors"
+    className="bg-blue-50 border-blue-500 focus:border-blue-700"
+  />
+</TextField>;
+```
+
+## Example
+
+```tsx
+import { Ionicons } from '@expo/vector-icons';
+import { Description, Input, Label, TextField } from '@/heroui';
+import { useState } from 'react';
+import { Pressable, View } from 'react-native';
+import { withUniwind } from 'uniwind';
+
+const StyledIonicons = withUniwind(Ionicons);
+
+export const TextInputContent = () => {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [isPasswordVisible, setIsPasswordVisible] = useState(false);
+
+  return (
+    <View className="gap-4">
+      <TextField isRequired>
+        <Label>Email</Label>
+        <Input
+          placeholder="Enter your email"
+          keyboardType="email-address"
+          autoCapitalize="none"
+          value={email}
+          onChangeText={setEmail}
+        />
+        <Description>
+          We'll never share your email with anyone else.
+        </Description>
+      </TextField>
+
+      <TextField isRequired>
+        <Label>New password</Label>
+        <View className="w-full flex-row items-center">
+          <Input
+            value={password}
+            onChangeText={setPassword}
+            className="flex-1 px-10"
+            placeholder="Enter your password"
+            secureTextEntry={!isPasswordVisible}
+          />
+          <StyledIonicons
+            name="lock-closed-outline"
+            size={16}
+            className="absolute left-3.5 text-muted"
+            pointerEvents="none"
+          />
+          <Pressable
+            className="absolute right-4"
+            onPress={() => setIsPasswordVisible(!isPasswordVisible)}
+          >
+            <StyledIonicons
+              name={isPasswordVisible ? 'eye-off-outline' : 'eye-outline'}
+              size={16}
+              className="text-muted"
+            />
+          </Pressable>
+        </View>
+        <Description>Password must be at least 6 characters</Description>
+      </TextField>
+    </View>
+  );
+};
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/(home)/components/input.tsx>).
+
+## API Reference
+
+### Input
+
+| prop                      | type                       | default               | description                                                  |
+| ------------------------- | -------------------------- | --------------------- | ------------------------------------------------------------ |
+| isInvalid                 | `boolean`                  | `undefined`           | Whether the input is in an invalid state (overrides context) |
+| variant                   | `'primary' \| 'secondary'` | `'primary'`           | Variant style for the input                                  |
+| className                 | `string`                   | -                     | Custom class name for the input                              |
+| selectionColorClassName   | `string`                   | `"accent-accent"`     | Custom className for the selection color                     |
+| placeholderColorClassName | `string`                   | `"field-placeholder"` | Custom className for the placeholder text color              |
+| animation                 | `AnimationRoot`            | `undefined`           | Animation configuration for the input                        |
+| ...TextInputProps         | `TextInputProps`           | -                     | All standard React Native TextInput props are supported      |
+
+> **Note**: When used within a TextField component, Input automatically consumes form state (isDisabled, isInvalid) from TextField via the form-item-state context.