@gtcx/screens-mobile

Enterprise screen components for GTCX mobile applications. 18 full-page screens covering auth, dashboard, settings, search, document review, notifications, onboarding, and more.

Installation

pnpm add @gtcx/screens-mobile

Peer dependencies:

pnpm add react-native nativewind @gtcx/ui-mobile @gtcx/layouts-mobile

Usage

import { SignInScreen, DashboardScreen, DocumentScreen } from '@gtcx/screens-mobile';

// All screens are zero-business-logic — all state via props
function App() {
  return (
    <SignInScreen
      onSubmit={({ email, password }) => auth.signIn(email, password)}
      loading={auth.loading}
      error={auth.error}
    />
  );
}

Screens

Phase M — Core enterprise (12)

| Screen | Description | Key props | | ----------------------- | ----------------------------------------------- | --------------------------------------------- | | SignInScreen | Email/password sign-in form | onSubmit, loading, error | | SignUpScreen | Registration form | onSubmit, loading, error | | ForgotPasswordScreen | Email reset request | onSubmit, loading, success, error | | OtpVerificationScreen | 6-digit OTP input | onSubmit, onResend, loading, error | | DashboardScreen | KPI stats, activity feed, quick actions | stats, activity, actions, onAction | | AccountScreen | Profile view with avatar and nav sections | user, sections, onItemPress | | DataListScreen | Filterable, sortable, paginated data table | columns, rows, filters, onSort | | DetailScreen | Key-value entity detail with status and actions | title, sections, statusBadge, actions | | ApprovalsScreen | Approval queue with approve/reject per item | items, onApprove, onReject | | MembersScreen | Team member list with roles and invite | members, onMemberPress, onInvite |

Phase O — Enterprise extensions (6)

| Screen | Description | Key props | | --------------------- | ----------------------------------------------- | ----------------------------------------------- | | NotificationsScreen | Grouped notifications, unread badge, dismiss | notifications, onMarkAllRead, onDismiss | | TimelineScreen | Activity/audit history with filter tabs | entries, filters, onFilterChange | | SettingsScreen | iOS-style grouped settings: toggle, nav, action | sections, onItemPress, onToggleChange | | SearchScreen | Full-page search with recents, filters, results | value, onChangeText, recents, results | | DocumentScreen | Document viewer: metadata, attachments, audit | meta, attachments, auditTrail, actions | | OnboardingScreen | Multi-step onboarding with Stepper and Progress | steps, currentStepIndex, onNext, onBack |

Design principles

Zero business logic. Every screen is a pure UI component — all state, data, and callbacks flow in via props. No API calls, no routing, no stores inside screens.

Prop-driven state. Loading skeletons, empty states, error banners, and success messages are all controlled by props (loading, error, success, emptyMessage). The parent owns state; the screen renders it.

Consistent testID convention. Every screen element has a testID. Sub-elements follow ${testID}-subpart (e.g. document-heading, document-status-badge, document-action-approve). This makes integration testing deterministic.

Architecture

TypeScript shim

This package ships types/react-native.d.ts — a lightweight shim enabling typecheck and DTS generation without installing react-native. It is kept in sync with the source of truth at packages/ui-mobile/types/react-native.d.ts.

When to update the shim: If you add a screen that uses a React Native prop not yet declared (e.g. a new TextInput prop), add it to this shim AND to the matching shims in ui-mobile and layouts-mobile.

When to update the mock: If you use a new React Native component export (e.g. Animated, KeyboardAvoidingView), add it to tests/__mocks__/react-native.tsx.

Stories

Storybook stories live alongside each screen in src/<screen>/<screen>.stories.tsx. They are excluded from the package typecheck (stories are Storybook-only artifacts). The Storybook app at apps/storybook-native/ picks them up via glob.

Testing

pnpm --filter @gtcx/screens-mobile test       # 180 tests
pnpm --filter @gtcx/screens-mobile typecheck
pnpm --filter @gtcx/screens-mobile lint
pnpm --filter @gtcx/screens-mobile build

Contributing

• Follow the zero-business-logic principle — no API calls inside screens
• Add testIDs to every rendered element following the ${testID}-subpart pattern
• Write tests in tests/<phase>.test.tsx grouped by screen
• Update all three type shims when using a new React Native prop