@coze-arch/cli 0.0.10 → 0.0.11

package/lib/__templates__/expo/client/heroui/primitives/activity-indicator/activity-indicator.types.ts

@@ -0,0 +1,24 @@
+import type { SlottableViewProps, ViewRef } from '../../helpers/internal/types';
+
+/**
+ * Props for the activity indicator root component.
+ *
+ * @extends SlottableViewProps Inherits view props
+ */
+export interface RootProps extends SlottableViewProps {
+  /** Whether the activity indicator is loading */
+  isLoading?: boolean;
+}
+
+/** Reference type for the activity indicator root component */
+export type RootRef = ViewRef;
+
+/**
+ * Props for the activity indicator indicator component.
+ *
+ * @extends SlottableViewProps Inherits view props
+ */
+export interface IndicatorProps extends SlottableViewProps {}
+
+/** Reference type for the activity indicator indicator component */
+export type IndicatorRef = ViewRef;

package/lib/__templates__/expo/client/heroui/primitives/activity-indicator/index.ts

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

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

@@ -0,0 +1,124 @@
+import { createContext, forwardRef, useContext, useId } from 'react';
+import { Text as RNText, View } from 'react-native';
+import * as Slot from '../slot';
+import type {
+  ContentProps,
+  ContentRef,
+  DescriptionProps,
+  DescriptionRef,
+  IndicatorProps,
+  IndicatorRef,
+  RootContext,
+  RootProps,
+  RootRef,
+  TitleProps,
+  TitleRef,
+} from './alert.types';
+
+const AlertContext = createContext<(RootContext & { nativeID: string }) | null>(
+  null
+);
+
+/**
+ * Hook to access alert root context.
+ * Throws when used outside Alert.Root.
+ */
+function useRootContext(): RootContext & { nativeID: string } {
+  const context = useContext(AlertContext);
+  if (!context) {
+    throw new Error(
+      'Alert compound components cannot be rendered outside the Alert component'
+    );
+  }
+  return context;
+}
+
+// --------------------------------------------------
+
+const Root = forwardRef<RootRef, RootProps>(
+  ({ asChild, id, status = 'default', ...viewProps }, ref) => {
+    const generatedId = useId();
+    const nativeID = id != null ? String(id) : generatedId;
+
+    const Component = asChild ? Slot.View : View;
+
+    return (
+      <AlertContext.Provider value={{ nativeID, status }}>
+        <Component
+          ref={ref}
+          role="alert"
+          aria-labelledby={`${nativeID}_label`}
+          aria-describedby={`${nativeID}_desc`}
+          nativeID={nativeID}
+          {...viewProps}
+        />
+      </AlertContext.Provider>
+    );
+  }
+);
+
+Root.displayName = 'HeroUINative.Primitive.Alert.Root';
+
+// --------------------------------------------------
+
+const Indicator = forwardRef<IndicatorRef, IndicatorProps>(
+  ({ asChild, ...props }, ref) => {
+    const Component = asChild ? Slot.View : View;
+
+    return (
+      <Component ref={ref} role="presentation" aria-hidden={true} {...props} />
+    );
+  }
+);
+
+Indicator.displayName = 'HeroUINative.Primitive.Alert.Indicator';
+
+// --------------------------------------------------
+
+const Content = forwardRef<ContentRef, ContentProps>(
+  ({ asChild, ...props }, ref) => {
+    const Component = asChild ? Slot.View : View;
+
+    return <Component ref={ref} {...props} />;
+  }
+);
+
+Content.displayName = 'HeroUINative.Primitive.Alert.Content';
+
+// --------------------------------------------------
+
+const Title = forwardRef<TitleRef, TitleProps>(({ asChild, ...props }, ref) => {
+  const { nativeID } = useRootContext();
+
+  const Component = asChild ? Slot.Text : RNText;
+
+  return (
+    <Component
+      ref={ref}
+      role="heading"
+      aria-level={2}
+      nativeID={`${nativeID}_label`}
+      {...props}
+    />
+  );
+});
+
+Title.displayName = 'HeroUINative.Primitive.Alert.Title';
+
+// --------------------------------------------------
+
+const Description = forwardRef<DescriptionRef, DescriptionProps>(
+  ({ asChild, ...props }, ref) => {
+    const { nativeID } = useRootContext();
+
+    const Component = asChild ? Slot.Text : RNText;
+
+    return <Component ref={ref} nativeID={`${nativeID}_desc`} {...props} />;
+  }
+);
+
+Description.displayName = 'HeroUINative.Primitive.Alert.Description';
+
+// --------------------------------------------------
+
+export { Content, Description, Indicator, Root, Title, useRootContext };

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

@@ -0,0 +1,87 @@
+import type {
+  SlottableTextProps,
+  SlottableViewProps,
+  TextRef,
+  ViewRef,
+} from '../../helpers/internal/types';
+
+/**
+ * Alert status type controlling the visual treatment and icon displayed.
+ */
+export type AlertStatus =
+  | 'default'
+  | 'accent'
+  | 'success'
+  | 'warning'
+  | 'danger';
+
+/**
+ * Context for the alert root component.
+ * Provides unique identifier for accessibility labelling and the current status.
+ */
+export type RootContext = {
+  /** Unique identifier for the alert, used for aria-labelledby and aria-describedby */
+  nativeID: string;
+  /** Current alert status for sub-component styling */
+  status: AlertStatus;
+};
+
+/**
+ * Props for the Alert root component.
+ * Extends SlottableViewProps to support the asChild pattern.
+ *
+ * @extends SlottableViewProps Inherits view props for slot-based composition
+ */
+export type RootProps = SlottableViewProps & {
+  /** Unique identifier for the alert. Auto-generated when not provided. */
+  id?: string | number;
+  /**
+   * The status of the alert, controlling its icon and color treatment.
+   *
+   * @default "default"
+   */
+  status?: AlertStatus;
+};
+
+/**
+ * Props for the Alert indicator component.
+ * Visual indicator (e.g., icon, status dot) - decorative, hidden from assistive tech.
+ *
+ * @extends SlottableViewProps Inherits view props for slot-based composition
+ */
+export type IndicatorProps = SlottableViewProps;
+
+/**
+ * Props for the Alert content wrapper component.
+ * Container for title and description, provides layout structure.
+ *
+ * @extends SlottableViewProps Inherits view props for slot-based composition
+ */
+export type ContentProps = SlottableViewProps;
+
+/**
+ * Props for the Alert title component.
+ * Primary heading of the alert, used for aria-labelledby association.
+ *
+ * @extends SlottableTextProps Inherits text props for slot-based composition
+ */
+export type TitleProps = SlottableTextProps;
+
+/**
+ * Props for the Alert description component.
+ * Secondary text of the alert, used for aria-describedby association.
+ *
+ * @extends SlottableTextProps Inherits text props for slot-based composition
+ */
+export type DescriptionProps = SlottableTextProps;
+
+/** Reference type for the Alert root component */
+export type RootRef = ViewRef;
+/** Reference type for the Alert indicator component */
+export type IndicatorRef = ViewRef;
+/** Reference type for the Alert content component */
+export type ContentRef = ViewRef;
+/** Reference type for the Alert title component */
+export type TitleRef = TextRef;
+/** Reference type for the Alert description component */
+export type DescriptionRef = TextRef;

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

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

package/lib/__templates__/expo/client/heroui/primitives/avatar/avatar.tsx

@@ -0,0 +1,171 @@
+import * as React from 'react';
+import { createContext, forwardRef, useEffect, useMemo, useState } from 'react';
+import {
+  type ImageErrorEventData,
+  type ImageLoadEvent,
+  type NativeSyntheticEvent,
+  Image as RNImage,
+  View,
+} from 'react-native';
+import * as Slot from '../slot';
+import type {
+  AvatarStatus,
+  FallbackProps,
+  FallbackRef,
+  ImageProps,
+  ImageRef,
+  RootProps,
+  RootRef,
+} from './avatar.types';
+import { isSameSource, isValidSource } from './avatar.utils';
+
+interface IRootContext extends RootProps {
+  status: AvatarStatus;
+  setStatus: (status: AvatarStatus) => void;
+}
+
+const RootContext = createContext<IRootContext | null>(null);
+
+export function useRootContext() {
+  const context = React.useContext(RootContext);
+  if (!context) {
+    throw new Error(
+      'Avatar compound components cannot be rendered outside the Avatar component'
+    );
+  }
+  return context;
+}
+
+// --------------------------------------------------
+
+const Root = forwardRef<RootRef, RootProps>(
+  ({ asChild, alt, ...viewProps }, ref) => {
+    const [status, setStatus] = useState<AvatarStatus>('error');
+
+    const Component = asChild ? Slot.View : View;
+
+    const value = useMemo(
+      () => ({
+        alt,
+        status,
+        setStatus,
+      }),
+      [alt, status, setStatus]
+    );
+
+    return (
+      <RootContext.Provider value={value}>
+        <Component ref={ref} {...viewProps} />
+      </RootContext.Provider>
+    );
+  }
+);
+
+Root.displayName = 'HeroUINative.Primitive.Avatar.Root';
+
+// --------------------------------------------------
+
+const Image = forwardRef<ImageRef, ImageProps>(
+  (
+    {
+      asChild,
+      onLoad: onLoadProps,
+      onError: onErrorProps,
+      onLoadingStatusChange,
+      ...props
+    },
+    ref
+  ) => {
+    const { alt, setStatus, status } = useRootContext();
+
+    // Use ref to track the previous source value for comparison
+    const previousSourceRef = React.useRef<ImageProps['source'] | undefined>(
+      undefined
+    );
+
+    useEffect(() => {
+      const currentSource = props?.source;
+      const previousSource = previousSourceRef.current;
+
+      // Only reset status if the source actually changed (not just reference)
+      const sourceChanged = !isSameSource(currentSource, previousSource);
+
+      if (sourceChanged) {
+        // Update the ref to track the new source
+        previousSourceRef.current = currentSource;
+
+        if (isValidSource(currentSource)) {
+          setStatus('loading');
+        } else {
+          setStatus('error');
+        }
+      }
+
+      // Cleanup: only reset to error if component unmounts or source becomes invalid
+      return () => {
+        // Only reset if source is no longer valid or component is unmounting
+        if (!isValidSource(currentSource)) {
+          setStatus('error');
+        }
+      };
+    }, [props?.source, setStatus]);
+
+    const onLoad = React.useCallback(
+      (e: ImageLoadEvent) => {
+        setStatus('loaded');
+        onLoadingStatusChange?.('loaded');
+        onLoadProps?.(e);
+      },
+      [onLoadProps, setStatus, onLoadingStatusChange]
+    );
+
+    const onError = React.useCallback(
+      (e: NativeSyntheticEvent<ImageErrorEventData>) => {
+        setStatus('error');
+        onLoadingStatusChange?.('error');
+        onErrorProps?.(e);
+      },
+      [onErrorProps, setStatus, onLoadingStatusChange]
+    );
+
+    const Component = asChild ? Slot.Image : RNImage;
+
+    if (status === 'error') {
+      return null;
+    }
+
+    return (
+      <Component
+        ref={ref}
+        alt={alt}
+        onLoad={onLoad}
+        onError={onError}
+        {...props}
+      />
+    );
+  }
+);
+
+Image.displayName = 'HeroUINative.Primitive.Avatar.Image';
+
+// --------------------------------------------------
+
+const Fallback = forwardRef<FallbackRef, FallbackProps>(
+  ({ asChild, ...props }, ref) => {
+    const { alt, status } = useRootContext();
+
+    if (status !== 'error') {
+      return null;
+    }
+
+    const Component = asChild ? Slot.View : View;
+
+    return <Component ref={ref} role={'img'} aria-label={alt} {...props} />;
+  }
+);
+
+Fallback.displayName = 'HeroUINative.Primitive.Avatar.Fallback';
+
+// --------------------------------------------------
+
+export { Fallback, Image, Root };

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

@@ -0,0 +1,62 @@
+import type { Image, ImageProps as RNImageProps } from 'react-native';
+import type {
+  ComponentPropsWithAsChild,
+  SlottableViewProps,
+  ViewRef,
+} from '../../helpers/internal/types';
+
+/**
+ * Represents the loading state of an avatar image.
+ * - 'loading': Image is currently being loaded
+ * - 'loaded': Image has successfully loaded
+ * - 'error': Image failed to load or source is invalid
+ */
+type AvatarStatus = 'loading' | 'loaded' | 'error';
+
+/**
+ * Props for the Avatar root component.
+ * Extends SlottableViewProps to support the asChild pattern.
+ */
+type RootProps = SlottableViewProps & {
+  /** Alternative text description for the avatar, used for accessibility */
+  alt: string;
+};
+
+/**
+ * Props for the Avatar image component.
+ * Extends React Native Image props with additional avatar-specific functionality.
+ */
+type ImageProps = Omit<
+  ComponentPropsWithAsChild<typeof Image>,
+  'alt' | 'source'
+> & {
+  /** Optional child elements to render within the image component */
+  children?: React.ReactNode;
+  /** Source of the image */
+  source: RNImageProps['source'];
+  /** Callback fired when the loading status changes */
+  onLoadingStatusChange?: (status: AvatarStatus) => void;
+};
+
+/**
+ * Props for the Avatar fallback component.
+ * Displayed when the image fails to load or is in error state.
+ */
+type FallbackProps = SlottableViewProps;
+
+/** Reference type for the Avatar root component */
+type RootRef = ViewRef;
+/** Reference type for the Avatar image component */
+type ImageRef = React.ComponentRef<typeof Image>;
+/** Reference type for the Avatar fallback component */
+type FallbackRef = ViewRef;
+
+export type {
+  AvatarStatus,
+  FallbackProps,
+  FallbackRef,
+  ImageProps,
+  ImageRef,
+  RootProps,
+  RootRef,
+};

package/lib/__templates__/expo/client/heroui/primitives/avatar/avatar.utils.ts

@@ -0,0 +1,102 @@
+import type { ImageSourcePropType } from 'react-native';
+
+/**
+ * Validates whether an image source is valid and can be loaded.
+ *
+ * @param source - The image source to validate. Can be a require() statement,
+ *                 URI object, or array of URI objects.
+ * @returns `true` if the source is valid and contains loadable content, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * // Valid sources
+ * isValidSource(require('./avatar.png')); // true (returns a number)
+ * isValidSource({ uri: 'https://example.com/avatar.jpg' }); // true
+ * isValidSource([{ uri: 'https://example.com/avatar.jpg' }]); // true
+ *
+ * // Invalid sources
+ * isValidSource(undefined); // false
+ * isValidSource({ uri: '' }); // false
+ * isValidSource([{ uri: '' }, { uri: null }]); // false
+ * ```
+ */
+export function isValidSource(source?: ImageSourcePropType) {
+  if (!source) {
+    return false;
+  }
+  // Using require() for the source returns a number
+  if (typeof source === 'number') {
+    return true;
+  }
+
+  if (Array.isArray(source)) {
+    return source.some((s) => !!s.uri);
+  }
+
+  return !!source.uri;
+}
+
+/**
+ * Compares two image sources to determine if they represent the same image.
+ * Performs deep comparison of source values, not just reference equality.
+ *
+ * @param source1 - First image source to compare
+ * @param source2 - Second image source to compare
+ * @returns `true` if both sources represent the same image, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * // Same sources (different object references)
+ * isSameSource({ uri: 'https://example.com/img.jpg' }, { uri: 'https://example.com/img.jpg' }); // true
+ *
+ * // Different sources
+ * isSameSource({ uri: 'https://example.com/img1.jpg' }, { uri: 'https://example.com/img2.jpg' }); // false
+ *
+ * // Same require() values
+ * isSameSource(require('./img.png'), require('./img.png')); // true (if same number)
+ * ```
+ */
+export function isSameSource(
+  source1?: ImageSourcePropType,
+  source2?: ImageSourcePropType
+): boolean {
+  // Both undefined/null
+  if (!source1 && !source2) {
+    return true;
+  }
+
+  // One is undefined/null, the other is not
+  if (!source1 || !source2) {
+    return false;
+  }
+
+  // Both are numbers (require() statements)
+  if (typeof source1 === 'number' && typeof source2 === 'number') {
+    return source1 === source2;
+  }
+
+  // One is a number, the other is not
+  if (typeof source1 === 'number' || typeof source2 === 'number') {
+    return false;
+  }
+
+  // Both are arrays
+  if (Array.isArray(source1) && Array.isArray(source2)) {
+    if (source1.length !== source2.length) {
+      return false;
+    }
+    // Compare each element's URI
+    return source1.every((s1, index) => {
+      const s2 = source2[index];
+      return s1?.uri === s2?.uri;
+    });
+  }
+
+  // One is an array, the other is not
+  if (Array.isArray(source1) || Array.isArray(source2)) {
+    return false;
+  }
+
+  // Both are objects - compare URI values
+  return source1.uri === source2.uri;
+}

package/lib/__templates__/expo/client/heroui/primitives/avatar/index.ts

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