@sentropic/design-system-svelte 0.14.0 → 0.16.0

package/dist/Popper.svelte.d.ts

@@ -0,0 +1,70 @@
+import type { Snippet } from "svelte";
+export type PopperStrategy = "absolute" | "fixed";
+export type PopperPlacement = "top" | "bottom" | "left" | "right" | "top-start" | "top-end" | "bottom-start" | "bottom-end" | "left-start" | "left-end" | "right-start" | "right-end";
+export type PopperSide = "top" | "bottom" | "left" | "right";
+export type PopperAlign = "start" | "center" | "end";
+export type PopperProps = {
+    /** Reference element the panel is positioned against. */
+    anchor: HTMLElement | null;
+    /** Controlled open state. When false (or no anchor) nothing renders. */
+    open?: boolean;
+    /** Wanted placement of the panel relative to the anchor. */
+    placement?: PopperPlacement;
+    /** Main-axis distance (px) between the anchor and the panel. */
+    offset?: number;
+    /** Flip to the opposite side when the panel would overflow the viewport. */
+    flip?: boolean;
+    /** Shift along the cross axis to keep the panel within the viewport. */
+    shift?: boolean;
+    /** Expose a positioned arrow element. */
+    arrow?: boolean;
+    /** CSS positioning strategy. */
+    strategy?: PopperStrategy;
+    /** Render the panel into `document.body` via a Portal. */
+    portal?: boolean;
+    /** Optional class applied to the floating panel. */
+    class?: string;
+    /** Notified whenever the resolved placement changes (after flip). */
+    onPlacementChange?: (placement: PopperPlacement) => void;
+    children?: Snippet;
+};
+/** Split a placement into its side and (optional) alignment. */
+export declare function splitPlacement(placement: PopperPlacement): {
+    side: PopperSide;
+    align: PopperAlign;
+};
+/** Recompose a side + alignment into a placement string. */
+export declare function joinPlacement(side: PopperSide, align: PopperAlign): PopperPlacement;
+export type Rect = {
+    top: number;
+    left: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+};
+/**
+ * Pure geometry: compute the panel coordinates (in the chosen strategy's
+ * coordinate space) given the anchor rect, the panel size, and options.
+ * Returns the resolved placement (after flip) and the top/left coordinates,
+ * plus the arrow offset along the main edge.
+ *
+ * Coordinates are viewport-relative; callers add scroll offsets for the
+ * `absolute` strategy. No DOM access here — safe to unit test.
+ */
+export declare function computePosition(anchorRect: Rect, panelWidth: number, panelHeight: number, options: {
+    placement: PopperPlacement;
+    offset: number;
+    flip: boolean;
+    shift: boolean;
+    viewportWidth: number;
+    viewportHeight: number;
+}): {
+    placement: PopperPlacement;
+    top: number;
+    left: number;
+};
+declare const Popper: import("svelte").Component<PopperProps, {}, "">;
+type Popper = ReturnType<typeof Popper>;
+export default Popper;
+//# sourceMappingURL=Popper.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Popper.svelte.d.ts","sourceRoot":"","sources":["../src/lib/Popper.svelte.ts"],"names":[],"mappings":"AAGE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAGtC,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,OAAO,CAAC;AAElD,MAAM,MAAM,eAAe,GACvB,KAAK,GACL,QAAQ,GACR,MAAM,GACN,OAAO,GACP,WAAW,GACX,SAAS,GACT,cAAc,GACd,YAAY,GACZ,YAAY,GACZ,UAAU,GACV,aAAa,GACb,WAAW,CAAC;AAEhB,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAC7D,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;AAErD,MAAM,MAAM,WAAW,GAAG;IACxB,yDAAyD;IACzD,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,wEAAwE;IACxE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,4DAA4D;IAC5D,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,wEAAwE;IACxE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,yCAAyC;IACzC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,0DAA0D;IAC1D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,eAAe,KAAK,IAAI,CAAC;IACzD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,SAAS,EAAE,eAAe,GAAG;IAC1D,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,WAAW,CAAC;CACpB,CAGA;AAED,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,eAAe,CAEnF;AASD,MAAM,MAAM,IAAI,GAAG;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,IAAI,EAChB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE;IACP,SAAS,EAAE,eAAe,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB,GACA;IAAE,SAAS,EAAE,eAAe,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAwD3D;AAsHH,QAAA,MAAM,MAAM,iDAAwC,CAAC;AACrD,KAAK,MAAM,GAAG,UAAU,CAAC,OAAO,MAAM,CAAC,CAAC;AACxC,eAAe,MAAM,CAAC"}

package/dist/Portal.svelte

@@ -0,0 +1,80 @@
+<script lang="ts" module>
+  import type { Snippet } from "svelte";
+
+  export type PortalProps = {
+    /**
+     * Where to teleport the children. A CSS selector string or an actual
+     * `HTMLElement`. Defaults to the document `<body>`.
+     */
+    target?: string | HTMLElement;
+    /** When `true`, render inline in place (no teleportation). */
+    disabled?: boolean;
+    /** Optional class applied to the portal container element. */
+    class?: string;
+    children?: Snippet;
+  };
+
+  /**
+   * Resolve a target prop to an `HTMLElement`. Returns `null` when it cannot be
+   * resolved (SSR, missing selector, etc.).
+   */
+  export function resolvePortalTarget(
+    target: string | HTMLElement | undefined
+  ): HTMLElement | null {
+    if (typeof document === "undefined") return null;
+    if (target == null) return document.body;
+    if (typeof target === "string") {
+      return document.querySelector<HTMLElement>(target) ?? document.body;
+    }
+    return target;
+  }
+</script>
+
+<script lang="ts">
+  let {
+    target = "body",
+    disabled = false,
+    class: className,
+    children
+  }: PortalProps = $props();
+
+  // The container that actually holds the children. We render it inline first
+  // (so SSR produces markup in place) and move it into the target on mount.
+  let container = $state<HTMLDivElement | undefined>();
+
+  $effect(() => {
+    // Client-only: never touch the DOM during SSR or before mount.
+    if (disabled || !container) return;
+    if (typeof document === "undefined") return;
+
+    const destination = resolvePortalTarget(target);
+    if (!destination) return;
+
+    destination.appendChild(container);
+
+    return () => {
+      // Clean up on unmount / target change: remove the container from the DOM.
+      container?.remove();
+    };
+  });
+</script>
+
+{#if disabled}
+  <div class={className ? `st-portal ${className}` : "st-portal"} data-st-portal="inline">
+    {@render children?.()}
+  </div>
+{:else}
+  <div
+    bind:this={container}
+    class={className ? `st-portal ${className}` : "st-portal"}
+    data-st-portal="teleported"
+  >
+    {@render children?.()}
+  </div>
+{/if}
+
+<style>
+  .st-portal {
+    display: contents;
+  }
+</style>

package/dist/Portal.svelte.d.ts

@@ -0,0 +1,22 @@
+import type { Snippet } from "svelte";
+export type PortalProps = {
+    /**
+     * Where to teleport the children. A CSS selector string or an actual
+     * `HTMLElement`. Defaults to the document `<body>`.
+     */
+    target?: string | HTMLElement;
+    /** When `true`, render inline in place (no teleportation). */
+    disabled?: boolean;
+    /** Optional class applied to the portal container element. */
+    class?: string;
+    children?: Snippet;
+};
+/**
+ * Resolve a target prop to an `HTMLElement`. Returns `null` when it cannot be
+ * resolved (SSR, missing selector, etc.).
+ */
+export declare function resolvePortalTarget(target: string | HTMLElement | undefined): HTMLElement | null;
+declare const Portal: import("svelte").Component<PortalProps, {}, "">;
+type Portal = ReturnType<typeof Portal>;
+export default Portal;
+//# sourceMappingURL=Portal.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Portal.svelte.d.ts","sourceRoot":"","sources":["../src/lib/Portal.svelte.ts"],"names":[],"mappings":"AAGE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC,MAAM,MAAM,WAAW,GAAG;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,GACvC,WAAW,GAAG,IAAI,CAOpB;AA+CH,QAAA,MAAM,MAAM,iDAAwC,CAAC;AACrD,KAAK,MAAM,GAAG,UAAU,CAAC,OAAO,MAAM,CAAC,CAAC;AACxC,eAAe,MAAM,CAAC"}

package/dist/SelectableList.svelte

@@ -0,0 +1,186 @@
+<script lang="ts" module>
+  import type { Snippet } from "svelte";
+
+  export type SelectableListProps = {
+    /** Accessible name for the listbox (required for SR users). */
+    label?: string;
+    /** References the id of an external visible label (alternative to `label`). */
+    labelledby?: string;
+    /**
+     * Allow more than one selected row. Adds aria-multiselectable and toggles
+     * each row independently. Defaults to false (single-select).
+     */
+    multiple?: boolean;
+    /**
+     * Selected value(s). Controlled when provided. For single-select pass a
+     * string (or null); for multiple pass a string[]. When omitted the list is
+     * uncontrolled and keeps its own internal selection.
+     */
+    value?: string | string[] | null;
+    /**
+     * Fired with the new selection on every change. Receives a string|null for
+     * single-select and a string[] for multiple. Required for the controlled
+     * pattern; also fires for uncontrolled lists.
+     */
+    onchange?: (value: string | string[] | null) => void;
+    class?: string;
+    children?: Snippet;
+  };
+</script>
+
+<script lang="ts">
+  import { setContext, untrack } from "svelte";
+  import {
+    SELECTABLE_LIST_KEY,
+    type SelectableListContext
+  } from "./SelectableRow.svelte";
+
+  let {
+    label,
+    labelledby,
+    multiple = false,
+    value,
+    onchange,
+    class: className,
+    children
+  }: SelectableListProps = $props();
+
+  // Controlled when the consumer passes `value` (including null). Otherwise the
+  // list owns an internal selection set.
+  const controlled = $derived(value !== undefined);
+
+  function toSet(v: string | string[] | null | undefined): Set<string> {
+    if (v == null) return new Set();
+    return new Set(Array.isArray(v) ? v : [v]);
+  }
+
+  // Internal selection for the uncontrolled case.
+  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. -------------------------------
+  type Entry = { el: HTMLElement; value: string | undefined };
+  let entries = $state<Entry[]>([]);
+
+  // The element that currently holds the roving tab stop (tabindex 0). Null until
+  // a row is focused; until then the FIRST enabled row is the default stop.
+  let tabStopEl = $state<HTMLElement | null>(null);
+
+  function sortByDom(list: Entry[]): Entry[] {
+    return [...list].sort((a, b) => {
+      const pos = a.el.compareDocumentPosition(b.el);
+      if (pos & Node.DOCUMENT_POSITION_FOLLOWING) return -1;
+      if (pos & Node.DOCUMENT_POSITION_PRECEDING) return 1;
+      return 0;
+    });
+  }
+
+  // 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.
+  function register(el: HTMLElement, rowValue: string | undefined): () => void {
+    untrack(() => {
+      entries = sortByDom([...entries.filter((e) => e.el !== el), { el, value: rowValue }]);
+    });
+    return () => {
+      untrack(() => {
+        entries = entries.filter((e) => e.el !== el);
+        if (tabStopEl === el) tabStopEl = null;
+      });
+    };
+  }
+
+  // Default roving stop = first registered (DOM-ordered) row when none focused.
+  const effectiveTabStop = $derived(tabStopEl ?? entries[0]?.el ?? null);
+
+  function valueOf(el: HTMLElement): string | undefined {
+    return entries.find((e) => e.el === el)?.value;
+  }
+
+  function isSelected(el: HTMLElement): boolean {
+    const v = valueOf(el);
+    return v !== undefined && selectedValues.has(v);
+  }
+
+  function isTabStop(el: HTMLElement): boolean {
+    return el === effectiveTabStop;
+  }
+
+  function emit(next: Set<string>) {
+    if (!controlled) internal = next;
+    if (multiple) onchange?.([...next]);
+    else onchange?.(next.size ? [...next][0] : null);
+  }
+
+  function activate(el: HTMLElement) {
+    const v = valueOf(el);
+    if (v === undefined) return;
+    const current = selectedValues;
+    let next: Set<string>;
+    if (multiple) {
+      next = new Set(current);
+      if (next.has(v)) next.delete(v);
+      else next.add(v);
+    } else {
+      // Single-select toggles off when re-activating the selected row.
+      next = current.has(v) && current.size === 1 ? new Set() : new Set([v]);
+    }
+    emit(next);
+  }
+
+  function focusRow(el: HTMLElement) {
+    tabStopEl = el;
+  }
+
+  function navigate(el: HTMLElement, key: string) {
+    if (entries.length === 0) return;
+    const idx = entries.findIndex((e) => e.el === el);
+    if (idx === -1) return;
+    let targetIdx = idx;
+    if (key === "ArrowDown" || key === "ArrowRight") targetIdx = idx + 1;
+    else if (key === "ArrowUp" || key === "ArrowLeft") targetIdx = idx - 1;
+    else if (key === "Home") targetIdx = 0;
+    else if (key === "End") targetIdx = entries.length - 1;
+    // Clamp (no wrap) so Home/End and arrows stay within bounds.
+    targetIdx = Math.max(0, Math.min(entries.length - 1, targetIdx));
+    const target = entries[targetIdx]?.el;
+    if (target) {
+      tabStopEl = target;
+      target.focus();
+    }
+  }
+
+  const context: SelectableListContext = {
+    managed: true,
+    itemRole: "option",
+    register,
+    isSelected,
+    isTabStop,
+    activate,
+    focusRow,
+    navigate
+  };
+  setContext(SELECTABLE_LIST_KEY, context);
+
+  const classes = $derived(["st-selectableList", className].filter(Boolean).join(" "));
+</script>
+
+<div
+  class={classes}
+  role="listbox"
+  aria-label={labelledby ? undefined : label}
+  aria-labelledby={labelledby}
+  aria-multiselectable={multiple ? "true" : undefined}
+>
+  {@render children?.()}
+</div>
+
+<style>
+  .st-selectableList {
+    display: flex;
+    flex-direction: column;
+    gap: var(--st-spacing-1, 0.25rem);
+    width: 100%;
+  }
+</style>

package/dist/SelectableList.svelte.d.ts

@@ -0,0 +1,30 @@
+import type { Snippet } from "svelte";
+export type SelectableListProps = {
+    /** Accessible name for the listbox (required for SR users). */
+    label?: string;
+    /** References the id of an external visible label (alternative to `label`). */
+    labelledby?: string;
+    /**
+     * Allow more than one selected row. Adds aria-multiselectable and toggles
+     * each row independently. Defaults to false (single-select).
+     */
+    multiple?: boolean;
+    /**
+     * Selected value(s). Controlled when provided. For single-select pass a
+     * string (or null); for multiple pass a string[]. When omitted the list is
+     * uncontrolled and keeps its own internal selection.
+     */
+    value?: string | string[] | null;
+    /**
+     * Fired with the new selection on every change. Receives a string|null for
+     * single-select and a string[] for multiple. Required for the controlled
+     * pattern; also fires for uncontrolled lists.
+     */
+    onchange?: (value: string | string[] | null) => void;
+    class?: string;
+    children?: Snippet;
+};
+declare const SelectableList: import("svelte").Component<SelectableListProps, {}, "">;
+type SelectableList = ReturnType<typeof SelectableList>;
+export default SelectableList;
+//# sourceMappingURL=SelectableList.svelte.d.ts.map

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

@@ -0,0 +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;AA0JJ,QAAA,MAAM,cAAc,yDAAwC,CAAC;AAC7D,KAAK,cAAc,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;AACxD,eAAe,cAAc,CAAC"}

package/dist/SelectableRow.svelte

@@ -0,0 +1,291 @@
+<script lang="ts" module>
+  import type { Snippet } from "svelte";
+
+  /**
+   * Shared context contract between {@link SelectableList} and its slotted
+   * {@link SelectableRow} children. The list owns selection + roving tabindex and
+   * exposes reactive getters the rows read to derive their own `role` / `tabindex`
+   * / `aria-selected`, plus callbacks for registration and activation. When a row
+   * is used STANDALONE (no list) `getContext` returns undefined and the row falls
+   * back to its own `role` / `tabindex` / selection state.
+   */
+  export const SELECTABLE_LIST_KEY = Symbol("st-selectable-list");
+
+  export type SelectableListContext = {
+    /** True when the list manages selection/roving for its rows. */
+    readonly managed: true;
+    /** listbox role for the wrapper → rows are "option". */
+    readonly itemRole: "option";
+    /** Register a row element; returns an unregister callback. */
+    register: (el: HTMLElement, value: string | undefined) => () => void;
+    /** Is the row with this element currently selected? */
+    isSelected: (el: HTMLElement) => boolean;
+    /** Should the row with this element be the roving-tabindex stop (tabindex 0)? */
+    isTabStop: (el: HTMLElement) => boolean;
+    /** Row was activated (click / Space / Enter). The list toggles selection. */
+    activate: (el: HTMLElement) => void;
+    /** Row received focus → becomes the roving tab stop. */
+    focusRow: (el: HTMLElement) => void;
+    /** Arrow / Home / End navigation from a row. */
+    navigate: (el: HTMLElement, key: string) => void;
+  };
+
+  export type SelectableRowProps = {
+    /**
+     * Selected state (bindable). Honoured when the row is used STANDALONE; inside
+     * a {@link SelectableList} the list is the source of truth and drives the
+     * selected styling, so this prop is ignored for managed rows.
+     */
+    selected?: boolean;
+    /** Notified on every toggle with the new selected state (standalone rows). */
+    onselect?: (selected: boolean) => void;
+    /** Non-interactive when true. */
+    disabled?: boolean;
+    /** Stable value, surfaced as `data-value` and used by the list for `value`. */
+    value?: string;
+    /**
+     * ARIA role for the standalone row. Defaults to "option" so a lone row still
+     * reads as a selectable item. Inside a list the role is forced to "option".
+     */
+    role?: string;
+    /**
+     * Opt-in left accent bar on the selected state. Off by default so the
+     * selected item is a calm tinted surface + accented text (two signals only).
+     */
+    accentBar?: boolean;
+    /** Leading slot (icon / avatar). */
+    leading?: Snippet;
+    /** Trailing slot (meta / icon). */
+    trailing?: Snippet;
+    /** Main content. */
+    children?: Snippet;
+    class?: string;
+  };
+</script>
+
+<script lang="ts">
+  import { getContext } from "svelte";
+
+  let {
+    selected = $bindable(false),
+    onselect,
+    disabled = false,
+    value,
+    role = "option",
+    accentBar = false,
+    leading,
+    trailing,
+    children,
+    class: className
+  }: SelectableRowProps = $props();
+
+  // When rendered inside a SelectableList, the list (via context) owns selection
+  // and the roving tabindex. Standalone rows manage their own state.
+  const list = getContext<SelectableListContext | undefined>(SELECTABLE_LIST_KEY);
+
+  let el: HTMLElement | null = $state(null);
+
+  // Register with the parent list (if any) so it can order rows for arrow nav
+  // and compute the roving tab stop. The effect re-registers if value changes.
+  $effect(() => {
+    if (!list || !el || disabled) return;
+    return list.register(el, value);
+  });
+
+  // Effective selected state: list-managed rows read the list; standalone rows
+  // use their own bindable prop.
+  const isSelected = $derived(list && el ? list.isSelected(el) : selected);
+
+  // Effective role: a managed row is always an "option" inside the listbox.
+  const effectiveRole = $derived(list ? list.itemRole : role);
+
+  // Roving tabindex: in a list, exactly one enabled row is the tab stop (0), the
+  // rest are -1. Standalone enabled rows are always tabbable (0). Disabled = -1.
+  const tabindex = $derived(
+    disabled ? -1 : list && el ? (list.isTabStop(el) ? 0 : -1) : 0
+  );
+
+  const classes = $derived(
+    [
+      "st-selectableRow",
+      isSelected ? "st-selectableRow--selected" : null,
+      disabled ? "st-selectableRow--disabled" : null,
+      accentBar ? "st-selectableRow--accentBar" : null,
+      className
+    ]
+      .filter(Boolean)
+      .join(" ")
+  );
+
+  function activate() {
+    if (disabled) return;
+    if (list && el) {
+      list.activate(el);
+      return;
+    }
+    selected = !selected;
+    onselect?.(selected);
+  }
+
+  function handleKeydown(e: KeyboardEvent) {
+    if (disabled) return;
+    if (e.key === "Enter" || e.key === " ") {
+      e.preventDefault();
+      activate();
+      return;
+    }
+    // Roving navigation is owned by the list; forward the relevant keys.
+    if (
+      list &&
+      el &&
+      (e.key === "ArrowDown" ||
+        e.key === "ArrowUp" ||
+        e.key === "ArrowLeft" ||
+        e.key === "ArrowRight" ||
+        e.key === "Home" ||
+        e.key === "End")
+    ) {
+      e.preventDefault();
+      list.navigate(el, e.key);
+    }
+  }
+
+  function handleFocus() {
+    if (disabled) return;
+    if (list && el) list.focusRow(el);
+  }
+</script>
+
+<!-- The row carries an interactive ARIA role (option/listbox item) so a roving
+     tabindex is correct; the role is dynamic, which the static a11y check cannot
+     verify, hence the targeted ignore. -->
+<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+<div
+  bind:this={el}
+  class={classes}
+  role={effectiveRole}
+  aria-selected={effectiveRole === "option" ? isSelected : undefined}
+  aria-disabled={disabled ? "true" : undefined}
+  data-value={value}
+  {tabindex}
+  onclick={activate}
+  onkeydown={handleKeydown}
+  onfocus={handleFocus}
+>
+  {#if leading}
+    <span class="st-selectableRow__leading">{@render leading()}</span>
+  {/if}
+  <span class="st-selectableRow__content">{@render children?.()}</span>
+  {#if trailing}
+    <span class="st-selectableRow__trailing">{@render trailing()}</span>
+  {/if}
+</div>
+
+<style>
+  /* Compact, full-width selectable list/rail row. By DEFAULT the selected state
+     is just two calm signals — a tinted surface + accented text — deliberately
+     NOT the off-theme "boudin box" (inset box-shadow + heavy rounded border) it
+     replaces, and NOT a reflow-causing font-weight bump. The fine left accent
+     bar is OPT-IN via the `accentBar` prop. */
+  .st-selectableRow {
+    align-items: center;
+    background: transparent;
+    border-radius: var(--st-radius-sm, 0.25rem);
+    box-sizing: border-box;
+    color: var(--st-semantic-text-secondary, #475569);
+    cursor: pointer;
+    display: flex;
+    gap: var(--st-spacing-2, 0.5rem);
+    padding: 0.5rem 0.75rem;
+    position: relative;
+    text-align: left;
+    transition:
+      background-color var(--st-motion-fast, 120ms) var(--st-motion-easing, ease),
+      color var(--st-motion-fast, 120ms) var(--st-motion-easing, ease);
+    user-select: none;
+    width: 100%;
+  }
+
+  /* Opt-in accent bar: reserve the 2px gutter only when enabled so text never
+     shifts on selection. */
+  .st-selectableRow--accentBar {
+    padding-left: calc(0.75rem - 2px);
+    border-left: 2px solid transparent;
+  }
+
+  .st-selectableRow:hover:not(.st-selectableRow--disabled):not(.st-selectableRow--selected) {
+    background: var(
+      --st-component-control-hoverBackground,
+      var(--st-semantic-surface-subtle, #f8fafc)
+    );
+    color: var(--st-semantic-text-primary, #0f172a);
+  }
+
+  /* Focus ring as an EXTERNAL offset (not inset) so it reads as a focus
+     affordance around the row rather than an inner stroke. */
+  .st-selectableRow:focus-visible {
+    outline: 2px solid var(--st-semantic-border-interactive, var(--st-semantic-action-primary));
+    outline-offset: 2px;
+  }
+
+  /* Selected: two signals by default — tinted surface + accented (contrast-safe)
+     text. The token values carry a flat fallback; the inline color-mix is only a
+     last-resort default when the token is unset. */
+  .st-selectableRow--selected {
+    background: var(
+      --st-component-selectableRow-selectedBackground,
+      color-mix(in oklch, var(--st-semantic-action-primary, #2563eb) 12%, transparent)
+    );
+    color: var(
+      --st-component-selectableRow-selectedText,
+      color-mix(in oklch, var(--st-semantic-action-primary, #2563eb) 78%, black)
+    );
+  }
+
+  /* The left accent bar paints only when opt-in AND selected. */
+  .st-selectableRow--accentBar.st-selectableRow--selected {
+    border-left-color: var(
+      --st-component-selectableRow-selectedAccent,
+      var(--st-semantic-action-primary, #2563eb)
+    );
+  }
+
+  /* color-mix fallback: engines without color-mix() get a flat tinted surface +
+     a solid accent text from the resolved tokens' plain values. */
+  @supports not (color: color-mix(in oklch, red, blue)) {
+    .st-selectableRow--selected {
+      background: var(
+        --st-component-selectableRow-selectedBackground,
+        var(--st-semantic-surface-subtle, #eef2ff)
+      );
+      color: var(
+        --st-component-selectableRow-selectedText,
+        var(--st-semantic-action-primary, #1d4ed8)
+      );
+    }
+  }
+
+  .st-selectableRow--disabled {
+    cursor: not-allowed;
+    opacity: 0.55;
+  }
+
+  .st-selectableRow__leading,
+  .st-selectableRow__trailing {
+    align-items: center;
+    display: inline-flex;
+    flex: 0 0 auto;
+  }
+
+  .st-selectableRow__content {
+    flex: 1 1 auto;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .st-selectableRow { transition: none; }
+  }
+</style>