@sentropic/design-system-svelte 0.34.24 → 0.34.25

package/dist/AreaChart.svelte

@@ -24,6 +24,7 @@
     type ChartAnnotation
   } from "./chartAnnotations.js";
   import { formatDataLabel, normalizeDataLabels, type DataLabelsProp } from "./chartDataLabels.js";
+  import { keyForX, resolveActiveIndex } from "./chartCrosshair.js";
 
   type AreaChartProps = {
     data: (number | AreaChartDatum)[];
@@ -46,6 +47,20 @@
      * ChartDataList.
      */
     dataLabels?: DataLabelsProp;
+    /**
+     * CONTROLLED synchronised hover key (FR-3). A datum's key is `String(x)`. When
+     * provided (string or null), the crosshair + tooltip track this key instead of
+     * the chart's internal pointer hover (null ⇒ nothing shown), letting a parent
+     * share one hover channel across several aligned charts. Absent (`undefined`)
+     * keeps the legacy uncontrolled behaviour.
+     */
+    hoverKey?: string | null;
+    /**
+     * Emitted when the user hovers a datum (its key) or leaves the plot (`null`).
+     * Always fired on pointer move/leave — even while CONTROLLED — so dataviz can
+     * keep the shared hover channel in sync.
+     */
+    onHoverKeyChange?: (key: string | null) => void;
     class?: string;
   };
 
@@ -58,6 +73,8 @@
     label,
     annotations,
     dataLabels,
+    hoverKey,
+    onHoverKeyChange,
     class: className
   }: AreaChartProps = $props();
 
@@ -271,19 +288,34 @@
     return entries;
   });
 
+  // Stable key per datum (FR-3): `String(x)` of the normalised datum (a bare
+  // number becomes its index). Resolves a controlled `hoverKey` to an index and
+  // feeds `onHoverKeyChange` from pointer events.
+  const hoverKeys = $derived(normalizedData.map((d) => keyForX(d.x)));
+  function emitHoverKey(index: number | null) {
+    onHoverKeyChange?.(index == null ? null : hoverKeys[index] ?? null);
+  }
   function handleLeave() {
     hoveredIndex = null;
+    emitHoverKey(null);
   }
   function handleVisualPointerMove(event: PointerEvent) {
     const target = event.target;
     if (!(target instanceof Element)) {
       hoveredIndex = null;
+      emitHoverKey(null);
       return;
     }
-    const index = Number(target.getAttribute("data-chart-index"));
-    hoveredIndex = Number.isInteger(index) ? index : null;
+    const raw = Number(target.getAttribute("data-chart-index"));
+    const index = Number.isInteger(raw) ? raw : null;
+    hoveredIndex = index;
+    emitHoverKey(index);
   }
 
+  // Index whose crosshair/tooltip is DISPLAYED: the controlled `hoverKey` when
+  // provided (resolved against `hoverKeys`), else the internal pointer index.
+  const activeIndex = $derived(resolveActiveIndex(hoverKey, hoveredIndex, hoverKeys));
+
   // Generates a unique gradient id to avoid conflicts when rendering multiple charts on the same page
   const gradientId = $derived.by(() => {
     return `st-areachart-gradient-${Math.random().toString(36).substring(2, 9)}`;
@@ -441,13 +473,23 @@
         {/each}
       </g>
     {/if}
+
+    <!-- Crosshair (FR-3) — a tokenised vertical line + marker at the active key.
+         Decorative (aria-hidden); the value is in the tooltip + ChartDataList. -->
+    {#if activeIndex >= 0 && points[activeIndex]}
+      {@const cp = points[activeIndex]}
+      <g class="st-areaChart__crosshair" aria-hidden="true">
+        <line class="st-areaChart__crosshairLine" x1={cp.x} x2={cp.x} y1={MARGIN.top} y2={MARGIN.top + plotHeight} />
+        <circle class="st-areaChart__crosshairMarker" cx={cp.x} cy={cp.y} r="5" />
+      </g>
+    {/if}
     </svg>
   </div>
 
   <ChartDataList {label} items={dataValueItems} />
 
-  {#if hoveredIndex !== null && points[hoveredIndex]}
-    {@const p = points[hoveredIndex]}
+  {#if activeIndex >= 0 && points[activeIndex]}
+    {@const p = points[activeIndex]}
     <div
       class="st-areaChart__tooltip"
       role="presentation"
@@ -588,4 +630,19 @@
     font-size: 0.6875rem;
     font-weight: 600;
   }
+
+  /* --- Crosshair layer (FR-3) ----------------------------------------------
+     A tokenised dashed vertical line at the active (hovered/controlled) key,
+     plus an emphasised marker on the point. Decorative (aria-hidden). */
+  .st-areaChart__crosshairLine {
+    stroke: var(--st-semantic-border-strong);
+    stroke-width: 1;
+    stroke-dasharray: 3 3;
+    opacity: 0.7;
+  }
+  .st-areaChart__crosshairMarker {
+    fill: currentColor;
+    stroke: var(--st-semantic-surface-default);
+    stroke-width: 2;
+  }
 </style>

package/dist/AreaChart.svelte.d.ts

@@ -26,6 +26,20 @@ type AreaChartProps = {
      * ChartDataList.
      */
     dataLabels?: DataLabelsProp;
+    /**
+     * CONTROLLED synchronised hover key (FR-3). A datum's key is `String(x)`. When
+     * provided (string or null), the crosshair + tooltip track this key instead of
+     * the chart's internal pointer hover (null ⇒ nothing shown), letting a parent
+     * share one hover channel across several aligned charts. Absent (`undefined`)
+     * keeps the legacy uncontrolled behaviour.
+     */
+    hoverKey?: string | null;
+    /**
+     * Emitted when the user hovers a datum (its key) or leaves the plot (`null`).
+     * Always fired on pointer move/leave — even while CONTROLLED — so dataviz can
+     * keep the shared hover channel in sync.
+     */
+    onHoverKeyChange?: (key: string | null) => void;
     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;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"}
+{"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;AAI/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;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAkYJ,QAAA,MAAM,SAAS,oDAAwC,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}

package/dist/BarChart.svelte

@@ -57,6 +57,7 @@
     type ChartAnnotation
   } from "./chartAnnotations.js";
   import { formatDataLabel, normalizeDataLabels, type DataLabelsProp } from "./chartDataLabels.js";
+  import { resolveActiveIndex } from "./chartCrosshair.js";
 
   type BarChartProps = {
     data: BarChartDatum[];
@@ -124,6 +125,20 @@
      * cross-chart parity and otherwise ignored.
      */
     showLegend?: boolean;
+    /**
+     * CONTROLLED synchronised hover key (FR-3). A bar's key is its `label`. When
+     * provided (string or null), the crosshair + tooltip track this key instead of
+     * the chart's internal pointer hover (null ⇒ nothing shown), letting a parent
+     * share one hover channel across several aligned charts. Absent (`undefined`)
+     * keeps the legacy uncontrolled behaviour. Independent of `selectedKeys`.
+     */
+    hoverKey?: string | null;
+    /**
+     * Emitted when the user hovers a bar (its `label`) or leaves the plot (`null`).
+     * Always fired on pointer move/leave — even while CONTROLLED — so dataviz can
+     * keep the shared hover channel in sync.
+     */
+    onHoverKeyChange?: (key: string | null) => void;
     class?: string;
   };
 
@@ -144,6 +159,8 @@
     scale = "linear",
     invertAxis = false,
     showLegend,
+    hoverKey,
+    onHoverKeyChange,
     class: className
   }: BarChartProps = $props();
 
@@ -599,19 +616,33 @@
     }));
   });
 
+  // Stable key per bar (FR-3): its `label`. Resolves a controlled `hoverKey` to
+  // an index and feeds `onHoverKeyChange` from pointer events.
+  const hoverKeys = $derived(bars.map((b) => b.datum.label));
+  function emitHoverKey(index: number | null) {
+    onHoverKeyChange?.(index == null ? null : hoverKeys[index] ?? null);
+  }
   function handleLeave() {
     hoveredIndex = null;
+    emitHoverKey(null);
   }
   function handleVisualPointerMove(event: PointerEvent) {
     const target = event.target;
     if (!(target instanceof Element)) {
       hoveredIndex = null;
+      emitHoverKey(null);
       return;
     }
-    const index = Number(target.getAttribute("data-chart-index"));
-    hoveredIndex = Number.isInteger(index) ? index : null;
+    const raw = Number(target.getAttribute("data-chart-index"));
+    const index = Number.isInteger(raw) ? raw : null;
+    hoveredIndex = index;
+    emitHoverKey(index);
   }
 
+  // Index whose crosshair/tooltip is DISPLAYED: the controlled `hoverKey` when
+  // provided (resolved against `hoverKeys`), else the internal pointer index.
+  const activeIndex = $derived(resolveActiveIndex(hoverKey, hoveredIndex, hoverKeys));
+
   const classes = () => ["st-barChart", className].filter(Boolean).join(" ");
 </script>
 
@@ -836,6 +867,20 @@
         {/each}
       </g>
     {/if}
+
+    <!-- Crosshair (FR-3) — a tokenised dashed line on the CATEGORY axis at the
+         active bar: vertical (vertical bars) / horizontal (horizontal bars).
+         Decorative (aria-hidden); the value is in the tooltip + ChartDataList. -->
+    {#if activeIndex >= 0 && bars[activeIndex]}
+      {@const cb = bars[activeIndex]}
+      <g class="st-barChart__crosshair" aria-hidden="true">
+        {#if isVertical}
+          <line class="st-barChart__crosshairLine" x1={cb.cx} x2={cb.cx} y1={MARGIN.top} y2={MARGIN.top + scales.plotHeight} />
+        {:else}
+          <line class="st-barChart__crosshairLine" x1={MARGIN.left} x2={MARGIN.left + scales.plotWidth} y1={cb.cy} y2={cb.cy} />
+        {/if}
+      </g>
+    {/if}
     </svg>
   </div>
 
@@ -861,8 +906,8 @@
 
   <ChartDataList {label} items={dataValueItems} />
 
-  {#if hoveredIndex !== null && bars[hoveredIndex]}
-    {@const bar = bars[hoveredIndex]}
+  {#if activeIndex >= 0 && bars[activeIndex]}
+    {@const bar = bars[activeIndex]}
     <div
       class="st-barChart__tooltip"
       role="presentation"
@@ -1124,4 +1169,14 @@
     font-size: 0.6875rem;
     font-weight: 600;
   }
+
+  /* --- Crosshair layer (FR-3) ----------------------------------------------
+     A tokenised dashed line on the CATEGORY axis at the active (hovered/
+     controlled) bar. Decorative (aria-hidden). */
+  .st-barChart__crosshairLine {
+    stroke: var(--st-semantic-border-strong);
+    stroke-width: 1;
+    stroke-dasharray: 3 3;
+    opacity: 0.7;
+  }
 </style>

package/dist/BarChart.svelte.d.ts

@@ -99,6 +99,20 @@ type BarChartProps = {
      * cross-chart parity and otherwise ignored.
      */
     showLegend?: boolean;
+    /**
+     * CONTROLLED synchronised hover key (FR-3). A bar's key is its `label`. When
+     * provided (string or null), the crosshair + tooltip track this key instead of
+     * the chart's internal pointer hover (null ⇒ nothing shown), letting a parent
+     * share one hover channel across several aligned charts. Absent (`undefined`)
+     * keeps the legacy uncontrolled behaviour. Independent of `selectedKeys`.
+     */
+    hoverKey?: string | null;
+    /**
+     * Emitted when the user hovers a bar (its `label`) or leaves the plot (`null`).
+     * Always fired on pointer move/leave — even while CONTROLLED — so dataviz can
+     * keep the shared hover channel in sync.
+     */
+    onHoverKeyChange?: (key: string | null) => void;
     class?: string;
 };
 declare const BarChart: import("svelte").Component<BarChartProps, {}, "">;

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;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"}
+{"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;AAI/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;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AA8qBJ,QAAA,MAAM,QAAQ,mDAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}

package/dist/LineChart.svelte

@@ -60,6 +60,7 @@
     type ChartAnnotation
   } from "./chartAnnotations.js";
   import { formatDataLabel, normalizeDataLabels, type DataLabelsProp } from "./chartDataLabels.js";
+  import { keyForX, resolveActiveIndex } from "./chartCrosshair.js";
 
   type LineChartProps = {
     data: LineChartDatum[];
@@ -111,6 +112,20 @@
      * no legend surface, so this prop is accepted for parity and otherwise ignored.
      */
     showLegend?: boolean;
+    /**
+     * CONTROLLED synchronised hover key (FR-3). A datum's key is `String(x)`. When
+     * provided (string or null), the crosshair + tooltip track this key instead of
+     * the chart's internal pointer hover (null ⇒ nothing shown), letting a parent
+     * share one hover channel across several aligned charts. Absent (`undefined`)
+     * keeps the legacy uncontrolled behaviour.
+     */
+    hoverKey?: string | null;
+    /**
+     * Emitted when the user hovers a datum (its key) or leaves the plot (`null`).
+     * Always fired on pointer move/leave — even while CONTROLLED — so dataviz can
+     * keep the shared hover channel in sync.
+     */
+    onHoverKeyChange?: (key: string | null) => void;
     class?: string;
   };
 
@@ -132,6 +147,8 @@
     scale = "linear",
     invertAxis = false,
     showLegend,
+    hoverKey,
+    onHoverKeyChange,
     class: className
   }: LineChartProps = $props();
 
@@ -617,19 +634,33 @@
     return entries;
   });
 
+  // Stable key per datum (FR-3): `String(x)`. Resolves a controlled `hoverKey`
+  // to an index and feeds `onHoverKeyChange` from pointer events.
+  const hoverKeys = $derived(data.map((d) => keyForX(d.x)));
+  function emitHoverKey(index: number | null) {
+    onHoverKeyChange?.(index == null ? null : hoverKeys[index] ?? null);
+  }
   function handleLeave() {
     hoveredIndex = null;
+    emitHoverKey(null);
   }
   function handleVisualPointerMove(event: PointerEvent) {
     const target = event.target;
     if (!(target instanceof Element)) {
       hoveredIndex = null;
+      emitHoverKey(null);
       return;
     }
-    const index = Number(target.getAttribute("data-chart-index"));
-    hoveredIndex = Number.isInteger(index) ? index : null;
+    const raw = Number(target.getAttribute("data-chart-index"));
+    const index = Number.isInteger(raw) ? raw : null;
+    hoveredIndex = index;
+    emitHoverKey(index);
   }
 
+  // Index whose crosshair/tooltip is DISPLAYED: the controlled `hoverKey` when
+  // provided (resolved against `hoverKeys`), else the internal pointer index.
+  const activeIndex = $derived(resolveActiveIndex(hoverKey, hoveredIndex, hoverKeys));
+
   const classes = () =>
     ["st-lineChart", `st-lineChart--${tone}`, className].filter(Boolean).join(" ");
 </script>
@@ -820,13 +851,23 @@
         {/each}
       </g>
     {/if}
+
+    <!-- Crosshair (FR-3) — a tokenised vertical line + marker at the active key.
+         Decorative (aria-hidden); the value is in the tooltip + ChartDataList. -->
+    {#if activeIndex >= 0 && points[activeIndex]}
+      {@const cp = points[activeIndex]}
+      <g class="st-lineChart__crosshair" aria-hidden="true">
+        <line class="st-lineChart__crosshairLine" x1={cp.x} x2={cp.x} y1={MARGIN.top} y2={MARGIN.top + plotHeight} />
+        <circle class="st-lineChart__crosshairMarker" cx={cp.x} cy={cp.y} r="5" />
+      </g>
+    {/if}
     </svg>
   </div>
 
   <ChartDataList {label} items={dataValueItems} />
 
-  {#if hoveredIndex !== null && points[hoveredIndex]}
-    {@const p = points[hoveredIndex]}
+  {#if activeIndex >= 0 && points[activeIndex]}
+    {@const p = points[activeIndex]}
     <div
       class="st-lineChart__tooltip"
       role="presentation"
@@ -1028,4 +1069,19 @@
     font-size: 0.6875rem;
     font-weight: 600;
   }
+
+  /* --- Crosshair layer (FR-3) ----------------------------------------------
+     A tokenised dashed vertical line at the active (hovered/controlled) key,
+     plus an emphasised marker on the point. Decorative (aria-hidden). */
+  .st-lineChart__crosshairLine {
+    stroke: var(--st-semantic-border-strong);
+    stroke-width: 1;
+    stroke-dasharray: 3 3;
+    opacity: 0.7;
+  }
+  .st-lineChart__crosshairMarker {
+    fill: currentColor;
+    stroke: var(--st-semantic-surface-default);
+    stroke-width: 2;
+  }
 </style>

package/dist/LineChart.svelte.d.ts

@@ -86,6 +86,20 @@ type LineChartProps = {
      * no legend surface, so this prop is accepted for parity and otherwise ignored.
      */
     showLegend?: boolean;
+    /**
+     * CONTROLLED synchronised hover key (FR-3). A datum's key is `String(x)`. When
+     * provided (string or null), the crosshair + tooltip track this key instead of
+     * the chart's internal pointer hover (null ⇒ nothing shown), letting a parent
+     * share one hover channel across several aligned charts. Absent (`undefined`)
+     * keeps the legacy uncontrolled behaviour.
+     */
+    hoverKey?: string | null;
+    /**
+     * Emitted when the user hovers a datum (its key) or leaves the plot (`null`).
+     * Always fired on pointer move/leave — even while CONTROLLED — so dataviz can
+     * keep the shared hover channel in sync.
+     */
+    onHoverKeyChange?: (key: string | null) => void;
     class?: string;
 };
 declare const LineChart: import("svelte").Component<LineChartProps, {}, "">;

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;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"}
+{"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;AAI/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;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AA+qBJ,QAAA,MAAM,SAAS,oDAAwC,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}

package/dist/chartCrosshair.d.ts

@@ -0,0 +1,19 @@
+/** Serialises a Line/Area datum's `x` to its stable hover key. */
+export declare function keyForX(x: number | string): string;
+/**
+ * Resolves the hover key to a datum index within `keys` (the ordered list of
+ * every datum's key). Returns -1 when the key is null/undefined or unmatched.
+ */
+export declare function indexForHoverKey(hoverKey: string | null | undefined, keys: string[]): number;
+/**
+ * Picks the datum index to DISPLAY the crosshair/tooltip at.
+ *   - Controlled (`hoverKey !== undefined`): the index of `hoverKey` in `keys`
+ *     (or -1 when null/unmatched). The internal pointer index is ignored for
+ *     display.
+ *   - Uncontrolled (`hoverKey === undefined`): the internal pointer index.
+ * Returns -1 when nothing should be shown.
+ */
+export declare function resolveActiveIndex(hoverKey: string | null | undefined, internalIndex: number | null, keys: string[]): number;
+/** True when the chart is CONTROLLED (the parent supplied `hoverKey`). */
+export declare function isControlled(hoverKey: string | null | undefined): boolean;
+//# sourceMappingURL=chartCrosshair.d.ts.map

package/dist/chartCrosshair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chartCrosshair.d.ts","sourceRoot":"","sources":["../src/lib/chartCrosshair.ts"],"names":[],"mappings":"AAsBA,kEAAkE;AAClE,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAElD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAG5F;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,aAAa,EAAE,MAAM,GAAG,IAAI,EAC5B,IAAI,EAAE,MAAM,EAAE,GACb,MAAM,CAGR;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAEzE"}

package/dist/chartCrosshair.js

@@ -0,0 +1,51 @@
+// --- Chart crosshair / synchronised hover layer (shared, framework-agnostic) -
+//
+// FR-3: a CONTROLLED crosshair + tooltip whose position is driven by a `hoverKey`
+// string the parent owns, so dataviz can share one hover channel across several
+// aligned panels (a "linked" tooltip). The DS stays presentational: it resolves
+// the key to a datum index, draws a tokenised vertical line at that x (plus a
+// marker on the point for Line/Area), and reuses the existing tooltip surface.
+//
+// The "key" is the stable identifier of a datum on the categorical/x axis:
+//   - Bar:        the bar's `label`.
+//   - Line/Area:  the point's `x`, serialised with `String(x)`.
+//
+// Behaviour:
+//   - `hoverKey === undefined` → UNCONTROLLED (internal hover, unchanged, fully
+//     backward compatible).
+//   - `hoverKey` provided (string or null) → CONTROLLED: the displayed
+//     crosshair/tooltip tracks `hoverKey` (null = nothing shown), the chart's own
+//     pointer hover no longer drives the DISPLAY, but `onHoverKeyChange` is still
+//     emitted so the parent can keep the shared channel in sync.
+//
+// Purely additive: a chart that passes neither prop renders exactly as before.
+/** Serialises a Line/Area datum's `x` to its stable hover key. */
+export function keyForX(x) {
+    return String(x);
+}
+/**
+ * Resolves the hover key to a datum index within `keys` (the ordered list of
+ * every datum's key). Returns -1 when the key is null/undefined or unmatched.
+ */
+export function indexForHoverKey(hoverKey, keys) {
+    if (hoverKey == null)
+        return -1;
+    return keys.indexOf(hoverKey);
+}
+/**
+ * Picks the datum index to DISPLAY the crosshair/tooltip at.
+ *   - Controlled (`hoverKey !== undefined`): the index of `hoverKey` in `keys`
+ *     (or -1 when null/unmatched). The internal pointer index is ignored for
+ *     display.
+ *   - Uncontrolled (`hoverKey === undefined`): the internal pointer index.
+ * Returns -1 when nothing should be shown.
+ */
+export function resolveActiveIndex(hoverKey, internalIndex, keys) {
+    if (hoverKey !== undefined)
+        return indexForHoverKey(hoverKey, keys);
+    return internalIndex == null ? -1 : internalIndex;
+}
+/** True when the chart is CONTROLLED (the parent supplied `hoverKey`). */
+export function isControlled(hoverKey) {
+    return hoverKey !== undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentropic/design-system-svelte",
-  "version": "0.34.24",
+  "version": "0.34.25",
   "type": "module",
   "publishConfig": {
     "access": "public"