Skip to content

.copilot-instructions.md

Latest commit

 

History

History
198 lines (156 loc) · 6.8 KB

.copilot-instructions.md

File metadata and controls

198 lines (156 loc) · 6.8 KB

GitHub Copilot Instructions for Datas Project

Project Overview

Datas is a JavaScript vanilla utility library for date manipulation, developed using "vibe coding" methodology with Claude AI assistance.

Key Technologies

  • Language: JavaScript ES6+ (Vanilla, no frameworks)
  • Testing: Jest with jsdom environment
  • Styling: CSS3 with Flexbox/Grid and responsive design
  • Deployment: GitHub Pages
  • Language: Portuguese (Brazil) for UI and documentation

Core Architecture

Main Components

  1. DateUtils Class (date-utils.js)

    • Static utility methods for date operations
    • Core functionality includes: date differences, age calculation, moon phases, calendar generation
    • Uses astronomical algorithms for lunar calculations

  2. App Interface (app.js)

    • DOM manipulation and event handling
    • User interface logic for the HTML forms
    • Connects UI elements to DateUtils methods

  3. Test Suite (*.test.js)

    • Comprehensive Jest tests (54+ tests)
    • Pattern: describe() blocks by class/method, test() for specific cases
    • Uses mocks for Date objects to ensure deterministic testing

File Structure Pattern

├── index.html          # Main interface
├── styles.css          # Responsive styles with Wildtech gradient
├── date-utils.js       # Core utility class
├── app.js             # UI interaction logic
├── *.test.js          # Jest unit tests
├── jest.setup.js      # Test configuration
└── documentation files

Coding Conventions

JavaScript Style

  • ES6 Classes: Use static methods for utilities
  • Arrow Functions: For callbacks and short functions
  • Template Literals: For HTML generation and multi-line strings
  • Destructuring: For object/array operations
  • No Frameworks: Pure vanilla JavaScript only

Method Naming

  • Camel Case: calculateAge, daysBetween, getMoonPhase
  • Boolean Methods: Prefix with is - isLeapYear, isWeekend
  • Get Methods: For data retrieval - getWeekNumber, getQuarter
  • Generate Methods: For creating complex structures - generateCalendar

Return Patterns

  • Primitive Returns: Numbers, strings, booleans for simple calculations
  • Object Returns: For complex data like {years, months, days} from calculateAge
  • Array Returns: For collections like calendar data or moon phases

Date Handling Patterns

Date Input Processing

// Always create new Date instances to avoid mutation
const d1 = new Date(date1);
const d2 = new Date(date2);

// Use Math.abs for distance calculations
const diffTime = Math.abs(d2 - d1);
const diffDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24));

Date Formatting Standards

  • dd/mm/yyyy: Default Brazilian format
  • yyyy-mm-dd: ISO format for calculations
  • extenso: Full Portuguese format with day names
  • Month Names: Use Portuguese month/day names from predefined arrays

Astronomical Calculations

  • Julian Day: Base for lunar calculations using astronomical formula
  • Synodic Month: 29.53058867 days lunar cycle
  • 8 Moon Phases: Nova, Crescente, Quarto Crescente, Gibosa Crescente, Cheia, Gibosa Minguante, Quarto Minguante, Minguante

UI Patterns

HTML Structure

  • Semantic IDs: Use descriptive IDs like calculateBtn, resultDiv, date1, date2
  • Form Organization: Group related inputs in sections
  • Result Display: Use dedicated divs with styled borders for feedback

CSS Classes and Styling

  • Color Scheme: Wildtech gradient from orange (#ff7b00) to brown (#8b4513)
  • Responsive Design: Mobile-first approach with flexbox
  • Visual Feedback: Border colors for success (green) and error (red) states

Event Handling

// Pattern for event listeners
document.addEventListener('DOMContentLoaded', function() {
    // Initialize all event listeners here
    document.getElementById('calculateBtn').addEventListener('click', calculateFunction);
});

// Validation pattern
if (!input || !isValid(input)) {
    resultDiv.textContent = 'Error message in Portuguese';
    resultDiv.style.borderLeftColor = '#dc3545';
    return;
}

Testing Patterns

Test Structure

describe('ClassName', () => {
  describe('methodName', () => {
    test('deve fazer algo específico', () => {
      // Arrange
      const input = 'test value';
      
      // Act
      const result = DateUtils.method(input);
      
      // Assert
      expect(result).toBe(expected);
    });
  });
});

Mock Patterns

  • Date Mocking: Mock Date constructor for deterministic tests
  • DOM Mocking: Use jsdom setup for UI testing
  • Cleanup: Restore original implementations after each test

Test Categories

  • Happy Path: Normal use cases
  • Edge Cases: Leap years, month boundaries, weekend detection
  • Error Cases: Invalid inputs, null/undefined handling
  • Astronomical: Moon phase calculations with known dates

Common Development Tasks

Adding New Date Utility

  1. Add static method to DateUtils class
  2. Follow naming conventions (camel case, descriptive)
  3. Handle edge cases (invalid dates, null inputs)
  4. Add comprehensive tests
  5. Update UI if needed
  6. Document in README if user-facing

Adding UI Feature

  1. Update HTML structure with semantic IDs
  2. Add event listeners in app.js
  3. Follow validation pattern with visual feedback
  4. Add responsive CSS if needed
  5. Test manually and with Jest

Moon Phase Calculations

  • Use existing julianDay helper for date conversion
  • Follow astronomical formulas for accuracy
  • Return Portuguese phase names
  • Include emoji icons for visual representation

Performance Considerations

  • Date Object Creation: Create new instances instead of mutating
  • Calculation Efficiency: Use mathematical operations over iteration
  • Memory Management: Avoid storing large date arrays unnecessarily
  • DOM Updates: Batch DOM changes when possible

Internationalization Notes

  • Language: All user-facing text in Portuguese (Brazil)
  • Date Formats: Use Brazilian conventions (dd/mm/yyyy)
  • Month/Day Names: Portuguese language arrays
  • Error Messages: Provide helpful Portuguese error messages

Dependencies and Environment

  • Runtime: Browser environment (ES6+ support required)
  • Testing: Node.js with Jest and jsdom
  • No External Libraries: Keep project dependency-free
  • Build: No build process - direct file serving

Documentation Standards

  • JSDoc: Use for complex methods and classes
  • README: Keep user-focused with examples
  • Comments: Minimal but clear, in Portuguese when needed
  • Tests as Documentation: Comprehensive test cases show intended usage

This file provides GitHub Copilot with comprehensive context about the Datas project patterns, conventions, and best practices for effective code assistance.