Beautiful map components. 100% Free, Zero config, one command setup.
TypeScript
feat(site): add mapcn agent skill, hero install command
Anmol4f2f059d86a1
diff --git a/README.md b/README.mdindex 9a39921..89cf99e 100644--- a/README.md+++ b/README.md@@ -37,6 +37,16 @@- ๐ค๏ธ **Routes** โ Draw routes and paths on your maps- ๐ฎ **Controls** โ Zoom, compass, locate, and fullscreen controls+## Agent Skill++Teach your coding agent (Claude Code, Cursor, Codex, โฆ) how to use mapcn:++```bash+npx skills add AnmolSaini16/mapcn+```++Then ask for a map, or ask where one would fit in your app. See [mapcn.dev/docs/skill](https://mapcn.dev/docs/skill).+## Basemap Terms of ServiceThis project uses [CARTO Basemaps](https://docs.carto.com/faqs/carto-basemaps) which are based on OpenStreetMap data.diff --git a/package.json b/package.jsonindex 21f9307..61c51a8 100644--- a/package.json+++ b/package.json@@ -7,7 +7,8 @@"build": "next build","start": "next start","lint": "eslint",- "registry:build": "npx shadcn build -o ./public/r && npx tsx scripts/fix-registry-imports.ts",+ "registry:build": "npx shadcn build -o ./public/r && npx tsx scripts/fix-registry-imports.ts && npm run skill:build",+ "skill:build": "npx tsx scripts/build-skill.ts","blocks:thumbnails": "npx tsx scripts/capture-block-thumbnails.ts"},"dependencies": {diff --git a/public/r/delivery-tracker.json b/public/r/delivery-tracker.jsonindex c4d5f73..5fbd360 100644--- a/public/r/delivery-tracker.json+++ b/public/r/delivery-tracker.json@@ -4,7 +4,8 @@"title": "Delivery Tracker","description": "Live order tracking with route progress, courier position, and order details.","dependencies": [- "lucide-react"+ "lucide-react",+ "next-themes"],"registryDependencies": ["@mapcn/map",diff --git a/public/r/registry.json b/public/r/registry.jsonindex 94941e3..855de05 100644--- a/public/r/registry.json+++ b/public/r/registry.json@@ -208,7 +208,8 @@"title": "Delivery Tracker","description": "Live order tracking with route progress, courier position, and order details.","dependencies": [- "lucide-react"+ "lucide-react",+ "next-themes"],"registryDependencies": ["@mapcn/map",diff --git a/registry.json b/registry.jsonindex 94941e3..855de05 100644--- a/registry.json+++ b/registry.json@@ -208,7 +208,8 @@"title": "Delivery Tracker","description": "Live order tracking with route progress, courier position, and order details.","dependencies": [- "lucide-react"+ "lucide-react",+ "next-themes"],"registryDependencies": ["@mapcn/map",diff --git a/scripts/build-skill.ts b/scripts/build-skill.tsnew file mode 100644index 0000000..3326b3c--- /dev/null+++ b/scripts/build-skill.ts@@ -0,0 +1,286 @@+import { execFileSync } from "child_process";+import fs from "fs";+import path from "path";++import registry from "../registry.json";+import { createBasemapMarkdown, type RegistryItem } from "@/lib/llm-content";++// SKILL.md and references/patterns.md are hand-written. This script fills the+// generated sections of SKILL.md and rewrites the generated reference files.+const ROOT = process.cwd();+const SKILL_DIR = path.join(ROOT, "skills", "mapcn");+const REFERENCES_DIR = path.join(SKILL_DIR, "references");+const DOCS_DIR = path.join(ROOT, "src/app/(main)/docs");+const SITE = "https://mapcn.dev";+const EXAMPLES_PATH = "src/app/(main)/docs/_components/examples";+const EXAMPLES_RAW = `https://raw.githubusercontent.com/AnmolSaini16/mapcn/${getExamplesCommit()}/${EXAMPLES_PATH}`;++const groups: {+ title: string;+ docs: string;+ exports: Record<string, string>;+}[] = [+ {+ title: "Map",+ docs: "/docs/basic-map",+ exports: {+ Map: "The map itself. Fills its parent, takes `center` ([lng, lat]), `zoom`, `theme`, `styles`, `blank`, `projection`, controlled `viewport`, `loading`, plus any MapLibre map option.",+ useMap:+ "Hook for children of `<Map>`: returns `{ map, isLoaded }` for raw MapLibre access.",+ },+ },+ {+ title: "Controls",+ docs: "/docs/controls",+ exports: {+ MapControls:+ "Zoom, compass, locate and fullscreen buttons. Pick with `showZoom`, `showCompass`, `showLocate`, `showFullscreen` and place with `position`.",+ },+ },+ {+ title: "Markers",+ docs: "/docs/markers",+ exports: {+ MapMarker:+ "A DOM marker at `longitude`/`latitude`. Supports `draggable` and click, hover and drag handlers.",+ MarkerContent:+ "Custom marker visuals. Any React content; defaults to a dot.",+ MarkerPopup: "Popup that opens when its marker is clicked.",+ MarkerTooltip: "Tooltip shown while hovering its marker.",+ MarkerLabel: "Text label above or below its marker (`position`).",+ },+ },+ {+ title: "Popups",+ docs: "/docs/popups",+ exports: {+ MapPopup:+ "Standalone popup at any coordinate, controlled by your state. Use it for clicks on layers, clusters or arcs.",+ },+ },+ {+ title: "Routes",+ docs: "/docs/routes",+ exports: {+ MapRoute:+ "Line through `coordinates` ([lng, lat][]), with `progress` (0โ1) for tracking. Render-only: fetch directions in the parent.",+ RouteProgress:+ "Inside `MapRoute`: styles the travelled part of the route, up to the route's `progress`.",+ RouteMarker:+ 'Inside `MapRoute`: a marker pinned along the route with `at` (`"start"`, `"end"`, `"progress"` or a 0โ1 fraction), such as a courier.',+ },+ },+ {+ title: "Arcs",+ docs: "/docs/arcs",+ exports: {+ MapArc:+ "Curved lines between origin/destination pairs (flights, trade lanes), with hover and click events.",+ },+ },+ {+ title: "GeoJSON",+ docs: "/docs/geojson",+ exports: {+ MapGeoJSON:+ "Fill and outline layers from a GeoJSON object or URL, with `fillPaint`, `linePaint`, `fillHoverPaint` and hover and click events. Pair with `<Map blank>` for choropleths.",+ },+ },+ {+ title: "Clusters",+ docs: "/docs/clusters",+ exports: {+ MapClusterLayer:+ "GPU-clustered points from GeoJSON (object or URL) for large datasets, with point and cluster click handlers.",+ },+ },+];++// Pin example links to the last commit that touched them, so an installed+// skill keeps working when examples are renamed or moved on main.+function getExamplesCommit() {+ const git = (...args: string[]) =>+ execFileSync("git", args, { cwd: ROOT, encoding: "utf8" }).trim();+ try {+ if (git("status", "--porcelain", "--", EXAMPLES_PATH)) {+ console.warn(+ "Docs examples have uncommitted changes: commit them and rebuild, or example links will point at the previous versions.",+ );+ }+ return git("log", "-1", "--format=%H", "--", EXAMPLES_PATH) || "main";+ } catch {+ return "main";+ }+}++function getMapExports() {+ const source = fs.readFileSync(+ path.join(ROOT, "src/registry/map.tsx"),+ "utf8",+ );+ const block = source.match(/^export \{([^}]+)\};/m);+ if (!block) throw new Error("Couldn't find the export block in map.tsx");+ return block[1]+ .split(",")+ .map((name) => name.trim())+ .filter(Boolean);+}++function checkExportsCovered() {+ const documented = new Set(groups.flatMap((g) => Object.keys(g.exports)));+ const exported = getMapExports();+ const missing = exported.filter((name) => !documented.has(name));+ const stale = [...documented].filter((name) => !exported.includes(name));+ if (missing.length || stale.length) {+ throw new Error(+ [+ missing.length && `Undocumented exports: ${missing.join(", ")}`,+ stale.length && `Documented but not exported: ${stale.join(", ")}`,+ ]+ .filter(Boolean)+ .join("\n") + "\nUpdate `groups` in scripts/build-skill.ts.",+ );+ }+}++function fillSection(source: string, name: string, content: string) {+ const pattern = new RegExp(+ `(<!-- generated:${name} -->)[\\s\\S]*?(<!-- /generated:${name} -->)`,+ );+ if (!pattern.test(source)) {+ throw new Error(`SKILL.md is missing the generated:${name} markers`);+ }+ return source.replace(+ pattern,+ (_, open, close) => `${open}\n${content.trim()}\n${close}`,+ );+}++function createComponentList() {+ return groups+ .map(+ (g) =>+ `- **${g.title}:** ${Object.keys(g.exports)+ .map((name) => `\`${name}\``)+ .join(", ")}`,+ )+ .join("\n");+}++function createComponentsMarkdown() {+ const sections = groups.map((g) =>+ [+ `## ${g.title}`,+ "",+ `Docs: ${SITE}${g.docs}`,+ "",+ ...Object.entries(g.exports).map(+ ([name, description]) => `- \`${name}\`: ${description}`,+ ),+ ...formatExamples(g.docs),+ ].join("\n"),+ );++ return [+ "# Components",+ "",+ "All exports come from `@/components/ui/map`, installed by `npx shadcn@latest add @mapcn/map`. Every prop is typed and commented in that file, so read it for exact props. Prop types are exported too (`MapProps`, `MapMarkerProps`, โฆ), along with `MapRef` for `<Map ref>` and `MapViewport`.\n\nExamples link to the source of the demos in the docs. Fetch one only when you need a full working version. If a link fails, the docs page above shows the same example. They import from `@/registry/map`, which is `@/components/ui/map` in an installed project.",+ "",+ ...sections.flatMap((s) => [s, ""]),+ "## Advanced",+ "",+ `Docs: ${SITE}/docs/advanced-usage`,+ ...formatExamples("/docs/advanced-usage"),+ "",+ ].join("\n");+}++// Examples shown on a docs page, read from its getExampleSource() calls.+function formatExamples(docs: string) {+ const page = path.join(DOCS_DIR, docs.replace(/^\/docs\/?/, ""), "page.tsx");+ const source = fs.readFileSync(page, "utf8");+ const files = [...source.matchAll(/getExampleSource\("([^"]+)"\)/g)].map(+ (match) => match[1],+ );+ if (!files.length) return [];+ return ["", "Examples:", ...files.map((file) => `- ${EXAMPLES_RAW}/${file}`)];+}++function usesNextThemes(block: RegistryItem) {+ return (block.files ?? []).some((file) =>+ fs.readFileSync(path.join(ROOT, file.path), "utf8").includes("next-themes"),+ );+}++function createBlocksMarkdown() {+ const blocks = (registry.items as RegistryItem[]).filter(+ (item) => item.type === "registry:block",+ );++ const sections = blocks.map((block) => {+ const page = block.files?.find((file) => file.type === "registry:page");+ return [+ `## ${block.title ?? block.name}`,+ "",+ block.description ?? "",+ "",+ "```bash",+ `npx shadcn@latest add @mapcn/${block.name}`,+ "```",+ "",+ page?.target ? `- Adds the page at \`${page.target}\`` : null,+ `- Files: ${(block.files ?? []).map((file) => `\`${file.target ?? file.path}\``).join(", ")}`,+ usesNextThemes(block)+ ? "- Reads the theme with `useTheme` from `next-themes`. Without next-themes, use the project's own theme hook, or remove it and let the map follow the theme itself."+ : null,+ block.registryDependencies?.length+ ? `- Pulls in: ${block.registryDependencies.map((dep) => `\`${dep}\``).join(", ")}`+ : null,+ `- Preview: ${SITE}/blocks/${block.name}`,+ ]+ .filter((line) => line !== null)+ .join("\n");+ });++ return [+ "# Blocks",+ "",+ "Full pages built from the map components, installed into the user's app with the shadcn CLI. Most ship with sample data (usually `data.ts`): swap in the user's data.",+ "",+ "## Routes outside the Next.js App Router",+ "",+ 'Block files install to App Router paths (`app/<route>/page.tsx`, with `data.ts` and `components/` beside it). Every block page is a `"use client"` component with `export default function Page`. Check the project\'s router and move the files to match:',+ "",+ "- **Next.js App Router:** keep the paths. Rename the route folder if it clashes with an existing page.",+ "- **Remix or React Router (framework mode):** `app/` is the app's own source folder. Move the page into `app/routes/` (for example `app/routes/store-locator.tsx`), or register it in `app/routes.ts` if the project uses config routes. Keep `data.ts` and `components/` outside `app/routes/`.",+ "- **Next.js Pages Router:** move the page to `pages/<route>.tsx`, or `pages/<route>/index.tsx`, and keep `data.ts` and `components/` outside `pages/` so they don't become routes.",+ "- **Vite, React Router, TanStack Router and others:** move the folder to where the project keeps pages (for example `src/pages/<route>/`), rename `page.tsx` and `Page` to something like `StoreLocatorPage`, and register it in the router config.",+ "- **No router:** render the page component where the user wants it.",+ "",+ "After moving, fix the relative imports (`./data`, `./components/...`) and delete only the emptied `app/<route>/` folder the block created. Never delete `app/` itself: in Next.js, Remix and React Router it holds the rest of the app.",+ "",+ ...sections.flatMap((s) => [s, ""]),+ ].join("\n");+}++function main() {+ checkExportsCovered();++ const skillPath = path.join(SKILL_DIR, "SKILL.md");+ let skill = fs.readFileSync(skillPath, "utf8");+ skill = fillSection(skill, "basemap", createBasemapMarkdown());+ skill = fillSection(skill, "components", createComponentList());+ fs.writeFileSync(skillPath, skill);++ fs.writeFileSync(+ path.join(REFERENCES_DIR, "components.md"),+ createComponentsMarkdown(),+ );+ fs.writeFileSync(+ path.join(REFERENCES_DIR, "blocks.md"),+ createBlocksMarkdown(),+ );+ console.log("Built skills/mapcn: SKILL.md, components.md, blocks.md");+}++main();diff --git a/skills/mapcn/SKILL.md b/skills/mapcn/SKILL.mdnew file mode 100644index 0000000..bbe4080--- /dev/null+++ b/skills/mapcn/SKILL.md@@ -0,0 +1,78 @@+---+name: mapcn+description: Build maps in React with mapcn, themeable shadcn-style map components on MapLibre GL and Tailwind CSS. Use when the user wants to add, customize or theme a map: markers, popups, tooltips, routes, arcs, GeoJSON or choropleth layers, clusters, a globe, custom basemap styles or light/dark theming, or a full map page (analytics dashboard, delivery tracker, store locator) in a React, Next.js or Vite project using shadcn/ui or Tailwind. Also use when they ask where a map would fit in their app.+---++# mapcn++Map components for React that you install with the shadcn CLI. Everything lives in one file, `components/ui/map.tsx`, built on MapLibre GL and styled with the project's shadcn theme. Blocks are full pages (dashboards, trackers, locators) built from those components.++## When the user hasn't named a map++If they ask what mapcn could do for their app, or where a map would fit:++1. Read the stack (`package.json`, `components.json`) and skim the pages and data models.+2. Suggest 2โ4 places a map fits, most noticeable first. Tie each one to something real in their code and name what you'd use, for example:+ - addresses or locations, leading to a **Store Locator** or markers with popups+ - orders or shipments, leading to **Delivery Tracker** (`MapRoute` + `RouteProgress`)+ - per-country or per-region stats, leading to **Choropleth** or **Analytics Map**+ - links between places (flights, traffic, supply chains), leading to `MapArc` or **Logistics Network**+3. Install and build only what the user picks.++## Before you start++1. **shadcn/ui and Tailwind CSS.** Look for `components.json`. If there isn't one, tell the user mapcn needs shadcn/ui and offer to run `npx shadcn@latest init` first.+2. **Already installed?** Check `aliases.ui` in `components.json` (usually `@/components/ui`) for `map.tsx`. If it's there, don't reinstall. Read it instead.++## Install++```bash+npx shadcn@latest add @mapcn/map+```++That adds `components/ui/map.tsx`, installs `maplibre-gl` and adds a few popup and attribution styles to the global CSS. Blocks install the same way, `npx shadcn@latest add @mapcn/<block>`, and pull in the map component themselves. Block files install to Next.js App Router paths (`app/<route>/page.tsx`). In any other setup, move them and register the route: see `references/blocks.md`.++Never write or paste `map.tsx` by hand. If the CLI fails, read https://mapcn.dev/r/map.json, install the dependencies it lists, and report what went wrong.++## Rules++- **Give the map a height.** `<Map>` fills its parent, and a parent without a height shows nothing. Wrap it: `<div className="h-[400px]">` or `<Card className="h-[320px] overflow-hidden p-0">`.+- **Coordinates are `[longitude, latitude]`.** `center={[-74.006, 40.7128]}` is New York. Markers take `longitude` and `latitude` props. Swapping them is the most common bug.+- **Client components only.** `map.tsx` is already `"use client"`. Any component that uses `useMap`, refs or map event handlers needs it too. In Next.js, keep data fetching in a server component and pass the data down.+- **Props are documented in the installed `map.tsx`.** Every prop has a JSDoc comment. Read the types there and don't guess. Don't edit the file unless the user asks.+- **Routes don't fetch.** `MapRoute` only draws the coordinates it's given; `RouteProgress` and `RouteMarker` go inside it and work from that same line. Fetch directions (OSRM, Mapbox, Google) in the parent and pass `[lng, lat][]` down. See the OSRM example linked under Routes in `references/components.md`. `MapGeoJSON` and `MapClusterLayer` take a GeoJSON object or a URL.+- **Use theme colors in your own UI.** Marker content, popups and overlays are plain React, so use `bg-background`, `text-muted-foreground`, `border` and so on. Data colors on lines and fills (`MapRoute color`, paint props) can be real colors.+- **Theme follows the app.** The basemap switches light/dark from a `dark` or `light` class or a `data-theme` attribute on `<html>` (next-themes works out of the box), falling back to the system preference. Pass `theme` only to force one.+- **Raw MapLibre when you need it:** `useMap()` inside `<Map>` returns `{ map, isLoaded }`, or pass a `ref` (`MapRef`) to `<Map>`. Wait for `isLoaded` before adding sources or layers, and remove them on cleanup.++<!-- generated:basemap -->+## Basemap Selection++- Use `<Map>` without `blank` for the default free CARTO basemap tiles. This is best for store locators, delivery tracking, logistics maps, address maps, and any UI where users need streets, place labels, or geographic context.+- Use `<Map blank>` for a transparent, tile-less canvas. Used alone it renders nothing; add your own layers such as `MapGeoJSON`, `MapArc`, markers, clusters, or custom MapLibre layers. This is best for choropleths, arc maps, dot maps, dashboards, and data visualizations where the data should define the geography.+- If the user wants a blank map with only countries or country borders, use `<Map blank>` with `<MapGeoJSON data={WORLD_GEOJSON} />`. For world countries, a Natural Earth GeoJSON source works well: `https://cdn.jsdelivr.net/gh/nvkelso/[email protected]/geojson/ne_110m_admin_0_countries.geojson`. Users can also provide their own GeoJSON URL or GeoJSON object to `MapGeoJSON`.+- Use the `styles` prop for custom MapLibre-compatible style URLs or style objects, for example MapTiler, OpenFreeMap, CARTO, or a self-hosted style. Explicit `styles` override `blank`.+<!-- /generated:basemap -->++## Components++Everything is imported from `@/components/ui/map`:++<!-- generated:components -->+- **Map:** `Map`, `useMap`+- **Controls:** `MapControls`+- **Markers:** `MapMarker`, `MarkerContent`, `MarkerPopup`, `MarkerTooltip`, `MarkerLabel`+- **Popups:** `MapPopup`+- **Routes:** `MapRoute`, `RouteProgress`, `RouteMarker`+- **Arcs:** `MapArc`+- **GeoJSON:** `MapGeoJSON`+- **Clusters:** `MapClusterLayer`+<!-- /generated:components -->++## References++Read only what the task needs. Reading this from a URL instead of an installed skill? The same files are at https://raw.githubusercontent.com/AnmolSaini16/mapcn/main/skills/mapcn/references/.++- `references/components.md`: every export with what it's for, its docs page and links to example source+- `references/blocks.md`: each block, what it shows, the files it adds and its install command+- `references/patterns.md`: controlled viewport, fly-to, route fetching, custom layers, large datasets, Web Worker and CSPdiff --git a/skills/mapcn/references/blocks.md b/skills/mapcn/references/blocks.mdnew file mode 100644index 0000000..0eef112--- /dev/null+++ b/skills/mapcn/references/blocks.md@@ -0,0 +1,121 @@+# Blocks++Full pages built from the map components, installed into the user's app with the shadcn CLI. Most ship with sample data (usually `data.ts`): swap in the user's data.++## Routes outside the Next.js App Router++Block files install to App Router paths (`app/<route>/page.tsx`, with `data.ts` and `components/` beside it). Every block page is a `"use client"` component with `export default function Page`. Check the project's router and move the files to match:++- **Next.js App Router:** keep the paths. Rename the route folder if it clashes with an existing page.+- **Remix or React Router (framework mode):** `app/` is the app's own source folder. Move the page into `app/routes/` (for example `app/routes/store-locator.tsx`), or register it in `app/routes.ts` if the project uses config routes. Keep `data.ts` and `components/` outside `app/routes/`.+- **Next.js Pages Router:** move the page to `pages/<route>.tsx`, or `pages/<route>/index.tsx`, and keep `data.ts` and `components/` outside `pages/` so they don't become routes.+- **Vite, React Router, TanStack Router and others:** move the folder to where the project keeps pages (for example `src/pages/<route>/`), rename `page.tsx` and `Page` to something like `StoreLocatorPage`, and register it in the router config.+- **No router:** render the page component where the user wants it.++After moving, fix the relative imports (`./data`, `./components/...`) and delete only the emptied `app/<route>/` folder the block created. Never delete `app/` itself: in Next.js, Remix and React Router it holds the rest of the app.++## Analytics Map++Real-time analytics overview with a world map, breakdown cards, and device stats.++```bash+npx shadcn@latest add @mapcn/analytics-map+```++- Adds the page at `app/analytics/page.tsx`+- Files: `app/analytics/page.tsx`, `app/analytics/data.ts`, `app/analytics/components/overview-card.tsx`, `app/analytics/components/breakdown-card.tsx`+- Pulls in: `@mapcn/map`, `card`, `chart`+- Preview: https://mapcn.dev/blocks/analytics-map++## Choropleth++World choropleth map shading countries by a metric, with a hover tooltip and legend.++```bash+npx shadcn@latest add @mapcn/choropleth+```++- Adds the page at `app/choropleth/page.tsx`+- Files: `app/choropleth/page.tsx`, `app/choropleth/data.ts`, `@lib/use-world-data.ts`+- Reads the theme with `useTheme` from `next-themes`. Without next-themes, use the project's own theme hook, or remove it and let the map follow the theme itself.+- Pulls in: `@mapcn/map`+- Preview: https://mapcn.dev/blocks/choropleth++## Analytics Card++Compact analytics card with a headline metric over a world map.++```bash+npx shadcn@latest add @mapcn/analytics-card+```++- Adds the page at `app/analytics-card/page.tsx`+- Files: `app/analytics-card/page.tsx`, `app/analytics-card/data.ts`+- Pulls in: `@mapcn/map`, `card`, `badge`+- Preview: https://mapcn.dev/blocks/analytics-card++## Delivery Tracker++Live order tracking with route progress, courier position, and order details.++```bash+npx shadcn@latest add @mapcn/delivery-tracker+```++- Adds the page at `app/delivery/page.tsx`+- Files: `app/delivery/page.tsx`, `app/delivery/data.ts`+- Reads the theme with `useTheme` from `next-themes`. Without next-themes, use the project's own theme hook, or remove it and let the map follow the theme itself.+- Pulls in: `@mapcn/map`, `card`, `badge`, `button`+- Preview: https://mapcn.dev/blocks/delivery-tracker++## Uptime Monitor++Status-page style map of edge network locations with live health, latency, and uptime.++```bash+npx shadcn@latest add @mapcn/uptime-monitor+```++- Adds the page at `app/uptime-monitor/page.tsx`+- Files: `app/uptime-monitor/page.tsx`, `app/uptime-monitor/data.ts`, `app/uptime-monitor/components/edge-node-marker.tsx`, `app/uptime-monitor/components/status-sidebar.tsx`+- Pulls in: `@mapcn/map`+- Preview: https://mapcn.dev/blocks/uptime-monitor++## Heatmap++Globe-projected heatmap visualizing earthquake density with zoom-dependent styling.++```bash+npx shadcn@latest add @mapcn/heatmap+```++- Adds the page at `app/heatmap/page.tsx`+- Files: `app/heatmap/page.tsx`+- Pulls in: `@mapcn/map`+- Preview: https://mapcn.dev/blocks/heatmap++## Logistics Network++Domestic logistics map with a sidebar of stats.++```bash+npx shadcn@latest add @mapcn/logistics-network+```++- Adds the page at `app/logistics/page.tsx`+- Files: `app/logistics/page.tsx`, `app/logistics/data.ts`, `app/logistics/components/filter-sidebar.tsx`, `app/logistics/components/network-map.tsx`+- Pulls in: `@mapcn/map`, `sidebar`, `separator`+- Preview: https://mapcn.dev/blocks/logistics-network++## Store Locator++Searchable store list synced with map markers.++```bash+npx shadcn@latest add @mapcn/store-locator+```++- Adds the page at `app/store-locator/page.tsx`+- Files: `app/store-locator/page.tsx`, `app/store-locator/data.ts`, `app/store-locator/components/store-list.tsx`, `app/store-locator/components/locator-map.tsx`+- Pulls in: `@mapcn/map`, `input`, `sidebar`+- Preview: https://mapcn.dev/blocks/store-locatordiff --git a/skills/mapcn/references/components.md b/skills/mapcn/references/components.mdnew file mode 100644index 0000000..29a0614--- /dev/null+++ b/skills/mapcn/references/components.md@@ -0,0 +1,101 @@+# Components++All exports come from `@/components/ui/map`, installed by `npx shadcn@latest add @mapcn/map`. Every prop is typed and commented in that file, so read it for exact props. Prop types are exported too (`MapProps`, `MapMarkerProps`, โฆ), along with `MapRef` for `<Map ref>` and `MapViewport`.++Examples link to the source of the demos in the docs. Fetch one only when you need a full working version. If a link fails, the docs page above shows the same example. They import from `@/registry/map`, which is `@/components/ui/map` in an installed project.++## Map++Docs: https://mapcn.dev/docs/basic-map++- `Map`: The map itself. Fills its parent, takes `center` ([lng, lat]), `zoom`, `theme`, `styles`, `blank`, `projection`, controlled `viewport`, `loading`, plus any MapLibre map option.+- `useMap`: Hook for children of `<Map>`: returns `{ map, isLoaded }` for raw MapLibre access.++Examples:+- https://raw.githubusercontent.com/AnmolSaini16/mapcn/752906803fbba96490914adc760ab0efdab69457/src/app/(main)/docs/_components/examples/basic-map-example.tsx+- https://raw.githubusercontent.com/AnmolSaini16/mapcn/752906803fbba96490914adc760ab0efdab69457/src/app/(main)/docs/_components/examples/controlled-map-example.tsx+- https://raw.githubusercontent.com/AnmolSaini16/mapcn/752906803fbba96490914adc760ab0efdab69457/src/app/(main)/docs/_components/examples/custom-style-example.tsx+- https://raw.githubusercontent.com/AnmolSaini16/mapcn/752906803fbba96490914adc760ab0efdab69457/src/app/(main)/docs/_components/examples/blank-map-example.tsx++## Controls++Docs: https://mapcn.dev/docs/controls++- `MapControls`: Zoom, compass, locate and fullscreen buttons. Pick with `showZoom`, `showCompass`, `showLocate`, `showFullscreen` and place with `position`.++Examples:+- https://raw.githubusercontent.com/AnmolSaini16/mapcn/752906803fbba96490914adc760ab0efdab69457/src/app/(main)/docs/_components/examples/map-controls-example.tsx++## Markers++Docs: https://mapcn.dev/docs/markers++- `MapMarker`: A DOM marker at `longitude`/`latitude`. Supports `draggable` and click, hover and drag handlers.+- `MarkerContent`: Custom marker visuals. Any React content; defaults to a dot.+- `MarkerPopup`: Popup that opens when its marker is clicked.+- `MarkerTooltip`: Tooltip shown while hovering its marker.+- `MarkerLabel`: Text label above or below its marker (`position`).++Examples:+- https://raw.githubusercontent.com/AnmolSaini16/mapcn/752906803fbba96490914adc760ab0efdab69457/src/app/(main)/docs/_components/examples/markers-example.tsx+- https://raw.githubusercontent.com/AnmolSaini16/mapcn/752906803fbba96490914adc760ab0efdab69457/src/app/(main)/docs/_components/examples/popup-example.tsx++## Popups++Docs: https://mapcn.dev/docs/popups++- `MapPopup`: Standalone popup at any coordinate, controlled by your state. Use it for clicks on layers, clusters or arcs.++Examples:+- https://raw.githubusercontent.com/AnmolSaini16/mapcn/752906803fbba96490914adc760ab0efdab69457/src/app/(main)/docs/_components/examples/standalone-popup-example.tsx++## Routes++Docs: https://mapcn.dev/docs/routes++- `MapRoute`: Line through `coordinates` ([lng, lat][]), with `progress` (0โ1) for tracking. Render-only: fetch directions in the parent.+- `RouteProgress`: Inside `MapRoute`: styles the travelled part of the route, up to the route's `progress`.+- `RouteMarker`: Inside `MapRoute`: a marker pinned along the route with `at` (`"start"`, `"end"`, `"progress"` or a 0โ1 fraction), such as a courier.++Examples:+- https://raw.githubusercontent.com/AnmolSaini16/mapcn/752906803fbba96490914adc760ab0efdab69457/src/app/(main)/docs/_components/examples/route-example.tsx+- https://raw.githubusercontent.com/AnmolSaini16/mapcn/752906803fbba96490914adc760ab0efdab69457/src/app/(main)/docs/_components/examples/route-progress-example.tsx+- https://raw.githubusercontent.com/AnmolSaini16/mapcn/752906803fbba96490914adc760ab0efdab69457/src/app/(main)/docs/_components/examples/osrm-route-example.tsx++## Arcs++Docs: https://mapcn.dev/docs/arcs++- `MapArc`: Curved lines between origin/destination pairs (flights, trade lanes), with hover and click events.++Examples:+- https://raw.githubusercontent.com/AnmolSaini16/mapcn/752906803fbba96490914adc760ab0efdab69457/src/app/(main)/docs/_components/examples/arc-example.tsx+- https://raw.githubusercontent.com/AnmolSaini16/mapcn/752906803fbba96490914adc760ab0efdab69457/src/app/(main)/docs/_components/examples/interactive-arc-example.tsx++## GeoJSON++Docs: https://mapcn.dev/docs/geojson++- `MapGeoJSON`: Fill and outline layers from a GeoJSON object or URL, with `fillPaint`, `linePaint`, `fillHoverPaint` and hover and click events. Pair with `<Map blank>` for choropleths.++Examples:+- https://raw.githubusercontent.com/AnmolSaini16/mapcn/752906803fbba96490914adc760ab0efdab69457/src/app/(main)/docs/_components/examples/geojson-example.tsx+- https://raw.githubusercontent.com/AnmolSaini16/mapcn/752906803fbba96490914adc760ab0efdab69457/src/app/(main)/docs/_components/examples/map-overlay-example.tsx++## Clusters++Docs: https://mapcn.dev/docs/clusters++- `MapClusterLayer`: GPU-clustered points from GeoJSON (object or URL) for large datasets, with point and cluster click handlers.++Examples:+- https://raw.githubusercontent.com/AnmolSaini16/mapcn/752906803fbba96490914adc760ab0efdab69457/src/app/(main)/docs/_components/examples/cluster-example.tsx++## Advanced++Docs: https://mapcn.dev/docs/advanced-usage++Examples:+- https://raw.githubusercontent.com/AnmolSaini16/mapcn/752906803fbba96490914adc760ab0efdab69457/src/app/(main)/docs/_components/examples/advanced-usage-example.tsx+- https://raw.githubusercontent.com/AnmolSaini16/mapcn/752906803fbba96490914adc760ab0efdab69457/src/app/(main)/docs/_components/examples/custom-layer-example.tsx+- https://raw.githubusercontent.com/AnmolSaini16/mapcn/752906803fbba96490914adc760ab0efdab69457/src/app/(main)/docs/_components/examples/layer-markers-example.tsxdiff --git a/skills/mapcn/references/patterns.md b/skills/mapcn/references/patterns.mdnew file mode 100644index 0000000..213f761--- /dev/null+++ b/skills/mapcn/references/patterns.md@@ -0,0 +1,113 @@+# Patterns++Recipes the components don't spell out. All imports come from `@/components/ui/map`.++## Controlled viewport++Pass `viewport` and `onViewportChange` together and the map follows your state. Use `onViewportChange` alone just to observe.++```tsx+const [viewport, setViewport] = useState<MapViewport>({+ center: [-74.006, 40.7128],+ zoom: 8,+ bearing: 0,+ pitch: 0,+});++<Map viewport={viewport} onViewportChange={setViewport} />+```++## Fly to a place++To move the camera from outside the map, for example from a list item, pass a ref:++```tsx+const mapRef = useRef<MapRef>(null);++<Map ref={mapRef} center={[-74.006, 40.7128]} zoom={11} />++mapRef.current?.flyTo({ center: [store.lng, store.lat], zoom: 14 });+```++Inside `<Map>`, use `useMap()`:++```tsx+function FlyButton({ to }: { to: [number, number] }) {+ const { map } = useMap();+ return <Button onClick={() => map?.flyTo({ center: to, zoom: 14 })}>Go</Button>;+}+```++To show a set of points, fit their bounds: `map.fitBounds([[minLng, minLat], [maxLng, maxLat]], { padding: 48 })`.++## Routes from a directions API++`MapRoute` only draws. Fetch in the parent and pass coordinates down. OSRM's demo server is free and needs no key, which makes it fine for prototypes. Use a real provider in production.++```tsx+const res = await fetch(+ `https://router.project-osrm.org/route/v1/driving/${a.lng},${a.lat};${b.lng},${b.lat}?overview=full&geometries=geojson`,+);+const { routes } = await res.json();+const coordinates: [number, number][] = routes[0].geometry.coordinates;++<Map loading={!coordinates}>+ <MapRoute coordinates={coordinates} />+</Map>+```++For live tracking (a courier moving along the route), use `RouteProgress` and `RouteMarker` inside `MapRoute`. Drive the progress from your own state. See the route progress example in `components.md` and the `delivery-tracker` block.++## Custom MapLibre layers++For anything the components don't cover, such as heatmaps, 3D buildings or raster overlays, add sources and layers yourself:++```tsx+function Heat({ data }: { data: GeoJSON.FeatureCollection }) {+ const { map, isLoaded } = useMap();++ useEffect(() => {+ if (!map || !isLoaded) return;+ map.addSource("heat", { type: "geojson", data });+ map.addLayer({ id: "heat", type: "heatmap", source: "heat" });+ return () => {+ if (map.getLayer("heat")) map.removeLayer("heat");+ if (map.getSource("heat")) map.removeSource("heat");+ };+ }, [map, isLoaded, data]);++ return null;+}+```++When the theme changes, the basemap style reloads and `isLoaded` drops to `false` until the new style is ready. Keying the effect on `isLoaded`, as above, re-adds the layers on their own. Keep the `getLayer`/`getSource` guards in cleanup. See the custom layer example under Advanced in `components.md`.++## Large datasets++- From a few hundred points up: use `MapClusterLayer` instead of many `MapMarker`s. Each marker is a DOM node, but clusters render on the GPU.+- For thousands of styled points or shapes, use a `MapGeoJSON` layer or a custom `circle` layer. Keep DOM markers for the handful that need rich content.+- Memoize the data you pass in (`useMemo`), so React doesn't rebuild the source on every render.++## Choropleth or data-only maps++Use `<Map blank>` with `MapGeoJSON`. Join your metric onto feature properties and color with a MapLibre expression in the fill paint, for example `["interpolate", ["linear"], ["get", "value"], 0, "#e5e7eb", 100, "#1d4ed8"]`. The `choropleth` block is a complete version with a legend and hover tooltip.++## Globe++`<Map projection={{ type: "globe" }} />`. It pairs well with arcs and heatmaps at low zoom.++## Next.js++- Pages can stay server components. Put the map in its own client component, then import and render it.+- If the map must never server-render, for example because it reads `window` at import time, load it with `dynamic(() => import("./my-map"), { ssr: false })` from a client component.++## Web Worker and CSP++MapLibre loads its tile worker from unpkg, pinned to the installed version, so no setup is needed. Under a strict Content Security Policy, allow:++```+script-src 'self' https://unpkg.com;+worker-src 'self' blob:;+```++Add your basemap host too. To self-host the worker, copy `maplibre-gl-worker.mjs` and `maplibre-gl-shared.mjs` from `node_modules/maplibre-gl/dist/` into `public/`, side by side. Then change the worker URL near the top of `map.tsx` to `MapLibreGL.setWorkerUrl("/maplibre-gl-worker.mjs")`.diff --git a/src/app/(main)/(home)/_components/hero-install-command.tsx b/src/app/(main)/(home)/_components/hero-install-command.tsxnew file mode 100644index 0000000..105afd7--- /dev/null+++ b/src/app/(main)/(home)/_components/hero-install-command.tsx@@ -0,0 +1,40 @@+"use client";++import { Check, Copy } from "lucide-react";+import { getCopyLabel, useCopy } from "@/hooks/use-copy";+import { trackEvent } from "@/lib/events";+import { mapInstallCommand } from "@/lib/llm-prompts";+import { cn } from "@/lib/utils";++export function HeroInstallCommand({ className }: { className?: string }) {+ const { status, copy } = useCopy();++ async function copyCommand() {+ if (await copy(mapInstallCommand)) {+ trackEvent({+ name: "copy_install_command",+ properties: { name: "@mapcn/map", source: "hero" },+ });+ }+ }++ return (+ <button+ type="button"+ onClick={copyCommand}+ title="Copy install command"+ className={cn(+ "group bg-surface ring-foreground/10 focus-visible:ring-ring/50 hover:bg-muted dark:hover:bg-muted/70 inline-flex h-10 min-w-0 items-center gap-2 rounded-md px-4 font-mono text-[13px] ring-1 transition-colors outline-none focus-visible:ring-[3px]",+ className,+ )}+ >+ <span className="truncate">{mapInstallCommand}</span>+ <span className="text-muted-foreground group-hover:text-foreground ml-1 transition-colors [&_svg]:size-3.5">+ {status === "copied" ? <Check /> : <Copy />}+ </span>+ <span aria-live="polite" className="sr-only">+ {getCopyLabel(status, "")}+ </span>+ </button>+ );+}diff --git a/src/app/(main)/(home)/page.tsx b/src/app/(main)/(home)/page.tsxindex 532ef21..0dc3c50 100644--- a/src/app/(main)/(home)/page.tsx+++ b/src/app/(main)/(home)/page.tsx@@ -1,6 +1,8 @@import Link from "next/link";import { CSSProperties } from "react";+import { ArrowRight } from "lucide-react";+import { HeroInstallCommand } from "./_components/hero-install-command";import { MapWall } from "./_components/map-wall";import { Footer } from "@/components/footer";import {@@ -15,24 +17,26 @@ export default function Page() {return (<><div className="flex-1">- <PageHeader animated>+ <PageHeader animated className="pt-7 md:pt-12 lg:pt-18 lg:pb-16">+ <Link+ href="/docs/skill"+ style={{ "--stagger": 1 } as CSSProperties}+ className="animate-fade-up animate-stagger text-muted-foreground hover:text-foreground -mb-1 inline-flex items-center gap-1.5 text-[13px] font-medium transition-colors"+ >+ Agent skill for mapcn+ <ArrowRight className="size-3" />+ </Link><PageHeaderHeading>Beautiful maps, made simple</PageHeaderHeading><PageHeaderDescription>Ready to use, customizable map components for React.{" "}<br className="hidden sm:block" />Built on MapLibre. Styled with Tailwind.</PageHeaderDescription>- <PageActions className="mt-5">- <Button asChild className="min-w-36 justify-center">+ <PageActions>+ <HeroInstallCommand className="max-w-full" />+ <Button asChild size="lg" className="min-w-36 justify-center"><Link href="/docs">Get Started</Link></Button>- <Button- variant="outline"- asChild- className="min-w-36 justify-center"- >- <Link href="/docs/basic-map">View Components</Link>- </Button></PageActions></PageHeader>@@ -40,11 +44,11 @@ export default function Page() {className="animate-fade-up animate-stagger relative"style={{- "--stagger": 5,+ "--stagger": 4.5,} as CSSProperties}>- <div className="relative h-[34rem] overflow-hidden mask-b-from-65% max-md:mask-r-from-85% max-md:mask-l-from-85% md:h-[44rem] lg:h-[clamp(52rem,calc(100svh-28.3125rem),90rem)]">+ <div className="relative h-[34rem] overflow-hidden mask-b-from-65% max-md:mask-r-from-85% max-md:mask-l-from-85% md:h-[44rem] lg:h-[clamp(52rem,calc(100svh-28.5rem),90rem)]"><div className="absolute inset-0 [background-image:radial-gradient(var(--color-border)_1px,transparent_0)] mask-t-from-0% [background-size:24px_24px]" /><MapWall className="pt-6" /></div>diff --git a/src/app/(main)/blocks/_components/block-install-button.tsx b/src/app/(main)/blocks/_components/block-install-button.tsxindex 334a3a6..afe86da 100644--- a/src/app/(main)/blocks/_components/block-install-button.tsx+++ b/src/app/(main)/blocks/_components/block-install-button.tsx@@ -2,7 +2,7 @@import { Check, Terminal } from "lucide-react";import { Button } from "@/components/ui/button";-import { useCopy } from "@/hooks/use-copy";+import { getCopyLabel, useCopy } from "@/hooks/use-copy";import { trackEvent } from "@/lib/events";export function BlockInstallButton({ name }: { name: string }) {@@ -24,14 +24,8 @@ export function BlockInstallButton({ name }: { name: string }) {{status === "copied" ? <Check /> : <Terminal />}<span className="truncate">npx shadcn add @mapcn/{name}</span><span aria-live="polite" className="sr-only">- {STATUS_MESSAGES[status]}+ {getCopyLabel(status, "")}</span></Button>);}--const STATUS_MESSAGES = {- idle: "",- copied: "Copied",- failed: "Couldn't copy",-};diff --git a/src/app/(main)/docs/_components/agent-prompt.tsx b/src/app/(main)/docs/_components/agent-prompt.tsxindex fdac1a3..e5cee4e 100644--- a/src/app/(main)/docs/_components/agent-prompt.tsx+++ b/src/app/(main)/docs/_components/agent-prompt.tsx@@ -4,7 +4,7 @@ import { Check, Copy } from "lucide-react";import { mapInstallAgentPrompt } from "@/lib/llm-prompts";import { Button } from "@/components/ui/button";-import { useCopy } from "@/hooks/use-copy";+import { getCopyLabel, useCopy } from "@/hooks/use-copy";import { trackEvent } from "@/lib/events";export function AgentPrompt() {@@ -23,7 +23,7 @@ export function AgentPrompt() {aria-live="polite"variant="outline"size="sm"- title="Paste into your AI coding agent to install mapcn"+ title="Paste into your coding agent to install the mapcn skill and mapcn"className="text-muted-foreground hover:text-foreground h-7 shrink-0 gap-1.5 bg-transparent px-2.5 text-[13px] font-normal shadow-none dark:bg-transparent">{status === "copied" ? (@@ -31,13 +31,7 @@ export function AgentPrompt() {) : (<Copy className="size-3.5" />)}- {LABELS[status]}+ {getCopyLabel(status, "Copy prompt")}</Button>);}--const LABELS = {- idle: "Copy prompt",- copied: "Copied",- failed: "Couldn't copy",-};diff --git a/src/app/(main)/docs/_components/install-command.tsx b/src/app/(main)/docs/_components/install-command.tsxindex 9fac4f3..c51490c 100644--- a/src/app/(main)/docs/_components/install-command.tsx+++ b/src/app/(main)/docs/_components/install-command.tsx@@ -4,12 +4,14 @@ import { useState } from "react";import { Check, Copy } from "lucide-react";import { Button } from "@/components/ui/button";import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";-import { useCopy } from "@/hooks/use-copy";+import { getCopyLabel, useCopy } from "@/hooks/use-copy";import { trackEvent } from "@/lib/events";interface InstallCommandProps {- /** The shadcn registry item to add, e.g. "@mapcn/map" */+ /** What to add, e.g. "@mapcn/map" */name: string;+ /** The CLI and subcommand to run it with */+ cli?: string;}const PACKAGE_MANAGERS = [@@ -19,10 +21,13 @@ const PACKAGE_MANAGERS = [{ manager: "bun", exec: "bunx --bun" },] as const;-export function InstallCommand({ name }: InstallCommandProps) {+export function InstallCommand({+ name,+ cli = "shadcn@latest add",+}: InstallCommandProps) {const tabs = PACKAGE_MANAGERS.map(({ manager, exec }) => ({manager,- command: `${exec} shadcn@latest add ${name}`,+ command: `${exec} ${cli} ${name}`,}));const [active, setActive] = useState<string>(tabs[0].manager);@@ -33,7 +38,7 @@ export function InstallCommand({ name }: InstallCommandProps) {if (!current || !(await copy(current.command))) return;trackEvent({name: "copy_install_command",- properties: { name, packageManager: active },+ properties: { name, cli, packageManager: active },});};@@ -59,7 +64,7 @@ export function InstallCommand({ name }: InstallCommandProps) {variant="ghost"size="icon-sm"onClick={copyCommand}- aria-label={COPY_LABELS[status]}+ aria-label={getCopyLabel(status, "Copy command")}className="text-muted-foreground">{status === "copied" ? <Check /> : <Copy />}@@ -78,9 +83,3 @@ export function InstallCommand({ name }: InstallCommandProps) {</div>);}--const COPY_LABELS = {- idle: "Copy command",- copied: "Copied",- failed: "Couldn't copy",-};diff --git a/src/app/(main)/docs/api-reference/page.tsx b/src/app/(main)/docs/api-reference/page.tsxindex 0b2cd33..66d6437 100644--- a/src/app/(main)/docs/api-reference/page.tsx+++ b/src/app/(main)/docs/api-reference/page.tsx@@ -44,7 +44,7 @@ export default function ApiReferencePage() {<DocsLayouttitle="API Reference"description="Complete reference for all map components and their props."- prev={{ title: "Installation", href: "/docs/installation" }}+ prev={{ title: "Skill", href: "/docs/skill" }}next={{ title: "Map", href: "/docs/basic-map" }}><DocsNote>diff --git a/src/app/(main)/docs/installation/page.tsx b/src/app/(main)/docs/installation/page.tsxindex 50e2b1a..979a53c 100644--- a/src/app/(main)/docs/installation/page.tsx+++ b/src/app/(main)/docs/installation/page.tsx@@ -44,7 +44,7 @@ export default function InstallationPage() {title="Installation"description="How to install and set up mapcn in your project."prev={{ title: "Introduction", href: "/docs" }}- next={{ title: "API Reference", href: "/docs/api-reference" }}+ next={{ title: "Skill", href: "/docs/skill" }}action={<AgentPrompt />}><DocsSection title="Prerequisites">diff --git a/src/app/(main)/docs/skill/page.tsx b/src/app/(main)/docs/skill/page.tsxnew file mode 100644index 0000000..e5bac8e--- /dev/null+++ b/src/app/(main)/docs/skill/page.tsx@@ -0,0 +1,128 @@+import { Metadata } from "next";++import {+ DocsCode,+ DocsLayout,+ DocsLink,+ DocsSection,+} from "../_components/docs";+import { CodeBlock } from "../_components/code-block";+import { InstallCommand } from "../_components/install-command";+import { CodeCopyButton } from "@/components/code-copy-button";+import { githubRepoUrl } from "@/lib/site-navigation";++export const metadata: Metadata = {+ title: "Skill",+ description:+ "Teach your coding agent mapcn: install components and blocks, and follow the rules that make maps work.",+};++export default function SkillPage() {+ return (+ <DocsLayout+ title="Skill"+ description="Teach your coding agent mapcn, so it installs the right pieces and writes maps that work the first time."+ prev={{ title: "Installation", href: "/docs/installation" }}+ next={{ title: "API Reference", href: "/docs/api-reference" }}+ >+ <DocsSection title="Installation">+ <InstallCommand cli="skills add" name="AnmolSaini16/mapcn" />+ <p>+ Works with Claude Code, Cursor, Codex and other agents that support+ skills. To add it by hand, copy the{" "}+ <DocsLink href={`${githubRepoUrl}/tree/main/skills/mapcn`} external>+ skills/mapcn+ </DocsLink>{" "}+ folder into <DocsCode>.claude/skills/</DocsCode> or your agent's+ skills folder.+ </p>+ <p>+ The skill loads on its own when you ask for a map. Not sure where a+ map fits? Ask it to look through your project and suggest some.+ </p>+ <p>+ Agent doesn't support skills? Point it at{" "}+ <DocsLink href="/llms.txt" external>+ llms.txt+ </DocsLink>{" "}+ instead.+ </p>+ </DocsSection>++ <DocsSection title="What it knows">+ <ul>+ <li>+ <strong>Setup.</strong> Installs the map and blocks with the shadcn+ CLI, and skips what's already there.+ </li>+ <li>+ <strong>The gotchas.</strong> Gives every map a height, keeps+ coordinates in <DocsCode>[lng, lat]</DocsCode> order, and fetches+ route data outside the map.+ </li>+ <li>+ <strong>Basemaps.</strong> Street tiles when people need to find+ places, a blank canvas when the data is the map, or your own style.+ </li>+ <li>+ <strong>Recipes.</strong> Fly-to, live route tracking, custom+ layers, large datasets and strict CSP.+ </li>+ <li>+ <strong>Every component and block,</strong> with links to the+ working examples in these docs.+ </li>+ </ul>+ </DocsSection>++ <DocsSection title="Try asking">+ <div className="bg-surface overflow-hidden rounded-lg">+ <ul className="divide-y">+ {examplePrompts.map((prompt) => (+ <li+ key={prompt}+ className="group flex items-center justify-between gap-4 py-2.5 pr-2.5 pl-4"+ >+ <span>{prompt}</span>+ <CodeCopyButton+ text={prompt}+ label="Copy prompt"+ className="shrink-0 bg-transparent opacity-0 group-hover:opacity-100 focus-visible:opacity-100 pointer-coarse:opacity-100"+ />+ </li>+ ))}+ </ul>+ </div>+ </DocsSection>++ <DocsSection title="What's inside">+ <p>+ The skill is generated from the same registry and examples as this+ site, so it stays in step with the components. Your agent reads only+ the files a task needs.+ </p>+ <CodeBlock+ code={skillTree}+ language="bash"+ showLineNumbers={false}+ showCopyButton={false}+ />+ </DocsSection>+ </DocsLayout>+ );+}++const examplePrompts = [+ "Where could a map help in this app?",+ "Add a store locator for our locations.",+ "Show the delivery route on the order page with live progress.",+ "Make a choropleth of revenue by country.",+ "Draw arcs between our offices on a globe.",+];++const skillTree = `skills/mapcn/+โโโ SKILL.md # workflow, install, rules, basemaps+โโโ references/+ โโโ components.md # every export, docs and example links+ โโโ blocks.md # blocks, files they add, install commands+ โโโ patterns.md # recipes beyond the basics`;diff --git a/src/components/code-copy-button.tsx b/src/components/code-copy-button.tsxindex af2aeef..aa604be 100644--- a/src/components/code-copy-button.tsx+++ b/src/components/code-copy-button.tsx@@ -3,16 +3,19 @@import { Check, Copy } from "lucide-react";import { cn } from "@/lib/utils";import { Button } from "@/components/ui/button";-import { useCopy } from "@/hooks/use-copy";+import { getCopyLabel, useCopy } from "@/hooks/use-copy";interface CodeCopyButtonProps {text: string;+ /** Accessible label while idle */+ label?: string;onCopy?: () => void;className?: string;}export function CodeCopyButton({text,+ label = "Copy code",onCopy,className,}: CodeCopyButtonProps) {@@ -27,16 +30,10 @@ export function CodeCopyButton({variant="ghost"size="icon-sm"onClick={copyText}- aria-label={COPY_LABELS[status]}+ aria-label={getCopyLabel(status, label)}className={cn("text-muted-foreground bg-code", className)}>{status === "copied" ? <Check /> : <Copy />}</Button>);}--const COPY_LABELS = {- idle: "Copy code",- copied: "Copied",- failed: "Couldn't copy",-};diff --git a/src/components/command-search.tsx b/src/components/command-search.tsxindex 09afe58..2640bd7 100644--- a/src/components/command-search.tsx+++ b/src/components/command-search.tsx@@ -182,7 +182,7 @@ export function CommandSearch({ className }: { className?: string }) {</CommandItem><CommandItemvalue="Copy prompt for your agent"- keywords={["ai", "llm", "claude", "cursor"]}+ keywords={["ai", "llm", "claude", "cursor", "skill"]}onSelect={() =>copy("prompt", mapInstallAgentPrompt, "copy_agent_prompt")}diff --git a/src/components/page-header.tsx b/src/components/page-header.tsxindex b14face..134996c 100644--- a/src/components/page-header.tsx+++ b/src/components/page-header.tsx@@ -141,7 +141,7 @@ function PageActions({ children, className }: PageActionsProps) {return (<divclassName={cn(- "mt-3 flex flex-wrap items-center gap-3",+ "mt-6 flex flex-wrap items-center gap-4 max-sm:w-full max-sm:flex-col",animated && "animate-fade-up animate-stagger",align === "center" ? "justify-center" : "justify-start",className,diff --git a/src/hooks/use-copy.ts b/src/hooks/use-copy.tsindex 211ffb5..ccf53a7 100644--- a/src/hooks/use-copy.ts+++ b/src/hooks/use-copy.ts@@ -4,6 +4,12 @@ import { useCallback, useEffect, useRef, useState } from "react";type CopyStatus = "idle" | "copied" | "failed";+const STATUS_LABELS = { copied: "Copied", failed: "Couldn't copy" };++export function getCopyLabel(status: CopyStatus, idle: string) {+ return status === "idle" ? idle : STATUS_LABELS[status];+}+export function useCopy(resetAfter = 2000) {const [status, setStatus] = useState<CopyStatus>("idle");const timer = useRef<number | undefined>(undefined);diff --git a/src/lib/llm-content.ts b/src/lib/llm-content.tsindex 5bfa63f..ff15b77 100644--- a/src/lib/llm-content.ts+++ b/src/lib/llm-content.ts@@ -1,5 +1,9 @@import registry from "../../registry.json";-import { mapInstallCommand } from "@/lib/llm-prompts";+import {+ mapInstallCommand,+ skillInstallCommand,+ skillRawUrl,+} from "@/lib/llm-prompts";interface ComponentDoc {title: string;@@ -56,7 +60,7 @@ function formatFiles(files: RegistryFile[] | undefined) {.join("\n");}-function createBasemapMarkdown() {+export function createBasemapMarkdown() {return `## Basemap Selection- Use ${code("<Map>")} without ${code("blank")} for the default free CARTO basemap tiles. This is best for store locators, delivery tracking, logistics maps, address maps, and any UI where users need streets, place labels, or geographic context.@@ -103,6 +107,8 @@ mapcn is a free, open-source shadcn-style registry of ready-to-use React map comWebsite: ${typedRegistry.homepage ?? "https://mapcn.dev"}Registry index: https://mapcn.dev/r/registry.json+For fuller agent instructions (rules, patterns, every component and block), install the mapcn skill with ${code(`${skillInstallCommand} -y`)}, or read ${skillRawUrl}/SKILL.md (the files it references are in the same folder).+## Install the base map componentRun:diff --git a/src/lib/llm-prompts.ts b/src/lib/llm-prompts.tsindex e65f103..0d29b5c 100644--- a/src/lib/llm-prompts.ts+++ b/src/lib/llm-prompts.ts@@ -1,3 +1,12 @@export const mapInstallCommand = "npx shadcn@latest add @mapcn/map";-export const mapInstallAgentPrompt = `Read the mapcn agent instructions at https://mapcn.dev/llms.txt, then install mapcn in this project. Run ${mapInstallCommand}. Then add a basic example that imports Map and MapControls from "@/components/ui/map" and renders a map inside a sized container. Use the default tiled basemap for maps that need streets, labels, or geographic context. If the user wants a blank/data-only map, such as countries or country borders, use <Map blank> with MapGeoJSON and either a user-provided GeoJSON URL/object or a world countries GeoJSON source. Preserve the existing Tailwind CSS and shadcn/ui setup. Do not manually rewrite the registry component unless the command fails; if it fails, inspect https://mapcn.dev/r/map.json and install the listed dependencies.`;+export const skillInstallCommand = "npx skills add AnmolSaini16/mapcn";++// Raw skill folder, for agents that can't install skills.+export const skillRawUrl =+ "https://raw.githubusercontent.com/AnmolSaini16/mapcn/main/skills/mapcn";++// -y skips the CLI's prompts, which an agent's shell can't answer.+const skillInstallAgentCommand = `${skillInstallCommand} -y`;++export const mapInstallAgentPrompt = `Install the mapcn agent skill with ${skillInstallAgentCommand} and read its SKILL.md. If you can't install skills, read ${skillRawUrl}/SKILL.md instead, and fetch the files it references from that same folder. Then install mapcn in this project with ${mapInstallCommand} and add a basic map example, following the skill's rules. When you're done, offer to look through the project and suggest where other maps or blocks would fit, but don't build them unless I ask.`;diff --git a/src/lib/site-navigation.ts b/src/lib/site-navigation.tsindex 47936ce..c06eb0f 100644--- a/src/lib/site-navigation.ts+++ b/src/lib/site-navigation.ts@@ -25,7 +25,7 @@ export const docsNavigation: SiteNavigationGroup[] = [items: [{ title: "Getting Started", href: "/docs", icon: BookOpen },{ title: "Installation", href: "/docs/installation", icon: BookOpen },- { title: "llms.txt", href: "/llms.txt", icon: BookOpen, new: true },+ { title: "Skill", href: "/docs/skill", icon: BookOpen, new: true },{ title: "API Reference", href: "/docs/api-reference", icon: BookOpen },],},