Add docs page for the Mapbox map component (#2787)

docs/pages/ui/components/map.mdx

@@ -0,0 +1,118 @@
+---
+title: Map
+summary: A map shows places and markers on an interactive world map. Tabler provides the markup and the setup code, and the map itself is rendered by Mapbox GL JS.
+description: Show places on an interactive map.
+layout: '@layouts/DocsMdxLayout.astro'
+---
+import Example from '@components/Example.astro';
+import { Code } from 'astro:components';
+
+## Overview
+
+The map is a small wrapper around [Mapbox GL JS](https://docs.mapbox.com/mapbox-gl-js/). Tabler gives you the container markup and a short init script. Mapbox draws the tiles, handles zoom, and renders the markers.
+
+A Mapbox account and an access token are needed, because every map load calls the Mapbox API. If you only need a simple map of countries or regions, use the [vector map](/ui/components/vector-map/) instead. It needs no account and no network calls.
+
+## Installation
+
+Add the Mapbox GL JS script and stylesheet to your page. Tabler uses version 1.8.0:
+
+<Code
+	lang="html"
+	code={`<link href="https://api.mapbox.com/mapbox-gl-js/v1.8.0/mapbox-gl.css" rel="stylesheet" />
+<script src="https://api.mapbox.com/mapbox-gl-js/v1.8.0/mapbox-gl.js"></script>`}
+/>
+
+Then create a free account on [mapbox.com](https://www.mapbox.com/) and copy your public access token. It starts with `pk.`. Set it once, before you create a map:
+
+```js
+mapboxgl.accessToken = 'pk.your-token-here'
+```
+
+Use a public token only. A secret token (`sk.`) must never be sent to the browser. Limit the token to your own domains in the Mapbox dashboard.
+
+## Usage
+
+### Markup
+
+Put the map container inside a `ratio` element, so the map keeps its shape on every screen size. Give the inner element an `id` and the `w-100 h-100` classes.
+
+<Example codeOnly>
+<div class="ratio ratio-16x9"> <div> <div id="map-simple" class="w-100 h-100"></div> </div> </div>
+</Example>
+
+Change the shape with the ratio classes, for example `ratio-21x9` for a wide map or `ratio-1x1` for a square one.
+
+### Init the map
+
+Create the map after the DOM is ready. Pass the id of your container, a style, a zoom level, and a center point.
+
+```js
+document.addEventListener('DOMContentLoaded', function () {
+  mapboxgl.accessToken = 'pk.your-token-here'
+
+  const map = new mapboxgl.Map({
+    container: 'map-simple',
+    style: 'mapbox://styles/mapbox/streets-v11',
+    zoom: 13,
+    center: [13.4049, 52.518827],
+  })
+})
+```
+
+`center` takes the longitude first and the latitude second. This is the Mapbox order, and it is the opposite of what most map services show.
+
+### Map styles
+
+Set `style` to any Mapbox style URL. These three are used in the Tabler demos:
+
+| Style | Result |
+| --- | --- |
+| `mapbox://styles/mapbox/streets-v11` | Default street map. |
+| `mapbox://styles/mapbox/light-v10` | Light map, good under charts and markers. |
+| `mapbox://styles/mapbox/satellite-v9` | Satellite photos. |
+
+### Markers
+
+Add a marker for each place. `setLngLat` takes the same longitude and latitude order as `center`.
+
+```js
+const cities = [
+  [-58.666667, -34.58333333], // Buenos Aires
+  [16.366667, 48.2], // Vienna
+  [116.383333, 39.91666667], // Beijing
+]
+
+cities.forEach(function (coords) {
+  new mapboxgl.Marker({ color: 'var(--tblr-primary)' }).setLngLat(coords).addTo(map)
+})
+```
+
+The `color` option is written to the `fill` attribute of the marker icon. A CSS variable works there, so `var(--tblr-primary)` keeps the markers in your theme color, including after a theme change.
+
+## Examples
+
+### Map in a card
+
+Add a card title above the map. This is the usual layout for a small map next to other content.
+
+<Example codeOnly>
+<div class="card"> <div class="card-body"> <div class="card-title">Simple map</div> <div class="ratio ratio-16x9"> <div> <div id="map-card" class="w-100 h-100"></div> </div> </div> </div> </div>
+</Example>
+
+### Full-card map
+
+Drop the card body to let the map fill the whole card. Add `rounded` to the container, so the map follows the card corners.
+
+<Example codeOnly>
+<div class="card"> <div class="ratio ratio-21x9"> <div> <div id="map-full" class="w-100 h-100 rounded"></div> </div> </div> </div>
+</Example>
+
+Live versions of these maps are on the [maps preview page](https://preview.tabler.io/maps.html).
+
+## Accessibility
+
+- The map is a picture for most users. Give the same information as text near it, for example the address or a list of places.
+- Add an `aria-label` to the map container, so screen reader users know what the map shows.
+- Do not put an action only on a marker. Repeat it in a normal link or button below the map.
+- Keep a visible fallback when the script fails to load, for example the address in text.

shared/data/docs.json

@@ -232,6 +232,10 @@
 							"title": "Inline player",
 							"url": "/ui/components/inline-player/"
 						},
+						{
+							"title": "Map",
+							"url": "/ui/components/map/"
+						},
 						{
 							"title": "Modal",
 							"url": "/ui/components/modal/"