@coze-arch/cli 0.0.10 → 0.0.11

package/lib/__templates__/expo/client/heroui/primitives/toast/toast.types.ts

@@ -0,0 +1,86 @@
+import type {
+  PressableRef,
+  SlottablePressableProps,
+  SlottableTextProps,
+  SlottableViewProps,
+  TextRef,
+  ViewRef,
+} from '../../helpers/internal/types';
+
+/**
+ * Context for the toast root component
+ */
+type RootContext = {
+  /** Unique identifier for the toast */
+  nativeID: string;
+};
+
+/**
+ * Props for the toast root component
+ */
+type RootProps = SlottableViewProps & {
+  /** Unique identifier for the toast */
+  id?: string | number;
+};
+
+/**
+ * Props for the toast title component
+ */
+type TitleProps = SlottableTextProps;
+
+/**
+ * Props for the toast description component
+ */
+type DescriptionProps = SlottableTextProps;
+
+/**
+ * Props for the toast action component
+ */
+type ActionProps = SlottablePressableProps & {
+  /** Alternative label for the action button for accessibility */
+  altText?: string;
+};
+
+/**
+ * Props for the toast close button component
+ */
+type CloseProps = SlottablePressableProps;
+
+/**
+ * Ref type for the toast root
+ */
+type RootRef = ViewRef;
+
+/**
+ * Ref type for the toast title
+ */
+type TitleRef = TextRef;
+
+/**
+ * Ref type for the toast description
+ */
+type DescriptionRef = TextRef;
+
+/**
+ * Ref type for the toast action button
+ */
+type ActionRef = PressableRef;
+
+/**
+ * Ref type for the toast close button
+ */
+type CloseRef = PressableRef;
+
+export type {
+  ActionProps,
+  ActionRef,
+  CloseProps,
+  CloseRef,
+  DescriptionProps,
+  DescriptionRef,
+  RootContext,
+  RootProps,
+  RootRef,
+  TitleProps,
+  TitleRef,
+};

package/lib/__templates__/expo/client/heroui/providers/animation-settings/index.ts

@@ -0,0 +1,8 @@
+export {
+  default as GlobalAnimationSettingsProvider,
+  useGlobalAnimationSettings,
+} from './provider';
+export type {
+  GlobalAnimationSettingsContextValue,
+  GlobalAnimationSettingsProviderProps,
+} from './types';

package/lib/__templates__/expo/client/heroui/providers/animation-settings/provider.tsx

@@ -0,0 +1,47 @@
+import React from 'react';
+import { useReducedMotion } from 'react-native-reanimated';
+import { createContext } from '../../helpers/internal/utils';
+import type {
+  GlobalAnimationSettingsContextValue,
+  GlobalAnimationSettingsProviderProps,
+} from './types';
+
+const [GlobalAnimationSettingsProvider, useGlobalAnimationSettings] =
+  createContext<GlobalAnimationSettingsContextValue>({
+    name: 'GlobalAnimationSettingsContext',
+    strict: false,
+  });
+
+export { useGlobalAnimationSettings };
+
+/**
+ * GlobalAnimationSettingsProvider Component
+ *
+ * @description
+ * Provider component that controls global animation settings across the application.
+ * When animation is set to 'disable-all', all animations will be disabled globally.
+ * Additionally, if the user has enabled reduce motion in accessibility settings,
+ * all animations will be disabled automatically.
+ *
+ * This provider wraps AnimationSettingsProvider to cascade the global setting
+ * down through the component tree.
+ *
+ * @param {GlobalAnimationSettingsProviderProps} props - Provider props
+ * @param {AnimationRootDisableAll} [props.animation] - Global animation setting
+ * @param {ReactNode} props.children - Child components to wrap
+ */
+export const GlobalAnimationSettingsProviderComponent: React.FC<
+  GlobalAnimationSettingsProviderProps
+> = ({ animation, children }) => {
+  const reducedMotion = useReducedMotion();
+  const globalIsAllAnimationsDisabled =
+    animation === 'disable-all' || reducedMotion;
+
+  return (
+    <GlobalAnimationSettingsProvider value={{ globalIsAllAnimationsDisabled }}>
+      {children}
+    </GlobalAnimationSettingsProvider>
+  );
+};
+
+export default GlobalAnimationSettingsProviderComponent;

package/lib/__templates__/expo/client/heroui/providers/animation-settings/types.ts

@@ -0,0 +1,27 @@
+import type { ReactNode } from 'react';
+import type { AnimationRootDisableAll } from '../../helpers/internal/types/animation';
+
+/**
+ * Props for GlobalAnimationSettingsProvider component
+ */
+export interface GlobalAnimationSettingsProviderProps {
+  /**
+   * Global animation setting
+   * When set to 'disable-all', all animations across the app will be disabled
+   */
+  animation?: AnimationRootDisableAll;
+  /**
+   * Child components to render within the provider
+   */
+  children: ReactNode;
+}
+
+/**
+ * Context value for global animation settings
+ */
+export interface GlobalAnimationSettingsContextValue {
+  /**
+   * Whether all animations should be disabled globally
+   */
+  globalIsAllAnimationsDisabled: boolean;
+}

package/lib/__templates__/expo/client/heroui/providers/hero-ui-native/index.ts

@@ -0,0 +1,2 @@
+export { default as HeroUINativeProvider } from './provider';
+export * from './types';

package/lib/__templates__/expo/client/heroui/providers/hero-ui-native/provider.tsx

@@ -0,0 +1,67 @@
+import React from 'react';
+import { SafeAreaListener } from 'react-native-safe-area-context';
+import { Uniwind } from 'uniwind';
+import { useDevInfo } from '../../helpers/internal/hooks';
+import { PortalHost } from '../../primitives/portal';
+import { GlobalAnimationSettingsProvider } from '../animation-settings';
+import { TextComponentProvider } from '../text-component/provider';
+import { ToastProvider } from '../toast/provider';
+import type { HeroUINativeProviderProps } from './types';
+
+/**
+ * HeroUINativeProvider Component
+ *
+ * @description
+ * Main provider component for HeroUI Native that configures the application
+ * with global settings. This component should wrap your entire application
+ * or the section where you want to use HeroUI Native components.
+ *
+ * Currently provides:
+ * - Global animation settings
+ * - Global text component configuration
+ * - Toast notification system
+ * - Portal management for overlays
+ *
+ * @param {HeroUINativeProviderProps} props - Provider configuration props
+ * @param {ReactNode} props.children - Child components to wrap
+ * @param {HeroUINativeConfig} [props.config] - Configuration object
+ *
+ */
+const HeroUINativeProvider: React.FC<HeroUINativeProviderProps> = ({
+  children,
+  config = {},
+}) => {
+  const { textProps, toast, animation, devInfo } = config;
+
+  useDevInfo(devInfo);
+
+  // Determine if toast should be enabled and get props
+  const isToastEnabled = toast !== false && toast !== 'disabled';
+  const toastProps = typeof toast === 'object' ? toast : {};
+
+  return (
+    <SafeAreaListener
+      onChange={({ insets }) => {
+        Uniwind.updateInsets(insets);
+      }}
+    >
+      <GlobalAnimationSettingsProvider animation={animation}>
+        <TextComponentProvider value={{ textProps }}>
+          {isToastEnabled ? (
+            <ToastProvider {...toastProps}>
+              {children}
+              <PortalHost />
+            </ToastProvider>
+          ) : (
+            <>
+              {children}
+              <PortalHost />
+            </>
+          )}
+        </TextComponentProvider>
+      </GlobalAnimationSettingsProvider>
+    </SafeAreaListener>
+  );
+};
+
+export default HeroUINativeProvider;

package/lib/__templates__/expo/client/heroui/providers/hero-ui-native/types.ts

@@ -0,0 +1,114 @@
+import type { ReactNode } from 'react';
+import type { AnimationRootDisableAll } from '../../helpers/internal/types';
+import type { TextComponentContextValue } from '../text-component/types';
+import type { ToastProviderProps } from '../toast/types';
+
+/**
+ * Developer information messages configuration
+ *
+ * @interface DevInfoConfig
+ *
+ * @description
+ * Controls developer-facing informational messages displayed in the console.
+ * These messages provide important guidance and best practices.
+ */
+export interface DevInfoConfig {
+  /**
+   * Show styling principles information message
+   *
+   * @description
+   * When set to `false`, disables the styling principles information message
+   * that appears in the console during development.
+   *
+   * @default true
+   */
+  stylingPrinciples?: boolean;
+}
+
+/**
+ * Configuration object for HeroUINativeProvider
+ *
+ * @interface HeroUINativeConfig
+ * @extends TextComponentContextValue
+ *
+ * @description
+ * Contains configuration options for the HeroUI Native provider.
+ * Additional configuration options can be added in future versions.
+ */
+export interface HeroUINativeConfig extends TextComponentContextValue {
+  /**
+   * Global animation configuration
+   *
+   * @description
+   * When set to 'disable-all', all animations across the application will be disabled.
+   */
+  animation?: AnimationRootDisableAll;
+  /**
+   * Toast configuration
+   *
+   * @description
+   * Configure the global toast system including insets and wrapper components.
+   * Set to `false` or `'disabled'` to disable the toast provider entirely.
+   * Provide a `ToastProviderProps` object for custom configuration.
+   */
+  toast?: boolean | 'disabled' | ToastProviderProps;
+  /**
+   * Developer information messages configuration
+   *
+   * @description
+   * Controls developer-facing informational messages displayed in the console.
+   * Use this to disable specific informational messages during development.
+   */
+  devInfo?: DevInfoConfig;
+}
+
+/**
+ * Props for HeroUINativeProvider component
+ *
+ * @interface HeroUINativeProviderProps
+ *
+ * @description
+ * Main provider component props that wraps the entire application
+ * or a section of it to provide HeroUI Native functionality.
+ *
+ * @example
+ * ```tsx
+ * <HeroUINativeProvider config={{
+ *   textProps: {
+ *     allowFontScaling: false,
+ *     maxFontSizeMultiplier: 1.5
+ *   }
+ * }}>
+ *   <App />
+ * </HeroUINativeProvider>
+ * ```
+ */
+export interface HeroUINativeProviderProps {
+  /**
+   * Child components to render within the provider
+   *
+   * @description
+   * All children will have access to HeroUI Native theme
+   * and configuration through the provider.
+   */
+  children: ReactNode;
+
+  /**
+   * Configuration object for the provider
+   *
+   * @description
+   * Contains all configuration options including global text component configuration.
+   *
+   * @example
+   * ```tsx
+   * const config: HeroUINativeConfig = {
+   *   textProps: {
+   *     allowFontScaling: false,
+   *     adjustsFontSizeToFit: false,
+   *     maxFontSizeMultiplier: 1.5
+   *   }
+   * };
+   * ```
+   */
+  config?: HeroUINativeConfig;
+}

package/lib/__templates__/expo/client/heroui/providers/hero-ui-native-raw/index.ts

@@ -0,0 +1,2 @@
+export { default as HeroUINativeProviderRaw } from './provider';
+export * from './types';

package/lib/__templates__/expo/client/heroui/providers/hero-ui-native-raw/provider.tsx

@@ -0,0 +1,50 @@
+import React from 'react';
+import { SafeAreaListener } from 'react-native-safe-area-context';
+import { Uniwind } from 'uniwind';
+import { useDevInfo } from '../../helpers/internal/hooks';
+import { GlobalAnimationSettingsProvider } from '../animation-settings';
+import { TextComponentProvider } from '../text-component/provider';
+import type { HeroUINativeProviderRawProps } from './types';
+
+/**
+ * HeroUINativeProviderRaw Component
+ *
+ * @description
+ * Raw provider component for HeroUI Native that configures the application
+ * with global settings but without ToastProvider and PortalHost.
+ * Use this when you need to manage toast and portal functionality separately
+ * (e.g. nested providers or custom setups).
+ *
+ * Currently provides:
+ * - Global animation settings
+ * - Global text component configuration
+ *
+ * @param {HeroUINativeProviderRawProps} props - Provider configuration props
+ * @param {ReactNode} props.children - Child components to wrap
+ * @param {HeroUINativeConfigRaw} [props.config] - Configuration object
+ *
+ */
+const HeroUINativeProviderRaw: React.FC<HeroUINativeProviderRawProps> = ({
+  children,
+  config = {},
+}) => {
+  const { textProps, animation, devInfo } = config;
+
+  useDevInfo(devInfo);
+
+  return (
+    <SafeAreaListener
+      onChange={({ insets }) => {
+        Uniwind.updateInsets(insets);
+      }}
+    >
+      <GlobalAnimationSettingsProvider animation={animation}>
+        <TextComponentProvider value={{ textProps }}>
+          {children}
+        </TextComponentProvider>
+      </GlobalAnimationSettingsProvider>
+    </SafeAreaListener>
+  );
+};
+
+export default HeroUINativeProviderRaw;

package/lib/__templates__/expo/client/heroui/providers/hero-ui-native-raw/types.ts

@@ -0,0 +1,39 @@
+import type { ReactNode } from 'react';
+import type { HeroUINativeConfig } from '../hero-ui-native/types';
+
+/**
+ * Configuration object for HeroUINativeProviderRaw
+ *
+ * @description
+ * A subset of {@link HeroUINativeConfig} containing only the configuration
+ * options supported by the raw provider.
+ */
+export type HeroUINativeConfigRaw = Pick<
+  HeroUINativeConfig,
+  'textProps' | 'animation' | 'devInfo'
+>;
+
+/**
+ * Props for HeroUINativeProviderRaw component
+ *
+ * @interface HeroUINativeProviderRawProps
+ *
+ * @description
+ * Props for the raw variant of the provider that includes only
+ * a subset of functionality from {@link HeroUINativeProviderProps}.
+ */
+export interface HeroUINativeProviderRawProps {
+  /**
+   * Child components to render within the raw provider
+   */
+  children: ReactNode;
+
+  /**
+   * Configuration object for the raw provider
+   *
+   * @description
+   * A subset of configuration options supported by the raw provider.
+   * See {@link HeroUINativeConfigRaw} for available options.
+   */
+  config?: HeroUINativeConfigRaw;
+}

package/lib/__templates__/expo/client/heroui/providers/text-component/index.ts

@@ -0,0 +1,2 @@
+export * from './provider';
+export * from './types';

package/lib/__templates__/expo/client/heroui/providers/text-component/provider.tsx

@@ -0,0 +1,9 @@
+import { createContext } from '../../helpers/internal/utils';
+import type { TextComponentContextValue } from './types';
+
+const [TextComponentProvider, useTextComponent] =
+  createContext<TextComponentContextValue>({
+    name: 'TextComponentContext',
+  });
+
+export { TextComponentProvider, useTextComponent };

package/lib/__templates__/expo/client/heroui/providers/text-component/types.ts

@@ -0,0 +1,52 @@
+import type { TextProps } from 'react-native';
+
+/**
+ * Global text component configuration props.
+ * These props are carefully selected to include only those that make sense
+ * to configure globally across all Text components in the application.
+ *
+ * @description
+ * Includes accessibility and font scaling settings that typically
+ * should be consistent throughout the app for better UX.
+ */
+export type TextComponentProps = {
+  /**
+   * Specifies whether fonts should be scaled down automatically to fit given style constraints.
+   *
+   * @default false
+   */
+  adjustsFontSizeToFit?: TextProps['adjustsFontSizeToFit'];
+  /**
+   * Specifies whether fonts should scale to respect Text Size accessibility settings.
+   *
+   * @default true
+   */
+  allowFontScaling?: TextProps['allowFontScaling'];
+  /**
+   * Specifies the largest possible scale a font can reach when `allowFontScaling` is enabled.
+   *
+   * Possible values:
+   *
+   * - `null` or `undefined`: inherit from the parent node or the global default (0)
+   * - `0`: no max, ignore parent/global default
+   * - `>= 1`: sets the `maxFontSizeMultiplier` of this node to this value
+   *
+   * @default `undefined`
+   */
+  maxFontSizeMultiplier?: TextProps['maxFontSizeMultiplier'];
+  /**
+   * Specifies the smallest possible scale a font can reach when adjustsFontSizeToFit is enabled. (values 0.01-1.0).
+   *
+   * iOS only
+   *
+   * @default `undefined`
+   */
+  minimumFontScale?: TextProps['minimumFontScale'];
+};
+
+/**
+ * Context value for text component configuration
+ */
+export interface TextComponentContextValue {
+  textProps?: TextComponentProps;
+}

package/lib/__templates__/expo/client/heroui/providers/toast/index.ts

@@ -0,0 +1,3 @@
+export { ToastProvider, useToast } from './provider';
+export { useToastConfig } from './toast-config.context';
+export type * from './types';

package/lib/__templates__/expo/client/heroui/providers/toast/insets-container.tsx

@@ -0,0 +1,87 @@
+import type { ReactNode } from 'react';
+import { useMemo } from 'react';
+import { Platform, View } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { FullWindowOverlay } from '../../helpers/internal/components';
+import type { ToastInsets } from './types';
+
+interface InsetsContainerProps {
+  /**
+   * When true, uses a regular View instead of FullWindowOverlay on iOS.
+   * Enables element inspector but toasts won't appear above native modals.
+   * @default false
+   */
+  disableFullWindowOverlay: boolean;
+  /**
+   * Optional inset values for all edges
+   * If not provided, defaults to platform-specific values:
+   * - iOS: safe area insets + 0px (top), + 6px (bottom), + 12px (left/right)
+   * - Android: safe area insets + 12px (all edges)
+   */
+  insets?: ToastInsets;
+  /**
+   * Custom wrapper function to wrap the toast content
+   * Receives children and should return a component that wraps them
+   * The wrapper should apply flex: 1 (via className or style) to ensure proper layout
+   * Can be any component wrapper - KeyboardAvoidingView, View, or any custom component
+   */
+  contentWrapper?: (children: ReactNode) => React.ReactElement;
+  /**
+   * Children to render inside the container
+   */
+  children: ReactNode;
+}
+
+/**
+ * Container component that applies inset padding to position toasts
+ * away from screen edges and safe areas
+ *
+ * Combines custom insets with safe area insets:
+ * - If custom inset is provided, it overrides safe area + default padding
+ * - If not provided, uses platform-specific defaults:
+ *   - iOS: safe area inset + 0px for top, + 6px for bottom, + 12px for left/right
+ *   - Android: safe area inset + 12px for all edges
+ */
+export function InsetsContainer({
+  insets,
+  contentWrapper,
+  children,
+  disableFullWindowOverlay,
+}: InsetsContainerProps) {
+  const safeAreaInsets = useSafeAreaInsets();
+
+  const finalInsets = useMemo(() => {
+    return {
+      top: insets?.top ?? safeAreaInsets.top + (Platform.OS === 'ios' ? 0 : 12),
+      bottom:
+        insets?.bottom ??
+        safeAreaInsets.bottom + (Platform.OS === 'ios' ? 6 : 12),
+      left: insets?.left ?? safeAreaInsets.left + 12,
+      right: insets?.right ?? safeAreaInsets.right + 12,
+    };
+  }, [safeAreaInsets, insets]);
+
+  const content = (
+    <View
+      className="absolute inset-0 pointer-events-box-none"
+      style={{
+        paddingTop: finalInsets.top,
+        paddingBottom: finalInsets.bottom,
+        paddingLeft: finalInsets.left,
+        paddingRight: finalInsets.right,
+      }}
+    >
+      {contentWrapper ? contentWrapper(children) : children}
+    </View>
+  );
+
+  if (Platform.OS !== 'ios') {
+    return content;
+  }
+
+  return (
+    <FullWindowOverlay disableFullWindowOverlay={disableFullWindowOverlay}>
+      {content}
+    </FullWindowOverlay>
+  );
+}