@codeimplants/ui-kit

Enterprise-grade error UI screens and components for React Native

Overview

@codeimplants/ui-kit provides beautiful, production-ready error screens and UI components for React Native applications. Designed with 100% customizability in mind, every pixel, color, and text can be controlled via props.

This package contains 22 unique screens categorized into four main domains: Errors, Network, Permissions, and System.

Project Structure

The package is organized into a modular structure for better maintainability and discoverability:

src/
├── components/       # Shared UI components (buttons, cards, icons, etc.)
├── screens/          # Full-screen views (errors, system, permissions)
├── types/            # Modular type definitions
├── utils/            # Utility functions
└── index.ts          # Public API export

Common Configuration

All screens share a set of common configuration props that unify the design and behavior across your app.

🎨 Theme & Styling

Customize the look and feel globally or per-screen using the theme prop.

<Screen
  theme={{
    primary: '#6200EE',       // Main brand color
    background: '#FFFFFF',    // Screen background
    surface: '#F5F5F5',       // Card/Input background
    textPrimary: '#000000',   // Main text color
    textSecondary: '#757575', // Subtitle text color
    error: '#B00020',         // Error state color
    success: '#00C853',       // Success state color
    warning: '#FFAB00',       // Warning state color
  }}
/>

🛠 Support Integration

Integrates seamlessly with @codeimplants/support. All screens accept a support prop to display contact options as a tray of circular buttons under the primary action. message/subject/body pre-fill the chat or mail draft, so support isn't left asking who is writing in.

<Screen
  support={{
    whatsapp: { number: '1234567890', label: 'Chat Support', message: 'Hi, I need help with…' },
    phone: { number: '1800-123-456', label: 'Call Us' },
    email: { address: '[email protected]', label: 'Email Us', subject: 'Support request' }
  }}
/>

For a pre-filled diagnostic report — app version, platform, OS, time, error, code, and which screen the user was on — build the message with the kit's own helpers rather than a local template, so every app reports in the same shape:

import { buildErrorContext, formatErrorForSupport } from '@codeimplants/ui-kit';

const report = formatErrorForSupport(
  buildErrorContext('Request timed out', { screenName: 'API Error', errorCode: '504' })
);
<Screen support={{ whatsapp: { number, message: report }, /* … */ }} />

Every report ends with a separator and a note asking the user not to delete the details above and to type below the line — otherwise a pre-filled draft reads as someone else's text and gets cleared before sending. Reword or translate it with initializeUIKit({ supportMessageFooter }). The version comes from that same initializeUIKit({ appVersion }) call, so make it early: without it every report claims 1.0.0.

The tray ships with WhatsApp, handset, and envelope glyphs in the kit's own colours (each exported individually — WhatsAppIcon, PhoneIcon, MailIcon — for reuse in an app's own support UI). Every part of it is overridable per app via supportButtons — no forking required:

<Screen
  support={supportContact}
  supportButtons={{
    // Per channel: icon, colours, size, a11y label, or a completely custom press handler
    whatsapp: { icon: <MyBrandChatIcon size={24} />, backgroundColor: '#25D366' },
    phone: { iconColor: '#FFF7ED', onPress: () => openInAppDialer() },
    email: { hidden: true },

    // Tray-wide
    channels: ['phone', 'whatsapp'],   // which channels, and in what order
    iconSize: 22,
    buttonSize: 48,
    caption: 'Talk to us',             // `null` removes the caption
    captionStyle: { color: '#64748B' },
    trayStyle: { backgroundColor: '#F1F5F9' },
    buttonStyle: { borderWidth: 1 },
    containerStyle: { marginTop: 12 },
    showStatusDot: false,              // the green "online" dot on WhatsApp
    statusDotColor: '#4ADE80',
  }}
/>

icon accepts any element, so an app can pass its own SVG, a lucide-react-native icon, or an <Image>. Channels with no matching support entry are skipped, and the tray renders nothing at all when none are configured.

The legacy supportVariant prop ('icon-only' | 'compact' | 'full') is a no-op — the tray is the only rendering. Use supportButtons instead.

🔄 Retry Logic

For error and network screens, the optional retryInfo prop displays attempt counts and limits.

<Screen
  onRetry={handleRetry}
  retryInfo={{
    attempt: 2,
    maxAttempts: 5
  }} // Displays "Retrying (2/5)..."
/>

Screen Reference

1. Error Screens (5 Screens)

Generic and specific handlers for API and runtime errors.

| Screen | Description | Key Props | |--------|-------------|-----------| | ApiErrorScreen | General API error handler. | onRetry, errorCode, statusCode | | ClientErrorScreen | Handler for 4xx series errors (e.g., 404). | statusCode, onGoBack | | ServerErrorScreen | Handler for 5xx series errors (e.g., 500). | statusCode, onRetry, retryInfo | | ErrorBoundaryScreen | Global fallback for app crashes. | error, errorDetails, onReset, icon, tips, tipsTitle, showTips, resetButtonStyle | | InvalidResponseScreen | For malformed/unexpected server data. | errorDetails, onReportError |

2. Network Screens (3 Screens)

Connectivity states handling.

| Screen | Description | Key Props | |--------|-------------|-----------| | NetworkOfflineScreen | No internet connection. | onRetry, tips (troubleshooting steps) | | NetworkSlowConnectionScreen | High latency / poor connection. | connectionSpeed, onContinue (ignore warning) | | ApiTimeoutScreen | Request timeout. | timeoutDuration, onRetry |

3. Permission Screens (4 Screens)

OS permission request flows.

| Screen | Description | Key Props | |--------|-------------|-----------| | PermissionScreen | Simple single-permission request. | permissionType, onAllow, onDeny | | PermissionRequestScreen | Detailed request with "Why we need this". | reasons (array), icon | | PermissionDeniedScreen | Help screen when permission is permanently denied. | steps (how to enable in settings), onOpenSettings | | MultiPermissionRequestScreen| Request multiple permissions in one flow. | permissions (array of status objects) |

4. System Screens (10 Screens)

App lifecycle and maintenance events.

Update Screens: | Screen | Description | Key Props | |--------|-------------|-----------| | AppUpdateScreen | Unified update handler (soft/force/security). | updateType, newVersion, releaseNotes | | SoftUpdateScreen | Optional update with "Skip" option. | features, onSkip | | OptionalUpdateScreen | Standard update with "Remind Later". | onMaybeLater | | ForceUpdateScreen | Mandatory blocking update. | onUpdate (no skip option) | | SecurityUpdateScreen | Critical security patch alert. | features (security fixes details) |

Maintenance Screens: | Screen | Description | Key Props | |--------|-------------|-----------| | SystemMaintenanceScreen | Unified maintenance handler. | type (planned/emergency), estimatedEndTime | | PlannedMaintenanceScreen | Scheduled maintenance with countdown. | onNotifyWhenBack | | UnplannedOutageScreen | Unexpected downtime apology. | onCheckAgain | | EmergencyOutageScreen | Critical service failure. | incidentDetails, onGetUpdates | | ServiceUnavailableScreen | 503 Service Unavailable fallback. | onRetry |

Installation

npm install @codeimplants/ui-kit @codeimplants/support

Platform Compatibility

| Platform | Status | |----------|--------| | iOS | ✅ | | Android | ✅ | | Web (React Native Web) | ✅ | | Expo | ✅ | | Bare React Native | ✅ |

License

MIT