@brightspot/ui 3.0.0 → 3.0.1-cms-ui-migration.1

package/src/legacy/tool-ui/src/main/webapp/v4/rte/plugins/enhancement_manager/EnhancementManager.js

@@ -0,0 +1,428 @@
+import { PM_CONTEXT_PATH } from './constants'
+import { Plugin, PluginKey, TextSelection } from 'prosemirror-state'
+import { DOMParser } from 'prosemirror-model'
+import { keydownHandler } from 'prosemirror-keymap'
+import { constants } from '../../settings'
+import { Decoration, DecorationSet } from 'prosemirror-view'
+import { setBlockType } from 'prosemirror-commands'
+import { keyMappingHandler } from '../../settings/keymapBuilder'
+import onVisible from '../../../dom/onVisible'
+import { v1 as uuidv1 } from 'uuid'
+
+const RICH_TEXT_ELEMENTS_PM_MAP = new Map()
+RICH_TEXT_ELEMENTS_PM.forEach((item) => {
+  RICH_TEXT_ELEMENTS_PM_MAP.set(item.tag, item)
+})
+
+/**
+ * Generates the partial URL for the enhancement form that opens in the popup.
+ *
+ * @param {string} enhancementID type id of the enhancement, which determines
+ *    what form is called and opened.
+ */
+const getEnhancementEditFormURL = (
+  enhancementID,
+  element,
+  isCustom,
+  customUrl,
+) => {
+  const closestElementWithTypeId = element.closest('form[data-type-id]')
+  const closestElementWithContainerId = element.closest('form[data-object-id]')
+  let containerTypeId = ''
+  let containerId = ''
+
+  if (closestElementWithTypeId) {
+    containerTypeId = closestElementWithTypeId.getAttribute('data-type-id')
+  }
+  if (closestElementWithContainerId) {
+    containerId = closestElementWithContainerId.getAttribute('data-object-id')
+  }
+
+  if (isCustom && customUrl) {
+    return `${PM_CONTEXT_PATH}${customUrl}`
+  }
+
+  return `${PM_CONTEXT_PATH}content/enhancement.jsp?typeId=${enhancementID}&containerTypeId=${containerTypeId}&containerId=${containerId}`
+}
+
+/**
+ * Sets up the topic subscription to listen to the topic that triggers the publish
+ * function below. See the top of the enhancement.jsp file to find the publish trigger.
+ * It is embedded in the java code that produces the JS, which also closes the popup.
+ *
+ * @param {string} tempId A temp id from the originating command to be used as the topic
+ *    for the pub/sub triggerded from the enhancement.jsp. We store this on the event trigger
+ *    because the java-generated JS has access to that DOM element.
+ * @param {Object.<string>} meta
+ * @param {Prosemirror.EditorState} state
+ * @param {Prosemirror.EditorView.dispatch} dispatch
+ * @param {Event} evt DOM event that triggered the originating command.
+ * @param {string} text The text the user entered, in case we don't get back a label.
+ * @param {ProseMirror.Node|null} node Node or mark that is being modified during an enhancement
+ *    edit.
+ * @param {boolean} isEdit Flag to indicate if this is an edit to an existing enhancement
+ * @param {string} id UUID of the enhancement decoration
+ * @param {ProseMirror.EditorView} editorView
+ */
+const setUpSubscription = (
+  editorView,
+  tempId,
+  meta,
+  state,
+  dispatch,
+  evt,
+  text,
+  node,
+  isEdit,
+  id,
+) => {
+  PubSub.subscribe(tempId, (incomingData) => {
+    incomingData.meta = meta
+    publish(incomingData, dispatch, text, node, isEdit, id, editorView)
+    return false
+  })
+}
+
+/**
+ * Sets up and then triggers the frame and its popup
+ *    popup that will contain the enhancement form.
+ *
+ * @param {Event} evt DOM event that triggered the originating
+ *    command. We need this to properly trigger the frame as it's
+ *    part of the frame API.
+ * @param {string} id UUID of the enhancement decoration
+ * @param {ProseMirror.EditorView} editorView
+ */
+const setUpAndTriggerFrame = (evt, id, editorView) => {
+  if (!evt.target.getAttribute('target')) {
+    evt.target.setAttribute('target', `contentEnhancement-${Date.now()}`)
+  }
+
+  const $eventParent = $(evt.target.parent)
+  const $framedParent = $eventParent.frame()
+  $framedParent.trigger('create')
+  $framedParent.trigger('click.frame')
+  onVisible(
+    `.Popup[name="${evt.target.getAttribute('target')}"]`,
+    (element) => {
+      const closeButton = element.querySelector('.Popup-close')
+      if (closeButton) {
+        closeButton.addEventListener('click', () => {
+          PubSub.publish('collabUnlock', { id })
+          editorView.focus()
+        })
+      }
+      const saveButton = element.querySelector('.action-save')
+      if (saveButton) {
+        saveButton.addEventListener('click', () => {
+          PubSub.publish('collabUnlock', { id })
+          editorView.focus()
+        })
+      }
+    },
+  )
+}
+
+/**
+ * This builds the label. It will fall back to the text the user
+ * entered (if any) if there is no label. If no label and no text,
+ * we will look for an `href` attribute in case this is a link that
+ * was created without a label and without any starter text. Otherwise,
+ * we get back an empty string.
+ *
+ * @param {Object.<Object.<string>>} enhancementData The data about the enhancement
+ *    from the server.
+ * @param {string} text The text the user entered.
+ * @return {string} The label, derived by what fields are available.
+ */
+const getLabel = (enhancementData, text) => {
+  return (
+    enhancementData.label ||
+    text ||
+    (enhancementData.data && enhancementData.data.href) ||
+    ''
+  )
+}
+
+/**
+ * This is triggered when a subscription is published from the enhancement.jsp.
+ * See the top of the enhancement.jsp file to find the publish trigger. It is embedded in
+ * the java code that produces the JS, which also closes the popup. The enhancement
+ * data includes the `label`, which is the contract between the back and front-ends for
+ * the text that is displayed for an enhancement. All data needed to save and display
+ * the enhancement is in the enhancement data. In addition, the meta data for the enhancement
+ * is included in the enhancementData object so that the enhancement has it readily
+ * available for when the user edits the enhancement.
+ *
+ * @param {Object.<string|number|Array|Object>} enhancementData The data returned from
+ *    the server upon sucessful save.
+ * @param {Prosemirror.EditorState} state
+ * @param {Prosemirror.EditorView.dispatch} dispatch Announces a transaction
+ *    This method is bound to the view instance, so that it can be easily passed around.
+ * @param {string} text The text the user entered, in case we don't get back a label.
+ * @param {ProseMirror.Node|null} node Node or mark that is being modified during an enhancement
+ *    edit.
+ * @param {boolean} isEdit Flag to indicate if this is an edit to an existing enhancement
+ * @param {string} id UUID of the enhancement decoration
+ * @param {ProseMirror.EditorView} editorView
+ */
+const publish = (
+  enhancementData,
+  dispatch,
+  text,
+  node,
+  isEdit,
+  id,
+  editorView,
+) => {
+  let state = editorView.state
+  let transaction = state.tr
+  let from
+
+  if (node?.attrs?.id) {
+    const doc = state.doc
+    let to
+
+    doc.descendants((n, p) => {
+      if (
+        n.attrs.id === node.attrs.id ||
+        n.marks.some((mark) => mark.attrs.id === node.attrs.id)
+      ) {
+        if (!from) {
+          from = p
+        }
+
+        to = p + n.nodeSize
+      }
+    })
+
+    transaction.setSelection(TextSelection.create(doc, from, to))
+  } else {
+    from = state.selection.from
+  }
+
+  const { empty, ranges, $anchor } = state.selection
+
+  let label = getLabel(enhancementData, text)
+  if (enhancementData.meta.line && !enhancementData.meta.readOnly) {
+    const node = state.doc.nodeAt($anchor.before($anchor.depth))
+    if (node) {
+      label = node.textContent ? node.textContent : label
+    }
+  }
+  const schema = state.config.schema
+
+  let enhancement
+  let pos = findPlaceholder(editorView, id)
+  if (pos == null) return
+  const nodeId = isEdit ? node.attrs.id : `enhancement-${uuidv1()}`
+
+  if (Array.isArray(enhancementData)) {
+    enhancementData.forEach((enhancement, index) => {
+      let tag = enhancementData.meta.tag
+      if (enhancement.tag) {
+        enhancement.meta = RICH_TEXT_ELEMENTS_PM_MAP.get(enhancement.tag)
+        tag = enhancement.tag
+      }
+      const enhancementType = schema.nodes[tag]
+      enhancement = enhancementType.create({
+        label,
+        attributes: enhancement.data,
+        typeId: enhancement.enhancementID,
+        meta: enhancement.meta,
+        id: nodeId,
+      })
+
+      transaction.insert(pos.from + index, enhancement)
+    })
+  } else {
+    let tag = enhancementData.meta.tag
+    if (enhancementData.tag) {
+      enhancementData.meta = RICH_TEXT_ELEMENTS_PM_MAP.get(enhancementData.tag)
+      tag = enhancementData.tag
+    }
+
+    if (enhancementData.meta.readOnly || enhancementData.meta.line) {
+      const enhancementType = schema.nodes[tag]
+      if (enhancementData.meta.readOnly) {
+        const enhancementType = schema.nodes[tag]
+
+        enhancement = enhancementType.create({
+          label,
+          attributes: enhancementData.data,
+          typeId: enhancementData.enhancementID,
+          meta: enhancementData.meta,
+          id: nodeId,
+        })
+
+        transaction.replaceRangeWith(pos.from, pos.to, enhancement)
+      } else {
+        setBlockType(enhancementType, {
+          label,
+          attributes: enhancementData.data,
+          typeId: enhancementData.enhancementID,
+          meta: enhancementData.meta,
+          id: nodeId,
+        })(state, dispatch)
+        state = editorView.state
+        transaction = state.tr
+
+        if (
+          !isEdit &&
+          state.selection.empty &&
+          enhancementData?.meta?.initialBody
+        ) {
+          transaction.insert(
+            from,
+            state.schema.text(enhancementData.meta.initialBody),
+          )
+        }
+      }
+    } else {
+      const mark = schema.marks[enhancementData.meta.tag].create({
+        label,
+        attributes: enhancementData.data,
+        typeId: enhancementData.enhancementID,
+        meta: enhancementData.meta,
+        id: nodeId,
+      })
+      const domFragment = document.createElement('div')
+      domFragment.innerHTML = label || ''
+      const slice = DOMParser.fromSchema(state.schema).parseSlice(domFragment, {
+        preserveWhitespace: 'full',
+      })
+
+      // ProseMirror select all will start at 0 while text selection will start at 1.
+      const to = from + slice.size + (from === 0 ? 1 : 0)
+
+      transaction.replaceSelection(slice).addMark(from, to, mark)
+      transaction.setSelection(TextSelection.create(transaction.doc, from, to))
+    }
+  }
+  transaction.setMeta('enhancementManager$', {
+    remove: { id },
+  })
+
+  if (
+    editorView.dom.parentElement.classList.contains(
+      constants.CLASSES.IS_PLACEHOLDER_CONTENT,
+    )
+  ) {
+    editorView.dom.parentElement.classList.remove(
+      constants.CLASSES.IS_PLACEHOLDER_CONTENT,
+    )
+  }
+  dispatch(transaction.scrollIntoView())
+  return true
+}
+
+/**
+ * @type {Object.<function>} Mapping of command keys to the function
+ *    to trigger the insert enhancement command.
+ */
+const keyHandlers = RICH_TEXT_ELEMENTS_PM.reduce((prev, next) => {
+  if (next.keymap) {
+    const className = next.styleName
+    next.keymap.forEach((str) => {
+      // PM will expect the shift key to be engaged if the item is capitalized,
+      // and many of our key commands are capitalized but do not intend to
+      // require the shift key
+      prev[str.toLowerCase()] = keyMappingHandler(className)
+    })
+  }
+  return prev
+}, {})
+
+const handleKeyDown = keydownHandler(keyHandlers)
+
+const key = new PluginKey('enhancementManager')
+
+const enhancementManagerPlugin = (ctx, compliantTagNameMap) => {
+  return new Plugin({
+    key,
+    state: {
+      init() {
+        return DecorationSet.empty
+      },
+      apply(tr, set, state) {
+        // Adjust decoration positions to changes made by the transaction
+        set = set.map(tr.mapping, tr.doc)
+        let action = tr.getMeta(this)
+        let deco
+
+        if (action && action.add) {
+          if (action.add.to) {
+            deco = Decoration.inline(
+              action.add.from,
+              action.add.to,
+              { class: 'Prosemirror-placeholder' },
+              {
+                id: action.add.id,
+              },
+            )
+          } else {
+            const widget = document.createElement('placeholder')
+            deco = Decoration.widget(action.add.from, widget, {
+              side: -1,
+              id: action.add.id,
+            })
+          }
+
+          set = set.add(tr.doc, [deco])
+        } else if (action && action.remove) {
+          set = set.remove(
+            set.find(null, null, (spec) => spec.id === action.remove.id),
+          )
+        }
+
+        return set
+      },
+    },
+    view: (view) => {
+      return {
+        update: (editorView, prevState) => {
+          const currNode = editorView.state.tr?.curSelection?.node
+
+          editorView.dom
+            .querySelectorAll('.is-active')
+            .forEach((n) => n.classList.remove('is-active'))
+
+          if (currNode && currNode?.type?.isAtom) {
+            editorView
+              .nodeDOM(editorView.state.tr?.curSelection.from)
+              ?.classList.add('is-active')
+          }
+        },
+      }
+    },
+    props: {
+      decorations(state) {
+        return this.getState(state)
+      },
+      handleKeyDown,
+    },
+  })
+}
+
+/**
+ * Helper function to find the placeholder decoration that has a spec
+ * that provides the current position of the decoration (and thus where
+ * to insert the pasted text).
+ *
+ * @param {ProseMirror.EditorView} view
+ * @param {string} id The ID of the plugin that we want to find.
+ * @return {number|null} The current position of the decoration or null
+ *  if the decoration was not found.
+ */
+function findPlaceholder(view, id) {
+  let decos = enhancementManagerPlugin().getState(view.state)
+  let found = decos.find(null, null, (spec) => spec.id === id)
+  return found.length ? found[0] : null
+}
+
+export {
+  enhancementManagerPlugin,
+  getEnhancementEditFormURL,
+  setUpSubscription,
+  setUpAndTriggerFrame,
+}

package/src/legacy/tool-ui/src/main/webapp/v4/rte/plugins/enhancement_manager/README.md

@@ -0,0 +1,63 @@
+# Brightspot Rich Text Editor Enhancement Manager Plugin
+
+Extends Prosemirror to allow users to create custom enhancements.
+
+## Table of Contents
+
+1.  [Must Knows](#must-knows)
+2.  [Usage](#usage)
+3.  [Component and Directory Structure](#component-and-directory-structure)
+    1.  [Commands](#commands)
+    2.  [Constants](#constants)
+
+## Must Knows
+
+1. Enhancements are defined in the schema and the serializer as either nodes or marks, depending on the properties of the enhancement. They are further distinguished by their read-only (not editable), popup (has fields), and line (is block) properties. Enhancements fall into these categories and much of the code forking follows this pattern:
+
+   - **Editable (!readOnly)**
+     - Inline with popup: mark with attrs (e.g link)
+     - Line with popup: node with attrs
+     - Inline with no popup - mark
+     - line with no popup - node (e.g. headings, subheads)
+   - **Non-Editable**
+     - Inline with pop-up: node with attrs and no content
+     - Line with pop-up: node with attrs and no content (e.g. bsp-image)
+
+   The following process flow diagram depicts how the code determines whether enhancements are represented as nodes or marks and whether they have attrs or not. In general, if content is editable and is inline, it is a mark. If it is editable and a block (line), then it is a node. They will both have attrs if they have fields (have popups) that can be edited from a popup but also content that can be edited directly in the RTE. Noneditable inline and block enhancements are nodes with fields (have popups) and can only be modified via the popup.
+
+![process flow diagram](./enhancement-creation.jpeg)
+
+2. Enhancements **with** popups
+
+   1. There is an enhancement node/mark view that provides the DOM for an enhancement within the RTE. This allows us to assign event handlers to the enhancement to open the enhancement's submenu, which is 1 div that is created at RTE instantiation time (code can be found in ProseMirror.js). The node views are assigned at run-time as properties of the RTE view, and this code can be found in the main ProseMirror.js file.
+   2. The submenu content is replaced whenever the user engages a submenu and its left and top positions are set to display the submenu slightly below the enhancement text.
+   3. At the top of the enhancement.jsp file is a pub/sub publish action. It is embedded in the java code that produces the popup form JS, which also closes the popup. The "topic" data returned is the data generated by the backend for the enhancement. It is all the needed data to be added to the DOM element as attributes so that the enhancement is saved properly. The enhancement's event trigger is subscribed to this "topic", and when it is published, the enhancement DOM and node attrs will be populated with the "topic" data. The `label` is the contract between the back and front-ends for the text that is displayed for an enhancement, and it will be in the topic data. It is possible that a project might remove the `label` field, in which case the RTE uses the text in the RTE as the label. See the flow chart below for complete workflow:
+
+![Flow chart of workflow](./rte-flow.jpeg)
+
+3. Enhancements **without** popups
+
+   - Line enhancements are treated as nodes.
+   - Inline enhancements are treated as marks.
+
+4. Pasted Embeds
+   1. Cut and paste of embeds is supported via decorations because we are unable to insert DOM elements directly into the RTE DOM. Decorations are used because their positions can be mapped through state changes, thus if the user inserts any content before the paste insertion point, the position of where the embed should be inserted is also updated. The flow is:
+      - When a paste is detected, a placeholder decoration is created and an id and the current position - 1 is set on the decoration spec. Its position is mapped through state changes (managed by this plugin) in the plugin's state.apply property. We subtract one from the current position to account for the original pasted text being removed from the document.
+      - An async call is made to our backend to build the embed. It returns a string version of the embed element or just the entered text if the pasted text was not an embed link.
+      - If there are any errors returned by the promise or if plain text is returned, then the plain text is reinserted into the document.
+      - Else a block enhancement is then created. Using a helper function, we retrieve the decoration and get its current position from its spec. We use this as the transaction replacement point for the block enhancement. We then set the decoration spec to indicate that the decoration should be removed upon next state update.
+
+## Usage
+
+1. Implementation is similar to Codemirror legacy RTE. Enhancements are defined on the page inside a global object, which is output from the backend. The schema iterates over that object and builds the enhancement node or mark type spec, differentiating based on the information above.
+2. Display in the RTE can be controlled with CSS.
+
+## Component and Directory Structure
+
+### Commands
+
+This is where the insert, edit, and remove commands are defined.
+
+### Constants
+
+Constants localized to this plugin.