@classic-homes/theme-mcp 0.1.21 → 0.1.22

package/dist/cli.js

@@ -18114,7 +18114,7 @@ var maps_catalog_default = {
         },
         {
           name: "MarkerProps",
-          description: "Props for map markers",
+          description: "Props for map markers. NOTE: DOM-based markers (maplibregl.Marker) are susceptible to CSS framework interference that can cause visual sliding during map pan/rotate operations. For production use cases requiring markers, consider using SymbolLayer instead, which renders on the GPU canvas and is immune to CSS interference.",
           properties: [
             { name: "id", type: "string", required: false, description: "Unique marker ID" },
             { name: "coordinates", type: "[number, number]", required: true, description: "Marker position [lng, lat]" },
@@ -18898,6 +18898,126 @@ var maps_catalog_default = {
         "Consider `maxWidth` prop for content-heavy popups"
       ]
     },
+    markers: {
+      title: "Markers",
+      guidelines: [
+        "DOM-based Marker components use maplibregl.Marker which renders in the DOM",
+        "DOM markers are susceptible to CSS framework interference (e.g., Tailwind) that can cause visual sliding during pan/rotate",
+        "For production use with many markers or when CSS conflicts occur, prefer SymbolLayer which renders on the GPU canvas",
+        "SymbolLayer is immune to CSS interference and generally performs better at scale",
+        "Use Marker component only for simple cases or when you need custom HTML content that can't be achieved with icons",
+        "If using DOM markers, the component applies CSS protection but this may not fully prevent sliding in all CSS environments"
+      ]
+    },
+    dynamicData: {
+      title: "Dynamic Data Loading",
+      description: "Patterns for loading and updating map data dynamically (async fetching, user interactions, etc.)",
+      guidelines: [
+        "For dynamic marker-like points, use Source + CircleLayer/SymbolLayer instead of individual Marker components",
+        "When Source data prop changes, the component automatically calls source.setData() to update layers efficiently",
+        "Convert your data array to GeoJSON FeatureCollection format using useMemo/derived to avoid unnecessary re-renders",
+        "Layers automatically re-render when their source data changes - no need to recreate layers",
+        "Use generateId prop on Source to enable feature state (hover effects, selection)",
+        "For popups with SymbolLayer, use onClick handler to get feature coordinates and properties",
+        "This approach is more performant than DOM markers: single GPU draw call vs O(n) DOM operations",
+        "DOM Markers also support dynamic loading - they appear immediately when added after map initialization"
+      ],
+      recommendedPattern: {
+        name: "Dynamic SymbolLayer with Popup",
+        description: "Recommended pattern for dynamic points with popups - GPU-based, efficient, and immune to CSS conflicts",
+        react: `const [points, setPoints] = useState([]);
+
+const geojson = useMemo(() => ({
+  type: 'FeatureCollection',
+  features: points.map(p => ({
+    type: 'Feature',
+    properties: { name: p.name, id: p.id },
+    geometry: { type: 'Point', coordinates: p.coordinates }
+  }))
+}), [points]);
+
+const [selected, setSelected] = useState(null);
+
+return (
+  <Map title="Dynamic Points">
+    <Source id="points" type="geojson" data={geojson} generateId>
+      <CircleLayer
+        id="circles"
+        source="points"
+        circleRadius={10}
+        circleColor="#3ba4a7"
+        onClick={(e) => setSelected({ ...e.feature.properties, coordinates: e.lngLat })}
+        onHover={() => {}}
+      />
+      <SymbolLayer
+        id="labels"
+        source="points"
+        textField={['get', 'name']}
+        textOffset={[0, 1.5]}
+      />
+    </Source>
+    {selected && (
+      <Popup coordinates={selected.coordinates} onClose={() => setSelected(null)} closeButton>
+        <PopupCard>
+          <PopupHeader title={selected.name} />
+        </PopupCard>
+      </Popup>
+    )}
+  </Map>
+);`,
+        svelte: `<script>
+  let points = $state([]);
+  let selected = $state(null);
+
+  const geojson = $derived({
+    type: 'FeatureCollection',
+    features: points.map(p => ({
+      type: 'Feature',
+      properties: { name: p.name, id: p.id },
+      geometry: { type: 'Point', coordinates: p.coordinates }
+    }))
+  });
+</script>
+
+<Map title="Dynamic Points">
+  <Source id="points" type="geojson" data={geojson} generateId>
+    <CircleLayer
+      id="circles"
+      source="points"
+      circleRadius={10}
+      circleColor="#3ba4a7"
+      onClick={(e) => selected = { ...e.feature.properties, coordinates: e.lngLat }}
+      onHover={() => {}}
+    />
+    <SymbolLayer id="labels" source="points" textField={['get', 'name']} textOffset={[0, 1.5]} />
+  </Source>
+  {#if selected}
+    <Popup coordinates={selected.coordinates} onClose={() => selected = null} closeButton>
+      <PopupCard><PopupHeader title={selected.name} /></PopupCard>
+    </Popup>
+  {/if}
+</Map>`
+      },
+      comparisonTable: {
+        description: "Comparison of dynamic data approaches",
+        approaches: [
+          {
+            name: "Source + SymbolLayer (Recommended)",
+            updateMechanism: "source.setData() on existing source",
+            performance: "Single GPU draw call",
+            cssImmunity: "Yes - rendered on canvas",
+            useCase: "Most marker-like use cases, especially with many points"
+          },
+          {
+            name: "DOM Markers",
+            updateMechanism: "Create/destroy marker instances",
+            performance: "O(n) DOM operations",
+            cssImmunity: "No - CSS protection applied but not guaranteed",
+            useCase: "Custom HTML content that can't be achieved with icons"
+          }
+        ]
+      }
+    },
     mapboxMigration: {
       title: "Migrating from Mapbox GL",
       differences: [