Migrating from ghl-ui Popover to HighRise Popover

The Popover component from ghl-ui has been reimplemented in HighRise UI with improved TypeScript support, better accessibility, and enhanced functionality. This guide will help you migrate your popovers to use the new HLPopover component.

Import Changes

- import { UIPopover } from '@gohighlevel/ghl-ui'
+ import { HLPopover } from '@platform-ui/highrise'

Basic Usage Changes

- <UIPopover
-   trigger="click"
-   placement="bottom"
- >
-   <template #trigger>
-     <UIButton>Click me</UIButton>
-   </template>
-   <div>Popover content</div>
- </UIPopover>

+ <HLPopover
+   id="my-popover"
+   trigger="click"
+   placement="bottom"
+   :show-arrow="false"
+ >
+   <template #trigger>
+     <HLButton id="popover-trigger">Click me</HLButton>
+   </template>
+   <template #header>
+     <div>Header content</div>
+   </template>
+   <div>Popover content</div>
+   <template #footer>
+     <div>Footer content</div>
+   </template>
+ </HLPopover>

Props Changes

Required Props

Prop	Type	Notes
id	string	Required for accessibility

Optional Props

ghl-ui Prop	HighRise Prop	Type	Default	Notes
trigger	trigger	'click' | 'hover' | 'focus' | 'manual'	'click'	Trigger mode
placement	placement	'top' | 'bottom' | 'left' | 'right' + modifiers	'bottom'	More placement options available
showArrow	showArrow	boolean	false	Show/hide popover arrow
width	width	number | 'trigger'	-	Width of the popover
-	contentClass	string	-	Custom class for content
-	headerClass	string	-	Custom class for header
-	footerClass	string	-	Custom class for footer

Slot Changes

Slot Name	Description
trigger	Element that triggers the popover
header	Content to be displayed in popover header
default	Main content of the popover
footer	Content to be displayed in popover footer

Examples

Basic Popover

<template>
  <HLPopover id="basic-popover" trigger="click" placement="bottom">
    <template #trigger>
      <HLButton id="popover-trigger">Click me</HLButton>
    </template>
    <div class="p-4">
      <p>This is a basic popover content.</p>
    </div>
  </HLPopover>
</template>

<script setup>
import { HLPopover, HLButton } from '@platform-ui/highrise'
</script>

With Header and Footer

<template>
  <HLPopover id="advanced-popover" trigger="hover" placement="right" content-class="p-4" header-class="p-2" footer-class="p-2">
    <template #trigger>
      <HLButton id="popover-trigger">Hover me</HLButton>
    </template>
    <template #header>
      <h3>Popover Title</h3>
    </template>
    <div>
      <p>This is the main content of the popover.</p>
      <p>You can add multiple elements here.</p>
    </div>
    <template #footer>
      <HLButton id="popover-action" size="sm">Action</HLButton>
    </template>
  </HLPopover>
</template>

Manual Control

<template>
  <HLPopover id="controlled-popover" ref="popoverRef" trigger="manual" placement="top">
    <template #trigger>
      <HLButton id="popover-trigger" @click="togglePopover">Toggle Popover</HLButton>
    </template>
    <div class="p-4">Manually controlled popover content</div>
  </HLPopover>
</template>

<script setup>
import { ref } from 'vue'
import { HLPopover, HLButton } from '@platform-ui/highrise'

const popoverRef = ref()
const togglePopover = () => {
  popoverRef.value?.setShow(true)
}
</script>

Best Practices

1. Always provide unique id props for accessibility
2. Use appropriate trigger modes based on context
3. Consider mobile usability when choosing placement
4. Keep content concise and focused
5. Use header and footer slots for better organization
6. Implement proper focus management
7. Handle keyboard navigation
8. Consider responsive behavior
9. Follow accessibility guidelines
10. Maintain consistent styling

Breaking Changes

1. New required id prop for accessibility
2. Changed default arrow visibility to false
3. Modified placement options
4. New slot system
5. Changed styling implementation
6. Modified theme customization
7. Changed event handling
8. New manual control methods
9. Modified accessibility implementation
10. Changed animation system

TypeScript Support

The Popover component includes comprehensive TypeScript support:

interface HLPopoverProps {
  id: string
  trigger?: 'click' | 'hover' | 'focus' | 'manual'
  placement?: string
  showArrow?: boolean
  width?: number | 'trigger'
  contentClass?: string
  headerClass?: string
  footerClass?: string
}