@coze-arch/cli 0.0.10 → 0.0.11

package/lib/__templates__/expo/client/heroui/components/radio-group/radio-group.tsx

@@ -0,0 +1,220 @@
+import { forwardRef, useCallback, useMemo } from 'react';
+
+import { useIsOnSurface } from '../../helpers/external/hooks';
+import {
+  AnimationSettingsProvider,
+  FormFieldProvider,
+} from '../../helpers/internal/contexts';
+import { childrenToString } from '../../helpers/internal/utils';
+import * as RadioGroupPrimitives from '../../primitives/radio-group';
+import Label from '../label/label';
+import Radio from '../radio/radio';
+import { useRadioGroupRootAnimation } from './radio-group.animation';
+import { DISPLAY_NAME } from './radio-group.constants';
+import { RadioGroupItemProvider } from './radio-group.context';
+import { radioGroupClassNames } from './radio-group.styles';
+import type {
+  RadioGroupItemProps,
+  RadioGroupItemRenderProps,
+  RadioGroupProps,
+} from './radio-group.types';
+
+const useRadioGroup = RadioGroupPrimitives.useRadioGroupContext;
+
+// --------------------------------------------------
+
+const RadioGroupRoot = forwardRef<
+  RadioGroupPrimitives.RootRef,
+  RadioGroupProps
+>((props, ref) => {
+  const {
+    className,
+    isDisabled = false,
+    isInvalid = false,
+    animation,
+    ...restProps
+  } = props;
+
+  const rootClassName = radioGroupClassNames.root({
+    className,
+  });
+
+  const { isAllAnimationsDisabled } = useRadioGroupRootAnimation({
+    animation,
+  });
+
+  const animationSettingsContextValue = useMemo(
+    () => ({
+      isAllAnimationsDisabled,
+    }),
+    [isAllAnimationsDisabled]
+  );
+
+  const formFieldContextValue = useMemo(
+    () => ({
+      isDisabled,
+      isInvalid,
+      isRequired: false,
+      hasFieldPadding: false,
+    }),
+    [isDisabled, isInvalid]
+  );
+
+  return (
+    <AnimationSettingsProvider value={animationSettingsContextValue}>
+      <FormFieldProvider value={formFieldContextValue}>
+        <RadioGroupPrimitives.Root
+          ref={ref}
+          className={rootClassName}
+          isDisabled={isDisabled}
+          isInvalid={isInvalid}
+          {...restProps}
+        />
+      </FormFieldProvider>
+    </AnimationSettingsProvider>
+  );
+});
+
+// --------------------------------------------------
+
+const RadioGroupItem = forwardRef<
+  RadioGroupPrimitives.ItemRef,
+  RadioGroupItemProps
+>((props, ref) => {
+  const {
+    children,
+    value,
+    isDisabled,
+    isInvalid,
+    variant,
+    className,
+    ...restProps
+  } = props;
+
+  const stringifiedChildren =
+    typeof children === 'function'
+      ? null
+      : childrenToString(children as React.ReactNode);
+
+  const {
+    value: groupValue,
+    onValueChange: groupOnValueChange,
+    isInvalid: groupIsInvalid,
+    isDisabled: groupIsDisabled,
+    variant: groupVariant,
+  } = useRadioGroup();
+
+  const isSelected = groupValue === value;
+  const isDisabledValue = isDisabled ?? groupIsDisabled ?? false;
+  const isInvalidValue = isInvalid ?? groupIsInvalid ?? false;
+
+  /** Selects this item in the group (radio behavior: always selects, never deselects) */
+  const handleSelectedChange = useCallback(() => {
+    groupOnValueChange(value);
+  }, [groupOnValueChange, value]);
+
+  const isOnSurfaceAutoDetected = useIsOnSurface();
+
+  const finalVariant =
+    variant !== undefined
+      ? variant
+      : groupVariant !== undefined
+        ? groupVariant
+        : isOnSurfaceAutoDetected
+          ? 'secondary'
+          : 'primary';
+
+  const itemClassName = radioGroupClassNames.item({
+    className,
+  });
+
+  const renderProps: RadioGroupItemRenderProps = {
+    isSelected,
+    isDisabled: isDisabledValue,
+    isInvalid: isInvalidValue,
+  };
+
+  const content = stringifiedChildren ? (
+    <>
+      <Label>{stringifiedChildren}</Label>
+      <Radio />
+    </>
+  ) : typeof children === 'function' ? (
+    children(renderProps)
+  ) : (
+    children
+  );
+
+  const contextValue = useMemo(
+    () => ({
+      isSelected,
+      isDisabled: isDisabledValue,
+      isInvalid: isInvalidValue,
+      variant: finalVariant,
+      onSelectedChange: handleSelectedChange,
+    }),
+    [
+      isSelected,
+      isDisabledValue,
+      isInvalidValue,
+      finalVariant,
+      handleSelectedChange,
+    ]
+  );
+
+  const formFieldContextValue = useMemo(
+    () => ({
+      isDisabled: isDisabledValue,
+      isInvalid: isInvalidValue,
+      isRequired: false,
+      hasFieldPadding: false,
+    }),
+    [isDisabledValue, isInvalidValue]
+  );
+
+  return (
+    <FormFieldProvider value={formFieldContextValue}>
+      <RadioGroupItemProvider value={contextValue}>
+        <RadioGroupPrimitives.Item
+          ref={ref}
+          value={value}
+          className={itemClassName}
+          isDisabled={isDisabledValue}
+          {...restProps}
+        >
+          {content}
+        </RadioGroupPrimitives.Item>
+      </RadioGroupItemProvider>
+    </FormFieldProvider>
+  );
+});
+
+RadioGroupRoot.displayName = DISPLAY_NAME.RADIO_GROUP_ROOT;
+RadioGroupItem.displayName = DISPLAY_NAME.RADIO_GROUP_ITEM;
+
+/**
+ * Compound RadioGroup component with sub-components.
+ *
+ * @component RadioGroup - Container that manages the selection state of RadioGroupItem components.
+ * Supports both horizontal and vertical orientations.
+ *
+ * @component RadioGroup.Item - Individual radio option within a RadioGroup. Must be used inside
+ * RadioGroup. Handles selection state and renders a default `<Radio />` indicator if text children
+ * are provided. Supports render function children to access state.
+ *
+ * Use the `Radio` component (and its sub-components `Radio.Indicator`, `Radio.IndicatorThumb`)
+ * inside RadioGroup.Item for custom indicator rendering. The Radio component automatically detects
+ * the RadioGroupItem context and derives selection state from it.
+ *
+ * Props flow from RadioGroup to RadioGroupItem to Radio via context (variant, value, isSelected).
+ * RadioGroup manages the overall selection state and orientation.
+ *
+ * @see Full documentation: https://v3.heroui.com/docs/native/components/radio-group
+ */
+const CompoundRadioGroup = Object.assign(RadioGroupRoot, {
+  /** Individual radio option within a RadioGroup */
+  Item: RadioGroupItem,
+});
+
+export default CompoundRadioGroup;
+export { useRadioGroup };

package/lib/__templates__/expo/client/heroui/components/radio-group/radio-group.types.ts

@@ -0,0 +1,64 @@
+import type { AnimationRootDisableAll } from '../../helpers/internal/types';
+import type { ItemProps, RootProps } from '../../primitives/radio-group';
+
+/**
+ * Props for RadioGroup root component
+ */
+export interface RadioGroupProps extends Omit<RootProps, 'asChild'> {
+  /** Radio group content */
+  children?: React.ReactNode;
+  /** Custom class name */
+  className?: string;
+  /**
+   * Animation configuration for radio group
+   * - `"disable-all"`: Disable all animations including children
+   * - `undefined`: Use default animations
+   */
+  animation?: AnimationRootDisableAll;
+}
+
+/**
+ * Context values shared between RadioGroupItem compound components
+ */
+export interface RadioGroupItemContextValue {
+  /** Whether the radio item is selected */
+  isSelected: boolean;
+  /** Whether the radio item is disabled */
+  isDisabled?: boolean;
+  /** Whether the radio item is invalid */
+  isInvalid?: boolean;
+  /** Variant style for the radio item */
+  variant?: 'primary' | 'secondary';
+  /** Callback to change the selection state (selects this item in the group) */
+  onSelectedChange?: (isSelected: boolean) => void;
+}
+
+/**
+ * Render function props for RadioGroupItem children
+ */
+export interface RadioGroupItemRenderProps {
+  /** Whether the radio item is selected */
+  isSelected: boolean;
+  /** Whether the radio item is disabled */
+  isDisabled: boolean;
+  /** Whether the radio item is invalid */
+  isInvalid: boolean;
+}
+
+/**
+ * Props for the RadioGroupItem component
+ */
+export interface RadioGroupItemProps extends Omit<ItemProps, 'children'> {
+  /** Radio item content, or a render function */
+  children?:
+    | React.ReactNode
+    | ((props: RadioGroupItemRenderProps) => React.ReactNode);
+  /** Whether the radio item is invalid @default false */
+  isInvalid?: boolean;
+  /** Variant style for the radio item
+   * @default 'primary'
+   */
+  variant?: 'primary' | 'secondary';
+  /** Custom class name */
+  className?: string;
+}

package/lib/__templates__/expo/client/heroui/components/scroll-shadow/index.ts

@@ -0,0 +1,7 @@
+export { default as ScrollShadow } from './scroll-shadow';
+export { scrollShadowClassNames } from './scroll-shadow.styles';
+export type {
+  ScrollShadowOrientation,
+  ScrollShadowProps,
+  ScrollShadowVisibility,
+} from './scroll-shadow.types';

package/lib/__templates__/expo/client/heroui/components/scroll-shadow/scroll-shadow.animation.ts

@@ -0,0 +1,132 @@
+import {
+  Extrapolation,
+  interpolate,
+  useAnimatedScrollHandler,
+  useAnimatedStyle,
+  useDerivedValue,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated';
+import { useCombinedAnimationDisabledState } from '../../helpers/internal/hooks';
+import {
+  getAnimationValueProperty,
+  getIsAnimationDisabledValue,
+  getRootAnimationState,
+} from '../../helpers/internal/utils';
+import { SHADOW_EXIT_ANIMATION_DURATION } from './scroll-shadow.constants';
+import type {
+  ScrollShadowOrientation,
+  ScrollShadowRootAnimation,
+  ScrollShadowVisibility,
+} from './scroll-shadow.types';
+
+// --------------------------------------------------
+
+/**
+ * Animation hook for ScrollShadow root component
+ * Handles cascading animation disabled state and all animation logic
+ */
+export function useScrollShadowRootAnimation(options: {
+  animation: ScrollShadowRootAnimation | undefined;
+  orientation: ScrollShadowOrientation;
+  size: number;
+  visibility: ScrollShadowVisibility;
+  isEnabled: boolean;
+}) {
+  const { animation, orientation, size, visibility, isEnabled } = options;
+
+  const { animationConfig, isAnimationDisabled } =
+    getRootAnimationState(animation);
+
+  const isAllAnimationsDisabled = useCombinedAnimationDisabledState(animation);
+
+  const isAnimationDisabledValue = getIsAnimationDisabledValue({
+    isAnimationDisabled,
+    isAllAnimationsDisabled,
+  });
+
+  // Opacity animation values
+  const topOpacityValue = getAnimationValueProperty({
+    animationValue: animationConfig?.opacity,
+    property: 'value',
+    defaultValue: [0, 1] as [number, number],
+  });
+
+  // Reverse array for bottom shadow: [1, 0]
+  const bottomOpacityValue: [number, number] = [
+    topOpacityValue[1],
+    topOpacityValue[0],
+  ];
+
+  const scrollOffset = useSharedValue(0);
+  const contentSize = useSharedValue(0);
+  const containerSize = useSharedValue(0);
+
+  const localScrollHandler = useAnimatedScrollHandler({
+    onScroll: (event) => {
+      const offset =
+        orientation === 'vertical'
+          ? event.contentOffset.y
+          : event.contentOffset.x;
+      scrollOffset.set(offset);
+    },
+  });
+
+  const topShadowOpacity = useDerivedValue(() => {
+    if (isAnimationDisabledValue) {
+      return 1;
+    }
+
+    if (!isEnabled)
+      return withTiming(0, { duration: SHADOW_EXIT_ANIMATION_DURATION });
+    if (visibility === 'none')
+      return withTiming(0, { duration: SHADOW_EXIT_ANIMATION_DURATION });
+    if (visibility === 'bottom' || visibility === 'right')
+      return withTiming(0, { duration: SHADOW_EXIT_ANIMATION_DURATION });
+
+    return interpolate(
+      scrollOffset.get(),
+      [0, size / 4],
+      topOpacityValue,
+      Extrapolation.CLAMP
+    );
+  });
+
+  const bottomShadowOpacity = useDerivedValue(() => {
+    if (isAnimationDisabledValue) {
+      return 1;
+    }
+
+    if (!isEnabled)
+      return withTiming(0, { duration: SHADOW_EXIT_ANIMATION_DURATION });
+    if (visibility === 'none')
+      return withTiming(0, { duration: SHADOW_EXIT_ANIMATION_DURATION });
+    if (visibility === 'top' || visibility === 'left')
+      return withTiming(0, { duration: SHADOW_EXIT_ANIMATION_DURATION });
+
+    return interpolate(
+      scrollOffset.get() + containerSize.get(),
+      [contentSize.get() - size / 4, contentSize.get()],
+      bottomOpacityValue,
+      Extrapolation.CLAMP
+    );
+  });
+
+  const topShadowStyle = useAnimatedStyle(() => ({
+    opacity: topShadowOpacity.get(),
+  }));
+
+  const bottomShadowStyle = useAnimatedStyle(() => ({
+    opacity: bottomShadowOpacity.get(),
+  }));
+
+  return {
+    scrollOffset,
+    contentSize,
+    containerSize,
+    localScrollHandler,
+    topShadowStyle,
+    bottomShadowStyle,
+    isAllAnimationsDisabled,
+  };
+}

package/lib/__templates__/expo/client/heroui/components/scroll-shadow/scroll-shadow.constants.ts

@@ -0,0 +1,21 @@
+/**
+ * Display name constants for ScrollShadow components
+ */
+export const SCROLL_SHADOW_DISPLAY_NAME = {
+  ROOT: 'HeroUINative.ScrollShadow',
+} as const;
+
+/**
+ * Default size for gradient shadows in pixels
+ */
+export const DEFAULT_SHADOW_SIZE = 50;
+
+/**
+ * Animation duration for shadow opacity transitions in milliseconds
+ */
+export const SHADOW_EXIT_ANIMATION_DURATION = 200;
+
+/**
+ * Default scroll event throttle for performance
+ */
+export const DEFAULT_SCROLL_EVENT_THROTTLE = 16;

package/lib/__templates__/expo/client/heroui/components/scroll-shadow/scroll-shadow.md

@@ -0,0 +1,206 @@
+# ScrollShadow
+
+Adds dynamic gradient shadows to scrollable content based on scroll position and overflow.
+
+## Import
+
+```tsx
+import { ScrollShadow } from '@/heroui';
+```
+
+## Anatomy
+
+```tsx
+<ScrollShadow LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+```
+
+- **ScrollShadow**: Main container that wraps scrollable components and adds dynamic gradient shadows at the edges based on scroll position and content overflow. Automatically detects scroll orientation (horizontal/vertical) and manages shadow visibility.
+- **LinearGradientComponent**: Required prop that accepts a LinearGradient component from compatible libraries (expo-linear-gradient, react-native-linear-gradient, etc.) to render the gradient shadows.
+
+## Usage
+
+### Basic Usage
+
+Wrap any scrollable component to automatically add edge shadows.
+
+```tsx
+<ScrollShadow LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+```
+
+### Horizontal Scrolling
+
+The component auto-detects horizontal scrolling from the child's `horizontal` prop.
+
+```tsx
+<ScrollShadow LinearGradientComponent={LinearGradient}>
+  <FlatList horizontal data={data} renderItem={...} />
+</ScrollShadow>
+```
+
+### Custom Shadow Size
+
+Control the gradient shadow height/width with the `size` prop.
+
+```tsx
+<ScrollShadow size={100} LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+```
+
+### Visibility Control
+
+Specify which shadows to display using the `visibility` prop.
+
+```tsx
+<ScrollShadow visibility="top" LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+
+<ScrollShadow visibility="bottom" LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+
+<ScrollShadow visibility="none" LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+```
+
+### Custom Shadow Color
+
+Override the default shadow color which uses the theme's background.
+
+```tsx
+<ScrollShadow color="#ffffff" LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+```
+
+### With Custom Scroll Handler
+
+**Important:** ScrollShadow internally converts the child to a Reanimated animated component. If you need to use the `onScroll` prop, you must use `useAnimatedScrollHandler` from react-native-reanimated.
+
+```tsx
+import { LinearGradient } from 'expo-linear-gradient';
+import Animated, { useAnimatedScrollHandler } from 'react-native-reanimated';
+
+const scrollHandler = useAnimatedScrollHandler({
+  onScroll: (event) => {
+    console.log(event.contentOffset.y);
+  },
+});
+
+<ScrollShadow LinearGradientComponent={LinearGradient}>
+  <Animated.ScrollView onScroll={scrollHandler}>...</Animated.ScrollView>
+</ScrollShadow>;
+```
+
+## Example
+
+```tsx
+import { ScrollShadow, Surface } from '@/heroui';
+import { LinearGradient } from 'expo-linear-gradient';
+import { FlatList, ScrollView, Text, View } from 'react-native';
+
+export default function ScrollShadowExample() {
+  const horizontalData = Array.from({ length: 10 }, (_, i) => ({
+    id: i,
+    title: `Card ${i + 1}`,
+  }));
+
+  return (
+    <View className="flex-1 bg-background">
+      <Text className="px-5 py-3 text-lg font-semibold">Horizontal List</Text>
+      <ScrollShadow LinearGradientComponent={LinearGradient}>
+        <FlatList
+          data={horizontalData}
+          horizontal
+          renderItem={({ item }) => (
+            <Surface variant="2" className="w-32 h-24 justify-center px-4">
+              <Text>{item.title}</Text>
+            </Surface>
+          )}
+          showsHorizontalScrollIndicator={false}
+          contentContainerClassName="p-5 gap-4"
+        />
+      </ScrollShadow>
+
+      <Text className="px-5 py-3 text-lg font-semibold">Vertical Content</Text>
+      <ScrollShadow
+        size={80}
+        className="h-48"
+        LinearGradientComponent={LinearGradient}
+      >
+        <ScrollView
+          contentContainerClassName="p-5"
+          showsVerticalScrollIndicator={false}
+        >
+          <Text className="mb-4 text-2xl font-bold">Long Content</Text>
+          <Text className="mb-4 text-base leading-6">
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+            eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
+            ad minim veniam, quis nostrud exercitation ullamco laboris.
+          </Text>
+          <Text className="mb-4 text-base leading-6">
+            Sed ut perspiciatis unde omnis iste natus error sit voluptatem
+            accusantium doloremque laudantium, totam rem aperiam, eaque ipsa
+            quae ab illo inventore veritatis et quasi architecto beatae vitae.
+          </Text>
+        </ScrollView>
+      </ScrollShadow>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/(home)/components/scroll-shadow.tsx>).
+
+## API Reference
+
+### ScrollShadow
+
+| prop                      | type                                                                   | default      | description                                                                                                     |
+| ------------------------- | ---------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------- |
+| `children`                | `React.ReactElement`                                                   | -            | The scrollable component to enhance with shadows. Must be a single React element (ScrollView, FlatList, etc.)   |
+| `LinearGradientComponent` | `ComponentType<`<br/>`LinearGradientProps>`                            | **required** | LinearGradient component from any compatible library (expo-linear-gradient, react-native-linear-gradient, etc.) |
+| `size`                    | `number`                                                               | `50`         | Size (height/width) of the gradient shadow in pixels                                                            |
+| `orientation`             | `'horizontal' \| 'vertical'`                                           | auto-detect  | Orientation of the scroll shadow. If not provided, will auto-detect from child's `horizontal` prop              |
+| `visibility`              | `'auto' \| 'top' \| 'bottom' \| 'left' \| 'right' \| 'both' \| 'none'` | `'auto'`     | Visibility mode for the shadows. 'auto' shows shadows based on scroll position and content overflow             |
+| `color`                   | `string`                                                               | theme color  | Custom color for the gradient shadow. If not provided, uses the theme's background color                        |
+| `isEnabled`               | `boolean`                                                              | `true`       | Whether the shadow effect is enabled                                                                            |
+| `animation`               | `ScrollShadowRootAnimation`                                            | -            | Animation configuration                                                                                         |
+| `className`               | `string`                                                               | -            | Additional CSS classes to apply to the container                                                                |
+| `...ViewProps`            | `ViewProps`                                                            | -            | All standard React Native View props are supported                                                              |
+
+#### ScrollShadowRootAnimation
+
+Animation configuration for ScrollShadow 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                                     |
+| `opacity.value` | `[number, number]`                       | `[0, 1]` | `Opacity values [initial, active].`<br/>`For bottom/right shadow, this is reversed` |
+
+### LinearGradientProps
+
+The `LinearGradientComponent` prop expects a component that accepts these props:
+
+| prop        | type                              | description                                                        |
+| ----------- | --------------------------------- | ------------------------------------------------------------------ |
+| `colors`    | `any`                             | Array of colors for the gradient                                   |
+| `locations` | `any` (optional)                  | Array of numbers defining the location of each gradient color stop |
+| `start`     | `any` (optional)                  | Start point of the gradient (e.g., `{ x: 0, y: 0 }`)               |
+| `end`       | `any` (optional)                  | End point of the gradient (e.g., `{ x: 1, y: 0 }`)                 |
+| `style`     | `StyleProp<ViewStyle>` (optional) | Style to apply to the gradient view                                |
+
+## Special Notes
+
+**Important:** ScrollShadow internally converts the child to a Reanimated animated component. If you need to use the `onScroll` prop on your scrollable component, you must use `useAnimatedScrollHandler` from react-native-reanimated instead of the standard `onScroll` prop.