@coze-arch/cli 0.0.10 → 0.0.11

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

@@ -0,0 +1,311 @@
+# Checkbox
+
+A selectable control that allows users to toggle between checked and unchecked states.
+
+## Import
+
+```tsx
+import { Checkbox } from '@/heroui';
+```
+
+## Anatomy
+
+```tsx
+<Checkbox>
+  <Checkbox.Indicator>...</Checkbox.Indicator>
+</Checkbox>
+```
+
+- **Checkbox**: Main container that handles selection state and user interaction. Renders default indicator with animated checkmark if no children provided. Automatically detects surface context for proper styling. Features press scale animation that can be customized or disabled. Supports render function children to access state (`isSelected`, `isInvalid`, `isDisabled`).
+- **Checkbox.Indicator**: Optional checkmark container with default slide, scale, opacity, and border radius animations when selected. Renders animated check icon with SVG path drawing animation if no children provided. All animations can be individually customized or disabled. Supports render function children to access state.
+
+## Usage
+
+### Basic Usage
+
+The Checkbox component renders with a default animated indicator if no children are provided. It automatically detects whether it's on a surface background for proper styling.
+
+```tsx
+<Checkbox isSelected={isSelected} onSelectedChange={setIsSelected} />
+```
+
+### With Custom Indicator
+
+Use a render function in the Indicator to show/hide custom icons based on state.
+
+```tsx
+<Checkbox isSelected={isSelected} onSelectedChange={setIsSelected}>
+  <Checkbox.Indicator>
+    {({ isSelected }) => (isSelected ? <CheckIcon /> : null)}
+  </Checkbox.Indicator>
+</Checkbox>
+```
+
+### Invalid State
+
+Show validation errors with the `isInvalid` prop, which applies danger color styling.
+
+```tsx
+<Checkbox
+  isSelected={isSelected}
+  onSelectedChange={setIsSelected}
+  isInvalid={hasError}
+/>
+```
+
+### Custom Animations
+
+Customize or disable animations for both the root checkbox and indicator.
+
+```tsx
+{
+  /* Disable all animations (root and indicator) */
+}
+<Checkbox
+  animation="disable-all"
+  isSelected={isSelected}
+  onSelectedChange={setIsSelected}
+>
+  <Checkbox.Indicator />
+</Checkbox>;
+
+{
+  /* Disable only root animation */
+}
+<Checkbox
+  animation="disabled"
+  isSelected={isSelected}
+  onSelectedChange={setIsSelected}
+>
+  <Checkbox.Indicator />
+</Checkbox>;
+
+{
+  /* Disable only indicator animation */
+}
+<Checkbox isSelected={isSelected} onSelectedChange={setIsSelected}>
+  <Checkbox.Indicator animation="disabled" />
+</Checkbox>;
+
+{
+  /* Custom animation configuration */
+}
+<Checkbox
+  animation={{ scale: { value: [1, 0.9], timingConfig: { duration: 200 } } }}
+  isSelected={isSelected}
+  onSelectedChange={setIsSelected}
+>
+  <Checkbox.Indicator
+    animation={{
+      scale: { value: [0.5, 1] },
+      opacity: { value: [0, 1] },
+      translateX: { value: [-8, 0] },
+      borderRadius: { value: [12, 0] },
+    }}
+  />
+</Checkbox>;
+```
+
+## Example
+
+```tsx
+import {
+  Checkbox,
+  Description,
+  ControlField,
+  Label,
+  Separator,
+  Surface,
+} from '@/heroui';
+import React from 'react';
+import { View, Text } from 'react-native';
+
+interface CheckboxFieldProps {
+  isSelected: boolean;
+  onSelectedChange: (value: boolean) => void;
+  title: string;
+  description: string;
+}
+
+const CheckboxField: React.FC<CheckboxFieldProps> = ({
+  isSelected,
+  onSelectedChange,
+  title,
+  description,
+}) => {
+  return (
+    <ControlField isSelected={isSelected} onSelectedChange={onSelectedChange}>
+      <ControlField.Indicator>
+        <Checkbox className="mt-0.5" />
+      </ControlField.Indicator>
+      <View className="flex-1">
+        <Label className="text-lg">{title}</Label>
+        <Description className="text-base">{description}</Description>
+      </View>
+    </ControlField>
+  );
+};
+
+export default function BasicUsage() {
+  const [fields, setFields] = React.useState({
+    newsletter: true,
+    marketing: false,
+    terms: false,
+  });
+
+  const fieldConfigs: Record<
+    keyof typeof fields,
+    { title: string; description: string }
+  > = {
+    newsletter: {
+      title: 'Subscribe to newsletter',
+      description: 'Get weekly updates about new features and tips',
+    },
+    marketing: {
+      title: 'Marketing communications',
+      description: 'Receive promotional emails and special offers',
+    },
+    terms: {
+      title: 'Accept terms and conditions',
+      description: 'Agree to our Terms of Service and Privacy Policy',
+    },
+  };
+
+  const handleFieldChange = (key: keyof typeof fields) => (value: boolean) => {
+    setFields((prev) => ({ ...prev, [key]: value }));
+  };
+
+  const fieldKeys = Object.keys(fields) as Array<keyof typeof fields>;
+
+  return (
+    <View className="flex-1 items-center justify-center px-5">
+      <Surface className="py-5 w-full">
+        {fieldKeys.map((key, index) => (
+          <React.Fragment key={key}>
+            {index > 0 && <Separator className="my-4" />}
+            <CheckboxField
+              isSelected={fields[key]}
+              onSelectedChange={handleFieldChange(key)}
+              title={fieldConfigs[key].title}
+              description={fieldConfigs[key].description}
+            />
+          </React.Fragment>
+        ))}
+      </Surface>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/(home)/components/checkbox.tsx>).
+
+## API Reference
+
+### Checkbox
+
+| prop                    | type                                                                   | default     | description                                                               |
+| ----------------------- | ---------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- |
+| `children`              | `React.ReactNode \| ((props: CheckboxRenderProps) => React.ReactNode)` | `undefined` | Child elements or render function to customize the checkbox               |
+| `isSelected`            | `boolean`                                                              | `undefined` | Whether the checkbox is currently selected                                |
+| `onSelectedChange`      | `(isSelected: boolean) => void`                                        | `undefined` | Callback fired when the checkbox selection state changes                  |
+| `isDisabled`            | `boolean`                                                              | `false`     | Whether the checkbox is disabled and cannot be interacted with            |
+| `isInvalid`             | `boolean`                                                              | `false`     | Whether the checkbox is invalid (shows danger color)                      |
+| `variant`               | `'primary' \| 'secondary'`                                             | `'primary'` | Variant style for the checkbox                                            |
+| `hitSlop`               | `number`                                                               | `6`         | Hit slop for the pressable area                                           |
+| `animation`             | `CheckboxRootAnimation`                                                | -           | Animation configuration                                                   |
+| `isAnimatedStyleActive` | `boolean`                                                              | `true`      | Whether animated styles (react-native-reanimated) are active              |
+| `className`             | `string`                                                               | `undefined` | Additional CSS classes to apply                                           |
+| `...PressableProps`     | `PressableProps`                                                       | -           | All standard React Native Pressable props are supported (except disabled) |
+
+#### CheckboxRenderProps
+
+| prop         | type      | description                      |
+| ------------ | --------- | -------------------------------- |
+| `isSelected` | `boolean` | Whether the checkbox is selected |
+| `isInvalid`  | `boolean` | Whether the checkbox is invalid  |
+| `isDisabled` | `boolean` | Whether the checkbox is disabled |
+
+#### CheckboxRootAnimation
+
+Animation configuration for checkbox 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 |
+| `scale.value`        | `[number, number]`                       | `[1, 0.96]`         | Scale values [unpressed, pressed]               |
+| `scale.timingConfig` | `WithTimingConfig`                       | `{ duration: 150 }` | Animation timing configuration                  |
+
+### Checkbox.Indicator
+
+| prop                    | type                                                                   | default     | description                                                  |
+| ----------------------- | ---------------------------------------------------------------------- | ----------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode \| ((props: CheckboxRenderProps) => React.ReactNode)` | `undefined` | Content or render function for the checkbox indicator        |
+| `className`             | `string`                                                               | `undefined` | Additional CSS classes for the indicator                     |
+| `iconProps`             | `CheckboxIndicatorIconProps`                                           | `undefined` | Custom props for the default animated check icon             |
+| `animation`             | `CheckboxIndicatorAnimation`                                           | -           | Animation configuration                                      |
+| `isAnimatedStyleActive` | `boolean`                                                              | `true`      | Whether animated styles (react-native-reanimated) are active |
+| `...AnimatedViewProps`  | `AnimatedProps<ViewProps>`                                             | -           | All standard React Native Animated View props are supported  |
+
+#### CheckboxIndicatorIconProps
+
+Props for customizing the default animated check icon.
+
+| prop            | type     | description                                      |
+| --------------- | -------- | ------------------------------------------------ |
+| `size`          | `number` | Icon size                                        |
+| `strokeWidth`   | `number` | Icon stroke width                                |
+| `color`         | `string` | Icon color (defaults to theme accent-foreground) |
+| `enterDuration` | `number` | Duration of enter animation (check appearing)    |
+| `exitDuration`  | `number` | Duration of exit animation (check disappearing)  |
+
+#### CheckboxIndicatorAnimation
+
+Animation configuration for checkbox indicator 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]`      | `[0, 1]`            | Opacity values [unselected, selected]           |
+| `opacity.timingConfig`      | `WithTimingConfig`      | `{ duration: 100 }` | Animation timing configuration                  |
+| `borderRadius.value`        | `[number, number]`      | `[8, 0]`            | Border radius values [unselected, selected]     |
+| `borderRadius.timingConfig` | `WithTimingConfig`      | `{ duration: 50 }`  | Animation timing configuration                  |
+| `translateX.value`          | `[number, number]`      | `[-4, 0]`           | TranslateX values [unselected, selected]        |
+| `translateX.timingConfig`   | `WithTimingConfig`      | `{ duration: 100 }` | Animation timing configuration                  |
+| `scale.value`               | `[number, number]`      | `[0.8, 1]`          | Scale values [unselected, selected]             |
+| `scale.timingConfig`        | `WithTimingConfig`      | `{ duration: 100 }` | Animation timing configuration                  |
+
+## Hooks
+
+### useCheckbox
+
+Hook to access checkbox context values within custom components or compound components.
+
+```tsx
+import { useCheckbox } from '@/heroui';
+
+const CustomIndicator = () => {
+  const { isSelected, isInvalid, isDisabled } = useCheckbox();
+  // ... your implementation
+};
+```
+
+**Returns:** `UseCheckboxReturn`
+
+| property           | type                                           | description                                                    |
+| ------------------ | ---------------------------------------------- | -------------------------------------------------------------- |
+| `isSelected`       | `boolean \| undefined`                         | Whether the checkbox is currently selected                     |
+| `onSelectedChange` | `((isSelected: boolean) => void) \| undefined` | Callback function to change the checkbox selection state       |
+| `isDisabled`       | `boolean`                                      | Whether the checkbox is disabled and cannot be interacted with |
+| `isInvalid`        | `boolean`                                      | Whether the checkbox is invalid (shows danger color)           |
+| `nativeID`         | `string \| undefined`                          | Native ID for the checkbox element                             |
+
+**Note:** This hook must be used within a `Checkbox` component. It will throw an error if called outside of the checkbox context.

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

@@ -0,0 +1,105 @@
+import { StyleSheet } from 'react-native';
+import { tv } from 'tailwind-variants';
+import { combineStyles } from '../../helpers/internal/utils';
+
+/**
+ * Root style definition
+ *
+ * @note ANIMATED PROPERTIES (cannot be set via className):
+ * The following property is animated and cannot be overridden using Tailwind classes:
+ * - `transform` (specifically `scale`) - Animated for press feedback transitions (unpressed: 1, pressed: 0.96)
+ *
+ * To customize this property, use the `animation` prop on `Checkbox`:
+ * ```tsx
+ * <Checkbox
+ *   animation={{
+ *     scale: { value: [1, 0.96], timingConfig: { duration: 150 } }
+ *   }}
+ * />
+ * ```
+ *
+ * To completely disable animated styles and apply your own via className or style prop,
+ * set `isAnimatedStyleActive={false}` on `Checkbox`.
+ */
+const root = tv({
+  base: 'size-6 rounded-lg overflow-hidden',
+  variants: {
+    variant: {
+      primary: 'bg-field shadow-field',
+      secondary: 'bg-default',
+    },
+    isSelected: {
+      true: '',
+      false: '',
+    },
+    isDisabled: {
+      true: 'opacity-disabled pointer-events-none',
+      false: '',
+    },
+    isInvalid: {
+      true: 'border border-danger',
+      false: 'border-0',
+    },
+  },
+  compoundVariants: [
+    {
+      isSelected: false,
+      isInvalid: true,
+      className: 'bg-transparent',
+    },
+  ],
+  defaultVariants: {
+    variant: 'primary',
+    isSelected: false,
+    isDisabled: false,
+    isInvalid: false,
+  },
+});
+
+/**
+ * Indicator style definition
+ *
+ * @note ANIMATED PROPERTIES (cannot be set via className):
+ * The following properties are animated and cannot be overridden using Tailwind classes:
+ * - `opacity` - Animated for selection transitions (unselected: 0, selected: 1)
+ * - `borderRadius` - Animated for selection transitions (unselected: 8, selected: 0)
+ * - `transform` (specifically `translateX` and `scale`) - Animated for selection transitions (translateX: unselected: -4, selected: 0; scale: unselected: 0.8, selected: 1)
+ *
+ * To customize these properties, use the `animation` prop on `Checkbox.Indicator`:
+ * ```tsx
+ * <Checkbox.Indicator
+ *   animation={{
+ *     opacity: { value: [0, 1], timingConfig: { duration: 100 } },
+ *     borderRadius: { value: [8, 0], timingConfig: { duration: 50 } },
+ *     translateX: { value: [-4, 0], timingConfig: { duration: 100 } },
+ *     scale: { value: [0.8, 1], timingConfig: { duration: 100 } }
+ *   }}
+ * />
+ * ```
+ *
+ * To completely disable animated styles and apply your own via className or style prop,
+ * set `isAnimatedStyleActive={false}` on `Checkbox.Indicator`.
+ */
+const indicator = tv({
+  base: 'absolute inset-0 items-center justify-center',
+  variants: {
+    isInvalid: {
+      true: 'bg-danger',
+      false: 'bg-accent',
+    },
+  },
+  defaultVariants: {
+    isInvalid: false,
+  },
+});
+
+export const checkboxClassNames = combineStyles({
+  root,
+  indicator,
+});
+
+export const checkboxStyleSheet = StyleSheet.create({
+  root: {
+    borderCurve: 'continuous',
+  },
+});

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

@@ -0,0 +1,251 @@
+import { forwardRef, useCallback, useMemo } from 'react';
+import { View, type GestureResponderEvent } from 'react-native';
+import Animated from 'react-native-reanimated';
+import { useIsOnSurface, useThemeColor } from '../../helpers/external/hooks';
+import {
+  AnimatedCheckIcon,
+  CheckIcon,
+} from '../../helpers/internal/components';
+import { AnimationSettingsProvider } from '../../helpers/internal/contexts';
+import * as CheckboxPrimitives from '../../primitives/checkbox';
+import * as CheckboxPrimitivesTypes from '../../primitives/checkbox/checkbox.types';
+import {
+  CheckboxAnimationProvider,
+  useCheckboxIndicatorAnimation,
+  useCheckboxRootAnimation,
+} from './checkbox.animation';
+import { DEFAULT_HIT_SLOP, DISPLAY_NAME } from './checkbox.constants';
+import { checkboxClassNames, checkboxStyleSheet } from './checkbox.styles';
+import type {
+  CheckboxIndicatorProps,
+  CheckboxProps,
+  CheckboxRenderProps,
+} from './checkbox.types';
+
+const AnimatedRootView = Animated.createAnimatedComponent(
+  CheckboxPrimitives.Root
+);
+
+const AnimatedIndicatorView = Animated.createAnimatedComponent(
+  CheckboxPrimitives.Indicator
+);
+
+const useCheckbox = CheckboxPrimitives.useCheckboxContext;
+
+// --------------------------------------------------
+
+const CheckboxRoot = forwardRef<CheckboxPrimitivesTypes.RootRef, CheckboxProps>(
+  (props, ref) => {
+    const {
+      children,
+      isSelected,
+      onSelectedChange,
+      isDisabled = false,
+      isInvalid = false,
+      variant,
+      hitSlop = DEFAULT_HIT_SLOP,
+      className,
+      style,
+      onPressIn,
+      onPressOut,
+      animation,
+      isAnimatedStyleActive = true,
+      ...restProps
+    } = props;
+
+    const isOnSurfaceAutoDetected = useIsOnSurface();
+    const finalVariant =
+      variant !== undefined
+        ? variant
+        : isOnSurfaceAutoDetected
+          ? 'secondary'
+          : 'primary';
+
+    const rootClassName = checkboxClassNames.root({
+      variant: finalVariant,
+      isSelected,
+      isDisabled,
+      isInvalid,
+      className,
+    });
+
+    const { rContainerStyle, isCheckboxPressed, isAllAnimationsDisabled } =
+      useCheckboxRootAnimation({
+        animation,
+      });
+
+    const rootStyle = isAnimatedStyleActive
+      ? [rContainerStyle, checkboxStyleSheet.root, style]
+      : [checkboxStyleSheet.root, style];
+
+    const animationContextValue = useMemo(
+      () => ({
+        isCheckboxPressed,
+      }),
+      [isCheckboxPressed]
+    );
+
+    const animationSettingsContextValue = useMemo(
+      () => ({
+        isAllAnimationsDisabled,
+      }),
+      [isAllAnimationsDisabled]
+    );
+
+    const handlePressIn = useCallback(
+      (event: GestureResponderEvent) => {
+        isCheckboxPressed.set(true);
+        onPressIn?.(event);
+      },
+      [isCheckboxPressed, onPressIn]
+    );
+
+    const handlePressOut = useCallback(
+      (event: GestureResponderEvent) => {
+        isCheckboxPressed.set(false);
+        onPressOut?.(event);
+      },
+      [isCheckboxPressed, onPressOut]
+    );
+
+    const renderProps: CheckboxRenderProps = {
+      isSelected,
+      isInvalid,
+      isDisabled,
+    };
+
+    const content =
+      typeof children === 'function'
+        ? children(renderProps)
+        : (children ?? <CheckboxIndicator />);
+
+    return (
+      <AnimationSettingsProvider value={animationSettingsContextValue}>
+        <CheckboxAnimationProvider value={animationContextValue}>
+          <AnimatedRootView
+            ref={ref}
+            className={rootClassName}
+            isSelected={isSelected}
+            onSelectedChange={onSelectedChange}
+            isDisabled={isDisabled}
+            isInvalid={isInvalid}
+            hitSlop={hitSlop}
+            onPressIn={handlePressIn}
+            onPressOut={handlePressOut}
+            style={rootStyle}
+            {...restProps}
+          >
+            {content}
+          </AnimatedRootView>
+        </CheckboxAnimationProvider>
+      </AnimationSettingsProvider>
+    );
+  }
+);
+
+// --------------------------------------------------
+
+const CheckboxIndicator = forwardRef<
+  CheckboxPrimitivesTypes.IndicatorRef,
+  CheckboxIndicatorProps
+>((props, ref) => {
+  const {
+    children,
+    iconProps,
+    className,
+    style,
+    animation,
+    isAnimatedStyleActive = true,
+    ...restProps
+  } = props;
+
+  const { isSelected, isDisabled, isInvalid } = useCheckbox();
+
+  const themeColorAccentForeground = useThemeColor('accent-foreground');
+
+  const iconSize = iconProps?.size;
+  const iconStrokeWidth = iconProps?.strokeWidth;
+  const iconColor = iconProps?.color ?? themeColorAccentForeground;
+  const iconEnterDuration = iconProps?.enterDuration;
+  const iconExitDuration = iconProps?.exitDuration;
+
+  const indicatorClassName = checkboxClassNames.indicator({
+    isInvalid,
+    className,
+  });
+
+  const { rContainerStyle, isAnimationDisabled } =
+    useCheckboxIndicatorAnimation({
+      animation,
+      isSelected,
+    });
+
+  const indicatorStyle = isAnimatedStyleActive
+    ? [rContainerStyle, style]
+    : style;
+
+  const renderProps: CheckboxRenderProps = {
+    isSelected,
+    isInvalid: isInvalid ?? false,
+    isDisabled: isDisabled ?? false,
+  };
+
+  const content =
+    typeof children === 'function'
+      ? children(renderProps)
+      : (children ??
+        (isAnimationDisabled ? (
+          <View className="translate-y-px">
+            <CheckIcon size={iconSize} color={iconColor} />
+          </View>
+        ) : (
+          <AnimatedCheckIcon
+            size={iconSize}
+            strokeWidth={iconStrokeWidth}
+            color={iconColor}
+            isSelected={isSelected}
+            enterDuration={iconEnterDuration}
+            exitDuration={iconExitDuration}
+          />
+        )));
+
+  return (
+    <AnimatedIndicatorView
+      ref={ref}
+      className={indicatorClassName}
+      style={indicatorStyle}
+      {...restProps}
+    >
+      {content}
+    </AnimatedIndicatorView>
+  );
+});
+
+// --------------------------------------------------
+
+CheckboxRoot.displayName = DISPLAY_NAME.CHECKBOX_ROOT;
+CheckboxIndicator.displayName = DISPLAY_NAME.CHECKBOX_INDICATOR;
+
+/**
+ * Compound Checkbox component with sub-components
+ *
+ * @component Checkbox - Main container that handles selection state and user interaction.
+ * Renders default indicator with checkmark if no children provided.
+ * Animates background and border color based on selection state.
+ *
+ * @component Checkbox.Indicator - Optional checkmark container that scales in when selected.
+ * Renders default check icon if no children provided. Handles enter/exit animations
+ * and can be replaced with custom indicators.
+ *
+ * Props flow from Checkbox to sub-components via context (isSelected).
+ * The checkbox supports controlled and uncontrolled modes through isSelected/onSelectedChange.
+ *
+ * @see Full documentation: https://v3.heroui.com/docs/native/components/checkbox
+ */
+const CompoundCheckbox = Object.assign(CheckboxRoot, {
+  /** @optional Custom indicator with scale animations */
+  Indicator: CheckboxIndicator,
+});
+
+export { useCheckbox };
+export default CompoundCheckbox;