entasis 0.11.0 → 0.13.0

package/dist/components/Form/Slider/slider.state.svelte.js

@@ -22,8 +22,16 @@ export class SliderState extends createBindableStateClass() {
     // eslint-disable-next-line svelte/prefer-svelte-reactivity -- Render-time attachment caches must not update reactive state.
     thumbAttachments = new Map();
     // eslint-disable-next-line svelte/prefer-svelte-reactivity -- Render-time attachment caches must not update reactive state.
+    thumbInputAttachments = new Map();
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity -- Render-time attachment caches must not update reactive state.
     thumbHitboxAttachments = new Map();
     documentHitboxDragCleanup = null;
+    // What the value was when the interaction in progress began. The commit compares against it,
+    // so an interaction that ends where it started commits nothing.
+    dragFrom = null;
+    inputFrom = null;
+    // Not reactive: `fieldValue` memoizes its array output here (see fieldValue).
+    arrayFieldValue = null;
     trackDrag = createPointerDrag({
         disabled: () => this.isDisabled(),
         onStart: (payload) => this.startTrackPointerDrag(payload),
@@ -56,11 +64,47 @@ export class SliderState extends createBindableStateClass() {
         const maxDistance = this.thumbCount <= 1 ? requestedDistance : availableDistance / (this.thumbCount - 1);
         return Math.min(requestedDistance, maxDistance);
     });
+    /** Amount PageUp, PageDown and Shift+Arrow move a thumb by. */
+    largeStepSize = $derived.by(() => {
+        const largeStep = getFiniteNumber(this.largeStep, 0);
+        return largeStep > 0 ? largeStep : this.stepValue * 10;
+    });
+    collisionBehavior = $derived(this.thumbCollisionBehavior === 'push' || this.thumbCollisionBehavior === 'swap'
+        ? this.thumbCollisionBehavior
+        : 'none');
     orientationValue = $derived(this.orientation === 'vertical' ? 'vertical' : 'horizontal');
     values = $derived.by(() => this.getNormalizedValues());
     isRange = $derived(this.values.length > 1);
-    fieldType = $derived(this.isRange ? 'slider-range' : 'slider');
-    fieldValue = $derived(this.isRange ? this.values : (this.values[0] ?? this.minValue));
+    /** Whether any single thumb is disabled on its own. */
+    hasLockedThumb = $derived(this.values.some((_, index) => this.isThumbLocked(index)));
+    /** The selected range moves as a unit only when every thumb is free to move and edits are allowed. */
+    canDragRange = $derived(!!this.dragRange && this.isRange && !this.hasLockedThumb && !this.readOnly);
+    /**
+     * The thumb that stands for the field: the label's target and the focus target for errors. It is
+     * the first thumb that can take focus, because a disabled input ignores label clicks and focus().
+     */
+    controlIndex = $derived.by(() => {
+        const free = this.values.findIndex((_, index) => !this.isThumbDisabled(index));
+        return free === -1 ? 0 : free;
+    });
+    /** The value keeps an array shape (even with one thumb) when it arrived as one or is a range. */
+    isArrayValue = $derived(Array.isArray(this.value) || this.mode === 'range' || this.thumbCount > 1);
+    fieldType = $derived(this.isArrayValue ? 'slider-range' : 'slider');
+    fieldValue = $derived.by(() => {
+        if (!this.isArrayValue)
+            return this.values[0] ?? this.minValue;
+        // Reuse the last array handed out while it holds the same values: a Form bound to $state
+        // writes the value back as a new deep proxy, and a new array per pass would never settle.
+        // It stays plain data, never the proxied `value` prop, so callers can clone, post or keep it.
+        const values = this.values;
+        const previous = this.arrayFieldValue;
+        if (previous?.length === values.length &&
+            previous.every((item, index) => item === values[index])) {
+            return previous;
+        }
+        this.arrayFieldValue = [...values];
+        return this.arrayFieldValue;
+    });
     startPercentage = $derived(this.getPercentage(this.values[0] ?? this.minValue));
     endPercentage = $derived(this.getPercentage(this.values[this.values.length - 1] ?? this.minValue));
     valuePayloads = $derived.by(() => this.values.map((value, index) => this.getValuePayload(index, value)));
@@ -87,38 +131,60 @@ export class SliderState extends createBindableStateClass() {
             offPointerDown();
             this.cleanupDocumentHitboxDrag();
             this.trackNode = null;
-            this.endDrag();
+            this.cancelDrag();
         };
     };
     range = (node) => {
         return this.rangeDrag(node);
     };
+    /** The pointer surface of a thumb: its visual wrapper, which holds the focusable range input. */
     thumb(index) {
         const cachedAttachment = this.thumbAttachments.get(index);
         if (cachedAttachment)
             return cachedAttachment;
         const attachment = (node) => {
             const drag = createPointerDrag({
-                disabled: () => this.isDisabled(),
+                disabled: () => this.isThumbDisabled(index),
                 stopPropagation: true,
-                onStart: () => this.startThumbPointerDrag(index, node),
+                onStart: () => this.startThumbHitboxPointerDrag(index),
                 onMove: (payload) => this.updatePointerDrag(payload),
                 onEnd: () => this.endDrag()
             });
+            const offLocked = this.swallowLockedPress(node, index);
+            const offDrag = drag(node);
+            return () => {
+                offLocked();
+                offDrag?.();
+            };
+        };
+        this.thumbAttachments.set(index, attachment);
+        return attachment;
+    }
+    /** The focus target of a thumb: its visually hidden `<input type="range">`. */
+    thumbInput(index) {
+        const cachedAttachment = this.thumbInputAttachments.get(index);
+        if (cachedAttachment)
+            return cachedAttachment;
+        const attachment = (node) => {
             const offFocus = on(node, 'focus', () => this.focusThumb(index));
             const offBlur = on(node, 'blur', this.onThumbBlur);
-            const offDrag = drag(node);
             const offKeyDown = on(node, 'keydown', (event) => this.onThumbKeyDown(event, index));
+            // Assistive technology adjusts a range input without key events, through `input`
+            // while it moves and `change` once the adjustment is done.
+            const offInput = on(node, 'input', () => this.onThumbInput(index));
+            const offChange = on(node, 'change', () => this.flushInputCommit());
             this.thumbNodes.set(index, node);
             return () => {
                 offFocus();
                 offBlur();
-                offDrag?.();
                 offKeyDown();
-                this.thumbNodes.delete(index);
+                offInput();
+                offChange();
+                if (this.thumbNodes.get(index) === node)
+                    this.thumbNodes.delete(index);
             };
         };
-        this.thumbAttachments.set(index, attachment);
+        this.thumbInputAttachments.set(index, attachment);
         return attachment;
     }
     thumbHitbox(index) {
@@ -127,13 +193,18 @@ export class SliderState extends createBindableStateClass() {
             return cachedAttachment;
         const attachment = (node) => {
             const drag = createPointerDrag({
-                disabled: () => this.isDisabled(),
+                disabled: () => this.isThumbDisabled(index),
                 stopPropagation: true,
                 onStart: () => this.startThumbHitboxPointerDrag(index),
                 onMove: (payload) => this.updatePointerDrag(payload),
                 onEnd: () => this.endDrag()
             });
-            return drag(node);
+            const offLocked = this.swallowLockedPress(node, index);
+            const offDrag = drag(node);
+            return () => {
+                offLocked();
+                offDrag?.();
+            };
         };
         this.thumbHitboxAttachments.set(index, attachment);
         return attachment;
@@ -218,15 +289,34 @@ export class SliderState extends createBindableStateClass() {
             thumbMax: thumbBounds.max
         };
     }
+    /**
+     * The range a thumb can move within. A thumb is stopped by the thumbs that block it: its
+     * neighbours when thumbs stop at each other, and a disabled thumb in every mode. Pushing needs
+     * room for each thumb it moves along, so its bounds leave that room.
+     */
     getThumbBounds(index) {
-        const previousValue = this.values[index - 1];
-        const nextValue = this.values[index + 1];
-        return {
-            min: typeof previousValue === 'number'
-                ? this.normalize(previousValue + this.minDistance)
-                : this.minValue,
-            max: typeof nextValue === 'number' ? this.normalize(nextValue - this.minDistance) : this.maxValue
-        };
+        const values = this.values;
+        const gap = this.minDistance;
+        const behavior = this.collisionBehavior;
+        const pushes = behavior === 'push';
+        const blocks = (other) => behavior === 'none' || this.isThumbLocked(other);
+        let below = index - 1;
+        while (below >= 0 && !blocks(below))
+            below -= 1;
+        let above = index + 1;
+        while (above < values.length && !blocks(above))
+            above += 1;
+        const lower = below < 0
+            ? pushes
+                ? this.minValue + index * gap
+                : this.minValue
+            : values[below] + (pushes ? index - below : 1) * gap;
+        const upper = above >= values.length
+            ? pushes
+                ? this.maxValue - (values.length - 1 - index) * gap
+                : this.maxValue
+            : values[above] - (pushes ? above - index : 1) * gap;
+        return { min: this.normalize(lower), max: this.normalize(upper) };
     }
     markPayload(mark) {
         const value = this.clamp(mark.value);
@@ -237,10 +327,13 @@ export class SliderState extends createBindableStateClass() {
             formatted: this.getFormattedValue(value, 0, this.values)
         };
     }
+    /** The enabled thumb nearest to `value`, or null when none can move. */
     getClosestThumbIndex(value) {
-        let closestIndex = 0;
+        let closestIndex = null;
         let closestDistance = Number.POSITIVE_INFINITY;
         this.values.forEach((thumbValue, index) => {
+            if (this.isThumbLocked(index))
+                return;
             const distance = Math.abs(thumbValue - value);
             if (distance < closestDistance) {
                 closestIndex = index;
@@ -249,20 +342,54 @@ export class SliderState extends createBindableStateClass() {
         });
         return closestIndex;
     }
+    /**
+     * Moves a thumb toward `nextValue`, the way the collision behavior allows, and returns the
+     * index the thumb ends at. The index changes only when thumbs swap places.
+     */
     setThumbValue(index, nextValue) {
+        if (this.readOnly || this.isThumbDisabled(index))
+            return index;
+        const bounds = this.getThumbBounds(index);
+        if (bounds.min > bounds.max)
+            return index;
+        const gap = this.minDistance;
+        const target = Math.min(bounds.max, Math.max(bounds.min, nextValue));
         const nextValues = [...this.values];
-        const previousValue = nextValues[index - 1] ?? this.minValue - this.minDistance;
-        const nextThumbValue = nextValues[index + 1] ?? this.maxValue + this.minDistance;
-        const constrainedValue = Math.min(nextThumbValue - this.minDistance, Math.max(previousValue + this.minDistance, nextValue));
-        nextValues[index] = this.normalize(constrainedValue);
-        this.setValues(nextValues);
+        if (this.collisionBehavior === 'swap') {
+            // The thumb is re-inserted among the others where its new value falls, keeping the
+            // minimum distance on both sides. A tie stays where the thumb is.
+            const others = nextValues.filter((_, other) => other !== index);
+            const before = others.filter((other) => other < target).length;
+            const upTo = others.filter((other) => other <= target).length;
+            const position = Math.min(upTo, Math.max(before, index));
+            const lower = position > 0 ? others[position - 1] + gap : this.minValue;
+            const upper = position < others.length ? others[position] - gap : this.maxValue;
+            if (lower > upper)
+                return index;
+            others.splice(position, 0, this.normalize(Math.min(upper, Math.max(lower, target))));
+            if (others.every((value, other) => value === this.values[other]))
+                return index;
+            this.setValues(others);
+            return position;
+        }
+        nextValues[index] = this.normalize(target);
+        if (this.collisionBehavior === 'push') {
+            for (let other = index + 1; other < nextValues.length; other += 1) {
+                nextValues[other] = Math.max(nextValues[other], nextValues[other - 1] + gap);
+            }
+            for (let other = index - 1; other >= 0; other -= 1) {
+                nextValues[other] = Math.min(nextValues[other], nextValues[other + 1] - gap);
+            }
+        }
+        this.setValues(nextValues.map((value) => this.normalize(value)));
+        return index;
     }
     setValues(nextValues) {
         const constrainedValues = this.constrainValues(nextValues);
         if (constrainedValues.length === this.values.length &&
             constrainedValues.every((value, index) => value === this.values[index]))
             return;
-        if (this.thumbCount === 1) {
+        if (!this.isArrayValue) {
             this.value = constrainedValues[0] ?? this.minValue;
             return;
         }
@@ -270,17 +397,21 @@ export class SliderState extends createBindableStateClass() {
     }
     startTrackDrag(pointerValue) {
         const index = this.getClosestThumbIndex(pointerValue);
-        this.setThumbValue(index, pointerValue);
-        this.startThumbDrag(index);
-        return index;
+        if (index === null)
+            return null;
+        this.beginDrag();
+        const thumb = this.setThumbValue(index, pointerValue);
+        this.enterThumbDrag(thumb);
+        return thumb;
     }
     startThumbDrag(index) {
-        this.activeThumb = index;
-        this.dragState = { type: 'thumb', index };
+        this.beginDrag();
+        this.enterThumbDrag(index);
     }
     startRangeDrag(pointerValue) {
         if (this.values.length <= 1)
             return false;
+        this.beginDrag();
         this.dragState = {
             type: 'range',
             pointerValue,
@@ -288,6 +419,13 @@ export class SliderState extends createBindableStateClass() {
         };
         return true;
     }
+    beginDrag() {
+        this.dragFrom = [...this.values];
+    }
+    enterThumbDrag(index) {
+        this.activeThumb = index;
+        this.dragState = { type: 'thumb', index };
+    }
     moveRange(delta) {
         if (this.values.length <= 1)
             return;
@@ -308,16 +446,46 @@ export class SliderState extends createBindableStateClass() {
             this.moveRange(pointerValue - this.dragState.pointerValue);
             return true;
         }
-        this.setThumbValue(this.dragState.index, pointerValue);
+        const index = this.dragState.index;
+        const thumb = this.setThumbValue(index, pointerValue);
+        if (thumb !== index) {
+            // The thumbs swapped places: the drag, the focus and the highlight follow the one moving.
+            this.enterThumbDrag(thumb);
+            this.focusThumbNode(thumb);
+        }
         return true;
     }
+    /** Ends the drag, release or cancel alike, and commits the value if the drag changed it. */
     endDrag() {
         this.dragState = null;
+        const from = this.dragFrom;
+        this.dragFrom = null;
+        if (from)
+            this.commit(from);
+    }
+    /** Drops the drag without a commit: the slider went away mid-drag. */
+    cancelDrag() {
+        this.dragState = null;
+        this.dragFrom = null;
+    }
+    /** Reports the settled value, unless the interaction ended where it began. */
+    commit(from) {
+        const values = this.values;
+        if (from.length === values.length && from.every((value, index) => value === values[index])) {
+            return;
+        }
+        this.onValueCommit?.(this.isArrayValue ? [...values] : (values[0] ?? this.minValue));
+    }
+    flushInputCommit() {
+        const from = this.inputFrom;
+        this.inputFrom = null;
+        if (from)
+            this.commit(from);
     }
     getDirection = useDirection(() => this.trackNode);
     applyThumbKey(index, key, shiftKey) {
         const currentValue = this.values[index] ?? this.minValue;
-        const stepSize = shiftKey ? this.stepValue * 10 : this.stepValue;
+        const stepSize = shiftKey ? this.largeStepSize : this.stepValue;
         let nextValue;
         // Horizontal arrows follow the writing direction: in RTL, ArrowRight decreases.
         const rtl = this.orientationValue !== 'vertical' && this.getDirection() === 'rtl';
@@ -330,10 +498,10 @@ export class SliderState extends createBindableStateClass() {
             nextValue = currentValue - stepSize;
         }
         else if (key === 'PageUp') {
-            nextValue = currentValue + this.stepValue * 10;
+            nextValue = currentValue + this.largeStepSize;
         }
         else if (key === 'PageDown') {
-            nextValue = currentValue - this.stepValue * 10;
+            nextValue = currentValue - this.largeStepSize;
         }
         else if (key === 'Home') {
             nextValue = this.minValue;
@@ -344,8 +512,10 @@ export class SliderState extends createBindableStateClass() {
         else {
             return false;
         }
-        this.activeThumb = index;
-        this.setThumbValue(index, nextValue);
+        const thumb = this.setThumbValue(index, nextValue);
+        this.activeThumb = thumb;
+        if (thumb !== index)
+            this.focusThumbNode(thumb);
         return true;
     }
     validate(value, onValidate) {
@@ -358,6 +528,21 @@ export class SliderState extends createBindableStateClass() {
     isDisabled() {
         return !!this.disabled;
     }
+    /** Whether this thumb alone is disabled (not the whole slider). */
+    isThumbLocked(index) {
+        return !!this.thumbDisabled?.[index];
+    }
+    /** Whether this thumb cannot be moved: the slider or the thumb itself is disabled. */
+    isThumbDisabled(index) {
+        return this.isDisabled() || this.isThumbLocked(index);
+    }
+    /** A press on a disabled thumb does nothing, instead of falling through to the track. */
+    swallowLockedPress(node, index) {
+        return on(node, 'pointerdown', (event) => {
+            if (this.isThumbLocked(index))
+                event.stopPropagation();
+        });
+    }
     getPointerValue(event) {
         if (!this.trackNode)
             return null;
@@ -369,7 +554,8 @@ export class SliderState extends createBindableStateClass() {
             const offset = rect.bottom - event.clientY;
             return this.getValueFromPercentage((offset / size) * 100);
         }
-        const offset = event.clientX - rect.left;
+        // The track mirrors in RTL (thumbs sit at inset-inline-start), so the minimum is the right edge.
+        const offset = this.getDirection() === 'rtl' ? rect.right - event.clientX : event.clientX - rect.left;
         return this.getValueFromPercentage((offset / size) * 100);
     }
     focusThumbNode(index) {
@@ -385,18 +571,17 @@ export class SliderState extends createBindableStateClass() {
         const pointerValue = this.getPointerValue(payload.event);
         if (pointerValue === null)
             return false;
-        this.focusThumbNode(this.startTrackDrag(pointerValue));
-    }
-    startThumbPointerDrag(index, node) {
-        node.focus();
-        this.startThumbDrag(index);
+        const index = this.startTrackDrag(pointerValue);
+        if (index === null)
+            return false;
+        this.focusThumbNode(index);
     }
     startThumbHitboxPointerDrag(index) {
         this.focusThumbNode(index);
         this.startThumbDrag(index);
     }
     startRangePointerDrag(payload) {
-        if (!this.dragRange || !this.isRange)
+        if (!this.canDragRange)
             return false;
         const pointerValue = this.getPointerValue(payload.event);
         if (pointerValue === null)
@@ -420,19 +605,58 @@ export class SliderState extends createBindableStateClass() {
         this.updateDrag(pointerValue);
     }
     onThumbKeyDown(event, index) {
-        if (this.isDisabled())
+        if (this.isThumbDisabled(index))
             return;
-        if (this.applyThumbKey(index, event.key, event.shiftKey)) {
-            event.preventDefault();
+        const from = [...this.values];
+        if (!this.applyThumbKey(index, event.key, event.shiftKey))
+            return;
+        event.preventDefault();
+        // Each accepted key is its own interaction; a key during a drag belongs to the drag.
+        if (!this.dragState)
+            this.commit(from);
+    }
+    /**
+     * Assistive technology adjusts the range input directly (a VoiceOver swipe, a TalkBack
+     * gesture) and sends no key events. The input's value is read as a request: the accepted
+     * value is written back, so a refused one (read-only, a blocked thumb) leaves the input
+     * showing what the slider holds.
+     */
+    onThumbInput(index) {
+        const input = this.thumbNodes.get(index);
+        if (!input)
+            return;
+        const requested = Number(input.value);
+        let thumb = index;
+        if (Number.isFinite(requested) && !this.isThumbDisabled(index)) {
+            this.inputFrom ??= [...this.values];
+            thumb = this.setThumbValue(index, requested);
+        }
+        for (const [other, node] of this.thumbNodes) {
+            const accepted = `${this.values[other] ?? this.minValue}`;
+            if (node.value !== accepted)
+                node.value = accepted;
         }
+        if (thumb !== index)
+            this.focusThumbNode(thumb);
     }
     onThumbBlur = (event) => {
+        // An adjustment whose `change` never came ends with the focus leaving.
+        this.flushInputCommit();
         const relatedTarget = event.relatedTarget;
-        if (relatedTarget instanceof Node && this.trackNode?.contains(relatedTarget))
+        if (relatedTarget instanceof Node && this.isInsideTrack(relatedTarget))
             return;
         this.focused = false;
         this.activeThumb = null;
     };
+    /** Containment that also holds when the slider sits in a shadow root. */
+    isInsideTrack(node) {
+        for (let current = node; current;) {
+            if (current === this.trackNode)
+                return true;
+            current = current.parentNode ?? (current instanceof ShadowRoot ? current.host : null);
+        }
+        return false;
+    }
     onDocumentPointerDown(event) {
         if (event.button !== 0 || this.dragState || this.isDisabled() || !this.trackNode)
             return;
@@ -453,7 +677,7 @@ export class SliderState extends createBindableStateClass() {
         const hitboxes = this.trackNode.querySelectorAll('[data-slider-thumb-hitbox]');
         for (const [index, hitbox] of hitboxes.entries()) {
             const rect = hitbox.getBoundingClientRect();
-            if (rect.width <= 0 || rect.height <= 0)
+            if (rect.width <= 0 || rect.height <= 0 || this.isThumbLocked(index))
                 continue;
             const isInside = event.clientX >= rect.left &&
                 event.clientX <= rect.right &&