Calendar View UI

Relevant source files

The following files were used as context for generating this wiki page:

• internal/web/calendar_templ.go
• internal/app/calendar.go
• GLOSSARY.md
• README.md
• internal/app/ics.go
• internal/web/settings_templ.go

The Calendar View UI provides a central dashboard for managing a household's schedule through multiple time-based perspectives. It renders server-side using Go templates and includes four primary viewing modes: Month, Week, Day, and Agenda. The system distinguishes between "Household events," which appear for all users, and member-specific events that support individual filtering.

Sources: GLOSSARY.md:21-23, internal/web/calendar_templ.go:34-45, internal/app/calendar.go:94-98

Calendar Architecture and Data Structures

The calendar interface relies on a structured hierarchy of data to represent time periods, days, and individual occurrences. The CalendarPage struct serves as the top-level container for the view state, including navigation links and filtered data.

Core Data Models

Structure	Purpose	Key Fields
CalendarPage	Manages the overall state of the current view.	View, Date, Days, Users, Members, Calendars, ICS
CalendarDay	Represents a single date and its associated events.	Date, Today, Faded, Events
CalendarEvent	Represents one instance of an event on the UI.	ID, Original, Title, Time, Colors, ReadOnly
CalendarInfo	Defines metadata for specific calendar sources.	ID, Name, Color

Sources: internal/web/calendar_templ.go:17-45

View Navigation Flow

The application calculates the date range (span) based on the selected view and focal date. Navigation controls allow users to jump between "Previous," "Today," and "Next" periods.

The diagram shows the logic used to determine which dates and events to display when a user accesses the calendar.
Sources: internal/app/calendar.go:60-77, internal/app/calendar.go:94-110

Event Management and Interaction

Users interact with the calendar to create, edit, or delete events. The UI supports single events and complex recurring "Series."

Event Editing Scopes

When modifying a recurring event (Series), the UI provides three edit scopes:

• This event: A "One-off edit" affecting only the specific Occurrence.
• This and following: A "Split" that ends the current Series and starts a new one.
• All events: Changes the core Series definition.

Sources: GLOSSARY.md:25-37, internal/web/calendar_templ.go:343

Event Form Validation

The EventForm component handles user input for event details. It includes conditional logic to disable certain scopes if the user modifies time or repeat rules.

This sequence illustrates how the UI maintains data integrity by restricting edit scopes based on field changes.
Sources: internal/web/calendar_templ.go:347-363, internal/app/calendar.go:346-397

Real-time Updates and Sync

The Calendar View uses a native EventSource to implement live updates. This ensures the UI reflects changes made by other household members or external calendar feeds without manual refreshes.

Live Update Mechanism

1. The browser connects to /events/stream.
2. The backend publishes an event when a calendar, member, or event is created or updated.
3. The client receives a message and triggers the refresh function.
4. The refresh function fetches the current URL using fetch().
5. The script replaces the #live DOM region with the newly parsed content.

Sources: internal/web/calendar_templ.go:215-242, internal/app/calendar.go:214

External Integrations

The system supports two primary methods for interacting with external calendar data:

ICS Export

GoCasa provides an absolute URL for ICS export. This allows external clients to subscribe to household calendars. The export includes RRULE, EXDATE, and RDATE parameters to represent recurring series accurately.
Sources: internal/app/ics.go:17-20, internal/app/calendar.go:142

Read-Only Feeds

Users can add external iCal or webcal feeds through the Settings module. These events appear in the Calendar View but are marked as ReadOnly and cannot be edited within the GoCasa UI.
Sources: internal/web/settings_templ.go:187-189, internal/web/calendar_templ.go:114-117

Filtering and Presentation

The UI includes a filter section allowing users to toggle visibility based on household members. "Household events" (unassigned to specific members) always remain visible. Members are represented by avatars or initials on their designated color.

Sources: internal/web/calendar_templ.go:151-163, internal/web/settings_templ.go:38-46, GLOSSARY.md:21-23