Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions .github/workflows/check.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
name: Checks
on:
push:
pull_request:
permissions:
contents: read
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 24
cache: npm
- run: npm ci
- run: npm test
- run: npm run check
- run: npm run lint
- run: npm run build
113 changes: 84 additions & 29 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,41 +1,96 @@
# Svelte MapLibre Stack

Overlay clipped basemaps over each other.

## Known Issues

- Zooming in/out is visually unstable.

- Pinch-zooming over an overlay can/does move the overlay itself on mobile.

- Text labels in overlays are clipped.

## Developing

Install dependencies with `npm install` and start a development server:

```sh
npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open
Place clipped vector basemaps on one interactive globe.

`Map` renders one MapLibre canvas. A worker clips, relocates, and merges overlay
vector tiles into namespaced source layers. The basemap keeps its native sources,
so overlay changes do not reload it. All layers share the camera and label collision
system. Labels can extend beyond region edges without CSS clipping.

## Usage

Existing `Map`, `MapState`, `MapLayer`, and layer configuration exports remain available.

```svelte
<script lang="ts">
import { Map, MapState } from "@aakside/svelte-maplibre-stack";

const mapState = new MapState([
{
bearing: 0,
center: { lng: -87.63, lat: 41.88 },
visible: true,
zoom: 12,
},
]);
</script>

<div style="height: 100vh;">
<Map {mapState} />
</div>
```

## Building

To build:
Add overlays with `mapState.addLayer({ baseMapPosition, overlayCenter, bearing,
geojson, visible, style })`. `geojson` is a Polygon or MultiPolygon in source
coordinates; `overlayCenter` is aligned with `baseMapPosition`. An omitted overlay
style inherits the base style. The demo includes light and dark Manhattan overlays
positioned beside Chicago.

One-finger or mouse dragging moves a region. A second pointer cancels region movement
and leaves pinch zoom/rotation to the camera. Visibility, opacity, bearing locks,
borders, `flyToLayer`, and configuration serialization remain available.

## Integration changes

- Every `MapLayer.map` refers to the same MapLibre instance. Attach global controls
and listeners once per map. Runtime image generators are bridged to namespaced
sprite images, including asynchronous generators.
- Layer and source-layer IDs are namespaced. Code querying original style IDs must
use the composed IDs from `layer.map.getStyle()`.
- `clipPath` remains available for existing controls that detect a region; it is
no longer applied to a canvas. Borders are MapLibre line layers.
- `MapState.update()` replaces the layer configuration, including removing surplus
overlays. Removing an overlay never removes the shared map.
- Use `onerror` on `Map` and/or render `mapState.error` in an alert. Tile, style,
glyph, and unsupported-source errors are surfaced rather than replaced by empty
tiles. The demo renders this alert.

## Supported data

Overlay styles must use vector sources with XYZ or TMS MVT tiles, directly or via
TileJSON. Raster, terrain, and other non-vector overlay sources are rejected.
Basemap sources retain their normal MapLibre behavior. Styles and resources must
be browser-accessible with the appropriate CORS headers. Inline styles should use
absolute resource URLs; URL-loaded styles resolve relative resource paths.

Placement uses a Mercator similarity transform, including latitude scale and
rotation. Scale is preserved locally at the anchor, not globally across large
continental regions. Anchors and region coordinates must be within Web Mercator's
latitude domain (approximately ±85.0511°).

Static font stacks and literal stacks in match/case/step/coalesce expressions are
supported. Font names supplied entirely by feature data require normalization in
the source style. Custom source protocols, authenticated request transforms, and
terrain relocation are not implemented.

The build requires a bundler supporting module workers via `new URL(...,
import.meta.url)`, such as Vite. The worker ships in the package.

## Development

```sh
npm pack
npm install
npm test
npm run check
npm run lint
npm run dev
```

To create a production version of the demo:

```sh
npm run build
```
Hot reload is enabled by default. `npm run build` builds the demo and validates the
package. `npm pack` creates the library package; `npm run preview` previews the demo.

Preview the production build with `npm run preview`.
See [the rendering design](docs/vector-tiles.md) for geometry and interaction rules.
`FourwaySplitMap` remains a separate experimental comparison component.

## License

Expand Down
56 changes: 56 additions & 0 deletions docs/vector-tiles.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# Single-globe vector composition

The public MapState / MapLayer configuration remains the integration boundary. All
layers share one MapLibre map, camera, symbol collision domain, and gesture surface.
The unclipped basemap retains its native sources so moving an overlay does not
reload the basemap. Overlay geometry is clipped in source coordinates, relocated, and encoded into
namespaced MVT source layers. Labels are clipped by their geometry/anchor, never by
CSS, so glyphs may extend past the region boundary.

Placement is a Mercator similarity transform: source anchor to destination anchor,
rotation relative to the base bearing, and a cosine latitude scale preserving local
ground size at the anchor. This is locally scale preserving, not an equal-area
projection for continent-sized regions. The renderer can still use globe projection.

Tile requests inverse-transform destination bounds, select the corresponding source
zoom, fetch overlapping upstream tiles, and merge the transformed features. Source
zoom bounds come from TileJSON or the MapLibre vector source specification. Requests
are abortable; errors must reach MapLibre's error event and MapState.error.

Style sources, layers, sprite names and glyph stacks need isolated namespaces.
Overlay backgrounds become polygon fills. Unsupported overlay source types must
fail explicitly. Style replacement must not reset camera or expose stale async work.

Dragging a region uses one pointer only. A second touch cancels region movement and
returns control to MapLibre's pinch handler. Changes to placement invalidate tiles;
camera zoom and pan do not change placement. Visibility, opacity, borders, layer
removal, serialization, and mixed style resources must remain usable.

The library has released versions. Existing exported configuration names remain;
MapLayer.map now refers to the shared map. FourwaySplitMap is a separate experimental
comparison component, not the implementation of Map.

## Loading and interaction performance

Source regions are projected once per configuration. Decoded, clipped source
features are reused across destination tiles and placement changes. Preparation
is retained for the current destination zoom and invalidated when source geometry
or URLs change. Independent contributions and upstream requests run concurrently;
shared in-flight fetches have independent consumer cancellation. Bounding boxes
reject unrelated features before polygon clipping, and rectangular interiors pass
through unchanged. Destination indexing starts at the root and only subdivides
along the requested tile path.

Worker configurations are sent once per revision; tile messages contain only a
revision and coordinates. A replacement style stages invisible overlay layers
alongside the displayed generation, then swaps them after all replacement sources
are loaded. Superseded generations are removed. Paint-only changes reuse existing
vector sources. Errors remain visible through MapState.error and the onerror hook.

Dragging captures the selected overlay into a temporary transparent bitmap on the
same map's render events. This avoids translating MapLibre paint across unchanged
tile stencil masks, which would cut gaps at tile boundaries. The bitmap moves once
per animation frame; source placement is committed on pointer release. There is
one live map and WebGL context; the temporary 2D canvases are disposed after the
replacement renders or the gesture is cancelled. The preview contains the visible
viewport at drag start; newly revealed offscreen content arrives with final tiles.
Loading
Loading