@coze-arch/cli 0.0.10 → 0.0.11

package/lib/__templates__/expo/client/heroui/components/button/button.tsx

@@ -0,0 +1,284 @@
+import { forwardRef, useMemo } from 'react';
+import { Text as RNText } from 'react-native';
+import { useThemeColor } from '../../helpers/external/hooks';
+import { colorKit } from '../../helpers/external/utils';
+import { HeroText } from '../../helpers/internal/components';
+import type { PressableRef } from '../../helpers/internal/types';
+import { childrenToString, createContext } from '../../helpers/internal/utils';
+import {
+  PressableFeedback,
+  type PressableFeedbackHighlightAnimation,
+  type PressableFeedbackRippleAnimation,
+  type PressableFeedbackScaleAnimation,
+} from '../pressable-feedback';
+import { DISPLAY_NAME } from './button.constants';
+import { buttonClassNames, buttonStyleSheet } from './button.styles';
+import type {
+  ButtonContextValue,
+  ButtonLabelProps,
+  ButtonRootProps,
+} from './button.types';
+import { isAnimationDisabled, resolveAnimationObject } from './button.utils';
+
+const [ButtonProvider, useButton] = createContext<ButtonContextValue>({
+  name: 'ButtonContext',
+});
+
+// --------------------------------------------------
+
+const ButtonRoot = forwardRef<PressableRef, ButtonRootProps>((props, ref) => {
+  const {
+    children,
+    variant = 'primary',
+    feedbackVariant = 'scale-highlight',
+    animation,
+    size = 'md',
+    isIconOnly = false,
+    isDisabled = false,
+    className,
+    style,
+    accessibilityRole = 'button',
+    ...restProps
+  } = props;
+
+  const [
+    themeColorAccentHover,
+    themeColorDefaultHover,
+    themeColorDangerHover,
+    themeColorDangerSoftHover,
+  ] = useThemeColor([
+    'accent-hover',
+    'default-hover',
+    'danger-hover',
+    'danger-soft-hover',
+  ]);
+
+  const stringifiedChildren = childrenToString(children);
+
+  const rootClassName = buttonClassNames.root({
+    variant,
+    size,
+    isIconOnly,
+    isDisabled,
+    className,
+  });
+
+  const resolvedAnimation = resolveAnimationObject(animation);
+  const allAnimationsDisabled = isAnimationDisabled(animation);
+
+  const highlightColorMap = useMemo(() => {
+    switch (variant) {
+      case 'primary':
+        return themeColorAccentHover;
+      case 'secondary':
+        return themeColorDefaultHover;
+      case 'tertiary':
+        return themeColorDefaultHover;
+      case 'outline':
+        return colorKit.setAlpha(themeColorDefaultHover, 0.3).hex();
+      case 'ghost':
+        return colorKit.setAlpha(themeColorDefaultHover, 0.3).hex();
+      case 'danger':
+        return themeColorDangerHover;
+      case 'danger-soft':
+        return themeColorDangerSoftHover;
+    }
+  }, [
+    variant,
+    themeColorAccentHover,
+    themeColorDefaultHover,
+    themeColorDangerHover,
+    themeColorDangerSoftHover,
+  ]);
+
+  const highlightAnimationConfig = useMemo(() => {
+    if (feedbackVariant !== 'scale-highlight') {
+      return undefined;
+    }
+
+    const highlightAnimation = resolvedAnimation?.highlight as
+      | PressableFeedbackHighlightAnimation
+      | undefined;
+
+    if (highlightAnimation === false || highlightAnimation === 'disabled') {
+      return undefined;
+    }
+
+    const defaultConfig = {
+      backgroundColor: {
+        value: highlightColorMap,
+      },
+      opacity: {
+        value: [0, 1] as [number, number],
+      },
+    };
+
+    if (typeof highlightAnimation === 'object' && highlightAnimation !== null) {
+      return {
+        backgroundColor: {
+          ...defaultConfig.backgroundColor,
+          ...(highlightAnimation.backgroundColor ?? {}),
+        },
+        opacity: {
+          ...defaultConfig.opacity,
+          ...(highlightAnimation.opacity ?? {}),
+        },
+      };
+    }
+
+    return defaultConfig;
+  }, [feedbackVariant, highlightColorMap, resolvedAnimation?.highlight]);
+
+  const rippleAnimationConfig = useMemo(() => {
+    if (feedbackVariant !== 'scale-ripple') {
+      return undefined;
+    }
+
+    const rippleAnimation = resolvedAnimation?.ripple as
+      | PressableFeedbackRippleAnimation
+      | undefined;
+
+    if (rippleAnimation === false || rippleAnimation === 'disabled') {
+      return undefined;
+    }
+
+    const defaultConfig = {
+      backgroundColor: { value: highlightColorMap },
+      opacity: { value: [0, 1, 0] as [number, number, number] },
+    };
+
+    if (typeof rippleAnimation === 'object' && rippleAnimation !== null) {
+      return {
+        backgroundColor: {
+          ...defaultConfig.backgroundColor,
+          ...(rippleAnimation.backgroundColor ?? {}),
+        },
+        opacity: {
+          ...defaultConfig.opacity,
+          ...(rippleAnimation.opacity ?? {}),
+        },
+        ...(rippleAnimation.scale !== undefined && {
+          scale: rippleAnimation.scale,
+        }),
+        ...(rippleAnimation.progress !== undefined && {
+          progress: rippleAnimation.progress,
+        }),
+      };
+    }
+
+    return defaultConfig;
+  }, [feedbackVariant, highlightColorMap, resolvedAnimation?.ripple]);
+
+  const scaleAnimation = resolvedAnimation?.scale as
+    | PressableFeedbackScaleAnimation
+    | undefined;
+
+  const rootAnimation = useMemo(() => {
+    if (allAnimationsDisabled) {
+      return 'disable-all' as const;
+    }
+    if (feedbackVariant === 'none') {
+      return false as const;
+    }
+    if (scaleAnimation === false || scaleAnimation === 'disabled') {
+      return false as const;
+    }
+    if (typeof scaleAnimation === 'object' && scaleAnimation !== null) {
+      return { scale: scaleAnimation };
+    }
+    return undefined;
+  }, [allAnimationsDisabled, feedbackVariant, scaleAnimation]);
+
+  const contextValue = useMemo(
+    () => ({
+      size,
+      variant,
+      isDisabled,
+    }),
+    [size, variant, isDisabled]
+  );
+
+  const content = stringifiedChildren ? (
+    <ButtonLabel>{stringifiedChildren}</ButtonLabel>
+  ) : (
+    children
+  );
+
+  return (
+    <ButtonProvider value={contextValue}>
+      <PressableFeedback
+        ref={ref}
+        isDisabled={isDisabled}
+        className={rootClassName}
+        style={
+          typeof style === 'function'
+            ? (state) => [buttonStyleSheet.buttonRoot, style(state)]
+            : [buttonStyleSheet.buttonRoot, style]
+        }
+        accessibilityRole={accessibilityRole}
+        accessibilityState={{ disabled: isDisabled }}
+        animation={rootAnimation}
+        {...restProps}
+      >
+        {feedbackVariant === 'scale-highlight' &&
+          highlightAnimationConfig !== undefined && (
+            <PressableFeedback.Highlight animation={highlightAnimationConfig} />
+          )}
+        {feedbackVariant === 'scale-ripple' &&
+          rippleAnimationConfig !== undefined && (
+            <PressableFeedback.Ripple animation={rippleAnimationConfig} />
+          )}
+        {content}
+      </PressableFeedback>
+    </ButtonProvider>
+  );
+});
+
+// --------------------------------------------------
+
+const ButtonLabel = forwardRef<RNText, ButtonLabelProps>((props, ref) => {
+  const { children, className, ...restProps } = props;
+
+  const { size, variant } = useButton();
+
+  const labelClassName = buttonClassNames.label({
+    size,
+    variant,
+    className,
+  });
+
+  return (
+    <HeroText ref={ref} className={labelClassName} {...restProps}>
+      {children}
+    </HeroText>
+  );
+});
+
+// --------------------------------------------------
+
+ButtonRoot.displayName = DISPLAY_NAME.BUTTON_ROOT;
+ButtonLabel.displayName = DISPLAY_NAME.BUTTON_LABEL;
+
+/**
+ * Compound Button component with sub-components.
+ *
+ * @component Button - Main button container wrapping `PressableFeedback`. Handles press
+ * interactions, visual variants, and feedback animations. The `feedbackVariant` prop controls
+ * which effects are rendered (`scale-highlight`, `scale-ripple`, `scale`, or `none`), while the
+ * `animation` prop provides granular control over each sub-animation (scale, highlight, ripple).
+ * String children are automatically rendered as a label.
+ *
+ * @component Button.Label - Text content of the button. Inherits size and variant styling
+ * from the parent Button context.
+ *
+ * Props flow from Button to sub-components via context (size, variant, isDisabled).
+ *
+ * @see Full documentation: https://v3.heroui.com/docs/native/components/button
+ */
+const CompoundButton = Object.assign(ButtonRoot, {
+  /** Button label - renders text or custom content */
+  Label: ButtonLabel,
+});
+
+export { useButton };
+export default CompoundButton;

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

@@ -0,0 +1,175 @@
+import type { TextProps } from 'react-native';
+import type {
+  AnimationRoot,
+  AnimationRootDisableAll,
+} from '../../helpers/internal/types';
+import type {
+  PressableFeedbackHighlightAnimation,
+  PressableFeedbackProps,
+  PressableFeedbackRippleAnimation,
+  PressableFeedbackScaleAnimation,
+} from '../pressable-feedback';
+
+/**
+ * Size variants for the Button component
+ */
+export type ButtonSize = 'sm' | 'md' | 'lg';
+
+/**
+ * Variant types for the Button component
+ */
+export type ButtonVariant =
+  | 'primary'
+  | 'secondary'
+  | 'tertiary'
+  | 'outline'
+  | 'ghost'
+  | 'danger'
+  | 'danger-soft';
+
+/**
+ * Feedback variant that determines which PressableFeedback compound parts are rendered
+ */
+export type ButtonFeedbackVariant =
+  | 'scale-highlight'
+  | 'scale-ripple'
+  | 'scale'
+  | 'none';
+
+/**
+ * Shared base props for the Button.Root component (common across all feedback variants)
+ */
+type ButtonRootPropsBase = Omit<PressableFeedbackProps, 'animation'> & {
+  /**
+   * Visual variant of the button
+   * @default 'primary'
+   */
+  variant?: ButtonVariant;
+  /**
+   * Size of the button
+   * @default 'md'
+   */
+  size?: ButtonSize;
+  /**
+   * Whether the button displays an icon only (needed for correct layout)
+   * @default false
+   */
+  isIconOnly?: boolean;
+};
+
+/**
+ * Props when feedbackVariant is 'scale-highlight' (default).
+ * Animation accepts scale and highlight configuration.
+ */
+export type ButtonRootPropsScaleHighlight = ButtonRootPropsBase & {
+  /**
+   * Feedback variant that renders Scale + Highlight compound parts
+   * @default 'scale-highlight'
+   */
+  feedbackVariant?: 'scale-highlight';
+  /**
+   * Animation configuration for scale and highlight feedback
+   */
+  animation?: AnimationRoot<{
+    /** Scale animation configuration */
+    scale?: PressableFeedbackScaleAnimation;
+    /** Highlight overlay configuration */
+    highlight?: PressableFeedbackHighlightAnimation;
+  }>;
+};
+
+/**
+ * Props when feedbackVariant is 'scale-ripple'.
+ * Animation accepts scale and ripple configuration.
+ */
+type ButtonRootPropsScaleRipple = ButtonRootPropsBase & {
+  /**
+   * Feedback variant that renders Scale + Ripple compound parts
+   */
+  feedbackVariant: 'scale-ripple';
+  /**
+   * Animation configuration for scale and ripple feedback
+   */
+  animation?: AnimationRoot<{
+    /** Scale animation configuration */
+    scale?: PressableFeedbackScaleAnimation;
+    /** Ripple overlay configuration */
+    ripple?: PressableFeedbackRippleAnimation;
+  }>;
+};
+
+/**
+ * Props when feedbackVariant is 'scale'.
+ * Only the built-in scale animation is active — no highlight or ripple overlay is rendered.
+ */
+type ButtonRootPropsScale = ButtonRootPropsBase & {
+  /**
+   * Feedback variant that renders only the built-in scale animation (no highlight or ripple overlay)
+   */
+  feedbackVariant: 'scale';
+  /**
+   * Animation configuration for scale-only feedback
+   */
+  animation?: AnimationRoot<{
+    /** Scale animation configuration */
+    scale?: PressableFeedbackScaleAnimation;
+  }>;
+};
+
+/**
+ * Props when feedbackVariant is 'none'.
+ * All feedback effects are disabled — no scale, highlight, or ripple is rendered.
+ */
+type ButtonRootPropsNone = ButtonRootPropsBase & {
+  /**
+   * Feedback variant that disables all feedback effects (no scale, highlight, or ripple)
+   */
+  feedbackVariant: 'none';
+  /**
+   * Only 'disable-all' is accepted when feedback is disabled
+   */
+  animation?: AnimationRootDisableAll;
+};
+
+/**
+ * Props for the Button.Root component.
+ * Discriminated union based on `feedbackVariant` — the `animation` prop type
+ * is constrained to only the relevant sub-component configs for each variant.
+ */
+export type ButtonRootProps =
+  | ButtonRootPropsScaleHighlight
+  | ButtonRootPropsScaleRipple
+  | ButtonRootPropsScale
+  | ButtonRootPropsNone;
+
+/**
+ * Props for the Button.Label component
+ */
+export interface ButtonLabelProps extends TextProps {
+  /**
+   * Content to be rendered as label
+   */
+  children?: React.ReactNode;
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+}
+
+/**
+ * Context values shared between Button components
+ */
+export interface ButtonContextValue {
+  /**
+   * Size of the button
+   */
+  size: ButtonSize;
+  /**
+   * Visual variant of the button
+   */
+  variant: ButtonVariant;
+  /**
+   * Whether the button is disabled
+   */
+  isDisabled: boolean;
+}

package/lib/__templates__/expo/client/heroui/components/button/button.utils.ts

@@ -0,0 +1,34 @@
+import type { ButtonRootProps } from './button.types';
+
+/**
+ * Resolves the animation prop into its object form.
+ * Returns `undefined` when the animation is a non-object value (boolean / string).
+ */
+export function resolveAnimationObject(
+  animation: ButtonRootProps['animation']
+): Record<string, unknown> | undefined {
+  if (typeof animation === 'object' && animation !== null) {
+    return animation;
+  }
+  return undefined;
+}
+
+/**
+ * Determines whether all animations should be disabled based on the animation prop value.
+ */
+export function isAnimationDisabled(
+  animation: ButtonRootProps['animation']
+): boolean {
+  if (
+    animation === false ||
+    animation === 'disabled' ||
+    animation === 'disable-all'
+  ) {
+    return true;
+  }
+  if (typeof animation === 'object' && animation !== null) {
+    const { state } = animation;
+    return state === false || state === 'disabled' || state === 'disable-all';
+  }
+  return false;
+}

package/lib/__templates__/expo/client/heroui/components/button/index.ts

@@ -0,0 +1,9 @@
+export { default as Button, useButton } from './button';
+export { buttonClassNames } from './button.styles';
+export type {
+  ButtonContextValue,
+  ButtonLabelProps,
+  ButtonRootProps,
+  ButtonSize,
+  ButtonVariant,
+} from './button.types';

package/lib/__templates__/expo/client/heroui/components/card/card.constants.ts

@@ -0,0 +1,11 @@
+/**
+ * Display names for Card components
+ */
+export const DISPLAY_NAME = {
+  ROOT: 'HeroUINative.Card.Root',
+  HEADER: 'HeroUINative.Card.Header',
+  BODY: 'HeroUINative.Card.Body',
+  FOOTER: 'HeroUINative.Card.Footer',
+  TITLE: 'HeroUINative.Card.Title',
+  DESCRIPTION: 'HeroUINative.Card.Description',
+};

package/lib/__templates__/expo/client/heroui/components/card/card.md

@@ -0,0 +1,186 @@
+# Card
+
+Displays a card container with flexible layout sections for structured content.
+
+## Import
+
+```tsx
+import { Card } from '@/heroui';
+```
+
+## Anatomy
+
+```tsx
+<Card>
+  <Card.Header>...</Card.Header>
+  <Card.Body>
+    <Card.Title>...</Card.Title>
+    <Card.Description>...</Card.Description>
+  </Card.Body>
+  <Card.Footer>...</Card.Footer>
+</Card>
+```
+
+- **Card**: Main container that extends Surface component. Provides base card structure with configurable surface variants and handles overall layout.
+- **Card.Header**: Header section for top-aligned content like icons or badges.
+- **Card.Body**: Main content area with flex-1 that expands to fill all available space between Card.Header and Card.Footer.
+- **Card.Title**: Title text with foreground color and medium font weight.
+- **Card.Description**: Description text with muted color and smaller font size.
+- **Card.Footer**: Footer section for bottom-aligned actions like buttons.
+
+## Usage
+
+### Basic Usage
+
+The Card component creates a container with built-in sections for organized content.
+
+```tsx
+<Card>
+  <Card.Body>...</Card.Body>
+</Card>
+```
+
+### With Title and Description
+
+Combine title and description components for structured text content.
+
+```tsx
+<Card>
+  <Card.Body>
+    <Card.Title>...</Card.Title>
+    <Card.Description>...</Card.Description>
+  </Card.Body>
+</Card>
+```
+
+### With Header and Footer
+
+Add header and footer sections for icons, badges, or actions.
+
+```tsx
+<Card>
+  <Card.Header>...</Card.Header>
+  <Card.Body>...</Card.Body>
+  <Card.Footer>...</Card.Footer>
+</Card>
+```
+
+### Variants
+
+Control the card's background appearance using different variants.
+
+```tsx
+<Card variant="default">...</Card>
+<Card variant="secondary">...</Card>
+<Card variant="tertiary">...</Card>
+<Card variant="transparent">...</Card>
+```
+
+### Horizontal Layout
+
+Create horizontal cards by using flex-row styling.
+
+```tsx
+<Card className="flex-row gap-4">
+  <Image source={...} className="size-24 rounded-lg" />
+</Card>
+```
+
+### Background Image
+
+Use an image as an absolute positioned background.
+
+```tsx
+<Card>
+  <Image source={...} className="absolute inset-0" />
+  <View className="gap-4">...</View>
+</Card>
+```
+
+## Example
+
+```tsx
+import { Button, Card } from '@/heroui';
+import { Ionicons } from '@expo/vector-icons';
+import { View } from 'react-native';
+
+export default function CardExample() {
+  return (
+    <Card>
+      <View className="gap-4">
+        <Card.Body className="mb-4">
+          <View className="gap-1 mb-2">
+            <Card.Title className="text-pink-500">$450</Card.Title>
+            <Card.Title>Living room Sofa • Collection 2025</Card.Title>
+          </View>
+          <Card.Description>
+            This sofa is perfect for modern tropical spaces, baroque inspired
+            spaces.
+          </Card.Description>
+        </Card.Body>
+        <Card.Footer className="gap-3">
+          <Button variant="primary">Buy now</Button>
+          <Button variant="ghost">
+            <Button.Label>Add to cart</Button.Label>
+            <Ionicons name="bag-outline" size={16} />
+          </Button>
+        </Card.Footer>
+      </View>
+    </Card>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/(home)/components/card.tsx>).
+
+## API Reference
+
+### Card
+
+| prop           | type                                                      | default     | description                                                                               |
+| -------------- | --------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| `children`     | `React.ReactNode`                                         | -           | Content to be rendered inside the card                                                    |
+| `variant`      | `'default' \| 'secondary' \| 'tertiary' \| 'transparent'` | `'default'` | Visual variant of the card surface                                                        |
+| `className`    | `string`                                                  | -           | Additional CSS classes to apply                                                           |
+| `animation`    | `"disable-all" \| undefined`                              | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children |
+| `...ViewProps` | `ViewProps`                                               | -           | All standard React Native View props are supported                                        |
+
+### Card.Header
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Children elements to be rendered inside the header |
+| `className`    | `string`          | -       | Additional CSS classes                             |
+| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported |
+
+### Card.Body
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Children elements to be rendered inside the body   |
+| `className`    | `string`          | -       | Additional CSS classes                             |
+| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported |
+
+### Card.Footer
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Children elements to be rendered inside the footer |
+| `className`    | `string`          | -       | Additional CSS classes                             |
+| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported |
+
+### Card.Title
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Children elements to be rendered as the title text |
+| `className`    | `string`          | -       | Additional CSS classes                             |
+| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |
+
+### Card.Description
+
+| prop           | type              | default | description                                              |
+| -------------- | ----------------- | ------- | -------------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Children elements to be rendered as the description text |
+| `className`    | `string`          | -       | Additional CSS classes                                   |
+| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported       |