documentatie

static/js/wiki/cmap/cmap-map-controller.js

@@ -29,6 +29,11 @@ export class CmapMapController {
     this.refreshPageConnections = refreshPageConnections;
   }
 
+  /**
+   * goal   : Refresh the CMap catalogue and its lightweight global reference index.
+   * post   : Workspace CMap lists, selector and usage indicators reflect the repository.
+   * result : The current list of stored CMaps.
+   */
   async loadMaps() {
     const [conceptMaps, placements] = await Promise.all([
       this.repository.list(),
@@ -65,6 +70,11 @@ export class CmapMapController {
     this.renderSelector();
   }
 
+  /**
+   * goal   : Open a stored CMap or its source map when it is a derived submap view.
+   * pre    : slug identifies a stored CMap; a later request supersedes this load safely.
+   * post   : Active map state, editor document and saved snapshot are synchronized.
+   */
   async open(slug) {
     if (!slug) return;
     const loadSequence = ++this.state.cmapLoadSequence;
@@ -103,6 +113,7 @@ export class CmapMapController {
     this.status(this.translate("concept-map-loaded", "CMap loaded"), true);
   }
 
+  /** Restore the source submap context for a stored derived CMap. */
   openDerivedView(conceptMap, derivedView) {
     const editor = this.getEditor();
     const root = editor.itemRecord(derivedView.rootItemId);
@@ -124,6 +135,10 @@ export class CmapMapController {
     editor.openSubmapMap(root);
   }
 
+  /**
+   * goal   : Load one immutable CMap version for review or subsequent explicit save.
+   * post   : The editor shows the historical model while the current map remains dirty.
+   */
   async loadHistoricalVersion(version) {
     const conceptMap = this.getCurrentStorageMap();
     if (!conceptMap) return;
@@ -145,6 +160,11 @@ export class CmapMapController {
     location.hash = this.cmapRoute(conceptMap.slug);
   }
 
+  /**
+   * goal   : Extract the selected inline submap into a complete stored CMap.
+   * post   : Parent and child map are saved consistently; cross-boundary relations remain on the parent.
+   * result : Whether extraction completed or was deliberately cancelled.
+   */
   async promoteSelectedSubmap() {
     const editor = this.getEditor();
     const record = editor ? editor.selected() : null;
@@ -263,6 +283,11 @@ export class CmapMapController {
       { tags: [], summary: "", explanationPageSlug: "" };
   }
 
+  /**
+   * goal   : Persist map metadata through either the source editor or a derived map model.
+   * post   : Namespace, tags, summary and explanation-page reference are stored together.
+   * result : False when there is no editable map or saving fails.
+   */
   async saveMetadata(metadata) {
     const conceptMap = this.state.currentConceptMap;
     const editor = this.getEditor();
@@ -290,6 +315,11 @@ export class CmapMapController {
     return true;
   }
 
+  /**
+   * goal   : Archive the active CMap after explicit title confirmation.
+   * post   : Active map state is cleared and navigation continues to another CMap or overview.
+   * result : False when confirmation is cancelled, mismatched or persistence fails.
+   */
   async archive() {
     this.cancelAutosave();
     const conceptMap = this.state.currentConceptMap;
@@ -324,6 +354,7 @@ export class CmapMapController {
     }
   }
 
+  /** Create an explicit, named immutable snapshot of the active stored CMap. */
   async createSnapshot() {
     if (!this.getCurrentStorageMap()) return false;
     const description = window.prompt(this.translate("snapshot-description", "Snapshot description"), "");