matterviz 0.4.1 → 0.4.3

package/dist/plot/box/BoxPlot.svelte

@@ -2,7 +2,7 @@
   lang="ts"
   generics="Metadata extends Record<string, unknown> = Record<string, unknown>"
 >
-  import { format_value } from '../../labels'
+  import { format_value_or_num } from '../../labels'
   import { FullscreenToggle, set_fullscreen_bg } from '../../layout'
   import type { Vec2 } from '../../math'
   import type {
@@ -28,8 +28,17 @@
     compute_element_placement,
     PlotAxis,
     PlotLegend,
+    PlotMarginals,
     ReferenceLine,
   } from '..'
+  import type { MarginalSeriesInput, MarginalsProp } from '../core/marginals'
+  import {
+    add_sides,
+    marginal_axis,
+    marginal_axis_presence,
+    normalize_marginals,
+    reserve_marginal_pad,
+  } from '../core/marginals'
   import {
     build_obstacles_norm,
     clip_bar,
@@ -49,7 +58,9 @@
     resolve_axis_ranges,
   } from '../core/interactions'
   import {
+    AXIS_TITLE_OFFSET,
     calc_auto_padding,
+    DEFAULT_PLOT_PADDING,
     filter_padding,
     LABEL_GAP_DEFAULT,
     y2_axis_label_x,
@@ -59,7 +70,7 @@
   import type { IndexedRefLine } from '../core/reference-line'
   import { group_ref_lines_by_z, index_ref_lines } from '../core/reference-line'
   import {
-    create_scale,
+    create_axis_scales,
     generate_ticks,
     get_nice_data_range,
     get_tick_label,
@@ -114,8 +125,8 @@
     y_axis = $bindable({}),
     y2_axis: y2_axis_prop = $bindable({}),
     display = $bindable(DEFAULTS.box.display),
-    range_padding = 0.05,
-    padding = { t: 20, b: 60, l: 60, r: 20 },
+    range_padding = 0,
+    padding = DEFAULT_PLOT_PADDING,
     legend = {},
     show_legend,
     box = {},
@@ -129,7 +140,7 @@
     show_mean = $bindable(DEFAULTS.box.show_mean),
     show_value_labels = false,
     value_label_stat = `median`,
-    value_label_format = `.3~s`,
+    value_label_format = ``,
     kind = $bindable(DEFAULTS.box.kind),
     side = $bindable(DEFAULTS.box.side),
     bandwidth = DEFAULTS.box.bandwidth,
@@ -158,51 +169,55 @@
     header_controls,
     controls_extra,
     pan = {},
+    marginals = false,
     ...rest
-  }: HTMLAttributes<HTMLDivElement> & BasePlotProps & PlotConfig & {
-    series?: BoxPlotSeries<Metadata>[]
-    orientation?: Orientation
-    legend?: LegendConfig | null
-    show_legend?: boolean
-    box?: BoxStyle
-    whisker?: WhiskerStyle
-    median_style?: BoxLineStyle
-    outlier_style?: OutlierStyle
-    whisker_mode?: WhiskerMode
-    whisker_range?: number
-    whisker_percentiles?: Vec2
-    show_outliers?: boolean
-    show_mean?: boolean
-    show_value_labels?: boolean
-    value_label_stat?: `median` | `mean`
-    value_label_format?: string
-    kind?: ViolinKind
-    side?: ViolinSide
-    bandwidth?: BandwidthOption
-    violin_width?: number
-    violin_style?: ViolinStyle
-    kde_points?: number
-    kde_cut?: number
-    kde_max_samples?: number
-    kde_clip?: [number | null, number | null]
-    tooltip?: Snippet<[BoxHandlerProps<Metadata>]>
-    user_content?: Snippet<[UserContentProps]>
-    header_controls?: Snippet<[{ height: number; width: number; fullscreen: boolean }]>
-    controls_extra?: Snippet<[{ orientation: Orientation } & Required<PlotConfig>]>
-    change?: (data: BoxHandlerProps<Metadata> | null) => void
-    on_box_click?: (
-      data: BoxHandlerProps<Metadata> & { event: MouseEvent | KeyboardEvent },
-    ) => void
-    on_box_hover?: (
-      data:
-        | (BoxHandlerProps<Metadata> & { event: MouseEvent | FocusEvent | KeyboardEvent })
-        | null,
-    ) => void
-    ref_lines?: RefLine[]
-    on_ref_line_click?: (event: RefLineEvent) => void
-    on_ref_line_hover?: (event: RefLineEvent | null) => void
-    pan?: PanConfig
-  } = $props()
+  }: HTMLAttributes<HTMLDivElement> &
+    BasePlotProps &
+    PlotConfig & {
+      series?: BoxPlotSeries<Metadata>[]
+      orientation?: Orientation
+      legend?: LegendConfig | null
+      show_legend?: boolean
+      box?: BoxStyle
+      whisker?: WhiskerStyle
+      median_style?: BoxLineStyle
+      outlier_style?: OutlierStyle
+      whisker_mode?: WhiskerMode
+      whisker_range?: number
+      whisker_percentiles?: Vec2
+      show_outliers?: boolean
+      show_mean?: boolean
+      show_value_labels?: boolean
+      value_label_stat?: `median` | `mean`
+      value_label_format?: string
+      kind?: ViolinKind
+      side?: ViolinSide
+      bandwidth?: BandwidthOption
+      violin_width?: number
+      violin_style?: ViolinStyle
+      kde_points?: number
+      kde_cut?: number
+      kde_max_samples?: number
+      kde_clip?: [number | null, number | null]
+      tooltip?: Snippet<[BoxHandlerProps<Metadata>]>
+      user_content?: Snippet<[UserContentProps]>
+      header_controls?: Snippet<[{ height: number; width: number; fullscreen: boolean }]>
+      controls_extra?: Snippet<[{ orientation: Orientation } & Required<PlotConfig>]>
+      change?: (data: BoxHandlerProps<Metadata> | null) => void
+      on_box_click?: (
+        data: BoxHandlerProps<Metadata> & { event: MouseEvent | KeyboardEvent },
+      ) => void
+      on_box_hover?: (
+        data:
+          | (BoxHandlerProps<Metadata> & { event: MouseEvent | FocusEvent | KeyboardEvent })
+          | null,
+      ) => void
+      ref_lines?: RefLine[]
+      on_ref_line_click?: (event: RefLineEvent) => void
+      on_ref_line_hover?: (event: RefLineEvent | null) => void
+      pan?: PanConfig
+      marginals?: MarginalsProp
+    } = $props()
 
   let box_state = $derived({ ...DEFAULTS.box.box, ...box })
   let whisker_state = $derived({ ...DEFAULTS.box.whisker, ...whisker })
@@ -212,24 +227,20 @@
 
   // Merge secondary-axis defaults as deriveds instead of assigning back into the
   // $bindable props (which would push library defaults into the parent's bound state)
-  let y2_axis = $derived(
-    {
-      format: ``,
-      scale_type: `linear`,
-      ticks: 5,
-      range: [null, null],
-      ...y2_axis_prop,
-    } as typeof y2_axis_prop,
-  )
-  let x2_axis = $derived(
-    {
-      format: ``,
-      scale_type: `linear`,
-      ticks: 5,
-      range: [null, null],
-      ...x2_axis_prop,
-    } as typeof x2_axis_prop,
-  )
+  let y2_axis = $derived({
+    format: ``,
+    scale_type: `linear`,
+    ticks: 5,
+    range: [null, null],
+    ...y2_axis_prop,
+  } as typeof y2_axis_prop)
+  let x2_axis = $derived({
+    format: ``,
+    scale_type: `linear`,
+    ticks: 5,
+    range: [null, null],
+    ...x2_axis_prop,
+  } as typeof x2_axis_prop)
 
   let [width, height] = $state([0, 0])
   let wrapper: HTMLDivElement | undefined = $state()
@@ -256,7 +267,7 @@
         whisker_range: srs.whisker_range ?? whisker_range,
         whisker_percentiles: srs.whisker_percentiles ?? whisker_percentiles,
         collect_outliers: show_outliers && draws_box(srs) && (srs.visible ?? true),
-      })
+      }),
     ),
   )
 
@@ -309,9 +320,8 @@
   // KDE per visible violin series, keyed by series index (bandwidth from the full sample)
   let violin_kdes = $derived.by(() => {
     const map = new SvelteMap<number, KdeResult>()
-    const [val_axis, val_axis2] = orientation === `vertical`
-      ? [y_axis, y2_axis]
-      : [x_axis, x2_axis]
+    const [val_axis, val_axis2] =
+      orientation === `vertical` ? [y_axis, y2_axis] : [x_axis, x2_axis]
     for (const box_item of visible_boxes) {
       if (!draws_violin(box_item.series)) continue
       const samples = box_item.series.y ?? []
@@ -319,7 +329,10 @@
       // On a log value axis the KDE grid tail (data_min - cut*bandwidth) is usually <= 0 →
       // NaN pixels + LOG_EPS range pollution. Clamp the grid to the smallest positive sample.
       if ((is_secondary(box_item.series) ? val_axis2 : val_axis).scale_type === `log`) {
-        const min_pos = samples.reduce((min, val) => (val > 0 && val < min ? val : min), Infinity)
+        const min_pos = samples.reduce(
+          (min, val) => (val > 0 && val < min ? val : min),
+          Infinity,
+        )
         // Guard: no positive samples → min_pos is Infinity; leave clip unchanged so the KDE
         // never receives a non-finite lower bound
         if (Number.isFinite(min_pos)) {
@@ -343,7 +356,11 @@
   // The horizontal category pixel axis is inverted, so flip the half-violin side to keep
   // `positive` meaning "above the center line" (vertical/`both` pass through unchanged)
   const to_screen_side = (eff_side: ViolinSide, vertical: boolean): ViolinSide =>
-    vertical || eff_side === `both` ? eff_side : eff_side === `positive` ? `negative` : `positive`
+    vertical || eff_side === `both`
+      ? eff_side
+      : eff_side === `positive`
+        ? `negative`
+        : `positive`
 
   // Peak density per violin, computed once on data change (avoids spreading kde.density into
   // Math.max — unsafe for large kde_points — and re-deriving it on every render/hover).
@@ -360,8 +377,15 @@
   // Which boxes live on the secondary value axis (y2 for vertical, x2 for horizontal)
   const is_secondary = (srs: BoxPlotSeries<Metadata>): boolean =>
     orientation === `vertical` ? srs.y_axis === `y2` : srs.x_axis === `x2`
-  let secondary_boxes = $derived(visible_boxes.filter((box_item) => is_secondary(box_item.series)))
+  let secondary_boxes = $derived(
+    visible_boxes.filter((box_item) => is_secondary(box_item.series)),
+  )
   let has_secondary = $derived(secondary_boxes.length > 0)
+  // The secondary value axis renders transposed by orientation: x2 (top) when horizontal, y2
+  // (right) when vertical. Derive once so axis rendering, ticks, range writes, point picking, and
+  // marginal placement all stay provably in sync.
+  let show_x2 = $derived(has_secondary && orientation === `horizontal`)
+  let show_y2 = $derived(has_secondary && orientation === `vertical`)
 
   // Collect value-axis points (whiskers, quartiles, outliers, KDE tails) for auto-range
   const value_points = (boxes: Box[]): { x: number; y: number }[] =>
@@ -407,8 +431,8 @@
     )
 
     return vertical
-      ? ({ x: cat_range, x2: [0, 1] as Vec2, y: value_primary, y2: value_secondary })
-      : ({ x: value_primary, x2: value_secondary, y: cat_range, y2: [0, 1] as Vec2 })
+      ? { x: cat_range, x2: [0, 1] as Vec2, y: value_primary, y2: value_secondary }
+      : { x: value_primary, x2: value_secondary, y: cat_range, y2: [0, 1] as Vec2 }
   })
 
   let ranges = $state<{
@@ -419,10 +443,14 @@
     current: { x: [0, 1], x2: [0, 1], y: [0, 1], y2: [0, 1] },
   })
 
-  $effect(() => { // sync ranges from axis.range overrides / auto ranges
+  $effect(() => {
+    // sync ranges from axis.range overrides / auto ranges
     // resolve_axis_ranges returns null for transient non-finite bounds (skip: writing
     // NaN breaks scales and, since NaN !== NaN, loops the effect)
-    const next = resolve_axis_ranges({ x: x_axis, x2: x2_axis, y: y_axis, y2: y2_axis }, auto_ranges)
+    const next = resolve_axis_ranges(
+      { x: x_axis, x2: x2_axis, y: y_axis, y2: y2_axis },
+      auto_ranges,
+    )
     if (!next) return
     // untrack the read of `ranges` so the assignment can't re-trigger this effect
     // (reading + writing the same state otherwise causes effect_update_depth_exceeded).
@@ -432,34 +460,42 @@
     }
   })
 
-  const default_padding = { t: 20, b: 60, l: 60, r: 20 }
-  let base_pad = $derived(filter_padding(padding, default_padding))
-
-  $effect(() => { // dynamic padding from tick label widths
-    const new_pad = width && height && ticks.y.length > 0
-      ? calc_auto_padding({
-        padding,
-        default_padding,
-        x2_axis: { ...x2_axis, tick_values: ticks.x2 },
-        y_axis: { ...y_axis, tick_values: ticks.y },
-        y2_axis: { ...y2_axis, tick_values: ticks.y2 },
-      })
-      : filter_padding(padding, default_padding)
-    if (
-      width && height && orientation === `vertical` && has_secondary && ticks.y2.length > 0
-    ) {
+  let base_pad = $derived(filter_padding(padding, DEFAULT_PLOT_PADDING))
+
+  $effect(() => {
+    // dynamic padding from tick label widths
+    const new_pad =
+      width && height && ticks.y.length > 0
+        ? calc_auto_padding({
+            padding,
+            default_padding: DEFAULT_PLOT_PADDING,
+            x2_axis: { ...x2_axis, tick_values: ticks.x2 },
+            y_axis: { ...y_axis, tick_values: ticks.y },
+            y2_axis: { ...y2_axis, tick_values: ticks.y2 },
+          })
+        : filter_padding(padding, DEFAULT_PLOT_PADDING)
+    if (width && height && show_y2 && ticks.y2.length > 0) {
       const inside = y2_axis.tick?.label?.inside ?? false
       const tick_shift = inside ? 0 : (y2_axis.tick?.label?.shift?.x ?? 0) + 8
       const tick_width_contribution = inside ? 0 : tick_label_widths.y2_max
       const label_space = y2_axis.label ? 20 : 0
       new_pad.r = Math.max(new_pad.r, tick_shift + tick_width_contribution + 30 + label_space)
     }
-    if (base_pad.t !== new_pad.t || base_pad.b !== new_pad.b ||
-      base_pad.l !== new_pad.l || base_pad.r !== new_pad.r) base_pad = new_pad
+    if (
+      base_pad.t !== new_pad.t ||
+      base_pad.b !== new_pad.b ||
+      base_pad.l !== new_pad.l ||
+      base_pad.r !== new_pad.r
+    )
+      base_pad = new_pad
   })
 
   let legend_element = $state<HTMLDivElement | undefined>()
-  const legend_footprint = $derived(measured_footprint(legend_element, { width: 120, height: 60 }))
+  let legend_size_revision = $state(0)
+  const legend_footprint = $derived.by(() => {
+    void legend_size_revision
+    return measured_footprint(legend_element, { width: 120, height: 60 })
+  })
   const legend_has_explicit_pos = $derived(has_explicit_position(legend?.style))
 
   // Obstacle field in normalized [0,1] coords: each box modeled as a whisker-spanning segment
@@ -476,8 +512,12 @@
       const secondary = is_secondary(box_item.series)
       const cat_rng = vertical ? ranges.current.x : ranges.current.y
       const val_rng = vertical
-        ? (secondary ? ranges.current.y2 : ranges.current.y)
-        : (secondary ? ranges.current.x2 : ranges.current.x)
+        ? secondary
+          ? ranges.current.y2
+          : ranges.current.y
+        : secondary
+          ? ranges.current.x2
+          : ranges.current.x
       const cat_span = cat_rng[1] - cat_rng[0]
       const val_span = val_rng[1] - val_rng[0]
       if (cat_span === 0 || val_span === 0) continue
@@ -493,43 +533,73 @@
   })
 
   const should_show_legend = $derived(show_legend ?? false)
-  const decor = $derived.by(() =>
+  const decor = $derived(
     place_decorations({
       base_pad,
       width,
       height,
       obstacles_norm,
-      legend: legend != null && should_show_legend && legend_element != null &&
-          !legend_has_explicit_pos
-        ? { footprint: legend_footprint, clearance: legend?.axis_clearance }
-        : null,
-    })
+      legend:
+        legend != null &&
+        should_show_legend &&
+        legend_element != null &&
+        !legend_has_explicit_pos
+          ? { footprint: legend_footprint, clearance: legend?.axis_clearance }
+          : null,
+    }),
+  )
+  // Marginals are opt-in (default prop `false`) and bind to the VALUE axis, pooling each box's
+  // raw samples. The default side follows orientation (value axis = y when vertical, x when
+  // horizontal) so the `marginals` boolean / type-string shorthand land on a meaningful side.
+  // Each box is tagged with its value axis so a primary-axis marginal ignores secondary boxes.
+  const marginal_vertical = $derived(orientation === `vertical`)
+  const resolved_marginals = $derived(
+    normalize_marginals(marginals, marginal_vertical ? { right: true } : { top: true }),
   )
-  const pad = $derived(decor.pad)
-  const legend_auto_outside = $derived(decor.legend_outside)
-  const legend_outside_x = $derived(decor.legend_pos.x)
-  const legend_outside_y = $derived(decor.legend_pos.y)
+  const pad = $derived(add_sides(decor.pad, reserve_marginal_pad(resolved_marginals)))
+  const marginal_series = $derived<MarginalSeriesInput[]>(
+    visible_boxes.map((box_item) => {
+      const secondary = is_secondary(box_item.series)
+      return {
+        x: marginal_vertical ? undefined : (box_item.series.y ?? []),
+        y: marginal_vertical ? (box_item.series.y ?? []) : undefined,
+        color: box_color(box_item.idx),
+        label: box_item.series.label,
+        visible: true,
+        x_axis: marginal_vertical ? `x1` : secondary ? `x2` : `x1`,
+        y_axis: marginal_vertical ? (secondary ? `y2` : `y1`) : `y1`,
+      }
+    }),
+  )
+  const marginal_has_axis = $derived(marginal_axis_presence(show_x2, show_y2))
   const chart_width = $derived(Math.max(1, width - pad.l - pad.r))
   const chart_height = $derived(Math.max(1, height - pad.t - pad.b))
 
-  let scales = $derived({
-    x: create_scale(x_axis.scale_type ?? `linear`, ranges.current.x, [pad.l, width - pad.r]),
-    x2: create_scale(x2_axis.scale_type ?? `linear`, ranges.current.x2, [pad.l, width - pad.r]),
-    y: create_scale(y_axis.scale_type ?? `linear`, ranges.current.y, [height - pad.b, pad.t]),
-    y2: create_scale(y2_axis.scale_type ?? `linear`, ranges.current.y2, [height - pad.b, pad.t]),
-  })
+  let scales = $derived(
+    create_axis_scales(
+      { x: x_axis, x2: x2_axis, y: y_axis, y2: y2_axis },
+      ranges.current,
+      pad,
+      width,
+      height,
+    ),
+  )
 
   // Value scale for a box (vertical -> y/y2, horizontal -> x/x2), made log-safe: on a
   // log value axis, stats at values <= 0 (whisker_low is often exactly 0; negative
   // outliers) have no finite pixel. Clamp to LOG_EPS so whiskers/boxes/labels draw
   // toward the plot edge (the clip group crops the overshoot) instead of NaN coords.
-  const box_val_scale = (srs: BoxPlotSeries<Metadata>): (val: number) => number => {
+  const box_val_scale = (srs: BoxPlotSeries<Metadata>): ((val: number) => number) => {
     const vertical = orientation === `vertical`
     const secondary = is_secondary(srs)
     const scale = vertical
-      ? (secondary ? scales.y2 : scales.y)
-      : (secondary ? scales.x2 : scales.x)
-    const axis = vertical ? (secondary ? y2_axis : y_axis) : (secondary ? x2_axis : x_axis)
+      ? secondary
+        ? scales.y2
+        : scales.y
+      : secondary
+        ? scales.x2
+        : scales.x
+    const axis = vertical ? (secondary ? y2_axis : y_axis) : secondary ? x2_axis : x_axis
     return axis.scale_type === `log` ? (val) => scale(Math.max(val, LOG_EPS)) : scale
   }
 
@@ -543,48 +613,50 @@
     return Object.fromEntries(slot_list.map((cat, idx) => [idx, cat]))
   })
 
-  let ticks = $derived({
-    x: width && height
-      ? (cat_axis === `x` ? slot_indices : generate_ticks(
-        ranges.current.x,
-        x_axis.scale_type ?? `linear`,
-        x_axis.ticks,
-        scales.x,
-        { default_count: 8 },
-      ))
-      : [],
-    y: width && height
-      ? (cat_axis === `y` ? slot_indices : generate_ticks(
-        ranges.current.y,
-        y_axis.scale_type ?? `linear`,
-        y_axis.ticks,
-        scales.y,
-        { default_count: 6 },
-      ))
-      : [],
-    y2: width && height && has_secondary && orientation === `vertical`
-      ? generate_ticks(ranges.current.y2, y2_axis.scale_type ?? `linear`, y2_axis.ticks, scales.y2, {
-        default_count: 6,
-      })
-      : [],
-    x2: width && height && has_secondary && orientation === `horizontal`
-      ? generate_ticks(ranges.current.x2, x2_axis.scale_type ?? `linear`, x2_axis.ticks, scales.x2, {
-        default_count: 8,
-      })
-      : [],
+  let ticks = $derived.by(() => {
+    const axis_ticks = (
+      axis: typeof x_axis,
+      range: Vec2,
+      scale: typeof scales.x,
+      default_count: number,
+      show = true,
+    ) =>
+      width && height && show
+        ? generate_ticks(range, axis.scale_type ?? `linear`, axis.ticks, scale, {
+            default_count,
+          })
+        : []
+    // categorical axes show one tick per slot instead of generated numeric ticks
+    return {
+      x:
+        cat_axis === `x` && width && height
+          ? slot_indices
+          : axis_ticks(x_axis, ranges.current.x, scales.x, 8),
+      y:
+        cat_axis === `y` && width && height
+          ? slot_indices
+          : axis_ticks(y_axis, ranges.current.y, scales.y, 6),
+      y2: axis_ticks(y2_axis, ranges.current.y2, scales.y2, 6, show_y2),
+      x2: axis_ticks(x2_axis, ranges.current.x2, scales.x2, 8, show_x2),
+    }
   })
 
   let tick_label_widths = $derived({
     y_max: measure_max_tick_width(ticks.y, y_axis.format ?? ``),
     y2_max: measure_max_tick_width(ticks.y2, y2_axis.format ?? ``),
-    x2_max: measure_max_tick_width(ticks.x2, x2_axis.format ?? ``),
   })
 
   // Shared pan/zoom/touch/drag-rect interaction controller
   const pan_zoom = create_pan_zoom({
     ranges: () => ranges.current,
-    scale_type: (axis) => ({ x: x_axis, x2: x2_axis, y: y_axis, y2: y2_axis })[axis].scale_type,
-    plot_dims: () => ({ width: chart_width, height: chart_height }),
+    scale_type: (axis) =>
+      ({ x: x_axis, x2: x2_axis, y: y_axis, y2: y2_axis })[axis].scale_type,
+    plot_bounds: () => ({
+      x: pad.l,
+      y: pad.t,
+      width: chart_width,
+      height: chart_height,
+    }),
     pan: () => pan,
     set_range: (axis, range) => (ranges.current[axis] = range),
     svg: () => svg_element,
@@ -595,15 +667,11 @@
       // the secondary value axis is x2 only in horizontal mode, y2 only in vertical
       // (is_secondary keys off orientation); writing the off-orientation axis would
       // store a phantom range from its [0, 1] sentinel scale into the bound prop
-      const next_x2 = has_secondary && orientation === `horizontal`
-        ? invert_rect_range(scales.x2, start.x, current.x)
-        : null
+      const next_x2 = show_x2 ? invert_rect_range(scales.x2, start.x, current.x) : null
       if (next_x2) x2_axis_prop = { ...x2_axis_prop, range: next_x2 }
       const next_y = invert_rect_range(scales.y, start.y, current.y)
       if (next_y) y_axis = { ...y_axis, range: next_y }
-      const next_y2 = has_secondary && orientation === `vertical`
-        ? invert_rect_range(scales.y2, start.y, current.y)
-        : null
+      const next_y2 = show_y2 ? invert_rect_range(scales.y2, start.y, current.y) : null
       if (next_y2) y2_axis_prop = { ...y2_axis_prop, range: next_y2 }
     },
     on_reset: () => {
@@ -632,7 +700,10 @@
     })),
   )
 
-  const legend_vis = create_legend_visibility(() => series, (next) => (series = next))
+  const legend_vis = create_legend_visibility(
+    () => series,
+    (next) => (series = next),
+  )
 
   let box_points_for_placement = $derived.by(() => {
     if (!width || !height || visible_boxes.length === 0) return []
@@ -650,7 +721,7 @@
 
   let hovered_legend_series_idx = $state<number | null>(null)
 
-  let legend_placement = $derived.by(() => {
+  const get_legend_placement = () => {
     if (!should_show_legend || !width || !height) return null
     return compute_element_placement({
       plot_bounds: { x: pad.l, y: pad.t, width: chart_width, height: chart_height },
@@ -660,15 +731,16 @@
       exclude_rects: [],
       points: box_points_for_placement,
     })
-  })
+  }
 
   // Tweened legend coordinates with shared placement stability gating
   const legend_tween = create_placed_tween({
-    placement: () => legend_placement,
+    placement: get_legend_placement,
     dims: () => ({ width, height }),
     responsive: () => legend?.responsive ?? false,
     element: () => legend_element,
     tween: () => legend?.tween,
+    on_element_resize: () => (legend_size_revision += 1),
   })
 
   // === Tooltip / hover ===
@@ -720,21 +792,24 @@
     on_box_hover?.({ ...hover_info, event })
   }
 
+  const clear_hover = () => {
+    hover_info = null
+    change(null)
+    on_box_hover?.(null)
+  }
+
   // Set theme-aware background when entering fullscreen
   $effect(() => set_fullscreen_bg(wrapper, fullscreen, `--boxplot-fullscreen-bg`))
 
   // Value label helper
   const value_label_for = (stats: Box[`stats`]): string =>
-    format_value(value_label_stat === `mean` ? stats.mean : stats.median, value_label_format)
+    format_value_or_num(
+      value_label_stat === `mean` ? stats.mean : stats.median,
+      value_label_format,
+    )
 </script>
 
-{#snippet seg(
-  p1: Vec2,
-  p2: Vec2,
-  stroke: string,
-  sw: number,
-  dash?: string,
-)}
+{#snippet seg(p1: Vec2, p2: Vec2, stroke: string, sw: number, dash?: string)}
   <line
     x1={p1[0]}
     y1={p1[1]}
@@ -790,7 +865,7 @@
   bind:clientWidth={width}
   bind:clientHeight={height}
   {...rest}
-  class="box-plot {rest.class ?? ``}"
+  class={[`box-plot`, rest.class]}
   class:fullscreen
 >
   {#if width && height}
@@ -806,7 +881,7 @@
       bind:this={svg_element}
       role="application"
       aria-label={rest[`aria-label`] ??
-      ([x_axis.label, y_axis.label].filter(Boolean).join(` vs `) || `Box plot`)}
+        ([x_axis.label, y_axis.label].filter(Boolean).join(` vs `) || `Box plot`)}
       tabindex="0"
       onfocusin={() => pan_zoom.set_focused(true)}
       onfocusout={() => pan_zoom.set_focused(false)}
@@ -815,9 +890,7 @@
       onkeydown={pan_zoom.on_key_down}
       onmouseleave={() => {
         hovered = false
-        hover_info = null
-        change(null)
-        on_box_hover?.(null)
+        clear_hover()
       }}
       onwheel={pan_zoom.on_wheel}
       ontouchstart={pan_zoom.on_touch_start}
@@ -847,65 +920,67 @@
 
       <PlotAxis
         side="x"
-        ticks={ticks.x as number[]}
+        ticks={ticks.x}
         place={scales.x}
         axis={x_axis}
-        domain={ranges.current.x as Vec2}
+        domain={ranges.current.x}
         {pad}
         {width}
         {height}
         show_grid={display.x_grid}
         tick_label={(tick) =>
-        get_tick_label(tick, cat_axis === `x` ? effective_cat_ticks : x_axis.ticks)}
+          get_tick_label(tick, cat_axis === `x` ? effective_cat_ticks : x_axis.ticks)}
         tick_color={cat_axis === `x` ? (tick) => slot_colors.get(tick) : undefined}
         label_x={pad.l + chart_width / 2 + (x_axis.label_shift?.x ?? 0)}
-        label_y={height - pad.b / 3 + (x_axis.label_shift?.y ?? 0)}
+        label_y={height - pad.b + AXIS_TITLE_OFFSET + (x_axis.label_shift?.y ?? 0)}
       />
 
-      {#if has_secondary && orientation === `horizontal`}
+      {#if show_x2}
         <PlotAxis
           side="x2"
-          ticks={ticks.x2 as number[]}
+          ticks={ticks.x2}
           place={scales.x2}
           axis={x2_axis}
-          domain={ranges.current.x2 as Vec2}
+          domain={ranges.current.x2}
           {pad}
           {width}
           {height}
           show_grid={display.x2_grid}
           tick_label={(tick) => get_tick_label(tick, x2_axis.ticks)}
           label_x={pad.l + chart_width / 2 + (x2_axis.label_shift?.x ?? 0)}
-          label_y={Math.max(12, pad.t - (x2_axis.label_shift?.y ?? 40))}
+          label_y={Math.max(12, pad.t - (x2_axis.label_shift?.y ?? AXIS_TITLE_OFFSET))}
         />
       {/if}
 
       <PlotAxis
         side="y"
-        ticks={ticks.y as number[]}
+        ticks={ticks.y}
         place={scales.y}
         axis={y_axis}
-        domain={ranges.current.y as Vec2}
+        domain={ranges.current.y}
         {pad}
         {width}
         {height}
         show_grid={display.y_grid}
         tick_label={(tick) =>
-        get_tick_label(tick, cat_axis === `y` ? effective_cat_ticks : y_axis.ticks)}
+          get_tick_label(tick, cat_axis === `y` ? effective_cat_ticks : y_axis.ticks)}
         tick_color={cat_axis === `y` ? (tick) => slot_colors.get(tick) : undefined}
         label_x={Math.max(
           12,
-          pad.l - (y_axis.tick?.label?.inside ? 0 : tick_label_widths.y_max) - LABEL_GAP_DEFAULT,
+          pad.l -
+            (y_axis.tick?.label?.inside ? 0 : tick_label_widths.y_max) -
+            LABEL_GAP_DEFAULT,
         ) + (y_axis.label_shift?.x ?? 0)}
         label_y={pad.t + chart_height / 2 + (y_axis.label_shift?.y ?? 0)}
       />
 
-      {#if has_secondary && orientation === `vertical`}
+      {#if show_y2}
         <PlotAxis
           side="y2"
-          ticks={ticks.y2 as number[]}
+          ticks={ticks.y2}
           place={scales.y2}
           axis={y2_axis}
-          domain={ranges.current.y2 as Vec2}
+          domain={ranges.current.y2}
           {pad}
           {width}
           {height}
@@ -941,8 +1016,8 @@
           x2_scale_type={x2_axis.scale_type}
           y_scale_type={y_axis.scale_type}
           y2_scale_type={y2_axis.scale_type}
-          has_x2={has_secondary && orientation === `horizontal`}
-          has_y2={has_secondary && orientation === `vertical`}
+          has_x2={show_x2}
+          has_y2={show_y2}
           {width}
           {height}
           {pad}
@@ -963,12 +1038,13 @@
             {@const draw_box = draws_box(box_item.series)}
             {@const kde = violin_kdes.get(box_item.idx)}
             {@const eff_side = box_item.series.side ?? side}
-            {@const bw = box_item.series.box_width ??
-            (kde ? DEFAULTS.box.violin_box_width : DEFAULTS.box.box_width)}
+            {@const bw =
+              box_item.series.box_width ??
+              (kde ? DEFAULTS.box.violin_box_width : DEFAULTS.box.box_width)}
             {@const c_lo = cat_scale(box_item.slot - bw / 2)}
             {@const c_hi = cat_scale(box_item.slot + bw / 2)}
             {@const c_center = cat_scale(box_item.slot)}
-            {@const cap = Math.abs(c_hi - c_lo) * (whisker_state.cap_fraction ?? 0.5) / 2}
+            {@const cap = (Math.abs(c_hi - c_lo) * (whisker_state.cap_fraction ?? 0.5)) / 2}
             {@const cap_lo = c_center - cap}
             {@const cap_hi = c_center + cap}
             {@const v_q1 = val_scale(stats.q1)}
@@ -978,7 +1054,7 @@
             {@const v_wh = val_scale(stats.whisker_high)}
             {@const v_mean = val_scale(stats.mean)}
             {@const pt = (cross: number, val: number): Vec2 =>
-            vertical ? [cross, val] : [val, cross]}
+              vertical ? [cross, val] : [val, cross]}
             {@const [q1x, q1y] = pt(c_lo, v_q1)}
             {@const [q3x, q3y] = pt(c_hi, v_q3)}
             {@const [wlx, wly] = pt(c_lo, v_wl)}
@@ -992,12 +1068,12 @@
             {@const hit_w = Math.abs(whx - wlx)}
             {@const hit_h = Math.abs(why - wly)}
             {@const [label_x, label_y] = vertical
-            ? [c_center, Math.min(v_wh, v_wl) - 6]
-            : [Math.max(v_wh, v_wl) + 6, c_center]}
+              ? [c_center, Math.min(v_wh, v_wl) - 6]
+              : [Math.max(v_wh, v_wl) + 6, c_center]}
             {@const violin_half = Math.abs(
-            cat_scale(box_item.slot + (box_item.series.violin_width ?? violin_width) / 2) -
-              c_center,
-          )}
+              cat_scale(box_item.slot + (box_item.series.violin_width ?? violin_width) / 2) -
+                c_center,
+            )}
             {@const max_density = kde ? (violin_max_density.get(box_item.idx) ?? 0) : 0}
             <!-- svelte-ignore a11y_no_static_element_interactions a11y_click_events_have_key_events -->
             <g
@@ -1008,16 +1084,13 @@
               aria-label={`box ${box_item.idx + 1}: ${box_item.series.label ?? ``}`}
               style:cursor={on_box_click ? `pointer` : undefined}
               opacity={hovered_legend_series_idx !== null &&
-                  hovered_legend_series_idx !== box_item.idx
+              hovered_legend_series_idx !== box_item.idx
                 ? 0.25
                 : 1}
               onmousemove={handle_box_hover(box_item, color)}
-              onmouseleave={() => {
-                hover_info = null
-                change(null)
-                on_box_hover?.(null)
-              }}
-              onclick={(evt) => on_box_click?.({ ...get_box_data(box_item, color), event: evt })}
+              onmouseleave={clear_hover}
+              onclick={(evt) =>
+                on_box_click?.({ ...get_box_data(box_item, color), event: evt })}
               onkeydown={(evt) => {
                 if (evt.key === `Enter` || evt.key === ` `) {
                   evt.preventDefault()
@@ -1064,7 +1137,12 @@
                   stroke-width={box_state.stroke_width}
                 />
                 <!-- median (solid) and mean (dashed) -->
-                {@render seg(pt(c_lo, v_med), pt(c_hi, v_med), median_state.color, median_state.width)}
+                {@render seg(
+                  pt(c_lo, v_med),
+                  pt(c_hi, v_med),
+                  median_state.color,
+                  median_state.width,
+                )}
                 {#if show_mean}
                   {@render seg(
                     pt(c_lo, v_mean),
@@ -1120,16 +1198,33 @@
 
       {@render ref_lines_layer(ref_lines_by_z.below_points)}
       {@render ref_lines_layer(ref_lines_by_z.above_all)}
+
+      <!-- Marginal distribution strips -->
+      <PlotMarginals
+        marginals={resolved_marginals}
+        series={marginal_series}
+        {width}
+        {height}
+        {pad}
+        has_axis={marginal_has_axis}
+        axes={{
+          x1: marginal_axis(scales.x, ranges.current.x, x_axis),
+          x2: marginal_axis(scales.x2, ranges.current.x2, x2_axis),
+          y1: marginal_axis(scales.y, ranges.current.y, y_axis),
+          y2: marginal_axis(scales.y2, ranges.current.y2, y2_axis),
+        }}
+        id={clip_path_id}
+      />
     </svg>
 
     {#if legend && should_show_legend}
       {@const legend_pos = placed_coords(
-      legend_auto_outside,
-      { x: legend_outside_x, y: legend_outside_y },
-      legend_placement,
-      legend_tween.coords.current,
-      { x: pad.l + 10, y: pad.t + 10 },
-    )}
+        decor.legend_outside,
+        decor.legend_pos,
+        legend_tween.placed(),
+        legend_tween.coords.current,
+        { x: pad.l + 10, y: pad.t + 10 },
+      )}
       <PlotLegend
         bind:root_element={legend_element}
         {...legend}
@@ -1139,9 +1234,8 @@
         on_double_click={legend?.on_double_click ?? legend_vis.on_double_click}
         on_hover_change={legend_tween.set_locked}
         on_item_hover={(item) =>
-          (hovered_legend_series_idx = item != null && item.series_idx >= 0
-            ? item.series_idx
-            : null)}
+          (hovered_legend_series_idx =
+            item != null && item.series_idx >= 0 ? item.series_idx : null)}
         active_series_idx={hover_info?.series_idx ?? hovered_legend_series_idx}
         style={`position: absolute; left: ${legend_pos.x}px; top: ${legend_pos.y}px; pointer-events: auto; ${
           legend?.style || ``
@@ -1161,7 +1255,7 @@
         {#if tooltip}
           {@render tooltip({ ...hover_info, fullscreen })}
         {:else}
-          {@const fmt = (orientation === `vertical` ? y_axis.format : x_axis.format) || `.3~s`}
+          {@const fmt = orientation === `vertical` ? y_axis.format : x_axis.format}
           {@const stat = hover_info.stats}
           {@const rows = [
             [`max`, stat.whisker_high],
@@ -1175,7 +1269,7 @@
             <div><strong>{hover_info.category_label}</strong></div>
           {/if}
           {#each rows as [label, value] (label)}
-            <div>{label}: {format_value(value, fmt)}</div>
+            <div>{label}: {format_value_or_num(value, fmt)}</div>
           {/each}
           {#if show_outliers && stat.outliers.length > 0}
             <div>outliers: {stat.outliers.length}</div>
@@ -1206,12 +1300,12 @@
         bind:y_axis
         bind:y2_axis={y2_axis_prop}
         bind:display
-        auto_x_range={auto_ranges.x as Vec2}
-        auto_x2_range={auto_ranges.x2 as Vec2}
-        auto_y_range={auto_ranges.y as Vec2}
-        auto_y2_range={auto_ranges.y2 as Vec2}
-        has_x2_points={has_secondary && orientation === `horizontal`}
-        has_y2_points={has_secondary && orientation === `vertical`}
+        auto_x_range={auto_ranges.x}
+        auto_x2_range={auto_ranges.x2}
+        auto_y_range={auto_ranges.y}
+        auto_y2_range={auto_ranges.y2}
+        has_x2_points={show_x2}
+        has_y2_points={show_y2}
         children={controls_extra}
       />
     {/if}
@@ -1268,7 +1362,9 @@
   .box-plot :global(.pane-toggle),
   .box-plot .header-controls {
     opacity: 0;
-    transition: opacity 0.2s, background-color 0.2s;
+    transition:
+      opacity 0.2s,
+      background-color 0.2s;
   }
   .box-plot:hover :global(.pane-toggle),
   .box-plot:hover .header-controls,