feat(Progress): new component (#697)

Co-authored-by: Benjamin Canac <canacb1@gmail.com>

docs/components/content/examples/ProgressExampleAnimation.vue

@@ -0,0 +1,34 @@
+<template>
+  <UProgress class="progress">
+    <template #indicator>
+      <div class="text-right text-amber-500">
+        🔥 This is too hot!
+      </div>
+    </template>
+  </UProgress>
+</template>
+
+<style scoped>
+.progress:deep(progress:indeterminate.animation-default) {
+  &:after {
+    @apply w-full text-red-500;
+    animation: my-glow-animation 3s ease-in-out infinite;
+  }
+
+  &::-webkit-progress-value {
+    @apply w-full text-red-500;
+    animation: my-glow-animation 3s ease-in-out infinite;
+  }
+
+  &::-moz-progress-bar {
+    @apply w-full text-red-500;
+    animation: my-glow-animation 3s ease-in-out infinite;
+  }
+}
+
+@keyframes my-glow-animation {
+  50% {
+    @apply text-amber-400;
+  }
+}
+</style>

docs/components/content/examples/ProgressExampleSlotIndicator.vue

@@ -0,0 +1,25 @@
+<script setup>
+const temp = ref(35)
+
+const color = computed(() => {
+  switch (true) {
+  case temp.value < 10: return 'blue'
+  case temp.value < 20: return 'amber'
+  case temp.value < 30: return 'orange'
+  default: return 'red'
+  }
+})
+</script>
+
+<template>
+  <UProgress :value="temp" :max="40" :color="color">
+    <template #indicator="{ percent }">
+      <div class="text-right" :style="{ width: `${percent}%` }">
+        <span v-if="temp < 10" class="text-blue-500">Too cold!</span>
+        <span v-else-if="temp < 20" class="text-amber-500">Warm</span>
+        <span v-else-if="temp < 30" class="text-orange-500">Hot</span>
+        <span v-else class="text-red-500 font-bold">🔥 Too hot!</span>
+      </div>
+    </template>
+  </UProgress>
+</template>

docs/components/content/examples/ProgressExampleSlotStep.vue

@@ -0,0 +1,31 @@
+<script setup>
+const task = ref(1)
+
+const steps = [
+  'Cloning...',
+  'Migrating...',
+  'Deploying...'
+]
+</script>
+
+<template>
+  <UProgress :value="task" :max="steps" indicator>
+    <template #step-0="{ step }">
+      <span class="text-lime-500">
+        <UIcon name="i-heroicons-arrow-down-circle" /> {{ step }}
+      </span>
+    </template>
+
+    <template #step-1="{ step }">
+      <span class="text-amber-500">
+        <UIcon name="i-heroicons-circle-stack" /> {{ step }}
+      </span>
+    </template>
+
+    <template #step-2="{ step }">
+      <span class="text-blue-500">
+        <UIcon name="i-heroicons-hand-thumb-up" /> {{ step }}
+      </span>
+    </template>
+  </UProgress>
+</template>

docs/content/2.elements/10.progress.md

@@ -0,0 +1,153 @@
+---
+title: 'Progress'
+description: Show a horizontal bar to indicate task progression.
+navigation:
+  badge: New
+links:
+  - label: GitHub
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/ui/blob/dev/src/runtime/components/elements/Progress.vue
+---
+
+## Usage
+
+Pass an integer as the `value` from `0` to `100` to the Progress bar component.
+
+::component-card
+---
+props:
+  value: 70
+---
+::
+
+::callout{icon="i-heroicons-light-bulb"}
+Check out the [Range](/forms/range) component for forms.
+::
+
+### Max
+
+You may also set the `max` number to set the maximum progress value, which will be relative to 100% percent.
+
+::component-card
+---
+props:
+  value: 2
+  max: 5
+options:
+  - name: max
+    restriction: only
+    values:
+      - 3
+      - 4
+      - 5
+      - 6
+      - 7
+---
+::
+
+### Steps
+
+You can set an array of named steps in the `max` prop to show the active step, at the same time it sets the maximum value.
+
+The first step is always shown at `0%`, making the last `100%`.
+
+::component-card
+---
+props:
+  value: 0
+  max:
+    - Waiting to start
+    - Cloning...
+    - Migrating...
+    - Deployed!
+excludedProps:
+  - max
+---
+::
+
+### Progress indicator
+
+You can add a numeric indicator, which will show the percent on top the progress track.
+
+::component-card
+---
+props:
+  value: 20
+  indicator: true
+---
+::
+
+### Indeterminate
+
+By not setting a `value`, or setting it as `null`, the progress bar becomes _indeterminate_. The bar will be animated as a carousel, but you can change it using the `animation` prop for an inverse carousel, a swinging bar or an elastic bar.
+
+::component-card
+---
+baseProps:
+  value: null
+props:
+  animation: 'carousel'
+options:
+  - name: animation
+    restriction: only
+    values:
+      - 'carousel'
+      - 'carousel-inverse'
+      - 'swing'
+      - 'elastic'
+---
+::
+
+### Size
+
+Use the `size` prop to change the size of the progress bar.
+
+::component-card
+---
+baseProps:
+  value: 70
+props:
+  size: 'sm'
+  indicator: false
+excludedProps:
+  - value
+---
+::
+
+### Style
+
+Use the `color` prop to change the visual style of the Progress bar. The `color` can be any color from the `ui.colors` object.
+
+::component-card
+---
+baseProps:
+  value: 70
+props:
+  color: 'primary'
+  indicator: false
+excludedProps:
+  - modelValue
+---
+::
+
+## Slots
+
+### `indicator`
+
+You can use the `#indicator` slot to show a custom indicator above the progress bar. It receives the current `percent` of progress.
+
+:component-example{component="progress-example-slot-indicator"}
+
+### `step-<index>`
+
+Use the `#step-<index>` to alter the HTML being shown for each step.
+
+:component-example{component="progress-example-slot-step"}
+
+## Props
+
+:component-props
+
+## Preset
+
+:component-preset

src/colors.ts

@@ -171,6 +171,12 @@ const safelistByComponent = {
     pattern: new RegExp(`ring-(${colorsAsRegex})-500`),
     variants: ['focus-visible']
   }],
+  progress: (colorsAsRegex) => [{
+    pattern: new RegExp(`text-(${colorsAsRegex})-400`),
+    variants: ['dark']
+  }, {
+    pattern: new RegExp(`text-(${colorsAsRegex})-500`)
+  }],
   notification: (colorsAsRegex) => [{
     pattern: new RegExp(`bg-(${colorsAsRegex})-400`),
     variants: ['dark']

src/runtime/components/elements/Progress.vue

@@ -0,0 +1,308 @@
+<template>
+  <div :class="ui.wrapper" v-bind="attrs">
+    <slot v-if="indicator || $slots.indicator" name="indicator" v-bind="{ percent }">
+      <div v-if="!isSteps" :class="indicatorContainerClass" :style="{ width: `${percent}%` }">
+        <div :class="indicatorClass">
+          {{ Math.round(percent) }}%
+        </div>
+      </div>
+    </slot>
+
+    <progress :class="progressClass" v-bind="{ value, max: realMax }">
+      {{ Math.round(percent) }}%
+    </progress>
+
+    <div v-if="isSteps" :class="stepsClass">
+      <div v-for="(step, index) in max" :key="index" :class="stepClasses(index)">
+        <slot :name="`step-${index}`" v-bind="{ step }">
+          {{ step }}
+        </slot>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script lang="ts">
+import { computed, defineComponent, toRef } from 'vue'
+import type { PropType } from 'vue'
+import { twJoin } from 'tailwind-merge'
+import { useUI } from '../../composables/useUI'
+import { mergeConfig } from '../../utils'
+import type { Strategy, ProgressSize, ProgressAnimation } from '../../types'
+// @ts-expect-error
+import appConfig from '#build/app.config'
+import { progress } from '#ui/ui.config'
+
+const config = mergeConfig<typeof progress>(appConfig.ui.strategy, appConfig.ui.progress, progress)
+
+export default defineComponent({
+  inheritAttrs: false,
+  props: {
+    value: {
+      type: [Number, null, undefined],
+      default: null
+    },
+    max: {
+      type: [Number, Array<any>],
+      default: 100
+    },
+    indicator: {
+      type: Boolean,
+      default: false
+    },
+    animation: {
+      type: String as PropType<ProgressAnimation>,
+      default: () => config.default.animation,
+      validator (value: string) {
+        return Object.keys(config.animation).includes(value)
+      }
+    },
+    size: {
+      type: String as PropType<ProgressSize>,
+      default: () => config.default.size,
+      validator (value: string) {
+        return Object.keys(config.progress.size).includes(value)
+      }
+    },
+    color: {
+      type: String,
+      default: () => config.default.color,
+      validator (value: string) {
+        return appConfig.ui.colors.includes(value)
+      }
+    },
+    class: {
+      type: [String, Object, Array] as PropType<any>,
+      default: undefined
+    },
+    ui: {
+      type: Object as PropType<Partial<typeof config & { strategy?: Strategy }>>,
+      default: undefined
+    }
+  },
+  setup (props) {
+    const { ui, attrs } = useUI('progress', toRef(props, 'ui'), config, toRef(props, 'class'))
+
+    const indicatorContainerClass = computed(() => {
+      return twJoin(
+        ui.value.indicator.container.base,
+        ui.value.indicator.container.width,
+        ui.value.indicator.container.transition
+      )
+    })
+
+    const indicatorClass = computed(() => {
+      return twJoin(
+        ui.value.indicator.align,
+        ui.value.indicator.width,
+        ui.value.indicator.color,
+        ui.value.indicator.size[props.size]
+      )
+    })
+
+    const progressClass = computed(() => {
+      const classes = [
+        ui.value.progress.base,
+        ui.value.progress.width,
+        ui.value.progress.size[props.size],
+        ui.value.progress.rounded,
+        ui.value.progress.track,
+        ui.value.progress.bar,
+        // Intermediate class to allow thumb ring or background color (set to `current`) as it's impossible to safelist with arbitrary values
+        ui.value.progress.color?.replaceAll('{color}', props.color),
+        ui.value.progress.background,
+        ui.value.progress.indeterminate.base,
+        ui.value.progress.indeterminate.rounded
+      ]
+
+      if (isIndeterminate.value) {
+        classes.push(ui.value.animation[props.animation])
+      }
+
+      return twJoin(...classes)
+    })
+
+    const stepsClass = computed(() => {
+      return twJoin(
+        ui.value.steps.base,
+        ui.value.steps.color?.replaceAll('{color}', props.color),
+        ui.value.steps.size[props.size]
+      )
+    })
+
+    const stepClass = computed(() => {
+      return twJoin(
+        ui.value.step.base,
+        ui.value.step.align
+      )
+    })
+
+    const stepActiveClass = computed(() => {
+      return twJoin(
+        ui.value.step.active
+      )
+    })
+
+    const stepFirstClass = computed(() => {
+      return twJoin(
+        ui.value.step.first
+      )
+    })
+
+    function isActive (index: number) {
+      return index === Number(props.value)
+    }
+
+    function isFirst (index: number) {
+      return index === 0
+    }
+
+    function stepClasses (index: string|number) {
+      index = Number(index)
+
+      const classes = [stepClass.value]
+
+      if (isFirst(index)) {
+        classes.push(stepFirstClass.value)
+      }
+
+      if (isActive(index)) {
+        classes.push(stepActiveClass.value)
+      }
+
+      return classes.join(' ')
+    }
+
+    const isIndeterminate = computed(() => [undefined, null].includes(props.value))
+    const isSteps = computed(() => Array.isArray(props.max))
+
+    const realMax = computed(() => {
+      if (isIndeterminate.value) {
+        return null
+      }
+
+      if (Array.isArray(props.max)) {
+        return props.max.length - 1
+      }
+
+      return Number(props.max)
+    })
+
+    const percent = computed(() => {
+      switch (true) {
+      case props.value < 0: return 0
+      case props.value > 100: return 100
+      default: return (props.value / realMax.value) * 100
+      }
+    })
+
+    return {
+      // eslint-disable-next-line vue/no-dupe-keys
+      ui,
+      attrs,
+      indicatorContainerClass,
+      indicatorClass,
+      progressClass,
+      stepsClass,
+      stepClasses,
+      isIndeterminate,
+      isSteps,
+      realMax,
+      percent
+    }
+  }
+})
+</script>
+
+<style scoped>
+/** These styles are required to animate the bar */
+progress:indeterminate {
+  @apply relative;
+
+  &:after {
+    @apply content-[''];
+    @apply absolute inset-0;
+    @apply bg-current;
+  }
+
+  &::-webkit-progress-value {
+    @apply bg-current;
+  }
+
+  &::-moz-progress-bar {
+    @apply bg-current;
+  }
+
+  &.bar-animation-carousel {
+    &:after {
+      animation: carousel 2s ease-in-out infinite;
+    }
+    &::-webkit-progress-value {
+      animation: carousel 2s ease-in-out infinite;
+    }
+    &::-moz-progress-bar {
+      animation: carousel 2s ease-in-out infinite;
+    }
+  }
+
+  &.bar-animation-carousel-inverse {
+    &:after {
+      animation: carousel-inverse 2s ease-in-out infinite;
+    }
+    &::-webkit-progress-value {
+      animation: carousel-inverse 2s ease-in-out infinite;
+    }
+    &::-moz-progress-bar {
+      animation: carousel-inverse 2s ease-in-out infinite;
+    }
+  }
+
+  &.bar-animation-swing {
+    &:after {
+      animation: swing 3s ease-in-out infinite;
+    }
+    &::-webkit-progress-value {
+      animation: swing 3s ease-in-out infinite;
+    }
+    &::-moz-progress-bar {
+      animation: swing 3s ease-in-out infinite;
+    }
+  }
+
+  &.bar-animation-elastic {
+    &::after {
+      animation: elastic 3s ease-in-out infinite;
+    }
+    &::-webkit-progress-value {
+      animation: elastic 3s ease-in-out infinite;
+    }
+    &::-moz-progress-bar {
+      animation: elastic 3s ease-in-out infinite;
+    }
+  }
+}
+
+@keyframes carousel {
+  0%, 100% { width: 50% }
+  0% { transform: translateX(-100%) }
+  100% { transform: translateX(200%) }
+}
+
+@keyframes carousel-inverse {
+  0%, 100% { width: 50% }
+  0% { transform: translateX(200%) }
+  100% { transform: translateX(-100%) }
+}
+
+@keyframes swing {
+  0%, 100% { width: 50% }
+  0%, 100% { transform: translateX(-25%) }
+  50% { transform: translateX(125%) }
+}
+
+@keyframes elastic {
+  /* Firefox doesn't do "margin: 0 auto", we have to play with margin-left */
+  0%, 100% { width: 50%; margin-left: 25%; }
+  50% { width: 90%; margin-left: 5% }
+}
+</style>

src/runtime/types/index.d.ts

@@ -9,6 +9,7 @@ export * from './form'
 export * from './link'
 export * from './notification'
 export * from './popper'
+export * from './progress'
 export * from './tabs'
 export * from './vertical-navigation'
 export * from './utils'

src/runtime/types/progress.ts

@@ -0,0 +1,4 @@
+import { progress } from '../ui.config'
+
+export type ProgressSize = keyof typeof progress.progress.size
+export type ProgressAnimation = keyof typeof progress.animation

src/runtime/ui.config.ts

@@ -384,6 +384,78 @@ export const kbd = {
   }
 }
 
+export const progress = {
+  wrapper: 'w-full flex flex-col gap-2',
+  indicator: {
+    container: {
+      base: 'flex flex-row justify-end',
+      width: 'min-w-fit',
+      transition: 'transition-all'
+    },
+    align: 'text-end',
+    width: 'w-fit',
+    color: 'text-gray-400 dark:text-gray-500',
+    size: {
+      '2xs': 'text-xs',
+      xs: 'text-xs',
+      sm: 'text-sm',
+      md: 'text-sm',
+      lg: 'text-sm',
+      xl: 'text-base'
+    }
+  },
+  progress: {
+    base: 'block appearance-none border-none overflow-hidden',
+    width: 'w-full [&::-webkit-progress-bar]:w-full',
+    size: {
+      xs: 'h-px',
+      sm: 'h-1',
+      md: 'h-2',
+      lg: 'h-3',
+      xl: 'h-4',
+      '2xl': 'h-6'
+    },
+    rounded: 'rounded-full [&::-webkit-progress-bar]:rounded-full',
+    track: '[&::-webkit-progress-bar]:bg-gray-200 [&::-webkit-progress-bar]:dark:bg-gray-700 [@supports(selector(&::-moz-progress-bar))]:bg-gray-200 [@supports(selector(&::-moz-progress-bar))]:dark:bg-gray-700',
+    bar: '[&::-webkit-progress-value]:rounded-full [&::-webkit-progress-value]:transition-all [&::-webkit-progress-value]:ease-in-out [&::-moz-progress-bar]:rounded-full',
+    color: 'text-{color}-500 dark:text-{color}-400',
+    background: '[&::-webkit-progress-value]:bg-current [&::-moz-progress-bar]:bg-current',
+    indeterminate: {
+      base: 'indeterminate:relative',
+      rounded: 'indeterminate:after:rounded-full [&:indeterminate::-webkit-progress-value]:rounded-full [&:indeterminate::-moz-progress-bar]:rounded-full'
+    }
+  },
+  steps: {
+    base: 'grid grid-cols-1',
+    color: 'text-{color}-500 dark:text-{color}-400',
+    size: {
+      '2xs': 'text-xs',
+      xs: 'text-xs',
+      sm: 'text-sm',
+      md: 'text-sm',
+      lg: 'text-sm',
+      xl: 'text-base'
+    }
+  },
+  step: {
+    base: 'transition-all opacity-0 truncate row-start-1 col-start-1',
+    align: 'text-end',
+    active: 'opacity-100',
+    first: 'text-gray-500'
+  },
+  animation: {
+    carousel: 'bar-animation-carousel',
+    'carousel-inverse': 'bar-animation-carousel-inverse',
+    swing: 'bar-animation-swing',
+    elastic: 'bar-animation-elastic'
+  },
+  default: {
+    color: 'primary',
+    size: 'md',
+    animation: 'carousel'
+  }
+}
+
 // Forms
 
 export const input = {