fjkit-charts 0.1.0__tar.gz

fjkit_charts-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+*.egg-info
+
+# Packaging output — anchored to the repo root on purpose, so the pattern does
+# not swallow app/static/dist/, which is a build artefact we DO commit.
+/build/
+/dist/
+/wheels/
+
+# Virtual environments
+.venv
+
+# Project
+.env
+# The admin demo's database — created and seeded on first start.
+examples/fjkit-admin-demo/admin-demo.sqlite
+.jinja-cache/
+.pytest_cache/
+
+# fjkit build output — regenerated by `uv run fjkit build-css`
+packages/fjkit/src/fjkit/static/dist/
+
+# Docs-site intermediate — regenerated by `docs/workbench/build.py`. The
+# templates and the renderers are the source; this is the rendered previews on
+# their way into docs/assets/data.js, which IS committed.
+packages/fjkit/docs/workbench/data.json
+
+# 私人目標文件 — 刻意不進版控
+/goal/
+
+# Agent worktrees — embedded checkouts, never part of a commit.
+.claude/worktrees/
+
+# The built editor extension; `tools/fjkit-vscode/build.py` recreates it.
+tools/fjkit-vscode/dist/

fjkit_charts-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 liweicheng00
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fjkit_charts-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.5
+Name: fjkit-charts
+Version: 0.1.0
+Summary: Server-rendered Plotly charts for fjkit — a plugin, no front-end build
+Project-URL: Homepage, https://liweicheng00.github.io/fjkit/
+Project-URL: Documentation, https://liweicheng00.github.io/fjkit/
+Project-URL: Repository, https://github.com/liweicheng00/fjkit
+Project-URL: Issues, https://github.com/liweicheng00/fjkit/issues
+Author: liweicheng00
+License-Expression: MIT
+License-File: LICENSE
+Keywords: charts,dashboard,fastapi,fjkit,jinja2,no-build,plotly,server-rendered
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: fjkit>=0.1.0.dev0
+Requires-Dist: pydantic>=2.9
+Description-Content-Type: text/markdown
+
+# fjkit-charts
+
+Server-rendered Plotly charts for [fjkit](https://liweicheng00.github.io/fjkit/).
+A plugin, one line to add, no front-end build.
+
+```bash
+uv add fjkit-charts
+```
+
+```python
+from fjkit import FjkitConfig
+from fjkit_charts import ChartsPlugin
+
+config = FjkitConfig(template_dir=APP_DIR / "templates", plugins=(ChartsPlugin(),))
+```
+
+```jinja
+{% from "charts/macros.html" import chart, chart_scripts %}
+{% for item in charts %}{{ chart(item) }}{% endfor %}
+
+{% block scripts %}{{ chart_scripts() }}{% endblock %}
+```
+
+Plotly's basic bundle ships inside this wheel and is served from the plugin's
+own static mount. Nothing is fetched at runtime, and a page loads the 1.1 MB
+only if it calls `chart_scripts()`.
+
+Chart chrome — axis text, grid lines, tick colour, the hover card — is resolved
+from the live theme tokens on every draw, so a theme toggle is a redraw.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

fjkit_charts-0.1.0/README.md

@@ -0,0 +1,33 @@
+# fjkit-charts
+
+Server-rendered Plotly charts for [fjkit](https://liweicheng00.github.io/fjkit/).
+A plugin, one line to add, no front-end build.
+
+```bash
+uv add fjkit-charts
+```
+
+```python
+from fjkit import FjkitConfig
+from fjkit_charts import ChartsPlugin
+
+config = FjkitConfig(template_dir=APP_DIR / "templates", plugins=(ChartsPlugin(),))
+```
+
+```jinja
+{% from "charts/macros.html" import chart, chart_scripts %}
+{% for item in charts %}{{ chart(item) }}{% endfor %}
+
+{% block scripts %}{{ chart_scripts() }}{% endblock %}
+```
+
+Plotly's basic bundle ships inside this wheel and is served from the plugin's
+own static mount. Nothing is fetched at runtime, and a page loads the 1.1 MB
+only if it calls `chart_scripts()`.
+
+Chart chrome — axis text, grid lines, tick colour, the hover card — is resolved
+from the live theme tokens on every draw, so a theme toggle is a redraw.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

fjkit_charts-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+# Charts as their own distribution, so an app that draws none does not install
+# Plotly. The bundle is 1.1 MB — 365 KB over the wire — and was 37% of what
+# `pip install fjkit` downloaded while it lived in the kit's wheel.
+#
+# The import package is `fjkit_charts`, not `fjkit_charts`: `fjkit/__init__.py`
+# exists, so `fjkit` is a regular package and a second distribution cannot
+# legally write into its directory. Making `fjkit` a PEP 420 namespace package
+# would cost that `__init__.py`. The underscore is the cheaper answer, and it
+# was free to take before 0.1.0 reached PyPI.
+[project]
+name = "fjkit-charts"
+version = "0.1.0"
+description = "Server-rendered Plotly charts for fjkit — a plugin, no front-end build"
+readme = "README.md"
+requires-python = ">=3.13"
+authors = [{ name = "liweicheng00" }]
+license = "MIT"
+license-files = ["LICENSE"]
+
+keywords = ["fastapi", "jinja2", "fjkit", "plotly", "charts", "dashboard", "server-rendered", "no-build"]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Web Environment",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+    "Topic :: Scientific/Engineering :: Visualization",
+    "Topic :: Software Development :: User Interfaces",
+    "Typing :: Typed",
+]
+
+# `pydantic` came across with `figures.py`, which was its only importer in the
+# kit: `PlotlyFigure` is a model an app embeds in its own `response_model`.
+#
+# `plotly` the Python package is deliberately absent. `figures.py` duck-types on
+# `to_plotly_json()`, so an app that builds figures by hand needs nothing extra
+# and an app that uses `plotly` declares it itself.
+dependencies = [
+    "fjkit>=0.1.0.dev0",
+    "pydantic>=2.9",
+]
+
+[project.urls]
+Homepage = "https://liweicheng00.github.io/fjkit/"
+Documentation = "https://liweicheng00.github.io/fjkit/"
+Repository = "https://github.com/liweicheng00/fjkit"
+Issues = "https://github.com/liweicheng00/fjkit/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fjkit_charts"]
+
+[tool.hatch.build]
+# The Plotly bundle and the theming bridge ship inside the wheel — that is what
+# keeps "nothing to download" true for a page that draws charts.
+artifacts = [
+    "src/fjkit_charts/templates/**/*",
+    "src/fjkit_charts/static/**/*",
+]

fjkit_charts-0.1.0/scripts/vendor_plotly.py

@@ -0,0 +1,42 @@
+"""Vendor Plotly's basic bundle into the fjkit-charts package.
+
+Split out of the kit's `scripts/vendor_ui.py` when charts became their own
+distribution: the bytes live here now, so the script that fetches them does too.
+
+    uv run python packages/fjkit-charts/scripts/vendor_plotly.py
+"""
+
+from __future__ import annotations
+
+import urllib.request
+from pathlib import Path
+
+# Single source of truth lives in the package, so the URL the plugin advertises
+# cannot drift from the bytes on disk.
+from fjkit_charts.plugin import PLOTLY_FILENAME, PLOTLY_VERSION
+
+PACKAGE = Path(__file__).resolve().parent.parent / "src" / "fjkit_charts"
+VENDOR = PACKAGE / "static" / "vendor" / "plotly"
+
+JSDELIVR = "https://cdn.jsdelivr.net/npm"
+
+
+def fetch(url: str) -> bytes:
+    with urllib.request.urlopen(url, timeout=30) as response:
+        return response.read()
+
+
+def vendor_plotly() -> None:
+    # The basic bundle, not the full one — `PLOTLY_VERSION` says why. Served
+    # from this plugin's own static mount, and loaded by nothing but the page
+    # that calls `chart_scripts()`.
+    print(f"plotly.js-basic-dist-min@{PLOTLY_VERSION}")
+    target = VENDOR / PLOTLY_FILENAME
+    target.parent.mkdir(parents=True, exist_ok=True)
+    payload = fetch(f"{JSDELIVR}/plotly.js-basic-dist-min@{PLOTLY_VERSION}/{PLOTLY_FILENAME}")
+    target.write_bytes(payload)
+    print(f"  {target.relative_to(PACKAGE.parent.parent)}  {len(payload) / 1024:.0f} KB")
+
+
+if __name__ == "__main__":
+    vendor_plotly()

fjkit_charts-0.1.0/src/fjkit_charts/__init__.py

@@ -0,0 +1,55 @@
+"""Charts for a fjkit app: a plugin, one line to add and nothing to skip.
+
+    from fjkit import FjkitConfig
+    from fjkit_charts import ChartsPlugin
+
+    config = FjkitConfig(
+        template_dir=APP_DIR / "templates",
+        plugins=(ChartsPlugin(),),
+    )
+
+Then in a template:
+
+    {% from "charts/macros.html" import chart, chart_scripts %}
+    {% for item in charts %}{{ chart(item) }}{% endfor %}
+
+    {% block scripts %}{{ chart_scripts() }}{% endblock %}
+
+and in the router, a `Chart` per figure:
+
+    from fjkit_charts import Chart, figure_of
+
+    Chart(id="by-owner", title="Workload", summary="Ana has 5 of 12 open tasks.",
+          figure=figure_of(go.Figure(...)))
+
+That is the whole setup. Plotly's basic bundle ships in this wheel — one of the
+scripts CHARTER §7 whitelists, pinned here rather than in `fjkit.vendored`
+because the bytes are here too — and is served from this plugin's own static
+mount. No download, no npm, no bundler, nothing fetched at runtime. A page
+loads the 1.1 MB only if it calls `chart_scripts()`.
+"""
+
+from __future__ import annotations
+
+from fjkit_charts.figures import (
+    Chart,
+    PlotlyFigure,
+    PlotlyLayout,
+    PlotlyTrace,
+    assert_no_colour_in,
+    figure_of,
+)
+from fjkit_charts.plugin import PLOTLY_FILENAME, PLOTLY_URL, PLOTLY_VERSION, ChartsPlugin
+
+__all__ = [
+    "PLOTLY_FILENAME",
+    "PLOTLY_URL",
+    "PLOTLY_VERSION",
+    "Chart",
+    "ChartsPlugin",
+    "PlotlyFigure",
+    "PlotlyLayout",
+    "PlotlyTrace",
+    "assert_no_colour_in",
+    "figure_of",
+]

fjkit_charts-0.1.0/src/fjkit_charts/figures.py

@@ -0,0 +1,189 @@
+"""A Plotly figure, typed down to the parts this package reads.
+
+The figure that reaches the browser is a Plotly figure: `data` and `layout`, the
+names Plotly's own documentation uses. It is not `dict[str, Any]` — the fields
+the drawing code branches on are typed, and the rest arrives through an explicit
+tail. OpenAPI can then state which fields are promised and which are Plotly's.
+
+A figure carries no colour.
+
+Series run on Plotly's own palette, applied in the browser, so nothing on the
+server picks a hue. A colour written into the figure is wrong in one of the two
+themes, invisible to `fjkit check` (which reads class attributes, not JSON), and
+unchangeable without a redeploy.
+
+`extra="allow"` makes the Plotly tail reachable and is also the hole in that
+rule: `#1F77B4` is a legal `str`, so no schema stops a colour arriving through
+it. The guard is a test that scans the rendered figure JSON, which does not care
+which field the bytes came from. `ChartsPlugin` ships that test as
+`fjkit_charts.assert_no_colour_in`, so an app gets it in one line.
+
+**plotly is not a dependency of fjkit.** `figure_of` takes anything with a
+`to_plotly_json()`, which is its whole required surface. An app that builds
+figures by hand as dicts never installs plotly.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict
+
+__all__ = [
+    "Chart",
+    "PlotlyFigure",
+    "PlotlyLayout",
+    "PlotlyTrace",
+    "assert_no_colour_in",
+    "figure_of",
+]
+
+
+class PlotlyTrace(BaseModel):
+    """One series, in Plotly's vocabulary.
+
+    Typed down to what the drawing code reads and no further. `type` is a
+    `Literal` rather than `str` because the browser branches on it: a fourth
+    trace kind arriving unannounced renders a silent empty chart, which is how
+    `mpl_to_plotly` fails.
+
+    Everything else Plotly accepts — `mode`, `hole`, `textposition`,
+    `hovertemplate` — comes through `extra="allow"` untyped. That tail is what
+    makes the full library reachable, and why the colour check is not optional.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    type: Literal["bar", "scatter", "pie"]
+    name: str | None = None
+    #: Cartesian traces. Not "category" and "value": Plotly's `x` and `y` are
+    #: axes, and a horizontal bar puts the numbers on `x` and the labels on
+    #: `y`. Typing them as `str` and `float` respectively looks right until the
+    #: first `orientation="h"` chart. That is this module's lesson in small: a
+    #: typed subset of somebody else's schema is a guess, and the tail is what
+    #: stops a wrong guess being fatal.
+    x: list[str | float] | None = None
+    y: list[str | float] | None = None
+    #: Pie traces use different names for the same two ideas.
+    labels: list[str] | None = None
+    values: list[float] | None = None
+
+
+class PlotlyLayout(BaseModel):
+    """Layout, minus everything the theme owns.
+
+    No font, no grid colour, no background: those resolve from the live tokens
+    at draw time and would be overwritten anyway. What remains is what the route
+    decides — how bars combine, whether there is a legend, what the axes are
+    called, and the tick rules the data implies.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    barmode: Literal["stack", "group"] | None = None
+    showlegend: bool | None = None
+
+
+class PlotlyFigure(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    data: list[PlotlyTrace]
+    layout: PlotlyLayout
+
+
+class Chart(BaseModel):
+    """A figure, plus the three things a figure cannot supply itself: a stable
+    id, a sentence describing it, and what its series mean.
+
+    `summary` is required, not decoration. It is the text alternative, and the
+    only content a reader without JavaScript gets. A required field rather than
+    a keyword someone forgets: a chart with no text alternative is invisible to
+    a screen reader, and the macro cannot invent the sentence.
+    """
+
+    id: str
+    title: str
+    description: str = ""
+    #: Write it from the same numbers the traces are built from, so it cannot
+    #: describe a different chart.
+    summary: str
+    height: int = 288
+    figure: PlotlyFigure
+
+    # A plain property, not a `@computed_field`: a computed field joins the JSON
+    # representation, putting the same bytes on the wire twice — `figure` is
+    # already there, and this only renders it for an HTML attribute. Jinja reads
+    # plain properties.
+    @property
+    def figure_json(self) -> str:
+        """Render the figure for an HTML attribute.
+
+        `exclude_none` because the typed fields are a superset of any one trace:
+        a bar has no `labels`, a pie has no `x`. Emitting them as nulls sends
+        Plotly keys it has to ignore, on every trace."""
+        return json.dumps(self.figure.model_dump(exclude_none=True))
+
+
+def figure_of(fig: Any) -> PlotlyFigure:
+    """Validate a `plotly.graph_objects.Figure` into the model above.
+
+    Two things happen on the way through. Both must happen exactly once, so
+    neither is left to callers:
+
+    * `template` is dropped. `plotly.py` writes one even when it is set to
+      `None`, and the default template is 7,621 bytes carrying 111 colour
+      literals, each of which violates this module's colour rule.
+    * the figure is validated, so a trace type the browser cannot draw fails
+      here rather than rendering an empty box.
+
+    Duck-typed on `to_plotly_json()` rather than imported from plotly, which
+    keeps plotly out of fjkit's dependencies. A plain dict also works.
+    """
+    payload = fig.to_plotly_json() if hasattr(fig, "to_plotly_json") else dict(fig)
+    layout = payload.get("layout")
+    if isinstance(layout, dict):
+        layout.pop("template", None)
+    return PlotlyFigure.model_validate(payload)
+
+
+#: Hex literals and the CSS colour functions, in figure JSON. The same families
+#: `fjkit check` looks for in markup: one rule, of which this is the half that
+#: reads JSON instead of class attributes.
+_COLOUR = re.compile(
+    r"#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b"
+    r"|\b(?:rgb|rgba|hsl|hsla|oklch|oklab|lab|lch)\("
+    r"|\bvar\(--"
+)
+
+
+def assert_no_colour_in(charts: Any) -> None:
+    """Raise if any figure carries a colour. For an app's own test suite.
+
+        from fjkit_charts import assert_no_colour_in
+
+        def test_the_figures_carry_no_colour(client):
+            assert_no_colour_in(build_my_charts())
+
+    Scans the rendered JSON rather than the model fields, so it catches a hue
+    that arrived through `extra="allow"` — the only route a hue can take.
+
+    `var(--…)` is in the pattern because that failure looks like it works:
+    `plotly.py` accepts the string, validates it and serialises it, and the
+    browser's parser then discards it silently. A token name on the server is
+    not a token; it is a typo with a plausible shape.
+
+    Accepts one `Chart`, an iterable of them, or anything JSON-serialisable.
+    """
+    items = charts if isinstance(charts, (list, tuple)) else [charts]
+    for item in items:
+        blob = item.figure_json if isinstance(item, Chart) else json.dumps(item, default=str)
+        found = _COLOUR.search(blob)
+        if found is not None:
+            where = getattr(item, "id", "<figure>")
+            raise AssertionError(
+                f"chart {where!r} carries the colour literal {found.group(0)!r}. "
+                "Series colours are Plotly's and the chrome is resolved from tokens in the "
+                "browser — a colour written on the server is wrong in one of the two themes."
+            )

fjkit_charts-0.1.0/src/fjkit_charts/plugin.py

@@ -0,0 +1,108 @@
+"""`ChartsPlugin` — charts as a registration, not a page built twice.
+
+    config = FjkitConfig(template_dir=…, plugins=(ChartsPlugin(),))
+
+That gives an app the `chart` macro, the theming bridge, the Plotly bundle and
+the two `<script>` lines that load them. Nothing to download, nothing to mount:
+Plotly ships inside this wheel — one of the scripts CHARTER §7 whitelists — and
+is served from this plugin's own static mount.
+
+**The division of labour.** Python decides the shape of the figure; the browser
+decides its chrome. Axis text, grid lines, tick colour, the gaps between pie
+slices and the hover card belong to the card a chart sits in, not to the data,
+and Plotly's defaults for them are `#444` on `#eee` — a chart drawn for a white
+page, on a page that may be dark. So `charts.js` resolves those from the live
+tokens on every draw, and a theme toggle is a redraw. The series colours are
+Plotly's own and never change.
+
+**Why the JavaScript is not in the shell.** A plugin cannot inject markup into
+`ui/shell.html` (`fjkit.plugins`), and this is why that rule holds: Plotly's
+basic bundle is 1.1 MB, so a hook letting this plugin put a `<script>` on every
+page would put it on the login screen. Instead the page that draws charts calls
+`chart_scripts()` in its own `{% block scripts %}` and no other page pays. Being
+in the wheel changes what an install contains, not what a page downloads, and §7
+budgets the download. Which distribution the bundle lives in decides the first
+of those: an app that never draws a chart does not install `fjkit-charts` and
+never carries the 1.1 MB at all.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fjkit.plugins import AppSetup, EnvSetup
+from fjkit.templating import static_url
+
+__all__ = ["PLOTLY_VERSION", "ChartsPlugin"]
+
+#: This plugin's own templates. Named `templates/charts/` so template names are
+#: `charts/…`, matching how `apidocs` does it.
+TEMPLATE_DIR = Path(__file__).parent / "templates"
+
+#: `charts.js` — the theming bridge. 3 KB, and the only JavaScript this plugin
+#: ships of its own.
+STATIC_DIR = Path(__file__).parent / "static"
+
+#: Plotly's basic bundle — scatter, bar and pie. The full `plotly.js-dist-min`
+#: is 4.85 MB of 3D, maps, financial and statistical traces most dashboards
+#: never draw; the basic one is 1.1 MB, and picking the bundle is the only size
+#: knob Plotly offers without a build step.
+#:
+#: The pin lives here rather than in `fjkit.vendored` because the bytes do:
+#: `scripts/vendor_plotly.py` writes them under this package's own
+#: `static/vendor/plotly/`, and the kit no longer knows Plotly exists.
+PLOTLY_VERSION = "3.7.0"
+
+PLOTLY_FILENAME = "plotly-basic.min.js"
+
+#: Relative to this plugin's `assets` mount, not the kit's static mount.
+PLOTLY_PATH = f"vendor/plotly/{PLOTLY_FILENAME}"
+PLOTLY_URL = f"https://cdn.jsdelivr.net/npm/plotly.js-basic-dist-min@{PLOTLY_VERSION}/{PLOTLY_FILENAME}"
+
+
+class ChartsPlugin:
+    """Register in `FjkitConfig.plugins`.
+
+    :param url: where this plugin's own assets (`charts.js`) are served. Keep it
+        outside `config.static_url` (`/_fjkit` by default): Starlette matches
+        the first mount whose prefix fits, so a path nested inside the kit's own
+        static mount is swallowed by it and 404s against a directory that does
+        not hold this plugin's files.
+    :param plotly_url: serve Plotly from somewhere other than the copy in the
+        wheel — a path your app already serves, or a URL. The default is the
+        vendored bundle under this plugin's own `url`, cache-stamped like every
+        other kit asset.
+    """
+
+    name = "charts"
+
+    def __init__(self, *, url: str = "/_fjkit-charts", plotly_url: str | None = None) -> None:
+        if not url.startswith("/") or url == "/":
+            raise ValueError(f"ChartsPlugin(url={url!r}) must be an absolute path such as '/_fjkit-charts'.")
+        self.url = url.rstrip("/")
+        self.plotly_url = plotly_url
+
+    # ---------------------------------------------------------------- plugin
+
+    def mount(self, setup: AppSetup) -> None:
+        # The bridge and the bundle both. `STATIC_DIR` holds `charts.js` beside
+        # `vendor/plotly/`, so one mount serves everything this plugin ships.
+        setup.mount_static(f"{self.url}/assets", STATIC_DIR)
+
+    def extend(self, setup: EnvSetup) -> None:
+        """Contribute the templates and the two URLs they need.
+
+        The globals are namespaced `fjkit_charts_*` for the reason `EnvSetup`
+        makes collisions a startup error: an app is entitled to want `charts`
+        for its own context.
+        """
+        setup.add_template_dir(TEMPLATE_DIR)
+
+        # Same `?v=<mtime>` stamp the kit's own assets get, for the same reason:
+        # StaticFiles sends no Cache-Control, so a browser may keep a script
+        # whose lifetime it was never told.
+        assets = static_url(f"{self.url}/assets", STATIC_DIR, auto_reload=setup.config.auto_reload)
+        setup.add_global("fjkit_charts_script", lambda: assets("charts.js"))
+
+        plotly = self.plotly_url if self.plotly_url is not None else assets(PLOTLY_PATH)
+        setup.add_global("fjkit_charts_plotly", lambda: plotly)