@umbra.ui/core 0.1.0

package/src/components/indicators/Tooltip/README.md

@@ -0,0 +1,723 @@
+# Tooltip
+
+A flexible tooltip system built with Vue 3 Composition API and TypeScript. The Tooltip component provides contextual information and help text that appears on hover with smart positioning, smooth animations, and global state management.
+
+## Installation/Import
+
+```typescript
+import { TooltipProvider, useTooltip, vTooltip } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- @floating-ui/vue (for positioning)
+
+## Basic Usage
+
+### Setup (App Level)
+
+```vue
+<script setup lang="ts">
+import { createApp } from "vue";
+import { TooltipProvider } from "@umbra-ui/core";
+import App from "./App.vue";
+
+const app = createApp(App);
+app.mount("#app");
+</script>
+
+<template>
+  <div>
+    <!-- Your app content -->
+    <TooltipProvider />
+  </div>
+</template>
+```
+
+### Using the Directive
+
+```vue
+<script setup lang="ts">
+import { vTooltip } from "@umbra-ui/core";
+</script>
+
+<template>
+  <div>
+    <button v-tooltip="'This is a simple tooltip'">Hover me</button>
+
+    <button v-tooltip="{ content: 'Custom tooltip', placement: 'bottom' }">
+      Advanced tooltip
+    </button>
+  </div>
+</template>
+```
+
+### Using the Composable
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from "vue";
+import { useTooltip } from "@umbra-ui/core";
+
+const buttonRef = ref<HTMLElement>();
+
+const { bindTooltip } = useTooltip({
+  content: "This tooltip was created with the composable",
+  placement: "top",
+  delay: 500,
+});
+
+onMounted(() => {
+  if (buttonRef.value) {
+    bindTooltip(buttonRef.value);
+  }
+});
+</script>
+
+<template>
+  <button ref="buttonRef">Hover me</button>
+</template>
+```
+
+## Props
+
+### TooltipProvider Component
+
+This component does not accept props. It automatically manages all tooltips through the global tooltip state.
+
+## Events
+
+### TooltipProvider Component
+
+This component does not emit events.
+
+## Slots
+
+### TooltipProvider Component
+
+This component does not use slots.
+
+## Exposed Methods/Refs
+
+### useTooltip Composable
+
+The `useTooltip` composable provides the following methods:
+
+| Method Name   | Parameters               | Return Type  | Description                                           |
+| ------------- | ------------------------ | ------------ | ----------------------------------------------------- |
+| `bindTooltip` | `(element: HTMLElement)` | `() => void` | Binds tooltip to an element, returns cleanup function |
+| `showTooltip` | `(element: HTMLElement)` | `void`       | Manually show tooltip for an element                  |
+| `hideTooltip` | `()`                     | `void`       | Hide the currently visible tooltip                    |
+
+### useTooltipProvider Composable
+
+The `useTooltipProvider` composable provides the following:
+
+| Property/Method | Type                | Description                                    |
+| --------------- | ------------------- | ---------------------------------------------- |
+| `tooltipState`  | `TooltipState`      | Reactive tooltip state object                  |
+| `showTooltip`   | `(element, config)` | Show tooltip for an element with configuration |
+| `hideTooltip`   | `()`                | Hide the currently visible tooltip             |
+
+## Types
+
+### TooltipConfig
+
+```typescript
+interface TooltipConfig {
+  content: string;
+  placement?: "top" | "bottom" | "left" | "right";
+  delay?: number;
+  offset?: number;
+}
+```
+
+### TooltipState
+
+```typescript
+interface TooltipState {
+  isVisible: boolean;
+  content: string;
+  targetElement: HTMLElement | null;
+  placement: TooltipConfig["placement"];
+  offset: number;
+}
+```
+
+## CSS Customization
+
+The Tooltip component uses CSS custom properties for easy theming and customization:
+
+```css
+/* Tooltip background colors */
+--tooltip-bg: #f0f2f4;
+
+/* Tooltip text colors */
+--tooltip-text: #1a1d23;
+```
+
+## Examples
+
+### Basic Tooltip Usage
+
+```vue
+<script setup lang="ts">
+import { vTooltip } from "@umbra-ui/core";
+</script>
+
+<template>
+  <div class="tooltip-examples">
+    <button v-tooltip="'Simple tooltip text'">Simple Tooltip</button>
+
+    <button
+      v-tooltip="
+        'This is a longer tooltip that provides more detailed information about the button.'
+      "
+    >
+      Long Tooltip
+    </button>
+  </div>
+</template>
+
+<style module>
+.tooltip-examples {
+  display: flex;
+  gap: 1rem;
+  padding: 2rem;
+}
+
+button {
+  padding: 0.5rem 1rem;
+  background-color: #007bff;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+}
+</style>
+```
+
+### Different Placements
+
+```vue
+<script setup lang="ts">
+import { vTooltip } from "@umbra-ui/core";
+</script>
+
+<template>
+  <div class="placement-examples">
+    <div class="placement-grid">
+      <button v-tooltip="{ content: 'Top placement', placement: 'top' }">
+        Top
+      </button>
+
+      <button v-tooltip="{ content: 'Bottom placement', placement: 'bottom' }">
+        Bottom
+      </button>
+
+      <button v-tooltip="{ content: 'Left placement', placement: 'left' }">
+        Left
+      </button>
+
+      <button v-tooltip="{ content: 'Right placement', placement: 'right' }">
+        Right
+      </button>
+    </div>
+  </div>
+</template>
+
+<style module>
+.placement-examples {
+  padding: 2rem;
+}
+
+.placement-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 2rem;
+  max-width: 300px;
+  margin: 0 auto;
+}
+
+button {
+  padding: 1rem;
+  background-color: #6c757d;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+}
+</style>
+```
+
+### Custom Delay and Offset
+
+```vue
+<script setup lang="ts">
+import { vTooltip } from "@umbra-ui/core";
+</script>
+
+<template>
+  <div class="custom-examples">
+    <button v-tooltip="{ content: 'Quick tooltip', delay: 200 }">
+      Quick (200ms)
+    </button>
+
+    <button v-tooltip="{ content: 'Slow tooltip', delay: 2000 }">
+      Slow (2s)
+    </button>
+
+    <button v-tooltip="{ content: 'Close tooltip', offset: 5 }">
+      Close (5px)
+    </button>
+
+    <button v-tooltip="{ content: 'Far tooltip', offset: 20 }">
+      Far (20px)
+    </button>
+  </div>
+</template>
+
+<style module>
+.custom-examples {
+  display: flex;
+  gap: 1rem;
+  padding: 2rem;
+  flex-wrap: wrap;
+}
+
+button {
+  padding: 0.5rem 1rem;
+  background-color: #28a745;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+}
+</style>
+```
+
+### Form Field Help
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { vTooltip } from "@umbra-ui/core";
+
+const email = ref("");
+const password = ref("");
+</script>
+
+<template>
+  <div class="form-example">
+    <h3>User Registration</h3>
+
+    <div class="form-group">
+      <label>
+        Email Address
+        <span
+          v-tooltip="'Enter a valid email address that you have access to'"
+          class="help-icon"
+        >
+          ?
+        </span>
+      </label>
+      <input v-model="email" type="email" placeholder="Enter your email" />
+    </div>
+
+    <div class="form-group">
+      <label>
+        Password
+        <span
+          v-tooltip="
+            'Password must be at least 8 characters long and contain at least one number'
+          "
+          class="help-icon"
+        >
+          ?
+        </span>
+      </label>
+      <input
+        v-model="password"
+        type="password"
+        placeholder="Enter your password"
+      />
+    </div>
+
+    <button type="submit">Register</button>
+  </div>
+</template>
+
+<style module>
+.form-example {
+  max-width: 400px;
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+}
+
+.form-group {
+  margin-bottom: 1rem;
+}
+
+label {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+}
+
+.help-icon {
+  width: 16px;
+  height: 16px;
+  border-radius: 50%;
+  background-color: #6c757d;
+  color: white;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 12px;
+  cursor: help;
+}
+
+input {
+  width: 100%;
+  padding: 0.5rem;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  font-size: 1rem;
+}
+
+button {
+  width: 100%;
+  padding: 0.75rem;
+  background-color: #007bff;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 1rem;
+}
+</style>
+```
+
+### Icon Tooltips
+
+```vue
+<script setup lang="ts">
+import { vTooltip } from "@umbra-ui/core";
+</script>
+
+<template>
+  <div class="icon-examples">
+    <h3>Action Buttons</h3>
+
+    <div class="icon-group">
+      <button
+        v-tooltip="{ content: 'Save your changes', placement: 'top' }"
+        class="icon-button"
+      >
+        💾
+      </button>
+
+      <button
+        v-tooltip="{ content: 'Delete this item', placement: 'top' }"
+        class="icon-button"
+      >
+        🗑️
+      </button>
+
+      <button
+        v-tooltip="{ content: 'Edit this item', placement: 'top' }"
+        class="icon-button"
+      >
+        ✏️
+      </button>
+
+      <button
+        v-tooltip="{ content: 'Share this item', placement: 'top' }"
+        class="icon-button"
+      >
+        📤
+      </button>
+    </div>
+  </div>
+</template>
+
+<style module>
+.icon-examples {
+  padding: 2rem;
+}
+
+.icon-group {
+  display: flex;
+  gap: 1rem;
+}
+
+.icon-button {
+  width: 40px;
+  height: 40px;
+  border: none;
+  border-radius: 50%;
+  background-color: #f8f9fa;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 1.2rem;
+  transition: background-color 0.2s;
+}
+
+.icon-button:hover {
+  background-color: #e9ecef;
+}
+</style>
+```
+
+### Dynamic Tooltips
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { vTooltip } from "@umbra-ui/core";
+
+const user = ref({
+  name: "John Doe",
+  email: "john@example.com",
+  role: "Administrator",
+});
+
+const tooltipConfig = computed(() => ({
+  content: `Name: ${user.value.name}\nEmail: ${user.value.email}\nRole: ${user.value.role}`,
+  placement: "right" as const,
+  delay: 300,
+}));
+
+const updateUser = () => {
+  user.value.name = "Jane Smith";
+  user.value.email = "jane@example.com";
+  user.value.role = "Editor";
+};
+</script>
+
+<template>
+  <div class="dynamic-example">
+    <h3>User Profile</h3>
+
+    <div class="user-card">
+      <div v-tooltip="tooltipConfig" class="user-avatar">
+        {{ user.name.charAt(0) }}
+      </div>
+
+      <div class="user-info">
+        <h4>{{ user.name }}</h4>
+        <p>{{ user.email }}</p>
+        <p>{{ user.role }}</p>
+      </div>
+    </div>
+
+    <button @click="updateUser">Update User</button>
+  </div>
+</template>
+
+<style module>
+.dynamic-example {
+  padding: 2rem;
+  max-width: 400px;
+}
+
+.user-card {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  padding: 1rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+  margin-bottom: 1rem;
+}
+
+.user-avatar {
+  width: 50px;
+  height: 50px;
+  border-radius: 50%;
+  background-color: #007bff;
+  color: white;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 1.5rem;
+  font-weight: bold;
+  cursor: help;
+}
+
+.user-info h4 {
+  margin: 0 0 0.5rem 0;
+}
+
+.user-info p {
+  margin: 0 0 0.25rem 0;
+  color: #666;
+}
+
+button {
+  padding: 0.5rem 1rem;
+  background-color: #28a745;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+}
+</style>
+```
+
+### Composable Usage
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from "vue";
+import { useTooltip } from "@umbra-ui/core";
+
+const buttonRef = ref<HTMLElement>();
+const inputRef = ref<HTMLElement>();
+
+const { bindTooltip: bindButtonTooltip } = useTooltip({
+  content: "This button was configured using the composable",
+  placement: "top",
+  delay: 500,
+});
+
+const { bindTooltip: bindInputTooltip } = useTooltip({
+  content: "Enter your search query here",
+  placement: "bottom",
+  delay: 200,
+});
+
+onMounted(() => {
+  if (buttonRef.value) {
+    bindButtonTooltip(buttonRef.value);
+  }
+
+  if (inputRef.value) {
+    bindInputTooltip(inputRef.value);
+  }
+});
+</script>
+
+<template>
+  <div class="composable-example">
+    <h3>Composable Usage</h3>
+
+    <button ref="buttonRef">Composable Button</button>
+
+    <input ref="inputRef" placeholder="Search..." />
+  </div>
+</template>
+
+<style module>
+.composable-example {
+  padding: 2rem;
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  max-width: 300px;
+}
+
+button {
+  padding: 0.5rem 1rem;
+  background-color: #dc3545;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+}
+
+input {
+  padding: 0.5rem;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  font-size: 1rem;
+}
+</style>
+```
+
+### Disabled State Handling
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { vTooltip } from "@umbra-ui/core";
+
+const isDisabled = ref(false);
+
+const toggleDisabled = () => {
+  isDisabled.value = !isDisabled.value;
+};
+</script>
+
+<template>
+  <div class="disabled-example">
+    <h3>Disabled State</h3>
+
+    <button
+      :disabled="isDisabled"
+      v-tooltip="
+        isDisabled
+          ? 'This button is currently disabled'
+          : 'This button is enabled'
+      "
+    >
+      {{ isDisabled ? "Disabled" : "Enabled" }}
+    </button>
+
+    <button @click="toggleDisabled">Toggle State</button>
+  </div>
+</template>
+
+<style module>
+.disabled-example {
+  padding: 2rem;
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  max-width: 200px;
+}
+
+button {
+  padding: 0.5rem 1rem;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 1rem;
+}
+
+button:first-child {
+  background-color: #007bff;
+  color: white;
+}
+
+button:first-child:disabled {
+  background-color: #6c757d;
+  cursor: not-allowed;
+}
+
+button:last-child {
+  background-color: #28a745;
+  color: white;
+}
+</style>
+```
+
+## Notes
+
+- The tooltip system uses Vue's `Teleport` to render tooltips outside the component tree for proper z-index layering
+- Tooltips include smooth fade transitions for a polished user experience
+- The system uses Floating UI for smart positioning with automatic collision detection
+- Tooltips automatically flip and shift to stay within viewport boundaries
+- The system supports both directive and composable usage patterns
+- Tooltips are fully accessible and support keyboard navigation
+- The global tooltip state ensures only one tooltip is visible at a time
+- The system includes proper cleanup to prevent memory leaks
+- Tooltips support both light and dark themes through CSS custom properties
+- The directive automatically handles element lifecycle and cleanup
+- Custom delays and offsets provide fine-grained control over tooltip behavior