npm package: @gtcx/layouts-mobile
Description: GTCX mobile layout shells — React Native + NativeWind v4
Latest version: 0.1.0

# @gtcx/layouts-mobile

Mobile app shell components for the GTCX ecosystem. 5 layout shells covering the full range of enterprise mobile navigation patterns.

## Installation

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

Peer dependencies:

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

## Usage

```tsx
import { TabShell, StackShell } from '@gtcx/layouts-mobile';

// Bottom tab navigation
function App() {
  return (
    <TabShell
      tabs={[
        { id: 'home', label: 'Home', icon: <HomeIcon /> },
        { id: 'search', label: 'Search', icon: <SearchIcon /> },
      ]}
      activeTabId="home"
      onTabPress={(id) => navigate(id)}
    >
      <HomeScreen />
    </TabShell>
  );
}

// Standard screen with sticky header
function ProfileScreen() {
  return (
    <StackShell title="Profile" onBack={() => router.back()}>
      <ProfileContent />
    </StackShell>
  );
}
```

## Shells

### Phase L — Foundation (4)

| Shell      | Import       | Description                                                       |
| ---------- | ------------ | ----------------------------------------------------------------- |
| ModalShell | `ModalShell` | Full-screen modal with header, back/close button, optional footer |
| SplitShell | `SplitShell` | Master/detail layout for tablets                                  |
| StackShell | `StackShell` | Standard screen: sticky header + scrollable body + optional back  |
| TabShell   | `TabShell`   | Bottom tab bar with icon, label, badge support                    |

### Phase N-L — Extended (2)

| Shell                  | Import                   | Description                                                              |
| ---------------------- | ------------------------ | ------------------------------------------------------------------------ |
| CollapsibleHeaderShell | `CollapsibleHeaderShell` | Scroll-driven header collapse — large title transitions to compact title |
| SearchShell            | `SearchShell`            | Full-screen search overlay with recents, results, loading, empty states  |

## Architecture

### NativeWind v4 className API

All shells use the NativeWind v4 `className` API. No `StyleSheet.create`, no hardcoded values.

### TypeScript shim

This package ships `types/react-native.d.ts` — a lightweight shim enabling typecheck and DTS generation. 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 shell that uses a React Native prop not yet declared, add it to this shim AND to the other two shims in `ui-mobile` and `screens-mobile`. Also add the component to `tests/__mocks__/react-native.tsx` if it's a new export.

### Scroll events (CollapsibleHeaderShell)

`CollapsibleHeaderShell` uses `onScroll` with `scrollEventThrottle` — both are declared in the shim's `ScrollViewProps`. The collapse threshold is 60px (configurable via `collapseThreshold` prop).

## Testing

```bash
pnpm --filter @gtcx/layouts-mobile test
pnpm --filter @gtcx/layouts-mobile typecheck
pnpm --filter @gtcx/layouts-mobile lint
pnpm --filter @gtcx/layouts-mobile build
```

## Contributing

- All shells are zero-business-logic — all state and callbacks via props
- testID sub-parts follow `${testID}-subpart` convention
- All interactive elements have `accessibilityRole` and `accessibilityLabel`