refactor: enhance documentation for section attributes and commands in DocumentSection (#805)

Author: caio-pizzol

packages/super-editor/src/extensions/structured-content/document-section.js

@@ -1,34 +1,34 @@
 // @ts-check
 
 /**
- * Base section attributes
+ * Document section attributes
  * @typedef {Object} SectionAttributes
- * @property {number} [id] - Section identifier
- * @property {string} [title] - Section title
- * @property {string} [description] - Section description
- * @property {string} [sectionType] - Type of section
- * @property {boolean} [isLocked] - Whether section is locked
+ * @property {number} [id] - Unique section identifier
+ * @property {string} [title] - Display label (becomes w:alias in Word)
+ * @property {string} [description] - Additional metadata stored in w:tag
+ * @property {string} [sectionType] - Business type for filtering/logic (e.g., 'legal', 'pricing')
+ * @property {boolean} [isLocked] - Lock state (maps to w:lock="sdtContentLocked")
  */
 
 /**
- * Options for creating a section
+ * Create a new document section
  * @typedef {Object} SectionCreate
- * @property {number} [id] - Section identifier (auto-generated if not provided)
- * @property {string} [title] - Section title (defaults to "Document section")
- * @property {string} [description] - Section description
- * @property {string} [sectionType] - Type of section
- * @property {boolean} [isLocked] - Whether section is locked
- * @property {string} [html] - HTML content to parse
- * @property {Object} [json] - ProseMirror JSON content (takes precedence over html)
+ * @property {number} [id] - Unique ID. Auto-increments from existing sections if omitted
+ * @property {string} [title="Document section"] - Label shown in section header
+ * @property {string} [description] - Metadata for tracking (stored in Word's w:tag)
+ * @property {string} [sectionType] - Business classification
+ * @property {boolean} [isLocked=false] - Prevent editing when true
+ * @property {string} [html] - HTML content to insert
+ * @property {Object} [json] - ProseMirror JSON (overrides html if both provided)
  */
 
 /**
- * Options for updating a section
+ * Update an existing section
  * @typedef {Object} SectionUpdate
- * @property {number} id - Section ID to update (required)
- * @property {string} [html] - HTML content to parse
- * @property {Object} [json] - ProseMirror JSON content (takes precedence over html)
- * @property {Partial<SectionAttributes>} [attrs] - Attributes to update
+ * @property {number} id - Target section ID (required)
+ * @property {string} [html] - Replace content with HTML
+ * @property {Object} [json] - Replace content with ProseMirror JSON (overrides html)
+ * @property {Partial<SectionAttributes>} [attrs] - Update attributes only (preserves content)
  */
 
 import { Node, Attribute } from '@core/index.js';
@@ -39,8 +39,9 @@ import { DOMParser as PMDOMParser } from 'prosemirror-model';
 import { findParentNode, SectionHelpers } from '@helpers/index.js';
 
 /**
- * Document Section - Structured content blocks
  * @module DocumentSection
+ * @sidebarTitle Document Section
+ * @snippetPath /snippets/extensions/document-section.mdx
  */
 export const DocumentSection = Node.create({
   name: 'documentSection',
@@ -98,10 +99,17 @@ export const DocumentSection = Node.create({
   addCommands() {
     return {
       /**
-       * Create a new document section
+       * Create a lockable content section
        * @category Command
-       * @param {SectionCreate} [options={}]
-       * @returns {Function} Command function - returns true if section was created successfully
+       * @param {SectionCreate} [options={}] - Section configuration
+       * @returns {Function} Command - true if created, false if position invalid
+       * @example
+       * createDocumentSection({
+       *   id: 'legal-1',
+       *   title: 'Terms & Conditions',
+       *   isLocked: true,
+       *   html: '<p>Legal content...</p>'
+       * })
        */
       createDocumentSection:
         (options = {}) =>
@@ -214,9 +222,12 @@ export const DocumentSection = Node.create({
         },
 
       /**
-       * Remove section at current selection, keeping content
+       * Remove section wrapper at cursor, preserving its content
        * @category Command
-       * @returns {Function} Command function - returns true if section was removed, false if none found
+       * @returns {Function} Command - true if removed, false if no section at position
+       * @example
+       * removeSectionAtSelection()
+       * @note Content stays in document, only section wrapper is removed
        */
       removeSectionAtSelection:
         () =>
@@ -254,10 +265,12 @@ export const DocumentSection = Node.create({
         },
 
       /**
-       * Remove section by ID
+       * Delete section and all its content
        * @category Command
-       * @param {number} id - Section ID to remove
-       * @returns {Function} Command function - returns true if section was removed, false if not found
+       * @param {number} id - Section to delete
+       * @returns {Function} Command - true if deleted, false if ID doesn't exist
+       * @example
+       * removeSectionById(123)
        */
       removeSectionById:
         (id) =>
@@ -282,11 +295,12 @@ export const DocumentSection = Node.create({
         },
 
       /**
-       * Lock section by ID
+       * Lock section against edits
        * @category Command
-       * @param {number} id - Section ID to lock
-       * @returns {Function} Command function - returns true if section was locked, false if not found
-       * @private
+       * @param {number} id - Section to lock
+       * @returns {Function} Command - true if locked, false if ID doesn't exist
+       * @example
+       * lockSectionById(123)
        */
       lockSectionById:
         (id) =>
@@ -306,10 +320,23 @@ export const DocumentSection = Node.create({
         },
 
       /**
-       * Update section by ID
+       * Modify section attributes or content
        * @category Command
-       * @param {SectionUpdate} options
-       * @returns {Function} Command function - returns true if section was updated, false if not found
+       * @param {SectionUpdate} options - Changes to apply
+       * @returns {Function} Command - true if updated, false if ID doesn't exist
+       * @example
+       * // Toggle lock
+       * updateSectionById({ id: 123, attrs: { isLocked: false } })
+       *
+       * // Replace content
+       * updateSectionById({ id: 123, html: '<p>New content</p>' })
+       *
+       * // Both
+       * updateSectionById({
+       *   id: 123,
+       *   html: '<p>Updated</p>',
+       *   attrs: { title: 'New Title' }
+       * })
        */
       updateSectionById:
         ({ id, html, json, attrs }) =>