@sentropic/design-system-svelte 0.34.28 → 0.34.33

package/dist/ScatterPlot.svelte

@@ -26,6 +26,15 @@
 
 <script lang="ts">
   import ChartDataList from "./ChartDataList.svelte";
+  import {
+    annotationDataListItems,
+    polygonPoints,
+    resolveAnnotations,
+    type ChartAnnotation,
+  } from "./chartAnnotations.js";
+  import { formatDataLabel, normalizeDataLabels, type DataLabelsProp } from "./chartDataLabels.js";
+  import { resolveActiveIndex } from "./chartCrosshair.js";
+  import { datapointAriaLabel, datapointNavAction, rovingTabIndex } from "./chartKeyboardNav.js";
 
   type ScatterPlotProps = {
     data: ScatterPlotDatum[];
@@ -39,6 +48,29 @@
      * coordinates are folded into the axis domain. Non-finite x/y are skipped.
      */
     centroids?: ScatterPlotCentroid[];
+    /**
+     * Annotation overlay in DATA space (points, labels, axis lines, regions,
+     * polygons). Both axes are continuous (linear). Additive: absent ⇒ unchanged.
+     */
+    annotations?: ChartAnnotation[];
+    /**
+     * Per-point value labels. `false`/absent → none. `true` → each point's value
+     * (the datum `label` wins when present). Object → `format`/`position`.
+     * Default position `top`. Labels are `aria-hidden`.
+     */
+    dataLabels?: DataLabelsProp;
+    /**
+     * CONTROLLED synchronised hover key (FR-3). A point's key is its `label` when
+     * present, otherwise `"x,y"`. Absent (`undefined`) keeps the uncontrolled
+     * behaviour.
+     */
+    hoverKey?: string | null;
+    /** Emitted on hover (the key) / leave (`null`); fired even while controlled. */
+    onHoverKeyChange?: (key: string | null) => void;
+    /** FR-5 — roving-tabindex keyboard navigation of the data points. */
+    keyboardNav?: boolean;
+    /** Emitted on Enter/Space select (the key) / Escape (`null`); enables nav. */
+    onSelectKey?: (key: string | null) => void;
     label: string;
     class?: string;
   };
@@ -51,6 +83,12 @@
     yLabel,
     radius = 5,
     centroids,
+    annotations,
+    dataLabels,
+    hoverKey,
+    onHoverKeyChange,
+    keyboardNav,
+    onSelectKey,
     label,
     class: className
   }: ScatterPlotProps = $props();
@@ -88,6 +126,9 @@
   }
 
   let hoveredIndex: number | null = $state(null);
+  // FR-5 — roving keyboard focus over the data points (separate from hover).
+  let focusedIndex: number = $state(-1);
+  let datapointRefs: Array<SVGRectElement | null> = [];
 
   const TONES = ["category1","category2","category3","category4","category5","category6","category7","category8"] as const;
 
@@ -95,6 +136,11 @@
   // the plot); non-finite/negative values fall back to the global radius.
   const MAX_POINT_RADIUS = 32;
 
+  /** Stable hover/selection key of a point: its label, else `"x,y"`. */
+  function keyForPoint(d: ScatterPlotDatum): string {
+    return d.label ?? `${d.x},${d.y}`;
+  }
+
   // Centroids guarded once: non-finite coordinates are skipped entirely.
   const validCentroids = $derived(
     (centroids ?? []).filter((c) => Number.isFinite(c.x) && Number.isFinite(c.y))
@@ -124,6 +170,7 @@
       cy: MARGIN.top + scaleLinear(d.y, yMin, yMax, plotH, 0),
       r: typeof d.r === "number" && Number.isFinite(d.r) && d.r >= 0 ? Math.min(d.r, MAX_POINT_RADIUS) : radius,
       datum: d,
+      index: i,
       tone: d.tone ?? TONES[i % TONES.length]
     }));
   });
@@ -138,21 +185,110 @@
     }));
   });
 
+  // --- Annotation overlay ----------------------------------------------------
+  // Both axes continuous: linear `xScale`/`yScale`, out-of-domain ⇒ null.
+  const annotationXScale = $derived((v: number | string): number | null => {
+    const { xMin, xMax, plotW } = scales;
+    if (typeof v !== "number" || !Number.isFinite(v)) return null;
+    if (v < xMin || v > xMax) return null;
+    return scaleLinear(v, xMin, xMax, 0, plotW);
+  });
+  const annotationYScale = $derived((v: number): number | null => {
+    const { yMin, yMax, plotH } = scales;
+    if (!Number.isFinite(v)) return null;
+    if (v < yMin || v > yMax) return null;
+    return scaleLinear(v, yMin, yMax, plotH, 0);
+  });
+  const resolvedAnnotations = $derived(
+    resolveAnnotations(annotations, {
+      xScale: annotationXScale,
+      yScale: annotationYScale,
+      plotLeft: MARGIN.left,
+      plotTop: MARGIN.top,
+      plotWidth: scales.plotW,
+      plotHeight: scales.plotH
+    })
+  );
+  const annotationRegions = $derived(resolvedAnnotations.filter((a) => a.kind === "region"));
+  const annotationAbove = $derived(resolvedAnnotations.filter((a) => a.kind !== "region"));
+
+  // --- Data labels -----------------------------------------------------------
+  // One label per point. Default `top`. The datum `label` wins; else the y.
+  const dataLabelOpts = $derived(normalizeDataLabels(dataLabels));
+  const dataLabelItems = $derived(
+    dataLabelOpts.enabled
+      ? points.map((p) => {
+          const text = p.datum.label ?? formatDataLabel(p.datum.y, dataLabelOpts, fmt);
+          const center = dataLabelOpts.position === "center" || dataLabelOpts.position === "inside";
+          return {
+            key: p.index,
+            x: p.cx,
+            y: center ? p.cy : p.cy - (p.r + 5),
+            text,
+            baseline: (center ? "middle" : "auto") as "middle" | "auto"
+          };
+        })
+      : []
+  );
+
   const dataValueItems = $derived([
     ...data.map((d) => (d.label ? `${d.label}: x ${d.x}, y ${d.y}` : `x ${d.x}, y ${d.y}`)),
     ...validCentroids.map((c) =>
       c.label ? `Centroïde ${c.label}: (${c.x}, ${c.y})` : `Centroïde: (${c.x}, ${c.y})`
-    )
+    ),
+    ...annotationDataListItems(annotations)
   ]);
 
+  // Stable key per point (FR-3): `label` else `"x,y"`.
+  const hoverKeys = $derived(data.map((d) => keyForPoint(d)));
+  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));
+
+  // --- Keyboard navigation (FR-5) --------------------------------------------
+  // Active when wired explicitly (`keyboardNav`) or implicitly (`onSelectKey`).
+  const navEnabled = $derived((keyboardNav === true || onSelectKey !== undefined) && points.length > 0);
+  // Comfortable square hit area centred on each dot.
+  const NAV_HIT = 18;
+  function focusDatum(index: number) {
+    focusedIndex = index;
+    datapointRefs[index]?.focus();
+    emitHoverKey(index);
+  }
+  function handleDatapointKeyDown(event: KeyboardEvent, index: number) {
+    const action = datapointNavAction(event.key, index, points.length);
+    if (!action) return;
+    event.preventDefault();
+    if (action.kind === "move") {
+      focusDatum(action.index);
+    } else if (action.kind === "select") {
+      onSelectKey?.(hoverKeys[index] ?? null);
+    } else {
+      focusedIndex = -1;
+      emitHoverKey(null);
+      onSelectKey?.(null);
+      (event.currentTarget as SVGElement).blur();
+    }
   }
 
   const classes = () => ["st-scatterPlot", className].filter(Boolean).join(" ");
@@ -164,7 +300,7 @@
     role="img"
     aria-label={label}
     onpointermove={handleVisualPointerMove}
-    onpointerleave={() => (hoveredIndex = null)}
+    onpointerleave={handleLeave}
   >
     <svg viewBox="0 0 {width} {height}" preserveAspectRatio="xMidYMid meet" width="100%" height="100%" focusable="false" aria-hidden="true">
       <!-- gridlines + ticks Y -->
@@ -190,6 +326,20 @@
         <text class="st-scatterPlot__axisLabel" x={12} y={MARGIN.top + scales.plotH / 2} text-anchor="middle" transform="rotate(-90 12 {MARGIN.top + scales.plotH / 2})">{yLabel}</text>
       {/if}
 
+      <!-- Annotation regions sit BEHIND the points (filled bands). -->
+      {#if annotationRegions.length > 0}
+        <g class="st-scatterPlot__annotations st-scatterPlot__annotations--behind">
+          {#each annotationRegions as a (a.key)}
+            {#if a.kind === "region"}
+              <rect class="st-scatterPlot__annotationRegion" x={a.x} y={a.y} width={a.width} height={a.height} />
+              {#if a.label}
+                <text class="st-scatterPlot__annotationLabel" x={a.x + 4} y={a.y + 11}>{a.label}</text>
+              {/if}
+            {/if}
+          {/each}
+        </g>
+      {/if}
+
       <!-- points -->
       {#each points as p, i (i)}
         <circle
@@ -209,13 +359,100 @@
           <line class="st-scatterPlot__centroidCross" x1={c.cx} x2={c.cx} y1={c.cy - 3.5} y2={c.cy + 3.5} />
         </g>
       {/each}
+
+      <!-- Annotations ABOVE the points: lines, shapes, points, labels. -->
+      {#if annotationAbove.length > 0}
+        <g class="st-scatterPlot__annotations st-scatterPlot__annotations--above">
+          {#each annotationAbove as a (a.key)}
+            {#if a.kind === "line"}
+              <line class="st-scatterPlot__annotationLine" x1={a.x1} y1={a.y1} x2={a.x2} y2={a.y2} />
+              {#if a.label}
+                <text
+                  class="st-scatterPlot__annotationLabel"
+                  x={a.axis === "x" ? a.x1 + 4 : MARGIN.left + scales.plotW - 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-scatterPlot__annotationShape" points={polygonPoints(a.points)} />
+              {#if a.label}
+                <text class="st-scatterPlot__annotationLabel" x={a.labelX} y={a.labelY} text-anchor="middle">{a.label}</text>
+              {/if}
+            {:else if a.kind === "point"}
+              <circle class="st-scatterPlot__annotationPoint" cx={a.x} cy={a.y} r="4.5" />
+              {#if a.label}
+                <text class="st-scatterPlot__annotationLabel" x={a.x} y={a.y - 8} text-anchor="middle">{a.label}</text>
+              {/if}
+            {:else if a.kind === "label"}
+              <text class="st-scatterPlot__annotationText" x={a.x} y={a.y} text-anchor={a.anchor}>{a.text}</text>
+            {/if}
+          {/each}
+        </g>
+      {/if}
+
+      <!-- Data labels — one value/label per point, drawn on top. aria-hidden. -->
+      {#if dataLabelItems.length > 0}
+        <g class="st-scatterPlot__dataLabels" aria-hidden="true">
+          {#each dataLabelItems as d (d.key)}
+            <text class="st-scatterPlot__dataLabel" x={d.x} y={d.y} text-anchor="middle" dominant-baseline={d.baseline}>{d.text}</text>
+          {/each}
+        </g>
+      {/if}
+
+      <!-- Crosshair (FR-3) — a tokenised CROSSED pair (vertical + horizontal) at
+           the active key, plus a marker on the point. Decorative (aria-hidden). -->
+      {#if activeIndex >= 0 && points[activeIndex]}
+        {@const cp = points[activeIndex]}
+        <g class="st-scatterPlot__crosshair" aria-hidden="true">
+          <line class="st-scatterPlot__crosshairLine" x1={cp.cx} x2={cp.cx} y1={MARGIN.top} y2={MARGIN.top + scales.plotH} />
+          <line class="st-scatterPlot__crosshairLine" x1={MARGIN.left} x2={MARGIN.left + scales.plotW} y1={cp.cy} y2={cp.cy} />
+          <circle class="st-scatterPlot__crosshairMarker" cx={cp.cx} cy={cp.cy} r="5" />
+        </g>
+      {/if}
     </svg>
+
+    <!-- Keyboard navigation overlay (FR-5) — a focusable, transparent hit layer
+         over the points. NOT aria-hidden: it is the accessible roving cursor.
+         Each rect announces its key + value; the focus ring is tokenised via
+         CSS. Absent unless keyboard nav is enabled. -->
+    {#if navEnabled}
+      <svg
+        class="st-scatterPlot__navLayer"
+        viewBox="0 0 {width} {height}"
+        preserveAspectRatio="xMidYMid meet"
+        width="100%"
+        height="100%"
+        role="group"
+        aria-label={`${label} — points de données`}
+      >
+        {#each points as p, i (p.index)}
+          <rect
+            bind:this={datapointRefs[i]}
+            class="st-scatterPlot__navDatum"
+            x={p.cx - NAV_HIT / 2}
+            y={p.cy - NAV_HIT / 2}
+            width={NAV_HIT}
+            height={NAV_HIT}
+            rx="3"
+            role="img"
+            tabindex={rovingTabIndex(i, focusedIndex, points.length)}
+            aria-label={datapointAriaLabel(p.datum.label ?? `${p.datum.x}, ${p.datum.y}`, p.datum.y)}
+            onkeydown={(event) => handleDatapointKeyDown(event, i)}
+            onfocus={() => {
+              focusedIndex = i;
+              emitHoverKey(i);
+            }}
+          />
+        {/each}
+      </svg>
+    {/if}
   </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-scatterPlot__tooltip" role="presentation" style="left: {(p.cx / width) * 100}%; top: {(p.cy / height) * 100}%">
       {#if p.datum.label}<span class="st-scatterPlot__tooltipLabel">{p.datum.label}</span>{/if}
       <span class="st-scatterPlot__tooltipValue">x {p.datum.x} · y {p.datum.y}</span>
@@ -252,6 +489,23 @@
   .st-scatterPlot__centroid--category6 { color: var(--st-semantic-data-category6); }
   .st-scatterPlot__centroid--category7 { color: var(--st-semantic-data-category7); }
   .st-scatterPlot__centroid--category8 { color: var(--st-semantic-data-category8); }
+  /* --- Annotation layer ----------------------------------------------------
+     Regions render BEHIND the points (color-mix tint, never raw opacity so the
+     data keeps contrast); lines/shapes/points/labels render ABOVE. */
+  .st-scatterPlot__annotationRegion { fill: color-mix(in srgb, var(--st-semantic-feedback-info) 12%, transparent); stroke: none; }
+  .st-scatterPlot__annotationLine { stroke: var(--st-semantic-feedback-info); stroke-width: 1.5; stroke-dasharray: 4 3; }
+  .st-scatterPlot__annotationShape { fill: color-mix(in srgb, var(--st-semantic-feedback-info) 14%, transparent); stroke: var(--st-semantic-feedback-info); stroke-width: 1.5; }
+  .st-scatterPlot__annotationPoint { fill: var(--st-semantic-feedback-info); stroke: var(--st-semantic-surface-default); stroke-width: 1.5; }
+  .st-scatterPlot__annotationLabel, .st-scatterPlot__annotationText { fill: var(--st-semantic-text-primary); font-size: 0.625rem; font-weight: 600; }
+  /* Data labels — per-point value/label, drawn on top. Token-only colour. */
+  .st-scatterPlot__dataLabel { fill: var(--st-semantic-text-primary); font-size: 0.6875rem; font-weight: 600; }
+  /* --- Crosshair layer (FR-3) — tokenised CROSSED pair + marker. -------------- */
+  .st-scatterPlot__crosshairLine { stroke: var(--st-semantic-border-strong); stroke-width: 1; stroke-dasharray: 3 3; opacity: 0.7; }
+  .st-scatterPlot__crosshairMarker { fill: currentColor; stroke: var(--st-semantic-surface-default); stroke-width: 2; }
+  /* --- Keyboard navigation layer (FR-5) — focusable transparent hit-rects. ---- */
+  .st-scatterPlot__navLayer { inset: 0; position: absolute; }
+  .st-scatterPlot__navDatum { fill: transparent; outline: none; }
+  .st-scatterPlot__navDatum:focus-visible { fill: color-mix(in srgb, var(--st-semantic-border-interactive) 12%, transparent); outline: 2px solid var(--st-semantic-border-interactive); outline-offset: 1px; }
   @media (prefers-reduced-motion: reduce) {
     .st-scatterPlot__point { transition: none; }
   }

package/dist/ScatterPlot.svelte.d.ts

@@ -17,6 +17,8 @@ export type ScatterPlotCentroid = {
     tone?: ScatterPlotTone;
     label?: string;
 };
+import { type ChartAnnotation } from "./chartAnnotations.js";
+import { type DataLabelsProp } from "./chartDataLabels.js";
 type ScatterPlotProps = {
     data: ScatterPlotDatum[];
     width?: number;
@@ -29,6 +31,29 @@ type ScatterPlotProps = {
      * coordinates are folded into the axis domain. Non-finite x/y are skipped.
      */
     centroids?: ScatterPlotCentroid[];
+    /**
+     * Annotation overlay in DATA space (points, labels, axis lines, regions,
+     * polygons). Both axes are continuous (linear). Additive: absent ⇒ unchanged.
+     */
+    annotations?: ChartAnnotation[];
+    /**
+     * Per-point value labels. `false`/absent → none. `true` → each point's value
+     * (the datum `label` wins when present). Object → `format`/`position`.
+     * Default position `top`. Labels are `aria-hidden`.
+     */
+    dataLabels?: DataLabelsProp;
+    /**
+     * CONTROLLED synchronised hover key (FR-3). A point's key is its `label` when
+     * present, otherwise `"x,y"`. Absent (`undefined`) keeps the uncontrolled
+     * behaviour.
+     */
+    hoverKey?: string | null;
+    /** Emitted on hover (the key) / leave (`null`); fired even while controlled. */
+    onHoverKeyChange?: (key: string | null) => void;
+    /** FR-5 — roving-tabindex keyboard navigation of the data points. */
+    keyboardNav?: boolean;
+    /** Emitted on Enter/Space select (the key) / Escape (`null`); enables nav. */
+    onSelectKey?: (key: string | null) => void;
     label: string;
     class?: string;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"ScatterPlot.svelte.d.ts","sourceRoot":"","sources":["../src/lib/ScatterPlot.svelte.ts"],"names":[],"mappings":"AAGE,MAAM,MAAM,eAAe,GACvB,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,GACrD,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AAE1D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB;;;OAGG;IACH,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF,2EAA2E;AAC3E,MAAM,MAAM,mBAAmB,GAAG;IAChC,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAMF,KAAK,gBAAgB,GAAG;IACtB,IAAI,EAAE,gBAAgB,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,SAAS,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAmLJ,QAAA,MAAM,WAAW,sDAAwC,CAAC;AAC1D,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAClD,eAAe,WAAW,CAAC"}
+{"version":3,"file":"ScatterPlot.svelte.d.ts","sourceRoot":"","sources":["../src/lib/ScatterPlot.svelte.ts"],"names":[],"mappings":"AAGE,MAAM,MAAM,eAAe,GACvB,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,GACrD,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AAE1D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB;;;OAGG;IACH,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF,2EAA2E;AAC3E,MAAM,MAAM,mBAAmB,GAAG;IAChC,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAIJ,OAAO,EAIH,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AACjC,OAAO,EAAwC,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAK/F,KAAK,gBAAgB,GAAG;IACtB,IAAI,EAAE,gBAAgB,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,SAAS,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAClC;;;OAGG;IACH,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC;;;;OAIG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gFAAgF;IAChF,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAChD,qEAAqE;IACrE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAsWJ,QAAA,MAAM,WAAW,sDAAwC,CAAC;AAC1D,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAClD,eAAe,WAAW,CAAC"}

package/dist/SelectableList.svelte

@@ -58,8 +58,11 @@
   let internal = $state<Set<string>>(new Set());
   const selectedValues = $derived(controlled ? toSet(value) : internal);
 
-  // --- Row registry: ordered by DOM position so arrow nav matches the visual
-  //     order regardless of registration timing. -------------------------------
+  // --- Row registry. Rows are stored in INSERTION order (registration is O(1));
+  //     the DOM-ordered view is computed LAZILY (see `orderedEntries`) and only
+  //     when a consumer actually needs visual order (arrow nav / roving tab stop).
+  //     Sorting eagerly on every register() was O(n) per mount → O(n²) for the
+  //     whole list (issue #26); deferring it makes a large list mount in O(n).
   type Entry = { el: HTMLElement; value: string | undefined; disabled?: boolean };
   let entries = $state<Entry[]>([]);
 
@@ -76,17 +79,28 @@
     });
   }
 
+  // DOM-ordered view of the registry. Memoised by `$derived.by` so the O(n log n)
+  // `compareDocumentPosition` sort runs at most ONCE per registry change (a batch
+  // of mounts in the same tick collapses into a single recompute), not once per
+  // register() call. ORDER-dependent readers (`navigate`, `effectiveTabStop`'s
+  // "first enabled row") read THIS so visual order is correct regardless of
+  // registration timing; order-INDEPENDENT lookups (`valueOf`/`isSelected`,
+  // disabled-membership) read the raw `entries`. register() itself stays O(1).
+  const orderedEntries = $derived.by(() => sortByDom(entries));
+
   // register/unregister are called from each row's $effect. They read AND write
   // `entries`, so the read must be untracked — otherwise the calling effect would
   // subscribe to `entries`, and writing it would re-run the effect forever.
-  // Disabled rows are registered with disabled:true so navigate() can skip them
-  // explicitly, making the skip correct even when disabled state changes mid-session.
+  // register() APPENDS in insertion order (O(1)); the DOM sort is deferred to the
+  // lazy `orderedEntries`. Disabled rows are registered with disabled:true so
+  // navigate() can skip them explicitly, making the skip correct even when the
+  // disabled state changes mid-session.
   function register(el: HTMLElement, rowValue: string | undefined, rowDisabled = false): () => void {
     untrack(() => {
-      entries = sortByDom([
+      entries = [
         ...entries.filter((e) => e.el !== el),
         { el, value: rowValue, disabled: rowDisabled }
-      ]);
+      ];
     });
     return () => {
       untrack(() => {
@@ -103,7 +117,8 @@
       const entry = entries.find((e) => e.el === tabStopEl);
       if (entry && !entry.disabled) return tabStopEl;
     }
-    return entries.find((e) => !e.disabled)?.el ?? null;
+    // "First enabled row" must be in DOM order, so read the ordered view.
+    return orderedEntries.find((e) => !e.disabled)?.el ?? null;
   });
 
   // Si la row qui détient le focus DOM devient disabled (in-place, sans unmount),
@@ -161,38 +176,42 @@
   }
 
   function navigate(el: HTMLElement, key: string) {
-    if (entries.length === 0) return;
-    const idx = entries.findIndex((e) => e.el === el);
+    // Keyboard navigation walks rows in VISUAL (DOM) order, so read the lazily
+    // sorted view here. This is the first point the deferred sort is forced — the
+    // O(n²) register-time sort storm is gone, the sort runs once on demand.
+    const ordered = orderedEntries;
+    if (ordered.length === 0) return;
+    const idx = ordered.findIndex((e) => e.el === el);
     if (idx === -1) return;
 
     let targetIdx: number | null = null;
 
     if (key === "ArrowDown" || key === "ArrowRight") {
       // Walk forward from current position, find the next non-disabled entry.
-      for (let i = idx + 1; i < entries.length; i++) {
-        if (!entries[i].disabled) { targetIdx = i; break; }
+      for (let i = idx + 1; i < ordered.length; i++) {
+        if (!ordered[i].disabled) { targetIdx = i; break; }
       }
     } else if (key === "ArrowUp" || key === "ArrowLeft") {
       // Walk backward from current position, find the previous non-disabled entry.
       for (let i = idx - 1; i >= 0; i--) {
-        if (!entries[i].disabled) { targetIdx = i; break; }
+        if (!ordered[i].disabled) { targetIdx = i; break; }
       }
     } else if (key === "Home") {
       // First non-disabled entry.
-      for (let i = 0; i < entries.length; i++) {
-        if (!entries[i].disabled) { targetIdx = i; break; }
+      for (let i = 0; i < ordered.length; i++) {
+        if (!ordered[i].disabled) { targetIdx = i; break; }
       }
     } else if (key === "End") {
       // Last non-disabled entry.
-      for (let i = entries.length - 1; i >= 0; i--) {
-        if (!entries[i].disabled) { targetIdx = i; break; }
+      for (let i = ordered.length - 1; i >= 0; i--) {
+        if (!ordered[i].disabled) { targetIdx = i; break; }
       }
     }
 
     // If no target found (all remaining are disabled, or already at boundary), stay put.
     if (targetIdx === null) return;
 
-    const target = entries[targetIdx]?.el;
+    const target = ordered[targetIdx]?.el;
     if (target) {
       tabStopEl = target;
       target.focus();

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

@@ -1 +1 @@
-{"version":3,"file":"SelectableList.svelte.d.ts","sourceRoot":"","sources":["../src/lib/SelectableList.svelte.ts"],"names":[],"mappings":"AAGE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC,MAAM,MAAM,mBAAmB,GAAG;IAChC,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,KAAK,IAAI,CAAC;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AA0MJ,QAAA,MAAM,cAAc,yDAAwC,CAAC;AAC7D,KAAK,cAAc,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;AACxD,eAAe,cAAc,CAAC"}
+{"version":3,"file":"SelectableList.svelte.d.ts","sourceRoot":"","sources":["../src/lib/SelectableList.svelte.ts"],"names":[],"mappings":"AAGE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC,MAAM,MAAM,mBAAmB,GAAG;IAChC,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,KAAK,IAAI,CAAC;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AA6NJ,QAAA,MAAM,cAAc,yDAAwC,CAAC;AAC7D,KAAK,cAAc,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;AACxD,eAAe,cAAc,CAAC"}

package/dist/SelectableRow.svelte

@@ -60,6 +60,16 @@
     trailing?: Snippet;
     /** Main content. */
     children?: Snippet;
+    /**
+     * Optional secondary line (the "legend") rendered MUTED and smaller UNDER
+     * `children`. When present the content column stacks vertically (a
+     * `--hasCaption` modifier); when absent the row stays single-line and
+     * byte-identical. The caption joins the row's accessible name by default (the
+     * SR reads "label, caption"); wrap it `aria-hidden` if it is purely
+     * decorative. MUST NOT contain interactive controls — a row is a single tab
+     * stop.
+     */
+    caption?: Snippet;
     class?: string;
   };
 </script>
@@ -77,6 +87,7 @@
     leading,
     trailing,
     children,
+    caption,
     class: className
   }: SelectableRowProps = $props();
 
@@ -125,6 +136,7 @@
       isSelected ? "st-selectableRow--selected" : null,
       disabled ? "st-selectableRow--disabled" : null,
       accentBar ? "st-selectableRow--accentBar" : null,
+      caption ? "st-selectableRow--hasCaption" : null,
       className
     ]
       .filter(Boolean)
@@ -190,7 +202,17 @@
   {#if leading}
     <span class="st-selectableRow__leading">{@render leading()}</span>
   {/if}
-  <span class="st-selectableRow__content">{@render children?.()}</span>
+  {#if caption}
+    <!-- Caption present: the content column stacks the primary label over a muted
+         second line. Both lines truncate independently (each min-width:0 + ellipsis)
+         so a long caption never pushes the row width. -->
+    <span class="st-selectableRow__content st-selectableRow__content--stacked">
+      <span class="st-selectableRow__label">{@render children?.()}</span>
+      <span class="st-selectableRow__caption">{@render caption()}</span>
+    </span>
+  {:else}
+    <span class="st-selectableRow__content">{@render children?.()}</span>
+  {/if}
   {#if trailing}
     <span class="st-selectableRow__trailing">{@render trailing()}</span>
   {/if}
@@ -300,6 +322,36 @@
     white-space: nowrap;
   }
 
+  /* Caption variant (additive). Rows WITHOUT a caption keep the single-line
+     `.st-selectableRow__content` above byte-identically (no `--stacked` rule
+     applies). `--stacked` overlays a vertical column: the primary `__label` keeps
+     its own single-line ellipsis, and the muted `__caption` truncates
+     independently so a long legend never pushes the row width. Every leaf falls
+     back to a base literal so a theme that emits no
+     `--st-component-selectableRow-caption*` renders the caption identically. */
+  .st-selectableRow__content--stacked {
+    display: flex;
+    flex-direction: column;
+    /* The column stack drops the inline ellipsis/nowrap (each line truncates on
+       its own child); keep min-width:0 so the column can shrink and ellipsize. */
+    overflow: visible;
+    white-space: normal;
+    gap: var(--st-component-selectableRow-captionGap, 0.125rem);
+  }
+
+  .st-selectableRow__label,
+  .st-selectableRow__caption {
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .st-selectableRow__caption {
+    color: var(--st-component-selectableRow-captionColor, var(--st-semantic-text-muted));
+    font-size: var(--st-component-selectableRow-captionFontSize, 0.75rem);
+  }
+
   @media (prefers-reduced-motion: reduce) {
     .st-selectableRow { transition: none; }
   }

package/dist/SelectableRow.svelte.d.ts

@@ -56,6 +56,16 @@ export type SelectableRowProps = {
     trailing?: Snippet;
     /** Main content. */
     children?: Snippet;
+    /**
+     * Optional secondary line (the "legend") rendered MUTED and smaller UNDER
+     * `children`. When present the content column stacks vertically (a
+     * `--hasCaption` modifier); when absent the row stays single-line and
+     * byte-identical. The caption joins the row's accessible name by default (the
+     * SR reads "label, caption"); wrap it `aria-hidden` if it is purely
+     * decorative. MUST NOT contain interactive controls — a row is a single tab
+     * stop.
+     */
+    caption?: Snippet;
     class?: string;
 };
 declare const SelectableRow: import("svelte").Component<SelectableRowProps, {}, "selected">;

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

@@ -1 +1 @@
-{"version":3,"file":"SelectableRow.svelte.d.ts","sourceRoot":"","sources":["../src/lib/SelectableRow.svelte.ts"],"names":[],"mappings":"AAGE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,eAA+B,CAAC;AAEhE,MAAM,MAAM,qBAAqB,GAAG;IAClC,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IACvB,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,wIAAwI;IACxI,QAAQ,EAAE,CAAC,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,CAAC,EAAE,OAAO,KAAK,MAAM,IAAI,CAAC;IACzF,uDAAuD;IACvD,UAAU,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC;IACzC,iFAAiF;IACjF,SAAS,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC;IACxC,6EAA6E;IAC7E,QAAQ,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,IAAI,CAAC;IACpC,wDAAwD;IACxD,QAAQ,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,IAAI,CAAC;IACpC,gDAAgD;IAChD,QAAQ,EAAE,CAAC,EAAE,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;IACvC,iCAAiC;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,oCAAoC;IACpC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,oBAAoB;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAiIJ,QAAA,MAAM,aAAa,gEAAwC,CAAC;AAC5D,KAAK,aAAa,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;AACtD,eAAe,aAAa,CAAC"}
+{"version":3,"file":"SelectableRow.svelte.d.ts","sourceRoot":"","sources":["../src/lib/SelectableRow.svelte.ts"],"names":[],"mappings":"AAGE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,eAA+B,CAAC;AAEhE,MAAM,MAAM,qBAAqB,GAAG;IAClC,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IACvB,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,wIAAwI;IACxI,QAAQ,EAAE,CAAC,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,CAAC,EAAE,OAAO,KAAK,MAAM,IAAI,CAAC;IACzF,uDAAuD;IACvD,UAAU,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC;IACzC,iFAAiF;IACjF,SAAS,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC;IACxC,6EAA6E;IAC7E,QAAQ,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,IAAI,CAAC;IACpC,wDAAwD;IACxD,QAAQ,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,IAAI,CAAC;IACpC,gDAAgD;IAChD,QAAQ,EAAE,CAAC,EAAE,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;IACvC,iCAAiC;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,oCAAoC;IACpC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,oBAAoB;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AA2IJ,QAAA,MAAM,aAAa,gEAAwC,CAAC;AAC5D,KAAK,aAAa,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;AACtD,eAAe,aAAa,CAAC"}