grid-view-spec 2.0.0__py3-none-any.whl

grid_view_spec/__init__.py

@@ -0,0 +1,23 @@
+"""Framework-agnostic GridViewSpec vNext contract (grid-view-spec 2.x)."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from grid_view_spec.types import GridViewBlock, GridViewSpec, GridViewTable, GridViewToolbar
+from grid_view_spec.validate import normalize_spec, spec_from_wire, spec_to_wire, validate_spec
+
+try:
+    __version__ = version("grid-view-spec")
+except PackageNotFoundError:
+    __version__ = "2.0.0"
+
+__all__ = [
+    "GridViewBlock",
+    "GridViewSpec",
+    "GridViewTable",
+    "GridViewToolbar",
+    "__version__",
+    "normalize_spec",
+    "spec_from_wire",
+    "spec_to_wire",
+    "validate_spec",
+]

grid_view_spec/backends/django/__init__.py

@@ -0,0 +1,43 @@
+"""Django host backend adapters."""
+
+from typing import TYPE_CHECKING
+
+from grid_view_spec.backends.django.host import DjangoGridViewHost
+from grid_view_spec.backends.django.prefs import DjangoOrmPrefs
+
+if TYPE_CHECKING:
+    from grid_view_spec.backends.django.views import (
+        django_host,
+        export_pdf,
+        export_xlsx,
+        load_lazy_block,
+        render_lazy_block_response,
+        save_grid_prefs,
+    )
+
+__all__ = [
+    "DjangoGridViewHost",
+    "DjangoOrmPrefs",
+    "django_host",
+    "export_pdf",
+    "export_xlsx",
+    "load_lazy_block",
+    "render_lazy_block_response",
+    "save_grid_prefs",
+]
+
+
+def __getattr__(name: str) -> object:
+    if name in {
+        "django_host",
+        "export_pdf",
+        "export_xlsx",
+        "load_lazy_block",
+        "render_lazy_block_response",
+        "save_grid_prefs",
+    }:
+        from grid_view_spec.backends.django import views
+
+        return getattr(views, name)
+    msg = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(msg)

grid_view_spec/backends/django/ag_grid/__init__.py

@@ -0,0 +1,26 @@
+"""AG-Grid infinite row model — server-side query helpers."""
+
+from grid_view_spec.backends.django.ag_grid.export import (
+    EXPORT_COLS_PARAM,
+    parse_active_col_ids,
+    resolve_export_columns,
+)
+from grid_view_spec.backends.django.ag_grid.server import (
+    InfiniteGridParams,
+    apply_grid_filters,
+    apply_grid_sort,
+    parse_infinite_params,
+)
+from grid_view_spec.types.ag_grid import AgGridColumnSpec, AgGridPageSpec
+
+__all__ = [
+    "AgGridColumnSpec",
+    "AgGridPageSpec",
+    "EXPORT_COLS_PARAM",
+    "InfiniteGridParams",
+    "apply_grid_filters",
+    "apply_grid_sort",
+    "parse_active_col_ids",
+    "parse_infinite_params",
+    "resolve_export_columns",
+]

grid_view_spec/backends/django/ag_grid/export.py

@@ -0,0 +1,26 @@
+"""Resolve AG-Grid export columns from page spec + optional live grid snapshot."""
+
+from __future__ import annotations
+
+from django.http import HttpRequest
+from grid_view_spec.types.ag_grid import AgGridPageSpec
+
+EXPORT_COLS_PARAM = "export_cols"
+
+
+def parse_active_col_ids(
+    request: HttpRequest,
+    *,
+    param: str = EXPORT_COLS_PARAM,
+) -> tuple[str, ...]:
+    """Read comma-separated active column ids synced from the browser grid."""
+    raw = request.GET.get(param, "")
+    return tuple(col_id.strip() for col_id in raw.split(",") if col_id.strip())
+
+
+def resolve_export_columns(
+    spec: AgGridPageSpec,
+    request: HttpRequest,
+) -> list[str]:
+    """Resolve export column order from *spec* and optional ``export_cols`` query param."""
+    return spec.resolve_export_columns(parse_active_col_ids(request))

grid_view_spec/backends/django/ag_grid/server.py

@@ -0,0 +1,235 @@
+"""Parse AG-Grid infinite-model request params and apply filters/sort to querysets."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import TypeVar
+
+from django.db.models import F, Model, Q, QuerySet
+from django.http import HttpRequest
+from grid_view_spec.search.term_match import (
+    NUMERIC_OPS,
+    parse_range_bounds,
+    parse_search_number,
+)
+from grid_view_spec.types.json import as_str_object_dict, json_object_list_from
+from grid_view_spec.types.narrowing import is_object_list
+
+_QS = TypeVar("_QS", bound=QuerySet[Model])
+
+
+@dataclass(frozen=True)
+class InfiniteGridParams:
+    """Normalized query parameters from an AG-Grid infinite datasource fetch."""
+
+    start_row: int
+    end_row: int
+    search_query: str
+    visible_cols: tuple[str, ...]
+    filters: dict[str, object]
+    sort_model: list[dict[str, object]]
+    action: str | None = None
+    action_field: str | None = None
+
+
+def parse_infinite_params(
+    request: HttpRequest,
+    *,
+    default_page_size: int = 100,
+) -> InfiniteGridParams:
+    """Read standard infinite-grid GET params from *request*."""
+    start_row = int(request.GET.get("startRow", 0))
+    end_row = int(request.GET.get("endRow", default_page_size))
+    search_query = request.GET.get("q", "").strip()
+    visible_cols_str = request.GET.get("cols", "")
+    visible_cols = tuple(c.strip() for c in visible_cols_str.split(",") if c.strip())
+
+    filters: dict[str, object] = {}
+    filters_json = request.GET.get("filters")
+    if filters_json:
+        try:
+            filters = as_str_object_dict(json.loads(filters_json))
+        except (json.JSONDecodeError, TypeError):
+            pass
+
+    sort_model: list[dict[str, object]] = []
+    sort_json = request.GET.get("sort")
+    if sort_json:
+        try:
+            parsed_sort = json.loads(sort_json)
+            sort_model = [
+                {str(k): v for k, v in item.items()} for item in json_object_list_from(parsed_sort)
+            ]
+        except (json.JSONDecodeError, TypeError):
+            pass
+
+    action = request.GET.get("action") or None
+    action_field = request.GET.get("field") or None
+
+    return InfiniteGridParams(
+        start_row=start_row,
+        end_row=end_row,
+        search_query=search_query,
+        visible_cols=visible_cols,
+        filters=filters,
+        sort_model=sort_model,
+        action=action,
+        action_field=action_field,
+    )
+
+
+FilterValueFormatter = Callable[[str, object], object]
+
+
+def apply_grid_filters(
+    qs: _QS,
+    filters: Mapping[str, object],
+    field_map: Mapping[str, str],
+    *,
+    format_filter_value: FilterValueFormatter | None = None,
+) -> _QS:
+    """Apply AG-Grid ``filterModel`` entries to *qs* using *field_map* (colId → ORM path)."""
+    for col_id, rules in filters.items():
+        if col_id not in field_map:
+            continue
+        rule_map = as_str_object_dict(rules)
+        if not rule_map:
+            continue
+        db_field = field_map[col_id]
+
+        mode = rule_map.get("mode")
+        if mode == "empty":
+            qs = qs.filter(empty_field_q(db_field, numeric=bool(rule_map.get("numeric"))))
+            continue
+        if mode == "non_empty":
+            qs = qs.exclude(empty_field_q(db_field, numeric=bool(rule_map.get("numeric"))))
+            continue
+
+        values = rule_map.get("values")
+        if is_object_list(values):
+            target_vals: list[object] = []
+            for val in values:
+                if format_filter_value is not None:
+                    target_vals.append(format_filter_value(col_id, val))
+                else:
+                    target_vals.append(val)
+            qs = qs.filter(**{f"{db_field}__in": target_vals})
+            continue
+
+        if rule_map.get("filterType") == "cm-expr":
+            expr = str(rule_map.get("expr", "")).strip()
+            if expr:
+                expr_q = build_expr_q(db_field, expr, numeric=bool(rule_map.get("numeric")))
+                if expr_q is not None:
+                    qs = qs.filter(expr_q)
+            continue
+
+        if rule_map.get("filterType") == "text":
+            operator = str(rule_map.get("type", "contains"))
+            f_val = rule_map.get("filter", "")
+            if not f_val:
+                continue
+            lookup = _text_lookup(db_field, operator)
+            if lookup is None:
+                continue
+            if operator == "notContains":
+                qs = qs.exclude(**{lookup: f_val})
+            elif operator == "notEqual":
+                qs = qs.exclude(**{lookup: f_val})
+            else:
+                qs = qs.filter(**{lookup: f_val})
+    return qs
+
+
+def apply_grid_sort(
+    qs: _QS,
+    sort_model: Sequence[Mapping[str, object]],
+    field_map: Mapping[str, str],
+    *,
+    tie_breaker: str = "-id",
+) -> _QS:
+    """Apply the first AG-Grid sort model entry to *qs*."""
+    if not sort_model:
+        return qs
+    first = sort_model[0]
+    ui_col = str(first.get("colId", ""))
+    direction = str(first.get("sort", "asc"))
+    db_field = field_map.get(ui_col)
+    if not db_field:
+        return qs
+    f_obj = F(db_field)
+    if direction == "desc":
+        f_obj = f_obj.desc(nulls_last=True)
+    else:
+        f_obj = f_obj.asc(nulls_last=True)
+    return qs.order_by(f_obj, tie_breaker)
+
+
+def empty_field_q(db_field: str, *, numeric: bool = False) -> Q:
+    """Values treated as empty: null always; 0 for numeric columns, else blank/dash.
+
+    Comparing a numeric column against ``""``/``"-"`` raises a DB type error, so
+    numeric columns use ``isnull`` + ``= 0`` instead.
+    """
+    if numeric:
+        return Q(**{f"{db_field}__isnull": True}) | Q(**{db_field: 0})
+    return Q(**{f"{db_field}__isnull": True}) | Q(**{db_field: ""}) | Q(**{db_field: "-"})
+
+
+def _text_lookup(db_field: str, operator: str) -> str | None:
+    mapping = {
+        "contains": f"{db_field}__icontains",
+        "notContains": f"{db_field}__icontains",
+        "equals": f"{db_field}__iexact",
+        "notEqual": f"{db_field}__iexact",
+        "startsWith": f"{db_field}__istartswith",
+        "endsWith": f"{db_field}__iendswith",
+    }
+    return mapping.get(operator)
+
+
+_NUMERIC_OP_LOOKUPS = {">": "__gt", ">=": "__gte", "<": "__lt", "<=": "__lte", "=": ""}
+
+
+def build_expr_q(db_field: str, expr: str, *, numeric: bool = False) -> Q | None:
+    """Translate a smart-search expression into an ORM ``Q`` for *db_field*.
+
+    Mirrors the client matcher (``grid_view_spec.search.term_match``). Numeric
+    comparison/range lookups are emitted only for ``numeric`` columns to avoid
+    type-mismatch errors when comparing a text column against a number.
+    """
+    q = str(expr or "").strip()
+    if not q:
+        return None
+    # Negation: !<expr>
+    if len(q) > 1 and q[0] == "!":
+        inner = build_expr_q(db_field, q[1:].strip(), numeric=numeric)
+        return ~inner if inner is not None else None
+    if numeric:
+        bounds = parse_range_bounds(q)
+        if bounds is not None:
+            return Q(**{f"{db_field}__gte": bounds[0], f"{db_field}__lte": bounds[1]})
+        for op in NUMERIC_OPS:
+            if q.startswith(op):
+                num = parse_search_number(q[len(op) :].strip())
+                if num is None:
+                    return None
+                suffix = _NUMERIC_OP_LOOKUPS[op]
+                return Q(**{db_field if suffix == "" else f"{db_field}{suffix}": num})
+        num = parse_search_number(q)
+        return Q(**{db_field: num}) if num is not None else None
+    # Text operators (safe on text columns).
+    if len(q) > 1 and q[0] == "^":
+        return Q(**{f"{db_field}__istartswith": q[1:].strip()})
+    if len(q) > 1 and q[-1] == "$":
+        return Q(**{f"{db_field}__iendswith": q[:-1].strip()})
+    if "%" in q:
+        if q.startswith("%") and q.endswith("%") and len(q) >= 2:
+            return Q(**{f"{db_field}__icontains": q[1:-1]})
+        if q.startswith("%"):
+            return Q(**{f"{db_field}__iendswith": q[1:]})
+        if q.endswith("%"):
+            return Q(**{f"{db_field}__istartswith": q[:-1]})
+    return Q(**{f"{db_field}__icontains": q})

grid_view_spec/backends/django/apps.py

@@ -0,0 +1,18 @@
+from pathlib import Path
+
+import grid_view_spec
+from django.apps import AppConfig
+
+
+class GridViewSpecDjangoConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "grid_view_spec.backends.django"
+    label = "grid_view_spec_django"
+    path = str(Path(grid_view_spec.__file__).resolve().parent)
+    verbose_name = "Grid View Spec (Django)"
+
+    def ready(self) -> None:
+        from django.conf import settings
+        from grid_view_spec.backends.django.wire_templates import wire_grid_view_spec_templates
+
+        wire_grid_view_spec_templates(settings.TEMPLATES)

grid_view_spec/backends/django/assets.py

@@ -0,0 +1,152 @@
+"""Django asset plan → ``<link>`` / ``<script>`` emission for GridViewSpec pages."""
+
+from __future__ import annotations
+
+from django.utils.safestring import SafeString, mark_safe
+from grid_view_spec.render.block_registry import (
+    AG_GRID_BUNDLE_IDS,
+    CHARTS_BUNDLE_ID,
+    CORE_BUNDLE_ID,
+    blocks_require_ag_grid,
+    blocks_require_charts,
+)
+from grid_view_spec.types.spec import GridViewSpec
+
+# Request flags set by ``render_grid_view_spec``; read by ``grid_view_spec_assets``.
+AG_GRID_REQUEST_FLAG = "_grid_view_spec_needs_ag_grid"
+CHARTS_REQUEST_FLAG = "_grid_view_spec_needs_charts"
+
+_ASSETS_CSS_FLAG = "_grid_view_spec_assets_css_emitted"
+_ASSETS_JS_FLAG = "_grid_view_spec_assets_js_emitted"
+_AG_GRID_JS_SUPPLEMENT_FLAG = "_grid_view_spec_ag_grid_js_emitted"
+
+
+def mark_ag_grid_needed(request: object) -> None:
+    setattr(request, AG_GRID_REQUEST_FLAG, True)
+
+
+def mark_charts_needed(request: object) -> None:
+    setattr(request, CHARTS_REQUEST_FLAG, True)
+
+
+def mark_assets_from_spec(request: object, spec: GridViewSpec) -> None:
+    """Mark optional bundle requirements on ``request`` before template ``<head>`` renders."""
+    if blocks_require_ag_grid(spec.blocks):
+        mark_ag_grid_needed(request)
+    if blocks_require_charts(spec.blocks):
+        mark_charts_needed(request)
+
+
+def _request_flag(request: object | None, name: str) -> bool:
+    if request is None:
+        return False
+    return bool(getattr(request, name, False))
+
+
+def build_assets_context(
+    request: object | None,
+    *,
+    part: str,
+    force_core: bool = False,
+    force_ag_grid: bool = False,
+    force_charts: bool = False,
+) -> dict[str, SafeString | str | bool | tuple[str, ...]]:
+    """Build inclusion-tag context for CSS or JS asset partials."""
+    from grid_view_spec.backends.django.conf import (
+        ag_grid_cdn_url,
+        ag_grid_stylesheet_urls,
+        ag_grid_stylesheets_bundled,
+        echarts_cdn_url,
+    )
+    from grid_view_spec.backends.django.grid_preferences import grid_preferences_url
+    from grid_view_spec.backends.django.i18n import get_js_i18n_catalog_json
+
+    if part == "css":
+        if request is not None and getattr(request, _ASSETS_CSS_FLAG, False):
+            return {
+                "include": False,
+                "load_ag_grid": False,
+                "ag_grid_css_url": "",
+                "ag_grid_theme_css_url": "",
+            }
+        if request is not None:
+            setattr(request, _ASSETS_CSS_FLAG, True)
+        load_ag_grid_css = force_ag_grid or _request_flag(request, AG_GRID_REQUEST_FLAG)
+        ag_grid_css, ag_grid_theme_css = ("", "")
+        if load_ag_grid_css:
+            from grid_view_spec.backends.django.conf import ag_grid_stylesheet_urls
+
+            ag_grid_css, ag_grid_theme_css = ag_grid_stylesheet_urls()
+        return {
+            "include": True,
+            "load_ag_grid": load_ag_grid_css,
+            "ag_grid_bundled": ag_grid_stylesheets_bundled(),
+            "ag_grid_css_url": ag_grid_css,
+            "ag_grid_theme_css_url": ag_grid_theme_css,
+        }
+
+    if part == "ag_grid":
+        load_ag_grid = force_ag_grid or _request_flag(request, AG_GRID_REQUEST_FLAG)
+        empty_ag_grid: dict[str, SafeString | str | bool | tuple[str, ...]] = {
+            "include_scripts": False,
+            "load_ag_grid": False,
+            "ag_grid_bundled": False,
+            "ag_grid_cdn_url": "",
+        }
+        if not load_ag_grid:
+            return empty_ag_grid
+        if request is not None and getattr(request, _AG_GRID_JS_SUPPLEMENT_FLAG, False):
+            return empty_ag_grid
+        if request is not None:
+            setattr(request, _AG_GRID_JS_SUPPLEMENT_FLAG, True)
+        return {
+            "include_scripts": True,
+            "load_ag_grid": True,
+            "ag_grid_bundled": ag_grid_stylesheets_bundled(),
+            "ag_grid_cdn_url": ag_grid_cdn_url(),
+        }
+
+    if request is not None and getattr(request, _ASSETS_JS_FLAG, False):
+        return {
+            "include_scripts": False,
+            "load_charts": False,
+            "load_ag_grid": False,
+            "grid_view_i18n_catalog": mark_safe("{}"),
+            "preferences_url": grid_preferences_url(),
+            "ag_grid_cdn_url": "",
+            "echarts_cdn_url": "",
+            "core_bundle": CORE_BUNDLE_ID,
+            "charts_bundle": CHARTS_BUNDLE_ID,
+            "ag_grid_bundles": (),
+        }
+
+    load_ag_grid = force_ag_grid or _request_flag(request, AG_GRID_REQUEST_FLAG)
+    load_charts = force_charts or _request_flag(request, CHARTS_REQUEST_FLAG)
+    include_scripts = force_core or request is not None or load_ag_grid or load_charts
+    from grid_view_spec.backends.django.conf import ag_grid_stylesheet_urls
+
+    ag_grid_css, ag_grid_theme_css = ag_grid_stylesheet_urls()
+
+    if request is not None:
+        setattr(request, _ASSETS_JS_FLAG, True)
+
+    return {
+        "include_scripts": include_scripts,
+        "load_charts": load_charts,
+        "load_ag_grid": load_ag_grid,
+        # Selects static-vs-CDN URLs in the __GridViewAssets manifest. Must reflect
+        # whether vendor assets are bundled regardless of load_ag_grid: the manifest
+        # is consumed by the client lazy-loader after HTMX swaps, when AG-Grid was
+        # not eagerly loaded this render. Gating on load_ag_grid emitted raw relative
+        # vendor paths that resolved against the page URL (NS_ERROR_CORRUPTED_CONTENT).
+        "ag_grid_bundled": ag_grid_stylesheets_bundled(),
+        "grid_view_i18n_catalog": mark_safe(get_js_i18n_catalog_json()),
+        "preferences_url": grid_preferences_url(),
+        "ag_grid_cdn_url": ag_grid_cdn_url(),
+        "echarts_cdn_url": echarts_cdn_url(),
+        "ag_grid_css_url": ag_grid_css,
+        "ag_grid_theme_css_url": ag_grid_theme_css,
+        "core_bundle": CORE_BUNDLE_ID,
+        "charts_bundle": CHARTS_BUNDLE_ID,
+        "ag_grid_bundles": AG_GRID_BUNDLE_IDS if load_ag_grid else (),
+    }

grid_view_spec/backends/django/conf.py

@@ -0,0 +1,117 @@
+"""Host-configurable URL names and CDN pins for third-party scripts."""
+
+from __future__ import annotations
+
+from django.conf import settings
+
+DEFAULT_AG_GRID_VERSION = "31.3.4"
+DEFAULT_SORTABLE_VERSION = "1.15.2"
+DEFAULT_ECHARTS_VERSION = "5.5.1"
+
+
+def _str_setting(name: str, default: str) -> str:
+    val = getattr(settings, name, None)
+    if val is not None:
+        return str(val).strip()
+    return default
+
+
+def _optional_str_setting(name: str) -> str | None:
+    val = getattr(settings, name, None)
+    if val is not None:
+        return str(val).strip()
+    return None
+
+
+def export_pdf_url_name() -> str:
+    """Django URL name for PDF export (default ``api_export_pdf``)."""
+    return _str_setting("GRID_VIEW_SPEC_EXPORT_PDF_URL", "api_export_pdf")
+
+
+def grid_preferences_url_name() -> str:
+    """Django URL name for saved column presets (default ``api_grid_preferences``)."""
+    return _str_setting("GRID_VIEW_SPEC_GRID_PREFERENCES_URL", "api_grid_preferences")
+
+
+def export_xlsx_url_name() -> str:
+    """Django URL name for XLSX export (default ``api_export_xlsx``)."""
+    return _str_setting("GRID_VIEW_SPEC_EXPORT_XLSX_URL", "api_export_xlsx")
+
+
+def lazy_url_name() -> str:
+    """Django URL name for HTMX lazy block loader (default ``lazy``)."""
+    return _str_setting("GRID_VIEW_SPEC_LAZY_URL", "lazy")
+
+
+def ag_grid_version() -> str:
+    """Pinned AG-Grid Community semver (default ``31.3.4``)."""
+    return _str_setting("GRID_VIEW_SPEC_AG_GRID_VERSION", DEFAULT_AG_GRID_VERSION)
+
+
+def ag_grid_cdn_url() -> str:
+    """Script URL for AG-Grid Community.
+
+    Default: vendored copy under ``grid_view_spec/vendor/`` (see frontend build).
+    Override with ``GRID_VIEW_SPEC_AG_GRID_CDN_URL``.
+    """
+    override = _optional_str_setting("GRID_VIEW_SPEC_AG_GRID_CDN_URL")
+    if override:
+        return override
+    return "grid_view_spec/vendor/ag-grid-community.min.js"
+
+
+def ag_grid_use_bundled_assets() -> bool:
+    """True when templates should emit ``{% static %}`` vendor paths."""
+    return _optional_str_setting("GRID_VIEW_SPEC_AG_GRID_CDN_URL") is None
+
+
+def ag_grid_stylesheet_urls() -> tuple[str, str]:
+    """AG-Grid core + Quartz theme CSS URLs."""
+    css_override = _optional_str_setting("GRID_VIEW_SPEC_AG_GRID_CSS_URL")
+    theme_override = _optional_str_setting("GRID_VIEW_SPEC_AG_GRID_THEME_CSS_URL")
+    if css_override and theme_override:
+        return (css_override, theme_override)
+    if ag_grid_use_bundled_assets():
+        return (
+            "grid_view_spec/vendor/ag-grid.css",
+            "grid_view_spec/vendor/ag-theme-quartz.css",
+        )
+    version = ag_grid_version()
+    base = f"https://cdn.jsdelivr.net/npm/ag-grid-community@{version}/styles"
+    return (f"{base}/ag-grid.css", f"{base}/ag-theme-quartz.css")
+
+
+def ag_grid_stylesheets_bundled() -> bool:
+    """When True, ``css.html`` / ``js.html`` use ``{% static %}`` vendor paths."""
+    return (
+        ag_grid_use_bundled_assets()
+        and _optional_str_setting("GRID_VIEW_SPEC_AG_GRID_CSS_URL") is None
+    )
+
+
+def sortable_version() -> str:
+    """Pinned SortableJS semver for column-settings drag-reorder (default ``1.15.2``)."""
+    return _str_setting("GRID_VIEW_SPEC_SORTABLE_VERSION", DEFAULT_SORTABLE_VERSION)
+
+
+def sortable_cdn_url() -> str:
+    """Script URL for SortableJS (column settings modal)."""
+    override = _optional_str_setting("GRID_VIEW_SPEC_SORTABLE_CDN_URL")
+    if override:
+        return override
+    version = sortable_version()
+    return f"https://cdn.jsdelivr.net/npm/sortablejs@{version}/Sortable.min.js"
+
+
+def echarts_version() -> str:
+    """Pinned ECharts semver for host base templates (default ``5.5.1``)."""
+    return _str_setting("GRID_VIEW_SPEC_ECHARTS_VERSION", DEFAULT_ECHARTS_VERSION)
+
+
+def echarts_cdn_url() -> str:
+    """Script URL for Apache ECharts (load in host base template before page JS bundle)."""
+    override = _optional_str_setting("GRID_VIEW_SPEC_ECHARTS_CDN_URL")
+    if override:
+        return override
+    version = echarts_version()
+    return f"https://cdn.jsdelivr.net/npm/echarts@{version}/dist/echarts.min.js"