[Traits](https://oods-foundry.com/traits) / InteractionTooltip

# InteractionTooltip

Shows contextual details-on-demand when focusing or hovering a specific datum.

Generated from @oods/foundry 0.10.1

- Group

  viz.interaction

- Maturity

  alpha

- Contexts

  none listed

## Fields it adds

| Field | Type | Required | Description |
| - | - | - | - |
| `viz_interaction_tooltip_fields` | `string[]` | yes | Fields surfaced inside the tooltip. |
| `viz_interaction_tooltip_trigger` | `string` (hover, focus) | yes | Event stream used to reveal the tooltip. |
| `viz_interaction_tooltip_alignment` | `string` (auto, top, bottom, left, right) | no | Preferred tooltip alignment token. |

## What it shows in each context

This trait places no component of its own.

## Parameters

- `fields` `string[]`, required

  Ordered field list rendered inside the tooltip.

- `trigger` `string`

  Event stream that reveals the tooltip.

- `alignment` `string`

  Preferred tooltip alignment around the data point.

## States

`hidden`, `visible` . It starts `hidden`.

- `hidden` to `visible`, on `show`
- `visible` to `hidden`, on `dismiss`

## Objects that use it

No shipped object uses this trait.

## The trait file

`traits/viz/interaction-tooltip.trait.yaml`

```
trait:
  name: InteractionTooltip
  version: 0.2.0
  description: >-
    Shows contextual details-on-demand when focusing or hovering a specific datum.
  category: viz.interaction
  tags:
    - viz
    - interaction
    - tooltip

parameters:
  - name: fields
    type: string[]
    required: true
    description: Ordered field list rendered inside the tooltip.
  - name: trigger
    type: string
    required: false
    description: Event stream that reveals the tooltip.
    default: hover
    validation:
      enum:
        - hover
        - focus
  - name: alignment
    type: string
    required: false
    description: Preferred tooltip alignment around the data point.
    default: auto
    validation:
      enum:
        - auto
        - top
        - bottom
        - left
        - right

schema:
  viz_interaction_tooltip_fields:
    type: string[]
    required: true
    description: Fields surfaced inside the tooltip.
  viz_interaction_tooltip_trigger:
    type: string
    required: true
    description: Event stream used to reveal the tooltip.
    defaultFromParameter: trigger
    validation:
      enum:
        - hover
        - focus
  viz_interaction_tooltip_alignment:
    type: string
    required: false
    description: Preferred tooltip alignment token.
    defaultFromParameter: alignment
    validation:
      enum:
        - auto
        - top
        - bottom
        - left
        - right

semantics:
  viz_interaction_tooltip_fields:
    semantic_type: viz.interaction.fields
    ui_hints:
      component: ListSummary
  viz_interaction_tooltip_trigger:
    semantic_type: viz.interaction.trigger
    ui_hints:
      component: Badge
  viz_interaction_tooltip_alignment:
    semantic_type: viz.interaction.tooltip.alignment
    ui_hints:
      component: Badge

state_machine:
  states:
    - hidden
    - visible
  initial: hidden
  transitions:
    - from: hidden
      to: visible
      trigger: show
    - from: visible
      to: hidden
      trigger: dismiss

tokens:
  viz.interaction.tooltip.bg: "var(--cmp-viz-tooltip-bg)"
  viz.interaction.tooltip.text: "var(--cmp-viz-tooltip-text)"
  viz.interaction.tooltip.border: "var(--cmp-viz-tooltip-border)"
  viz.interaction.tooltip.shadow: "var(--cmp-viz-tooltip-shadow)"

dependencies: []

metadata:
  created: "2025-11-15"
  updated: "2026-02-28"
  owners:
    - viz@oods.systems
    - accessibility@oods.systems
  maturity: alpha
  accessibility:
    keyboard: |
      Tooltip is triggered on focus (not just hover) to support keyboard-only users.
      Escape dismisses the tooltip. Tooltip content is not focusable — it is read-only
      supplementary information announced by the screen reader.
    screenreader: |
      Tooltip content is exposed via aria-describedby on the focused datum.
      Screen readers announce the tooltip fields in declared order when the
      datum receives focus.
    focusManagement: |
      Focus remains on the data mark, not the tooltip. The tooltip is a non-modal
      overlay that follows the focused element. Dismissal returns no focus change.
  examples:
    - RevenueByRegionTooltip
    - UserActivityHoverDetail
  references:
    - "WCAG 2.1 SC 1.4.13 — Content on Hover or Focus"
    - RDS.7 Trait-Driven Visualization System Specification (v0.1)
```