@nuxtseo/design-system 0.0.0-stage → 0.1.0

package/app/components/element/UiTooltip.vue

@@ -0,0 +1,390 @@
+<script setup lang="ts">
+import type { VNodeChild } from 'vue'
+import { computed, nextTick, onMounted, onUpdated, ref, shallowRef, useSlots, watch } from 'vue'
+import { TooltipContent, TooltipPortal, TooltipProvider, TooltipRoot, TooltipTrigger, UiIcon } from '#components'
+/**
+ * UiTooltip
+ *
+ * Built directly on reka-ui's Tooltip primitives. Skips Nuxt UI's `UTooltip`
+ * wrapper because that layer has historically been buggy in dense scenarios
+ * (heatmap cells, packed grids).
+ *
+ * The global `TooltipProvider` is set up once in `app/app.vue`
+ * (`<UApp :tooltip="{ delayDuration: 0 }">`) so adjacent tooltips coordinate
+ * via `skipDelayDuration` automatically.
+ *
+ * Defaults match tooltip semantics:
+ * - `disableHoverableContent: true` — the content layer cannot be hovered,
+ *   eliminating the "safe-polygon" cursor traversal flicker between
+ *   tightly-packed triggers.
+ * - `pointer-events: none` on the content node — defence in depth so the
+ *   tooltip never steals events from underlying interactive content.
+ */
+
+interface Props {
+  /** Plain text body. */
+  text?: string
+  /** Bold title rendered above description. */
+  title?: string
+  /** Secondary body text. */
+  description?: string
+  /** Raw HTML body — only rendered when title/description/text/#text are all absent. */
+  html?: string
+  /** Renders a label with a (?) trigger icon; tooltip mounts on the icon only. */
+  label?: string
+  size?: keyof typeof sizes
+  iconSize?: 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+  side?: 'top' | 'bottom' | 'left' | 'right'
+  align?: 'start' | 'center' | 'end'
+  sideOffset?: number
+  /** Open delay (ms). Falls back to the provider default (0 in this app). */
+  delayDuration?: number
+  /** Whether the cursor may enter the tooltip body. Default `true` (tooltip semantics). */
+  disableHoverableContent?: boolean
+  disabled?: boolean
+  /**
+   * Default-variant trigger element. `'span'` (default) wraps the slot in a
+   * span. Keyboard focus on any focusable element inside opens the tooltip and
+   * describes that element; when the slot holds nothing focusable, the span
+   * itself becomes the Tab stop, so every tooltip stays keyboard-reachable.
+   * `'button'` wraps it in a focusable button so a non-interactive trigger
+   * (e.g. a bare info icon) stays keyboard- and screen-reader-reachable.
+   * `'child'` makes the slot's single root element the trigger directly — use
+   * it for full-width links/rows where an extra inline wrapper would alter
+   * layout or truncate the hit area.
+   */
+  triggerAs?: 'span' | 'button' | 'child'
+}
+
+const {
+  text,
+  title,
+  description,
+  html,
+  side = 'top',
+  align = 'center',
+  sideOffset = 6,
+  disableHoverableContent = true,
+  disabled = false,
+  size = 'md',
+  triggerAs = 'span',
+} = defineProps<Props>()
+
+defineSlots<{
+  default?: () => VNodeChild
+  text?: () => VNodeChild
+}>()
+
+const slots = useSlots()
+const childTriggerElement = shallowRef<HTMLElement>()
+
+// Reka's as-child ref can stop at a Vue component instance. NuxtLink and other
+// component triggers then leave Floating UI with no measurable anchor, so the
+// tooltip falls back to viewport 0,0. Event listeners still reach the rendered
+// DOM root, which gives us the concrete anchor without adding a layout wrapper.
+function captureChildTrigger(event: Event): void {
+  if (event.currentTarget instanceof HTMLElement)
+    childTriggerElement.value = event.currentTarget
+}
+
+// Span trigger. Reka listens for `focus` on the trigger itself, and focus does
+// not bubble, so a focusable child (a button, a link, a tabindex cell) never
+// opened the tooltip and the description landed on the span. Listen for
+// `focusin` instead, open on keyboard focus, and move the description onto the
+// focused element. A span with nothing focusable inside takes the Tab stop.
+// A trigger inside an `aria-hidden` or `inert` subtree (a position-only plot
+// whose data a table carries) never takes a Tab stop: focus there is unnamed.
+const open = ref(false)
+const spanTrigger = shallowRef<HTMLElement>()
+const spanTabStop = ref(false)
+const focusedChild = shallowRef<HTMLElement>()
+const FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), summary, [contenteditable="true"], [tabindex]:not([tabindex="-1"])'
+
+function syncSpanTabStop(): void {
+  const span = spanTrigger.value
+  if (!span)
+    return
+  spanTabStop.value = !disabled && hasContent.value
+    && !span.querySelector(FOCUSABLE)
+    && !span.closest('[aria-hidden="true"], [inert]')
+}
+onMounted(syncSpanTabStop)
+onUpdated(syncSpanTabStop)
+
+function onSpanFocusIn(event: FocusEvent): void {
+  const target = event.target
+  if (!(target instanceof HTMLElement) || target === spanTrigger.value)
+    return
+  if (disabled || !hasContent.value || !target.matches(':focus-visible'))
+    return
+  focusedChild.value = target
+  open.value = true
+}
+
+function onSpanFocusOut(event: FocusEvent): void {
+  if (event.target === spanTrigger.value)
+    return
+  if (event.relatedTarget instanceof Node && spanTrigger.value?.contains(event.relatedTarget))
+    return
+  open.value = false
+}
+
+// Reka sets `aria-describedby` on the span while open; add it to the focused
+// child, which is what a screen reader announces, and restore it on close.
+let childDescribedBy: string | null = null
+watch(open, async (isOpen) => {
+  const child = focusedChild.value
+  if (!child)
+    return
+  if (!isOpen) {
+    if (childDescribedBy)
+      child.setAttribute('aria-describedby', childDescribedBy)
+    else
+      child.removeAttribute('aria-describedby')
+    focusedChild.value = undefined
+    return
+  }
+  await nextTick()
+  const id = spanTrigger.value?.getAttribute('aria-describedby')
+  if (!id)
+    return
+  childDescribedBy = child.getAttribute('aria-describedby')
+  child.setAttribute('aria-describedby', childDescribedBy ? `${childDescribedBy} ${id}` : id)
+})
+
+const hasContent = computed(() =>
+  !!(text || title || description || html || slots.text),
+)
+const tooltipMaxWidth = computed(() =>
+  `min(${sizes[size]}px, calc(100vw - 2.5rem), var(--reka-tooltip-content-available-width, 100vw))`,
+)
+</script>
+
+<script lang="ts">
+export const sizes = {
+  xs: 80,
+  sm: 160,
+  md: 250,
+  lg: 440,
+  xl: 640,
+}
+</script>
+
+<template>
+  <!-- Label variant: tooltip mounts on a small ? icon next to plain text -->
+  <span v-if="label" class="inline-flex items-center gap-1">
+    <span>{{ label }}</span>
+    <TooltipProvider :delay-duration="delayDuration ?? 0" :skip-delay-duration="300" :disable-hoverable-content="disableHoverableContent">
+      <TooltipRoot
+        :delay-duration="delayDuration"
+        :disable-hoverable-content="disableHoverableContent"
+        :disabled="disabled || !hasContent"
+      >
+        <TooltipTrigger
+          :aria-label="`More information: ${label}`"
+          class="-m-1.5 inline-flex min-h-6 min-w-6 items-center justify-center rounded-full text-dimmed hover:text-muted transition-colors cursor-help focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary"
+        >
+          <UiIcon name="life-buoy" class="size-3" aria-hidden="true" />
+        </TooltipTrigger>
+        <TooltipPortal>
+          <TooltipContent
+            :side="side"
+            :align="align"
+            :side-offset="sideOffset"
+            :collision-padding="8"
+            class="ui-tooltip-content"
+            role="tooltip"
+          >
+            <div class="w-max space-y-2 text-left text-xs font-normal leading-normal" :style="{ maxWidth: tooltipMaxWidth }" data-ui="UiTooltip">
+              <template v-if="title">
+                <div class="font-semibold">
+                  {{ title }}
+                </div>
+                <div v-if="description" class="text-muted text-xs">
+                  {{ description }}
+                </div>
+              </template>
+              <div v-else>
+                {{ text }}
+              </div>
+            </div>
+          </TooltipContent>
+        </TooltipPortal>
+      </TooltipRoot>
+    </TooltipProvider>
+  </span>
+
+  <!-- Default variant: tooltip wraps the trigger (slot, or fallback (?) icon) -->
+  <TooltipProvider
+    v-else
+    :delay-duration="delayDuration ?? 0"
+    :skip-delay-duration="300"
+    :disable-hoverable-content="disableHoverableContent"
+  >
+    <TooltipRoot
+      v-model:open="open"
+      :delay-duration="delayDuration"
+      :disable-hoverable-content="disableHoverableContent"
+      :disabled="disabled || !hasContent"
+    >
+      <TooltipTrigger
+        v-if="$slots.default && triggerAs === 'child'"
+        :reference="childTriggerElement"
+        as-child
+        @pointermove="captureChildTrigger"
+        @focus="captureChildTrigger"
+      >
+        <slot />
+      </TooltipTrigger>
+      <TooltipTrigger v-else as-child>
+        <!-- `max-w-full`: a trigger never outgrows its container. Without it a
+             truncating child (a long query in a table cell) set the span's
+             width and spilled over the next column at phone width. -->
+        <span
+          v-if="$slots.default && triggerAs === 'span'"
+          ref="spanTrigger"
+          class="inline-block max-w-full"
+          :class="spanTabStop ? 'rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary' : undefined"
+          :tabindex="spanTabStop ? 0 : undefined"
+          @focusin="onSpanFocusIn"
+          @focusout="onSpanFocusOut"
+        >
+          <slot />
+        </span>
+        <button
+          v-else-if="$slots.default"
+          type="button"
+          :aria-label="text || title || description"
+          class="-m-0.5 inline-flex min-h-6 min-w-6 items-center justify-center cursor-help rounded-full focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary"
+        >
+          <slot />
+        </button>
+        <button
+          v-else
+          type="button"
+          aria-label="More information"
+          class="-m-0.5 inline-flex min-h-6 min-w-6 items-center justify-center cursor-help rounded-full focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary"
+        >
+          <UiIcon name="life-buoy" class="text-primary" :class="({ xs: 'size-3', sm: 'size-3.5', md: 'size-4', lg: 'size-5', xl: 'size-6' })[iconSize || 'md']" aria-hidden="true" />
+        </button>
+      </TooltipTrigger>
+      <TooltipPortal>
+        <TooltipContent
+          :side="side"
+          :align="align"
+          :side-offset="sideOffset"
+          :collision-padding="8"
+          class="ui-tooltip-content"
+          role="tooltip"
+        >
+          <div class="w-max space-y-2 text-left text-xs font-normal leading-normal" :style="{ maxWidth: tooltipMaxWidth }" data-ui="UiTooltip">
+            <slot v-if="$slots.text" name="text" />
+            <template v-else-if="title">
+              <div class="font-semibold">
+                {{ title }}
+              </div>
+              <div v-if="description" class="text-muted text-xs">
+                {{ description }}
+              </div>
+            </template>
+            <div v-else-if="text">
+              {{ text }}
+            </div>
+            <div v-else-if="html" v-html="html" />
+          </div>
+        </TooltipContent>
+      </TooltipPortal>
+    </TooltipRoot>
+  </TooltipProvider>
+</template>
+
+<style>
+.ui-tooltip-content {
+  background-color: var(--ui-bg-elevated);
+  /* Popover-tier depth — see global.css. --elevation-popover carries the
+     atmospheric shadow + brand bevel; --surface-raised is the top-lit fill. */
+  background-image: var(--surface-raised);
+  box-shadow: var(--elevation-popover);
+  color: var(--ui-text);
+  border: 1px solid var(--ui-border);
+  border-radius: 0.5rem;
+  padding: 0.625rem 0.75rem;
+  pointer-events: none;
+  z-index: 50;
+  will-change: transform, opacity;
+  transform-origin: var(--reka-tooltip-content-transform-origin, center);
+  letter-spacing: -0.005em;
+  -webkit-font-smoothing: antialiased;
+}
+
+/* Reka emits data-state + data-side; hook spring-out enter, soft exit. */
+.ui-tooltip-content[data-state="delayed-open"],
+.ui-tooltip-content[data-state="instant-open"] {
+  animation: ui-tooltip-in 140ms cubic-bezier(0.22, 1, 0.36, 1);
+}
+
+.ui-tooltip-content[data-state="closed"] {
+  animation: ui-tooltip-out 90ms ease-out;
+}
+
+@keyframes ui-tooltip-in {
+  from {
+    opacity: 0;
+    transform: scale(0.96) translateY(var(--tt-slide-y, 0)) translateX(var(--tt-slide-x, 0));
+  }
+  to {
+    opacity: 1;
+    transform: scale(1) translateY(0) translateX(0);
+  }
+}
+
+@keyframes ui-tooltip-out {
+  from {
+    opacity: 1;
+    transform: scale(1);
+  }
+  to {
+    opacity: 0;
+    transform: scale(0.97);
+  }
+}
+
+/* Slide-from-trigger directional accents */
+.ui-tooltip-content[data-side="top"] { --tt-slide-y: 4px; }
+.ui-tooltip-content[data-side="bottom"] { --tt-slide-y: -4px; }
+.ui-tooltip-content[data-side="left"] { --tt-slide-x: 4px; }
+.ui-tooltip-content[data-side="right"] { --tt-slide-x: -4px; }
+
+@media (prefers-reduced-motion: reduce) {
+  .ui-tooltip-content[data-state="delayed-open"],
+  .ui-tooltip-content[data-state="instant-open"],
+  .ui-tooltip-content[data-state="closed"] {
+    animation: none;
+  }
+}
+
+[data-ui="UiTooltip"] {
+  p, ul {
+    &:not(:last-child) {
+      margin-bottom: 0.75rem;
+    }
+  }
+
+  ul {
+    padding-left: 1.5rem;
+    padding-right: 0.5rem;
+    list-style-type: disc;
+  }
+
+  li {
+    margin-bottom: 0.25rem;
+    list-style-type: disc;
+  }
+
+  code {
+    padding: 0.125rem 0.25rem;
+    border-radius: 0.375rem;
+    background-color: var(--ui-bg-accented);
+  }
+}
+</style>