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 / map-based-memo-exploration

Map-based memo exploration

Map-based memo exploration lets signed-in users find memos with saved locations on a full-screen map. It joins the active memo scope and filters with a geographic view so users can select nearby memos, inspect their metadata, keep a place in the URL, and create a new memo at a selected point. It is the map view of the wider web application experience, and it complements memo authoring and browsing and calendar and temporal memo views.

Map route

The map is a signed-in collection route at /map. It also exists below a Space, where the URL keeps the active Space while the map shows that Space's memo collection. The route uses the full available viewport instead of the normal page scroll area, which gives the canvas room for panning and for the memo panel.

The sidebar opens the map without dropping the current collection context. Map navigation also remains a first-class collection action, so changing Space preserves the map state and Quick Find returns to the matching Home collection.

References: web/…/index.tsx• L107-137 web/…/routes.ts• L29-63 web/…/AppSidebar.tsx• L380-403 web/…/RootLayout.tsx• L43-53

Location-aware memo retrieval

The map requests the normal memos that are visible in the current user and Space context. It adds the has_location condition, so the canvas receives only memos that can be placed on the map. The active view filters and time basis still apply, which keeps the map aligned with the rest of the collection rather than making it a separate search result.

The map loads all result pages before it declares the collection complete. It keeps partial results during a failed page load and can retry the failed request. The result set is then deduplicated, checked for valid coordinates, and ordered by the active memo time basis. Changes made through shared memo actions update the map data as well.

References: web/…/useMapMemos.ts• L13-36 web/…/model.ts• L11-35

Map canvas

The canvas turns location-bearing memos into selectable map markers. Nearby markers form a count cluster to keep dense areas readable; selecting a marker or cluster opens the related memos in the reading panel instead of forcing the user to zoom first. A click on the bare map closes the current selection.

The map fits the loaded locations once after the first complete load. Users can then pan and zoom without the next data refresh changing their view. When a selection opens a panel, the canvas makes the selected point visible beside that panel on desktop or above the bottom sheet on a small screen.

The main map interactions are:

  • Select one marker to read the memo at that place.
  • Select a cluster to read all memos represented by that cluster.
  • Use the fit control to return to all visible locations.
  • Use desktop zoom controls or normal touch and pointer gestures to change scale.
  • Click the bare map to close the memo panel.

References: web/…/MapCanvas.tsx• L32-38 web/…/MapCanvas.tsx• L40-88 web/…/MapCanvas.tsx• L92-152 web/…/MapView.tsx• L194-237

Basemap layers

The basemap supplies geographic context behind the memo markers. The preferred layer uses a quiet OpenFreeMap vector style that follows the resolved light or dark theme. A style that stalls, cannot start, or loses its graphics context causes the map to fall back to OpenStreetMap raster tiles.

The vector layer does not fall back for an individual tile or sprite request that fails after the style loads. A basemap failure is separate from memo data, so it does not remove the memo markers or their panel. If the fallback tiles also fail, the map reports the tile problem and offers a retry. Theme changes restyle the active vector layer without resetting its map context. The map keeps attribution visible for the active map source.

References: web/…/BasemapLayer.tsx• L8-15 web/…/BasemapLayer.tsx• L17-84 web/…/map-utils.tsx• L5-13 web/…/positron.ts• L1-29

View state and memo panel

The map stores its navigable state in the URL. This makes a place view shareable and lets a memo detail view return to the same map context. The map reads a center and zoom from lat, lng, and zoom; selected memo names use repeated memo parameters; active memo filters remain in the existing filter parameters.

URL stateUser-facing purpose
lat, lng, zoomRestore the current map view after navigation or reload
memoOpen one or more selected memos in the panel
filterKeep the same collection constraints as other memo views

The panel shows the selected memo metadata and groups a selection by its place label. When all selected memos share one coordinate, it offers a new memo action at that location. The editor starts with the location already set, so a user can move from geographic discovery to place-based authoring without entering the coordinates again.

After a new memo is saved, the map refreshes its location-aware results. If the saved memo is outside the active filters, the map does not pretend that it is selected; it offers a direct link to open the memo instead.

References: web/…/MapView.tsx• L25-149 web/…/MapView.tsx• L265-301 web/…/model.ts• L18-26 web/…/model.ts• L37-58

Map exploration flow

This flow shows how collection scope and filters become geographic memo metadata and then return to the memo reader or editor.

flowchart TD
    A[Open map route] --> B[Build active collection filters]
    B --> C[Load normal memos with locations]
    C --> D[Load all result pages]
    D --> E[Place valid memos on map]
    E --> F{User action}
    F -->|Pan or zoom| G[Save viewport in URL]
    F -->|Select marker or cluster| H[Open memo panel]
    F -->|Fit all| I[Fit visible locations]
    H --> J{Shared location}
    J -->|Yes| K[Offer new memo at place]
    J -->|No| L[Read selected metadata]
    K --> M[Refresh map after save]
    L --> N[Open memo detail or related content]

The URL is the link between map movement and the rest of the application. A map selection can open memo detail with the map as its return origin, and a Space switch keeps the selection, viewport, and filters under the new collection path when the state remains valid.

References: web/…/useMapMemos.ts• L16-36 web/…/MapView.tsx• L65-149 web/…/map-routes.test.ts• L7-22

Change checklist

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

  • Keep the has_location map condition aligned with the location field used by memo creation and memo updates. A mismatch can make a saved location invisible on the map.
  • Preserve the URL contract for lat, lng, zoom, repeated memo, and filter values when changing route navigation or memo detail origins. These values carry the user's map context across pages and Space switches.
  • Keep the map's collection route classification aligned across router matching, Space path building, sidebar actions, Quick Find, and full-bleed layout behavior.
  • Keep vector basemap failure handling separate from raster tile failure handling. A vector tile or sprite error after the style loads should not trigger the raster fallback, show a final tile error, or discard memo data.
  • Keep selection cleanup delayed until all memo pages load. Early cleanup can remove a valid deep-linked memo before its page arrives.

Important failure modes

TriggerConsequenceGuard
A result page fails during the full map loadThe map shows partial locations but must not claim that the collection is completeKeep complete false and retry the failed page
A selected memo is not present after all pages loadThe URL can point to a memo that is no longer in the active collectionRemove only unavailable selections after pagination completes
A map style stalls, WebGL fails, or the graphics context is lostThe preferred basemap cannot provide geographic contextReplace it with OpenStreetMap tiles
An individual vector tile or sprite request fails after the style loadsThe vector map may have a partial background but remains usableDo not treat post-load resource errors as fatal to the vector layer
OpenStreetMap tiles also failThe map background may be incomplete or blankShow a tile error and allow a tile redraw retry
A saved memo does not match the active map filtersThe new memo is not visible in the current marker setShow a link to the memo instead of creating a false map selection
A selection opens under the memo panelThe selected marker can be hidden by the side rail or bottom sheetPan by the smallest offset that keeps the point visible

Key files

FileWhy to read it
web/…/index.tsxShows the authenticated global and Space-specific map routes
web/…/MapView.tsxShows the map page flow, URL state, panel behavior, and map controls
web/…/useMapMemos.tsShows which memos the map can retrieve and when loading is complete
web/…/MapCanvas.tsxShows marker selection, clustering, viewport behavior, and map interactions
web/…/model.tsDefines the map's valid location, viewport, selection, and result rules
web/…/BasemapLayer.tsxShows theme-aware vector basemap selection and fallback behavior
web/…/map-utils.tsxShows the raster fallback and attribution boundary
web/…/positron.tsShows the vector layer setup, worker loading, attribution, and cleanup guard
web/…/routes.tsShows how map navigation and collection search actions are classified