canvas-globe 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -6,6 +6,14 @@ All notable changes to this package are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.1.3] - 2026-09-14
+
+- Added JSR package configuration and tokenless GitHub publishing workflow.
+- Added a Custom Elements Manifest for `<geo-globe>` so catalogs, IDEs, and
+  documentation tools can discover its attributes, properties, methods, and events.
+- Added installation guidance for npm, pnpm, Yarn, Bun, Deno, jsDelivr, UNPKG,
+  and browser ESM CDNs.
+
 ## [0.1.2] - 2026-09-14
 
 - Added npm, CI, license, TypeScript, and zero-dependency badges to the README.

package/README.md

@@ -1,6 +1,7 @@
 # CanvasGlobe
 
 [![npm version](https://img.shields.io/npm/v/canvas-globe.svg)](https://www.npmjs.com/package/canvas-globe)
+[![JSR](https://jsr.io/badges/@swiftools/canvas-globe)](https://jsr.io/@swiftools/canvas-globe)
 [![npm downloads](https://img.shields.io/npm/dm/canvas-globe.svg)](https://www.npmjs.com/package/canvas-globe)
 [![CI](https://github.com/Shree-hari/canvas-globe/actions/workflows/ci.yml/badge.svg)](https://github.com/Shree-hari/canvas-globe/actions/workflows/ci.yml)
 [![GPL-3.0-only](https://img.shields.io/npm/l/canvas-globe.svg)](LICENSE)
@@ -16,6 +17,9 @@
 [Showcase](https://canvasglobe.swiftools.com/showcase) ·
 [Commercial pricing](https://canvasglobe.swiftools.com/pricing)
 
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz_small.svg)](https://stackblitz.com/github/Shree-hari/canvas-globe?startScript=start)
+[![Open in CodeSandbox](https://img.shields.io/badge/Open_in-CodeSandbox-151515?logo=codesandbox)](https://codesandbox.io/p/github/Shree-hari/canvas-globe)
+
 `canvas-globe` is a zero-dependency JavaScript library for an interactive
 **3D globe** and **flat world map** on Canvas 2D. It works with
 vanilla JavaScript, React, or a Web Component and requires no WebGL, map API
@@ -80,14 +84,73 @@ console warning in browser builds.
 
 ## Install
 
+Choose the package manager already used by your project:
+
 ```bash
+# npm
 npm install canvas-globe
+
+# pnpm
+pnpm add canvas-globe
+
+# Yarn
+yarn add canvas-globe
+
+# Bun
+bun add canvas-globe
+
+# Deno and JSR-aware projects
+deno add jsr:@swiftools/canvas-globe
+npx jsr add @swiftools/canvas-globe
+```
+
+You can also import the JSR release directly in Deno:
+
+```js
+import { createGlobe } from "jsr:@swiftools/canvas-globe@0.1.3";
+```
+
+The React entry point remains on npm so React's peer dependency is resolved by
+your existing application rather than installing a second React copy.
+
+### Browser CDN
+
+For a plain `<script>` installation, use the versioned UMD build:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/canvas-globe@0.1.3/dist/canvas-globe.umd.js"></script>
+```
+
+The same npm release is also available from UNPKG:
+
+```html
+<script src="https://unpkg.com/canvas-globe@0.1.3/dist/canvas-globe.umd.js"></script>
+```
+
+Modern browsers can import the package through an ESM CDN:
+
+```js
+import { createGlobe } from "https://esm.sh/canvas-globe@0.1.3";
+```
+
+Pin an exact version in production so a future release cannot change a deployed page unexpectedly.
+
+### Quick start
+
+```bash
+npm install canvas-globe
+```
+
+Then import the library:
+
+```js
+import { createGlobe } from "canvas-globe";
 ```
 
-Or drop it on a page with no build step at all:
+Or drop the UMD build on a page with no build step at all:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/canvas-globe/dist/canvas-globe.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/canvas-globe@0.1.3/dist/canvas-globe.umd.js"></script>
 <canvas id="globe" style="width:520px;aspect-ratio:1"></canvas>
 <script>
   CanvasGlobe.createGlobe(document.getElementById("globe"), {

package/codemeta.json

@@ -5,7 +5,7 @@
   "identifier": "canvas-globe",
   "description": "Zero-dependency JavaScript and React library for interactive 3D globes and flat world maps rendered with Canvas 2D, with no WebGL or API-key requirement.",
   "url": "https://canvasglobe.swiftools.com/",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "codeRepository": "https://github.com/Shree-hari/canvas-globe",
   "issueTracker": "https://github.com/Shree-hari/canvas-globe/issues",
   "downloadUrl": "https://www.npmjs.com/package/canvas-globe",

package/custom-elements.json

@@ -0,0 +1,142 @@
+{
+  "schemaVersion": "2.1.0",
+  "readme": "README.md",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "src/element.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "name": "GeoGlobeElement",
+          "description": "Framework-independent interactive globe and flat world map rendered with Canvas 2D.",
+          "customElement": true,
+          "tagName": "geo-globe",
+          "superclass": {
+            "name": "HTMLElement",
+            "package": "global:"
+          },
+          "members": [
+            {
+              "kind": "field",
+              "name": "globe",
+              "description": "Underlying GeoGlobe instance after the element is connected.",
+              "type": { "text": "GeoGlobe | null" }
+            },
+            {
+              "kind": "field",
+              "name": "markers",
+              "description": "Marker data displayed on the globe.",
+              "type": { "text": "Marker[]" }
+            },
+            {
+              "kind": "field",
+              "name": "arcs",
+              "description": "Great-circle route data displayed on the globe.",
+              "type": { "text": "Arc[]" }
+            },
+            {
+              "kind": "field",
+              "name": "options",
+              "description": "Applies options that cannot be represented as HTML attributes. Accepts Partial<GeoGlobeOptions>."
+            },
+            {
+              "kind": "method",
+              "name": "flyTo",
+              "description": "Animates the view to a longitude and latitude.",
+              "parameters": [
+                { "name": "lon", "type": { "text": "number" } },
+                { "name": "lat", "type": { "text": "number" } },
+                { "name": "opts", "type": { "text": "FlyToOptions" }, "optional": true }
+              ],
+              "return": { "type": { "text": "this" } }
+            },
+            {
+              "kind": "method",
+              "name": "fitTo",
+              "description": "Fits the view to geographic bounds.",
+              "parameters": [
+                { "name": "bounds", "type": { "text": "[number, number, number, number]" } },
+                { "name": "opts", "type": { "text": "FlyToOptions & { padding?: number }" }, "optional": true }
+              ],
+              "return": { "type": { "text": "this" } }
+            },
+            {
+              "kind": "method",
+              "name": "snapshot",
+              "description": "Returns a data URL snapshot of the current canvas.",
+              "parameters": [
+                { "name": "type", "type": { "text": "string" }, "optional": true },
+                { "name": "quality", "type": { "text": "number" }, "optional": true }
+              ],
+              "return": { "type": { "text": "string | undefined" } }
+            }
+          ],
+          "attributes": [
+            { "name": "mode", "description": "Rendering mode.", "type": { "text": "'globe' | 'map'" }, "default": "globe" },
+            { "name": "projection", "description": "Flat-map projection.", "type": { "text": "'equirectangular' | 'mercator' | 'naturalEarth'" }, "default": "equirectangular" },
+            { "name": "theme", "description": "Built-in theme name or serialized theme object.", "type": { "text": "string" }, "default": "atlas" },
+            { "name": "preset", "description": "Built-in visual preset.", "type": { "text": "string" } },
+            { "name": "land-style", "description": "Land rendering style.", "type": { "text": "'fill' | 'dots' | 'outline' | 'glow' | 'none'" }, "default": "fill" },
+            { "name": "marker-style", "description": "Marker rendering style.", "type": { "text": "string" } },
+            { "name": "aria-label", "description": "Accessible label for the canvas.", "type": { "text": "string" } },
+            { "name": "license-key", "description": "CanvasGlobe license key.", "type": { "text": "string" } },
+            { "name": "auto-rotate", "description": "Enables automatic rotation.", "type": { "text": "boolean" } },
+            { "name": "interactive", "description": "Enables pointer interaction.", "type": { "text": "boolean" }, "default": "true" },
+            { "name": "keyboard", "description": "Enables keyboard controls.", "type": { "text": "boolean" }, "default": "true" },
+            { "name": "graticule", "description": "Shows latitude and longitude grid lines.", "type": { "text": "boolean" } },
+            { "name": "stars", "description": "Shows the star background.", "type": { "text": "boolean" } },
+            { "name": "shade", "description": "Enables sphere shading.", "type": { "text": "boolean" } },
+            { "name": "terminator", "description": "Shows the day and night terminator.", "type": { "text": "boolean" } },
+            { "name": "cluster", "description": "Clusters nearby markers.", "type": { "text": "boolean" } },
+            { "name": "tooltip", "description": "Enables the built-in tooltip.", "type": { "text": "boolean" } },
+            { "name": "zoomable", "description": "Enables wheel and pinch zoom.", "type": { "text": "boolean" }, "default": "true" },
+            { "name": "zoom", "description": "Initial zoom level.", "type": { "text": "number" } },
+            { "name": "min-zoom", "description": "Minimum zoom level.", "type": { "text": "number" } },
+            { "name": "max-zoom", "description": "Maximum zoom level.", "type": { "text": "number" } },
+            { "name": "rotate-speed", "description": "Automatic rotation speed.", "type": { "text": "number" } },
+            { "name": "marker-scale", "description": "Global marker scale.", "type": { "text": "number" } },
+            { "name": "radius-ratio", "description": "Globe radius relative to its canvas.", "type": { "text": "number" } },
+            { "name": "fps", "description": "Maximum animation frame rate.", "type": { "text": "number" } },
+            { "name": "cluster-radius", "description": "Marker clustering radius in pixels.", "type": { "text": "number" } },
+            { "name": "arc-lift", "description": "Default arc lift above the sphere.", "type": { "text": "number" } },
+            { "name": "arc-speed", "description": "Default animated arc speed.", "type": { "text": "number" } },
+            { "name": "lat", "description": "Initial centre latitude.", "type": { "text": "number" } },
+            { "name": "lon", "description": "Initial centre longitude.", "type": { "text": "number" } },
+            { "name": "orbits", "description": "Number of decorative orbit rings.", "type": { "text": "number" } },
+            { "name": "dot-spacing", "description": "Dot land-style spacing in degrees.", "type": { "text": "number" } },
+            { "name": "dot-size", "description": "Dot land-style radius in pixels.", "type": { "text": "number" } },
+            { "name": "markers", "description": "Serialized marker array.", "type": { "text": "Marker[]" } },
+            { "name": "arcs", "description": "Serialized route array.", "type": { "text": "Arc[]" } },
+            { "name": "country-colors", "description": "Serialized country colour mapping.", "type": { "text": "Record<string, string>" } },
+            { "name": "lat-range", "description": "Serialized latitude range.", "type": { "text": "[number, number]" } }
+          ],
+          "events": [
+            { "name": "geo-hover", "description": "Fires when the hovered marker changes.", "type": { "text": "CustomEvent<{ marker: Marker | ClusterMarker | null; pos: { x: number; y: number } | null }>" } },
+            { "name": "geo-click", "description": "Fires when a marker is clicked.", "type": { "text": "CustomEvent<{ marker: Marker | ClusterMarker; pos: { x: number; y: number } }>" } },
+            { "name": "geo-country-hover", "description": "Fires when the hovered country changes.", "type": { "text": "CustomEvent<{ country: CountryShape | null; pos: { x: number; y: number } | null }>" } },
+            { "name": "geo-country-click", "description": "Fires when a country is clicked.", "type": { "text": "CustomEvent<{ country: CountryShape; pos: { x: number; y: number } }>" } },
+            { "name": "geo-render", "description": "Fires after CanvasGlobe renders a frame.", "type": { "text": "CustomEvent<{ globe: GeoGlobe }>" } }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "GeoGlobeElement",
+          "declaration": { "name": "GeoGlobeElement", "module": "src/element.js" }
+        },
+        {
+          "kind": "js",
+          "name": "defineGeoGlobe",
+          "declaration": { "name": "defineGeoGlobe", "module": "src/element.js" }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "geo-globe",
+          "declaration": { "name": "GeoGlobeElement", "module": "src/element.js" }
+        }
+      ]
+    }
+  ]
+}

package/dist/canvas-globe.umd.js

@@ -4250,7 +4250,7 @@ const createElementClass = () => class GeoGlobeElement extends HTMLElement {
       onClick: (marker, pos) => this._emit("geo-click", { marker, pos }),
       onCountryHover: (country, pos) => this._emit("geo-country-hover", { country, pos }),
       onCountryClick: (country, pos) => this._emit("geo-country-click", { country, pos }),
-      onRender: () => this._emit("geo-render", { globe: this.globe }),
+      onRender: (globe) => this._emit("geo-render", { globe }),
     });
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canvas-globe",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Zero-dependency JavaScript and React library for interactive 3D globes and flat world maps rendered with Canvas 2D. No WebGL or API key.",
   "license": "GPL-3.0-only",
   "author": {
@@ -42,6 +42,7 @@
   "main": "./src/index.js",
   "module": "./src/index.js",
   "types": "./types/index.d.ts",
+  "customElements": "./custom-elements.json",
   "unpkg": "./dist/canvas-globe.umd.js",
   "jsdelivr": "./dist/canvas-globe.umd.js",
   "exports": {
@@ -60,7 +61,11 @@
       "import": "./src/react.js",
       "default": "./src/react.js"
     },
-    "./data/world": "./src/data/world.js",
+    "./data/world": {
+      "types": "./types/data/world.d.ts",
+      "import": "./src/data/world.js",
+      "default": "./src/data/world.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -73,7 +78,8 @@
     "LICENSE",
     "LICENSING.md",
     "THIRD_PARTY_NOTICES.md",
-    "codemeta.json"
+    "codemeta.json",
+    "custom-elements.json"
   ],
   "sideEffects": [
     "./src/element.js"
@@ -82,6 +88,7 @@
     "access": "public"
   },
   "scripts": {
+    "start": "node scripts/serve.mjs",
     "build": "node scripts/build.mjs",
     "data": "node scripts/generate-data.mjs && node scripts/generate-timezones.mjs",
     "example": "node scripts/serve.mjs",

package/src/element.js

@@ -1,3 +1,5 @@
+/* @ts-self-types="../types/element.d.ts" */
+
 /**
  * `<geo-globe>` custom element. Wraps GeoGlobe so it can be dropped into any
  * framework or plain HTML without requiring the imperative API.
@@ -45,7 +47,7 @@ const createElementClass = () => class GeoGlobeElement extends HTMLElement {
       onClick: (marker, pos) => this._emit("geo-click", { marker, pos }),
       onCountryHover: (country, pos) => this._emit("geo-country-hover", { country, pos }),
       onCountryClick: (country, pos) => this._emit("geo-country-click", { country, pos }),
-      onRender: () => this._emit("geo-render", { globe: this.globe }),
+      onRender: (globe) => this._emit("geo-render", { globe }),
     });
   }
 

package/src/index.js

@@ -1,3 +1,5 @@
+/* @ts-self-types="../types/index.d.ts" */
+
 export {
   GeoGlobe,
   GeoGlobe as CanvasGlobe,

package/src/react.js

@@ -1,3 +1,5 @@
+/* @ts-self-types="../types/react.d.ts" */
+
 /**
  * React binding. `import { Globe } from "canvas-globe/react"`.
  * React is a peer dependency and is only required by this entry point.

package/types/data/world.d.ts

@@ -0,0 +1,5 @@
+import type { CountryShape } from "../index.js";
+
+export declare const world: CountryShape[];
+
+export default world;

package/types/jsr-element.d.ts

@@ -0,0 +1,29 @@
+import type { Arc, CountryShape, GeoGlobe, GeoGlobeOptions, Marker, ClusterMarker, FlyToOptions } from "./index.js";
+
+export interface GeoGlobeEventMap {
+  "geo-hover": CustomEvent<{ marker: Marker | ClusterMarker | null; pos: { x: number; y: number } | null }>;
+  "geo-click": CustomEvent<{ marker: Marker | ClusterMarker; pos: { x: number; y: number } }>;
+  "geo-country-hover": CustomEvent<{ country: CountryShape | null; pos: { x: number; y: number } | null }>;
+  "geo-country-click": CustomEvent<{ country: CountryShape; pos: { x: number; y: number } }>;
+  "geo-render": CustomEvent<{ globe: GeoGlobe }>;
+}
+
+declare class GeoGlobeElementInstance extends HTMLElement {
+  globe: GeoGlobe | null;
+  markers: Marker[];
+  arcs: Arc[];
+  set options(value: Partial<GeoGlobeOptions>);
+  flyTo(lon: number, lat: number, opts?: FlyToOptions): this;
+  fitTo(bounds: [number, number, number, number], opts?: FlyToOptions & { padding?: number }): this;
+  snapshot(type?: string, quality?: number): string | undefined;
+  addEventListener<K extends keyof GeoGlobeEventMap>(
+    type: K,
+    listener: (this: GeoGlobeElementInstance, ev: GeoGlobeEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions
+  ): void;
+  addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+}
+
+export type GeoGlobeElement = GeoGlobeElementInstance;
+export declare const GeoGlobeElement: (new () => GeoGlobeElementInstance) | null;
+export declare function defineGeoGlobe(tag?: string): (new () => GeoGlobeElementInstance) | null;