Skip to content

Commit fa488b5

Browse files
marcocesaratomarcocesarato
committed
docs: add copilot instructions for contributing and development workflows
1 parent e058cee commit fa488b5

File tree

1 file changed

+320
-0
lines changed

1 file changed

+320
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 320 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,320 @@
1+
# React Native Big List - GitHub Copilot Instructions
2+
3+
<meta>
4+
<project-type>React Native Library</project-type>
5+
<platforms>iOS, Android, Web, Expo</platforms>
6+
<main-language>JavaScript (ES6+)</main-language>
7+
<framework>React Native</framework>
8+
<test-framework>Jest</test-framework>
9+
<docs-framework>Docusaurus</docs-framework>
10+
<license>MIT</license>
11+
</meta>
12+
13+
## 🎯 Project Goal
14+
15+
<goal>
16+
Make small, safe, well-tested improvements to this high-performance React Native list library. Focus on:
17+
- **Bug fixes** with proper test coverage
18+
- **Documentation** improvements and corrections
19+
- **Small feature additions** that maintain backward compatibility
20+
- **Performance optimizations** that are opt-in or transparent
21+
- **Testing** enhancements and edge case coverage
22+
23+
⚠️ **Always prefer minimal, reversible changes with comprehensive validation**
24+
</goal>
25+
26+
## 🗺️ Repository Architecture
27+
28+
### Core Components
29+
<core-files>
30+
| File | Purpose | Key Responsibilities |
31+
|------|---------|---------------------|
32+
| `lib/BigList.jsx` | Main component | Item rendering, scroll/layout event handling, public API |
33+
| `lib/BigListProcessor.js` | Layout engine | Computes visible items, spacers, scroll positions |
34+
| `lib/BigListItemRecycler.js` | Memory optimization | Recycles view objects, prevents memory leaks |
35+
| `lib/BigListItem.jsx` | Item wrapper | Individual item rendering and lifecycle |
36+
| `lib/BigListSection.jsx` | Section support | Section headers/footers, grouped data |
37+
| `lib/BigListPlaceholder.jsx` | Loading states | Placeholder component for unrendered items |
38+
</core-files>
39+
40+
### Public API & Types
41+
<api-files>
42+
| File | Purpose | Update Triggers |
43+
|------|---------|----------------|
44+
| `lib/index.d.ts` | TypeScript definitions | Any prop/method signature changes |
45+
| `index.js` | Main export | New components or utility exports |
46+
| `lib/utils.js` | Shared utilities | Helper functions used across components |
47+
</api-files>
48+
49+
### Development & Testing
50+
<dev-files>
51+
| Directory | Purpose | Usage |
52+
|-----------|---------|-------|
53+
| `__tests__/` | Jest test suites | Validate behaviors, catch regressions |
54+
| `example/` | Expo demo app | Smoke testing, performance validation |
55+
| `docs/` | Docusaurus documentation | API docs, guides, examples |
56+
| `scripts/` | Build tooling | Distribution, publishing automation |
57+
</dev-files>
58+
59+
## 🧩 Architecture Patterns
60+
61+
### Core Design Principles
62+
<patterns>
63+
<pattern name="Pure JavaScript Implementation">
64+
- **Why**: Cross-platform compatibility (iOS, Android, Web, Expo)
65+
- **Rule**: Never add native modules or platform-specific code
66+
- **Validation**: Test on multiple platforms including web
67+
</pattern>
68+
69+
<pattern name="Height-First Rendering">
70+
- **Concept**: All items must have deterministic heights
71+
- **Implementation**: Heights specified as numbers or functions
72+
- **Key Methods**: `BigList.getItemHeight()`, `BigListProcessor.getItemHeight()`
73+
- **Validation**: Check height calculations in processor tests
74+
</pattern>
75+
76+
<pattern name="Processor-Centric Layout">
77+
- **Engine**: `BigListProcessor.process()` computes all layout
78+
- **Outputs**: Visible items array, spacer components, total height
79+
- **Invariants**: Spacer math must be consistent with recycling logic
80+
- **Testing**: Layout changes require processor unit tests
81+
</pattern>
82+
83+
<pattern name="View Recycling">
84+
- **Manager**: `BigListItemRecycler` preserves React elements
85+
- **Benefit**: Prevents expensive re-renders, maintains scroll performance
86+
- **Caution**: Item key/shape changes need recycler mapping updates
87+
- **Debug**: Visual glitches often indicate recycler issues
88+
</pattern>
89+
90+
<pattern name="Dual Data Modes">
91+
- **Flat Mode**: `data` prop with simple array
92+
- **Section Mode**: `sections` prop with grouped data
93+
- **Branching**: `this.hasSections()` determines code path
94+
- **Requirement**: Update both modes for data-related changes
95+
</pattern>
96+
</patterns>
97+
98+
## 🛠️ Development Workflows
99+
100+
### Testing & Validation
101+
<commands>
102+
```bash
103+
# Run complete test suite
104+
yarn test
105+
npm test
106+
107+
# Run tests in watch mode
108+
yarn test --watch
109+
110+
# Run specific test file
111+
yarn test BigList.basic.test.js
112+
113+
# Test with coverage
114+
yarn test --coverage
115+
```
116+
</commands>
117+
118+
### Example App Development
119+
<commands>
120+
```bash
121+
# Navigate to example directory
122+
cd example/
123+
124+
# Install dependencies
125+
yarn install
126+
# or
127+
npm install
128+
129+
# Start Expo development server
130+
expo start
131+
132+
# Run on specific platform
133+
expo start --ios
134+
expo start --android
135+
expo start --web
136+
```
137+
</commands>
138+
139+
### Build & Distribution
140+
<commands>
141+
```bash
142+
# Build package for distribution
143+
yarn prepare
144+
145+
# This runs:
146+
# 1. bob build (creates dist files)
147+
# 2. node scripts/dist.js (finalizes distribution)
148+
149+
# Lint and format code
150+
yarn prettify # Prettier formatting
151+
yarn lint # ESLint checking
152+
153+
# Pre-commit hooks run lint-staged automatically
154+
```
155+
</commands>
156+
157+
## 🔧 Change Guidelines
158+
159+
### Bug Fixes & Runtime Issues
160+
<change-type category="bugfix">
161+
**Focus Areas:**
162+
- Scrolling math errors (off-by-one, position calculations)
163+
- Spacer height inconsistencies
164+
- Memory leaks in recycler
165+
- Event handler edge cases
166+
167+
**Validation Process:**
168+
1. Create focused Jest test reproducing the issue
169+
2. Implement minimal fix
170+
3. Verify test passes
171+
4. Run full test suite
172+
5. Test in example app with edge cases
173+
</change-type>
174+
175+
### API Changes & Extensions
176+
<change-type category="api">
177+
**Required Updates:**
178+
- `lib/index.d.ts` - TypeScript definitions
179+
- `index.js` - Export declarations
180+
- `docs/docs/*.md` - Documentation updates
181+
- `example/` - Usage examples (if applicable)
182+
183+
**Backward Compatibility:**
184+
- Add new props as optional with sensible defaults
185+
- Deprecate old APIs before removing (use console.warn)
186+
- Add migration notes to CHANGELOG.md
187+
</change-type>
188+
189+
### Performance Optimizations
190+
<change-type category="performance">
191+
**Validation Requirements:**
192+
- Profile with `example/` app using large datasets
193+
- Create synthetic benchmark tests
194+
- Make optimizations opt-in via props when behavior changes
195+
- Document performance impact in PR description
196+
197+
**Common Areas:**
198+
- Scroll event throttling
199+
- Layout calculation caching
200+
- Render cycle optimization
201+
- Memory usage improvements
202+
</change-type>
203+
204+
## 📖 Key Files Reference
205+
206+
### Primary Implementation
207+
<file-reference>
208+
| File | Focus Areas | Common Changes |
209+
|------|-------------|----------------|
210+
| `lib/BigList.jsx` | Event handlers, prop validation, lifecycle | onScroll logic, prop additions, state management |
211+
| `lib/BigListProcessor.js` | Math calculations, layout logic | Height calculations, visible item computation, scrollToPosition |
212+
| `lib/BigListItemRecycler.js` | Memory management, view reuse | Key mapping, recycling strategy, cleanup logic |
213+
</file-reference>
214+
215+
### Documentation & API
216+
<file-reference>
217+
| File | Content Type | Update Triggers |
218+
|------|--------------|-----------------|
219+
| `docs/docs/props.md` | Prop documentation | New props, prop behavior changes |
220+
| `docs/docs/methods.md` | Method documentation | New methods, signature changes |
221+
| `__tests__/*.test.js` | Behavior validation | Any functional changes |
222+
</file-reference>
223+
224+
## ✅ Quality Standards
225+
226+
### Code Style & Commit Standards
227+
<standards>
228+
**Commit Guidelines:**
229+
- Keep changes small and focused (one behavior per PR)
230+
- Write descriptive commit messages explaining the "why"
231+
- Include test updates with behavioral changes
232+
- Update documentation for public API changes
233+
234+
**Code Quality:**
235+
- Follow existing code patterns and conventions
236+
- Maintain consistency with current architecture
237+
- Add TypeScript types for new functionality
238+
- Include JSDoc comments for public methods
239+
240+
**Testing Requirements:**
241+
- Unit tests for logic changes
242+
- Integration tests for component behavior
243+
- Performance tests for optimization changes
244+
- Regression tests for bug fixes
245+
</standards>
246+
247+
### Validation Checklist
248+
<validation>
249+
Before submitting changes:
250+
251+
- [ ] All tests pass (`yarn test`)
252+
- [ ] Code follows project style (`yarn lint`, `yarn prettify`)
253+
- [ ] Example app runs without errors (`cd example && expo start`)
254+
- [ ] Documentation updated for API changes
255+
- [ ] TypeScript definitions updated
256+
- [ ] Backward compatibility maintained
257+
- [ ] Performance impact assessed (if applicable)
258+
</validation>
259+
260+
## 🔍 Common Implementation Patterns
261+
262+
### Scroll Position Calculations
263+
<implementation-example>
264+
**Pattern**: `BigListProcessor.scrollToPosition`
265+
```javascript
266+
// Always account for:
267+
// 1. Header/content insets
268+
// 2. Section headers (if sections mode)
269+
// 3. Item positions and heights
270+
// 4. Spacer components
271+
272+
const scrollPosition = headerHeight + sectionHeadersHeight + itemsHeight;
273+
scrollView.scrollTo({ y: scrollPosition, animated: true });
274+
```
275+
</implementation-example>
276+
277+
### Height Calculations
278+
<implementation-example>
279+
**Pattern**: `BigList.getItemHeight` and `BigListProcessor.getItemHeight`
280+
```javascript
281+
// Handle both numeric and function forms:
282+
const height = typeof itemHeight === 'function'
283+
? itemHeight(item, index)
284+
: itemHeight;
285+
286+
// Always validate height is numeric
287+
if (typeof height !== 'number' || height <= 0) {
288+
console.warn('Invalid item height:', height);
289+
return DEFAULT_ITEM_HEIGHT;
290+
}
291+
```
292+
</implementation-example>
293+
294+
## 🆘 Troubleshooting Guide
295+
296+
### When You Get Stuck
297+
<troubleshooting>
298+
1. **Visual Bugs**: Run example app (`cd example && expo start`) to reproduce
299+
2. **Logic Issues**: Add/update tests in `__tests__/` to encode expected behavior
300+
3. **API Questions**: Check `docs/docs/props.md` and `docs/docs/methods.md`
301+
4. **Performance Problems**: Profile with large datasets in example app
302+
5. **Type Issues**: Update `lib/index.d.ts` alongside implementation changes
303+
</troubleshooting>
304+
305+
### Common Issues & Solutions
306+
<common-issues>
307+
| Issue | Likely Cause | Solution |
308+
|-------|--------------|----------|
309+
| Blank items appearing | Render performance | Optimize renderItem, check height calculations |
310+
| Scroll position jumps | Height calculation errors | Validate height functions, check spacer math |
311+
| Memory usage growing | Recycler not working | Check item key consistency, recycler mapping |
312+
| TypeScript errors | Missing type definitions | Update `lib/index.d.ts` |
313+
| Tests failing | Logic regression | Update tests to match new behavior |
314+
</common-issues>
315+
316+
---
317+
318+
<footer>
319+
**Remember**: This library prioritizes performance and stability. Always validate changes thoroughly and maintain backward compatibility unless explicitly requested otherwise.
320+
</footer>

0 commit comments

Comments
 (0)