@coze-arch/cli 0.0.10 → 0.0.11

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

@@ -0,0 +1,320 @@
+import type {
+  EntryOrExitLayoutType,
+  WithTimingConfig,
+} from 'react-native-reanimated';
+import type {
+  AnimationRoot,
+  AnimationValue,
+  ViewRef,
+} from '../../helpers/internal/types';
+import type * as ToastPrimitive from '../../primitives/toast';
+import type {
+  ToastComponentProps,
+  ToastShowOptions,
+} from '../../providers/toast';
+import type { ButtonRootProps } from '../button';
+import type { ButtonRootPropsScaleHighlight } from '../button/button.types';
+
+/**
+ * Toast variant types
+ */
+export type ToastVariant =
+  | 'default'
+  | 'accent'
+  | 'success'
+  | 'warning'
+  | 'danger';
+
+/**
+ * Toast placement types
+ */
+export type ToastPlacement = 'top' | 'bottom';
+
+/**
+ * Animation configuration for toast root component
+ */
+export type ToastRootAnimation = AnimationRoot<{
+  opacity?: AnimationValue<{
+    /**
+     * Opacity interpolation values [start, end]
+     * Controls how fast toast items fade out as they move beyond the visible stack limits.
+     * When toasts are pushed out of view (beyond the last few visible items), their opacity
+     * gradually decreases to create a smooth disappearing effect.
+     * - First value: fully visible opacity (1) for items within visible stack
+     * - Second value: hidden opacity (0) for items pushed out of view
+     * @default [1, 0]
+     */
+    value?: [number, number];
+    /**
+     * Animation timing configuration
+     * @default { duration: 300 }
+     */
+    timingConfig?: WithTimingConfig;
+  }>;
+  translateY?: AnimationValue<{
+    /**
+     * Translate Y interpolation values [start, end]
+     * Controls how much of a toast item is visible when it's positioned behind the last visible toast.
+     * This creates a "peek" effect where stacked toasts are slightly offset vertically,
+     * allowing users to see a portion of the toast behind the current one.
+     * - First value: no offset (0) for the last/active toast
+     * - Second value: vertical offset in pixels (10) for toasts behind the last one
+     * Note: The offset direction is automatically adjusted based on placement (top/bottom)
+     * @default [0, 10] (multiplied by placement sign)
+     */
+    value?: [number, number];
+    /**
+     * Animation timing configuration
+     * @default { duration: 300 }
+     */
+    timingConfig?: WithTimingConfig;
+  }>;
+  scale?: AnimationValue<{
+    /**
+     * Scale interpolation values [start, end]
+     * Controls the size scaling of toast items in the stack.
+     * Toasts behind the active one are slightly scaled down to create depth and visual hierarchy.
+     * - First value: normal scale (1) for the active/last toast
+     * - Second value: scaled down value (0.97) for toasts positioned behind
+     * @default [1, 0.97]
+     */
+    value?: [number, number];
+    /**
+     * Animation timing configuration
+     * @default { duration: 300 }
+     */
+    timingConfig?: WithTimingConfig;
+  }>;
+  entering?: AnimationValue<{
+    /**
+     * Custom entering animation for top placement
+     * @default FadeInUp.springify().withInitialValues({ opacity: 1, transform: [{ translateY: -100 }] }).mass(3)
+     */
+    top?: EntryOrExitLayoutType;
+    /**
+     * Custom entering animation for bottom placement
+     * @default FadeInDown.springify().withInitialValues({ opacity: 1, transform: [{ translateY: 100 }] }).mass(3)
+     */
+    bottom?: EntryOrExitLayoutType;
+  }>;
+  exiting?: AnimationValue<{
+    /**
+     * Custom exiting animation for top placement
+     * @default Keyframe animation with translateY: -100, scale: 0.97, opacity: 0.5
+     */
+    top?: EntryOrExitLayoutType;
+    /**
+     * Custom exiting animation for bottom placement
+     * @default Keyframe animation with translateY: 100, scale: 0.97, opacity: 0.5
+     */
+    bottom?: EntryOrExitLayoutType;
+  }>;
+}>;
+
+/**
+ * Props for the Toast.Root component
+ */
+export interface ToastRootProps
+  extends ToastPrimitive.RootProps,
+    Omit<ToastComponentProps, 'id'> {
+  /**
+   * Visual variant of the toast
+   * @default 'default'
+   */
+  variant?: ToastVariant;
+  /**
+   * Placement of the toast
+   * @default 'top'
+   */
+  placement?: ToastPlacement;
+  /**
+   * Additional CSS class for the toast container
+   *
+   * @note The following style properties are occupied by animations and cannot be set via className:
+   * - `opacity` - Animated for visibility transitions when toasts are pushed beyond visible stack limits
+   * - `transform` (translateY) - Animated for vertical position transitions when toasts are stacked, and for swipe-to-dismiss gestures
+   * - `transform` (scale) - Animated for size scaling transitions when toasts are stacked (toasts behind active one are scaled down)
+   * - `height` - Animated for height transitions when toast content changes
+   *
+   * To customize these properties, use the `animation` prop:
+   * ```tsx
+   * <Toast.Root
+   *   animation={{
+   *     opacity: {
+   *       value: [1, 0],
+   *       timingConfig: { duration: 300 }
+   *     },
+   *     translateY: {
+   *       value: [0, 10],
+   *       timingConfig: { duration: 300 }
+   *     },
+   *     scale: {
+   *       value: [1, 0.97],
+   *       timingConfig: { duration: 300 }
+   *     }
+   *   }}
+   * />
+   * ```
+   *
+   * To completely disable animated styles and use your own via className or style prop, set `isAnimatedStyleActive={false}`.
+   */
+  className?: string;
+  /**
+   * Animation configuration for toast
+   * - `false` or `"disabled"`: Disable only root animations
+   * - `"disable-all"`: Disable all animations including children
+   * - `true` or `undefined`: Use default animations
+   * - `object`: Custom animation configuration
+   */
+  animation?: ToastRootAnimation;
+  /**
+   * Whether the toast can be swiped to dismiss and dragged with rubber effect
+   * @default true
+   */
+  isSwipeable?: boolean;
+  /**
+   * Whether animated styles (react-native-reanimated) are active
+   * When `false`, the animated style is removed and you can implement custom logic
+   * This prop should only be used when you want to write custom styling logic instead of the default animated styles
+   * @default true
+   */
+  isAnimatedStyleActive?: boolean;
+}
+
+/**
+ * Props for the Toast.Title component
+ */
+export interface ToastTitleProps extends ToastPrimitive.TitleProps {
+  /**
+   * Content to be rendered as title
+   */
+  children?: React.ReactNode;
+  /**
+   * Additional CSS class for the title
+   */
+  className?: string;
+}
+
+/**
+ * Props for the Toast.Description component
+ */
+export interface ToastDescriptionProps extends ToastPrimitive.DescriptionProps {
+  /**
+   * Content to be rendered as description
+   */
+  children?: React.ReactNode;
+  /**
+   * Additional CSS class for the description
+   */
+  className?: string;
+}
+
+/**
+ * Props for the Toast.Action component
+ */
+export type ToastActionProps = Omit<
+  ButtonRootPropsScaleHighlight,
+  'feedbackVariant'
+>;
+
+/**
+ * Props for the Toast.Close component
+ */
+export type ToastCloseProps = ButtonRootProps & {
+  /**
+   * Custom icon props for the close button icon
+   */
+  iconProps?: {
+    size?: number;
+    color?: string;
+  };
+};
+
+/**
+ * Context values shared between Toast components
+ */
+export interface ToastContextValue {
+  /**
+   * Visual variant of the toast
+   */
+  variant: ToastVariant;
+  /**
+   * Function to hide the toast
+   */
+  hide?: (ids?: string | string[] | 'all') => void;
+  /**
+   * ID of the toast
+   */
+  id?: string;
+}
+
+/**
+ * Ref type for the Toast.Root component
+ */
+export type ToastRootRef = ViewRef;
+
+/**
+ * Props for useToastRootAnimation hook
+ * Picks required properties from ToastRootProps and adds id from ToastComponentProps
+ */
+export type UseToastRootAnimationOptions = Pick<
+  ToastRootProps,
+  | 'animation'
+  | 'index'
+  | 'total'
+  | 'heights'
+  | 'placement'
+  | 'hide'
+  | 'isSwipeable'
+  | 'maxVisibleToasts'
+> &
+  Pick<ToastComponentProps, 'id'>;
+
+/**
+ * Props for the DefaultToast component
+ * Used internally when showing toasts with string or config object (without component)
+ */
+export interface DefaultToastProps extends ToastComponentProps {
+  /**
+   * Visual variant of the toast
+   * @default 'default'
+   */
+  variant?: ToastRootProps['variant'];
+  /**
+   * Placement of the toast
+   * @default 'top'
+   */
+  placement?: ToastRootProps['placement'];
+  /**
+   * Animation configuration for toast
+   */
+  animation?: ToastRootProps['animation'];
+  /**
+   * Whether the toast can be swiped to dismiss and dragged with rubber effect
+   */
+  isSwipeable?: ToastRootProps['isSwipeable'];
+  /**
+   * Label text for the toast
+   */
+  label?: string;
+  /**
+   * Description text for the toast
+   */
+  description?: string;
+  /**
+   * Action button label text
+   */
+  actionLabel?: string;
+  /**
+   * Callback function called when the action button is pressed
+   * Receives show and hide functions for programmatic toast control
+   */
+  onActionPress?: (helpers: {
+    show: (options: string | ToastShowOptions) => string;
+    hide: (ids?: string | string[] | 'all') => void;
+  }) => void;
+  /**
+   * Icon element to display in the toast
+   */
+  icon?: React.ReactNode;
+}

package/lib/__templates__/expo/client/heroui/docs.md

@@ -0,0 +1,47 @@
+# HeroUI Native Documentation
+
+> Documentation for HeroUI Native component library.
+
+HeroUI Native is a component library built on [Tailwind v4](https://tailwindcss.com/) via [Uniwind](https://uniwind.dev/) and modern mobile development technologies. Every component comes with smooth animations, polished details, and built-in accessibility—ready to use, fully customizable.
+
+## Documentation Index
+
+### Components
+
+- [Button](./components/button/button.md): Interactive component that triggers an action when pressed.
+- [CloseButton](./components/close-button/close-button.md): Button component for closing dialogs, modals, or dismissing content.
+- [Menu](./components/menu/menu.md): A floating context menu with positioning, selection groups, and multiple presentation modes.
+- [TagGroup](./components/tag-group/tag-group.md): A compound component for displaying and managing selectable tags with optional removal.
+- [Slider](./components/slider/slider.md): A draggable input for selecting a value or range within a bounded interval.
+- [Switch](./components/switch/switch.md): A toggle control that allows users to switch between on and off states.
+- [Chip](./components/chip/chip.md): Displays a compact element in a capsule shape.
+- [Alert](./components/alert/alert.md): Displays important messages and notifications to users with status indicators.
+- [SkeletonGroup](./components/skeleton-group/skeleton-group.md): Coordinates multiple skeleton loading placeholders with centralized animation control.
+- [Skeleton](./components/skeleton/skeleton.md): Displays a loading placeholder with shimmer or pulse animation effects.
+- [Spinner](./components/spinner/spinner.md): Displays an animated loading indicator.
+- [Checkbox](./components/checkbox/checkbox.md): A selectable control that allows users to toggle between checked and unchecked states.
+- [ControlField](./components/control-field/control-field.md): A field component that combines a label, description (or other content), and a control component (Switch or Checkbox) into a single pressable area.
+- [Description](./components/description/description.md): Text component for providing accessible descriptions and helper text for form fields and other UI elements.
+- [FieldError](./components/field-error/field-error.md): Displays validation error message content with smooth animations.
+- [InputGroup](./components/input-group/input-group.md): A compound layout component that groups an input with optional prefix and suffix decorators.
+- [InputOTP](./components/input-otp/input-otp.md): Input component for entering one-time passwords (OTP) with individual character slots, animations, and validation support.
+- [Input](./components/input/input.md): A text input component with styled border and background for collecting user input.
+- [Label](./components/label/label.md): Text component for labeling form fields and other UI elements with support for required indicators and validation states.
+- [RadioGroup](./components/radio-group/radio-group.md): A set of radio buttons where only one option can be selected at a time.
+- [SearchField](./components/search-field/search-field.md): A compound search input for filtering and querying content.
+- [Select](./components/select/select.md): Displays a list of options for the user to pick from — triggered by a button.
+- [TextArea](./components/text-area/text-area.md): A multiline text input component with styled border and background for collecting longer user input.
+- [TextField](./components/text-field/text-field.md): A text input component with label, description, and error handling for collecting user input.
+- [Card](./components/card/card.md): Displays a card container with flexible layout sections for structured content.
+- [Separator](./components/separator/separator.md): A simple line to separate content visually.
+- [Surface](./components/surface/surface.md): Container component that provides elevation and background styling.
+- [Avatar](./components/avatar/avatar.md): Displays a user avatar with support for images, text initials, or fallback icons.
+- [Accordion](./components/accordion/accordion.md): A collapsible content panel for organizing information in a compact space
+- [ListGroup](./components/list-group/list-group.md): A Surface-based container that groups related list items with consistent layout and spacing.
+- [Tabs](./components/tabs/tabs.md): Organize content into tabbed views with animated transitions and indicators.
+- [BottomSheet](./components/bottom-sheet/bottom-sheet.md): Displays a bottom sheet that slides up from the bottom with animated transitions and swipe-to-dismiss gestures.
+- [Dialog](./components/dialog/dialog.md): Displays a modal overlay with animated transitions and gesture-based dismissal.
+- [Popover](./components/popover/popover.md): Displays a floating content panel anchored to a trigger element with placement and alignment options.
+- [Toast](./components/toast/toast.md): Displays temporary notification messages that appear at the top or bottom of the screen.
+- [PressableFeedback](./components/pressable-feedback/pressable-feedback.md): Container component that provides visual feedback for press interactions with automatic scale animation.
+- [ScrollShadow](./components/scroll-shadow/scroll-shadow.md): Adds dynamic gradient shadows to scrollable content based on scroll position and overflow.

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

@@ -0,0 +1,3 @@
+export { useTextComponent } from '../../../providers/text-component/index';
+export * from './use-is-on-surface';
+export * from './use-theme-color';

package/lib/__templates__/expo/client/heroui/helpers/external/hooks/use-is-on-surface.ts

@@ -0,0 +1,8 @@
+import { useSurface } from '../../../components/surface';
+
+export const useIsOnSurface = () => {
+  const surfaceContext = useSurface();
+  return surfaceContext?.variant && surfaceContext.variant !== 'transparent'
+    ? true
+    : false;
+};

package/lib/__templates__/expo/client/heroui/helpers/external/hooks/use-theme-color.ts

@@ -0,0 +1,137 @@
+import { useCSSVariable } from 'uniwind';
+
+/**
+ * Theme colors as const array for efficient mapping
+ * Ordered to match the order in src/styles/theme.css
+ */
+const THEME_COLORS = [
+  'background',
+  'foreground',
+  'surface',
+  'surface-foreground',
+  'surface-hover',
+  'overlay',
+  'overlay-foreground',
+  'muted',
+  'accent',
+  'accent-foreground',
+  'segment',
+  'segment-foreground',
+  'border',
+  'separator',
+  'focus',
+  'link',
+  'default',
+  'default-foreground',
+  'success',
+  'success-foreground',
+  'warning',
+  'warning-foreground',
+  'danger',
+  'danger-foreground',
+  'field',
+  'field-foreground',
+  'field-placeholder',
+  'field-border',
+  'background-secondary',
+  'background-tertiary',
+  'background-inverse',
+  'default-hover',
+  'accent-hover',
+  'success-hover',
+  'warning-hover',
+  'danger-hover',
+  'field-hover',
+  'field-focus',
+  'field-border-hover',
+  'field-border-focus',
+  'accent-soft',
+  'accent-soft-foreground',
+  'accent-soft-hover',
+  'danger-soft',
+  'danger-soft-foreground',
+  'danger-soft-hover',
+  'warning-soft',
+  'warning-soft-foreground',
+  'warning-soft-hover',
+  'success-soft',
+  'success-soft-foreground',
+  'success-soft-hover',
+  'surface-secondary',
+  'surface-tertiary',
+  'on-surface',
+  'on-surface-foreground',
+  'on-surface-hover',
+  'on-surface-focus',
+  'on-surface-secondary',
+  'on-surface-secondary-foreground',
+  'on-surface-secondary-hover',
+  'on-surface-secondary-focus',
+  'on-surface-tertiary',
+  'on-surface-tertiary-foreground',
+  'on-surface-tertiary-hover',
+  'on-surface-tertiary-focus',
+  'separator-secondary',
+  'separator-tertiary',
+  'border-secondary',
+  'border-tertiary',
+] as const;
+
+/**
+ * Theme colors type derived from THEME_COLORS array
+ */
+export type ThemeColor = (typeof THEME_COLORS)[number];
+
+/**
+ * Helper type to create a tuple of strings with the same length as the input array
+ */
+type CreateStringTuple<
+  N extends number,
+  TAcc extends string[] = [],
+> = TAcc['length'] extends N ? TAcc : CreateStringTuple<N, [...TAcc, string]>;
+
+/**
+ * Hook to retrieve theme color values from CSS variables.
+ * Supports both single color and multiple colors for efficient batch retrieval.
+ *
+ * @param themeColor - Single theme color name or array of theme color names
+ * @returns Single color string or array of color strings
+ *
+ * @example
+ * // Single color
+ * const primaryColor = useThemeColor('accent');
+ *
+ * @example
+ * // Multiple colors (more efficient)
+ * const [primaryColor, backgroundColor] = useThemeColor(['accent', 'background']);
+ */
+export function useThemeColor(themeColor: ThemeColor): string;
+export function useThemeColor<T extends readonly [ThemeColor, ...ThemeColor[]]>(
+  themeColor: T
+): CreateStringTuple<T['length']>;
+export function useThemeColor(themeColor: ThemeColor[]): string[];
+export function useThemeColor(
+  themeColor: ThemeColor | ThemeColor[]
+): string | string[] {
+  const isArray = Array.isArray(themeColor);
+  const cssVariables = isArray
+    ? themeColor.map((color) => `--color-${color}`)
+    : [`--color-${themeColor}`];
+
+  const resolvedColors = useCSSVariable(cssVariables);
+
+  const processedColors: string[] = resolvedColors.map((color) => {
+    if (typeof color === 'string') {
+      return color;
+    }
+    if (typeof color === 'number') {
+      return String(color);
+    }
+    return 'invalid';
+  });
+
+  if (isArray) {
+    return processedColors;
+  }
+  return processedColors[0]!;
+}

package/lib/__templates__/expo/client/heroui/helpers/external/utils/cn.ts

@@ -0,0 +1,12 @@
+import { cnMerge, type CnOptions } from 'tailwind-variants';
+
+export function cn(...args: CnOptions) {
+  return cnMerge(args)({
+    twMerge: true,
+    twMergeConfig: {
+      classGroups: {
+        opacity: [{ opacity: ['disabled'] }],
+      },
+    },
+  });
+}