XWIKI-24372: Implement auto-save for BlockNote realtime collaboration sessions

* Separate the generic XWiki document API from the real-time specific one, by splitting the XWikiDocument class in
  two: XWikiDocument, which holds the generic API, and RealtimeXWikiDocument, which adds the Netflux channels API on
  top of it. Both stay in the same module for now.
* Decouple XWikiDocument from the current document, so that it can target any document: the constructor became a copy
  constructor, update() merges only the data it is given, and the current document is now obtained through the static
  currentDocument() factory. The page state side effect (the meta version and the hidden fields of the edit form)
  moved to syncCurrentDocumentState().
* Limit the jQuery usage to event handling, which is the only place where it is required, since XWiki triggers its
  events with jQuery: $.extend became Object.assign, $.param became URLSearchParams, $.getJSON and $.post became
  fetch, and $('#id').val() became plain DOM access. Note that fetch keeps the form token and the custom XWiki
  response headers working because xwiki.js wraps it for that purpose.
* Remove XWikiDocument#save(), which never had a caller since it was introduced.
* Request the REST API of the edited document translation rather than the one of the original translation, which is
  exposed through a different URL. The Netflux channels are still requested from the page, because they are not
  exposed per translation: the translations are separated by the channel path instead.
* Stop overwriting the language field received from the REST API. The raw locale is kept in 'language' while the real
  locale is exposed by the new realLocale accessor, computed from the raw locale and the default locale.
* Align the XWikiDocument implementation with the one from XWiki.InplaceEditing, in order to ease a future
  de-duplication: reuse its getOldAPI() and removeNullProperties() helpers, its real locale computation and its
  translation aware REST URL. The fallback on document.documentElement.lang is deliberately left out, because two
  users having different UI locales would then compute different real locales for a technical document (the one
  having the root locale as default locale), and thus end up using different Netflux channels.

Verified with RealtimeWYSIWYGEditorIT (28 tests) after each step. Two cases are not covered by the automated tests
and were checked by reading the code only:

* a technical document, having the root locale as default locale, edited by two users having different UI locales;
* the toolbar version entries, whose author and date come from the document translation history.

Both deserve a follow-up, together with these two findings:

* Saver#_notifyInitialVersion() swallows every error with a console.debug(), which is why the REST URL targeting the
  wrong document translation produced no signal at all.
* The in-place editor and lock.js compute the real locale of a technical document from the UI locale, so two users
  having different UI locales use different lock keys for the same document translation.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: mflorea

xwiki-platform-core/xwiki-platform-realtime/xwiki-platform-realtime-ui/src/main/resources/XWiki/Realtime/Configuration.xml

@@ -540,18 +540,19 @@ ul.realtime-versions > li.divider:last-child {
 {{html clean="false"}}
 #getUserAvatarURL($xcontext.userReference $avatarURL 120)
 ## Note that we have to pass some document information that is missing from the meta:
-## * meta includes only the raw document locale value which is the same for documents with translations (e.g. having
-##   English as default locale) and for technical documents that don't have translations (e.g. having ROOT as default
-##   locale)
-## * meta includes the document version but not its timestamp which is needed to be able to properly merge on save.
+## * 'realLocale' because meta includes only the raw document locale value which is the same for documents with
+##   translations (e.g. having English as default locale) and for technical documents that don't have translations
+##   (e.g. having ROOT as default locale)
+## * 'modified' because meta includes the document version but not its timestamp which is needed to be able to
+##   properly merge on save.
 #set ($config = {
   'webSocketURL': $services.websocket.url('netflux'),
   'user': {
     'name': $xwiki.getUserName($xcontext.user, false),
     'avatarURL': $avatarURL.url
   },
   'document': {
-    'language': $tdoc.realLocale,
+    'realLocale': $tdoc.realLocale,
     'modified': $tdoc.date.time
   },
   'dateFormat': $xwiki.getXWikiPreference('dateformat', 'yyyy/MM/dd HH:mm')

xwiki-platform-core/xwiki-platform-realtime/xwiki-platform-realtime-webjar/src/main/webjar/document.js

@@ -24,97 +24,196 @@ define('xwiki-realtime-document', [
 ], function($, meta, realtimeConfig) {
   'use strict';
 
-  const channelListAPI = {
-    getByPath: function(path) {
-      return this.find(channel => JSON.stringify(channel.path) === JSON.stringify(path));
-    },
-    getByPathPrefix: function(pathPrefix) {
-      return this.filter(channel => channel.path.length >= pathPrefix.length &&
-        JSON.stringify(channel.path.slice(0, pathPrefix.length)) === JSON.stringify(pathPrefix));
+  // Serialize the given parameters as a query string, supporting multi-value parameters (e.g. {path: ['a', 'b']}) and
+  // ignoring the parameters that have no value. Parameters that are already serialized are returned as they are.
+  function toQueryString(params) {
+    if (typeof params !== 'object' || params === null) {
+      return params;
     }
-  };
+    const queryString = new URLSearchParams();
+    for (const [name, value] of Object.entries(params)) {
+      for (const item of Array.isArray(value) ? value : [value]) {
+        if (item !== undefined && item !== null) {
+          queryString.append(name, item);
+        }
+      }
+    }
+    return queryString.toString();
+  }
+
+  // Fetch JSON from the given URL. The error thrown when the request fails carries the response status.
+  async function getJSON(url) {
+    const response = await fetch(url, {
+      // The XWiki REST API doesn't specify how its responses should be cached, so we ask for a fresh one.
+      cache: 'no-store',
+      headers: {
+        // Without this the XWiki REST API answers with XML.
+        'Accept': 'application/json',
+        // Some server side code answers differently when the request is made from JavaScript.
+        'X-Requested-With': 'XMLHttpRequest'
+      }
+    });
+    if (!response.ok) {
+      const error = new Error(`Failed to fetch [${url}]. Response status: ${response.status}`);
+      error.status = response.status;
+      throw error;
+    }
+    return response.json();
+  }
+
+  function getOldAPI(xwikiDocument) {
+    return (xwikiDocument.documentReference && new XWiki.Document(xwikiDocument.documentReference)) ||
+      XWiki.currentDocument;
+  }
+
+  function removeNullProperties(object) {
+    return Object.fromEntries(Object.entries(object).filter(([key, value]) => value != null));
+  }
 
+  // The value of a hidden field of the edit form, when that field is present.
+  function getFieldValue(id) {
+    return document.getElementById(id)?.value;
+  }
+
+  // Update the value of a hidden field of the edit form, when that field is present.
+  function setFieldValue(id, value) {
+    const field = document.getElementById(id);
+    if (field) {
+      field.value = value;
+    }
+  }
+
+  // Generic client-side API for an XWiki document. Nothing real-time specific should go here.
   class XWikiDocument {
-    constructor() {
-      // Initialize with document fields coming from the real-time configuration.
-      $.extend(this, realtimeConfig.document);
-      this.update();
-    }
-
-    reload() {
-      return $.getJSON(meta.restURL, {
-        // Make sure the response is not retrieved from cache (IE11 doesn't obey the caching HTTP headers).
-        timestamp: Date.now()
-      }).then(updatedDocument => {
-        // Reload succeeded.
-        // We were able to load the document so it's not new.
-        this.isNew = false;
-        return $.extend(this, updatedDocument, {
-          // We need the real locale.
-          language: updatedDocument.language || updatedDocument.translations['default']
+    // The document currently displayed by the web page, with the fields exposed by the meta information.
+    static currentDocument() {
+      return new this({
+        documentReference: meta.documentReference,
+        language: meta.locale,
+        version: meta.version,
+        isNew: meta.isNew
+      });
+    }
+
+    constructor(data) {
+      Object.assign(this, data);
+    }
+
+    async reload() {
+      try {
+        const updatedDocument = await getJSON(this.getRestURL());
+        return this.update({
+          // The REST API response includes some properties with null values, that would otherwise overwrite the
+          // properties of this document that have a value set.
+          ...removeNullProperties(updatedDocument),
+          // We were able to load the document so it's not new.
+          isNew: false
         });
-      }, error => {
+      } catch (error) {
         if (error.status === 404) {
           // The document doesn't exist anymore. Maybe it was deleted?
-          return $.extend(this, {
+          return this.update({
             version: '1.1',
             modified: 0,
             content: '',
             isNew: true
           });
-        } else {
-          // Reload failed. Continue using the current data.
-          return this;
         }
-      }).then(this.update.bind(this));
+        // Otherwise the reload failed and we continue using the current data.
+        return this.update();
+      }
     }
 
     update(data) {
-      data = data || {
-        documentReference: meta.documentReference,
-        // We need the real locale.
-        language: meta.locale || realtimeConfig.document.language,
-        version: meta.version,
-        // The timestamp of the last modification is needed to be able to properly merge on save.
-        modified: meta.modified || realtimeConfig.document.modified,
-        isNew: meta.isNew
-      };
-      $.extend(this, data);
-      if (this.documentReference === meta.documentReference && this.version !== meta.version) {
-        // Update the meta and the hidden fields used by the edit form in order to ensure proper merge on save.
+      Object.assign(this, data);
+      this.syncCurrentDocumentState();
+      return this;
+    }
+
+    // Whether this document is the one currently displayed by the web page.
+    isCurrentDocument() {
+      return !!this.documentReference?.equals(meta.documentReference);
+    }
+
+    // Keep the meta and the hidden fields used by the edit form in sync, in order to ensure a proper merge on save.
+    syncCurrentDocumentState() {
+      if (this.isCurrentDocument() && this.version !== meta.version) {
         meta.setVersion(this.version);
-        $('#editingVersionDate').val(this.modified);
-        $('#isNew').val(this.isNew);
+        setFieldValue('editingVersionDate', this.modified);
+        setFieldValue('isNew', this.isNew);
       }
-      return this;
     }
 
-    save(data) {
-      return $.post(globalThis.docsaveurl, $.param($.extend({
-        /* jshint camelcase:false */
-        form_token: meta.form_token,
-        xredirect: '',
-        language: this.language,
-        xaction: ['save', 'saveandcontinue', 'preview', 'cancel'],
-        action_saveandcontinue: 'Save',
-        xeditaction: 'edit',
-        previousVersion: this.version,
-        isNew: this.isNew,
-        editingVersionDate: this.modified,
-        minorEdit: 1,
-        ajax: true
-      }, data), true)).then(this.reload.bind(this));
+    // This document's real locale. It differs from its (raw) locale only for the original translation, whose raw
+    // locale is empty.
+    get realLocale() {
+      const locale = this.language;
+      if (typeof locale !== 'string' || locale === '') {
+        return this.defaultLocale;
+      }
+      return locale;
+    }
+
+    // The locale of this document's original translation. Note that it is the empty string for a technical document,
+    // whose default locale is the root locale.
+    get defaultLocale() {
+      return this.translations?.['default'];
+    }
+
+    getURL(action, params, fragment) {
+      return getOldAPI(this).getURL(action, toQueryString(params), fragment);
+    }
+
+    // The REST URL of the wiki page this document belongs to, without taking its translation into account.
+    getPageRestURL(entity, params) {
+      return getOldAPI(this).getRestURL(entity, toQueryString(params));
+    }
+
+    // The REST URL of this document. Note that a document translation is exposed through a different REST URL than
+    // the original translation.
+    getRestURL(entity, params) {
+      const translationEntity = this.language && ('translations/' + encodeURIComponent(this.language));
+      return this.getPageRestURL([translationEntity, entity].filter(segment => segment).join('/'), params);
+    }
+
+    getRevision(version) {
+      return getJSON(this.getRestURL('history/' + encodeURIComponent(version), {
+        prettyNames: true
+      }));
+    }
+  }
+
+  const channelListAPI = {
+    getByPath: function(path) {
+      return this.find(channel => JSON.stringify(channel.path) === JSON.stringify(path));
+    },
+    getByPathPrefix: function(pathPrefix) {
+      return this.filter(channel => channel.path.length >= pathPrefix.length &&
+        JSON.stringify(channel.path.slice(0, pathPrefix.length)) === JSON.stringify(pathPrefix));
+    }
+  };
+
+  // Adds the real-time channels API on top of the generic XWiki document API.
+  class RealtimeXWikiDocument extends XWikiDocument {
+    static currentDocument() {
+      const currentDocument = super.currentDocument();
+      const config = realtimeConfig.document || {};
+      if (!currentDocument.language) {
+        // We know this is the original document translation, but the meta information doesn't expose its actual
+        // (real) locale, so we take it from the real-time configuration.
+        currentDocument.translations = {'default': config.realLocale};
+      }
+      // The meta information doesn't expose the date of the last modification, which is needed to properly merge on
+      // save. We keep it up to date on the edit form ourselves, see syncCurrentDocumentState().
+      currentDocument.modified = Number(getFieldValue('editingVersionDate')) || config.modified;
+      return currentDocument;
     }
 
     getChannels(params) {
-      const url = new XWiki.Document(this.documentReference).getRestURL('channels');
-      params = $.extend({
-        // Make sure the response is not retrieved from cache (IE11 doesn't obey the caching HTTP headers).
-        timestamp: Date.now()
-      }, params);
-      return $.getJSON(url, $.param(params, true)).then(function(data) {
+      const url = this.getPageRestURL('channels', params);
+      return getJSON(url).then(function(data) {
         if (Array.isArray(data)) {
-          return $.extend(data, channelListAPI);
+          return Object.assign(data, channelListAPI);
         } else {
           throw new TypeError('Invalid response from the server when requesting the list of document channels.',
             {cause: data});
@@ -123,24 +222,15 @@ define('xwiki-realtime-document', [
         throw new Error('Failed to retrieve the list of document channels.', {cause: error});
       });
     }
-
-    getURL(...args) {
-      return new XWiki.Document(this.documentReference).getURL(...args);
-    }
-
-    getRevision(version) {
-      return $.getJSON(meta.restURL + '/history/' + encodeURIComponent(version), $.param({
-        prettyNames: true
-      }, true));
-    }
   }
 
-  // Initialize the document fields based on the meta information available on page load.
-  const xwikiDocument = new XWikiDocument();
+  // The document currently displayed by the web page.
+  const xwikiDocument = RealtimeXWikiDocument.currentDocument();
 
   // Update the document fields before and after the document is edited inplace (without reloading the web page).
+  // We need jQuery here because these events are triggered with jQuery.
   $(document).on('xwiki:actions:edit xwiki:actions:view', function(event, data) {
-    xwikiDocument.update();
+    xwikiDocument.update(RealtimeXWikiDocument.currentDocument());
   });
 
   return xwikiDocument;

xwiki-platform-core/xwiki-platform-realtime/xwiki-platform-realtime-webjar/src/main/webjar/loader.js

@@ -69,11 +69,11 @@ define('xwiki-realtime-loader', [
     async updateChannels() {
       const channels = await doc.getChannels({
         path: [
-          `translations/${doc.language}/saver`,
-          `translations/${doc.language}/userData`,
-          `translations/${doc.language}/fields/${this.info.field}/editors/${this.info.type}`,
+          `translations/${doc.realLocale}/saver`,
+          `translations/${doc.realLocale}/userData`,
+          `translations/${doc.realLocale}/fields/${this.info.field}/editors/${this.info.type}`,
           // Check also if the field is edited in real-time with other editors at the same time.
-          `translations/${doc.language}/fields/${this.info.field}/editors/`,
+          `translations/${doc.realLocale}/fields/${this.info.field}/editors/`,
         ],
         create: true
       });
@@ -83,9 +83,9 @@ define('xwiki-realtime-loader', [
 
     _parseChannels(channels) {
       let keys = {};
-      const saverChannel = channels.getByPath(['translations', doc.language, 'saver']);
-      const userDataChannel = channels.getByPath(['translations', doc.language, 'userData']);
-      const editorChannel = channels.getByPath(['translations', doc.language, 'fields', this.info.field, 'editors',
+      const saverChannel = channels.getByPath(['translations', doc.realLocale, 'saver']);
+      const userDataChannel = channels.getByPath(['translations', doc.realLocale, 'userData']);
+      const editorChannel = channels.getByPath(['translations', doc.realLocale, 'fields', this.info.field, 'editors',
         this.info.type]);
       if (!saverChannel || !userDataChannel || !editorChannel) {
         console.error('Missing document channels.');
@@ -100,7 +100,7 @@ define('xwiki-realtime-loader', [
         // Collect the other active real-time editing session (for the specified document field) that are using a
         // different editor (e.g. the WYSIWYG editor).
         channels.getByPathPrefix([
-          'translations', doc.language, 'fields', this.info.field, 'editors'
+          'translations', doc.realLocale, 'fields', this.info.field, 'editors'
         ]).forEach(channel => {
           if (channel.userCount > 0 && JSON.stringify(channel.path) !== JSON.stringify(editorChannel.path)) {
             keys.active[channel.path.slice(5).join('/')] = channel;
@@ -482,7 +482,7 @@ define('xwiki-realtime-loader', [
 
   getAllUsersChannel = async function() {
     const channels = await doc.getChannels({
-      path: `translations/${doc.language}/loader`,
+      path: `translations/${doc.realLocale}/loader`,
       create: true
     });
     if (channels.length) {

xwiki-platform-core/xwiki-platform-realtime/xwiki-platform-realtime-webjar/src/main/webjar/toolbar.js

@@ -320,10 +320,10 @@ define('xwiki-realtime-toolbar', [
       const template = document.querySelector('template#realtime-version');
       const versionElement = template.content.querySelector('.realtime-version').cloneNode(true);
       versionElement.dataset.version = JSON.stringify(version);
-      versionElement.href = xwikiDocument.getURL('view', $.param({
+      versionElement.href = xwikiDocument.getURL('view', {
         'rev': version.number,
-        'language': xwikiDocument.language
-      }));
+        'language': xwikiDocument.realLocale
+      });
       versionElement.querySelector('.realtime-version-number').textContent = version.number;
       versionElement.querySelector('.realtime-version-date').textContent = moment(version.date)
         .format(this._dateFormat);

xwiki-platform-core/xwiki-platform-realtime/xwiki-platform-realtime-wysiwyg/xwiki-platform-realtime-wysiwyg-webjar/src/main/webjar/wysiwygEditor.js

@@ -422,13 +422,13 @@ define('xwiki-realtime-wysiwyg', [
     }
 
     async _resetContent() {
-      const html = await $.get(xwikiDocument.getURL('get', $.param({
+      const html = await $.get(xwikiDocument.getURL('get', {
         xpage:'get',
         outputSyntax:'annotatedhtml',
         outputSyntaxVersion:'5.0',
         transformations:'macro',
-        language: xwikiDocument.language
-      })));
+        language: xwikiDocument.realLocale
+      }));
       this._hideChangesFromSaver(this._patchedEditor.setHTML(html, true));
     }