@coze-arch/cli 0.0.1-alpha.ef0249 → 0.0.1-alpha.f0fbc7

package/lib/__templates__/expo/client/heroui/helpers/internal/hooks/use-relative-position.ts

@@ -0,0 +1,353 @@
+import * as React from 'react';
+import {
+  Dimensions,
+  type LayoutRectangle,
+  type ScaledSize,
+} from 'react-native';
+import type { Insets } from '../types';
+
+type UseRelativePositionArgs = Omit<
+  GetContentStyleArgs,
+  'triggerPosition' | 'contentLayout' | 'dimensions'
+> & {
+  triggerPosition: LayoutPosition | null;
+  contentLayout: LayoutRectangle | null;
+  disablePositioningStyle?: boolean;
+};
+
+export function useRelativePosition({
+  align,
+  avoidCollisions,
+  triggerPosition,
+  contentLayout,
+  alignOffset,
+  insets,
+  offset,
+  placement,
+  disablePositioningStyle,
+}: UseRelativePositionArgs) {
+  const dimensions = Dimensions.get('screen');
+
+  return React.useMemo(() => {
+    if (disablePositioningStyle) {
+      return {};
+    }
+    if (!triggerPosition || !contentLayout) {
+      return {
+        position: 'absolute',
+        opacity: 0,
+        top: dimensions.height,
+      } as const;
+    }
+    return getContentStyle({
+      align,
+      avoidCollisions,
+      contentLayout,
+      placement,
+      triggerPosition,
+      alignOffset,
+      insets,
+      offset,
+      dimensions,
+    });
+  }, [
+    align,
+    avoidCollisions,
+    placement,
+    alignOffset,
+    insets,
+    triggerPosition,
+    contentLayout,
+    dimensions,
+    disablePositioningStyle,
+    offset,
+  ]);
+}
+
+export interface LayoutPosition {
+  pageY: number;
+  pageX: number;
+  width: number;
+  height: number;
+}
+
+interface GetPositionArgs {
+  dimensions: ScaledSize;
+  avoidCollisions: boolean;
+  triggerPosition: LayoutPosition;
+  contentLayout: LayoutRectangle;
+  insets?: Insets;
+}
+
+interface GetSidePositionArgs extends GetPositionArgs {
+  placement: 'top' | 'bottom' | 'left' | 'right';
+  offset: number;
+}
+
+function getSidePosition({
+  placement,
+  triggerPosition,
+  contentLayout,
+  offset,
+  insets,
+  avoidCollisions,
+  dimensions,
+}: GetSidePositionArgs) {
+  const insetTop = insets?.top ?? 0;
+  const insetBottom = insets?.bottom ?? 0;
+  const insetLeft = insets?.left ?? 0;
+  const insetRight = insets?.right ?? 0;
+
+  // Handle vertical sides (top/bottom)
+  if (placement === 'top' || placement === 'bottom') {
+    const positionTop = triggerPosition?.pageY - offset - contentLayout.height;
+    const positionBottom =
+      triggerPosition.pageY + triggerPosition.height + offset;
+
+    if (!avoidCollisions) {
+      return {
+        top: placement === 'top' ? positionTop : positionBottom,
+      };
+    }
+
+    if (placement === 'top') {
+      return {
+        top: Math.min(
+          Math.max(insetTop, positionTop),
+          dimensions.height - insetBottom - contentLayout.height
+        ),
+      };
+    }
+
+    return {
+      top: Math.min(
+        dimensions.height - insetBottom - contentLayout.height,
+        positionBottom
+      ),
+    };
+  }
+
+  // Handle horizontal sides (left/right)
+  const maxContentWidth = dimensions.width - insetLeft - insetRight;
+  const contentWidth = Math.min(contentLayout.width, maxContentWidth);
+
+  const positionLeft = triggerPosition.pageX - offset - contentWidth;
+  const positionRight = triggerPosition.pageX + triggerPosition.width + offset;
+
+  if (!avoidCollisions) {
+    return {
+      left: placement === 'left' ? positionLeft : positionRight,
+    };
+  }
+
+  if (placement === 'left') {
+    return {
+      left: Math.min(
+        Math.max(insetLeft, positionLeft),
+        dimensions.width - insetRight - contentWidth
+      ),
+    };
+  }
+
+  // For right placement, ensure content doesn't go beyond left inset
+  return {
+    left: Math.max(
+      insetLeft,
+      Math.min(dimensions.width - insetRight - contentWidth, positionRight)
+    ),
+  };
+}
+
+interface GetAlignPositionArgs extends GetPositionArgs {
+  align: 'start' | 'center' | 'end';
+  alignOffset: number;
+  placement: 'top' | 'bottom' | 'left' | 'right';
+}
+
+function getAlignPosition({
+  align,
+  avoidCollisions,
+  contentLayout,
+  triggerPosition,
+  alignOffset,
+  insets,
+  dimensions,
+  placement,
+}: GetAlignPositionArgs) {
+  const insetLeft = insets?.left ?? 0;
+  const insetRight = insets?.right ?? 0;
+  const insetTop = insets?.top ?? 0;
+  const insetBottom = insets?.bottom ?? 0;
+
+  // For top/bottom sides, align horizontally
+  if (placement === 'top' || placement === 'bottom') {
+    const maxContentWidth = dimensions.width - insetLeft - insetRight;
+    const contentWidth = Math.min(contentLayout.width, maxContentWidth);
+
+    let left = getHorizontalAlignPosition(
+      align,
+      triggerPosition.pageX,
+      triggerPosition.width,
+      contentWidth,
+      alignOffset,
+      insetLeft,
+      insetRight,
+      dimensions
+    );
+
+    if (avoidCollisions) {
+      const doesCollide =
+        left < insetLeft || left + contentWidth > dimensions.width - insetRight;
+      if (doesCollide) {
+        const spaceLeft = left - insetLeft;
+        const spaceRight =
+          dimensions.width - insetRight - (left + contentWidth);
+
+        if (spaceLeft > spaceRight && spaceLeft >= contentWidth) {
+          left = insetLeft;
+        } else if (spaceRight >= contentWidth) {
+          left = dimensions.width - insetRight - contentWidth;
+        } else {
+          const centeredPosition = Math.max(
+            insetLeft,
+            (dimensions.width - contentWidth - insetRight) / 2
+          );
+          left = centeredPosition;
+        }
+      }
+    }
+
+    return { left, maxWidth: maxContentWidth };
+  }
+
+  // For left/right sides, align vertically and constrain width
+  const maxContentHeight = dimensions.height - insetTop - insetBottom;
+  const maxContentWidth = dimensions.width - insetLeft - insetRight;
+  const contentHeight = Math.min(contentLayout.height, maxContentHeight);
+
+  let top = getVerticalAlignPosition(
+    align,
+    triggerPosition.pageY,
+    triggerPosition.height,
+    contentHeight,
+    alignOffset,
+    insetTop,
+    insetBottom,
+    dimensions
+  );
+
+  if (avoidCollisions) {
+    const doesCollide =
+      top < insetTop || top + contentHeight > dimensions.height - insetBottom;
+    if (doesCollide) {
+      const spaceTop = top - insetTop;
+      const spaceBottom =
+        dimensions.height - insetBottom - (top + contentHeight);
+
+      if (spaceTop > spaceBottom && spaceTop >= contentHeight) {
+        top = insetTop;
+      } else if (spaceBottom >= contentHeight) {
+        top = dimensions.height - insetBottom - contentHeight;
+      } else {
+        const centeredPosition = Math.max(
+          insetTop,
+          (dimensions.height - contentHeight - insetBottom) / 2
+        );
+        top = centeredPosition;
+      }
+    }
+  }
+
+  return { top, maxHeight: maxContentHeight, maxWidth: maxContentWidth };
+}
+
+function getHorizontalAlignPosition(
+  align: 'start' | 'center' | 'end',
+  triggerPageX: number,
+  triggerWidth: number,
+  contentWidth: number,
+  alignOffset: number,
+  insetLeft: number,
+  insetRight: number,
+  dimensions: ScaledSize
+) {
+  let left = 0;
+  if (align === 'start') {
+    left = triggerPageX;
+  }
+  if (align === 'center') {
+    left = triggerPageX + triggerWidth / 2 - contentWidth / 2;
+  }
+  if (align === 'end') {
+    left = triggerPageX + triggerWidth - contentWidth;
+  }
+  return Math.max(
+    insetLeft,
+    Math.min(left + alignOffset, dimensions.width - contentWidth - insetRight)
+  );
+}
+
+function getVerticalAlignPosition(
+  align: 'start' | 'center' | 'end',
+  triggerPageY: number,
+  triggerHeight: number,
+  contentHeight: number,
+  alignOffset: number,
+  insetTop: number,
+  insetBottom: number,
+  dimensions: ScaledSize
+) {
+  let top = 0;
+  if (align === 'start') {
+    top = triggerPageY;
+  }
+  if (align === 'center') {
+    top = triggerPageY + triggerHeight / 2 - contentHeight / 2;
+  }
+  if (align === 'end') {
+    top = triggerPageY + triggerHeight - contentHeight;
+  }
+  return Math.max(
+    insetTop,
+    Math.min(top + alignOffset, dimensions.height - contentHeight - insetBottom)
+  );
+}
+
+type GetContentStyleArgs = GetPositionArgs &
+  GetSidePositionArgs &
+  GetAlignPositionArgs;
+
+function getContentStyle({
+  align,
+  avoidCollisions,
+  contentLayout,
+  placement,
+  triggerPosition,
+  alignOffset,
+  insets,
+  offset,
+  dimensions,
+}: GetContentStyleArgs) {
+  return Object.assign(
+    { position: 'absolute' } as const,
+    getSidePosition({
+      placement,
+      triggerPosition,
+      contentLayout,
+      offset,
+      insets,
+      avoidCollisions,
+      dimensions,
+    }),
+    getAlignPosition({
+      align,
+      avoidCollisions,
+      triggerPosition,
+      contentLayout,
+      alignOffset,
+      insets,
+      dimensions,
+      placement,
+    })
+  );
+}

package/lib/__templates__/expo/client/heroui/helpers/internal/hooks/use-resolved-style-property.ts

@@ -0,0 +1,118 @@
+import { useMemo } from 'react';
+import type { ImageStyle, StyleProp, TextStyle, ViewStyle } from 'react-native';
+import { StyleSheet } from 'react-native';
+import { useResolveClassNames } from 'uniwind';
+
+/**
+ * Combined style type from React Native
+ */
+type Style = ViewStyle | TextStyle | ImageStyle;
+
+/**
+ * Parameters for single property resolution
+ */
+interface UseResolvedStylePropertyParamsSingle<K extends keyof Style> {
+  /** The className string to resolve styles from */
+  className?: string;
+  /** The style prop (can be object, array, or null) */
+  style?: StyleProp<ViewStyle> | StyleProp<TextStyle> | StyleProp<ImageStyle>;
+  /** The name of the style property to resolve */
+  propertyName: K;
+}
+
+/**
+ * Parameters for multiple properties resolution
+ */
+interface UseResolvedStylePropertyParamsMultiple<K extends keyof Style> {
+  /** The className string to resolve styles from */
+  className?: string;
+  /** The style prop (can be object, array, or null) */
+  style?: StyleProp<ViewStyle> | StyleProp<TextStyle> | StyleProp<ImageStyle>;
+  /** Array of style property names to resolve */
+  propertyNames: readonly K[];
+}
+
+/**
+ * A hook that resolves specific style properties from both className and style props.
+ * The style prop takes precedence over className.
+ *
+ * This is useful when you need to extract specific style values (like width, height)
+ * that might come from either Tailwind classes or inline styles.
+ *
+ * @param params - Configuration object with className, style, and propertyName(s)
+ * @returns The resolved style property value(s) or undefined if not found
+ *
+ * @example Single property
+ * ```tsx
+ * const width = useResolvedStyleProperty({
+ *   className: 'w-10 h-8',
+ *   style: { width: 50 },
+ *   propertyName: 'width',
+ * });
+ * // Returns: 50 (from style, takes precedence)
+ * ```
+ *
+ * @example Multiple properties
+ * ```tsx
+ * const [width, left] = useResolvedStyleProperty({
+ *   className: 'w-10 left-2',
+ *   propertyNames: ['width', 'left'],
+ * });
+ * // Returns: [40, 8] (from className)
+ * ```
+ */
+function useResolvedStyleProperty<K extends keyof Style>(
+  params: UseResolvedStylePropertyParamsSingle<K>
+): Style[K] | undefined;
+function useResolvedStyleProperty<K extends keyof Style>(
+  params: UseResolvedStylePropertyParamsMultiple<K>
+): (Style[K] | undefined)[];
+function useResolvedStyleProperty<K extends keyof Style>(
+  params:
+    | UseResolvedStylePropertyParamsSingle<K>
+    | UseResolvedStylePropertyParamsMultiple<K>
+): Style[K] | undefined | (Style[K] | undefined)[] {
+  const { className, style } = params;
+
+  const resolvedClassName = useResolveClassNames(className ?? '');
+  const resolvedStyle = useMemo(
+    () => (style ? StyleSheet.flatten(style) : undefined),
+    [style]
+  );
+
+  return useMemo(() => {
+    // Check if we're resolving multiple properties
+    if ('propertyNames' in params) {
+      return params.propertyNames.map((propertyName) => {
+        // Style prop takes precedence over className
+        if (resolvedStyle && propertyName in resolvedStyle) {
+          return resolvedStyle[propertyName];
+        }
+
+        // Fall back to className-resolved styles
+        if (resolvedClassName && propertyName in resolvedClassName) {
+          return resolvedClassName[propertyName];
+        }
+
+        return undefined;
+      });
+    }
+
+    // Single property resolution
+    const propertyName = params.propertyName;
+
+    // Style prop takes precedence over className
+    if (resolvedStyle && propertyName in resolvedStyle) {
+      return resolvedStyle[propertyName];
+    }
+
+    // Fall back to className-resolved styles
+    if (resolvedClassName && propertyName in resolvedClassName) {
+      return resolvedClassName[propertyName];
+    }
+
+    return undefined;
+  }, [resolvedStyle, resolvedClassName, params]);
+}
+
+export { useResolvedStyleProperty };

package/lib/__templates__/expo/client/heroui/helpers/internal/types/animation.ts

@@ -0,0 +1,131 @@
+import type {
+  BaseAnimationBuilder,
+  EntryOrExitLayoutType,
+  LayoutAnimationFunction,
+  WithSpringConfig,
+  WithTimingConfig,
+} from 'react-native-reanimated';
+
+/**
+ * Universal animation prop type
+ * - `true` or `undefined`: Use default animations
+ * - `false` or `"disabled"`: Disable all animations
+ * - `object`: Custom animation configuration
+ *   - Can include `state?: 'disabled' | boolean | undefined` to disable animations while customizing properties
+ */
+export type Animation<
+  TConfig extends Record<string, any> = Record<string, any>,
+> = boolean | 'disabled' | (TConfig & { state?: 'disabled' | boolean });
+
+export type AnimationDisabled = 'disabled' | false;
+
+/**
+ * Root-level animation prop type with cascading control
+ * - `true` or `undefined`: Use default animations
+ * - `false` or `"disabled"`: Disable only root animations (children can still animate)
+ * - `"disable-all"`: Disable all animations including children (cascades down)
+ * - `object`: Custom animation configuration
+ *   - Can include `state?: 'disabled' | 'disable-all' | boolean` to disable animations while customizing properties
+ */
+export type AnimationRoot<
+  TConfig extends Record<string, any> = Record<string, any>,
+> =
+  | boolean
+  | 'disabled'
+  | 'disable-all'
+  | (TConfig & { state?: 'disabled' | 'disable-all' | boolean });
+
+export type AnimationRootDisableAll = Extract<AnimationRoot, 'disable-all'>;
+
+/**
+ * Animation value that can be a custom config
+ * Used for granular animation control within a component
+ */
+export type AnimationValue<
+  TConfig extends Record<string, any> = Record<string, any>,
+> = TConfig;
+
+export type LayoutTransition =
+  | BaseAnimationBuilder
+  | LayoutAnimationFunction
+  | typeof BaseAnimationBuilder
+  | undefined;
+
+/**
+ * Spring animation configuration
+ */
+export interface SpringAnimationConfig {
+  type: 'spring';
+  config?: WithSpringConfig;
+}
+
+/**
+ * Timing animation configuration
+ */
+export interface TimingAnimationConfig {
+  type: 'timing';
+  config?: WithTimingConfig;
+}
+
+/**
+ * Animation configuration for popup overlay components (Dialog, Select, BottomSheet, Popover, etc.)
+ * Supports both progress-based opacity animation and entering/exiting animations
+ */
+export type PopupOverlayAnimation = Animation<{
+  /**
+   * Opacity animation configuration (progress-based)
+   * Takes effect for bottom-sheet/dialog presentation
+   * @default [0, 1, 0] - opacity values for [idle, open, close] states
+   */
+  opacity?: AnimationValue<{
+    /**
+     * Opacity values [idle, open, close]
+     * @default [0, 1, 0]
+     */
+    value?: [number, number, number];
+  }>;
+  /**
+   * Takes effect for popover presentation
+   * @default FadeIn with duration 200ms
+   */
+  entering?: EntryOrExitLayoutType;
+  /**
+   * Takes effect for popover presentation
+   * @default FadeOut with duration 150ms
+   */
+  exiting?: EntryOrExitLayoutType;
+}>;
+
+/**
+ * Animation configuration for popup dialog content components (Dialog, Select dialog presentation)
+ * Supports opacity and scale animations
+ */
+export type PopupDialogContentAnimation = Animation<{
+  /**
+   * Custom Keyframe animation for entering transition
+   * @default Keyframe with scale, and opacity (200ms)
+   */
+  entering?: EntryOrExitLayoutType;
+  /**
+   * Custom Keyframe animation for exiting transition
+   * @default Keyframe mirroring entering animation (150ms)
+   */
+  exiting?: EntryOrExitLayoutType;
+}>;
+
+/**
+ * Animation configuration for popup popover content components (Popover, Select popover presentation)
+ * Supports custom Keyframe animations for entering and exiting transitions
+ */
+export type PopupPopoverContentAnimation = Animation<{
+  /**
+   * Custom Keyframe animation for entering transition
+   * @default Keyframe with translateY/translateX, scale, and opacity (200ms)
+   */
+  entering?: EntryOrExitLayoutType;
+  /**
+   * Custom Keyframe animation for exiting transition
+   * @default Keyframe mirroring entering animation (150ms)
+   */
+  exiting?: EntryOrExitLayoutType;
+}>;

package/lib/__templates__/expo/client/heroui/helpers/internal/types/bottom-sheet.ts

@@ -0,0 +1,99 @@
+import type { BottomSheetViewProps } from '@gorhom/bottom-sheet/lib/typescript/components/bottomSheetView/types';
+import type { ReactNode } from 'react';
+import type { SharedValue } from 'react-native-reanimated';
+import type { AnimationDisabled } from './animation';
+
+/**
+ * State type for bottom sheet content container animation coordination
+ */
+export type BottomSheetContentContainerState = 'idle' | 'open' | 'close';
+
+/**
+ * Props for the reusable BottomSheetContentContainer component
+ */
+export interface BottomSheetContentContainerProps {
+  /**
+   * The content to be rendered inside the container
+   */
+  children?: ReactNode;
+  /**
+   * Additional CSS class for the content container
+   */
+  contentContainerClassName?: string;
+  /**
+   * Props for the content container
+   */
+  contentContainerProps?: Omit<BottomSheetViewProps, 'children'>;
+  /**
+   * Whether the bottom sheet is open
+   */
+  isOpen: boolean;
+  /**
+   * Animation progress shared value (0=idle, 1=open, 2=close)
+   */
+  progress: SharedValue<number>;
+  /**
+   * Whether the bottom sheet is dragging
+   */
+  isDragging: SharedValue<boolean>;
+  /**
+   * Whether the bottom sheet is pan activated
+   */
+  isPanActivated: SharedValue<boolean>;
+  /**
+   * Whether the bottom sheet is closing on swipe
+   */
+  isClosingOnSwipe: SharedValue<boolean>;
+  /**
+   * Initial index of the bottom sheet
+   */
+  initialIndex: number;
+  /**
+   * Callback when the bottom sheet is opened
+   */
+  onOpenChange: (open: boolean) => void;
+}
+
+/**
+ * Base props shared across BottomSheet Content components
+ * Used by BottomSheet, Popover, and Select components when using bottom-sheet presentation
+ */
+export interface BaseBottomSheetContentProps {
+  /**
+   * The bottom sheet content
+   */
+  children?: ReactNode;
+  /**
+   * Additional CSS class for the bottom sheet
+   */
+  className?: string;
+  /**
+   * Additional CSS class for the container
+   */
+  containerClassName?: string;
+  /**
+   * Additional CSS class for the content container
+   */
+  contentContainerClassName?: string;
+  /**
+   * Additional CSS class for the background
+   */
+  backgroundClassName?: string;
+  /**
+   * Additional CSS class for the handle
+   */
+  handleClassName?: string;
+  /**
+   * Additional CSS class for the handle indicator
+   */
+  handleIndicatorClassName?: string;
+  /**
+   * Props for the content container
+   */
+  contentContainerProps?: Omit<BottomSheetViewProps, 'children'>;
+  /**
+   * Animation configuration for bottom sheet content
+   * - `false` or `"disabled"`: Disable all animations
+   */
+  animation?: AnimationDisabled;
+}

package/lib/__templates__/expo/client/heroui/helpers/internal/types/index.ts

@@ -0,0 +1,5 @@
+export * from './animation';
+export * from './bottom-sheet';
+export * from './misc';
+export * from './primitives';
+export * from './theme';