# MapViewport

> The shared stage of the maps: draws the regions of a fitted geometry, owns zoom and pan (wheel, drag, pinch, buttons, keys), the region labels, the zoom buttons and the focusable …

Source: https://ui.jcsoftdev.com/docs/components/map-viewport

The shared stage of the maps: draws the regions of a fitted geometry, owns
zoom and pan (wheel, drag, pinch, buttons, keys), the region labels, the
zoom buttons and the focusable keyboard layer. Charts supply fills,
hover/click semantics, an SVG overlay (markers) and HTML (tooltip).

## Import

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

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

## Usage

```tsx
<MapViewport
  caption="Citas por distrito"
  rows={rows}
  valueName="Citas"
  labels={labels}
  height={280}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `width` * | `number` |  |  |
| `height` * | `number` |  |  |
| `title` * | `string` |  | Accessible name of the drawing. |
| `geometry` * | `MapGeometry` |  |  |
| `labels` * | `MapLabels` |  |  |
| `fills` * | `readonly string[]` |  | CSS fill of each region. |
| `interactive` * | `boolean` |  | Regions react to hover, focus and click. Off for a plain base map. |
| `activeRegion` | `number \| null` | `null` | Region under the pointer or the keyboard, or null. |
| `onRegionHover` | `((index: number, event: { clientX: number; clientY: number; }) => void)` |  |  |
| `onLeave` | `(() => void)` |  |  |
| `onRegionClick` | `((index: number) => void)` |  |  |
| `regionLabels` | `readonly (string \| null)[]` |  | Text drawn on each region where it fits (null leaves it out). |
| `controller` * | `{ ref: RefObject<SVGSVGElement \| null>; view: MapView; dragging: boolean; wasDragged: () => boolean; zoomBy: (factor: number, cx?: number, cy?: number) => void; fit: () => void; panBy: (dx: number, dy: number) => void; …` |  | Zoom and pan state, from `useMapView`; the parent owns it so markers can depend on the zoom. |
| `zoomable` * | `boolean` |  | Shows the zoom buttons and enables the zoom keys (gestures are configured in `useMapView`). |
| `containerRef` | `RefObject<HTMLDivElement \| null>` |  | Ref of the positioned container, for pointer-relative tooltips. |
| `keyboard` | `{ count: number; active: number \| null; valueText: string; onKeyDown?: (event: KeyboardEvent<HTMLElement>) => void; onFocus?: () => void; onBlur?: () => void; onActivate?: () => void; }` |  | Keyboard model, usually from `useIndexNavigation(...).sliderProps`. |
| `reveal` | `readonly [number, number] \| null` |  | Zoom 1 pixel position to keep in view while the keyboard moves (null: no panning). |
| `overlay` | `((context: MapViewportContext) => ReactNode)` |  | SVG drawn in screen space over the regions (markers, bubbles). |
| `floating` | `((context: MapViewportContext) => ReactNode)` |  | HTML positioned over the map (tooltips). |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-mapdatatable--default)
- [Narrow](/storybook/?path=/story/charts-primitives-mapdatatable--narrow)
- [Sequential](/storybook/?path=/story/charts-primitives-maplegend--sequential)
- [Diverging](/storybook/?path=/story/charts-primitives-maplegend--diverging)
- [Stepped Ranges](/storybook/?path=/story/charts-primitives-maplegend--stepped-ranges)
- [Default](/storybook/?path=/story/charts-primitives-mapviewport--default)
- [With Region Names](/storybook/?path=/story/charts-primitives-mapviewport--with-region-names)
- [Static Base Map](/storybook/?path=/story/charts-primitives-mapviewport--static-base-map)

## Source

`packages/ui/src/charts/maps/geo/map-viewport.tsx`