travels-map 1.0.0

package/LICENSE.md

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2017-2026 Robert Marsal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# Travels
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Reusable travel map web component for any website.
+
+![Preview](http://i.imgur.com/7kFVWux.png)
+
+See a live demo here: [https://robertmarsal.com/travels/](https://robertmarsal.com/travels/)
+
+## What it is
+
+This package exposes a custom element:
+
+```html
+<travels-map></travels-map>
+```
+
+It is framework-agnostic, so it can be used in plain HTML, React, Vue, Svelte,
+Astro, or any other frontend that can load a browser module.
+
+## Installation
+
+```sh
+npm install travels-map
+```
+
+## Local development
+
+```sh
+git clone https://github.com/robertmarsal/travels.git
+cd travels
+npm install
+npm run dev
+```
+
+## Demo
+
+The repository includes a local demo app for development and manual testing.
+
+Run it with:
+
+```sh
+npm run dev
+```
+
+Then edit [`src/demo/data.ts`](./src/demo/data.ts) to change the sample points
+shown in the demo.
+
+## Usage
+
+### Plain HTML with remote JSON
+
+```html
+<travels-map
+    data-src="/travels.json"
+    theme="dark-monochrome"
+    marker-color="#ff0066"
+    center="38.957083,-39.074225"
+    zoom="3"
+    show-legends="true"
+></travels-map>
+
+<script type="module" src="/dist/travels-map.js"></script>
+```
+
+Your JSON can be either:
+
+```json
+{
+  "points": [
+    { "lat": 51.500736, "lng": -0.124625, "title": "London - United Kingdom" }
+  ]
+}
+```
+
+or a raw array of point objects.
+
+### JavaScript property API
+
+```js
+import "travels-map";
+
+const map = document.querySelector("travels-map");
+map.markerColor = "#00d1b2";
+map.points = [
+    { lat: 51.500736, lng: -0.124625, title: "London - United Kingdom" },
+];
+```
+
+## Public API
+
+Attributes:
+
+- `data-src`: URL returning JSON data
+- `theme`: currently `dark-monochrome`
+- `marker-color`: optional CSS color for the dots
+- `center`: fallback map center as `"lat,lng"`
+- `zoom`: fallback zoom level when there are no points
+- `show-legends`: set to `"false"` to hide legends
+- `tiles-url`: optional custom tile URL template
+
+Properties:
+
+- `points`: array of `{ lat, lng, title }`
+- `markerColor`: optional color string for the dots
+
+Styling:
+
+- The component uses shadow DOM.
+- You can theme it with CSS custom properties on `travels-map`, such as
+  `--travels-marker`, `--travels-panel-bg`, and `--travels-map-bg`.

package/dist/travels-map/TravelsMapElement.d.ts

@@ -0,0 +1,34 @@
+import type { TravelPoint } from "./types";
+export declare class TravelsMapElement extends HTMLElement {
+    static get observedAttributes(): string[];
+    private map;
+    private tileLayer;
+    private tileUrl;
+    private markerLayer;
+    private legendControls;
+    private resizeObserver;
+    private pointsValue;
+    private dataRequestId;
+    private readonly mapElement;
+    private readonly locationsLegendElement;
+    private readonly countriesLegendElement;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    get points(): TravelPoint[];
+    set points(value: unknown);
+    get markerColor(): string | null;
+    set markerColor(value: string | null);
+    private loadConfiguredData;
+    private ensureMap;
+    private setupResizeObserver;
+    private getTheme;
+    private applyTheme;
+    private applyMarkerColor;
+    private getCenter;
+    private getZoom;
+    private getShowLegends;
+    private getTileUrl;
+    private render;
+}

package/dist/travels-map/index.d.ts

@@ -0,0 +1,3 @@
+import { TravelsMapElement } from "./TravelsMapElement";
+export { TravelsMapElement };
+export type { TravelsMapData, TravelPoint } from "./types";

package/dist/travels-map/legends.d.ts

@@ -0,0 +1,8 @@
+import { type Control, type Map } from "leaflet";
+import type { TravelPoint } from "./types";
+type LegendElements = {
+    countries: HTMLDivElement;
+    locations: HTMLDivElement;
+};
+export declare function updateLegends(map: Map, points: TravelPoint[], showLegends: boolean, legendElements: LegendElements, existingControls: Control[]): Control[];
+export {};

package/dist/travels-map/map.d.ts

@@ -0,0 +1,17 @@
+import { type LayerGroup, type Map, type TileLayer } from "leaflet";
+import type { TravelPoint } from "./types";
+export declare const DEFAULT_CENTER: [number, number];
+export declare const DEFAULT_ZOOM = 3;
+export declare const DEFAULT_TILE_URL = "https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}{r}.png";
+export declare const DEFAULT_TILE_OPTIONS: {
+    maxZoom: number;
+    subdomains: string;
+    attribution: string;
+};
+export declare function createMap(element: HTMLElement): {
+    map: Map;
+    markerLayer: LayerGroup;
+};
+export declare function updateTileLayer(map: Map, tileLayer: TileLayer | null, currentTileUrl: string | null, tileUrl: string): TileLayer;
+export declare function updateMarkers(markerLayer: LayerGroup, points: TravelPoint[]): void;
+export declare function updateViewport(map: Map, points: TravelPoint[], center: [number, number], zoom: number): void;

package/dist/travels-map/types.d.ts

@@ -0,0 +1,8 @@
+export type TravelPoint = {
+    lat: number;
+    lng: number;
+    title: string;
+};
+export type TravelsMapData = {
+    points: TravelPoint[];
+};

package/dist/travels-map/utils.d.ts

@@ -0,0 +1,6 @@
+import type { TravelPoint } from "./types";
+export declare function parseBooleanAttribute(value: string | null, defaultValue?: boolean): boolean;
+export declare function parseNumberAttribute(value: string | null, fallback: number): number;
+export declare function parseCenterAttribute(value: string | null): [number, number];
+export declare function normalizePoints(points: unknown): TravelPoint[];
+export declare function countCountries(points: TravelPoint[]): number;