@npm9912/v-map 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +180 -96
- package/package.json +29 -5
package/README.md
CHANGED
|
@@ -1,121 +1,202 @@
|
|
|
1
|
-
# V-Map
|
|
1
|
+
# V-Map
|
|
2
2
|
|
|
3
|
-
**
|
|
4
|
-
Gebaut mit [Stencil.js](https://stenciljs.com/)
|
|
3
|
+
**Provider-agnostische Web-Mapping-Komponentenbibliothek für Webanwendungen.**
|
|
4
|
+
Gebaut mit [Stencil.js](https://stenciljs.com/) und [OpenLayers](https://openlayers.org/), [Cesium](https://cesium.com/), [Leaflet](https://leafletjs.com/) und [Deck.gl](https://deck.gl/) als austauschbare Render-Provider.
|
|
5
5
|
|
|
6
|
-
[](https://
|
|
7
|
-
[](https://www.npmjs.com/package/@npm9912/v-map)
|
|
7
|
+
[](https://github.com/pt9912/v-map/actions/workflows/test.yml)
|
|
8
|
+
[](https://github.com/pt9912/v-map/actions/workflows/build.yml)
|
|
9
|
+
[](https://pt9912.github.io/v-map/)
|
|
9
10
|
[](https://opensource.org/licenses/MIT)
|
|
10
11
|
|
|
11
12
|
---
|
|
12
13
|
|
|
13
|
-
##
|
|
14
|
+
## Features
|
|
14
15
|
|
|
15
|
-
- **
|
|
16
|
-
- **Layer-
|
|
17
|
-
- **
|
|
18
|
-
- **
|
|
19
|
-
- **
|
|
20
|
-
- **
|
|
21
|
-
- **
|
|
22
|
-
- **
|
|
23
|
-
- **Devcontainer-Support**: Voll ausgestattete Entwicklungsumgebung mit Docker
|
|
16
|
+
- **Provider-agnostisch:** OpenLayers, Leaflet, Cesium und Deck.gl hinter einem einheitlichen deklarativen Web-Component-API — ein Providerwechsel ist eine einzige Prop (`flavour`).
|
|
17
|
+
- **Reicher Layer-Katalog:** OSM, XYZ, WMS, WFS, WCS, GeoJSON, WKT, GeoTIFF, 3D-Tiles, Terrain, Deck.gl-Scatterplot, Google Tiles.
|
|
18
|
+
- **Layer-Gruppen & Layer-Control:** Basemap-/Overlay-Verwaltung mit Sichtbarkeitssteuerung (`v-map-layergroup`, `v-map-layercontrol`).
|
|
19
|
+
- **Styling:** `v-map-style` mit Unterstützung für [GeoStyler](https://geostyler.org/) JSON und SLD.
|
|
20
|
+
- **Deklaratives Building:** `v-map-builder` zum Konfigurieren komplexer Karten per Attribut.
|
|
21
|
+
- **Runtime-Error-API:** einheitliches `vmap-error` Event über alle Layer-Komponenten für konsistente Fehlerbehandlung.
|
|
22
|
+
- **Touch-optimiert:** Desktop und mobile Geräte.
|
|
23
|
+
- **Vollständige TypeScript-Typen** und JSX-Integration für Stencil/React/Vue/Svelte.
|
|
24
24
|
|
|
25
25
|
---
|
|
26
26
|
|
|
27
|
-
##
|
|
27
|
+
## Installation
|
|
28
28
|
|
|
29
29
|
```bash
|
|
30
|
-
|
|
31
|
-
# oder
|
|
32
|
-
|
|
30
|
+
pnpm add @npm9912/v-map
|
|
31
|
+
# oder
|
|
32
|
+
npm install @npm9912/v-map
|
|
33
33
|
```
|
|
34
34
|
|
|
35
|
+
Je nach gewünschtem Provider installierst du zusätzlich die passende Peer-Dependency:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
pnpm add ol # für flavour="ol"
|
|
39
|
+
pnpm add leaflet # für flavour="leaflet"
|
|
40
|
+
pnpm add cesium # für flavour="cesium"
|
|
41
|
+
pnpm add @deck.gl/core # für flavour="deck"
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## Verwendung
|
|
47
|
+
|
|
48
|
+
### Plain HTML / ESM
|
|
49
|
+
|
|
50
|
+
```html
|
|
51
|
+
<!DOCTYPE html>
|
|
52
|
+
<html>
|
|
53
|
+
<head>
|
|
54
|
+
<script type="module"
|
|
55
|
+
src="./node_modules/@npm9912/v-map/dist/v-map/v-map.esm.js"></script>
|
|
56
|
+
<style>v-map { display: block; width: 100%; height: 100vh; }</style>
|
|
57
|
+
</head>
|
|
58
|
+
<body>
|
|
59
|
+
<v-map flavour="ol">
|
|
60
|
+
<v-map-layergroup group-title="Basiskarten" basemapid="OSM-BASE">
|
|
61
|
+
<v-map-layer-osm id="OSM-BASE" label="OpenStreetMap"
|
|
62
|
+
z-index="0" opacity="1.0"></v-map-layer-osm>
|
|
63
|
+
</v-map-layergroup>
|
|
64
|
+
<v-map-layergroup group-title="Overlays">
|
|
65
|
+
<v-map-layer-geojson src="data/points.geojson"></v-map-layer-geojson>
|
|
66
|
+
</v-map-layergroup>
|
|
67
|
+
</v-map>
|
|
68
|
+
</body>
|
|
69
|
+
</html>
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### Framework-Integration (React, Vue, Svelte, SvelteKit …)
|
|
73
|
+
|
|
74
|
+
```ts
|
|
75
|
+
import { defineCustomElements } from '@npm9912/v-map/loader';
|
|
76
|
+
|
|
77
|
+
defineCustomElements();
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Danach stehen die Custom Elements (`<v-map>`, `<v-map-layer-osm>`, …) im gesamten Projekt zur Verfügung.
|
|
81
|
+
|
|
82
|
+
Eine vollständige SvelteKit-Integration findest du unter [`demo/sveltekit-demo/`](./demo/sveltekit-demo/).
|
|
83
|
+
|
|
84
|
+
### Unterstützte `flavour`-Werte
|
|
85
|
+
|
|
86
|
+
| Wert | Render-Provider |
|
|
87
|
+
|------------|----------------------------------|
|
|
88
|
+
| `ol` | OpenLayers (Default) |
|
|
89
|
+
| `leaflet` | Leaflet |
|
|
90
|
+
| `cesium` | CesiumJS (2D + 3D Globus) |
|
|
91
|
+
| `deck` | Deck.gl (GPU-beschleunigt) |
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## Komponenten-Übersicht
|
|
96
|
+
|
|
97
|
+
Insgesamt 18 Web Components in `src/components/`:
|
|
98
|
+
|
|
99
|
+
**Karten-Container & Infrastruktur**
|
|
100
|
+
- `v-map` — Haupt-Kartencontainer
|
|
101
|
+
- `v-map-builder` — deklaratives Building komplexer Karten
|
|
102
|
+
- `v-map-layergroup` — Gruppierung und Sichtbarkeitssteuerung
|
|
103
|
+
- `v-map-layercontrol` — interaktives Layer-Control
|
|
104
|
+
- `v-map-style` — Styling via GeoStyler JSON oder SLD
|
|
105
|
+
|
|
106
|
+
**Raster-Layer**
|
|
107
|
+
- `v-map-layer-osm` — OpenStreetMap-Tiles
|
|
108
|
+
- `v-map-layer-xyz` — generische XYZ-Tile-Sources
|
|
109
|
+
- `v-map-layer-google` — Google Maps Tiles
|
|
110
|
+
- `v-map-layer-wms` — OGC WMS
|
|
111
|
+
- `v-map-layer-wcs` — OGC WCS
|
|
112
|
+
- `v-map-layer-geotiff` — GeoTIFF
|
|
113
|
+
|
|
114
|
+
**Vektor-Layer**
|
|
115
|
+
- `v-map-layer-geojson` — GeoJSON
|
|
116
|
+
- `v-map-layer-wkt` — Well-Known-Text
|
|
117
|
+
- `v-map-layer-wfs` — OGC WFS
|
|
118
|
+
- `v-map-layer-scatterplot` — Deck.gl-Scatterplot
|
|
119
|
+
|
|
120
|
+
**3D & Terrain**
|
|
121
|
+
- `v-map-layer-tile3d` — 3D Tiles (Cesium)
|
|
122
|
+
- `v-map-layer-terrain` — Terrain-Provider
|
|
123
|
+
- `v-map-layer-terrain-geotiff` — Terrain aus GeoTIFF
|
|
124
|
+
|
|
125
|
+
Vollständige API-Referenz: [GitHub Pages Dokumentation](https://pt9912.github.io/v-map/).
|
|
126
|
+
|
|
35
127
|
---
|
|
36
128
|
|
|
37
|
-
##
|
|
129
|
+
## Error Handling
|
|
38
130
|
|
|
39
|
-
|
|
40
|
-
import { VMap } from '@pt9912/v-map';
|
|
131
|
+
Alle Layer-Komponenten emittieren ein einheitliches `vmap-error` Event bei Lade- und Laufzeitfehlern:
|
|
41
132
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
<v-map-layer-geojson src="data/points.geojson"></v-map-layer-geojson>
|
|
48
|
-
</v-map-layergroup>
|
|
49
|
-
</v-map>;
|
|
133
|
+
```ts
|
|
134
|
+
document.querySelector('v-map')?.addEventListener('vmap-error', (e) => {
|
|
135
|
+
const { detail } = e as CustomEvent;
|
|
136
|
+
console.error(detail.source, detail.phase, detail.message);
|
|
137
|
+
});
|
|
50
138
|
```
|
|
51
139
|
|
|
52
|
-
|
|
53
|
-
- Layer können kombiniert und gruppiert werden (`<v-map-layergroup>`).
|
|
140
|
+
Details: `docs/dev/CONCEPT-ERROR-API.md`.
|
|
54
141
|
|
|
55
142
|
---
|
|
56
143
|
|
|
57
|
-
##
|
|
144
|
+
## Entwicklung
|
|
58
145
|
|
|
59
146
|
### Voraussetzungen
|
|
60
147
|
|
|
61
148
|
- Node.js ≥ 22
|
|
62
149
|
- pnpm ≥ 9
|
|
63
|
-
- Docker (für Devcontainer
|
|
150
|
+
- optional: Docker (für den Devcontainer)
|
|
64
151
|
|
|
65
152
|
### Setup
|
|
66
153
|
|
|
67
154
|
```bash
|
|
68
155
|
pnpm install
|
|
156
|
+
pnpm start # Dev-Server auf http://localhost:3333
|
|
69
157
|
```
|
|
70
158
|
|
|
71
|
-
###
|
|
159
|
+
### Tests
|
|
160
|
+
|
|
161
|
+
Das Projekt nutzt [Vitest](https://vitest.dev/) mit den Projekten `spec`, `unit` und `browser`.
|
|
72
162
|
|
|
73
163
|
```bash
|
|
74
|
-
pnpm
|
|
164
|
+
pnpm test # spec + browser
|
|
165
|
+
pnpm test:coverage # alle Vitest-Projekte mit Coverage
|
|
166
|
+
pnpm test:vitest:browser # nur Browser-/Runtime-Tests
|
|
167
|
+
pnpm test:vitest:browser:watch # Browser-Tests im Watch-Modus
|
|
75
168
|
```
|
|
76
169
|
|
|
77
|
-
|
|
170
|
+
Hintergrund und CI-Hinweise: `docs/dev/vitest.md`.
|
|
78
171
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
## 🧪 Tests
|
|
82
|
-
|
|
83
|
-
Dieses Projekt nutzt **Vitest** für `spec`-, `unit`- und Browser-Tests.
|
|
172
|
+
### Storybook
|
|
84
173
|
|
|
85
174
|
```bash
|
|
86
|
-
pnpm
|
|
87
|
-
pnpm test:coverage # alle Vitest-Projekte mit Coverage
|
|
88
|
-
pnpm test:vitest:browser # Browser-/Runtime-Tests
|
|
89
|
-
pnpm test:vitest:browser:watch # Browser-Tests im Watch-Modus
|
|
175
|
+
pnpm storybook # http://localhost:6006
|
|
90
176
|
```
|
|
91
177
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
## 📖 Storybook
|
|
95
|
-
|
|
96
|
-
Interaktive Dokumentation der Komponenten:
|
|
178
|
+
### Dokumentation lokal bauen
|
|
97
179
|
|
|
98
180
|
```bash
|
|
99
|
-
pnpm
|
|
181
|
+
pnpm docs:dev # VitePress Dev-Server
|
|
182
|
+
pnpm docs:build # Statische Ausgabe in docs/.vitepress/dist
|
|
100
183
|
```
|
|
101
184
|
|
|
102
|
-
Erreichbar unter: [http://localhost:6006](http://localhost:6006)
|
|
103
|
-
|
|
104
185
|
---
|
|
105
186
|
|
|
106
|
-
##
|
|
187
|
+
## Devcontainer
|
|
107
188
|
|
|
108
|
-
Das Projekt enthält eine vorkonfigurierte
|
|
189
|
+
Das Projekt enthält eine vorkonfigurierte Devcontainer-Umgebung (`.devcontainer/`):
|
|
109
190
|
|
|
110
|
-
-
|
|
111
|
-
-
|
|
191
|
+
- Basis-Image `node:22`
|
|
192
|
+
- pnpm, GitHub CLI, ESLint, Prettier, Vitest vorinstalliert
|
|
112
193
|
- Automatisches Setup via `post-create.sh`
|
|
113
194
|
|
|
114
|
-
Öffne das Repo in [VS Code Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) oder [GitHub Codespaces].
|
|
195
|
+
Öffne das Repo in [VS Code Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) oder [GitHub Codespaces](https://github.com/features/codespaces).
|
|
115
196
|
|
|
116
197
|
---
|
|
117
198
|
|
|
118
|
-
##
|
|
199
|
+
## Build & Release
|
|
119
200
|
|
|
120
201
|
### Build
|
|
121
202
|
|
|
@@ -123,63 +204,66 @@ Das Projekt enthält eine vorkonfigurierte **Devcontainer-Umgebung**:
|
|
|
123
204
|
pnpm build
|
|
124
205
|
```
|
|
125
206
|
|
|
126
|
-
Erzeugt
|
|
207
|
+
Erzeugt die distributierbaren Bundles in `dist/` sowie den `loader/` für Framework-Integration.
|
|
127
208
|
|
|
128
209
|
### Release
|
|
129
210
|
|
|
130
|
-
Releases werden
|
|
211
|
+
Releases werden **vollautomatisch** durch [semantic-release](https://semantic-release.gitbook.io/) erstellt. Ausgelöst wird der Release-Workflow durch einen Merge von `develop` nach `main`.
|
|
131
212
|
|
|
132
|
-
-
|
|
133
|
-
-
|
|
134
|
-
|
|
135
|
-
```bash
|
|
136
|
-
pnpm release
|
|
137
|
-
```
|
|
213
|
+
- Versionierung und Changelog entstehen aus den [Conventional Commits](https://www.conventionalcommits.org/) seit dem letzten Tag.
|
|
214
|
+
- npm-Publish, GitHub-Release und Tag werden automatisch erzeugt.
|
|
215
|
+
- Vollständige Anleitung, Voraussetzungen und Fehlerbehebung: **[`docs/releasing.md`](./docs/releasing.md)**.
|
|
138
216
|
|
|
139
217
|
---
|
|
140
218
|
|
|
141
|
-
##
|
|
219
|
+
## Projektstruktur
|
|
142
220
|
|
|
143
221
|
```
|
|
144
222
|
v-map/
|
|
145
223
|
├── src/
|
|
146
|
-
│ ├── components/
|
|
147
|
-
│
|
|
148
|
-
│
|
|
149
|
-
│
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
│
|
|
154
|
-
├──
|
|
155
|
-
|
|
156
|
-
├──
|
|
157
|
-
├──
|
|
158
|
-
├──
|
|
159
|
-
|
|
224
|
+
│ ├── components/ # 18 Web Components (v-map, v-map-layer-*, …)
|
|
225
|
+
│ ├── map-provider/ # Provider-Implementierungen (ol, leaflet, cesium, deck)
|
|
226
|
+
│ ├── testing/ # Test-Setups und Mocks
|
|
227
|
+
│ └── index.ts # Entry Point
|
|
228
|
+
├── loader/ # Framework-Loader (defineCustomElements)
|
|
229
|
+
├── dist/ # Build-Artefakte (generiert)
|
|
230
|
+
├── docs/
|
|
231
|
+
│ ├── releasing.md # Release-Prozess
|
|
232
|
+
│ ├── dev/ # Interne Entwicklerdoku
|
|
233
|
+
│ └── .vitepress/ # VitePress-Konfiguration
|
|
234
|
+
├── demo/ # HTML- und SvelteKit-Integrationsdemos
|
|
235
|
+
├── .devcontainer/ # VS Code / Codespaces Setup
|
|
236
|
+
├── .github/workflows/ # CI/CD Pipelines (test, test-browser, build, release, docs)
|
|
237
|
+
├── .releaserc.json # semantic-release Konfiguration
|
|
238
|
+
├── stencil.config.ts # Stencil-Konfiguration
|
|
239
|
+
├── vite.config.ts # Vite-Konfiguration
|
|
240
|
+
└── vitest.config.mts # Vitest-Projekte
|
|
160
241
|
```
|
|
161
242
|
|
|
162
243
|
---
|
|
163
244
|
|
|
164
245
|
## Architektur
|
|
165
246
|
|
|
166
|
-
- Saubere Trennung von deklarativem DOM-API (
|
|
167
|
-
|
|
168
|
-
-
|
|
247
|
+
- **Saubere Trennung** von deklarativem DOM-API (Web Components) und imperativer Kartenlogik (Provider).
|
|
248
|
+
- **Engine-agnostisch:** Austausch bzw. Koexistenz von OpenLayers, Leaflet, Deck.gl und Cesium über ein klares Interface.
|
|
249
|
+
- **Typsicherheit** durch `LayerConfig`-Union mit exhaustiveness checks.
|
|
250
|
+
- **Shadow-DOM-kompatibel:** CSS-Injection, Adopted Stylesheets.
|
|
251
|
+
- **Erweiterbarkeit:** Neue Layer-Typen und Engines fügen sich je über einen Adapter ein.
|
|
252
|
+
- **Wiederverwendbarkeit:** `VMapLayerHelper` als einheitliche Registrierungs-/Update-Pipeline.
|
|
253
|
+
- **Konsistentes Error-API:** einheitliches `vmap-error` Event über alle Layer-Komponenten.
|
|
169
254
|
|
|
170
|
-
|
|
255
|
+
---
|
|
171
256
|
|
|
172
|
-
|
|
257
|
+
## Contributing
|
|
173
258
|
|
|
174
|
-
|
|
259
|
+
Pull Requests und Issues sind willkommen.
|
|
175
260
|
|
|
176
|
-
-
|
|
261
|
+
- Branch-Strategie: Feature-Branch → `develop` → `main` (siehe `docs/releasing.md`)
|
|
262
|
+
- Commit-Format: [Conventional Commits](https://www.conventionalcommits.org/)
|
|
263
|
+
- Alle Tests und Lints müssen grün sein (`pnpm test`, `pnpm lint`, `pnpm typecheck`)
|
|
177
264
|
|
|
178
265
|
---
|
|
179
266
|
|
|
180
|
-
##
|
|
267
|
+
## Lizenz
|
|
181
268
|
|
|
182
|
-
|
|
183
|
-
Bitte halte dich an [Conventional Commits](https://www.conventionalcommits.org/).
|
|
184
|
-
|
|
185
|
-
---
|
|
269
|
+
[MIT](./LICENSE)
|
package/package.json
CHANGED
|
@@ -1,7 +1,34 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@npm9912/v-map",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "Provider-agnostische Web-Mapping-Komponentenbibliothek auf Basis von Stencil.js — unterstützt OpenLayers, Cesium, Leaflet und Deck.gl über ein einheitliches deklaratives Web-Component-API.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"map",
|
|
7
|
+
"mapping",
|
|
8
|
+
"web-map",
|
|
9
|
+
"web-mapping",
|
|
10
|
+
"gis",
|
|
11
|
+
"geospatial",
|
|
12
|
+
"cartography",
|
|
13
|
+
"openlayers",
|
|
14
|
+
"leaflet",
|
|
15
|
+
"cesium",
|
|
16
|
+
"deck.gl",
|
|
17
|
+
"deckgl",
|
|
18
|
+
"web-components",
|
|
19
|
+
"custom-elements",
|
|
20
|
+
"stencil",
|
|
21
|
+
"stenciljs",
|
|
22
|
+
"typescript",
|
|
23
|
+
"geojson",
|
|
24
|
+
"wms",
|
|
25
|
+
"wfs",
|
|
26
|
+
"wcs",
|
|
27
|
+
"geotiff",
|
|
28
|
+
"3d-map",
|
|
29
|
+
"terrain",
|
|
30
|
+
"provider-agnostic"
|
|
31
|
+
],
|
|
5
32
|
"main": "dist/index.cjs.js",
|
|
6
33
|
"module": "dist/index.js",
|
|
7
34
|
"types": "dist/types/index.d.ts",
|
|
@@ -23,9 +50,6 @@
|
|
|
23
50
|
"require": "./loader/index.cjs"
|
|
24
51
|
}
|
|
25
52
|
},
|
|
26
|
-
"branches": [
|
|
27
|
-
"main"
|
|
28
|
-
],
|
|
29
53
|
"publishConfig": {
|
|
30
54
|
"access": "public"
|
|
31
55
|
},
|