Slider value unset

etc/lime-elements.api.md

@@ -833,11 +833,12 @@ export namespace Components {
         "helperText": string;
         "invalid": boolean;
         "label": string;
+        "language": Languages;
         "readonly": boolean;
         "required": boolean;
         "step": number;
         "unit": string;
-        "value": number;
+        "value": number | null;
         "valuemax": number;
         "valuemin": number;
     }
@@ -3401,12 +3402,13 @@ export namespace JSX {
         "helperText"?: string;
         "invalid"?: boolean;
         "label"?: string;
-        "onChange"?: (event: LimelSliderCustomEvent<number>) => void;
+        "language"?: Languages;
+        "onChange"?: (event: LimelSliderCustomEvent<number | null>) => void;
         "readonly"?: boolean;
         "required"?: boolean;
         "step"?: number;
         "unit"?: string;
-        "value"?: number;
+        "value"?: number | null;
         "valuemax"?: number;
         "valuemin"?: number;
     }
@@ -3426,6 +3428,8 @@ export namespace JSX {
         // (undocumented)
         "label": string;
         // (undocumented)
+        "language": Languages;
+        // (undocumented)
         "readonly": boolean;
         // (undocumented)
         "required": boolean;
@@ -3434,7 +3438,7 @@ export namespace JSX {
         // (undocumented)
         "unit": string;
         // (undocumented)
-        "value": number;
+        "value": number | null;
         // (undocumented)
         "valuemax": number;
         // (undocumented)

src/components/chip-set/examples/chip-set-progress.tsx

@@ -49,8 +49,9 @@ export class ChipSetProgressExample {
         );
     }
 
-    private setProgress = (event: CustomEvent<number>) => {
+    private setProgress = (event: CustomEvent<number | null>) => {
         event.stopPropagation();
-        this.progress = event.detail;
+        // The slider is clearable, so it emits `null` when unset.
+        this.progress = event.detail ?? 0;
     };
 }

src/components/chip/examples/chip-progress.tsx

@@ -60,7 +60,8 @@ export class ChipProgressExample {
         ];
     }
 
-    private handleChange = (event: CustomEvent<number>) => {
-        this.progress = event.detail;
+    private handleChange = (event: CustomEvent<number | null>) => {
+        // The slider is clearable, so it emits `null` when unset.
+        this.progress = event.detail ?? 0;
     };
 }

src/components/file/examples/file-per-file-progress.tsx

@@ -71,8 +71,9 @@ export class FilePerFileProgressExample {
         this.file = event.detail;
     };
 
-    private setProgress = (event: CustomEvent<number>) => {
+    private setProgress = (event: CustomEvent<number | null>) => {
         event.stopPropagation();
-        this.progress = event.detail;
+        // The slider is clearable, so it emits `null` when unset.
+        this.progress = event.detail ?? 0;
     };
 }

src/components/file/examples/file-per-file-status.tsx

@@ -89,8 +89,9 @@ export class FilePerFileStatusExample {
         this.statusText = event.detail;
     };
 
-    private setProgress = (event: CustomEvent<number>) => {
+    private setProgress = (event: CustomEvent<number | null>) => {
         event.stopPropagation();
-        this.progress = event.detail;
+        // The slider is clearable, so it emits `null` when unset.
+        this.progress = event.detail ?? 0;
     };
 }

src/components/file/examples/file-resize-image.tsx

@@ -124,7 +124,11 @@ export class FileResizeImageExample {
                     />
                     <limel-slider
                         label="JPEG quality"
-                        value={Math.round((this.options.quality ?? 0) * 100)}
+                        value={
+                            this.options.quality == null
+                                ? null
+                                : Math.round(this.options.quality * 100)
+                        }
                         valuemin={1}
                         valuemax={100}
                         step={1}
@@ -193,8 +197,18 @@ export class FileResizeImageExample {
         this.updateNumericOption('height', event.detail);
     };
 
-    private handleQualityChange = (event: CustomEvent<number>) => {
+    private handleQualityChange = (event: CustomEvent<number | null>) => {
         event.stopPropagation();
+
+        // A cleared slider means "not set", like the dimension fields above:
+        // omit `quality` so the browser's native encoding quality is used
+        // rather than an imposed one.
+        if (event.detail === null) {
+            this.updateOption('quality', undefined);
+
+            return;
+        }
+
         const quality = Math.max(0, Math.min(1, event.detail / 100));
         this.updateOption('quality', quality);
     };

src/components/form/widgets/slider.ts

@@ -39,7 +39,7 @@ export class Slider extends React.Component {
         });
     }
 
-    private handleChange(event: CustomEvent<number>) {
+    private handleChange(event: CustomEvent<number | null>) {
         const props = this.props;
         event.stopPropagation();
 

src/components/slider/examples/slider-basic.tsx

@@ -15,7 +15,10 @@ export class SliderBasicExample {
     private readonly = false;
 
     @State()
-    private value = 25;
+    private required = false;
+
+    @State()
+    private value: number | null = 25;
 
     private minValue = 15;
     private maxValue = 75;
@@ -30,6 +33,7 @@ export class SliderBasicExample {
                 valuemin={this.minValue}
                 disabled={this.disabled}
                 readonly={this.readonly}
+                required={this.required}
                 onChange={this.handleChange}
             />,
             <limel-example-controls>
@@ -43,12 +47,17 @@ export class SliderBasicExample {
                     label="Readonly"
                     onChange={this.setReadonly}
                 />
+                <limel-switch
+                    value={this.required}
+                    label="Required"
+                    onChange={this.setRequired}
+                />
             </limel-example-controls>,
             <limel-example-value value={this.value} />,
         ];
     }
 
-    private handleChange = (event: CustomEvent<number>) => {
+    private handleChange = (event: CustomEvent<number | null>) => {
         this.value = event.detail;
     };
 
@@ -61,4 +70,9 @@ export class SliderBasicExample {
         event.stopPropagation();
         this.readonly = event.detail;
     };
+
+    private readonly setRequired = (event: CustomEvent<boolean>) => {
+        event.stopPropagation();
+        this.required = event.detail;
+    };
 }

src/components/slider/examples/slider-unset.tsx

@@ -0,0 +1,50 @@
+import { Component, h, Host, State } from '@stencil/core';
+
+/**
+ * Unsetting the value
+ *
+ * This slider is initialized *unset*, which means its `value` is `null`.
+ * Therefore the thumb rests in the middle, and the value indicator shows a
+ * left-right arrow (`↔`) instead of a number.
+ * Assistive technologies announce the value as "Value not set".
+ *
+ * As soon as the user drags the thumb, presses anywhere on the track, or
+ * nudges the thumb with the arrow keys, the slider becomes set and the
+ * trailing **clear** button becomes active.
+ * Pressing it unsets the slider again, emitting `null` on the `change`
+ * event — so a handler must accept `number | null`.
+ *
+ * A `required` slider does not offer the clear button — a required value
+ * cannot be unset — but it can still start unset to prompt a first choice.
+ *
+ * To unset the slider programmatically, set its `value` to `null`. Any other
+ * value that is not a finite number — `undefined`, or `NaN` — works too.
+ */
+@Component({
+    tag: 'limel-example-slider-unset',
+    shadow: true,
+})
+export class SliderUnsetExample {
+    @State()
+    private value: number | null = null;
+
+    public render() {
+        return (
+            <Host>
+                <limel-slider
+                    label="Priority"
+                    value={this.value}
+                    valuemin={1}
+                    valuemax={5}
+                    step={1}
+                    onChange={this.handleChange}
+                />
+                <limel-example-value value={this.value} />
+            </Host>
+        );
+    }
+
+    private readonly handleChange = (event: CustomEvent<number | null>) => {
+        this.value = event.detail;
+    };
+}

src/components/slider/partial-styles/_thumb.scss

@@ -86,8 +86,10 @@
     border-radius: 1.25rem;
     padding: 0 0.375rem;
     height: 1.25rem;
+    min-width: 1.25rem;
     display: flex;
     align-items: center;
+    justify-content: center;
     white-space: nowrap;
 
     color: rgb(var(--color-white));

src/components/slider/slider.scss

@@ -4,6 +4,10 @@
 @forward './partial-styles/thumb';
 @use '../../style/internal/shared_input-select-picker';
 
+$size-of-clear-value-button: 1rem;
+$gap-of-clear-value-button: 0.25rem;
+$color-of-track: rgba(var(--contrast-700), 0.6);
+
 *,
 *:before,
 *:after {
@@ -84,7 +88,7 @@ input[type='range'] {
     transform: translateY(-50%);
     height: 0.5rem;
     border-radius: 1rem;
-    background-color: rgba(var(--contrast-700), 0.6);
+    background-color: $color-of-track;
 
     &:before,
     &:after {
@@ -99,7 +103,7 @@ input[type='range'] {
         width: 0.375rem;
         height: 0.375rem;
         border-radius: 50%;
-        background-color: rgba(var(--contrast-700), 0.6);
+        background-color: $color-of-track;
     }
 
     &:before {
@@ -156,4 +160,83 @@ input[type='range'] {
     }
 }
 
+:host(.has-clear-button) {
+    div[slot='content'] {
+        padding-right: calc(
+            #{$size-of-clear-value-button} + #{$gap-of-clear-value-button}
+        );
+    }
+}
+
+:host(.is-unset) {
+    // When the slider is unset, the thumb is centered and the track shows no
+    // fill, so it doesn't read as a real selection (the left-right arrow
+    // indicator — see the TSX — replaces the number). The native input's value
+    // still rests at the step-aligned midpoint (see `getRestingDisplayValue`)
+    // so both arrow-key directions are live; the thumb is centered here with
+    // `left: 50%` because a midpoint that isn't a whole step (e.g. a 4-stop
+    // range) would otherwise sit slightly off-center.
+    .track .active {
+        width: 0;
+    }
+
+    .thumb {
+        left: 50%;
+    }
+}
+
+button.clear-button {
+    @include mixins.reset-button-user-agent-styles;
+    @include mixins.visualize-keyboard-focus;
+
+    &:not([disabled]) {
+        @include mixins.is-flat-clickable(
+            $color: rgb(var(--contrast-1100)),
+            $color--hovered: rgb(var(--contrast-100)),
+            $background-color: $color-of-track,
+            $background-color--hovered: rgb(var(--contrast-1000))
+        );
+
+        &:focus-visible {
+            background-color: rgb(var(--contrast-1000));
+        }
+    }
+
+    position: absolute;
+    // Since helper text can change the height of the component
+    // we need to be specific about `inset` `top`
+    inset: 0.75rem 0 0 auto;
+
+    display: flex;
+    align-items: center;
+    justify-content: center;
+
+    height: $size-of-clear-value-button;
+    width: $size-of-clear-value-button;
+    border-radius: 50%;
+
+    svg {
+        width: calc(#{$size-of-clear-value-button} - 0.25rem);
+        height: calc(#{$size-of-clear-value-button} - 0.25rem);
+        fill: currentColor;
+    }
+
+    &:before {
+        content: '';
+        position: absolute;
+        inset: 0 auto 0 0;
+        margin: auto;
+        height: 0.125rem;
+        width: $gap-of-clear-value-button;
+        background-color: $color-of-track;
+        transform: translate(-100%, 0);
+    }
+
+    &[disabled] {
+        color: rgb(var(--contrast-1000));
+        background-color: rgb(var(--contrast-600));
+        cursor: not-allowed;
+    }
+}
+
 @include mixins.hide-helper-line-when-not-needed(limel-slider);