npm package: @gtcx/screens-mobile
Description: GTCX mobile screen library — enterprise screens for React Native
Latest version: 0.1.0

# @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

```bash
pnpm add @gtcx/screens-mobile
```

Peer dependencies:

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

## Usage

```tsx
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

```bash
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