denwa-react-shared/skills/material-map/SKILL.md

---
name: material-map
description: >
  Integrate Yandex Maps for coordinate selection. Covers map initialization, 
  setting markers, and coordinate synchronization.
type: framework
library: denwa-react-shared
framework: react
library_version: "1.0.88"
requires:
  - session-auth
sources:
  - "Denwa799/react-shared:src/shared/ui/material-map/index.tsx"
---

# Yandex Maps Integration

`BaseMaterialMap` uses Yandex Maps to allow users to select geographic coordinates. It requires a Yandex Maps API key and provides a simple interface for single-point selection.

## Setup

```tsx
import { BaseMaterialMap } from 'denwa-react-shared';

const LocationPicker = () => {
  return (
    <BaseMaterialMap
      apiKey="your-yandex-api-key"
      value={{ lat: 55.751244, lng: 37.618423 }}
      onChange={(coords) => setLocation(coords)}
      height={400}
      zoom={10}
      noDataText="Координаты не выбраны"
    />
  );
};
```

## Core Patterns

### Manual Coordinate Entry
The component displays the current coordinates in inputs. Users can either click on the map or type values manually. Always ensure `onChange` is provided to capture changes from both sources.

### Custom Height and Styling
The map container should be constrained by the `height` prop. It defaults to `100%` width of the parent container.

## Common Mistakes

### CRITICAL Missing API Key
Wrong:
```tsx
<BaseMaterialMap value={coords} />
```
Correct:
```tsx
<BaseMaterialMap apiKey={import.meta.env.VITE_YAMAP_KEY} value={coords} />
```
The map uses `@iminside/react-yandex-maps` internally. If the `apiKey` is missing or invalid, the map will fail to load or will show a "Demo mode" watermark.

Source: src/shared/ui/material-map/index.tsx

### HIGH Forgetting default center for empty values
If the `value` is undefined, the map might center on a default (often 0,0) or fail. Always provide a fallback `defaultCenter` or check for existence.

Source: maintainer interview