feat(Labels): Add middle placement and change center to center within the bar body. Improve docs. Resolves #378

Author: techniq

.changeset/labels-center-placement.md

@@ -0,0 +1,7 @@
+---
+'layerchart': minor
+---
+
+feat(Labels): Add `middle` placement and change `center` to center within the bar body
+
+`placement="center"` now positions the label at the center of the bar body (between the value edge and the baseline). The previous `center` behavior (label aligned to the value edge with a middle anchor) is now available as the new `placement="middle"`.

docs/src/content/components/Labels.md

@@ -15,20 +15,44 @@ By default labels will be on the outside of bars, above for positive values and
 
 :example{ component="Bars" name="vertical-outside-labels-default" showCode }
 
-You can also use `placement="inside"` to place within the bars (near the value)
+You can also use `placement="inside"` to place within the bars (near the value edge)
 
 :example{ component="Bars" name="vertical-inside-labels" }
 
+Use `placement="middle"` to align the label to the value edge with a centered anchor, or `placement="center"` to center the label within the bar body (between the value edge and the baseline).
+
+:example{ component="BarChart" name="labels-placement" }
+
+Labels work with horizontal bar charts, with placement respecting the value edge direction.
+
+:example{ component="BarChart" name="series-horizontal-labels" }
+
+Labels on grouped series bar charts will be placed relative to each series' bar.
+
+:example{ component="BarChart" name="group-series-labels" }
+
+Labels are also supported on duration (range) bars, showing the span value inside or outside each bar.
+
+:example{ component="BarChart" name="duration-labels" }
+
 ### Line charts
 
 :example{ component="Spline" name="with-labels" }
 
-### Scatter charts
+Use `placement="smart"` to dynamically position labels based on neighboring point values (peaks, troughs, rising, and falling) to reduce overlap.
+
+:example{ component="LineChart" name="smart-labels-with-points" }
+
+Labels can also be rendered within enlarged points for a compact inline annotation style.
+
+:example{ component="LineChart" name="labels-within-points" }
+
+Series end labels can be shown for multi-series line charts, and highlighted on hover.
 
-:example{ component="Points" name="with-labels" }
+:example{ component="LineChart" name="series-labels-hover" }
 
 ### Simplified charts
 
 Labels are also integrated in simplified charts via the `labels` prop
 
-:example{ component="BarChart" name="labels" }
+:example{ component="BarChart" name="labels" showCode }

docs/src/examples/components/BarChart/labels-placement.svelte

@@ -0,0 +1,35 @@
+<script lang="ts">
+	import { BarChart } from 'layerchart';
+	import { MenuField } from 'svelte-ux';
+	import { createDateSeries } from '$lib/utils/data.js';
+
+	type Placement = 'inside' | 'outside' | 'middle' | 'center' | 'smart';
+
+	const placements: { label: string; value: Placement }[] = [
+		{ label: 'Inside', value: 'inside' },
+		{ label: 'Outside', value: 'outside' },
+		{ label: 'Middle', value: 'middle' },
+		{ label: 'Center', value: 'center' }
+	];
+
+	let placement: Placement = $state('outside');
+
+	const data = createDateSeries({
+		count: 10,
+		min: -20,
+		max: 100,
+		value: 'integer',
+		keys: ['value', 'baseline']
+	});
+	export { data };
+</script>
+
+<MenuField
+	label="Placement"
+	options={placements}
+	bind:value={placement}
+	stepper
+	classes={{ root: 'mb-4', menuIcon: 'hidden' }}
+/>
+
+<BarChart {data} x="date" y="value" labels={{ placement }} yPadding={[20, 20]} height={300} />

packages/layerchart/src/lib/components/Labels.svelte

@@ -42,15 +42,19 @@
 
     /**
      * The placement of the label relative to the point.
-     * `smart` dynamically positions labels based on neighboring point values (peak, trough, rising, falling).
+     * - `outside`: outside the bar/point.
+     * - `inside`: inside the bar/point near the value edge.
+     * - `middle`: aligned to the value edge with a middle anchor.
+     * - `center`: centered within the bar body (between the value edge and baseline).
+     * - `smart`: dynamically positions labels based on neighboring point values (peak, trough, rising, falling).
      * @default 'outside'
      */
-    placement?: 'inside' | 'outside' | 'center' | 'smart';
+    placement?: 'inside' | 'outside' | 'middle' | 'center' | 'smart';
 
     /**
      * The offset of the label from the point
      *
-     * @default placement === 'center' ? 0 : 4
+     * @default placement === 'center' || placement === 'middle' ? 0 : 4
      */
     offset?: number;
 
@@ -81,6 +85,7 @@
   import { getChartContext } from '$lib/contexts/chart.js';
   import Group from './Group.svelte';
   import { extractLayerProps } from '$lib/utils/attributes.js';
+  import { createDimensionGetter } from '$lib/utils/rect.svelte.js';
 
   const ctx = getChartContext();
 
@@ -94,7 +99,7 @@
     y,
     seriesKey,
     placement = 'outside',
-    offset = placement === 'center' ? 0 : 4,
+    offset = placement === 'center' || placement === 'middle' ? 0 : 4,
     format,
     key = (_: any, i: number) => i,
     children: childrenProp,
@@ -104,6 +109,9 @@
     ...restProps
   }: LabelsProps<TData> = $props();
 
+  // Used to compute the bar's bounding rect for `center` placement
+  const getDimensions = $derived(createDimensionGetter(ctx, () => ({ x, y })));
+
   // TODO: Should we let `Points` handle opacity for children snippet as well?
   let series = $derived(ctx.series.series.find((s) => s.key === seriesKey));
   let derivedOpacity = $derived(
@@ -146,14 +154,27 @@
 
     if (isScaleBand(ctx.yScale)) {
       // Position label left/right on horizontal bars
-      if (isLowEdge) {
+      if (placement === 'center') {
+        // Center within the bar body
+        const dims = getDimensions(point.data) ?? { x: point.x, y: point.y, width: 0, height: 0 };
+        result = {
+          value: formattedValue,
+          fill: fillValue,
+          x: dims.x + dims.width / 2,
+          y: dims.y + dims.height / 2,
+          textAnchor: 'middle',
+          verticalAnchor: 'middle',
+          capHeight: '.6rem',
+        };
+      } else if (isLowEdge) {
         // left
         result = {
           value: formattedValue,
           fill: fillValue,
           x: point.x + (placement === 'outside' ? -offset : offset),
           y: point.y,
-          textAnchor: placement === 'outside' ? 'end' : 'start',
+          textAnchor:
+            placement === 'middle' ? 'middle' : placement === 'outside' ? 'end' : 'start',
           verticalAnchor: 'middle',
           capHeight: '.6rem',
         };
@@ -164,14 +185,27 @@
           fill: fillValue,
           x: point.x + (placement === 'outside' ? offset : -offset),
           y: point.y,
-          textAnchor: placement === 'outside' ? 'start' : 'end',
+          textAnchor:
+            placement === 'middle' ? 'middle' : placement === 'outside' ? 'start' : 'end',
           verticalAnchor: 'middle',
           capHeight: '.6rem',
         };
       }
     } else {
       // Position label top/bottom on vertical bars
-      if (isLowEdge) {
+      if (placement === 'center') {
+        // Center within the bar body
+        const dims = getDimensions(point.data) ?? { x: point.x, y: point.y, width: 0, height: 0 };
+        result = {
+          value: formattedValue,
+          fill: fillValue,
+          x: dims.x + dims.width / 2,
+          y: dims.y + dims.height / 2,
+          capHeight: '.6rem',
+          textAnchor: 'middle',
+          verticalAnchor: 'middle',
+        };
+      } else if (isLowEdge) {
         // bottom
         result = {
           value: formattedValue,
@@ -181,7 +215,7 @@
           capHeight: '.6rem',
           textAnchor: 'middle',
           verticalAnchor:
-            placement === 'center' ? 'middle' : placement === 'outside' ? 'start' : 'end',
+            placement === 'middle' ? 'middle' : placement === 'outside' ? 'start' : 'end',
         };
       } else {
         // top
@@ -193,7 +227,7 @@
           capHeight: '.6rem',
           textAnchor: 'middle',
           verticalAnchor:
-            placement === 'center' ? 'middle' : placement === 'outside' ? 'end' : 'start',
+            placement === 'middle' ? 'middle' : placement === 'outside' ? 'end' : 'start',
         };
       }
     }
@@ -271,7 +305,8 @@
       --fill-color: var(--color-surface-content, currentColor);
       --stroke-color: var(--color-surface-100, light-dark(white, black));
 
-      &[data-placement='inside'] {
+      &[data-placement='inside'],
+      &[data-placement='center'] {
         --fill-color: var(--color-surface-100, light-dark(white, black));
         --stroke-color: var(--color-surface-content, currentColor);
       }