@croacroa/react-native-template 1.0.0 → 2.0.0

package/components/ui/VirtualizedList.tsx

@@ -0,0 +1,285 @@
+/**
+ * @fileoverview High-performance virtualized list component
+ * Wraps @shopify/flash-list for optimal list rendering with large datasets.
+ * @module components/ui/VirtualizedList
+ */
+
+import React, { useCallback, useMemo } from "react";
+import {
+  View,
+  Text,
+  ActivityIndicator,
+  RefreshControl,
+  StyleSheet,
+} from "react-native";
+import { FlashList, FlashListProps } from "@shopify/flash-list";
+import { useTheme } from "@/hooks/useTheme";
+import { cn } from "@/utils/cn";
+
+/**
+ * Props for VirtualizedList component
+ */
+interface VirtualizedListProps<T> extends Omit<FlashListProps<T>, "renderItem" | "estimatedItemSize"> {
+  /**
+   * Array of data items to render
+   */
+  data: T[];
+
+  /**
+   * Render function for each item
+   */
+  renderItem: (info: { item: T; index: number }) => React.ReactElement | null;
+
+  /**
+   * Unique key extractor for items
+   */
+  keyExtractor: (item: T, index: number) => string;
+
+  /**
+   * Estimated height of each item for better performance
+   * Required for optimal FlashList performance
+   */
+  estimatedItemSize?: number;
+
+  /**
+   * Whether the list is currently loading
+   */
+  isLoading?: boolean;
+
+  /**
+   * Whether the list is refreshing (pull-to-refresh)
+   */
+  isRefreshing?: boolean;
+
+  /**
+   * Callback when user pulls to refresh
+   */
+  onRefresh?: () => void;
+
+  /**
+   * Whether there's more data to load
+   */
+  hasMore?: boolean;
+
+  /**
+   * Callback when user scrolls near the end
+   */
+  onLoadMore?: () => void;
+
+  /**
+   * Component to render when list is empty
+   */
+  emptyComponent?: React.ReactElement;
+
+  /**
+   * Message to show when list is empty
+   */
+  emptyMessage?: string;
+
+  /**
+   * Component to render at the bottom when loading more
+   */
+  loadingMoreComponent?: React.ReactElement;
+
+  /**
+   * Additional class name for container
+   */
+  className?: string;
+
+  /**
+   * Threshold for onEndReached (0 to 1)
+   * @default 0.5
+   */
+  onEndReachedThreshold?: number;
+
+  /**
+   * Whether to show scroll indicator
+   * @default false
+   */
+  showsVerticalScrollIndicator?: boolean;
+
+  /**
+   * Draw distance for rendering items outside visible area
+   * Higher values = smoother scroll but more memory
+   * @default 250
+   */
+  drawDistance?: number;
+}
+
+/**
+ * Default empty component
+ */
+function DefaultEmptyComponent({ message }: { message: string }) {
+  const { isDark } = useTheme();
+
+  return (
+    <View className="flex-1 items-center justify-center py-12">
+      <Text
+        className={cn(
+          "text-base",
+          isDark ? "text-muted-dark" : "text-muted-light"
+        )}
+      >
+        {message}
+      </Text>
+    </View>
+  );
+}
+
+/**
+ * Default loading more component
+ */
+function DefaultLoadingMoreComponent() {
+  return (
+    <View className="items-center justify-center py-4">
+      <ActivityIndicator size="small" />
+    </View>
+  );
+}
+
+/**
+ * High-performance virtualized list component.
+ * Optimized for rendering large datasets with minimal memory usage.
+ *
+ * Features:
+ * - Automatic item recycling
+ * - Pull-to-refresh support
+ * - Infinite scroll (load more)
+ * - Empty state handling
+ * - Loading states
+ *
+ * @example
+ * ```tsx
+ * interface User {
+ *   id: string;
+ *   name: string;
+ * }
+ *
+ * function UserList() {
+ *   const { data, isLoading, refetch, hasNextPage, fetchNextPage } = useUsers();
+ *
+ *   return (
+ *     <VirtualizedList<User>
+ *       data={data}
+ *       renderItem={({ item }) => <UserCard user={item} />}
+ *       keyExtractor={(item) => item.id}
+ *       estimatedItemSize={72}
+ *       isLoading={isLoading}
+ *       isRefreshing={isLoading}
+ *       onRefresh={refetch}
+ *       hasMore={hasNextPage}
+ *       onLoadMore={fetchNextPage}
+ *       emptyMessage="No users found"
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function VirtualizedList<T>({
+  data,
+  renderItem,
+  keyExtractor,
+  estimatedItemSize = 50,
+  isLoading = false,
+  isRefreshing = false,
+  onRefresh,
+  hasMore = false,
+  onLoadMore,
+  emptyComponent,
+  emptyMessage = "No items found",
+  loadingMoreComponent,
+  className,
+  onEndReachedThreshold = 0.5,
+  showsVerticalScrollIndicator = false,
+  drawDistance = 250,
+  ...flashListProps
+}: VirtualizedListProps<T>) {
+  const { isDark } = useTheme();
+
+  // Memoize empty component
+  const ListEmptyComponent = useMemo(() => {
+    if (isLoading) return null;
+    if (emptyComponent) return emptyComponent;
+    return <DefaultEmptyComponent message={emptyMessage} />;
+  }, [isLoading, emptyComponent, emptyMessage]);
+
+  // Memoize footer component
+  const ListFooterComponent = useCallback(() => {
+    if (!hasMore || data.length === 0) return null;
+    if (loadingMoreComponent) return loadingMoreComponent;
+    return <DefaultLoadingMoreComponent />;
+  }, [hasMore, data.length, loadingMoreComponent]);
+
+  // Handle end reached
+  const handleEndReached = useCallback(() => {
+    if (hasMore && onLoadMore && !isLoading) {
+      onLoadMore();
+    }
+  }, [hasMore, onLoadMore, isLoading]);
+
+  // Memoize refresh control
+  const refreshControl = useMemo(() => {
+    if (!onRefresh) return undefined;
+
+    return (
+      <RefreshControl
+        refreshing={isRefreshing}
+        onRefresh={onRefresh}
+        tintColor={isDark ? "#94a3b8" : "#64748b"}
+        colors={["#3b82f6"]}
+      />
+    );
+  }, [onRefresh, isRefreshing, isDark]);
+
+  // Loading state
+  if (isLoading && data.length === 0) {
+    return (
+      <View className={cn("flex-1 items-center justify-center", className)}>
+        <ActivityIndicator size="large" color="#3b82f6" />
+      </View>
+    );
+  }
+
+  return (
+    <FlashList
+      data={data}
+      renderItem={renderItem}
+      keyExtractor={keyExtractor}
+      ListEmptyComponent={ListEmptyComponent}
+      ListFooterComponent={ListFooterComponent}
+      refreshControl={refreshControl}
+      onEndReached={handleEndReached}
+      onEndReachedThreshold={onEndReachedThreshold}
+      showsVerticalScrollIndicator={showsVerticalScrollIndicator}
+      // FlashList specific optimizations
+      estimatedItemSize={estimatedItemSize}
+      drawDistance={drawDistance}
+      {...flashListProps}
+      contentContainerStyle={[
+        styles.container,
+        flashListProps.contentContainerStyle,
+      ]}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flexGrow: 1,
+  },
+});
+
+/**
+ * Horizontal virtualized list variant
+ */
+export function HorizontalVirtualizedList<T>(
+  props: Omit<VirtualizedListProps<T>, "horizontal">
+) {
+  return (
+    <VirtualizedList
+      {...props}
+      horizontal
+      showsHorizontalScrollIndicator={false}
+    />
+  );
+}

package/components/ui/index.ts

@@ -1,18 +1,23 @@
-export { Button } from "./Button";
-export { Input } from "./Input";
-export { Card } from "./Card";
-export { Modal } from "./Modal";
-export { AnimatedButton } from "./AnimatedButton";
-export { AnimatedCard, AnimatedList } from "./AnimatedCard";
-export { Select } from "./Select";
-export type { SelectOption } from "./Select";
-export { Checkbox, CheckboxGroup } from "./Checkbox";
-export { BottomSheet, useBottomSheet } from "./BottomSheet";
-export type { BottomSheetRef } from "./BottomSheet";
-export { Avatar, AvatarGroup } from "./Avatar";
-export { Badge, Chip, CountBadge } from "./Badge";
-export {
-  OptimizedImage,
-  BackgroundImage,
-  ProgressiveImage,
-} from "./OptimizedImage";
+export { Button } from "./Button";
+export { Input } from "./Input";
+export { Card } from "./Card";
+export { Modal } from "./Modal";
+export { AnimatedButton } from "./AnimatedButton";
+export { AnimatedCard, AnimatedList } from "./AnimatedCard";
+export { Select } from "./Select";
+export type { SelectOption } from "./Select";
+export { Checkbox, CheckboxGroup } from "./Checkbox";
+export { BottomSheet, useBottomSheet } from "./BottomSheet";
+export type { BottomSheetRef } from "./BottomSheet";
+export { Avatar, AvatarGroup } from "./Avatar";
+export { Badge, Chip, CountBadge } from "./Badge";
+export {
+  OptimizedImage,
+  BackgroundImage,
+  ProgressiveImage,
+} from "./OptimizedImage";
+export { Skeleton, SkeletonText, SkeletonCircle } from "./Skeleton";
+export {
+  VirtualizedList,
+  HorizontalVirtualizedList,
+} from "./VirtualizedList";

package/constants/config.ts

@@ -1,54 +1,97 @@
-import Constants from "expo-constants";
-
-// Environment detection
-export const IS_DEV = __DEV__;
-export const IS_PREVIEW =
-  Constants.expoConfig?.extra?.APP_VARIANT === "preview";
-export const IS_PROD = !IS_DEV && !IS_PREVIEW;
-
-// API Configuration
-// TODO: Replace with your actual API URLs
-export const API_URL = IS_PROD
-  ? "https://api.yourapp.com"
-  : IS_PREVIEW
-    ? "https://staging-api.yourapp.com"
-    : "http://localhost:3000";
-
-// App Configuration
-export const APP_NAME = Constants.expoConfig?.name || "YourApp";
-export const APP_VERSION = Constants.expoConfig?.version || "1.0.0";
-export const APP_SCHEME = Constants.expoConfig?.scheme || "yourapp";
-
-// Feature Flags
-export const FEATURES = {
-  ENABLE_ANALYTICS: IS_PROD,
-  ENABLE_CRASH_REPORTING: IS_PROD,
-  ENABLE_PUSH_NOTIFICATIONS: true,
-  ENABLE_BIOMETRIC_AUTH: true,
-  ENABLE_PERFORMANCE_MONITORING: IS_DEV || IS_PREVIEW,
-} as const;
-
-// Export individual flags for convenience
-export const ENABLE_ANALYTICS = FEATURES.ENABLE_ANALYTICS;
-export const ENABLE_CRASH_REPORTING = FEATURES.ENABLE_CRASH_REPORTING;
-export const ENABLE_PUSH_NOTIFICATIONS = FEATURES.ENABLE_PUSH_NOTIFICATIONS;
-export const ENABLE_BIOMETRIC_AUTH = FEATURES.ENABLE_BIOMETRIC_AUTH;
-export const ENABLE_PERFORMANCE_MONITORING =
-  FEATURES.ENABLE_PERFORMANCE_MONITORING;
-
-// Timing Constants
-export const TIMING = {
-  DEBOUNCE_MS: 300,
-  ANIMATION_DURATION_MS: 200,
-  TOAST_DURATION_MS: 3000,
-  API_TIMEOUT_MS: 30000,
-} as const;
-
-// Storage Keys
-export const STORAGE_KEYS = {
-  AUTH_TOKEN: "auth_token",
-  USER: "auth_user",
-  THEME: "theme_mode",
-  ONBOARDING_COMPLETED: "onboarding_completed",
-  PUSH_TOKEN: "push_token",
-} as const;
+import Constants from "expo-constants";
+
+// Environment detection
+export const IS_DEV = __DEV__;
+export const IS_PREVIEW =
+  Constants.expoConfig?.extra?.APP_VARIANT === "preview";
+export const IS_PROD = !IS_DEV && !IS_PREVIEW;
+
+// API Configuration
+// TODO: Replace with your actual API URLs
+export const API_URL = IS_PROD
+  ? "https://api.yourapp.com"
+  : IS_PREVIEW
+    ? "https://staging-api.yourapp.com"
+    : "http://localhost:3000";
+
+// App Configuration
+export const APP_NAME = Constants.expoConfig?.name || "YourApp";
+export const APP_VERSION = Constants.expoConfig?.version || "1.0.0";
+export const APP_SCHEME = Constants.expoConfig?.scheme || "yourapp";
+
+// Feature Flags
+export const FEATURES = {
+  ENABLE_ANALYTICS: IS_PROD,
+  ENABLE_CRASH_REPORTING: IS_PROD,
+  ENABLE_PUSH_NOTIFICATIONS: true,
+  ENABLE_BIOMETRIC_AUTH: true,
+  ENABLE_PERFORMANCE_MONITORING: IS_DEV || IS_PREVIEW,
+} as const;
+
+// Export individual flags for convenience
+export const ENABLE_ANALYTICS = FEATURES.ENABLE_ANALYTICS;
+export const ENABLE_CRASH_REPORTING = FEATURES.ENABLE_CRASH_REPORTING;
+export const ENABLE_PUSH_NOTIFICATIONS = FEATURES.ENABLE_PUSH_NOTIFICATIONS;
+export const ENABLE_BIOMETRIC_AUTH = FEATURES.ENABLE_BIOMETRIC_AUTH;
+export const ENABLE_PERFORMANCE_MONITORING =
+  FEATURES.ENABLE_PERFORMANCE_MONITORING;
+
+// Timing Constants
+export const TIMING = {
+  DEBOUNCE_MS: 300,
+  ANIMATION_DURATION_MS: 200,
+  TOAST_DURATION_MS: 3000,
+  API_TIMEOUT_MS: 30000,
+} as const;
+
+// Storage Keys
+export const STORAGE_KEYS = {
+  AUTH_TOKEN: "auth_token",
+  USER: "auth_user",
+  THEME: "theme_mode",
+  ONBOARDING_COMPLETED: "onboarding_completed",
+  PUSH_TOKEN: "push_token",
+} as const;
+
+// Security Configuration
+export const SECURITY = {
+  /**
+   * SSL Pinning configuration for enhanced network security.
+   * Add your API server's certificate public key hashes here.
+   *
+   * To generate a pin from your certificate:
+   * 1. Get your server's certificate: openssl s_client -connect api.yourapp.com:443
+   * 2. Extract public key: openssl x509 -pubkey -noout -in cert.pem
+   * 3. Generate hash: openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64
+   *
+   * @example
+   * SSL_PINS: {
+   *   "api.yourapp.com": [
+   *     "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=", // Primary cert
+   *     "sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=", // Backup cert
+   *   ],
+   * }
+   */
+  SSL_PINS: {
+    // TODO: Add your production API certificate pins
+    // "api.yourapp.com": [
+    //   "sha256/YOUR_CERTIFICATE_HASH_HERE=",
+    // ],
+  } as Record<string, string[]>,
+
+  /**
+   * Enable SSL pinning in production
+   * Set to true once you've configured the SSL_PINS above
+   */
+  ENABLE_SSL_PINNING: IS_PROD && false, // Enable when pins are configured
+
+  /**
+   * Request signing configuration
+   * Used to sign API requests for added security
+   */
+  REQUEST_SIGNING: {
+    ENABLED: false,
+    ALGORITHM: "sha256",
+    HEADER_NAME: "X-Request-Signature",
+  },
+} as const;

package/docs/adr/001-state-management.md

@@ -1,79 +1,79 @@
-# ADR-001: Use Zustand for State Management
-
-## Status
-
-Accepted
-
-## Date
-
-2024-01-01
-
-## Context
-
-We need a state management solution for our React Native application. The requirements are:
-
-1. Simple API with minimal boilerplate
-2. Good TypeScript support
-3. Small bundle size (mobile performance matters)
-4. Support for persistence
-5. Devtools support for debugging
-6. No need for complex middleware or actions
-
-Options considered:
-
-- **Redux Toolkit**: Industry standard, but verbose for our needs
-- **MobX**: Powerful but adds complexity with observables
-- **Jotai**: Atomic state, good for simple cases
-- **Zustand**: Simple, small, flexible
-- **React Context**: Built-in, but can cause performance issues
-
-## Decision
-
-We chose **Zustand** for global state management.
-
-## Rationale
-
-1. **Simplicity**: Creating a store is just a function call
-
-   ```ts
-   const useStore = create((set) => ({
-     count: 0,
-     increment: () => set((s) => ({ count: s.count + 1 })),
-   }));
-   ```
-
-2. **Bundle size**: ~1KB gzipped vs Redux's ~7KB
-
-3. **TypeScript**: Excellent inference, minimal type annotations needed
-
-4. **Persistence**: Easy integration with AsyncStorage via middleware
-
-5. **No Providers**: Works outside React components, useful for API services
-
-6. **Selective subscriptions**: Components only re-render when selected state changes
-
-## Consequences
-
-### Positive
-
-- Faster development with less boilerplate
-- Smaller bundle size
-- Easy to test stores
-- Can use stores outside React (e.g., in API handlers)
-
-### Negative
-
-- Less structured than Redux (could lead to inconsistent patterns)
-- Smaller ecosystem than Redux
-- Team needs to establish conventions
-
-### Mitigation
-
-- Document store patterns in CONTRIBUTING.md
-- Use TypeScript for store definitions
-- Keep stores focused (one concern per store)
-
-## References
-
-- [Zustand Documentation](https://github.com/pmndrs/zustand)
-- [React Native Performance](https://reactnative.dev/docs/performance)
+# ADR-001: Use Zustand for State Management
+
+## Status
+
+Accepted
+
+## Date
+
+2024-01-01
+
+## Context
+
+We need a state management solution for our React Native application. The requirements are:
+
+1. Simple API with minimal boilerplate
+2. Good TypeScript support
+3. Small bundle size (mobile performance matters)
+4. Support for persistence
+5. Devtools support for debugging
+6. No need for complex middleware or actions
+
+Options considered:
+
+- **Redux Toolkit**: Industry standard, but verbose for our needs
+- **MobX**: Powerful but adds complexity with observables
+- **Jotai**: Atomic state, good for simple cases
+- **Zustand**: Simple, small, flexible
+- **React Context**: Built-in, but can cause performance issues
+
+## Decision
+
+We chose **Zustand** for global state management.
+
+## Rationale
+
+1. **Simplicity**: Creating a store is just a function call
+
+   ```ts
+   const useStore = create((set) => ({
+     count: 0,
+     increment: () => set((s) => ({ count: s.count + 1 })),
+   }));
+   ```
+
+2. **Bundle size**: ~1KB gzipped vs Redux's ~7KB
+
+3. **TypeScript**: Excellent inference, minimal type annotations needed
+
+4. **Persistence**: Easy integration with AsyncStorage via middleware
+
+5. **No Providers**: Works outside React components, useful for API services
+
+6. **Selective subscriptions**: Components only re-render when selected state changes
+
+## Consequences
+
+### Positive
+
+- Faster development with less boilerplate
+- Smaller bundle size
+- Easy to test stores
+- Can use stores outside React (e.g., in API handlers)
+
+### Negative
+
+- Less structured than Redux (could lead to inconsistent patterns)
+- Smaller ecosystem than Redux
+- Team needs to establish conventions
+
+### Mitigation
+
+- Document store patterns in CONTRIBUTING.md
+- Use TypeScript for store definitions
+- Keep stores focused (one concern per store)
+
+## References
+
+- [Zustand Documentation](https://github.com/pmndrs/zustand)
+- [React Native Performance](https://reactnative.dev/docs/performance)