New ArcLabel component (#817)

* feat(ArcLabel): New component for positioning text labels on arc segments.  Resolves #7

* Add labels to Partition/sunburst example

Author: techniq

.changeset/arclabel-component.md

@@ -0,0 +1,17 @@
+---
+'layerchart': minor
+---
+
+feat(ArcLabel): New component for positioning text labels on arc segments
+
+`ArcLabel` is a new marking component for placing text (and optional leader lines) relative to an arc. It's used internally by `PieChart` and `ArcChart` when the `labels` prop is set, but can also be rendered directly inside an `Arc` children snippet.
+
+Supported placements:
+
+- `centroid` — at the arc centroid (horizontal text, default)
+- `centroid-rotated` — at the centroid, rotated to follow the arc tangent, flipped where needed so text stays upright
+- `centroid-radial` — at the centroid, rotated to read along the radial direction (center → outer edge)
+- `inner` / `middle` / `outer` — along the inner, medial, or outer arc path (centered via `startOffset: '50%'` by default)
+- `callout` — outside the arc with a leader line that bends horizontally to the label
+
+`ArcLabel` accepts a single `offset` prop that is routed to the placement-appropriate radial padding (centroid offset, `innerPadding`/`outerPadding`, or `calloutLineLength`), plus `calloutLineLength` / `calloutLabelOffset` / `calloutPadding` for fine-grained control of callout leader lines. The leader line renders via the `Path` primitive, so it works in both SVG and Canvas chart layers.

.changeset/arctext-centered-default.md

@@ -0,0 +1,7 @@
+---
+'layerchart': minor
+---
+
+breaking(Arc): Center arc text along path by default for `inner`/`middle`/`outer` positions
+
+`getArcTextProps('inner' | 'middle' | 'outer')` now defaults to `startOffset: '50%'` with `textAnchor: 'middle'`, centering the text along the arc path rather than anchoring it at the arc start. When an explicit `startOffset` is provided, the anchor falls back to `'start'` so the text begins at that position (matching prior behavior for callers that set a start offset).

.changeset/arctext-inner-padding.md

@@ -0,0 +1,7 @@
+---
+'layerchart': minor
+---
+
+feat(Arc): Add `innerPadding` option to `getArcTextProps` / `getTrackTextProps`
+
+`ArcTextOptions` now supports an `innerPadding` option, symmetric to the existing `outerPadding`. Positive values shrink the inner radius used to build the `inner`/`middle` arc text paths, moving text inward (toward the chart center). Previously, offsetting an `inner`-placed arc label away from the arc edge required overriding the path manually; now it works the same as `outerPadding` does for `outer` text.

.changeset/piechart-arcchart-labels-prop.md

@@ -0,0 +1,14 @@
+---
+'layerchart': minor
+---
+
+feat(PieChart/ArcChart): Add top-level `labels` prop
+
+`PieChart` and `ArcChart` now accept a `labels` prop that renders text labels on each arc without requiring a custom `arc` snippet. Pass `true` to enable defaults (centroid placement, default value accessor), or an object to configure any `ArcLabel` props — placement, offset, value accessor, callout line lengths, leader line style, text class, etc.
+
+```svelte
+<PieChart
+  {data}
+  labels={{ placement: 'callout', value: 'fruit' }}
+/>
+```

docs/src/content/components/ArcChart.md

@@ -9,6 +9,12 @@ related: [Chart, Pie]
 
 :example{ name="basic" showCode }
 
+### Labels
+
+Enable arc labels via the `labels` prop. Pass `true` for defaults, or an object to configure placement and other [`ArcLabel`](/docs/components/ArcLabel) props.
+
+:example{ name="labels" }
+
 <!-- ## Examples
 
 ### Basic

docs/src/content/components/ArcLabel.md

@@ -0,0 +1,78 @@
+---
+description: Marking component which positions text labels on pie and arc chart segments, including along the arc path, at the centroid (horizontal, tangent-rotated, or radially-rotated), outside the arc, and with callout leader lines.
+category: marks
+layers: [svg]
+related: [Arc, Pie, PieChart, ArcChart, Labels]
+---
+
+## Usage
+
+`ArcLabel` positions a text label (and optional leader line) relative to an arc. It's used by `PieChart` and `ArcChart` internally when the `labels` prop is set, but can also be used directly inside an `Arc` children snippet for full control.
+
+:example{ component="PieChart" name="labels" showCode }
+
+### Placements
+
+- `centroid` — at the arc centroid (horizontal text, default).
+- `centroid-rotated` — at the centroid, rotated to follow the arc tangent. The rotation is flipped where needed so text stays upright.
+- `centroid-radial` — at the centroid, rotated to read along the radial direction (center → outer edge). Useful for sunburst-style labels.
+- `inner` — along the inner arc path.
+- `middle` — along the medial arc path (midway between inner and outer).
+- `outer` — along the outer arc path.
+- `callout` — outside the arc with a polyline leader line that bends horizontally toward the label.
+
+### Offsets
+
+Depending on the placement, different offset props apply:
+
+- `outerPadding` — adds padding to the outer radius used for `inner` / `middle` / `outer` arc text paths.
+- `startOffset` — percentage along the arc path where the text starts. Defaults to `'50%'` (centered).
+- `calloutLineLength` — length of the radial portion of the `callout` leader line.
+- `calloutLabelOffset` — length of the horizontal portion of the `callout` leader line after the bend.
+- `calloutPadding` — gap between the end of the leader line and the label text.
+
+### Callout leader lines
+
+`placement="callout"` draws a line from the outer arc edge to the label with a single bend. The line is rendered via the [`Path`](/docs/components/Path) component so it works in both SVG and Canvas chart layers.
+
+Three props control the geometry:
+
+- `calloutLineLength` — length of the radial (first) segment, from the outer arc edge out to the bend.
+- `calloutLabelOffset` — length of the horizontal (second) segment, from the bend to the label.
+- `calloutPadding` — gap between the end of the line and the label text.
+
+:example{ component="PieChart" name="labels-callout" }
+
+Customize the line itself via the `line` prop, which forwards props to `<Path>`:
+
+```svelte
+<PieChart
+  {data}
+  labels={{
+    placement: 'callout',
+    value: 'fruit',
+    line: { stroke: 'currentColor', strokeWidth: 1.5, class: 'opacity-50' }
+  }}
+/>
+```
+
+### Using `ArcLabel` directly
+
+When using `Arc` directly (outside of `PieChart`/`ArcChart`), render `ArcLabel` inside the `Arc` children snippet. The snippet exposes `centroid`, `startAngle`, `endAngle`, `innerRadius`, `outerRadius`, and `getArcTextProps` — all of which `ArcLabel` accepts.
+
+```svelte
+<Arc {...arcProps}>
+  {#snippet children({ centroid, startAngle, endAngle, innerRadius, outerRadius, getArcTextProps })}
+    <ArcLabel
+      {centroid}
+      {startAngle}
+      {endAngle}
+      {innerRadius}
+      {outerRadius}
+      {getArcTextProps}
+      placement="centroid-radial"
+      value="Label text"
+    />
+  {/snippet}
+</Arc>
+```

docs/src/content/components/PieChart.md

@@ -9,6 +9,12 @@ related: [Chart, Pie]
 
 :example{ name="basic" showCode }
 
+### Labels
+
+Enable arc labels via the `labels` prop. Pass `true` for defaults, or an object to configure placement and other [`ArcLabel`](/docs/components/ArcLabel) props.
+
+:example{ name="labels" }
+
 <!-- ## Examples
 
 ### Basic

docs/src/examples/components/ArcChart/labels.svelte

@@ -0,0 +1,51 @@
+<script lang="ts">
+	import { ArcChart, type ArcLabelPlacement } from 'layerchart';
+	import { MenuField, RangeField } from 'svelte-ux';
+	import { fruitColors } from '$lib/utils/fruitColors';
+	import { longData } from '$lib/utils/data';
+
+	const placements: { label: string; value: ArcLabelPlacement }[] = [
+		{ label: 'Centroid', value: 'centroid' },
+		{ label: 'Centroid (rotated)', value: 'centroid-rotated' },
+		{ label: 'Centroid (radial)', value: 'centroid-radial' },
+		{ label: 'Inner', value: 'inner' },
+		{ label: 'Middle', value: 'middle' },
+		{ label: 'Outer', value: 'outer' },
+		{ label: 'Callout', value: 'callout' }
+	];
+
+	let placement: ArcLabelPlacement = $state('centroid');
+	let offset = $state(0);
+
+	const data = longData.filter((d) => d.year === 2019);
+	export { data };
+</script>
+
+<div class="grid grid-cols-[1fr_1fr] gap-2 mb-4">
+	<MenuField
+		label="Placement"
+		options={placements}
+		bind:value={placement}
+		stepper
+		classes={{ menuIcon: 'hidden' }}
+	/>
+	<RangeField label="Offset" bind:value={offset} min={-40} max={60} />
+</div>
+
+<ArcChart
+	{data}
+	key="fruit"
+	value="value"
+	cRange={fruitColors}
+	outerRadius={-60}
+	innerRadius={-20}
+	cornerRadius={10}
+	padding={{ top: 24, bottom: 24, left: 80, right: 80 }}
+	labels={{
+		placement,
+		offset,
+		value: 'fruit',
+		class: 'text-xs fill-surface-content'
+	}}
+	height={400}
+/>

docs/src/examples/components/ArcChart/series-labels.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-	import { Arc, ArcChart, Text } from 'layerchart';
+	import { ArcChart } from 'layerchart';
 
 	const data = [
 		{ key: 'move', value: 400, maxValue: 1000, color: '#ef4444' },
@@ -23,18 +23,11 @@
 	outerRadius={-25}
 	innerRadius={-20}
 	cornerRadius={10}
+	labels={{
+		placement: 'middle',
+		startOffset: '0%',
+		value: 'key',
+		class: 'fill-black pointer-events-none text-xs'
+	}}
 	height={180}
->
-	{#snippet arc({ context, props, seriesIndex })}
-		<Arc {...props}>
-			{#snippet children({ getArcTextProps })}
-				<Text
-					{...getArcTextProps('middle')}
-					value={context.series.visibleSeries[seriesIndex].key}
-					class="fill-black pointer-events-none"
-					font-size="12px"
-				/>
-			{/snippet}
-		</Arc>
-	{/snippet}
-</ArcChart>
+/>

docs/src/examples/components/Chord/basic.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
 	import { scaleOrdinal } from 'd3-scale';
 	import { schemeTableau10 } from 'd3-scale-chromatic';
-	import { Chart, Layer, Chord, Ribbon, Arc, Group, Text } from 'layerchart';
+	import { Chart, Layer, Chord, Ribbon, Arc, ArcLabel } from 'layerchart';
 
 	// Population migration between regions (in thousands)
 	const names = ['Asia', 'Europe', 'Africa', 'Americas', 'Oceania'];
@@ -41,21 +41,17 @@
 						{outerRadius}
 						fill={color(names[group.index])}
 						stroke="none"
-					/>
-					<Group
-						x={(outerRadius + 6) * Math.cos((group.startAngle + group.endAngle) / 2 - Math.PI / 2)}
-						y={(outerRadius + 6) * Math.sin((group.startAngle + group.endAngle) / 2 - Math.PI / 2)}
 					>
-						<Text
-							value={names[group.index]}
-							textAnchor={(group.startAngle + group.endAngle) / 2 > Math.PI ? 'end' : 'start'}
-							verticalAnchor="middle"
-							class="text-xs font-medium"
-							transform="rotate({(((group.startAngle + group.endAngle) / 2) * 180) / Math.PI -
-								90 +
-								((group.startAngle + group.endAngle) / 2 > Math.PI ? 180 : 0)})"
-						/>
-					</Group>
+						{#snippet children(arcProps)}
+							<ArcLabel
+								{...arcProps}
+								placement="centroid-rotated"
+								offset={(outerRadius - innerRadius) / 2 + 6}
+								value={names[group.index]}
+								class="text-xs font-medium"
+							/>
+						{/snippet}
+					</Arc>
 				{/each}
 			{/snippet}
 		</Chord>