fastplotpy 0.3.0a1__py3-none-win_amd64.whl

fastplotpy/overlays.py

@@ -0,0 +1,561 @@
+"""Host-side programmatic tooltip and crosshair state."""
+from copy import deepcopy
+from datetime import datetime, timezone
+from math import cos, hypot, isfinite, sin
+from sys import float_info
+from typing import Mapping
+from zoneinfo import ZoneInfo
+
+from .defaults import get_defaults
+from .interactions import _axis_domains
+from .subplots import resolveTraceSubplotBindings
+from .scene import _number, _scaled
+
+
+_CARTESIAN = {"line", "scatter", "bar", "pie", "heatmap", "wonderplot"}
+
+
+def _numeric(value):
+    return type(value) in (int, float) and isfinite(value)
+
+
+def _js_number(value):
+    """Match JSON.stringify's integer spelling for a finite JS Number."""
+    return int(value) if type(value) is float and isfinite(value) and value.is_integer() else value
+
+
+def _unscaled(value, axis):
+    return 10 ** value if axis.get("scale") == "logarithmic" else value
+
+
+def _format_axis_value(value, axis):
+    if axis.get("scale") == "datetime":
+        timezone_name = (axis.get("dateTime") or {}).get("timeZone")
+        zone = timezone.utc if timezone_name == "utc" else (
+            ZoneInfo(timezone_name) if timezone_name and timezone_name != "browser" else None)
+        text = datetime.fromtimestamp(value / 1000, tz=zone).strftime("%m/%d/%Y, %I:%M %p")
+    else:
+        categories = axis.get("categories") or []
+        index = int(value + .5) - 1
+        if 0 <= index < len(categories):
+            text = str(categories[index])
+        elif _numeric(axis.get("decimals")):
+            text = f"{value:.{int(axis['decimals'])}f}"
+        else:
+            text = str(_js_number(value))
+    return f"{axis.get('labelPrefix', '')}{text}{axis.get('labelSuffix', '')}"
+
+
+def _style(options):
+    defaults = get_defaults("tooltip")
+    base = options.get("style") or {}
+    tooltip_base = base.get("tooltip") or {}
+    interaction = (options.get("interactions") or {}).get("tooltip")
+    interaction = interaction if isinstance(interaction, Mapping) else {}
+    overrides = interaction.get("style") or {}
+    text = {"font": defaults["font"], "color": defaults["textColor"],
+            "lineHeight": defaults["textLineHeight"]}
+    for layer in (base.get("text") or {}, tooltip_base.get("text") or {},
+                  interaction.get("textStyle") or overrides.get("text") or {}):
+        for key in text:
+            if layer.get(key) is not None:
+                text[key] = layer[key]
+    result = {"text": text}
+    for key in ("backgroundColor", "borderColor", "borderWidth", "borderRadius", "padding"):
+        value = defaults[key]
+        for layer in (base if key == "backgroundColor" else {}, tooltip_base,
+                      overrides, interaction):
+            if layer.get(key) is not None:
+                value = layer[key]
+        result[key] = value
+    return result
+
+
+def tooltip_state(options, scene, target):
+    interaction = (options.get("interactions") or {}).get("tooltip")
+    if (not interaction or (isinstance(interaction, Mapping) and interaction.get("enabled") is False)
+            or not isinstance(target, Mapping)):
+        return None
+    trace_index, point_index = target.get("traceIndex"), target.get("pointIndex")
+    if type(trace_index) is not int or type(point_index) is not int or trace_index < 0 or point_index < 0:
+        return None
+    if options.get("type") in {"scatter3d", "line3d", "surface", "mesh3d", "pie3d"}:
+        return _scene3d_tooltip_state(options, scene, target, interaction)
+    if options.get("type") == "pie":
+        return _pie_tooltip_state(options, scene, target, interaction)
+    family = options.get("type")
+    if family not in ("line", "scatter", "bar", "polar", "heatmap", "wonderplot"):
+        return None
+    bindings = resolveTraceSubplotBindings(options)
+    if trace_index >= len(bindings):
+        return None
+    binding = bindings[trace_index]
+    trace = binding["trace"]
+    if trace.get("visible") is False:
+        return None
+    subplot_id = binding["subplotId"]
+    if target.get("subplotId") is not None and target["subplotId"] != subplot_id:
+        return None
+    data = trace.get("data") or []
+    if point_index >= len(data) or not isinstance(data[point_index], Mapping):
+        return None
+    raw = data[point_index]
+    if raw.get("x") is None or raw.get("y") is None:
+        return None
+    primitive = next((item for item in scene.get("primitives", [])
+                      if item.get("traceIndex", 0) == trace_index and item.get("subplot") == subplot_id
+                      and item.get("type") == family), None)
+    if primitive is None:
+        return None
+    bounds = primitive["bounds"]
+    x_axis, y_axis = binding["xAxisId"], binding["yAxisId"]
+    axes = (options.get("axes") or {})
+    x_options = ((axes.get("xAxes") or {}).get(x_axis) or {})
+    y_options = ((axes.get("yAxes") or {}).get(y_axis) or {})
+    x_value = _number(raw["x"], x_options)
+    y_value = _number(raw["y"], y_options)
+    point = None
+    extra = {}
+    if family in ("line", "scatter"):
+        # The source interaction index uses unfiltered original data identities,
+        # then checks transformed values against the active viewport domains.
+        x_domain, _, _ = _axis_domains(options, x_axis, "x")
+        y_domain, _, _ = _axis_domains(options, y_axis, "y")
+        if x_domain is None or y_domain is None:
+            return None
+        try:
+            transformed_x = _scaled(x_value, x_options)
+            transformed_y = _scaled(y_value, y_options)
+        except ValueError:
+            return None
+        if (not x_domain[0] <= transformed_x <= x_domain[1]
+                or not y_domain[0] <= transformed_y <= y_domain[1]):
+            return None
+        if point_index < len(primitive.get("points") or []) and not options.get("viewport"):
+            point = primitive["points"][point_index]
+        else:
+            point = {"x": (transformed_x - x_domain[0]) / (x_domain[1] - x_domain[0]) * (bounds["right"] - bounds["left"]),
+                     "y": (1 - (transformed_y - y_domain[0]) / (y_domain[1] - y_domain[0])) * (bounds["bottom"] - bounds["top"])}
+    elif family == "bar":
+        bar = next((item for index, item in enumerate(primitive.get("bars") or [])
+                    if item.get("sourceIndex", index) == point_index), None)
+        if bar is None:
+            return None
+        point = {"x": bar["x"] + bar["width"] / 2, "y": bar["y"] + bar["height"] / 2}
+        for key in ("normalizedValue", "baseline"):
+            if key in bar:
+                extra[key] = bar[key]
+    elif family == "polar":
+        sector = next((item for index, item in enumerate(primitive.get("polarSectors") or [])
+                       if item.get("sourceIndex", index) == point_index), None)
+        if sector is None:
+            return None
+        midpoint = (sector["startAngle"] + sector["endAngle"]) / 2
+        radius = (sector["innerRadius"] + sector["outerRadius"]) / 2
+        point = {"x": sector["centerX"] + cos(midpoint) * radius,
+                 "y": sector["centerY"] + sin(midpoint) * radius}
+        if (options.get("polar") or {}).get("angleCategories"):
+            x_value = sector["angle"]
+    elif family == "heatmap":
+        cell = next((item for index, item in enumerate(primitive.get("heatmapCells") or [])
+                     if item.get("sourceIndex", index) == point_index and not item.get("missing")), None)
+        if cell is None:
+            return None
+        point = {"x": cell["x"] + cell["width"] / 2, "y": cell["y"] + cell["height"] / 2}
+        x_value, y_value = cell["xValue"], cell["yValue"]
+        for key in ("xCategory", "yCategory"):
+            if key in cell:
+                extra[key] = cell[key]
+        if "value" in raw:
+            extra["value"] = raw["value"]
+        if "z" in raw:
+            extra["z"] = raw["z"]
+        extra["colorValue"] = cell["value"]
+    elif family == "wonderplot":
+        wonder = next((item for index, item in enumerate(primitive.get("wonderPoints") or [])
+                       if item.get("sourceIndex", index) == point_index), None)
+        if wonder is None:
+            return None
+        point = {"x": wonder["x"], "y": wonder["y"]}
+        for raw_key, output in (("value", "value"), ("z", "z"), ("size", "size"),
+                                ("opacity", "opacity")):
+            if raw_key in raw:
+                extra[output] = raw[raw_key]
+        if "value" in raw:
+            extra["colorValue"] = raw["value"]
+        for source_key, output in (("sizeValue", "sizeValue"), ("size", "radius"),
+                                   ("opacityValue", "opacityValue"), ("opacity", "renderedOpacity")):
+            if source_key in wonder:
+                extra[output] = wonder[source_key]
+    values = {"subplotId": subplot_id, "traceIndex": trace_index,
+              "pointIndex": point_index, "xAxisId": x_axis, "yAxisId": y_axis,
+              "x": raw["x"], "y": raw["y"], "xValue": x_value, "yValue": y_value,
+              **extra}
+    if isinstance(trace.get("name"), str):
+        values["traceName"] = trace["name"]
+    if isinstance(primitive.get("color"), str):
+        values["traceColor"] = primitive["color"]
+    tooltip_options = interaction if isinstance(interaction, Mapping) else {}
+    text = f"{x_axis}: {raw['x']} | {y_axis}: {raw['y']}"
+    if family in ("heatmap", "wonderplot") and "value" in raw:
+        text += f" | value: {raw['value']}"
+    if trace.get("name"):
+        text = f"{trace['name']} | {text}"
+    if tooltip_options.get("mode") == "custom" and callable(tooltip_options.get("formatter")):
+        text = tooltip_options["formatter"](deepcopy(values))
+    if tooltip_options.get("shared") and family in ("line", "scatter"):
+        items = [values]
+        for other_index, other in enumerate(bindings):
+            if (other_index == trace_index or other["subplotId"] != subplot_id
+                    or other["xAxisId"] != x_axis
+                    or other["trace"].get("visible") is False):
+                continue
+            other_x_options = ((axes.get("xAxes") or {}).get(other["xAxisId"]) or {})
+            other_y_options = ((axes.get("yAxes") or {}).get(other["yAxisId"]) or {})
+            other_x_domain, _, _ = _axis_domains(options, other["xAxisId"], "x")
+            other_y_domain, _, _ = _axis_domains(options, other["yAxisId"], "y")
+            if other_x_domain is None or other_y_domain is None:
+                continue
+            other_primitive = next((item for item in scene.get("primitives", [])
+                                    if item.get("type") == family and item.get("traceIndex", 0) == other_index
+                                    and item.get("subplot") == subplot_id), None)
+            if other_primitive is None:
+                continue
+            best = None
+            for candidate_index, candidate in enumerate(other["trace"].get("data") or []):
+                if not isinstance(candidate, Mapping) or candidate.get("x") is None or candidate.get("y") is None:
+                    continue
+                other_x = _number(candidate["x"], other_x_options)
+                other_y = _number(candidate["y"], other_y_options)
+                scale = max(1, abs(other_x), abs(x_value))
+                if (tooltip_options.get("sharedXMode") != "nearest"
+                        and abs(other_x - x_value) > float_info.epsilon * scale * 16):
+                    continue
+                transformed_x = _scaled(other_x, other_x_options)
+                transformed_y = _scaled(other_y, other_y_options)
+                if (not other_x_domain[0] <= transformed_x <= other_x_domain[1]
+                        or not other_y_domain[0] <= transformed_y <= other_y_domain[1]):
+                    continue
+                other_point_x = (transformed_x - other_x_domain[0]) / (other_x_domain[1] - other_x_domain[0]) * (bounds["right"] - bounds["left"])
+                other_point_y = (1 - (transformed_y - other_y_domain[0]) / (other_y_domain[1] - other_y_domain[0])) * (bounds["bottom"] - bounds["top"])
+                distance_x = abs(other_point_x - point["x"])
+                distance = hypot(other_point_x - point["x"], other_point_y - point["y"])
+                order = (distance_x, distance, candidate_index)
+                if best is not None and order >= best[0]:
+                    continue
+                other_values = {"subplotId": subplot_id, "traceIndex": other_index,
+                                "pointIndex": candidate_index, "xAxisId": other["xAxisId"],
+                                "yAxisId": other["yAxisId"], "x": candidate["x"],
+                                "y": candidate["y"], "xValue": other_x,
+                                "yValue": other_y}
+                if "name" in other["trace"]:
+                    other_values["traceName"] = other["trace"]["name"]
+                if "color" in other_primitive:
+                    other_values["traceColor"] = other_primitive["color"]
+                best = order, other_values
+            if best is not None:
+                items.append(best[1])
+        items.sort(key=lambda item: item["traceIndex"])
+        values["items"] = deepcopy(items)
+        text = f"{x_axis}: {raw['x']} | " + " | ".join(
+            f"{item.get('traceName') or 'Trace ' + str(item['traceIndex'] + 1)} | {item['yAxisId']}: {item['y']}"
+            for item in items)
+        if tooltip_options.get("mode") == "custom" and callable(tooltip_options.get("formatter")):
+            text = tooltip_options["formatter"](deepcopy(values))
+    return {"active": True, "activeSubplotId": subplot_id,
+            "pointer": {"x": bounds["left"] + point["x"], "y": bounds["top"] + point["y"]},
+            "text": text, "style": _style(options), "values": values}
+
+
+def _scene3d_tooltip_state(options, scene, target, interaction):
+    """Resolve source-indexed 3D primitives without browser-side calculation."""
+    if not isinstance(scene, Mapping):
+        return None
+    family = options.get("type")
+    trace_index, point_index = target["traceIndex"], target["pointIndex"]
+    traces = options.get("traces")
+    if traces is None:
+        traces = [{"data": options.get("data") or []}]
+    if trace_index >= len(traces) or traces[trace_index].get("visible") is False:
+        return None
+    trace = traces[trace_index]
+    for primitive in scene.get("primitives", []):
+        if primitive.get("type") != family or primitive.get("traceIndex", 0) != trace_index:
+            continue
+        subplot_id = primitive.get("subplot", "scene3d")
+        if target.get("subplotId") is not None and target["subplotId"] != subplot_id:
+            continue
+        bounds = primitive.get("bounds") or {}
+        values = {"subplotId": subplot_id, "traceIndex": trace_index,
+                  "pointIndex": point_index, "xAxisId": "x", "yAxisId": "y"}
+        if family == "scatter3d":
+            point = next((item for item in primitive.get("scatter3dPoints") or []
+                          if item.get("sourceIndex") == point_index), None)
+            if point is None:
+                continue
+            pointer = {"x": bounds.get("left", 0) + point["x"],
+                       "y": bounds.get("top", 0) + point["y"]}
+            values.update({"x": point["sourceX"], "y": point["sourceY"],
+                           "xValue": point["sourceX"], "yValue": point["sourceY"],
+                           "z": point["sourceZ"], "renderedColor": point["fillColor"],
+                           "radius": point["radius"], "renderedOpacity": point["opacity"],
+                           "depth": point["depth"]})
+            for point_key, value_key in (("colorValue", "colorValue"), ("sizeValue", "size"),
+                                         ("sizeValue", "sizeValue"), ("opacityValue", "opacity"),
+                                         ("opacityValue", "opacityValue")):
+                if point_key in point:
+                    values[value_key] = point[point_key]
+        elif family == "line3d":
+            segments = [item for item in primitive.get("line3dSegments") or []
+                        if item.get("sourceIndex1") == point_index]
+            if not segments:
+                continue
+            segment = min(segments, key=lambda item: item.get("sourceRatio1", 0))
+            pointer = {"x": bounds.get("left", 0) + segment["x1"],
+                       "y": bounds.get("top", 0) + segment["y1"]}
+            values.update({"x": segment["sourceX1"], "y": segment["sourceY1"],
+                           "xValue": segment["sourceX1"], "yValue": segment["sourceY1"],
+                           "z": segment["sourceZ1"],
+                           "radius": max(get_defaults("line3d")["minimumHitRadius"],
+                                         primitive.get("lineWidth", 0) / 2),
+                           "renderedOpacity": segment.get("opacity", 1),
+                           "depth": segment["depth1"]})
+        else:
+            triangle_key = "surface3dTriangles" if family == "surface" else "mesh3dTriangles"
+            source_key = "sourceCell" if family == "surface" else "sourceFace"
+            triangle = next((item for item in primitive.get(triangle_key) or []
+                             if item[source_key]["index"] == point_index), None)
+            if triangle is None:
+                continue
+            vertices = triangle["vertices"]
+            screen_weights = [1 / 3] * 3
+            metadata = next((item for item in scene.get("scenes3d") or [] if item.get("subplotId") == subplot_id),
+                            scene.get("scene3d") or {})
+            camera = metadata.get("camera") or {}
+            source_weights = screen_weights
+            if camera.get("projection") == "perspective":
+                span = camera["far"] - camera["near"]
+                adjusted = [weight / max(1e-12, camera["near"] + vertex["depth"] * span)
+                            for weight, vertex in zip(screen_weights, vertices)]
+                total = sum(adjusted)
+                source_weights = [weight / total for weight in adjusted]
+            pointer = {"x": bounds.get("left", 0) + sum(vertex["x"] * weight for vertex, weight in zip(vertices, screen_weights)),
+                       "y": bounds.get("top", 0) + sum(vertex["y"] * weight for vertex, weight in zip(vertices, screen_weights))}
+            if family == "pie3d":
+                pie = triangle["pie3d"]
+                values.update({"x": pie["label"], "y": pie["value"],
+                               "xValue": pie["fraction"] * 100, "yValue": pie["value"],
+                               "value": pie["value"]})
+                values["traceColor"] = pie["color"]
+            else:
+                coordinates = {axis: sum(vertex["source" + axis.upper()] * weight
+                                         for vertex, weight in zip(vertices, source_weights))
+                               for axis in "xyz"}
+                values.update({"x": coordinates["x"], "y": coordinates["y"],
+                               "xValue": coordinates["x"], "yValue": coordinates["y"],
+                               "z": coordinates["z"]})
+                values["traceColor"] = triangle["fillColor"]
+            values.update({"radius": 0, "renderedOpacity": triangle["opacity"],
+                           "depth": sum(vertex["depth"] * weight for vertex, weight in zip(vertices, source_weights))})
+        if "name" in trace:
+            values["traceName"] = trace["name"]
+        if "traceColor" not in values and "color" in primitive:
+            values["traceColor"] = primitive["color"]
+        pointer = {key: _js_number(value) for key, value in pointer.items()}
+        values = {key: _js_number(value) for key, value in values.items()}
+        text = f"x: {values['xValue']} | y: {values['yValue']}"
+        if "z" in values:
+            text += f" | z: {values['z']}"
+        if family == "scatter3d":
+            for label, key in (("value", "colorValue"), ("size", "sizeValue"),
+                               ("opacity", "opacityValue")):
+                if key in values:
+                    text += f" | {label}: {values[key]}"
+        if trace.get("name"):
+            text = f"{trace['name']} | {text}"
+        if isinstance(interaction, Mapping) and interaction.get("mode") == "custom" and callable(interaction.get("formatter")):
+            text = interaction["formatter"](deepcopy(values))
+        return {"active": True, "activeSubplotId": subplot_id, "pointer": pointer,
+                "text": text, "style": _style(options), "values": values}
+    return None
+
+
+def _pie_tooltip_state(options, scene, target, interaction):
+    trace_index, point_index = target["traceIndex"], target["pointIndex"]
+    bindings = resolveTraceSubplotBindings(options)
+    for primitive in scene.get("primitives", []):
+        if primitive.get("type") != "pie":
+            continue
+        subplot_id = primitive.get("subplot", "main")
+        if target.get("subplotId") is not None and target["subplotId"] != subplot_id:
+            continue
+        sector = next((item for item in primitive.get("pieSectors") or []
+                       if item.get("traceIndex", 0) == trace_index
+                       and item.get("sourceIndex") == point_index), None)
+        if sector is None:
+            continue
+        if trace_index < len(bindings) and bindings[trace_index]["trace"].get("visible") is False:
+            return None
+        midpoint = sector["startAngle"] + sector.get("sweep", sector["endAngle"] - sector["startAngle"]) / 2
+        radius = (sector["innerRadius"] + sector["outerRadius"]) / 2
+        bounds = primitive["bounds"]
+        pointer = {"x": bounds["left"] + sector["centerX"] + cos(midpoint) * radius,
+                   "y": bounds["top"] + sector["centerY"] + sin(midpoint) * radius}
+        x_axis = bindings[trace_index]["xAxisId"] if trace_index < len(bindings) else "x"
+        y_axis = bindings[trace_index]["yAxisId"] if trace_index < len(bindings) else "y"
+        values = {"subplotId": subplot_id, "traceIndex": trace_index,
+                  "traceColor": sector["color"], "pointIndex": point_index,
+                  "xAxisId": x_axis, "yAxisId": y_axis, "x": sector["label"],
+                  "y": sector["value"], "xValue": sector["fraction"] * 100,
+                  "yValue": sector["value"], "value": sector["value"]}
+        if trace_index < len(bindings) and "name" in bindings[trace_index]["trace"]:
+            values["traceName"] = bindings[trace_index]["trace"]["name"]
+        text = f"{x_axis}: {values['xValue']} | {y_axis}: {values['yValue']}"
+        if values.get("traceName"):
+            text = f"{values['traceName']} | {text}"
+        if isinstance(interaction, Mapping) and interaction.get("mode") == "custom" and callable(interaction.get("formatter")):
+            text = interaction["formatter"](deepcopy(values))
+        return {"active": True, "activeSubplotId": subplot_id, "pointer": pointer,
+                "text": text, "style": _style(options), "values": values}
+    return None
+
+
+def crosshair_state(options, scene, position):
+    interaction = (options.get("interactions") or {}).get("crosshair")
+    if not interaction or not isinstance(position, Mapping) or options.get("type") not in _CARTESIAN - {"pie"}:
+        return None
+    crosshair_options = interaction if isinstance(interaction, Mapping) else {}
+    if crosshair_options.get("enabled") is False:
+        return None
+    bindings = resolveTraceSubplotBindings(options)
+    binding = next((item for item in bindings if item["trace"].get("visible") is not False
+                    and (position.get("activeSubplotId") is None or item["subplotId"] == position["activeSubplotId"])
+                    and (position.get("xAxisId") is None or item["xAxisId"] == position["xAxisId"])
+                    and (position.get("yAxisId") is None or item["yAxisId"] == position["yAxisId"])), None)
+    if binding is None:
+        return None
+    x_domain, _, x_axis = _axis_domains(options, binding["xAxisId"], "x")
+    y_domain, _, y_axis = _axis_domains(options, binding["yAxisId"], "y")
+    if x_domain is None or y_domain is None:
+        return None
+    if options.get("type") == "bar":
+        # Source crosshairs use bar axis domains, including half-slot padding
+        # around categorical positions instead of ordinary line domains.
+        orientation = (options.get("bar") or {}).get("orientation", "vertical")
+        slot_letter = "y" if orientation == "horizontal" else "x"
+        slot_axis = y_axis if slot_letter == "y" else x_axis
+        slot_id = binding["yAxisId"] if slot_letter == "y" else binding["xAxisId"]
+        if slot_axis.get("range") is None:
+            slot_values = []
+            for current in bindings:
+                if (current[slot_letter + "AxisId"] != slot_id
+                        or current["trace"].get("visible") is False):
+                    continue
+                for item in current["trace"].get("data") or []:
+                    if item.get(slot_letter) is not None:
+                        slot_values.append(_scaled(_number(item[slot_letter], slot_axis), slot_axis))
+            slot_values.extend(range(1, len(slot_axis.get("categories") or []) + 1))
+            unique = sorted(set(slot_values))
+            intervals = [right - left for left, right in zip(unique, unique[1:]) if right > left]
+            padding = min(intervals) / 2 if intervals else .5
+            if slot_letter == "x":
+                x_domain = x_domain[0] - padding, x_domain[1] + padding
+            else:
+                y_domain = y_domain[0] - padding, y_domain[1] + padding
+    try:
+        x = _number(position.get("xValue"), x_axis)
+        y = _number(position.get("yValue"), y_axis)
+        x_transformed, y_transformed = _scaled(x, x_axis), _scaled(y, y_axis)
+    except (TypeError, ValueError):
+        return None
+    if x_domain[1] == x_domain[0] or y_domain[1] == y_domain[0]:
+        return None
+    x_ratio = (x_transformed - x_domain[0]) / (x_domain[1] - x_domain[0])
+    y_ratio = (y_transformed - y_domain[0]) / (y_domain[1] - y_domain[0])
+    if not (0 <= x_ratio <= 1 and 0 <= y_ratio <= 1):
+        return None
+    primitive = next((item for item in scene.get("primitives", [])
+                      if item.get("subplot") == binding["subplotId"]), None)
+    if primitive is None:
+        return None
+    bounds = primitive["bounds"]
+    mode = crosshair_options.get("mode", "xy")
+    if mode not in ("x", "y", "xy"):
+        mode = "xy"
+    pointer_x = bounds["left"] + x_ratio * (bounds["right"] - bounds["left"])
+    pointer_y = bounds["bottom"] - y_ratio * (bounds["bottom"] - bounds["top"])
+    if crosshair_options.get("snap") == "nearest":
+        best = None
+        best_distance = float("inf")
+        for trace_index, current in enumerate(bindings):
+            if current["subplotId"] != binding["subplotId"] or current["trace"].get("visible") is False:
+                continue
+            raw_data = current["trace"].get("data") or []
+            for part in scene.get("primitives", []):
+                if (part.get("subplot") != binding["subplotId"]
+                        or part.get("traceIndex", 0) != trace_index
+                        or part.get("type") != options.get("type")
+                        or part.get("trendline") or part.get("bounds") != bounds):
+                    continue
+                candidates = []
+                if options["type"] in ("line", "scatter"):
+                    for index, point in enumerate(part.get("points") or []):
+                        candidates.append((bounds["left"] + point["x"],
+                                           bounds["top"] + point["y"], None, None))
+                elif options["type"] == "bar":
+                    for index, bar in enumerate(part.get("bars") or []):
+                        source_index = bar.get("sourceIndex", index)
+                        if source_index >= len(raw_data):
+                            continue
+                        candidates.append((bounds["left"] + bar["x"] + bar["width"] / 2,
+                                           bounds["top"] + bar["y"] + bar["height"] / 2,
+                                           raw_data[source_index]["x"], raw_data[source_index]["y"]))
+                elif options["type"] == "heatmap":
+                    for cell in part.get("heatmapCells") or []:
+                        if cell.get("missing"):
+                            continue
+                        candidates.append((bounds["left"] + cell["x"] + cell["width"] / 2,
+                                           bounds["top"] + cell["y"] + cell["height"] / 2,
+                                           cell["xValue"], cell["yValue"]))
+                elif options["type"] == "wonderplot":
+                    for index, point in enumerate(part.get("wonderPoints") or []):
+                        source_index = point.get("sourceIndex", index)
+                        if source_index >= len(raw_data):
+                            continue
+                        candidates.append((bounds["left"] + point["x"], bounds["top"] + point["y"],
+                                           raw_data[source_index]["x"], raw_data[source_index]["y"]))
+                for candidate_x, candidate_y, raw_x, raw_y in candidates:
+                    if not (bounds["left"] <= candidate_x <= bounds["right"]
+                            and bounds["top"] <= candidate_y <= bounds["bottom"]):
+                        continue
+                    distance = (abs(pointer_x - candidate_x) if mode == "x" else
+                                abs(pointer_y - candidate_y) if mode == "y" else
+                                hypot(pointer_x - candidate_x, pointer_y - candidate_y))
+                    if distance < best_distance:
+                        best = candidate_x, candidate_y, raw_x, raw_y, current
+                        best_distance = distance
+        if best is None:
+            return None
+        pointer_x, pointer_y, raw_x, raw_y, snapped_binding = best
+        x_axis_id, y_axis_id = snapped_binding["xAxisId"], snapped_binding["yAxisId"]
+        x_axis = ((options.get("axes") or {}).get("xAxes") or {}).get(x_axis_id) or {}
+        y_axis = ((options.get("axes") or {}).get("yAxes") or {}).get(y_axis_id) or {}
+        if raw_x is None or raw_y is None:
+            x = _unscaled(x_domain[0] + (x_domain[1] - x_domain[0])
+                          * (pointer_x - bounds["left"]) / (bounds["right"] - bounds["left"]), x_axis)
+            y = _unscaled(y_domain[0] + (y_domain[1] - y_domain[0])
+                          * (bounds["bottom"] - pointer_y) / (bounds["bottom"] - bounds["top"]), y_axis)
+        else:
+            x, y = _number(raw_x, x_axis), _number(raw_y, y_axis)
+    else:
+        x_axis_id, y_axis_id = binding["xAxisId"], binding["yAxisId"]
+    x_label, y_label = _format_axis_value(x, x_axis), _format_axis_value(y, y_axis)
+    default_label = (f"x: {x_label}" if mode == "x" else
+                     f"y: {y_label}" if mode == "y" else
+                     f"x: {x_label} | y: {y_label}")
+    return {"activeSubplotId": binding["subplotId"], "mode": mode,
+            "snap": crosshair_options.get("snap", "none"),
+            "xAxisId": x_axis_id, "yAxisId": y_axis_id,
+            "xValue": _js_number(x), "yValue": _js_number(y),
+            "xLabel": x_label, "yLabel": y_label, "defaultLabel": default_label,
+            "pointer": {"x": _js_number(pointer_x), "y": _js_number(pointer_y)}}

fastplotpy/point_labels.py

@@ -0,0 +1,86 @@
+"""Line point label resolution and geometry from the source contract."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from decimal import Decimal, ROUND_HALF_UP
+from math import floor, isfinite
+from typing import Mapping
+
+from .defaults import get_defaults
+
+
+def resolve_point_labels(plot_value, trace_value):
+    resolved = dict(get_defaults("point-labels"))
+    for raw in (plot_value, trace_value):
+        if raw is None:
+            continue
+        if isinstance(raw, bool):
+            resolved["show"] = raw
+            continue
+        source = raw if isinstance(raw, Mapping) else {}
+        resolved["show"] = source.get("show", True)
+        for key in ("color", "font"):
+            value = source.get(key)
+            if isinstance(value, str) and value.strip():
+                resolved[key] = value
+        for key in ("lineHeight", "offset", "collisionPadding"):
+            value = source.get(key)
+            if isinstance(value, (int, float)) and not isinstance(value, bool) and isfinite(value) and (value > 0 if key == "lineHeight" else value >= 0):
+                resolved[key] = value
+        position = source.get("position")
+        if position is not None:
+            if position not in ("above", "below", "auto"):
+                raise ValueError("pointLabels.position must be 'above', 'below', or 'auto'")
+            resolved["position"] = position
+        decimals = source.get("decimals")
+        if isinstance(decimals, (int, float)) and not isinstance(decimals, bool) and isfinite(decimals):
+            resolved["decimals"] = max(0, min(12, floor(decimals + .5)))
+        for key in ("prefix", "suffix"):
+            if isinstance(source.get(key), str):
+                resolved[key] = source[key]
+        if callable(source.get("formatter")):
+            resolved["formatter"] = source["formatter"]
+    return resolved
+
+
+def _text(value, axis, labels):
+    if axis.get("scale") == "datetime":
+        date = datetime.fromtimestamp(value / 1000, tz=timezone.utc)
+        format_options = (axis.get("dateTime") or {}).get("format") or {}
+        if format_options == {"year": "numeric"}:
+            number = str(date.year)
+        else:
+            number = date.strftime("%m/%d/%Y, %I:%M %p")
+    elif labels["decimals"] == 0:
+        number = str(floor(value + .5))
+    else:
+        places = labels["decimals"]
+        number = format(Decimal(str(value)).quantize(Decimal(1).scaleb(-places), rounding=ROUND_HALF_UP), f".{places}f")
+    return f"{labels['prefix']}{number}{labels['suffix']}"
+
+
+def build_point_labels(trace, normalized, labels, markers, x_axis, y_axis,
+                       x_domain, y_domain, width, height):
+    if not labels["show"]:
+        return None
+    from .scene import _scaled
+    marker_offset = markers["size"] if markers and markers["show"] else 0
+    output = []
+    for index, point in enumerate(normalized):
+        if point is None:
+            continue
+        x = (_scaled(point["x"], x_axis) - x_domain[0]) / max(x_domain[1] - x_domain[0], 2.220446049250313e-16) * width
+        point_y = (1 - (_scaled(point["y"], y_axis) - y_domain[0]) / max(y_domain[1] - y_domain[0], 2.220446049250313e-16)) * height
+        if not (0 <= x <= width and 0 <= point_y <= height):
+            continue
+        position = labels["position"]
+        if position == "auto":
+            position = "above" if point_y - marker_offset - labels["offset"] - labels["lineHeight"] >= 0 else "below"
+        label = {"x": x, "y": point_y - marker_offset - labels["offset"] if position == "above" else point_y + marker_offset + labels["offset"],
+                 "value": point["y"], "text": _text(point["y"], y_axis, labels),
+                 "color": labels["color"], "font": labels["font"], "lineHeight": labels["lineHeight"],
+                 "position": position, "textBaseline": "bottom" if position == "above" else "top",
+                 "sourceIndex": index, "collisionPadding": labels["collisionPadding"]}
+        output.append(label)
+    return output or None