# Attention (w-attention)

## Description

Note: attention will soon be split into multiple components (tooltip, callout, popover, highlight) at which time this component will be deprecated. For now, use the `tooltip`, `callout`, `popover`, and `highlight` boolean properties to achieve the desired style and behavior.

Attention is a versatile component for displaying contextual information and messages. It can be used for a wide range of purposes, such as tooltips, callouts, popovers, and highlights.

The component is designed to be anchored to a trigger element, providing contextual information related to that element. It supports various placements and styling options to accommodate different use cases and design needs.

[Warp component reference](https://warp-ds.github.io/docs/components/tooltip/frameworks/elements)

## Usage

`w-attention` is used to show contextual messaging anchored to a target element.

### Basic Structure

Use the `target` slot for the trigger/anchor element and the `message` slot for the content.

```html
<w-attention placement="bottom" popover>
  <w-button slot="target" variant="secondary">Open message</w-button>
  <span slot="message">I'm a popover</span>
</w-attention>
```

### Visibility (`show`)

`w-attention` visibility is controlled with the `show` property. Toggle it based on user interaction.

```html
<w-attention id="my-attention" placement="bottom" popover>
  <w-button id="my-trigger" slot="target" variant="secondary">Toggle</w-button>
  <span slot="message">I'm a popover</span>
</w-attention>

<script>
  const trigger = document.getElementById('my-trigger');
  const attention = document.getElementById('my-attention');
  trigger.addEventListener('click', () => {
    attention.show = !attention.show;
  });
</script>
```

### Variants

`w-attention` supports four visual variants:

- `tooltip`
- `popover`
- `callout`
- `highlight`

Use one variant at a time.

```html
<w-attention tooltip placement="right">
  <w-button slot="target" variant="secondary">Hover me</w-button>
  <span slot="message">Short helper text</span>
</w-attention>
```

### Placement and Collision Handling

Use `placement` to define preferred direction. For overlays, `flip`, `cross-axis`, and `fallback-placements` can improve placement in constrained layouts.

```html
<w-attention
  popover
  placement="right"
  flip
  cross-axis
  fallback-placements='["bottom","left","top"]'
>
  <w-button slot="target" variant="secondary">Open</w-button>
  <span slot="message">Smartly positioned message</span>
</w-attention>
```

### Dismissible Messages

Use `can-close` for an internal close button, and listen for the `close` event.

```html
<w-attention id="dismissible-attention" highlight can-close placement="right">
  <w-button id="dismissible-trigger" slot="target" variant="secondary">Show message</w-button>
  <span slot="message">You can dismiss this message.</span>
</w-attention>

<script>
  const trigger = document.getElementById('dismissible-trigger');
  const attention = document.getElementById('dismissible-attention');

  trigger.addEventListener('click', () => {
    attention.show = true;
  });

  attention.addEventListener('close', () => {
    attention.show = false;
  });
</script>
```

## Accessibility

`w-attention` provides built-in accessibility helpers for tooltip/popover/callout messaging:

- It sets `role="tooltip"` for tooltip mode.
- It sets `role="img"` for non-tooltip variants.
- It provides a default localized `aria-label` describing the attention type and arrow direction.

### Authoring Guidance

- Provide meaningful text in the `message` slot.
- Ensure the `target` slot content is keyboard-accessible (for example `w-button` or a native button).
- For hover-triggered tooltips, also support focus/blur so keyboard users receive the same information.

### Reading Order and Placement

For left/top placements, placing the attention message before the target in DOM order can improve screen reader flow.

### Precise ARIA Targeting

If only part of the message should be announced as details, set an explicit id on the relevant message content and reference it from the target with `aria-details`.

```html
<w-attention id="accessible-attention" placement="right" popover>
  <div slot="message">
    <p id="aria-content" role="tooltip">Important contextual text</p>
    <p>Secondary text</p>
  </div>
  <w-button aria-details="aria-content" slot="target" variant="secondary">
    Open
  </w-button>
</w-attention>
```

### Dismissible Attention

When `can-close` is used, ensure your app listens to the `close` event and updates `show` accordingly so the UI and assistive technology state stay in sync.

```html
<w-attention id="dismissible" can-close highlight>
  <w-button slot="target" variant="secondary">Show message</w-button>
  <span slot="message">Dismissible message</span>
</w-attention>

<script>
  const attention = document.getElementById('dismissible');
  attention.addEventListener('close', () => {
    attention.show = false;
  });
</script>
```

## Examples

### Popover (Click To Toggle)

<elements-example>

```html
<w-attention id="example-popover" placement="bottom" popover flip>
  <w-button id="example-popover-trigger" slot="target" variant="secondary">Click to toggle a popover</w-button>
  <span slot="message">I'm a popover</span>
</w-attention>
<script>
  (() => {
    const trigger = document.getElementById('example-popover-trigger');
    const attention = document.getElementById('example-popover');
    trigger.addEventListener('click', () => {
      attention.show = !attention.show;
    });
  })();
</script>
```

</elements-example>

### Tooltip (Hover and Focus)

<elements-example>

```html
<w-attention id="example-tooltip" placement="right" tooltip flip>
  <w-button id="example-tooltip-trigger" slot="target" variant="secondary">Hover or focus me</w-button>
  <span slot="message">I'm a tooltip</span>
</w-attention>
<script>
  (() => {
    const trigger = document.getElementById('example-tooltip-trigger');
    const attention = document.getElementById('example-tooltip');
    trigger.addEventListener('mouseenter', () => {
      attention.show = true;
    });
    trigger.addEventListener('mouseleave', () => {
      attention.show = false;
    });
    trigger.addEventListener('focus', () => {
      attention.show = true;
    });
    trigger.addEventListener('blur', () => {
      attention.show = false;
    });
  })();
</script>
```

</elements-example>

### Inline Callout

<elements-example>
  
```html
<w-attention callout show placement="right">
  <w-button slot="target" variant="secondary">Inline target</w-button>
  <span slot="message">I'm an inline callout</span>
</w-attention>
```

</elements-example>

### Dismissible Highlight

<elements-example>

```html
<w-attention id="example-highlight" highlight can-close placement="right" flip>
  <w-button id="example-highlight-trigger" slot="target" variant="secondary">Click me</w-button>
  <span slot="message">I'm highlighted and dismissible</span>
</w-attention>
<script>
  (() => {
    const trigger = document.getElementById('example-highlight-trigger');
    const attention = document.getElementById('example-highlight');
    trigger.addEventListener('click', () => {
      attention.show = true;
    });
    attention.addEventListener('close', () => {
      attention.show = false;
    });
  })();
</script>
```

</elements-example>

## Styling API

## `<w-attention>` API

Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

### Properties

| Name | Type | Default | Summary |
|-|-|-|-|
| _actualDirection (JS only) | `unknown` | `-` | - |
| _initialPlacement (JS only) | `unknown` | `-` | - |
| activeAttentionType (JS only) | `activeAttentionType() => void` | `-` | - |
| callout | `boolean` | `false` | Renders the component as an inline callout. |
| can-close | `boolean` | `false` | Shows a close button inside the attention component. |
| close (JS only) | `close() => void` | `-` | - |
| cross-axis | `boolean` | `false` | Allows overflow checks on the cross axis when flipping. |
| defaultAriaLabel (JS only) | `defaultAriaLabel() => void` | `-` | - |
| distance | `number` | `8` | Distance offset between trigger and attention panel. |
| fallback-placements | `Directions[]` | `[]` | Ordered list of fallback placements. |
| flip | `boolean` | `false` | Enables automatic flipping when placement has no space. |
| handleDone (JS only) | `handleDone() => void` | `-` | - |
| highlight | `boolean` | `false` | Renders the component with highlight styling. |
| keypressed (JS only) | `keypressed(e: KeyboardEvent) => void` | `-` | - |
| no-arrow | `boolean` | `false` | Hides the directional arrow of the attention component. |
| placement | [`Directions`](#directions) | `"bottom"` | Preferred placement relative to the trigger element. |
| pointingAtDirection (JS only) | `pointingAtDirection() => void` | `-` | - |
| popover | `boolean` | `false` | Enables native popover behavior for the attention element. |
| show | `boolean` | `false` | Controls whether the attention panel is visible. |
| skidding | `number` | `0` | Cross-axis offset for fine-grained positioning. |
| tooltip | `boolean` | `false` | Renders the component with tooltip styling and behavior. |

### Property Details

#### _actualDirection (JS only)



- Type: `unknown`
- Default: `-`

#### _initialPlacement (JS only)



- Type: `unknown`
- Default: `-`

#### activeAttentionType (JS only)



- Type: `activeAttentionType() => void`
- Default: `-`

#### callout

Renders the component as an inline callout.
Callout mode is used for always-in-flow informational content instead of floating overlay behavior.

- Type: `boolean`
- Default: `false`

#### can-close

Shows a close button inside the attention component.
Adds an internal dismiss action that lets users close the attention panel.

- Type: `boolean`
- Default: `false`

#### close (JS only)



- Type: `close() => void`
- Default: `-`

#### cross-axis

Allows overflow checks on the cross axis when flipping.
Use with `flip` to improve collision handling when space is constrained horizontally or vertically.

- Type: `boolean`
- Default: `false`

#### defaultAriaLabel (JS only)



- Type: `defaultAriaLabel() => void`
- Default: `-`

#### distance

Distance offset between trigger and attention panel.
Defines the main-axis spacing in pixels from the anchor element.

- Type: `number`
- Default: `8`

#### fallback-placements

Ordered list of fallback placements.
Provides explicit alternative placements to try when `flip` is enabled and the preferred placement does not fit.

- Type: `Directions[]`
- Default: `[]`

#### flip

Enables automatic flipping when placement has no space.
Allows the component to choose an alternative side if the preferred placement would overflow.

- Type: `boolean`
- Default: `false`

#### handleDone (JS only)



- Type: `handleDone() => void`
- Default: `-`

#### highlight

Renders the component with highlight styling.
Use highlight mode to visually emphasize important contextual information.

- Type: `boolean`
- Default: `false`

#### keypressed (JS only)



- Type: `keypressed(e: KeyboardEvent) => void`
- Default: `-`

#### no-arrow

Hides the directional arrow of the attention component.
Disable the arrow when the visual connection to the trigger should not be shown.

- Type: `boolean`
- Default: `false`

#### placement

Preferred placement relative to the trigger element.
Sets the initial direction for positioning, for example `top`, `right`, `bottom`, or `left` variants.

- Type: [`Directions`](#directions)
- Default: `"bottom"`

#### pointingAtDirection (JS only)



- Type: `pointingAtDirection() => void`
- Default: `-`

#### popover

Enables native popover behavior for the attention element.
When enabled, the component uses popover semantics and styling suitable for floating surface UI.

- Type: `boolean`
- Default: `false`

#### show

Controls whether the attention panel is visible.
Set to `true` to show the attention content and `false` to hide it.

- Type: `boolean`
- Default: `false`

#### skidding

Cross-axis offset for fine-grained positioning.
Moves the panel along the cross axis in pixels to adjust alignment with the trigger.

- Type: `number`
- Default: `0`

#### tooltip

Renders the component with tooltip styling and behavior.
Use for compact, non-modal contextual hints anchored to another element.

- Type: `boolean`
- Default: `false`

### Types

#### Directions

`'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end'`