|
| 1 | +# GitHub Copilot Instructions for Datas Project |
| 2 | + |
| 3 | +## Project Overview |
| 4 | + |
| 5 | +**Datas** is a JavaScript vanilla utility library for date manipulation, developed using "vibe coding" methodology with Claude AI assistance. |
| 6 | + |
| 7 | +### Key Technologies |
| 8 | +- **Language**: JavaScript ES6+ (Vanilla, no frameworks) |
| 9 | +- **Testing**: Jest with jsdom environment |
| 10 | +- **Styling**: CSS3 with Flexbox/Grid and responsive design |
| 11 | +- **Deployment**: GitHub Pages |
| 12 | +- **Language**: Portuguese (Brazil) for UI and documentation |
| 13 | + |
| 14 | +## Core Architecture |
| 15 | + |
| 16 | +### Main Components |
| 17 | + |
| 18 | +1. **DateUtils Class** (`date-utils.js`) |
| 19 | + - Static utility methods for date operations |
| 20 | + - Core functionality includes: date differences, age calculation, moon phases, calendar generation |
| 21 | + - Uses astronomical algorithms for lunar calculations |
| 22 | + |
| 23 | +2. **App Interface** (`app.js`) |
| 24 | + - DOM manipulation and event handling |
| 25 | + - User interface logic for the HTML forms |
| 26 | + - Connects UI elements to DateUtils methods |
| 27 | + |
| 28 | +3. **Test Suite** (`*.test.js`) |
| 29 | + - Comprehensive Jest tests (54+ tests) |
| 30 | + - Pattern: describe() blocks by class/method, test() for specific cases |
| 31 | + - Uses mocks for Date objects to ensure deterministic testing |
| 32 | + |
| 33 | +### File Structure Pattern |
| 34 | +``` |
| 35 | +├── index.html # Main interface |
| 36 | +├── styles.css # Responsive styles with Wildtech gradient |
| 37 | +├── date-utils.js # Core utility class |
| 38 | +├── app.js # UI interaction logic |
| 39 | +├── *.test.js # Jest unit tests |
| 40 | +├── jest.setup.js # Test configuration |
| 41 | +└── documentation files |
| 42 | +``` |
| 43 | + |
| 44 | +## Coding Conventions |
| 45 | + |
| 46 | +### JavaScript Style |
| 47 | +- **ES6 Classes**: Use static methods for utilities |
| 48 | +- **Arrow Functions**: For callbacks and short functions |
| 49 | +- **Template Literals**: For HTML generation and multi-line strings |
| 50 | +- **Destructuring**: For object/array operations |
| 51 | +- **No Frameworks**: Pure vanilla JavaScript only |
| 52 | + |
| 53 | +### Method Naming |
| 54 | +- **Camel Case**: `calculateAge`, `daysBetween`, `getMoonPhase` |
| 55 | +- **Boolean Methods**: Prefix with `is` - `isLeapYear`, `isWeekend` |
| 56 | +- **Get Methods**: For data retrieval - `getWeekNumber`, `getQuarter` |
| 57 | +- **Generate Methods**: For creating complex structures - `generateCalendar` |
| 58 | + |
| 59 | +### Return Patterns |
| 60 | +- **Primitive Returns**: Numbers, strings, booleans for simple calculations |
| 61 | +- **Object Returns**: For complex data like `{years, months, days}` from `calculateAge` |
| 62 | +- **Array Returns**: For collections like calendar data or moon phases |
| 63 | + |
| 64 | +## Date Handling Patterns |
| 65 | + |
| 66 | +### Date Input Processing |
| 67 | +```javascript |
| 68 | +// Always create new Date instances to avoid mutation |
| 69 | +const d1 = new Date(date1); |
| 70 | +const d2 = new Date(date2); |
| 71 | + |
| 72 | +// Use Math.abs for distance calculations |
| 73 | +const diffTime = Math.abs(d2 - d1); |
| 74 | +const diffDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24)); |
| 75 | +``` |
| 76 | + |
| 77 | +### Date Formatting Standards |
| 78 | +- **dd/mm/yyyy**: Default Brazilian format |
| 79 | +- **yyyy-mm-dd**: ISO format for calculations |
| 80 | +- **extenso**: Full Portuguese format with day names |
| 81 | +- **Month Names**: Use Portuguese month/day names from predefined arrays |
| 82 | + |
| 83 | +### Astronomical Calculations |
| 84 | +- **Julian Day**: Base for lunar calculations using astronomical formula |
| 85 | +- **Synodic Month**: 29.53058867 days lunar cycle |
| 86 | +- **8 Moon Phases**: Nova, Crescente, Quarto Crescente, Gibosa Crescente, Cheia, Gibosa Minguante, Quarto Minguante, Minguante |
| 87 | + |
| 88 | +## UI Patterns |
| 89 | + |
| 90 | +### HTML Structure |
| 91 | +- **Semantic IDs**: Use descriptive IDs like `calculateBtn`, `resultDiv`, `date1`, `date2` |
| 92 | +- **Form Organization**: Group related inputs in sections |
| 93 | +- **Result Display**: Use dedicated divs with styled borders for feedback |
| 94 | + |
| 95 | +### CSS Classes and Styling |
| 96 | +- **Color Scheme**: Wildtech gradient from orange (#ff7b00) to brown (#8b4513) |
| 97 | +- **Responsive Design**: Mobile-first approach with flexbox |
| 98 | +- **Visual Feedback**: Border colors for success (green) and error (red) states |
| 99 | + |
| 100 | +### Event Handling |
| 101 | +```javascript |
| 102 | +// Pattern for event listeners |
| 103 | +document.addEventListener('DOMContentLoaded', function() { |
| 104 | + // Initialize all event listeners here |
| 105 | + document.getElementById('calculateBtn').addEventListener('click', calculateFunction); |
| 106 | +}); |
| 107 | + |
| 108 | +// Validation pattern |
| 109 | +if (!input || !isValid(input)) { |
| 110 | + resultDiv.textContent = 'Error message in Portuguese'; |
| 111 | + resultDiv.style.borderLeftColor = '#dc3545'; |
| 112 | + return; |
| 113 | +} |
| 114 | +``` |
| 115 | + |
| 116 | +## Testing Patterns |
| 117 | + |
| 118 | +### Test Structure |
| 119 | +```javascript |
| 120 | +describe('ClassName', () => { |
| 121 | + describe('methodName', () => { |
| 122 | + test('deve fazer algo específico', () => { |
| 123 | + // Arrange |
| 124 | + const input = 'test value'; |
| 125 | + |
| 126 | + // Act |
| 127 | + const result = DateUtils.method(input); |
| 128 | + |
| 129 | + // Assert |
| 130 | + expect(result).toBe(expected); |
| 131 | + }); |
| 132 | + }); |
| 133 | +}); |
| 134 | +``` |
| 135 | + |
| 136 | +### Mock Patterns |
| 137 | +- **Date Mocking**: Mock Date constructor for deterministic tests |
| 138 | +- **DOM Mocking**: Use jsdom setup for UI testing |
| 139 | +- **Cleanup**: Restore original implementations after each test |
| 140 | + |
| 141 | +### Test Categories |
| 142 | +- **Happy Path**: Normal use cases |
| 143 | +- **Edge Cases**: Leap years, month boundaries, weekend detection |
| 144 | +- **Error Cases**: Invalid inputs, null/undefined handling |
| 145 | +- **Astronomical**: Moon phase calculations with known dates |
| 146 | + |
| 147 | +## Common Development Tasks |
| 148 | + |
| 149 | +### Adding New Date Utility |
| 150 | +1. Add static method to DateUtils class |
| 151 | +2. Follow naming conventions (camel case, descriptive) |
| 152 | +3. Handle edge cases (invalid dates, null inputs) |
| 153 | +4. Add comprehensive tests |
| 154 | +5. Update UI if needed |
| 155 | +6. Document in README if user-facing |
| 156 | + |
| 157 | +### Adding UI Feature |
| 158 | +1. Update HTML structure with semantic IDs |
| 159 | +2. Add event listeners in app.js |
| 160 | +3. Follow validation pattern with visual feedback |
| 161 | +4. Add responsive CSS if needed |
| 162 | +5. Test manually and with Jest |
| 163 | + |
| 164 | +### Moon Phase Calculations |
| 165 | +- Use existing `julianDay` helper for date conversion |
| 166 | +- Follow astronomical formulas for accuracy |
| 167 | +- Return Portuguese phase names |
| 168 | +- Include emoji icons for visual representation |
| 169 | + |
| 170 | +## Performance Considerations |
| 171 | + |
| 172 | +- **Date Object Creation**: Create new instances instead of mutating |
| 173 | +- **Calculation Efficiency**: Use mathematical operations over iteration |
| 174 | +- **Memory Management**: Avoid storing large date arrays unnecessarily |
| 175 | +- **DOM Updates**: Batch DOM changes when possible |
| 176 | + |
| 177 | +## Internationalization Notes |
| 178 | + |
| 179 | +- **Language**: All user-facing text in Portuguese (Brazil) |
| 180 | +- **Date Formats**: Use Brazilian conventions (dd/mm/yyyy) |
| 181 | +- **Month/Day Names**: Portuguese language arrays |
| 182 | +- **Error Messages**: Provide helpful Portuguese error messages |
| 183 | + |
| 184 | +## Dependencies and Environment |
| 185 | + |
| 186 | +- **Runtime**: Browser environment (ES6+ support required) |
| 187 | +- **Testing**: Node.js with Jest and jsdom |
| 188 | +- **No External Libraries**: Keep project dependency-free |
| 189 | +- **Build**: No build process - direct file serving |
| 190 | + |
| 191 | +## Documentation Standards |
| 192 | + |
| 193 | +- **JSDoc**: Use for complex methods and classes |
| 194 | +- **README**: Keep user-focused with examples |
| 195 | +- **Comments**: Minimal but clear, in Portuguese when needed |
| 196 | +- **Tests as Documentation**: Comprehensive test cases show intended usage |
| 197 | + |
| 198 | +This file provides GitHub Copilot with comprehensive context about the Datas project patterns, conventions, and best practices for effective code assistance. |
0 commit comments