@gtcx/layouts-mobile

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

Installation

pnpm add @gtcx/layouts-mobile

Peer dependencies:

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

Usage

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

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