fjkit-charts 0.1.0.dev0__py3-none-any.whl

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/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/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)

fjkit_charts/static/charts.js

@@ -0,0 +1,199 @@
+/*
+  Themes a Plotly chart to the fjkit page it sits on.
+
+  The series run on Plotly's own palette: the figure the server sends carries no
+  colour, and nothing here paints one on. This file does the other half —
+  everything around the data. Axis labels, grid lines, tick text, the gaps
+  between pie slices, the hover card. Those belong to the card the chart sits in,
+  not to the data, and Plotly's defaults for them are `#444` text on `#eee` grid:
+  a chart drawn for a white page, on a page that might be dark.
+
+  So the chrome is resolved from the live tokens on every draw, and a theme
+  toggle is a redraw. The data colours are not resolved and do not change.
+
+  The division of labour with the server: Python decides the shape, this file
+  decides the chrome.
+
+  Loaded only by charts/page.html. Plotly is 1.1 MB — no other page pays for it.
+*/
+(() => {
+  "use strict";
+
+  /* How a token becomes something Plotly understands.
+
+     The tokens are `oklch()`. Plotly parses colours with tinycolor2, which
+     predates CSS Color 4: hand it `oklch(0.72 0.15 275)` and it reports no
+     error, it draws its own default palette instead. That failure is invisible
+     in a screenshot unless you know what fjkit's primary is meant to look like,
+     which is what makes it worth this much comment. `var(--success)` fails the
+     same way and is worse, because `plotly.py` accepts that string on the
+     server: it validates, it serialises, and it is discarded here.
+
+     So the conversion happens in the browser, using the browser's own parser.
+     Any table written here would be a second definition of the colour, and the
+     point is that there is one.
+
+     Not enough: assigning to `fillStyle` and reading it back. That round-trip
+     normalises the legacy formats to `#rrggbb` but preserves modern colour
+     functions verbatim — `oklch` in, `oklch` out — so it looks like it works
+     until you check what Plotly received.
+
+     Painting one pixel and reading it does work. `getImageData` answers in sRGB
+     bytes whatever the source notation was, which is also the right clamp: the
+     SVG Plotly emits is sRGB regardless. One 1x1 canvas, read a handful of times
+     per redraw.
+
+     Assigning the fallback first matters: an unparseable value leaves
+     `fillStyle` untouched, so without a known starting point a mistyped token
+     would inherit the previous colour instead of being visibly wrong. */
+  const canvas = document.createElement("canvas");
+  canvas.width = canvas.height = 1;
+  const probe = canvas.getContext("2d", { willReadFrequently: true });
+
+  function resolve(token, fallback) {
+    const raw = getComputedStyle(document.documentElement).getPropertyValue(token).trim();
+    probe.clearRect(0, 0, 1, 1);
+    probe.fillStyle = fallback;
+    probe.fillStyle = raw || fallback;
+    probe.fillRect(0, 0, 1, 1);
+    /* Alpha is carried through rather than flattened: `--border` is defined as
+       white at 11% in dark mode, and a grid line that ignores that is drawn on
+       top of the data. */
+    const [r, g, b, a] = probe.getImageData(0, 0, 1, 1).data;
+    return `rgba(${r}, ${g}, ${b}, ${(a / 255).toFixed(3)})`;
+  }
+
+  /* Read once per draw, not once per load: the theme toggle changes all three,
+     and a cached palette leaves the chart in the previous theme's colours. */
+  function palette() {
+    return {
+      text: resolve("--foreground", "#333333"),
+      grid: resolve("--border", "#cccccc"),
+      surface: resolve("--popover", "#ffffff"),
+    };
+  }
+
+  /* The per-trace half of the chrome.
+
+     Only pies need it, and only because Plotly's pie ignores `layout.font`: its
+     `textfont` defaults to #444 whatever the rest of the figure says, so the
+     labels come out dark grey on whatever colour the card is. The slice gaps get
+     the card's colour too, which makes a donut read as cut rather than outlined.
+
+     Nothing here touches `marker.color` or `marker.colors`. The series palette
+     is Plotly's. */
+  function chrome(data, colors) {
+    return data.map((trace) =>
+      trace.type === "pie"
+        ? {
+            ...trace,
+            marker: { ...trace.marker, line: { color: colors.surface, width: 2 } },
+            textfont: { color: colors.text },
+          }
+        : trace,
+    );
+  }
+
+  /* The layout half the theme owns. The figure's own layout is merged over the
+     top, so anything the route decided wins. */
+  function themed(colors, height) {
+    /* Inherits the page's font rather than naming one. Plotly's default is
+       Open Sans, which nothing else on the card is set in. */
+    const font = { color: colors.text, family: getComputedStyle(document.body).fontFamily, size: 12 };
+    const axis = {
+      gridcolor: colors.grid,
+      zerolinecolor: colors.grid,
+      linecolor: colors.grid,
+      tickfont: font,
+      automargin: true,
+    };
+
+    return {
+      height: height,
+      /* Transparent, so the card underneath is the background in both themes and
+         there is no second surface colour to keep in agreement. */
+      paper_bgcolor: "rgba(0,0,0,0)",
+      plot_bgcolor: "rgba(0,0,0,0)",
+      font: font,
+      margin: { l: 8, r: 8, t: 8, b: 8 },
+      legend: { orientation: "h", y: -0.18, font: font },
+      xaxis: { ...axis },
+      yaxis: { ...axis, rangemode: "tozero" },
+      hoverlabel: { bgcolor: colors.surface, bordercolor: colors.grid, font: font },
+    };
+  }
+
+  /* One level deep, which is what the axes need: the figure carries
+     `yaxis: {title, dtick}` and the theme carries `yaxis: {gridcolor,
+     tickfont}`. A plain spread would drop one whole side of that. */
+  function merge(base, extra) {
+    const out = { ...base };
+    for (const [key, value] of Object.entries(extra || {})) {
+      const mergeable =
+        value && typeof value === "object" && !Array.isArray(value) && base[key] && typeof base[key] === "object";
+      out[key] = mergeable ? { ...base[key], ...value } : value;
+    }
+    return out;
+  }
+
+  /* `react` rather than `newPlot`: `react` is idempotent. First draw, theme
+     change and htmx swap all go through the same call, so there is no "has this
+     been drawn yet" flag to get wrong. */
+  const CONFIG = { displayModeBar: false, responsive: true, staticPlot: false };
+
+  function draw(element) {
+    const figure = JSON.parse(element.dataset.figure);
+    /* The height arrives as a number and is applied here rather than as a
+       `style=""` in the template. fjkit's vocabulary is closed and has no sizing
+       utility, so the alternative was an inline style in markup — and the height
+       is a property of the figure, which is already a model. */
+    const height = Number(element.dataset.height) || 288;
+    element.style.height = height + "px";
+
+    const colors = palette();
+    Plotly.react(element, chrome(figure.data, colors), merge(themed(colors, height), figure.layout), CONFIG);
+  }
+
+  function drawAll(root) {
+    const scope = root || document;
+    /* `matches` first, because an htmx swap can hand back the chart element
+       itself — `querySelectorAll` never returns its own root. */
+    if (scope.matches && scope.matches("[data-chart]")) draw(scope);
+    if (scope.querySelectorAll) scope.querySelectorAll("[data-chart]").forEach(draw);
+  }
+
+  if (!window.Plotly) {
+    console.warn("[charts] Plotly did not load; the figcaption under each chart is the fallback.");
+    return;
+  }
+
+  addEventListener("DOMContentLoaded", () => drawAll(document));
+
+  /* htmx swaps in charts that have never been drawn. `htmx:load` fires once per
+     new node, which is the hook needed here — `htmx:afterSwap` fires once per
+     request and hands back the target rather than the new content. */
+  document.body.addEventListener("htmx:load", (event) => drawAll(event.target));
+
+  /* htmx also swaps charts out. Plotly attaches resize listeners and, on some
+     trace types, a WebGL context; dropping the node without purging leaks both.
+     A chart inside a partial usually forgets this half. */
+  document.body.addEventListener("htmx:beforeCleanupElement", (event) => {
+    if (event.target.matches && event.target.matches("[data-chart]")) Plotly.purge(event.target);
+  });
+
+  /* The theme toggle flips `.dark` on <html> and nothing else fires. Watching
+     the attribute keeps this file independent of how the toggle is implemented,
+     and a `prefers-color-scheme` change lands here too, because the shell's
+     flash-guard writes the same class.
+
+     The redraw changes the chrome: text, grid, slice gaps, hover card. The data
+     keeps its colours, which were never ours.
+
+     Not watched: the demo's style-pack picker. The eight packs define no colour
+     tokens at all — they differ in geometry, radii and control heights — so a
+     pack switch cannot change anything read here. */
+  new MutationObserver(() => drawAll(document)).observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: ["class"],
+  });
+})();