Skill: yahongie2014/react-native-clean-pattern (version 1.0.5)

--- name: clawhub-mobile description: Clawhub master skill for Expo/React Native. Production-grade patterns: MVC-Lite, RTL-First, Centralized Hook Styles, Zero-Any TS, and Sentry-Integrated Logging. --- # 📱 Clawhub React Native (Expo) Master Skill A unified, intelligent guide for building and maintaining high-performance mobile applications within the **Clawhub** ecosystem. ## 📥 Installation ### 1. Register the Skill: Add this directory to your agent's skill path. ### 2. Environment Setup: Ensure you have the following global dependencies installed: ```bash npm install -g expo-cli eas-cli react-native-clean-pattern ``` OR ```bash bun clawdhub install react-native-clean-pattern ``` ## ⌨️ Usage ### To start a new project: ```bash /provision-app ``` ### To scaffold a new feature/screen: ```bash /make-screen ``` ### To scaffold a new component: ```bash /make-component ``` ### To setup API or Navigation infrastructure: ```bash /setup-api /setup-navigation ``` --- ## 🚀 §0 — Execution & Workflow Standards Follow these steps for any task in the Clawhub ecosystem: 1. **STRATEGIZE**: Identify if the task is **Provisioning** (New App), **Expansion** (New Screen/Feature), or **Diagnosis** (Bug Fix). 2. **AUDIT & CLEAN**: Before adding new code, check for **Duplicated Files** or redundant logic. Reuse existing `@shared` components or `@hooks`. 3. **SCAFFOLD**: If expanding, always create the 4-file MVC-Lite structure. 4. **STYLING**: Initialize `getStyles` using the `useAppStyle()` hook for RTL-compliance. Use HSL tokens from `@styles/common`. 5. **INTEGRATE**: Connect UI logic to `controller.ts`, utilizing `@hooks/useRedux` and `@services/apiClient`. 6. **SECURE & OPTIMIZE**: Ensure `mountedRef` is used in all async controllers to prevent **Memory Leaks**. 7. **VERIFY**: Run `npx tsc --noEmit` and check RTL/LTR UI toggle. --- ## 🏗️ §1 — Project Architecture & Path Aliases Standardized, strictly typed, and RTL-ready folder architecture. All files must be interconnected via aliases. ```text . ├── app/ # Expo Router (routes & layouts) ├── screens/ # Feature-specific implementations (MVC-Lite) ├── components/ # Distributed Atom/Molecule components │ ├── [RegularComponent]/ # Regular/Feature components (e.g., DynamicIsland) │ └── SharedComponent/ # Global blessed component library (@shared) ├── services/ # Infrastructure (API, Auth, Firebase, Storage) ├── store/ # State Management (Redux Power Slices) ├── hooks/ # Custom logical hooks (@hooks) ├── helpers/ # Shared pure logic & utilities (@helpers) ├── enums/ # Global Constants & Types (@enums) ├── styles/ # Design Token System (@styles) ├── i18n/ # Localization assets (@i18n) └── assets/ # Media & Fonts (@assets) ``` ### ⭐ Path Alias Enforcement Never use relative paths (`../../`). Always use: `@shared`, `@services`, `@hooks`, `@store`, `@helpers`, `@config`, `@styles`, `@enums`. --- ## §1.1 — Standardized Enums (`@enums`) Use these enums to ensure zero `string-literal` errors across the app. | Enum | Key Values | |:---|:---| | `AuthScreen` | `LOGIN`, `REGISTER`, `FORGOT_PASSWORD`, `OTP_VERIFY` | | `ValidationRule` | `REQUIRED`, `EMAIL`, `MIN_LENGTH`, `MATCH` | | `UserType` | `USER`, `VENDOR`, `ADMIN`, `DELIVERY_BOY` | | `TokenKey` | `ACCESS_TOKEN`, `REFRESH_TOKEN`, `FCM_TOKEN` | --- ## §1.2 — Core Application Hooks (`@hooks`) | Hook | Responsibility | |:---|:---| | `useAppDispatch` / `useAppSelector` | Strictly typed Redux access. | | `useRTL` | Manages `I18nManager` force-flipping and app reloads. | | `useAppStyle` | Dynamic UI pipe that merges base themes with remote config, resolves RTL directionality (rowDirection, textAlign), and provides centralized design tokens and localized font resolution. | | `useAppConfig` | Reactive access to merged Local/Remote Config. | | `useColorScheme` | Reactive system theme detection (Light/Dark mode). | | `useNotifications` | Orchestrates FCM registration, Notifee channel management, and real-time state rehydration (Profile/Theme) upon receipt of push payloads. | --- ## 📦 §2 — Core Modules (The Gold Standards) ### 2.1 Configuration System (`@config`) Environment-driven, strictly typed central config: - **Environment**: Mapped to `.env` variables via `process.env`. - **Typing**: Governed by the `AppConfig` interface. - **Safety**: Includes fallbacks and platform-specific logic. ### 2.2 API Client (`@services/apiClient`) Singleton wrapper with: - **Auth**: Automatic Bearer token injection. - **I18n**: Reactive `Accept-Language` headers. - **Payloads**: Native support for `JSON` and `FormData`. - **Logging**: Detailed request/response tracing with duration. ### 2.3 Auth Service (`@services/authService`) Orchestrator for Login, Register, OTP, and Profile management with: - **Multi-Method Support**: Native handling for `EMAIL_PASSWORD`, `EMAIL_OTP`, and `PHONE_OTP`. - **UserType Injection**: Context-aware management of delivery, vendor, or customer states. - **Redux Integration**: Synchronized state for OTP sending status and active auth methods. ### 2.4 Firebase Service (`@services/firebaseService`) Platform-aware initialization for Expo Go and Development Builds. ### 2.5 Notification Service (`@services/notificationService`) Management of paginated alert listing and "read" state synchronization. ### 2.6 Security Storage (`@services/tokenStorage`) Encrypted or AsyncStorage persistence for tokens and user metadata. ### 2.7 Consolidated Logging (`@helpers/logger`) Sensitized logging system with: - **Redaction**: Automatic sanitization of sensitive fields (`password`, `token`, `authorization`, `otp`). - **Tracing**: Structured `request()`, `response()`, and `error()` tracing with latency tracking. - **Observability**: Seamless Sentry integration via `addBreadcrumb` and `captureException`. - **Environment Aware**: Debug-only rich formatting (`__DEV__`) with terminal icons (🌐, ✅, ❌, 🔴, ℹ️, ⚠️). ### 2.8 Localization (`@i18n`) RTL-First standard with: - **Engine**: `i18next` with `compatibilityJSON: 'v3'` for React Native safe pluralization. - **Persistence**: Mandatory `AsyncStorage` usage to remember language selection across reloads. - **Hypdration**: `initializeI18n()` async boot sequence required in `_layout.tsx`. - **RTL**: `I18nManager` force-flip with `expo-updates` reload (try/catch protected). - **State Sync**: Must use a callback pattern for Redux synchronization; NEVER import `store` directly into the i18n instance. - **Reload**: Integration with `expo-updates` for mandatory UI rehydration on direction change. - **Sync**: `setupRTL()` boot helper to maintain state consistency. ### 2.9 Redux Toolkit Power Slices (`@store`) Strictly typed state management with: - **Hooks**: Mandatory use of `useAppDispatch` and `useAppSelector` for type-safe state access. - **Pillars**: Auth (Session/User/AuthMethod), App (Theme/Language/RTL), and Notification (Alerts) slices. --- ## 🧩 §3 — Standard Component Library (@shared) | Component | Purpose | Key Props | |:---|:---|:---| | `AppText` | Typography with RTL font scaling. | `variant`, `weight`, `align` | | `Button` | Themed touchable with loading states. | `title`, `loading`, `icon`, `variant` | | `AppHeader` | RTL-aware screen header with back/actions. | `title`, `showBackButton`, `rightComp` | | `AppInput` | Validated text input with icons. | `label`, `error`, `icon`, `secure` | | `PriceTag` | Currency-aware formatted price display. | `price`, `originalPrice`, `discount` | | `AppLoader` | Lottie-powered full-screen or inline loading. | `visible`, `variant`, `message` | | `AppModal` | Standardized bottom-sheet or center popup. | `visible`, `onClose`, `title` | --- ## 🛠️ §4 — Standard Feature Modules Implemented as isolated folders under `screens/` following MVC-Lite: 1. **Auth Flow**: Sign In, Sign Up, OTP, Password Recovery. 2. **Catalog**: Product List (FlashList optimized), Category Browse. 3. **Cart & Checkout**: Multi-step checkout, Order Summary, Payments. 4. **Profile**: User Details, Address Management, Order History. --- ## 📚 §5 — Approved Dependency Matrix * **Core**: `expo@~55.0.5`, `react@19.2.0`, `react-native@0.83.2`. * **Navigation**: `@react-navigation/native`, `@react-navigation/native-stack`, `@react-navigation/bottom-tabs`. * **Standards**: Dynamic configuration-driven Bottom Tabs and Auth/Guest gating with Navigator-level `key` remounting. * **State & Logic**: `@reduxjs/toolkit@^2.11.2`, `react-redux@^9.2.0`. * **Networking & Auth**: `@react-native-firebase/app`, `@react-native-firebase/messaging`. * **Persistence**: `@react-native-async-storage/async-storage@^2.2.0`. * **Internationalization**: `i18next@^25.8.16`, `react-i18next@^16.5.6`, `expo-localization`. * **UI & Visuals**: `lottie-react-native@~7.3.4`, `react-native-reanimated@4.2.1`, `react-native-render-html`. * **Maps & Location**: `react-native-maps`, `react-native-maps-directions`, `expo-location`. * **Typography**: `@expo-google-fonts/cairo`, `@expo-google-fonts/outfit`, `@expo-google-fonts/roboto`. * **Observability**: `@sentry/react-native@~7.11.0`. * **Native Features**: `@notifee/react-native`, `expo-image-picker`, `expo-document-picker`. --- ## 🧱 §6 — Expansion Pattern (MVC-Lite) Every new screen, feature, OR shared component MUST consist of exactly 4 files: 1. **`index.tsx` (Skin)**: Pure JSX. Connects to `controller.ts`. 2. **`controller.ts` (Brain)**: logic hook, utilizes `@hooks/useRedux`. 3. **`styles.ts` (Nerves)**: Function-based styles consuming `useAppStyle`. 4. **`types.ts` (Structure)**: Interface definitions. Zero `any`. --- ## 🛡️ §7 — Defensive Coding & Security * **Memory Safety**: Always use `isMounted` ref in controllers. Abort all API calls in `useEffect` cleanup. * **Zero Duplication**: Shared logic must stay in `@hooks` or `@helpers`. Don't copy-paste styles; use `@styles/common`. **Hard Requirement**: All sizes, spacing, and colors must be consumed via `useAppStyle().tokens` and `useAppStyle().colors`. * **Zero Hardcoding**: Using literal hex codes (`#FFFFFF`) or RGBA strings in UI components is FORBIDDEN. All UI colors must be resolved from the `colors` object provided by the central styling hook. * **Zero Inline Styles**: Using the `style={{ ... }}` prop in JSX is FORBIDDEN for layout and presentation. All styles MUST be defined in the accompanying `styles.ts` file and resolve via the screen/component controller to ensure theme and RTL reactivity. * **Branding Sync**: Primary theme colors MUST be defined in `src/config/index.ts` and consumed via `@constants/Colors.ts` to support white-labeling and remote branding. * **RTL Enforcement**: Use `rowDirection` and `textAlign` from `useAppStyle`. * **Sanitization**: Never log raw bodies containing `password` or `token`. * **Absolute Paths**: All imports MUST use standardized aliases. Relative paths (`../../`) are forbidden. * **Standard Aliases**: `@/`, `@components`, `@hooks`, `@constants`, `@store`, `@i18n`, `@assets`, `@config`, `@app-types`, `@enums`, `@utils`, `@helpers`, `@services`, `@screens`, `@styles`. --- ## ✅ §8 — Verification Checklist 1. [ ] `npx tsc --noEmit` passes with zero errors. 2. [ ] i18n RTL/LTR layout flip verified. 3. [ ] No hardcoded colors/spacing outside of `@styles/common`. 4. [ ] No relative paths found in imports. 5. [ ] Async logic verified for `mountedRef` safety. --- ## 🏗️ §9 — Provisioning Guide (Training) When starting a **NEW** application, you must follow this interactive training flow to ensure architectural integrity without merely copy-pasting old classes. ### 1. The Inquiry Phase You **MUST** ask the user for authorization to implement: - **Project Identity**: Targeted app name and bundle identifier. - **Localization**: RTL support needs and target languages (LTR: EN, ES, FR, etc. | RTL: AR, HE, FA, etc.). - **Core Screens**: - `app/_layout.tsx`: Master orchestrator (Sentry, Redux, RTL, Hydration). - `app/(auth)`: Auth flow group (Login, Register, OTP). - `app/(tabs)`: Main application navigation. - **Core Auth**: Login, Register, OTP, and Forgot Password recovery screens. - **State Architecture**: Redux Toolkit (Auth/App/Notify slices). - **Native Bridges**: Firebase Messaging and Notifee. - **Observation Layer**: Sentry integration and Custom Logger. - **Persistence**: Encrypted Token Storage. ### 2. The Structural Blueprint Instead of copying files, generate fresh implementations based on these patterns: - **Auth (MVC-Lite)**: Each screen (`Login`, `Register`, `OTP`) gets its own `Skin`, `Brain`, `Nerves`, and `Structure`. - **Services**: Freshly authored `apiClient.ts` and `authService.ts`. - **Global Store**: A clean Redux initialization with strictly typed slices. ### 3. The Activation Loop 1. **Initialize**: Generate the `package.json`, `tsconfig.json`, and `app.json`. 2. **Install**: Run `npm install` or `bun install` to pull the **Approved Dependency Matrix**. 3. **Environment**: Create the `.env` file from the `.env.example` template. 4. **Launch**: Execute `npx expo start` to verify the baseline. ## ⌨️ §10 — Workflow & Slash Command Reference Use these commands to automate common development tasks within the Clawhub ecosystem: | Command | Purpose | When to Use | | :--- | :--- | :--- | | `/provision-app` | **Initialize Project** | Starting a new app from scratch. | | `/setup-api` | **API & Observability** | Adding a production-grade `apiClient.ts` and `logger.ts`. | | `/setup-navigation` | **Router Setup** | Scaffolding Root (Auth) and Main (Dynamic Tab) navigators. | | `/make-screen` | **Feature Scaffolding** | Creating a new screen using the 4-file MVC-Lite pattern. | | `/make-component` | **UI Scaffolding** | Creating a new **Shared**, **Regular**, or **Local** component. | --- ## 🔗 Author & Links - **GitHub**: [yahongie2014](https://github.com/yahongie2014) - **Website**: [coder79.me](https://coder79.me)

path: CHANGELOG.md
content: # Changelog

All notable changes to the **Clawhub Mobile (React Native)** standard and project components will be documented in this file.

The format is based on [Github](http://github.com/yahongie2014/), and this project adheres to [website](https://coder79.me).

## [1.0.0] - 2026-04-07

### ✨ Added
- **Clawhub Mobile Skill**: Created standardized `.agents/skills/clawhub-mobile/SKILL.md` for intelligent agent guidance.
- **Master Skill Migration**: Rebranded and cleaned `expo-master.md` to align with Clawhub architecture.
- **ProductDetail Example**: Implemented a reference feature screen demonstrating the mandatory 4-file pattern:
  - `index.tsx` (Pure UI / 4-State Rendering)
  - `controller.ts` (Logic / Memory-safe Hooks)
  - `styles.ts` (HSL-Tailored / RTL-aware Functional Styles)
  - `types.ts` (Strict Data Interfaces)

### 🏗️ Architecture
- **Separation of Concerns**: Enforced Pure UI / Logic Controller separation.
- **Type Safety**: Implemented strict TypeScript configuration (Zero `any`).
- **Memory Safety**: Standardized `useMountedRef` check for all async state updates.
- **Localization**: Added RTL support and `i18next` integration patterns for Arabic/English switching.

### 🍱 Design System
- **HSL Color Palette**: Integrated high-trust HSL-based color tokens for primary, accent, and error states.
- **Tailored Font Sizes**: Established a responsive font scale for tiny to huge text sizes.

## [1.1.0] - 2026-04-07

### ✨ Implemented Core Modules
- **ApiClient**: Production-grade fetch wrapper with `AbortController` and error parsing.
- **TokenStorage**: Secure authentication management via `SecureStore` and `AsyncStorage`.
- **Firebase Strategy**: Safe initialization pattern for push notifications and analytics.
- **i18n & RTL**: Established first-class localization patterns for Arabic/English with app-reloading for RTL flip.

### 🏗️ Project Scaffolding
- **Directory Structure**: Fully scaffolded the repository to align with the Clawhub Master Skill architecture.
- **Foundation Styles**: Implemented `styles/common.ts` as the root of the functional design system.
- **Shared Service**: Added `sharedService.ts` for dynamic app-wide settings management.


---
*Generated by Clawhub Assistant*


path: _agents/workflows/make-component.md
content: ---
description: Scaffold a new shared component for React Native
---

// turbo-all
# 🧩 Component Scaffolding

Follow these steps to generate a standardized, reusable component for the `@shared` library.

## 🟢 Step 1: Definition
Ask the user for:
1.  **Component Type**:
    - **Shared**: (Target: `src/components/SharedComponent/`) - Global, "blessed" components, usually prefixed with `App`.
    - **Regular**: (Target: `src/components/`) - Feature-specific or general application components.
    - **Local**: (Target: `src/screens/[ScreenName]/local-components/`) - Bound to specific features.
2.  **Component Name**: (e.g., `AppCard`, `Tag`, `Banner`)
3.  **Complexity**: Is it a simple UI atom or a complex molecule with its own controller?

## 🟡 Step 2: Implementation (The Standard Structure)
Create a new directory in the **Target Directory** and generate:

### 1. `types.ts` (Structure)
- Define the `[Name]Props` interface.
- **Mandatory Prop Standards**: Every shared component MUST support these if applicable:
    - `containerStyle?: ViewStyle`: For external layout positioning.
    - `style?: TextStyle | ViewStyle`: For overriding internal element styles.
    - `disabled?: boolean`: To handle interaction states.
    - `testID?: string`: For automated testing identification.
    - `children?: React.ReactNode`: If the component acts as a wrapper.
- Ensure all style props are optional and correctly typed using absolute path aliases.

### 2. `styles.ts` (Nerves)
- Implement `getStyles` consuming `colors`, `tokens`, and RTL config.
- Use **centralized spacing and radius tokens** instead of hardcoded values.

### 3. `index.tsx` (The Component)
- Wrap the component in `React.memo` for performance.
- Use `useAppStyle` to resolve colors and styles if needed.
- Merge user-provided `style` and `containerStyle` props correctly.

### 4. `controller.ts` (Brain)
- Standard requirement for all Clawhub components. 
- Defines the `use[Name]Controller` hook providing styles and interaction logic to the UI skin.

## 🔵 Step 3: Registration
1.  **If Shared**, add the new component to `src/components/SharedComponent/index.ts`.
2.  **If Regular**, add to `src/components/index.ts`.
3.  **Ensure it is exported** with a clear, prefixed name if it is shared (e.g., `AppButton`).

## 🏁 Step 4: Quality Check
- [ ] Component is memoized (`React.memo`).
- [ ] Props allow for style overrides.
- [ ] RTL/LTR directionality is respected.
- [ ] Accessibility props (`accessibilityLabel`, etc.) are included where appropriate.


path: _agents/workflows/setup-navigation.md
content: ---
description: Setup production-grade Root and dynamic Main (Tab) Navigators
---

// turbo-all
# 🗺️ Navigation Setup (Root & Main)

Follow these steps to implement a reactive, configuration-driven navigation system with Auth/Verified/Guest gating.

## 🟢 Step 1: Definition
Verify the requirements:
1.  **Auth Gating**: Does the app require a different stack for authenticated vs. guest users?
2.  **Verification Flow**: Does the app have a multi-step user verification process (e.g., OTP, Profile completion)?
3.  **Dynamic Tabs**: Should the bottom tab bar be driven by the central `Config`?

## 🟡 Step 2: Optimization (Centralization)

### 1. `src/hooks/useAppStyle.ts` (Global Config)
Centralize common navigation options to ensure project-wide consistency and perfect RTL handling.
```typescript
const navigationOptions = {
    headerShown: false,
    contentStyle: { backgroundColor: colors.background },
    animation: isRTL ? 'slide_from_left' : 'slide_from_right' as any,
};
```

## 🟡 Step 3: Implementation (Root Navigator)

### 1. `src/navigation/RootNavigator.tsx` (The Gatekeeper)
Implement the `RootNavigator` stack using the centralized logic:
- **Centralized Options**: Consuming `navigationOptions` from `useAppStyle`.
- **Key-Based Remounting**: Use `key={isAuthenticated ? 'authed' : 'guest'}` on the navigator to clear state during transitions.

## 🟡 Step 4: Implementation (Main Navigator)

### 1. `src/navigation/MainNavigator.tsx` (Dynamic Tabs)
Implement the `MainNavigator` (usually a BottomTabNavigator):
- **Config Driven**: Map `config.navigation.bottomTabs` items to screen components.
- **Custom Tab Bar**: Integrate a `CustomTabBar` component for premium aesthetics.
- **Togglability**: Allow disabling the tab bar via `config.features.enableBottomNavbar`.

## 🔵 Step 5: Component Support

### 1. `src/components/CustomTabBar/`
Ensure a premium, animated tab bar is implemented using:
- **Reanimated**: For smooth active-tab indicator transitions.
- **Config Labels**: Fetching localized labels and icons from the central config.
- **Icon Mapping**: Converting generic icon names from the backend/config to `Ionicons` or `AppImage` sources.

## 🏁 Step 6: Verification
- [ ] Log out and verify the navigator resets correctly to the `Login` screen.
- [ ] Toggle a tab in `Config.ts` and verify it appears/disappears dynamically.
- [ ] Check RTL transitions for correct slide direction.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)