dmx-api 3.1.0 → 4.0.1

package/README.md

@@ -2,6 +2,18 @@
 
 ## Version History
 
+**4.0.1** -- Jan 31, 2026
+
+* Improvement:
+    - No alert box appears when WebSocket connection is dropped. Reopens when browser is "foregrounded".
+* Fix:
+    - Topic positioning for `Topicmap` instances hold as reactive Vue 3 state.
+
+**4.0** -- Oct 16, 2024
+
+* BREAKING CHANGE
+    - requires Vue 3 (instead Vue 2)
+
 **3.1** -- Oct 16, 2024
 
 * Adapted to DMX 5.3.5 (account management)
@@ -326,4 +338,4 @@ library's `init()` function.
 
 ------------
 Jörg Richter  
-Oct 16, 2024
+Jan 31, 2026

package/package.json

@@ -1,18 +1,21 @@
 {
   "name": "dmx-api",
-  "version": "3.1.0",
+  "version": "4.0.1",
   "description": "API and utilities for DMX 5 based frontends",
   "author": "Jörg Richter <jri@dmx.berlin>",
   "license": "AGPL-3.0",
   "main": "src/index.js",
   "repository": {
     "type": "git",
-    "url": "https://github.com/dmx-systems/dmx-api.git"
+    "url": "git+https://github.com/dmx-systems/dmx-api.git"
   },
   "dependencies": {
     "axios": "0.18.1",
     "clone": "2.1.2",
     "debounce": "1.2.0",
     "font-awesome": "4.7.0"
+  },
+  "peerDependencies": {
+    "vue": "3.x"
   }
 }

package/src/index.js

@@ -6,7 +6,7 @@ import icons        from './icons'
 import DMXWebSocket from './websocket'
 import {default as typeCache, init as initTypeCache, storeModule} from './type-cache'
 
-console.log('[DMX-API] 3.1')
+console.log('[DMX-API] 2026/01/28')
 
 let adminWorkspaceId    // promise
 

package/src/model.js

@@ -2,7 +2,6 @@ import rpc from './rpc'
 import typeCache from './type-cache'
 import permCache from './permission-cache'
 import utils from './utils'
-import Vue from 'vue'
 
 // TODO: inject or factor out
 const DEFAULT_TOPIC_ICON = '\uf111'               // fa-circle
@@ -734,6 +733,9 @@ class Topicmap extends Topic {
     this._assocs = utils.mapById(utils.instantiateMany(topicmap.assocs, ViewAssoc))   // map: ID -> dmx.ViewAssoc
   }
 
+  /**
+   * @param   id    Number or String
+   */
   getTopic (id) {
     const topic = this.getTopicIfExists(id)
     if (!topic) {
@@ -742,6 +744,9 @@ class Topicmap extends Topic {
     return topic
   }
 
+  /**
+   * @param   id    Number or String
+   */
   getAssoc (id) {
     const assoc = this.getAssocIfExists(id)
     if (!assoc) {
@@ -761,26 +766,44 @@ class Topicmap extends Topic {
     return o
   }
 
+  /**
+   * @param   id    Number or String
+   */
   getTopicIfExists (id) {
     return this._topics[id]
   }
 
+  /**
+   * @param   id    Number or String
+   */
   getAssocIfExists (id) {
     return this._assocs[id]
   }
 
+  /**
+   * @param   id    Number or String
+   */
   hasTopic (id) {
     return this.getTopicIfExists(id)
   }
 
+  /**
+   * @param   id    Number or String
+   */
   hasAssoc (id) {
     return this.getAssocIfExists(id)
   }
 
+  /**
+   * @param   id    Number or String
+   */
   hasObject (id) {
     return this.hasTopic(id) || this.hasAssoc(id)
   }
 
+  /**
+   * @param   id    Number or String
+   */
   hasVisibleObject (id) {
     const o = this.getTopicIfExists(id) || this.getAssocIfExists(id)
     return o && o.isVisible()
@@ -831,8 +854,7 @@ class Topicmap extends Topic {
     if (!(topic instanceof ViewTopic)) {
       throw Error(`addTopic() expects ViewTopic, got ${topic.constructor.name}`)
     }
-    // reactivity is required to trigger "visibleTopicIds" getter (module dmx-cytoscape-renderer)
-    Vue.set(this._topics, topic.id, topic)
+    this._topics[topic.id] = topic
   }
 
   /**
@@ -845,8 +867,7 @@ class Topicmap extends Topic {
     if (!(assoc instanceof ViewAssoc)) {
       throw Error(`addAssoc() expects ViewAssoc, got ${assoc.constructor.name}`)
     }
-    // reactivity is required to trigger "visibleAssocIds" getter (module dmx-cytoscape-renderer)
-    Vue.set(this._assocs, assoc.id, assoc)
+    this._assocs[assoc.id] = assoc
   }
 
   /**
@@ -880,7 +901,11 @@ class Topicmap extends Topic {
       viewTopic.children = topic.children   // ### TODO, see comment in newViewTopic() above
       this.addTopic(viewTopic)
       op.type = 'add'
-      op.viewTopic = viewTopic
+      op.viewTopic = this.getTopic(topic.id)
+      // Note: we don't assign plain "viewTopic" to op.viewTopic but must re-access it by this.getTopic(). In case of a
+      // Vue 3 application both are not the same as addTopic() implicitly wraps viewTopic into a JS Proxy object
+      // (provided this Topicmap instance is reactive state). All subsequent modifications of viewTopic (in particular
+      // the initialization of its position) must be applied to the Proxy object then, not the original viewTopic.
     } else {
       if (!viewTopic.isVisible()) {
         viewTopic.setVisibility(true)
@@ -919,11 +944,8 @@ class Topicmap extends Topic {
 
   updateTopic (topic) {
     if (this.id === topic.id) {
-      Vue.set(
-        this.children,
-        'dmx.base.url#dmx.topicmaps.background_image',
-        topic.children['dmx.base.url#dmx.topicmaps.background_image']
-      )
+      const uri = 'dmx.base.url#dmx.topicmaps.background_image'
+      this.children[uri] = topic.children[uri]
     }
   }
 
@@ -934,16 +956,14 @@ class Topicmap extends Topic {
    * Note: if the topic is not in this topicmap nothing is performed.
    */
   removeTopic (id) {
-    // reactivity is required to trigger "visibleTopicIds" getter (module dmx-cytoscape-renderer)
-    Vue.delete(this._topics, id)
+    delete this._topics[id]
   }
 
   /**
    * Note: if the assoc is not in this topicmap nothing is performed.
    */
   removeAssoc (id) {
-    // reactivity is required to trigger "visibleAssocIds" getter (module dmx-cytoscape-renderer)
-    Vue.delete(this._assocs, id)
+    delete this._assocs[id]
   }
 
   // Associations
@@ -1042,9 +1062,7 @@ const viewPropsMixin = Base => class extends Base {
   }
 
   setViewProp (propUri, value) {
-    // Note: some view props must be reactive, e.g. 'dmx.topicmaps.pinned' reflects pin button state.
-    // Test it with topics/assocs which don't have a 'dmx.topicmaps.pinned' setting yet. ### FIXDOC
-    Vue.set(this.viewProps, propUri, value)
+    this.viewProps[propUri] = value
   }
 }
 

package/src/rpc.js

@@ -536,7 +536,7 @@ export default {
   },
 
   /**
-   * @param   password   expected to be SHA256 encoded
+   * @param   password   plain text
    *
    * @return  a promise for a Username topic
    */

package/src/type-cache.js

@@ -1,7 +1,7 @@
-import {Topic, TopicType, AssocType, RoleType} from './model'
+import { nextTick } from 'vue'
+import { Topic, TopicType, AssocType, RoleType } from './model'
 import rpc from './rpc'
 import utils from './utils'
-import Vue from 'vue'
 
 const typeP = {}      // intermediate type promises
 
@@ -87,7 +87,7 @@ const actions = {
       }
       // Note: role types are never updated as they are simple values and thus immutable
     })
-    Vue.nextTick(() => {
+    nextTick(() => {
       // console.log(`Type-cache: processing ${directives.length} directives (DELETE_TYPE)`)
       directives.forEach(dir => {
         switch (dir.type) {
@@ -278,25 +278,21 @@ function _putType (type, typeClass, prop) {
   if (!(type instanceof typeClass)) {
     throw Error(`can't cache "${type.constructor.name}", expected is "${typeClass.name}", ${JSON.stringify(type)}`)
   }
-  // Note: type cache must be reactive
-  Vue.set(state[prop], type.uri, type)
+  state[prop][type.uri] = type
 }
 
 // ---
 
 function removeTopicType (uri) {
-  // Note: type cache must be reactive
-  Vue.delete(state.topicTypes, uri)
+  delete state.topicTypes[uri]
 }
 
 function removeAssocType (uri) {
-  // Note: type cache must be reactive
-  Vue.delete(state.assocTypes, uri)
+  delete state.assocTypes[uri]
 }
 
 function removeRoleType (uri) {
-  // Note: type cache must be reactive
-  Vue.delete(state.roleTypes, uri)
+  delete state.roleTypes[uri]
 }
 
 // ---

package/src/websocket.js

@@ -1,4 +1,4 @@
-const IDLE_INTERVAL = 60 * 1000     // 60s
+const HEARTBEAT_INTERVAL = 25 * 1000     // 25s
 
 /**
  * A WebSocket connection to the DMX server.
@@ -13,6 +13,8 @@ const IDLE_INTERVAL = 60 * 1000     // 60s
 export default class DMXWebSocket {
 
   /**
+   * @param   config
+   *              a promise for an object having a `dmx.websockets.url` property.
    * @param   messageHandler
    *              the function that processes incoming messages.
    *              One argument is passed: the message pushed by the server (a deserialzed JSON object).
@@ -20,8 +22,8 @@ export default class DMXWebSocket {
   constructor (config, messageHandler) {
     this.messageHandler = messageHandler
     config.then(config => {
+      document.addEventListener('visibilitychange', this._handleVisibilityChange.bind(this))
       this.url = config['dmx.websockets.url']
-      // DEV && console.log('[DMX] CONFIG: WebSocket server is reachable at', this.url)
       this._connect()
     })
   }
@@ -35,11 +37,21 @@ export default class DMXWebSocket {
     this.ws.send(JSON.stringify(message))
   }
 
+  _handleVisibilityChange () {
+    DEV && console.log('[DMX] Document visibility:', document.visibilityState, new Date())
+    if (document.visibilityState === "hidden") {
+      // mobile browsers often kill background sockets anyway
+      this._close()
+    } else {
+      this._connect()
+    }
+  }
+
   _connect () {
-    DEV && console.log('[DMX] Opening WebSocket connection to', this.url)
+    DEV && console.log('[DMX] Connecting', this.url)
     this.ws = new WebSocket(this.url)
     this.ws.onopen = e => {
-      this._startIdling()
+      this._startHeartbeat()
     }
     this.ws.onmessage = e => {
       const message = JSON.parse(e.data)
@@ -47,33 +59,32 @@ export default class DMXWebSocket {
       this.messageHandler(message)
     }
     this.ws.onclose = e => {
-      DEV && console.log('[DMX] WebSocket connection closed (' + e.reason + ')')
-      this._stopIdling()
-      this._reload()      // a closed ws connection is regarded an (backend/network) error which requires page reloading
+      DEV && console.log('[DMX] WebSocket closed', e.reason)
+      this._cleanup()
     }
     this.ws.onerror = e => {
       DEV && console.warn('[DMX] WebSocket error')
     }
   }
 
-  _startIdling () {
-    this.idleId = setInterval(this._idle.bind(this), IDLE_INTERVAL)
+  _startHeartbeat () {
+    this.heartbeatTimer = setInterval(this._ping.bind(this), HEARTBEAT_INTERVAL)
+  }
+
+  _stopHeartbeat () {
+    clearInterval(this.heartbeatTimer)
   }
 
-  _stopIdling () {
-    clearInterval(this.idleId)
+  _ping () {
+    DEV && console.log('[DMX] WebSocket ping')
+    this.send({type: 'ping'})
   }
 
-  _idle () {
-    DEV && console.log('[DMX] WebSocket connection idle')
-    this.send({type: 'idle'})
+  _close () {
+    this.ws.close()
   }
 
-  _reload () {
-    setTimeout(() => {
-      alert('There is a problem with the server or network.\n\nPlease press OK to reload page.\n' +
-        'If it fails try manual page reload.')
-      location.reload()
-    }, 1000)    // timeout to not interfere with interactive page reload (which also closes websocket connection)
+  _cleanup () {
+    this._stopHeartbeat()
   }
 }