browser-commander 0.8.0 → 0.8.1

package/.prettierignore

@@ -1,6 +1,7 @@
 node_modules
 coverage
 dist
+docs-api
 *.min.js
 package-lock.json
 .eslintcache

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.8.1
+
+### Patch Changes
+
+- ffc59e6: Add generated JSDoc API documentation support for the JavaScript package.
+
 ## 0.8.0
 
 ### Minor Changes

package/README.md

@@ -18,6 +18,16 @@ npm install playwright
 npm install puppeteer
 ```
 
+## Documentation
+
+Generate the JavaScript API reference locally with:
+
+```bash
+npm run docs:api
+```
+
+The repository Documentation workflow also combines this JSDoc output with Rust `cargo doc` output for GitHub Pages publishing from `main`.
+
 ## Core Concept: Page State Machine
 
 Browser Commander manages the browser as a state machine with two states:
@@ -290,6 +300,24 @@ await commander.fillTextArea({
 });
 ```
 
+### Keyboard Interactions
+
+```javascript
+import { pressKey, typeText, keyDown, keyUp } from 'browser-commander';
+
+// Press a single key
+await pressKey({ page, engine: 'playwright', key: 'Escape' });
+await pressKey({ page, engine: 'playwright', key: 'Enter' });
+await pressKey({ page, engine: 'playwright', key: 'Tab' });
+
+// Type text
+await typeText({ page, engine: 'playwright', text: 'Hello World' });
+
+// Hold and release modifier keys
+await keyDown({ page, engine: 'playwright', key: 'Control' });
+await keyUp({ page, engine: 'playwright', key: 'Control' });
+```
+
 ### commander.destroy()
 
 ```javascript

package/eslint.config.js

@@ -118,6 +118,7 @@ export default [
       'node_modules/**',
       'coverage/**',
       'dist/**',
+      'docs-api/**',
       '*.min.js',
       '.eslintcache',
     ],

package/jsdoc.json

@@ -0,0 +1,11 @@
+{
+  "source": {
+    "include": ["src"],
+    "includePattern": ".+\\.js$"
+  },
+  "opts": {
+    "destination": "docs-api",
+    "readme": "README.md",
+    "recurse": true
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Universal browser automation library that supports both Playwright and Puppeteer with a unified API",
   "main": "src/index.js",
   "type": "module",
@@ -19,6 +19,7 @@
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
+    "docs:api": "jsdoc -c jsdoc.json",
     "check:duplication": "jscpd .",
     "check": "npm run lint && npm run format:check && npm run check:duplication",
     "prepare": "husky || true",
@@ -69,6 +70,7 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
     "husky": "^9.1.7",
+    "jsdoc": "^4.0.4",
     "jscpd": "^4.0.5",
     "lint-staged": "^16.2.6",
     "playwright": "^1.56.1",

package/src/browser/navigation.js

@@ -220,7 +220,7 @@ export async function waitForUrlStabilization(options = {}) {
  * @param {boolean} options.verify - Whether to verify the navigation (default: true)
  * @param {Function} options.verifyFn - Custom verification function (optional)
  * @param {number} options.verificationTimeout - Verification timeout in ms (default: TIMING.VERIFICATION_TIMEOUT)
- * @returns {Promise<{navigated: boolean, verified: boolean, actualUrl?: string, reason?: string}>}
+ * @returns {Promise<Object>} Navigation result.
  */
 export async function goto(options = {}) {
   const {

package/src/interactions/click.js

@@ -173,7 +173,7 @@ export async function verifyClick(options = {}) {
  * @param {boolean} options.verify - Whether to verify the click operation (default: true)
  * @param {Function} options.verifyFn - Custom verification function (optional)
  * @param {Object} options.adapter - Engine adapter (optional, will be created if not provided)
- * @returns {Promise<{clicked: boolean, verified: boolean, reason?: string}>}
+ * @returns {Promise<Object>} Click result.
  */
 export async function clickElement(options = {}) {
   const {
@@ -352,7 +352,7 @@ async function prepareElement(options = {}) {
  * @param {boolean} options.noAutoScroll - Prevent Playwright's automatic scrolling
  * @param {boolean} options.verify - Whether to verify the click operation
  * @param {Function} options.verifyFn - Custom verification function (optional)
- * @returns {Promise<{clicked: boolean, verified: boolean, reason?: string, navigated: boolean}>}
+ * @returns {Promise<Object>} Click result.
  */
 async function executeClick(options = {}) {
   const {
@@ -567,7 +567,7 @@ async function handleNavigationAfterClick(options = {}) {
  * @param {number} options.timeout - Timeout in ms (default: TIMING.DEFAULT_TIMEOUT)
  * @param {boolean} options.verify - Whether to verify the click operation (default: true)
  * @param {Function} options.verifyFn - Custom verification function (optional)
- * @returns {Promise<{clicked: boolean, navigated: boolean, verified: boolean, reason?: string}>}
+ * @returns {Promise<Object>} Click result.
  *   - clicked: true if click was performed
  *   - navigated: true if click caused navigation
  *   - verified: true if click was verified (navigation counts as verification)

package/src/interactions/fill.js

@@ -146,7 +146,7 @@ export async function checkIfElementEmpty(options = {}) {
  * @param {number} options.verificationTimeout - Verification timeout in ms (default: TIMING.VERIFICATION_TIMEOUT)
  * @param {Function} options.log - Logger instance (optional)
  * @param {Object} options.adapter - Engine adapter (optional, will be created if not provided)
- * @returns {Promise<{filled: boolean, verified: boolean, actualValue?: string}>}
+ * @returns {Promise<Object>} Fill result.
  */
 export async function performFill(options = {}) {
   const {
@@ -240,7 +240,7 @@ export async function performFill(options = {}) {
  * @param {boolean} options.verify - Whether to verify the fill operation (default: true)
  * @param {Function} options.verifyFn - Custom verification function (optional, uses defaultFillVerification if not provided)
  * @param {number} options.verificationTimeout - Verification timeout in ms (default: TIMING.VERIFICATION_TIMEOUT)
- * @returns {Promise<{filled: boolean, verified: boolean, skipped: boolean, actualValue?: string}>}
+ * @returns {Promise<Object>} Fill result.
  *   - filled: true if fill operation was attempted
  *   - verified: true if fill was verified successfully (only meaningful if filled is true)
  *   - skipped: true if element already had content and checkEmpty was true