@zywave/zui-slider 4.4.0-pre.3 → 4.4.0-pre.5

package/src/zui-slider.ts

@@ -1,13 +1,17 @@
 import { ZuiFormAssociatedElement } from '@zywave/zui-base';
-import { html, nothing, TemplateResult } from 'lit';
+import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { classMap } from 'lit/directives/class-map.js';
+import { ifDefined } from 'lit/directives/if-defined.js';
 import { live } from 'lit/directives/live.js';
 import { styleMap } from 'lit/directives/style-map.js';
 import { style } from './zui-slider-css.js';
 
 type ThumbFlag = 'thumb' | 'startThumb' | 'endThumb';
 
+/** Number, string, or `{ value, label? }` object. `label` is the display value; `value` drives snapping. */
+type StepInput = number | string | { value: number | string; label?: string };
+
 /**
  * A range form control for choosing values along a slider.
  * @element zui-slider
@@ -23,8 +27,8 @@ type ThumbFlag = 'thumb' | 'startThumb' | 'endThumb';
  * @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
- *
+ * @attr {string} [steps=''] - Comma-separated step labels; overrides min/max/step. Labels containing commas must be set via the property instead.
+ * @attr {boolean} [show-step-labels=false] - When set, displays each step's label beneath its dot on the track
  * @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
@@ -40,7 +44,9 @@ type ThumbFlag = 'thumb' | 'startThumb' | 'endThumb';
  * @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
+ * @prop {StepInput[]} [steps=[]] - Custom step values; overrides min/max/step. Thumbs at equal visual intervals. Accepts number, string, or { value, label? }. Use { value: Infinity, label: '...' } for an unbounded overflow step. Labels with commas must be set via the property.
+ * @prop {((input: string) => number | string | null) | null} [stepParser=null] - Resolves user-typed strings to a step value; returns a number (snap to nearest), a valid step label, or null to reject. Must be set via the property.
+ * @prop {boolean} [showStepLabels=false] - When true, displays each step's label (or its value if no label was provided) beneath the corresponding dot on the track
  *
  * @cssprop [--zui-slider-input-width=7ch] - Width of the floating value input above each slider thumb
  *
@@ -55,13 +61,15 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
   #valueStart: string = '0';
   #valueEnd: string = '100';
 
+  #cachedNormalizedSteps: { value: number | string; label: string }[] | null = null;
+  #cachedNumericValues: number[] | null = null;
+
   #thumbInputState = new Map<
     ThumbFlag,
     {
       visible: boolean;
       focused: boolean;
       timer?: ReturnType<typeof setTimeout>;
-      debounceTimer?: ReturnType<typeof setTimeout>;
     }
   >([
     ['thumb', { visible: false, focused: false }],
@@ -69,12 +77,7 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
     ['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)
+  // Cached floating input change handlers; commit value on Enter or blur
   #onThumbFloatingChange = this.#makeFloatingChange(
     'thumb',
     (v) => (this.value = v),
@@ -91,11 +94,21 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
     () => this.#onRangeChange()
   );
 
+  // Cached keydown handler: Enter commits the floating input value in both number and text modes.
+  #onFloatingInputKeydown = (e: KeyboardEvent) => {
+    if (e.key === 'Enter') {
+      e.preventDefault();
+      const input = e.target as HTMLInputElement;
+      input.dispatchEvent(new Event('change'));
+      input.blur();
+    }
+  };
+
   // 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
+  // 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'),
@@ -121,9 +134,30 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
     return [super.styles, style];
   }
 
+  @property({
+    converter: {
+      fromAttribute: (value: string | null) => (value ? value.split(',').map((s) => s.trim()) : []),
+      toAttribute: (value: StepInput[]) =>
+        value.map((s) => (typeof s === 'object' ? s.label ?? String(s.value) : String(s))).join(','),
+    },
+  })
+  steps: StepInput[] = [];
+
+  @property({ attribute: false }) stepParser: ((input: string) => number | string | null) | null = null;
+
   connectedCallback() {
     super.connectedCallback();
     this.updateComplete.then(() => {
+      if (this.#stepsMode) {
+        this.#syncValuesToSteps();
+        if (this.range) {
+          this.#defaultValueStart = this.#valueStart;
+          this.#defaultValueEnd = this.#valueEnd;
+        } else {
+          this.#defaultValue = this.#value;
+        }
+        return;
+      }
       if (this.range) {
         const [startInput, endInput] = this.#rangeInputs();
         this.#valueStart = startInput.value;
@@ -143,8 +177,7 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
   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.
+    // Re-render to reflect cleared visibility state; Lit defers this until reconnect.
     this.requestUpdate();
   }
 
@@ -152,10 +185,15 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
     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 (changed.has('steps')) {
+      this.#cachedNormalizedSteps = null;
+      this.#cachedNumericValues = null;
+      if (this.#stepsMode) {
+        this.#syncValuesToSteps();
+      }
+    }
+    if (!this.#stepsMode && (changed.has('min') || changed.has('max'))) {
+      // Native inputs clamp/snap to new bounds; read back and sync state. Re-render if value changed.
       if (this.range) {
         const [startInput, endInput] = this.#rangeInputs();
         const newStart = startInput.value;
@@ -196,8 +234,7 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
 
   protected formResetCallback() {
     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).
+    // Force re-render: if the reset value equals the current value, the setter's requestUpdate is a no-op.
     this.requestUpdate();
     if (this.range) {
       this.valueStart = this.#defaultValueStart;
@@ -210,23 +247,59 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
   #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;
     }
   }
 
-  /**
-   * 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.
-   */
+  #syncValuesToSteps() {
+    const lastIdx = this.#normalizedSteps.length - 1;
+    if (this.range) {
+      if (this.#stepsIndexOf(this.#valueStart) < 0) {
+        this.#valueStart = this.#stepAt(0);
+        this.requestUpdate();
+      }
+      if (this.#stepsIndexOf(this.#valueEnd) < 0) {
+        this.#valueEnd = this.#stepAt(lastIdx);
+        this.requestUpdate();
+      }
+      this._setFormValue(`${this.#valueStart},${this.#valueEnd}`);
+    } else {
+      if (this.#stepsIndexOf(this.#value) < 0) {
+        this.#value = this.#stepAt(0);
+        this.requestUpdate();
+      }
+      this._setFormValue(this.#value);
+    }
+  }
+
+  /** Steps mode: snaps to nearest step. Normal mode: clamps to [min, max]. Empty string passes through. */
   #clampToRange(rawVal: string): string {
     if (rawVal === '') {
       return rawVal;
     }
+    if (this.#stepsMode) {
+      if (this.#stepsIndexOf(rawVal) >= 0) {
+        return rawVal;
+      }
+      let n: number | null = null;
+      if (this.stepParser) {
+        const result = this.stepParser(rawVal);
+        if (typeof result === 'number') {
+          n = result;
+        } else if (typeof result === 'string' && this.#stepsIndexOf(result) >= 0) {
+          return result;
+        }
+      }
+      if (n === null) {
+        n = parseFloat(rawVal);
+      }
+      if (!isNaN(n)) {
+        return this.#snapToSteps(n);
+      }
+      return this.#stepAt(0);
+    }
     const num = parseFloat(rawVal);
     if (isNaN(num)) {
       return rawVal;
@@ -251,9 +324,6 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
     return parseFloat(this.#value);
   }
 
-  /**
-   * Enables range mode with two thumbs for selecting a value range
-   */
   @property({ type: Boolean }) range = false;
 
   @property({ attribute: 'value-start' })
@@ -282,25 +352,14 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
     this.requestUpdate('valueEnd', oldVal);
   }
 
-  /**
-   * Represents the minimum permitted value
-   */
   @property({ type: Number }) min = 0;
 
-  /**
-   * Represents the maximum permitted value
-   */
   @property({ type: Number }) max = 100;
 
-  /**
-   * Represents the stepping interval, used both for user interface and validation purposes
-   */
   @property({ type: Number }) step = 0;
 
-  /**
-   * Shows the min and max values beneath the slider
-   */
-  @property({ type: Boolean, attribute: 'show-min-max' }) showMinMax = false;
+  /** Displays each step's label beneath its dot on the track. Requires `steps` to be set. */
+  @property({ type: Boolean, attribute: 'show-step-labels' }) showStepLabels = false;
 
   get #range() {
     return this.max - this.min;
@@ -314,6 +373,109 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
     return this.#thumbInputState.get(flag)!.visible && !this.disabled;
   }
 
+  // ─── Steps helpers ───────────────────────────────────────────────────────────
+
+  get #stepsMode(): boolean {
+    return this.steps.length > 0;
+  }
+
+  get #nativeRangeAttrs(): { nativeMin: string; nativeMax: string; nativeStep: string } {
+    return {
+      nativeMin: this.#stepsMode ? '0' : String(this.min),
+      nativeMax: this.#stepsMode ? String(this.#normalizedSteps.length - 1) : String(this.max),
+      nativeStep: this.#stepsMode ? '1' : this.step > 0 ? String(this.step) : '1',
+    };
+  }
+
+  /** Normalizes each StepInput to `{ value, label }`. Cached after first access. */
+  get #normalizedSteps(): { value: number | string; label: string }[] {
+    if (!this.#cachedNormalizedSteps) {
+      this.#cachedNormalizedSteps = this.steps.map((s) => {
+        if (typeof s === 'number') {
+          return { value: s, label: String(s) };
+        }
+        if (typeof s === 'string') {
+          return { value: s, label: s };
+        }
+        return { value: s.value, label: s.label ?? String(s.value) };
+      });
+    }
+    return this.#cachedNormalizedSteps;
+  }
+
+  #stepsIndexOf(val: string): number {
+    return this.#normalizedSteps.findIndex((s) => s.label === val);
+  }
+
+  #stepAt(index: number): string {
+    const normalized = this.#normalizedSteps;
+    return normalized[Math.max(0, Math.min(normalized.length - 1, index))].label;
+  }
+
+  /** Numeric value per step for #snapToSteps. Strings parsed via parseFloat; unparseable strings map to Infinity. */
+  get #stepsNumericValues(): number[] {
+    if (!this.#cachedNumericValues) {
+      this.#cachedNumericValues = this.#normalizedSteps.map((step) => {
+        if (typeof step.value === 'number') {
+          return step.value;
+        }
+        const sv = step.value as string;
+        const n = parseFloat(sv);
+        return isNaN(n) ? Infinity : n;
+      });
+    }
+    return this.#cachedNumericValues;
+  }
+
+  /** Snaps n to the nearest step by numeric value; overflow steps win only past the last finite value. */
+  #snapToSteps(n: number): string {
+    const numericValues = this.#stepsNumericValues;
+    let lastFiniteValue = -Infinity;
+    for (const v of numericValues) {
+      if (isFinite(v) && v > lastFiniteValue) {
+        lastFiniteValue = v;
+      }
+    }
+    let bestIdx = 0;
+    let bestDist = Infinity;
+    for (let i = 0; i < numericValues.length; i++) {
+      const v = numericValues[i];
+      const dist = v === Infinity ? (n > lastFiniteValue ? 0 : Math.abs(n - lastFiniteValue) + 1) : Math.abs(n - v);
+      if (dist < bestDist) {
+        bestDist = dist;
+        bestIdx = i;
+      }
+    }
+    return this.#stepAt(bestIdx);
+  }
+
+  /** Resolves a user-typed string to a step label; returns null if unresolvable. Steps mode only. */
+  #resolveFloatingInput(raw: string): string | null {
+    // Exact label match wins; a valid label is never rejected by a stepParser that doesn't recognize it.
+    const exactIdx = this.#stepsIndexOf(raw);
+    if (exactIdx >= 0) {
+      return this.#stepAt(exactIdx);
+    }
+    if (this.stepParser) {
+      const result = this.stepParser(raw);
+      if (result === null) {
+        return null;
+      }
+      if (typeof result === 'number') {
+        return this.#snapToSteps(result);
+      }
+      // String result must be a valid step label
+      return this.#stepsIndexOf(result) >= 0 ? result : null;
+    }
+    const n = parseFloat(raw);
+    if (isNaN(n)) {
+      return null;
+    }
+    return this.#snapToSteps(n);
+  }
+
+  // ─── Progress ────────────────────────────────────────────────────────────────
+
   get progress() {
     return this.#computeProgress(this.#value);
   }
@@ -327,6 +489,14 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
   }
 
   #computeProgress(rawValue: string): number {
+    if (this.#stepsMode) {
+      const total = this.#normalizedSteps.length - 1;
+      if (total <= 0) {
+        return 0;
+      }
+      const idx = this.#stepsIndexOf(rawValue);
+      return idx < 0 ? 0 : parseFloat(((idx / total) * 100).toFixed(4));
+    }
     if (this.#range === 0) {
       return 0;
     }
@@ -347,22 +517,27 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
     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 ──────────────────────────────────────────────────────────────────
+
   render() {
     return html`${this.range ? this.#renderRange() : this.#renderSingle()}${this.#renderMinMaxLabels()}`;
   }
 
   #renderSingle() {
     const progress = this.progress;
+    const { nativeMin, nativeMax, nativeStep } = this.#nativeRangeAttrs;
+    // live() required: direct DOM writes during drag don't trigger a state change, so Lit won't re-sync without it.
+    const nativeValue = this.#stepsMode ? String(Math.max(0, this.#stepsIndexOf(this.#value))) : this.#value;
     return html`
       <div class="single-wrapper">
         <input
           aria-label="Slider value"
           style=${styleMap({ '--zui-slider-track-bg': this.#singleTrackBackground(progress) })}
           type="range"
-          .min="${String(this.min)}"
-          .max="${String(this.max)}"
-          .step="${this.step > 0 ? String(this.step) : '1'}"
-          .value="${this.#value}"
+          .min="${nativeMin}"
+          .max="${nativeMax}"
+          .step="${nativeStep}"
+          .value="${live(nativeValue)}"
           ?disabled="${this.disabled || this.readOnly}"
           @input="${this.#onInput}"
           @change="${this.#onChange}"
@@ -373,7 +548,6 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
         />
         ${this.#renderFloatingInput(
           this.#value,
-          this.#onThumbFloatingInput,
           this.#onThumbFloatingChange,
           'thumb',
           this.#isVisible('thumb'),
@@ -392,7 +566,6 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
         ${this.#renderRangeInput('start', this.#rangeTrackBackground(progressStart, progressEnd))}
         ${this.#renderFloatingInput(
           this.#valueStart,
-          this.#onStartThumbFloatingInput,
           this.#onStartThumbFloatingChange,
           'startThumb',
           this.#isVisible('startThumb'),
@@ -401,7 +574,6 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
         ${this.#renderRangeInput('end')}
         ${this.#renderFloatingInput(
           this.#valueEnd,
-          this.#onEndThumbFloatingInput,
           this.#onEndThumbFloatingChange,
           'endThumb',
           this.#isVisible('endThumb'),
@@ -417,19 +589,19 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
     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.
+    const { nativeMin, nativeMax, nativeStep } = this.#nativeRangeAttrs;
+    const nativeValue = this.#stepsMode ? String(Math.max(0, this.#stepsIndexOf(val))) : val;
+    // live() required: direct DOM writes during drag don't trigger a state change, so Lit won't re-sync without it.
     return html`
       <input
         aria-label="${which === 'start' ? 'Range start' : 'Range end'}"
         class="range-${which}"
         type="range"
         style=${trackBg ? styleMap({ '--zui-slider-track-bg': trackBg }) : nothing}
-        .min="${String(this.min)}"
-        .max="${String(this.max)}"
-        .step="${this.step > 0 ? String(this.step) : '1'}"
-        .value="${live(val)}"
+        .min="${nativeMin}"
+        .max="${nativeMax}"
+        .step="${nativeStep}"
+        .value="${live(nativeValue)}"
         ?disabled="${this.disabled || this.readOnly}"
         @input="${onInput}"
         @change="${this.#onRangeChange}"
@@ -443,16 +615,16 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
 
   #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.
+    // type="text" in steps mode to allow label and stepParser input.
+    // live() required: commits that snap/clamp to the current value skip reactive updates, so Lit won't re-sync without it.
+    const ariaLabel =
+      flag === 'startThumb' ? 'Range start value' : flag === 'endThumb' ? 'Range end value' : 'Slider value';
     return html`
       <div
         class=${classMap({ 'thumb-input': true, 'thumb-input--visible': visible })}
@@ -461,19 +633,15 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
         @pointerleave="${h.hide}"
       >
         <input
-          aria-label="${flag === 'startThumb'
-            ? 'Range start value'
-            : flag === 'endThumb'
-            ? 'Range end value'
-            : 'Slider value'}"
-          type="number"
+          aria-label="${ariaLabel}"
+          type="${this.#stepsMode ? 'text' : 'number'}"
           .value="${live(val)}"
-          .min="${String(this.min)}"
-          .max="${String(this.max)}"
-          .step="${this.step > 0 ? String(this.step) : '1'}"
+          .min="${this.#stepsMode ? '' : String(this.min)}"
+          .max="${this.#stepsMode ? '' : String(this.max)}"
+          .step="${this.#stepsMode ? '' : this.step > 0 ? String(this.step) : '1'}"
           ?disabled="${this.disabled}"
           ?readonly="${this.readOnly}"
-          @input="${onInput}"
+          @keydown="${this.#onFloatingInputKeydown}"
           @change="${onFloatingChange}"
           @focus="${h.focus}"
           @blur="${h.blur}"
@@ -483,6 +651,29 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
   }
 
   #renderStepDots() {
+    if (this.#stepsMode) {
+      const normalized = this.#normalizedSteps;
+      const total = normalized.length - 1;
+      if (total <= 0 || normalized.length > 100) {
+        return nothing;
+      }
+      const stepDots = normalized.map((step, i) => {
+        const left =
+          i === 0
+            ? 'var(--zui-slider-thumb-size)'
+            : i === total
+            ? 'calc(100% - var(--zui-slider-thumb-size))'
+            : ZuiSlider.#thumbPositionCSS((i / total) * 100);
+        return html`<span
+            class=${classMap({ 'step-dot': true, 'step-dot--last': i === total && this.showStepLabels })}
+            style="left: ${left}"
+          ></span>
+          ${this.showStepLabels
+            ? html`<span class="step-dot-label" style="left: ${left}">${step.label}</span>`
+            : nothing}`;
+      });
+      return html`<div class="step-dots">${stepDots}</div>`;
+    }
     if (this.step <= 0 || this.#range === 0) {
       return nothing;
     }
@@ -490,7 +681,7 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
     if (count > 100) {
       return nothing;
     }
-    const dots: TemplateResult[] = [];
+    const dots = [];
     for (let i = 0; i <= count; i++) {
       let left: string;
       if (i === 0) {
@@ -507,22 +698,34 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
   }
 
   #renderMinMaxLabels() {
-    if (!this.showMinMax) {
-      return nothing;
-    }
+    const normalized = this.#normalizedSteps;
+    const minLabel = this.#stepsMode ? normalized[0]?.label ?? '' : String(this.min);
+    const maxLabel = this.#stepsMode ? normalized[normalized.length - 1]?.label ?? '' : String(this.max);
+    const hidden = this.showStepLabels && this.#stepsMode;
     return html`
-      <div class="min-max-labels">
-        <span class="min-max-label">${this.min}</span>
-        <span class="min-max-label">${this.max}</span>
+      <div
+        class="min-max-labels"
+        aria-hidden="${ifDefined(hidden ? 'true' : undefined)}"
+        style=${hidden ? styleMap({ visibility: 'hidden' }) : nothing}
+      >
+        <span class="min-max-label">${minLabel}</span>
+        <span class="min-max-label">${maxLabel}</span>
       </div>
     `;
   }
 
+  // ─── Event handlers ──────────────────────────────────────────────────────────
+
   #onInput(e: Event) {
     if (this.readOnly) {
       return;
     }
-    this.value = (e.target as HTMLInputElement).value;
+    const input = e.target as HTMLInputElement;
+    if (this.#stepsMode) {
+      this.value = this.#stepAt(parseInt(input.value, 10));
+    } else {
+      this.value = input.value;
+    }
   }
 
   #onChange() {
@@ -536,36 +739,45 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
     return stepDecimals > 0 ? clamped.toFixed(stepDecimals) : String(Math.round(clamped));
   }
 
-  #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();
-    };
+  #currentValueForFlag(flag: ThumbFlag): string {
+    if (flag === 'startThumb') {
+      return this.#valueStart;
+    }
+    if (flag === 'endThumb') {
+      return this.#valueEnd;
+    }
+    return this.#value;
   }
 
-  #onFloatingInput(flag: ThumbFlag, setter: (val: string) => void) {
+  #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 === '') {
+        input.value = this.#currentValueForFlag(flag);
         return;
       }
-      const raw = parseFloat(input.value);
-      const entry = this.#thumbInputState.get(flag)!;
-      clearTimeout(entry.debounceTimer);
-      entry.debounceTimer = setTimeout(() => setter(this.#processFloatingValue(raw)), 300);
+      const before = this.#currentValueForFlag(flag);
+      if (this.#stepsMode) {
+        const resolved = this.#resolveFloatingInput(input.value);
+        if (resolved !== null) {
+          setter(resolved);
+          this.requestUpdate();
+          if (this.#currentValueForFlag(flag) !== before) {
+            dispatch();
+          }
+        } else {
+          input.value = this.#currentValueForFlag(flag);
+        }
+      } else {
+        setter(this.#processFloatingValue(parseFloat(input.value)));
+        this.requestUpdate();
+        if (this.#currentValueForFlag(flag) !== before) {
+          dispatch();
+        }
+      }
     };
   }
 
@@ -575,18 +787,37 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
         return;
       }
       const input = e.target as HTMLInputElement;
-      if (which === 'start') {
-        if (parseFloat(input.value) >= parseFloat(this.#valueEnd)) {
-          input.value = this.#valueStart;
-          return;
+      if (this.#stepsMode) {
+        const idx = parseInt(input.value, 10);
+        const startIdx = Math.max(0, this.#stepsIndexOf(this.#valueStart));
+        const endIdx = Math.max(0, this.#stepsIndexOf(this.#valueEnd));
+        if (which === 'start') {
+          if (idx >= endIdx) {
+            input.value = String(startIdx);
+            return;
+          }
+          this.valueStart = this.#stepAt(idx);
+        } else {
+          if (idx <= startIdx) {
+            input.value = String(endIdx);
+            return;
+          }
+          this.valueEnd = this.#stepAt(idx);
         }
-        this.valueStart = input.value;
       } else {
-        if (parseFloat(input.value) <= parseFloat(this.#valueStart)) {
-          input.value = this.#valueEnd;
-          return;
+        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;
         }
-        this.valueEnd = input.value;
       }
     };
   }
@@ -612,10 +843,41 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
     const trackLeft = rect.left + thumbRadius;
     const effectiveWidth = rect.width - 2 * thumbRadius;
     const fraction = Math.max(0, Math.min(1, (e.clientX - trackLeft) / effectiveWidth));
+
+    if (this.#stepsMode) {
+      const total = this.#normalizedSteps.length - 1;
+      if (total <= 0) {
+        return;
+      }
+      const clickedIdx = Math.round(fraction * total);
+      const startIdx = Math.max(0, this.#stepsIndexOf(this.#valueStart));
+      const endIdx = Math.max(0, this.#stepsIndexOf(this.#valueEnd));
+
+      // Ignore clicks within a thumb's hit area
+      const startX = trackLeft + (startIdx / total) * effectiveWidth;
+      const endX = trackLeft + (endIdx / total) * effectiveWidth;
+      if (Math.abs(e.clientX - startX) <= thumbRadius || Math.abs(e.clientX - endX) <= thumbRadius) {
+        return;
+      }
+
+      // Move whichever thumb is closer by index distance; prefer start on a tie
+      if (Math.abs(clickedIdx - startIdx) <= Math.abs(clickedIdx - endIdx)) {
+        if (clickedIdx < endIdx) {
+          this.valueStart = this.#stepAt(clickedIdx);
+          this.#onRangeChange();
+        }
+      } else {
+        if (clickedIdx > startIdx) {
+          this.valueEnd = this.#stepAt(clickedIdx);
+          this.#onRangeChange();
+        }
+      }
+      return;
+    }
+
     const rawValue = this.min + fraction * (this.max - this.min);
 
-    // Ignore clicks that land within a thumb's hit area — those bubble up from native input
-    // interactions and should not be treated as track clicks.
+    // Ignore clicks within a thumb's hit area; those are native input interactions, not track clicks.
     const startX = trackLeft + (this.progressStart / 100) * effectiveWidth;
     const endX = trackLeft + (this.progressEnd / 100) * effectiveWidth;
     if (Math.abs(e.clientX - startX) <= thumbRadius || Math.abs(e.clientX - endX) <= thumbRadius) {
@@ -677,9 +939,7 @@ export class ZuiSlider extends ZuiFormAssociatedElement {
     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).
+  // Maps progress 0-100 to a --zui-slider-thumb-size multiplier (1.5 at 0%, -1.5 at 100%) that centers the thumb on the track.
   static #thumbCenterOffset(progress: number): number {
     return 1.5 - (3 * progress) / 100;
   }