@gtcx/ui-mobile

Mobile UI component library for the GTCX ecosystem. 27 primitive and enterprise components built with NativeWind v4.

Installation

pnpm add @gtcx/ui-mobile

Peer dependencies (installed by your Expo/React Native app):

pnpm add react-native nativewind

Usage

import { Button, Card, Badge, Timeline } from '@gtcx/ui-mobile';

function MyScreen() {
  return (
    <Card>
      <Badge variant="success">Active</Badge>
      <Timeline entries={entries} />
      <Button variant="primary" onPress={handleSubmit}>
        Submit
      </Button>
    </Card>
  );
}

All components use the NativeWind v4 className API — no StyleSheet.create, no hardcoded hex values. Styling is done exclusively through utility classes and CSS variables.

Components

Phase K — Foundation (17)

| Component | Import | Description | | --------- | ------------------------------------ | ------------------------------------------------------------------------------------------------- | | Alert | Alert | Inline status message. Variants: default, success, warning, error, info | | Avatar | Avatar | Circular user avatar with image fallback and initials | | Badge | Badge | Inline status/count label | | Button | Button | Interactive button. Variants: primary, secondary, outline, ghost, destructive. Supports loading | | Card | Card, CardHeader | Container with optional header slot | | DataGrid | DataGrid | Sortable, paginated data table | | Input | Input | Text input with label, hint, and error state | | Modal | Modal | Full-screen or bottom-sheet modal overlay | | Progress | Progress | Linear progress bar (value 0–100) | | Select | Select | Native picker with option list | | Separator | Separator | Horizontal or vertical divider | | Skeleton | Skeleton | Shimmer loading placeholder | | Stepper | Stepper | Multi-step progress indicator | | Switch | Switch | Accessible toggle | | Tabs | Tabs | Horizontal tab group | | TextArea | TextArea | Multi-line text input | | Toast | Toast, ToastProvider, useToast | Ephemeral notification system |

Phase N — Extended (10)

| Component | Import | Description | | -------------- | ---------------- | ------------------------------------------------------------- | | ActionSheet | ActionSheet | Bottom sheet action menu with cancel group | | Chip | Chip | Selectable/dismissible tag chip | | EmptyState | EmptyState | Zero-state placeholder with icon, title, description, actions | | FileAttachment | FileAttachment | File row with type badge, upload progress, status | | ListItem | ListItem | Row with leading/trailing slots, title, subtitle, chevron | | NumberStepper | NumberStepper | Increment/decrement control with min/max/step | | SearchBar | SearchBar | Search input with clear and optional cancel button | | Segmented | Segmented | Horizontal radio tab group | | SparkLine | SparkLine | Tiny bar chart for stat tiles. No SVG dependency | | Timeline | Timeline | Vertical activity list with status dots and connectors |

Architecture

NativeWind v4 className API

All components receive a className prop for style customisation:

<Button className="mt-4" variant="primary">Submit</Button>
<Badge className="ml-2" variant="success">Active</Badge>

TypeScript shim

This package ships a lightweight types/react-native.d.ts shim that enables typecheck and DTS generation without installing the full react-native package. The real react-native is resolved at runtime by the consumer's Expo/React Native environment.

Maintaining the shim: When you use a React Native prop that is not yet declared in the shim, add it to types/react-native.d.ts. This shim is the source of truth — also update the parallel shims in packages/layouts-mobile and packages/screens-mobile.

Test mock pattern

Vitest tests use a DOM-based mock at tests/__mocks__/react-native.tsx. The mock maps React Native primitives (View, Text, Pressable, TextInput, Modal, etc.) to their HTML equivalents so @testing-library/react can query them in jsdom.

When adding a new React Native component export to the shim, add a corresponding mock entry.

Testing

pnpm --filter @gtcx/ui-mobile test
pnpm --filter @gtcx/ui-mobile typecheck
pnpm --filter @gtcx/ui-mobile lint
pnpm --filter @gtcx/ui-mobile build

Contributing

• All components use className — no StyleSheet, no hardcoded colors
• All interactive elements have accessibilityRole and accessibilityLabel
• All rendered elements have a testID prop (sub-parts follow ${testID}-subpart convention)
• Zero business logic in components — all state via props