@harbour-enterprises/superdoc 0.18.0-next.2 → 0.18.0-next.4

package/dist/chunks/{super-editor.es-D0wPEvPh.cjs → super-editor.es-CpjpLN5S.cjs}

@@ -48516,6 +48516,10 @@ const TextAlign = Extension.create({
       {
         types: this.options.types,
         attributes: {
+          /**
+           * @category Attribute
+           * @param {string} [textAlign='left'] - Text alignment value (left, center, right, justify)
+           */
           textAlign: {
             default: this.options.defaultAlignment,
             parseDOM: (el) => {
@@ -48536,11 +48540,32 @@ const TextAlign = Extension.create({
   },
   addCommands() {
     return {
+      /**
+       * Set text alignment
+       * @category Command
+       * @param {string} alignment - Alignment value (left, center, right, justify)
+       * @returns {Function} Command function
+       * @example
+       * // Set to center
+       * setTextAlign('center')
+       *
+       * // Set to justify
+       * setTextAlign('justify')
+       * @note Applies to all configured node types (heading, paragraph by default)
+       */
       setTextAlign: (alignment2) => ({ commands: commands2 }) => {
         const containsAlignment = this.options.alignments.includes(alignment2);
         if (!containsAlignment) return false;
         return this.options.types.map((type2) => commands2.updateAttributes(type2, { textAlign: alignment2 })).every((result) => result);
       },
+      /**
+       * Remove text alignment (reset to default)
+       * @category Command
+       * @returns {Function} Command function
+       * @example
+       * unsetTextAlign()
+       * @note Resets alignment to the default value
+       */
       unsetTextAlign: () => ({ commands: commands2 }) => {
         return this.options.types.map((type2) => commands2.resetAttributes(type2, "textAlign")).every((result) => result);
       }
@@ -48571,6 +48596,10 @@ const TextIndent = Extension.create({
       {
         types: this.options.types,
         attributes: {
+          /**
+           * @category Attribute
+           * @param {string} [textIndent] - Text indentation value with unit (e.g., '0.5in')
+           */
           textIndent: {
             default: null,
             parseDOM: (el) => el.style.textIndent,
@@ -48588,13 +48617,43 @@ const TextIndent = Extension.create({
   },
   addCommands() {
     return {
+      /**
+       * Set text indentation
+       * @category Command
+       * @param {string} indent - Indentation value with unit (e.g., '0.5in', '2cm')
+       * @returns {Function} Command function
+       * @example
+       * // Set to 0.5 inches
+       * setTextIndent('0.5in')
+       *
+       * // Set to 2 centimeters
+       * setTextIndent('2cm')
+       * @note Accepts any valid CSS unit (in, cm, px, em, etc.)
+       */
       setTextIndent: (indent) => ({ commands: commands2 }) => {
         if (!indent) return false;
         return this.options.types.map((type2) => commands2.updateAttributes(type2, { textIndent: indent })).every((result) => result);
       },
+      /**
+       * Remove text indentation
+       * @category Command
+       * @returns {Function} Command function
+       * @example
+       * unsetTextIndent()
+       * @note Removes all indentation from the selected nodes
+       */
       unsetTextIndent: () => ({ commands: commands2 }) => {
         return this.options.types.map((type2) => commands2.resetAttributes(type2, "textIndent")).every((result) => result);
       },
+      /**
+       * Increase text indentation
+       * @category Command
+       * @returns {Function} Command function
+       * @example
+       * increaseTextIndent()
+       * @note Increments by the default value (0.125in by default)
+       * @note Creates initial indent if none exists
+       */
       increaseTextIndent: () => ({ commands: commands2 }) => {
         return this.options.types.map((type2) => {
           let { textIndent } = this.editor.getAttributes(type2);
@@ -48605,7 +48664,7 @@ const TextIndent = Extension.create({
             });
           }
           let [value, unit] = parseSizeUnit(textIndent);
-          value = value + this.options.defaults.increment;
+          value = Number(value) + this.options.defaults.increment;
           unit = unit ? unit : this.options.defaults.unit;
           if (Number.isNaN(value)) return false;
           return commands2.updateAttributes(type2, {
@@ -48613,12 +48672,21 @@ const TextIndent = Extension.create({
           });
         }).every((result) => result);
       },
+      /**
+       * Decrease text indentation
+       * @category Command
+       * @returns {Function} Command function
+       * @example
+       * decreaseTextIndent()
+       * @note Decrements by the default value (0.125in by default)
+       * @note Removes indentation completely if it reaches 0 or below
+       */
       decreaseTextIndent: () => ({ commands: commands2 }) => {
         return this.options.types.map((type2) => {
           let { textIndent } = this.editor.getAttributes(type2);
           if (!textIndent) return false;
           let [value, unit] = parseSizeUnit(textIndent);
-          value = value - this.options.defaults.increment;
+          value = Number(value) - this.options.defaults.increment;
           unit = unit ? unit : this.options.defaults.unit;
           if (Number.isNaN(value)) return false;
           if (value <= 0) {
@@ -49187,8 +49255,17 @@ const Gapcursor = Extension.create({
   addPmPlugins() {
     return [gapCursor()];
   },
+  /**
+   * Extend node schema to allow gap cursor positioning
+   * @returns {Object} Schema extension with allowGapCursor property
+   */
   extendNodeSchema(extension) {
     return {
+      /**
+       * Whether to allow gap cursor before/after this node
+       * Set to false on nodes where gap cursor shouldn't appear
+       * @type {boolean|null}
+       */
       allowGapCursor: callOrGet(
         getExtensionConfigField(extension, "allowGapCursor", {
           name: extension.name,
@@ -50250,10 +50327,12 @@ const getLinkedStyle = (styleId, styles = []) => {
 };
 const getSpacingStyle = (spacing) => {
   const { lineSpaceBefore, lineSpaceAfter, line, lineRule } = spacing;
+  const lineHeightResult = getLineHeightValueString(line, "", lineRule, true);
+  const lineHeightStyles = typeof lineHeightResult === "object" && lineHeightResult !== null ? lineHeightResult : {};
   return {
     "margin-top": lineSpaceBefore + "px",
     "margin-bottom": lineSpaceAfter + "px",
-    ...getLineHeightValueString(line, "", lineRule, true)
+    ...lineHeightStyles
   };
 };
 const getSpacingStyleString = (spacing) => {
@@ -50438,6 +50517,11 @@ const createLinkedStylesPlugin = (editor) => {
   return new Plugin({
     key: LinkedStylesPluginKey,
     state: {
+      /**
+       * Initialize plugin state with styles and decorations
+       * @returns {Object} Initial state with styles and decorations
+       * @private
+       */
       init() {
         if (!editor.converter || editor.options.mode !== "docx") return {};
         const styles = editor.converter?.linkedStyles || [];
@@ -50446,6 +50530,15 @@ const createLinkedStylesPlugin = (editor) => {
           decorations: generateDecorations(editor.state, styles)
         };
       },
+      /**
+       * Update decorations when document changes
+       * @param {Object} tr - The transaction
+       * @param {Object} prev - Previous plugin state
+       * @param {Object} oldEditorState - Old editor state
+       * @param {Object} newEditorState - New editor state
+       * @returns {Object} Updated state with styles and decorations
+       * @private
+       */
       apply(tr, prev, oldEditorState, newEditorState) {
         if (!editor.converter || editor.options.mode !== "docx") return { ...prev };
         let decorations = prev.decorations || DecorationSet.empty;
@@ -50457,6 +50550,12 @@ const createLinkedStylesPlugin = (editor) => {
       }
     },
     props: {
+      /**
+       * Provide decorations to the editor view
+       * @param {Object} state - Current editor state
+       * @returns {Object} The decoration set
+       * @private
+       */
       decorations(state2) {
         return LinkedStylesPluginKey.getState(state2)?.decorations;
       }
@@ -50498,24 +50597,35 @@ const LinkedStyles = Extension.create({
   addCommands() {
     return {
       /**
-       * Apply a linked style to the current selection.
-       *
-       * @param {object} style The linked style to apply
-       * @param {string} style.id The style ID (e.g., 'Heading1')
-       * @returns {boolean} Whether the style was correctly applied
+       * Apply a linked style to the selected paragraphs
+       * @category Command
+       * @param {Object} style - The style object to apply
+       * @returns {Function} Command function
+       * @example
+       * const style = editor.helpers.linkedStyles.getStyleById('Heading1');
+       * setLinkedStyle(style);
+       * @note Clears existing formatting when applying a style
+       * @note Works with custom selection preservation
        */
       setLinkedStyle: (style2) => (params2) => {
         const { tr } = params2;
         return applyLinkedStyleToTransaction(tr, this.editor, style2);
       },
       /**
-       * Toggle a linked style on the current selection.
+       * Toggle a linked style on the current selection
+       * @category Command
+       * @param {Object} style - The linked style to apply (with id property)
+       * @param {string|null} [nodeType=null] - Node type to restrict toggle to (e.g., 'paragraph')
+       * @returns {Function} Command function
+       * @example
+       * // Toggle a heading style
+       * const style = editor.helpers.linkedStyles.getStyleById('Heading1');
+       * toggleLinkedStyle(style)
        *
-       * @param {object} style The linked style to apply
-       * @param {string} style.id The style ID (e.g., 'Heading1')
-       * @param {string|null} nodeType The node type to restrict the toggle to (e.g., 'paragraph'). If null,
-       * the style can be toggled on any node type.
-       * @returns {boolean} Whether the style was correctly applied/removed
+       * // Toggle only on paragraph nodes
+       * toggleLinkedStyle(style, 'paragraph')
+       * @note If selection is empty, returns false
+       * @note Removes style if already applied, applies it if not
        */
       toggleLinkedStyle: (style2, nodeType = null) => (params2) => {
         const { tr } = params2;
@@ -50538,9 +50648,17 @@ const LinkedStyles = Extension.create({
         return applyLinkedStyleToTransaction(tr, this.editor, style2);
       },
       /**
-       * Apply a linked style by its ID.
-       * @param {string} styleId The style ID (e.g., 'Heading1')
-       * @returns {boolean} Whether the style was correctly applied
+       * Apply a linked style by its ID
+       * @category Command
+       * @param {string} styleId - The style ID to apply (e.g., 'Heading1')
+       * @returns {Function} Command function
+       * @example
+       * // Apply a heading style
+       * setStyleById('Heading1')
+       *
+       * // Apply a normal style
+       * setStyleById('Normal')
+       * @note Looks up the style from loaded Word styles
        */
       setStyleById: (styleId) => (params2) => {
         const { state: state2, tr } = params2;
@@ -50555,22 +50673,39 @@ const LinkedStyles = Extension.create({
   addHelpers() {
     return {
       /**
-       * Get all linked styles available in the editor
+       * Get all available linked styles
+       * @category Helper
        * @returns {Array} Array of linked style objects
+       * @example
+       * const styles = editor.helpers.linkedStyles.getStyles();
+       * // Returns all styles from the Word document
        */
       getStyles: () => {
         const styles = LinkedStylesPluginKey.getState(this.editor.state)?.styles || [];
         return styles;
       },
       /**
-       * Get a linked style by its ID
-       * @param {string} styleId The style ID (e.g., 'Heading1')
-       * @returns {object|null} The linked style object or null if not found
+       * Get a specific style by ID
+       * @category Helper
+       * @param {string} styleId - The style ID to find
+       * @returns {Object} The style object or undefined
+       * @example
+       * const headingStyle = editor.helpers.linkedStyles.getStyleById('Heading1');
        */
       getStyleById: (styleId) => {
         const styles = this.editor.helpers[this.name].getStyles();
         return styles.find((s) => s.id === styleId);
       },
+      /**
+       * Get the CSS string for a style
+       * @category Helper
+       * @param {string} styleId - The style ID
+       * @returns {string} CSS style string
+       * @example
+       * const css = editor.helpers.linkedStyles.getLinkedStyleString('Heading1');
+       * // Returns: "font-size: 16pt; font-weight: bold; color: #2E74B5"
+       * @private
+       */
       getLinkedStyleString: (styleId) => {
         const styles = this.editor.helpers.linkedStyles.getStyles();
         const style2 = styles.find((s) => s.id === styleId);
@@ -56949,6 +57084,10 @@ const Image = Node$1.create({
   },
   addAttributes() {
     return {
+      /**
+       * @category Attribute
+       * @param {string} [src] - Image source URL or path
+       */
       src: {
         default: null,
         renderDOM: ({ src }) => {
@@ -56957,31 +57096,90 @@ const Image = Node$1.create({
           };
         }
       },
+      /**
+       * @category Attribute
+       * @param {string} [alt='Uploaded picture'] - Alternative text for accessibility
+       */
       alt: {
         default: "Uploaded picture"
       },
+      /**
+       * @category Attribute
+       * @param {string} [id] - Image element ID
+       * @private
+       */
       id: { rendered: false },
+      /**
+       * @category Attribute
+       * @param {string} [title] - Image title/tooltip text
+       */
       title: {
         default: null
       },
+      /**
+       * @category Attribute
+       * @param {string} [rId] - Relationship ID for Word export
+       * @private
+       */
       rId: {
         default: null,
         rendered: false
       },
+      /**
+       * @category Attribute
+       * @param {Object} [originalPadding] - Original padding values from Word import
+       * @private
+       */
       originalPadding: {
         default: null,
         rendered: false
       },
+      /**
+       * @category Attribute
+       * @param {Object} [originalAttributes] - Original attributes from Word import
+       * @private
+       */
       originalAttributes: { rendered: false },
+      /**
+       * @category Attribute
+       * @param {boolean} [wrapTopAndBottom] - Wrap text above and below image
+       * @private
+       */
       wrapTopAndBottom: { rendered: false },
+      /**
+       * @category Attribute
+       * @param {Object} [anchorData] - Anchor positioning data for Word
+       * @private
+       */
       anchorData: {
         default: null,
         rendered: false
       },
+      /**
+       * @category Attribute
+       * @param {boolean} [isAnchor] - Whether image is anchored
+       * @private
+       */
       isAnchor: { rendered: false },
+      /**
+       * @category Attribute
+       * @param {boolean} [simplePos] - Simple positioning flag
+       * @private
+       */
       simplePos: { rendered: false },
+      /**
+       * @category Attribute
+       * @param {string} [wrapText] - Text wrapping style
+       * @private
+       */
       wrapText: { rendered: false },
       extension: { rendered: false },
+      /**
+       * @category Attribute
+       * @param {Object} [size] - Image dimensions
+       * @param {number} [size.width] - Width in pixels
+       * @param {number} [size.height] - Height in pixels
+       */
       size: {
         default: {},
         renderDOM: ({ size: size2, extension }) => {
@@ -56994,6 +57192,14 @@ const Image = Node$1.create({
           return { style: style2 };
         }
       },
+      /**
+       * @category Attribute
+       * @param {Object} [padding] - Image padding/margins
+       * @param {number} [padding.left] - Left padding in pixels
+       * @param {number} [padding.top] - Top padding in pixels
+       * @param {number} [padding.bottom] - Bottom padding in pixels
+       * @param {number} [padding.right] - Right padding in pixels
+       */
       padding: {
         default: {},
         renderDOM: ({ padding, marginOffset }) => {
@@ -57006,6 +57212,12 @@ const Image = Node$1.create({
           return { style: style2 };
         }
       },
+      /**
+       * @category Attribute
+       * @param {Object} [marginOffset] - Margin offset for anchored images
+       * @param {number} [marginOffset.left] - Left margin offset
+       * @param {number} [marginOffset.top] - Top margin offset
+       */
       marginOffset: {
         default: {},
         renderDOM: ({ marginOffset, anchorData }) => {
@@ -57021,6 +57233,10 @@ const Image = Node$1.create({
           return { style: style2 };
         }
       },
+      /**
+       * @category Attribute
+       * @param {string} [style] - Custom inline CSS styles
+       */
       style: {
         default: null,
         rendered: true,
@@ -57043,6 +57259,27 @@ const Image = Node$1.create({
   },
   addCommands() {
     return {
+      /**
+       * Insert an image at the current position
+       * @category Command
+       * @param {Object} options - Image attributes
+       * @param {string} options.src - Image source URL or data URI
+       * @param {string} [options.alt] - Alternative text
+       * @param {string} [options.title] - Image title
+       * @param {Object} [options.size] - Image dimensions
+       * @returns {Function} Command function
+       * @example
+       * // Insert an image from a URL
+       * setImage({ src: 'https://example.com/image.jpg' })
+       *
+       * // Insert a base64 encoded image
+       * setImage({
+       *   src: 'data:image/png;base64,...',
+       *   alt: 'Company logo',
+       *   size: { width: 200 }
+       * })
+       * @note Supports URLs, relative paths, and base64 data URIs
+       */
       setImage: (options) => ({ commands: commands2 }) => {
         return commands2.insertContent({
           type: this.name,
@@ -57080,7 +57317,9 @@ const getFileOpener = () => {
 const handleImageUpload = (file) => {
   return new Promise((resolve, reject) => {
     let reader = new FileReader();
-    reader.onload = (event) => resolve(event.target.result);
+    reader.onload = (event) => {
+      resolve(event.target.result);
+    };
     reader.onerror = reject;
     setTimeout(() => reader.readAsDataURL(file), 250);
   });
@@ -57284,8 +57523,8 @@ async function uploadImage({ editor, view, file, size: size2, uploadHandler }) {
     let rId = null;
     if (editor.options.mode === "docx") {
       const [, path] = mediaPath.split("word/");
-      const id2 = addImageRelationship({ editor, path });
-      if (id2) rId = id2;
+      const imageid = addImageRelationship({ editor, path });
+      if (imageid) rId = imageid;
     }
     let imageNode = schema.nodes.image.create({
       src: mediaPath,
@@ -57308,8 +57547,8 @@ function addImageRelationship({ editor, path }) {
   const target = path;
   const type2 = "image";
   try {
-    const id = insertNewRelationship(target, type2, editor);
-    return id;
+    const relationshipId = insertNewRelationship(target, type2, editor);
+    return relationshipId;
   } catch {
     return null;
   }
@@ -58422,6 +58661,17 @@ const BlockNode = Extension.create({
   name: "blockNode",
   addCommands() {
     return {
+      /**
+       * Replace a block node by its ID with new content
+       * @category Command
+       * @param {string} id - The sdBlockId of the node to replace
+       * @param {Object} contentNode - The replacement ProseMirror node
+       * @returns {Function} Command function
+       * @example
+       * const newParagraph = editor.schema.nodes.paragraph.create({}, editor.schema.text('New content'))
+       * replaceBlockNodeById('block-123', newParagraph)
+       * @note The replacement node should have the same type as the original
+       */
       replaceBlockNodeById: (id, contentNode) => ({ dispatch, tr }) => {
         const blockNode = this.editor.helpers.blockNode.getBlockNodeById(id);
         if (!blockNode || blockNode.length > 1) {
@@ -58438,6 +58688,15 @@ const BlockNode = Extension.create({
         }
         return true;
       },
+      /**
+       * Delete a block node by its ID
+       * @category Command
+       * @param {string} id - The sdBlockId of the node to delete
+       * @returns {Function} Command function
+       * @example
+       * deleteBlockNodeById('block-123')
+       * @note Completely removes the node from the document
+       */
       deleteBlockNodeById: (id) => ({ dispatch, tr }) => {
         const blockNode = this.editor.helpers.blockNode.getBlockNodeById(id);
         if (!blockNode || blockNode.length > 1) {
@@ -58454,6 +58713,18 @@ const BlockNode = Extension.create({
         }
         return true;
       },
+      /**
+       * Update attributes of a block node by its ID
+       * @category Command
+       * @param {string} id - The sdBlockId of the node to update
+       * @param {Object} attrs - Attributes to update
+       * @returns {Function} Command function
+       * @example
+       * updateBlockNodeAttributes('block-123', { textAlign: 'center' })
+       * @example
+       * updateBlockNodeAttributes('block-123', { indent: { left: 20 } })
+       * @note Merges new attributes with existing ones
+       */
       updateBlockNodeAttributes: (id, attrs = {}) => ({ dispatch, tr }) => {
         const blockNode = this.editor.helpers.blockNode.getBlockNodeById(id);
         if (!blockNode || blockNode.length > 1) {
@@ -58476,15 +58747,54 @@ const BlockNode = Extension.create({
   },
   addHelpers() {
     return {
+      /**
+       * Get all block nodes in the document
+       * @category Helper
+       * @returns {Array<BlockNodeInfo>} Array of block node info objects
+       * @example
+       * const blocks = editor.helpers.blockNode.getBlockNodes()
+       * console.log(`Found ${blocks.length} block nodes`)
+       */
       getBlockNodes: () => {
         return findChildren(this.editor.state.doc, (node2) => nodeAllowsSdBlockIdAttr(node2));
       },
+      /**
+       * Get a specific block node by its ID
+       * @category Helper
+       * @param {string} id - The sdBlockId to search for
+       * @returns {Array<BlockNodeInfo>} Array containing the matching node (or empty)
+       * @example
+       * const block = editor.helpers.blockNode.getBlockNodeById('block-123')
+       * if (block.length) console.log('Found:', block[0].node.type.name)
+       */
       getBlockNodeById: (id) => {
         return findChildren(this.editor.state.doc, (node2) => node2.attrs.sdBlockId === id);
       },
+      /**
+       * Get all block nodes of a specific type
+       * @category Helper
+       * @param {string} type - The node type name (e.g., 'paragraph', 'heading')
+       * @returns {Array<BlockNodeInfo>} Array of matching block nodes
+       * @example
+       * const paragraphs = editor.helpers.blockNode.getBlockNodesByType('paragraph')
+       * const headings = editor.helpers.blockNode.getBlockNodesByType('heading')
+       */
       getBlockNodesByType: (type2) => {
         return findChildren(this.editor.state.doc, (node2) => node2.type.name === type2);
       },
+      /**
+       * Get all block nodes within a position range
+       * @category Helper
+       * @param {number} from - Start position
+       * @param {number} to - End position
+       * @returns {Array<BlockNodeInfo>} Array of block nodes in the range
+       * @example
+       * const selection = editor.state.selection
+       * const blocksInSelection = editor.helpers.blockNode.getBlockNodesInRange(
+       *   selection.from,
+       *   selection.to
+       * )
+       */
       getBlockNodesInRange: (from2, to) => {
         let blockNodes = [];
         this.editor.state.doc.nodesBetween(from2, to, (node2, pos) => {
@@ -58540,10 +58850,11 @@ const nodeNeedsSdBlockId = (node2) => {
   return !currentId;
 };
 const checkForNewBlockNodesInTrs = (transactions) => {
-  return transactions.some((tr) => {
+  return Array.from(transactions).some((tr) => {
     return tr.steps.some((step) => {
+      if (!(step instanceof ReplaceStep)) return false;
       const hasValidSdBlockNodes = step.slice?.content?.content?.some((node2) => nodeAllowsSdBlockIdAttr(node2));
-      return step instanceof ReplaceStep && hasValidSdBlockNodes;
+      return hasValidSdBlockNodes;
     });
   });
 };
@@ -58572,6 +58883,10 @@ const TextStyle = Mark2.create({
   },
   addAttributes() {
     return {
+      /**
+       * @category Attribute
+       * @param {string} [styleId] - Style identifier for referencing predefined styles
+       */
       styleId: {}
     };
   },
@@ -58580,10 +58895,11 @@ const TextStyle = Mark2.create({
       /**
        * Remove empty text style marks
        * @category Command
-       * @returns {Function} Command - Removes mark if no attributes present
+       * @returns {Function} Command function - Removes mark if no attributes present
        * @example
        * removeEmptyTextStyle()
        * @note Cleanup utility to prevent empty span elements
+       * @note Automatically checks if any style attributes exist before removal
        */
       removeEmptyTextStyle: () => ({ state: state2, commands: commands2 }) => {
         const attributes = Attribute2.getMarkAttributes(state2, this.type);
@@ -59605,12 +59921,16 @@ const TextTransform = Extension.create({
       {
         types: this.options.types,
         attributes: {
+          /**
+           * @category Attribute
+           * @param {string} [textTransform] - Text transform value (uppercase, lowercase, capitalize, none)
+           */
           textTransform: {
             default: null,
             renderDOM: (attrs) => {
-              if (!attrs.textCase) return {};
+              if (!attrs.textTransform) return {};
               return {
-                style: `text-transform: ${attrs.textCase}`
+                style: `text-transform: ${attrs.textTransform}`
               };
             }
           }