Composants

registry.unmap.dev est un registre de composants au format shadcn pour les cartes unmap. Les composants sont copiés dans votre projet, et non installés comme un paquet : vous en possédez le code et pouvez le modifier librement. Ils s'installent comme n'importe quel composant shadcn : on enregistre le registre @unmap une fois, puis on ajoute par nom. Les fichiers arrivent dans components/ui/ et lib/ à côté des vôtres, et la CLI demande avant de remplacer quoi que ce soit.

npx shadcn@latest registry add @unmap=https://registry.unmap.dev/r/{name}.json
npx shadcn@latest add @unmap/map

npx shadcn-vue@latest add https://registry.unmap.dev/r/vue/map.json

La ligne React enregistre le registre une fois par projet, ce qui permet ensuite de nommer les éléments @unmap/<item>; shadcn-vue n'a pas de registry add et prend directement l'URL de l'élément. Les fichiers arrivent dans components/ui/ à côté des vôtres; rien n'est remplacé sans confirmation.

Deux voies, une par CLI, avec les mêmes éléments :

Chaque famille d'éléments a sa page :

@unmap/cli crée un projet shadcn ou shadcn-vue avec les composants déjà en place :

npx @unmap/cli create mon-app --key um_live_...

La commande lance npx shadcn init (ou shadcn-vue init pour --framework nuxt et vue) avec votre gabarit et votre préréglage, enregistre @unmap, ajoute les quatre composants, écrit la clé dans le fichier d'environnement public du cadriciel et remplace la page d'accueil par une carte, une boîte de recherche et un marqueur. Passez --theme <code> depuis /create et elle demande si les marqueurs et les itinéraires prennent l'accent du thème ou le --primary de votre système de design.

npx @unmap/cli add map geocoder

add lit votre package.json pour choisir la voie, écrit lui-même l'entrée @unmap dans components.json si elle n'y est pas encore, puis délègue à la CLI shadcn. À la main, cela fait deux commandes sur React et une seule sur Vue et Nuxt :

npx shadcn@latest registry add @unmap=https://registry.unmap.dev/r/{name}.json
npx shadcn@latest add @unmap/map @unmap/geocoder @unmap/routing-panel @unmap/marker-popup

npx shadcn-vue@latest add https://registry.unmap.dev/r/vue/map.json

shadcn-vue n'a pas encore de commande registry add. Pour écrire @unmap/map plutôt qu'une URL, ajoutez le registre à components.json une fois pour toutes (unmap add le fait pour vous) :

{ "registries": { "@unmap": "https://registry.unmap.dev/r/vue/{name}.json" } }

npx shadcn-vue@latest add @unmap/map @unmap/geocoder @unmap/routing-panel @unmap/marker-popup

Chaque composant lié à la carte dépend de map-context : en ajouter un le récupère. Le géocodeur amène le Combobox officiel ; le panneau d'itinéraire amène Field, Input, Button et Alert. Les éléments React supposent un projet shadcn sur Base UI, le style base-nova que met en place npx shadcn init --base base --preset nova et qu'utilise unmap create : le géocodeur est le Combobox de Base UI, et les contrôles de la carte passent votre Button au Tooltip par la propriété render de Base UI plutôt que par l'asChild de Radix. Prévisualisez avec --dry-run avant de toucher un fichier (shadcn accepte aussi --diff ; shadcn-vue 2.8 ne gère encore ni l'un ni l'autre, donc sur la voie Vue unmap add --dry-run se contente d'afficher ce qu'il exécuterait). npx shadcn search @unmap (ou npx shadcn-vue search @unmap, et view @unmap/map pour le détail d'un élément) liste chaque élément une fois l'espace de noms enregistré.

import { Map } from "@/components/ui/map";
import { Geocoder } from "@/components/ui/geocoder";
import { Marker, Popup } from "@/components/ui/marker-popup";
import { MAP_THEMES } from "@/lib/map-themes";
 
export default function Demo() {
  const apiKey = process.env.NEXT_PUBLIC_UNMAP_KEY!;
  return (
    <div style={{ height: 480 }}>
      <Map apiKey={apiKey} center={[-114.07, 51.05]} zoom={11} theme={MAP_THEMES.boreal} accent="system">
        <div style={{ position: "absolute", top: 12, left: 12, width: 280, zIndex: 10 }}>
          <Geocoder apiKey={apiKey} />
        </div>
        <Marker lngLat={[-114.07, 51.05]}>
          <Popup>Centre-ville de Calgary</Popup>
        </Marker>
      </Map>
    </div>
  );
}

La carte que ces composants montent est celle que construit @unmap/maps, et elle ressemble à ceci :

import { Unmap } from "@unmap/sdk";

const unmap = new Unmap({
  key: "um_live_...",
  container: "map",
  style: "base",
  mode: "light",
  lang: "fr",
  center: [-114.07, 51.05],
  zoom: 11,
});

Si vous préférez ne pas copier de composants, @unmap/react et @unmap/next fournissent la même carte sous forme de hooks et de composant prêt à l'emploi. Voir la Vue d'ensemble.

La voie Vue s'installe par shadcn-vue dans un projet qui a exécuté npx shadcn-vue init. Les fichiers arrivent un dossier par élément, chacun avec un index.ts : components/ui/map/UnmapMap.vue, geocoder/UnmapGeocoder.vue, routing-panel/UnmapRoutingPanel.vue, marker-popup/UnmapMarker.vue, UnmapPopup.vue, UnmapMarkerTooltip.vue et UnmapMarkerLabel.vue, plus lib/map-context/index.ts, sous src/ ou le app/ de Nuxt 4 selon vos alias. L'import est @/lib/map-context.

<script setup lang="ts">
import { UnmapMap } from "@/components/ui/map";
import { UnmapGeocoder } from "@/components/ui/geocoder";
import { UnmapMarker, UnmapPopup } from "@/components/ui/marker-popup";
 
const apiKey = import.meta.env.VITE_UNMAP_KEY;
</script>
 
<template>
  <div style="height: 480px">
    <UnmapMap :api-key="apiKey" :center="[-114.07, 51.05]" :zoom="11" theme="u4e" accent="system">
      <div style="position: absolute; top: 12px; left: 12px; width: 280px; z-index: 10">
        <UnmapGeocoder :api-key="apiKey" />
      </div>
      <UnmapMarker :lng-lat="[-114.07, 51.05]">
        <UnmapPopup>Centre-ville de Calgary</UnmapPopup>
      </UnmapMarker>
    </UnmapMap>
  </div>
</template>

UnmapMap reçoit le style sous map-style ("base", "muted", "outdoor", "blueprint", "blush", "orchid", "canopy", "lagoon", "tropic", "sunset", "bold", "pastel", "atlas" ou "swiss") pour que l'attribut style continue de styler le conteneur ; class et style lui sont transmis. Il accepte aussi mode ("light" ou "dark") et lang ("en" ou "fr"). Les noms gardent le préfixe Unmap parce que <map> est un élément HTML. Sur Nuxt, shadcn-nuxt lit l'index.ts de chaque dossier et importe automatiquement les composants sous <UiUnmapMap>, <UiUnmapGeocoder>, etc. ; définissez shadcn: { prefix: "" } dans nuxt.config.ts pour les utiliser sous <UnmapMap>.

Pas sur shadcn-vue ? @unmap/vue et @unmap/nuxt fournissent la carte, le géocodeur et l'itinéraire sous forme de composables pour n'importe quelle interface. Voir la Vue d'ensemble.

Style et thème

Le registre ne livre ni thème ni couleur de marque. Les composants adoptent votre système de design :

• Le conteneur de carte utilise rounded-lg et bg-muted, donc il suit votre --radius et votre palette.
• Le géocodeur et le panneau d'itinéraire sont vos propres primitives shadcn.
• Les infobulles, les boutons de zoom et de boussole, l'attribution et l'échelle de MapLibre sont restylés sur --popover, --background, --border, --radius, --ring et --muted-foreground par le CSS que l'élément map ajoute à votre feuille de style à l'installation, limité à [data-unmap-map] pour laisser intactes les autres cartes de votre application ; les infobulles et les contrôles prennent la police de la page via font: inherit. L'habillage suit votre classe .dark.
• Les marqueurs et les lignes d'itinéraire prennent par défaut votre --primary, résolu en couleur concrète quand ils sont dessinés, puis de nouveau après chaque changement de style, parce que la peinture MapLibre ne lit pas var().
• Les boutons de zoom et de boussole sont activés par défaut, en haut à droite. <Map controls={false}> les retire et <Map controls={{ position: 'bottom-left' }}> les déplace. L'attribution reste dans tous les cas. Pour des boutons sur vos propres primitives, ajoutez map-controls, décrit dans Carte et marqueurs.
• La carte est un globe par défaut, qui s'aplatit en Mercator quand on zoome. <Map projection="mercator"> dessine la carte plane à tous les zooms.
• Le fond de carte suit le mode clair ou sombre de votre page : une classe dark ou light sur <html>, puis data-theme, puis color-scheme, puis le réglage système du lecteur. <Map mode="light"> ou mode="dark" le fixe. Changer de mode, de style, de thème ou de lang remplace le style sur place : la caméra, les marqueurs, les fenêtres contextuelles et un itinéraire tracé restent en place.
• Les couches que vous ajoutez vous-même doivent s'ajouter de nouveau quand useMapGeneration() change, ou quand useMapReady() repasse à true : un changement de style retire toutes les sources et toutes les couches.
• center, zoom, bearing et pitch déplacent la caméra sur place. Passez onViewportChange (Vue : @viewport-change) et renvoyez les valeurs pour une carte contrôlée ; les mouvements causés par ces props ne sont pas renvoyés, donc aucune boucle n'est possible.
• Votre Spinner couvre la carte jusqu'au chargement de son premier style. <Map loading> l'affiche à la demande, par exemple pendant le chargement de vos propres données.

La cartographie est distincte de l'interface. La propriété theme reçoit un code court comme u4e ou un code ut1. complet du compositeur de thèmes ; ce code porte ses propres couleurs de marqueur et d'itinéraire. <Map accent="theme" | "system"> dit laquelle l'emporte : "theme" par défaut quand un theme est défini, "system" sinon, et la boîte d'export de /create vous pose la question avant d'écrire l'extrait. Une propriété color ou lineColor explicite l'emporte toujours sur les deux. Voir l'API de cartes.

Chaque composant marque sa racine d'un attribut data-unmap-map, data-unmap-geocoder, data-unmap-routing ou data-unmap-legend, et chaque infobulle porte la classe unmap-popup, comme points d'accroche pour votre propre CSS.

Les modèles de cartes sont des expériences React complètes distribuées comme éléments registry:block. Ils copient des composants modifiables et des données de démonstration en français et en anglais, installent leurs dépendances et suivent votre thème shadcn. Les quatre modèles utilisent les primitives shadcn Base UI.

Une fois l'espace de noms @unmap ci-dessus configuré :

npx shadcn@latest add @unmap/business-locator-01
npx shadcn@latest add @unmap/local-guide-01
npx shadcn@latest add @unmap/public-notices-01
npx shadcn@latest add @unmap/map-story-01

Ou avec la CLI unmap, qui fonctionne aussi pour les exemples : npx @unmap/cli add business-locator-01.

Vous pouvez aussi installer directement, sans configurer l'espace de noms :

npx shadcn@latest add https://registry.unmap.dev/r/business-locator-01.json

import { BusinessLocator } from "@/components/unmap-business-locator"
 
<BusinessLocator apiKey="um_live_..." lang="fr" />

Passez votre clé navigateur et autorisez l'origine de votre site. Utilisez lang="fr" pour le français. Modifiez lib/business-locator-01-data.ts pour remplacer les lieux, et les composants copiés pour changer la disposition. Les autres exports sont LocalGuide, PublicNotices et MapStory, dans components/unmap-local-guide.tsx, components/unmap-public-notices.tsx et components/unmap-map-story.tsx.

MapStory suit le défilement du lecteur, avec ses chapitres dans lib/map-story-01-data.ts : quand un chapitre atteint le milieu de l'écran, la caméra s'y rend, et un chapitre qui a un itinéraire ou des zones de temps de parcours les demande une seule fois à l'API d'itinéraires, la première fois qu'il s'ouvre (une requête chacun). LocalGuide, lui, passe d'un arrêt à l'autre avec les boutons Arrêt précédent et Arrêt suivant.

Les petits exemples sont distribués de la même façon : un élément chacun, en React seulement, à installer avec npx @unmap/cli add <nom>. Ils figurent dans la galerie et à côté de chaque élément sur la page de sa famille, comme Outils cartographiques.

Les modèles et les exemples sont livrés dans la voie React seulement ; les blocs de page s'installent dans les deux. Le localisateur de commerces, le guide local et les avis publics ont aussi des modèles HTML autonomes et des téléchargements GeoJSON sur leurs pages de modèle.

registry.unmap.dev/llms.txt répertorie chaque élément pour les agents de programmation, et chaque élément a une page Markdown avec sa commande d'installation, ses propriétés et un exemple qui fonctionne : registry.unmap.dev/llm/<item>.md pour React et registry.unmap.dev/llm/vue/<item>.md pour Vue et Nuxt. npx @unmap/cli add affiche les pages des éléments qu'il installe. Une consigne qui fonctionne dans un projet doté d'un components.json :

Lis https://registry.unmap.dev/llms.txt. Ensuite, exécute npx @unmap/cli add map dans ce projet et affiche la carte sur la page d'accueil, centrée sur Calgary, avec ma clé unmap lue dans l'environnement.

Prochaines étapes

• Parcourez chaque élément avec ses commandes d'installation sur registry.unmap.dev.
• Le Démarrage rapide pour la voie JavaScript pur avec @unmap/sdk.
• L'API de géocodage et l'API d'itinéraires pour ce que le géocodeur et le panneau d'itinéraire appellent sous le capot.
• Énergie pour energy-map, well-search, energy-popup et energy-layer-control.