@campxdev/react-native-blueprint 0.1.0

package/src/components/ui/AppBar.tsx

@@ -0,0 +1,551 @@
+import type { LucideIcon } from 'lucide-react-native';
+import { ArrowLeft, Menu, MoreVertical } from 'lucide-react-native';
+import { cssInterop, useColorScheme } from 'nativewind';
+import * as React from 'react';
+import {
+  Platform,
+  Pressable as RNPressable,
+  View as RNView,
+  StatusBar,
+} from 'react-native';
+import { SafeAreaView } from 'react-native-safe-area-context';
+import { cn } from '../../lib/utils';
+import { Icon } from './Icon';
+import { Text } from './Text';
+
+const View = cssInterop(RNView, { className: 'style' });
+const Pressable = cssInterop(RNPressable, { className: 'style' });
+
+/**
+ * Configuration for an action item in the AppBar
+ *
+ * @property {LucideIcon} icon - Icon component from lucide-react-native
+ * @property {() => void} [onPress] - Callback when action is pressed
+ * @property {string} [label] - Accessibility label for the action
+ * @property {string} [className] - Additional classes for the action button container
+ * @property {string} [iconClassName] - Additional classes for the icon
+ * @property {boolean} [disabled] - Whether the action is disabled
+ *
+ * @example
+ * ```tsx
+ * const actions: AppBarAction[] = [
+ *   { icon: Search, onPress: handleSearch, label: 'Search' },
+ *   { icon: MoreVertical, onPress: handleMore, label: 'More options' }
+ * ];
+ * ```
+ */
+export type AppBarAction = {
+  icon: LucideIcon;
+  onPress?: () => void;
+  label?: string;
+  className?: string;
+  iconClassName?: string;
+  disabled?: boolean;
+};
+
+/**
+ * Props for AppBar component - A flexible top app bar following Material Design guidelines
+ *
+ * @property {string | React.ReactNode} [title] - AppBar title text or custom component
+ * @property {string} [subtitle] - Optional subtitle text displayed below title
+ *
+ * @property {React.ReactNode} [leading] - Custom leading widget (can include multiple icons or custom components, overrides default back button)
+ * @property {boolean} [showLeading=true] - Whether to show the leading widget
+ * @property {() => void} [onLeadingPress] - Callback when leading icon is pressed (only used if no custom leading provided)
+ * @property {LucideIcon} [leadingIcon=ArrowLeft] - Icon for the leading button (only used if no custom leading provided)
+ *
+ * @property {React.ReactNode} [center] - Custom center component (overrides title/subtitle, can include images, text, or complex layouts)
+ *
+ * @property {AppBarAction[]} [actions=[]] - Array of action items to display on the right (supports multiple icons)
+ *
+ * @property {string} [className] - Additional classes for the root container
+ * @property {string} [titleClassName] - Additional classes for the title text
+ * @property {string} [subtitleClassName] - Additional classes for the subtitle text
+ * @property {string} [contentClassName] - Additional classes for the content container
+ * @property {string} [leadingClassName] - Additional classes for the leading section container
+ * @property {string} [centerClassName] - Additional classes for the center section container
+ * @property {string} [actionsClassName] - Additional classes for the actions section container
+ *
+ * @property {boolean} [centerTitle=false] - Whether to center the title
+ * @property {number} [elevation=4] - Elevation level for shadow (0 = no shadow)
+ * @property {boolean} [transparent=false] - Whether the AppBar background is transparent
+ *
+ * @property {boolean} [useSafeArea=true] - Whether to respect safe area insets
+ *
+ * @property {string} [backgroundColor] - Custom background color class
+ * @property {string} [foregroundColor] - Custom foreground/text color class
+ *
+ * @property {'default' | 'light-content' | 'dark-content'} [statusBarStyle] - Status bar text color (auto-adjusts based on theme if not set)
+ * @property {string} [statusBarColor] - Status bar background color (Android)
+ *
+ * @property {number} [height] - Custom height in pixels (default: 56px per Material Design)
+ *
+ * @property {React.ReactNode} [bottom] - Additional content below main app bar (e.g., tabs, search)
+ *
+ * @example
+ * ```tsx
+ * // Simple app bar with title
+ * <AppBar title="Home" />
+ *
+ * // With custom center containing image and text
+ * <AppBar
+ *   center={
+ *     <View className="flex-row items-center gap-2">
+ *       <Image source={logo} className="w-8 h-8" />
+ *       <Text className="text-lg font-bold">MyApp</Text>
+ *     </View>
+ *   }
+ * />
+ *
+ * // With multiple leading icons
+ * <AppBar
+ *   title="Settings"
+ *   leading={
+ *     <View className="flex-row items-center">
+ *       <IconButton icon={Menu} onPress={openMenu} />
+ *       <IconButton icon={ArrowLeft} onPress={goBack} />
+ *     </View>
+ *   }
+ *   actions={[
+ *     { icon: Search, onPress: handleSearch },
+ *     { icon: Settings, onPress: openSettings },
+ *     { icon: MoreVertical, onPress: handleMore }
+ *   ]}
+ * />
+ * ```
+ */
+export type AppBarProps = {
+  // Title and subtitle
+  title?: string | React.ReactNode;
+  subtitle?: string;
+
+  // Leading (supports custom components with multiple icons)
+  leading?: React.ReactNode;
+  showLeading?: boolean;
+  onLeadingPress?: () => void;
+  leadingIcon?: LucideIcon;
+
+  // Center (custom component that can include images or complex layouts)
+  center?: React.ReactNode;
+
+  // Actions (supports multiple icons)
+  actions?: AppBarAction[];
+
+  // Styling
+  className?: string;
+  titleClassName?: string;
+  subtitleClassName?: string;
+  contentClassName?: string;
+  leadingClassName?: string;
+  centerClassName?: string;
+  actionsClassName?: string;
+
+  // Layout
+  centerTitle?: boolean;
+  elevation?: number;
+  transparent?: boolean;
+
+  // Safe area
+  useSafeArea?: boolean;
+
+  // Colors
+  backgroundColor?: string;
+  foregroundColor?: string;
+
+  // Status bar (iOS/Android)
+  statusBarStyle?: 'default' | 'light-content' | 'dark-content';
+  statusBarColor?: string;
+
+  // Height
+  height?: number;
+
+  // Additional content
+  bottom?: React.ReactNode;
+};
+
+/**
+ * A flexible top app bar component following Material Design guidelines
+ *
+ * Provides consistent navigation and actions across your app with support for:
+ * - Customizable leading navigation (back button, menu, custom widget)
+ * - Title and subtitle with flexible positioning
+ * - Action buttons on the right side
+ * - Safe area insets handling
+ * - Platform-specific status bar configuration
+ * - Transparent overlay mode
+ * - Bottom content slot for tabs or search bars
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic with back button
+ * <AppBar
+ *   title="Profile"
+ *   onLeadingPress={() => navigation.goBack()}
+ * />
+ *
+ * // With menu and actions
+ * <AppBar
+ *   title="Home"
+ *   leadingIcon={Menu}
+ *   onLeadingPress={openDrawer}
+ *   actions={[
+ *     { icon: Search, onPress: handleSearch },
+ *     { icon: Settings, onPress: openSettings }
+ *   ]}
+ * />
+ *
+ * // Transparent overlay (for use over content)
+ * <AppBar
+ *   title="Photo"
+ *   transparent
+ *   foregroundColor="text-white"
+ *   statusBarStyle="light-content"
+ * />
+ * ```
+ *
+ * @accessibility
+ * - Leading button includes "Navigate back" accessibility label
+ * - Action buttons support custom accessibility labels
+ * - Proper button role for all interactive elements
+ */
+const AppBar = React.forwardRef<RNView, AppBarProps>(
+  (
+    {
+      title,
+      subtitle,
+      leading,
+      showLeading = true,
+      onLeadingPress,
+      leadingIcon = ArrowLeft,
+      center,
+      actions = [],
+      className,
+      titleClassName,
+      subtitleClassName,
+      contentClassName,
+      leadingClassName,
+      centerClassName,
+      actionsClassName,
+      centerTitle = false,
+      elevation = 4,
+      transparent = false,
+      useSafeArea = true,
+      backgroundColor,
+      foregroundColor,
+      statusBarStyle,
+      statusBarColor,
+      height,
+      bottom,
+    },
+    ref
+  ) => {
+    // Get the current color scheme for dark mode support
+    const { colorScheme } = useColorScheme();
+    const isDark = colorScheme === 'dark';
+
+    // Default height following Material Design guidelines
+    const defaultHeight = 56;
+    const appBarHeight = height ?? defaultHeight;
+
+    // Determine status bar style based on theme if not explicitly set
+    const defaultStatusBarStyle = transparent
+      ? 'light-content' // Transparent bars usually overlay content, so use light text
+      : isDark
+        ? 'light-content'
+        : 'dark-content';
+    const resolvedStatusBarStyle = statusBarStyle ?? defaultStatusBarStyle;
+
+    // Background color
+    const bgColor = transparent
+      ? 'bg-transparent'
+      : backgroundColor || 'bg-background';
+
+    // Shadow/elevation styles
+    const elevationStyle =
+      !transparent && elevation > 0 ? 'border-b border-border shadow-sm' : '';
+
+    // Render center/title content
+    const renderCenter = () => {
+      // If custom center is provided, use it
+      if (center) {
+        return (
+          <View className={cn('flex-1 justify-center', centerClassName)}>
+            {center}
+          </View>
+        );
+      }
+
+      // Otherwise fall back to title/subtitle
+      if (!title) return null;
+
+      if (typeof title === 'string') {
+        return (
+          <View
+            className={cn(
+              'flex-1 justify-center',
+              subtitle && 'gap-0.5',
+              centerClassName
+            )}
+          >
+            <Text
+              className={cn(
+                'text-xl font-semibold',
+                foregroundColor || 'text-foreground',
+                titleClassName
+              )}
+              numberOfLines={1}
+              ellipsizeMode="tail"
+            >
+              {title}
+            </Text>
+            {subtitle && (
+              <Text
+                className={cn(
+                  'text-xs',
+                  foregroundColor ? 'opacity-70' : 'text-muted-foreground',
+                  subtitleClassName
+                )}
+                numberOfLines={1}
+                ellipsizeMode="tail"
+              >
+                {subtitle}
+              </Text>
+            )}
+          </View>
+        );
+      }
+
+      return (
+        <View className={cn('flex-1 justify-center', centerClassName)}>
+          {title}
+        </View>
+      );
+    };
+
+    // Render leading icon/widget
+    const renderLeading = () => {
+      if (!showLeading) return null;
+
+      if (leading) {
+        return <View className={cn('mr-2', leadingClassName)}>{leading}</View>;
+      }
+
+      if (onLeadingPress) {
+        const LeadingIcon = leadingIcon;
+        return (
+          <Pressable
+            onPress={onLeadingPress}
+            className={cn(
+              'mr-2 -ml-2 h-10 w-10 items-center justify-center rounded-full active:bg-accent/50',
+              leadingClassName
+            )}
+            accessibilityRole="button"
+            accessibilityLabel="Navigate back"
+          >
+            <Icon
+              as={LeadingIcon}
+              size={24}
+              className={cn(foregroundColor || 'text-foreground')}
+            />
+          </Pressable>
+        );
+      }
+
+      return null;
+    };
+
+    // Render action items
+    const renderActions = () => {
+      if (!actions || actions.length === 0) return null;
+
+      return (
+        <View className={cn('flex-row items-center gap-1', actionsClassName)}>
+          {actions.map((action, index) => {
+            const ActionIcon = action.icon;
+            return (
+              <Pressable
+                key={index}
+                onPress={action.onPress}
+                disabled={action.disabled}
+                className={cn(
+                  'h-10 w-10 items-center justify-center rounded-full active:bg-accent/50',
+                  action.disabled && 'opacity-50',
+                  action.className
+                )}
+                accessibilityRole="button"
+                accessibilityLabel={action.label || `Action ${index + 1}`}
+              >
+                <Icon
+                  as={ActionIcon}
+                  size={24}
+                  className={cn(
+                    foregroundColor || 'text-foreground',
+                    action.iconClassName
+                  )}
+                />
+              </Pressable>
+            );
+          })}
+        </View>
+      );
+    };
+
+    return (
+      <>
+        {/* Status Bar */}
+        {Platform.OS !== 'web' && (
+          <StatusBar
+            barStyle={resolvedStatusBarStyle}
+            backgroundColor={statusBarColor || 'transparent'}
+            translucent={useSafeArea}
+          />
+        )}
+
+        {/* Main AppBar Container with SafeAreaView */}
+        {useSafeArea ? (
+          <SafeAreaView edges={['top']}>
+            <View
+              ref={ref as any}
+              className={cn(bgColor, elevationStyle, className)}
+            >
+              {/* AppBar Content */}
+              <View
+                className={cn(
+                  'flex-row items-center justify-between px-4',
+                  contentClassName
+                )}
+                style={{ height: appBarHeight }}
+              >
+                {/* Leading Section */}
+                {renderLeading()}
+
+                {/* Center/Title Section */}
+                <View
+                  className={cn(
+                    'flex-1',
+                    centerTitle && 'items-center',
+                    !centerTitle && 'items-start'
+                  )}
+                >
+                  {renderCenter()}
+                </View>
+
+                {/* Actions Section */}
+                {renderActions()}
+              </View>
+
+              {/* Bottom Content (for tabs, search bar, etc.) */}
+              {bottom && <View className="pb-2">{bottom}</View>}
+            </View>
+          </SafeAreaView>
+        ) : (
+          <View
+            ref={ref as any}
+            className={cn(bgColor, elevationStyle, className)}
+          >
+            {/* AppBar Content */}
+            <View
+              className={cn(
+                'flex-row items-center justify-between px-4',
+                contentClassName
+              )}
+              style={{ height: appBarHeight }}
+            >
+              {/* Leading Section */}
+              {renderLeading()}
+
+              {/* Center/Title Section */}
+              <View
+                className={cn(
+                  'flex-1',
+                  centerTitle && 'items-center',
+                  !centerTitle && 'items-start'
+                )}
+              >
+                {renderCenter()}
+              </View>
+
+              {/* Actions Section */}
+              {renderActions()}
+            </View>
+
+            {/* Bottom Content (for tabs, search bar, etc.) */}
+            {bottom && <View className="pb-2">{bottom}</View>}
+          </View>
+        )}
+      </>
+    );
+  }
+);
+
+AppBar.displayName = 'AppBar';
+
+/**
+ * Pre-configured AppBar variants for common use cases
+ *
+ * @example
+ * ```tsx
+ * // Simple app bar without navigation
+ * <AppBarVariants.Simple title="Home" />
+ *
+ * // With back button
+ * <AppBarVariants.WithBack title="Details" onLeadingPress={goBack} />
+ *
+ * // With menu drawer
+ * <AppBarVariants.WithMenu title="Main" onLeadingPress={openDrawer} />
+ *
+ * // Transparent overlay
+ * <AppBarVariants.Transparent title="Gallery" />
+ *
+ * // Centered title
+ * <AppBarVariants.Centered title="About" />
+ * ```
+ */
+export const AppBarVariants = {
+  // Simple app bar with just a title
+  Simple: (props: Omit<AppBarProps, 'showLeading'>) => (
+    <AppBar {...props} showLeading={false} />
+  ),
+
+  // App bar with back button
+  WithBack: (props: AppBarProps) => <AppBar {...props} showLeading={true} />,
+
+  // App bar with menu icon
+  WithMenu: (props: Omit<AppBarProps, 'leadingIcon'>) => (
+    <AppBar {...props} leadingIcon={Menu} showLeading={true} />
+  ),
+
+  // Transparent app bar (for use over content)
+  Transparent: (props: Omit<AppBarProps, 'transparent'>) => (
+    <AppBar {...props} transparent={true} elevation={0} />
+  ),
+
+  // Centered title app bar
+  Centered: (props: Omit<AppBarProps, 'centerTitle'>) => (
+    <AppBar {...props} centerTitle={true} />
+  ),
+};
+
+/**
+ * Common icons exported for convenience when configuring AppBar
+ *
+ * @example
+ * ```tsx
+ * import { AppBar, AppBarIcons } from './AppBar';
+ *
+ * <AppBar
+ *   leadingIcon={AppBarIcons.Menu}
+ *   actions={[
+ *     { icon: AppBarIcons.MoreVertical, onPress: handleMore }
+ *   ]}
+ * />
+ * ```
+ */
+export const AppBarIcons = {
+  Menu,
+  ArrowLeft,
+  MoreVertical,
+};
+
+export { AppBar };

package/src/components/ui/Aspect-Ratio.tsx

@@ -0,0 +1,25 @@
+import * as AspectRatioPrimitive from '@rn-primitives/aspect-ratio';
+
+/**
+ * Maintains a consistent aspect ratio for its child content
+ *
+ * Displays content within a desired ratio (e.g., 16/9, 4/3, 1/1) regardless of available space.
+ * Commonly used for images, videos, and embedded content that require specific proportions.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // 16:9 aspect ratio for video container
+ * <AspectRatio ratio={16 / 9} className="bg-muted">
+ *   <Image source={{uri: 'video-thumbnail.jpg'}} className="h-full w-full rounded-md object-cover" />
+ * </AspectRatio>
+ *
+ * // Square aspect ratio for avatars
+ * <AspectRatio ratio={1} className="w-full">
+ *   <Image source={{uri: 'avatar.jpg'}} className="h-full w-full" />
+ * </AspectRatio>
+ * ```
+ */
+const AspectRatio = AspectRatioPrimitive.Root;
+
+export { AspectRatio };

package/src/components/ui/Avatar.tsx

@@ -0,0 +1,103 @@
+import * as React from 'react';
+import { Image, View } from 'react-native';
+import { cssInterop } from 'nativewind';
+import { cn } from '../../lib/utils';
+import type { ViewRef, SlottableViewProps } from '@rn-primitives/types';
+import * as Slot from '@rn-primitives/slot';
+
+cssInterop(View, { className: 'style' });
+cssInterop(Slot.View, { className: 'style' });
+cssInterop(Image, { className: 'style' });
+
+/**
+ * Avatar container component
+ *
+ * Circular container for displaying user avatars with images or fallback initials.
+ * Use with AvatarImage and AvatarFallback for complete functionality.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Avatar>
+ *   <AvatarImage source={{ uri: userPhoto }} alt="User avatar" />
+ *   <AvatarFallback>
+ *     <Text>JD</Text>
+ *   </AvatarFallback>
+ * </Avatar>
+ * ```
+ *
+ * @property {boolean} [asChild] - When true, merges props into immediate child
+ * @property {string} [className] - Additional Tailwind classes
+ */
+const Avatar = React.forwardRef<
+  ViewRef,
+  SlottableViewProps & { className?: string }
+>(({ className, asChild = false, ...props }, ref) => {
+  const Component = asChild ? Slot.View : View;
+  return (
+    <Component
+      className={cn(
+        'relative flex h-10 w-10 shrink-0 overflow-hidden rounded-full',
+        className
+      )}
+      ref={ref as any}
+      {...props}
+    />
+  );
+});
+Avatar.displayName = 'Avatar';
+
+/**
+ * AvatarImage - Image component for avatar
+ *
+ * Displays the user's profile image. Falls back to AvatarFallback if image fails to load.
+ *
+ * @property {ImageSource} source - Image source (local or remote URI)
+ * @property {string} [alt] - Alternative text for accessibility
+ * @property {string} [className] - Additional Tailwind classes
+ */
+const AvatarImage = React.forwardRef<
+  React.ElementRef<typeof Image>,
+  React.ComponentPropsWithoutRef<typeof Image> & {
+    className?: string;
+    alt?: string;
+  }
+>(({ className, ...props }, ref) => {
+  return (
+    <Image
+      className={cn('aspect-square h-full w-full', className)}
+      ref={ref}
+      {...props}
+    />
+  );
+});
+AvatarImage.displayName = 'AvatarImage';
+
+/**
+ * AvatarFallback - Fallback content when image is unavailable
+ *
+ * Typically displays user initials or an icon. Shows when AvatarImage fails to load
+ * or is not provided.
+ *
+ * @property {boolean} [asChild] - When true, merges props into immediate child
+ * @property {string} [className] - Additional Tailwind classes
+ */
+const AvatarFallback = React.forwardRef<
+  ViewRef,
+  SlottableViewProps & { className?: string }
+>(({ className, asChild = false, ...props }, ref) => {
+  const Component = asChild ? Slot.View : View;
+  return (
+    <Component
+      className={cn(
+        'flex h-full w-full items-center justify-center rounded-full bg-muted',
+        className
+      )}
+      ref={ref}
+      {...props}
+    />
+  );
+});
+AvatarFallback.displayName = 'AvatarFallback';
+
+export { Avatar, AvatarImage, AvatarFallback };