@erquhart/heroui-native 1.0.0-beta.10.1

package/src/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/src/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/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/src/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/src/primitives/avatar/index.ts

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

package/src/primitives/bottom-sheet/bottom-sheet.tsx

@@ -0,0 +1,246 @@
+import { createContext, forwardRef, useContext, useId } from 'react';
+import {
+  type GestureResponderEvent,
+  Pressable,
+  Text,
+  View,
+} from 'react-native';
+import { useControllableState } from '../../helpers/hooks';
+import { Portal as PortalPrimitive } from '../portal';
+import * as Slot from '../slot';
+import type {
+  CloseProps,
+  CloseRef,
+  ContentProps,
+  ContentRef,
+  DescriptionProps,
+  DescriptionRef,
+  OverlayProps,
+  OverlayRef,
+  PortalProps,
+  RootContext,
+  RootProps,
+  RootRef,
+  TitleProps,
+  TitleRef,
+  TriggerProps,
+  TriggerRef,
+} from './bottom-sheet.types';
+
+const BottomSheetContext = createContext<
+  (RootContext & { nativeID: string }) | null
+>(null);
+
+const Root = forwardRef<RootRef, RootProps>(
+  (
+    {
+      asChild,
+      isOpen: isOpenProp,
+      isDefaultOpen,
+      onOpenChange: onOpenChangeProp,
+      ...viewProps
+    },
+    ref
+  ) => {
+    const [isOpen = false, onOpenChange] = useControllableState({
+      prop: isOpenProp,
+      defaultProp: isDefaultOpen,
+      onChange: onOpenChangeProp,
+    });
+
+    const nativeID = useId();
+
+    const Component = asChild ? Slot.View : View;
+
+    return (
+      <BottomSheetContext.Provider
+        value={{
+          isOpen,
+          onOpenChange,
+          nativeID,
+        }}
+      >
+        <Component ref={ref} {...viewProps} />
+      </BottomSheetContext.Provider>
+    );
+  }
+);
+
+function useRootContext() {
+  const context = useContext(BottomSheetContext);
+  if (!context) {
+    throw new Error(
+      'BottomSheet compound components cannot be rendered outside the BottomSheet component'
+    );
+  }
+  return context;
+}
+
+Root.displayName = 'HeroUINative.Primitive.BottomSheet.Root';
+
+// --------------------------------------------------
+
+const Trigger = forwardRef<TriggerRef, TriggerProps>(
+  ({ asChild, onPress: onPressProp, disabled = false, ...props }, ref) => {
+    const { isOpen, onOpenChange } = useRootContext();
+
+    function onPress(ev: GestureResponderEvent) {
+      if (disabled) return;
+      const newValue = !isOpen;
+      onOpenChange(newValue);
+      onPressProp?.(ev);
+    }
+
+    const Component = asChild ? Slot.Pressable : Pressable;
+    return (
+      <Component
+        ref={ref}
+        aria-disabled={disabled ?? undefined}
+        role="button"
+        onPress={onPress}
+        disabled={disabled ?? undefined}
+        {...props}
+      />
+    );
+  }
+);
+
+Trigger.displayName = 'HeroUINative.Primitive.BottomSheet.Trigger';
+
+// --------------------------------------------------
+
+/**
+ * @warning when using a custom `<PortalHost />`, you might have to adjust the Content's offset to account for nav elements like headers.
+ */
+function Portal({ hostName, children }: PortalProps) {
+  const value = useRootContext();
+
+  if (!value.isOpen) {
+    return null;
+  }
+
+  return (
+    <PortalPrimitive hostName={hostName} name={`${value.nativeID}_portal`}>
+      <BottomSheetContext.Provider value={value}>
+        {children}
+      </BottomSheetContext.Provider>
+    </PortalPrimitive>
+  );
+}
+
+// --------------------------------------------------
+
+const Overlay = forwardRef<OverlayRef, OverlayProps>(
+  ({ asChild, isCloseOnPress = true, onPress: OnPressProp, ...props }, ref) => {
+    const { isOpen, onOpenChange } = useRootContext();
+
+    function onPress(ev: GestureResponderEvent) {
+      if (isCloseOnPress) {
+        onOpenChange(!isOpen);
+      }
+      OnPressProp?.(ev);
+    }
+
+    if (!isOpen) {
+      return null;
+    }
+
+    const Component = asChild ? Slot.Pressable : Pressable;
+    return <Component ref={ref} onPress={onPress} {...props} />;
+  }
+);
+
+Overlay.displayName = 'HeroUINative.Primitive.BottomSheet.Overlay';
+
+// --------------------------------------------------
+
+const Content = forwardRef<ContentRef, ContentProps>(
+  ({ asChild, ...props }, ref) => {
+    const { isOpen, nativeID } = useRootContext();
+
+    if (!isOpen) {
+      return null;
+    }
+
+    const Component = asChild ? Slot.View : View;
+
+    return (
+      <Component
+        ref={ref}
+        role="dialog"
+        nativeID={nativeID}
+        aria-labelledby={`${nativeID}_label`}
+        aria-describedby={`${nativeID}_desc`}
+        aria-modal={true}
+        {...props}
+      />
+    );
+  }
+);
+
+Content.displayName = 'HeroUINative.Primitive.BottomSheet.Content';
+
+// --------------------------------------------------
+
+const Close = forwardRef<CloseRef, CloseProps>(
+  ({ asChild, onPress: onPressProp, disabled = false, ...props }, ref) => {
+    const { onOpenChange } = useRootContext();
+
+    function onPress(ev: GestureResponderEvent) {
+      if (disabled) return;
+      onOpenChange(false);
+      onPressProp?.(ev);
+    }
+
+    const Component = asChild ? Slot.Pressable : Pressable;
+
+    return (
+      <Component
+        ref={ref}
+        aria-disabled={disabled ?? undefined}
+        role="button"
+        onPress={onPress}
+        disabled={disabled ?? undefined}
+        {...props}
+      />
+    );
+  }
+);
+
+Close.displayName = 'HeroUINative.Primitive.BottomSheet.Close';
+
+// --------------------------------------------------
+
+const Title = forwardRef<TitleRef, TitleProps>((props, ref) => {
+  const { nativeID } = useRootContext();
+  return (
+    <Text ref={ref} role="heading" nativeID={`${nativeID}_label`} {...props} />
+  );
+});
+
+Title.displayName = 'HeroUINative.Primitive.BottomSheet.Title';
+
+// --------------------------------------------------
+
+const Description = forwardRef<DescriptionRef, DescriptionProps>(
+  (props, ref) => {
+    const { nativeID } = useRootContext();
+    return <Text ref={ref} nativeID={`${nativeID}_desc`} {...props} />;
+  }
+);
+
+Description.displayName = 'HeroUINative.Primitive.BottomSheet.Description';
+
+// --------------------------------------------------
+
+export {
+  Close,
+  Content,
+  Description,
+  Overlay,
+  Portal,
+  Root,
+  Title,
+  Trigger,
+  useRootContext,
+};

package/src/primitives/bottom-sheet/bottom-sheet.types.ts

@@ -0,0 +1,127 @@
+import type {
+  PressableRef,
+  SlottablePressableProps,
+  SlottableTextProps,
+  SlottableViewProps,
+  TextRef,
+  ViewRef,
+} from '../../helpers/types';
+
+/**
+ * Context for the bottom sheet root component
+ */
+type RootContext = {
+  /** Whether the bottom sheet is currently open */
+  isOpen: boolean;
+  /** Callback fired when the open state changes */
+  onOpenChange: (value: boolean) => void;
+};
+
+/**
+ * Props for the bottom sheet root component
+ */
+type RootProps = SlottableViewProps & {
+  /** The controlled open state of the bottom sheet */
+  isOpen?: boolean;
+  /** The open state of the bottom sheet when initially rendered (uncontrolled) */
+  isDefaultOpen?: boolean;
+  /** Event handler called when the open state changes */
+  onOpenChange?: (value: boolean) => void;
+};
+
+/**
+ * Props for the bottom sheet portal component
+ */
+interface PortalProps {
+  /** The content to be rendered in the portal */
+  children: React.ReactNode;
+  /** Optional portal host name to render into a specific portal container */
+  hostName?: string;
+}
+
+/**
+ * Props for the bottom sheet overlay component
+ */
+type OverlayProps = SlottablePressableProps & {
+  /** Whether clicking the overlay should close the bottom sheet */
+  isCloseOnPress?: boolean;
+};
+
+/**
+ * Props for the bottom sheet content component
+ */
+type ContentProps = SlottableViewProps;
+
+/**
+ * Props for the bottom sheet trigger component
+ */
+type TriggerProps = SlottablePressableProps;
+
+/**
+ * Props for the bottom sheet close button component
+ */
+type CloseProps = SlottablePressableProps;
+
+/**
+ * Props for the bottom sheet title component
+ */
+type TitleProps = SlottableTextProps;
+
+/**
+ * Props for the bottom sheet description component
+ */
+type DescriptionProps = SlottableTextProps;
+
+/**
+ * Ref type for the bottom sheet close button
+ */
+type CloseRef = PressableRef;
+
+/**
+ * Ref type for the bottom sheet content
+ */
+type ContentRef = ViewRef;
+
+/**
+ * Ref type for the bottom sheet description
+ */
+type DescriptionRef = TextRef;
+
+/**
+ * Ref type for the bottom sheet overlay
+ */
+type OverlayRef = PressableRef;
+
+/**
+ * Ref type for the bottom sheet root
+ */
+type RootRef = ViewRef;
+
+/**
+ * Ref type for the bottom sheet title
+ */
+type TitleRef = TextRef;
+
+/**
+ * Ref type for the bottom sheet trigger
+ */
+type TriggerRef = PressableRef;
+
+export type {
+  CloseProps,
+  CloseRef,
+  ContentProps,
+  ContentRef,
+  DescriptionProps,
+  DescriptionRef,
+  OverlayProps,
+  OverlayRef,
+  PortalProps,
+  RootContext,
+  RootProps,
+  RootRef,
+  TitleProps,
+  TitleRef,
+  TriggerProps,
+  TriggerRef,
+};

package/src/primitives/bottom-sheet/index.ts

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