entasis 0.11.0 → 0.12.0

package/dist/components/Form/Slider/slider.mcp.js

@@ -1,7 +1,7 @@
 export const sliderDescription = `
 # Slider Component
 
-The Slider component is a Field-based numeric control for scalar values, range tuples, vertical layouts, multi-thumb values, and draggable selected ranges. It renders ARIA slider thumbs instead of relying on a native range input so every mode shares the same state machine and theme parts.
+The Slider component is a Field-based numeric control for scalar values, range tuples, vertical layouts, multi-thumb values, and draggable selected ranges. Each thumb is a visually hidden native \`<input type="range">\` inside a styled thumb, so every mode shares one state machine and theme parts while mobile screen readers can adjust the value with their own gestures (VoiceOver swipe up and down, TalkBack adjust), which send no key events.
 
 ## Basic Usage
 
@@ -39,15 +39,18 @@ The Slider component is a Field-based numeric control for scalar values, range t
 Extends all Field props plus:
 
 ### Core Props
-- **value**: number | number[] | null (bindable) - Current scalar or multi-thumb value
+- **value**: number | number[] | null (bindable) - Current scalar or multi-thumb value; an array keeps its array shape, even with one element (\`[25]\` stays \`[26]\` after ArrowRight, never \`26\`)
 - **mode**: 'single' | 'range' (default: 'single') - Range mode defaults to two thumbs
 - **variant**: 'default' | 'thick' | 'contained' (default: 'default') - Visual track style; \`thick\` renders a heavier track with an inset pill thumb, while \`contained\` places the label and optional value inside an input-like rail
 - **thumbs**: number - Number of thumbs when the value is missing or scalar
 - **min**: number (default: 0) - Minimum selectable value
 - **max**: number (default: 100) - Maximum selectable value
 - **step**: number (default: 1) - Pointer and keyboard increment
+- **largeStep**: number (default: 10 × step) - Amount PageUp, PageDown and Shift+Arrow change the value by. The result still snaps to \`step\`
 - **minStepsBetweenThumbs**: number (default: 0) - Minimum spacing between neighboring thumbs, in step units
 - **orientation**: 'horizontal' | 'vertical' (default: 'horizontal') - Track direction
+- **thumbCollisionBehavior**: 'none' | 'push' | 'swap' (default: 'none') - What a thumb does when it meets a neighbour. \`none\` stops it at the neighbour (and at \`minStepsBetweenThumbs\`), \`push\` moves the neighbours along while there is room, \`swap\` lets it pass: the thumbs trade places, and focus and the drag follow the moving thumb. Each thumb's \`aria-valuemin\`/\`aria-valuemax\` follow the mode
+- **thumbDisabled**: boolean[] - Disables thumbs by index. A disabled thumb keeps its value (and its place in the submitted value) but cannot be focused or moved, and it blocks the thumbs next to it in every collision mode. Track presses move the closest free thumb, and dragging the selected range is off while any thumb is disabled
 - **dragRange**: boolean (default: false) - Allows dragging the selected range segment as a unit
 - **color**: semantic color (default: 'primary') - Filled track and thumb color
 
@@ -66,7 +69,9 @@ Extends all Field props plus:
 - **size**: 'small' | 'normal' | 'large' - Control size
 - **errors**: string[] | boolean (bindable) - Validation errors
 - **focused**: boolean (bindable) - Focus state
-- **onValueChange**: (value: number | number[]) => void - Called when value changes
+- **readOnly**: boolean - Refuses every edit (pointer, keys and assistive technology) while thumbs stay focusable, announced with \`aria-readonly\`, and the value is still submitted. The track and thumbs carry \`data-readonly\`
+- **onValueChange**: (value: number | number[]) => void - Called when value changes, on every pointer move
+- **onValueCommit**: (value: number | number[]) => void - Called when an interaction ends with a value that differs from the one it started with: on pointer release, on pointer cancel, after each accepted key press, and when assistive technology finishes an adjustment. Never called for a no-op. Use it to save on release
 - **onValidate**: (value: number | number[]) => string[] | boolean - Custom validation
 
 ### Slots
@@ -81,7 +86,7 @@ Extends all Field props plus:
 
 ## Form Integration
 
-Use \`type: 'slider'\` for scalar values and \`type: 'slider-range'\` for submitted number arrays.
+Use \`type: 'slider'\` for scalar values and \`type: 'slider-range'\` for submitted number arrays. A \`slider-range\` holds one or more values, so a one-thumb array value such as \`[25]\` is submitted as \`[25]\`.
 
 \`\`\`svelte
 <Form
@@ -116,12 +121,14 @@ Use \`type: 'slider'\` for scalar values and \`type: 'slider-range'\` for submit
 	<InputContainer>
 		<Prefix />
 		<SliderRoot>
-			<HiddenInput />
 			<Track role="group">
 				<ScreenReaderInstructions />
 				<TrackBackground />
 				<SelectedRange />
-				<Thumb role="slider" />
+				<Thumb>
+					<input type="range" />
+					<ThumbVisual />
+				</Thumb>
 				<Marks />
 			</Track>
 			<ValueLabels />
@@ -192,6 +199,39 @@ Use \`type: 'slider'\` for scalar values and \`type: 'slider-range'\` for submit
 />
 \`\`\`
 
+### Save On Release
+\`\`\`svelte
+<Slider
+	label="Volume"
+	bind:value={volume}
+	onValueCommit={(value) => saveVolume(value)}
+/>
+\`\`\`
+
+### Thumb Collisions
+\`\`\`svelte
+<!-- push: a thumb moves its neighbours along -->
+<Slider label="Split" bind:value={split} thumbs={3} thumbCollisionBehavior="push" />
+
+<!-- swap: a thumb passes its neighbour and the two trade places -->
+<Slider mode="range" label="Window" bind:value={window} thumbCollisionBehavior="swap" />
+\`\`\`
+
+### Disabled Thumb
+\`\`\`svelte
+<Slider
+	mode="range"
+	label="Budget"
+	bind:value={budget}
+	thumbDisabled={[true, false]}
+/>
+\`\`\`
+
+### Read Only
+\`\`\`svelte
+<Slider label="Level" value={72} readOnly />
+\`\`\`
+
 ### Custom Range Label
 \`\`\`svelte
 <Slider mode="range" bind:value={range} showValue>
@@ -203,15 +243,18 @@ Use \`type: 'slider'\` for scalar values and \`type: 'slider-range'\` for submit
 
 ## Accessibility
 
-- Each thumb is a button with \`role="slider"\`
+- Each thumb contains a visually hidden \`<input type="range">\` (role slider), the one focus target. Clicking the Field label focuses the first thumb. The input also submits the value natively under the field name, once per thumb; a slider without a name submits nothing, and a disabled slider is left out
+- Mobile screen-reader adjust gestures change the input directly: the slider reads the new value from its \`input\` event and reports one commit on \`change\`
 - Single-thumb sliders use the visible Field label when present; multi-thumb sliders add per-thumb labels such as "Budget minimum" and "Budget maximum"
-- The track is exposed as a labelled group when the label is plain text, with hidden keyboard instructions referenced by \`aria-describedby\`
+- The track is exposed as a group named by the rendered label (\`aria-labelledby\`), whether the label is text or a snippet, with hidden keyboard instructions referenced by \`aria-describedby\`
 - Thumb values expose \`aria-valuemin\`, \`aria-valuemax\`, \`aria-valuenow\`, \`aria-valuetext\`, and \`aria-orientation\`
 - Multi-thumb \`aria-valuemin\`/\`aria-valuemax\` reflect each thumb's current movement bounds, including minimum thumb spacing
-- Keyboard support: Arrow keys move by one step, Shift+Arrow and PageUp/PageDown move by ten steps, Home/End jump to bounds
+- Keyboard support: Arrow keys move by one step, Shift+Arrow and PageUp/PageDown move by \`largeStep\` (ten steps by default), Home/End jump to bounds. Each accepted key press is one \`onValueCommit\`
+- Read-only sliders expose \`aria-readonly\` on every thumb and refuse edits from every source
 - ArrowLeft / ArrowRight follow the writing direction: in RTL, ArrowLeft increases and ArrowRight decreases (vertical sliders are unaffected)
+- In RTL a horizontal track mirrors to match: the minimum sits at the right edge, thumbs, the filled range, marks and contained ticks are placed from the inline start, and a pointer press reads its value from the right edge. An I18n direction that the document does not carry is applied to the whole slider field (label, description, errors and track) through a \`dir\` attribute on the field root, and it takes precedence over a \`dir\` in \`fieldAttrs\`, as it does for the arrow keys and pointer. The slider follows its nearest direction, so an ltr slider inside an rtl page stays ltr; set the direction with I18n or a \`dir\` attribute rather than CSS \`direction\` alone
 - Multi-thumb sliders enforce ordering and optional minimum thumb spacing
-- Disabled state blocks pointer, keyboard, and selected-range dragging
+- Disabled state blocks pointer, keyboard, and selected-range dragging; a disabled thumb leaves the tab order
 
 ## Theme Customization
 
@@ -222,7 +265,7 @@ Theme parts:
 - **track**: Pointer surface and color carrier
 - **trackBackground**: Unselected track
 - **range**: Selected range segment
-- **thumb**: Individual slider thumb button
+- **thumb**: Individual slider thumb wrapper; it holds the hidden range input, and the focus ring is drawn on the visual through \`group-has-[:focus-visible]\`
 - **thumbHitbox**: Invisible thick-variant thumb pointer target
 - **thumbVisual**: Visible thumb shape
 - **valueLabels**: Value chip group
@@ -240,5 +283,6 @@ Theme parts:
 - **value**: current bindable editable value.
 - **defaultValue**: initial value used only when \`value\` is omitted.
 - **onValueChange**: called with the new value when the component changes it.
+- **onValueCommit**: called with the settled value when an interaction ends with a different value.
 
 `;

package/dist/components/Form/Slider/slider.props.d.ts

@@ -14,8 +14,21 @@ export type SliderMark = {
 export type SliderRangeLabelPayload = SliderRangePayload;
 export type SliderMode = 'single' | 'range';
 export type SliderVariant = 'default' | 'thick' | 'contained';
+/**
+ * What a thumb does when it meets a neighbour.
+ *
+ * - `none`: stops against the neighbour (and `minStepsBetweenThumbs`).
+ * - `push`: moves the neighbour along, as long as there is room.
+ * - `swap`: passes through; the thumbs trade places and focus follows the moving one.
+ *
+ * A disabled thumb never moves, and no other thumb passes or pushes it.
+ */
+export type SliderThumbCollisionBehavior = 'none' | 'push' | 'swap';
 export type SliderProps = Omit<InputProps<'slider'>, 'value' | 'defaultValue' | 'onValueChange' | 'onValidate'> & {
-    /** The field's value, bindable with `bind:value`; arrays render multiple thumbs. */
+    /**
+     * The field's value, bindable with `bind:value`. An array renders one thumb per entry and keeps
+     * its array shape, even with a single entry: `[25]` becomes `[26]`, never `26`.
+     */
     value?: number | number[] | null;
     /** Initial field value when `value` is omitted. */
     defaultValue?: number | number[] | null;
@@ -25,6 +38,11 @@ export type SliderProps = Omit<InputProps<'slider'>, 'value' | 'defaultValue' |
     max?: number;
     /** Value increment used by pointer and keyboard changes. */
     step?: number;
+    /**
+     * Amount PageUp, PageDown and Shift+Arrow change the value by; the result still snaps to
+     * `step`. Defaults to ten times `step`.
+     */
+    largeStep?: number;
     /** Rendering mode; range defaults to two thumbs and range Form semantics. */
     mode?: SliderMode;
     /** Visual track style; contained places the label and optional value inside an input-like rail. */
@@ -35,6 +53,14 @@ export type SliderProps = Omit<InputProps<'slider'>, 'value' | 'defaultValue' |
     orientation?: 'horizontal' | 'vertical';
     /** Minimum distance between neighboring thumbs, expressed in step units. */
     minStepsBetweenThumbs?: number;
+    /** What a thumb does when it meets a neighbour. @default 'none' */
+    thumbCollisionBehavior?: SliderThumbCollisionBehavior;
+    /**
+     * Disables individual thumbs by index. A disabled thumb keeps its value (and its place in the
+     * submitted value) but cannot be focused or moved, and it blocks the thumbs next to it. Range
+     * dragging is off while any thumb is disabled.
+     */
+    thumbDisabled?: boolean[];
     /** Allows dragging the filled range segment when multiple thumbs are rendered. */
     dragRange?: boolean;
     /** Semantic color used for the filled track and thumb. */
@@ -53,8 +79,15 @@ export type SliderProps = Omit<InputProps<'slider'>, 'value' | 'defaultValue' |
     thumbLabels?: string[];
     /** Per-instance i18n overrides, merged over the global catalog. */
     i18n?: Partial<Messages>;
-    /** Called whenever the field value changes. */
+    /** Called whenever the field value changes, with the same scalar or array shape as `value`. */
     onValueChange?: (value: number | number[] | null) => void;
+    /**
+     * Called when an interaction ends with a value that differs from the one it started with: on
+     * pointer release, on pointer cancel, after each accepted key press, and when assistive
+     * technology finishes an adjustment. It never fires for a no-op. The value has the same scalar
+     * or array shape as `value`. Use it to save on release instead of on every move.
+     */
+    onValueCommit?: (value: number | number[]) => void;
     /** Validates the current value, returning error messages (or false) when invalid. */
     onValidate?: (value: number | number[]) => string[] | boolean;
     /** Theme overrides for slider parts and inherited Field parts. */

package/dist/components/Form/Slider/slider.state.svelte.d.ts

@@ -1,5 +1,6 @@
 import type { Attachment } from 'svelte/attachments';
 import type { FieldValue } from '../Field/field.js';
+import type { SliderThumbCollisionBehavior } from './slider.props.js';
 export type SliderValue = number | number[];
 export type SliderOrientation = 'horizontal' | 'vertical';
 export type SliderFormatValue = (value: number, index: number, values: number[]) => string;
@@ -34,16 +35,23 @@ type SliderDragState = {
 };
 type SliderStateOptions = {
     value?: SliderValue | null;
+    mode?: 'single' | 'range';
     min?: number;
     max?: number;
     step?: number;
+    largeStep?: number;
     thumbs?: number;
     minStepsBetweenThumbs?: number;
+    thumbCollisionBehavior?: SliderThumbCollisionBehavior;
+    thumbDisabled?: boolean[];
     orientation?: SliderOrientation;
     formatValue?: SliderFormatValue;
     disabled?: boolean;
+    readOnly?: boolean;
     dragRange?: boolean;
     focused?: boolean;
+    /** Receives the settled value (scalar or array, like the field value) when an interaction ends. */
+    onValueCommit?: (value: SliderValue) => void;
 };
 declare const SliderState_base: new (props: SliderStateOptions) => {} & SliderStateOptions;
 export declare class SliderState extends SliderState_base {
@@ -55,8 +63,12 @@ export declare class SliderState extends SliderState_base {
     private trackNode;
     private thumbNodes;
     private thumbAttachments;
+    private thumbInputAttachments;
     private thumbHitboxAttachments;
     private documentHitboxDragCleanup;
+    private dragFrom;
+    private inputFrom;
+    private arrayFieldValue;
     private trackDrag;
     private rangeDrag;
     minValue: number;
@@ -65,9 +77,23 @@ export declare class SliderState extends SliderState_base {
     valuePrecision: number;
     thumbCount: number;
     minDistance: number;
+    /** Amount PageUp, PageDown and Shift+Arrow move a thumb by. */
+    largeStepSize: number;
+    collisionBehavior: SliderThumbCollisionBehavior;
     orientationValue: SliderOrientation;
     values: number[];
     isRange: boolean;
+    /** Whether any single thumb is disabled on its own. */
+    hasLockedThumb: boolean;
+    /** The selected range moves as a unit only when every thumb is free to move and edits are allowed. */
+    canDragRange: boolean;
+    /**
+     * 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: number;
+    /** The value keeps an array shape (even with one thumb) when it arrived as one or is a range. */
+    isArrayValue: boolean;
     fieldType: "slider-range" | "slider";
     fieldValue: SliderValue;
     startPercentage: number;
@@ -78,7 +104,10 @@ export declare class SliderState extends SliderState_base {
     constructor(options: SliderStateOptions);
     track: Attachment<HTMLElement>;
     range: Attachment<HTMLElement>;
-    thumb(index: number): Attachment<HTMLButtonElement>;
+    /** The pointer surface of a thumb: its visual wrapper, which holds the focusable range input. */
+    thumb(index: number): Attachment<HTMLElement>;
+    /** The focus target of a thumb: its visually hidden `<input type="range">`. */
+    thumbInput(index: number): Attachment<HTMLInputElement>;
     thumbHitbox(index: number): Attachment<HTMLElement>;
     getNormalizedValues(): number[];
     getRawValues(): number[];
@@ -92,6 +121,11 @@ export declare class SliderState extends SliderState_base {
     getValueFromPercentage(percentage: number): number;
     getFormattedValue(value: number, index: number, values: number[]): string;
     getValuePayload(index: number, value?: number): SliderValuePayload;
+    /**
+     * 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: number): {
         min: number;
         max: number;
@@ -111,30 +145,57 @@ export declare class SliderState extends SliderState_base {
         thumbMin: number;
         thumbMax: number;
     };
-    getClosestThumbIndex(value: number): number;
-    setThumbValue(index: number, nextValue: number): void;
+    /** The enabled thumb nearest to `value`, or null when none can move. */
+    getClosestThumbIndex(value: number): null;
+    /**
+     * 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: number, nextValue: number): number;
     setValues(nextValues: number[]): void;
-    startTrackDrag(pointerValue: number): number;
+    startTrackDrag(pointerValue: number): number | null;
     startThumbDrag(index: number): void;
     startRangeDrag(pointerValue: number): boolean;
+    private beginDrag;
+    private enterThumbDrag;
     moveRange(delta: number): void;
     updateDrag(pointerValue: number): boolean;
+    /** Ends the drag, release or cancel alike, and commits the value if the drag changed it. */
     endDrag(): void;
+    /** Drops the drag without a commit: the slider went away mid-drag. */
+    private cancelDrag;
+    /** Reports the settled value, unless the interaction ended where it began. */
+    private commit;
+    private flushInputCommit;
     private getDirection;
     applyThumbKey(index: number, key: string, shiftKey: boolean): boolean;
     validate(value: FieldValue<'slider' | 'slider-range'>, onValidate?: (value: FieldValue<'slider' | 'slider-range'>) => string[] | boolean): boolean | string[];
     private isDisabled;
+    /** Whether this thumb alone is disabled (not the whole slider). */
+    isThumbLocked(index: number): boolean;
+    /** Whether this thumb cannot be moved: the slider or the thumb itself is disabled. */
+    isThumbDisabled(index: number): boolean;
+    /** A press on a disabled thumb does nothing, instead of falling through to the track. */
+    private swallowLockedPress;
     private getPointerValue;
     private focusThumbNode;
     private focusThumb;
     private startTrackPointerDrag;
-    private startThumbPointerDrag;
     private startThumbHitboxPointerDrag;
     private startRangePointerDrag;
     private updatePointerDrag;
     private updatePointerEvent;
     private onThumbKeyDown;
+    /**
+     * 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.
+     */
+    private onThumbInput;
     private onThumbBlur;
+    /** Containment that also holds when the slider sits in a shadow root. */
+    private isInsideTrack;
     private onDocumentPointerDown;
     private getDocumentHitboxIndex;
     private startDocumentHitboxDrag;