@mapette/core
v0.1.7
Published
Framework-agnostic map UI on MapLibre for place-and-photo sites: Apple Maps–like basemap, cluster bubbles, photo pins, popovers, a side panel / bottom sheet, theme and locale helpers.
Maintainers
Readme
@mapette/core
Framework-agnostic map UI on MapLibre GL for sites built around places and photos. Everything that touches the DOM or MapLibre lives here; @mapette/vue is a thin binding.
npm i @mapette/core maplibre-glimport { createMap } from "@mapette/core";
import "@mapette/core/mapette.css";
const ctrl = await createMap({ container: el, preset: "compact", center: [135.77, 34.97], zoom: 13 });What's inside
createMap(options)– creates the map and returns a controller. MapLibre is loaded lazily, so this is safe in server-rendered apps.preset:static(display only),compact(pan and zoom, no rotation; for cards),explore(full screen, globe, view in the URL hash).interactiveoverrides the preset per feature, e.g.{ pan: false }.style: a style URL, a style object, or a function of{ palette, dark, locale }. Defaults to the mapette basemap.- Follows the page's color scheme (
data-theme,.dark, or the system), keeps givenkeepSourcesacross restyles, and avoids panels viapadding. controller.reveal(lngLat)pans a location into view without changing the zoom.
- Basemap and overlays –
createBasemap,clusterSource/clusterLayers,pointLayer,focusPointLayer,heatmapLayer,coneLayerswithviewCone/fieldOfViewfor camera directions. - Controls –
ScaleBar,MapButtons(compass, locate, zoom),ClusterExpander. - Markers and popovers –
LocationMarker,PhotoPins(photos on the map at street zoom),MapPopover(positioned with Floating UI inside the visible map; card or menu style; card style is off unlesspopovers: true). Menus stop at 360px tall and scroll inside; set--mapette-popover-menu-max-heightto change that. - Layout –
Sheet: side panel on desktop, bottom sheet on phones that moves as one piece: below full height any vertical drag moves the whole sheet, at full height the content scrolls and pulling down from the top lowers the sheet. It reports the area it covers, and the map keeps its view still when that area changes. - Theme – CSS variables (
--mapette-*, each split into-light/-darkhalves),applyTheme(el, theme), built-inthemes, each with a day and a night half (neutral, the default;cool, with bluer land, buildings and roads;warm, paper-like;mono, grayscale), theme preference helpers andthemeInitScriptfor a flash-free first paint. - Locale and SEO – path-prefix locales (
/,/zh-hant,/ja,/en), built-in UI texts in four languages (kitText),seoHeadfor localized<head>data. - Keyboard –
onShortcutsthat ignores typing in inputs and IME composition. - PWA updates –
registerServiceWorkerregisters the service worker and reports a new version waiting to take over;apply()switches to it and reloads. The service worker must wait for a{ type: "SKIP_WAITING" }message instead of callingskipWaitingon install, and its content must change with each deploy.
License
MIT. The default basemap uses OpenFreeMap tiles (© OpenStreetMap contributors) and AWS Terrain Tiles; keep the attribution visible.
