Make DashGlobe snappier for large datasets

.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: Deploy docs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - master
+      - main
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yml"
+      - "README.md"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload docs artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/publish-package.yml

@@ -75,7 +75,12 @@ jobs:
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git add dash_globe/package.json dash_globe/dash_globe/package-info.json dash_globe/Project.toml
+          git add \
+            dash_globe/package.json \
+            dash_globe/package-lock.json \
+            dash_globe/dash_globe/package-info.json \
+            dash_globe/Project.toml \
+            dash_globe/DESCRIPTION
           git diff --cached --quiet || git commit -m "chore: release ${{ steps.version.outputs.tag }} [skip release]"
 
       - name: Tag release

CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [1.0.0] - 2026-09-02
+
+First major release of `dash-globe`.
+
+### Added
+
+- Client-side `data_url(...)` layer sources so large GeoJSON/JSON datasets stay out of the Dash layout and are fetched in the browser.
+- `enable_large_data_mode()` helper plus `largeDataMode` / `eventDataMode` props for snappier large-dataset rendering and compact click/hover payloads.
+- Webpack splits the physical globe bundle into cached `async-three`, `async-h3`, and `async-globe-vendor` chunks so `async-DashGlobe.js` stays small.
+- Gallery example: "Large Dataset via data_url".
+- Mantine-styled interactive docs gallery in `usage.py` (AppShell sidebar, Demo/Code tabs, CodeHighlight).
+- GitHub Pages documentation site under `docs/` with getting-started guide and example screenshots/GIFs.
+- `script/capture_docs_media.py` to regenerate docs media from the local gallery.
+- Release tooling now keeps `DESCRIPTION` and `package-lock.json` in sync with the package version.
+
+### Changed
+
+- Default interaction payloads now use summary mode (geometry omitted) to avoid shipping full polygon/path objects back to Python on every hover.
+- Distributed Python package no longer ships multi-megabyte `.js.map` files.
+- CSS color constants (for example `rgba(...)`) and dotted label paths are wrapped into real accessors so upstream `accessor-fn` renders them correctly.
+- `data_url` layers wait until fetch completes before mounting the globe, avoiding an empty polygons layer after async load.
+- Root and package READMEs updated for the 1.0 docs/media experience.
+
+### Fixed
+
+- Large-dataset polygons using constant CSS colors no longer fail to paint.
+- Client fetch retry after aborted `data_url` requests (Strict Mode / remount-safe).
+
 ## [0.0.1] - 2026-04-18
 
 Initial public release of `dash_globe`.

README.md

@@ -1,81 +1,154 @@
 # Dash Globe
 
-Dash Globe is a Pythonic Dash wrapper for [`react-globe.gl`](https://github.com/vasturiano/react-globe.gl), aimed at giving Dash developers a figure-like API for building interactive 3D globes.
+[![PyPI](https://img.shields.io/pypi/v/dash-globe.svg)](https://pypi.org/project/dash-globe/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-0A7EA4)](https://jeffgallini.github.io/dash-globe/)
 
-The current implementation includes:
+**Interactive 3D globes for Dash** — a figure-like Python wrapper around [`react-globe.gl`](https://github.com/vasturiano/react-globe.gl).
 
-- A real `react-globe.gl` integration instead of the Dash boilerplate placeholder component.
-- A chainable Python API with helpers such as `update_layout`, `update_globe`, `update_controls`, `update_view`, `update_clouds`, `add_points`, `add_arcs`, `add_polygons`, `add_labels`, `add_hex_bins`, and `add_rings`.
-- Raw layer props can be configured with either Dash-style camelCase names or Python-friendly snake_case aliases.
-- Dash-friendly event props like `clickData`, `rightClickData`, `hoverData`, and `currentView`.
-- A richer [`usage.py`](dash_globe/usage.py) gallery showing multiple globe configurations, including upstream airline-routes and choropleth-countries examples.
+![Dash Globe large dataset example](docs/assets/examples/hero.png)
 
-## Quick Start
-
-From the generated package folder:
-
-```bash
-cd dash_globe
-python usage.py
-```
+## Highlights
 
-Then open `http://127.0.0.1:8050`.
+- Chainable helpers: `update_layout`, `update_globe`, `update_view`, `add_points`, `add_arcs`, `add_polygons`, and more
+- Full layer coverage: points, arcs, polygons, paths, heatmaps, hex bins, tiles, particles, rings, labels
+- Dash-native events: `clickData`, `hoverData`, `rightClickData`, `currentView`, `globeReady`
+- Scene effects: day/night cycle, rotating clouds, serializable materials and ring fades
+- Large data: `data_url(...)` + `enable_large_data_mode()` keep GeoJSON out of the Dash layout
+- Docs gallery: Mantine-styled [`usage.py`](dash_globe/usage.py) plus [GitHub Pages docs](https://jeffgallini.github.io/dash-globe/)
 
-To opt back into Dash debug mode for local development:
+## Install
 
 ```bash
-DASH_GLOBE_DEBUG=1 python usage.py
+pip install dash-globe
 ```
 
-In PowerShell:
-
-```powershell
-$env:DASH_GLOBE_DEBUG="1"
-python usage.py
-```
-
-## Python API Example
+## Quick Start
 
 ```python
+from dash import Dash, html
 import dash_globe
 
+app = Dash(__name__)
+
 globe = (
-    dash_globe.DashGlobe(id="routes")
-    .update_layout(height=500, background_color="#03111f")
-    .update_globe(show_atmosphere=True, atmosphere_color="#8ecae6")
+    dash_globe.DashGlobe(id="globe")
+    .update_layout(height=520, background_color="#020817")
+    .update_globe(globe_image_url=dash_globe.PRESETS.EARTH_NIGHT, show_atmosphere=True)
     .update_controls(auto_rotate=True, auto_rotate_speed=0.35)
-    .update_view(lat=25, lng=20, altitude=1.9)
-    .update_clouds(image_url=dash_globe.PRESETS.CLOUDS)
     .add_points([
         {"name": "New York", "lat": 40.7128, "lng": -74.0060, "color": "#ff6b6b"},
         {"name": "London", "lat": 51.5072, "lng": -0.1276, "color": "#ffd166"},
+        {"name": "Tokyo", "lat": 35.6762, "lng": 139.6503, "color": "#4cc9f0"},
     ])
     .update_points(
-        pointLat="lat",
-        pointLng="lng",
-        pointColor="color",
-        pointLabel="name",
-        pointAltitude=0.08,
-        pointRadius=0.28,
+        point_lat="lat",
+        point_lng="lng",
+        point_color="color",
+        point_label="name",
+        point_altitude=0.08,
+        point_radius=0.28,
     )
 )
+
+app.layout = html.Div(globe)
+
+if __name__ == "__main__":
+    app.run(debug=True)
 ```
 
-## Development
+## Large Datasets
+
+Fetch GeoJSON in the browser so the Dash layout stays small:
+
+```python
+globe = (
+    dash_globe.DashGlobe(id="countries")
+    .enable_large_data_mode()
+    .update_polygons(
+        data=dash_globe.data_url(
+            "https://raw.githubusercontent.com/vasturiano/react-globe.gl/master/example/datasets/ne_110m_admin_0_countries.geojson"
+        ),
+        polygon_geo_json_geometry="geometry",
+        polygon_cap_color="rgba(56, 189, 248, 0.55)",
+        polygon_altitude=0.06,
+        polygon_label="properties.ADMIN",
+    )
+)
+```
+
+## Examples
+
+| Example | Preview |
+| --- | --- |
+| Large dataset via `data_url` | ![Large dataset](docs/assets/examples/large-dataset.png) |
+| Choropleth countries | ![Choropleth](docs/assets/examples/choropleth.png) |
+| Day / night cycle | ![Day night](docs/assets/examples/day-night-cycle.png) |
+| Airline routes | ![Airline routes](docs/assets/examples/airline-routes.png) |
+
+More screenshots and short loops: [Examples on GitHub Pages](https://jeffgallini.github.io/dash-globe/examples.html).
+
+### Run the interactive gallery locally
 
-Inside [`dash_globe`](dash_globe):
+```bash
+cd dash_globe
+python usage.py
+```
+
+Open `http://127.0.0.1:8050`.
+
+Opt into Dash debug mode:
+
+```bash
+# bash
+DASH_GLOBE_DEBUG=1 python usage.py
+```
+
+```powershell
+# PowerShell
+$env:DASH_GLOBE_DEBUG="1"
+python usage.py
+```
+
+## Documentation
+
+- **Hosted docs:** https://jeffgallini.github.io/dash-globe/
+- **Getting started:** https://jeffgallini.github.io/dash-globe/getting-started.html
+- **Live gallery source:** [`dash_globe/usage.py`](dash_globe/usage.py)
+- **Changelog:** [`CHANGELOG.md`](CHANGELOG.md)
+
+## Development
 
 ```bash
+cd dash_globe
 npm install
 npm run build:js
-venv\Scripts\dash-generate-components.exe .\src\lib\components dash_globe -p package-info.json -i \.test\.
+npm run build:backends
 python usage.py
 ```
 
-`usage.py` now runs with Dash debug mode off by default to avoid upstream Dash/React dev-bundle warnings in the browser console. Set `DASH_GLOBE_DEBUG=1` when you want Dash debug tooling back.
+Regenerate docs screenshots/GIFs from a running gallery:
+
+```bash
+python script/capture_docs_media.py
+```
+
+Release versioning:
+
+```bash
+python script/release_version.py current
+python script/release_version.py set 1.0.0
+```
+
+Pushing to `master` with a commit message containing `v1.0.0` (or relying on the publish workflow) tags and publishes the package.
 
 ## Notes
 
-- The wrapper currently focuses on JSON-serialisable `react-globe.gl` features, which maps well to Dash callbacks.
-- Features that require raw JavaScript functions, DOM nodes, or arbitrary ThreeJS objects are not yet exposed through high-level Python helpers, although common scene-level effects like day/night shaders and the rotating clouds shell now have first-class APIs.
-- Any remaining `defaultProps` warnings seen only while `DASH_GLOBE_DEBUG=1` is enabled come from upstream Dash core component dev bundles, not from `dash-globe` rendering logic.
+- The wrapper focuses on JSON-serialisable `react-globe.gl` features that map cleanly to Dash callbacks.
+- Prefer `data_url(...)` plus `enable_large_data_mode()` for country-scale GeoJSON.
+- Three.js / H3 load as separately cached async chunks so the DashGlobe bundle stays small.
+- CSS color constants like `rgba(...)` are wrapped into real accessors so they render correctly with upstream `accessor-fn`.
+
+## License
+
+MIT

dash_globe/DESCRIPTION

@@ -1,6 +1,6 @@
 Package: dashGlobe
 Title: React Globe.gl in Dash
-Version: 0.0.1
+Version: 1.0.0
 Description: React Globe.gl in Dash
 Depends: R (>= 3.0.2)
 Imports: 

dash_globe/MANIFEST.in

@@ -1,9 +1,9 @@
 include dash_globe/dash_globe.min.js
-include dash_globe/dash_globe.min.js.map
 include dash_globe/async-*.js
-include dash_globe/async-*.js.map
 include dash_globe/metadata.json
 include dash_globe/package-info.json
 include README.md
 include LICENSE
 include package.json
+# Source maps are generated for local debugging but intentionally omitted from
+# the distributed package to keep installs small and snappy.

dash_globe/NAMESPACE

@@ -1,3 +1,5 @@
 # AUTO GENERATED FILE - DO NOT EDIT
 
-export(''DashGlobe)
+export(DashGlobe)
+export(DashGlobe)
+export(dashGlobe)

dash_globe/Project.toml

@@ -2,7 +2,7 @@
 name = "DashGlobe"
 uuid = "1b08a953-4be3-4667-9a23-6c0995ef58b1"
 authors = ["Jeff Gallini <gallinij@gmail.com>"]
-version = "0.0.10"
+version = "1.0.0"
 [deps]
 Dash = "1b08a953-4be3-4667-9a23-3db579824955"