coeftable 0.6.0__tar.gz → 0.7.0__tar.gz

{coeftable-0.6.0 → coeftable-0.7.0}/.github/workflows/ci.yml

@@ -4,7 +4,6 @@ on:
   push:
     branches: [main]
   pull_request:
-    branches: [main]
 
 jobs:
   prek:

coeftable-0.7.0/AGENTS.md

@@ -0,0 +1,8 @@
+# Agent guidelines
+
+## Changelog
+
+Never edit `CHANGELOG.md`. It is generated by release automation:
+`.github/workflows/post-release.yml` runs the `changelog-from-release` action
+against it, from release notes built out of merged PR titles and categorized by
+`.github/release.yml`. Describe changes in the PR description instead.

{coeftable-0.6.0 → coeftable-0.7.0}/CHANGELOG.md

@@ -1,3 +1,26 @@
+<a id="v0.6.0"></a>
+# [v0.6.0](https://github.com/kylejcaron/coeftable/releases/tag/v0.6.0) - 2026-08-27
+
+<!-- Release notes generated using configuration in .github/release.yml at v0.6.0 -->
+
+## What's Changed
+### New Features
+* Add coeftable.plots public facade for SVG plot primitives by [@kylejcaron](https://github.com/kylejcaron) in [#35](https://github.com/kylejcaron/coeftable/pull/35)
+* Add typed card adornment vocabulary and HTML rendering by [@kylejcaron](https://github.com/kylejcaron) in [#36](https://github.com/kylejcaron/coeftable/pull/36)
+* Add exact card measurement engine (chrome geometry) by [@kylejcaron](https://github.com/kylejcaron) in [#37](https://github.com/kylejcaron/coeftable/pull/37)
+* Add trend, interval, metric, diagnostics and event card regions by [@kylejcaron](https://github.com/kylejcaron) in [#38](https://github.com/kylejcaron/coeftable/pull/38)
+* Add public Card and CardGrid entry points by [@kylejcaron](https://github.com/kylejcaron) in [#39](https://github.com/kylejcaron/coeftable/pull/39)
+* Add the panel composition layer by [@kylejcaron](https://github.com/kylejcaron) in [#40](https://github.com/kylejcaron/coeftable/pull/40)
+* Add the metric tree / driver-tree graph builder by [@kylejcaron](https://github.com/kylejcaron) in [#41](https://github.com/kylejcaron/coeftable/pull/41)
+### Maintenance
+* Update changelog for v0.5.0 by [@github-actions](https://github.com/github-actions)[bot] in [#34](https://github.com/kylejcaron/coeftable/pull/34)
+
+
+**Full Changelog**: https://github.com/kylejcaron/coeftable/compare/v0.5.0...v0.6.0
+
+[Changes][v0.6.0]
+
+
 <a id="v0.5.0"></a>
 # [v0.5.0](https://github.com/kylejcaron/coeftable/releases/tag/v0.5.0) - 2026-08-19
 
@@ -124,6 +147,7 @@
 [Changes][v0.1.0]
 
 
+[v0.6.0]: https://github.com/kylejcaron/coeftable/compare/v0.5.0...v0.6.0
 [v0.5.0]: https://github.com/kylejcaron/coeftable/compare/v0.4.0...v0.5.0
 [v0.4.0]: https://github.com/kylejcaron/coeftable/compare/v0.3.1...v0.4.0
 [v0.3.1]: https://github.com/kylejcaron/coeftable/compare/v0.3.0...v0.3.1

{coeftable-0.6.0 → coeftable-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coeftable
-Version: 0.6.0
+Version: 0.7.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
@@ -640,6 +640,126 @@ CSS and no JavaScript.
 A `MetricTree` left as the last notebook expression renders itself via
 `_repr_html_`; `with_theme()` follows the same conventions as cards.
 
+## Driver-tree reports (experimental)
+
+`coeftable.graph.DriverTree` is the composition root over the metric-tree
+layer: give it level series and a decomposition per parent, and it builds the
+cards, wires, and layout itself, plus three opt-in honesty checks a hand-built
+`MetricTree` graph would otherwise have to redo per node. The API is
+experimental and may change; it is deliberately not exported from the
+top-level `coeftable` namespace yet.
+
+```python
+import coeftable as ct
+from coeftable.graph import DriverTree
+from coeftable.graph.breakout import Breakout
+from coeftable.graph.timeline import TimelineEvent
+
+x = (0.0, 1.0, 2.0, 3.0)
+series = {
+    "revenue": (1000.0, 1071.0, 1144.0, 1219.0),
+    "users": (100.0, 105.0, 110.0, 115.0),
+    "aov": (10.0, 10.2, 10.4, 10.6),
+    "us": (600.0, 640.0, 680.0, 720.0),
+    "eu": (400.0, 431.0, 464.0, 499.0),
+}
+titles = {"revenue": "Revenue", "users": "Users", "aov": "AOV", "us": "US", "eu": "EU"}
+breakouts = {
+    "revenue": (
+        Breakout(key="drivers", label="by drivers", op="x", children=("users", "aov")),
+        Breakout(key="region", label="by region", op="+", children=("us", "eu")),
+    )
+}
+events = (TimelineEvent(at=1.0, label="Launch", color="#4C72B0", affects=("revenue", "users")),)
+
+report = DriverTree(
+    series,
+    titles,
+    breakouts,
+    ct.Percent(decimals=1),
+    x,
+    events=events,
+    level_fmt=ct.Number(decimals=1),
+)
+html = report.as_raw_html()
+```
+
+Every node id in `series` and `titles` is derived from `breakouts`: each key
+is a parent, and each `Breakout` names one decomposition of it (an `op="x"`
+product or an `op="+"` sum) plus the child node ids it contributes. A parent
+with two or more breakouts (like `revenue` above) renders a native
+`<select>` that swaps its children's whole subtree in place — no JavaScript,
+because the alternatives share one slotted position and pure CSS shows
+exactly one of them at a time.
+
+Each decomposition is checked against its own arithmetic: a parent that
+should equal the sum or product of its children but falls short gets an
+injected `"Unattributed"` residual card (additive shortfalls) or a reported
+gap badge (multiplicative shortfalls, which have no subtraction fix), and a
+decomposition explaining under 80% of its parent refuses to build rather than
+render a misleading tree. Every wire's label role comes from its own child's
+noise-aware confidence interval, so a wobbly delta renders muted with a
+`· ns` marker instead of a confident color. Anti-correlated siblings (movers
+that trade off against each other week to week) surface a callout hosted on
+one of the participating children, so it stays visible only alongside that
+alternative rather than the parent, which stays visible under every switch.
+The root card renders no text of its own; pass `caption=` to add one. It
+wraps to fit the card using an estimated character width, growing across
+as many lines as that estimate needs. Runs of whitespace collapse to a
+single space and line breaks are not preserved, and unusually wide text
+can still be clipped on a line, since the wrap is an estimate rather than
+a font measurement. A literal `{weeks}` placeholder is substituted for the
+observed period count, and `caption` defaults to `None`, so nothing
+renders unless you ask for it.
+If you want a note that edge labels are accounting, not causal
+claims, that wording is yours to choose — for example
+`caption="Edge labels are an accounting of the realized {weeks}-week
+change, not causal impact."` `events` fan out to every card named in their
+`affects` tuple, both as sparkline markers and as captions, and the
+report's header is a timeline strip indexing them across the whole canvas.
+That strip carries no heading of its own — pass `strip_title=` if you want
+one, since only you know whether your events are deploys, holidays, or
+experiments. With neither events nor a `strip_title` there is nothing to
+index and no heading to show, so the strip is omitted rather than reserving
+space for a bare axis; supplying either one brings it back.
+
+**Switchers can nest.** Every level of the tree may carry its own switcher at
+the same time — revenue by drivers or region, and within drivers, active users
+by funnel or country, and within that, sessions by platform or channel.
+Switching an outer choice takes away the whole branch beneath it, including any
+nested switcher and its alternatives; switching back restores it with the inner
+selection intact, because a native `<select>` keeps its value while hidden.
+
+**Limitations.** All alternatives of one switcher must have the same number of
+children, since they share the same positions.
+
+And every card must keep a visible parent under every combination of choices. A
+card that disappears together with its own alternative is fine — that is the
+point of a switcher. What is refused is a card whose visibility depends on
+several switchers that do not subsume one another, so that some combination of
+selections leaves it on the page with every route to it closed.
+
+Nesting satisfies this on its own: an outer choice that removes a branch is
+decided by the outer rule alone, and everything below goes with it. Being
+reachable through more than one switcher is not by itself a problem either — if
+every option of each switcher reaches the card, or if any route to it is
+unconditional, it always keeps a parent and the tree is accepted.
+
+One shape is refused: a card where *every* route can be independently closed and
+none survives unconditionally. The clearest example is a card reachable through a
+nested branch and also through a different alternative of the switcher above it.
+Keep the outer branch that preserves the nested switcher, then pick an inner
+option that does not reach the card, and both of its routes close at once. Since
+each switcher's rules are emitted independently, no single one can see that. Such
+a tree is rejected at construction with a `SpecError` naming the card and every
+switcher implicated in it.
+
+`DriverTree` returns a `GraphReport`: the underlying `Graph`, and above it a
+measured, exact-width timeline strip whenever events or a `strip_title` call
+for one. `report.measure()`,
+`report.as_raw_html()`, and its `_repr_html_` notebook display all work the
+same way they do for a plain `Graph`.
+
 ## Plot annotations
 
 `ct.Rule` draws a line and `ct.Band` shades an interval in a forest plot or

{coeftable-0.6.0 → coeftable-0.7.0}/README.md

@@ -586,6 +586,126 @@ CSS and no JavaScript.
 A `MetricTree` left as the last notebook expression renders itself via
 `_repr_html_`; `with_theme()` follows the same conventions as cards.
 
+## Driver-tree reports (experimental)
+
+`coeftable.graph.DriverTree` is the composition root over the metric-tree
+layer: give it level series and a decomposition per parent, and it builds the
+cards, wires, and layout itself, plus three opt-in honesty checks a hand-built
+`MetricTree` graph would otherwise have to redo per node. The API is
+experimental and may change; it is deliberately not exported from the
+top-level `coeftable` namespace yet.
+
+```python
+import coeftable as ct
+from coeftable.graph import DriverTree
+from coeftable.graph.breakout import Breakout
+from coeftable.graph.timeline import TimelineEvent
+
+x = (0.0, 1.0, 2.0, 3.0)
+series = {
+    "revenue": (1000.0, 1071.0, 1144.0, 1219.0),
+    "users": (100.0, 105.0, 110.0, 115.0),
+    "aov": (10.0, 10.2, 10.4, 10.6),
+    "us": (600.0, 640.0, 680.0, 720.0),
+    "eu": (400.0, 431.0, 464.0, 499.0),
+}
+titles = {"revenue": "Revenue", "users": "Users", "aov": "AOV", "us": "US", "eu": "EU"}
+breakouts = {
+    "revenue": (
+        Breakout(key="drivers", label="by drivers", op="x", children=("users", "aov")),
+        Breakout(key="region", label="by region", op="+", children=("us", "eu")),
+    )
+}
+events = (TimelineEvent(at=1.0, label="Launch", color="#4C72B0", affects=("revenue", "users")),)
+
+report = DriverTree(
+    series,
+    titles,
+    breakouts,
+    ct.Percent(decimals=1),
+    x,
+    events=events,
+    level_fmt=ct.Number(decimals=1),
+)
+html = report.as_raw_html()
+```
+
+Every node id in `series` and `titles` is derived from `breakouts`: each key
+is a parent, and each `Breakout` names one decomposition of it (an `op="x"`
+product or an `op="+"` sum) plus the child node ids it contributes. A parent
+with two or more breakouts (like `revenue` above) renders a native
+`<select>` that swaps its children's whole subtree in place — no JavaScript,
+because the alternatives share one slotted position and pure CSS shows
+exactly one of them at a time.
+
+Each decomposition is checked against its own arithmetic: a parent that
+should equal the sum or product of its children but falls short gets an
+injected `"Unattributed"` residual card (additive shortfalls) or a reported
+gap badge (multiplicative shortfalls, which have no subtraction fix), and a
+decomposition explaining under 80% of its parent refuses to build rather than
+render a misleading tree. Every wire's label role comes from its own child's
+noise-aware confidence interval, so a wobbly delta renders muted with a
+`· ns` marker instead of a confident color. Anti-correlated siblings (movers
+that trade off against each other week to week) surface a callout hosted on
+one of the participating children, so it stays visible only alongside that
+alternative rather than the parent, which stays visible under every switch.
+The root card renders no text of its own; pass `caption=` to add one. It
+wraps to fit the card using an estimated character width, growing across
+as many lines as that estimate needs. Runs of whitespace collapse to a
+single space and line breaks are not preserved, and unusually wide text
+can still be clipped on a line, since the wrap is an estimate rather than
+a font measurement. A literal `{weeks}` placeholder is substituted for the
+observed period count, and `caption` defaults to `None`, so nothing
+renders unless you ask for it.
+If you want a note that edge labels are accounting, not causal
+claims, that wording is yours to choose — for example
+`caption="Edge labels are an accounting of the realized {weeks}-week
+change, not causal impact."` `events` fan out to every card named in their
+`affects` tuple, both as sparkline markers and as captions, and the
+report's header is a timeline strip indexing them across the whole canvas.
+That strip carries no heading of its own — pass `strip_title=` if you want
+one, since only you know whether your events are deploys, holidays, or
+experiments. With neither events nor a `strip_title` there is nothing to
+index and no heading to show, so the strip is omitted rather than reserving
+space for a bare axis; supplying either one brings it back.
+
+**Switchers can nest.** Every level of the tree may carry its own switcher at
+the same time — revenue by drivers or region, and within drivers, active users
+by funnel or country, and within that, sessions by platform or channel.
+Switching an outer choice takes away the whole branch beneath it, including any
+nested switcher and its alternatives; switching back restores it with the inner
+selection intact, because a native `<select>` keeps its value while hidden.
+
+**Limitations.** All alternatives of one switcher must have the same number of
+children, since they share the same positions.
+
+And every card must keep a visible parent under every combination of choices. A
+card that disappears together with its own alternative is fine — that is the
+point of a switcher. What is refused is a card whose visibility depends on
+several switchers that do not subsume one another, so that some combination of
+selections leaves it on the page with every route to it closed.
+
+Nesting satisfies this on its own: an outer choice that removes a branch is
+decided by the outer rule alone, and everything below goes with it. Being
+reachable through more than one switcher is not by itself a problem either — if
+every option of each switcher reaches the card, or if any route to it is
+unconditional, it always keeps a parent and the tree is accepted.
+
+One shape is refused: a card where *every* route can be independently closed and
+none survives unconditionally. The clearest example is a card reachable through a
+nested branch and also through a different alternative of the switcher above it.
+Keep the outer branch that preserves the nested switcher, then pick an inner
+option that does not reach the card, and both of its routes close at once. Since
+each switcher's rules are emitted independently, no single one can see that. Such
+a tree is rejected at construction with a `SpecError` naming the card and every
+switcher implicated in it.
+
+`DriverTree` returns a `GraphReport`: the underlying `Graph`, and above it a
+measured, exact-width timeline strip whenever events or a `strip_title` call
+for one. `report.measure()`,
+`report.as_raw_html()`, and its `_repr_html_` notebook display all work the
+same way they do for a plain `Graph`.
+
 ## Plot annotations
 
 `ct.Rule` draws a line and `ct.Band` shades an interval in a forest plot or

{coeftable-0.6.0 → coeftable-0.7.0}/src/coeftable/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.6.0'
-__version_tuple__ = version_tuple = (0, 6, 0)
+__version__ = version = '0.7.0'
+__version_tuple__ = version_tuple = (0, 7, 0)
 
 __commit_id__ = commit_id = None

{coeftable-0.6.0 → coeftable-0.7.0}/src/coeftable/cards/__init__.py

@@ -7,6 +7,7 @@ resolve into; `render_adornment` is its only serializer.
 from coeftable.cards.adornments import (
     Adornment,
     Badge,
+    Callout,
     CaptionRow,
     InlineSvg,
     KeyValuePopover,
@@ -38,6 +39,7 @@ __all__ = [
     "Adornment",
     "Anchor",
     "Badge",
+    "Callout",
     "CaptionRow",
     "Card",
     "CardChrome",

{coeftable-0.6.0 → coeftable-0.7.0}/src/coeftable/cards/adornments.py

@@ -1,6 +1,6 @@
 """Typed card-content vocabulary: the closed set card regions resolve into.
 
-The renderer (`coeftable.cards.fragments`) knows exactly these nine types
+The renderer (`coeftable.cards.fragments`) knows exactly these types
 and never branches on report type. Construction is the runtime contract
 boundary for intrinsic field validity: every invalid value raises `SpecError`
 here. Layout-dependent fit, including overflow and minimum widths, raises
@@ -204,6 +204,23 @@ class Badge:
         _require_member(self.role, _ROLES, name="Badge.role")
 
 
+@dataclass(frozen=True, slots=True)
+class Callout:
+    """Role-coloured prose that wraps: a warning or caveat with severity."""
+
+    text: str
+    role: Role = "neutral"
+    max_lines: int = 3
+
+    def __post_init__(self) -> None:
+        """Validate fields."""
+        _require_str(self.text, name="Callout.text")
+        _require_member(self.role, _ROLES, name="Callout.role")
+        _require_int(self.max_lines, name="Callout.max_lines")
+        if self.max_lines < 1:
+            raise SpecError("Callout.max_lines must be >= 1")
+
+
 @dataclass(frozen=True, slots=True)
 class CaptionRow:
     """A caption line with an optional colour-matched line marker."""
@@ -248,6 +265,7 @@ type Adornment = (
     | KeyValuePopover
     | SelectControl
     | Badge
+    | Callout
     | CaptionRow
     | Legend
     | RuleStrip

{coeftable-0.6.0 → coeftable-0.7.0}/src/coeftable/cards/chrome.py

@@ -41,6 +41,8 @@ class CardChrome:
     swatch_gap: int = 4
     chip_gap: int = 10
     value_detail_gap: int = 4
+    callout_accent: int = 3
+    callout_inset: int = 6
 
     def __post_init__(self) -> None:
         """Validate all geometry fields."""

{coeftable-0.6.0 → coeftable-0.7.0}/src/coeftable/cards/fragments.py

@@ -18,6 +18,7 @@ from typing import assert_never
 from coeftable.cards.adornments import (
     Adornment,
     Badge,
+    Callout,
     CaptionRow,
     InlineSvg,
     KeyValuePopover,
@@ -174,6 +175,13 @@ def render_adornment(
                 f'white-space:nowrap;overflow:hidden;text-overflow:ellipsis;max-width:100%">'
                 f"{_esc(text)}</span>"
             )
+        case Callout(text=text, role=role):
+            style = _row(chrome.body_size, theme.color(role), chrome)
+            return (
+                f'<div style="{style};border-left:{chrome.callout_accent}px solid '
+                f'{_esc(theme.color(role))};padding-left:{chrome.callout_inset}px">'
+                f"{_esc(text)}</div>"
+            )
         case CaptionRow(text=text, color=color, dash=dash):
             marker = (
                 ""

{coeftable-0.6.0 → coeftable-0.7.0}/src/coeftable/cards/measure.py

@@ -16,6 +16,7 @@ from dataclasses import dataclass, replace
 from coeftable.cards.adornments import (
     Adornment,
     Badge,
+    Callout,
     CaptionRow,
     InlineSvg,
     KeyValuePopover,
@@ -64,6 +65,12 @@ def _minimum_inline_width(adornment: Adornment, chrome: CardChrome) -> float | N
         return 2 * chrome.chip_padding_x + _minimum_text_width(
             adornment.text, chrome.chip_size, chrome.char_width_ratio
         )
+    if isinstance(adornment, Callout):
+        return (
+            chrome.callout_accent
+            + chrome.callout_inset
+            + _minimum_text_width(adornment.text, chrome.body_size, chrome.char_width_ratio)
+        )
     if isinstance(adornment, CaptionRow):
         fixed = 0 if adornment.color is None else chrome.swatch_width + chrome.swatch_gap
         return fixed + _minimum_text_width(
@@ -242,6 +249,16 @@ def resolve_rows(
                             replace(adornment, text=lined, max_lines=1), line_height(size, chrome)
                         )
                     )
+            case Callout(text=text, max_lines=max_lines):
+                inset = chrome.callout_accent + chrome.callout_inset
+                budget = _budget(usable - inset, chrome.body_size, chrome.char_width_ratio)
+                for lined in text_line_plan(text, budget=budget, max_lines=max_lines):
+                    rows.append(
+                        RenderRow(
+                            replace(adornment, text=lined, max_lines=1),
+                            line_height(chrome.body_size, chrome),
+                        )
+                    )
             case MetricValue():
                 rows.append(_metric_row(adornment, usable, chrome, where))
             case InlineSvg(width=svg_width, height=svg_height):

{coeftable-0.6.0 → coeftable-0.7.0}/src/coeftable/cards/panel.py

@@ -9,6 +9,7 @@ from typing import cast
 from coeftable.cards.adornments import (
     Adornment,
     Badge,
+    Callout,
     CaptionRow,
     InlineSvg,
     KeyValuePopover,
@@ -32,6 +33,7 @@ _ADORNMENT_TYPES = (
     KeyValuePopover,
     SelectControl,
     Badge,
+    Callout,
     CaptionRow,
     Legend,
     RuleStrip,

{coeftable-0.6.0 → coeftable-0.7.0}/src/coeftable/cards/regions.py

@@ -19,6 +19,7 @@ from coeftable.cards.adornments import (
     _DASHES,
     Adornment,
     Badge,
+    Callout,
     CaptionRow,
     InlineSvg,
     KeyValuePopover,
@@ -51,6 +52,7 @@ _ADORNMENT_TYPES = (
     KeyValuePopover,
     SelectControl,
     Badge,
+    Callout,
     CaptionRow,
     Legend,
     RuleStrip,

{coeftable-0.6.0 → coeftable-0.7.0}/src/coeftable/graph/__init__.py

@@ -1,5 +1,7 @@
 """Experimental graph value types."""
 
+from coeftable.graph.breakout import Breakout
+from coeftable.graph.driver_tree import DriverTree
 from coeftable.graph.metric_tree import MetricTree
 from coeftable.graph.model import (
     Atom,
@@ -11,15 +13,22 @@ from coeftable.graph.model import (
     StateRule,
     Wire,
 )
+from coeftable.graph.report import GraphReport, MeasuredReport
+from coeftable.graph.timeline import TimelineEvent
 
 __all__ = [
     "Atom",
+    "Breakout",
     "ControlRef",
+    "DriverTree",
     "Graph",
+    "GraphReport",
     "MeasuredGraph",
+    "MeasuredReport",
     "MetricTree",
     "Slot",
     "Slotted",
     "StateRule",
+    "TimelineEvent",
     "Wire",
 ]