chore: wip

Author: chrisbbreuer

CLAUDE.md

@@ -2,7 +2,7 @@
 
 ## About
 
-A zero-dependency TypeScript library for creating interactive SVG-based vector maps with data visualization support (choropleth maps, heat maps, bubble charts). It provides multiple map projections (Mercator, Equal Earth), built-in world and country maps, interactive legends and tooltips, and official React, Vue, and Nuxt bindings. Inspired by jsvectormap.
+A zero-dependency, TypeScript-native interactive mapping library. Mapbox-class feature set (vector tiles + Mapbox GL Style Spec subset, expressions, 3D fill-extrusion + terrain + fog/sky, globe projection, collision-aware symbol labels, WebGL renderer) with a Leaflet-style ergonomic API. Ships geocoding / directions / matrix adapters, offline tile caching, and official React, Vue, Svelte, Solid, Nuxt, and React-Native bindings.
 
 ## Linting
 

README.md

@@ -6,52 +6,48 @@
 
 # ts-maps
 
-> Modern TypeScript library for creating stunning vector maps
+> A zero-dependency, TypeScript-native, interactive mapping library — Mapbox-class features with a Leaflet-style API.
 
 ## Features
 
-- 🗺️ **Interactive slippy maps** — `TsMap`, a modern TypeScript port of
-
-  Leaflet with fractional zoom, bearing (rotation), pitch (tilt), and
-  unified `flyTo` / `easeTo` / `jumpTo` camera animations.
+- 🗺️ **Interactive slippy maps** — `TsMap` gives you fractional zoom, bearing
+  (rotation), pitch (tilt), and unified `flyTo` / `easeTo` / `jumpTo` camera
+  animations.
 
 - 🧱 **Vector tiles + style spec** — in-house MVT (`.pbf`) decoder, full
-
   subset of the Mapbox GL Style Specification, and an expression engine
   that understands `interpolate` / `step` / `case` / `match` / `coalesce`
-  and friends. `setStyle`, `addSource`, `addStyleLayer`, `setPaintProperty`,
-  `setFilter` — the works.
+  and friends. `setStyle`, `addSource`, `addLayer`, `setPaintProperty`,
+  `setFilter`, `queryRenderedFeatures`, `querySourceFeatures` — the works.
 
 - 🏔️ **3D** — `fill-extrusion`, atmospheric `setFog`, a sky layer via
-
   `setSky`, and DEM-based terrain via `setTerrain` (auto-loads tiles from
   a `raster-dem` source). A `CustomLayerInterface` lets apps render raw
   WebGL2 alongside the built-in layers.
 
-- 🧭 **Services** — geocoding (Nominatim, Photon, Mapbox, Maptiler,
+- 🌍 **Globe** — seamless transition between Mercator and globe projection
+  around zoom 5.5, with an atmosphere halo.
 
-  Google), directions (OSRM, Valhalla, Mapbox, Google), isochrones, and
-  matrix adapters behind a common interface. Defaults are keyless.
+- 🧭 **Services** — geocoding (Nominatim, Photon, Mapbox, Maptiler,
+  Google), directions (OSRM, Valhalla, Mapbox, Google), isochrones,
+  and distance matrix adapters behind a common interface. Defaults are
+  keyless.
 
 - 📴 **Offline** — IndexedDB-backed `TileCache`, `saveOfflineRegion` for
-
   pre-fetching bboxes, and a worker pool for off-main-thread tile decode.
 
-- 🗺️ **Legacy `VectorMap`** — choropleth + bubble + heatmap API for the
-
-  classic "static country map with data overlay" use case.
+- 🧩 **Layer-scoped events** — `map.on('click', 'layer-id', handler)`,
+  Mapbox-style: handler only fires when a feature on the named style
+  layer is hit.
 
-- 🎯 **Zero runtime dependencies, 138 KB gzipped.** Subpath exports
-
-  (`ts-maps/services`, `ts-maps/style-spec`, …) let you import just the
-  slice you need.
+- 🎯 **Zero runtime dependencies.** Subpath exports (`ts-maps/services`,
+  `ts-maps/style-spec`, …) let you import just the slice you need.
 
 - 🧩 **Framework bindings** — `@ts-maps/react`, `@ts-maps/vue`,
-
+  `@ts-maps/svelte`, `@ts-maps/solid`, `@ts-maps/nuxt`,
   `@ts-maps/react-native` (WebView-hosted).
 
 - 🔒 **TypeScript-native** — full `isolatedDeclarations` compliance,
-
   strict types, and declaration files for every public module.
 
 ## Installation
@@ -70,23 +66,17 @@ yarn add ts-maps
 bun add ts-maps
 ```
 
-### Framework Bindings
+### Framework bindings
 
 ```bash
-# React
-npm install ts-maps ts-maps-react
-
-# Vue
-npm install ts-maps ts-maps-vue
-
-# Nuxt
-npm install ts-maps-nuxt
+npm install ts-maps ts-maps-react    # React
+npm install ts-maps ts-maps-vue      # Vue
+npm install ts-maps ts-maps-svelte   # Svelte
+npm install ts-maps ts-maps-solid    # SolidJS
+npm install ts-maps-nuxt             # Nuxt module
 ```
 
-## Quick Start — modern `TsMap`
-
-The modern API is an interactive slippy map with fractional zoom, bearing,
-pitch, and layer-based rendering.
+## Quick start
 
 ```typescript
 import 'ts-maps/styles.css'
@@ -126,6 +116,11 @@ vectorTileLayer({
       paint: { 'line-color': '#6b7280', 'line-width': ['interpolate', ['linear'], ['zoom'], 10, 0.5, 16, 3] } },
   ],
 }).addTo(map)
+
+// Layer-scoped events (Mapbox-style):
+map.on('click', 'primary-roads', (e) => {
+  console.log('road clicked', e.features[0].properties)
+})
 ```
 
 ### 3D — terrain, sky, fog, fill-extrusion
@@ -148,7 +143,7 @@ map.setFog({ color: 'rgb(245, 247, 250)', 'horizon-blend': 0.1 })
 const m = map.queryTerrainElevation({ lng: -74, lat: 40.7 })
 ```
 
-### Services — geocoding, directions
+### Services — geocoding, directions, matrix
 
 ```ts
 import { services } from 'ts-maps'
@@ -161,6 +156,12 @@ const routes = await directions.getDirections(
   [{ lat: 51.5055, lng: -0.0754 }, { lat: 51.5074, lng: -0.1278 }],
   { profile: 'driving' },
 )
+
+const matrix = services.defaultMatrix() // OSRM /table endpoint
+const m = await matrix.getMatrix(
+  [{ lat: 51.5055, lng: -0.0754 }, { lat: 51.5074, lng: -0.1278 }, { lat: 51.5155, lng: -0.1408 }],
+  { profile: 'driving' },
+)
 ```
 
 ### Offline tiles
@@ -178,10 +179,17 @@ await saveOfflineRegion({
 // Later: await cache.close() when the map is torn down.
 ```
 
+### Static image export
+
+```ts
+const dataUrl = await map.toDataURL()      // PNG data URL of the current view
+const blob = await map.toBlob('image/png') // or a Blob
+```
+
 ### Tree-shaking with subpath imports
 
-Only need the services layer? Import from the subpath — about 8 KB
-gzipped instead of pulling the full 138 KB bundle:
+Only need the services layer? Import from the subpath — a small slice
+instead of the full bundle:
 
 ```ts
 import { defaultGeocoder } from 'ts-maps/services'
@@ -191,164 +199,7 @@ import { LatLng, LatLngBounds } from 'ts-maps/geo'
 ```
 
 Available subpaths: `services`, `style-spec`, `storage`, `geo`,
-`geometry`, `symbols`, `analytics`, plus each built-in country map
-(`ts-maps/world`, `ts-maps/canada`, …).
-
-## Legacy `VectorMap` (static choropleth maps)
-
-```typescript
-import type { VectorMapOptions } from 'ts-maps'
-import { VectorMap } from 'ts-maps'
-
-// Create a map instance
-const map = new VectorMap({
-  container: 'map',
-  map: 'world',
-  theme: 'light',
-  style: {
-    regions: {
-      fill: '#e4e4e4',
-      stroke: '#ffffff',
-      strokeWidth: 1,
-    },
-    hover: {
-      fill: '#2ca25f',
-    },
-  },
-})
-
-// Add interactivity
-map.on('regionClick', (event, region) => {
-  console.log(`Clicked: ${region.id}`)
-})
-```
-
-### Data Visualization
-
-```typescript
-import type { DataVisualizationOptions } from 'ts-maps'
-import { VectorMap } from 'ts-maps'
-
-const map = new VectorMap({
-  container: 'map',
-  map: 'world',
-})
-
-// Add data visualization
-const options: DataVisualizationOptions = {
-  scale: ['#e5f5f9', '#2ca25f'], // Color gradient from light blue to green
-  values: {
-    US: 100,
-    CA: 80,
-    GB: 65,
-  },
-}
-
-map.visualizeData(options)
-```
-
-### React Component
-
-```tsx
-import type { VectorMapProps } from 'ts-maps-react'
-import { useVectorMap } from 'ts-maps-react'
-
-function WorldMap() {
-  const { map, isLoading } = useVectorMap({
-    map: 'world',
-    theme: 'light',
-  })
-
-  return (
-    <div className="map-container">
-      {isLoading
-        ? (
-            <div>Loading...</div>
-          )
-        : (
-            <div id="map" />
-          )}
-    </div>
-  )
-}
-```
-
-### Vue Component
-
-```vue
-<script setup lang="ts">
-import type { VectorMapOptions } from 'ts-maps'
-import { useVectorMap } from 'ts-maps-vue'
-
-const { map, isLoading } = useVectorMap({
-  map: 'world',
-  theme: 'light',
-})
-</script>
-
-<template>
-  <div class="map-container">
-    <div v-if="isLoading">
-      Loading...
-    </div>
-    <div v-else id="map" />
-  </div>
-</template>
-```
-
-### Nuxt Component
-
-For Nuxt applications, first add the module to your `nuxt.config.ts`:
-
-```ts
-export default defineNuxtConfig({
-  modules: [
-    'ts-maps-nuxt'
-  ]
-})
-```
-
-Then use the components directly in your Vue templates:
-
-```vue
-<script setup lang="ts">
-import type { MapOptions } from 'ts-maps'
-
-const mapOptions: Omit<MapOptions, 'selector'> = {
-  backgroundColor: '#f0f0f0',
-  zoomOnScroll: true,
-  style: {
-    regions: {
-      fill: '#e4e4e4',
-      stroke: '#ffffff',
-      strokeWidth: 1,
-    },
-  },
-}
-</script>
-
-<template>
-  <VectorMap
-    :options="mapOptions"
-    map-name="world"
-    height="500px"
-  />
-</template>
-```
-
-Available components include:
-
-- `VectorMap` - Generic map component
-- `WorldMap` - World map
-- `UnitedStates` - United States map
-- `Canada` - Canada map
-- `Brasil` - Brazil map
-- `Spain` - Spain map
-- `Italy` - Italy map
-- `Russia` - Russia map
-- `Iraq` - Iraq map
-
-See [Nuxt Components Documentation][nuxt-components-documentation] for detailed usage.
+`geometry`, `symbols`.
 
 ## Documentation
 
@@ -371,13 +222,13 @@ cd ts-maps
 2. Install dependencies:
 
 ```bash
-pnpm install
+bun install
 ```
 
 3. Start development:
 
 ```bash
-pnpm dev
+bun run dev
 ```
 
 ## Changelog
@@ -400,7 +251,7 @@ For casual chit-chat with others using this package:
 
 ## Postcardware
 
-“Software that is free, but hopes for a postcard.” We love receiving postcards from around the world showing where `ts-maps` is being used! We showcase them on our website too.
+"Software that is free, but hopes for a postcard." We love receiving postcards from around the world showing where `ts-maps` is being used! We showcase them on our website too.
 
 Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎
 
@@ -413,7 +264,10 @@ We would like to extend our thanks to the following sponsors for funding Stacks
 
 ## Credits
 
-- [jsvectormap][jsvectormap]
+- [Leaflet][leaflet] — the module layout and public API shape of the
+  interactive map API follow its design.
+- [Mapbox GL JS][mapbox-gl-js] — the style spec, expression engine, and
+  vector-tile renderer are modeled after its design.
 - [Chris Breuer][chris-breuer]
 - [All Contributors][all-contributors]
 
@@ -424,14 +278,11 @@ The MIT License (MIT). Please see [LICENSE][license] for more information.
 Made with 💙
 
 <!-- Badges -->
-[npm-version-src]: https://img.shields.io/npm/v/@stacksjs/clarity?style=flat-square
-[npm-version-href]: https://npmjs.com/package/@stacksjs/clarity
-[github-actions-src]: https://img.shields.io/github/actions/workflow/status/stacksjs/clarity/ci.yml?style=flat-square&branch=main
-[github-actions-href]: https://github.com/stacksjs/clarity/actions?query=workflow%3Aci
-
-<!-- [codecov-src]: https://img.shields.io/codecov/c/gh/stacksjs/clarity/main?style=flat-square -->
+[npm-version-src]: https://img.shields.io/npm/v/ts-maps?style=flat-square
+[npm-version-href]: https://npmjs.com/package/ts-maps
+[github-actions-src]: https://img.shields.io/github/actions/workflow/status/stacksjs/ts-maps/ci.yml?style=flat-square&branch=main
+[github-actions-href]: https://github.com/stacksjs/ts-maps/actions?query=workflow%3Aci
 [commitizen-friendly]: https://img.shields.io/badge/commitizen-friendly-brightgreen.svg
-[nuxt-components-documentation]: https://ts-maps.com/components/nuxt
 [introduction]: https://ts-maps.dev/intro
 [installation]: https://ts-maps.dev/install
 [usage-guide]: https://ts-maps.dev/usage
@@ -444,8 +295,9 @@ Made with 💙
 [join-the-stacks-discord-server]: https://discord.gg/stacksjs
 [jetbrains]: https://www.jetbrains.com/
 [the-solana-foundation]: https://solana.com/
-[jsvectormap]: https://github.com/themustafaomar/jsvectormap
+[leaflet]: https://leafletjs.com/
+[mapbox-gl-js]: https://github.com/mapbox/mapbox-gl-js
 [chris-breuer]: https://github.com/chrisbbreuer
 [all-contributors]: https://github.com/stacksjs/ts-maps/contributors
-[license]: https://github.com/stacksjs/clarity/blob/main/LICENSE.md
+[license]: https://github.com/stacksjs/ts-maps/blob/main/LICENSE.md
 [commitizen-href]: http://commitizen.github.io/cz-cli/