Merge branch 'develop' into programmatic-text-selection-example

Author: chittolinag

.github/workflows/trigger-docs-update.yml

@@ -0,0 +1,35 @@
+name: Trigger Documentation Update
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      # Trigger when extensions change
+      - 'packages/super-editor/src/extensions/**/*.js'
+      # - 'packages/super-editor/src/core/**/*.js'
+      # - 'packages/super-editor/src/components/**/*.js'
+  workflow_dispatch:  # Manual trigger
+
+jobs:
+  trigger-docs:
+    runs-on: ubuntu-latest    
+    steps:
+      - name: Trigger Documentation Repository Update
+        run: |
+          # Set the required variables
+          repo_owner="Harbour-Enterprises" 
+          repo_name="SuperDoc-Docs"  
+          event_type="docs-update"
+
+          curl -L \
+            -X POST \
+            -H "Accept: application/vnd.github+json" \
+            -H "Authorization: Bearer ${{ secrets.SUPERDOC_PAT }}" \
+            -H "X-GitHub-Api-Version: 2022-11-28" \
+            https://api.github.com/repos/$repo_owner/$repo_name/dispatches \
+            -d "{\"event_type\": \"$event_type\"}"
+      
+      - name: Notify Success
+        if: success()
+        run: echo "✅ Documentation update triggered successfully"

.gitignore

@@ -10,6 +10,7 @@ dist-ssr
 .env
 .npmrc
 .eslintcache
+types/
 
 npm-debug.log*
 yarn-debug.log*

eslint.config.docs.mjs

@@ -0,0 +1,84 @@
+import jsdoc from 'eslint-plugin-jsdoc';
+
+export default [
+  {
+    files: ['packages/super-editor/src/extensions/**/*.js'],
+    plugins: {
+      jsdoc
+    },
+    rules: {
+      // Require minimal JSDoc for extensions
+      'jsdoc/require-jsdoc': ['warn', {
+        publicOnly: true,
+        require: {
+          FunctionDeclaration: false,
+          MethodDefinition: false,
+          ClassDeclaration: false,
+          ArrowFunctionExpression: false,
+          FunctionExpression: false
+        },
+        contexts: [
+          // Document the extension module
+          'ExportNamedDeclaration > VariableDeclaration > VariableDeclarator > CallExpression[callee.property.name="create"]'
+
+          // Note: We document commands/helpers with @param/@returns
+          // inside addCommands/addHelpers, not with require-jsdoc
+        ]
+      }],
+
+      // When JSDoc exists, validate it's correct
+      'jsdoc/require-param': 'error',             // All params must be documented
+      'jsdoc/require-param-type': 'error',        // @param must have {Type}
+      'jsdoc/check-param-names': 'error',         // @param names must match
+      'jsdoc/check-types': 'error',               // Valid type syntax (string not String)
+
+      // Optional - we use @returns {Function} or skip it
+      'jsdoc/require-returns': 'off',
+      'jsdoc/require-returns-type': 'off',
+
+      // Don't require descriptions if obvious
+      'jsdoc/require-param-description': 'off',
+      'jsdoc/require-returns-description': 'off',
+      'jsdoc/require-description': 'off',
+
+      // Don't require examples - nice to have but not essential
+      'jsdoc/require-example': 'off',
+
+      // Simple formatting
+      'jsdoc/require-hyphen-before-param-description': 'off', // Optional: @param {Type} name - Description
+
+      // Allow types from our .d.ts files and common types
+      'jsdoc/no-undefined-types': ['warn', {
+        definedTypes: [
+          // Allow any type that starts with capital letter (likely imported)
+          '/^[A-Z]/',
+
+          // Common utility types
+          'Partial', 'Required', 'Readonly', 'Pick', 'Omit',
+
+          // Built-in types
+          'Function', 'Object', 'Array', 'Promise',
+
+          // DOM
+          'HTMLElement', 'Element', 'Event'
+        ]
+      }],
+
+      // Don't enforce these
+      'jsdoc/valid-types': 'off',                 // We use TypeScript syntax
+      'jsdoc/check-tag-names': 'off',             // Allow @module, @typedef, etc.
+      'jsdoc/check-alignment': 'off',             // Don't worry about alignment
+      'jsdoc/multiline-blocks': 'off'             // Allow single or multi-line
+    },
+    settings: {
+      jsdoc: {
+        mode: 'typescript',      // Understand TypeScript syntax in JSDoc
+        preferredTypes: {
+          object: 'Object',      // Use Object not object
+          array: 'Array',        // Use Array not array
+          'Array.<>': 'Array<>', // Use Array<Type> not Array.<Type>
+        }
+      }
+    }
+  }
+];

package-lock.json

@@ -25,6 +25,8 @@
     "format:check": "prettier --check \"**/*.{js,jsx,vue,css,scss,json,md}\"",
     "lint": "eslint",
     "lint:fix": "eslint --fix",
+    "lint:jsdoc": "eslint packages/super-editor/src/extensions/field-annotation/field-annotation.js --config eslint.config.docs.mjs",
+    "lint:jsdoc:fix": "eslint packages/super-editor/src/extensions/field-annotation/field-annotation.js --config eslint.config.docs.mjs --fix",
     "docs:dev": "vuepress dev docs",
     "docs:build": "vuepress build docs",
     "pack": "npm run build:super-editor && npm --prefix ./packages/superdoc run pack",
@@ -54,6 +56,7 @@
     "@vuepress/theme-default": "^2.0.0-rc.60",
     "eslint": "^9.31.0",
     "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-jsdoc": "^54.1.0",
     "husky": "^9.1.7",
     "lint-staged": "^16.1.4",
     "prettier": "3.3.3",