@sentropic/design-system-svelte 0.34.22 → 0.34.24

package/dist/AreaChart.svelte

@@ -17,6 +17,13 @@
 
 <script lang="ts">
   import ChartDataList from "./ChartDataList.svelte";
+  import {
+    resolveAnnotations,
+    annotationDataListItems,
+    polygonPoints,
+    type ChartAnnotation
+  } from "./chartAnnotations.js";
+  import { formatDataLabel, normalizeDataLabels, type DataLabelsProp } from "./chartDataLabels.js";
 
   type AreaChartProps = {
     data: (number | AreaChartDatum)[];
@@ -25,6 +32,20 @@
     tone?: AreaChartTone;
     smooth?: boolean;
     label: string;
+    /**
+     * Annotation overlay in DATA space (points, labels, axis lines, regions,
+     * polygons), resolved to pixels via the chart scales. Regions render behind
+     * the area, every other kind above it. Additive: absent ⇒ unchanged.
+     */
+    annotations?: ChartAnnotation[];
+    /**
+     * Per-point value labels. `false`/absent (default) → none. `true` → each
+     * point's value with the chart's numeric formatter. Object → `format(value)`
+     * and/or a `position` override. Default position is `top` (above the point).
+     * Labels are `aria-hidden` — the values already live in the accessible
+     * ChartDataList.
+     */
+    dataLabels?: DataLabelsProp;
     class?: string;
   };
 
@@ -35,6 +56,8 @@
     tone = "category1",
     smooth = false,
     label,
+    annotations,
+    dataLabels,
     class: className
   }: AreaChartProps = $props();
 
@@ -87,7 +110,10 @@
     });
   });
 
-  const dataValueItems = $derived(normalizedData.map((d) => `${d.x}: ${d.y}`));
+  const dataValueItems = $derived([
+    ...normalizedData.map((d) => `${d.x}: ${d.y}`),
+    ...annotationDataListItems(annotations)
+  ]);
 
   let hoveredIndex: number | null = $state(null);
 
@@ -139,6 +165,50 @@
     });
   });
 
+  // --- Annotation overlay ---------------------------------------------------
+  // `xScale` honours the ordinal/numeric x domain; `yScale` mirrors the point
+  // y mapping. Out-of-domain coordinates yield `null` → the resolver drops them.
+  const annotationXScale = $derived((v: number | string): number | null => {
+    if (xDomain.kind === "numeric") {
+      if (typeof v !== "number" || !Number.isFinite(v)) return null;
+      if (v < xDomain.min || v > xDomain.max) return null;
+      return scaleLinear(v, xDomain.min, xDomain.max, 0, plotWidth);
+    }
+    const i = normalizedData.findIndex((d) => d.x === v);
+    if (i < 0) return null;
+    const denom = Math.max(normalizedData.length - 1, 1);
+    return normalizedData.length === 1 ? plotWidth / 2 : (i / denom) * plotWidth;
+  });
+  const annotationYScale = $derived((v: number): number | null => {
+    if (!Number.isFinite(v) || v < yDomain.min || v > yDomain.max) return null;
+    return scaleLinear(v, yDomain.min, yDomain.max, plotHeight, 0);
+  });
+  const resolvedAnnotations = $derived(
+    resolveAnnotations(annotations, {
+      xScale: annotationXScale,
+      yScale: annotationYScale,
+      plotLeft: MARGIN.left,
+      plotTop: MARGIN.top,
+      plotWidth,
+      plotHeight
+    })
+  );
+  const annotationRegions = $derived(resolvedAnnotations.filter((a) => a.kind === "region"));
+  const annotationAbove = $derived(resolvedAnnotations.filter((a) => a.kind !== "region"));
+
+  // --- Data labels ----------------------------------------------------------
+  // One value label per point. Default `top`: just above the dot. `center` sits
+  // on the dot. aria-hidden (values are in the ChartDataList already).
+  const dataLabelOpts = $derived(normalizeDataLabels(dataLabels));
+  const dataLabelItems = $derived.by(() => {
+    if (!dataLabelOpts.enabled) return [] as { key: number; x: number; y: number; text: string; baseline: string }[];
+    return points.map((p) => {
+      const text = formatDataLabel(p.datum.y, dataLabelOpts, formatTick);
+      const center = dataLabelOpts.position === "center" || dataLabelOpts.position === "inside";
+      return { key: p.index, x: p.x, y: center ? p.y : p.y - 8, text, baseline: center ? "middle" : "auto" };
+    });
+  });
+
   function buildLinearPath(pts: { x: number; y: number }[]): string {
     return pts.map((p, i) => `${i === 0 ? "M" : "L"}${p.x.toFixed(2)},${p.y.toFixed(2)}`).join(" ");
   }
@@ -294,6 +364,20 @@
       </text>
     {/each}
 
+    <!-- Annotation regions sit BEHIND the area. -->
+    {#if annotationRegions.length > 0}
+      <g class="st-areaChart__annotations st-areaChart__annotations--behind">
+        {#each annotationRegions as a (a.key)}
+          {#if a.kind === "region"}
+            <rect class="st-areaChart__annotationRegion" x={a.x} y={a.y} width={a.width} height={a.height} />
+            {#if a.label}
+              <text class="st-areaChart__annotationLabel" x={a.x + 4} y={a.y + 11}>{a.label}</text>
+            {/if}
+          {/if}
+        {/each}
+      </g>
+    {/if}
+
     {#if areaPath}
       <path class="st-areaChart__area" d={areaPath} fill="url(#{gradientId})" />
     {/if}
@@ -317,6 +401,46 @@
         data-chart-index={p.index}
       />
     {/each}
+
+    <!-- Annotations ABOVE the area: lines, shapes, points, labels. -->
+    {#if annotationAbove.length > 0}
+      <g class="st-areaChart__annotations st-areaChart__annotations--above">
+        {#each annotationAbove as a (a.key)}
+          {#if a.kind === "line"}
+            <line class="st-areaChart__annotationLine" x1={a.x1} y1={a.y1} x2={a.x2} y2={a.y2} />
+            {#if a.label}
+              <text
+                class="st-areaChart__annotationLabel"
+                x={a.axis === "x" ? a.x1 + 4 : MARGIN.left + plotWidth - 4}
+                y={a.axis === "x" ? MARGIN.top + 11 : a.y1 - 4}
+                text-anchor={a.axis === "x" ? "start" : "end"}
+              >{a.label}</text>
+            {/if}
+          {:else if a.kind === "shape"}
+            <polygon class="st-areaChart__annotationShape" points={polygonPoints(a.points)} />
+            {#if a.label}
+              <text class="st-areaChart__annotationLabel" x={a.labelX} y={a.labelY} text-anchor="middle">{a.label}</text>
+            {/if}
+          {:else if a.kind === "point"}
+            <circle class="st-areaChart__annotationPoint" cx={a.x} cy={a.y} r="4.5" />
+            {#if a.label}
+              <text class="st-areaChart__annotationLabel" x={a.x} y={a.y - 8} text-anchor="middle">{a.label}</text>
+            {/if}
+          {:else}
+            <text class="st-areaChart__annotationText" x={a.x} y={a.y} text-anchor={a.anchor}>{a.text}</text>
+          {/if}
+        {/each}
+      </g>
+    {/if}
+
+    <!-- Data labels — one value per point, drawn on top. aria-hidden. -->
+    {#if dataLabelItems.length > 0}
+      <g class="st-areaChart__dataLabels" aria-hidden="true">
+        {#each dataLabelItems as d (d.key)}
+          <text class="st-areaChart__dataLabel" x={d.x} y={d.y} text-anchor="middle" dominant-baseline={d.baseline}>{d.text}</text>
+        {/each}
+      </g>
+    {/if}
     </svg>
   </div>
 
@@ -429,4 +553,39 @@
   .st-areaChart__tooltipValue {
     opacity: 0.85;
   }
+
+  /* --- Annotation layer ----------------------------------------------------
+     Regions render BEHIND the area; lines/shapes/points/labels render ABOVE. */
+  .st-areaChart__annotationRegion {
+    fill: color-mix(in srgb, var(--st-semantic-feedback-info) 12%, transparent);
+    stroke: none;
+  }
+  .st-areaChart__annotationLine {
+    stroke: var(--st-semantic-feedback-info);
+    stroke-width: 1.5;
+    stroke-dasharray: 4 3;
+  }
+  .st-areaChart__annotationShape {
+    fill: color-mix(in srgb, var(--st-semantic-feedback-info) 14%, transparent);
+    stroke: var(--st-semantic-feedback-info);
+    stroke-width: 1.5;
+  }
+  .st-areaChart__annotationPoint {
+    fill: var(--st-semantic-feedback-info);
+    stroke: var(--st-semantic-surface-default);
+    stroke-width: 1.5;
+  }
+  .st-areaChart__annotationLabel,
+  .st-areaChart__annotationText {
+    fill: var(--st-semantic-text-primary);
+    font-size: 0.625rem;
+    font-weight: 600;
+  }
+
+  /* Data labels — per-point value, drawn on top. Token-only colour. */
+  .st-areaChart__dataLabel {
+    fill: var(--st-semantic-text-primary);
+    font-size: 0.6875rem;
+    font-weight: 600;
+  }
 </style>

package/dist/AreaChart.svelte.d.ts

@@ -3,6 +3,8 @@ export type AreaChartDatum = {
     x: number | string;
     y: number;
 };
+import { type ChartAnnotation } from "./chartAnnotations.js";
+import { type DataLabelsProp } from "./chartDataLabels.js";
 type AreaChartProps = {
     data: (number | AreaChartDatum)[];
     width?: number;
@@ -10,6 +12,20 @@ type AreaChartProps = {
     tone?: AreaChartTone;
     smooth?: boolean;
     label: string;
+    /**
+     * Annotation overlay in DATA space (points, labels, axis lines, regions,
+     * polygons), resolved to pixels via the chart scales. Regions render behind
+     * the area, every other kind above it. Additive: absent ⇒ unchanged.
+     */
+    annotations?: ChartAnnotation[];
+    /**
+     * Per-point value labels. `false`/absent (default) → none. `true` → each
+     * point's value with the chart's numeric formatter. Object → `format(value)`
+     * and/or a `position` override. Default position is `top` (above the point).
+     * Labels are `aria-hidden` — the values already live in the accessible
+     * ChartDataList.
+     */
+    dataLabels?: DataLabelsProp;
     class?: string;
 };
 declare const AreaChart: import("svelte").Component<AreaChartProps, {}, "">;

package/dist/AreaChart.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AreaChart.svelte.d.ts","sourceRoot":"","sources":["../src/lib/AreaChart.svelte.ts"],"names":[],"mappings":"AAGE,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,CAAC;AAEhB,MAAM,MAAM,cAAc,GAAG;IAC3B,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACnB,CAAC,EAAE,MAAM,CAAC;CACX,CAAC;AAMF,KAAK,cAAc,GAAG;IACpB,IAAI,EAAE,CAAC,MAAM,GAAG,cAAc,CAAC,EAAE,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAmQJ,QAAA,MAAM,SAAS,oDAAwC,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}
+{"version":3,"file":"AreaChart.svelte.d.ts","sourceRoot":"","sources":["../src/lib/AreaChart.svelte.ts"],"names":[],"mappings":"AAGE,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,CAAC;AAEhB,MAAM,MAAM,cAAc,GAAG;IAC3B,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACnB,CAAC,EAAE,MAAM,CAAC;CACX,CAAC;AAIJ,OAAO,EAIH,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AACjC,OAAO,EAAwC,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG/F,KAAK,cAAc,GAAG;IACpB,IAAI,EAAE,CAAC,MAAM,GAAG,cAAc,CAAC,EAAE,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAuWJ,QAAA,MAAM,SAAS,oDAAwC,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}

package/dist/BarChart.svelte

@@ -50,6 +50,13 @@
 
 <script lang="ts">
   import ChartDataList from "./ChartDataList.svelte";
+  import {
+    resolveAnnotations,
+    annotationDataListItems,
+    polygonPoints,
+    type ChartAnnotation
+  } from "./chartAnnotations.js";
+  import { formatDataLabel, normalizeDataLabels, type DataLabelsProp } from "./chartDataLabels.js";
 
   type BarChartProps = {
     data: BarChartDatum[];
@@ -86,6 +93,22 @@
     bands?: ChartBand[];
     /** A single goal line, emphasised above the bars. */
     goalLine?: ChartGoalLine;
+    /**
+     * Annotation overlay in DATA space. The x coordinate is CATEGORICAL — it
+     * matches a bar by its `label` (centre of band) and is ignored otherwise; the
+     * y coordinate (and `value`/`from`/`to`) are value-axis numbers. Regions
+     * render behind the bars, every other kind above. Additive: absent ⇒
+     * unchanged.
+     */
+    annotations?: ChartAnnotation[];
+    /**
+     * Per-bar value labels. `false`/absent (default) → none. `true` → each bar's
+     * value with the chart's numeric formatter. Object → `format(value)` and/or
+     * a `position` override. Default position is `outside` (above the bar in
+     * vertical mode, past the bar end in horizontal mode). Labels are
+     * `aria-hidden` — the values already live in the accessible ChartDataList.
+     */
+    dataLabels?: DataLabelsProp;
     /**
      * Value-axis scale. `"linear"` (default) is unchanged. `"log"` switches the
      * value axis to a base-10 logarithmic scale — values `<= 0` are ignored for
@@ -116,6 +139,8 @@
     referenceLines,
     bands,
     goalLine,
+    annotations,
+    dataLabels,
     scale = "linear",
     invertAxis = false,
     showLegend,
@@ -469,9 +494,85 @@
     return out;
   });
 
+  // --- Annotation overlay ---------------------------------------------------
+  // The x coordinate is CATEGORICAL (a bar `label` → centre of band); the y
+  // coordinate is a value-axis number. For a HORIZONTAL chart the value axis is
+  // x and the category axis is y, so the data-space (x=category, y=value)
+  // convention is transposed onto the pixel axes: the resolver's `xScale` maps
+  // the value, `yScale` the category, and each annotation's `axis`/coords are
+  // swapped so a value reference (`axis: "y"`) still spans the full plot.
+  const categoryPixel = $derived((v: number | string): number | null => {
+    const bar = bars.find((b) => b.datum.label === String(v));
+    if (!bar) return null;
+    return isVertical ? bar.cx - MARGIN.left : bar.cy - MARGIN.top;
+  });
+  const valuePixelRel = $derived((v: number): number | null => {
+    if (!Number.isFinite(v)) return null;
+    return valuePos(v) - (isVertical ? MARGIN.top : MARGIN.left);
+  });
+  const transposeAnnotations = $derived((list: ChartAnnotation[] | undefined): ChartAnnotation[] | undefined => {
+    if (!list || isVertical) return list;
+    // Horizontal: swap the data-space x/y (and the region/line axis) so the
+    // generic resolver — which always emits xScale→x-pixel, yScale→y-pixel —
+    // lands the value on the x axis and the category on the y axis.
+    return list.map((a): ChartAnnotation => {
+      switch (a.kind) {
+        case "line":
+          return { ...a, axis: a.axis === "x" ? "y" : "x" };
+        case "region":
+          return { ...a, axis: a.axis === "x" ? "y" : "x" };
+        case "point":
+          return { ...a, x: a.y, y: typeof a.x === "number" ? a.x : NaN } as ChartAnnotation;
+        case "label":
+          return { ...a, x: a.y, y: typeof a.x === "number" ? a.x : NaN } as ChartAnnotation;
+        case "shape":
+          return { ...a, points: a.points.map((p) => ({ x: p.y, y: typeof p.x === "number" ? p.x : NaN })) };
+      }
+    });
+  });
+  const annXScale = $derived((v: number | string): number | null =>
+    isVertical ? categoryPixel(v) : typeof v === "number" ? valuePixelRel(v) : null
+  );
+  const annYScale = $derived((v: number): number | null => (isVertical ? valuePixelRel(v) : categoryPixel(v)));
+  const resolvedAnnotations = $derived(
+    resolveAnnotations(transposeAnnotations(annotations), {
+      xScale: annXScale,
+      yScale: annYScale,
+      plotLeft: MARGIN.left,
+      plotTop: MARGIN.top,
+      plotWidth: scales.plotWidth,
+      plotHeight: scales.plotHeight
+    })
+  );
+  const annotationRegions = $derived(resolvedAnnotations.filter((a) => a.kind === "region"));
+  const annotationAbove = $derived(resolvedAnnotations.filter((a) => a.kind !== "region"));
+
+  // --- Data labels ----------------------------------------------------------
+  // One value label per bar, placed at the bar's value end. Default `outside`:
+  // above the bar (vertical) / past the bar end (horizontal). `inside`/`center`
+  // sit at the bar's mid-length. aria-hidden (values are in the ChartDataList).
+  const dataLabelOpts = $derived(normalizeDataLabels(dataLabels));
+  const dataLabelItems = $derived.by(() => {
+    if (!dataLabelOpts.enabled) return [] as { key: string; x: number; y: number; text: string; anchor: "start" | "middle" | "end"; baseline: string }[];
+    return bars.map((bar) => {
+      const text = formatDataLabel(bar.datum.value, dataLabelOpts, formatTick);
+      const pos = dataLabelOpts.position ?? "outside";
+      const inside = pos === "inside" || pos === "center";
+      if (isVertical) {
+        const x = bar.cx;
+        const y = inside ? bar.y + bar.height / 2 : bar.cy - 6;
+        return { key: bar.datum.label, x, y, text, anchor: "middle" as const, baseline: inside ? "middle" : "auto" };
+      }
+      const y = bar.cy;
+      const x = inside ? bar.x + bar.width / 2 : bar.cx + 4;
+      return { key: bar.datum.label, x, y, text, anchor: inside ? ("middle" as const) : ("start" as const), baseline: "middle" };
+    });
+  });
+
   const dataValueItems = $derived([
     ...data.map((d) => `${d.label}: ${d.value}`),
-    ...overlayDataListItems(referenceLines, bands, goal)
+    ...overlayDataListItems(referenceLines, bands, goal),
+    ...annotationDataListItems(annotations)
   ]);
 
   const valueAxisTicks = $derived.by(() => {
@@ -630,6 +731,20 @@
       {/if}
     {/each}
 
+    <!-- Annotation regions sit BEHIND the bars (filled bands). -->
+    {#if annotationRegions.length > 0}
+      <g class="st-barChart__annotations st-barChart__annotations--behind">
+        {#each annotationRegions as a (a.key)}
+          {#if a.kind === "region"}
+            <rect class="st-barChart__annotationRegion" x={a.x} y={a.y} width={a.width} height={a.height} />
+            {#if a.label}
+              <text class="st-barChart__annotationLabel" x={a.x + 4} y={a.y + 11}>{a.label}</text>
+            {/if}
+          {/if}
+        {/each}
+      </g>
+    {/if}
+
     <!-- bars -->
     <!-- The bars live inside an aria-hidden SVG, so they are NEVER an accessible
          surface. When `onSelect` is provided they only carry a mouse click
@@ -681,6 +796,46 @@
         text-anchor={isVertical ? "end" : "start"}
       >{goalGeom.label ?? `Objectif ${goalGeom.value}`}</text>
     {/if}
+
+    <!-- Annotations ABOVE the bars: lines, shapes, points, labels. -->
+    {#if annotationAbove.length > 0}
+      <g class="st-barChart__annotations st-barChart__annotations--above">
+        {#each annotationAbove as a (a.key)}
+          {#if a.kind === "line"}
+            <line class="st-barChart__annotationLine" x1={a.x1} y1={a.y1} x2={a.x2} y2={a.y2} />
+            {#if a.label}
+              <text
+                class="st-barChart__annotationLabel"
+                x={a.axis === "x" ? a.x1 + 4 : MARGIN.left + scales.plotWidth - 4}
+                y={a.axis === "x" ? MARGIN.top + 11 : a.y1 - 4}
+                text-anchor={a.axis === "x" ? "start" : "end"}
+              >{a.label}</text>
+            {/if}
+          {:else if a.kind === "shape"}
+            <polygon class="st-barChart__annotationShape" points={polygonPoints(a.points)} />
+            {#if a.label}
+              <text class="st-barChart__annotationLabel" x={a.labelX} y={a.labelY} text-anchor="middle">{a.label}</text>
+            {/if}
+          {:else if a.kind === "point"}
+            <circle class="st-barChart__annotationPoint" cx={a.x} cy={a.y} r="4.5" />
+            {#if a.label}
+              <text class="st-barChart__annotationLabel" x={a.x} y={a.y - 8} text-anchor="middle">{a.label}</text>
+            {/if}
+          {:else}
+            <text class="st-barChart__annotationText" x={a.x} y={a.y} text-anchor={a.anchor}>{a.text}</text>
+          {/if}
+        {/each}
+      </g>
+    {/if}
+
+    <!-- Data labels — one value per bar, drawn on top. aria-hidden. -->
+    {#if dataLabelItems.length > 0}
+      <g class="st-barChart__dataLabels" aria-hidden="true">
+        {#each dataLabelItems as d (d.key)}
+          <text class="st-barChart__dataLabel" x={d.x} y={d.y} text-anchor={d.anchor} dominant-baseline={d.baseline}>{d.text}</text>
+        {/each}
+      </g>
+    {/if}
     </svg>
   </div>
 
@@ -934,4 +1089,39 @@
     .st-barChart__bar,
     .st-barChart__filterChip { transition: none; }
   }
+
+  /* --- Annotation layer ----------------------------------------------------
+     Regions render BEHIND the bars; lines/shapes/points/labels render ABOVE. */
+  .st-barChart__annotationRegion {
+    fill: color-mix(in srgb, var(--st-semantic-feedback-info) 12%, transparent);
+    stroke: none;
+  }
+  .st-barChart__annotationLine {
+    stroke: var(--st-semantic-feedback-info);
+    stroke-width: 1.5;
+    stroke-dasharray: 4 3;
+  }
+  .st-barChart__annotationShape {
+    fill: color-mix(in srgb, var(--st-semantic-feedback-info) 14%, transparent);
+    stroke: var(--st-semantic-feedback-info);
+    stroke-width: 1.5;
+  }
+  .st-barChart__annotationPoint {
+    fill: var(--st-semantic-feedback-info);
+    stroke: var(--st-semantic-surface-default);
+    stroke-width: 1.5;
+  }
+  .st-barChart__annotationLabel,
+  .st-barChart__annotationText {
+    fill: var(--st-semantic-text-primary);
+    font-size: 0.625rem;
+    font-weight: 600;
+  }
+
+  /* Data labels — per-bar value, drawn on top. Token-only colour. */
+  .st-barChart__dataLabel {
+    fill: var(--st-semantic-text-primary);
+    font-size: 0.6875rem;
+    font-weight: 600;
+  }
 </style>

package/dist/BarChart.svelte.d.ts

@@ -31,6 +31,8 @@ export type ChartGoalLine = {
 };
 /** Value-axis scale type. `log` requires strictly positive values. */
 export type ChartScale = "linear" | "log";
+import { type ChartAnnotation } from "./chartAnnotations.js";
+import { type DataLabelsProp } from "./chartDataLabels.js";
 type BarChartProps = {
     data: BarChartDatum[];
     width?: number;
@@ -66,6 +68,22 @@ type BarChartProps = {
     bands?: ChartBand[];
     /** A single goal line, emphasised above the bars. */
     goalLine?: ChartGoalLine;
+    /**
+     * Annotation overlay in DATA space. The x coordinate is CATEGORICAL — it
+     * matches a bar by its `label` (centre of band) and is ignored otherwise; the
+     * y coordinate (and `value`/`from`/`to`) are value-axis numbers. Regions
+     * render behind the bars, every other kind above. Additive: absent ⇒
+     * unchanged.
+     */
+    annotations?: ChartAnnotation[];
+    /**
+     * Per-bar value labels. `false`/absent (default) → none. `true` → each bar's
+     * value with the chart's numeric formatter. Object → `format(value)` and/or
+     * a `position` override. Default position is `outside` (above the bar in
+     * vertical mode, past the bar end in horizontal mode). Labels are
+     * `aria-hidden` — the values already live in the accessible ChartDataList.
+     */
+    dataLabels?: DataLabelsProp;
     /**
      * Value-axis scale. `"linear"` (default) is unchanged. `"log"` switches the
      * value axis to a base-10 logarithmic scale — values `<= 0` are ignored for

package/dist/BarChart.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BarChart.svelte.d.ts","sourceRoot":"","sources":["../src/lib/BarChart.svelte.ts"],"names":[],"mappings":"AAGE,MAAM,MAAM,YAAY,GACpB,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,CAAC;AAEhB,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AAEpF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,IAAI,CAAC,EAAE,GAAG,GAAG,GAAG,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,sEAAsE;AACtE,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,KAAK,CAAC;AAM1C,KAAK,aAAa,GAAG;IACnB,IAAI,EAAE,aAAa,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,UAAU,GAAG,YAAY,CAAC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,+DAA+D;IAC/D,cAAc,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACtC,oDAAoD;IACpD,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;IACpB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAghBJ,QAAA,MAAM,QAAQ,mDAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"BarChart.svelte.d.ts","sourceRoot":"","sources":["../src/lib/BarChart.svelte.ts"],"names":[],"mappings":"AAGE,MAAM,MAAM,YAAY,GACpB,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,CAAC;AAEhB,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AAEpF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,IAAI,CAAC,EAAE,GAAG,GAAG,GAAG,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,sEAAsE;AACtE,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,KAAK,CAAC;AAI5C,OAAO,EAIH,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AACjC,OAAO,EAAwC,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG/F,KAAK,aAAa,GAAG;IACnB,IAAI,EAAE,aAAa,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,UAAU,GAAG,YAAY,CAAC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,+DAA+D;IAC/D,cAAc,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACtC,oDAAoD;IACpD,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;IACpB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAipBJ,QAAA,MAAM,QAAQ,mDAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}

package/dist/DonutChart.svelte

@@ -12,6 +12,7 @@
 
 <script lang="ts">
   import ChartDataList from "./ChartDataList.svelte";
+  import { formatDataLabel, normalizeDataLabels, type DataLabelsProp } from "./chartDataLabels.js";
 
   type DonutChartProps = {
     data: DonutChartDatum[];
@@ -21,6 +22,14 @@
     thickness?: number;
     /** Texte au centre (sinon le total). null pour masquer. */
     centerLabel?: string | null;
+    /**
+     * Per-slice value labels. `false`/absent (default) → none. `true` → each
+     * slice's value with the default formatter. Object → `format(value)` and/or a
+     * `position` override (default `center` of the arc). Slices too thin to fit a
+     * legible label are skipped. Labels are `aria-hidden` — the values already
+     * live in the accessible ChartDataList.
+     */
+    dataLabels?: DataLabelsProp;
     label: string;
     class?: string;
   };
@@ -30,6 +39,7 @@
     size = 220,
     thickness = 34,
     centerLabel,
+    dataLabels,
     label,
     class: className
   }: DonutChartProps = $props();
@@ -39,11 +49,14 @@
     "category5", "category6", "category7", "category8"
   ];
 
+  // A slice must span at least this many degrees to host a legible label.
+  const DATA_LABEL_MIN_DEG = 18;
+
   let hoveredIndex: number | null = $state(null);
 
   const slices = $derived.by(() => {
     const total = data.reduce((sum, d) => sum + Math.max(d.value, 0), 0);
-    if (total <= 0) return { total: 0, items: [] as Array<{ d: DonutChartDatum; path: string; tone: DonutChartTone; pct: number }> };
+    if (total <= 0) return { total: 0, items: [] as Array<{ d: DonutChartDatum; path: string; tone: DonutChartTone; pct: number; spanDeg: number; labelX: number; labelY: number }> };
     const cx = size / 2;
     const cy = size / 2;
     const rOuter = size / 2 - 2;
@@ -64,7 +77,11 @@
       const [x1i, y1i] = polar(rInner, a1);
       const [x0i, y0i] = polar(rInner, a0);
       const path = `M ${x0o} ${y0o} A ${rOuter} ${rOuter} 0 ${large} 1 ${x1o} ${y1o} L ${x1i} ${y1i} A ${rInner} ${rInner} 0 ${large} 0 ${x0i} ${y0i} Z`;
-      return { d, path, tone: d.tone ?? TONES[i % TONES.length], pct: frac * 100 };
+      // Label anchor: centre of the arc (mid-angle, mid-radius of the ring).
+      const aMid = (a0 + a1) / 2;
+      const rMid = (rOuter + rInner) / 2;
+      const [labelX, labelY] = polar(rMid, aMid);
+      return { d, path, tone: d.tone ?? TONES[i % TONES.length], pct: frac * 100, spanDeg: (span * 180) / Math.PI, labelX, labelY };
     });
     return { total, items };
   });
@@ -75,6 +92,24 @@
     slices.items.map((slice) => `${slice.d.label}: ${slice.d.value} (${fmtPct(slice.pct)})`)
   );
 
+  // --- Data labels ----------------------------------------------------------
+  // One value label centred in each arc (default `center`). Slices thinner than
+  // DATA_LABEL_MIN_DEG are skipped so labels stay legible. aria-hidden (values
+  // are in the ChartDataList already).
+  const dataLabelOpts = $derived(normalizeDataLabels(dataLabels));
+  const dataLabelItems = $derived(
+    dataLabelOpts.enabled
+      ? slices.items
+          .filter((slice) => slice.spanDeg >= DATA_LABEL_MIN_DEG)
+          .map((slice) => ({
+            key: slice.d.label,
+            x: slice.labelX,
+            y: slice.labelY,
+            text: formatDataLabel(slice.d.value, dataLabelOpts, (v) => String(v))
+          }))
+      : []
+  );
+
   function handleVisualPointerMove(event: PointerEvent) {
     const target = event.target;
     if (!(target instanceof Element)) {
@@ -109,6 +144,14 @@
             {centerLabel ?? slices.total}
           </text>
         {/if}
+        <!-- Data labels — one value per slice, centred in the arc. aria-hidden. -->
+        {#if dataLabelItems.length > 0}
+          <g class="st-donutChart__dataLabels" aria-hidden="true">
+            {#each dataLabelItems as d (d.key)}
+              <text class="st-donutChart__dataLabel" x={d.x} y={d.y} text-anchor="middle" dominant-baseline="central">{d.text}</text>
+            {/each}
+          </g>
+        {/if}
       {/if}
     </svg>
   </div>
@@ -160,6 +203,13 @@
     font-weight: 650;
   }
 
+  /* Data labels — per-slice value, centred in the arc. Token-only colour. */
+  .st-donutChart__dataLabel {
+    fill: var(--st-semantic-text-inverse);
+    font-size: 0.6875rem;
+    font-weight: 600;
+  }
+
   .st-donutChart__tooltip {
     background: var(--st-semantic-surface-inverse);
     border-radius: var(--st-radius-sm, 0.25rem);

package/dist/DonutChart.svelte.d.ts

@@ -4,6 +4,7 @@ export type DonutChartDatum = {
     value: number;
     tone?: DonutChartTone;
 };
+import { type DataLabelsProp } from "./chartDataLabels.js";
 type DonutChartProps = {
     data: DonutChartDatum[];
     /** Diamètre du SVG. */
@@ -12,6 +13,14 @@ type DonutChartProps = {
     thickness?: number;
     /** Texte au centre (sinon le total). null pour masquer. */
     centerLabel?: string | null;
+    /**
+     * Per-slice value labels. `false`/absent (default) → none. `true` → each
+     * slice's value with the default formatter. Object → `format(value)` and/or a
+     * `position` override (default `center` of the arc). Slices too thin to fit a
+     * legible label are skipped. Labels are `aria-hidden` — the values already
+     * live in the accessible ChartDataList.
+     */
+    dataLabels?: DataLabelsProp;
     label: string;
     class?: string;
 };

package/dist/DonutChart.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DonutChart.svelte.d.ts","sourceRoot":"","sources":["../src/lib/DonutChart.svelte.ts"],"names":[],"mappings":"AAGE,MAAM,MAAM,cAAc,GACtB,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,GACrD,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AAE1D,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AAMF,KAAK,eAAe,GAAG;IACrB,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB,uBAAuB;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAmGJ,QAAA,MAAM,UAAU,qDAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}
+{"version":3,"file":"DonutChart.svelte.d.ts","sourceRoot":"","sources":["../src/lib/DonutChart.svelte.ts"],"names":[],"mappings":"AAGE,MAAM,MAAM,cAAc,GACtB,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,GACrD,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AAE1D,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AAIJ,OAAO,EAAwC,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG/F,KAAK,eAAe,GAAG;IACrB,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB,uBAAuB;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAsIJ,QAAA,MAAM,UAAU,qDAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}