npm package: @gtcx/ui-mobile
Description: GTCX mobile UI component library — React Native + NativeWind v4
Latest version: 0.1.0

# @gtcx/ui-mobile

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

## Installation

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

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

```bash
pnpm add react-native nativewind
```

## Usage

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

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

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