@zywave/zui-slider 4.3.2 → 4.4.0-pre.0

package/src/zui-slider.ts

@@ -1,10 +1,12 @@
 import { ZuiFormAssociatedElement } from '@zywave/zui-base';
-import { html } from 'lit';
+import { html, nothing, TemplateResult } from 'lit';
 import { property } from 'lit/decorators.js';
+import { classMap } from 'lit/directives/class-map.js';
+import { live } from 'lit/directives/live.js';
 import { styleMap } from 'lit/directives/style-map.js';
 import { style } from './zui-slider-css.js';
 
-const DEFAULT_MAX = 100;
+type ThumbFlag = 'thumb' | 'startThumb' | 'endThumb';
 
 /**
  * A range form control for choosing values along a slider.
@@ -14,47 +16,235 @@ const DEFAULT_MAX = 100;
  * @attr {boolean} [disabled=false] - Represents whether a user can make changes to this element; if true, the value of this element will be excluded from the form submission
  * @attr {boolean} [readonly=false] - Represents whether a user can make changes to this element; the value of this element will still be included in the form submission
  * @attr {boolean} [autofocus=false] - If true, this element will be focused when connected to the document
- * @attr {number} [value=50] - Represents the value of the input. Can be set to a default value, and will reflect the value provided by the user when interactive with the control
+ * @attr {number} [value=50] - Represents the value of the input (single mode). Can be set to a default value, and will reflect the value provided by the user when interactive with the control
+ * @attr {boolean} [range=false] - Enables range mode with two thumbs for selecting a range
+ * @attr {number} [value-start=0] - Represents the start (lower) value in range mode
+ * @attr {number} [value-end=100] - Represents the end (upper) value in range mode
+ * @attr {number} [min=0] - Represents the minimum permitted value
+ * @attr {number} [max=100] - Represents the maximum permitted value
+ * @attr {number} [step=0] - Represents the stepping interval; 0 means any value is allowed
+ * @attr {boolean} [show-min-max=false] - Shows the min and max values beneath the slider
  *
  * @prop {string | null} [name=null] - The name of this element that is associated with form submission
  * @prop {boolean} [disabled=false] - Represents whether a user can make changes to this element; if true, the value of this element will be excluded from the form submission
  * @prop {boolean} [readOnly=false] - Represents whether a user can make changes to this element; the value of this element will still be included in the form submission
  * @prop {boolean} [autofocus=false] - If true, this element will be focused when connected to the document
- * @prop {number} [valueAsNumber=50] - Returns the value of the element, interpreted as one of the following, in order: A number, NaN if conversion is impossible
- * @prop {string} [value='50'] - Represents the value of the input. Can be set to a default value, and will reflect the value provided by the user when interactive with the control
- * @prop {number} [progress=50] - Determines visual placement of the slider thumb along the line
+ * @prop {number} [valueAsNumber=50] - Returns the value as a number. Invalid or non-numeric values are clamped to min; empty string (representing an in-progress edit) returns NaN
+ * @prop {string} [value='50'] - Represents the value of the input (single mode). Can be set to a default value, and will reflect the value provided by the user when interactive with the control
+ * @prop {number} [progress=50] - Determines visual placement of the slider thumb along the line (single mode)
+ * @prop {boolean} [range=false] - Enables range mode with two thumbs for selecting a range
+ * @prop {string} [valueStart='0'] - Represents the start (lower) value in range mode
+ * @prop {string} [valueEnd='100'] - Represents the end (upper) value in range mode
+ * @prop {number} [progressStart=0] - Determines visual placement of the start thumb in range mode
+ * @prop {number} [progressEnd=100] - Determines visual placement of the end thumb in range mode
+ * @prop {number} [min=0] - Represents the minimum permitted value
+ * @prop {number} [max=100] - Represents the maximum permitted value
+ * @prop {number} [step=0] - Represents the stepping interval; 0 means any value is allowed
+ * @prop {boolean} [showMinMax=false] - Shows the min and max values beneath the slider
  *
- * @cssprop [--zui-slider-thumb-size=1.875rem (30px)] - Point of contact to grab and slide to change value
+ * @cssprop [--zui-slider-thumb-size=0.875rem (14px)] - Controls the visual dot size and thumb hit-area (hit area is 3× this value)
+ * @cssprop [--zui-slider-input-width=7ch] - Width of the floating value input above each thumb
  *
- * @event {CustomEvent} change - Fires when value changes, details contain `value`
+ * @event {CustomEvent} change - Fires when value changes; in single mode detail is the value string; in range mode detail is { valueStart, valueEnd }
  */
 export class ZuiSlider extends ZuiFormAssociatedElement {
+  #defaultValue: string = '50';
+  #defaultValueStart: string = '0';
+  #defaultValueEnd: string = '100';
+
+  #value: string = '50';
+  #valueStart: string = '0';
+  #valueEnd: string = '100';
+
+  #thumbInputState = new Map<
+    ThumbFlag,
+    {
+      visible: boolean;
+      focused: boolean;
+      timer?: ReturnType<typeof setTimeout>;
+      debounceTimer?: ReturnType<typeof setTimeout>;
+    }
+  >([
+    ['thumb', { visible: false, focused: false }],
+    ['startThumb', { visible: false, focused: false }],
+    ['endThumb', { visible: false, focused: false }],
+  ]);
+
+  // Pre-bound floating input handlers cached to avoid new function references on every render
+  #onThumbFloatingInput = this.#onFloatingInput('thumb', (v) => (this.value = v));
+  #onStartThumbFloatingInput = this.#onFloatingInput('startThumb', (v) => (this.valueStart = v));
+  #onEndThumbFloatingInput = this.#onFloatingInput('endThumb', (v) => (this.valueEnd = v));
+
+  // Cached floating input change handlers — flush debounce and dispatch immediately on commit (Enter/blur)
+  #onThumbFloatingChange = this.#makeFloatingChange(
+    'thumb',
+    (v) => (this.value = v),
+    () => this.#onChange()
+  );
+  #onStartThumbFloatingChange = this.#makeFloatingChange(
+    'startThumb',
+    (v) => (this.valueStart = v),
+    () => this.#onRangeChange()
+  );
+  #onEndThumbFloatingChange = this.#makeFloatingChange(
+    'endThumb',
+    (v) => (this.valueEnd = v),
+    () => this.#onRangeChange()
+  );
+
+  // Cached range drag input handlers
+  #onRangeStartInput = this.#onRangeInput('start');
+  #onRangeEndInput = this.#onRangeInput('end');
+
+  // Cached pointer/focus handlers per thumb — prevents new closures on every render
+  #h: Record<ThumbFlag, { show: () => void; hide: () => void; focus: () => void; blur: () => void }> = {
+    thumb: {
+      show: () => this.#showThumbInput('thumb'),
+      hide: () => this.#scheduleHideThumbInput('thumb'),
+      focus: () => this.#focusFloatingInput('thumb'),
+      blur: () => this.#blurFloatingInput('thumb'),
+    },
+    startThumb: {
+      show: () => this.#showThumbInput('startThumb'),
+      hide: () => this.#scheduleHideThumbInput('startThumb'),
+      focus: () => this.#focusFloatingInput('startThumb'),
+      blur: () => this.#blurFloatingInput('startThumb'),
+    },
+    endThumb: {
+      show: () => this.#showThumbInput('endThumb'),
+      hide: () => this.#scheduleHideThumbInput('endThumb'),
+      focus: () => this.#focusFloatingInput('endThumb'),
+      blur: () => this.#blurFloatingInput('endThumb'),
+    },
+  };
+
+  static get styles() {
+    return [super.styles, style];
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.updateComplete.then(() => {
+      if (this.range) {
+        const [startInput, endInput] = this.#rangeInputs();
+        this.#valueStart = startInput.value;
+        this.#valueEnd = endInput.value;
+        this.#defaultValueStart = startInput.value;
+        this.#defaultValueEnd = endInput.value;
+        this._setFormValue(`${startInput.value},${endInput.value}`);
+      } else {
+        const input = this.#singleInput();
+        this.#value = input.value;
+        this.#defaultValue = input.value;
+        this._setFormValue(input.value);
+      }
+    });
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.#clearAllThumbInputState();
+    // Schedule a re-render so the cleared visibility state is reflected in the DOM.
+    // Lit defers this render until the element reconnects if it is currently disconnected.
+    this.requestUpdate();
+  }
+
+  protected updated(changed: Map<PropertyKey, unknown>) {
+    if (changed.has('disabled') && this.disabled) {
+      this.#clearAllThumbInputState();
+    }
+    if (changed.has('min') || changed.has('max')) {
+      // The native inputs have already clamped (and step-snapped) their values to the new bounds.
+      // Read them back and sync internal state + form value. If the value changed, request a
+      // re-render so the floating input (which binds to #value/#valueStart/#valueEnd) stays in sync.
+      if (this.range) {
+        const [startInput, endInput] = this.#rangeInputs();
+        const newStart = startInput.value;
+        const newEnd = endInput.value;
+        if (newStart !== this.#valueStart || newEnd !== this.#valueEnd) {
+          this.#valueStart = newStart;
+          this.#valueEnd = newEnd;
+          this.requestUpdate();
+        }
+        this._setFormValue(`${this.#valueStart},${this.#valueEnd}`);
+      } else {
+        const newValue = this.#singleInput().value;
+        if (newValue !== this.#value) {
+          this.#value = newValue;
+          this.requestUpdate();
+        }
+        this._setFormValue(this.#value);
+      }
+    }
+  }
+
+  #singleInput(): HTMLInputElement {
+    return this.shadowRoot!.querySelector<HTMLInputElement>('input[type="range"]')!;
+  }
+
+  #rangeInputs(): [HTMLInputElement, HTMLInputElement] {
+    const inputs = this.shadowRoot!.querySelectorAll<HTMLInputElement>('input[type="range"]');
+    return [inputs[0], inputs[1]];
+  }
+
   protected get _focusControlSelector() {
     return 'input';
   }
 
   protected get _formValue() {
-    return this.value;
+    return this.range ? `${this.#valueStart},${this.#valueEnd}` : this.#value;
   }
 
   protected formResetCallback() {
-    this.value = this.#defaultValue;
+    this.#clearAllThumbInputState();
+    // Always request a re-render so the cleared thumb visibility is reflected even when the
+    // reset value equals the current value (the named setter requestUpdate would be a no-op).
+    this.requestUpdate();
+    if (this.range) {
+      this.valueStart = this.#defaultValueStart;
+      this.valueEnd = this.#defaultValueEnd;
+    } else {
+      this.value = this.#defaultValue;
+    }
   }
 
-  #defaultValue = `${DEFAULT_MAX / 2}`;
+  #clearAllThumbInputState() {
+    for (const entry of this.#thumbInputState.values()) {
+      clearTimeout(entry.timer);
+      clearTimeout(entry.debounceTimer);
+      entry.timer = undefined;
+      entry.debounceTimer = undefined;
+      entry.visible = false;
+      entry.focused = false;
+    }
+  }
 
-  #value = `${DEFAULT_MAX / 2}`;
+  /**
+   * Clamps a raw string value to the current [min, max] range.
+   * Empty string is passed through unchanged (represents an in-progress floating input edit).
+   * Non-numeric strings are passed through unchanged.
+   */
+  #clampToRange(rawVal: string): string {
+    if (rawVal === '') {
+      return rawVal;
+    }
+    const num = parseFloat(rawVal);
+    if (isNaN(num)) {
+      return rawVal;
+    }
+    return String(Math.min(this.max, Math.max(this.min, num)));
+  }
 
   @property()
   get value() {
     return this.#value;
   }
 
-  set value(val) {
+  set value(rawVal: string) {
+    rawVal = this.#clampToRange(rawVal);
     const oldVal = this.#value;
-    val = this._ensureValidValue(val);
-    this.#value = val;
-    this._setFormValue(this.#value);
+    this.#value = rawVal;
+    this._setFormValue(rawVal);
     this.requestUpdate('value', oldVal);
   }
 
@@ -63,14 +253,45 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
   }
 
   /**
-   * Represents the maximum permitted value
+   * Enables range mode with two thumbs for selecting a value range
+   */
+  @property({ type: Boolean }) range = false;
+
+  @property({ attribute: 'value-start' })
+  get valueStart() {
+    return this.#valueStart;
+  }
+
+  set valueStart(rawVal: string) {
+    rawVal = this.#clampToRange(rawVal);
+    const oldVal = this.#valueStart;
+    this.#valueStart = rawVal;
+    this._setFormValue(`${rawVal},${this.#valueEnd}`);
+    this.requestUpdate('valueStart', oldVal);
+  }
+
+  @property({ attribute: 'value-end' })
+  get valueEnd() {
+    return this.#valueEnd;
+  }
+
+  set valueEnd(rawVal: string) {
+    rawVal = this.#clampToRange(rawVal);
+    const oldVal = this.#valueEnd;
+    this.#valueEnd = rawVal;
+    this._setFormValue(`${this.#valueStart},${rawVal}`);
+    this.requestUpdate('valueEnd', oldVal);
+  }
+
+  /**
+   * Represents the minimum permitted value
    */
   @property({ type: Number }) min = 0;
 
   /**
    * Represents the maximum permitted value
    */
-  @property({ type: Number, attribute: 'max' }) max = 100;
+  @property({ type: Number }) max = 100;
 
   /**
    * Represents the stepping interval, used both for user interface and validation purposes
@@ -78,93 +299,354 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
   @property({ type: Number }) step = 0;
 
   /**
-   * Represents that this control must be filled in for form submission
+   * Shows the min and max values beneath the slider
    */
-  @property({ type: Boolean, attribute: 'no-text' }) noText = false;
+  @property({ type: Boolean, attribute: 'show-min-max' }) showMinMax = false;
+
+  get #range() {
+    return this.max - this.min;
+  }
+
+  get #progressColor() {
+    return this.disabled ? 'var(--zui-gray)' : 'var(--zui-blue)';
+  }
+
+  #isVisible(flag: ThumbFlag): boolean {
+    return this.#thumbInputState.get(flag)!.visible && !this.disabled;
+  }
 
   get progress() {
-    return ((this.valueAsNumber - this.min) / (this.max - this.min)) * 100;
+    return this.#computeProgress(this.#value);
   }
 
-  static get styles() {
-    return [super.styles, style];
+  get progressStart() {
+    return this.#computeProgress(this.#valueStart);
   }
 
-  connectedCallback() {
-    super.connectedCallback();
+  get progressEnd() {
+    return this.#computeProgress(this.#valueEnd);
+  }
 
-    // we want to go a little faster than LitElement and behave more like native HTML Form Associated Elements
-    let value = this.getAttribute('value') ?? this.value;
-    const max = this.getAttribute('max') ?? this.max;
-    const min = this.getAttribute('min') ?? this.min;
+  #computeProgress(rawValue: string): number {
+    if (this.#range === 0) {
+      return 0;
+    }
+    const num = parseFloat(rawValue);
+    return isNaN(num) ? 0 : parseFloat((((num - this.min) / this.#range) * 100).toFixed(4));
+  }
 
-    value = this._ensureValidValue(value, min, max);
+  #singleTrackBackground(progress: number): string {
+    const c = this.#progressColor;
+    const stop = ZuiSlider.#thumbPositionCSS(progress);
+    return `linear-gradient(to right, transparent var(--zui-slider-thumb-size), ${c} var(--zui-slider-thumb-size), ${c} ${stop}, var(--zui-gray-200) ${stop}, var(--zui-gray-200) calc(100% - var(--zui-slider-thumb-size)), transparent calc(100% - var(--zui-slider-thumb-size)))`;
+  }
 
-    this.#defaultValue = value;
-    this._setFormValue(value.toString());
+  #rangeTrackBackground(progressStart: number, progressEnd: number): string {
+    const c = this.#progressColor;
+    const startStop = ZuiSlider.#thumbPositionCSS(progressStart);
+    const endStop = ZuiSlider.#thumbPositionCSS(progressEnd);
+    return `linear-gradient(to right, transparent var(--zui-slider-thumb-size), var(--zui-gray-200) var(--zui-slider-thumb-size), var(--zui-gray-200) ${startStop}, ${c} ${startStop}, ${c} ${endStop}, var(--zui-gray-200) ${endStop}, var(--zui-gray-200) calc(100% - var(--zui-slider-thumb-size)), transparent calc(100% - var(--zui-slider-thumb-size)))`;
   }
 
   render() {
-    const progressColor = this.disabled ? 'var(--zui-gray)' : 'var(--zui-blue)';
-    const styles = {
-      background: `linear-gradient(to right, ${progressColor} 0%, ${progressColor} ${this.progress}%, var(--zui-gray-200) ${this.progress}%, var(--zui-gray-200) 100%)`,
-    };
-    return html`<input
-        style=${styleMap(styles)}
+    return html`${this.range ? this.#renderRange() : this.#renderSingle()}${this.#renderMinMaxLabels()}`;
+  }
+
+  #renderSingle() {
+    const progress = this.progress;
+    return html`
+      <div class="single-wrapper">
+        <input
+          aria-label="Slider value"
+          style=${styleMap({ background: this.#singleTrackBackground(progress) })}
+          type="range"
+          .min="${String(this.min)}"
+          .max="${String(this.max)}"
+          .step="${this.step > 0 ? String(this.step) : '1'}"
+          .value="${this.#value}"
+          ?disabled="${this.disabled}"
+          @input="${this.#onInput}"
+          @change="${this.#onChange}"
+          @pointerenter="${this.#h.thumb.show}"
+          @pointerleave="${this.#h.thumb.hide}"
+          @focus="${this.#h.thumb.show}"
+          @blur="${this.#h.thumb.hide}"
+        />
+        ${this.#renderStepDots()}
+        ${this.#renderFloatingInput(
+          this.#value,
+          this.#onThumbFloatingInput,
+          this.#onThumbFloatingChange,
+          'thumb',
+          this.#isVisible('thumb'),
+          progress
+        )}
+      </div>
+    `;
+  }
+
+  #renderRange() {
+    const progressStart = this.progressStart;
+    const progressEnd = this.progressEnd;
+    return html`
+      <div
+        class="range-wrapper"
+        style=${styleMap({ background: this.#rangeTrackBackground(progressStart, progressEnd) })}
+      >
+        ${this.#renderStepDots()}${this.#renderRangeInput('start')}
+        ${this.#renderFloatingInput(
+          this.#valueStart,
+          this.#onStartThumbFloatingInput,
+          this.#onStartThumbFloatingChange,
+          'startThumb',
+          this.#isVisible('startThumb'),
+          progressStart
+        )}
+        ${this.#renderRangeInput('end')}
+        ${this.#renderFloatingInput(
+          this.#valueEnd,
+          this.#onEndThumbFloatingInput,
+          this.#onEndThumbFloatingChange,
+          'endThumb',
+          this.#isVisible('endThumb'),
+          progressEnd
+        )}
+      </div>
+    `;
+  }
+
+  #renderRangeInput(which: 'start' | 'end') {
+    const flag: ThumbFlag = which === 'start' ? 'startThumb' : 'endThumb';
+    const val = which === 'start' ? this.#valueStart : this.#valueEnd;
+    const onInput = which === 'start' ? this.#onRangeStartInput : this.#onRangeEndInput;
+    const h = this.#h[flag];
+    // live() is required: when #onRangeInput snaps the DOM value back via direct input.value
+    // assignment (drag past the other thumb), there is no state change → no re-render. live()
+    // forces Lit to re-read the current DOM value and re-sync it on every render.
+    return html`
+      <input
+        aria-label="${which === 'start' ? 'Range start' : 'Range end'}"
+        class="range-${which}"
         type="range"
-        .value="${this.value}"
-        .min="${this.min}"
-        .max="${this.max}"
-        .step="${this.step}"
+        .min="${String(this.min)}"
+        .max="${String(this.max)}"
+        .step="${this.step > 0 ? String(this.step) : '1'}"
+        .value="${live(val)}"
         ?disabled="${this.disabled}"
-        @input="${this._onInput}"
-        @change="${this._onChange}"
-      />${this._renderText()}`;
+        @input="${onInput}"
+        @change="${this.#onRangeChange}"
+        @pointerenter="${h.show}"
+        @pointerleave="${h.hide}"
+        @focus="${h.show}"
+        @blur="${h.hide}"
+      />
+    `;
+  }
+
+  #renderFloatingInput(
+    val: string,
+    onInput: (e: Event) => void,
+    onFloatingChange: (e: Event) => void,
+    flag: ThumbFlag,
+    visible: boolean,
+    progress: number
+  ) {
+    const h = this.#h[flag];
+    // live() is required on the number input: when the debounced setter clamps a value to the
+    // same string it already holds (e.g. typing 150 when max=100 clamps back to '100'), no
+    // reactive property change occurs and Lit skips the DOM update. live() forces a re-read.
+    return html`
+      <div
+        class=${classMap({ 'thumb-input': true, 'thumb-input--visible': visible })}
+        style=${styleMap({ left: ZuiSlider.#thumbPositionCSS(progress) })}
+        @pointerenter="${h.show}"
+        @pointerleave="${h.hide}"
+      >
+        <input
+          aria-label="${flag === 'startThumb'
+            ? 'Range start value'
+            : flag === 'endThumb'
+            ? 'Range end value'
+            : 'Slider value'}"
+          type="number"
+          .value="${live(val)}"
+          .min="${String(this.min)}"
+          .max="${String(this.max)}"
+          .step="${this.step > 0 ? String(this.step) : '1'}"
+          ?disabled="${this.disabled}"
+          ?readonly="${this.readOnly}"
+          @input="${onInput}"
+          @change="${onFloatingChange}"
+          @focus="${h.focus}"
+          @blur="${h.blur}"
+        />
+      </div>
+    `;
   }
 
-  private _renderText() {
-    if (this.noText) {
-      return html``;
+  #renderStepDots() {
+    if (this.step <= 0 || this.#range === 0) {
+      return nothing;
     }
-    const thumbOffset = `var(--zui-slider-thumb-size) * ${this.progress / 100}`;
-    const styles = {
-      left: `calc(${this.progress}% - ${thumbOffset} + 0.125rem)`,
-    };
-    return html`<span style=${styleMap(styles)}>${this.value}</span>`;
+    const count = Math.round(this.#range / this.step);
+    if (count > 100) {
+      return nothing;
+    }
+    const dots: TemplateResult[] = [];
+    for (let i = 0; i <= count; i++) {
+      let left: string;
+      if (i === 0) {
+        left = 'var(--zui-slider-thumb-size)';
+      } else if (i === count) {
+        left = 'calc(100% - var(--zui-slider-thumb-size))';
+      } else {
+        const pos = parseFloat((((i * this.step) / this.#range) * 100).toFixed(4));
+        left = ZuiSlider.#thumbPositionCSS(pos);
+      }
+      dots.push(html`<span class="step-dot" style="left: ${left}"></span>`);
+    }
+    return html`<div class="step-dots">${dots}</div>`;
+  }
+
+  #renderMinMaxLabels() {
+    if (!this.showMinMax) {
+      return nothing;
+    }
+    return html`
+      <div class="min-max-labels">
+        <span class="min-max-label">${this.min}</span>
+        <span class="min-max-label">${this.max}</span>
+      </div>
+    `;
   }
 
-  private _onInput(e: Event) {
+  #onInput(e: Event) {
+    if (this.readOnly) {
+      return;
+    }
     this.value = (e.target as HTMLInputElement).value;
   }
 
-  private _onChange() {
-    this.dispatchEvent(new CustomEvent('change', { detail: this.value, bubbles: true }));
+  #onChange() {
+    this.dispatchEvent(new CustomEvent('change', { detail: this.#value, bubbles: true }));
   }
 
-  private _ensureValidValue(value: string | number, min?: number | string | null, max?: number | string | null) {
-    if (value === '') {
-      return value;
-    }
-    min = min ?? this.min;
-    max = max ?? this.max;
+  #processFloatingValue(raw: number): string {
+    const stepDecimals = this.step > 0 ? (String(this.step).split('.')[1] ?? '').length : 0;
+    const stepped = this.step > 0 ? Math.round((raw - this.min) / this.step) * this.step + this.min : raw;
+    const clamped = Math.min(this.max, Math.max(this.min, stepped));
+    return stepDecimals > 0 ? clamped.toFixed(stepDecimals) : String(Math.round(clamped));
+  }
 
-    if (typeof value === 'string') {
-      value = parseFloat(value);
-    }
-    if (typeof min === 'string') {
-      min = parseFloat(min);
-    }
-    if (typeof max === 'string') {
-      max = parseFloat(max);
+  #makeFloatingChange(flag: ThumbFlag, setter: (val: string) => void, dispatch: () => void) {
+    return (e: Event) => {
+      if (this.readOnly) {
+        return;
+      }
+      const input = e.target as HTMLInputElement;
+      if (input.value === '') {
+        return;
+      }
+      const entry = this.#thumbInputState.get(flag)!;
+      clearTimeout(entry.debounceTimer);
+      entry.debounceTimer = undefined;
+      setter(this.#processFloatingValue(parseFloat(input.value)));
+      dispatch();
+    };
+  }
+
+  #onFloatingInput(flag: ThumbFlag, setter: (val: string) => void) {
+    return (e: Event) => {
+      if (this.readOnly) {
+        return;
+      }
+      const input = e.target as HTMLInputElement;
+      if (input.value === '') {
+        return;
+      }
+      const raw = parseFloat(input.value);
+      const entry = this.#thumbInputState.get(flag)!;
+      clearTimeout(entry.debounceTimer);
+      entry.debounceTimer = setTimeout(() => setter(this.#processFloatingValue(raw)), 300);
+    };
+  }
+
+  #onRangeInput(which: 'start' | 'end') {
+    return (e: Event) => {
+      if (this.readOnly) {
+        return;
+      }
+      const input = e.target as HTMLInputElement;
+      if (which === 'start') {
+        if (parseFloat(input.value) >= parseFloat(this.#valueEnd)) {
+          input.value = this.#valueStart;
+          return;
+        }
+        this.valueStart = input.value;
+      } else {
+        if (parseFloat(input.value) <= parseFloat(this.#valueStart)) {
+          input.value = this.#valueEnd;
+          return;
+        }
+        this.valueEnd = input.value;
+      }
+    };
+  }
+
+  #onRangeChange() {
+    this.dispatchEvent(
+      new CustomEvent('change', {
+        detail: { valueStart: this.#valueStart, valueEnd: this.#valueEnd },
+        bubbles: true,
+      })
+    );
+  }
+
+  #showThumbInput(flag: ThumbFlag) {
+    if (this.disabled) {
+      return;
     }
+    const entry = this.#thumbInputState.get(flag)!;
+    clearTimeout(entry.timer);
+    entry.timer = undefined;
+    entry.visible = true;
+    this.requestUpdate();
+  }
+
+  #scheduleHideThumbInput(flag: ThumbFlag) {
+    const entry = this.#thumbInputState.get(flag)!;
+    clearTimeout(entry.timer);
+    entry.timer = setTimeout(() => {
+      if (!entry.focused) {
+        entry.visible = false;
+        this.requestUpdate();
+      }
+    }, 100);
+  }
 
-    if (value < min) {
-      value = min;
-    } else if (value > max) {
-      value = max;
+  #focusFloatingInput(flag: ThumbFlag) {
+    if (this.disabled) {
+      return;
     }
+    this.#showThumbInput(flag);
+    this.#thumbInputState.get(flag)!.focused = true;
+  }
+
+  #blurFloatingInput(flag: ThumbFlag) {
+    const entry = this.#thumbInputState.get(flag)!;
+    entry.focused = false;
+    this.#scheduleHideThumbInput(flag);
+  }
+
+  // Maps a 0–100 progress value to a CSS multiplier for --zui-slider-thumb-size so that
+  // `progress% + thumbSize * offset` lands on the thumb center within the inset wrapper.
+  // At 0%: offset=1.5 → thumbSize*1.5 (thumb center at min). At 100%: offset=-1.5 → -thumbSize*1.5 (thumb center at max).
+  static #thumbCenterOffset(progress: number): number {
+    return 1.5 - (3 * progress) / 100;
+  }
 
-    return value.toString();
+  static #thumbPositionCSS(progress: number): string {
+    return `calc(${progress}% + var(--zui-slider-thumb-size) * ${ZuiSlider.#thumbCenterOffset(progress)})`;
   }
 }