@sentropic/design-system-svelte 0.34.22 → 0.34.24

package/dist/LineChart.svelte

@@ -53,6 +53,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 LineChartProps = {
     data: LineChartDatum[];
@@ -70,6 +77,21 @@
     goalLine?: ChartGoalLine;
     /** Least-squares trend line over the data points. */
     trend?: boolean;
+    /**
+     * Annotation overlay in DATA space (points, labels, axis lines, regions,
+     * polygons). Resolved to pixels via the chart's scales and drawn in a
+     * dedicated `<g class="st-lineChart__annotations">` — regions behind the
+     * series, 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;
     /**
      * Fixed value-axis (y) domain `[min, max]`. When provided (and finite,
      * min<max) the y scale uses it instead of the data-derived range — letting
@@ -104,6 +126,8 @@
     bands,
     goalLine,
     trend = false,
+    annotations,
+    dataLabels,
     domain,
     scale = "linear",
     invertAxis = false,
@@ -441,6 +465,53 @@
     };
   });
 
+  // --- Annotation overlay ---------------------------------------------------
+  // Data-space annotations resolved to absolute pixels via the chart scales.
+  // `xScale` honours the ordinal/numeric x domain (a category matches by
+  // equality, a numeric value must sit inside the domain); `yScale` reuses the
+  // value fraction. Out-of-domain coordinates yield `null` → the resolver drops
+  // them, so an annotation never escapes the plot.
+  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 = data.findIndex((d) => d.x === v);
+    if (i < 0) return null;
+    const denom = Math.max(data.length - 1, 1);
+    return data.length === 1 ? plotWidth / 2 : (i / denom) * plotWidth;
+  });
+  const annotationYScale = $derived((v: number): number | null => {
+    if (!Number.isFinite(v)) return null;
+    return plotHeight * (1 - valueFraction(v));
+  });
+  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" };
+    });
+  });
+
   // --- Forecast segments ------------------------------------------------------
   // A datum with `forecast: true` renders as a forecast point: its dot takes
   // the forecast tone and every segment touching a forecast point is dashed,
@@ -466,7 +537,8 @@
 
   const dataValueItems = $derived([
     ...data.map((d, i) => (forecastFlags[i] ? `${d.x}: ${d.y} (prévision)` : `${d.x}: ${d.y}`)),
-    ...overlayDataListItems(referenceLines, bands, goal, trendModel)
+    ...overlayDataListItems(referenceLines, bands, goal, trendModel),
+    ...annotationDataListItems(annotations)
   ]);
 
   function buildLinearPath(pts: { x: number; y: number }[]): string {
@@ -651,6 +723,20 @@
       <line class="st-lineChart__trend" x1={trendLine.x1} y1={trendLine.y1} x2={trendLine.x2} y2={trendLine.y2} />
     {/if}
 
+    <!-- Annotation regions sit BEHIND the series (filled bands). -->
+    {#if annotationRegions.length > 0}
+      <g class="st-lineChart__annotations st-lineChart__annotations--behind">
+        {#each annotationRegions as a (a.key)}
+          {#if a.kind === "region"}
+            <rect class="st-lineChart__annotationRegion" x={a.x} y={a.y} width={a.width} height={a.height} />
+            {#if a.label}
+              <text class="st-lineChart__annotationLabel" x={a.x + 4} y={a.y + 11}>{a.label}</text>
+            {/if}
+          {/if}
+        {/each}
+      </g>
+    {/if}
+
     {#if area && areaPath}
       <path class="st-lineChart__area" d={areaPath} />
     {/if}
@@ -694,6 +780,46 @@
         {goalGeom.label ?? `Objectif ${goalGeom.value}`}
       </text>
     {/if}
+
+    <!-- Annotations ABOVE the series: lines, shapes, points, labels. -->
+    {#if annotationAbove.length > 0}
+      <g class="st-lineChart__annotations st-lineChart__annotations--above">
+        {#each annotationAbove as a (a.key)}
+          {#if a.kind === "line"}
+            <line class="st-lineChart__annotationLine" x1={a.x1} y1={a.y1} x2={a.x2} y2={a.y2} />
+            {#if a.label}
+              <text
+                class="st-lineChart__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-lineChart__annotationShape" points={polygonPoints(a.points)} />
+            {#if a.label}
+              <text class="st-lineChart__annotationLabel" x={a.labelX} y={a.labelY} text-anchor="middle">{a.label}</text>
+            {/if}
+          {:else if a.kind === "point"}
+            <circle class="st-lineChart__annotationPoint" cx={a.x} cy={a.y} r="4.5" />
+            {#if a.label}
+              <text class="st-lineChart__annotationLabel" x={a.x} y={a.y - 8} text-anchor="middle">{a.label}</text>
+            {/if}
+          {:else}
+            <text class="st-lineChart__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-lineChart__dataLabels" aria-hidden="true">
+        {#each dataLabelItems as d (d.key)}
+          <text class="st-lineChart__dataLabel" x={d.x} y={d.y} text-anchor="middle" dominant-baseline={d.baseline}>{d.text}</text>
+        {/each}
+      </g>
+    {/if}
     </svg>
   </div>
 
@@ -867,4 +993,39 @@
     font-size: 0.6875rem;
     font-weight: 600;
   }
+
+  /* --- Annotation layer ----------------------------------------------------
+     Regions render BEHIND the series; lines/shapes/points/labels render ABOVE. */
+  .st-lineChart__annotationRegion {
+    fill: color-mix(in srgb, var(--st-semantic-feedback-info) 12%, transparent);
+    stroke: none;
+  }
+  .st-lineChart__annotationLine {
+    stroke: var(--st-semantic-feedback-info);
+    stroke-width: 1.5;
+    stroke-dasharray: 4 3;
+  }
+  .st-lineChart__annotationShape {
+    fill: color-mix(in srgb, var(--st-semantic-feedback-info) 14%, transparent);
+    stroke: var(--st-semantic-feedback-info);
+    stroke-width: 1.5;
+  }
+  .st-lineChart__annotationPoint {
+    fill: var(--st-semantic-feedback-info);
+    stroke: var(--st-semantic-surface-default);
+    stroke-width: 1.5;
+  }
+  .st-lineChart__annotationLabel,
+  .st-lineChart__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-lineChart__dataLabel {
+    fill: var(--st-semantic-text-primary);
+    font-size: 0.6875rem;
+    font-weight: 600;
+  }
 </style>

package/dist/LineChart.svelte.d.ts

@@ -34,6 +34,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 LineChartProps = {
     data: LineChartDatum[];
     width?: number;
@@ -50,6 +52,21 @@ type LineChartProps = {
     goalLine?: ChartGoalLine;
     /** Least-squares trend line over the data points. */
     trend?: boolean;
+    /**
+     * Annotation overlay in DATA space (points, labels, axis lines, regions,
+     * polygons). Resolved to pixels via the chart's scales and drawn in a
+     * dedicated `<g class="st-lineChart__annotations">` — regions behind the
+     * series, 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;
     /**
      * Fixed value-axis (y) domain `[min, max]`. When provided (and finite,
      * min<max) the y scale uses it instead of the data-derived range — letting

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

@@ -1 +1 @@
-{"version":3,"file":"LineChart.svelte.d.ts","sourceRoot":"","sources":["../src/lib/LineChart.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;IACV;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,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,cAAc,GAAG;IACpB,IAAI,EAAE,cAAc,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,cAAc,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACtC,oDAAoD;IACpD,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;IACpB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,qDAAqD;IACrD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1B;;;;OAIG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,iDAAiD;IACjD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAgjBJ,QAAA,MAAM,SAAS,oDAAwC,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}
+{"version":3,"file":"LineChart.svelte.d.ts","sourceRoot":"","sources":["../src/lib/LineChart.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;IACV;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,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,cAAc,GAAG;IACpB,IAAI,EAAE,cAAc,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,cAAc,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACtC,oDAAoD;IACpD,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;IACpB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,qDAAqD;IACrD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1B;;;;OAIG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,iDAAiD;IACjD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAqpBJ,QAAA,MAAM,SAAS,oDAAwC,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}

package/dist/StackedBarChart.svelte

@@ -17,6 +17,7 @@
 
 <script lang="ts">
   import ChartDataList from "./ChartDataList.svelte";
+  import { formatDataLabel, normalizeDataLabels, type DataLabelsProp } from "./chartDataLabels.js";
 
   type StackedBarChartProps = {
     data: StackedBarDatum[];
@@ -24,6 +25,14 @@
     height?: number;
     label: string;
     showLegend?: boolean;
+    /**
+     * Per-segment value labels. `false`/absent (default) → none. `true` → each
+     * segment's value with the chart's numeric formatter. Object → `format(value)`
+     * and/or a `position` override (default `center` of the segment). Segments too
+     * short to host a legible label are skipped. Labels are `aria-hidden` — the
+     * values already live in the accessible ChartDataList.
+     */
+    dataLabels?: DataLabelsProp;
     class?: string;
   };
 
@@ -33,12 +42,16 @@
     height = 260,
     label,
     showLegend = true,
+    dataLabels,
     class: className
   }: StackedBarChartProps = $props();
 
   const MARGIN = { top: 14, right: 16, bottom: 34, left: 44 };
   const TONES = ["category1","category2","category3","category4","category5","category6","category7","category8"] as const;
 
+  // A segment must be at least this tall (px) to host a legible label.
+  const DATA_LABEL_MIN_SEG_PX = 14;
+
   function niceTicks(min: number, max: number, target = 5): number[] {
     if (!Number.isFinite(min) || !Number.isFinite(max) || min === max) return [Number.isFinite(max) ? max : 0];
     const range = max - min;
@@ -104,6 +117,26 @@
     data.flatMap((bar) => bar.segments.map((seg) => `${bar.label}, ${seg.label}: ${seg.value}`))
   );
 
+  // --- Data labels ----------------------------------------------------------
+  // One value label centred in each segment (default `center`). Segments shorter
+  // than DATA_LABEL_MIN_SEG_PX are skipped so labels stay legible. aria-hidden
+  // (values are in the ChartDataList already).
+  const dataLabelOpts = $derived(normalizeDataLabels(dataLabels));
+  const dataLabelItems = $derived(
+    dataLabelOpts.enabled
+      ? bars.flatMap((bar) =>
+          bar.segs
+            .filter((s) => s.height >= DATA_LABEL_MIN_SEG_PX)
+            .map((s) => ({
+              key: `${bar.label}-${s.seg.label}`,
+              x: s.cx,
+              y: s.cy,
+              text: formatDataLabel(s.seg.value, dataLabelOpts, fmt)
+            }))
+        )
+      : []
+  );
+
   function handleVisualPointerMove(event: PointerEvent) {
     const target = event.target;
     if (!(target instanceof Element)) {
@@ -148,6 +181,15 @@
           />
         {/each}
       {/each}
+
+      <!-- Data labels — one value per segment, drawn on top. aria-hidden. -->
+      {#if dataLabelItems.length > 0}
+        <g class="st-stackedBar__dataLabels" aria-hidden="true">
+          {#each dataLabelItems as d (d.key)}
+            <text class="st-stackedBar__dataLabel" x={d.x} y={d.y} text-anchor="middle" dominant-baseline="central">{d.text}</text>
+          {/each}
+        </g>
+      {/if}
     </svg>
   </div>
 
@@ -189,6 +231,8 @@
   .st-stackedBar__seg--category6 { fill: var(--st-semantic-data-category6); }
   .st-stackedBar__seg--category7 { fill: var(--st-semantic-data-category7); }
   .st-stackedBar__seg--category8 { fill: var(--st-semantic-data-category8); }
+  /* Data labels — per-segment value, centred. Token-only colour. */
+  .st-stackedBar__dataLabel { fill: var(--st-semantic-text-inverse); font-size: 0.6875rem; font-weight: 600; }
   .st-stackedBar__tooltip {
     background: var(--st-semantic-surface-inverse); border-radius: var(--st-radius-sm, 0.25rem);
     color: var(--st-semantic-text-inverse); display: inline-flex; flex-direction: column; font-size: 0.75rem;

package/dist/StackedBarChart.svelte.d.ts

@@ -8,12 +8,21 @@ export type StackedBarDatum = {
     label: string;
     segments: StackedBarSegment[];
 };
+import { type DataLabelsProp } from "./chartDataLabels.js";
 type StackedBarChartProps = {
     data: StackedBarDatum[];
     width?: number;
     height?: number;
     label: string;
     showLegend?: boolean;
+    /**
+     * Per-segment value labels. `false`/absent (default) → none. `true` → each
+     * segment's value with the chart's numeric formatter. Object → `format(value)`
+     * and/or a `position` override (default `center` of the segment). Segments too
+     * short to host a legible label are skipped. Labels are `aria-hidden` — the
+     * values already live in the accessible ChartDataList.
+     */
+    dataLabels?: DataLabelsProp;
     class?: string;
 };
 declare const StackedBarChart: import("svelte").Component<StackedBarChartProps, {}, "">;

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

@@ -1 +1 @@
-{"version":3,"file":"StackedBarChart.svelte.d.ts","sourceRoot":"","sources":["../src/lib/StackedBarChart.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,iBAAiB,GAAG;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B,CAAC;AAMF,KAAK,oBAAoB,GAAG;IAC1B,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAiJJ,QAAA,MAAM,eAAe,0DAAwC,CAAC;AAC9D,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;AAC1D,eAAe,eAAe,CAAC"}
+{"version":3,"file":"StackedBarChart.svelte.d.ts","sourceRoot":"","sources":["../src/lib/StackedBarChart.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,iBAAiB,GAAG;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B,CAAC;AAIJ,OAAO,EAAwC,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG/F,KAAK,oBAAoB,GAAG;IAC1B,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAmLJ,QAAA,MAAM,eAAe,0DAAwC,CAAC;AAC9D,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;AAC1D,eAAe,eAAe,CAAC"}

package/dist/chartAnnotations.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Marker glyph for a `point` annotation. Defaults to `circle`.
+ */
+export type ChartAnnotationMarker = "circle" | "square" | "diamond";
+/**
+ * A single chart annotation in DATA space. Discriminated on `kind`:
+ * - `point`  — a marked coordinate `(x, y)` with an optional label.
+ * - `label`  — free text anchored at `(x, y)`.
+ * - `line`   — a full-width/height guide on one axis at `value` (vertical when
+ *              `axis: "x"`, horizontal when `axis: "y"`).
+ * - `region` — a filled band on one axis between `from` and `to`.
+ * - `shape`  — a closed polygon through `points` (data-space coordinates).
+ *
+ * `x` may be a string for categorical (ordinal) x axes — it then matches a
+ * category by equality; `y` and value-axis numbers are always numeric.
+ */
+export type ChartAnnotation = {
+    kind: "point";
+    x: number | string;
+    y: number;
+    label?: string;
+    marker?: ChartAnnotationMarker;
+} | {
+    kind: "label";
+    x: number | string;
+    y: number;
+    text: string;
+    anchor?: "start" | "middle" | "end";
+} | {
+    kind: "line";
+    axis: "x" | "y";
+    value: number;
+    label?: string;
+} | {
+    kind: "region";
+    axis: "x" | "y";
+    from: number;
+    to: number;
+    label?: string;
+} | {
+    kind: "shape";
+    points: {
+        x: number | string;
+        y: number;
+    }[];
+    label?: string;
+};
+/**
+ * Scale context for {@link resolveAnnotations}. `xScale` / `yScale` map a data
+ * value to a pixel offset RELATIVE to the plot (0..plotWidth / 0..plotHeight),
+ * returning `null` when the value is non-finite, out of domain, or — for a
+ * categorical x axis — does not match any category. `plotLeft` / `plotTop` are
+ * the plot's pixel origin (chart margins); `plotWidth` / `plotHeight` its size.
+ */
+export type AnnotationScaleContext = {
+    xScale: (value: number | string) => number | null;
+    yScale: (value: number) => number | null;
+    plotLeft: number;
+    plotTop: number;
+    plotWidth: number;
+    plotHeight: number;
+};
+/** Resolved annotation primitive in ABSOLUTE pixel space (plot origin folded in). */
+export type ResolvedAnnotation = {
+    kind: "region";
+    key: number;
+    axis: "x" | "y";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    label?: string;
+} | {
+    kind: "line";
+    key: number;
+    axis: "x" | "y";
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    label?: string;
+} | {
+    kind: "shape";
+    key: number;
+    points: {
+        x: number;
+        y: number;
+    }[];
+    label?: string;
+    labelX: number;
+    labelY: number;
+} | {
+    kind: "point";
+    key: number;
+    x: number;
+    y: number;
+    label?: string;
+    marker: ChartAnnotationMarker;
+} | {
+    kind: "label";
+    key: number;
+    x: number;
+    y: number;
+    text: string;
+    anchor: "start" | "middle" | "end";
+};
+/**
+ * Resolves DATA-space annotations to ABSOLUTE-pixel primitives. Pure: given the
+ * same inputs it always returns the same output, with no DOM/framework access.
+ *
+ * Region/line on `axis: "x"` are positioned via `xScale` (vertical guide / band
+ * spanning the full plot height); on `axis: "y"` via `yScale` (horizontal guide
+ * / band spanning the full plot width). Points, labels and shape vertices are
+ * positioned via both scales. Any annotation whose required coordinates fall
+ * outside the domain (scale returns `null`) or are non-finite is DROPPED, so an
+ * annotation never escapes the plot. The original index is preserved as `key`
+ * for stable rendering keys + a11y ordering.
+ */
+export declare function resolveAnnotations(annotations: ReadonlyArray<ChartAnnotation> | undefined, ctx: AnnotationScaleContext): ResolvedAnnotation[];
+/**
+ * Screen-reader descriptions of the annotations, appended after the data values
+ * (and any analytical overlays) in the ChartDataList. Each item is
+ * `Annotation: <label/text>`; annotations without a label/text are skipped
+ * (nothing meaningful to announce). Empty when no annotation is present.
+ */
+export declare function annotationDataListItems(annotations: ReadonlyArray<ChartAnnotation> | undefined): string[];
+/** SVG polygon `points` attribute from resolved pixel vertices. */
+export declare function polygonPoints(points: ReadonlyArray<{
+    x: number;
+    y: number;
+}>): string;
+//# sourceMappingURL=chartAnnotations.d.ts.map

package/dist/chartAnnotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chartAnnotations.d.ts","sourceRoot":"","sources":["../src/lib/chartAnnotations.ts"],"names":[],"mappings":"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"}

package/dist/chartAnnotations.js

@@ -0,0 +1,125 @@
+// --- Chart annotation layer (shared, framework-agnostic) -------------------
+//
+// A declarative overlay of annotations expressed in DATA space (x / y values),
+// resolved here to framework-agnostic PIXEL primitives. The model is the
+// `ChartAnnotation` discriminated union provided by dataviz-core; the resolver
+// is pure and identical across react / vue / svelte so the three renderers stay
+// in strict parity. Purely additive: an absent/empty `annotations` prop yields
+// no primitives and no a11y items.
+const finite = (v) => typeof v === "number" && Number.isFinite(v);
+/**
+ * Resolves DATA-space annotations to ABSOLUTE-pixel primitives. Pure: given the
+ * same inputs it always returns the same output, with no DOM/framework access.
+ *
+ * Region/line on `axis: "x"` are positioned via `xScale` (vertical guide / band
+ * spanning the full plot height); on `axis: "y"` via `yScale` (horizontal guide
+ * / band spanning the full plot width). Points, labels and shape vertices are
+ * positioned via both scales. Any annotation whose required coordinates fall
+ * outside the domain (scale returns `null`) or are non-finite is DROPPED, so an
+ * annotation never escapes the plot. The original index is preserved as `key`
+ * for stable rendering keys + a11y ordering.
+ */
+export function resolveAnnotations(annotations, ctx) {
+    if (!annotations || annotations.length === 0)
+        return [];
+    const { xScale, yScale, plotLeft, plotTop, plotWidth, plotHeight } = ctx;
+    const out = [];
+    annotations.forEach((a, key) => {
+        switch (a.kind) {
+            case "region": {
+                if (!finite(a.from) || !finite(a.to))
+                    return;
+                if (a.axis === "x") {
+                    const p1 = xScale(a.from);
+                    const p2 = xScale(a.to);
+                    if (p1 === null || p2 === null)
+                        return;
+                    const x = plotLeft + Math.min(p1, p2);
+                    out.push({ kind: "region", key, axis: "x", x, y: plotTop, width: Math.max(Math.abs(p2 - p1), 0.5), height: plotHeight, label: a.label });
+                }
+                else {
+                    const p1 = yScale(a.from);
+                    const p2 = yScale(a.to);
+                    if (p1 === null || p2 === null)
+                        return;
+                    const y = plotTop + Math.min(p1, p2);
+                    out.push({ kind: "region", key, axis: "y", x: plotLeft, y, width: plotWidth, height: Math.max(Math.abs(p2 - p1), 0.5), label: a.label });
+                }
+                return;
+            }
+            case "line": {
+                if (!finite(a.value))
+                    return;
+                if (a.axis === "x") {
+                    const p = xScale(a.value);
+                    if (p === null)
+                        return;
+                    const x = plotLeft + p;
+                    out.push({ kind: "line", key, axis: "x", x1: x, y1: plotTop, x2: x, y2: plotTop + plotHeight, label: a.label });
+                }
+                else {
+                    const p = yScale(a.value);
+                    if (p === null)
+                        return;
+                    const y = plotTop + p;
+                    out.push({ kind: "line", key, axis: "y", x1: plotLeft, y1: y, x2: plotLeft + plotWidth, y2: y, label: a.label });
+                }
+                return;
+            }
+            case "shape": {
+                if (!a.points || a.points.length < 2)
+                    return;
+                const pts = [];
+                for (const p of a.points) {
+                    const px = xScale(p.x);
+                    const py = yScale(p.y);
+                    if (px === null || py === null)
+                        return; // a missing vertex invalidates the polygon
+                    pts.push({ x: plotLeft + px, y: plotTop + py });
+                }
+                const labelX = pts.reduce((s, p) => s + p.x, 0) / pts.length;
+                const labelY = pts.reduce((s, p) => s + p.y, 0) / pts.length;
+                out.push({ kind: "shape", key, points: pts, label: a.label, labelX, labelY });
+                return;
+            }
+            case "point": {
+                const px = xScale(a.x);
+                const py = yScale(a.y);
+                if (px === null || py === null)
+                    return;
+                out.push({ kind: "point", key, x: plotLeft + px, y: plotTop + py, label: a.label, marker: a.marker ?? "circle" });
+                return;
+            }
+            case "label": {
+                const px = xScale(a.x);
+                const py = yScale(a.y);
+                if (px === null || py === null)
+                    return;
+                out.push({ kind: "label", key, x: plotLeft + px, y: plotTop + py, text: a.text, anchor: a.anchor ?? "middle" });
+                return;
+            }
+        }
+    });
+    return out;
+}
+/**
+ * Screen-reader descriptions of the annotations, appended after the data values
+ * (and any analytical overlays) in the ChartDataList. Each item is
+ * `Annotation: <label/text>`; annotations without a label/text are skipped
+ * (nothing meaningful to announce). Empty when no annotation is present.
+ */
+export function annotationDataListItems(annotations) {
+    if (!annotations || annotations.length === 0)
+        return [];
+    const items = [];
+    for (const a of annotations) {
+        const text = a.kind === "label" ? a.text : a.label;
+        if (text)
+            items.push(`Annotation: ${text}`);
+    }
+    return items;
+}
+/** SVG polygon `points` attribute from resolved pixel vertices. */
+export function polygonPoints(points) {
+    return points.map((p) => `${p.x.toFixed(2)},${p.y.toFixed(2)}`).join(" ");
+}