npm package: @mbrain/epichug-react-native
Description: - `@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 hav
Latest version: 0.0.19

## 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](epichug/functions/FabButton.md) 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](./functions/sleep.md) `function`
  - Creates a pause in async code execution for the specified duration
- [getExpoPluginConfig](./functions/getExpoPluginConfig.md) `function`
  - Retrieves the configuration object for a specific Expo plugin from the app.json/app.config.js
- [useEpicDevMenu](./functions/useEpicDevMenu.md) `hook`
  - Extends the Expo development menu with: Sitemap, Theme preview
- [useOrientation](./functions/useOrientation.md) `hook`
  - Provides real-time screen orientation information and orientation lock status
- [useIsKeyboardVisible](./functions/useIsKeyboardVisible.md) `hook`
  - Detect if the virtual keyboard is currently visible on screen
- [useSortableList](./functions/useSortableList.md) `hook`
  - Hook for managing state and logic for drag-and-drop reorderable lists, with optimistic updates and error handling
- [useDebouncedChangeText](./functions/useDebouncedChangeText.md) `hook`
  - Hook that adds debouncing to text input changes to prevent excessive API calls or state updates
- [useDebouncedColorScheme](./functions/useDebouncedColorScheme.md) `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](./functions/colorWithOpacity.md) `function`
  - Utility function that adds opacity to any color format and returns an rgba string
- [createIntlService](./functions/createIntlService.md) `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](./functions/createLocalStorage.md) `function`
  - Returns localStorage object with methods for storing, retrieving, and observing changes to local data with automatic JSON serialization/deserialization and error handling
- [createFileStorage](./functions/createFileStorage.md) `function`
  - Creates a file storage service for uploading and managing files on backend servers
- [getZustandLocalStorage](./functions/getZustandLocalStorage.md) `function`
  - Creates a local storage adapter for Zustand persist middleware using MMKV
- [getTanstackLocalStorage](./functions/getTanstackLocalStorage.md) `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](./variables/JsStack.md) `component`
  - Expo router support for JavaScript Stack navigator, use it only if there is some explicit reason, otherwise use native stack
- [MaterialTopTabs](./variables/MaterialTopTabs.md) `component`
  - Expo router support for Material Top Tabs navigator
- [CustomBottomTabs](./functions/CustomBottomTabs.md) `component`
  - Customizable React Navigation bottom tab bar with blur effects, floating mode, and theme integration
- [ScreenContent](./variables/ScreenContent.md) `component`
  - A comprehensive screen wrapper component that handles safe areas, scrolling, and keyboard avoidance
  - ScreenContent props are defined in [ScreenContentProps](./type-aliases/ScreenContentProps.md) `type`
- [useLogRouteChange](./functions/useLogRouteChange.md) `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-aliases/Theme.md) `type`
    - Extended Material Design 3 theme with additional spacing and layout properties.
  - [ThemeValuePerSize](./type-aliases/ThemeValuePerSize.md) `type`
    - Responsive size-based value mapping for consistent spacing and sizing across the application.
  - [themeDefaults](./variables/themeDefaults.md) `variable`
    - Default theme values
- [AppThemeProvider](./functions/AppThemeProvider.md) `component`
  - React context provider for theme management with automatic system theme detection and persistence
  - [ThemesConfig](./type-aliases/ThemesConfig.md) `type`
  - [AppThemeContextValue](./type-aliases/AppThemeContextValue.md) `type`
  - [AppThemeProviderProps](./type-aliases/AppThemeProviderProps.md) `type`
- [useAppTheme](./functions/useAppTheme.md) `hook`
  - React hook for accessing the current application theme with full type safety
- [useNavigationTheme](./functions/useNavigationTheme.md) `hook`
  - Hook that converts the current app theme to React Navigation compatible theme format
- [ThemePreview](./variables/ThemePreview.md) `component`
  - Comprehensive theme preview component that displays all Material Design 3 colors and components
- [ThemePreviewButton](./variables/ThemePreviewButton.md) `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](./functions/SharedUiProvider.md) `component`
  - Context provider for shared UI elements including snackbars, dialogs, and theme preview
  - [SharedUiContextValue](./type-aliases/SharedUiContextValue.md)
  - [SharedUiProviderProps](./type-aliases/SharedUiProviderProps.md)
- [useSnackbar](./functions/useSnackbar.md) `hook`
  - Hook for managing snackbar notifications
  - [SnackbarConfig](./type-aliases/SnackbarConfig.md)
- [useDialog](./functions/useDialog.md) `hook`
  - Hook for managing modal dialogs
  - [DialogConfig](./type-aliases/DialogConfig.md)
- [useThemePreview](./functions/useThemePreview.md) `hook`
  - Hook for displaying theme preview modal

### Components

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

### Button Components

- [ThumbnailImage](./functions/ThumbnailImage.md) `component`
- [FabButton](./functions/FabButton.md) `component`
  - Themed floating action button with consistent positioning and styling
- [FabGroupButton](./functions/FabGroupButton.md) `component`
  - Enhanced floating action button group with smart visibility management
- [BackButton](./functions/BackButton.md) `component`
  - Themed navigation back button with automatic router integration
- [DrawerButton](./functions/DrawerButton.md) `component`
  - Themed drawer navigation button with automatic drawer integration
- [GradientButton](./functions/GradientButton.md) `component`
  - Customizable gradient button with advanced visual effects and theming

### Form Components

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

### Access Control

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

### Appwrite Backend Helpers

- [fromAppwriteUser](./functions/fromAppwriteUser.md) `component`
  - Converts raw Appwrite user object to standardized application user format
- [toAppwriteDoc](./functions/toAppwriteDoc.md) `component`
  - Converts JavaScript object to Appwrite document format for database operations
- [fromAppwriteDoc](./functions/fromAppwriteDoc.md) `component`
  - Converts Appwrite document to standard JavaScript object format