@umituz/react-native-design-system 2.6.107 → 2.6.111

package/src/infinite-scroll/domain/types/infinite-scroll-config.ts

@@ -0,0 +1,108 @@
+/**
+ * Infinite Scroll Configuration Types
+ *
+ * Domain types for infinite scroll configuration
+ * Follows SOLID, DRY, KISS principles
+ */
+
+/**
+ * Paginated result for cursor-based pagination
+ */
+export interface PaginatedResult<T> {
+  items: T[];
+  nextCursor: string | null;
+  hasMore: boolean;
+}
+
+/**
+ * Base configuration shared by all pagination modes
+ */
+interface BaseConfig<T> {
+  /**
+   * Total number of items available (optional, for progress tracking)
+   */
+  totalItems?: number;
+
+  /**
+   * Number of items to load per page
+   * Default: 20
+   */
+  pageSize?: number;
+
+  /**
+   * Number of items from the end to trigger loading more
+   * Default: 5 (loads more when 5 items from bottom)
+   */
+  threshold?: number;
+
+  /**
+   * Enable automatic loading when threshold is reached
+   * Default: true
+   */
+  autoLoad?: boolean;
+
+  /**
+   * Optional: Function to get unique key for each item
+   * If not provided, uses array index
+   * @param item - Item to get key for
+   * @param index - Item index
+   * @returns Unique key string
+   */
+  getItemKey?: (item: T, index: number) => string;
+}
+
+/**
+ * Page-based pagination configuration (default, backward compatible)
+ */
+export interface PageBasedConfig<T> extends BaseConfig<T> {
+  /**
+   * Initial page number (0-indexed)
+   * Default: 0
+   */
+  initialPage?: number;
+
+  /**
+   * Function to fetch data for a specific page
+   * @param page - Page number (0-indexed)
+   * @param pageSize - Number of items per page
+   * @returns Promise resolving to array of items
+   */
+  fetchData: (page: number, pageSize: number) => Promise<T[]>;
+
+  /**
+   * Optional: Function to check if there are more items
+   * If not provided, checks if last page has fewer items than pageSize
+   * @param lastPage - Last fetched page of items
+   * @param allPages - All fetched pages
+   * @returns true if there are more items to load
+   */
+  hasMore?: (lastPage: T[], allPages: T[][]) => boolean;
+}
+
+/**
+ * Cursor-based pagination configuration (new, for Firestore)
+ */
+export interface CursorBasedConfig<T> extends BaseConfig<T> {
+  /**
+   * Discriminator for cursor-based mode
+   */
+  paginationMode: "cursor";
+
+  /**
+   * Function to fetch data using cursor
+   * @param cursor - Cursor for next page (undefined for first page)
+   * @param pageSize - Number of items per page
+   * @returns Promise resolving to paginated result with cursor
+   */
+  fetchCursor: (
+    cursor: string | undefined,
+    pageSize: number,
+  ) => Promise<PaginatedResult<T>>;
+}
+
+/**
+ * Infinite scroll configuration (discriminated union)
+ */
+export type InfiniteScrollConfig<T> =
+  | PageBasedConfig<T>
+  | CursorBasedConfig<T>;

package/src/infinite-scroll/domain/types/infinite-scroll-return.ts

@@ -0,0 +1,40 @@
+/**
+ * Infinite Scroll Return Types
+ *
+ * Domain types for hook return values
+ * Follows SOLID, DRY, KISS principles
+ */
+
+import type { InfiniteScrollState } from "./infinite-scroll-state";
+
+export interface UseInfiniteScrollReturn<T> {
+  /**
+   * All loaded items (flattened)
+   */
+  items: T[];
+
+  /**
+   * Current state
+   */
+  state: InfiniteScrollState<T>;
+
+  /**
+   * Load next page of items
+   */
+  loadMore: () => Promise<void>;
+
+  /**
+   * Refresh all data (resets to page 0)
+   */
+  refresh: () => Promise<void>;
+
+  /**
+   * Reset to initial state
+   */
+  reset: () => void;
+
+  /**
+   * Check if can load more
+   */
+  canLoadMore: boolean;
+}

package/src/infinite-scroll/domain/types/infinite-scroll-state.ts

@@ -0,0 +1,58 @@
+/**
+ * Infinite Scroll State Types
+ *
+ * Domain types for infinite scroll state management
+ * Follows SOLID, DRY, KISS principles
+ */
+
+export interface InfiniteScrollState<T> {
+  /**
+   * All loaded items (flattened from pages)
+   */
+  items: T[];
+
+  /**
+   * All pages of items (used in page-based mode)
+   */
+  pages: T[][];
+
+  /**
+   * Current page number (0-indexed, page-based mode)
+   */
+  currentPage: number;
+
+  /**
+   * Current cursor (cursor-based mode)
+   */
+  cursor: string | null;
+
+  /**
+   * Whether more items are available
+   */
+  hasMore: boolean;
+
+  /**
+   * Whether currently loading initial data
+   */
+  isLoading: boolean;
+
+  /**
+   * Whether currently loading more items
+   */
+  isLoadingMore: boolean;
+
+  /**
+   * Whether currently refreshing
+   */
+  isRefreshing: boolean;
+
+  /**
+   * Error message if any
+   */
+  error: string | null;
+
+  /**
+   * Total number of items (if known)
+   */
+  totalItems?: number;
+}

package/src/infinite-scroll/domain/utils/pagination-utils.ts

@@ -0,0 +1,63 @@
+/**
+ * Pagination Utilities
+ *
+ * Pure functions for pagination calculations
+ * Follows SOLID, DRY, KISS principles
+ */
+
+/**
+ * Calculate onEndReachedThreshold from threshold value
+ * Converts threshold (number of items) to percentage (0-1)
+ *
+ * @param threshold - Number of items from bottom to trigger load
+ * @param defaultThreshold - Default threshold if not provided (default: 0.1 = 10%)
+ * @returns Threshold value between 0.01 and 1.0
+ */
+export function calculateEndReachedThreshold(
+  threshold?: number,
+  defaultThreshold = 0.1,
+): number {
+  if (!threshold) {
+    return defaultThreshold;
+  }
+
+  // Convert threshold to percentage (0-1 range)
+  // Ensure minimum 0.01 (1%) and maximum 1.0 (100%)
+  const calculated = threshold / 100;
+  return Math.max(0.01, Math.min(1.0, calculated));
+}
+
+/**
+ * Calculate pagination slice for client-side pagination
+ *
+ * @param items - All items to paginate
+ * @param page - Page number (0-indexed)
+ * @param pageSize - Number of items per page
+ * @returns Slice of items for the requested page
+ */
+export function getPageSlice<T>(
+  items: T[],
+  page: number,
+  pageSize: number,
+): T[] {
+  const start = page * pageSize;
+  const end = start + pageSize;
+  return items.slice(start, end);
+}
+
+/**
+ * Check if there are more items to load
+ *
+ * @param lastPage - Last fetched page
+ * @param allPages - All fetched pages
+ * @param pageSize - Page size
+ * @returns True if there are more items to load
+ */
+export function hasMoreItems<T>(
+  lastPage: T[],
+  allPages: T[][],
+  pageSize: number,
+): boolean {
+  // If last page has fewer items than pageSize, we've reached the end
+  return lastPage.length >= pageSize;
+}

package/src/infinite-scroll/domain/utils/type-guards.ts

@@ -0,0 +1,53 @@
+/**
+ * Type Guard Utilities
+ *
+ * Runtime type checking for better type safety
+ */
+
+import type { InfiniteScrollConfig, PageBasedConfig, CursorBasedConfig } from "../types/infinite-scroll-config";
+
+/**
+ * Check if config is page-based pagination
+ */
+export function isPageBasedConfig<T>(
+  config: InfiniteScrollConfig<T>,
+): config is PageBasedConfig<T> {
+  return "fetchData" in config && typeof config.fetchData === "function";
+}
+
+/**
+ * Check if config is cursor-based pagination
+ */
+export function isCursorBasedConfig<T>(
+  config: InfiniteScrollConfig<T>,
+): config is CursorBasedConfig<T> {
+  return "paginationMode" in config && config.paginationMode === "cursor";
+}
+
+/**
+ * Check if value is a valid error
+ */
+export function isError(value: unknown): value is Error {
+  return value instanceof Error;
+}
+
+/**
+ * Check if value is a non-null object
+ */
+export function isNonNullObject<T>(value: T | null | undefined): value is T {
+  return value !== null && value !== undefined;
+}
+
+/**
+ * Check if array has items
+ */
+export function hasItems<T>(items: T[] | null | undefined): items is T[] {
+  return Array.isArray(items) && items.length > 0;
+}
+
+/**
+ * Check if string is not empty
+ */
+export function isNonEmptyString(value: string | null | undefined): value is string {
+  return typeof value === "string" && value.length > 0;
+}

package/src/infinite-scroll/index.ts

@@ -0,0 +1,62 @@
+/**
+ * React Native Infinite Scroll
+ *
+ * Modern infinite scroll system for React Native
+ * Follows SOLID, DRY, KISS principles
+ *
+ * Features:
+ * - Page-based and cursor-based pagination
+ * - Automatic retry with exponential backoff
+ * - Request cancellation with AbortController
+ * - Performance monitoring in __DEV__ mode
+ * - Full accessibility support
+ * - Type-safe utilities
+ */
+
+// Domain Layer
+export type {
+  InfiniteScrollConfig,
+  PaginatedResult,
+  PageBasedConfig,
+  CursorBasedConfig,
+} from "./domain/types/infinite-scroll-config";
+export type { InfiniteScrollState } from "./domain/types/infinite-scroll-state";
+export type { UseInfiniteScrollReturn } from "./domain/types/infinite-scroll-return";
+export type { InfiniteScrollListProps } from "./domain/interfaces/infinite-scroll-list-props";
+
+// Domain Utils
+export {
+  calculateEndReachedThreshold,
+  getPageSlice,
+  hasMoreItems,
+} from "./domain/utils/pagination-utils";
+
+// Type Guards
+export {
+  isPageBasedConfig,
+  isCursorBasedConfig,
+  isError,
+  isNonNullObject,
+  hasItems,
+  isNonEmptyString,
+} from "./domain/utils/type-guards";
+
+// Presentation Layer - Hooks
+export { useInfiniteScroll } from "./presentation/hooks/useInfiniteScroll";
+
+// Presentation Layer - Components
+export { InfiniteScrollList } from "./presentation/components/infinite-scroll-list";
+
+// Component Types
+export type {
+  EmptyProps,
+  ErrorProps,
+  LoadingProps,
+  LoadingMoreProps,
+} from "./presentation/components/types";
+
+// State Components
+export { Loading } from "./presentation/components/loading";
+export { LoadingMore } from "./presentation/components/loading-more";
+export { Empty } from "./presentation/components/empty";
+export { Error } from "./presentation/components/error";

package/src/infinite-scroll/presentation/components/empty.tsx

@@ -0,0 +1,44 @@
+/**
+ * Empty Component
+ *
+ * Presentation component for empty state
+ * Fully customizable via props
+ * Accessibility support included
+ */
+
+import React from "react";
+import { View, Text, StyleSheet } from "react-native";
+import type { EmptyProps } from "./types";
+
+export const Empty = React.memo<EmptyProps>(({
+  text = "No items found",
+  containerStyle,
+  textStyle,
+  accessibilityLabel = "Empty list",
+  ...accessibilityProps
+}) => (
+  <View
+    style={[styles.container, containerStyle]}
+    accessibilityLabel={accessibilityLabel}
+    accessibilityRole="text"
+    accessibilityValue={{ text }}
+    {...accessibilityProps}
+  >
+    <Text style={[styles.text, textStyle]}>{text}</Text>
+  </View>
+));
+
+Empty.displayName = "Empty";
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    justifyContent: "center",
+    alignItems: "center",
+    padding: 20,
+  },
+  text: {
+    fontSize: 16,
+    textAlign: "center",
+  },
+});

package/src/infinite-scroll/presentation/components/error.tsx

@@ -0,0 +1,66 @@
+/**
+ * Error Component
+ *
+ * Presentation component for error state
+ * Fully customizable via props
+ * Accessibility support included
+ */
+
+import React from "react";
+import { View, Text, StyleSheet, TouchableOpacity } from "react-native";
+import type { ErrorProps } from "./types";
+
+export const Error = React.memo<ErrorProps>(({
+  error,
+  onRetry,
+  retryText = "Tap to retry",
+  containerStyle,
+  errorTextStyle,
+  retryTextStyle,
+  accessibilityLabel,
+  retryAccessibilityHint = "Double tap to retry",
+  ...accessibilityProps
+}) => (
+  <View
+    style={[styles.container, containerStyle]}
+    accessibilityLabel={accessibilityLabel || `Error: ${error}`}
+    accessibilityRole="alert"
+    {...accessibilityProps}
+  >
+    <Text
+      style={[styles.errorText, errorTextStyle]}
+      accessibilityRole="text"
+    >
+      {error}
+    </Text>
+    <TouchableOpacity
+      onPress={onRetry}
+      accessibilityRole="button"
+      accessibilityLabel={retryText}
+      accessibilityHint={retryAccessibilityHint}
+    >
+      <Text style={[styles.retryText, retryTextStyle]}>{retryText}</Text>
+    </TouchableOpacity>
+  </View>
+));
+
+Error.displayName = "Error";
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    justifyContent: "center",
+    alignItems: "center",
+    padding: 20,
+  },
+  errorText: {
+    fontSize: 16,
+    textAlign: "center",
+    marginBottom: 8,
+  },
+  retryText: {
+    fontSize: 14,
+    textAlign: "center",
+    marginTop: 8,
+  },
+});

package/src/infinite-scroll/presentation/components/infinite-scroll-list.tsx

@@ -0,0 +1,120 @@
+/**
+ * InfiniteScrollList Component
+ *
+ * Presentation component for infinite scroll list
+ * Optimized with React.memo for performance
+ */
+
+import React from "react";
+import { FlatList } from "react-native";
+import { useInfiniteScroll } from "../hooks/useInfiniteScroll";
+import { calculateEndReachedThreshold } from "../../domain/utils/pagination-utils";
+import type { InfiniteScrollListProps } from "../../domain/interfaces/infinite-scroll-list-props";
+import { Loading } from "./loading";
+import { LoadingMore } from "./loading-more";
+import { Empty } from "./empty";
+import { Error } from "./error";
+
+/**
+ * Render error component
+ */
+function renderErrorComponent(
+  error: string,
+  retry: () => void,
+  errorComponent?: (error: string, retry: () => void) => React.ReactElement,
+): React.ReactElement {
+  if (errorComponent) {
+    return errorComponent(error, retry);
+  }
+  return <Error error={error} onRetry={retry} />;
+}
+
+/**
+ * InfiniteScrollList Component
+ *
+ * FlatList wrapper with automatic infinite scroll and pagination
+ *
+ * @example
+ * ```tsx
+ * <InfiniteScrollList
+ *   config={{
+ *     pageSize: 20,
+ *     threshold: 5,
+ *     fetchData: async (page, pageSize) => {
+ *       const response = await api.getItems({ page, limit: pageSize });
+ *       return response.data;
+ *     },
+ *   }}
+ *   renderItem={(item) => <ItemCard item={item} />}
+ * />
+ * ```
+ */
+function InfiniteScrollListComponent<T>({
+  config,
+  renderItem,
+  loadingComponent,
+  loadingMoreComponent,
+  emptyComponent,
+  errorComponent,
+  ListHeaderComponent,
+  ListFooterComponent,
+  flatListProps,
+}: InfiniteScrollListProps<T>): React.ReactElement {
+  const { items, state, loadMore, refresh, canLoadMore } = useInfiniteScroll(config);
+
+  const handleEndReached = React.useCallback(() => {
+    if (canLoadMore && config.autoLoad !== false) {
+      loadMore();
+    }
+  }, [canLoadMore, loadMore, config.autoLoad]);
+
+  const getItemKey = React.useCallback(
+    (item: T, index: number): string => {
+      if (config.getItemKey) {
+        return config.getItemKey(item, index);
+      }
+      return `item-${index}`;
+    },
+    [config],
+  );
+
+  // Loading state
+  if (state.isLoading) {
+    return loadingComponent || <Loading />;
+  }
+
+  // Error state
+  if (state.error) {
+    return renderErrorComponent(state.error, refresh, errorComponent);
+  }
+
+  // Empty state
+  if (items.length === 0 && !state.isLoading) {
+    return emptyComponent || <Empty />;
+  }
+
+  // Render list
+  return (
+    <FlatList
+      data={items}
+      renderItem={({ item, index }) => renderItem(item, index)}
+      keyExtractor={(item, index) => getItemKey(item, index)}
+      onEndReached={handleEndReached}
+      onEndReachedThreshold={calculateEndReachedThreshold(config.threshold)}
+      onRefresh={refresh}
+      refreshing={state.isRefreshing}
+      ListHeaderComponent={ListHeaderComponent}
+      ListFooterComponent={
+        <>
+          {ListFooterComponent}
+          {state.isLoadingMore && (loadingMoreComponent || <LoadingMore />)}
+        </>
+      }
+      {...flatListProps}
+    />
+  );
+}
+
+export const InfiniteScrollList = React.memo(InfiniteScrollListComponent) as <T>(
+  props: InfiniteScrollListProps<T>,
+) => React.ReactElement;

package/src/infinite-scroll/presentation/components/loading-more.tsx

@@ -0,0 +1,38 @@
+/**
+ * Loading More Component
+ *
+ * Presentation component for loading more state
+ * Fully customizable via props
+ * Accessibility support included
+ */
+
+import React from "react";
+import { View, ActivityIndicator, StyleSheet } from "react-native";
+import type { LoadingMoreProps } from "./types";
+
+export const LoadingMore = React.memo<LoadingMoreProps>(({
+  containerStyle,
+  size = "small",
+  color,
+  accessibilityLabel = "Loading more",
+  ...accessibilityProps
+}) => (
+  <View
+    style={[styles.container, containerStyle]}
+    accessibilityLabel={accessibilityLabel}
+    accessibilityRole="progressbar"
+    accessibilityState={{ busy: true }}
+    {...accessibilityProps}
+  >
+    <ActivityIndicator size={size} color={color} />
+  </View>
+));
+
+LoadingMore.displayName = "LoadingMore";
+
+const styles = StyleSheet.create({
+  container: {
+    padding: 16,
+    alignItems: "center",
+  },
+});

package/src/infinite-scroll/presentation/components/loading.tsx

@@ -0,0 +1,40 @@
+/**
+ * Loading Component
+ *
+ * Presentation component for loading state
+ * Fully customizable via props
+ * Accessibility support included
+ */
+
+import React from "react";
+import { View, ActivityIndicator, StyleSheet } from "react-native";
+import type { LoadingProps } from "./types";
+
+export const Loading = React.memo<LoadingProps>(({
+  containerStyle,
+  size = "large",
+  color,
+  accessibilityLabel = "Loading",
+  ...accessibilityProps
+}) => (
+  <View
+    style={[styles.container, containerStyle]}
+    accessibilityLabel={accessibilityLabel}
+    accessibilityRole="progressbar"
+    accessibilityState={{ busy: true }}
+    {...accessibilityProps}
+  >
+    <ActivityIndicator size={size} color={color} />
+  </View>
+));
+
+Loading.displayName = "Loading";
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    justifyContent: "center",
+    alignItems: "center",
+    padding: 20,
+  },
+});