fix(kepler-jupyter): load config issue + empty geometry + json encoder

[lixun910]

This pull request enhances the flexibility and robustness of the kepler.gl Python bindings v0.4.0 rc3:

• fix: async loadData and loadConfig may avoid config when it is loaded before data
• feat: add app name and theme customization to KeplerGl widget and HTML export
• feat: enhance GeoDataFrame serialization with custom JSON encoder (for datetime)
• fix: handle serialization of empty and all-null geometries in GeoDataFrame

[Copilot]

Pull request overview

This PR improves the kepler.gl Python bindings’ robustness around initial data/config loading, adds theme + app name customization to the widget and HTML export, and hardens GeoDataFrame serialization (datetime + empty/all-null geometries).

Changes:

• Update the Jupyter widget frontend to better coordinate initial dataset/config application and add UI theme/app name props.
• Enhance Python serialization + HTML export to support datetime encoding and empty/all-null geometries.
• Add regression tests and notebooks demonstrating the new behaviors.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
bindings/python/tests/test_serializers.py	Adds regression tests for empty and all-null-geometry GeoDataFrame serialization.
bindings/python/tests/test_html_export.py	Adds tests for datetime GeoDataFrames, json_encoder behavior, and theme/app_name export behavior.
bindings/python/src/widget.ts	Refactors initial load path and config application logic; introduces dataset tracking.
bindings/python/src/types.ts	Extends widget model typing with theme and app_name.
bindings/python/src/components/App.tsx	Wires theme + app_name traitlets into the KeplerGl React component.
bindings/python/notebooks/hex_config.py	Updates example config basemap styleType value.
bindings/python/notebooks/datetime_map.html	Adds an exported HTML example output.
bindings/python/notebooks/Theme and App Name.ipynb	New notebook demonstrating theme/app name customization and export behavior.
bindings/python/notebooks/Load kepler.gl.ipynb	Updates notebook outputs/examples to reflect current behavior/export support.
bindings/python/notebooks/GeoJSON.ipynb	Updates notebook output to reflect HTML export support.
bindings/python/notebooks/GeoDataFrame.ipynb	Updates notebook output to reflect HTML export support.
bindings/python/notebooks/GeoDataFrame with Datetime.ipynb	New notebook demonstrating datetime-safe GeoDataFrame handling and export.
bindings/python/notebooks/Empty GeoDataFrame.ipynb	New notebook demonstrating empty and null-geometry GeoDataFrame handling.
bindings/python/notebooks/DataFrame.ipynb	Updates notebook execution metadata/outputs.
bindings/python/keplergl/widget.py	Adds theme/app_name traitlets and forwards json_encoder/theme/app_name through save_to_html.
bindings/python/keplergl/serializers.py	Handles empty/all-null GeoSeries when building GeoArrow geometry arrays.
bindings/python/keplergl/_html_export.py	Adds json_encoder support for GeoDataFrame-to-GeoJSON and adds theme/app_name to exported HTML.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[lixun910]

@karosc Can you help to verify these fixes and enhancement using version 0.4.0rc3 https://pypi.org/project/keplergl/0.4.0rc3/ ? Thank you!

[karosc]

@lixun910 ,can you try running this notebook in a fresh venv with the pypi wheel installed? The lines on the jupyter widget show up a nice thick cyan color in the jupyter widget (as the config specifies), but in the html file they show up a thin blue color (for me anyway). FYI, I am using python 3.12 and a Firefox browser.

GeoDataFrame links.ipynb

[lixun910]

@karosc Yes, it's a bug: the processGeojson processes the data and the geometry column becomes _geojson. So any layer config that references the original geometry column name (e.g., "geometry") needs to be updated to "_geojson".

Just publish 0.4.0rc4 with this fix. Can you help to test it again? Thanks!

[lixun910]

@karosc can you help to take a look? Thank you!

[karosc]

Apologies, got very busy at work this week. I can test tonight

[karosc]

@lixun910, my config works again and the app_name argument is a very nice feature.

I think this goes a long way for users like myself who create stand-alone reports and tools. Now I can easily title my analysis reports and have that show up in the UI. Great feature! Thanks again!

[lixun910]

Thanks for helping verifying the fix! @karosc I will try to push out a release for version v0.40 soon.

[igorDykhta]

Great!