Introducing a new way to review your PRs.

Read the announcement

usememos / memos

Memos is an open-source, self-hosted note-taking app that brings your everyday thoughts together in a personal timeline. Your data stays yours, and you choose what to keep private or share.

View on GitHub

25 documents · Updated Nov 20, 2026

docs / calendar-and-temporal-memo-views

Calendar and temporal memo views

The calendar view gives signed-in users a time-based way to browse and create memos. It turns one month into a day grid and a selected-day memo view, while the URL keeps the month, day, Space, and active filters in one navigable state. See Web application experience for the wider shell and Memo authoring and browsing UI for the shared memo cards and editor.

Calendar route

Route scope

The calendar is a protected collection view. It is available as a global route and as a Space route, so the same experience can show either the user's main collection or the selected Space. The route accepts a year, month, and optional day. Invalid or incomplete date values return to the current month instead of leaving the page in an unclear state.

The URL is the source of truth for temporal state. A month path such as /calendar/2026/08 shows the month, while /calendar/2026/08/07 also opens 7 August. Calendar links keep the current query string, which lets view and tag filters continue to narrow the calendar as the user moves between months and days.

References: web/…/index.tsx• L91-100 web/…/index.tsx• L111-125 web/…/Calendar.tsx• L7-19 web/…/paths.ts• L12-31 web/…/CalendarLink.tsx• L5-17

Month data

The month view combines two kinds of data. Statistics provide a fast memo count for each calendar day, while the month query provides the memos needed for previews and the selected-day view. The view applies the same collection, view, tag, and time-basis rules used by the related memo collection before it adds the local month range.

The month is treated as a local calendar period. The selected time basis is either memo creation time or update time, so changing that preference changes both which month contains a memo and how the day view is ordered. The month model then creates stable day summaries from the full result: it keeps all memos for the day, records the creators in first-seen order, and selects a short readable preview and limited image set without exposing redacted memo content. This keeps counts, previews, and day contents aligned.

References: web/…/CalendarView.tsx• L60-91 web/…/useMonthMemos.ts• L12-56 web/…/calendar-utils.ts• L32-72 web/…/dayModel.ts• L187-220

Month grid

The month grid gives each day a direct entry point to that day's memo view. It pads the first and last weeks with nearby dates, follows the instance's preferred first day of the week, and marks today and the selected day so the user can keep time context while browsing.

Each current-month cell can show a count, a short safe preview, and a small set of image previews when the cell has room. Preview capacity follows the measured grid size, so the content remains usable when the viewport or the adjacent day panel changes the available space. The preview model uses readable memo content first and can fall back to an attachment name when no readable text exists. It keeps hidden memos in day counts and author context but excludes their text and images. While memo data is still loading, a cell can show a loading mark when its statistics already show activity. Empty and out-of-month cells remain part of the grid but do not claim memo content for the shown month.

References: web/…/CalendarGrid.tsx• L41-124 web/…/CalendarDayCell.tsx• L35-45 web/…/CalendarDayCell.tsx• L93-179 web/…/monthDays.ts• L24-59 web/…/MonthCalendar.tsx• L31-69 web/…/dayModel.ts• L115-185 web/…/dayModel.ts• L187-220

Temporal navigation

Month navigation

The calendar header provides adjacent-month controls, a month picker, and a Today control. Adjacent-month links move one month at a time. The picker lets the user step through years and choose any month. Today returns to the current month and opens or closes today's day view when the layout supports a closable panel.

Navigation changes the URL rather than hiding state inside the view. This makes month and day locations bookmarkable and lets normal browser history and link behavior work across the calendar. The current query string stays attached to these changes, so a filtered calendar does not silently become unfiltered.

References: web/…/CalendarHeader.tsx• L12-64 web/…/MonthPicker.tsx• L24-97 web/…/CalendarLink.tsx• L11-17

Day movement

The grid supports direct selection and keyboard movement. Arrow keys move by one day or one week, while Home and End move to the first and last date of the month. Horizontal movement follows the interface direction, so right-to-left layouts keep the expected physical key behavior. The grid has one keyboard entry point: the open day when one exists, otherwise today for the current month or the first day of another month.

Selecting a cell navigates to the corresponding day path. The selected cell then remains visible as the user's position while the day view appears beside or below the grid according to the screen size.

References: web/…/CalendarGrid.tsx• L41-91 web/…/CalendarDayCell.tsx• L47-61 web/…/CalendarDayCell.tsx• L120-135 web/…/paths.ts• L28-37

Day-panel interactions

Day stream

The day view presents the memos for one date in time order. It uses the normal memo view, so memo display, reactions, comments, visibility, pin state, and Space context remain familiar across the Home view and calendar. On layouts with a separate panel, the view has its own date heading and can be closed.

The calendar keeps day contents from the already loaded month. This lets a user move between days without a second day-specific load and keeps the grid preview and day view based on the same day model. The model includes every memo in the day stream and keeps the selected time basis as its ordering rule.

References: web/…/CalendarView.tsx• L94-119 web/…/dayModel.ts• L187-220 web/…/MemoPanelList.tsx• L46-108 web/…/MemoPanel.tsx• L53-61

Day memo creation

The day view ends with a new-memo action for the selected date. Opening it places the standard memo editor in the day view and seeds the memo's creation time from that date. Changing to another day closes the in-progress day editor, which prevents an unfinished entry from silently changing dates.

References: web/…/CalendarView.tsx• L104-119 web/…/MemoPanelList.tsx• L32-44 web/…/MemoPanelList.tsx• L86-107

Responsive day placement

The day view changes placement to keep both the calendar and memo content usable. From medium screens it appears in a resizable side panel. On smaller screens the grid becomes compact and the day view appears below it, with today or the first day shown by default until the URL names a day.

The grid measures its available cell area so each day can choose an appropriate amount of preview text and media. The side-panel width is remembered between visits. Closing the side panel removes the day from the URL while preserving the month and active filters. The inline layout uses the same day content without a separate close action.

References: web/…/CalendarView.tsx• L27-45 web/…/CalendarView.tsx• L94-165 web/…/CalendarGrid.tsx• L58-71 web/…/CalendarDayCell.tsx• L35-45 web/…/MemoPanel.tsx• L53-61

Application shell integration

The application shell exposes Calendar as a primary navigation item for signed-in users and marks it active for both global and Space calendar paths. Its route sidebar shows the collection's view and tag filters without the separate statistics block used by the main memo collection. Search from Calendar returns to the matching collection's Home view because Calendar is a browse view rather than a memo list route.

The calendar follows the shell's collection rules. Switching Spaces carries the calendar route and query when the current page is a collection view, so the temporal view stays in the user's chosen collection.

References: web/…/AppSidebar.tsx• L108-149 web/…/AppSidebar.tsx• L287-300 web/…/AppSidebar.tsx• L376-392 web/…/routes.ts• L28-49 web/…/routes.ts• L30-73

Calendar flow

The following flow shows how a calendar URL becomes a month grid and an optional day interaction.

flowchart LR
    A[Calendar URL] --> B[Validate month and day]
    B --> C[Resolve Space and query filters]
    C --> D[Load month counts and memos]
    D --> E[Build day summaries]
    E --> F[Measure and render month grid]
    F --> G[Select a day]
    G --> H[Open day view]
    H --> I[Read or create a memo]

The route and shell establish scope first. The calendar then joins day counts with memo summaries and sizes each cell for the available layout. A day selection reuses the matching summaries for browsing or authoring.

References: web/…/index.tsx• L75-125 web/…/Calendar.tsx• L7-19 web/…/CalendarView.tsx• L64-148 web/…/CalendarGrid.tsx• L49-124 web/…/dayModel.ts• L187-220 web/…/MemoPanelList.tsx• L51-107

The calendar complements the memo list rather than replacing it. Use Memo authoring and browsing UI for the shared memo reading and editing experience, and Web settings and account management for the instance setting that controls the first day of the week and other calendar context. The parent Web application experience explains how these views fit into the complete web shell. Map-based memo exploration provides a separate location-based way to explore memo metadata.

Change checklist

When these files or sections are changed, remember to consider these:

  • Route changes must keep global and Space calendar paths aligned, including collection detection and Space preservation.
  • Changes to memo filters or the selected time basis must update both the month query range and the day statistics source.
  • Changes to the day model must keep grid counts, creator context, previews, redaction behavior, and day-view memo order consistent.
  • Changes to calendar links must preserve the active query string so view and tag filters do not disappear during temporal navigation.
  • Changes to responsive panel behavior must keep URL close behavior, keyboard focus, and the small-screen default day in sync.
  • Changes to grid sizing or cell previews must keep measured layout, loading feedback, and the available text and image content aligned at all viewport sizes.

Important failure modes

TriggerConsequenceGuard
An invalid month or day reaches the calendar pageThe view could request an undefined time range or show a non-existent dateValidate route parameters and redirect invalid input to the current month
The month query returns only one page of memosCounts and day views can omit memos from a busy monthDrain all pages before building the month model
The month query failsA failed month could look like an empty monthShow the memo-list error and keep the empty-month message disabled while an error exists
A calendar link drops the query stringView and tag filters stop applying after month or day navigationRoute links carry the current search string
Tag settings load after previews renderA memo that must be blurred can briefly expose text or imagesDelay the month model until user settings are ready
A day editor remains open after the selected date changesA new memo can be saved under the wrong dayTie the composing state to the selected date and close it when the date changes
Cell content ignores the space lost to a resized panelDay previews can be clipped or crowd the date and media areasMeasure the grid and derive preview capacity from the current cell size

Key files

FileWhy to read it
web/…/Calendar.tsxShows the route entry point and invalid-date redirect.
web/…/CalendarView.tsxShows how filters, month data, grid state, and responsive day placement join together.
web/…/useMonthMemos.tsShows the month-level data boundary and full-month loading rule.
web/…/dayModel.tsShows how memos become per-day order, creator context, excerpts, and image previews.
web/…/CalendarGrid.tsxShows the day grid, measured preview layout, focus movement, counts, and selected-day state.
web/…/CalendarDayCell.tsxShows how a day becomes a navigable cell with counts, previews, media, and loading feedback.
web/…/MemoPanelList.tsxShows how the calendar reuses memo cards and date-aware memo creation.
web/…/MemoPanel.tsxShows the shared responsive panel used for a selected day.
web/…/CalendarHeader.tsxShows month, year, adjacent-month, and Today navigation.
web/…/AppSidebar.tsxShows Calendar's primary navigation and route-specific shell content.
web/…/routes.tsShows collection scope and global-versus-Space path behavior.