youplot 1.0.0__py3-none-any.whl

youplot/render/scatter_js.py

@@ -0,0 +1,195 @@
+"""Scatter plot JS."""
+
+SCATTER_JS = r"""
+(function() {
+
+function hexAlpha(hex,alpha){
+  if(!hex)return'rgba(128,128,128,'+alpha+')';
+  if(hex.startsWith('rgba')||hex.startsWith('rgb'))return hex;
+  var h=hex.replace('#','');
+  if(h.length===3)h=h[0]+h[0]+h[1]+h[1]+h[2]+h[2];
+  var r=parseInt(h.slice(0,2),16),g=parseInt(h.slice(2,4),16),b=parseInt(h.slice(4,6),16);
+  return'rgba('+r+','+g+','+b+','+alpha+')';
+}
+function lerpColor(hex1,hex2,t){
+  var h1=hex1.replace('#',''),h2=hex2.replace('#','');
+  if(h1.length===3)h1=h1[0]+h1[0]+h1[1]+h1[1]+h1[2]+h1[2];
+  if(h2.length===3)h2=h2[0]+h2[0]+h2[1]+h2[1]+h2[2]+h2[2];
+  var r=Math.round(parseInt(h1.slice(0,2),16)*(1-t)+parseInt(h2.slice(0,2),16)*t);
+  var g=Math.round(parseInt(h1.slice(2,4),16)*(1-t)+parseInt(h2.slice(2,4),16)*t);
+  var b=Math.round(parseInt(h1.slice(4,6),16)*(1-t)+parseInt(h2.slice(4,6),16)*t);
+  return'rgb('+r+','+g+','+b+')';
+}
+function drawShape(ctx,shape,cx,cy,r){
+  ctx.beginPath();
+  switch(shape){
+    case'square':ctx.rect(cx-r,cy-r,r*2,r*2);break;
+    case'triangle':ctx.moveTo(cx,cy-r);ctx.lineTo(cx+r*0.866,cy+r*0.5);ctx.lineTo(cx-r*0.866,cy+r*0.5);ctx.closePath();break;
+    case'diamond':ctx.moveTo(cx,cy-r);ctx.lineTo(cx+r,cy);ctx.lineTo(cx,cy+r);ctx.lineTo(cx-r,cy);ctx.closePath();break;
+    case'cross':var t=r*0.32;ctx.rect(cx-r,cy-t,r*2,t*2);ctx.rect(cx-t,cy-r,t*2,r*2);break;
+    case'star':for(var i=0;i<10;i++){var a=(i*Math.PI/5)-Math.PI/2,rad=i%2===0?r:r*0.45;if(i===0)ctx.moveTo(cx+rad*Math.cos(a),cy+rad*Math.sin(a));else ctx.lineTo(cx+rad*Math.cos(a),cy+rad*Math.sin(a));}ctx.closePath();break;
+    default:ctx.arc(cx,cy,r,0,Math.PI*2);
+  }
+}
+function linearRegression(xs,ys){
+  var n=xs.length,sx=0,sy=0,sxy=0,sxx=0;
+  for(var i=0;i<n;i++){sx+=xs[i];sy+=ys[i];sxy+=xs[i]*ys[i];sxx+=xs[i]*xs[i];}
+  var slope=(n*sxy-sx*sy)/(n*sxx-sx*sx);
+  return{slope:slope,intercept:(sy-slope*sx)/n};
+}
+function rSquared(xs,ys,slope,intercept){
+  var ym=ys.reduce(function(a,b){return a+b;},0)/ys.length,ssTot=0,ssRes=0;
+  for(var i=0;i<xs.length;i++){ssTot+=Math.pow(ys[i]-ym,2);ssRes+=Math.pow(ys[i]-(slope*xs[i]+intercept),2);}
+  return ssTot===0?1:1-ssRes/ssTot;
+}
+function round2(v){return Math.round(v*100)/100;}
+function fmtVal(v,fmt){if(!fmt)return round2(v);var m=fmt.match(/\.(\d+)f/);return m?v.toFixed(parseInt(m[1])):round2(v);}
+
+function makeScatterPlugin(scatterConfigs, tooltipId, upRegions, isTimeseries) {
+  var hitMap = [];
+
+  return {
+    hooks: {
+      ready: [function(u) {
+        var el = document.getElementById(tooltipId);
+        if (!el) return;
+
+        // Identical pattern to line chart:
+        // mousemove on u.over → compute position → find hit → show/hide
+        u.over.addEventListener('mousemove', function(e) {
+          // mouse position relative to the plot area (same space as hitMap hx/hy)
+          var rect = u.over.getBoundingClientRect();
+          var mx = e.clientX - rect.left;
+          var my = e.clientY - rect.top;
+
+          // Find point whose drawn radius contains the mouse
+          var best = null;
+          var bestDist = Infinity;
+          for (var k = 0; k < hitMap.length; k++) {
+            var h = hitMap[k];
+            if (h.cfg.visible === false) continue;
+            var d = Math.sqrt(Math.pow(mx - h.hx, 2) + Math.pow(my - h.hy, 2));
+            // Only trigger if mouse is within the drawn point radius (+2px grace)
+            if (d <= h.r + 2 && d < bestDist) {
+              bestDist = d;
+              best = h;
+            }
+          }
+
+          if (!best) { el.style.display = 'none'; return; }
+
+          var cfg = best.cfg, unit = cfg.hoverUnit||'';
+          var html = '<div class="up-tooltip-time">'+(cfg.label||'')+'</div>';
+          
+          if (upRegions) {
+            var tsVal = best.xv;
+            var xVal = isTimeseries ? tsVal * 1000 : tsVal;
+            upRegions.forEach(function(r){
+              if (r._tagId && r.label && xVal >= Math.min(r.x_start, r.x_end) && xVal <= Math.max(r.x_start, r.x_end)) {
+                html += '<div class="up-tooltip-row" style="background:'+hexAlpha(r.color, 0.15)+'; border-radius:4px; padding:3px 6px; margin-bottom:6px; border:1px solid '+hexAlpha(r.color,0.3)+';">'
+                  + '<span class="up-tooltip-dot" style="background:'+r.color+'"></span>'
+                  + '<span class="up-tooltip-name" style="font-weight:600; color:'+r.color+'; text-shadow:0 0 1px #000;">Tag: '+r.label+'</span>'
+                  + '</div>';
+              }
+            });
+          }
+
+          html += '<div class="up-tooltip-row">'
+            +'<span class="up-tooltip-dot" style="background:'+best.fillColor+'"></span>'
+            +'<span class="up-tooltip-name">'+(cfg.hoverXLabel||'x')+'</span>'
+            +'<span class="up-tooltip-val" style="color:'+best.fillColor+'">'+fmtVal(best.xv,cfg.hoverFormat)+unit+'</span>'
+            +'</div>'
+            +'<div class="up-tooltip-row">'
+            +'<span class="up-tooltip-dot" style="background:'+best.fillColor+'"></span>'
+            +'<span class="up-tooltip-name">'+(cfg.hoverYLabel||'y')+'</span>'
+            +'<span class="up-tooltip-val" style="color:'+best.fillColor+'">'+fmtVal(best.yv,cfg.hoverFormat)+unit+'</span>'
+            +'</div>';
+          if(cfg._sizeData&&cfg._sizeData[best.i]!=null)
+            html+='<div class="up-tooltip-row"><span class="up-tooltip-name">size</span><span class="up-tooltip-val">'+round2(cfg._sizeData[best.i])+'</span></div>';
+          if(cfg._colorData&&cfg._colorData[best.i]!=null)
+            html+='<div class="up-tooltip-row"><span class="up-tooltip-name">value</span><span class="up-tooltip-val">'+round2(cfg._colorData[best.i])+'</span></div>';
+
+          el.innerHTML = html;
+          el.style.display = 'block';
+
+          // Position using e.clientX/Y — exactly like line chart
+          var tw = el.offsetWidth || 200;
+          var left = e.clientX + 18;
+          if (left + tw > window.innerWidth - 12) left = e.clientX - tw - 18;
+          var top = e.clientY - 10;
+          if (top + 140 > window.innerHeight) top = e.clientY - 140;
+          el.style.left = left + 'px';
+          el.style.top  = top  + 'px';
+        });
+
+        u.over.addEventListener('mouseleave', function() {
+          el.style.display = 'none';
+        });
+      }],
+
+      draw: [function(u) {
+        var ctx=u.ctx, b=u.bbox;
+        ctx.save();
+        ctx.beginPath();ctx.rect(b.left,b.top,b.width,b.height);ctx.clip();
+        hitMap = [];
+
+        scatterConfigs.forEach(function(scfg){
+          if(scfg.visible===false)return;
+          var xData=scfg._xData,yData=scfg._yData,sizeData=scfg._sizeData,colorData=scfg._colorData,labelData=scfg._labelData;
+          var scaleKey=scfg.scale||'y';
+          var sMin=Infinity,sMax=-Infinity;
+          if(sizeData){for(var i=0;i<sizeData.length;i++){if(sizeData[i]!=null&&!isNaN(sizeData[i])){sMin=Math.min(sMin,sizeData[i]);sMax=Math.max(sMax,sizeData[i]);}}}
+          var cMin=Infinity,cMax=-Infinity;
+          if(colorData){for(var i=0;i<colorData.length;i++){if(colorData[i]!=null&&!isNaN(colorData[i])){cMin=Math.min(cMin,colorData[i]);cMax=Math.max(cMax,colorData[i]);}}}
+
+          var validX=[],validY=[];
+          for(var i=0;i<xData.length;i++){
+            var xv=xData[i],yv=yData[i];
+            if(xv==null||isNaN(xv)||yv==null||isNaN(yv))continue;
+            // canvas-absolute coords
+            var cx=u.valToPos(xv,'x',true);
+            var cy=u.valToPos(yv,scaleKey,true);
+            var r=scfg.size;
+            if(sizeData&&sizeData[i]!=null&&!isNaN(sizeData[i])&&sMax>sMin){var st=(sizeData[i]-sMin)/(sMax-sMin);r=scfg.sizeRange[0]+st*(scfg.sizeRange[1]-scfg.sizeRange[0]);}
+            var fillColor=scfg.color;
+            if(colorData&&colorData[i]!=null&&!isNaN(colorData[i])&&cMax>cMin){var ct=(colorData[i]-cMin)/(cMax-cMin);fillColor=lerpColor(scfg.colorScale[0],scfg.colorScale[1],ct);}
+
+            ctx.globalAlpha=scfg.opacity;ctx.fillStyle=fillColor;
+            drawShape(ctx,scfg.shape,cx,cy,r);ctx.fill();
+            if(scfg.strokeWidth>0){ctx.globalAlpha=Math.min(1,scfg.opacity+0.15);ctx.strokeStyle=scfg.stroke||fillColor;ctx.lineWidth=scfg.strokeWidth;drawShape(ctx,scfg.shape,cx,cy,r);ctx.stroke();}
+            ctx.globalAlpha=1;
+            if(labelData&&labelData[i]!=null){ctx.fillStyle=hexAlpha(scfg.labelColor||scfg.color,0.9);ctx.font=scfg.labelFontSize+'px -apple-system,sans-serif';ctx.textAlign='left';ctx.fillText(String(labelData[i]),cx+r+3,cy+4);}
+
+            // hitMap stores plot-area-relative coords (matching mx/my from mousemove)
+            // mx = e.clientX - over.rect.left  (over covers exactly the plot area in CSS pixels)
+            // hx = (cx - b.left) / pr          (convert canvas-abs to CSS plot-area-relative)
+            var pr = window.devicePixelRatio || 1;
+            hitMap.push({si:scfg._scatterIdx,i:i,hx:(cx-b.left)/pr,hy:(cy-b.top)/pr,r:r,xv:xv,yv:yv,fillColor:fillColor,cfg:scfg});
+            validX.push(xv);validY.push(yv);
+          }
+
+          if(scfg.trendline&&validX.length>=2){
+            var reg=linearRegression(validX,validY);
+            var r2=rSquared(validX,validY,reg.slope,reg.intercept);
+            var xMin=Math.min.apply(null,validX),xMax=Math.max.apply(null,validX);
+            var px0=u.valToPos(xMin,'x',true),px1=u.valToPos(xMax,'x',true);
+            var py0=u.valToPos(reg.slope*xMin+reg.intercept,scaleKey,true);
+            var py1=u.valToPos(reg.slope*xMax+reg.intercept,scaleKey,true);
+            ctx.strokeStyle=scfg.trendlineColor||scfg.color;ctx.lineWidth=scfg.trendlineWidth;
+            ctx.setLineDash(scfg.trendlineDash?[6,4]:[]);ctx.globalAlpha=0.75;
+            ctx.beginPath();ctx.moveTo(px0,py0);ctx.lineTo(px1,py1);ctx.stroke();
+            ctx.setLineDash([]);ctx.globalAlpha=1;
+            ctx.font='600 10px -apple-system,sans-serif';ctx.fillStyle=scfg.trendlineColor||scfg.color;ctx.globalAlpha=0.8;
+            ctx.fillText('R\u00b2='+r2.toFixed(3),px1-58,py1-6);ctx.globalAlpha=1;
+          }
+        });
+        ctx.restore();
+      }]
+    }
+  };
+}
+
+window._makeScatterPlugin = makeScatterPlugin;
+
+})();
+"""

youplot/render/serializer.py

@@ -0,0 +1,242 @@
+"""Serializer — Python data to JS strings for uPlot."""
+
+from __future__ import annotations
+import json
+from youplot.series.line import LineSeries
+
+
+def series_to_js_array(values: list, var_name: str) -> str:
+    nums = ["NaN" if v is None else repr(round(v, 6)) for v in values]
+    return f"const {var_name} = new Float64Array([{','.join(nums)}]);"
+
+
+def timestamps_to_js_array(ts_ms, var_name: str) -> str:
+    secs = [str(t / 1000) for t in ts_ms]
+    return f"const {var_name} = new Float64Array([{','.join(secs)}]);"
+
+
+def numeric_to_js_array(vals, var_name: str) -> str:
+    nums = [repr(float(v)) for v in vals]
+    return f"const {var_name} = new Float64Array([{','.join(nums)}]);"
+
+
+def series_config_to_js(series: list) -> str:
+    parts = ["{}"]
+    for s in series:
+        dash = s.resolved_dash()
+        dash_js = f"[{','.join(map(str, dash))}]" if dash else "[]"
+        cfg = (
+            "{"
+            f'label:{json.dumps(s.label)},'
+            f'scale:{json.dumps(s._scale_name)},'
+            f'stroke:{json.dumps(s.color)},'
+            f'width:{s.width},'
+            f'dash:{dash_js},'
+            f'points:{{show:{"true" if s.points else "false"},size:{s.points_size*2},fill:{json.dumps(s.resolved_points_color())}}},'
+            f'_fill:{json.dumps(s.fill)},'
+            f'_fillOpacity:{s.fill_opacity},'
+            f'_fillColor:{json.dumps(s.resolved_fill_color())},'
+            f'_hoverUnit:{json.dumps(s.hover_unit)},'
+            f'_hoverFormat:{json.dumps(s.hover_format)},'
+            "}"
+        )
+        parts.append(cfg)
+    return "[" + ",".join(parts) + "]"
+
+
+def scales_config_to_js(scale_names, right_scales, x_range, range_map, is_timeseries=True) -> str:
+    """
+    Put min/max in scale config for correct initial render.
+    uPlot scale config min/max sets the initial range but does NOT lock it —
+    setScale() and drag-zoom can always override it afterward.
+    """
+    parts = []
+    if x_range:
+        time_flag = '"time":true,' if is_timeseries else ''
+        parts.append(f'"x":{{{time_flag}"min":{x_range[0]},"max":{x_range[1]}}}')
+    else:
+        time_flag = '"time":true' if is_timeseries else '"time":false'
+        parts.append(f'"x":{{{time_flag}}}')
+    for name in scale_names:
+        rng = range_map.get(name)
+        if rng:
+            parts.append(f'{json.dumps(name)}:{{"auto":false,"min":{rng[0]},"max":{rng[1]}}}')
+        else:
+            parts.append(f'{json.dumps(name)}:{{"auto":true}}')
+    return "{" + ",".join(parts) + "}"
+
+
+def initial_ranges_to_js(x_range, range_map, is_timeseries) -> str:
+    """
+    Returns a JS object of scale→range pairs to apply in the ready hook.
+    e.g. {"x":[0,100],"y":[0,100]}
+    """
+    ranges = {}
+    if x_range:
+        ranges["x"] = [x_range[0], x_range[1]]
+    for name, rng in range_map.items():
+        if rng:
+            ranges[name] = [rng[0], rng[1]]
+    return json.dumps(ranges)
+
+
+def axes_config_to_js(
+    scale_names, right_scales, theme,
+    x_label, y_label, y_right_label,
+    x_format, y_format,
+    is_timeseries=True,
+) -> str:
+    t = theme
+    axes = []
+    x_cfg = (
+        "{"
+        f'stroke:{json.dumps(t.text_tick)},'
+        f'grid:{{stroke:{json.dumps(t.grid_color)},width:1}},'
+        f'ticks:{{stroke:{json.dumps(t.tick_stroke)},width:1,size:5}},'
+        f'font:"11px -apple-system,BlinkMacSystemFont,Inter,sans-serif",'
+        + (f'label:{json.dumps(x_label)},' if x_label else '')
+        + "}"
+    )
+    axes.append(x_cfg)
+    for name in scale_names:
+        is_right = name in right_scales
+        side  = 1 if is_right else 3
+        label = y_right_label if is_right else y_label
+        cfg = (
+            "{"
+            f'scale:{json.dumps(name)},'
+            f'side:{side},'
+            f'stroke:{json.dumps(t.text_tick)},'
+            f'grid:{{stroke:{json.dumps(t.grid_color)},width:1}},'
+            f'ticks:{{stroke:{json.dumps(t.tick_stroke)},width:1,size:5}},'
+            f'font:"11px -apple-system,BlinkMacSystemFont,Inter,sans-serif",'
+            + (f'label:{json.dumps(label)},' if label else '')
+            + "}"
+        )
+        axes.append(cfg)
+    return "[" + ",".join(axes) + "]"
+
+
+def annotations_to_js(vlines, hlines, regions) -> str:
+    # Map user-facing axis names to the internal uPlot scale keys used in UP_SCALES
+    _AXIS_TO_SCALE = {"left": "y", "right": "y2"}
+
+    def dc(obj):
+        d = {k: v for k, v in vars(obj).items()}
+        # ensure _tagId and _removable are always present
+        d.setdefault('_tagId', '')
+        d.setdefault('_removable', True)
+        return d
+
+    def dc_hline(h):
+        d = dc(h)
+        # Translate "left"/"right" to the actual uPlot scale key ("y"/"y2")
+        if d.get('scale') in _AXIS_TO_SCALE:
+            d['scale'] = _AXIS_TO_SCALE[d['scale']]
+        return d
+
+    return (
+        f"const UP_VLINES = {json.dumps([dc(v) for v in vlines])};\n"
+        f"const UP_HLINES = {json.dumps([dc_hline(h) for h in hlines])};\n"
+        f"let UP_REGIONS = {json.dumps([dc(r) for r in regions])};\n"
+    )
+
+
+def bands_to_js(bands) -> str:
+    """Serialize threshold bands to JS array."""
+    _AXIS_TO_SCALE = {"left": "y", "right": "y2"}
+
+    def dc(b):
+        d = {k: v for k, v in vars(b).items()}
+        if d.get('scale') in _AXIS_TO_SCALE:
+            d['scale'] = _AXIS_TO_SCALE[d['scale']]
+        return d
+    return json.dumps([dc(b) for b in bands])
+    from youplot.utils.data import to_float_list
+
+    all_decls = []
+    cfg_parts = []
+
+    for i, s in enumerate(scatter_series):
+        x_var  = f"SC_X_{i}"
+        y_var  = f"SC_Y_{i}"
+        sz_var = f"SC_SZ_{i}"
+        cv_var = f"SC_COL_{i}"
+        lv_var = f"SC_LBL_{i}"
+
+        x_vals = to_float_list(s.x)
+        if is_timeseries:
+            x_nums = [str(v/1000) if v is not None else "NaN" for v in x_vals]
+        else:
+            x_nums = [repr(float(v)) if v is not None else "NaN" for v in x_vals]
+        all_decls.append(f"const {x_var} = [{','.join(x_nums)}];")
+
+        y_vals = to_float_list(s.y)
+        y_nums = [repr(float(v)) if v is not None else "NaN" for v in y_vals]
+        all_decls.append(f"const {y_var} = [{','.join(y_nums)}];")
+
+        def opt_arr(data, var):
+            if data is None:
+                return f"const {var} = null;"
+            vals = to_float_list(data)
+            nums = [repr(float(v)) if v is not None else "NaN" for v in vals]
+            return f"const {var} = [{','.join(nums)}];"
+
+        all_decls.append(opt_arr(s.size_by,  sz_var))
+        all_decls.append(opt_arr(s.color_by, cv_var))
+
+        if s.labels is not None:
+            all_decls.append(f"const {lv_var} = {json.dumps([str(l) for l in s.labels])};")
+        else:
+            all_decls.append(f"const {lv_var} = null;")
+
+        cfg = (
+            "{"
+            f"_scatterIdx:{i},"
+            f"label:{json.dumps(s.label)},"
+            f"color:{json.dumps(s.color)},"
+            f"size:{s.size},"
+            f"opacity:{s.opacity},"
+            f"shape:{json.dumps(s.shape)},"
+            f"stroke:{json.dumps(s.resolved_stroke())},"
+            f"strokeWidth:{s.stroke_width},"
+            f"sizeRange:[{s.size_range[0]},{s.size_range[1]}],"
+            f"colorScale:[{','.join(json.dumps(c) for c in s.color_scale)}],"
+            f"trendline:{'true' if s.trendline else 'false'},"
+            f"trendlineColor:{json.dumps(s.resolved_trendline_color())},"
+            f"trendlineWidth:{s.trendline_width},"
+            f"trendlineDash:{'true' if s.trendline_dash else 'false'},"
+            f"hoverFormat:{json.dumps(s.hover_format)},"
+            f"hoverUnit:{json.dumps(s.hover_unit)},"
+            f"hoverXLabel:{json.dumps(s.hover_x_label)},"
+            f"hoverYLabel:{json.dumps(s.hover_y_label)},"
+            f"labelFontSize:{s.label_font_size},"
+            f"labelColor:{json.dumps(s.resolved_label_color())},"
+            f"scale:{json.dumps(s._scale_name)},"
+            f"visible:true,"
+            f"_xData:{x_var},"
+            f"_yData:{y_var},"
+            f"_sizeData:{sz_var},"
+            f"_colorData:{cv_var},"
+            f"_labelData:{lv_var},"
+            "}"
+        )
+        cfg_parts.append(cfg)
+
+    return "\n".join(all_decls), "[" + ",".join(cfg_parts) + "]"
+
+def pins_to_js(pins) -> str:
+    """Serialize code-defined annotation pins to a JS array."""
+    import json as _json
+    out = []
+    for p in pins:
+        out.append({
+            'id':    f'code_pin_{id(p)}',
+            'x':     p.x,
+            'label': p.label,
+            'y_frac': getattr(p, 'y_frac', 0.2),
+            'y': getattr(p, 'y', None),
+            'scale': getattr(p, 'scale', 'left'),
+            'color': p.color or None,   # None → auto-assigned in JS
+        })
+    return _json.dumps(out)

youplot/series/__init__.py

@@ -0,0 +1,2 @@
+from youplot.series.line import LineSeries
+from youplot.series.scatter import ScatterSeries

youplot/series/line.py

@@ -0,0 +1,70 @@
+"""
+LineSeries — represents one line on the chart.
+All fields are optional except x and y.
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class LineSeries:
+    # ── Required ──────────────────────────────────────────────────────────────
+    x: Any                          # array-like: timestamps (ms), numeric, or datetime
+    y: Any                          # array-like: numeric values
+
+    # ── Identity ──────────────────────────────────────────────────────────────
+    label: str = ""                 # legend + tooltip label
+
+    # ── Appearance ────────────────────────────────────────────────────────────
+    color: str = ""                 # resolved hex — set by Figure if empty
+    width: float = 2.0             # stroke width in px
+    opacity: float = 1.0           # line opacity 0–1
+
+    # Dash pattern
+    dash: bool | list[int] = False  # False=solid, True=[6,3], or custom [on,off]
+
+    # Fill under line
+    fill: bool = False              # gradient fill under line
+    fill_opacity: float = 0.15     # max opacity of fill gradient
+    fill_color: str = ""            # defaults to line color
+
+    # ── Axis binding ──────────────────────────────────────────────────────────
+    axis: str = "left"             # "left" or "right"
+    scale: str = ""                # explicit scale name — auto-set if empty
+
+    # ── Points ────────────────────────────────────────────────────────────────
+    points: bool = False           # show dots at each data point
+    points_size: float = 4.0      # dot radius in px
+    points_color: str = ""         # defaults to line color
+    points_filled: bool = True     # filled vs outline
+
+    # ── Smoothing / shape ─────────────────────────────────────────────────────
+    smooth: bool = False           # spline interpolation (uPlot path: spline)
+    step: bool = False             # step line
+
+    # ── Nulls & gaps ─────────────────────────────────────────────────────────
+    gap_threshold: float | None = None   # seconds — break line if gap exceeds this
+    null_handling: str = "gap"           # "gap" | "zero" | "ignore"
+
+    # ── Tooltip ───────────────────────────────────────────────────────────────
+    hover_format: str = ""         # e.g. ".2f" — python format spec
+    hover_unit: str = ""           # suffix shown in tooltip e.g. "V", "%", "A"
+
+    # ── Internal (set by Figure, not user) ────────────────────────────────────
+    _scale_name: str = field(default="", init=False, repr=False)
+
+    def resolved_dash(self) -> list[int] | None:
+        """Return JS dash array or None for solid."""
+        if self.dash is False:
+            return None
+        if self.dash is True:
+            return [6, 3]
+        return self.dash
+
+    def resolved_fill_color(self) -> str:
+        return self.fill_color if self.fill_color else self.color
+
+    def resolved_points_color(self) -> str:
+        return self.points_color if self.points_color else self.color

youplot/series/scatter.py

@@ -0,0 +1,76 @@
+"""
+ScatterSeries — represents one scatter series on the chart.
+Scatter in uPlot is rendered via a custom canvas plugin (no native scatter).
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ScatterSeries:
+    # ── Required ──────────────────────────────────────────────────────────────
+    x: Any                              # array-like: x values
+    y: Any                              # array-like: y values
+
+    # ── Identity ──────────────────────────────────────────────────────────────
+    label: str = ""
+
+    # ── Point appearance ──────────────────────────────────────────────────────
+    color: str = ""                     # resolved hex — set by Figure if empty
+    size: float = 6.0                   # dot radius in px
+    opacity: float = 0.85               # fill opacity
+
+    # Shape: "circle" | "square" | "triangle" | "diamond" | "cross" | "star"
+    shape: str = "circle"
+
+    # Outline
+    stroke: str = ""                    # border color — defaults to color (darker)
+    stroke_width: float = 1.0          # border width (0 = no border)
+
+    # ── Size encoding — map a third array to point size ───────────────────────
+    size_by: Any = None                 # array-like — values mapped to point sizes
+    size_range: list[float] = field(default_factory=lambda: [3.0, 18.0])  # [min_px, max_px]
+
+    # ── Color encoding — map a third array to point color (gradient) ──────────
+    color_by: Any = None                # array-like — values mapped to color scale
+    color_scale: list[str] = field(default_factory=lambda: ["#6366f1", "#f43f5e"])  # [low, high]
+
+    # ── Axis binding ──────────────────────────────────────────────────────────
+    axis: str = "left"
+    scale: str = ""
+
+    # ── Regression line ───────────────────────────────────────────────────────
+    trendline: bool = False             # draw linear regression line
+    trendline_color: str = ""           # defaults to series color
+    trendline_width: float = 1.5
+    trendline_dash: bool = True
+
+    # ── Hover ─────────────────────────────────────────────────────────────────
+    hover_format: str = ""
+    hover_unit: str = ""
+    hover_x_label: str = "x"           # label for x value in tooltip
+    hover_y_label: str = "y"           # label for y value in tooltip
+
+    # ── Labels on points ──────────────────────────────────────────────────────
+    labels: Any = None                  # array-like of strings — shown next to each point
+    label_font_size: int = 9
+    label_color: str = ""               # defaults to color
+
+    # ── Jitter — avoid overplotting ───────────────────────────────────────────
+    jitter_x: float = 0.0              # random x offset in data units
+    jitter_y: float = 0.0              # random y offset in data units
+
+    # ── Internal ──────────────────────────────────────────────────────────────
+    _scale_name: str = field(default="", init=False, repr=False)
+
+    def resolved_stroke(self) -> str:
+        """Border color — slightly darker version of fill color if not set."""
+        return self.stroke if self.stroke else self.color
+
+    def resolved_trendline_color(self) -> str:
+        return self.trendline_color if self.trendline_color else self.color
+
+    def resolved_label_color(self) -> str:
+        return self.label_color if self.label_color else self.color