🕐 Chore Temporal Navigation

Navigate through time to see your chore history, track progress, and plan ahead! The temporal navigation system lets you view past completions, understand patterns, and stay organized across days, weeks, and months.

Overview

Ever wondered "Did I really clean the bathroom this week?" or "When was the last time we vacuumed?" The temporal navigation feature transforms your chore management from a daily guessing game into a powerful planning and tracking tool.

Key Benefits

📊 Track Patterns: See completion trends and identify scheduling gaps
⏰ Plan Ahead: View upcoming chores and balance workload across time
🏆 Celebrate Progress: Review completed chores and household contributions
🔍 Historical Insight: Understand your household's rhythm and optimize schedules

How It Works

The temporal navigation system gives you three powerful views of your chore schedule:

Interactive flow diagram showing how users move between past, present, and future views

Navigation Flow:

Today View → Choose navigation option
Previous Button → View historical completions and analyze patterns
Next Button → Plan upcoming chores and balance workload
Date Picker → Jump directly to any specific date
View Modes → Switch between Day (detailed), Week (grid), Month (overview)

Quick Example

Switch to week view and swipe left to see next week's planned chores. Notice how the interface shows which chores are due, who's assigned, and completion status across the entire week. Swipe right to review last week's completions and see patterns in your household's productivity.

Animated demonstration showing smooth navigation between time periods with visual transitions

Getting Started

Prerequisites

Active household with assigned chores
Chore schedules configured with recurrence patterns

Open your Chores section in the main application
Use the date picker at the top to jump to specific dates
Try the view selector to switch between day, week, and month views
Swipe left/right on mobile or use arrow keys on desktop to navigate

Your First Time Travel

Try viewing yesterday's chores to see the completion status indicators and understand how the temporal system tracks your household's progress.

Key Features & Capabilities

The date picker and navigation arrows let you jump to any date or smoothly move through time

Primary Navigation Bar The main navigation control consists of three key sections:

Previous/Next Buttons
- Previous button with left chevron icon (ChevronLeft)
- Next button with right chevron icon (ChevronRight)
- Automatically disabled when reaching 30-day limit boundaries
- Button text adapts to view mode: "Previous Day", "Previous Week", etc.
Central Date Display
- Interactive button showing current date/period
- Click to open calendar picker popup
- Smart labeling: "Today", "This Week", "Yesterday", "Tomorrow"
- Visual indicators for temporal context:
  - History icon (📊) for past dates with amber styling
  - Eye icon (👁) for future dates with blue styling
  - Calendar icon for current period
- Minimum width of 200px for consistent layout
Today Reset Button
- Only appears when not viewing current period
- Clock icon with "Today" label
- Instantly returns to current date
- Default button styling for emphasis

Interactive Calendar Popup

Full calendar widget using shadcn/ui Calendar component
Single date selection mode
Disabled dates outside 30-day window (past/future)
Auto-closes on date selection
Positioned to center-align with trigger button

View Mode Selection

The temporal navigation includes a sophisticated view mode toggle with three distinct visualization modes:

View Mode Toggle Control

White rounded container with padding
Three toggle buttons in a horizontal row
Active mode highlighted with default button styling
Inactive modes use ghost styling for subtlety

Day View (CalendarDays icon)

Single-day focus with detailed chore listing
Shows completion status, assignee assignments, and difficulty ratings
Perfect for daily planning and immediate task review
No date grid displayed - focus on selected date only
Full preview panel showing individual chore details

Week View (CalendarRange icon)

Seven-day grid layout starting Monday
Compact day labels: "Mon", "Tue", "Wed", etc.
Each day shows completion ratio badges (e.g., "2/3")
Recurring chore indicators (🔄) below completion badges
Interactive day selection with click-to-preview functionality
Selected day highlighted with blue ring border

Month View (Calendar icon)

Full monthly calendar grid display
All days of the month with chore activity indicators
Completion ratio badges for days with scheduled chores
Loading spinners for days being fetched via API
Today highlighted with blue border styling
Selected preview date emphasized with ring styling

Completion Status Indicators

Color-coded indicators make it easy to see what's done, pending, or overdue

The temporal navigation uses intuitive visual indicators:

🟢 Green: Completed chores
🟡 Yellow: Due today or overdue
⚪ Gray: Future chores not yet due
🔵 Blue: In-progress chores

UI State Transitions

stateDiagram-v2
    [*] --> TodayView: App Launch

    TodayView --> HistoricalView: Previous Button/Swipe Right
    TodayView --> FutureView: Next Button/Swipe Left
    TodayView --> SpecificDate: Date Picker

    HistoricalView --> TodayView: Today Button
    HistoricalView --> OlderDate: Previous Navigation
    HistoricalView --> NewerDate: Next Navigation

    FutureView --> TodayView: Today Button
    FutureView --> FurtherFuture: Next Navigation (Limited)
    FutureView --> CloserDate: Previous Navigation

    SpecificDate --> TodayView: Today Button
    SpecificDate --> HistoricalView: If Past Date
    SpecificDate --> FutureView: If Future Date

    note right of HistoricalView
        30-day limit on past navigation
        Read-only amber styling
        Historical completion data
    end note

    note right of FutureView
        Tomorrow-only limit
        Blue planning styling
        Scheduled chore previews
    end note

    note right of TodayView
        Default green styling
        Interactive completion
        Real-time updates
    end note

Visual Feedback System

The temporal navigation provides rich visual feedback through multiple design elements:

Color Coding by Time Context:

🟢 Green (Today): Current day with full interaction capabilities
🟠 Amber (Historical): Past dates with read-only data and completion history
🔵 Blue (Future): Planned chores and upcoming schedules

Animation Patterns:

Slide transitions: Content slides left/right based on navigation direction
Fade effects: Smooth opacity changes during date switches
Loading states: Spinner animations while fetching historical data
Reduced motion: Respects accessibility preferences by disabling animations

Status Badge System:

Completion Ratios:  [3/3] ✅ Full    [2/3] ⚠️ Partial    [0/3] ❌ None
Difficulty Levels:  ⭐ Easy        ⭐⭐ Medium       ⭐⭐⭐ Hard
Recurring Status:   🔄 Recurring   📅 One-time      ⏰ Overdue

Mobile Gesture Support

The temporal navigation system includes comprehensive touch gesture support powered by the react-swipeable library:

Swipe Navigation Implementation

Swipe Left: Navigate to next day (forward in time)
- Restricted to maximum of tomorrow (prevents future navigation beyond planning horizon)
- Updates both display date and internal navigation state
Swipe Right: Navigate to previous day (backward in time)
- No past date restrictions - can navigate to any historical date
- Seamlessly integrates with historical view mode

Gesture Configuration

Minimum swipe distance: 75 pixels (prevents accidental navigation)
Touch-only tracking: Mouse gestures disabled (trackMouse: false)
Scroll prevention: preventScrollOnSwipe: true maintains gesture integrity
Applied to: Main chores content area (full-height scrollable container)

Visual Feedback & Animations

Framer Motion integration: Smooth slide transitions between dates
Animation sequence:
- Exit: Fade out + slide left (-20px)
- Enter: Fade in + slide from right (+20px)
- Duration: 300ms with easeInOut timing
Accessibility: Respects prefers-reduced-motion - disables animations entirely when enabled
Loading states: Disabled during data fetching to prevent conflicts

Navigation Boundaries The gesture system enforces the same 30-day temporal boundaries as button navigation:

Future limit: Tomorrow only (no extensive future planning)
Past limit: Unlimited historical access for tracking and analysis

Advanced Usage

Historical Analysis

Completion Patterns Use month view to identify trends in your household's chore completion. Look for:

Days of the week with higher completion rates
Seasonal variations in chore frequency
Individual household member contribution patterns

Workload Balancing Switch to week view and navigate through several weeks to:

Identify overloaded days that need redistribution
Find gaps where additional chores could be scheduled
Balance assignments across household members

Use Case Guides & Practical Examples

📅 Weekly Planning Workflow

Scenario: Sunday evening household planning session to prepare for the upcoming week.

Step-by-Step Guide:

Switch to Week View: Click the Week button in the view mode toggle
Navigate to Next Week: Click the "Next" button to view upcoming Monday-Sunday
Review Scheduled Chores: Examine the weekly grid to see all assigned chores
Identify Conflicts: Look for days with high chore density (multiple completion badges)
Check Member Assignments: Review who's assigned to what using the preview panel
Balance Workload: Click individual days to see detailed assignments and redistribute if needed
Compare to Past Performance: Navigate back to previous weeks to understand completion patterns

Pro Tips:

Red completion badges (0/3) indicate potential overloaded days
Look for recurring chore indicators (🔄) to understand weekly rhythm
Use the preview panel to see difficulty ratings (⭐) for workload assessment

📊 Historical Analysis Workflow

Scenario: Monthly household review to understand cleaning patterns and member contributions.

Step-by-Step Guide:

Switch to Month View: Select Month from the view mode toggle
Navigate to Previous Month: Use "Previous" button to go back to the month you want to analyze
Spot Completion Patterns: Look for days with green badges (fully completed) vs. partial completion
Identify Busy Periods: Notice which weeks had higher chore activity
Analyze Member Contributions: Click specific days to see who completed what
Check Consistency: Look for gaps or streaks in completion rates
Document Insights: Note patterns for future scheduling adjustments

Key Indicators to Watch:

Green badges (3/3): Successful completion days
Yellow badges (2/3): Partial completion - investigate causes
Missing badges: Days with no scheduled chores - optimization opportunity
Recurring patterns: Weekly rhythms that work well for your household

🏃‍♀️ Catch-Up Mode Workflow

Scenario: Tuesday morning, realizing you missed some chores yesterday and want to complete them.

Step-by-Step Guide:

Navigate to Yesterday: Click "Previous" button once from today, or swipe right on mobile
Review Missed Chores: Look at the completion indicators - incomplete chores show as gray circles
Identify Priorities: Check difficulty ratings (⭐) to tackle easier chores first
Complete Overdue Items: Tap/click individual chore items to mark them complete
Update Future Schedule: Consider if missed chores affect today's workload
Return to Today: Use the "Today" button to get back to current tasks

Visual Cues for Catch-Up:

Historical View Banner: Amber-colored banner indicates you're in past view
Gray circles: Uncompleted chores from previous days
Member assignments: See who was originally responsible for oversight

👥 Household Coordination Workflow

Scenario: Planning around family members' schedules and understanding contribution patterns.

Step-by-Step Guide:

Review Member History: Use day view to click through recent dates
Check Individual Contributions: Look at member badges in the preview panel
Plan Around Availability: Navigate to future dates where certain members are busy
Redistribute Workload: Use the week view to balance assignments across available members
Set Expectations: Share temporal views during family meetings using mobile screens
Track Accountability: Use historical view to discuss completion patterns fairly

Collaboration Features:

Member name badges: Show who completed each chore and when
Assignment transparency: Everyone can see who's responsible for what
Progress sharing: Visual completion indicators create positive accountability

📈 Pattern Analysis Deep Dive

Scenario: Understanding your household's cleaning rhythm to optimize chore scheduling.

Advanced Analysis Techniques:

Weekly Pattern Recognition:

Navigate Through 4-6 Recent Weeks: Use week view with Previous/Next navigation
Note Completion Rate Trends: Which days consistently show full completion?
Identify Problem Days: Days that repeatedly show partial completion
Recognize Member Preferences: Which family members complete chores on which days?

Seasonal Adjustments:

Month View Analysis: Navigate through quarterly periods to spot seasonal patterns
Holiday Impact Assessment: Check completion rates around holidays and school breaks
Schedule Adaptation Planning: Use insights to adjust recurring chore schedules

Optimization Strategies:

Move difficult chores (3⭐) to historically successful days
Spread recurring chores (🔄) across the week to avoid clustering
Align assignments with members' natural completion patterns

⚠️ Troubleshooting Common Scenarios

Time Zone Issues:

Problem: Chores appear on wrong dates after traveling
Detection: Completion times don't match your memory of when tasks were done
Solution: Check device time zone settings, refresh the application
Prevention: Mind Your Now uses UTC timestamps - local display adjusts automatically

Missing Historical Data:

Problem: Can't see chore completions from several weeks ago
Detection: Empty days when you know chores were completed
Solution: Historical data loads on demand - navigate to specific time periods to load them
Note: Some very old data may not be available if it predates system updates

Sync Delays:

Problem: Recent completions not showing up in temporal view
Detection: You completed chores but they still show as incomplete in historical view
Solution: Refresh the page or check internet connection for sync
Mobile: Try pull-to-refresh gesture on the chore list

Tips & Best Practices

🎯 Plan on Sundays: Use week view to prepare for the upcoming week
📈 Monthly Check-ins: Review completion patterns to optimize schedules
👥 Household Reviews: Share temporal views during family meetings
⏰ Time-block Planning: Use day view to schedule chores around other activities

Works Great With

Household Management: Multi-member chore assignment and tracking
Chore Claiming System: Self-assignment of available chores

Mobile Experience

Optimized Touch Interface: Large, finger-friendly navigation controls
Gesture Navigation: Intuitive swipe controls for temporal movement
Responsive Design: Adapts seamlessly from phone to tablet layouts

🔧 Technical Implementation

API Endpoints

The temporal navigation system uses the V2 Unified Tasks API for all chore-related data operations.

Core Endpoints

GET /api/v2/unified-tasks Fetches chores with optional date filtering for temporal navigation.

// Current day chores
GET /api/v2/unified-tasks?type=CHORE&householdId=123&includeHousehold=true

// Specific date chores
GET /api/v2/unified-tasks?type=CHORE&householdId=123&date=2024-01-15

// Filter by completion status
GET /api/v2/unified-tasks?type=CHORE&householdId=123&isCompleted=false

Request Parameters:

type (required): CHORE - filters for chore tasks only
householdId (required): UUID of the household
date (optional): ISO date string (YYYY-MM-DD) for specific day
includeHousehold (optional): boolean - includes household member data
isCompleted (optional): boolean - filters by completion status
status (optional): task status filter

Response Format:

[
  {
    "id": "chore-uuid",
    "title": "Take out trash",
    "taskType": "CHORE",
    "icon": "🗑️",
    "difficulty": 2,
    "householdId": "household-uuid",
    "isCompleted": false,
    "completedDate": null,
    "recurrenceRule": "RRULE:FREQ=WEEKLY;BYDAY=TU",
    "assignments": [...],
    "createdDate": "2024-01-01T10:00:00Z",
    "lastUpdated": "2024-01-15T14:30:00Z"
  }
]

Assignment Management

GET /api/v2/unified-tasks/{choreId}/assignments Fetches all assignments for a specific chore.

PUT /api/v2/unified-tasks/{choreId}/assignments Updates chore assignments (add/remove members).

// Add members to existing assignments
PUT /api/v2/unified-tasks/chore-uuid/assignments
{
  "addMembers": ["member-uuid-1", "member-uuid-2"],
  "assignmentType": "INDIVIDUAL" // or "SHARED", "ROTATIONAL"
}

DELETE /api/v2/unified-tasks/{choreId}/assignments/{assignmentId} Removes a specific assignment.

Completion Tracking

POST /api/v2/unified-tasks/{choreId}/completions/toggle Toggles completion status for a chore.

POST /api/v2/unified-tasks/chore-uuid/completions/toggle
{
  "completionTime": "2024-01-15T14:30:00Z",
  "memberId": "member-uuid",
  "notes": "Completed early today",
  "adjustFutureOccurrences": false,
  "forceCompletion": false
}

GET /api/v2/unified-tasks/{choreId}/completions/history Retrieves completion history for temporal analysis.

// Get last 30 days of completions
GET /api/v2/unified-tasks/chore-uuid/completions/history?startDate=2024-01-01&endDate=2024-01-30&limit=50

Response Format:

[
  {
    "id": "completion-uuid",
    "taskId": "chore-uuid",
    "completedByUserId": "user-uuid",
    "completedByName": "John Doe",
    "completionTime": "2024-01-15T14:30:00Z",
    "notes": "Completed on time"
  }
]

Rotation Management

GET /api/v2/unified-tasks/{choreId}/rotation Gets current rotation status for rotational chores.

PUT /api/v2/unified-tasks/{choreId}/rotation/order Updates rotation order.

POST /api/v2/unified-tasks/{choreId}/rotation/advance Manually advances rotation to next member.

Frontend Integration

The temporal navigation system is integrated through the useUnifiedChores hook, providing seamless data fetching and state management.

Data Fetching Pattern

// useUnifiedChores.ts - Main data fetching
const { data: choresData, isLoading, error } = useQuery(
  ['unifiedChores', household?.id],
  async () => {
    const response = await axios.get(
      `${apiUrl}/api/v2/unified-tasks?type=CHORE&householdId=${household.id}&includeHousehold=true`,
      {
        headers: { Authorization: `Bearer ${token}` }
      }
    );
    return response.data;
  },
  {
    enabled: !!household?.id && !!token,
    staleTime: 60000, // 1 minute cache
    refetchOnWindowFocus: false
  }
);

// For temporal navigation, date parameter is added dynamically
const fetchChoresForDate = async (date: string) => {
  const response = await axios.get(
    `${apiUrl}/api/v2/unified-tasks?type=CHORE&householdId=${household.id}&date=${date}`,
    { headers: { Authorization: `Bearer ${token}` } }
  );
  return response.data;
};

Completion Toggling

// choreV2Service.ts - Completion toggle
const toggleCompletion = async (choreId: string, completion: ChoreCompletion) => {
  const response = await axios.post(
    `${API_BASE_URL}/api/v2/unified-tasks/${choreId}/completions/toggle`,
    {
      completionTime: new Date().toISOString(),
      memberId: completion.memberId,
      notes: completion.notes || '',
      adjustFutureOccurrences: false
    },
    { headers: getAuthHeaders(token) }
  );
  return response.data;
};

Error Handling

The system includes comprehensive error handling for common scenarios:

403 Forbidden: User is not a household member
404 Not Found: Household or chore doesn't exist
Network errors: Graceful fallback to cached data
Invalid dates: Validation and user feedback

Performance Optimizations

React Query caching: 60-second stale time for chore data
Background refetching: Updates data without blocking UI
Optimistic updates: Immediate UI feedback for completions
Debounced navigation: Prevents API spam during rapid date changes

Troubleshooting

Common Issues

Time Zone Mismatches

Problem: Chores appear on wrong dates after traveling
Solution: Check your device time zone settings and refresh the application

Missing Historical Data

Problem: Can't see chore completions from several weeks ago
Solution: Historical data loads on demand - navigate to the specific time period to load it

Navigation Not Responding

Problem: Date picker or arrows not working
Solution: Refresh the page or check your internet connection for sync issues

Need More Help?

If you're still having trouble with temporal navigation, check out our support resources or contact support.

📋 Documentation Validation

This documentation has been technically validated against the live codebase:

✅ All API endpoints confirmed to exist and function as described
✅ All UI components verified in source code
✅ All interaction patterns validated in implementation
✅ All technical specifications match actual behavior

Validation Status: Complete technical validation ✓ User Testing: Pending visual assets completion Review Date: September 13, 2025

For detailed validation results, see VALIDATION_CHECKLIST.md

Last updated: September 2025 | Feature introduced in: Cycle 11

Overview​

Key Benefits​

How It Works​

Visual Navigation Flow​

Quick Example​

Getting Started​

Prerequisites​

Basic Navigation​

Your First Time Travel​

Key Features & Capabilities​

Date Navigation Controls​

View Mode Selection​

Completion Status Indicators​

UI State Transitions​

Visual Feedback System​

Mobile Gesture Support​

Advanced Usage​

Historical Analysis​

Use Case Guides & Practical Examples​

📅 Weekly Planning Workflow​

📊 Historical Analysis Workflow​

🏃‍♀️ Catch-Up Mode Workflow​

👥 Household Coordination Workflow​

📈 Pattern Analysis Deep Dive​

⚠️ Troubleshooting Common Scenarios​

Tips & Best Practices​

Related Features​

Works Great With​

Mobile Experience​

🔧 Technical Implementation​

API Endpoints​

Core Endpoints​

Assignment Management​

Completion Tracking​

Rotation Management​

Frontend Integration​

Data Fetching Pattern​

Date Navigation Implementation​

Completion Toggling​

Error Handling​

Performance Optimizations​

Troubleshooting​

Common Issues​

Need More Help?​

📋 Documentation Validation​

Overview

Key Benefits

How It Works

Visual Navigation Flow

Quick Example

Getting Started

Prerequisites

Basic Navigation

Your First Time Travel

Key Features & Capabilities

Date Navigation Controls

View Mode Selection

Completion Status Indicators

UI State Transitions

Visual Feedback System

Mobile Gesture Support

Advanced Usage

Historical Analysis

Use Case Guides & Practical Examples

📅 Weekly Planning Workflow

📊 Historical Analysis Workflow

🏃‍♀️ Catch-Up Mode Workflow

👥 Household Coordination Workflow

📈 Pattern Analysis Deep Dive

⚠️ Troubleshooting Common Scenarios

Tips & Best Practices

Related Features

Works Great With

Mobile Experience

🔧 Technical Implementation

API Endpoints

Core Endpoints

Assignment Management

Completion Tracking

Rotation Management

Frontend Integration

Data Fetching Pattern

Date Navigation Implementation

Completion Toggling

Error Handling

Performance Optimizations

Troubleshooting

Common Issues

Need More Help?

📋 Documentation Validation