@boneframework/native-components 1.0.61 → 1.0.62
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
# Copilot Instructions for @boneframework/native-components
|
|
2
|
+
|
|
3
|
+
This is an **Expo React Native component library** for the Bone Framework, providing reusable UI components and utilities for cross-platform (native + web) applications.
|
|
4
|
+
|
|
5
|
+
## Architecture Overview
|
|
6
|
+
|
|
7
|
+
### Core Layers
|
|
8
|
+
- **Components** (`components/`): Platform-specific UI components using `.native.tsx` (React Native) and `.web.tsx` (web) naming
|
|
9
|
+
- **Contexts** (`contexts/`): React Context API for state management (API, Auth, Cache, Colors, Settings, Theme)
|
|
10
|
+
- **Hooks** (`hooks/`): Custom hooks consuming contexts and managing side effects
|
|
11
|
+
- **API** (`api/`): HTTP clients using `apisauce` wrapper around axios, with built-in offline caching
|
|
12
|
+
- **Screens** (`screens/`): Full-page components for app navigation
|
|
13
|
+
- **Utilities** (`utilities/`): Helper functions (auth storage, caching, logging, JSON parsing)
|
|
14
|
+
|
|
15
|
+
### Data Flow Pattern
|
|
16
|
+
**API Call → Hook (useApi) → Context → Components**
|
|
17
|
+
|
|
18
|
+
Example: A screen dispatches an API call through `useApi(apiFunction)`, which updates context, triggering component re-renders.
|
|
19
|
+
|
|
20
|
+
## Key Patterns & Conventions
|
|
21
|
+
|
|
22
|
+
### 1. Platform-Specific Components
|
|
23
|
+
Use `.native.tsx` and `.web.tsx` extensions for platform divergence:
|
|
24
|
+
- `Animation.native.tsx` uses `lottie-react-native`
|
|
25
|
+
- `Animation.web.tsx` uses `lottie-react`
|
|
26
|
+
- `MapScreen.native.tsx` and `MapScreen.web.tsx` for native/web map implementations
|
|
27
|
+
|
|
28
|
+
**Import pattern:** `import Animation from './Animation'` (Expo auto-resolves `.native`/`.web`)
|
|
29
|
+
|
|
30
|
+
### 2. API Client & Caching
|
|
31
|
+
- Configured in `api/client.ts` using `apisauce` with `EXPO_PUBLIC_API_URL` env var
|
|
32
|
+
- Built-in offline fallback: if request fails, attempts to serve cached response
|
|
33
|
+
- Cache blacklist exists (commented out) for endpoints that shouldn't be cached
|
|
34
|
+
- API functions live in `api/{resource}.ts` and return Promise<apisauceResponse>
|
|
35
|
+
|
|
36
|
+
Example:
|
|
37
|
+
```typescript
|
|
38
|
+
// api/users.ts
|
|
39
|
+
const getUser = (id) => client.get(`/api/users/${id}`);
|
|
40
|
+
export default { getUser };
|
|
41
|
+
|
|
42
|
+
// Usage in hook
|
|
43
|
+
const { data, loading, error } = useApi(usersApi.getUser)(userId);
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
### 3. Forms with Formik + Validation
|
|
47
|
+
- `Form.tsx` wraps Formik with validation schema integration
|
|
48
|
+
- `FormField.tsx` components connect to Formik state
|
|
49
|
+
- Form components: `FormDateTimePicker`, `FormImagePicker`, `FormPicker`
|
|
50
|
+
- `SubmitButton.tsx` auto-disables when form is invalid
|
|
51
|
+
|
|
52
|
+
Pattern:
|
|
53
|
+
```typescript
|
|
54
|
+
<Form
|
|
55
|
+
initialValues={{email: ''}}
|
|
56
|
+
validationSchema={yupSchema}
|
|
57
|
+
onSubmit={handleSubmit}
|
|
58
|
+
>
|
|
59
|
+
<FormField name="email" />
|
|
60
|
+
<SubmitButton label="Submit" />
|
|
61
|
+
</Form>
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### 4. Auth & Storage
|
|
65
|
+
- JWT tokens stored securely via `expo-secure-store` (platform-native keychain)
|
|
66
|
+
- User objects stored in `AsyncStorage`
|
|
67
|
+
- `AuthContext` manages `login()`, `logout()`, `updateUser()`, user state, and loading state
|
|
68
|
+
- `useAuth()` hook provides auth context with type safety
|
|
69
|
+
- `authStorage.ts` handles all secure/async storage operations
|
|
70
|
+
|
|
71
|
+
### 5. Context Consumers Pattern
|
|
72
|
+
`BoneNativeProvider` aggregates all contexts. External projects pass config:
|
|
73
|
+
```typescript
|
|
74
|
+
<BoneNativeProvider
|
|
75
|
+
api={apiConfig}
|
|
76
|
+
cache={cacheInstance}
|
|
77
|
+
colors={themeColors}
|
|
78
|
+
settings={appSettings}
|
|
79
|
+
>
|
|
80
|
+
<YourApp />
|
|
81
|
+
</BoneNativeProvider>
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### 6. Reusable UI Components
|
|
85
|
+
- **Layout**: `Screen` (handles safe area + status bar), `Card`, `Background`
|
|
86
|
+
- **Input**: `TextInput`, `Picker`, `DateTimePicker`, `ImageInput`
|
|
87
|
+
- **Lists**: `ListItemSwipable`, `ListItemDeleteAction`, `ListItemSeparator`
|
|
88
|
+
- **Actions**: `Button`, `RoundIconButton`, `OfflineNotice`
|
|
89
|
+
- All follow React Native StyleSheet patterns with `useStyle()` hook for theme colors
|
|
90
|
+
|
|
91
|
+
## Development Workflows
|
|
92
|
+
|
|
93
|
+
### Environment Setup
|
|
94
|
+
```bash
|
|
95
|
+
pnpm install
|
|
96
|
+
# Uses Expo. Requires EXPO_PUBLIC_API_URL env var set
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### Key Files to Know
|
|
100
|
+
- `package.json`: Dependencies include Formik, apisauce, expo-router, Lottie animations
|
|
101
|
+
- `tsconfig.json`: Extends `expo/tsconfig.base`, uses JSX mode
|
|
102
|
+
- Asset animations in `assets/animations/` (loader.json, email.json, done.json)
|
|
103
|
+
|
|
104
|
+
### Building & Publishing
|
|
105
|
+
- Published to npm as `@boneframework/native-components`
|
|
106
|
+
- Main entry: `src/Bone.ts`
|
|
107
|
+
- Semantic versioning in use (currently v1.0.60)
|
|
108
|
+
|
|
109
|
+
## Integration Points
|
|
110
|
+
|
|
111
|
+
### External Dependencies
|
|
112
|
+
- **Expo ecosystem**: router, auth-session, camera, location, notifications, secure-store, image-picker, linear-gradient
|
|
113
|
+
- **Forms**: Formik + Yup (validation assumed by consumers)
|
|
114
|
+
- **Animations**: lottie-react-native (native), lottie-react (web)
|
|
115
|
+
- **Async**: AsyncStorage + Expo SecureStore for persistence
|
|
116
|
+
- **Networking**: apisauce (axios wrapper)
|
|
117
|
+
- **UI**: React Native, safe-area-context
|
|
118
|
+
|
|
119
|
+
### Expected Consumer Setup
|
|
120
|
+
Consumers must provide:
|
|
121
|
+
- API client configuration (baseURL)
|
|
122
|
+
- Theme colors & settings contexts
|
|
123
|
+
- Cache implementation
|
|
124
|
+
- Auth token management
|
|
125
|
+
|
|
126
|
+
## Common Tasks
|
|
127
|
+
|
|
128
|
+
### Adding a New Component
|
|
129
|
+
1. Create `components/YourComponent.tsx`
|
|
130
|
+
2. For platform variance, use `YourComponent.native.tsx` + `YourComponent.web.tsx`
|
|
131
|
+
3. Export from component with appropriate platform extension
|
|
132
|
+
4. Use `useStyle()` for theme-aware styling
|
|
133
|
+
|
|
134
|
+
### Adding an API Endpoint
|
|
135
|
+
1. Create `api/{resource}.ts`
|
|
136
|
+
2. Use `client` from `api/client.ts`
|
|
137
|
+
3. Export functions that return `client.get()`, `client.post()`, etc.
|
|
138
|
+
4. Consume via `useApi(resourceApi.method)` in components
|
|
139
|
+
|
|
140
|
+
### Handling Authentication
|
|
141
|
+
1. Call `authContext.login(token)` after successful auth
|
|
142
|
+
2. Token auto-stored securely via `authStorage.storeAuthToken()`
|
|
143
|
+
3. Use `useAuth()` hook in components to access `user` and `isLoading`
|
|
144
|
+
4. Use `ApiInterceptor.tsx` to attach tokens to outgoing requests
|
|
145
|
+
|
|
146
|
+
## Notes
|
|
147
|
+
- No test suite configured yet (test script is placeholder)
|
|
148
|
+
- Caching implementation partially disabled (commented toggle in `api/client.ts`)
|
|
149
|
+
- This is a **library** not a full app—consumers handle routing, screens, and data contracts
|
package/package.json
CHANGED
|
@@ -16,7 +16,7 @@ function MapScreen(props) {
|
|
|
16
16
|
|
|
17
17
|
const children = props.children;
|
|
18
18
|
|
|
19
|
-
if (Platform.OS === 'ios')
|
|
19
|
+
if (Platform.OS === 'ios') {
|
|
20
20
|
return <View style={styles.container}><AppleMaps.View style={styles.map} {...props} >{children}</AppleMaps.View></View>;
|
|
21
21
|
}
|
|
22
22
|
|