From 000494e0a480f55a7a20369dbdddb4d161988912 Mon Sep 17 00:00:00 2001
From: Dan Popescu <pdan.popescu@gmail.com>
Date: Tue, 22 Feb 2022 01:01:27 +0200
Subject: [PATCH] feat(QStep): simplify rules to apply *-color and *-icon props
 and document the rules #12547, #15259

---
 docs/src/examples/QStepper/HeaderClass.vue    |  26 ++-
 docs/src/pages/vue-components/stepper.md      |  19 +-
 .../pages/components/stepper-icons-colors.vue | 204 ++++++++++++++++++
 ui/src/components/stepper/QStep.json          |   2 +-
 ui/src/components/stepper/StepHeader.js       |  68 +++---
 5 files changed, 274 insertions(+), 45 deletions(-)
 create mode 100644 ui/dev/src/pages/components/stepper-icons-colors.vue

diff --git a/docs/src/examples/QStepper/HeaderClass.vue b/docs/src/examples/QStepper/HeaderClass.vue
index 838f2916d0cf..aa2d6b2e9a54 100644
--- a/docs/src/examples/QStepper/HeaderClass.vue
+++ b/docs/src/examples/QStepper/HeaderClass.vue
@@ -4,7 +4,7 @@
       v-model="step"
       ref="stepper"
       color="primary"
-      header-class="text-bold"
+      header-class="stepper-example__header--emphasized"
       animated
     >
       <q-step
@@ -12,6 +12,7 @@
         title="Select campaign settings"
         icon="settings"
         :done="step > 1"
+        :error="step > 1"
       >
         For each ad campaign that you create, you can control how much you're willing to
         spend on clicks and conversions, which networks and geographical locations you want
@@ -57,6 +58,29 @@
   </div>
 </template>
 
+<style lang="sass" scoped>
+:deep(.stepper-example__header--emphasized)
+  font-weight: bold
+
+  .q-stepper__tab
+    padding: 8px 16px
+
+  .q-stepper__dot
+    background-color: transparent
+    font-size: 18px
+    width: 28px
+    min-width: 28px
+    height: 28px
+    box-shadow: 0 0 4px 2px currentColor
+
+    span
+      color: currentColor
+
+  .q-stepper__tab--error-with-icon
+    .q-stepper__dot
+      box-shadow: none
+</style>
+
 <script>
 export default {
   data () {
diff --git a/docs/src/pages/vue-components/stepper.md b/docs/src/pages/vue-components/stepper.md
index dd727c2bf0dd..1c2fa1e4ce02 100644
--- a/docs/src/pages/vue-components/stepper.md
+++ b/docs/src/pages/vue-components/stepper.md
@@ -67,11 +67,26 @@ More info: [Quasar Screen Plugin](/options/screen-plugin).
 
 ### Style
 
-Play with coloring using the `*-icon` and `*-color` props (on QStepper or override on specific QStep).
+Play with coloring using the `*-icon` and `*-color` props.
+
+Starting with Quasar v1.18.6 the way `*-icon` and `*-color` props are applied on the header is:
+* Props on QStep override props on QStepper (`icon` and `color` on QStep override `inactive-color` and `inactive-icon` on QStepper)
+* Color:
+  1. If QStep is disabled the color for `title` and `caption` is light grey
+  2. If QStep has error the color is `error-color` (default `negative`)
+  3. If QStep is active the color is `active-color` (default `primary`)
+  4. If QStep is done the color is `done-color` (default `primary`)
+  5. Else the color is `color` from QStep or `inactive-color` from QStepper (default `grey-6`)
+* Icon:
+  1. If QStep is active the icon is `active-icon` (default `$q.iconset.stepper.active`)
+  2. If QStep has error the icon is `error-icon` (default `$q.iconset.stepper.error`)
+  3. If QStep is done the icon is `done-icon` (default `$q.iconset.stepper.done`)
+  4. Else the icon is `icon` from QStep or `inactive-icon` from QStepper (default `none`)
+  5. If the icon is `none` the `prefix` prop is displayed
 
 <doc-example title="Coloring" file="QStepper/Coloring" />
 
-You can also use `prefix` prop (max 2 characters) instead of an icon for each step's header. This will be displayed if the step is not currently being edited and it isn't marked with error or as "done".
+You can also use `prefix` prop (max 2 characters) instead of an icon for each step's header. This will be displayed if the step is not currently active and it isn't marked with error or as "done", or if the specific icon for the state is "none".
 
 <doc-example title="Step prefix" file="QStepper/Prefix" />
 
diff --git a/ui/dev/src/pages/components/stepper-icons-colors.vue b/ui/dev/src/pages/components/stepper-icons-colors.vue
new file mode 100644
index 000000000000..13056b5d447b
--- /dev/null
+++ b/ui/dev/src/pages/components/stepper-icons-colors.vue
@@ -0,0 +1,204 @@
+<template>
+  <div class="q-pa-md q-gutter-y-sm">
+    <q-card>
+      <q-card-section>
+        <q-card-section class="items-center q-col-gutter-md" style="flex-wrap: wrap" horizontal>
+          <div class="col-6 col-md-3 column no-wrap q-gutter-y-sm" v-for="prop in stepperProps" :key="prop">
+            <q-toggle
+              v-model="stepper[`${prop}Color`]"
+              :true-value="getProp(`${prop}Color`)"
+              :false-value="null"
+              :color="getProp(`${prop}Color`)"
+              :label="`${prop} color`"
+              size="48px"
+              dense
+            />
+            <q-toggle
+              v-model="stepper[`${prop}Icon`]"
+              toggle-indeterminate
+              :true-value="getProp(`${prop}Icon`)"
+              indeterminate-value="none"
+              :checked-icon="getProp(`${prop}Icon`)"
+              indeterminate-icon="looks_one"
+              unchecked-icon="library_add_check"
+              :false-value="null"
+              color="dark"
+              :label="`${prop} icon`"
+              size="48px"
+              dense
+            />
+          </div>
+        </q-card-section>
+      </q-card-section>
+
+      <q-card-section v-for="step in steps" :key="step.name">
+        <q-card-section class="items-center q-col-gutter-md" style="flex-wrap: wrap" horizontal>
+          <div class="col column no-wrap q-gutter-y-xs">
+            <div class="text-center">Step {{ step.name }}</div>
+            <q-toggle
+              v-model="step.color"
+              :true-value="stepColor"
+              :false-value="null"
+              :color="stepColor"
+              label="step color"
+              size="48px"
+              dense
+            />
+            <q-toggle
+              v-model="step.icon"
+              toggle-indeterminate
+              :true-value="stepIcon"
+              indeterminate-value="none"
+              :checked-icon="stepIcon"
+              indeterminate-icon="looks_one"
+              unchecked-icon="library_add_check"
+              :false-value="null"
+              color="dark"
+              label="step icon"
+              size="48px"
+              dense
+            />
+          </div>
+
+          <div class="col column no-wrap q-gutter-y-xs">
+            <q-toggle v-model="step.disable" color="dark" label="isDisabled" size=48px dense />
+            <q-toggle v-model="step.error" color="negative" label="isError" size=48px dense />
+            <q-toggle v-model="step.done" color="positive" label="isDone" size=48px dense />
+          </div>
+
+          <div class="col-6 col-md-3 column no-wrap q-gutter-y-sm" v-for="prop in stepProps" :key="prop">
+            <q-toggle
+              v-model="step[`${prop}Color`]"
+              :true-value="getProp(`${prop}Color`)"
+              :false-value="null"
+              :color="getProp(`${prop}Color`)"
+              :label="`${prop} color`"
+              size="48px"
+              dense
+            />
+            <q-toggle
+              v-model="step[`${prop}Icon`]"
+              toggle-indeterminate
+              :true-value="getProp(`${prop}Icon`)"
+              indeterminate-value="none"
+              :checked-icon="getProp(`${prop}Icon`)"
+              indeterminate-icon="looks_one"
+              unchecked-icon="library_add_check"
+              :false-value="null"
+              color="dark"
+              :label="`${prop} icon`"
+              size="48px"
+              dense
+            />
+          </div>
+        </q-card-section>
+
+      </q-card-section>
+
+      <q-card-actions align="right">
+        <q-btn flat color="primary" label="Reset" />
+      </q-card-actions>
+    </q-card>
+    <div class="column no-wrap q-gutter-y-sm">
+    </div>
+
+    <q-stepper
+      header-nav
+      animated
+      v-bind="mapBind(stepper)"
+      @input="step => { this.stepper.value = step }"
+    >
+      <q-step
+        v-for="step in steps"
+        :key="step.name"
+        v-bind="mapBind(step)"
+      >{{ lorem }}</q-step>
+    </q-stepper>
+  </div>
+</template>
+
+<script>
+function initSteps (steps) {
+  return Array(steps).fill(null).map((_, i) => ({
+    name: i + 1,
+    prefix: i + 1,
+    title: `Step ${i + 1}`,
+    caption: `Step ${i + 1} caption`,
+
+    done: false,
+    error: false,
+    disable: false,
+
+    color: null,
+    icon: null,
+
+    errorColor: null,
+    activeColor: null,
+    doneColor: null,
+
+    errorIcon: null,
+    activeIcon: null,
+    doneIcon: null
+  }))
+}
+
+function initStepper () {
+  return {
+    value: 1,
+
+    errorColor: null,
+    activeColor: null,
+    doneColor: null,
+    inactiveColor: null,
+
+    errorIcon: null,
+    activeIcon: null,
+    doneIcon: null,
+    inactiveIcon: null
+  }
+}
+
+export default {
+  data () {
+    return {
+      lorem: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.',
+
+      steps: initSteps(3),
+      stepper: initStepper(),
+
+      stepProps: ['error', 'active', 'done'],
+      stepperProps: ['inactive', 'error', 'active', 'done'],
+
+      stepColor: 'cyan-7',
+      errorColor: 'red-7',
+      activeColor: 'purple-7',
+      doneColor: 'green-7',
+      inactiveColor: 'blue-grey-6',
+
+      stepIcon: 'star',
+      errorIcon: 'error_outline',
+      activeIcon: 'visibility',
+      doneIcon: 'verified',
+      inactiveIcon: 'schedule'
+    }
+  },
+
+  methods: {
+    reset () {
+      this.steps = initSteps(3)
+      this.steper = initStepper()
+    },
+
+    getProp (prop) {
+      return this[prop]
+    },
+
+    mapBind (props) {
+      return Object.keys(props).reduce((acc, key) => {
+        acc[key] = props[key] === null ? void 0 : props[key]
+        return acc
+      }, {})
+    }
+  }
+}
+</script>
diff --git a/ui/src/components/stepper/QStep.json b/ui/src/components/stepper/QStep.json
index 86249a859691..d32cf75997b8 100644
--- a/ui/src/components/stepper/QStep.json
+++ b/ui/src/components/stepper/QStep.json
@@ -40,7 +40,7 @@
 
     "prefix": {
       "type": [ "String", "Number" ],
-      "desc": "Step's prefix (max 2 characters) which replaces the icon if step does not has error, is being edited or is marked as done",
+      "desc": "Step's prefix (max 2 characters) which replaces the icon if the step is not currently active and it isn't marked with error or as 'done', or if the specific icon for the state is 'none'",
       "examples": [
         "1", "2", "A", "B"
       ],
diff --git a/ui/src/components/stepper/StepHeader.js b/ui/src/components/stepper/StepHeader.js
index f22c163628d4..3547d30b8a57 100644
--- a/ui/src/components/stepper/StepHeader.js
+++ b/ui/src/components/stepper/StepHeader.js
@@ -22,15 +22,15 @@ export default Vue.extend({
   },
 
   computed: {
-    isActive () {
-      return this.stepper.value === this.step.name
-    },
-
     isDisable () {
       const opt = this.step.disable
       return opt === true || opt === ''
     },
 
+    isActive () {
+      return this.isDisable !== true && this.stepper.value === this.step.name
+    },
+
     isError () {
       const opt = this.step.error
       return opt === true || opt === ''
@@ -38,7 +38,7 @@ export default Vue.extend({
 
     isDone () {
       const opt = this.step.done
-      return this.isDisable === false && (opt === true || opt === '')
+      return opt === true || opt === ''
     },
 
     headerNav () {
@@ -52,58 +52,40 @@ export default Vue.extend({
     },
 
     hasPrefix () {
-      return this.step.prefix &&
-        (this.isActive === false || this.stepper.activeIcon === 'none') &&
-        (this.isError === false || this.stepper.errorIcon === 'none') &&
-        (this.isDone === false || this.stepper.doneIcon === 'none')
+      return this.step.prefix && this.icon === void 0
     },
 
     icon () {
-      const defaultIcon = this.step.icon || this.stepper.inactiveIcon
+      let icon
 
       if (this.isActive === true) {
-        const icon = this.step.activeIcon || this.stepper.activeIcon
-        return icon === 'none'
-          ? defaultIcon
-          : icon || this.$q.iconSet.stepper.active
+        icon = this.__getProp('activeIcon', this.$q.iconSet.stepper.active)
       }
-
-      if (this.isError === true) {
-        const icon = this.step.errorIcon || this.stepper.errorIcon
-        return icon === 'none'
-          ? defaultIcon
-          : icon || this.$q.iconSet.stepper.error
+      else if (this.isError === true) {
+        icon = this.__getProp('errorIcon', this.$q.iconSet.stepper.error)
       }
-
-      if (this.isDisable === false && this.isDone === true) {
-        const icon = this.step.doneIcon || this.stepper.doneIcon
-        return icon === 'none'
-          ? defaultIcon
-          : icon || this.$q.iconSet.stepper.done
+      else if (this.isDone === true) {
+        icon = this.__getProp('doneIcon', this.$q.iconSet.stepper.done)
+      }
+      else {
+        icon = this.step.icon || this.stepper.inactiveIcon
       }
 
-      return defaultIcon
+      return icon === 'none' ? void 0 : icon
     },
 
     color () {
-      const errorColor = this.isError === true
-        ? this.step.errorColor || this.stepper.errorColor
-        : void 0
+      if (this.isError === true) {
+        return this.__getProp('errorColor')
+      }
 
       if (this.isActive === true) {
-        const color = this.step.activeColor || this.stepper.activeColor || this.step.color
-        return color !== void 0
-          ? color
-          : errorColor
-      }
-      if (errorColor !== void 0) {
-        return errorColor
-      }
-      if (this.isDisable === false && this.isDone === true) {
-        return this.step.doneColor || this.stepper.doneColor || this.step.color || this.stepper.inactiveColor
+        return this.__getProp('activeColor')
       }
 
-      return this.step.color || this.stepper.inactiveColor
+      return this.isDisable === false && this.isDone === true
+        ? this.__getProp('doneColor')
+        : this.step.color || this.stepper.inactiveColor
     },
 
     classes () {
@@ -129,6 +111,10 @@ export default Vue.extend({
       if (e.keyCode === 13 && this.isActive === false) {
         this.stepper.goTo(this.step.name)
       }
+    },
+
+    __getProp (prop, fallback) {
+      return this.step[prop] || this.stepper[prop] || fallback
     }
   },