feat(range): add reference point for start position of range slider

angular/src/directives/proxies.ts

@@ -1304,13 +1304,13 @@ mouse drag, touch gesture, or keyboard interaction.
 
 @ProxyCmp({
   defineCustomElementFn: undefined,
-  inputs: ['color', 'debounce', 'disabled', 'dualKnobs', 'max', 'min', 'mode', 'name', 'pin', 'pinFormatter', 'snaps', 'step', 'ticks', 'value']
+  inputs: ['barActiveStart', 'color', 'debounce', 'disabled', 'dualKnobs', 'max', 'min', 'mode', 'name', 'pin', 'pinFormatter', 'snaps', 'step', 'ticks', 'value']
 })
 @Component({
   selector: 'ion-range',
   changeDetection: ChangeDetectionStrategy.OnPush,
   template: '<ng-content></ng-content>',
-  inputs: ['color', 'debounce', 'disabled', 'dualKnobs', 'max', 'min', 'mode', 'name', 'pin', 'pinFormatter', 'snaps', 'step', 'ticks', 'value']
+  inputs: ['barActiveStart', 'color', 'debounce', 'disabled', 'dualKnobs', 'max', 'min', 'mode', 'name', 'pin', 'pinFormatter', 'snaps', 'step', 'ticks', 'value']
 })
 export class IonRange {
   protected el: HTMLElement;

core/api.txt

@@ -971,6 +971,7 @@ ion-radio-group,prop,value,any,undefined,false,false
 ion-radio-group,event,ionChange,RadioGroupChangeEventDetail<any>,true
 
 ion-range,shadow
+ion-range,prop,barActiveStart,number,this.min,false,false
 ion-range,prop,color,"danger" | "dark" | "light" | "medium" | "primary" | "secondary" | "success" | "tertiary" | "warning" | string & Record<never, never> | undefined,undefined,false,true
 ion-range,prop,debounce,number,0,false,false
 ion-range,prop,disabled,boolean,false,false,false

core/src/components.d.ts

@@ -2076,6 +2076,10 @@ export namespace Components {
         "value"?: any | null;
     }
     interface IonRange {
+        /**
+          * The start position of the range active bar, only available with a single knob (dualKnobs="false"). Valid values are between the `min` and `max` values.
+         */
+        "barActiveStart"?: number;
         /**
           * The color to use from your application's color palette. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information on colors, see [theming](/docs/theming/basics).
          */
@@ -5961,6 +5965,10 @@ declare namespace LocalJSX {
         "value"?: any | null;
     }
     interface IonRange {
+        /**
+          * The start position of the range active bar, only available with a single knob (dualKnobs="false"). Valid values are between the `min` and `max` values.
+         */
+        "barActiveStart"?: number;
         /**
           * The color to use from your application's color palette. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information on colors, see [theming](/docs/theming/basics).
          */

core/src/components/range/range.tsx

@@ -16,6 +16,7 @@ import type {
 import { findClosestIonContent, disableContentScrollY, resetContentScrollY } from '../../utils/content';
 import type { Attributes } from '../../utils/helpers';
 import { inheritAriaAttributes, clamp, debounceEvent, getAriaLabel, renderHiddenInput } from '../../utils/helpers';
+import { printIonWarning } from '../../utils/logging';
 import { isRTL } from '../../utils/rtl';
 import { createColorClasses, hostContext } from '../../utils/theme';
 
@@ -142,6 +143,29 @@ export class Range implements ComponentInterface {
    */
   @Prop() ticks = true;
 
+  /**
+   * The start position of the range active bar, only available with a single knob (dualKnobs="false").
+   * Valid values are between the `min` and `max` values.
+   */
+  @Prop() barActiveStart?: number;
+  @Watch('barActiveStart')
+  protected barActiveStartChanged() {
+    const { barActiveStart } = this;
+    if (barActiveStart !== undefined) {
+      if (barActiveStart > this.max) {
+        printIonWarning(
+          `Range: The value of barActiveStart (${barActiveStart}) is greater than the max (${this.max}). Accepted values are between the min and max values of the range.`,
+          this.el
+        );
+      } else if (barActiveStart < this.min) {
+        printIonWarning(
+          `Range: The value of barActiveStart (${barActiveStart}) is less than the min (${this.min}). Accepted values are between the min and max values of the range.`,
+          this.el
+        );
+      }
+    }
+  }
+
   /**
    * If `true`, the user cannot interact with the range.
    */
@@ -252,6 +276,7 @@ export class Range implements ComponentInterface {
     this.updateRatio();
     this.debounceChanged();
     this.disabledChanged();
+    this.barActiveStartChanged();
 
     /**
      * If we have not yet rendered
@@ -395,7 +420,11 @@ export class Range implements ComponentInterface {
     if (this.dualKnobs) {
       return Math.min(this.ratioA, this.ratioB);
     }
-    return 0;
+    const { barActiveStart } = this;
+    if (barActiveStart == null) {
+      return 0;
+    }
+    return valueToRatio(barActiveStart, this.min, this.max);
   }
 
   private get ratioUpper() {
@@ -484,8 +513,8 @@ export class Range implements ComponentInterface {
       labelText = inheritedAttributes['aria-label'];
     }
     const mode = getIonMode(this);
-    const barStart = `${ratioLower * 100}%`;
-    const barEnd = `${100 - ratioUpper * 100}%`;
+    let barStart = `${ratioLower * 100}%`;
+    let barEnd = `${100 - ratioUpper * 100}%`;
 
     const rtl = isRTL(this.el);
 
@@ -498,6 +527,16 @@ export class Range implements ComponentInterface {
       };
     };
 
+    if (this.dualKnobs === false) {
+      if (this.valA < (this.barActiveStart ?? this.min)) {
+        barStart = `${ratioUpper * 100}%`;
+        barEnd = `${100 - ratioLower * 100}%`;
+      } else {
+        barStart = `${ratioLower * 100}%`;
+        barEnd = `${100 - ratioUpper * 100}%`;
+      }
+    }
+
     const barStyle = {
       [start]: barStart,
       [end]: barEnd,
@@ -510,7 +549,7 @@ export class Range implements ComponentInterface {
 
         const tick: any = {
           ratio,
-          active: ratio >= ratioLower && ratio <= ratioUpper,
+          active: ratio >= Math.min(ratioLower, ratioUpper) && ratio <= Math.max(ratioLower, ratioUpper),
         };
 
         tick[start] = `${ratio * 100}%`;

core/src/components/range/test/barActiveStart/index.html

@@ -0,0 +1,141 @@
+<!DOCTYPE html>
+<html lang="en" dir="ltr">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Range - barActiveStart</title>
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no"
+    />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no"
+    />
+    <link href="../../../../../css/core.css" rel="stylesheet" />
+    <link href="../../../../../scripts/testing/styles.css" rel="stylesheet" />
+    <script src="../../../../../scripts/testing/scripts.js"></script>
+    <script nomodule src="../../../../../dist/ionic/ionic.js"></script>
+    <script type="module" src="../../../../../dist/ionic/ionic.esm.js"></script>
+  </head>
+
+  <body>
+    <ion-app>
+      <ion-header>
+        <ion-toolbar>
+          <ion-title>Range - barActiveStart</ion-title>
+        </ion-toolbar>
+      </ion-header>
+      <ion-content class="ion-padding" id="content">
+        <ion-list>
+          <ion-item>
+            <ion-label position="stacked">barActiveStart is 0 and value is 0.</ion-label>
+            <ion-range
+              class="ion-no-padding"
+              min="-100"
+              max="100"
+              snaps="10"
+              step="10"
+              pin="true"
+              bar-active-start="0"
+              value="0"
+            >
+            </ion-range>
+          </ion-item>
+          <ion-item>
+            <ion-label position="stacked"> barActiveStart is 0 and value is 70. </ion-label>
+            <ion-range
+              class="ion-no-padding"
+              min="-100"
+              max="100"
+              snaps="10"
+              step="10"
+              pin="true"
+              bar-active-start="0"
+              value="70"
+            >
+            </ion-range>
+          </ion-item>
+          <ion-item>
+            <ion-label position="stacked"> barActiveStart is 0 and value is -70. </ion-label>
+            <ion-range
+              class="ion-no-padding"
+              min="-100"
+              max="100"
+              snaps="10"
+              step="10"
+              pin="true"
+              bar-active-start="0"
+              value="-70"
+            >
+            </ion-range>
+          </ion-item>
+          <ion-item>
+            <ion-label position="stacked"> barActiveStart is -30 and value is 0. </ion-label>
+            <ion-range
+              class="ion-no-padding"
+              min="-100"
+              max="100"
+              snaps="10"
+              step="10"
+              pin="true"
+              bar-active-start="-30"
+              value="0"
+            >
+            </ion-range>
+          </ion-item>
+          <ion-item>
+            <ion-label position="stacked"> barActiveStart is 30 and value is 0. </ion-label>
+            <ion-range
+              class="ion-no-padding"
+              min="-100"
+              max="100"
+              snaps="10"
+              step="10"
+              pin="true"
+              bar-active-start="30"
+              value="0"
+            >
+            </ion-range>
+          </ion-item>
+          <ion-item>
+            <ion-label position="stacked">barActiveStart is between steps</ion-label>
+            <ion-range
+              class="ion-no-padding"
+              min="-100"
+              max="100"
+              snaps="10"
+              step="10"
+              pin="true"
+              bar-active-start="25"
+              value="0"
+            ></ion-range>
+          </ion-item>
+          <ion-item>
+            <ion-label position="stacked">invalid barActiveStart value (less than min)</ion-label>
+            <ion-range class="ion-no-padding" min="0" max="100" snaps="10" step="10" pin="true" bar-active-start="-30">
+            </ion-range>
+          </ion-item>
+          <ion-item>
+            <ion-label position="stacked">invalid barActiveStart value (greater than max)</ion-label>
+            <ion-range class="ion-no-padding" min="0" max="100" snaps="10" step="10" pin="true" bar-active-start="110">
+            </ion-range>
+          </ion-item>
+          <ion-item>
+            <ion-label position="stacked"> barActiveStart is ignored with dual knobs enabled. </ion-label>
+            <ion-range
+              class="ion-no-padding"
+              min="-100"
+              max="100"
+              snaps="10"
+              step="10"
+              pin="true"
+              bar-active-start="-30"
+              dual-knobs="true"
+              value="30"
+            ></ion-range>
+          </ion-item>
+        </ion-list>
+      </ion-content>
+    </ion-app>
+  </body>
+</html>

core/src/components/range/test/barActiveStart/range.e2e.ts

@@ -0,0 +1,12 @@
+import { expect } from '@playwright/test';
+import { test } from '@utils/test/playwright';
+
+test.describe('range: barActiveStart', () => {
+  test('should not have visual regressions', async ({ page }) => {
+    await page.goto(`/src/components/range/test/barActiveStart`);
+
+    await page.setIonViewport();
+
+    expect(await page.screenshot()).toMatchSnapshot(`range-barActiveStart-diff-${page.getSnapshotSettings()}.png`);
+  });
+});

core/src/utils/logging/index.ts

@@ -4,8 +4,8 @@
  *
  * @param message - The string message to be logged to the console.
  */
-export const printIonWarning = (message: string) => {
-  return console.warn(`[Ionic Warning]: ${message}`);
+export const printIonWarning = (message: string, ...params: any[]) => {
+  return console.warn(`[Ionic Warning]: ${message}`, ...params);
 };
 
 /*

packages/vue/src/proxies.ts

@@ -587,6 +587,7 @@ export const IonRange = /*@__PURE__*/ defineContainer<JSX.IonRange>('ion-range',
   'snaps',
   'step',
   'ticks',
+  'barActiveStart',
   'disabled',
   'value',
   'ionChange',