docs: utility components

docs/.vitepress/config.ts

@@ -237,16 +237,12 @@ export default defineConfig({
           {
             text: 'Component',
             items: [
-              {
-                text: 'Config Provider',
-                link: '/docs/utilities/config-provider',
-              },
-              {
-                text: 'Visually Hidden',
-                link: '/docs/utilities/visually-hidden',
-              },
+              { text: 'Config Provider', link: '/docs/utilities/config-provider' },
+              { text: 'Focus Scope', link: '/docs/utilities/focus-scope' },
+              { text: 'Presence', link: '/docs/utilities/presence' },
               { text: 'Primitive', link: '/docs/utilities/primitive' },
               { text: 'Slot', link: '/docs/utilities/slot' },
+              { text: 'Visually Hidden', link: '/docs/utilities/visually-hidden' },
             ],
           },
           {

docs/components/LinkHoverCard.vue

@@ -7,7 +7,7 @@ const props = defineProps<{
   name: string
 }>()
 
-const UTILITY_COMPONENT = ['ConfigProvider', 'VisuallyHidden']
+const UTILITY_COMPONENT = ['ConfigProvider', 'VisuallyHidden', 'FocusScope']
 
 const href = computed(() => {
   if (UTILITY_COMPONENT.includes(props.name)) {

docs/components/PresenceCallout.vue

@@ -0,0 +1,9 @@
+<script setup lang="ts">
+import Callout from './Callout.vue'
+</script>
+
+<template>
+  <Callout type="tip">
+    Built with <a href="/docs/utilities/presence">Presence</a> component - supports any <a href="/docs/guides/animation">animation techniques</a> while maintaining access to presence emitted events.
+  </Callout>
+</template>

docs/content/docs/components/checkbox.md

@@ -78,6 +78,8 @@ Contains all the parts of a checkbox. An `input` will also render when used with
 
 Renders when the checkbox is in a checked or indeterminate state. You can style this element directly, or you can use it as a wrapper to put an icon into, or both.
 
+<PresenceCallout />
+
 <!-- @include: @/meta/CheckboxIndicator.md -->
 
 <DataAttributesTable

docs/content/docs/components/collapsible.md

@@ -90,6 +90,8 @@ The button that toggles the collapsible
 
 The component that contains the collapsible content.
 
+<PresenceCallout />
+
 <!-- @include: @/meta/CollapsibleContent.md -->
 
 <DataAttributesTable

docs/content/docs/components/combobox.md

@@ -152,6 +152,8 @@ You need to set `position="popper"` for `ComboboxContent` to make sure the posit
 
 The component that pops out when the combobox is open.
 
+<PresenceCallout />
+
 <!-- @include: @/meta/ComboboxContent.md -->
 
 <DataAttributesTable

docs/content/docs/components/dialog.md

@@ -98,6 +98,8 @@ When used, portals your overlay and content parts into the `body`.
 
 A layer that covers the inert portion of the view when the dialog is open.
 
+<PresenceCallout />
+
 <!-- @include: @/meta/DialogOverlay.md -->
 
 <DataAttributesTable
@@ -113,6 +115,8 @@ A layer that covers the inert portion of the view when the dialog is open.
 
 Contains content to be rendered in the open dialog
 
+<PresenceCallout />
+
 <!-- @include: @/meta/DialogContent.md -->
 
 <DataAttributesTable

docs/content/docs/components/hover-card.md

@@ -85,6 +85,8 @@ When used, portals the content part into the `body`.
 
 The component that pops out when the hover card is open.
 
+<PresenceCallout />
+
 <!-- @include: @/meta/HoverCardContent.md -->
 
 <DataAttributesTable

docs/content/docs/components/navigation-menu.md

@@ -160,6 +160,8 @@ The button that toggles the content.
 
 Contains the content associated with each trigger.
 
+<PresenceCallout />
+
 <!-- @include: @/meta/NavigationMenuContent.md -->
 
 <DataAttributesTable
@@ -198,6 +200,8 @@ A navigational link.
 
 An optional indicator element that renders below the list, is used to highlight the currently active trigger.
 
+<PresenceCallout />
+
 <!-- @include: @/meta/NavigationMenuIndicator.md -->
 
 <DataAttributesTable
@@ -230,6 +234,8 @@ An optional indicator element that renders below the list, is used to highlight
 
 An optional viewport element that is used to render active content outside of the list.
 
+<PresenceCallout />
+
 <!-- @include: @/meta/NavigationMenuViewport.md -->
 
 <DataAttributesTable

docs/content/docs/components/popover.md

@@ -95,6 +95,8 @@ When used, portals the content part into the `body`.
 
 The component that pops out when the popover is open.
 
+<PresenceCallout />
+
 <!-- @include: @/meta/PopoverContent.md -->
 
 <DataAttributesTable

docs/content/docs/components/radio-group.md

@@ -88,6 +88,8 @@ An item in the group that can be checked. An `input` will also render when used
 
 Renders when the radio item is in a checked state. You can style this element directly, or you can use it as a wrapper to put an icon into, or both.
 
+<PresenceCallout />
+
 <!-- @include: @/meta/RadioGroupIndicator.md -->
 
 <DataAttributesTable

docs/content/docs/components/scroll-area.md

@@ -71,6 +71,8 @@ The viewport area of the scroll area.
 
 The vertical scrollbar. Add a second `Scrollbar` with an `orientation` prop to enable horizontal scrolling.
 
+<PresenceCallout />
+
 <!-- @include: @/meta/ScrollAreaScrollbar.md -->
 
 <DataAttributesTable

docs/content/docs/components/select.md

@@ -144,6 +144,8 @@ When used, portals the content part into the `body`.
 
 The component that pops out when the select is open.
 
+<PresenceCallout />
+
 <!-- @include: @/meta/SelectContent.md -->
 
 <DataAttributesTable

docs/content/docs/components/tabs.md

@@ -129,6 +129,8 @@ The indicator that highlights the current active tab.
 
 Contains the content associated with each trigger.
 
+<PresenceCallout />
+
 <!-- @include: @/meta/TabsContent.md -->
 
 <DataAttributesTable

docs/content/docs/components/toast.md

@@ -71,6 +71,8 @@ The fixed area where toasts appear. Users can jump to the viewport by pressing a
 
 The toast that automatically closes. It should not be held open to [acquire a user response](/docs/components/toast#action).
 
+<PresenceCallout />
+
 <!-- @include: @/meta/ToastRoot.md -->
 
 <DataAttributesTable

docs/content/docs/components/tooltip.md

@@ -85,6 +85,8 @@ When used, portals the content part into the `body`.
 
 The component that pops out when the tooltip is open.
 
+<PresenceCallout />
+
 <!-- @include: @/meta/TooltipContent.md -->
 
 <DataAttributesTable

docs/content/docs/utilities/focus-scope.md

@@ -0,0 +1,78 @@
+---
+title: Focus Scope
+description:  Manages focus within a component boundary with support for trapping and looping focus navigation.
+---
+
+# Focus Scope
+
+<Description>
+ Manages focus within a component boundary with support for trapping and looping focus navigation.
+</Description>
+
+Focus Scope provides enhanced control over keyboard focus management within component boundaries. It can trap focus within its container and optionally loop focus navigation, making it ideal for modal interfaces and other interactive components that need to manage focus states.
+
+## API Reference
+
+<!-- @include: @/meta/FocusScope.md -->
+
+## Example
+
+Basic usage with focus trapping
+
+```vue line=2
+<template>
+  <FocusScope :trapped="true">
+    <div>
+      <button>Action 1</button>
+      <button>Action 2</button>
+      <button>Close</button>
+    </div>
+  </FocusScope>
+</template>
+```
+
+### With Focus Looping
+
+Enable both trapping and looping for complete focus management:
+
+```vue line=2
+<template>
+  <FocusScope :trapped="true" :loop="true">
+    <div>
+      <button v-for="item in items" :key="item.id">
+        {{ item.label }}
+      </button>
+    </div>
+  </FocusScope>
+</template>
+```
+
+### Handling Focus Event
+
+```vue line=2-5
+<script setup>
+function handleMountFocus(event) {
+  // Prevent default auto-focus behavior if needed
+  event.preventDefault()
+}
+</script>
+
+<template>
+  <FocusScope
+    @mount-auto-focus="handleMountFocus"
+    @unmount-auto-focus="handleUnmountFocus"
+  >
+    <div>
+      …
+    </div>
+  </FocusScope>
+</template>
+```
+
+<br>
+
+<Callout type="warning">
+
+When using trapped mode, ensure there is always at least one focusable element within the scope to prevent focus from being trapped in an inaccessible state.
+
+</Callout>

docs/content/docs/utilities/presence.md

@@ -0,0 +1,100 @@
+---
+title: Presence
+description: Manages mounting and unmounting of element with transition support.
+---
+
+# Presence
+
+<Description>
+Manages mounting and unmounting of element with transition support.
+</Description>
+
+<Callout type="info" title="Question">
+
+How is this component different from [Vue Transition](https://vuejs.org/guide/built-ins/transition.html#transition)?
+
+A: The biggest difference is it accepts css animation, and control the visibility of element.
+
+</Callout>
+
+Presence component provides enhanced control over element mounting/unmounting compared to Vue's native `v-if`. It ensures animations and transitions complete before removing elements from the DOM, making it perfect for animated UI components.
+
+## API Reference
+
+<PropsTable :data="[
+  {
+    'name': 'present',
+    'description': '<p>Conditional to mount or unmount the child element. Similar to <code>v-if</code></p>\n',
+    'type': 'boolean',
+    'required': true,
+  },
+  {
+    'name': 'forceMount',
+    'description': '<p>Force the element to render all the time.\n\nUseful for programmatically render grandchild component with the exposed <code>present</code></p>\n',
+    'type': 'boolean',
+    'required': false,
+    'default': false
+  },
+]" />
+
+<EmitsTable :data="[
+  {
+    'name': 'enter',
+    'description': '<p>Event handler called when the enter animation has started</p>\n',
+    'type': 'CustomEvent'
+  },
+  {
+    'name': 'after-enter',
+    'description': '<p>Event handler called when the enter animation has finished</p>\n',
+    'type': 'CustomEvent'
+  },
+  {
+    'name': 'leave',
+    'description': '<p>Event handler called when the leave animation has started</p>\n',
+    'type': 'CustomEvent'
+  },
+  {
+    'name': 'after-leave',
+    'description': '<p>Event handler called when the leave animation has finished</p>\n',
+    'type': 'CustomEvent'
+  },
+]" />
+
+<Callout type="tip">
+
+Read our [Animation Guide](/docs/guides/animation) to learn more about implementing animations with Presence component.
+
+</Callout>
+
+## Example
+
+```vue line=2,4,5
+<template>
+  <Presence :present="isVisible">
+    <div
+      :data-open="isVisible ? 'open' : 'close'"
+      class="data-[state=open]:animate-fadeIn data-[state=closed]:animate-fadeOut"
+    >
+      <slot />
+    </div>
+  </Presence>
+</template>
+```
+
+### Force Mount Usage
+
+When you need to ensure content is always rendered regardless of the present state:
+
+```vue
+<template>
+  <Presence v-slot="{ present }" :present="isVisible" :force-mount="true">
+    <div>
+      This content will always be rendered
+
+      <div v-if="present">
+        This content is hidden
+      </div>
+    </div>
+  </Presence>
+</template>
+```