@coze-arch/cli 0.0.10 → 0.0.11

package/lib/__templates__/expo/client/heroui/helpers/internal/components/full-window-overlay.tsx

@@ -0,0 +1,48 @@
+import type { ReactNode } from 'react';
+import { Platform } from 'react-native';
+import { FullWindowOverlay as NativeFullWindowOverlay } from 'react-native-screens';
+
+/**
+ * Props for the FullWindowOverlay component
+ *
+ * @description
+ * FullWindowOverlay renders content in a separate native window on iOS,
+ * which allows overlays (bottom sheets, dialogs, toasts) to appear above
+ * native modals and the keyboard. However, this breaks the React Native
+ * element inspector because it attaches to the main window.
+ *
+ * Set `disableFullWindowOverlay={true}` when you need to use the element
+ * inspector during development. Note: when disabled, overlay content will
+ * not render above native modals. iOS only; has no effect on Android.
+ */
+export interface FullWindowOverlayProps {
+  /**
+   * When true, uses a regular View instead of FullWindowOverlay on iOS.
+   * Enables element inspector but overlay content won't appear above native modals.
+   * @default false
+   */
+  disableFullWindowOverlay: boolean;
+  /**
+   * Content to render inside the overlay
+   */
+  children: ReactNode;
+}
+
+/**
+ * Wrapper for react-native-screens FullWindowOverlay with optional disable prop.
+ *
+ * @description
+ * On iOS, FullWindowOverlay creates a separate native window for overlay content,
+ * which breaks the React Native element inspector. Use `disableFullWindowOverlay`
+ * when debugging to render content in the main window instead.
+ */
+export function FullWindowOverlay({
+  disableFullWindowOverlay,
+  children,
+}: FullWindowOverlayProps) {
+  if (Platform.OS !== 'ios' || disableFullWindowOverlay) {
+    return <>{children}</>;
+  }
+
+  return <NativeFullWindowOverlay>{children}</NativeFullWindowOverlay>;
+}

package/lib/__templates__/expo/client/heroui/helpers/internal/components/hero-text.tsx

@@ -0,0 +1,71 @@
+import React from 'react';
+import { Text as RNText, type TextProps as RNTextProps } from 'react-native';
+import { useTextComponent } from '../../external/hooks';
+import { cn } from '../../external/utils';
+
+/**
+ * Props for HeroText component
+ */
+export interface HeroTextProps extends RNTextProps {
+  /**
+   * Additional CSS classes that will be merged with the default 'font-normal' class
+   */
+  className?: string;
+}
+
+/**
+ * HeroText component that automatically applies global text configuration
+ * from HeroUINativeProvider.
+ *
+ * This component is distinct from React Native's Text component and includes
+ * a default 'font-normal' className that can be extended via the className prop.
+ *
+ * Global text props that can be configured:
+ * - adjustsFontSizeToFit: Auto-scale text to fit constraints
+ * - allowFontScaling: Respect Text Size accessibility settings
+ * - maxFontSizeMultiplier: Maximum font scale when allowFontScaling is enabled
+ * - minimumFontScale: Minimum scale when adjustsFontSizeToFit is enabled (iOS only)
+ *
+ * @example
+ * ```tsx
+ * <HeroText>Hello World</HeroText>
+ * ```
+ *
+ * @example
+ * With custom className:
+ * ```tsx
+ * <HeroText className="text-lg font-bold">Hello World</HeroText>
+ * ```
+ *
+ * @example
+ * Global configuration in HeroUINativeProvider:
+ * ```tsx
+ * <HeroUINativeProvider config={{
+ *   textProps: {
+ *     allowFontScaling: false,
+ *     adjustsFontSizeToFit: false,
+ *     maxFontSizeMultiplier: 1.5
+ *   }
+ * }}>
+ *   <App />
+ * </HeroUINativeProvider>
+ * ```
+ */
+export const HeroText = React.forwardRef<RNText, HeroTextProps>(
+  (props, ref) => {
+    const { className, ...restProps } = props;
+    const { textProps } = useTextComponent();
+
+    const mergedProps = Object.assign({}, textProps, restProps);
+
+    return (
+      <RNText
+        ref={ref}
+        className={cn('font-normal', className)}
+        {...mergedProps}
+      />
+    );
+  }
+);
+
+HeroText.displayName = 'HeroText';

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

@@ -0,0 +1,9 @@
+export * from './animated-check-icon';
+export * from './bottom-sheet-content';
+export * from './bottom-sheet-content-container';
+export * from './check-icon';
+export * from './chevron-down-icon';
+export * from './chevron-right-icon';
+export * from './close-icon';
+export * from './full-window-overlay';
+export * from './hero-text';

package/lib/__templates__/expo/client/heroui/helpers/internal/contexts/animation-settings-context.ts

@@ -0,0 +1,19 @@
+import { createContext } from '../utils';
+
+/**
+ * Context value for global animation settings
+ */
+export interface AnimationSettingsContextValue {
+  /**
+   * Whether all animations should be disabled (cascading from parent)
+   */
+  isAllAnimationsDisabled: boolean;
+}
+
+const [AnimationSettingsProvider, useAnimationSettings] =
+  createContext<AnimationSettingsContextValue>({
+    name: 'AnimationSettingsContext',
+    strict: false,
+  });
+
+export { AnimationSettingsProvider, useAnimationSettings };

package/lib/__templates__/expo/client/heroui/helpers/internal/contexts/bottom-sheet-is-dragging-context.ts

@@ -0,0 +1,11 @@
+import type { SharedValue } from 'react-native-reanimated';
+import { createContext } from '../utils';
+
+const [BottomSheetIsDraggingProvider, useBottomSheetIsDragging] =
+  createContext<{
+    isDragging: SharedValue<boolean>;
+  }>({
+    name: 'BottomSheetIsDraggingContext',
+  });
+
+export { BottomSheetIsDraggingProvider, useBottomSheetIsDragging };

package/lib/__templates__/expo/client/heroui/helpers/internal/contexts/form-field-context.ts

@@ -0,0 +1,36 @@
+import { createContext } from '../utils';
+
+/**
+ * Combined context value for form field state and layout (shared across form field components).
+ *
+ * Providers: TextField, SearchField, ControlField, RadioGroup.
+ * Consumers: Label, Description, FieldError, Input.
+ */
+export interface FormFieldContextValue {
+  /**
+   * Whether the form field is required
+   */
+  isRequired: boolean;
+  /**
+   * Whether the form field is disabled
+   */
+  isDisabled: boolean;
+  /**
+   * Whether the form field is in an invalid state
+   */
+  isInvalid: boolean;
+  /**
+   * When true, child components (Label, Description, FieldError) apply
+   * additional horizontal padding (`px-1.5`) for consistent field layout.
+   *
+   * Set to `true` by container components like TextField and SearchField.
+   */
+  hasFieldPadding: boolean;
+}
+
+const [FormFieldProvider, useFormField] = createContext<FormFieldContextValue>({
+  name: 'FormFieldContext',
+  strict: false,
+});
+
+export { FormFieldProvider, useFormField };

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

@@ -0,0 +1,3 @@
+export * from './animation-settings-context';
+export * from './bottom-sheet-is-dragging-context';
+export * from './form-field-context';

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

@@ -0,0 +1,14 @@
+export * from './use-augmented-ref';
+export * from './use-bottom-sheet-aware-handlers';
+export * from './use-bottom-sheet-gesture-handlers';
+export * from './use-combined-animation-disabled-state';
+export * from './use-controllable-state';
+export * from './use-dev-info';
+export * from './use-keyboard-status';
+export * from './use-popup-bottom-sheet-content-animation';
+export * from './use-popup-dialog-content-animation';
+export * from './use-popup-overlay-animation';
+export * from './use-popup-popover-content-animation';
+export * from './use-popup-root-animation';
+export * from './use-relative-position';
+export * from './use-resolved-style-property';

package/lib/__templates__/expo/client/heroui/helpers/internal/hooks/use-augmented-ref.ts

@@ -0,0 +1,32 @@
+import * as React from 'react';
+import { useImperativeHandle, useRef } from 'react';
+
+interface AugmentRefProps<T> {
+  ref: React.Ref<T>;
+  methods?: Record<string, (...args: any[]) => any>;
+  deps?: any[];
+}
+
+export function useAugmentedRef<T>({
+  ref,
+  methods,
+  deps = [],
+}: AugmentRefProps<T>) {
+  const augmentedRef = useRef<T>(null);
+
+  useImperativeHandle(
+    ref,
+    () => {
+      if (typeof augmentedRef === 'function' || !augmentedRef?.current) {
+        return {} as T;
+      }
+      return {
+        ...augmentedRef.current,
+        ...methods,
+      };
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    deps
+  );
+  return augmentedRef;
+}

package/lib/__templates__/expo/client/heroui/helpers/internal/hooks/use-bottom-sheet-aware-handlers.ts

@@ -0,0 +1,94 @@
+import { useBottomSheetInternal } from '@gorhom/bottom-sheet';
+import { useCallback } from 'react';
+import {
+  findNodeHandle,
+  TextInput,
+  type BlurEvent,
+  type FocusEvent,
+} from 'react-native';
+
+/**
+ * Parameters for the bottom-sheet-aware handlers hook
+ */
+interface UseBottomSheetAwareHandlersParams {
+  /** User-provided onFocus handler to preserve */
+  onFocus?: ((e: FocusEvent) => void) | undefined;
+  /** User-provided onBlur handler to preserve */
+  onBlur?: ((e: BlurEvent) => void) | undefined;
+  /** Whether automatic bottom sheet keyboard handling is enabled */
+  isBottomSheetAware?: boolean;
+}
+
+/**
+ * Internal hook that automatically manages bottom sheet keyboard state
+ * when the component is rendered inside a BottomSheet context.
+ *
+ * Uses `useBottomSheetInternal(true)` (unsafe mode) so it returns `null`
+ * instead of throwing when called outside a BottomSheet. When inside a
+ * BottomSheet and `isBottomSheetAware` is true, it wraps the provided
+ * `onFocus`/`onBlur` handlers with the keyboard state management logic
+ * required by `@gorhom/bottom-sheet`.
+ *
+ * @param params - The handler parameters
+ * @returns Merged onFocus and onBlur handlers
+ */
+export function useBottomSheetAwareHandlers({
+  onFocus: onFocusProp,
+  onBlur: onBlurProp,
+  isBottomSheetAware = true,
+}: UseBottomSheetAwareHandlersParams) {
+  const bottomSheetContext = useBottomSheetInternal(true);
+
+  /** Whether the bottom sheet keyboard handling should be active */
+  const isActive = isBottomSheetAware && bottomSheetContext !== null;
+
+  /**
+   * Handles focus event: notifies the bottom sheet about the keyboard target,
+   * then delegates to the user-provided onFocus handler.
+   */
+  const onFocus = useCallback(
+    (e: FocusEvent) => {
+      if (isActive && bottomSheetContext) {
+        bottomSheetContext.animatedKeyboardState.set((state) => ({
+          ...state,
+          target: e.nativeEvent.target,
+        }));
+      }
+
+      onFocusProp?.(e);
+    },
+    [isActive, bottomSheetContext, onFocusProp]
+  );
+
+  /**
+   * Handles blur event: conditionally clears the keyboard target in the
+   * bottom sheet state, then delegates to the user-provided onBlur handler.
+   */
+  const onBlur = useCallback(
+    (e: BlurEvent) => {
+      if (isActive && bottomSheetContext) {
+        const keyboardState = bottomSheetContext.animatedKeyboardState.get();
+        const currentFocusedInput = findNodeHandle(
+          TextInput.State.currentlyFocusedInput() as TextInput | null
+        );
+        const shouldRemoveCurrentTarget =
+          keyboardState.target === e.nativeEvent.target;
+        const shouldIgnoreBlurEvent =
+          currentFocusedInput &&
+          bottomSheetContext.textInputNodesRef.current.has(currentFocusedInput);
+
+        if (shouldRemoveCurrentTarget && !shouldIgnoreBlurEvent) {
+          bottomSheetContext.animatedKeyboardState.set((state) => ({
+            ...state,
+            target: undefined,
+          }));
+        }
+      }
+
+      onBlurProp?.(e);
+    },
+    [isActive, bottomSheetContext, onBlurProp]
+  );
+
+  return { onFocus, onBlur };
+}

package/lib/__templates__/expo/client/heroui/helpers/internal/hooks/use-bottom-sheet-gesture-handlers.ts

@@ -0,0 +1,52 @@
+import {
+  useGestureEventsHandlersDefault,
+  type GestureEventHandlerCallbackType,
+  type GestureEventsHandlersHookType,
+} from '@gorhom/bottom-sheet';
+import { useBottomSheetIsDragging } from '../contexts/bottom-sheet-is-dragging-context';
+
+export const useBottomSheetGestureHandlers: GestureEventsHandlersHookType =
+  () => {
+    const { isDragging } = useBottomSheetIsDragging();
+
+    const defaultHandlers = useGestureEventsHandlersDefault();
+
+    const handleOnStart: GestureEventHandlerCallbackType = (
+      source,
+      payload
+    ) => {
+      'worklet';
+      isDragging.set(true);
+      defaultHandlers.handleOnStart(source, payload);
+    };
+
+    const handleOnChange: GestureEventHandlerCallbackType = (
+      source,
+      payload
+    ) => {
+      'worklet';
+      defaultHandlers.handleOnChange(source, payload);
+    };
+
+    const handleOnEnd: GestureEventHandlerCallbackType = (source, payload) => {
+      'worklet';
+      isDragging.set(false);
+      defaultHandlers.handleOnEnd(source, payload);
+    };
+
+    const handleOnFinalize: GestureEventHandlerCallbackType = (
+      source,
+      payload
+    ) => {
+      'worklet';
+      isDragging.set(false);
+      defaultHandlers.handleOnFinalize(source, payload);
+    };
+
+    return {
+      handleOnStart,
+      handleOnChange,
+      handleOnEnd,
+      handleOnFinalize,
+    };
+  };

package/lib/__templates__/expo/client/heroui/helpers/internal/hooks/use-combined-animation-disabled-state.ts

@@ -0,0 +1,49 @@
+import { useGlobalAnimationSettings } from '../../../providers/animation-settings';
+import { useAnimationSettings } from '../contexts/animation-settings-context';
+import type { AnimationRoot } from '../types/animation';
+import {
+  getCombinedAnimationDisabledState,
+  getRootAnimationState,
+} from '../utils/animation';
+
+/**
+ * Hook to combine global, parent, and own animation disabled states
+ *
+ * @description
+ * This hook combines three sources of animation disabled state:
+ * 1. Global state from GlobalAnimationSettingsProvider
+ * 2. Parent state from AnimationSettingsContext (component tree cascading)
+ * 3. Own state from the component's animation prop
+ *
+ * Priority: Global > Parent > Own (global wins if enabled)
+ *
+ * @param animation - Root animation configuration for the component
+ * @returns Combined isAllAnimationsDisabled value
+ *
+ * @example
+ * ```tsx
+ * const isAllAnimationsDisabled = useCombinedAnimationDisabledState(animation);
+ * ```
+ */
+export function useCombinedAnimationDisabledState<
+  TConfig extends Record<string, any>,
+>(animation: AnimationRoot<TConfig> | undefined): boolean {
+  // Get global animation disabled state
+  const { globalIsAllAnimationsDisabled } = useGlobalAnimationSettings();
+
+  // Read parent animation disabled state from global context
+  const parentAnimationSettingsContext = useAnimationSettings();
+  const parentIsAllAnimationsDisabled =
+    parentAnimationSettingsContext?.isAllAnimationsDisabled;
+
+  // Get own animation disabled state
+  const { isAllAnimationsDisabled: ownIsAllAnimationsDisabled } =
+    getRootAnimationState(animation);
+
+  // Combine global, parent, and own disable-all states (global > parent > own)
+  return getCombinedAnimationDisabledState({
+    globalIsAllAnimationsDisabled,
+    parentIsAllAnimationsDisabled,
+    ownIsAllAnimationsDisabled,
+  });
+}

package/lib/__templates__/expo/client/heroui/helpers/internal/hooks/use-controllable-state.ts

@@ -0,0 +1,124 @@
+// This project uses code from WorkOS/Radix Primitives.
+// The code is licensed under the MIT License.
+// https://github.com/radix-ui/primitives/tree/main
+
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+
+/**
+ * Parameters for the useControllableState hook
+ */
+type UseControllableStateParams<T> = {
+  /** The controlled value prop */
+  prop?: T | undefined;
+  /** The default value for uncontrolled mode */
+  defaultProp?: T | undefined;
+  /** Callback fired when the value changes */
+  onChange?: (state: T) => void;
+};
+
+/**
+ * Function type for state setter callbacks
+ */
+type SetStateFn<T> = (prevState?: T) => T;
+
+/**
+ * A hook that supports both controlled and uncontrolled state.
+ * When a value prop is provided, the component is controlled.
+ * When no value prop is provided, the component manages its own state.
+ *
+ * @param params - Configuration object with prop, defaultProp, and onChange
+ * @returns A tuple of [value, setValue] similar to useState
+ */
+function useControllableState<T>({
+  prop,
+  defaultProp,
+  onChange = () => {}, // eslint-disable-line @typescript-eslint/no-empty-function
+}: UseControllableStateParams<T>) {
+  const [uncontrolledProp, setUncontrolledProp] = useUncontrolledState({
+    defaultProp,
+    onChange,
+  });
+  const isControlled = prop !== undefined;
+  const value = isControlled ? prop : uncontrolledProp;
+  const handleChange = useCallbackRef(onChange);
+
+  /**
+   * When the component transitions from controlled (prop !== undefined)
+   * back to uncontrolled (prop === undefined), the internal uncontrolled
+   * state may hold a stale value from a previous selection. Reset it so
+   * the component correctly reflects the "no value" state.
+   */
+  const prevPropRef = useRef(prop);
+  useLayoutEffect(() => {
+    const wasControlled = prevPropRef.current !== undefined;
+    if (wasControlled && prop === undefined) {
+      setUncontrolledProp(undefined);
+    }
+    prevPropRef.current = prop;
+  }, [prop, setUncontrolledProp]);
+
+  const setValue: React.Dispatch<React.SetStateAction<T | undefined>> =
+    useCallback(
+      (nextValue) => {
+        if (isControlled) {
+          const setter = nextValue as SetStateFn<T>;
+          const val =
+            typeof nextValue === 'function' ? setter(prop) : nextValue;
+          if (val !== prop) handleChange(val as T);
+        } else {
+          setUncontrolledProp(nextValue);
+        }
+      },
+      [isControlled, prop, setUncontrolledProp, handleChange]
+    );
+
+  return [value, setValue] as const;
+}
+
+/**
+ * Internal hook for managing uncontrolled state with change callbacks
+ */
+function useUncontrolledState<T>({
+  defaultProp,
+  onChange,
+}: Omit<UseControllableStateParams<T>, 'prop'>) {
+  const uncontrolledState = useState<T | undefined>(defaultProp);
+  const [value] = uncontrolledState;
+  const prevValueRef = useRef(value);
+  const handleChange = useCallbackRef(onChange);
+
+  useEffect(() => {
+    if (prevValueRef.current !== value) {
+      handleChange(value as T);
+      prevValueRef.current = value;
+    }
+  }, [value, prevValueRef, handleChange]);
+
+  return uncontrolledState;
+}
+
+/**
+ * A custom hook that converts a callback to a ref to avoid triggering re-renders when passed as a
+ * prop or avoid re-executing effects when passed as a dependency
+ */
+function useCallbackRef<T extends (...args: any[]) => any>(
+  callback: T | undefined
+): T {
+  const callbackRef = useRef(callback);
+
+  useEffect(() => {
+    callbackRef.current = callback;
+  });
+
+  // https://github.com/facebook/react/issues/19240
+  return useMemo(() => ((...args) => callbackRef.current?.(...args)) as T, []);
+}
+
+export { useControllableState };

package/lib/__templates__/expo/client/heroui/helpers/internal/hooks/use-dev-info.ts

@@ -0,0 +1,38 @@
+import { useEffect } from 'react';
+import type { DevInfoConfig } from '../../../providers/hero-ui-native/types';
+
+const LOG_COLOR = {
+  BLUE: '\x1b[34m',
+  YELLOW: '\x1b[33m',
+  RESET: '\x1b[0m',
+};
+
+/**
+ * Hook that displays developer information messages in the console.
+ *
+ * @description
+ * Logs helpful styling principles and best practices during development.
+ * Messages are only shown in __DEV__ mode and can be disabled via the
+ * devInfo configuration.
+ *
+ * @param {DevInfoConfig} [devInfo] - Developer information configuration
+ */
+export function useDevInfo(devInfo?: DevInfoConfig): void {
+  const { stylingPrinciples = true } = devInfo || {};
+
+  useEffect(() => {
+    if (__DEV__ && stylingPrinciples) {
+      console.info(
+        `${LOG_COLOR.BLUE}HeroUI Native Styling Principles${LOG_COLOR.RESET}\n` +
+          `• className: this is your go-to styling solution. Use Tailwind CSS classes via className prop on all components.\n` +
+          `• StyleSheet precedence: The style prop (StyleSheet API) has precedence over className when both are provided. This allows you to override Tailwind classes when needed.\n` +
+          `• Animated styles: Some style properties are animated using react-native-reanimated and have precedence over className. To identify which styles are animated:\n` +
+          `  - Hover over className in your IDE - TypeScript definitions show which properties are occupied by animated styles\n` +
+          `  - Check component documentation - Each component page includes a link to the component's style source\n` +
+          `• If styles are occupied by animation, modify them via the animation prop on components that support it.\n` +
+          `• To deactivate animated style completely and apply your own styles, use isAnimatedStyleActive prop.\n` +
+          `${LOG_COLOR.YELLOW} To disable this message, set config.devInfo.stylingPrinciples to false${LOG_COLOR.RESET}`
+      );
+    }
+  }, [stylingPrinciples]);
+}

package/lib/__templates__/expo/client/heroui/helpers/internal/hooks/use-keyboard-status.ts

@@ -0,0 +1,22 @@
+import { useEffect, useState } from 'react';
+import { Keyboard } from 'react-native';
+
+export const useKeyboardStatus = () => {
+  const [keyboardStatus, setKeyboardStatus] = useState<boolean>(false);
+
+  useEffect(() => {
+    const showSubscription = Keyboard.addListener('keyboardDidShow', () => {
+      setKeyboardStatus(true);
+    });
+    const hideSubscription = Keyboard.addListener('keyboardDidHide', () => {
+      setKeyboardStatus(false);
+    });
+
+    return () => {
+      showSubscription.remove();
+      hideSubscription.remove();
+    };
+  }, [keyboardStatus]);
+
+  return keyboardStatus;
+};