From 944abcedc76e53db7f4229acb80d79e234243091 Mon Sep 17 00:00:00 2001
From: Amanda Johnston <90629384+amandaejohnston@users.noreply.github.com>
Date: Wed, 10 May 2023 10:43:14 -0500
Subject: [PATCH] docs(range): update docs to use label prop (#2955)

---
 docs/api/range.md                             |  31 ++++-
 static/usage/v7/range/label-slot/angular.md   |   7 ++
 static/usage/v7/range/label-slot/demo.html    |  31 +++++
 .../v7/range/{basic => label-slot}/index.md   |   2 +-
 .../usage/v7/range/label-slot/javascript.md   |   7 ++
 static/usage/v7/range/label-slot/react.md     |  14 +++
 static/usage/v7/range/label-slot/vue.md       |  18 +++
 static/usage/v7/range/labels/angular.md       |  12 +-
 static/usage/v7/range/labels/demo.html        |  20 ++--
 static/usage/v7/range/labels/javascript.md    |  12 +-
 static/usage/v7/range/labels/react.md         |  12 +-
 static/usage/v7/range/labels/vue.md           |  12 +-
 static/usage/v7/range/migration/index.md      | 108 ++++++++++++------
 .../{basic => no-visible-label}/angular.md    |   0
 .../{basic => no-visible-label}/demo.html     |   0
 .../usage/v7/range/no-visible-label/index.md  |   8 ++
 .../{basic => no-visible-label}/javascript.md |   0
 .../{basic => no-visible-label}/react.md      |   0
 .../range/{basic => no-visible-label}/vue.md  |   0
 19 files changed, 207 insertions(+), 87 deletions(-)
 create mode 100644 static/usage/v7/range/label-slot/angular.md
 create mode 100644 static/usage/v7/range/label-slot/demo.html
 rename static/usage/v7/range/{basic => label-slot}/index.md (84%)
 create mode 100644 static/usage/v7/range/label-slot/javascript.md
 create mode 100644 static/usage/v7/range/label-slot/react.md
 create mode 100644 static/usage/v7/range/label-slot/vue.md
 rename static/usage/v7/range/{basic => no-visible-label}/angular.md (100%)
 rename static/usage/v7/range/{basic => no-visible-label}/demo.html (100%)
 create mode 100644 static/usage/v7/range/no-visible-label/index.md
 rename static/usage/v7/range/{basic => no-visible-label}/javascript.md (100%)
 rename static/usage/v7/range/{basic => no-visible-label}/react.md (100%)
 rename static/usage/v7/range/{basic => no-visible-label}/vue.md (100%)

diff --git a/docs/api/range.md b/docs/api/range.md
index fd091246945..be52a7b1fea 100644
--- a/docs/api/range.md
+++ b/docs/api/range.md
@@ -22,18 +22,37 @@ The Range slider lets users select from a range of values by moving the slider k
 
 By default the Range slider has a minimum value of `0` and a maximum value of `100`. This can be configured with the `min` and `max` properties.
 
-## Basic Usage
+## Labels
 
-import Basic from '@site/static/usage/v7/range/basic/index.md';
+Range has several options for supplying a label for the component:
+- `label` property: used for plaintext labels
+- `label` slot: used for custom HTML labels
+- `aria-label`: used for ranges with no visible label
 
-<Basic />
+### Label Placement
 
-## Label Placement
+The below demo shows how to use the `labelPlacement` property to change the position of the label relative to the range. While the `label` property is used here, `labelPlacement` can also be used with the `label` slot.
 
 import LabelsPlayground from '@site/static/usage/v7/range/labels/index.md';
 
 <LabelsPlayground />
 
+### Label Slot
+
+While plaintext labels should be passed in via the `label` property, if custom HTML is needed, it can be passed through the `label` slot instead.
+
+import LabelSlotPlayground from '@site/static/usage/v7/range/label-slot/index.md';
+
+<LabelSlotPlayground />
+
+### No Visible Label
+
+If no visible label is needed, devs should still supply an `aria-label` so the range is accessible to screen readers.
+
+import NoVisibleLabel from '@site/static/usage/v7/range/no-visible-label/index.md';
+
+<NoVisibleLabel />
+
 ## Decorations
 
 Decorative elements can be passed into the `start` or `end` slots of the range. This is useful for adding icons such as low volume or high volume icons. Since these elements are decorative, they should not be announced by assistive technology such as screen readers.
@@ -116,7 +135,9 @@ Developers can perform this migration one range at a time. While developers can
 
 ### Using the Modern Syntax
 
-Using the modern syntax involves removing the `ion-label` and passing the label directly inside of `ion-range` using `slot="label"`. The placement of the label can be configured using the `labelPlacement` property on `ion-range`.
+Using the modern syntax involves removing the `ion-label` and passing the label to `ion-range` using the `label` property. The placement of the label can be configured using the `labelPlacement` property.
+
+If custom HTML is needed for the label, it can be passed directly inside the `ion-range` using the `label` slot instead.
 
 import Migration from '@site/static/usage/v7/range/migration/index.md';
 
diff --git a/static/usage/v7/range/label-slot/angular.md b/static/usage/v7/range/label-slot/angular.md
new file mode 100644
index 00000000000..83ae393896e
--- /dev/null
+++ b/static/usage/v7/range/label-slot/angular.md
@@ -0,0 +1,7 @@
+```html
+<ion-range>
+  <div slot="label">
+    Label with <ion-text color="primary">custom HTML</ion-text>
+  </div>
+</ion-range>
+```
diff --git a/static/usage/v7/range/label-slot/demo.html b/static/usage/v7/range/label-slot/demo.html
new file mode 100644
index 00000000000..8364ee4e28c
--- /dev/null
+++ b/static/usage/v7/range/label-slot/demo.html
@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Range</title>
+    <link rel="stylesheet" href="../../../common.css" />
+    <script src="../../../common.js"></script>
+    <script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/core@7/dist/ionic/ionic.esm.js"></script>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core@7/css/ionic.bundle.css" />
+    <style>
+      ion-range {
+        max-width: 400px;
+      }
+    </style>
+  </head>
+
+  <body>
+    <ion-app>
+      <ion-content>
+        <div class="container">
+          <ion-range>
+            <div slot="label">
+              Label with <ion-text color="primary">custom HTML</ion-text>
+            </div>
+          </ion-range>
+        </div>
+      </ion-content>
+    </ion-app>
+  </body>
+</html>
diff --git a/static/usage/v7/range/basic/index.md b/static/usage/v7/range/label-slot/index.md
similarity index 84%
rename from static/usage/v7/range/basic/index.md
rename to static/usage/v7/range/label-slot/index.md
index 59922df7eda..f885a98ce72 100644
--- a/static/usage/v7/range/basic/index.md
+++ b/static/usage/v7/range/label-slot/index.md
@@ -5,4 +5,4 @@ import react from './react.md';
 import vue from './vue.md';
 import angular from './angular.md';
 
-<Playground version="7" code={{ javascript, react, vue, angular }} src="usage/v7/range/basic/demo.html" />
+<Playground version="7" code={{ javascript, react, vue, angular }} src="usage/v7/range/label-slot/demo.html" />
diff --git a/static/usage/v7/range/label-slot/javascript.md b/static/usage/v7/range/label-slot/javascript.md
new file mode 100644
index 00000000000..83ae393896e
--- /dev/null
+++ b/static/usage/v7/range/label-slot/javascript.md
@@ -0,0 +1,7 @@
+```html
+<ion-range>
+  <div slot="label">
+    Label with <ion-text color="primary">custom HTML</ion-text>
+  </div>
+</ion-range>
+```
diff --git a/static/usage/v7/range/label-slot/react.md b/static/usage/v7/range/label-slot/react.md
new file mode 100644
index 00000000000..8a3e4a8a07d
--- /dev/null
+++ b/static/usage/v7/range/label-slot/react.md
@@ -0,0 +1,14 @@
+```tsx
+import React from 'react';
+import { IonRange, IonText } from '@ionic/react';
+function Example() {
+  return (
+    <IonRange>
+      <div slot="label">
+        Label with <IonText color="primary">custom HTML</IonText>
+      </div>
+    </IonRange>
+  );
+}
+export default Example;
+```
diff --git a/static/usage/v7/range/label-slot/vue.md b/static/usage/v7/range/label-slot/vue.md
new file mode 100644
index 00000000000..56765cdd14d
--- /dev/null
+++ b/static/usage/v7/range/label-slot/vue.md
@@ -0,0 +1,18 @@
+```html
+<template>
+  <ion-range>
+    <div slot="label">
+      Label with <ion-text color="primary">custom HTML</ion-text>
+    </div>
+  </ion-range>
+</template>
+
+<script lang="ts">
+  import { IonRange, IonText } from '@ionic/vue';
+  import { defineComponent } from 'vue';
+
+  export default defineComponent({
+    components: { IonRange, IonText },
+  });
+</script>
+```
diff --git a/static/usage/v7/range/labels/angular.md b/static/usage/v7/range/labels/angular.md
index 54964fa0d0c..45532c5f917 100644
--- a/static/usage/v7/range/labels/angular.md
+++ b/static/usage/v7/range/labels/angular.md
@@ -1,17 +1,11 @@
 ```html
-<ion-range labelPlacement="start">
-  <div slot="label">Label at the Start</div>
-</ion-range>
+<ion-range labelPlacement="start" label="Label at the Start"></ion-range>
 
 <br />
 
-<ion-range labelPlacement="end">
-  <div slot="label">Label at the End</div>
-</ion-range>
+<ion-range labelPlacement="end" label="Label at the End"></ion-range>
 
 <br />
 
-<ion-range labelPlacement="fixed">
-  <div slot="label">Fixed Width Label</div>
-</ion-range>
+<ion-range labelPlacement="fixed" label="Fixed Width Label"></ion-range>
 ```
diff --git a/static/usage/v7/range/labels/demo.html b/static/usage/v7/range/labels/demo.html
index e4e1e0c57a4..b44cc98584e 100644
--- a/static/usage/v7/range/labels/demo.html
+++ b/static/usage/v7/range/labels/demo.html
@@ -20,21 +20,15 @@
       <ion-content>
         <div class="container">
           <div class="wrapper">
-            <ion-range label-placement="start">
-              <div slot="label">Label at the Start</div>
-            </ion-range>
-
+            <ion-range label-placement="start" label="Label at the Start"></ion-range>
+            
             <br />
-
-            <ion-range label-placement="end">
-              <div slot="label">Label at the End</div>
-            </ion-range>
-
+            
+            <ion-range label-placement="end" label="Label at the End"></ion-range>
+            
             <br />
-
-            <ion-range label-placement="fixed">
-              <div slot="label">Fixed Width Label</div>
-            </ion-range>
+            
+            <ion-range label-placement="fixed" label="Fixed Width Label"></ion-range>
           </div>
         </div>
       </ion-content>
diff --git a/static/usage/v7/range/labels/javascript.md b/static/usage/v7/range/labels/javascript.md
index 1f08d5d29af..9ee164f7d4d 100644
--- a/static/usage/v7/range/labels/javascript.md
+++ b/static/usage/v7/range/labels/javascript.md
@@ -1,17 +1,11 @@
 ```html
-<ion-range label-placement="start">
-  <div slot="label">Label at the Start</div>
-</ion-range>
+<ion-range label-placement="start" label="Label at the Start"></ion-range>
 
 <br />
 
-<ion-range label-placement="end">
-  <div slot="label">Label at the End</div>
-</ion-range>
+<ion-range label-placement="end" label="Label at the End"></ion-range>
 
 <br />
 
-<ion-range label-placement="fixed">
-  <div slot="label">Fixed Width Label</div>
-</ion-range>
+<ion-range label-placement="fixed" label="Fixed Width Label"></ion-range>
 ```
diff --git a/static/usage/v7/range/labels/react.md b/static/usage/v7/range/labels/react.md
index 3096d66ac6f..ef5563f178e 100644
--- a/static/usage/v7/range/labels/react.md
+++ b/static/usage/v7/range/labels/react.md
@@ -4,21 +4,15 @@ import { IonRange } from '@ionic/react';
 function Example() {
   return (
     <>
-      <IonRange labelPlacement="start">
-        <div slot="label">Label at the Start</div>
-      </IonRange>
+      <IonRange labelPlacement="start" label="Label at the Start"></IonRange>
 
       <br />
 
-      <IonRange labelPlacement="end">
-        <div slot="label">Label at the End</div>
-      </IonRange>
+      <IonRange labelPlacement="end" label="Label at the End"></IonRange>
 
       <br />
 
-      <IonRange labelPlacement="fixed">
-        <div slot="label">Fixed Width Label</div>
-      </IonRange>
+      <IonRange labelPlacement="fixed" label="Fixed Width Label"></IonRange>
     </>
   );
 }
diff --git a/static/usage/v7/range/labels/vue.md b/static/usage/v7/range/labels/vue.md
index c5346470905..53b7932edb8 100644
--- a/static/usage/v7/range/labels/vue.md
+++ b/static/usage/v7/range/labels/vue.md
@@ -1,20 +1,14 @@
 ```html
 <template>
-  <ion-range label-placement="start">
-    <div slot="label">Label at the Start</div>
-  </ion-range>
+  <ion-range label-placement="start" label="Label at the Start"></ion-range>
 
   <br />
 
-  <ion-range label-placement="end">
-    <div slot="label">Label at the End</div>
-  </ion-range>
+  <ion-range label-placement="end" label="Label at the End"></ion-range>
 
   <br />
 
-  <ion-range label-placement="fixed">
-    <div slot="label">Fixed Width Label</div>
-  </ion-range>
+  <ion-range label-placement="fixed" label="Fixed Width Label"></ion-range>
 </template>
 
 <script lang="ts">
diff --git a/static/usage/v7/range/migration/index.md b/static/usage/v7/range/migration/index.md
index efec462c3d1..4025f91bc31 100644
--- a/static/usage/v7/range/migration/index.md
+++ b/static/usage/v7/range/migration/index.md
@@ -25,9 +25,7 @@ import TabItem from '@theme/TabItem';
 
 <!-- After -->
 <ion-item>
-  <ion-range>
-    <div slot="label">Notifications</div>
-  </ion-range>
+  <ion-range label="Notifications"></ion-range>
 </ion-item>
 
 <!-- Fixed Labels -->
@@ -40,9 +38,7 @@ import TabItem from '@theme/TabItem';
 
 <!-- After -->
 <ion-item>
-  <ion-range label-placement="fixed">
-    <div slot="label">Notifications</div>
-  </ion-range>
+  <ion-range label-placement="fixed" label="Notifications"></ion-range>
 </ion-item>
 
 <!-- Range at the start of line, Label at the end of line -->
@@ -55,8 +51,23 @@ import TabItem from '@theme/TabItem';
 
 <!-- After -->
 <ion-item>
-  <ion-range label-placement="end">
-    <div slot="label">Notifications</div>
+  <ion-range label-placement="end" label="Notifications"></ion-range>
+</ion-item>
+
+<!-- Custom HTML label -->
+
+<!-- Before -->
+<ion-item>
+  <ion-label>
+    <div class="custom-label">Notifications</div>
+  </ion-label>
+  <ion-range></ion-range>
+</ion-item>
+
+<!-- After -->
+<ion-item>
+  <ion-range>
+    <div slot="label" class="custom-label">Notifications</div>
   </ion-range>
 </ion-item>
 ```
@@ -74,9 +85,7 @@ import TabItem from '@theme/TabItem';
 
 <!-- After -->
 <ion-item>
-  <ion-range>
-    <div slot="label">Notifications</div>
-  </ion-range>
+  <ion-range label="Notifications"></ion-range>
 </ion-item>
 
 <!-- Fixed Labels -->
@@ -89,9 +98,7 @@ import TabItem from '@theme/TabItem';
 
 <!-- After -->
 <ion-item>
-  <ion-range labelPlacement="fixed">
-    <div slot="label">Notifications</div>
-  </ion-range>
+  <ion-range labelPlacement="fixed" label="Notifications"></ion-range>
 </ion-item>
 
 <!-- Range at the start of line, Label at the end of line -->
@@ -104,8 +111,23 @@ import TabItem from '@theme/TabItem';
 
 <!-- After -->
 <ion-item>
-  <ion-range labelPlacement="end">
-    <div slot="label">Notifications</div>
+  <ion-range labelPlacement="end" label="Notifications"></ion-range>
+</ion-item>
+
+<!-- Custom HTML label -->
+
+<!-- Before -->
+<ion-item>
+  <ion-label>
+    <div class="custom-label">Notifications</div>
+  </ion-label>
+  <ion-range></ion-range>
+</ion-item>
+
+<!-- After -->
+<ion-item>
+  <ion-range>
+    <div slot="label" class="custom-label">Notifications</div>
   </ion-range>
 </ion-item>
 ```
@@ -123,9 +145,7 @@ import TabItem from '@theme/TabItem';
 
 {/* After */}
 <IonItem>
-  <IonRange>
-    <div slot="label">Notifications</div>
-  </IonRange>
+  <IonRange label="Notifications"></IonRange>
 </IonItem>
 
 {/* Fixed Labels */}
@@ -138,9 +158,7 @@ import TabItem from '@theme/TabItem';
 
 {/* After */}
 <IonItem>
-  <IonRange labelPlacement="fixed">
-    <div slot="label">Notifications</div>
-  </IonRange>
+  <IonRange labelPlacement="fixed" label="Notifications"></IonRange>
 </IonItem>
 
 {/* Range at the start of line, Label at the end of line */}
@@ -153,8 +171,23 @@ import TabItem from '@theme/TabItem';
 
 {/* After */}
 <IonItem>
-  <IonRange labelPlacement="end">
-    <div slot="label">Notifications</div>
+  <IonRange labelPlacement="end" label="Notifications"></IonRange>
+</IonItem>
+
+{/* Custom HTML label */}
+
+{/* Before */}
+<IonItem>
+  <IonLabel>
+    <div className="custom-label">Notifications</div>
+  </IonLabel>
+  <IonRange></IonRange>
+</IonItem>
+
+<!-- After -->
+<IonItem>
+  <IonRange>
+    <div slot="label" className="custom-label">Notifications</div>
   </IonRange>
 </IonItem>
 ```
@@ -172,9 +205,7 @@ import TabItem from '@theme/TabItem';
 
 <!-- After -->
 <ion-item>
-  <ion-range>
-    <div slot="label">Notifications</div>
-  </ion-range>
+  <ion-range label="Notifications"></ion-range>
 </ion-item>
 
 <!-- Fixed Labels -->
@@ -187,9 +218,7 @@ import TabItem from '@theme/TabItem';
 
 <!-- After -->
 <ion-item>
-  <ion-range label-placement="fixed">
-    <div slot="label">Notifications</div>
-  </ion-range>
+  <ion-range label-placement="fixed" label="Notifications"></ion-range>
 </ion-item>
 
 <!-- Range at the start of line, Label at the end of line -->
@@ -202,8 +231,23 @@ import TabItem from '@theme/TabItem';
 
 <!-- After -->
 <ion-item>
-  <ion-range label-placement="end">
-    <div slot="label">Notifications</div>
+  <ion-range label-placement="end" label="Notifications"></ion-range>
+</ion-item>
+
+<!-- Custom HTML label -->
+
+<!-- Before -->
+<ion-item>
+  <ion-label>
+    <div class="custom-label">Notifications</div>
+  </ion-label>
+  <ion-range></ion-range>
+</ion-item>
+
+<!-- After -->
+<ion-item>
+  <ion-range>
+    <div slot="label" class="custom-label">Notifications</div>
   </ion-range>
 </ion-item>
 ```
diff --git a/static/usage/v7/range/basic/angular.md b/static/usage/v7/range/no-visible-label/angular.md
similarity index 100%
rename from static/usage/v7/range/basic/angular.md
rename to static/usage/v7/range/no-visible-label/angular.md
diff --git a/static/usage/v7/range/basic/demo.html b/static/usage/v7/range/no-visible-label/demo.html
similarity index 100%
rename from static/usage/v7/range/basic/demo.html
rename to static/usage/v7/range/no-visible-label/demo.html
diff --git a/static/usage/v7/range/no-visible-label/index.md b/static/usage/v7/range/no-visible-label/index.md
new file mode 100644
index 00000000000..f23fc3fd998
--- /dev/null
+++ b/static/usage/v7/range/no-visible-label/index.md
@@ -0,0 +1,8 @@
+import Playground from '@site/src/components/global/Playground';
+
+import javascript from './javascript.md';
+import react from './react.md';
+import vue from './vue.md';
+import angular from './angular.md';
+
+<Playground version="7" code={{ javascript, react, vue, angular }} src="usage/v7/range/no-visible-label/demo.html" />
diff --git a/static/usage/v7/range/basic/javascript.md b/static/usage/v7/range/no-visible-label/javascript.md
similarity index 100%
rename from static/usage/v7/range/basic/javascript.md
rename to static/usage/v7/range/no-visible-label/javascript.md
diff --git a/static/usage/v7/range/basic/react.md b/static/usage/v7/range/no-visible-label/react.md
similarity index 100%
rename from static/usage/v7/range/basic/react.md
rename to static/usage/v7/range/no-visible-label/react.md
diff --git a/static/usage/v7/range/basic/vue.md b/static/usage/v7/range/no-visible-label/vue.md
similarity index 100%
rename from static/usage/v7/range/basic/vue.md
rename to static/usage/v7/range/no-visible-label/vue.md