@fadyshawky/react-native-magic 2.2.1 → 2.3.0

package/template/docs/ARCHITECTURE.md

@@ -2,26 +2,56 @@
 
 ## Overview
 
-This app uses a layered structure: **UI** (screens, components) → **navigation** → **core** (store, api, theme, config) and **common** (components, localization, helpers).
+This app uses a layered structure: **UI** (screens, components) → **navigation** → **core** (store, api, theme, config, notifications) and **common** (components, localization, helpers). A **design-system** layer re-exports the theme tokens, the brand tokens (gradients/glow), and the theme provider as a single barrel.
+
+> Imports in `src/` are **relative**. Path aliases (`@core/*`, `@common/*`, `@design-system`, …) are configured in `babel.config.js`, `tsconfig.json`, and `jest.config.js` and are available if you prefer them, but the shipped code reaches into `core/theme/*` directly rather than going through the barrel.
 
 ## Folder map
 
 | Folder | Purpose |
 |--------|--------|
-| `src/common/` | Shared UI components, localization (i18n), helpers, validations, hooks, urls, utils |
-| `src/core/` | Store (Redux + persist), API client, theme, config, services, hooks |
-| `src/navigation/` | Navigator setup, auth stack, main stack, tab bar, header components |
-| `src/screens/` | Feature screens (Login, Home, Profile, etc.); each may have local `components/` and `hooks/` |
+| `src/common/` | Shared UI components (incl. `ErrorBoundary`, `NetworkBanner`, `SnackbarProvider`), localization (i18n), helpers, validations, hooks, urls, utils |
+| `src/core/api/` | Single axios instance + interceptors (auth, refresh-token dedup, locale, 401/402 handling) |
+| `src/core/store/` | Redux Toolkit slices (`app`, `user`, `categories`) + persist (AsyncStorage, selective whitelist transforms) |
+| `src/core/theme/` | `colors.ts`, `fonts.ts`, `commonSizes.ts`, `brand.ts` (gradients/glow), `ThemeProvider.tsx`. Light/dark/system theming |
+| `src/core/config/` | Env-driven config (`API_BASE_URL`, `ENV`, feature toggles) |
+| `src/core/notifications/` | FCM listeners (`notificationService.ts`), tap-routing (`routeFromNotificationData.ts`), auth check |
+| `src/design-system/` | Theme + brand token re-exports + theme provider re-export (barrel; `@design-system` alias available but unused) |
+| `src/navigation/` | Navigator setup, auth stack, main stack, root navigation ref, header components |
+| `src/screens/` | Feature screens (Splash, Login, OTP, Home, Profile); each may have local `components/` and `hooks/` |
+| `src/assets/brand/` | Brand logo SVGs (`logo-primary`, `logo-mono`, `logo-mark`, `wordmark-dark`) |
 | `src/sheetManager/` | Action sheet registration |
 
 ## Data flow
 
-- **Auth**: Token is stored in Redux (`user.accessToken`). Navigation shows Auth stack when there is no token, Main stack when there is.
-- **API**: Single axios instance in `src/core/api/serverHeaders.ts`. Base URL comes from `src/core/config` (and `.env`). Request interceptor adds `Authorization: Bearer` and `locale`; response interceptor handles 401 (e.g. logout).
-- **Redux**: Slices live under `src/core/store/<domain>/` (e.g. `app`, `user`). Persist whitelist controls what is saved to AsyncStorage.
+- **Auth**: Token is stored in Redux (`user.accessToken`). Navigation shows Auth stack when there is no token, Main stack when there is. `user.refreshToken` is persisted; the axios response interceptor dedups concurrent 401s via a single in-flight `refreshPromise`, then retries the original request. On refresh failure, `setLogout()` is dispatched.
+- **API**: Single axios instance in `src/core/api/serverHeaders.ts`. Base URL comes from `src/core/config` (and `.env`). Request interceptor adds `Authorization: Bearer` and `locale`. Response interceptor handles 401 (refresh) and 402 (logout).
+- **Redux**: Slices live under `src/core/store/<domain>/` (`app`, `user`, `categories`). Each follows the house pattern — a `newState` reducer helper, a `LoadState` enum for request status, and `createAsyncThunk` thunks that call the API helpers. `categories` is a worked example: its thunk GETs `/categories`, the slice tracks `LoadState`, and the Home screen's `useHomeData` hook renders the result through `FlatListWrapper` (a full data → thunk → slice → list demo). Persist whitelist (`store.tsx`) controls what survives a kill — `user`: `accessToken`, `refreshToken`, `fcmToken`, `user`; `app`: `language`, `isRTL`. The `app` slice defaults `language` to English (`Languages.en`); Arabic / RTL stay wired and switchable at runtime.
+- **Notifications**: `index.js` registers the FCM background handler before app boot — it queues any incoming `data` payload into `pendingBackgroundNotificationData`. `App.tsx` mounts `startPushNotificationListeners()` which wires foreground/background/cold-start/token-refresh listeners, plus an `AppState` + store subscriber that flushes the pending route when the user is logged in and the navigator is ready.
+- **Theming**: The "Indigo → Cyan" tokens live in `src/core/theme/colors.ts`; gradient and glow tokens (`BrandGradients`, `Glow`) live in `src/core/theme/brand.ts` and pair with `react-native-linear-gradient`. `ThemeProvider` exposes `useTheme()` and **follows the system color scheme by default** (`App.tsx` renders `<ThemeProvider>` with no forced theme). Light and dark are both supported; the Profile screen offers a manual toggle. The brand `Logo` (`src/common/components/Logo.tsx`) renders the "FS" monogram from `react-native-svg` in four variants (`gradient` / `mono` / `light` / `mark`).
+
+## Provider order in `App.tsx`
+
+Outer → inner:
+
+1. `ErrorBoundary` (catches render errors with a retry fallback)
+2. `Provider` (Redux store)
+3. `PersistGate` (redux-persist)
+4. `GestureHandlerRootView`
+5. `SnackbarProvider`
+6. `ThemeProvider`
+7. `RTLInitializer` (must wrap `LocalizationProvider`)
+8. `LocalizationProvider`
+9. `SafeAreaProvider`
+10. `SheetProvider` (react-native-actions-sheet)
+11. `BottomSheetModalProvider` (@gorhom/bottom-sheet)
+12. `AppNavigator`
+13. `NetworkBanner` (sibling of navigator, fixed position)
+
+Order is load-bearing: persist must be ready before redux-aware components mount; gesture-handler must wrap everything that uses gestures; RTL must initialize before localized text renders.
 
 ## SOLID mapping
 
 - **SRP**: One domain per store folder; one primary concern per component file; theme split into colors, fonts, sizes, consts, styles.
-- **OCP**: Extend by adding screens, slices, or routes without changing existing stack logic; extend theme by editing theme files.
-- **DIP**: Core (API, store) does not depend on UI; screens depend on core via hooks/selectors; config abstracts environment.
+- **OCP**: Extend by adding screens, slices, or routes without changing existing stack logic; extend theme by editing theme files; extend notifications by editing `routeFromNotificationData.ts` only.
+- **DIP**: Core (API, store, notifications) does not depend on UI; screens depend on core via hooks/selectors; config abstracts environment.

package/template/docs/BEST_PRACTICES.md

@@ -4,6 +4,8 @@
 
 - Use **TypeScript** strictly; avoid `any` where possible.
 - Use typed Redux: `useAppSelector`, `useAppDispatch`, and `createAppAsyncThunk` with `RootState` / `AppDispatch`.
+- Follow the house slice pattern: a `newState` reducer helper, a `LoadState` enum for request status, and `createAsyncThunk` thunks that call the API helpers. The `categories` slice (`src/core/store/categories/`) is the reference.
+- Use relative imports to match the existing code. Path aliases are configured but not used by the shipped `src/`.
 - Run `npm run lint` and fix issues.
 
 ## Structure
@@ -21,6 +23,13 @@
 
 - Avoid creating new objects/functions in render when they are passed as props to children.
 - Use stable keys for list items.
+- For heavy lists, use `src/common/components/FlatListWrapper.tsx` (FlashList-backed) and set `estimatedItemSize`; don't reintroduce a raw `FlatList`.
+
+## Theming
+
+- Change brand colors, fonts, and sizes only in `src/core/theme/` — keep the token keys stable so the rest of the app keeps working.
+- Reuse the gradient and glow tokens from `src/core/theme/brand.ts` (`BrandGradients`, `Glow`) for the futuristic surfaces rather than hardcoding shadows or gradient stops.
+- The app follows the system color scheme by default; verify new screens in both light and dark.
 
 ## Security
 
@@ -29,5 +38,5 @@
 
 ## LTS / upgrades
 
-- The template targets **Node >= 20** and current stable **React Native** (e.g. 0.84.x).
+- The template targets **Node >= 20** and **React Native 0.85.x** (React 19.2.x).
 - To upgrade React Native, use [React Native Upgrade Helper](https://react-native-community.github.io/upgrade-helper/): select your current version and the target version, then apply the suggested changes to `package.json`, `android/`, `ios/`, and config files.

package/template/docs/CUSTOMIZATION.md

@@ -17,17 +17,40 @@ If you omit `--package-name`, the template will **prompt you** after init to ent
 
 1. Copy `.env.example` to `.env`.
 2. Set `API_BASE_URL` (and any other keys) for your backend.
-3. The app reads these via `react-native-config`; `src/core/config/index.ts` re-exports them for type-safe use.
+3. The app reads these via `react-native-config`; `src/core/config/index.ts` re-exports them for type-safe use as `API_BASE_URL` and `ENV` (the environment name; falls back to a legacy `ENVIRONMENT` var). Route all env access through this module.
 
 Optional: use multiple env files (e.g. `.env.development`, `.env.staging`, `.env.production`) and build variants so each build uses the right URL.
 
-## Theme
+## Theme & branding
 
-Edit these files for your brand (no need to touch components):
+The template ships a futuristic **"Indigo → Cyan"** system (primary indigo `#5B6CFF`, accent cyan `#22E0D6`, deep ink `#0B1020`). Edit these files for your brand — token *keys* are stable across the app, so changing the hex values rebrands everything (no need to touch components):
 
 - **Colors**: `src/core/theme/colors.ts`
 - **Fonts**: `src/core/theme/fonts.ts`
 - **Sizes / spacing**: `src/core/theme/commonSizes.ts`
+- **Gradients & glow**: `src/core/theme/brand.ts` — `BrandColors`, `BrandGradients` (e.g. `BrandGradients.primary = ['#5B6CFF', '#22E0D6']`), `GradientDirection`, and `Glow` (ready-to-spread `ViewStyle` shadows). Gradient surfaces use `react-native-linear-gradient`.
+
+These tokens are also re-exported from the `src/design-system` barrel.
+
+### Light / dark / system theming
+
+`ThemeProvider` (`src/core/theme/ThemeProvider.tsx`) exposes `useTheme()` and **follows the OS color scheme by default** — `App.tsx` renders `<ThemeProvider>` with no forced theme. Both light and dark are supported, and the Profile screen includes a manual toggle. To force one theme, pass it to `<ThemeProvider>` in `App.tsx`.
+
+### Logo
+
+The brand mark is a forward-leaning **"FS" monogram**:
+
+- React component: `src/common/components/Logo.tsx` — `<Logo size={96} variant="gradient" />`, built on `react-native-svg`. Variants: `gradient` (default), `mono`, `light`, `mark`. It is wired into Splash, Login, Home, and Profile.
+- Raw SVGs: `src/assets/brand/` (`logo-primary.svg`, `logo-mono.svg`, `logo-mark.svg`, `wordmark-dark.svg`).
+
+To use your own mark, replace the paths in `Logo.tsx` (and the SVGs) — the rest of the app references the component, not the assets directly.
+
+### Visual references
+
+Two static reference pages ship with the template:
+
+- **[`docs/design-system.html`](./design-system.html)** — color ramps, gradients, glow, and logo variants.
+- **[`docs/wireframes.html`](./wireframes.html)** — the screen flow.
 
 ## Adding a new language
 
@@ -38,9 +61,11 @@ Edit these files for your brand (no need to touch components):
 
 ## Adding a screen
 
+The template ships real, branded screens: **Splash** (the Auth stack entry, which hands off to Login), **Login** (logo + phone/password), **OTP** (verifies via a `verifyOTP` thunk), **Home** (greeting + gradient hero card + a categories list), and **Profile** (user card + language toggle + theme toggle + logout). Use any of them as a starting point.
+
 1. Create a folder under `src/screens/<Feature>/` with `Feature.tsx` and optional `components/` and `hooks/`.
-2. Register the screen in the right stack in `src/navigation/` (e.g. `AuthStack.tsx` or `MainStack.tsx`).
-3. Add the route and component to the stack’s screen list.
+2. Register the screen in the right stack in `src/navigation/` (the Auth stack or the Main stack).
+3. Add the route to `RootStackParamList` in `src/navigation/types.ts` (currently `Splash`, `Login`, `OTP`, `Main`, `Account`) and add the component to the stack's screen list.
 
 ## Adding a Redux slice
 
@@ -48,6 +73,94 @@ Edit these files for your brand (no need to touch components):
 2. Add the slice to `src/core/store/rootReducer.ts`.
 3. If the slice should persist, add a `createWhitelistFilter('<domain>', ['field1', 'field2'])` entry in `src/core/store/store.tsx` persist config.
 
+The `categories` slice (`src/core/store/categories/`) is a complete, copyable example of the house pattern: a `newState` reducer helper, a `LoadState` enum for request status, and a `createAsyncThunk` that calls the `get()` API helper. The Home screen's `useHomeData` hook dispatches it and renders the result through `FlatListWrapper`.
+
 ## Feature flags / app config
 
 Toggle features or app-level constants in `src/core/config/index.ts` or via env vars read there (e.g. `enableRTL`).
+
+## Firebase / push notifications (FCM)
+
+The template ships with `@react-native-firebase/{app,messaging,analytics}` wired into `src/core/notifications/`. Listeners are started from `App.tsx` and the background handler is registered in `index.js`. To make this work on a real device you need to add your Firebase project credentials.
+
+### iOS
+
+1. In the [Firebase console](https://console.firebase.google.com), add an iOS app using your `BUNDLE_ID`.
+2. Download `GoogleService-Info.plist` and drag it into `ios/<YourApp>/` in Xcode (Copy items if needed, target = your app).
+3. In `ios/Podfile`, ensure modular headers are enabled near the top:
+   ```ruby
+   use_modular_headers!
+   ```
+4. In `ios/<YourApp>/AppDelegate.swift`, configure Firebase at startup:
+   ```swift
+   import FirebaseCore
+   // …
+   func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
+     FirebaseApp.configure()
+     // …
+   }
+   ```
+5. Enable **Push Notifications** + **Background Modes → Remote notifications** in the target's Signing & Capabilities.
+6. Upload your APNs auth key in Firebase project settings → Cloud Messaging.
+7. Run `cd ios && pod install`.
+
+### Android
+
+1. In the Firebase console, add an Android app using your `ANDROID_APP_ID`.
+2. Download `google-services.json` and drop it into `android/app/`.
+3. In `android/build.gradle`, add the Google services classpath:
+   ```gradle
+   buildscript {
+     dependencies {
+       classpath("com.google.gms:google-services:4.4.2")
+     }
+   }
+   ```
+4. In `android/app/build.gradle`, apply the plugin at the very bottom:
+   ```gradle
+   apply plugin: "com.google.gms.google-services"
+   ```
+5. Rebuild: `cd android && ./gradlew clean`.
+
+### Routing taps
+
+Notification taps route via `src/core/notifications/routeFromNotificationData.ts`. Send `data.screen` (and optionally `data.params` as a JSON string) in the FCM payload — the router calls `navigate(screen, params)`. Extend that file with `data.type`/`data.target` switches for richer flows.
+
+## React Native 0.85.x
+
+The template is on RN 0.85.2. If you upgrade your generated app to a newer RN later, use the [Upgrade Helper](https://react-native-community.github.io/upgrade-helper/) — select your current RN version on the left and the target on the right, then apply the suggested diffs to `package.json`, `ios/`, `android/`, and config files.
+
+`react-native-reanimated` 4.x requires `react-native-worklets` and the `react-native-worklets/plugin` babel plugin (already in `babel.config.js`). Do not also add `react-native-reanimated/plugin` — only one of the two.
+
+## Path aliases
+
+The template wires these aliases through `babel.config.js`, `tsconfig.json`, and `jest.config.js`. **They are configured but not used by the shipped code** — `src/` imports relatively. They are here if you prefer aliases; opt in per file.
+
+| Alias | Path |
+|-------|------|
+| `@core/*` | `src/core/*` |
+| `@common/*` | `src/common/*` |
+| `@navigation/*` | `src/navigation/*` |
+| `@screens/*` | `src/screens/*` |
+| `@sheetManager/*` | `src/sheetManager/*` |
+| `@design-system` | `src/design-system` |
+| `@types/*` | `src/types/*` |
+| `@utils/*` | `src/utils/*` |
+
+Add new aliases in all three files together — Babel rewrites imports at build time, TS resolves them for the editor, Jest resolves them for tests.
+
+## CI / version bumping
+
+`scripts/ci-sync-env.cjs` writes/updates `KEY=value` pairs in an env file. Use it in CI to inject Play Store / App Store auto-incremented build numbers:
+
+```bash
+node scripts/ci-sync-env.cjs .env.production \
+  ANDROID_VERSION_CODE=42 \
+  IOS_BUILD_NUMBER=42
+```
+
+Then run your release build — Gradle and the iOS scheme pick up the values via `react-native-config`.
+
+## Git hooks
+
+`husky` v9 + `lint-staged` are wired. Hooks live in `.husky/`. The pre-commit hook runs `lint-staged`, which applies `eslint --fix` and `prettier --write` to staged files only. To skip once (rare): `git commit --no-verify`.