html-to-gutenberg 4.2.7 → 4.2.9

package/package.json

@@ -1,37 +1,53 @@
 {
   "dependencies": {
-    "@babel/core": "^7.28.5",
+    "@babel/core": "^7.29.0",
     "@babel/preset-react": "^7.28.5",
     "@svgr/core": "^8.1.0",
-    "cheerio": "^1.1.2",
-    "css-scoping": "^1.0.1",
-    "fetch-page-assets": "^1.2.6",
+    "cheerio": "^1.2.0",
+    "css-scoping": "^1.0.5",
+    "dotenv": "^17.3.1",
+    "fetch-page-assets": "^1.2.7",
     "fs": "^0.0.1-security",
-    "html-screenshots": "^1.2.7",
-    "image-to-base64": "^2.2.0",
-    "node-html-to-jsx": "^1.3.7",
+    "node-fetch": "^3.3.2",
+    "node-html-to-jsx": "^1.4.4",
     "path": "^0.12.7"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/babel__core": "^7.20.5",
     "@types/beautify": "^0.0.3",
+    "@types/chai": "^5.2.3",
     "@types/cheerio": "^1.0.0",
     "@types/image-to-base64": "^2.1.2",
+    "@types/mocha": "^10.0.10",
     "@types/prettier": "^3.0.0",
-    "@types/svgo": "^3.0.0"
+    "@types/svgo": "^3.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
+    "chai": "^6.2.2",
+    "coveralls": "^3.1.1",
+    "eslint": "^10.0.2",
+    "mocha": "^11.3.0",
+    "nyc": "^18.0.0",
+    "source-map-support": "^0.5.21",
+    "ts-jest": "^29.4.6",
+    "ts-node": "^10.9.2",
+    "typescript-eslint": "^8.56.1"
   },
-  "type": "module",
   "types": "index.ts",
   "name": "html-to-gutenberg",
-  "version": "4.2.7",
+  "version": "4.2.9",
   "description": "Transform any valid HTML string into fully editable WP Gutenberg blocks in seconds rather than hours.",
   "main": "index.js",
   "directories": {
     "test": "test"
   },
   "scripts": {
-    "test": "jest",
-    "build": "tsc"
+    "postinstall": "mv ./node_modules/fetch-page-assets/index.ts ./node_modules/fetch-page-assets/index.ts.bak || true",
+    "test": "mocha -r ts-node/register index.test.ts",
+    "build": "tsc",
+    "coverage": "nyc mocha -r ts-node/register index.test.ts",
+    "coveralls": "nyc mocha -r ts-node/register index.test.ts && nyc report --reporter=lcov && cat coverage/lcov.info | coveralls"
   },
   "repository": {
     "type": "git",
@@ -55,5 +71,60 @@
   "bugs": {
     "url": "https://github.com/DiogoAngelim/html-to-gutenberg/issues"
   },
-  "homepage": "https://www.html-to-gutenberg.io"
-}
+  "homepage": "https://www.html-to-gutenberg.io",
+  "nyc": {
+    "reporter": [
+      "lcov",
+      "text"
+    ],
+    "exclude": [
+      "coverage"
+    ],
+    "include": [
+      "src/*.ts",
+      "src/**/*.ts"
+    ],
+    "extension": [
+      ".ts",
+      ".js"
+    ],
+    "all": true,
+    "sourceMap": true,
+    "instrument": true,
+    "require": [
+      "ts-node/register"
+    ]
+  },
+  "jest": {
+    "preset": "ts-jest/presets/js-with-ts",
+    "testEnvironment": "node",
+    "extensionsToTreatAsEsm": [
+      ".ts"
+    ],
+    "transform": {
+      "^.+\\.tsx?$": [
+        "ts-jest",
+        {
+          "useESM": true
+        }
+      ]
+    },
+    "globals": {
+      "ts-jest": {
+        "tsconfig": "tsconfig.json",
+        "useESM": true
+      }
+    },
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.js$": "$1"
+    },
+    "collectCoverage": true,
+    "collectCoverageFrom": [
+      "dist/*.js",
+      "!dist/*.test.js"
+    ],
+    "testMatch": [
+      "<rootDir>/dist/*.test.js"
+    ]
+  }
+}

package/readme.md

@@ -1,11 +1,13 @@
-
 # HTML to Gutenberg Converter
 
+<!-- [![Build Status](https://github.com/DiogoAngelim/html-to-gutenberg/actions/workflows/main.yml/badge.svg?cacheBust=1)](https://github.com/DiogoAngelim/html-to-gutenberg/actions)
+[![Coverage Status](https://coveralls.io/repos/github/DiogoAngelim/html-to-gutenberg/badge.svg?branch=main&cacheBust=1)](https://coveralls.io/github/DiogoAngelim/html-to-gutenberg?branch=main) -->
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/DiogoAngelim/html-to-gutenberg/blob/main/LICENSE.MD)
+
   
 
-Convert HTML strings to valid, editable WordPress Gutenberg blocks in seconds instead of hours. With this script, you can create and build valid Gutenberg blocks that feature editable text, forms, inline and background images, as well as SVGs. It includes support for TailwindCSS.
+Convert HTML strings to valid, editable WordPress Gutenberg blocks in seconds instead of hours. With this lib, you can create and build valid Gutenberg blocks that feature editable text, forms, inline and background images, as well as SVGs.
 
-  
 
 ## Features
 
@@ -41,16 +43,25 @@ Since it returns all files as either strings or source files, you can save them
 - 🧰 **Built for automation and customization**
 Can be embedded in custom tools, UIs, or pipelines to generate Gutenberg blocks on demand.
 
-  
-  
+## How it works
 
-## Installation
+This package is actually an alternative when AI fails converting it, which is usually very common.
 
-  
+Most of the logic is just hard-coded patterns. It first converts from plain HTML to Jsx (using the `html-to-jsx` package), which is the supported format of Gutenberg. Then, it follows structured conversion rules that build the WordPress block, which is then validated and parsed using Babel.
 
-Install html-to-gutenberg with npm:
+
+## The Building Process - An Overview
+
+
+Below is a visual overview of the block generation process:
+
+![Block Generation Process](process.png)  
+
+
+## Installation
 
   
+Install html-to-gutenberg with npm:
 
 ```bash
 
@@ -81,19 +92,11 @@ const  htmlString = '<div>My content</div>';
 
   
 
-When provided with a valid HTML string and the required options, the block function will generate the necessary WordPress block files with the specified configuration. To install the block and its assets, simply load the generated folder into the plugins folder and activate it.
 
+When provided with a valid HTML string with the desired options, the block function will generate the necessary WordPress block files with the specified configuration. To install the block and its assets, simply load the generated folder into the plugins folder and activate it as a plugin.
   
 
-## Example
-
-  
-
-[Working demo](https://www.html-to-gutenberg.io/)
-
-  
-
-## Options object reference
+## Options reference
 
 
 | Option              | Description                                                                                                                                           | Type     | Required?                                                                                          | Default            |
@@ -103,13 +106,30 @@ When provided with a valid HTML string and the required options, the block funct
 | prefix              | A namespace prefix for the block name, typically aligned with your project (e.g., "wp" or "myplugins").                                              | string   | No                                                                                                  | wp                |
 | category            | The WordPress block category where the block appears in the editor. Use an existing one or register a custom category if needed.                    | string   | No                                                                                                  | common            |
 | basePath            | The absolute path where the output files and folders will be saved.                                                                                  | string   | No                                                                                                  | Current directory |
-| generateIconPreview | If `true`, generates a static image preview (JPEG) of the block's icon for display in the block picker.                                              | boolean  | No                                                                                                  | false             |
+| generateIconPreview | If you enable the `generateIconPreview` option by setting it to `true`, this package will generate a static image preview of your block using the [SnapAPI](https://snapapi.pics/) screenshot service. You must provide a SnapAPI key in a `.env` file (see below), which will display it a replacement for the block icons in the WP dashboard. | boolean  | No                                                                                                  | false             |
 | shouldSaveFiles     | When `true`, the generated block files are saved directly to disk. When `false`, returns an object containing the file contents as strings instead. | boolean  | No                                                                                                  | true              |
 | jsFiles             | An array of external JavaScript file URLs to enqueue with the block on the editor and the frontend. Useful for adding remote libraries.             | string[] | No                                                                                                  | []                |
 | cssFiles            | An array of external CSS file URLs to enqueue with the block on the editor and the frontend. Useful for adding additional remote stylesheets.        | string[] | No                                                                                                  | []                |
 
 
 
+**Special thanks to [Alex Serebryakov](https://snapapi.pics/) for creating and maintaining SnapAPI!**
+
+
+## Running Tests
+
+To run the test suite, use:
+
+```bash
+cd html-to-gutenberg && npm install
+npm test
+```
+
+This will execute all unit and integration tests using Mocha and Chai. Make sure all dependencies are installed with `npm install` before running tests.
+
+Some tests (such as screenshot preview generation) may require a valid SnapAPI key in your `.env` file.
+
+
 ## License
   
 

package/snapapi-screenshot.test.ts

@@ -0,0 +1,46 @@
+import { expect } from 'chai';
+import block from './index.js';
+import fs from 'fs';
+import path from 'path';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+describe('block screenshot integration', () => {
+  const testHtml = '<html><body><h1>SnapAPI Test</h1></body></html>';
+  const testOptions = {
+    name: 'SnapAPITestBlock',
+    prefix: 'wp',
+    category: 'common',
+    basePath: process.cwd(),
+    shouldSaveFiles: true,
+    generateIconPreview: true,
+    jsFiles: [],
+    cssFiles: [],
+    source: 'https://example.com',
+  };
+  const previewPath = path.join(
+    testOptions.basePath,
+    'snapapitestblock',
+    'preview.jpeg'
+  );
+
+  after(function () {
+    if (fs.existsSync(previewPath)) {
+      fs.unlinkSync(previewPath);
+      // Use fs.rmSync for recursive directory removal in Node >=14
+      const dir = path.dirname(previewPath);
+      if (fs.existsSync(dir)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+      }
+    }
+  });
+
+  it('should generate a preview.jpeg using SnapAPI', async function (this: Mocha.Context) {
+    this.timeout(15000); // Allow time for API call
+    await block(testHtml, testOptions);
+    expect(fs.existsSync(previewPath)).to.equal(true);
+    const stats = fs.statSync(previewPath);
+    expect(stats.size).to.be.greaterThan(1000); // Should not be empty
+  });
+});

package/src/coverage-demo.ts

@@ -0,0 +1,3 @@
+export function add(a: number, b: number): number {
+  return a + b;
+}

package/src/utils-extra.test.ts

@@ -0,0 +1,108 @@
+import { expect } from 'chai';
+import * as utils from '../utils';
+
+describe('hasTailwindCdnSource edge cases', () => {
+  it('returns false for empty array', () => {
+    expect(utils.hasTailwindCdnSource([])).to.equal(false);
+  });
+  it('returns true for multiple tailwind URLs', () => {
+    expect(utils.hasTailwindCdnSource([
+      'https://cdn.tailwindcss.com',
+      'https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4.0.0'
+    ])).to.equal(true);
+  });
+  it('returns false for malformed URLs', () => {
+    expect(utils.hasTailwindCdnSource(['not-a-url'])).to.equal(false);
+  });
+});
+
+describe('replaceSourceUrlVars edge cases', () => {
+  it('replaces matching pattern', () => {
+    const str = "var.url+'http://site.com/path'";
+    const source = 'http://site.com';
+    const expected = "${vars.url}/path";
+    expect(utils.replaceSourceUrlVars(str, source)).to.contain(expected);
+  });
+  it('returns input for empty string', () => {
+    expect(utils.replaceSourceUrlVars('', 'http://site.com')).to.equal('');
+  });
+  it('returns input for null source', () => {
+    expect(utils.replaceSourceUrlVars("var.url+'http://site.com/path'", null)).to.equal("var.url+'http://site.com/path'");
+  });
+  it('replaces multiple matches', () => {
+    const str = "var.url+'http://site.com/a' and var.url+'http://site.com/b'";
+    const source = 'http://site.com';
+    const result = utils.replaceSourceUrlVars(str, source);
+    expect(result.match(/\${vars\.url}/g)?.length).to.be.greaterThanOrEqual(2);
+  });
+});
+
+describe('sanitizeAndReplaceLeadingNumbers edge cases', () => {
+  it('returns input for no numbers', () => {
+    expect(utils.sanitizeAndReplaceLeadingNumbers('test')).to.equal('test');
+  });
+  it('handles multiple leading numbers', () => {
+    expect(utils.sanitizeAndReplaceLeadingNumbers('123abc')).to.match(/one1two2three3abc|123abc/);
+  });
+  it('handles only numbers', () => {
+    expect(utils.sanitizeAndReplaceLeadingNumbers('123')).to.match(/one1two2three3|123/);
+  });
+  it('handles special characters', () => {
+    expect(utils.sanitizeAndReplaceLeadingNumbers('1_test')).to.match(/one1test|1test/);
+  });
+});
+
+describe('replaceUnderscoresSpacesAndUppercaseLetters edge cases', () => {
+  it('handles only underscores', () => {
+    expect(utils.replaceUnderscoresSpacesAndUppercaseLetters('___')).to.equal('---');
+  });
+  it('handles only spaces', () => {
+    expect(utils.replaceUnderscoresSpacesAndUppercaseLetters('   ')).to.equal('---');
+  });
+  it('handles mixed cases', () => {
+    expect(utils.replaceUnderscoresSpacesAndUppercaseLetters('Test_Name Here')).to.equal('test-name-here');
+  });
+  it('handles empty string', () => {
+    expect(utils.replaceUnderscoresSpacesAndUppercaseLetters('')).to.equal('');
+  });
+});
+
+describe('convertDashesSpacesAndUppercaseToUnderscoresAndLowercase edge cases', () => {
+  it('handles only dashes', () => {
+    expect(utils.convertDashesSpacesAndUppercaseToUnderscoresAndLowercase('---')).to.equal('___');
+  });
+  it('handles only spaces', () => {
+    expect(utils.convertDashesSpacesAndUppercaseToUnderscoresAndLowercase('   ')).to.equal('___');
+  });
+  it('handles mixed cases', () => {
+    expect(utils.convertDashesSpacesAndUppercaseToUnderscoresAndLowercase('Test-Name Here')).to.equal('test_name_here');
+  });
+  it('handles empty string', () => {
+    expect(utils.convertDashesSpacesAndUppercaseToUnderscoresAndLowercase('')).to.equal('');
+  });
+});
+
+describe('hasAbsoluteKeyword edge cases', () => {
+  it('detects uppercase', () => {
+    expect(utils.hasAbsoluteKeyword('ABSOLUTE')).to.equal(true);
+  });
+  it('returns false for empty string', () => {
+    expect(utils.hasAbsoluteKeyword('')).to.equal(false);
+  });
+  it('returns false for empty string', () => {
+    expect(utils.hasAbsoluteKeyword('')).to.equal(false);
+  });
+});
+
+describe('generateRandomVariableName edge cases', () => {
+  it('returns prefix only for length 0', () => {
+    expect(utils.generateRandomVariableName('prefix', 0)).to.equal('prefix');
+  });
+  it('returns only random part for empty prefix', () => {
+    expect(utils.generateRandomVariableName('', 3)).to.match(/^[a-z]{3}$/);
+  });
+  it('returns correct length', () => {
+    const result = utils.generateRandomVariableName('pre', 5);
+    expect(result.length).to.equal(8);
+  });
+});

package/src/utils.test.ts

@@ -0,0 +1,36 @@
+import { expect } from 'chai';
+import * as utils from '../utils';
+
+describe('utils.ts functions', () => {
+  it('hasTailwindCdnSource returns true for Tailwind CDN', () => {
+    expect(utils.hasTailwindCdnSource(['https://cdn.tailwindcss.com'])).to.equal(true);
+    expect(utils.hasTailwindCdnSource(['https://example.com'])).to.equal(false);
+  });
+
+  it('replaceSourceUrlVars returns input if no match', () => {
+    const str = "var.url+'http://site.com/path'";
+    const expected = "${vars.url}/path";
+    expect(utils.replaceSourceUrlVars(str, 'http://site.com')).to.equal(expected);
+  });
+
+  it('sanitizeAndReplaceLeadingNumbers replaces leading numbers', () => {
+    expect(utils.sanitizeAndReplaceLeadingNumbers('1test')).to.match(/one1test|1test/);
+  });
+
+  it('replaceUnderscoresSpacesAndUppercaseLetters replaces underscores and spaces', () => {
+    expect(utils.replaceUnderscoresSpacesAndUppercaseLetters('Test_Name Here')).to.equal('test-name-here');
+  });
+
+  it('convertDashesSpacesAndUppercaseToUnderscoresAndLowercase converts correctly', () => {
+    expect(utils.convertDashesSpacesAndUppercaseToUnderscoresAndLowercase('Test-Name Here')).to.equal('test_name_here');
+  });
+
+  it('hasAbsoluteKeyword detects absolute', () => {
+    expect(utils.hasAbsoluteKeyword('absolute')).to.equal(true);
+    expect(utils.hasAbsoluteKeyword('relative')).to.equal(false);
+  });
+
+  it('generateRandomVariableName returns string with prefix', () => {
+    expect(utils.generateRandomVariableName('prefix')).to.match(/^prefix/);
+  });
+});

package/temp-block-test.js

@@ -0,0 +1,19 @@
+import fs from 'fs';
+import block from './index.js';
+
+(async () => {
+  const htmlContent = fs.readFileSync('index.html', 'utf8');
+  const options = {
+    name: 'TempBlockTest',
+    prefix: 'wp',
+    category: 'common',
+    basePath: process.cwd(),
+    shouldSaveFiles: true,
+    generateIconPreview: true,
+    jsFiles: [],
+    cssFiles: [],
+    source: 'https://diogoangelim.github.io/html-to-gutenberg/',
+    };
+  const result = await block(htmlContent, options);
+  console.log('Block generation result:', Object.keys(result));
+})();

package/tsconfig.json

@@ -3,11 +3,17 @@
     "sourceMap": true,
     "outDir": "dist",
     "target": "esnext",
-    "module": "CommonJS",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
     "strict": true,
     "lib": [
       "esnext"
     ],
-    "esModuleInterop": true
-  }
+    "esModuleInterop": true,
+  },
+  "exclude": [
+    "node_modules"
+  ]
 }

package/utils.ts

@@ -0,0 +1,56 @@
+// Utility functions for html-to-gutenberg
+export function hasTailwindCdnSource(jsFiles: string[]): boolean {
+  const tailwindCdnRegex = /https:\/\/(cdn\.tailwindcss\.com(\?[^"'\s]*)?|cdn\.jsdelivr\.net\/npm\/@tailwindcss\/browser@4(\.\d+){0,2})/;
+  return jsFiles.some((url: string) => tailwindCdnRegex.test(url));
+}
+
+export function replaceSourceUrlVars(str: string, source: any): string {
+  if (!source) return str;
+  const escapedSource = String(source).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const pattern = new RegExp(`var\\.url\\+'${escapedSource}([^']*)'`, 'g');
+  if (!pattern.test(str)) return str;
+  return str.replace(pattern, (_match: string, path: string) => `\${vars.url}${path}`);
+}
+
+export function sanitizeAndReplaceLeadingNumbers(str: string): string {
+  const numberWords = ['zero', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine'];
+  let firstNumberReplaced = false;
+  return str
+    .toLowerCase()
+    .replace(/[\s\-_]/g, '')
+    .replace(/\d/g, (digit: string) => {
+      if (!firstNumberReplaced) {
+        firstNumberReplaced = true;
+        return numberWords[parseInt(digit)] + digit;
+      }
+      return digit;
+    })
+    .replace(/^[^a-z]+/, '');
+}
+
+export function replaceUnderscoresSpacesAndUppercaseLetters(name: string = ''): string {
+  return name.replace(new RegExp(/\W|_/, 'g'), '-').toLowerCase();
+}
+
+export function convertDashesSpacesAndUppercaseToUnderscoresAndLowercase(string: string): string {
+  if (string) {
+    return `${string.replaceAll('-', '_').replaceAll(' ', '_').toLowerCase()}`;
+  }
+  return '';
+}
+
+export function hasAbsoluteKeyword(str: string): boolean {
+  if (typeof str !== 'string') return false;
+  return str.toLowerCase().includes('absolute');
+}
+
+export function generateRandomVariableName(prefix: string = 'content', length: number = 3): string {
+  const chars = 'abcdefghijklmnopqrstuvwxyz';
+  let suffix = '';
+  for (let i = 0; i < length; i++) {
+    suffix += chars.charAt(
+      Math.floor(Math.random() * chars.length)
+    );
+  }
+  return `${prefix}${suffix}`;
+}