@coze-arch/cli 0.0.10 → 0.0.11

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

@@ -0,0 +1,243 @@
+import type { ViewStyle } from 'react-native';
+import {
+  useAnimatedStyle,
+  useSharedValue,
+  withSpring,
+  withTiming,
+} from 'react-native-reanimated';
+import { useThemeColor } from '../../helpers/external/hooks';
+import { useAnimationSettings } from '../../helpers/internal/contexts';
+import {
+  useCombinedAnimationDisabledState,
+  useResolvedStyleProperty,
+} from '../../helpers/internal/hooks';
+import {
+  createContext,
+  getAnimationState,
+  getAnimationValueMergedConfig,
+  getAnimationValueProperty,
+  getIsAnimationDisabledValue,
+  getRootAnimationState,
+} from '../../helpers/internal/utils';
+import { useControlField } from '../control-field/control-field.context';
+import {
+  DEFAULT_SPRING_CONFIG,
+  DEFAULT_THUMB_LEFT,
+  DEFAULT_THUMB_WIDTH,
+  DEFAULT_TIMING_CONFIG,
+} from './switch.constants';
+import type {
+  SwitchAnimationContextValue,
+  SwitchRootAnimation,
+  SwitchThumbAnimation,
+} from './switch.types';
+
+const [SwitchAnimationProvider, useSwitchAnimation] =
+  createContext<SwitchAnimationContextValue>({
+    name: 'SwitchAnimationContext',
+  });
+
+export { SwitchAnimationProvider, useSwitchAnimation };
+
+// --------------------------------------------------
+
+/**
+ * Animation hook for Switch root component
+ * Handles scale and background color animations and provides context for child components
+ */
+export function useSwitchRootAnimation(options: {
+  animation: SwitchRootAnimation | undefined;
+  isSelected: boolean | undefined;
+}) {
+  const { animation, isSelected } = options;
+
+  const [themeColorAccent, themeColorDefault] = useThemeColor([
+    'accent',
+    'default',
+  ]);
+
+  const controlFieldContext = useControlField();
+
+  const isSwitchPressed = useSharedValue(false);
+  const contentContainerWidth = useSharedValue(0);
+
+  const { animationConfig, isAnimationDisabled } =
+    getRootAnimationState(animation);
+
+  const isAllAnimationsDisabled = useCombinedAnimationDisabledState(animation);
+
+  const isAnimationDisabledValue = getIsAnimationDisabledValue({
+    isAnimationDisabled,
+    isAllAnimationsDisabled,
+  });
+
+  // Scale animation
+  const scaleValue = getAnimationValueProperty({
+    animationValue: animationConfig?.scale,
+    property: 'value',
+    defaultValue: [1, 0.96] as [number, number],
+  });
+
+  const scaleTimingConfig = getAnimationValueMergedConfig({
+    animationValue: animationConfig?.scale,
+    property: 'timingConfig',
+    defaultValue: { duration: 150 },
+  });
+
+  // Background color animation
+  const backgroundColorValue = getAnimationValueProperty({
+    animationValue: animationConfig?.backgroundColor,
+    property: 'value',
+    defaultValue: [themeColorDefault, themeColorAccent] as [string, string],
+  });
+
+  const backgroundColorTimingConfig = getAnimationValueMergedConfig({
+    animationValue: animationConfig?.backgroundColor,
+    property: 'timingConfig',
+    defaultValue: DEFAULT_TIMING_CONFIG,
+  });
+
+  const rContainerStyle = useAnimatedStyle(() => {
+    if (isAnimationDisabledValue) {
+      return {
+        backgroundColor: isSelected
+          ? backgroundColorValue[1]
+          : backgroundColorValue[0],
+      };
+    }
+
+    const pressed =
+      isSwitchPressed.get() || (controlFieldContext?.isPressed.get() ?? false);
+
+    return {
+      backgroundColor: withTiming(
+        isSelected ? backgroundColorValue[1] : backgroundColorValue[0],
+        backgroundColorTimingConfig
+      ),
+      transform: [
+        {
+          scale: withTiming(
+            pressed ? scaleValue[1] : scaleValue[0],
+            scaleTimingConfig
+          ),
+        },
+      ],
+    };
+  });
+
+  return {
+    rContainerStyle,
+    isSwitchPressed,
+    contentContainerWidth,
+    isAllAnimationsDisabled,
+  };
+}
+
+// --------------------------------------------------
+
+/**
+ * Animation hook for Switch thumb component
+ * Handles thumb position (left) and background color animations
+ */
+export function useSwitchThumbAnimation(options: {
+  animation: SwitchThumbAnimation | undefined;
+  style: ViewStyle | undefined;
+  className: string;
+  isSelected: boolean | undefined;
+}) {
+  const { animation, style, className, isSelected } = options;
+
+  const themeColorAccentForeground = useThemeColor('accent-foreground');
+
+  const [width, left] = useResolvedStyleProperty({
+    className,
+    style,
+    propertyNames: ['width', 'left'] as const,
+  });
+
+  const computedWidth = typeof width === 'number' ? width : DEFAULT_THUMB_WIDTH;
+  const computedLeft = typeof left === 'number' ? left : DEFAULT_THUMB_LEFT;
+
+  // Read from global animation context (always available in compound parts)
+  const { isAllAnimationsDisabled } = useAnimationSettings();
+
+  const { contentContainerWidth } = useSwitchAnimation();
+
+  const { animationConfig, isAnimationDisabled } = getAnimationState(animation);
+
+  const isAnimationDisabledValue = getIsAnimationDisabledValue({
+    isAnimationDisabled,
+    isAllAnimationsDisabled,
+  });
+
+  // Left position animation
+  const leftValue = getAnimationValueProperty({
+    animationValue: animationConfig?.left,
+    property: 'value',
+    defaultValue: computedLeft,
+  });
+
+  const leftSpringConfig = getAnimationValueMergedConfig({
+    animationValue: animationConfig?.left,
+    property: 'springConfig',
+    defaultValue: DEFAULT_SPRING_CONFIG,
+  });
+
+  // Background color animation
+  const backgroundColorValue = getAnimationValueProperty({
+    animationValue: animationConfig?.backgroundColor,
+    property: 'value',
+    defaultValue: ['white', themeColorAccentForeground] as [string, string],
+  });
+
+  const backgroundColorTimingConfig = getAnimationValueMergedConfig({
+    animationValue: animationConfig?.backgroundColor,
+    property: 'timingConfig',
+    defaultValue: DEFAULT_TIMING_CONFIG,
+  });
+
+  const rContainerStyle = useAnimatedStyle(() => {
+    const isMounted = contentContainerWidth.get() > 0;
+
+    // This is done to prevent the thumb from moving from the default position to the right
+    // when the component is mounted with `isSelected` set to `true`,
+    // and the user hasn't touched the switch yet.
+    if (!isMounted) {
+      if (isSelected) {
+        return {
+          right: leftValue,
+          backgroundColor: backgroundColorValue[1],
+        };
+      }
+      return {
+        left: leftValue,
+        backgroundColor: backgroundColorValue[0],
+      };
+    }
+
+    const targetLeft = isSelected
+      ? contentContainerWidth.get() - computedWidth - leftValue
+      : leftValue;
+
+    if (isAnimationDisabledValue) {
+      return {
+        left: targetLeft,
+        backgroundColor: isSelected
+          ? backgroundColorValue[1]
+          : backgroundColorValue[0],
+      };
+    }
+
+    return {
+      left: withSpring(targetLeft, leftSpringConfig),
+      backgroundColor: withTiming(
+        isSelected ? backgroundColorValue[1] : backgroundColorValue[0],
+        backgroundColorTimingConfig
+      ),
+    };
+  });
+
+  return {
+    rContainerStyle,
+  };
+}

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

@@ -0,0 +1,26 @@
+import { Easing } from 'react-native-reanimated';
+
+export const DISPLAY_NAME = {
+  SWITCH_ROOT: 'HeroUINative.Switch.Root',
+  SWITCH_THUMB: 'HeroUINative.Switch.Thumb',
+  SWITCH_START_CONTENT: 'HeroUINative.Switch.StartContent',
+  SWITCH_END_CONTENT: 'HeroUINative.Switch.EndContent',
+} as const;
+
+export const ANIMATION_DURATION = 175;
+export const ANIMATION_EASING = Easing.bezier(0.25, 0.1, 0.25, 1);
+
+export const DEFAULT_TIMING_CONFIG = {
+  duration: ANIMATION_DURATION,
+  easing: ANIMATION_EASING,
+};
+
+export const DEFAULT_SPRING_CONFIG = {
+  damping: 120,
+  stiffness: 1600,
+  mass: 2,
+};
+
+export const DEFAULT_THUMB_WIDTH = 28;
+
+export const DEFAULT_THUMB_LEFT = 2;

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

@@ -0,0 +1,334 @@
+# Switch
+
+A toggle control that allows users to switch between on and off states.
+
+## Import
+
+```tsx
+import { Switch } from '@/heroui';
+```
+
+## Anatomy
+
+```tsx
+<Switch>
+  <Switch.Thumb>...</Switch.Thumb>
+  <Switch.StartContent>...</Switch.StartContent>
+  <Switch.EndContent>...</Switch.EndContent>
+</Switch>
+```
+
+- **Switch**: Main container that handles toggle state and user interaction. Renders default thumb if no children provided. Animates scale (on press) and background color based on selection state. Acts as a pressable area for toggling.
+- **Switch.Thumb**: Optional sliding thumb element that moves between positions. Uses spring animation for smooth transitions. Can contain custom content like icons or be customized with different styles and animations.
+- **Switch.StartContent**: Optional content displayed on the left side of the switch. Typically used for icons or text that appear when switch is off. Positioned absolutely within the switch container.
+- **Switch.EndContent**: Optional content displayed on the right side of the switch. Typically used for icons or text that appear when switch is on. Positioned absolutely within the switch container.
+
+## Usage
+
+### Basic Usage
+
+The Switch component renders with default thumb if no children provided.
+
+```tsx
+<Switch isSelected={isSelected} onSelectedChange={setIsSelected} />
+```
+
+### With Custom Thumb
+
+Replace the default thumb with custom content using the Thumb component.
+
+```tsx
+<Switch isSelected={isSelected} onSelectedChange={setIsSelected}>
+  <Switch.Thumb>...</Switch.Thumb>
+</Switch>
+```
+
+### With Start and End Content
+
+Add icons or text that appear on each side of the switch.
+
+```tsx
+<Switch isSelected={isSelected} onSelectedChange={setIsSelected}>
+  <Switch.Thumb />
+  <Switch.StartContent>...</Switch.StartContent>
+  <Switch.EndContent>...</Switch.EndContent>
+</Switch>
+```
+
+### With Render Function
+
+Use render functions for dynamic content based on switch state.
+
+```tsx
+<Switch isSelected={isSelected} onSelectedChange={setIsSelected}>
+  {({ isSelected, isDisabled }) => (
+    <>
+      <Switch.Thumb>
+        {({ isSelected }) => (isSelected ? <CheckIcon /> : <XIcon />)}
+      </Switch.Thumb>
+    </>
+  )}
+</Switch>
+```
+
+### With Custom Animations
+
+Customize animations for the switch root and thumb components.
+
+```tsx
+<Switch
+  animation={{
+    scale: {
+      value: [1, 0.9],
+      timingConfig: { duration: 200 },
+    },
+    backgroundColor: {
+      value: ['#172554', '#eab308'],
+    },
+  }}
+>
+  <Switch.Thumb
+    animation={{
+      left: {
+        value: 4,
+        springConfig: {
+          damping: 30,
+          stiffness: 300,
+          mass: 1,
+        },
+      },
+      backgroundColor: {
+        value: ['#dbeafe', '#854d0e'],
+      },
+    }}
+  />
+</Switch>
+```
+
+### Disable Animations
+
+Disable animations entirely or only for specific components.
+
+```tsx
+{
+  /* Disable all animations including children */
+}
+<Switch animation="disable-all">
+  <Switch.Thumb />
+</Switch>;
+
+{
+  /* Disable only root animations, thumb can still animate */
+}
+<Switch>
+  <Switch.Thumb animation={false} />
+</Switch>;
+```
+
+## Example
+
+```tsx
+import { Switch } from '@/heroui';
+import { Ionicons } from '@expo/vector-icons';
+import React from 'react';
+import { View } from 'react-native';
+import Animated, { ZoomIn } from 'react-native-reanimated';
+
+export default function SwitchExample() {
+  const [darkMode, setDarkMode] = React.useState(false);
+
+  return (
+    <View className="flex-row gap-4">
+      <Switch
+        isSelected={darkMode}
+        onSelectedChange={setDarkMode}
+        className="w-[56px] h-[32px]"
+        animation={{
+          backgroundColor: {
+            value: ['#172554', '#eab308'],
+          },
+        }}
+      >
+        <Switch.Thumb
+          className="size-[22px]"
+          animation={{
+            left: {
+              value: 4,
+              springConfig: {
+                damping: 30,
+                stiffness: 300,
+                mass: 1,
+              },
+            },
+          }}
+        />
+        <Switch.StartContent className="left-2">
+          {darkMode && (
+            <Animated.View key="sun" entering={ZoomIn.springify()}>
+              <Ionicons name="sunny" size={16} color="#854d0e" />
+            </Animated.View>
+          )}
+        </Switch.StartContent>
+        <Switch.EndContent className="right-2">
+          {!darkMode && (
+            <Animated.View key="moon" entering={ZoomIn.springify()}>
+              <Ionicons name="moon" size={16} color="#dbeafe" />
+            </Animated.View>
+          )}
+        </Switch.EndContent>
+      </Switch>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/(home)/components/switch.tsx>).
+
+## API Reference
+
+### Switch
+
+| prop                        | type                                                                 | default     | description                                                  |
+| --------------------------- | -------------------------------------------------------------------- | ----------- | ------------------------------------------------------------ |
+| `children`                  | `React.ReactNode \| ((props: SwitchRenderProps) => React.ReactNode)` | `undefined` | Content to render inside the switch, or a render function    |
+| `isSelected`                | `boolean`                                                            | `undefined` | Whether the switch is currently selected                     |
+| `isDisabled`                | `boolean`                                                            | `false`     | Whether the switch is disabled and cannot be interacted with |
+| `className`                 | `string`                                                             | `undefined` | Custom class name for the switch                             |
+| `animation`                 | `SwitchRootAnimation`                                                | -           | Animation configuration                                      |
+| `isAnimatedStyleActive`     | `boolean`                                                            | `true`      | Whether animated styles (react-native-reanimated) are active |
+| `onSelectedChange`          | `(isSelected: boolean) => void`                                      | -           | Callback fired when the switch selection state changes       |
+| `...AnimatedPressableProps` | `AnimatedProps<PressableProps>`                                      | -           | All React Native Reanimated Pressable props are supported    |
+
+#### SwitchRenderProps
+
+| prop         | type      | description                    |
+| ------------ | --------- | ------------------------------ |
+| `isSelected` | `boolean` | Whether the switch is selected |
+| `isDisabled` | `boolean` | Whether the switch is disabled |
+
+#### SwitchRootAnimation
+
+Animation configuration for Switch 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                  |
+| `backgroundColor.value`        | `[string, string]`                       | Uses theme colors                                              | Background color values [unselected, selected]  |
+| `backgroundColor.timingConfig` | `WithTimingConfig`                       | `{ duration: 175, easing: Easing.bezier(0.25, 0.1, 0.25, 1) }` | Animation timing configuration                  |
+
+### Switch.Thumb
+
+| prop                    | type                                                                 | default     | description                                                  |
+| ----------------------- | -------------------------------------------------------------------- | ----------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode \| ((props: SwitchRenderProps) => React.ReactNode)` | `undefined` | Content to render inside the thumb, or a render function     |
+| `className`             | `string`                                                             | `undefined` | Custom class name for the thumb element                      |
+| `animation`             | `SwitchThumbAnimation`                                               | -           | Animation configuration                                      |
+| `isAnimatedStyleActive` | `boolean`                                                            | `true`      | Whether animated styles (react-native-reanimated) are active |
+| `...ViewProps`          | `ViewProps`                                                          | -           | All standard React Native View props are supported           |
+
+#### SwitchThumbAnimation
+
+Animation configuration for Switch.Thumb 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                         |
+| `left.value`                   | `number`                | `2`                                                            | Offset value from the edges (left when unselected, right when selected) |
+| `left.springConfig`            | `WithSpringConfig`      | `{ damping: 120, stiffness: 1600, mass: 2 }`                   | Spring animation configuration for thumb position                       |
+| `backgroundColor.value`        | `[string, string]`      | `['white', theme accent-foreground color]`                     | Background color values [unselected, selected]                          |
+| `backgroundColor.timingConfig` | `WithTimingConfig`      | `{ duration: 175, easing: Easing.bezier(0.25, 0.1, 0.25, 1) }` | Animation timing configuration                                          |
+
+### Switch.StartContent
+
+| prop           | type              | default     | description                                        |
+| -------------- | ----------------- | ----------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | `undefined` | Content to render inside the switch content        |
+| `className`    | `string`          | `undefined` | Custom class name for the content element          |
+| `...ViewProps` | `ViewProps`       | -           | All standard React Native View props are supported |
+
+### Switch.EndContent
+
+| prop           | type              | default     | description                                        |
+| -------------- | ----------------- | ----------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | `undefined` | Content to render inside the switch content        |
+| `className`    | `string`          | `undefined` | Custom class name for the content element          |
+| `...ViewProps` | `ViewProps`       | -           | All standard React Native View props are supported |
+
+## Hooks
+
+### useSwitch
+
+A hook that provides access to the Switch context. This is useful when building custom switch components or when you need to access switch state in child components.
+
+**Returns:**
+
+| Property     | Type      | Description                    |
+| ------------ | --------- | ------------------------------ |
+| `isSelected` | `boolean` | Whether the switch is selected |
+| `isDisabled` | `boolean` | Whether the switch is disabled |
+
+**Example:**
+
+```tsx
+import { useSwitch } from '@/heroui';
+
+function CustomSwitchContent() {
+  const { isSelected, isDisabled } = useSwitch();
+
+  return (
+    <View>
+      <Text>Status: {isSelected ? 'On' : 'Off'}</Text>
+      {isDisabled && <Text>Disabled</Text>}
+    </View>
+  );
+}
+
+// Usage
+<Switch>
+  <CustomSwitchContent />
+  <Switch.Thumb />
+</Switch>;
+```
+
+## Special Notes
+
+### Border Styling
+
+If you need to apply a border to the switch root, use the `outline` style properties instead of `border`. This ensures the border doesn't affect the internal layout calculations for the thumb position:
+
+```tsx
+<Switch className="outline outline-accent">
+  <Switch.Thumb />
+</Switch>
+```
+
+Using `outline` keeps the border visual without impacting the switch's internal width calculations, ensuring the thumb animates correctly.
+
+### Integration with ControlField
+
+The Switch component integrates seamlessly with ControlField for press state sharing:
+
+```tsx
+import { Description, ControlField, Label } from '@/heroui';
+
+<ControlField isSelected={isSelected} onSelectedChange={setIsSelected}>
+  <View className="flex-1">
+    <Label>Enable notifications</Label>
+    <Description>Receive push notifications</Description>
+  </View>
+  <ControlField.Indicator />
+</ControlField>;
+```
+
+When wrapped in ControlField, the Switch will automatically respond to press events on the entire ControlField container, creating a larger touch target and better user experience.

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

@@ -0,0 +1,83 @@
+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 properties are animated and cannot be overridden using Tailwind classes:
+ * - `backgroundColor` - Animated for selection transitions (unselected: default, selected: accent)
+ * - `transform` (specifically `scale`) - Animated for press feedback transitions (unpressed: 1, pressed: 0.96)
+ *
+ * To customize these properties, use the `animation` prop on `Switch`:
+ * ```tsx
+ * <Switch
+ *   animation={{
+ *     backgroundColor: { value: ['#e5e5e5', '#007AFF'], timingConfig: { duration: 175 } },
+ *     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 `Switch`.
+ */
+const root = tv({
+  base: 'w-[48px] h-[24px] rounded-full justify-center overflow-hidden',
+  variants: {
+    isDisabled: {
+      true: 'opacity-disabled pointer-events-none',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    isDisabled: false,
+  },
+});
+
+/**
+ * Thumb style definition
+ *
+ * @note ANIMATED PROPERTIES (cannot be set via className):
+ * The following properties are animated and cannot be overridden using Tailwind classes:
+ * - `left` - Animated for thumb position transitions (unselected: left edge offset, selected: right edge offset)
+ * - `backgroundColor` - Animated for selection transitions (unselected: white, selected: accent-foreground)
+ *
+ * To customize these properties, use the `animation` prop on `Switch.Thumb`:
+ * ```tsx
+ * <Switch.Thumb
+ *   animation={{
+ *     left: { value: 2, springConfig: { damping: 120, stiffness: 1600, mass: 2 } },
+ *     backgroundColor: { value: ['white', '#ffffff'], timingConfig: { duration: 175 } }
+ *   }}
+ * />
+ * ```
+ *
+ * To completely disable animated styles and apply your own via className or style prop,
+ * set `isAnimatedStyleActive={false}` on `Switch.Thumb`.
+ */
+const thumb = tv({
+  base: 'absolute left-[2px] items-center justify-center w-[28px] h-[20px] rounded-full shadow-field overflow-hidden',
+});
+
+const startContent = tv({
+  base: 'absolute left-[2px]',
+});
+
+const endContent = tv({
+  base: 'absolute right-[2px]',
+});
+
+export const switchClassNames = combineStyles({
+  root,
+  thumb,
+  startContent,
+  endContent,
+});
+
+export const switchStyleSheet = StyleSheet.create({
+  borderCurve: {
+    borderCurve: 'continuous',
+  },
+});