plotlet 0.1.0__tar.gz

plotlet-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gitbamboo42
+
+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.

plotlet-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: plotlet
+Version: 0.1.0
+Summary: Small, hackable Python library that emits matplotlib-style SVG plots.
+Author: gitbamboo42
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/gitbamboo42/plotlet
+Project-URL: Repository, https://github.com/gitbamboo42/plotlet
+Project-URL: Issues, https://github.com/gitbamboo42/plotlet/issues
+Keywords: plot,svg,matplotlib,scientific,visualization,jupyter,reproducible
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fonttools>=4.0
+Provides-Extra: dev
+Requires-Dist: jupyter; extra == "dev"
+Requires-Dist: nbconvert; extra == "dev"
+Dynamic: license-file
+
+# plotlet
+
+A small, hackable Python library that emits matplotlib-style SVG plots.
+
+## Why
+
+matplotlib is the right tool when you want the kitchen sink. plotlet's niche is **custom plot types** — genome tracks, Manhattan plots, phylogenetic trees, anything matplotlib's extension API makes painful. The whole library is ~700 lines of Python with a deliberately tiny, exposed core: adding a new plot type is a 3-step recipe, not an architecture project.
+
+It's a **scaffold, not a feature catalog**: the core ships ~5 standard plots and the infrastructure for extending. Custom plot types live in your own project (or [`cookbook/`](cookbook/)), not upstream. See [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md) for the full framing.
+
+```python
+import plotlet as pt
+
+data = {
+    "x":      [1, 2, 3, 4, 5, 1, 2, 3, 4, 5],
+    "y":      [1, 4, 9, 16, 25, 1, 8, 27, 64, 125],
+    "series": ["squares"] * 5 + ["cubes"] * 5,
+}
+
+c = pt.chart(data, title="Hello", xlabel="x", ylabel="y", legend=True, grid=True)
+c.line(x="x", y="y", hue="series")
+c                                        # auto-renders in Jupyter
+```
+
+## Install
+
+Not on PyPI yet — clone and install editable:
+
+```bash
+git clone <repo>
+cd plotlet
+pip install -e .
+```
+
+## Properties
+
+- **Lightweight.** `fonttools` for font handling. numpy / pandas / polars inputs work transparently if you have them.
+- **Static SVG output.** No interactivity, no animation. Same script → byte-identical SVG.
+- **Cross-machine reproducible.** Bundled DejaVu Sans + text-as-paths means rendering is identical on Linux, macOS, Windows, headless CI.
+- **Jupyter-native.** `Figure._repr_html_` auto-renders the last expression in a cell.
+- **Tiny output.** Each plot is ~50 KB SVG, self-contained.
+
+## API
+
+`pt.chart(data, **opts)` returns a `Chart` bound to a table — any object that supports `data[col_name]` returning an iterable (pandas / polars DataFrames, dict-of-lists, dict-of-arrays). All methods return `self`; `_repr_html_` makes the chart auto-render as the last expression in a Jupyter cell.
+
+### Frame options
+
+Pass at construction (`pt.chart(data, title=..., grid=True, ...)`) or as chained setters (`c.title(...)`, etc.):
+
+`title`, `xlabel`, `ylabel`, `xlim=(a, b)`, `ylim=(a, b)`, `xscale="log"|"linear"`, `yscale=...`, `grid=True/False`, `legend=True/False`, `width`, `height`
+
+### Mark methods
+
+| call | options |
+| --- | --- |
+| `.line(x=, y=, hue=, **opts)` | `color`, `label`, `linewidth`, `linestyle` (`"-"`, `"--"`, `":"`, `"-."`), `marker` (`"o"`, `"s"`, `"^"`, `"v"`, `"x"`, `"+"`), `markersize` |
+| `.scatter(x=, y=, hue=, **opts)` | `color`, `label`, `s` (size), `alpha`, `marker` |
+| `.bar(x=, y=, **opts)` | `color`, `label`, `alpha` |
+| `.hist(x=, **opts)` | `bins`, `color`, `alpha`, `label` |
+| `.fill_between(x=, y1=, y2=, **opts)` | `color`, `alpha`, `label` |
+
+`hue=<col>` (on `.line` / `.scatter`) splits into one call per unique value with auto-labels and tab10 colors.
+
+### Render / save
+
+```python
+c.show()                     # explicit display() inside a cell
+c.to_svg()                   # raw SVG string
+c.save_svg("plot.svg")       # SVG file
+c.write_html("plot.html")    # standalone HTML
+```
+
+### Color shortcuts
+
+- `"C0"`–`"C9"` → tab10 (matches matplotlib)
+- Named: `"blue"`, `"orange"`, `"green"`, `"red"`, `"purple"`, `"brown"`, `"pink"`, `"gray"`, `"olive"`, `"cyan"`
+- Single-letter: `"k"`, `"w"`, `"b"`, `"g"`, `"r"`
+- Any hex / CSS color string passes through
+
+## Adding a new plot type
+
+plotlet's central hackability claim: a custom plot type is a 3-step recipe (~50–100 lines) that gets axes, scales, legend, grid, and composability for free. The recommended home is your own project, or [`cookbook/`](cookbook/) as reference. Full guide: [docs/EXTENDING.md](docs/EXTENDING.md).
+
+## Testing
+
+```bash
+python tests/test_chart.py            # check vs. committed baselines
+python tests/test_chart.py --update   # regenerate (review the diff!)
+python tests/test_chart.py --gallery  # build tests/baseline_images/chart/index.html
+```
+
+## Non-goals
+
+- No interactivity (hover, zoom, click). Static rendering is the point.
+- Not competing with matplotlib on standard plots; matplotlib is bigger and battle-tested.
+- Not a 3D plotter, not a dashboard tool.
+- Not a feature catalog — new plot types belong in user projects or `cookbook/`, not in the core.
+
+## License
+
+MIT

plotlet-0.1.0/README.md

@@ -0,0 +1,102 @@
+# plotlet
+
+A small, hackable Python library that emits matplotlib-style SVG plots.
+
+## Why
+
+matplotlib is the right tool when you want the kitchen sink. plotlet's niche is **custom plot types** — genome tracks, Manhattan plots, phylogenetic trees, anything matplotlib's extension API makes painful. The whole library is ~700 lines of Python with a deliberately tiny, exposed core: adding a new plot type is a 3-step recipe, not an architecture project.
+
+It's a **scaffold, not a feature catalog**: the core ships ~5 standard plots and the infrastructure for extending. Custom plot types live in your own project (or [`cookbook/`](cookbook/)), not upstream. See [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md) for the full framing.
+
+```python
+import plotlet as pt
+
+data = {
+    "x":      [1, 2, 3, 4, 5, 1, 2, 3, 4, 5],
+    "y":      [1, 4, 9, 16, 25, 1, 8, 27, 64, 125],
+    "series": ["squares"] * 5 + ["cubes"] * 5,
+}
+
+c = pt.chart(data, title="Hello", xlabel="x", ylabel="y", legend=True, grid=True)
+c.line(x="x", y="y", hue="series")
+c                                        # auto-renders in Jupyter
+```
+
+## Install
+
+Not on PyPI yet — clone and install editable:
+
+```bash
+git clone <repo>
+cd plotlet
+pip install -e .
+```
+
+## Properties
+
+- **Lightweight.** `fonttools` for font handling. numpy / pandas / polars inputs work transparently if you have them.
+- **Static SVG output.** No interactivity, no animation. Same script → byte-identical SVG.
+- **Cross-machine reproducible.** Bundled DejaVu Sans + text-as-paths means rendering is identical on Linux, macOS, Windows, headless CI.
+- **Jupyter-native.** `Figure._repr_html_` auto-renders the last expression in a cell.
+- **Tiny output.** Each plot is ~50 KB SVG, self-contained.
+
+## API
+
+`pt.chart(data, **opts)` returns a `Chart` bound to a table — any object that supports `data[col_name]` returning an iterable (pandas / polars DataFrames, dict-of-lists, dict-of-arrays). All methods return `self`; `_repr_html_` makes the chart auto-render as the last expression in a Jupyter cell.
+
+### Frame options
+
+Pass at construction (`pt.chart(data, title=..., grid=True, ...)`) or as chained setters (`c.title(...)`, etc.):
+
+`title`, `xlabel`, `ylabel`, `xlim=(a, b)`, `ylim=(a, b)`, `xscale="log"|"linear"`, `yscale=...`, `grid=True/False`, `legend=True/False`, `width`, `height`
+
+### Mark methods
+
+| call | options |
+| --- | --- |
+| `.line(x=, y=, hue=, **opts)` | `color`, `label`, `linewidth`, `linestyle` (`"-"`, `"--"`, `":"`, `"-."`), `marker` (`"o"`, `"s"`, `"^"`, `"v"`, `"x"`, `"+"`), `markersize` |
+| `.scatter(x=, y=, hue=, **opts)` | `color`, `label`, `s` (size), `alpha`, `marker` |
+| `.bar(x=, y=, **opts)` | `color`, `label`, `alpha` |
+| `.hist(x=, **opts)` | `bins`, `color`, `alpha`, `label` |
+| `.fill_between(x=, y1=, y2=, **opts)` | `color`, `alpha`, `label` |
+
+`hue=<col>` (on `.line` / `.scatter`) splits into one call per unique value with auto-labels and tab10 colors.
+
+### Render / save
+
+```python
+c.show()                     # explicit display() inside a cell
+c.to_svg()                   # raw SVG string
+c.save_svg("plot.svg")       # SVG file
+c.write_html("plot.html")    # standalone HTML
+```
+
+### Color shortcuts
+
+- `"C0"`–`"C9"` → tab10 (matches matplotlib)
+- Named: `"blue"`, `"orange"`, `"green"`, `"red"`, `"purple"`, `"brown"`, `"pink"`, `"gray"`, `"olive"`, `"cyan"`
+- Single-letter: `"k"`, `"w"`, `"b"`, `"g"`, `"r"`
+- Any hex / CSS color string passes through
+
+## Adding a new plot type
+
+plotlet's central hackability claim: a custom plot type is a 3-step recipe (~50–100 lines) that gets axes, scales, legend, grid, and composability for free. The recommended home is your own project, or [`cookbook/`](cookbook/) as reference. Full guide: [docs/EXTENDING.md](docs/EXTENDING.md).
+
+## Testing
+
+```bash
+python tests/test_chart.py            # check vs. committed baselines
+python tests/test_chart.py --update   # regenerate (review the diff!)
+python tests/test_chart.py --gallery  # build tests/baseline_images/chart/index.html
+```
+
+## Non-goals
+
+- No interactivity (hover, zoom, click). Static rendering is the point.
+- Not competing with matplotlib on standard plots; matplotlib is bigger and battle-tested.
+- Not a 3D plotter, not a dashboard tool.
+- Not a feature catalog — new plot types belong in user projects or `cookbook/`, not in the core.
+
+## License
+
+MIT

plotlet-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "plotlet"
+version = "0.1.0"
+description = "Small, hackable Python library that emits matplotlib-style SVG plots."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [
+    { name = "gitbamboo42" },
+]
+keywords = [
+    "plot",
+    "svg",
+    "matplotlib",
+    "scientific",
+    "visualization",
+    "jupyter",
+    "reproducible",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Visualization",
+    "Topic :: Multimedia :: Graphics",
+]
+dependencies = [
+  "fonttools>=4.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "jupyter",
+  "nbconvert",
+]
+
+[project.urls]
+Homepage = "https://github.com/gitbamboo42/plotlet"
+Repository = "https://github.com/gitbamboo42/plotlet"
+Issues = "https://github.com/gitbamboo42/plotlet/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+plotlet = ["spec.json", "fonts/*.ttf"]

plotlet-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

plotlet-0.1.0/src/plotlet/__init__.py

@@ -0,0 +1,23 @@
+"""plotlet — pure-Python SVG renderer, matplotlib-flavored.
+
+Tabular API (recommended):
+
+    import plotlet as pt
+    c = pt.chart(df, title="...", xlabel="x", ylabel="y", legend=True, grid=True)
+    c.line(x="time", y="value", hue="series")
+    c                         # auto-renders in Jupyter
+
+Chained API (legacy, still supported):
+
+    fig = pt.figure()
+    fig.plot([1, 2, 3], [1, 4, 9], label="squares")
+    fig.title("Hello").legend().grid(True)
+    fig
+"""
+from ._spec import SPEC
+from .colors import TAB10, colors
+from .core import Figure, figure
+from .chart import Chart, chart
+
+__all__ = ["chart", "Chart", "figure", "Figure", "SPEC", "TAB10", "colors"]
+__version__ = "0.1.0"

plotlet-0.1.0/src/plotlet/_spec.py

@@ -0,0 +1,21 @@
+"""Visual spec — loaded from bundled spec.json. Internal.
+
+The spec is the locked visual contract: colors, fonts, sizes, default alphas,
+legend dimensions. Submodules read from here to avoid hardcoding literals.
+"""
+import json
+from pathlib import Path
+
+_HERE = Path(__file__).parent
+SPEC = json.loads((_HERE / "spec.json").read_text())
+
+# Convenience handles to subsections — used by other modules.
+_TAB10 = SPEC["colors"]["tab10"]
+_COLOR_NAMES = SPEC["colors"]["named"]
+_DASH = SPEC["linestyles"]
+_D = SPEC["defaults"]
+_FRAME = SPEC["frame"]
+_GRIDSPEC = SPEC["grid"]
+_FONTSPEC = SPEC["font"]
+_LEGSPEC = SPEC["legend"]
+_SIZESPEC = SPEC["size"]

plotlet-0.1.0/src/plotlet/artists.py

@@ -0,0 +1,154 @@
+"""Per-artist SVG-emit helpers, marker primitive, histogram binning.
+
+Each `_artist_<type>` takes the recorded artist dict, the x and y scales,
+and the resolved color, and returns an SVG fragment. They're called from
+`core._render`.
+"""
+import math
+
+from ._spec import _D, _DASH
+
+
+def _to_pylist(obj):
+    """Convert numpy / pandas / arbitrary iterables to plain Python lists."""
+    if hasattr(obj, "tolist"):
+        return obj.tolist()
+    if isinstance(obj, (list, tuple)):
+        return list(obj)
+    return list(obj)
+
+
+def _histogram(data, bins):
+    """Equal-width binning. Returns list of {'x0', 'x1', 'count'} dicts."""
+    data = [v for v in _to_pylist(data)
+            if v is not None and not (isinstance(v, float) and math.isnan(v))]
+    if not data:
+        return []
+    lo, hi = min(data), max(data)
+    if lo == hi:
+        hi = lo + 1
+    n = bins if isinstance(bins, int) else 10
+    width = (hi - lo) / n
+    counts = [0] * n
+    for v in data:
+        if v == hi:
+            counts[-1] += 1
+        else:
+            i = int((v - lo) / width)
+            if 0 <= i < n:
+                counts[i] += 1
+    return [{"x0": lo + i * width, "x1": lo + (i + 1) * width, "count": counts[i]}
+            for i in range(n)]
+
+
+# ---------------------------------------------------------------------------
+# Artist helpers
+# ---------------------------------------------------------------------------
+
+def _artist_plot(a, xs_, ys_, col):
+    out = []
+    opts = a["opts"]
+    pts = [(xs_(x), ys_(y)) for x, y in zip(a["xs"], a["ys"])]
+    pts = [(px, py) if (math.isfinite(px) and math.isfinite(py)) else None
+           for px, py in pts]
+    d_segs, started = [], False
+    for p in pts:
+        if p is None:
+            started = False
+            continue
+        d_segs.append(f'{"M" if not started else "L"}{p[0]:.2f},{p[1]:.2f}')
+        started = True
+    ls = opts.get("linestyle")
+    if ls not in ("", "none"):
+        da = f' stroke-dasharray="{_DASH[ls]}"' if ls and _DASH.get(ls) else ""
+        out.append(f'<path d="{"".join(d_segs)}" fill="none" stroke="{col}" '
+                   f'stroke-width="{opts.get("linewidth", _D["linewidth"])}"{da}/>')
+    if opts.get("marker"):
+        sz = opts.get("markersize", _D["markersize"])
+        for p in pts:
+            if p is None:
+                continue
+            out.append(_marker_at(opts["marker"], p[0], p[1], sz, col, 1))
+    return "".join(out)
+
+
+def _artist_scatter(a, xs_, ys_, col):
+    opts = a["opts"]
+    sz = math.sqrt(opts.get("s", _D["scatter_s"])) / 2
+    alpha = opts.get("alpha", _D["scatter_alpha"])
+    marker = opts.get("marker", "o")
+    out = []
+    for x, y in zip(a["xs"], a["ys"]):
+        px, py = xs_(x), ys_(y)
+        if not (math.isfinite(px) and math.isfinite(py)):
+            continue
+        out.append(_marker_at(marker, px, py, sz, col, alpha))
+    return "".join(out)
+
+
+def _artist_bar(a, xs_, ys_, col):
+    out = []
+    opts = a["opts"]
+    bw = xs_.bandwidth
+    y0 = ys_(0)
+    alpha = opts.get("alpha", _D["bar_alpha"])
+    for c, v in zip(a["cats"], a["vals"]):
+        x = xs_(c)
+        y = ys_(v)
+        out.append(f'<rect x="{x:.2f}" y="{min(y0, y):.2f}" width="{bw:.2f}" '
+                   f'height="{abs(y - y0):.2f}" fill="{col}" opacity="{alpha}"/>')
+    return "".join(out)
+
+
+def _artist_hist(a, xs_, ys_, ih, col):
+    out = []
+    alpha = a["opts"].get("alpha", _D["hist_alpha"])
+    half_gap = _D["hist_gap"] / 2
+    for b in a["_bins"]:
+        x0 = xs_(b["x0"]) + half_gap
+        x1 = xs_(b["x1"]) - half_gap
+        w = max(0, x1 - x0)
+        y = ys_(b["count"])
+        h = ih - y
+        out.append(f'<rect x="{x0:.2f}" y="{y:.2f}" width="{w:.2f}" height="{h:.2f}" '
+                   f'fill="{col}" opacity="{alpha}"/>')
+    return "".join(out)
+
+
+def _artist_fill_between(a, xs_, ys_, col):
+    upper = [(xs_(x), ys_(y)) for x, y in zip(a["xs"], a["y1"])]
+    lower = [(xs_(x), ys_(y)) for x, y in zip(a["xs"], a["y2"])]
+    pts = upper + list(reversed(lower))
+    if not pts:
+        return ""
+    d = "M" + "L".join(f"{p[0]:.2f},{p[1]:.2f}" for p in pts) + "Z"
+    alpha = a["opts"].get("alpha", _D["fill_alpha"])
+    return f'<path d="{d}" fill="{col}" opacity="{alpha}"/>'
+
+
+# ---------------------------------------------------------------------------
+# Marker primitive — used by plot/scatter and the legend
+# ---------------------------------------------------------------------------
+
+def _marker_at(marker, x, y, size, col, alpha):
+    msw = _D["marker_stroke_width"]
+    if marker == "o":
+        return f'<circle cx="{x:.2f}" cy="{y:.2f}" r="{size}" fill="{col}" opacity="{alpha}"/>'
+    if marker == "s":
+        return (f'<rect x="{x - size:.2f}" y="{y - size:.2f}" width="{2 * size}" '
+                f'height="{2 * size}" fill="{col}" opacity="{alpha}"/>')
+    if marker == "^":
+        return (f'<path d="M{x:.2f},{y - size:.2f}L{x + size:.2f},{y + size:.2f}'
+                f'L{x - size:.2f},{y + size:.2f}Z" fill="{col}" opacity="{alpha}"/>')
+    if marker == "v":
+        return (f'<path d="M{x:.2f},{y + size:.2f}L{x + size:.2f},{y - size:.2f}'
+                f'L{x - size:.2f},{y - size:.2f}Z" fill="{col}" opacity="{alpha}"/>')
+    if marker == "x":
+        return (f'<path d="M{x - size:.2f},{y - size:.2f}L{x + size:.2f},{y + size:.2f}'
+                f'M{x - size:.2f},{y + size:.2f}L{x + size:.2f},{y - size:.2f}" '
+                f'stroke="{col}" stroke-width="{msw}" opacity="{alpha}"/>')
+    if marker == "+":
+        return (f'<path d="M{x - size:.2f},{y:.2f}L{x + size:.2f},{y:.2f}'
+                f'M{x:.2f},{y - size:.2f}L{x:.2f},{y + size:.2f}" '
+                f'stroke="{col}" stroke-width="{msw}" opacity="{alpha}"/>')
+    return ""

plotlet-0.1.0/src/plotlet/chart.py

@@ -0,0 +1,150 @@
+"""Tidy-table-friendly facade over Figure.
+
+    c = chart(df, title="...", xlabel="...", legend=True, grid=True)
+    c.line(x="time", y="value", hue="series")
+    c                         # auto-renders in Jupyter
+
+Each mark method (`line`, `scatter`, `bar`, `hist`, `fill_between`) accepts
+either column-name kwargs against the bound table, or the existing array form
+as positional args. `hue=<col>` splits into one call per unique value with
+auto-labels and tab10 colors.
+
+The bound table can be anything that supports `df[col_name]` returning an
+iterable: pandas / polars DataFrames, dict-of-lists, dict-of-arrays. No
+pandas dependency.
+"""
+from __future__ import annotations
+
+from .core import Figure
+from .artists import _to_pylist
+
+
+class Chart:
+    def __init__(self, data=None, *, width: int | None = None, height: int | None = None,
+                 margin: dict | None = None,
+                 title: str | None = None,
+                 xlabel: str | None = None, ylabel: str | None = None,
+                 xlim: tuple | None = None, ylim: tuple | None = None,
+                 xscale: str | None = None, yscale: str | None = None,
+                 legend: bool | None = None, grid: bool | None = None):
+        self._fig = Figure(width=width, height=height, margin=margin)
+        self._data = data
+        if title  is not None: self._fig.title(title)
+        if xlabel is not None: self._fig.xlabel(xlabel)
+        if ylabel is not None: self._fig.ylabel(ylabel)
+        if xlim   is not None: self._fig.xlim(*xlim)
+        if ylim   is not None: self._fig.ylim(*ylim)
+        if xscale is not None: self._fig.xscale(xscale)
+        if yscale is not None: self._fig.yscale(yscale)
+        if legend is not None: self._fig.legend(legend)
+        if grid   is not None: self._fig.grid(grid)
+
+    # ---------- mark methods ----------
+
+    def line(self, *args, x=None, y=None, hue=None, data=None, **opts):
+        if x is not None or y is not None:
+            self._tabular("line", "plot", data, x, y, hue, opts)
+        else:
+            self._fig.plot(*args, **opts)
+        return self
+
+    def scatter(self, *args, x=None, y=None, hue=None, data=None, **opts):
+        if x is not None or y is not None:
+            self._tabular("scatter", "scatter", data, x, y, hue, opts)
+        else:
+            self._fig.scatter(*args, **opts)
+        return self
+
+    def bar(self, *args, x=None, y=None, data=None, **opts):
+        if x is not None or y is not None:
+            df = self._resolve_data(data, "bar")
+            self._fig.bar(_to_pylist(df[x]), _to_pylist(df[y]), **opts)
+        else:
+            self._fig.bar(*args, **opts)
+        return self
+
+    def hist(self, *args, x=None, data=None, **opts):
+        if x is not None:
+            df = self._resolve_data(data, "hist")
+            self._fig.hist(_to_pylist(df[x]), **opts)
+        else:
+            self._fig.hist(*args, **opts)
+        return self
+
+    def fill_between(self, *args, x=None, y1=None, y2=None, data=None, **opts):
+        if x is not None or y1 is not None or y2 is not None:
+            df = self._resolve_data(data, "fill_between")
+            self._fig.fill_between(
+                _to_pylist(df[x]), _to_pylist(df[y1]), _to_pylist(df[y2]), **opts)
+        else:
+            self._fig.fill_between(*args, **opts)
+        return self
+
+    # ---------- helpers ----------
+
+    def _resolve_data(self, data, public_name):
+        df = data if data is not None else self._data
+        if df is None:
+            raise ValueError(
+                f"Chart.{public_name}() with column-name kwargs requires a bound table; "
+                f"pass data=<table> or use chart(<table>)."
+            )
+        return df
+
+    def _tabular(self, public_name, kind, data, x_col, y_col, hue, opts):
+        df = self._resolve_data(data, public_name)
+        method = getattr(self._fig, kind)
+        if hue is None:
+            method(_to_pylist(df[x_col]), _to_pylist(df[y_col]), **opts)
+            return
+        hue_vals = _to_pylist(df[hue])
+        xs_all = _to_pylist(df[x_col])
+        ys_all = _to_pylist(df[y_col])
+        seen: list = []
+        for v in hue_vals:
+            if v not in seen:
+                seen.append(v)
+        opts.pop("label", None)  # hue overrides any user-provided label
+        for v in seen:
+            xs_g = [xs_all[i] for i, h in enumerate(hue_vals) if h == v]
+            ys_g = [ys_all[i] for i, h in enumerate(hue_vals) if h == v]
+            method(xs_g, ys_g, label=str(v), **opts)
+
+    # ---------- frame metadata (passthrough) ----------
+
+    def title(self, s):        self._fig.title(s);   return self
+    def xlabel(self, s):       self._fig.xlabel(s);  return self
+    def ylabel(self, s):       self._fig.ylabel(s);  return self
+    def xlim(self, a, b):      self._fig.xlim(a, b); return self
+    def ylim(self, a, b):      self._fig.ylim(a, b); return self
+    def xscale(self, s):       self._fig.xscale(s);  return self
+    def yscale(self, s):       self._fig.yscale(s);  return self
+    def grid(self, on=True):   self._fig.grid(on);   return self
+    def legend(self, on=True): self._fig.legend(on); return self
+
+    # ---------- render ----------
+
+    def to_svg(self) -> str:
+        return self._fig.to_svg()
+
+    def to_html(self, full_page: bool = False) -> str:
+        return self._fig.to_html(full_page=full_page)
+
+    def _repr_html_(self) -> str:
+        return self._fig.to_svg()
+
+    def show(self):
+        self._fig.show()
+
+    def save_svg(self, path):
+        self._fig.save_svg(path)
+        return self
+
+    def write_html(self, path):
+        self._fig.write_html(path)
+        return self
+
+
+def chart(data=None, **opts) -> Chart:
+    """Construct a table-bound Chart. See `Chart` for keyword arguments."""
+    return Chart(data, **opts)