entasis 0.11.0 → 0.12.0

package/dist/components/ScrollArea/scrollArea.svelte.js

@@ -1,8 +1,9 @@
 import { createBindableStateClass } from '../../utils/state.svelte.js';
 import { useBoundingClientRect } from '../../utils/useBoundingClientRect.svelte.js';
-import { useDrag } from '../../utils/useDrag.svelte.js';
+import { createPointerDrag } from '../../utils/pointerDrag.js';
 import { useHoverAction } from '../../utils/useHoverAction.svelte.js';
 import { useResizeObserver } from '../../utils/useResizeObserver.svelte.js';
+import { untrack } from 'svelte';
 import { on } from 'svelte/events';
 /**
  * Slack allowed between scroll extent and client box before it counts as real overflow.
@@ -10,6 +11,15 @@ import { on } from 'svelte/events';
  * remainder is not one.
  */
 const OVERFLOW_TOLERANCE = 1;
+/** Shortest a thumb gets, in px, whatever the content length or an overscroll asks for. */
+const MIN_THUMB_SIZE = 18;
+/** How long after the last scroll event the area still counts as scrolling, in ms. */
+const SCROLLING_IDLE_MS = 400;
+const clamp = (value, min, max) => Math.max(min, Math.min(value, max));
+/** `-0` becomes `0`, so a normalised RTL offset compares equal to zero. */
+const unsigned = (value) => (value === 0 ? 0 : value);
+/** How far a scroll offset sits beyond its range (rubber banding): negative before, positive after. */
+const overscrollOf = (scroll, max) => scroll - clamp(scroll, 0, max);
 export class ScrollArea extends createBindableStateClass() {
     viewportElement = $state();
     contentElement = $state();
@@ -52,75 +62,166 @@ export class ScrollArea extends createBindableStateClass() {
     scrollbarXEnabled = $derived(this.maxScrollX > OVERFLOW_TOLERANCE);
     visible = $derived(this.scrollbarYEnabled);
     visibleX = $derived(this.scrollbarXEnabled);
-    canScrollUp = $derived(this.maxScrollY > 0 && this.scrollY > 0);
-    canScrollDown = $derived(this.maxScrollY > 0 && this.scrollY < this.maxScrollY);
+    // Whether the viewport lays out right-to-left. In RTL the browser's `scrollLeft` runs from 0
+    // down to a negative number, so everything horizontal is read through `scrollX` (the distance
+    // travelled from the inline start, never negative inside the range) and written back mirrored.
+    rtl = $state(false);
+    // Thickness in px of each rendered scrollbar track (0 while it is not rendered). Where both
+    // bars show, each one stops short of the other so they do not overlap at the corner.
+    trackYThickness = $state(0);
+    trackXThickness = $state(0);
+    // The threshold for the overflow-edge hooks: hidden content past an edge counts once it is
+    // longer than this.
+    edgeThreshold = $derived(Math.max(0, this.overflowEdgeThreshold ?? OVERFLOW_TOLERANCE));
+    // Scroll distance travelled from the start and left to travel to the end, per axis. These stay
+    // inside the scroll range (an overscroll does not leave content "hidden") and are 0 while the
+    // axis does not overflow.
+    overflowYStart = $derived(this.scrollbarYEnabled ? clamp(this.scrollY, 0, this.maxScrollY) : 0);
+    overflowYEnd = $derived(this.scrollbarYEnabled ? clamp(this.maxScrollY - this.scrollY, 0, this.maxScrollY) : 0);
+    overflowXStart = $derived(this.scrollbarXEnabled ? clamp(this.scrollX, 0, this.maxScrollX) : 0);
+    overflowXEnd = $derived(this.scrollbarXEnabled ? clamp(this.maxScrollX - this.scrollX, 0, this.maxScrollX) : 0);
+    // Whether content is hidden past each edge, beyond the threshold.
+    hasOverflowYStart = $derived(this.overflowYStart > this.edgeThreshold);
+    hasOverflowYEnd = $derived(this.overflowYEnd > this.edgeThreshold);
+    hasOverflowXStart = $derived(this.overflowXStart > this.edgeThreshold);
+    hasOverflowXEnd = $derived(this.overflowXEnd > this.edgeThreshold);
+    canScrollUp = $derived(this.hasOverflowYStart);
+    canScrollDown = $derived(this.hasOverflowYEnd);
     thumbRect = useBoundingClientRect();
     trackRect = useBoundingClientRect();
-    thumbYSize = $derived.by(() => {
+    trackRectX = useBoundingClientRect();
+    // Track lengths and thumb sizes read the live DOM, so they also depend on everything that
+    // moves those numbers: the observed boxes, the scroll extent (`measureVersion`) and the track
+    // boxes themselves (which also change when the other bar's corner inset appears). Without them
+    // the thumb keeps the size it had when the content last crossed the overflow threshold.
+    trackYLength = $derived.by(() => {
+        void this.viewportDimensions;
+        void this.measureVersion;
+        void this.trackRect.current;
+        return this.scrollbarYElement?.clientHeight ?? 0;
+    });
+    trackXLength = $derived.by(() => {
+        void this.viewportDimensions;
+        void this.measureVersion;
+        void this.trackRectX.current;
+        return this.scrollbarXElement?.clientWidth ?? 0;
+    });
+    /** Thumb length the content ratio asks for, before any overscroll shrinks it. */
+    thumbYBaseSize = $derived.by(() => {
+        void this.contentDimensions;
         if (!this.scrollbarYEnabled ||
             !this.scrollbarYElement ||
             !this.viewportElement ||
             !this.contentElement) {
             return 0;
         }
-        const scrollbarYHeight = this.scrollbarYElement.clientHeight;
-        const thumbYRatio = this.viewportElement.clientHeight / this.viewportElement.scrollHeight;
-        return Math.max(thumbYRatio * scrollbarYHeight, 18);
+        const ratio = this.viewportElement.clientHeight / (this.viewportElement.scrollHeight || 1);
+        return Math.max(ratio * this.trackYLength, MIN_THUMB_SIZE);
+    });
+    thumbXBaseSize = $derived.by(() => {
+        void this.contentDimensions;
+        if (!this.scrollbarXEnabled ||
+            !this.scrollbarXElement ||
+            !this.viewportElement ||
+            !this.contentElement) {
+            return 0;
+        }
+        const ratio = this.viewportElement.clientWidth / (this.viewportElement.scrollWidth || 1);
+        return Math.max(ratio * this.trackXLength, MIN_THUMB_SIZE);
     });
-    dragY = useDrag({
-        isActive: true,
-        onDragStart: ({ clientY, target }) => {
-            // Calculate offset from mouse to thumb top using fresh rects
-            const thumbRect = target.getBoundingClientRect();
-            this.dragOffset = clientY - thumbRect.top;
+    // WebKit lets the scroll offset leave its range while it rubber-bands. The thumb shrinks by
+    // that amount and stays pinned to the edge that is being pulled, instead of leaving its track.
+    overscrollY = $derived(overscrollOf(this.scrollY, this.maxScrollY));
+    overscrollX = $derived(overscrollOf(this.scrollX, this.maxScrollX));
+    thumbYSize = $derived(this.thumbYBaseSize === 0
+        ? 0
+        : Math.max(this.thumbYBaseSize - Math.abs(this.overscrollY), MIN_THUMB_SIZE));
+    thumbXSize = $derived(this.thumbXBaseSize === 0
+        ? 0
+        : Math.max(this.thumbXBaseSize - Math.abs(this.overscrollX), MIN_THUMB_SIZE));
+    // Scroll snapping would pull a dragged viewport to the nearest snap point under the thumb,
+    // which then jumps between them. It is switched off while a thumb is held.
+    savedScrollSnapType = null;
+    pauseScrollSnap() {
+        const viewport = this.viewportElement;
+        if (!viewport || this.savedScrollSnapType !== null)
+            return;
+        this.savedScrollSnapType = viewport.style.scrollSnapType;
+        viewport.style.scrollSnapType = 'none';
+    }
+    restoreScrollSnap() {
+        if (this.savedScrollSnapType === null)
+            return;
+        if (this.viewportElement)
+            this.viewportElement.style.scrollSnapType = this.savedScrollSnapType;
+        this.savedScrollSnapType = null;
+    }
+    isDraggingY = $state(false);
+    // The thumb is a handle: the shared pointer drag captures the pointer on press (primary
+    // button only), and a cancelled touch, a lost capture or a mouse released outside the window
+    // ends the drag instead of leaving it stuck.
+    dragY = createPointerDrag({
+        onStart: ({ event, node }) => {
+            // Offset from the pointer to the thumb top, from a fresh rect
+            this.dragOffset = event.clientY - node.getBoundingClientRect().top;
+            this.isDraggingY = true;
+            this.pauseScrollSnap();
         },
-        onDrag: ({ clientY }) => {
+        onMove: ({ y }) => {
             if (!this.scrollbarYElement)
                 return;
             // Get fresh track rect at drag time
             const trackRect = this.scrollbarYElement.getBoundingClientRect();
-            const maxThumbPos = Math.max(0, trackRect.height - this.thumbYSize);
+            const maxThumbPos = Math.max(0, trackRect.height - this.thumbYBaseSize);
             // Calculate new thumb position relative to track
-            let newThumbTop = clientY - this.dragOffset - trackRect.top;
+            let newThumbTop = y - this.dragOffset - trackRect.top;
             newThumbTop = Math.max(0, Math.min(newThumbTop, maxThumbPos));
             const scrollPercentage = maxThumbPos > 0 ? newThumbTop / maxThumbPos : 0;
             this.viewportElement.scrollTop = scrollPercentage * this.maxScrollY;
+        },
+        onEnd: () => {
+            this.isDraggingY = false;
+            this.restoreScrollSnap();
+        },
+        onCancel: () => {
+            this.isDraggingY = false;
+            this.restoreScrollSnap();
         }
     });
-    isDraggingY = $derived(this.dragY.isDragging);
-    thumbXSize = $derived.by(() => {
-        if (!this.scrollbarXEnabled ||
-            !this.scrollbarXElement ||
-            !this.viewportElement ||
-            !this.contentElement) {
-            return 0;
-        }
-        const scrollbarXWidth = this.scrollbarXElement.clientWidth;
-        const thumbXRatio = this.viewportElement.clientWidth / this.viewportElement.scrollWidth;
-        return Math.max(thumbXRatio * scrollbarXWidth, 18);
-    });
-    dragX = useDrag({
-        isActive: true,
-        onDragStart: ({ clientX, target }) => {
-            const thumbRect = target.getBoundingClientRect();
-            this.dragOffset = clientX - thumbRect.left;
+    isDraggingX = $state(false);
+    dragX = createPointerDrag({
+        onStart: ({ event, node }) => {
+            // Offset from the pointer to the thumb's inline start edge.
+            this.syncDirection();
+            const rect = node.getBoundingClientRect();
+            this.dragOffset = this.rtl ? rect.right - event.clientX : event.clientX - rect.left;
+            this.isDraggingX = true;
+            this.pauseScrollSnap();
         },
-        onDrag: ({ clientX }) => {
+        onMove: ({ x }) => {
             if (!this.scrollbarXElement)
                 return;
             const trackRect = this.scrollbarXElement.getBoundingClientRect();
-            const maxThumbPos = Math.max(0, trackRect.width - this.thumbXSize);
-            let newThumbLeft = clientX - this.dragOffset - trackRect.left;
-            newThumbLeft = Math.max(0, Math.min(newThumbLeft, maxThumbPos));
-            const scrollPercentage = maxThumbPos > 0 ? newThumbLeft / maxThumbPos : 0;
-            this.viewportElement.scrollLeft = scrollPercentage * this.maxScrollX;
+            const maxThumbPos = Math.max(0, trackRect.width - this.thumbXBaseSize);
+            const pointer = this.rtl ? trackRect.right - x : x - trackRect.left;
+            const newThumbStart = Math.max(0, Math.min(pointer - this.dragOffset, maxThumbPos));
+            const scrollPercentage = maxThumbPos > 0 ? newThumbStart / maxThumbPos : 0;
+            this.writeScrollX(scrollPercentage * this.maxScrollX);
+        },
+        onEnd: () => {
+            this.isDraggingX = false;
+            this.restoreScrollSnap();
+        },
+        onCancel: () => {
+            this.isDraggingX = false;
+            this.restoreScrollSnap();
         }
     });
-    isDraggingX = $derived(this.dragX.isDragging);
-    // The viewport is the focusable scroll region — but only when it actually overflows, so an
-    // idle ScrollArea (e.g. a dropdown whose items fit) adds no phantom tab stop. Native
-    // `overflow: auto` then handles all keyboard scrolling (arrows, PageUp/Down, Home/End, Space).
-    viewportTabindex = $derived(this.scrollbarYEnabled || this.scrollbarXEnabled ? 0 : -1);
+    // The viewport is the focusable, named scroll region — but only when it actually overflows, so
+    // an idle ScrollArea (e.g. a dropdown whose items fit) adds no phantom tab stop and no group to
+    // the accessibility tree. Native `overflow: auto` then handles all keyboard scrolling (arrows,
+    // PageUp/Down, Home/End, Space).
+    overflowing = $derived(this.scrollbarYEnabled || this.scrollbarXEnabled);
     // Warning : non reactive.
     hoover = $derived(useHoverAction({
         delay: this.delay,
@@ -129,31 +230,77 @@ export class ScrollArea extends createBindableStateClass() {
     thumbYPosition = $derived.by(() => {
         if (this.maxScrollY <= 0 || !this.scrollbarYElement)
             return 0;
-        const trackHeight = this.scrollbarYElement.clientHeight;
-        return (this.scrollY / this.maxScrollY) * (trackHeight - this.thumbYSize);
+        const overscroll = this.overscrollY;
+        if (overscroll < 0)
+            return 0;
+        if (overscroll > 0)
+            return this.trackYLength - this.thumbYSize;
+        return (this.scrollY / this.maxScrollY) * (this.trackYLength - this.thumbYSize);
     });
+    /** Distance from the track's inline start to the thumb's inline start edge. */
     thumbXPosition = $derived.by(() => {
         if (this.maxScrollX <= 0 || !this.scrollbarXElement)
             return 0;
-        const trackWidth = this.scrollbarXElement.clientWidth;
-        return (this.scrollX / this.maxScrollX) * (trackWidth - this.thumbXSize);
+        const overscroll = this.overscrollX;
+        if (overscroll < 0)
+            return 0;
+        if (overscroll > 0)
+            return this.trackXLength - this.thumbXSize;
+        return (this.scrollX / this.maxScrollX) * (this.trackXLength - this.thumbXSize);
     });
+    /** The horizontal thumb's `translateX` in px: mirrored in RTL, where the track fills from the right. */
+    thumbXTranslate = $derived(this.rtl ? -this.thumbXPosition : this.thumbXPosition);
     // Wheel / touch / trackpad / momentum scrolling is fully NATIVE via the viewport's
     // `overflow: auto` — no custom handlers needed. This class only reads the native scroll
     // offset (handleScroll) to position the custom thumbs, and drives programmatic scroll for
     // thumb-drag, track-click, keyboard, and edge auto-scroll.
-    isScrolling = $state(null);
+    // True from the first scroll event until the viewport has been idle for a moment. The timer
+    // handle is a plain field: only the boolean is state, so a scroll session writes it twice
+    // instead of once per event.
+    isScrolling = $state(false);
+    scrollingTimer = null;
+    clearScrollingTimer() {
+        if (this.scrollingTimer === null)
+            return;
+        clearTimeout(this.scrollingTimer);
+        this.scrollingTimer = null;
+    }
+    /** Horizontal scroll offset as distance from the inline start, whatever the direction. */
+    readScrollX(viewport) {
+        return unsigned(this.rtl ? -viewport.scrollLeft : viewport.scrollLeft);
+    }
+    /** Scrolls horizontally to a distance from the inline start. */
+    writeScrollX(value) {
+        if (!this.viewportElement)
+            return;
+        this.viewportElement.scrollLeft = this.rtl ? -value : value;
+    }
+    /** Re-resolves the writing direction; true when it flipped. */
+    syncDirection() {
+        const rtl = this.direction?.() === 'rtl';
+        if (rtl === this.rtl)
+            return false;
+        this.rtl = rtl;
+        return true;
+    }
+    readScrollOffsets() {
+        const viewport = this.viewportElement;
+        if (!viewport)
+            return;
+        this.scrollY = viewport.scrollTop;
+        this.scrollX = this.readScrollX(viewport);
+    }
     handleScroll = () => {
-        if (this.isScrolling) {
-            clearTimeout(this.isScrolling);
-        }
-        this.isScrolling = setTimeout(() => {
-            this.isScrolling = null;
-        }, 400);
-        if (this.viewportElement) {
-            this.scrollY = this.viewportElement.scrollTop;
-            this.scrollX = this.viewportElement.scrollLeft;
-        }
+        if (!this.isScrolling)
+            this.isScrolling = true;
+        this.clearScrollingTimer();
+        this.scrollingTimer = setTimeout(() => {
+            this.scrollingTimer = null;
+            this.isScrolling = false;
+        }, SCROLLING_IDLE_MS);
+        // A `dir` flip moves no observed box; the next scroll is the cheapest place to notice it.
+        this.syncDirection();
+        this.readScrollOffsets();
     };
     handleTrackClick = (event) => {
         if (!this.viewportElement || !this.scrollbarYElement)
@@ -166,9 +313,9 @@ export class ScrollArea extends createBindableStateClass() {
         const trackRect = trackElement.getBoundingClientRect();
         const clickY = event.clientY - trackRect.top;
         // Calculate the maximum thumb position (track height minus thumb height)
-        const maxThumbPos = Math.max(0, trackRect.height - this.thumbYSize);
+        const maxThumbPos = Math.max(0, trackRect.height - this.thumbYBaseSize);
         // Center the thumb on the click position
-        const targetThumbPos = clickY - this.thumbYSize / 2;
+        const targetThumbPos = clickY - this.thumbYBaseSize / 2;
         const clampedThumbPos = Math.max(0, Math.min(targetThumbPos, maxThumbPos));
         // Convert thumb position to scroll position
         const scrollPercentage = maxThumbPos > 0 ? clampedThumbPos / maxThumbPos : 0;
@@ -179,18 +326,19 @@ export class ScrollArea extends createBindableStateClass() {
             return;
         if (event.composedPath().some((el) => el instanceof HTMLElement && el.dataset.thumb === ''))
             return;
+        this.syncDirection();
         const trackRect = this.scrollbarXElement.getBoundingClientRect();
-        const clickX = event.clientX - trackRect.left;
-        const maxThumbPos = Math.max(0, trackRect.width - this.thumbXSize);
-        const targetThumbPos = clickX - this.thumbXSize / 2;
+        const clickX = this.rtl ? trackRect.right - event.clientX : event.clientX - trackRect.left;
+        const maxThumbPos = Math.max(0, trackRect.width - this.thumbXBaseSize);
+        const targetThumbPos = clickX - this.thumbXBaseSize / 2;
         const clampedThumbPos = Math.max(0, Math.min(targetThumbPos, maxThumbPos));
         const scrollPercentage = maxThumbPos > 0 ? clampedThumbPos / maxThumbPos : 0;
-        this.viewportElement.scrollLeft = scrollPercentage * this.maxScrollX;
+        this.writeScrollX(scrollPercentage * this.maxScrollX);
     };
     // ---------------------------------------------------------------------------------------
     // Overflow measurement
     //
-    // `viewportTabindex` (WCAG SCR34) hangs off these numbers, so a stale measurement is an
+    // `overflowing` (the WCAG SCR34 tab stop) hangs off these numbers, so a stale measurement is an
     // accessibility bug, not a cosmetic one. Three things can make the first ResizeObserver
     // callback wrong: it can fire before the first layout has settled, the content can grow
     // afterwards without changing the observed border-boxes (an image resolving, a streamed
@@ -209,6 +357,10 @@ export class ScrollArea extends createBindableStateClass() {
         const viewport = this.viewportElement;
         if (!viewport)
             return;
+        // The direction decides how the horizontal offset reads (negative in RTL), so it is
+        // re-read with every measurement, and the offsets are published again when it flips.
+        this.syncDirection();
+        this.readScrollOffsets();
         const viewportWidth = viewport.clientWidth;
         const viewportHeight = viewport.clientHeight;
         if (viewportWidth !== this.viewportDimensions.width ||
@@ -222,7 +374,7 @@ export class ScrollArea extends createBindableStateClass() {
             contentHeight !== this.contentDimensions.height) {
             this.contentDimensions = { width: contentWidth, height: contentHeight };
         }
-        // The scroll extent is what `viewportTabindex` and the scrollbars are derived from, and it
+        // The scroll extent is what `overflowing` and the scrollbars are derived from, and it
         // can change while both observed border-boxes stay identical. Bump only when it moves.
         const extentY = viewport.scrollHeight - viewportHeight;
         const extentX = viewport.scrollWidth - viewportWidth;
@@ -253,6 +405,11 @@ export class ScrollArea extends createBindableStateClass() {
     }
     viewportAttachment = (element) => {
         this.viewportElement = element;
+        untrack(() => {
+            this.rtl = this.direction?.() === 'rtl';
+            // A restored or pre-set scroll position is not announced by a scroll event.
+            this.readScrollOffsets();
+        });
         const offScroll = on(element, 'scroll', this.handleScroll);
         // Hide the native scrollbars cross-browser (WebKit handled via the component <style>).
         element.style.scrollbarWidth = 'none'; // Firefox + standard
@@ -266,12 +423,24 @@ export class ScrollArea extends createBindableStateClass() {
             }
         });
         const offResize = resizeObserver.reference?.(element);
+        // A `dir` flip on the page or any wrapper (a language switcher) resizes nothing and need not
+        // scroll anything; watch the attribute on the way up so the direction is re-read.
+        let dirObserver = null;
+        if (typeof MutationObserver === 'function') {
+            dirObserver = new MutationObserver(this.scheduleMeasure);
+            for (let node = element; node; node = node.parentElement) {
+                dirObserver.observe(node, { attributes: true, attributeFilter: ['dir'] });
+            }
+        }
         // The observer's first callback can land before layout has settled; re-read next frame.
         this.scheduleMeasure();
         return () => {
             offScroll();
             offResize?.();
+            dirObserver?.disconnect();
             this.cancelScheduledMeasure();
+            this.clearScrollingTimer();
+            this.restoreScrollSnap();
         };
     };
     contentAttachment = (element) => {
@@ -311,28 +480,69 @@ export class ScrollArea extends createBindableStateClass() {
         };
     };
     // Forward a wheel over the (overlaid) custom scrollbar to the viewport, so wheeling on the
-    // thin bar scrolls the content just like wheeling on the viewport does.
+    // thin bar scrolls the content just like wheeling on the viewport does. The wheel is only
+    // consumed while the viewport can still move that way: at an edge it goes on to scroll the
+    // page behind, as it does over the viewport itself.
     forwardWheelToViewport = (event) => {
-        if (!this.viewportElement)
+        const viewport = this.viewportElement;
+        if (!viewport)
+            return;
+        const canScrollY = event.deltaY > 0
+            ? viewport.scrollHeight - viewport.clientHeight - viewport.scrollTop >= OVERFLOW_TOLERANCE
+            : event.deltaY < 0 && viewport.scrollTop >= OVERFLOW_TOLERANCE;
+        // Along the inline axis: a positive delta scrolls towards the inline end.
+        const towardsEnd = (this.rtl ? -event.deltaX : event.deltaX) > 0;
+        const towardsStart = (this.rtl ? -event.deltaX : event.deltaX) < 0;
+        const scrollX = this.readScrollX(viewport);
+        const maxScrollX = viewport.scrollWidth - viewport.clientWidth;
+        const canScrollX = (towardsEnd && maxScrollX - scrollX >= OVERFLOW_TOLERANCE) ||
+            (towardsStart && scrollX >= OVERFLOW_TOLERANCE);
+        if (!canScrollY && !canScrollX)
             return;
-        this.viewportElement.scrollTop += event.deltaY;
-        this.viewportElement.scrollLeft += event.deltaX;
+        viewport.scrollTop += event.deltaY;
+        viewport.scrollLeft += event.deltaX;
         event.preventDefault();
     };
+    // A press on a scrollbar or its thumb must not pull focus away from the control that has it
+    // (a Combobox input whose list is being dragged, say): the default action of the press, which
+    // moves focus and starts a text selection, is cancelled. Touch is left alone, where it would
+    // only stop the scroll gesture.
+    keepFocusOnPress = (event) => {
+        if (event.button === 0)
+            event.preventDefault();
+    };
     trackAttachment = (element) => {
+        this.trackYThickness = element.offsetWidth;
         const offClick = on(element, 'click', this.handleTrackClick);
         const offWheel = on(element, 'wheel', this.forwardWheelToViewport, { passive: false });
+        const offPointerDown = on(element, 'pointerdown', (event) => {
+            if (event.pointerType !== 'touch')
+                this.keepFocusOnPress(event);
+        });
+        const offMouseDown = on(element, 'mousedown', this.keepFocusOnPress);
         return () => {
             offClick();
             offWheel();
+            offPointerDown();
+            offMouseDown();
+            this.trackYThickness = 0;
         };
     };
     trackAttachmentX = (element) => {
+        this.trackXThickness = element.offsetHeight;
         const offClick = on(element, 'click', this.handleTrackClickX);
         const offWheel = on(element, 'wheel', this.forwardWheelToViewport, { passive: false });
+        const offPointerDown = on(element, 'pointerdown', (event) => {
+            if (event.pointerType !== 'touch')
+                this.keepFocusOnPress(event);
+        });
+        const offMouseDown = on(element, 'mousedown', this.keepFocusOnPress);
         return () => {
             offClick();
             offWheel();
+            offPointerDown();
+            offMouseDown();
+            this.trackXThickness = 0;
         };
     };
     scrollAnimationFrame = $state(null);

package/dist/components/ScrollArea/scrollArea.theme.js

@@ -24,11 +24,14 @@ const defaultScrollAreaContent = cva({
     // Sizing (min-width/width/position) is set inline in the component; keep this minimal.
     base: 'relative'
 });
+// Logical placement: the vertical bar sits at the inline end (the right in LTR, the left in RTL),
+// the horizontal bar fills from the inline start. Where both show, the component insets each by
+// the other's thickness so they do not overlap at the corner.
 const defaultScrollAreaScrollbar = cva({
-    base: 'absolute top-0 right-0 z-30 w-1.5 cursor-pointer'
+    base: 'absolute top-0 end-0 z-30 w-1.5 cursor-pointer'
 });
 const defaultScrollAreaScrollbarX = cva({
-    base: 'absolute bottom-0 left-0 z-30 h-1.5 cursor-pointer'
+    base: 'absolute bottom-0 start-0 z-30 h-1.5 cursor-pointer'
 });
 const defaultScrollAreaScrollbarThumb = cva({
     base: "relative bg-neutral-muted after:absolute after:-inset-1 after:content-['']"

package/dist/components/SegmentedControl/SegmentedControl.svelte

@@ -72,9 +72,10 @@
 		enabled: () => !disabled,
 		enableHoverFocus: false,
 		defaultFocusedIndex: () => (tabStopIndex >= 0 ? tabStopIndex : null),
-		onChange: (index) => {
-			if (index !== null) selectItem(index);
-		}
+		// Selection follows the keyboard, but only a deliberate key move (an arrow, Home or End)
+		// selects. Tabbing in, a programmatic focus or the restore after a removal never changes
+		// the value, and Alt, Ctrl or Meta with an arrow is left to the browser.
+		onKeyboardMove: (index) => selectItem(index)
 	});
 
 	const indicator = useSlidingIndicator({

package/dist/components/SegmentedControl/segmentedControl.mcp.d.ts

@@ -1 +1 @@
-export declare const segmentedControlDescription = "\n# SegmentedControl\n\nA compact single-selection input for switching between a small set of mutually exclusive modes. It uses radiogroup/radio semantics and an animated indicator that slides and resizes to the selected item.\n\n## Basic usage\n\n```svelte\n<script lang=\"ts\">\n  import { SegmentedControl } from './index.ts';\n  import { gridFourIcon } from 'entasis/icons/gridFour';\n  import { listIcon } from 'entasis/icons/list';\n\n  const items = [\n    { value: 'grid', label: 'Grid', icon: gridFourIcon },\n    { value: 'list', label: 'List', icon: listIcon }\n  ] as const;\n\n  let value = $state<(typeof items)[number]['value']>('grid');\n</script>\n\n<SegmentedControl {items} bind:value />\n```\n\n## Props\n\n- **items**: `readonly SegmentedControlItem[]` \u2014 required options with unique `value` fields.\n- **value**: `string` \u2014 bindable selected value; defaults to the first enabled item.\n- **defaultValue**: `string` \u2014 initial selected value when value is omitted.\n- **onValueChange**: `(value: string) => void` \u2014 called once after user interaction changes the value.\n- **item**: `Snippet<[SegmentedControlItem]>` \u2014 replaces the default item renderer.\n- **size**: `'small' | 'normal' | 'large'` \u2014 defaults to `'normal'`.\n- **color**: semantic color \u2014 controls the selected pill and focus ring; defaults to `'neutral'`.\n- **variant**: `'normal' | 'pill'` \u2014 controls corner radius; defaults to the moderately rounded `'normal'` shape.\n- **disabled**: `boolean` \u2014 disables the full control.\n- **label**: `string` \u2014 accessible name for the radiogroup; defaults to the catalog's \"Segmented control\".\n- **class**: additional root classes.\n- **theme**: component theme overrides.\n\n## Item shape\n\n```ts\ntype SegmentedControlItem<Value extends string = string> = {\n  value: Value;\n  label?: string | Snippet;\n  icon?: string | Snippet;\n  disabled?: boolean;\n};\n```\n\nThe default renderer displays `icon`, then `label`. `label` is also the segment's accessible name: a string is painted and spoken, a snippet names the segment through its own content, and an icon-only segment (no `label`) falls back to its `value`.\n\n## Custom item renderer\n\n```svelte\n<SegmentedControl {items} bind:value>\n  {#snippet item(option)}\n    <span>{option.label}</span>\n    <span>{option.count}</span>\n  {/snippet}\n</SegmentedControl>\n```\n\nExtra fields on item objects remain available to the snippet through generic inference.\n\n## Shapes\n\n`variant=\"normal\"` uses a moderately rounded track and segments. Use `variant=\"pill\"` for the fully rounded stadium shape.\n\n```svelte\n<SegmentedControl {items} bind:value />\n<SegmentedControl {items} bind:value variant=\"pill\" />\n```\n\n## Keyboard behavior\n\n- Tab enters on the selected item, or the first enabled item when no value matches.\n- Arrow Left/Right moves and selects, wrapping at the ends.\n- Home/End selects the first/last enabled item.\n- Disabled items are skipped.\n\nEach item has an invisible, size-aware pointer target that extends beyond the visual track: 36px for small, 44px for normal, and 48px for large. Adjacent targets meet at the midpoint of the configured gap instead of overlapping.\n\nUse SegmentedControl for mode or value selection. Use Tabbar when changing navigational views with tab semantics.\n";
+export declare const segmentedControlDescription = "\n# SegmentedControl\n\nA compact single-selection input for switching between a small set of mutually exclusive modes. It uses radiogroup/radio semantics and an animated indicator that slides and resizes to the selected item.\n\n## Basic usage\n\n```svelte\n<script lang=\"ts\">\n  import { SegmentedControl } from './index.ts';\n  import { gridFourIcon } from 'entasis/icons/gridFour';\n  import { listIcon } from 'entasis/icons/list';\n\n  const items = [\n    { value: 'grid', label: 'Grid', icon: gridFourIcon },\n    { value: 'list', label: 'List', icon: listIcon }\n  ] as const;\n\n  let value = $state<(typeof items)[number]['value']>('grid');\n</script>\n\n<SegmentedControl {items} bind:value />\n```\n\n## Props\n\n- **items**: `readonly SegmentedControlItem[]` \u2014 required options with unique `value` fields.\n- **value**: `string` \u2014 bindable selected value; defaults to the first enabled item.\n- **defaultValue**: `string` \u2014 initial selected value when value is omitted.\n- **onValueChange**: `(value: string) => void` \u2014 called once after user interaction changes the value.\n- **item**: `Snippet<[SegmentedControlItem]>` \u2014 replaces the default item renderer.\n- **size**: `'small' | 'normal' | 'large'` \u2014 defaults to `'normal'`.\n- **color**: semantic color \u2014 controls the selected pill and focus ring; defaults to `'neutral'`.\n- **variant**: `'normal' | 'pill'` \u2014 controls corner radius; defaults to the moderately rounded `'normal'` shape.\n- **disabled**: `boolean` \u2014 disables the full control.\n- **label**: `string` \u2014 accessible name for the radiogroup; defaults to the catalog's \"Segmented control\".\n- **class**: additional root classes.\n- **theme**: component theme overrides.\n\n## Item shape\n\n```ts\ntype SegmentedControlItem<Value extends string = string> = {\n  value: Value;\n  label?: string | Snippet;\n  icon?: string | Snippet;\n  disabled?: boolean;\n};\n```\n\nThe default renderer displays `icon`, then `label`. `label` is also the segment's accessible name: a string is painted and spoken, a snippet names the segment through its own content, and an icon-only segment (no `label`) falls back to its `value`.\n\n## Custom item renderer\n\n```svelte\n<SegmentedControl {items} bind:value>\n  {#snippet item(option)}\n    <span>{option.label}</span>\n    <span>{option.count}</span>\n  {/snippet}\n</SegmentedControl>\n```\n\nExtra fields on item objects remain available to the snippet through generic inference.\n\n## Shapes\n\n`variant=\"normal\"` uses a moderately rounded track and segments. Use `variant=\"pill\"` for the fully rounded stadium shape.\n\n```svelte\n<SegmentedControl {items} bind:value />\n<SegmentedControl {items} bind:value variant=\"pill\" />\n```\n\n## Keyboard behavior\n\n- Tab enters on the selected item, or the first enabled item when no value matches. Tabbing in never changes the value, even when the selected item is disabled or no value matches.\n- Arrow Left/Right moves and selects, wrapping at the ends. Only a deliberate key move selects: arrows, Home and End.\n- Home/End selects the first/last enabled item.\n- Disabled items are skipped.\n- Arrow, Home and End keys pressed with Alt, Ctrl or Meta are left to the browser and never change the selection (Alt+ArrowLeft stays Back); Shift+Arrow still moves.\n\nEach item has an invisible, size-aware pointer target that extends beyond the visual track: 36px for small, 44px for normal, and 48px for large. Adjacent targets meet at the midpoint of the configured gap instead of overlapping.\n\nUse SegmentedControl for mode or value selection. Use Tabbar when changing navigational views with tab semantics.\n";

package/dist/components/SegmentedControl/segmentedControl.mcp.js

@@ -74,10 +74,11 @@ Extra fields on item objects remain available to the snippet through generic inf
 
 ## Keyboard behavior
 
-- Tab enters on the selected item, or the first enabled item when no value matches.
-- Arrow Left/Right moves and selects, wrapping at the ends.
+- Tab enters on the selected item, or the first enabled item when no value matches. Tabbing in never changes the value, even when the selected item is disabled or no value matches.
+- Arrow Left/Right moves and selects, wrapping at the ends. Only a deliberate key move selects: arrows, Home and End.
 - Home/End selects the first/last enabled item.
 - Disabled items are skipped.
+- Arrow, Home and End keys pressed with Alt, Ctrl or Meta are left to the browser and never change the selection (Alt+ArrowLeft stays Back); Shift+Arrow still moves.
 
 Each item has an invisible, size-aware pointer target that extends beyond the visual track: 36px for small, 44px for normal, and 48px for large. Adjacent targets meet at the midpoint of the configured gap instead of overlapping.
 

package/dist/components/SelectionMenu/SelectionMenu.svelte

@@ -2,7 +2,8 @@
 	import { tick } from 'svelte';
 	import type { Attachment } from 'svelte/attachments';
 	import Popover from '../Popover/Popover.svelte';
-	import type { PopoverState } from '../Popover/popover.state.svelte.js';
+	import { popoverInternals, type PopoverState } from '../Popover/popover.state.svelte.js';
+	import type { PopoverApi } from '../Popover/popover.api.js';
 	import Slot from '../Slot/Slot.svelte';
 	import ToggleMenu from '../ToggleMenu/ToggleMenu.svelte';
 	import type { SelectionMenuProps, SelectionMenuPayload } from './selectionMenu.props.js';
@@ -84,7 +85,8 @@
 		open = nextOpen;
 	}
 
-	function contentReference(popover: PopoverState): Attachment<HTMLElement> {
+	function contentReference(api: PopoverApi): Attachment<HTMLElement> {
+		const popover = popoverInternals(api);
 		return (node) => {
 			popoverState = popover;
 			contentElement = node;

package/dist/components/Sidebar/SidebarAction.svelte

@@ -1,7 +1,12 @@
 <script lang="ts">
 	import PopupMenu from '../PopupMenu/PopupMenu.svelte';
 	import { dotsThreeIcon } from '../Icons/dotsThree.js';
-	import type { SidebarApi, SidebarMenuActionDescriptor, SidebarSize } from './sidebar.props.js';
+	import type {
+		SidebarApi,
+		SidebarMenuActionDescriptor,
+		SidebarDensity,
+		SidebarSize
+	} from './sidebar.props.js';
 	import { getSidebarMenuPosition } from './sidebar-position.js';
 	import SidebarIcon from './SidebarIcon.svelte';
 	import { useSidebarTheme, type SidebarThemeProps } from './sidebar.theme.js';
@@ -10,11 +15,13 @@
 		action,
 		api,
 		size,
+		density = 'normal',
 		theme
 	}: {
 		action: SidebarMenuActionDescriptor | import('svelte').Snippet<[SidebarApi]>;
 		api: SidebarApi;
 		size: SidebarSize;
+		density?: SidebarDensity;
 		theme?: SidebarThemeProps;
 	} = $props();
 
@@ -29,8 +36,11 @@
 	{@render action(api)}
 {:else if action.menu}
 	<PopupMenu
-		menu={{ items: action.menu }}
-		position={getSidebarMenuPosition(action.menuSide, action.menuAlign, api.isMobile)}
+		menu={{ items: action.menu, size, density }}
+		position={getSidebarMenuPosition(action.menuSide, action.menuAlign, {
+			isMobile: api.isMobile,
+			side: api.side
+		})}
 		class={action.menuClass}
 		fitTrigger={false}
 	>

package/dist/components/Sidebar/SidebarAction.svelte.d.ts

@@ -1,9 +1,10 @@
-import type { SidebarApi, SidebarMenuActionDescriptor, SidebarSize } from './sidebar.props.js';
+import type { SidebarApi, SidebarMenuActionDescriptor, SidebarDensity, SidebarSize } from './sidebar.props.js';
 import { type SidebarThemeProps } from './sidebar.theme.js';
 type $$ComponentProps = {
     action: SidebarMenuActionDescriptor | import('svelte').Snippet<[SidebarApi]>;
     api: SidebarApi;
     size: SidebarSize;
+    density?: SidebarDensity;
     theme?: SidebarThemeProps;
 };
 declare const SidebarAction: import("svelte").Component<$$ComponentProps, {}, "">;