@coze-arch/cli 0.0.10 → 0.0.11

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

@@ -0,0 +1,129 @@
+# Description
+
+Text component for providing accessible descriptions and helper text for form fields and other UI elements.
+
+## Import
+
+```tsx
+import { Description } from '@/heroui';
+```
+
+## Anatomy
+
+```tsx
+<Description>...</Description>
+```
+
+- **Description**: Text component that displays description or helper text with muted styling. Can be linked to form fields via `nativeID` for accessibility support.
+
+## Usage
+
+### Basic Usage
+
+Display description text with default muted styling.
+
+```tsx
+<Description>This is a helpful description.</Description>
+```
+
+### With Form Fields
+
+Provide accessible descriptions for form fields using the `nativeID` prop.
+
+```tsx
+<TextField>
+  <Label>Email address</Label>
+  <Input
+    placeholder="Enter your email"
+    keyboardType="email-address"
+    autoCapitalize="none"
+  />
+  <Description nativeID="email-desc">
+    We'll never share your email with anyone else.
+  </Description>
+</TextField>
+```
+
+### Accessibility Linking
+
+Link descriptions to form fields for screen reader support by using `nativeID` and `aria-describedby`.
+
+```tsx
+<TextField>
+  <Label>Password</Label>
+  <Input
+    placeholder="Create a password"
+    secureTextEntry
+    aria-describedby="password-desc"
+  />
+  <Description nativeID="password-desc">
+    Use at least 8 characters with a mix of letters, numbers, and symbols.
+  </Description>
+</TextField>
+```
+
+### Hiding on Invalid State
+
+Control whether the description should be hidden when the form field is invalid using the `hideOnInvalid` prop.
+
+```tsx
+<TextField isInvalid={isInvalid}>
+  <Label>Email</Label>
+  <Input placeholder="Enter your email" />
+  <Description hideOnInvalid>
+    We'll never share your email with anyone else.
+  </Description>
+  <FieldError>Please enter a valid email address</FieldError>
+</TextField>
+```
+
+When `hideOnInvalid` is `true`, the description will be hidden when the field is invalid. When `false` (default), the description remains visible even when invalid.
+
+## Example
+
+```tsx
+import { Description, TextField } from '@/heroui';
+import { View } from 'react-native';
+
+export default function DescriptionExample() {
+  return (
+    <View className="flex-1 justify-center px-5 gap-8">
+      <TextField>
+        <Label>Email address</Label>
+        <Input
+          placeholder="Enter your email"
+          keyboardType="email-address"
+          autoCapitalize="none"
+        />
+        <Description nativeID="email-desc">
+          We'll never share your email with anyone else.
+        </Description>
+      </TextField>
+      <TextField>
+        <Label>Password</Label>
+        <Input placeholder="Create a password" secureTextEntry />
+        <Description nativeID="password-desc">
+          Use at least 8 characters with a mix of letters, numbers, and symbols.
+        </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/description.tsx>).
+
+## API Reference
+
+### Description
+
+| prop            | type                                | default | description                                                                                |
+| --------------- | ----------------------------------- | ------- | ------------------------------------------------------------------------------------------ |
+| `children`      | `React.ReactNode`                   | -       | Description text content                                                                   |
+| `className`     | `string`                            | -       | Additional CSS classes to apply                                                            |
+| `nativeID`      | `string`                            | -       | Native ID for accessibility. Used to link description to form fields via aria-describedby. |
+| `isInvalid`     | `boolean`                           | -       | Whether the description is in an invalid state (overrides context)                         |
+| `isDisabled`    | `boolean`                           | -       | Whether the description is disabled (overrides context)                                    |
+| `hideOnInvalid` | `boolean`                           | `false` | Whether to hide the description when invalid                                               |
+| `animation`     | `DescriptionAnimation \| undefined` | -       | Animation configuration for description transitions                                        |
+| `...TextProps`  | `TextProps`                         | -       | All standard React Native Text props are supported                                         |

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

@@ -0,0 +1,25 @@
+import { tv } from 'tailwind-variants';
+import { combineStyles } from '../../helpers/internal/utils';
+
+const root = tv({
+  base: 'text-sm text-muted',
+  variants: {
+    isInsideField: {
+      true: 'px-1.5',
+    },
+    isInvalid: {
+      true: 'text-danger',
+    },
+    isDisabled: {
+      true: 'opacity-disabled',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    isDisabled: false,
+  },
+});
+
+export const descriptionClassNames = combineStyles({
+  root,
+});

package/lib/__templates__/expo/client/heroui/components/description/description.tsx

@@ -0,0 +1,81 @@
+import { forwardRef } from 'react';
+import Animated from 'react-native-reanimated';
+import { HeroText } from '../../helpers/internal/components';
+import { useFormField } from '../../helpers/internal/contexts';
+import type { TextRef } from '../../helpers/internal/types';
+import { useDescriptionAnimation } from './description.animation';
+import { DISPLAY_NAME } from './description.constants';
+import { descriptionClassNames } from './description.styles';
+import type { DescriptionProps } from './description.types';
+
+const AnimatedText = Animated.createAnimatedComponent(HeroText);
+
+// --------------------------------------------------
+
+const Description = forwardRef<TextRef, DescriptionProps>((props, ref) => {
+  const {
+    children,
+    className,
+    nativeID,
+    isInvalid: localIsInvalid,
+    isDisabled: localIsDisabled,
+    hideOnInvalid = false,
+    animation,
+    ...restProps
+  } = props;
+
+  const formField = useFormField();
+
+  const isInvalid =
+    localIsInvalid !== undefined
+      ? localIsInvalid
+      : (formField?.isInvalid ?? false);
+
+  const isDisabled =
+    localIsDisabled !== undefined
+      ? localIsDisabled
+      : (formField?.isDisabled ?? false);
+
+  const isInsideField = formField?.hasFieldPadding ?? false;
+
+  const rootClassName = descriptionClassNames.root({
+    isInvalid,
+    isDisabled,
+    isInsideField,
+    className,
+  });
+
+  const { entering, exiting } = useDescriptionAnimation({
+    animation,
+    hideOnInvalid,
+  });
+
+  if (isInvalid && hideOnInvalid) return null;
+
+  return (
+    <AnimatedText
+      ref={ref}
+      entering={entering}
+      exiting={exiting}
+      className={rootClassName}
+      nativeID={nativeID}
+      {...restProps}
+    >
+      {children}
+    </AnimatedText>
+  );
+});
+
+// --------------------------------------------------
+
+Description.displayName = DISPLAY_NAME.DESCRIPTION;
+
+/**
+ * Description component for form fields and other UI elements.
+ *
+ * Provides accessible description text with proper styling. Can be linked to
+ * form fields via the nativeID prop for accessibility support.
+ *
+ * @see Full documentation: https://v3.heroui.com/docs/native/components/description
+ */
+export default Description;

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

@@ -0,0 +1,77 @@
+import type { TextProps } from 'react-native';
+import type {
+  AnimatedProps,
+  EntryOrExitLayoutType,
+} from 'react-native-reanimated';
+import type {
+  AnimationRoot,
+  AnimationValue,
+  TextRef,
+} from '../../helpers/internal/types';
+
+/**
+ * Animation configuration for Description component
+ * Used by the Description component for animation support
+ */
+export type DescriptionAnimation = AnimationRoot<{
+  entering?: AnimationValue<{
+    /**
+     * Custom entering animation for description
+     */
+    value?: EntryOrExitLayoutType;
+  }>;
+  exiting?: AnimationValue<{
+    /**
+     * Custom exiting animation for description
+     */
+    value?: EntryOrExitLayoutType;
+  }>;
+}>;
+
+/**
+ * Props for the Description component
+ */
+export interface DescriptionProps
+  extends Omit<AnimatedProps<TextProps>, 'entering' | 'exiting'> {
+  /**
+   * Description text content
+   */
+  children?: React.ReactNode;
+  /**
+   * Whether the description is in an invalid state (overrides context)
+   * @default undefined
+   */
+  isInvalid?: boolean;
+  /**
+   * Whether the description is disabled (overrides context)
+   * @default undefined
+   */
+  isDisabled?: boolean;
+  /**
+   * Whether to hide the description when invalid
+   * @default false
+   */
+  hideOnInvalid?: boolean;
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+  /**
+   * Native ID for accessibility. Used to link description to form fields via aria-describedby.
+   * When provided, form fields can reference this description using aria-describedby={nativeID}.
+   */
+  nativeID?: string;
+  /**
+   * Animation configuration for description
+   * - `true` or `undefined`: Use default animations
+   * - `false` or `"disabled"`: Disable only description animations (children can still animate)
+   * - `"disable-all"`: Disable all animations including children (cascades down)
+   * - `object`: Custom animation configuration
+   */
+  animation?: DescriptionAnimation;
+}
+
+/**
+ * Reference type for the Description component
+ */
+export type DescriptionRef = TextRef;

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

@@ -0,0 +1,3 @@
+export { default as Description } from './description';
+export { descriptionClassNames } from './description.styles';
+export type { DescriptionProps, DescriptionRef } from './description.types';

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

@@ -0,0 +1,9 @@
+import { createContext } from '../../helpers/internal/utils';
+import type { DialogAnimationContextValue } from './dialog.types';
+
+const [DialogAnimationProvider, useDialogAnimation] =
+  createContext<DialogAnimationContextValue>({
+    name: 'DialogAnimationContext',
+  });
+
+export { DialogAnimationProvider, useDialogAnimation };

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

@@ -0,0 +1,13 @@
+/**
+ * Display names for Dialog components
+ */
+export const DISPLAY_NAME = {
+  ROOT: 'HeroUINative.Dialog.Root',
+  TRIGGER: 'HeroUINative.Dialog.Trigger',
+  PORTAL: 'HeroUINative.Dialog.Portal',
+  OVERLAY: 'HeroUINative.Dialog.Overlay',
+  CONTENT: 'HeroUINative.Dialog.Content',
+  CLOSE: 'HeroUINative.Dialog.Close',
+  TITLE: 'HeroUINative.Dialog.Title',
+  DESCRIPTION: 'HeroUINative.Dialog.Description',
+};

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

@@ -0,0 +1,288 @@
+# Dialog
+
+Displays a modal overlay with animated transitions and gesture-based dismissal.
+
+## Import
+
+```tsx
+import { Dialog } from '@/heroui';
+```
+
+## Anatomy
+
+```tsx
+<Dialog>
+  <Dialog.Trigger>...</Dialog.Trigger>
+  <Dialog.Portal>
+    <Dialog.Overlay>...</Dialog.Overlay>
+    <Dialog.Content>
+      <Dialog.Close>...</Dialog.Close>
+      <Dialog.Title>...</Dialog.Title>
+      <Dialog.Description>...</Dialog.Description>
+    </Dialog.Content>
+  </Dialog.Portal>
+</Dialog>
+```
+
+- **Dialog**: Root component that manages open state and provides context to child components.
+- **Dialog.Trigger**: Pressable element that opens the dialog when pressed.
+- **Dialog.Portal**: Renders dialog content in a portal with centered layout and animation control.
+- **Dialog.Overlay**: Background overlay that appears behind the dialog content, typically closes dialog when pressed.
+- **Dialog.Content**: Main dialog container with gesture support for drag-to-dismiss.
+- **Dialog.Close**: Close button for the dialog. Can accept custom children or uses default close icon.
+- **Dialog.Title**: Dialog title text with semantic heading role.
+- **Dialog.Description**: Dialog description text that provides additional context.
+
+## Usage
+
+### Basic Dialog
+
+Simple dialog with title, description, and close button.
+
+```tsx
+<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
+  <Dialog.Trigger asChild>
+    <Button>Open Dialog</Button>
+  </Dialog.Trigger>
+  <Dialog.Portal>
+    <Dialog.Overlay />
+    <Dialog.Content>
+      <Dialog.Close />
+      <Dialog.Title>...</Dialog.Title>
+      <Dialog.Description>...</Dialog.Description>
+    </Dialog.Content>
+  </Dialog.Portal>
+</Dialog>
+```
+
+### Scrollable Content
+
+Handle long content with scroll views.
+
+```tsx
+<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
+  <Dialog.Trigger>...</Dialog.Trigger>
+  <Dialog.Portal>
+    <Dialog.Overlay />
+    <Dialog.Content>
+      <Dialog.Close />
+      <Dialog.Title>...</Dialog.Title>
+      <View className="h-[300px]">
+        <ScrollView>...</ScrollView>
+      </View>
+    </Dialog.Content>
+  </Dialog.Portal>
+</Dialog>
+```
+
+### Form Dialog
+
+Dialog with text inputs and keyboard handling.
+
+```tsx
+<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
+  <Dialog.Trigger>...</Dialog.Trigger>
+  <Dialog.Portal>
+    <Dialog.Overlay />
+    <KeyboardAvoidingView behavior="padding">
+      <Dialog.Content>
+        <Dialog.Close />
+        <Dialog.Title>...</Dialog.Title>
+        <TextField>...</TextField>
+        <Button onPress={handleSubmit}>Submit</Button>
+      </Dialog.Content>
+    </KeyboardAvoidingView>
+  </Dialog.Portal>
+</Dialog>
+```
+
+## Example
+
+```tsx
+import { Button, Dialog } from '@/heroui';
+import { View } from 'react-native';
+import { useState } from 'react';
+
+export default function DialogExample() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
+      <Dialog.Trigger asChild>
+        <Button variant="primary">Open Dialog</Button>
+      </Dialog.Trigger>
+      <Dialog.Portal>
+        <Dialog.Overlay />
+        <Dialog.Content>
+          <Dialog.Close variant="ghost" />
+          <View className="mb-5 gap-1.5">
+            <Dialog.Title>Confirm Action</Dialog.Title>
+            <Dialog.Description>
+              Are you sure you want to proceed with this action? This cannot be
+              undone.
+            </Dialog.Description>
+          </View>
+          <View className="flex-row justify-end gap-3">
+            <Button variant="ghost" size="sm" onPress={() => setIsOpen(false)}>
+              Cancel
+            </Button>
+            <Button size="sm">Confirm</Button>
+          </View>
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/(home)/components/dialog.tsx>).
+
+## API Reference
+
+### Dialog
+
+| prop            | type                       | default | description                                        |
+| --------------- | -------------------------- | ------- | -------------------------------------------------- |
+| `children`      | `React.ReactNode`          | -       | Dialog content and trigger elements                |
+| `isOpen`        | `boolean`                  | -       | Controlled open state of the dialog                |
+| `isDefaultOpen` | `boolean`                  | `false` | Initial open state when uncontrolled               |
+| `animation`     | `AnimationRootDisableAll`  | -       | Animation configuration                            |
+| `onOpenChange`  | `(value: boolean) => void` | -       | Callback when open state changes                   |
+| `...ViewProps`  | `ViewProps`                | -       | All standard React Native View props are supported |
+
+#### AnimationRootDisableAll
+
+Animation configuration for dialog root component. Can be:
+
+- `false` or `"disabled"`: Disable only root animations
+- `"disable-all"`: Disable all animations including children
+- `true` or `undefined`: Use default animations
+
+### Dialog.Trigger
+
+| prop                       | type                    | default | description                                                    |
+| -------------------------- | ----------------------- | ------- | -------------------------------------------------------------- |
+| `children`                 | `React.ReactNode`       | -       | Trigger element content                                        |
+| `asChild`                  | `boolean`               | -       | Render as child element without wrapper                        |
+| `...TouchableOpacityProps` | `TouchableOpacityProps` | -       | All standard React Native TouchableOpacity props are supported |
+
+### Dialog.Portal
+
+| prop                       | type                   | default | description                                                                                                                   |
+| -------------------------- | ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `children`                 | `React.ReactNode`      | -       | Portal content (overlay and dialog)                                                                                           |
+| `disableFullWindowOverlay` | `boolean`              | `false` | When true on iOS, uses View instead of FullWindowOverlay. Enables element inspector; overlay won't appear above native modals |
+| `className`                | `string`               | -       | Additional CSS classes for portal container                                                                                   |
+| `style`                    | `StyleProp<ViewStyle>` | -       | Additional styles for portal container                                                                                        |
+| `hostName`                 | `string`               | -       | Optional portal host name for specific container                                                                              |
+| `forceMount`               | `boolean`              | -       | Force mount when closed for animation purposes                                                                                |
+
+### Dialog.Overlay
+
+| prop                    | type                     | default | description                                                  |
+| ----------------------- | ------------------------ | ------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode`        | -       | Custom overlay content                                       |
+| `className`             | `string`                 | -       | Additional CSS classes for overlay                           |
+| `style`                 | `ViewStyle`              | -       | Additional styles for overlay container                      |
+| `animation`             | `DialogOverlayAnimation` | -       | Animation configuration                                      |
+| `isAnimatedStyleActive` | `boolean`                | `true`  | Whether animated styles (react-native-reanimated) are active |
+| `isCloseOnPress`        | `boolean`                | `true`  | Whether pressing overlay closes dialog                       |
+| `forceMount`            | `boolean`                | -       | Force mount when closed for animation purposes               |
+| `...PressableProps`     | `PressableProps`         | -       | All standard React Native Pressable props are supported      |
+
+#### DialogOverlayAnimation
+
+Animation configuration for dialog overlay component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop            | type                       | default                 | description                                                                  |
+| --------------- | -------------------------- | ----------------------- | ---------------------------------------------------------------------------- |
+| `state`         | `'disabled' \| boolean`    | -                       | Disable animations while customizing properties                              |
+| `opacity.value` | `[number, number, number]` | `[0, 1, 0]`             | Opacity values [idle, open, close] (progress-based, for dialog presentation) |
+| `entering`      | `EntryOrExitLayoutType`    | `FadeIn.duration(200)`  | Custom entering animation (for popover presentation)                         |
+| `exiting`       | `EntryOrExitLayoutType`    | `FadeOut.duration(150)` | Custom exiting animation (for popover presentation)                          |
+
+### Dialog.Content
+
+| prop                    | type                     | default | description                                         |
+| ----------------------- | ------------------------ | ------- | --------------------------------------------------- |
+| `children`              | `React.ReactNode`        | -       | Dialog content                                      |
+| `className`             | `string`                 | -       | Additional CSS classes for content container        |
+| `style`                 | `StyleProp<ViewStyle>`   | -       | Additional styles for content container             |
+| `animation`             | `DialogContentAnimation` | -       | Animation configuration                             |
+| `isSwipeable`           | `boolean`                | `true`  | Whether the dialog content can be swiped to dismiss |
+| `forceMount`            | `boolean`                | -       | Force mount when closed for animation purposes      |
+| `...Animated.ViewProps` | `Animated.ViewProps`     | -       | All Reanimated Animated.View props are supported    |
+
+#### DialogContentAnimation
+
+Animation configuration for dialog content component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop       | type                    | default                                                                                     | description                                     |
+| ---------- | ----------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| `state`    | `'disabled' \| boolean` | -                                                                                           | Disable animations while customizing properties |
+| `entering` | `EntryOrExitLayoutType` | Keyframe with `scale: 0.96→1` and `opacity: 0→1` (200ms, easing: `Easing.out(Easing.ease)`) | Custom entering animation                       |
+| `exiting`  | `EntryOrExitLayoutType` | Keyframe with `scale: 1→0.96` and `opacity: 1→0` (150ms, easing: `Easing.in(Easing.ease)`)  | Custom exiting animation                        |
+
+### Dialog.Close
+
+Dialog.Close extends [CloseButton](../close-button/close-button.md) and automatically handles dialog dismissal when pressed.
+
+### Dialog.Title
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Title content                                      |
+| `className`    | `string`          | -       | Additional CSS classes for title                   |
+| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |
+
+### Dialog.Description
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Description content                                |
+| `className`    | `string`          | -       | Additional CSS classes for description             |
+| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |
+
+## Hooks
+
+### useDialog
+
+Hook to access dialog primitive context.
+
+```tsx
+const { isOpen, onOpenChange } = useDialog();
+```
+
+| property       | type                       | description                   |
+| -------------- | -------------------------- | ----------------------------- |
+| `isOpen`       | `boolean`                  | Current open state            |
+| `onOpenChange` | `(value: boolean) => void` | Function to change open state |
+
+### useDialogAnimation
+
+Hook to access dialog animation context for advanced customization.
+
+```tsx
+const { progress, isDragging, isGestureReleaseAnimationRunning } =
+  useDialogAnimation();
+```
+
+| property                           | type                   | description                                  |
+| ---------------------------------- | ---------------------- | -------------------------------------------- |
+| `progress`                         | `SharedValue<number>`  | Animation progress (0=idle, 1=open, 2=close) |
+| `isDragging`                       | `SharedValue<boolean>` | Whether dialog is being dragged              |
+| `isGestureReleaseAnimationRunning` | `SharedValue<boolean>` | Whether gesture release animation is running |
+
+## Special Notes
+
+### Element Inspector (iOS)
+
+Dialog uses FullWindowOverlay on iOS. To enable the React Native element inspector during development, set `disableFullWindowOverlay={true}` on `Dialog.Portal`. Tradeoff: the dialog will not appear above native modals when disabled.