context/DailyWorkAreaContext.ts

Purpose

DailyWorkAreaProvider manages the full lifecycle of the application’s “daily work area” workflow.

The provider coordinates:

• prompting the user to define a work area,
• restoring prior work-area selections,
• launching the work-area editor modal,
• pre-caching weather data for relevant geographic regions,
• seeding map state from device location,
• and exposing shared work-area state through React context.

This module acts as the orchestration layer between:

• UI (DailyWorkAreaModal),
• persistence (dailyWorkAreaStore),
• geolocation services,
• geocoding,
• and weather pre-cache infrastructure.

It provides a centralized workflow for ensuring the application has a valid geographic work area for weather-aware functionality.

Invariants

The provider maintains the following guarantees:

• Only one daily work-area gate check may execute at a time.

• The work-area modal is controlled entirely through provider state.

• Location-seeding requests are invalidated whenever modal state changes in a way that could make the result stale.

• The modal only auto-centers from device location when:

  • the modal is still visible,
  • the current open session matches the original request,
  • and no draft has already been selected.

• draftRef always mirrors the latest draft state value.

• visibleRef always mirrors the latest visible state value.

• Weather pre-cache operations always run using generated cache locations derived from a saved or fallback work area.

• The provider never blocks modal display if foreground location lookup fails.

• Address geocoding failures are surfaced through statusMessage instead of throwing.

• Saving a work area persists the circle before pre-caching weather.

• “Use previous work day” never modifies the stored fallback circle itself.

• Skipping pre-cache still marks the daily gate as handled.

• useDailyWorkArea() throws if used outside DailyWorkAreaProvider.

Modal Modes

The provider operates in two modal modes:

Variants

Gate Prompt Flow

Triggered through checkDailyWorkAreaGate() when:

• the user has not handled today’s work-area workflow,
• and no modal is currently visible.

Behavior:

• Loads persisted gate state.

• Opens the modal automatically.

• Seeds draft data from:

  • today’s saved circle,
  • fallback circle,
  • or current device location.

Manual Edit Flow

Triggered through openEditor().

Behavior:

• Opens the editor without daily-gate semantics.
• Uses existing saved/fallback circles when available.
• Allows closing without affecting daily prompt handling.

Draft-Based Editing

Occurs when the user:

• taps the map,
• selects an address suggestion,
• or geocodes an address manually.

Behavior:

• Updates the in-memory draft.
• Rebuilds map region state.
• Preserves existing radius where possible.

Weather Pre-cache Flow

Triggered after:

• saving today’s work area,
• or using the previous work day.

Behavior:

• Generates weather cache target locations.
• Pre-fetches weather data.
• Stores a human-readable cache status message.

Continue Without Pre-cache

Gate-only flow allowing the user to skip setup.

Behavior:

• Marks the daily gate as handled.
• Closes the modal.
• Records a skipped pre-cache status.

Foreground Location Seed

Executed when:

• the modal opens without an existing draft.

Behavior:

• Attempts to center the map near the user’s current location.
• Falls back silently to the default map region on failure.

Exports

Context Types

DailyWorkAreaContextValue

type DailyWorkAreaContextValue = {
  openEditor: () => void;
  checkDailyWorkAreaGate: () => Promise<void>;
  todayCircle: DailyWorkAreaCircle | null;
  fallbackCircle: DailyWorkAreaCircle | null;
  lastPrecacheStatus: string | null;
};

Shared context contract exposed by the provider.

Provider Component

DailyWorkAreaProvider

function DailyWorkAreaProvider({
  children,
}: {
  children: React.ReactNode;
})

Top-level orchestration provider responsible for:

• modal state,
• daily gate handling,
• weather pre-cache workflows,
• and shared work-area context.

Wraps the application subtree with DailyWorkAreaContext.Provider.

Hook

useDailyWorkArea

function useDailyWorkArea(): DailyWorkAreaContextValue

Context hook for accessing:

• work-area state,
• gate-check triggers,
• and editor controls.

Throws if used outside DailyWorkAreaProvider.

Internal Utility Functions

The following helpers are internal-only and not exported:

External Dependencies

UI

• DailyWorkAreaModal

Persistence

• getDailyWorkAreaGateState
• markDailyWorkAreaHandled
• saveDailyWorkAreaCircle

Services

• generateDailyWorkAreaCacheLocations
• geocodeWorkAreaAddress
• getForegroundLocationForWorkAreaSeed
• precacheWeatherForLocations

React Native Maps

Uses:

type Region

for map viewport state and initialization.