# Tooltip

Level: atom.

## Purpose and use

Provide brief supplementary text for a visible target. Use Popup or another appropriate composition for interactive or essential content; the tooltip itself contains plain text only.

## Confirmed M-003 correction target

The resumed M-003 correction removes the component minimum width. Tooltip sizes
to its content up to the verified 240 px maximum; short copy is not expanded to
an artificial 100 px minimum. It also adds an explicit `appearance` contract:
`default` keeps the dark surface with light text, while `inverted` uses a light
surface with dark text for dark-map controls.

## Anatomy and behavior

Project one `[wblTooltipTarget]` inside the wrapper. Hover/focus opens after 400 ms. Leaving the target, focusout, Escape, scrolling or disabling closes it. Empty text, disabled native targets and off-viewport targets do not open. CDK positions use a 4 px gap, fallbacks and 16 px viewport margin. The overlay uses `fit-content` with a 240 px maximum and no minimum inline size. `appearance` changes only the overlay colors; placement, timing, sizing and lifecycle remain unchanged. The component exposes no open-state input/output.

## Appearance and tokens

- `default`: `--color-background-tooltip` background and
  `--color-text-icon-primary-inverted` text.
- `inverted`: `--color-background-level-1-base` background and
  `--color-text-icon-primary` text.
- Both appearances retain the same radius, typography, spacing, shadow-free
  treatment and interaction behavior.

## Accessibility and content

The overlay has role tooltip and connects aria-describedby to the marked target while visible. The target must be keyboard reachable when keyboard access is needed; the wrapper does not add tabindex. The current description handling replaces/removes target aria-describedby rather than merging existing IDs.

## Open Questions

Preserving a target's existing aria-describedby and hover persistence when entering the tooltip need a separate accessibility correction; do not assume they are supported.

## Storybook coverage target

Show short and wrapping copy in both `default` and `inverted` appearances. The
two appearances must retain identical placement, dimensions and open/close
behavior while demonstrating their opposite surface/content contrast.

## Local component contract

This is the M-003 owned contract for `component.tooltip`. Historical migration
evidence does not override the local implementation, template and focused tests
listed below.

### Public type values

- `WblTooltipPlacement = 'top' | 'right' | 'bottom' | 'left'`.
- `WblTooltipAppearance = 'default' | 'inverted'`.

`text` is a required string; `disabled` is boolean. Content projection is
`[wblTooltipTarget]` only.

### Classes and selectors

- `WblTooltipComponent` — `wbl-tooltip` (src/app/design-system/primitives/tooltip/tooltip.component.ts).

### Inputs

- `WblTooltipComponent.text = input.required<string>()`
- `WblTooltipComponent.placement = input<WblTooltipPlacement>('top')`
- `WblTooltipComponent.appearance = input<WblTooltipAppearance>('default')`
- `WblTooltipComponent.disabled = input(false)`

### Models

- None.

### Outputs

- None.

### Slots and projection markers

- `WblTooltipComponent: <ng-content select="[wblTooltipTarget]">`

### Local evidence

- Behavior/template: `src/app/design-system/primitives/tooltip/tooltip.component.html` (reviewed in D-025, 2026-09-05).

- Code: `src/app/design-system/primitives/tooltip/tooltip.component.ts`.
- Focused test: `src/app/design-system/primitives/tooltip/tooltip.component.spec.ts`.
- Public export: `export * from './primitives/tooltip/tooltip.component';` in `src/app/design-system/index.ts`.
- Storybook: `storybook/stories/tooltip.stories.ts` (`Design System/Primitives/wbl-tooltip`).

### Focused regression target

- Short Tooltip copy renders at its content width and is not forced to 100 px.
- Long copy still wraps within the 240 px maximum.
- `default` renders a dark surface with light text; `inverted` renders a light
  surface with dark text.
- Switching appearance does not change placement, delay, sizing,
  `aria-describedby` or close behavior.

## Figma status

This runtime contract does not infer a Figma owner. Assembly evidence, when
verified, is maintained separately through the inventory-linked sidecar.

## Provenance

The archived source-document copy is historical evidence only. The active
resolver is local code/test/export and the exact Storybook story above.

## M-002 integrations

The existing Tooltip API is reused for two new targets:

- sortable Table Header buttons use text «Сортировать»;
- Sidebar collapse uses «Свернуть Ctrl B» / «Развернуть Ctrl B» on
  Windows/Linux and «Свернуть ⌘ B» / «Развернуть ⌘ B» on macOS.

Both targets are native buttons, so hover and keyboard focus follow the current
Tooltip interaction and `aria-describedby` contract. The Tooltip API is
unchanged. Collapse copy contains no separator punctuation and uses thin space
U+2009 between the modifier and `B`; the Sidebar implementation and focused
tests are current evidence.

## Documentation task

M-003 · [GitLab issue](https://gitlab.com/polozovdaniel/logistics-2/-/work_items/39) ·
actor `artem-mokin` / GitLab `26942597` · agent `Specs subagent` ·
run/session `7a124ab4-0ecb-435c-9cb5-dd9df24c995e`.