@sentropic/design-system-svelte 0.34.32 → 0.34.34

package/dist/Badge.svelte

@@ -4,13 +4,50 @@
 
   type BadgeProps = Omit<HTMLAttributes<HTMLSpanElement>, "class"> & {
     tone?: "neutral" | "success" | "warning" | "error" | "info";
+    /**
+     * Badge shape — `"pill"` (default) is the current render (radius 999px, width
+     * grows with content). `"circle"` renders an equal-sided round bubble
+     * (`min-width === min-height`, equal inline/block padding, tabular-nums) — best
+     * for ≤2-digit counts. 3+ digit content degrades GRACEFULLY to a rounded-rect
+     * (never clipped), so consumer counts reaching the 1000s stay legible.
+     * Mirrors `Avatar`'s `shape`. Additive: with `shape` unset the badge renders
+     * byte-identically to before.
+     */
+    shape?: "pill" | "circle";
+    /**
+     * Density — `"md"` (default) is the current render. `"sm"` shrinks the
+     * font-size (the rail-bubble scale). Additive: with `size` unset the badge
+     * renders byte-identically to before.
+     */
+    size?: "sm" | "md";
     class?: string;
+    /**
+     * The number / text. Stays content-driven (no `value` prop). For SR users a
+     * bare count is ambiguous — pass an `aria-label` via `...rest` describing what
+     * is counted (e.g. `aria-label="128 entities"`).
+     */
     children?: Snippet;
   };
 
-  let { tone = "neutral", class: className, children, ...rest }: BadgeProps = $props();
+  let {
+    tone = "neutral",
+    shape = "pill",
+    size = "md",
+    class: className,
+    children,
+    ...rest
+  }: BadgeProps = $props();
 
-  const classes = () => ["st-badge", `st-badge--${tone}`, className].filter(Boolean).join(" ");
+  const classes = () =>
+    [
+      "st-badge",
+      `st-badge--${tone}`,
+      `st-badge--${shape}`,
+      `st-badge--${size}`,
+      className
+    ]
+      .filter(Boolean)
+      .join(" ");
 </script>
 
 <span {...rest} class={classes()}>
@@ -34,6 +71,33 @@
     text-transform: var(--st-component-badge-textTransform, none);
   }
 
+  /* Shape variants (additive). `pill` is the UNTOUCHED base `.st-badge` above — no
+     `--pill` rule exists, so a `shape="pill"` (or unset) badge renders
+     byte-identically. `--circle` overlays an equal-sided round bubble ON TOP of
+     the base rules: equal min-width/min-height, equal inline/block padding,
+     centered, tabular-nums for stable digit width. 3+ digit content degrades to a
+     rounded-rect (the box grows past the diameter, never clips), so large counts
+     stay legible. Every leaf falls back to a base literal so a theme that emits no
+     `--st-component-badge-circle-*` renders the variant identically. */
+  .st-badge--circle {
+    border-radius: var(--st-component-badge-circle-radius, 50%);
+    box-sizing: border-box;
+    font-variant-numeric: tabular-nums;
+    justify-content: center;
+    min-width: var(--st-component-badge-circle-size, 1.25rem);
+    min-height: var(--st-component-badge-circle-size, 1.25rem);
+    /* Equal inline/block padding keeps 1–2 digits round; the inline padding lets
+       3+ digits grow the box into a rounded-rect instead of clipping. */
+    padding: var(--st-component-badge-circle-padding, 0.125rem);
+    text-align: center;
+  }
+
+  /* Density variant (additive). `md` is the UNTOUCHED base font-size; `--sm`
+     reuses the Tag `sm` scale for cross-house consistency. */
+  .st-badge--sm {
+    font-size: var(--st-component-badge-sm-fontSize, 0.6875rem);
+  }
+
   .st-badge--neutral {
     background: var(--st-semantic-surface-subtle);
     color: var(--st-semantic-text-secondary);

package/dist/Badge.svelte.d.ts

@@ -2,7 +2,28 @@ import type { Snippet } from "svelte";
 import type { HTMLAttributes } from "svelte/elements";
 type BadgeProps = Omit<HTMLAttributes<HTMLSpanElement>, "class"> & {
     tone?: "neutral" | "success" | "warning" | "error" | "info";
+    /**
+     * Badge shape — `"pill"` (default) is the current render (radius 999px, width
+     * grows with content). `"circle"` renders an equal-sided round bubble
+     * (`min-width === min-height`, equal inline/block padding, tabular-nums) — best
+     * for ≤2-digit counts. 3+ digit content degrades GRACEFULLY to a rounded-rect
+     * (never clipped), so consumer counts reaching the 1000s stay legible.
+     * Mirrors `Avatar`'s `shape`. Additive: with `shape` unset the badge renders
+     * byte-identically to before.
+     */
+    shape?: "pill" | "circle";
+    /**
+     * Density — `"md"` (default) is the current render. `"sm"` shrinks the
+     * font-size (the rail-bubble scale). Additive: with `size` unset the badge
+     * renders byte-identically to before.
+     */
+    size?: "sm" | "md";
     class?: string;
+    /**
+     * The number / text. Stays content-driven (no `value` prop). For SR users a
+     * bare count is ambiguous — pass an `aria-label` via `...rest` describing what
+     * is counted (e.g. `aria-label="128 entities"`).
+     */
     children?: Snippet;
 };
 declare const Badge: import("svelte").Component<BadgeProps, {}, "">;

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

@@ -1 +1 @@
-{"version":3,"file":"Badge.svelte.d.ts","sourceRoot":"","sources":["../src/lib/Badge.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGpD,KAAK,UAAU,GAAG,IAAI,CAAC,cAAc,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,GAAG;IACjE,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAmBJ,QAAA,MAAM,KAAK,gDAAwC,CAAC;AACpD,KAAK,KAAK,GAAG,UAAU,CAAC,OAAO,KAAK,CAAC,CAAC;AACtC,eAAe,KAAK,CAAC"}
+{"version":3,"file":"Badge.svelte.d.ts","sourceRoot":"","sources":["../src/lib/Badge.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGpD,KAAK,UAAU,GAAG,IAAI,CAAC,cAAc,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,GAAG;IACjE,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;IAC5D;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC1B;;;;OAIG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAmCJ,QAAA,MAAM,KAAK,gDAAwC,CAAC;AACpD,KAAK,KAAK,GAAG,UAAU,CAAC,OAAO,KAAK,CAAC,CAAC;AACtC,eAAe,KAAK,CAAC"}

package/dist/Collapsible.svelte

@@ -7,7 +7,22 @@
     /** État ouvert (bindable). */
     open?: boolean;
     title: string;
+    /**
+     * Density of the trigger — `"md"` (default) is the current render. `"sm"`
+     * de-emphasizes the trigger (smaller font/weight/padding) for NESTED /
+     * level-2 collapsibles; `"lg"` enlarges it. Additive: with `size` unset the
+     * trigger renders byte-identically to before.
+     */
+    size?: "sm" | "md" | "lg";
     disabled?: boolean;
+    /**
+     * Trailing content rendered inside the trigger, BETWEEN the title and the
+     * chevron (e.g. a count Badge, a status Tag, a glyph). The chevron stays the
+     * rightmost affordance. If the trailing content carries information SR users
+     * need as part of the trigger name, set `aria-label` on the Collapsible via
+     * `...rest` (e.g. `aria-label="Entities, 128 items"`).
+     */
+    trailing?: Snippet;
     onToggle?: (open: boolean) => void;
     class?: string;
     children?: Snippet;
@@ -16,7 +31,9 @@
   let {
     open = $bindable(false),
     title,
+    size = "md",
     disabled = false,
+    trailing,
     onToggle,
     class: className,
     children,
@@ -26,7 +43,14 @@
   const uid = `st-collapsible-${Math.random().toString(36).slice(2, 9)}`;
 
   const classes = $derived(
-    ["st-collapsible", open ? "st-collapsible--open" : null, className].filter(Boolean).join(" ")
+    [
+      "st-collapsible",
+      `st-collapsible--${size}`,
+      open ? "st-collapsible--open" : null,
+      className
+    ]
+      .filter(Boolean)
+      .join(" ")
   );
 
   function toggle() {
@@ -47,6 +71,9 @@
     onclick={toggle}
   >
     <span class="st-collapsible__title">{title}</span>
+    {#if trailing}
+      <span class="st-collapsible__trailing">{@render trailing()}</span>
+    {/if}
     <span class="st-collapsible__icon" aria-hidden="true">
       <ChevronDown size={18} strokeWidth={2.25} />
     </span>
@@ -103,10 +130,37 @@
     cursor: not-allowed;
   }
 
+  /* Density variants (additive). `md` is the UNTOUCHED base `.st-collapsible__trigger`
+     above — no `--md` rule exists, so a `size="md"` (or unset) trigger renders
+     byte-identically. `--sm` de-emphasizes for nesting; `--lg` enlarges. Every
+     leaf falls back to a base literal so a theme that emits no
+     `--st-component-collapsible-*` renders these variants identically. */
+  .st-collapsible--sm .st-collapsible__trigger {
+    font-size: var(--st-component-collapsible-sm-fontSize, 0.875rem);
+    font-weight: var(--st-component-collapsible-sm-fontWeight, 500);
+    padding: var(--st-component-collapsible-sm-paddingBlock, 0.4rem)
+      var(--st-component-collapsible-sm-paddingInline, 0.25rem);
+  }
+
+  .st-collapsible--lg .st-collapsible__trigger {
+    font-size: var(--st-component-collapsible-lg-fontSize, 1rem);
+    padding: var(--st-component-collapsible-lg-paddingBlock, 0.875rem)
+      var(--st-component-collapsible-lg-paddingInline, 0.25rem);
+  }
+
   .st-collapsible__title {
     flex: 1 1 auto;
   }
 
+  /* Trigger trailing slot (additive). Holds a count badge / status / glyph
+     between the title and the chevron; never grows, so the chevron stays the
+     rightmost affordance and the title keeps `flex: 1 1 auto`. */
+  .st-collapsible__trailing {
+    align-items: center;
+    display: inline-flex;
+    flex: 0 0 auto;
+  }
+
   .st-collapsible__icon {
     align-items: center;
     color: var(--st-semantic-text-secondary);

package/dist/Collapsible.svelte.d.ts

@@ -4,7 +4,22 @@ type CollapsibleProps = Omit<HTMLAttributes<HTMLDivElement>, "class" | "title">
     /** État ouvert (bindable). */
     open?: boolean;
     title: string;
+    /**
+     * Density of the trigger — `"md"` (default) is the current render. `"sm"`
+     * de-emphasizes the trigger (smaller font/weight/padding) for NESTED /
+     * level-2 collapsibles; `"lg"` enlarges it. Additive: with `size` unset the
+     * trigger renders byte-identically to before.
+     */
+    size?: "sm" | "md" | "lg";
     disabled?: boolean;
+    /**
+     * Trailing content rendered inside the trigger, BETWEEN the title and the
+     * chevron (e.g. a count Badge, a status Tag, a glyph). The chevron stays the
+     * rightmost affordance. If the trailing content carries information SR users
+     * need as part of the trigger name, set `aria-label` on the Collapsible via
+     * `...rest` (e.g. `aria-label="Entities, 128 items"`).
+     */
+    trailing?: Snippet;
     onToggle?: (open: boolean) => void;
     class?: string;
     children?: Snippet;

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

@@ -1 +1 @@
-{"version":3,"file":"Collapsible.svelte.d.ts","sourceRoot":"","sources":["../src/lib/Collapsible.svelte.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGpD,KAAK,gBAAgB,GAAG,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG;IAChF,8BAA8B;IAC9B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAgDJ,QAAA,MAAM,WAAW,0DAAwC,CAAC;AAC1D,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAClD,eAAe,WAAW,CAAC"}
+{"version":3,"file":"Collapsible.svelte.d.ts","sourceRoot":"","sources":["../src/lib/Collapsible.svelte.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGpD,KAAK,gBAAgB,GAAG,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG;IAChF,8BAA8B;IAC9B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AA4DJ,QAAA,MAAM,WAAW,0DAAwC,CAAC;AAC1D,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAClD,eAAe,WAAW,CAAC"}

package/dist/Collapsible.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Collapsible.test.d.ts.map

package/dist/Collapsible.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Collapsible.test.d.ts","sourceRoot":"","sources":["../src/lib/Collapsible.test.ts"],"names":[],"mappings":""}

package/dist/Collapsible.test.js

@@ -0,0 +1,68 @@
+import { fireEvent, render } from "@testing-library/svelte";
+import { createRawSnippet } from "svelte";
+import { describe, expect, it } from "vitest";
+import Collapsible from "./Collapsible.svelte";
+const snippet = (html) => createRawSnippet(() => ({ render: () => `<span>${html}</span>` }));
+// Svelte scopes component styles by appending a per-component hash class (e.g.
+// "svelte-pav3x3") to every styled element's class list. Compare against the
+// SEMANTIC class only (the first token) so the assertions are stable across
+// builds and read the structural class, not the scope hash.
+const structuralClass = (el) => el.className.split(/\s+/)[0];
+describe("Collapsible — base (byte-identity)", () => {
+    it("renders the default trigger with no trailing span and the md density class", () => {
+        const { container } = render(Collapsible, { props: { title: "Entities" } });
+        const root = container.querySelector(".st-collapsible");
+        expect(root).toBeTruthy();
+        // Default density is md (additive class), and there is NO trailing span when
+        // the slot is absent — the trigger keeps its original [title][chevron] shape.
+        expect(root.classList.contains("st-collapsible--md")).toBe(true);
+        expect(root.classList.contains("st-collapsible--sm")).toBe(false);
+        expect(container.querySelector(".st-collapsible__trailing")).toBeNull();
+        expect(container.querySelector(".st-collapsible__title")?.textContent).toBe("Entities");
+        // Trigger order is preserved: only the title span then the chevron.
+        const trigger = container.querySelector(".st-collapsible__trigger");
+        const spans = Array.from(trigger.children).map(structuralClass);
+        expect(spans).toEqual(["st-collapsible__title", "st-collapsible__icon"]);
+    });
+});
+describe("Collapsible — size", () => {
+    it("size=\"sm\" toggles st-collapsible--sm", () => {
+        const { container } = render(Collapsible, { props: { title: "Type", size: "sm" } });
+        const root = container.querySelector(".st-collapsible");
+        expect(root.classList.contains("st-collapsible--sm")).toBe(true);
+        expect(root.classList.contains("st-collapsible--md")).toBe(false);
+    });
+    it("size=\"lg\" toggles st-collapsible--lg", () => {
+        const { container } = render(Collapsible, { props: { title: "Section", size: "lg" } });
+        expect(container.querySelector(".st-collapsible").classList.contains("st-collapsible--lg")).toBe(true);
+    });
+});
+describe("Collapsible — trailing slot", () => {
+    it("renders trailing content between the title and the chevron", () => {
+        const { container } = render(Collapsible, {
+            props: { title: "Entities", trailing: snippet("128") },
+        });
+        const trailing = container.querySelector(".st-collapsible__trailing");
+        expect(trailing).toBeTruthy();
+        expect(trailing?.textContent).toContain("128");
+        // Order inside the trigger: title, trailing, chevron (chevron stays last).
+        const trigger = container.querySelector(".st-collapsible__trigger");
+        const order = Array.from(trigger.children).map(structuralClass);
+        expect(order).toEqual([
+            "st-collapsible__title",
+            "st-collapsible__trailing",
+            "st-collapsible__icon",
+        ]);
+    });
+});
+describe("Collapsible — a11y unchanged", () => {
+    it("toggles aria-expanded on click with size + trailing set", async () => {
+        const { container } = render(Collapsible, {
+            props: { title: "Entities", size: "sm", trailing: snippet("7") },
+        });
+        const trigger = container.querySelector(".st-collapsible__trigger");
+        expect(trigger.getAttribute("aria-expanded")).toBe("false");
+        await fireEvent.click(trigger);
+        expect(trigger.getAttribute("aria-expanded")).toBe("true");
+    });
+});

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"}