feat: add explicit import_luxon_dependency() helper to enable Tabulator date/time features (#40)

Author: AlePiccin

README.md

@@ -194,4 +194,41 @@ use_theme('bootstrap4', shared=False)
 def my_page():
     # use the theme only for this page
     use_theme('bootstrap4')
-```
+```
+
+
+### Dates & Times (Luxon)
+
+Tabulator’s date/time features (e.g. `formatter: "datetime"`, `sorter: "date"` or `sorter: "datetime"`)
+require **Luxon**. `nicegui-tabulator` does not bundle Luxon; enable it explicitly:
+
+```python
+from nicegui import ui
+from nicegui_tabulator import tabulator, import_luxon
+
+# Inject Luxon before creating tables that use date/time formatting/sorting
+import_luxon(shared=True)  # (app-wide)
+
+tabledata = [
+    {"id": 1, "name": "Oli Bob", "dob": "1982-05-14"},
+    {"id": 2, "name": "Mary May", "dob": "1999-01-31"},
+]
+
+table_config = {
+    "layout": "fitColumns",
+    "data": tabledata,
+    "columns": [
+        {"title": "Name", "field": "name"},
+        {
+            "title": "Date Of Birth",
+            "field": "dob",
+            "formatter": "datetime",
+            "formatterParams": {"inputFormat": "iso", "outputFormat": "dd/MM/yyyy"},
+            "sorter": "date",
+            "sorterParams": {"format": "iso"},
+        },
+    ],
+}
+
+tabulator(table_config)
+ui.run()

nicegui_tabulator/__init__.py

@@ -2,5 +2,6 @@
 from .core.tabulator import Tabulator as tabulator
 from .core.types import CellSlotProps
 from .core.themes import use_theme
+from .core.dependencies import import_luxon
 
-__all__ = ["__version__", "tabulator", "CellSlotProps", "use_theme"]
+__all__ = ["__version__", "tabulator", "CellSlotProps", "use_theme", "import_luxon"]

nicegui_tabulator/core/dependencies.py

@@ -0,0 +1,31 @@
+from typing import Final, Optional
+from nicegui import ui
+
+LUXON_DEFAULT_SCRIPT_URL: Final[str] = "https://cdn.jsdelivr.net/npm/luxon@3/build/global/luxon.min.js"
+
+
+def import_luxon(shared: Optional[bool] = None, script_url: str = LUXON_DEFAULT_SCRIPT_URL):
+    """Inject Luxon into the page so Tabulator date/time features can work.
+
+       Tabulator's date/time formatters and sorters require Luxon to be available in the
+       browser environment. Call this function **before** creating tables that use any of:
+       - ``formatter: "datetime"``
+       - ``sorter: "date"`` or ``sorter: "datetime"``
+       - editors that depend on Luxon (if used in the future)
+
+       Args:
+           shared:  Whether to import the dependency for all clients or only the current client.
+            `None`(default): import the dependency for all clients if the current client is an auto-index client, otherwise use it only for the current client.
+            `True`: import for all clients.
+            `False`: import only for the current client.
+           script_url: The URL of Luxon's global build. Override this if you self-host
+               Luxon or want to pin to a different version.
+
+       Notes:
+           - Call it once during your page/app setup, before creating Tabulator grids that
+             require date/time formatting/sorting.
+       """
+    if shared is None:
+        shared = ui.context.client.is_auto_index_client
+
+    ui.add_head_html(f'<script src="{script_url}"></script>', shared=shared)