Control Tooltips Programmatically

CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **Programmatic Control**: Tooltips can now be controlled programmatically via three methods:
+  - **Component Template Refs**: Access `show()`, `hide()`, `toggle()`, and `isVisible()` methods via template refs
+  - **v-model Support**: Two-way binding for tooltip visibility state
+  - **TooltipControl API**: Global API for controlling directive tooltips by ID (`TooltipControl.show()`, `TooltipControl.hide()`, `TooltipControl.toggle()`, `TooltipControl.isVisible()`)
+- Added `modelValue` prop to Tooltip component for v-model support
+- Added `id` prop to support unique identification for directive tooltips
+- Exported `TooltipExposed` type for TypeScript template ref typing
+- Exported `TooltipControl` API for programmatic directive control
+- Added comprehensive documentation for programmatic control at `docs/guide/programmatic-control.md`
+- Added examples demonstrating all three control methods in showcase components
+
 ## [1.5.0] - 2025-10-30
 
 ### Added

docs/.vitepress/config.ts

@@ -63,6 +63,7 @@ export default defineConfig({
           items: [
             { text: 'Component Usage', link: '/guide/component-usage' },
             { text: 'Directive Usage', link: '/guide/directive-usage' },
+            { text: 'Programmatic Control', link: '/guide/programmatic-control' },
             { text: 'Global Configuration', link: '/guide/global-config' },
             { text: 'Runtime Configuration', link: '/guide/runtime-config' },
           ],

docs/api/component.md

@@ -17,6 +17,79 @@ The Vue Custom Tooltip component provides a comprehensive API for creating and c
 | `showArrow` | `boolean` | `true` | Show arrow pointer |
 | `offset` | `number` | `8` | Offset from trigger (px) |
 | `dark` | `'auto' \| boolean` | `'auto'` | Dark mode behavior |
+| `modelValue` | `boolean` | `undefined` | Control visibility with v-model |
+
+## Exposed Methods
+
+The Tooltip component exposes methods for programmatic control via template refs:
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `show()` | `void` | Show the tooltip immediately (bypasses delays) |
+| `hide()` | `void` | Hide the tooltip immediately (bypasses delays) |
+| `toggle()` | `void` | Toggle the tooltip visibility |
+| `isVisible()` | `boolean` | Check if the tooltip is currently visible |
+
+### Using Template Refs
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import type { TooltipExposed } from '@borstihd/vue-custom-tooltip'
+
+const tooltipRef = ref<TooltipExposed | null>(null)
+
+function showTooltip() {
+  tooltipRef.value?.show()
+}
+
+function hideTooltip() {
+  tooltipRef.value?.hide()
+}
+
+function toggleTooltip() {
+  tooltipRef.value?.toggle()
+}
+</script>
+
+<template>
+  <div>
+    <Tooltip ref="tooltipRef" content="Programmatically controlled">
+      <button>Target Element</button>
+    </Tooltip>
+
+    <button @click="showTooltip">Show</button>
+    <button @click="hideTooltip">Hide</button>
+    <button @click="toggleTooltip">Toggle</button>
+  </div>
+</template>
+```
+
+### Using v-model
+
+The component supports two-way binding for visibility control:
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const isVisible = ref(false)
+</script>
+
+<template>
+  <div>
+    <Tooltip v-model="isVisible" content="Controlled via v-model">
+      <button>Target Element</button>
+    </Tooltip>
+
+    <button @click="isVisible = true">Show</button>
+    <button @click="isVisible = false">Hide</button>
+    <button @click="isVisible = !isVisible">Toggle</button>
+
+    <p>Tooltip is {{ isVisible ? 'visible' : 'hidden' }}</p>
+  </div>
+</template>
+```
 
 ## Slots
 
@@ -69,11 +142,21 @@ The content slot allows you to use rich HTML content in your tooltips:
 The component is fully typed. You can import the types for use in your TypeScript code:
 
 ```ts
-import type { TooltipPosition, TooltipProps, TooltipTrigger } from '@borstihd/vue-custom-tooltip'
+import type {
+  TooltipExposed,
+  TooltipPosition,
+  TooltipProps,
+  TooltipTrigger,
+} from '@borstihd/vue-custom-tooltip'
 
 // Example usage in component props
 const position: TooltipPosition = 'auto'
 const trigger: TooltipTrigger = 'both'
+
+// Example usage for template refs
+const tooltipRef = ref<TooltipExposed | null>(null)
+// or
+const tooltipRef = useTemplateRef<TooltipExposed | null>('tooltipRef')
 ```
 
 ## Best Practices

docs/api/directive.md

@@ -183,6 +183,7 @@ For more complex configurations, you can pass an object instead of a simple stri
 | `showArrow` | `boolean` | `true` | Show arrow pointer |
 | `offset` | `number` | `8` | Offset from trigger (px) |
 | `dark` | `'auto' \| boolean` | `'auto'` | Dark mode behavior |
+| `id` | `string` | `undefined` | Unique identifier for programmatic control |
 
 ### Combining with Modifiers
 
@@ -206,10 +207,103 @@ Object configuration can still be combined with modifiers for quick overrides:
 When using both modifiers and object configuration, modifiers take precedence over the object configuration for the same property.
 :::
 
+## Programmatic Control
+
+Directive tooltips can be controlled programmatically using the `TooltipControl` API. This requires assigning a unique `id` to the tooltip.
+
+### Using TooltipControl API
+
+```vue
+<script setup>
+import { TooltipControl } from '@borstihd/vue-custom-tooltip'
+
+function showTooltip() {
+  TooltipControl.show('my-tooltip')
+}
+
+function hideTooltip() {
+  TooltipControl.hide('my-tooltip')
+}
+
+function toggleTooltip() {
+  TooltipControl.toggle('my-tooltip')
+}
+
+function checkVisibility() {
+  const isVisible = TooltipControl.isVisible('my-tooltip')
+  console.log('Tooltip visible:', isVisible)
+}
+</script>
+
+<template>
+  <div>
+    <button
+      v-tooltip="{
+        content: 'Programmatically controlled',
+        id: 'my-tooltip'
+      }"
+    >
+      Target Element
+    </button>
+
+    <button @click="showTooltip">Show</button>
+    <button @click="hideTooltip">Hide</button>
+    <button @click="toggleTooltip">Toggle</button>
+  </div>
+</template>
+```
+
+### TooltipControl API
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `show(id)` | `id: string` | `void` | Show tooltip by ID |
+| `hide(id)` | `id: string` | `void` | Hide tooltip by ID |
+| `toggle(id)` | `id: string` | `void` | Toggle tooltip by ID |
+| `isVisible(id)` | `id: string` | `boolean` | Check if tooltip is visible |
+
+::: tip Note
+Programmatic control methods (`show`, `hide`, `toggle`) bypass delays for immediate response.
+:::
+
+### Coordinated Tooltips
+
+You can control multiple tooltips simultaneously:
+
+```vue
+<script setup>
+import { TooltipControl } from '@borstihd/vue-custom-tooltip'
+
+function showAllTooltips() {
+  TooltipControl.show('tooltip-1')
+  TooltipControl.show('tooltip-2')
+  TooltipControl.show('tooltip-3')
+}
+
+function hideAllTooltips() {
+  TooltipControl.hide('tooltip-1')
+  TooltipControl.hide('tooltip-2')
+  TooltipControl.hide('tooltip-3')
+}
+</script>
+
+<template>
+  <div>
+    <button v-tooltip="{ content: 'First', id: 'tooltip-1' }">1</button>
+    <button v-tooltip="{ content: 'Second', id: 'tooltip-2' }">2</button>
+    <button v-tooltip="{ content: 'Third', id: 'tooltip-3' }">3</button>
+
+    <button @click="showAllTooltips">Show All</button>
+    <button @click="hideAllTooltips">Hide All</button>
+  </div>
+</template>
+```
+
 ## Best Practices
 
 1. **Choose Wisely**: Use the directive for simple text tooltips. For rich content, use the component approach.
 2. **Clear Triggers**: Make it obvious which elements have tooltips through visual cues.
 3. **Concise Content**: Keep tooltip text short and informative.
 4. **Position Awareness**: Consider using `.auto` for dynamic positioning.
 5. **Animation Speed**: Use `.slow` for important information, `.fast` for subtle hints.
+6. **Programmatic IDs**: Use descriptive, unique IDs for programmatically controlled tooltips.