Migrating from ghl-ui Progress to HighRise Progress

This guide provides a comprehensive overview of migrating from the ghl-ui Progress component to the new HighRise Progress component.

Component Implementation Changes

Import Changes

- import { UIProgress } from '@gohighlevel/ghl-ui'
+ import { HLProgress } from '@platform-ui/highrise'

Basic Usage Changes

- <UIProgress
-   :percentage="60"
-   type="line"
-   indicator-placement="outside"
- />

+ <HLProgress
+   id="my-progress"
+   :percentage="60"
+   type="line"
+   value-placement="outside"
+   label="Progress"
+ />

Line Progress Example

- <UIProgress
-   :percentage="75"
-   type="line"
-   status="success"
- />

+ <HLProgress
+   id="line-progress"
+   :percentage="75"
+   type="line"
+   status="success"
+   label="Upload Progress"
+   helper-text="75 of 100 MB uploaded"
+   value-placement="outside"
+ />

Circle Progress Example

- <UIProgress
-   :percentage="80"
-   type="circle"
-   :processing="true"
- />

+ <HLProgress
+   id="circle-progress"
+   :percentage="80"
+   type="circle"
+   :processing="true"
+   dashboard-size="md"
+   label="Processing"
+ />

Dashboard Progress Example

- <UIProgress
-   :percentage="90"
-   type="dashboard"
-   :gap-degree="120"
- />

+ <HLProgress
+   id="dashboard-progress"
+   :percentage="90"
+   type="dashboard"
+   :gap-degree="120"
+   dashboard-size="lg"
+   label="Storage Used"
+ />

Props Changes

Core Props

ghl-ui Prop	HighRise Prop	Notes
-	id	Required string for accessibility
percentage	percentage	Number or number[] for multiple circles
type	type	'line', 'circle', 'dashboard', 'multiple-circle'
status	status	'success', 'error', 'warning', 'info', 'default'
indicatorPlacement	valuePlacement	'inside' or 'outside' (default: 'inside')
-	label	Optional label text
-	helperText	Optional helper text
-	dashboardSize	'2xs', 'xs', 'sm', 'md', 'lg' (default: 'sm')
processing	processing	Boolean to show spinning animation

Style Props

ghl-ui Prop	HighRise Prop	Default	Notes
strokeWidth	strokeWidth	7	Width of progress bar
color	color	-	String or string[] for gradient
railColor	railColor	-	Background track color
height	height	-	Height for line progress
borderRadius	borderRadius	-	Border radius for line type
circleGap	circleGap	1	Gap between circles in multiple-circle
gapDegree	gapDegree	75	Gap degree for dashboard (0-360)
offsetDegree	offsetDegree	0	Offset degree for circle progress
-	railStyle	-	Custom styles for rail
-	fillBorderRadius	-	Border radius for progress fill

Advanced Examples

Interactive Progress with Status

<template>
  <HLProgress
    id="interactive-progress"
    :percentage="progress"
    type="line"
    :status="status"
    :processing="isProcessing"
    label="Download Progress"
    :helper-text="helperText"
    value-placement="outside"
  />
</template>

<script setup>
import { ref, computed } from 'vue'

const progress = ref(0)
const isProcessing = ref(true)

const status = computed(() => {
  if (progress.value === 100) return 'success'
  if (progress.value < 30) return 'error'
  return 'default'
})

const helperText = computed(() => {
  if (progress.value === 100) return 'Download complete!'
  if (progress.value < 30) return 'Poor connection...'
  return `${progress.value}MB of 100MB downloaded`
})

// Simulate progress
const interval = setInterval(() => {
  if (progress.value < 100) {
    progress.value += 10
  } else {
    isProcessing.value = false
    clearInterval(interval)
  }
}, 1000)
</script>

Multiple Circle Progress with Custom Colors

<template>
  <HLProgress
    id="multi-circle-progress"
    :percentage="[30, 50, 70, 90]"
    type="multiple-circle"
    :color="colors"
    :rail-style="railStyles"
    dashboard-size="lg"
    label="Team Progress"
  >
    <div class="text-center">Team Stats</div>
  </HLProgress>
</template>

<script setup>
const colors = ['var(--primary-500)', 'var(--success-500)', 'var(--warning-500)', 'var(--error-500)']

const railStyles = colors.map(color => ({
  stroke: color,
  opacity: 0.2,
}))
</script>

Breaking Changes

1. Required ID Prop: The id prop is now required for accessibility purposes
2. Value Placement: indicatorPlacement prop has been renamed to valuePlacement
3. Dashboard Sizing: New dashboardSize prop replaces fixed sizes
4. Helper Text: New structured way to display additional text with label and helperText props
5. Multiple Circle Support: Enhanced support for multiple progress circles with new configuration options
6. Processing State: New processing prop for showing loading animations
7. Theme Integration: New color system integrated with HighRise theme variables
8. Accessibility: Enhanced ARIA support and keyboard navigation

Best Practices

1. Always provide a unique id prop for accessibility
2. Use appropriate progress types based on context:
   • line for general progress indicators
   • circle for compact displays
   • dashboard for metrics and stats
   • multiple-circle for comparing multiple values
3. Provide meaningful labels and helper text
4. Use appropriate status colors to indicate state
5. Consider mobile responsiveness when choosing sizes
6. Use processing state for active operations
7. Implement proper error handling
8. Follow accessibility guidelines
9. Use consistent styling across your application
10. Choose appropriate value placement based on available space

Additional Features

1. Enhanced Styling: Built-in support for theme variables
2. Auto-sizing: Intelligent size handling for different types
3. Processing Animation: Built-in loading animations
4. Multiple Progress: Support for multiple progress circles
5. Accessibility: Improved ARIA attributes and keyboard navigation
6. Helper Text: Structured way to display additional information
7. Theme Integration: Consistent styling with HighRise components
8. Custom Content: Slot support for custom indicators
9. Responsive Design: Flexible sizing options
10. Type Safety: Full TypeScript support