EPICHUG LIBRARY

• @mbrain/epichug-react-native is a React Native library with a lot of utility functions and components. Use it whenever you can.
• Also you can suggest changing or adding things to this library, its under programmers control.
• All epichug elements have linked documentation files
  • ALWAYS read the documentation file before using any element
  • The documentation contains the correct props, usage examples, and styling options
  • For example FabButton is linked to its docs etc.
• Example imports
  • import {sleep} from '@mbrain/epichug-react-native';
  • import {appwriteFileStorageProvider} from '@mbrain/epichug-react-native/appwrite';

Utils

General utility functions and hooks for common React Native development tasks.

• sleep function
  • Creates a pause in async code execution for the specified duration
• getExpoPluginConfig function
  • Retrieves the configuration object for a specific Expo plugin from the app.json/app.config.js
• useEpicDevMenu hook
  • Extends the Expo development menu with: Sitemap, Theme preview
• useOrientation hook
  • Provides real-time screen orientation information and orientation lock status
• useIsKeyboardVisible hook
  • Detect if the virtual keyboard is currently visible on screen
• useSortableList hook
  • Hook for managing state and logic for drag-and-drop reorderable lists, with optimistic updates and error handling
• useDebouncedChangeText hook
  • Hook that adds debouncing to text input changes to prevent excessive API calls or state updates
• useDebouncedColorScheme hook
  • Hook that debounces color scheme changes to prevent rapid theme switching and UI flickering, it should be used instead of React Native useColorScheme
• colorWithOpacity function
  • Utility function that adds opacity to any color format and returns an rgba string
• createIntlService function
  • Creates an internationalization service with device locale detection, language matching, and React hooks for i18next integration

Storage

Use these functions for local storage and for file storage (uploading files to server)

• createLocalStorage function
  • Returns localStorage object with methods for storing, retrieving, and observing changes to local data with automatic JSON serialization/deserialization and error handling
• createFileStorage function
  • Creates a file storage service for uploading and managing files on backend servers
• getZustandLocalStorage function
  • Creates a local storage adapter for Zustand persist middleware using MMKV
• getTanstackLocalStorage function
  • Creates a local storage adapter for TanStack React Query persistence using MMKV

Navigation

Components and functions that you can use with expo-router.

• JsStack component
  • Expo router support for JavaScript Stack navigator, use it only if there is some explicit reason, otherwise use native stack
• MaterialTopTabs component
  • Expo router support for Material Top Tabs navigator
• CustomBottomTabs component
  • Customizable React Navigation bottom tab bar with blur effects, floating mode, and theme integration
• ScreenContent component
  • A comprehensive screen wrapper component that handles safe areas, scrolling, and keyboard avoidance
  • ScreenContent props are defined in ScreenContentProps type
• useLogRouteChange hook
  • Logs to console route path change in dev environment

Theming

Theming is accomplished by extending react-native-paper's MD3Theme with a custom Theme type that includes additional design tokens (gap, border, margin, padding, roundness), managed through an AppThemeProvider that handles system theme detection and localStorage persistence, and consumed via the useAppTheme hook.

• Theme types used to create custom themes
  • Theme type
    • Extended Material Design 3 theme with additional spacing and layout properties.
  • ThemeValuePerSize type
    • Responsive size-based value mapping for consistent spacing and sizing across the application.
  • themeDefaults variable
    • Default theme values
• AppThemeProvider component
  • React context provider for theme management with automatic system theme detection and persistence
  • ThemesConfig type
  • AppThemeContextValue type
  • AppThemeProviderProps type
• useAppTheme hook
  • React hook for accessing the current application theme with full type safety
• useNavigationTheme hook
  • Hook that converts the current app theme to React Navigation compatible theme format
• ThemePreview component
  • Comprehensive theme preview component that displays all Material Design 3 colors and components
• ThemePreviewButton component
  • Button component that opens the comprehensive theme preview in a full-screen modal.

Shared UI Components

Shared UI components including snackbars, dialogs, and theme preview.

• SharedUiProvider component
  • Context provider for shared UI elements including snackbars, dialogs, and theme preview
  • SharedUiContextValue
  • SharedUiProviderProps
• useSnackbar hook
  • Hook for managing snackbar notifications
  • SnackbarConfig
• useDialog hook
  • Hook for managing modal dialogs
  • DialogConfig
• useThemePreview hook
  • Hook for displaying theme preview modal

Components

• Logo component
  • Flexible logo component with icon, title, subtitle, and decorative text elements
• ThumbnailImage component
  • Displays an image thumbnail with fallback to a default icon.
• Effect component
  • Applies various visual effects to its child components (none, blur, color, gradient, hueShift, sepia)
  • Effect variants props
    • EffectVariantNoneProps)
    • EffectVariantColorProps)
    • EffectVariantBlurProps)
    • EffectVariantGradientProps)
    • EffectVariantHueShiftProps)
    • EffectVariantSepiaProps)
• ThemePicker component
  • Interactive theme selection component with radio button interface
• LanguagePicker component
  • Interactive language selection component with radio button interface
  • LanguagePickerProps)
• LeanText component
  • LeanText is using RCTText directly, so its faster then Text
• LeanView component
  • LeanView is using RCTView directly, so its faster then View
• CustomSplashScreen component
  • Customizable splash screen component with animation support and overtime handling
• JellyList component
  • Animated FlatList component with dynamic skew effects during scrolling
• BackupData component
  • Complete backup and restore solution for app data management
• AuthForm component
  • Complete authentication form with login, registration, and password reset modes

Button Components

• ThumbnailImage component
• FabButton component
  • Themed floating action button with consistent positioning and styling
• FabGroupButton component
  • Enhanced floating action button group with smart visibility management
• BackButton component
  • Themed navigation back button with automatic router integration
• DrawerButton component
  • Themed drawer navigation button with automatic drawer integration
• GradientButton component
  • Customizable gradient button with advanced visual effects and theming

Form Components

• FieldErrors component
  • Displays validation errors for form fields integrated with React Hook Form, mostly used from field components: TextInputField, SwitchField, ImagePickerField etc.
• FormRootErrors component
  • Displays form-level validation errors that are not tied to specific fields, i.e. "root" errors in React Hook Form
• TextInputField component
  • Wrapper around Paper TextInput, with react-hook-form integration and several additional props
• SelectField component
  • Enhanced select dropdown component with optional React Hook Form integration
• SwitchField component
  • Wrapper around Paper Switch, with react-hook-form integration and several additional props
• ImagePickerField component
  • Image picker field component with optional react-hook-form integration.
  • BaseImagePickerFieldProps type

Access Control

• AccessControlProvider component
  • Provider component for role-based access control system
  • AccessControlContextValue type
  • AccessControlProviderProps type
• useAccessControl component
  • Hook for accessing role-based access control data with localization support
• PermissionsGroups component
  • Component that displays a list of permission groups with navigation support, its usually used together with PermissionsEdit
• PermissionsEdit component
  • Component for editing role-based permissions within a specific permission group, its usually used together with PermissionsGroups
• useAbility component
  • React hook for checking if the current user has a specific permission
• useAllAbilities component
  • React hook for checking if the current user has ALL of the specified permissions
• useSomeAbilities component
  • React hook for checking if the current user has ANY of the specified permissions
• validatePermissions component
  • Comprehensive validation function for access control system configuration
• Access control types
  • Roles type
    • Array of role identifiers in the access control system
  • PermGroup type
    • Permission group definition that organizes related permissions into logical categories
  • Permission type
    • Core permission definition that controls access to specific features or actions
  • Translations type
    • Complete translation configuration for the entire access control system

Appwrite Backend Helpers

• fromAppwriteUser component
  • Converts raw Appwrite user object to standardized application user format
• toAppwriteDoc component
  • Converts JavaScript object to Appwrite document format for database operations
• fromAppwriteDoc component
  • Converts Appwrite document to standard JavaScript object format