InteractionTooltip · Traits

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)