@fundar/data-chart-telling 0.0.25 → 0.0.27

package/dist/plots/pyramid/ValueLabels.svelte

@@ -1,11 +1,15 @@
 <script lang="ts" generics="TData extends Record<string, unknown>">
-  import { Text } from 'svelteplot';
+  import { Text, usePlot } from 'svelteplot';
   import { resolveAccessor } from '../utils/accessors';
+  import { disabledFillOverride } from '../utils/legendDisabled';
+  import { watchLabelOverflow } from '../utils/labelOverflow.svelte';
   import type { Series } from '../../types/plots/data/common';
-  import type { ValuesStyle } from '../../types/plots/styles/common';
+  import type { ValuesStyle } from '../../types/layout/styles';
   import type { ValueAnchor } from '../../types/plots/constants';
   import type { BarSegmentStyle } from '../../types/plots/segments/common';
   import type { VisualGroup } from '../../types/plots/segments/config';
+  import type { LegendDisabledStyle } from '../../types/layout/legend';
+  import type { MarginOverflow } from '../utils/labelOverflow.svelte';
 
   /**
    * Renders one series' value label on a pyramid bar — anchor-driven default
@@ -16,17 +20,53 @@
   let {
     group,
     valAnchor,
-    fmtVal,
+    formatValue,
     values,
     axisColor,
+    disabled,
+    onHoverSeries,
+    onHoverEnd,
+    onOverflow,
   }: {
     group: VisualGroup<Series<TData> & { side: 'left' | 'right' }, BarSegmentStyle>;
     valAnchor: ValueAnchor;
-    fmtVal: (value: number, seriesName: string) => string;
+    formatValue: (value: number, seriesName: string) => string;
     values: ValuesStyle | undefined;
     axisColor: string;
+    /** Resolved legend/hover-isolate dimming style for this group's series, if any. */
+    disabled?: LegendDisabledStyle;
+    /** Fired when the pointer enters this series' label — only wired when hover-isolate is enabled. */
+    onHoverSeries?: () => void;
+    onHoverEnd?: () => void;
+    /** Reports how far this label overflows the plot's own content box, in pixels, on each side (0 = no overflow). */
+    onOverflow?: (overflow: MarginOverflow) => void;
   } = $props();
 
+  const fillOverride = $derived(disabledFillOverride(disabled));
+  const plot = usePlot();
+  let groupEl: SVGGElement | undefined = $state();
+
+  watchLabelOverflow({
+    el: () => groupEl,
+    bounds: () => {
+      // getBBox() inside isn't itself tracked — depend on whatever actually
+      // changes the rendered label layout so this re-measures.
+      void group;
+      void values;
+      void valAnchor;
+      const xRange = plot.scales.x?.fn?.range?.()?.map(Number);
+      const yRange = plot.scales.y?.fn?.range?.()?.map(Number);
+      if (!xRange || !yRange) return undefined;
+      return {
+        left: Math.min(xRange[0], xRange[1]),
+        right: Math.max(xRange[0], xRange[1]),
+        top: Math.min(yRange[0], yRange[1]),
+        bottom: Math.max(yRange[0], yRange[1]),
+      };
+    },
+    onOverflow: (overflow) => onOverflow?.(overflow),
+  });
+
   const isLeft = $derived(group.series.side === 'left');
   const getCategory = $derived(resolveAccessor(group.series.x));
   const getMagnitude = $derived(resolveAccessor(group.series.y));
@@ -57,24 +97,30 @@
   const resolvedTextAnchor = $derived(font?.textAnchor === 'outside' ? undefined : font?.textAnchor);
 </script>
 
-<Text
-  data={group.series.data}
-  x={xFn}
-  y={getCategory}
-  text={(d: TData) => fmtVal(Math.abs(Number(getMagnitude(d))), group.series.name)}
-  dx={font?.dx ?? defaultDx}
-  dy={font?.dy ?? 0}
-  textAnchor={resolvedTextAnchor ?? defaultTextAnchor}
-  lineAnchor={font?.lineAnchor ?? 'middle'}
-  lineHeight={font?.lineHeight}
-  rotate={font?.rotate}
-  class={font?.class}
-  textClass={font?.textClass}
-  fill={font?.fill ?? axisColor}
-  fontSize={font?.fontSize ?? 12}
-  fontWeight={font?.fontWeight}
-  fontStyle={font?.fontStyle}
-  stroke={font?.stroke}
-  strokeWidth={font?.strokeWidth}
-  paintOrder={font?.paintOrder}
-/>
+<!-- svelteplot's Text mark never wires pointer handlers to its DOM node,
+     despite declaring them in its types — a wrapping <g> catches the
+     boundary crossing instead (pointerenter/leave fire on every ancestor). -->
+<g bind:this={groupEl} role="presentation" onpointerenter={onHoverSeries} onpointerleave={onHoverEnd}>
+  <Text
+    data={group.series.data}
+    x={xFn}
+    y={getCategory}
+    text={(d: TData) => formatValue(Math.abs(Number(getMagnitude(d))), group.series.name)}
+    dx={font?.dx ?? defaultDx}
+    dy={font?.dy ?? 0}
+    textAnchor={resolvedTextAnchor ?? defaultTextAnchor}
+    lineAnchor={font?.lineAnchor ?? 'middle'}
+    lineHeight={font?.lineHeight}
+    rotate={font?.rotate}
+    class={font?.class}
+    textClass={font?.textClass}
+    fill={font?.fill ?? axisColor}
+    fillOpacity={fillOverride?.fillOpacity}
+    fontSize={font?.fontSize ?? 12}
+    fontWeight={font?.fontWeight}
+    fontStyle={font?.fontStyle}
+    stroke={font?.stroke}
+    strokeWidth={font?.strokeWidth}
+    paintOrder={font?.paintOrder}
+  />
+</g>

package/dist/plots/pyramid/ValueLabels.svelte.d.ts

@@ -1,17 +1,26 @@
 import type { Series } from '../../types/plots/data/common';
-import type { ValuesStyle } from '../../types/plots/styles/common';
+import type { ValuesStyle } from '../../types/layout/styles';
 import type { ValueAnchor } from '../../types/plots/constants';
 import type { BarSegmentStyle } from '../../types/plots/segments/common';
 import type { VisualGroup } from '../../types/plots/segments/config';
+import type { LegendDisabledStyle } from '../../types/layout/legend';
+import type { MarginOverflow } from '../utils/labelOverflow.svelte';
 declare function $$render<TData extends Record<string, unknown>>(): {
     props: {
         group: VisualGroup<Series<TData> & {
             side: "left" | "right";
         }, BarSegmentStyle>;
         valAnchor: ValueAnchor;
-        fmtVal: (value: number, seriesName: string) => string;
+        formatValue: (value: number, seriesName: string) => string;
         values: ValuesStyle | undefined;
         axisColor: string;
+        /** Resolved legend/hover-isolate dimming style for this group's series, if any. */
+        disabled?: LegendDisabledStyle;
+        /** Fired when the pointer enters this series' label — only wired when hover-isolate is enabled. */
+        onHoverSeries?: () => void;
+        onHoverEnd?: () => void;
+        /** Reports how far this label overflows the plot's own content box, in pixels, on each side (0 = no overflow). */
+        onOverflow?: (overflow: MarginOverflow) => void;
     };
     exports: {};
     bindings: "";

package/dist/plots/pyramid/buildPyramidBarMarkers.d.ts

@@ -0,0 +1,19 @@
+import type { Series } from '../../types/plots/data/common';
+import type { BarSegmentStyle } from '../../types/plots/segments/common';
+import type { VisualGroup } from '../../types/plots/segments/config';
+import type { BarMarkerConfig } from '../../types/markers/common';
+/**
+ * Every `'bar'` marker for one PyramidPlot render — reuses `BarMarkerConfig`
+ * directly, always horizontal (category on y, signed magnitude on x) and
+ * with no insets. Emits no `role: 'hitArea'` markers, since PyramidPlot's
+ * hover matches nearest points rather than hit-testing category bands.
+ */
+export declare function buildPyramidBarMarkers<TData extends Record<string, unknown>, S extends Series<TData>>(args: {
+    groupedSeries: VisualGroup<S, BarSegmentStyle>[];
+    valueFor: (series: S, d: TData) => number;
+    colorFor: (series: S) => string;
+    disabledFillFor: (seriesName: string) => {
+        fill?: string;
+        fillOpacity?: number;
+    } | undefined;
+}): BarMarkerConfig[];

package/dist/plots/pyramid/buildPyramidBarMarkers.js

@@ -0,0 +1,32 @@
+import { resolveAccessor } from '../utils/accessors';
+/**
+ * Every `'bar'` marker for one PyramidPlot render — reuses `BarMarkerConfig`
+ * directly, always horizontal (category on y, signed magnitude on x) and
+ * with no insets. Emits no `role: 'hitArea'` markers, since PyramidPlot's
+ * hover matches nearest points rather than hit-testing category bands.
+ */
+export function buildPyramidBarMarkers(args) {
+    const { groupedSeries, valueFor, colorFor, disabledFillFor } = args;
+    const markers = [];
+    for (const group of groupedSeries) {
+        const getCategory = resolveAccessor(group.series.x);
+        const defaultColor = colorFor(group.series);
+        const disabledFill = disabledFillFor(group.series.name);
+        for (const seg of group.visualSegments) {
+            markers.push({
+                type: 'bar',
+                role: 'segment',
+                isHorizontal: true,
+                data: seg.data,
+                y: getCategory,
+                x1: 0,
+                x2: (d) => valueFor(group.series, d),
+                style: {
+                    fill: disabledFill?.fill ?? seg.style.fill ?? defaultColor,
+                    fillOpacity: disabledFill?.fillOpacity ?? seg.style.fillOpacity ?? 1,
+                },
+            });
+        }
+    }
+    return markers;
+}

package/dist/plots/scatter/Plot.svelte

@@ -0,0 +1,242 @@
+<script
+  lang="ts"
+  generics="TData extends Record<string, unknown>"
+>
+  import { resolveAccessor } from '../utils/accessors';
+  import { getConfiguration } from '../../configuration/config.svelte';
+  import { paletteColor } from '../../utils/color';
+  import { buildSeries } from '../../utils/grouping';
+  import { getLegendInteraction } from '../../layout/legend/interaction.svelte';
+  import { disabledDotsOverride } from '../utils/legendDisabled';
+  import { buildScatterMarkers } from './buildScatterMarkers';
+  import { resolveRadiusPaddedDomain } from './resolveRadiusPaddedDomain';
+  import { createLabelMarginTracker } from '../utils/labelOverflow.svelte';
+  import BasePlotLayout from '../../layout/plot/BasePlotLayout.svelte';
+  import ValueLabels from './ValueLabels.svelte';
+  import { hasHoverMarker, resolveHoverStrategy, resolveHoverSync } from '../../layout/tooltip/utils';
+  import { buildGroupedSeries, validateSegments, buildScopedMarkerGroups } from '../utils/segments';
+  import { numericMargin } from '../../layout/plot/margins';
+  import type { BasePlotProps } from '../../types/plots/props';
+  import type { AxisValue, AxisBasedScalesConfig } from '../../types/layout/scales';
+  import type { Series } from '../../types/plots/data/common';
+  import type { ScatterDataProps } from '../../types/plots/data/scatter';
+  import type { BasePlotStylesConfig } from '../../types/layout/styles';
+  import type { ScatterSegmentStyle } from '../../types/plots/segments/common';
+  import type { AxisBasedMarkersConfig } from '../../types/markers/common';
+  import type { LegendDisabledStyle } from '../../types/layout/legend';
+
+  /**
+   * A point cloud on continuous x/y axes. Accepts either a pre-built `series`
+   * array or flat `data/x/y/z` props — mirrors the line/bar plot contract so
+   * the chart-level container/timeline/facet/legend wrap it unchanged. `r`
+   * gives every dot a per-row radius (bubble sizing), independent of `z`
+   * grouping/coloring — see {@link ScatterDataProps} for its auto-scaling
+   * behavior.
+   */
+  type Props = BasePlotProps<
+    ScatterDataProps<TData>,
+    TData,
+    BasePlotStylesConfig,
+    ScatterSegmentStyle,
+    AxisBasedMarkersConfig,
+    AxisBasedScalesConfig<TData>
+  >;
+
+  let {
+    width,
+    height,
+    series,
+    data,
+    x,
+    y,
+    z,
+    r,
+    styles = {},
+    segments = {},
+    markers = [],
+    scales = {},
+    margins,
+    tooltip = undefined,
+  }: Props = $props();
+
+  const resolvedSeries = $derived(series ?? buildSeries(data!, x!, y!, z));
+  const legendInteraction = $derived(getLegendInteraction());
+
+  $effect(() => { validateSegments(segments); });
+
+  // A scatter point cloud is discrete (no connecting line), so adjacent
+  // segments never need a bridge point at their boundary — see
+  // buildGroupedSeries's own doc.
+  const groupedSeries = $derived(
+    buildGroupedSeries<Series<TData>, ScatterSegmentStyle>(resolvedSeries, segments, false),
+  );
+
+  const cfg = $derived(getConfiguration());
+  const showVals = $derived(styles.values?.show ?? false);
+  const formatValue = $derived(styles.values?.format ?? ((v: number) => `${v}`));
+  const hoverIsolate = $derived(styles.values?.hoverIsolate ?? false);
+
+  // A value label hovered while `styles.values.hoverIsolate` is on dims
+  // every other series exactly like a legend toggle would — local to this
+  // one `<Plot>` instance (not the shared HoverStore) so the gesture can't
+  // leak into unrelated tooltip/crosshair behavior.
+  let hoverIsolatedSeries = $state<string | null>(null);
+
+  function effectiveDisabledFor(name: string): LegendDisabledStyle | undefined {
+    return (
+      legendInteraction?.disabledSeries.get(name) ??
+      (hoverIsolate && hoverIsolatedSeries && hoverIsolatedSeries !== name
+        ? { opacity: cfg.legend.disabledOpacity }
+        : undefined)
+    );
+  }
+
+  const xAcc = $derived(resolveAccessor(resolvedSeries[0]?.x ?? ((d: TData) => d)));
+  const yAcc = $derived(resolveAccessor(resolvedSeries[0]?.y ?? ((d: TData) => d)));
+  const flat = $derived(resolvedSeries.flatMap((s) => s.data));
+
+  // A legend-disabled series is dimmed on the mark itself, but never surfaces
+  // in hover/tooltip — its points are simply absent from the candidate list.
+  const hoverPoints = $derived(
+    resolvedSeries.flatMap((s, idx) => {
+      if (legendInteraction?.disabledSeries.has(s.name)) return [];
+      const sx = resolveAccessor(s.x);
+      const sy = resolveAccessor(s.y);
+      return s.data.map((d) => ({
+        x: sx(d) as AxisValue,
+        y: Number(sy(d)),
+        row: d,
+        label: `${sx(d)}, ${sy(d)}`,
+        series: s.name,
+        color: paletteColor(idx, cfg.palette),
+      }));
+    }),
+  );
+
+  // Points scatter freely across x/y rather than sharing discrete x values —
+  // 'punctual' matches the single nearest point, not a whole column.
+  const hover = $derived({
+    active: tooltip != null || hasHoverMarker(markers),
+    points: hoverPoints,
+    label: (row: TData) => `${xAcc(row)}, ${yAcc(row)}`,
+    strategy: resolveHoverStrategy(tooltip?.strategy, markers, 'punctual'),
+    sync: resolveHoverSync(tooltip?.sync, markers),
+    tooltip,
+  });
+
+  const scatterMarkers = $derived(
+    buildScatterMarkers({
+      groupedSeries,
+      r,
+      disabledDotsFor: (name) => disabledDotsOverride(effectiveDisabledFor(name)),
+    }),
+  );
+
+  const scopedGroups = $derived(
+    buildScopedMarkerGroups<TData, Series<TData>, ScatterSegmentStyle>({
+      groupedSeries,
+      segments,
+      colorFor: (_series, seriesIndex) => paletteColor(seriesIndex, cfg.palette),
+      segmentColorFor: (style, defaultColor) => style?.dotFill ?? defaultColor,
+    }),
+  );
+
+  // svelteplot treats a per-row `r` (a field key or accessor function) as a
+  // proper channel bound to its own auto sqrt scale — the raw values it
+  // returns (e.g. a population in the millions) are data, not pixels, and
+  // get compressed into a modest, roughly data-magnitude-independent pixel
+  // range regardless of how large the raw numbers are. A literal constant
+  // `r` (or the theme/segment `dotRadius` fallback), by contrast, *is*
+  // already a literal pixel value. `AUTO_SCALED_RADIUS_ESTIMATE` stands in
+  // for whatever svelteplot's own r-scale ends up rendering at, since the
+  // real value isn't knowable until that scale is built.
+  const AUTO_SCALED_RADIUS_ESTIMATE = 20;
+
+  // The largest radius any dot actually renders at — pads the scale domain
+  // below so a point at the data extreme doesn't get its own circle clipped
+  // by the frame. svelteplot's own 'auto' margin only measures axis chrome,
+  // never mark geometry.
+  const maxDotRadius = $derived.by(() => {
+    let max = 0;
+    for (const marker of scatterMarkers) {
+      const rConst = typeof marker.r === 'number' ? marker.r : undefined;
+      const isChannel = typeof marker.r === 'function';
+      const fallbackR = marker.style?.dotRadius ?? cfg.scatter.dotRadius;
+      if (rConst !== undefined) {
+        max = Math.max(max, rConst);
+      } else if (isChannel) {
+        max = Math.max(max, AUTO_SCALED_RADIUS_ESTIMATE);
+      } else {
+        max = Math.max(max, fallbackR);
+      }
+    }
+    return max;
+  });
+
+  // Best-effort pre-render estimate of the plot's own inner content size —
+  // the real size isn't known until svelteplot measures its own axis
+  // chrome, so this is only used to convert a pixel radius into a domain
+  // padding amount, not as the actual rendered margin.
+  const estimatedMargins = $derived({ ...cfg.margins, ...margins });
+  const estimatedInnerWidth = $derived(
+    width - numericMargin('left', estimatedMargins.left) - numericMargin('right', estimatedMargins.right),
+  );
+  const estimatedInnerHeight = $derived(
+    height - numericMargin('top', estimatedMargins.top) - numericMargin('bottom', estimatedMargins.bottom),
+  );
+
+  const resolvedScales = $derived.by((): AxisBasedScalesConfig<TData> => {
+    if (maxDotRadius <= 0) return scales;
+    const xValues = flat.map((d) => Number(xAcc(d)));
+    const yValues = flat.map((d) => Number(yAcc(d)));
+    const paddedX = scales.x?.domain
+      ? undefined
+      : resolveRadiusPaddedDomain(xValues, maxDotRadius, estimatedInnerWidth);
+    const paddedY = scales.y?.domain
+      ? undefined
+      : resolveRadiusPaddedDomain(yValues, maxDotRadius, estimatedInnerHeight);
+    if (!paddedX && !paddedY) return scales;
+    return {
+      ...scales,
+      x: paddedX ? { ...scales.x, domain: paddedX } : scales.x,
+      y: paddedY ? { ...scales.y, domain: paddedY } : scales.y,
+    };
+  });
+
+  // A scatter point's value label can grow past the plot's own content box
+  // (e.g. a point volcado toward a corner, past what its own edge-aware flip
+  // can fit) — reserving real space there is what each label's own overflow
+  // measurement feeds into here, via a tracker local to this one `<Plot>`
+  // instance. See `labelOverflow.svelte.ts`.
+  const labelMargin = createLabelMarginTracker(() => margins);
+</script>
+
+<BasePlotLayout
+  {width}
+  {height}
+  {styles}
+  data={flat}
+  getX={xAcc}
+  getY={(d) => Number(yAcc(d))}
+  {hover}
+  scales={resolvedScales}
+  margins={labelMargin.resolvedMargins}
+  markers={[...scatterMarkers, ...markers]}
+  seriesData={resolvedSeries}
+  {scopedGroups}
+>
+  {#if showVals}
+    {#each groupedSeries as group (group.series.name)}
+      <ValueLabels
+        {group}
+        {formatValue}
+        values={styles.values}
+        defaultColor={cfg.axis.color}
+        disabled={effectiveDisabledFor(group.series.name)}
+        onHoverSeries={hoverIsolate ? () => { hoverIsolatedSeries = group.series.name; } : undefined}
+        onHoverEnd={hoverIsolate ? () => { hoverIsolatedSeries = null; } : undefined}
+        onOverflow={labelMargin.report}
+      />
+    {/each}
+  {/if}
+</BasePlotLayout>

package/dist/{layout/plot/GridLayout.svelte.d.ts → plots/scatter/Plot.svelte.d.ts}

@@ -1,8 +1,10 @@
-import type { AxisBasedScalesConfig } from '../../types/plots/props';
+import type { BasePlotProps } from '../../types/plots/props';
+import type { AxisBasedScalesConfig } from '../../types/layout/scales';
+import type { ScatterDataProps } from '../../types/plots/data/scatter';
+import type { BasePlotStylesConfig } from '../../types/layout/styles';
+import type { AxisBasedMarkersConfig } from '../../types/markers/common';
 declare function $$render<TData extends Record<string, unknown>>(): {
-    props: {
-        scales?: AxisBasedScalesConfig<TData>;
-    };
+    props: BasePlotProps<ScatterDataProps<TData>, TData, BasePlotStylesConfig, import("../..").DotStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
     exports: {};
     bindings: "";
     slots: {};
@@ -22,6 +24,6 @@ interface $$IsomorphicComponent {
     <TData extends Record<string, unknown>>(internal: unknown, props: ReturnType<__sveltets_Render<TData>['props']> & {}): ReturnType<__sveltets_Render<TData>['exports']>;
     z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
 }
-declare const GridLayout: $$IsomorphicComponent;
-type GridLayout<TData extends Record<string, unknown>> = InstanceType<typeof GridLayout<TData>>;
-export default GridLayout;
+declare const Plot: $$IsomorphicComponent;
+type Plot<TData extends Record<string, unknown>> = InstanceType<typeof Plot<TData>>;
+export default Plot;

package/dist/plots/scatter/ValueLabels.svelte

@@ -0,0 +1,149 @@
+<script lang="ts" generics="TData extends Record<string, unknown>">
+  import { Text, usePlot } from 'svelteplot';
+  import { SvelteMap } from 'svelte/reactivity';
+  import { resolveAccessor } from '../utils/accessors';
+  import { disabledFillOverride } from '../utils/legendDisabled';
+  import { watchLabelOverflow } from '../utils/labelOverflow.svelte';
+  import { resolveEdgeAwareAnchor, estimateTextWidth } from '../../utils/edgeAwareAnchor';
+  import type { Series } from '../../types/plots/data/common';
+  import type { ValuesStyle } from '../../types/layout/styles';
+  import type { ScatterSegmentStyle } from '../../types/plots/segments/common';
+  import type { VisualGroup } from '../../types/plots/segments/config';
+  import type { LegendDisabledStyle } from '../../types/layout/legend';
+  import type { MarginOverflow } from '../utils/labelOverflow.svelte';
+
+  /**
+   * Renders one series' point value labels — one `<Text>` mark per series
+   * (mirrors line/bar/pyramid's own `ValueLabels`), so a legend-disabled or
+   * hover-isolated series can carry its own constant `fillOpacity`. Labels
+   * the Y value, matching the "Y is the value axis" convention every other
+   * plot kind uses. Placement is edge-aware: a label whose default
+   * anchor/offset would push it past the plot's own content box flips to
+   * the opposite side instead of clipping — `onOverflow` below is a second,
+   * coarser line of defense for whatever the flip still can't fit (e.g. a
+   * corner point with no room in any direction).
+   */
+  let {
+    group,
+    formatValue,
+    values,
+    defaultColor,
+    disabled,
+    onHoverSeries,
+    onHoverEnd,
+    onOverflow,
+  }: {
+    group: VisualGroup<Series<TData>, ScatterSegmentStyle>;
+    formatValue: (value: number, seriesName: string) => string;
+    values: ValuesStyle | undefined;
+    defaultColor: string;
+    /** Resolved legend/hover-isolate dimming style for this group's series, if any. */
+    disabled?: LegendDisabledStyle;
+    /** Fired when the pointer enters this series' label — only wired when hover-isolate is enabled. */
+    onHoverSeries?: () => void;
+    onHoverEnd?: () => void;
+    /** Reports how far this series' labels overflow the plot's own content box, in pixels, on each side (0 = no overflow). */
+    onOverflow?: (overflow: MarginOverflow) => void;
+  } = $props();
+
+  const data = $derived(group.series.data);
+  const getX = $derived(resolveAccessor(group.series.x));
+  const getY = $derived(resolveAccessor(group.series.y));
+  const plot = usePlot();
+  let groupEl: SVGGElement | undefined = $state();
+
+  watchLabelOverflow({
+    el: () => groupEl,
+    bounds: () => {
+      // getBBox() inside isn't itself tracked — depend on whatever actually
+      // changes the rendered label layout so this re-measures.
+      void data;
+      void values;
+      const xRange = plot.scales.x?.fn?.range?.()?.map(Number);
+      const yRange = plot.scales.y?.fn?.range?.()?.map(Number);
+      if (!xRange || !yRange) return undefined;
+      return {
+        left: Math.min(xRange[0], xRange[1]),
+        right: Math.max(xRange[0], xRange[1]),
+        top: Math.min(yRange[0], yRange[1]),
+        bottom: Math.max(yRange[0], yRange[1]),
+      };
+    },
+    onOverflow: (overflow) => onOverflow?.(overflow),
+  });
+
+  const font = $derived(values?.fontStyle);
+  const preferredTextAnchor = $derived(
+    font?.textAnchor === 'outside' || font?.textAnchor === undefined ? 'start' : font.textAnchor,
+  );
+  const preferredLineAnchor = $derived(font?.lineAnchor ?? 'middle');
+  const gapX = $derived(Math.abs(font?.dx ?? 8));
+  const gapY = $derived(Math.abs(font?.dy ?? 0));
+  const fontSize = $derived(typeof font?.fontSize === 'number' ? font.fontSize : 11);
+  const fillOverride = $derived(disabledFillOverride(disabled));
+
+  function textOf(d: TData): string {
+    return formatValue(Number(getY(d)), group.series.name);
+  }
+
+  /** One placement per row, keyed by row reference — avoids recomputing the same scale/edge lookup for each of the four accessor channels below. */
+  const placements = $derived.by(() => {
+    const map = new SvelteMap<TData, ReturnType<typeof resolveEdgeAwareAnchor>>();
+    const xFn = plot.scales.x?.fn;
+    const yFn = plot.scales.y?.fn;
+    if (!xFn || !yFn) return map;
+    for (const d of data) {
+      const px = Number(xFn(getX(d) as never));
+      const py = Number(yFn(getY(d) as never));
+      const text = textOf(d);
+      map.set(
+        d,
+        resolveEdgeAwareAnchor({
+          px,
+          py,
+          width: plot.plotWidth,
+          height: plot.plotHeight,
+          textAnchor: preferredTextAnchor,
+          lineAnchor: preferredLineAnchor,
+          gapX,
+          gapY,
+          // Rough average glyph width — these labels are short numeric/formatted strings, not measured DOM text.
+          extent: { width: estimateTextWidth(text, fontSize), height: fontSize * 1.2 },
+        }),
+      );
+    }
+    return map;
+  });
+</script>
+
+<!-- svelteplot's Text mark never wires pointer handlers to its DOM node,
+     despite declaring them in its types — a wrapping <g> catches the
+     boundary crossing instead (pointerenter/leave fire on every ancestor). -->
+<g bind:this={groupEl} role="presentation" onpointerenter={onHoverSeries} onpointerleave={onHoverEnd}>
+  <Text
+    {data}
+    x={getX}
+    y={getY}
+    text={(d: TData) => textOf(d)}
+    fill={font?.fill ?? defaultColor}
+    fillOpacity={fillOverride?.fillOpacity}
+    {fontSize}
+    fontWeight={font?.fontWeight ?? 500}
+    fontStyle={font?.fontStyle}
+    textAnchor={(d: TData) => placements.get(d)?.textAnchor ?? preferredTextAnchor}
+    lineAnchor={
+      // svelteplot's own `lineAnchor` accessor type isn't parameterized over the mark's row type like its siblings are.
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (d: any) => placements.get(d)?.lineAnchor ?? preferredLineAnchor
+    }
+    dx={(d: TData) => placements.get(d)?.dx ?? gapX}
+    dy={(d: TData) => placements.get(d)?.dy ?? gapY}
+    lineHeight={font?.lineHeight}
+    rotate={font?.rotate}
+    stroke={font?.stroke}
+    strokeWidth={font?.strokeWidth}
+    paintOrder={font?.paintOrder}
+    class={font?.class}
+    textClass={font?.textClass}
+  />
+</g>

package/dist/plots/{bar/BarSegments.svelte.d.ts → scatter/ValueLabels.svelte.d.ts}

@@ -1,20 +1,22 @@
-import { BarX, BarY } from 'svelteplot';
 import type { Series } from '../../types/plots/data/common';
-import type { BarSegmentStyle } from '../../types/plots/segments/common';
+import type { ValuesStyle } from '../../types/layout/styles';
+import type { ScatterSegmentStyle } from '../../types/plots/segments/common';
 import type { VisualGroup } from '../../types/plots/segments/config';
-import type { BarLayout } from './layout.svelte';
+import type { LegendDisabledStyle } from '../../types/layout/legend';
+import type { MarginOverflow } from '../utils/labelOverflow.svelte';
 declare function $$render<TData extends Record<string, unknown>>(): {
     props: {
-        group: VisualGroup<Series<TData>, BarSegmentStyle>;
-        seriesIndex: number;
-        barLayout: BarLayout<TData>;
-        isHorizontal: boolean;
-        BarMark: typeof BarX | typeof BarY;
+        group: VisualGroup<Series<TData>, ScatterSegmentStyle>;
+        formatValue: (value: number, seriesName: string) => string;
+        values: ValuesStyle | undefined;
         defaultColor: string;
-        disabledFill?: {
-            fill?: string;
-            fillOpacity?: number;
-        };
+        /** Resolved legend/hover-isolate dimming style for this group's series, if any. */
+        disabled?: LegendDisabledStyle;
+        /** Fired when the pointer enters this series' label — only wired when hover-isolate is enabled. */
+        onHoverSeries?: () => void;
+        onHoverEnd?: () => void;
+        /** Reports how far this series' labels overflow the plot's own content box, in pixels, on each side (0 = no overflow). */
+        onOverflow?: (overflow: MarginOverflow) => void;
     };
     exports: {};
     bindings: "";
@@ -35,6 +37,6 @@ interface $$IsomorphicComponent {
     <TData extends Record<string, unknown>>(internal: unknown, props: ReturnType<__sveltets_Render<TData>['props']> & {}): ReturnType<__sveltets_Render<TData>['exports']>;
     z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
 }
-declare const BarSegments: $$IsomorphicComponent;
-type BarSegments<TData extends Record<string, unknown>> = InstanceType<typeof BarSegments<TData>>;
-export default BarSegments;
+declare const ValueLabels: $$IsomorphicComponent;
+type ValueLabels<TData extends Record<string, unknown>> = InstanceType<typeof ValueLabels<TData>>;
+export default ValueLabels;