django-grid-view 1.2.0

Declarative grid views for Django: Simple Table, AG-Grid helpers, KPI cards, ECharts, and an LLM-friendly GridViewSpec contract

Django Grid View

Declarative grid views for Django — server tables, AG-Grid dashboards, KPI strips, and ECharts from one typed package. You own the data (rows from SQL/ORM); the library owns layout, formatting, and front-end wiring.

Documentation · LLM context bundle · PyPI

---

Why this package

Building dashboards and chat analytics in Django usually means stitching together three different stacks: hand-rolled HTML tables, AG-Grid boilerplate, and ad‑hoc chart JSON. django-grid-view unifies them behind a single contract:

Principle	What it means for you
Structure ≠ data	Specs (GridViewSpec, wire JSON) describe columns, KPIs, and charts — never row values or aggregates from an LLM.
One render path	GridRenderer.build(spec, rows) → GridArtifact → templates + grid-view.min.js. No parallel chart/table code paths.
Typed boundaries	py.typed, strict-friendly django_grid_view.types, JSON Schema for wire specs — host apps keep pyright/mypy honest.
Production habits	HTMX-safe AG-Grid lifecycle, saved grid preferences, uk/en i18n, optional matplotlib PNG export for PDFs.

---

What you get

Simple Table

Server-rendered tables with sort, search, CSV/XLSX export, grouped headers — no SPA required.

from django_grid_view.tables import Column, SimpleTableConfig

config = SimpleTableConfig(
    grid_id="products",
    columns=[Column(key="sku", label="SKU"), Column(key="name", label="Name")],
    data=rows,
)

{% load django_grid_view %}
{% render_simple_table config %}

AG-Grid helpers

Scripts, toolbar, advanced search plugins, and GridPreference storage for large or infinite grids. The package does not own your gridApi — you keep control of the grid instance; we supply the integration layer.

Grid View — KPI, charts, and table together

One GridViewSpec drives KPI cards, ECharts blocks, and tabular layout. Ideal for dashboard pages and chat “visualizer” UIs fed by analytics SQL.

from django_grid_view import GridViewSpec, RowDict, build_artifact_from_view
from django_grid_view.types import ColumnSpec, KpiSpec, KpiAggregate

artifact = build_artifact_from_view(
    {
        "grid_id": "overview",
        "columns": [{"key": "name", "label": "Name"}],
        "kpis": [{"label": "Total", "column_key": "amount", "aggregate": "sum"}],
    },
    rows,
)

{% grid_view_bundle %}
{% render_grid_view artifact %}

---

Install

pip install django-grid-view
# optional: static chart PNG export for PDF pipelines
pip install "django-grid-view[static-charts]"

# settings.py
INSTALLED_APPS = ["django_grid_view"]

# settings.py
DJANGO_GRID_VIEW_EXPORT_PDF_URL = "api_export_pdf"
DJANGO_GRID_VIEW_EXPORT_XLSX_URL = "api_export_xlsx"

# api/urls.py — mount under path("api/", include(...))
from django_grid_view.export.pdf_view import export_pdf
from django_grid_view.export.xlsx_view import export_xlsx
from django_grid_view.views import save_grid_settings

urlpatterns = [
    path("grid/preferences/", save_grid_settings, name="api_grid_preferences"),
    path("export/pdf/", export_pdf, name="api_export_pdf"),
    path("export/xlsx/", export_xlsx, name="api_export_xlsx"),
]

python manage.py migrate django_grid_view

Full walkthrough: Getting started.

---

Documentation

Topic	Link
Simple Table	Guide
AG-Grid + HTMX	Guide
KPI & ECharts	Guide
GridViewSpec → artifact	Grid View artifacts
Python types for host apps	Reference
JSON Schema (wire)	schema/grid-view-spec.v1.json
Agents & coding tools	LLM bundle · Agent skill
Changelog	1.0.0 notes

---

Roadmap — A2UI & AG-UI

1.0 (shipped) is the renderer: tables, KPI strip, ECharts, i18n, and GridRenderer in this repo.

Next step for host applications is protocol alignment, not replacing the renderer:

• A2UI — treat GridViewSpec as the declarative UI catalog (structure-only JSON agents and planners emit).
• AG-UI — stream resolved grid_view artifacts over an application event channel (router, SSE, chat, dashboard, or another host transport).

django-grid-view stays the single place that turns rows + spec → GridArtifact. Presenter and transport logic live in consumer apps.

---

Development

Requires uv. CI uses uv sync --frozen --group dev.

Install git hooks (strips Co-authored-by: Cursor from commit messages):

./scripts/install-git-hooks.sh

uv sync --group dev
uv run pytest
uv run ruff check . && uv run ruff format --check .
uv run basedpyright --warnings src/django_grid_view tests
./scripts/docs_serve.sh   # MkDocs + LLM bundle

JavaScript (maintainers only)

Browser bundles are built from TypeScript in frontend/src/ and written to src/django_grid_view/static/django_grid_view/ (.js + .min.js). PyPI consumers do not need Node — the wheel ships pre-built static files.

frontend/src/
  grid-view-entry.ts      # esbuild entry (IIFE bundle → grid-view.js)
  grid-view/              # modules: charts, kpi, filter-bar, search/, …
  column-settings.ts
  types/                  # chart-bind, kpi-bind (mirror Python contracts)

cd frontend && npm ci && npm run build   # transpile + minify
npm run typecheck && npm run lint        # strict types on search/ + contracts; eslint on all src/
npm run test:conformance                 # Python↔JS filter/search parity (shared JSON fixtures)

After editing frontend/src/*.ts, commit the regenerated static artifacts (CI verifies git diff --exit-code src/django_grid_view/static/).

Load order for host pages: {% grid_view_bundle %} once → grid-view.min.js + column-settings.min.js. AG-Grid pages add scripts.html partials. Details: Architecture · JavaScript API.

Release: tag v* on main → PyPI via trusted publishing (environment: pypi). Docs deploy from main via GitHub Actions.

---

License

MIT — see LICENSE.