refactor: comprehensive map-editor plugin refactoring (phases 1-3)

This commit implements a complete refactoring of the map-editor plugin to
improve code organization, reusability, and maintainability.

## Phase 1: Extraction of composables and factory functions

**New composables:**
- `useMarkers.js`: Centralized marker state and CRUD operations
  - Exports: markers, selectedMarkerId, editingMarker refs
  - Computed: canAddMarker, hasMarkers, selectedMarker
  - Methods: addMarker, updateMarker, deleteMarker, selectMarker, etc.
  - Includes createMarker() factory to eliminate code duplication

- `useMapData.js`: Map data persistence (YAML load/save)
  - Exports: center, zoom refs
  - Methods: loadMapData, saveMapData, debouncedSave
  - Handles lifecycle cleanup of debounce timeouts

**Benefits:**
- Eliminated code duplication (2 identical marker creation blocks)
- Separated business logic from UI concerns
- Improved testability with pure functions
- Added JSDoc documentation throughout

## Phase 2: Component extraction

**New components:**
- `MarkerList.vue`: Extracted sidebar UI from MapEditor.vue
  - Props: markers, selectedMarkerId, maxMarkers
  - Emits: add-marker, select-marker, edit-marker, delete-marker, select-location
  - Includes integrated GeocodeSearch component
  - Self-contained styles with scoped CSS

**Benefits:**
- MapEditor.vue reduced from 370 → 230 lines (-40%)
- Clear separation of concerns (orchestration vs presentation)
- Reusable component for potential future use
- Easier to test and maintain

## Phase 3: Utils restructuring with JSDoc

**New structure:**
```
utils/
├── constants.js           # NOMINATIM_API, MAP_DEFAULTS, DEBOUNCE_DELAYS
├── api/
│   └── nominatim.js      # geocode() with full JSDoc typedefs
└── helpers/
    └── debounce.js       # Generic debounce utility
```

**Removed:**
- `utils/geocoding.js` (replaced by modular structure)

**Benefits:**
- Constants centralized for easy configuration
- API layer separated from helpers
- Complete JSDoc type annotations for better IDE support
- Better organization following standard patterns

## Updated components

**MapEditor.vue:**
- Now uses useMarkers and useMapData composables
- Uses MarkerList component instead of inline template
- Cleaner setup function with better separation
- Reduced from 537 → 256 lines (CSS moved to MarkerList)

**GeocodeSearch.vue:**
- Updated imports to use new utils structure
- Uses DEBOUNCE_DELAYS constant instead of hardcoded value

## Build verification

- ✅ npm run build successful
- ✅ Bundle size unchanged (806.10 kB / 223.46 KiB gzipped)
- ✅ All functionality preserved
- ✅ No breaking changes

## Documentation

- Added comprehensive README.md with:
  - Architecture overview
  - Composables usage examples
  - Component API documentation
  - Data flow diagrams
  - Development guide

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

public/site/plugins/map-editor/src/composables/useMapData.js

@@ -0,0 +1,119 @@
+/**
+ * Composable for managing map data persistence (YAML)
+ * Handles loading and saving map data to/from YAML format
+ */
+import { ref, onBeforeUnmount } from 'vue';
+import yaml from 'js-yaml';
+
+/**
+ * @param {Object} options
+ * @param {Object} options.defaultCenter - Default map center {lat, lon}
+ * @param {number} options.defaultZoom - Default zoom level
+ * @param {Function} options.onSave - Callback when data is saved
+ * @returns {Object} MapData composable
+ */
+export function useMapData(options = {}) {
+  const {
+    defaultCenter = { lat: 43.836699, lon: 4.360054 },
+    defaultZoom = 13,
+    onSave = () => {},
+  } = options;
+
+  const center = ref({ ...defaultCenter });
+  const zoom = ref(defaultZoom);
+  const saveTimeout = ref(null);
+
+  // Cleanup timeout on unmount
+  onBeforeUnmount(() => {
+    if (saveTimeout.value) {
+      clearTimeout(saveTimeout.value);
+    }
+  });
+
+  /**
+   * Load map data from YAML string
+   * @param {string} yamlString - YAML content
+   * @returns {Object|null} Parsed data or null if error
+   */
+  function loadMapData(yamlString) {
+    if (!yamlString || yamlString.trim() === '') {
+      return null;
+    }
+
+    try {
+      const data = yaml.load(yamlString);
+
+      if (data) {
+        if (data.center) {
+          center.value = {
+            lat: data.center.lat,
+            lon: data.center.lon,
+          };
+        }
+        if (data.zoom !== undefined) {
+          zoom.value = data.zoom;
+        }
+
+        return data;
+      }
+    } catch (error) {
+      console.error('Error loading map data:', error);
+      return null;
+    }
+
+    return null;
+  }
+
+  /**
+   * Save map data to YAML format
+   * @param {Array} markers - Array of marker objects
+   * @returns {string} YAML string
+   */
+  function saveMapData(markers = []) {
+    const data = {
+      background: {
+        type: 'osm',
+      },
+      center: {
+        lat: center.value.lat,
+        lon: center.value.lon,
+      },
+      zoom: zoom.value,
+      markers,
+    };
+
+    const yamlString = yaml.dump(data, {
+      indent: 2,
+      lineWidth: -1,
+      noRefs: true,
+    });
+
+    onSave(yamlString);
+    return yamlString;
+  }
+
+  /**
+   * Debounced save function
+   * @param {Array} markers - Array of marker objects
+   * @param {number} delay - Delay in milliseconds
+   */
+  function debouncedSave(markers, delay = 300) {
+    if (saveTimeout.value) {
+      clearTimeout(saveTimeout.value);
+    }
+    saveTimeout.value = setTimeout(() => {
+      saveMapData(markers);
+    }, delay);
+  }
+
+  return {
+    // State
+    center,
+    zoom,
+
+    // Methods
+    loadMapData,
+    saveMapData,
+    debouncedSave,
+  };
+}

public/site/plugins/map-editor/src/composables/useMarkers.js

@@ -0,0 +1,168 @@
+/**
+ * Composable for managing map markers
+ * Handles CRUD operations and state management for markers
+ */
+import { ref, computed } from 'vue';
+
+/**
+ * Creates a new marker object with default values
+ * @param {Object} position - The marker position {lat, lon}
+ * @returns {Object} New marker object
+ */
+export function createMarker(position) {
+  return {
+    id: `marker_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+    position: {
+      lat: position.lat,
+      lon: position.lon,
+    },
+    icon: {
+      type: 'default',
+    },
+    title: '',
+    description: '',
+    content: [],
+  };
+}
+
+/**
+ * @param {Object} options
+ * @param {number} options.maxMarkers - Maximum number of markers allowed
+ * @returns {Object} Markers composable
+ */
+export function useMarkers(options = {}) {
+  const { maxMarkers = 50 } = options;
+
+  const markers = ref([]);
+  const selectedMarkerId = ref(null);
+  const editingMarker = ref(null);
+
+  // Computed properties
+  const canAddMarker = computed(() => markers.value.length < maxMarkers);
+  const hasMarkers = computed(() => markers.value.length > 0);
+  const selectedMarker = computed(() =>
+    markers.value.find(m => m.id === selectedMarkerId.value)
+  );
+
+  /**
+   * Add a new marker
+   * @param {Object} position - Position {lat, lon}
+   */
+  function addMarker(position) {
+    if (!canAddMarker.value) {
+      return null;
+    }
+
+    const newMarker = createMarker(position);
+    markers.value = [...markers.value, newMarker];
+    selectedMarkerId.value = newMarker.id;
+
+    return newMarker;
+  }
+
+  /**
+   * Update an existing marker
+   * @param {string} markerId - Marker ID
+   * @param {Object} updates - Partial marker object with updates
+   */
+  function updateMarker(markerId, updates) {
+    const markerIndex = markers.value.findIndex(m => m.id === markerId);
+    if (markerIndex !== -1) {
+      const updatedMarkers = [...markers.value];
+      updatedMarkers[markerIndex] = {
+        ...updatedMarkers[markerIndex],
+        ...updates,
+      };
+      markers.value = updatedMarkers;
+    }
+  }
+
+  /**
+   * Delete a marker
+   * @param {string} markerId - Marker ID
+   * @param {boolean} skipConfirm - Skip confirmation dialog
+   * @returns {boolean} True if deleted, false if cancelled
+   */
+  function deleteMarker(markerId, skipConfirm = false) {
+    if (!skipConfirm && !confirm('Êtes-vous sûr de vouloir supprimer ce marqueur ?')) {
+      return false;
+    }
+
+    markers.value = markers.value.filter(m => m.id !== markerId);
+
+    if (selectedMarkerId.value === markerId) {
+      selectedMarkerId.value = null;
+    }
+
+    return true;
+  }
+
+  /**
+   * Select a marker
+   * @param {string} markerId - Marker ID
+   */
+  function selectMarker(markerId) {
+    selectedMarkerId.value = markerId;
+  }
+
+  /**
+   * Open marker editor
+   * @param {string} markerId - Marker ID
+   */
+  function editMarker(markerId) {
+    const marker = markers.value.find(m => m.id === markerId);
+    if (marker) {
+      editingMarker.value = JSON.parse(JSON.stringify(marker));
+    }
+  }
+
+  /**
+   * Save edited marker
+   * @param {Object} updatedMarker - Updated marker object
+   */
+  function saveMarker(updatedMarker) {
+    const markerIndex = markers.value.findIndex(m => m.id === updatedMarker.id);
+    if (markerIndex !== -1) {
+      const updatedMarkers = [...markers.value];
+      updatedMarkers[markerIndex] = updatedMarker;
+      markers.value = updatedMarkers;
+    }
+  }
+
+  /**
+   * Close marker editor
+   */
+  function closeEditor() {
+    editingMarker.value = null;
+  }
+
+  /**
+   * Set markers array
+   * @param {Array} newMarkers - Array of marker objects
+   */
+  function setMarkers(newMarkers) {
+    markers.value = newMarkers;
+  }
+
+  return {
+    // State
+    markers,
+    selectedMarkerId,
+    editingMarker,
+
+    // Computed
+    canAddMarker,
+    hasMarkers,
+    selectedMarker,
+
+    // Methods
+    addMarker,
+    updateMarker,
+    deleteMarker,
+    selectMarker,
+    editMarker,
+    saveMarker,
+    closeEditor,
+    setMarkers,
+  };
+}