# PlotOverlay

> Transparent, focusable layer over a plot: one place for pointer hover and keyboard exploration, shared by the non-cartesian charts.

Source: https://ui.jcsoftdev.com/docs/components/plot-overlay

Transparent, focusable layer over a plot: one place for pointer hover and
keyboard exploration, shared by the non-cartesian charts. It is a
`role="slider"` so assistive tech announces `valueText` as the arrows move.
Arrows step, Home/End jump, Escape clears.

## Import

```ts
import { PlotOverlay } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/core`.

## Usage

```tsx
export const Default: Story = {
  render: (args) => <OverlayDemo keys={args.keys ?? "horizontal"} />,
};
```

_Source of the Storybook story._

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `left` * | `number` |  | Position and size of the plot inside the chart container. |
| `top` * | `number` |  |  |
| `width` * | `number` |  |  |
| `height` * | `number` |  |  |
| `label` * | `string` |  | Accessible name (`labels.explore`). |
| `count` * | `number` |  | Number of explorable points. |
| `active` * | `number \| null` |  | Active point, or null. |
| `valueText` * | `string` |  | Reads the active point aloud: category and values. |
| `onActiveChange` * | `(index: number \| null) => void` |  |  |
| `indexAt` * | `(pointer: PlotPointer) => number \| null` |  | Maps a plot-relative pointer to a point; return null to clear (hit-testing charts). |
| `keys` | `"horizontal" \| "vertical" \| "both"` | `"horizontal"` | Which arrow keys step through the points. "both" maps Right/Down to next and Left/Up to previous. |
| `onKey` | `((event: KeyboardEvent<HTMLDivElement>) => boolean)` |  | Extra key handling, e.g. switching streams with Up/Down. Return true when handled. |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-plotoverlay--default)
- [Vertical Keys](/storybook/?path=/story/charts-primitives-plotoverlay--vertical-keys)
- [Both Axes Keys](/storybook/?path=/story/charts-primitives-plotoverlay--both-axes-keys)

## Source

`packages/ui/src/charts/core/plot-overlay.tsx`