coeftable 0.13.0__tar.gz → 0.14.0__tar.gz

{coeftable-0.13.0 → coeftable-0.14.0}/.github/workflows/ci.yml

@@ -30,3 +30,15 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - run: uv run --with nox nox -s "tests-${{ matrix.python-version }}"
+
+  browser:
+    runs-on: ubuntu-latest
+    needs: prek
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+      - run: uv sync --extra dev --extra browser
+      - run: uv run python -m playwright install --with-deps chromium
+      - run: uv run pytest --no-cov tests/test_interactive.py

{coeftable-0.13.0 → coeftable-0.14.0}/CHANGELOG.md

@@ -1,3 +1,35 @@
+<a id="v0.13.1"></a>
+# [v0.13.1](https://github.com/kylejcaron/coeftable/releases/tag/v0.13.1) - 2026-09-30
+
+<!-- Release notes generated using configuration in .github/release.yml at v0.13.1 -->
+
+## What's Changed
+### Maintenance
+* Update changelog for v0.13.0 by [@github-actions](https://github.com/github-actions)[bot] in [#63](https://github.com/kylejcaron/coeftable/pull/63)
+* Neutralize unsafe Markdown targets in table labels by [@kylejcaron](https://github.com/kylejcaron) in [#64](https://github.com/kylejcaron/coeftable/pull/64)
+
+
+**Full Changelog**: https://github.com/kylejcaron/coeftable/compare/v0.13.0...v0.13.1
+
+[Changes][v0.13.1]
+
+
+<a id="v0.13.0"></a>
+# [v0.13.0](https://github.com/kylejcaron/coeftable/releases/tag/v0.13.0) - 2026-09-28
+
+<!-- Release notes generated using configuration in .github/release.yml at v0.13.0 -->
+
+## What's Changed
+### Maintenance
+* Update changelog for v0.12.1 by [@github-actions](https://github.com/github-actions)[bot] in [#61](https://github.com/kylejcaron/coeftable/pull/61)
+* Add visible y-axes to sparkline surfaces by [@kylejcaron](https://github.com/kylejcaron) in [#62](https://github.com/kylejcaron/coeftable/pull/62)
+
+
+**Full Changelog**: https://github.com/kylejcaron/coeftable/compare/v0.12.1...v0.13.0
+
+[Changes][v0.13.0]
+
+
 <a id="v0.12.1"></a>
 # [v0.12.1](https://github.com/kylejcaron/coeftable/releases/tag/v0.12.1) - 2026-09-24
 
@@ -266,6 +298,8 @@
 [Changes][v0.1.0]
 
 
+[v0.13.1]: https://github.com/kylejcaron/coeftable/compare/v0.13.0...v0.13.1
+[v0.13.0]: https://github.com/kylejcaron/coeftable/compare/v0.12.1...v0.13.0
 [v0.12.1]: https://github.com/kylejcaron/coeftable/compare/v0.12.0...v0.12.1
 [v0.12.0]: https://github.com/kylejcaron/coeftable/compare/v0.11.0...v0.12.0
 [v0.11.0]: https://github.com/kylejcaron/coeftable/compare/v0.10.0...v0.11.0

coeftable-0.14.0/Makefile

@@ -0,0 +1,25 @@
+.PHONY: setup tests tests-all tests-browser lint typecheck prek
+
+setup:
+	uv sync --extra dev
+	uv run prek install
+
+tests:
+	uv run pytest
+
+tests-all:
+	uv run nox -s tests
+
+tests-browser:
+	uv sync --extra dev --extra browser
+	uv run python -m playwright install chromium
+	uv run pytest --no-cov tests/test_interactive.py
+
+lint:
+	uv run nox -s lint
+
+typecheck:
+	uv run nox -s typecheck
+
+prek:
+	SKIP=no-commit-to-branch uv run prek run --all-files

{coeftable-0.13.0 → coeftable-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coeftable
-Version: 0.13.0
+Version: 0.14.0
 Summary: Publication-quality summary tables for estimates with uncertainty.
 Project-URL: Homepage, https://github.com/kylejcaron/coeftable
 Project-URL: Repository, https://github.com/kylejcaron/coeftable
@@ -39,7 +39,10 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.12
 Requires-Dist: great-tables>=0.22
+Requires-Dist: multimark>=0.1.3
 Requires-Dist: narwhals>=2.24
+Provides-Extra: browser
+Requires-Dist: playwright>=1.50; extra == 'browser'
 Provides-Extra: dev
 Requires-Dist: nox>=2025.5; extra == 'dev'
 Requires-Dist: pandas>=2.2; extra == 'dev'
@@ -116,6 +119,16 @@ a `parameter` column.
 - `split_columns` — an optional column whose values produce repeated column
   groups side by side, useful for comparing methods.
 
+Row and nested labels support safe Markdown, including `{{m s^-1}}` units
+notation. Raw HTML in labels is displayed as text; dangerous link targets are
+neutralized. Group and split-column labels are literal text. These rules apply
+to standalone `as_raw_html()` and the table's initial `.gt()` HTML rendering;
+subsequent formatting added through `.gt()` follows Great Tables' own rules.
+LaTeX export also escapes group and split-column labels, including numeric and
+date-valued groups.
+Native `.gt()` spanner styles and footnotes select split headings using their
+original string IDs.
+
 **Series columns bend this rule.** A point estimate is one number (plus
 bounds), so a triple of scalar columns holds it. A `.sparkline(...)` series
 is N points, not one -- most naturally via the companion-frame door, a
@@ -541,6 +554,118 @@ shaded intervals via each function's `annotations=` parameter. Because a
 standalone plot and a table column share one `Theme`, a report that mixes
 both stays visually consistent.
 
+## Inspect plot values
+
+Pass `tooltip=ct.Tooltip()` to opt a plot into value inspection, then activate
+the composed HTML with `ct.interactive_html`. Existing renderers remain passive:
+`as_raw_html()`, `_repr_html_()`, `.gt()`, and standalone SVG strings do not
+execute scripts themselves.
+
+```python
+from pathlib import Path
+
+import coeftable as ct
+import polars as pl
+from coeftable.cards import Card, Trend
+from coeftable.plots import sparkline_bar
+
+history = pl.DataFrame({
+    "metric": ["Revenue", "Revenue", "Revenue"],
+    "day": [0, 2, 4],
+    "estimate": [1.0, None, 5.0],
+    "n": [10, 20, 30],
+})
+table = ct.CoefTable(pl.DataFrame({"metric": ["Revenue"]}), rows="metric").sparkline(
+    "Trend", value="estimate", x="day", data=history, ylim=(0, 3),
+    tooltip=ct.Tooltip(
+        fields=[ct.TooltipField("n", label="Sample size")],
+        value_label="Revenue", x_label="Day",
+    ),
+)
+
+# Direct plots and card regions receive aligned arrays, not dataframe fields.
+extras = [ct.TooltipValues("Sample size", [10, 20, 30])]
+line = sparkline_bar(
+    [0, 2, 4], [1, None, 5], [None] * 3, [None] * 3,
+    x_domain=(0, 4), domain=(0, 3), ref=None, color="#4C72B0", fmt=ct.Number(),
+    tooltip=ct.Tooltip(value_label="Revenue", x_label="Day"), tooltip_values=extras,
+)
+card = Card("Revenue", content=[
+    Trend(
+        x=[0, 2, 4], y=[1, None, 5], x_domain=(0, 4), domain=(0, 3),
+        tooltip=ct.Tooltip(value_label="Revenue", x_label="Day"), tooltip_values=extras,
+    ),
+])
+fragment = table.as_raw_html() + line + card.as_raw_html()
+document = ct.interactive_html(fragment, full_document=True)
+Path("inspection.html").write_text(document, encoding="utf-8")
+```
+
+Primary values are bold; the x coordinate is context, not the headline.
+`Tooltip(value_label="Sales", x_label="Date")` names both values explicitly.
+Labels default to `Value` and `x`; forest inspection uses only `value_label`.
+
+`TooltipField` binds **main-frame scalar columns for forest plots**, main-frame
+list columns for list-mode sparklines, and **companion-frame scalar columns**
+when `data=` is supplied. Companion sorting applies the same permutation to
+the extra measures. List-mode drawing retains its input order. Extras never
+affect plot domains or make an otherwise blank table cell drawable.
+
+`forest_bar` and card `Interval` accept `tooltip_values` of length one per
+field; `sparkline_bar` and `Trend` require each field to match the point arrays.
+For `sparkline_multi`, `tooltip_values` is an outer sequence aligned to the
+input traces: include an empty entry for any trace without extras. An empty
+outer sequence means no extras on any trace. `Trace` remains unchanged.
+Direct plots/regions reject unresolved `Tooltip.fields`; extra values without
+an enabled tooltip raise `SpecError`.
+
+**Selection and formatting.** Move anywhere horizontally inside the plot's
+data area, or drag, to select the nearest observed x. Midpoint ties choose
+the smaller x. Missing y displays “Missing”; an arm without that exact x
+displays “No observation”. Duplicate observations at one x remain separate.
+No interpolation or substitution from another date. Off-scale values keep
+their actual values and an above/below (forest: left/right) indication.
+Forest plots expose their one interval anywhere in the data area.
+
+`Tooltip(fmt=..., x_fmt=...)` overrides observation value/interval and x
+formatters independently. Otherwise the primary plot/region formatter is used
+for values (`Number()` for direct `forest_bar`). Numeric x defaults to
+`Number()`. Temporal table coordinates and `Trend(temporal=True)` use full
+`YYYY-MM-DD HH:MM:SS` coordinate dates, not contextual axis ticks such as “14”.
+These dates follow the existing epoch-coordinate convention formatted in UTC;
+this does not reinterpret the source timezone. Direct numeric emitters need
+an explicit `x_fmt` for date coordinates. Each extra field has its own `fmt`;
+null/NaN extras display “—” without invoking it. Formatters must return strings.
+
+**Input.** Focus an enabled plot, then use Left/Right, Home/End, or Escape.
+There is one tab stop per plot, not per point. Touch/pen release leaves the
+inspector available to read until dismissal or another selection; cancellation
+clears it and vertical page scrolling remains available. Long inspectors wrap
+and scroll within the viewport: PageUp/PageDown work while the plot is focused;
+Tab can enter the scroll region. Escape or an outside tap dismisses.
+
+| Delivery path | Behavior |
+|---|---|
+| Saved full document | Interactive offline when scripts are permitted; no kernel/server/CDN needed. |
+| Parser-inserted fragment | `interactive_html(fragment)` activates within its own wrapper. |
+| Dynamic `innerHTML` insertion | Scripts are inert. Load the packaged `coeftable/_tooltip_runtime.js` yourself and call `window.coeftableTooltips.mount(root)`; the returned function disposes the mount. Repeated mounts of the same root are idempotent. |
+| Live marimo | `mo.iframe(ct.interactive_html(fragment, full_document=True), height="500px")`; `mo.Html` is a passive path. |
+| SVG as an image, PNG/PDF, scripts blocked/disabled | Existing static appearance, without inspection. |
+
+Compose table, standalone and card HTML first, then activate once.
+`interactive_html` accepts **trusted fragments only**, not complete
+`html`/`head`/`body` documents, and is not an HTML sanitizer. If using
+`table.gt().as_raw_html(...)`, request a fragment rather than a document.
+Restrictive CSP policies may block the inline bootstrap/styles; asset/nonces
+integration, automatic notebook activation, Python callbacks and untested
+notebook/export hosts are not promised.
+
+**Data disclosure:** all configured observation values and extra fields are
+embedded in browser-readable output, including missing/off-scale observations.
+Plain-text escaping prevents formatter output from becoming markup; it does
+not make sensitive data private. Include only fields intended for recipients.
+
+
 ## Metric cards
 
 `coeftable.cards` composes the standalone plots into measured, foldable
@@ -1121,3 +1246,12 @@ the Sparkline y-domain and clip or omit distant marks. Annotations supplement
 rather than replace
 `ref`: `ref` remains the built-in semantic reference that controls colors and
 its optional dashed line.
+
+## Development checks
+
+`make setup` installs development dependencies without enabling optional browser
+tests. `make tests` runs the installed test selection. For plot interaction
+checks, `make tests-browser` installs the optional Playwright package and
+Chromium, then runs `tests/test_interactive.py`. Without the browser extra,
+only browser-dependent cases skip; HTML assembly checks still run. An installed
+Playwright package without Chromium is an error, not a passing skip.

{coeftable-0.13.0 → coeftable-0.14.0}/README.md

@@ -62,6 +62,16 @@ a `parameter` column.
 - `split_columns` — an optional column whose values produce repeated column
   groups side by side, useful for comparing methods.
 
+Row and nested labels support safe Markdown, including `{{m s^-1}}` units
+notation. Raw HTML in labels is displayed as text; dangerous link targets are
+neutralized. Group and split-column labels are literal text. These rules apply
+to standalone `as_raw_html()` and the table's initial `.gt()` HTML rendering;
+subsequent formatting added through `.gt()` follows Great Tables' own rules.
+LaTeX export also escapes group and split-column labels, including numeric and
+date-valued groups.
+Native `.gt()` spanner styles and footnotes select split headings using their
+original string IDs.
+
 **Series columns bend this rule.** A point estimate is one number (plus
 bounds), so a triple of scalar columns holds it. A `.sparkline(...)` series
 is N points, not one -- most naturally via the companion-frame door, a
@@ -487,6 +497,118 @@ shaded intervals via each function's `annotations=` parameter. Because a
 standalone plot and a table column share one `Theme`, a report that mixes
 both stays visually consistent.
 
+## Inspect plot values
+
+Pass `tooltip=ct.Tooltip()` to opt a plot into value inspection, then activate
+the composed HTML with `ct.interactive_html`. Existing renderers remain passive:
+`as_raw_html()`, `_repr_html_()`, `.gt()`, and standalone SVG strings do not
+execute scripts themselves.
+
+```python
+from pathlib import Path
+
+import coeftable as ct
+import polars as pl
+from coeftable.cards import Card, Trend
+from coeftable.plots import sparkline_bar
+
+history = pl.DataFrame({
+    "metric": ["Revenue", "Revenue", "Revenue"],
+    "day": [0, 2, 4],
+    "estimate": [1.0, None, 5.0],
+    "n": [10, 20, 30],
+})
+table = ct.CoefTable(pl.DataFrame({"metric": ["Revenue"]}), rows="metric").sparkline(
+    "Trend", value="estimate", x="day", data=history, ylim=(0, 3),
+    tooltip=ct.Tooltip(
+        fields=[ct.TooltipField("n", label="Sample size")],
+        value_label="Revenue", x_label="Day",
+    ),
+)
+
+# Direct plots and card regions receive aligned arrays, not dataframe fields.
+extras = [ct.TooltipValues("Sample size", [10, 20, 30])]
+line = sparkline_bar(
+    [0, 2, 4], [1, None, 5], [None] * 3, [None] * 3,
+    x_domain=(0, 4), domain=(0, 3), ref=None, color="#4C72B0", fmt=ct.Number(),
+    tooltip=ct.Tooltip(value_label="Revenue", x_label="Day"), tooltip_values=extras,
+)
+card = Card("Revenue", content=[
+    Trend(
+        x=[0, 2, 4], y=[1, None, 5], x_domain=(0, 4), domain=(0, 3),
+        tooltip=ct.Tooltip(value_label="Revenue", x_label="Day"), tooltip_values=extras,
+    ),
+])
+fragment = table.as_raw_html() + line + card.as_raw_html()
+document = ct.interactive_html(fragment, full_document=True)
+Path("inspection.html").write_text(document, encoding="utf-8")
+```
+
+Primary values are bold; the x coordinate is context, not the headline.
+`Tooltip(value_label="Sales", x_label="Date")` names both values explicitly.
+Labels default to `Value` and `x`; forest inspection uses only `value_label`.
+
+`TooltipField` binds **main-frame scalar columns for forest plots**, main-frame
+list columns for list-mode sparklines, and **companion-frame scalar columns**
+when `data=` is supplied. Companion sorting applies the same permutation to
+the extra measures. List-mode drawing retains its input order. Extras never
+affect plot domains or make an otherwise blank table cell drawable.
+
+`forest_bar` and card `Interval` accept `tooltip_values` of length one per
+field; `sparkline_bar` and `Trend` require each field to match the point arrays.
+For `sparkline_multi`, `tooltip_values` is an outer sequence aligned to the
+input traces: include an empty entry for any trace without extras. An empty
+outer sequence means no extras on any trace. `Trace` remains unchanged.
+Direct plots/regions reject unresolved `Tooltip.fields`; extra values without
+an enabled tooltip raise `SpecError`.
+
+**Selection and formatting.** Move anywhere horizontally inside the plot's
+data area, or drag, to select the nearest observed x. Midpoint ties choose
+the smaller x. Missing y displays “Missing”; an arm without that exact x
+displays “No observation”. Duplicate observations at one x remain separate.
+No interpolation or substitution from another date. Off-scale values keep
+their actual values and an above/below (forest: left/right) indication.
+Forest plots expose their one interval anywhere in the data area.
+
+`Tooltip(fmt=..., x_fmt=...)` overrides observation value/interval and x
+formatters independently. Otherwise the primary plot/region formatter is used
+for values (`Number()` for direct `forest_bar`). Numeric x defaults to
+`Number()`. Temporal table coordinates and `Trend(temporal=True)` use full
+`YYYY-MM-DD HH:MM:SS` coordinate dates, not contextual axis ticks such as “14”.
+These dates follow the existing epoch-coordinate convention formatted in UTC;
+this does not reinterpret the source timezone. Direct numeric emitters need
+an explicit `x_fmt` for date coordinates. Each extra field has its own `fmt`;
+null/NaN extras display “—” without invoking it. Formatters must return strings.
+
+**Input.** Focus an enabled plot, then use Left/Right, Home/End, or Escape.
+There is one tab stop per plot, not per point. Touch/pen release leaves the
+inspector available to read until dismissal or another selection; cancellation
+clears it and vertical page scrolling remains available. Long inspectors wrap
+and scroll within the viewport: PageUp/PageDown work while the plot is focused;
+Tab can enter the scroll region. Escape or an outside tap dismisses.
+
+| Delivery path | Behavior |
+|---|---|
+| Saved full document | Interactive offline when scripts are permitted; no kernel/server/CDN needed. |
+| Parser-inserted fragment | `interactive_html(fragment)` activates within its own wrapper. |
+| Dynamic `innerHTML` insertion | Scripts are inert. Load the packaged `coeftable/_tooltip_runtime.js` yourself and call `window.coeftableTooltips.mount(root)`; the returned function disposes the mount. Repeated mounts of the same root are idempotent. |
+| Live marimo | `mo.iframe(ct.interactive_html(fragment, full_document=True), height="500px")`; `mo.Html` is a passive path. |
+| SVG as an image, PNG/PDF, scripts blocked/disabled | Existing static appearance, without inspection. |
+
+Compose table, standalone and card HTML first, then activate once.
+`interactive_html` accepts **trusted fragments only**, not complete
+`html`/`head`/`body` documents, and is not an HTML sanitizer. If using
+`table.gt().as_raw_html(...)`, request a fragment rather than a document.
+Restrictive CSP policies may block the inline bootstrap/styles; asset/nonces
+integration, automatic notebook activation, Python callbacks and untested
+notebook/export hosts are not promised.
+
+**Data disclosure:** all configured observation values and extra fields are
+embedded in browser-readable output, including missing/off-scale observations.
+Plain-text escaping prevents formatter output from becoming markup; it does
+not make sensitive data private. Include only fields intended for recipients.
+
+
 ## Metric cards
 
 `coeftable.cards` composes the standalone plots into measured, foldable
@@ -1067,3 +1189,12 @@ the Sparkline y-domain and clip or omit distant marks. Annotations supplement
 rather than replace
 `ref`: `ref` remains the built-in semantic reference that controls colors and
 its optional dashed line.
+
+## Development checks
+
+`make setup` installs development dependencies without enabling optional browser
+tests. `make tests` runs the installed test selection. For plot interaction
+checks, `make tests-browser` installs the optional Playwright package and
+Chromium, then runs `tests/test_interactive.py`. Without the browser extra,
+only browser-dependent cases skip; HTML assembly checks still run. An installed
+Playwright package without Chromium is an error, not a passing skip.

{coeftable-0.13.0 → coeftable-0.14.0}/pyproject.toml

@@ -23,6 +23,7 @@ classifiers = [
 ]
 dependencies = [
     "great-tables>=0.22",
+    "multimark>=0.1.3",
     "narwhals>=2.24",
 ]
 
@@ -38,6 +39,7 @@ dev = [
     "nox>=2025.5",
     "pyarrow>=25.0.0",
 ]
+browser = ["playwright>=1.50"]
 
 [project.urls]
 Homepage = "https://github.com/kylejcaron/coeftable"
@@ -95,6 +97,7 @@ convention = "numpy"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+markers = ["integration: exercises rendering, subprocess, filesystem, or browser boundaries"]
 addopts = [
     "-v",
     "--strict-markers",

{coeftable-0.13.0 → coeftable-0.14.0}/src/coeftable/__init__.py

@@ -13,8 +13,10 @@ from coeftable.format import (
     Percent,
     TimeFormat,
 )
+from coeftable.interactive import interactive_html
 from coeftable.spec import CardColumn, CoefTable, Estimate, Forest, Passthrough, Sparkline
 from coeftable.theme import Theme, role_for
+from coeftable.tooltips import Tooltip, TooltipField, TooltipValues
 
 try:
     __version__ = version("coeftable")
@@ -40,7 +42,11 @@ __all__ = [
     "SpecError",
     "Theme",
     "TimeFormat",
+    "Tooltip",
+    "TooltipField",
+    "TooltipValues",
     "__version__",
+    "interactive_html",
     "role_for",
 ]