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 state | User-facing purpose |
|---|---|
lat, lng, zoom | Restore the current map view after navigation or reload |
memo | Open one or more selected memos in the panel |
filter | Keep 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_locationmap 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, repeatedmemo, andfiltervalues 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
| Trigger | Consequence | Guard |
|---|---|---|
| A result page fails during the full map load | The map shows partial locations but must not claim that the collection is complete | Keep complete false and retry the failed page |
| A selected memo is not present after all pages load | The URL can point to a memo that is no longer in the active collection | Remove only unavailable selections after pagination completes |
| A map style stalls, WebGL fails, or the graphics context is lost | The preferred basemap cannot provide geographic context | Replace it with OpenStreetMap tiles |
| An individual vector tile or sprite request fails after the style loads | The vector map may have a partial background but remains usable | Do not treat post-load resource errors as fatal to the vector layer |
| OpenStreetMap tiles also fail | The map background may be incomplete or blank | Show a tile error and allow a tile redraw retry |
| A saved memo does not match the active map filters | The new memo is not visible in the current marker set | Show a link to the memo instead of creating a false map selection |
| A selection opens under the memo panel | The selected marker can be hidden by the side rail or bottom sheet | Pan by the smallest offset that keeps the point visible |
Key files
| File | Why to read it |
|---|---|
| web/…/index.tsx | Shows the authenticated global and Space-specific map routes |
| web/…/MapView.tsx | Shows the map page flow, URL state, panel behavior, and map controls |
| web/…/useMapMemos.ts | Shows which memos the map can retrieve and when loading is complete |
| web/…/MapCanvas.tsx | Shows marker selection, clustering, viewport behavior, and map interactions |
| web/…/model.ts | Defines the map's valid location, viewport, selection, and result rules |
| web/…/BasemapLayer.tsx | Shows theme-aware vector basemap selection and fallback behavior |
| web/…/map-utils.tsx | Shows the raster fallback and attribution boundary |
| web/…/positron.ts | Shows the vector layer setup, worker loading, attribution, and cleanup guard |
| web/…/routes.ts | Shows how map navigation and collection search actions are classified |