@coze-arch/cli 0.0.10 → 0.0.11

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

@@ -0,0 +1,263 @@
+# Alert
+
+Displays important messages and notifications to users with status indicators.
+
+## Import
+
+```tsx
+import { Alert } from '@/heroui';
+```
+
+## Anatomy
+
+```tsx
+<Alert>
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>...</Alert.Title>
+    <Alert.Description>...</Alert.Description>
+  </Alert.Content>
+</Alert>
+```
+
+- **Alert**: Main container with `role="alert"` and status-based styling. Provides status context to sub-components via a primitive context.
+- **Alert.Indicator**: Renders a status-appropriate icon by default. Accepts custom children to override the default icon. Supports `iconProps` for customising size and color.
+- **Alert.Content**: Wrapper for the title and description. Provides layout structure for text content.
+- **Alert.Title**: Heading text with status-based color. Connected to root via `aria-labelledby`.
+- **Alert.Description**: Body text rendered with muted color. Connected to root via `aria-describedby`.
+
+## Usage
+
+### Basic Usage
+
+The Alert component uses compound parts to display a notification with an icon, title, and description.
+
+```tsx
+<Alert>
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>New features available</Alert.Title>
+    <Alert.Description>
+      Check out our latest updates including dark mode support and improved
+      accessibility features.
+    </Alert.Description>
+  </Alert.Content>
+</Alert>
+```
+
+### Status Variants
+
+Set the `status` prop to control the icon and title color. Available statuses are `default`, `accent`, `success`, `warning`, and `danger`.
+
+```tsx
+<Alert status="success">
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>Success</Alert.Title>
+    <Alert.Description>...</Alert.Description>
+  </Alert.Content>
+</Alert>
+
+<Alert status="warning">
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>Scheduled maintenance</Alert.Title>
+    <Alert.Description>...</Alert.Description>
+  </Alert.Content>
+</Alert>
+
+<Alert status="danger">
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>Unable to connect</Alert.Title>
+    <Alert.Description>...</Alert.Description>
+  </Alert.Content>
+</Alert>
+```
+
+### Title Only
+
+Omit `Alert.Description` for a compact single-line alert.
+
+```tsx
+<Alert status="success" className="items-center">
+  <Alert.Indicator className="pt-0" />
+  <Alert.Content>
+    <Alert.Title>Profile updated successfully</Alert.Title>
+  </Alert.Content>
+</Alert>
+```
+
+### With Action Buttons
+
+Place additional elements like buttons alongside the content.
+
+```tsx
+<Alert status="accent">
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>Update available</Alert.Title>
+    <Alert.Description>
+      A new version of the application is available.
+    </Alert.Description>
+  </Alert.Content>
+  <Button size="sm" variant="primary">
+    Refresh
+  </Button>
+</Alert>
+```
+
+### Custom Indicator
+
+Replace the default status icon by passing custom children to `Alert.Indicator`.
+
+```tsx
+<Alert status="accent">
+  <Alert.Indicator>
+    <Spinner>
+      <Spinner.Indicator iconProps={{ width: 20, height: 20 }} />
+    </Spinner>
+  </Alert.Indicator>
+  <Alert.Content>
+    <Alert.Title>Processing your request</Alert.Title>
+    <Alert.Description>Please wait while we sync your data.</Alert.Description>
+  </Alert.Content>
+</Alert>
+```
+
+### Custom Styling
+
+Apply custom styles using the `className` prop on the root and compound parts.
+
+```tsx
+<Alert className="bg-accent/10 rounded-xl">
+  <Alert.Indicator className="pt-1" />
+  <Alert.Content className="gap-1">
+    <Alert.Title className="text-lg">...</Alert.Title>
+    <Alert.Description className="text-base">...</Alert.Description>
+  </Alert.Content>
+</Alert>
+```
+
+## Example
+
+```tsx
+import { Alert, Button, CloseButton } from '@/heroui';
+import { View } from 'react-native';
+
+export default function AlertExample() {
+  return (
+    <View className="w-full gap-4">
+      <Alert status="accent">
+        <Alert.Indicator />
+        <Alert.Content>
+          <Alert.Title>Update available</Alert.Title>
+          <Alert.Description>
+            A new version of the application is available. Please refresh to get
+            the latest features and bug fixes.
+          </Alert.Description>
+        </Alert.Content>
+        <Button size="sm" variant="primary">
+          Refresh
+        </Button>
+      </Alert>
+
+      <Alert status="danger">
+        <Alert.Indicator />
+        <Alert.Content>
+          <Alert.Title>Unable to connect to server</Alert.Title>
+          <Alert.Description>
+            Unable to connect to the server. Check your internet connection and
+            try again.
+          </Alert.Description>
+        </Alert.Content>
+        <Button size="sm" variant="danger">
+          Retry
+        </Button>
+      </Alert>
+
+      <Alert status="success" className="items-center">
+        <Alert.Indicator className="pt-0" />
+        <Alert.Content>
+          <Alert.Title>Profile updated successfully</Alert.Title>
+        </Alert.Content>
+        <CloseButton />
+      </Alert>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/(home)/components/alert.tsx>).
+
+## API Reference
+
+### Alert
+
+| prop           | type                                                          | default     | description                                                       |
+| -------------- | ------------------------------------------------------------- | ----------- | ----------------------------------------------------------------- |
+| `children`     | `React.ReactNode`                                             | -           | Children elements to render inside the alert                      |
+| `status`       | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Status controlling the icon and color treatment                   |
+| `id`           | `string \| number`                                            | -           | Unique identifier for the alert. Auto-generated when not provided |
+| `className`    | `string`                                                      | -           | Additional CSS classes                                            |
+| `style`        | `ViewStyle`                                                   | -           | Additional styles applied to the root container                   |
+| `...ViewProps` | `ViewProps`                                                   | -           | All standard React Native View props are supported                |
+
+### Alert.Indicator
+
+| prop           | type              | default | description                                                        |
+| -------------- | ----------------- | ------- | ------------------------------------------------------------------ |
+| `children`     | `React.ReactNode` | -       | Custom children to render instead of the default status icon       |
+| `className`    | `string`          | -       | Additional CSS classes                                             |
+| `iconProps`    | `AlertIconProps`  | -       | Props passed to the default status icon (size and color overrides) |
+| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported                 |
+
+#### AlertIconProps
+
+| prop    | type     | default      | description            |
+| ------- | -------- | ------------ | ---------------------- |
+| `size`  | `number` | `18`         | Icon size in pixels    |
+| `color` | `string` | status color | Icon color as a string |
+
+### Alert.Content
+
+| prop           | type              | default | description                                                     |
+| -------------- | ----------------- | ------- | --------------------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Children elements (typically Alert.Title and Alert.Description) |
+| `className`    | `string`          | -       | Additional CSS classes                                          |
+| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported              |
+
+### Alert.Title
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Title text content                                 |
+| `className`    | `string`          | -       | Additional CSS classes                             |
+| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |
+
+### Alert.Description
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Description text content                           |
+| `className`    | `string`          | -       | Additional CSS classes                             |
+| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |
+
+## Hooks
+
+### useAlert
+
+Hook to access the alert root context. Must be used within an `Alert` component.
+
+```tsx
+import { useAlert } from '@/heroui';
+
+const { status, nativeID } = useAlert();
+```
+
+#### Returns
+
+| property   | type                                                          | description                                                  |
+| ---------- | ------------------------------------------------------------- | ------------------------------------------------------------ |
+| `status`   | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | Current alert status for sub-component styling               |
+| `nativeID` | `string`                                                      | Unique identifier used for accessibility and ARIA attributes |

package/lib/__templates__/expo/client/heroui/components/alert/alert.styles.ts

@@ -0,0 +1,65 @@
+import { StyleSheet } from 'react-native';
+import { tv } from 'tailwind-variants';
+import { combineStyles } from '../../helpers/internal/utils';
+
+/**
+ * Root style definition for the Alert container
+ */
+const root = tv({
+  base: 'p-3 flex-row gap-3 rounded-3xl bg-surface shadow-surface',
+});
+
+/**
+ * Indicator style definition for the status icon container
+ */
+const indicator = tv({
+  base: 'pt-[3.5px]',
+});
+
+/**
+ * Content style definition for the title/description wrapper
+ */
+const content = tv({
+  base: 'flex-1',
+});
+
+/**
+ * Title style definition with status-based color variants
+ */
+const title = tv({
+  base: 'text-base font-medium',
+  variants: {
+    status: {
+      default: 'text-foreground',
+      accent: 'text-accent',
+      success: 'text-success',
+      warning: 'text-warning',
+      danger: 'text-danger',
+    },
+  },
+  defaultVariants: {
+    status: 'default',
+  },
+});
+
+/**
+ * Description style definition
+ */
+const description = tv({
+  base: 'text-sm text-muted',
+});
+
+export const alertClassNames = combineStyles({
+  root,
+  indicator,
+  content,
+  title,
+  description,
+});
+
+/** StyleSheet for native-only properties (internal use only, NOT exported from index.ts) */
+export const alertStyleSheet = StyleSheet.create({
+  root: {
+    borderCurve: 'continuous',
+  },
+});

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

@@ -0,0 +1,181 @@
+import { forwardRef } from 'react';
+import { HeroText } from '../../helpers/internal/components';
+import * as AlertPrimitives from '../../primitives/alert';
+import type * as AlertPrimitiveTypes from '../../primitives/alert/alert.types';
+import { DEFAULT_ICON_SIZE, DISPLAY_NAME } from './alert.constants';
+import { useStatusColor } from './alert.hooks';
+import { alertClassNames, alertStyleSheet } from './alert.styles';
+import type {
+  AlertContentProps,
+  AlertDescriptionProps,
+  AlertIconProps,
+  AlertIndicatorProps,
+  AlertRootProps,
+  AlertTitleProps,
+} from './alert.types';
+import { getStatusIcon } from './alert.utils';
+
+const useAlert = AlertPrimitives.useRootContext;
+
+// --------------------------------------------------
+
+const AlertRoot = forwardRef<AlertPrimitiveTypes.RootRef, AlertRootProps>(
+  (props, ref) => {
+    const {
+      children,
+      status = 'default',
+      className,
+      style,
+      ...restProps
+    } = props;
+
+    const rootClassName = alertClassNames.root({ className });
+
+    return (
+      <AlertPrimitives.Root
+        ref={ref}
+        status={status}
+        className={rootClassName}
+        style={[alertStyleSheet.root, style]}
+        {...restProps}
+      >
+        {children}
+      </AlertPrimitives.Root>
+    );
+  }
+);
+
+// --------------------------------------------------
+
+const AlertIndicator = forwardRef<
+  AlertPrimitiveTypes.IndicatorRef,
+  AlertIndicatorProps
+>((props, ref) => {
+  const { children, className, iconProps, ...restProps } = props;
+
+  const { status } = useAlert();
+  const statusColor = useStatusColor(status);
+
+  const indicatorClassName = alertClassNames.indicator({ className });
+
+  /** Merge default color with user-provided iconProps */
+  const resolvedIconProps: AlertIconProps = {
+    size: iconProps?.size ?? DEFAULT_ICON_SIZE,
+    color: iconProps?.color ?? statusColor,
+  };
+
+  return (
+    <AlertPrimitives.Indicator
+      ref={ref}
+      className={indicatorClassName}
+      {...restProps}
+    >
+      {children ?? getStatusIcon(status, resolvedIconProps)}
+    </AlertPrimitives.Indicator>
+  );
+});
+
+// --------------------------------------------------
+
+const AlertContent = forwardRef<
+  AlertPrimitiveTypes.ContentRef,
+  AlertContentProps
+>((props, ref) => {
+  const { children, className, ...restProps } = props;
+
+  const contentClassName = alertClassNames.content({ className });
+
+  return (
+    <AlertPrimitives.Content
+      ref={ref}
+      className={contentClassName}
+      {...restProps}
+    >
+      {children}
+    </AlertPrimitives.Content>
+  );
+});
+
+// --------------------------------------------------
+
+const AlertTitle = forwardRef<AlertPrimitiveTypes.TitleRef, AlertTitleProps>(
+  (props, ref) => {
+    const { children, className, ...restProps } = props;
+
+    const { status } = useAlert();
+
+    const titleClassName = alertClassNames.title({ status, className });
+
+    return (
+      <AlertPrimitives.Title asChild {...restProps}>
+        <HeroText ref={ref} className={titleClassName}>
+          {children}
+        </HeroText>
+      </AlertPrimitives.Title>
+    );
+  }
+);
+
+// --------------------------------------------------
+
+const AlertDescription = forwardRef<
+  AlertPrimitiveTypes.DescriptionRef,
+  AlertDescriptionProps
+>((props, ref) => {
+  const { children, className, ...restProps } = props;
+
+  const descriptionClassName = alertClassNames.description({ className });
+
+  return (
+    <AlertPrimitives.Description asChild {...restProps}>
+      <HeroText ref={ref} className={descriptionClassName}>
+        {children}
+      </HeroText>
+    </AlertPrimitives.Description>
+  );
+});
+
+// --------------------------------------------------
+
+AlertRoot.displayName = DISPLAY_NAME.ROOT;
+AlertIndicator.displayName = DISPLAY_NAME.INDICATOR;
+AlertContent.displayName = DISPLAY_NAME.CONTENT;
+AlertTitle.displayName = DISPLAY_NAME.TITLE;
+AlertDescription.displayName = DISPLAY_NAME.DESCRIPTION;
+
+/**
+ * Compound Alert component with sub-components
+ *
+ * @component Alert - Main container that renders a styled alert with role="alert"
+ * and configurable status (default, accent, success, warning, danger).
+ * Status flows to sub-components via primitive context.
+ *
+ * @component Alert.Indicator - Renders a status-appropriate icon by default.
+ * Accepts custom children to override the default icon.
+ * Supports iconProps (size, color) for customising the default icon.
+ *
+ * @component Alert.Content - Flex-1 wrapper for Alert.Title and Alert.Description.
+ *
+ * @component Alert.Title - Heading text with status-based color (success, warning,
+ * danger apply their respective semantic color; default and accent use foreground).
+ *
+ * @component Alert.Description - Body text rendered with muted color.
+ *
+ * Props flow from Alert to sub-components via context (status, nativeID).
+ * Title and Description are connected to root via aria-labelledby / aria-describedby.
+ *
+ * @see Full documentation: https://v3.heroui.com/docs/native/components/alert
+ */
+const CompoundAlert = Object.assign(AlertRoot, {
+  /** @optional Status icon rendered as the leading visual element */
+  Indicator: AlertIndicator,
+  /** @optional Wrapper for title and description content */
+  Content: AlertContent,
+  /** @optional Primary heading with status-aware text color */
+  Title: AlertTitle,
+  /** @optional Secondary description with muted text color */
+  Description: AlertDescription,
+});
+
+export { useAlert };
+export default CompoundAlert;

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

@@ -0,0 +1,99 @@
+import type * as AlertPrimitiveTypes from '../../primitives/alert/alert.types';
+
+/**
+ * Props for the icon rendered inside the alert indicator.
+ */
+export interface AlertIconProps {
+  /**
+   * Icon size in pixels
+   *
+   * @default 20
+   */
+  size?: number;
+  /**
+   * Icon color as a CSS color string
+   */
+  color?: string;
+}
+
+/**
+ * Props for the Alert root component.
+ * Renders a styled alert container with status-based visual treatment.
+ */
+export interface AlertRootProps extends AlertPrimitiveTypes.RootProps {
+  /**
+   * Children elements to render inside the alert
+   */
+  children?: React.ReactNode;
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+}
+
+/**
+ * Props for the Alert.Indicator component.
+ * Renders a status icon by default when no children are provided.
+ */
+export interface AlertIndicatorProps
+  extends AlertPrimitiveTypes.IndicatorProps {
+  /**
+   * Custom children to render instead of the default status icon
+   */
+  children?: React.ReactNode;
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+  /**
+   * Props passed to the default status icon (size and color overrides)
+   */
+  iconProps?: AlertIconProps;
+}
+
+/**
+ * Props for the Alert.Content component.
+ * Container for the title and description.
+ */
+export interface AlertContentProps extends AlertPrimitiveTypes.ContentProps {
+  /**
+   * Children elements (typically Alert.Title and Alert.Description)
+   */
+  children?: React.ReactNode;
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+}
+
+/**
+ * Props for the Alert.Title component.
+ * Renders the alert heading with status-based text color.
+ */
+export interface AlertTitleProps
+  extends Omit<AlertPrimitiveTypes.TitleProps, 'asChild'> {
+  /**
+   * Title text content
+   */
+  children?: React.ReactNode;
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+}
+
+/**
+ * Props for the Alert.Description component.
+ * Renders the alert body text with muted styling.
+ */
+export interface AlertDescriptionProps
+  extends Omit<AlertPrimitiveTypes.DescriptionProps, 'asChild'> {
+  /**
+   * Description text content
+   */
+  children?: React.ReactNode;
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+}

package/lib/__templates__/expo/client/heroui/components/alert/alert.utils.tsx

@@ -0,0 +1,25 @@
+import type { AlertStatus } from '../../primitives/alert/alert.types';
+import { DEFAULT_ICON_SIZE } from './alert.constants';
+import type { AlertIconProps } from './alert.types';
+import { DefaultIcon } from './default-icon';
+import { SuccessIcon } from './success-icon';
+import { WarningIcon } from './warning-icon';
+
+/**
+ * Resolves the default icon component based on the current alert status.
+ */
+export function getStatusIcon(
+  status: AlertStatus,
+  iconProps: AlertIconProps
+): React.ReactElement {
+  const { size = DEFAULT_ICON_SIZE, color } = iconProps;
+
+  switch (status) {
+    case 'success':
+      return <SuccessIcon size={size} color={color} />;
+    case 'warning':
+      return <WarningIcon size={size} color={color} />;
+    default:
+      return <DefaultIcon size={size} color={color} />;
+  }
+}

package/lib/__templates__/expo/client/heroui/components/alert/default-icon.tsx

@@ -0,0 +1,28 @@
+import React from 'react';
+import Svg, { Path } from 'react-native-svg';
+import type { AlertIconProps } from './alert.types';
+
+/**
+ * Default info circle icon for the Alert indicator.
+ * Used for "default", "accent", and "danger" status values.
+ */
+export const DefaultIcon: React.FC<AlertIconProps> = ({ size = 20, color }) => {
+  return (
+    <Svg
+      width={size}
+      height={size}
+      viewBox="0 0 16 16"
+      fill={color}
+      accessibilityElementsHidden={true}
+      importantForAccessibility="no-hide-descendants"
+    >
+      <Path
+        d="M8 13.5a5.5 5.5 0 1 0 0-11a5.5 5.5 0 0 0 0 11M8 15A7 7 0 1 0 8 1a7 7 0 0 0 0 14m1-9.5a1 1 0 1 1-2 0a1 1 0 0 1 2 0m-.25 3a.75.75 0 0 0-1.5 0V11a.75.75 0 0 0 1.5 0z"
+        fillRule="evenodd"
+        clipRule="evenodd"
+      />
+    </Svg>
+  );
+};
+
+DefaultIcon.displayName = 'HeroUINative.Alert.DefaultIcon';

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

@@ -0,0 +1,15 @@
+// Component exports
+export { default as Alert, useAlert } from './alert';
+
+// ClassNames export for external reuse
+export { alertClassNames } from './alert.styles';
+
+// Type exports (named exports for better tree-shaking)
+export type {
+  AlertContentProps,
+  AlertDescriptionProps,
+  AlertIconProps,
+  AlertIndicatorProps,
+  AlertRootProps,
+  AlertTitleProps,
+} from './alert.types';