@jackuait/blok 0.3.1-beta.0 → 0.3.1-beta.3

package/README.md

@@ -44,10 +44,10 @@ Run the codemod to automatically update your codebase:
 
 ```bash
 # Preview changes (recommended first)
-npx @jackuait/blok-codemod ./src --dry-run
+npx blok-codemod ./src --dry-run
 
 # Apply changes
-npx @jackuait/blok-codemod ./src
+npx blok-codemod ./src
 ```
 
 The codemod handles:

package/codemod/README.md

@@ -0,0 +1,177 @@
+# EditorJS to Blok Codemod
+
+Automatically migrate your codebase from EditorJS to Blok.
+
+## Installation & Usage
+
+### Using npx (recommended)
+
+```bash
+# Dry run (preview changes without modifying files)
+npx blok-codemod ./src --dry-run
+
+# Apply changes
+npx blok-codemod ./src
+
+# Process entire project
+npx blok-codemod .
+
+# Verbose output
+npx blok-codemod ./src --verbose
+```
+
+## What It Does
+
+### Import Transformations
+
+```diff
+- import EditorJS from '@editorjs/editorjs';
++ import Blok from '@jackuait/blok';
+
+- import Header from '@editorjs/header';
+- import Paragraph from '@editorjs/paragraph';
++ // Header is now bundled with Blok: use Blok.Header
++ // Paragraph is now bundled with Blok: use Blok.Paragraph
+```
+
+### Type Transformations
+
+```diff
+- import type { EditorConfig } from '@editorjs/editorjs';
++ import type { BlokConfig } from '@jackuait/blok';
+```
+
+### Class Name Transformations
+
+```diff
+- const editor = new EditorJS({ ... });
++ const editor = new Blok({ ... });
+```
+
+### CSS Selector Transformations
+
+```diff
+- .codex-editor { }
++ .blok-editor { }
+
+- .ce-block { }
++ [data-blok-testid="block-wrapper"] { }
+
+- .ce-block--selected { }
++ [data-blok-selected="true"] { }
+
+- .ce-toolbar { }
++ [data-blok-testid="toolbar"] { }
+```
+
+### Data Attribute Transformations
+
+```diff
+- document.querySelector('[data-id="abc123"]');
++ document.querySelector('[data-blok-id="abc123"]');
+
+- document.querySelector('[data-item-name="bold"]');
++ document.querySelector('[data-blok-item-name="bold"]');
+```
+
+### Default Holder Transformation
+
+```diff
+- <div id="editorjs"></div>
++ <div id="blok"></div>
+
+- holder: 'editorjs'
++ holder: 'blok'
+```
+
+### Tool Configuration Transformations
+
+```diff
+tools: {
+-   header: Header,
+-   paragraph: Paragraph,
++   header: Blok.Header,
++   paragraph: Blok.Paragraph,
+}
+```
+
+### package.json Updates
+
+```diff
+{
+  "dependencies": {
+-   "@editorjs/editorjs": "^2.28.0",
+-   "@editorjs/header": "^2.8.0",
+-   "@editorjs/paragraph": "^2.11.0",
++   "@jackuait/blok": "latest"
+  }
+}
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Preview changes without modifying files |
+| `--verbose` | Show detailed output for each file |
+| `--help` | Show help message |
+
+## Supported File Types
+
+- JavaScript: `.js`, `.jsx`
+- TypeScript: `.ts`, `.tsx`
+- Vue: `.vue`
+- Svelte: `.svelte`
+- HTML: `.html`
+- CSS: `.css`, `.scss`, `.less`
+
+## After Migration
+
+1. **Install dependencies**: Run `npm install` or `yarn` to update your dependencies
+
+2. **Review changes**: The codemod handles most common patterns, but review the changes for:
+   - Custom tool implementations
+   - Complex selector patterns
+   - Dynamic string construction
+
+3. **Update custom tools**: If you have custom tools, ensure they follow Blok's API:
+   - Lifecycle hooks: `rendered()`, `updated()`, `removed()`, `moved()`
+   - Use `data-blok-*` attributes
+
+4. **Test thoroughly**: Run your test suite and manually verify the editor works correctly
+
+5. **Check MIGRATION.md**: See the full [migration guide](../MIGRATION.md) for manual updates
+
+## Programmatic Usage
+
+```javascript
+// If you've cloned the blok repository
+const {
+  transformFile,
+  updatePackageJson,
+  applyTransforms,
+} = require('./codemod/migrate-editorjs-to-blok');
+
+// Transform a single file
+const result = transformFile('/path/to/file.ts', false);
+console.log(result.changes);
+
+// Update package.json
+const pkgResult = updatePackageJson('/path/to/package.json', false);
+console.log(pkgResult.changes);
+```
+
+## Known Limitations
+
+- Does not handle dynamic imports with variable paths
+- Complex nested selectors may need manual adjustment
+- Custom EditorJS plugins need manual migration
+- String templates with EditorJS references need manual review
+
+## Contributing
+
+Found a pattern that should be transformed? Open an issue or PR on the [Blok repository](https://github.com/jackuait/blok).
+
+## License
+
+Apache-2.0

package/codemod/migrate-editorjs-to-blok.js

@@ -0,0 +1,496 @@
+#!/usr/bin/env node
+
+/**
+ * EditorJS to Blok Codemod
+ *
+ * This script automates the migration from EditorJS to Blok.
+ * It transforms imports, class names, selectors, data attributes, and text references.
+ *
+ * Usage:
+ *   npx blok-codemod [path] [options]
+ *
+ * Options:
+ *   --dry-run    Show changes without modifying files
+ *   --verbose    Show detailed output
+ *   --help       Show help
+ *
+ * Examples:
+ *   npx blok-codemod ./src
+ *   npx blok-codemod ./src --dry-run
+ *   npx blok-codemod .
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+const FILE_EXTENSIONS = ['.js', '.jsx', '.ts', '.tsx', '.vue', '.svelte', '.html', '.css', '.scss', '.less'];
+
+// Import transformations
+const IMPORT_TRANSFORMS = [
+  // Main EditorJS import
+  {
+    pattern: /from\s+['"]@editorjs\/editorjs['"]/g,
+    replacement: "from '@jackuait/blok'",
+  },
+  {
+    pattern: /require\s*\(\s*['"]@editorjs\/editorjs['"]\s*\)/g,
+    replacement: "require('@jackuait/blok')",
+  },
+  // Header tool (now bundled)
+  {
+    pattern: /import\s+(\w+)\s+from\s+['"]@editorjs\/header['"];?\n?/g,
+    replacement: '// Header is now bundled with Blok: use Blok.Header\n',
+    note: 'Header tool is now bundled',
+  },
+  // Paragraph tool (now bundled)
+  {
+    pattern: /import\s+(\w+)\s+from\s+['"]@editorjs\/paragraph['"];?\n?/g,
+    replacement: '// Paragraph is now bundled with Blok: use Blok.Paragraph\n',
+    note: 'Paragraph tool is now bundled',
+  },
+];
+
+// Type import transformations (order matters - more specific patterns first)
+const TYPE_TRANSFORMS = [
+  { pattern: /EditorJS\.EditorConfig/g, replacement: 'BlokConfig' },
+  { pattern: /EditorConfig/g, replacement: 'BlokConfig' },
+];
+
+// Class name transformations
+const CLASS_NAME_TRANSFORMS = [
+  // Constructor
+  { pattern: /new\s+EditorJS\s*\(/g, replacement: 'new Blok(' },
+  // Type annotations
+  { pattern: /:\s*EditorJS(?![a-zA-Z])/g, replacement: ': Blok' },
+  // Generic type parameters
+  { pattern: /<EditorJS>/g, replacement: '<Blok>' },
+];
+
+// CSS class transformations
+const CSS_CLASS_TRANSFORMS = [
+  // Editor wrapper classes
+  { pattern: /\.codex-editor(?![\w-])/g, replacement: '.blok-editor' },
+  { pattern: /\.codex-editor--narrow/g, replacement: '.blok-editor--narrow' },
+  { pattern: /\.codex-editor--rtl/g, replacement: '.blok-editor--rtl' },
+  // CE prefix classes (commonly used)
+  { pattern: /\.ce-block(?![\w-])/g, replacement: '[data-blok-testid="block-wrapper"]' },
+  { pattern: /\.ce-block--selected/g, replacement: '[data-blok-selected="true"]' },
+  { pattern: /\.ce-block--stretched/g, replacement: '[data-blok-stretched="true"]' },
+  { pattern: /\.ce-block__content/g, replacement: '[data-blok-testid="block-content"]' },
+  { pattern: /\.ce-toolbar(?![\w-])/g, replacement: '[data-blok-testid="toolbar"]' },
+  { pattern: /\.ce-toolbar__plus/g, replacement: '[data-blok-testid="plus-button"]' },
+  { pattern: /\.ce-toolbar__settings-btn/g, replacement: '[data-blok-testid="settings-toggler"]' },
+  { pattern: /\.ce-toolbar__actions/g, replacement: '[data-blok-testid="toolbar-actions"]' },
+  { pattern: /\.ce-inline-toolbar/g, replacement: '[data-blok-testid="inline-toolbar"]' },
+  { pattern: /\.ce-popover(?![\w-])/g, replacement: '[data-blok-testid="popover-container"]' },
+  { pattern: /\.ce-popover-item/g, replacement: '[data-blok-testid="popover-item"]' },
+];
+
+// Data attribute transformations
+const DATA_ATTRIBUTE_TRANSFORMS = [
+  // Core data attributes
+  { pattern: /data-id(?=["'\]=\s\]])/g, replacement: 'data-blok-id' },
+  { pattern: /data-item-name/g, replacement: 'data-blok-item-name' },
+  { pattern: /data-empty/g, replacement: 'data-blok-empty' },
+  // Cypress/test selectors
+  { pattern: /\[data-cy=["']?editorjs["']?\]/g, replacement: '[data-blok-testid="blok-editor"]' },
+  { pattern: /data-cy=["']?editorjs["']?/g, replacement: 'data-blok-testid="blok-editor"' },
+];
+
+// Selector transformations for JavaScript/TypeScript query strings
+const SELECTOR_TRANSFORMS = [
+  // querySelector patterns
+  { pattern: /\[data-id=/g, replacement: '[data-blok-id=' },
+  { pattern: /\[data-item-name=/g, replacement: '[data-blok-item-name=' },
+  { pattern: /\[data-empty\]/g, replacement: '[data-blok-empty]' },
+  { pattern: /\[data-empty=/g, replacement: '[data-blok-empty=' },
+];
+
+// Default holder transformation
+const HOLDER_TRANSFORMS = [
+  // HTML id attribute
+  { pattern: /id=["']editorjs["']/g, replacement: 'id="blok"' },
+  // JavaScript string literals for holder
+  { pattern: /holder:\s*['"]editorjs['"]/g, replacement: "holder: 'blok'" },
+  { pattern: /getElementById\s*\(\s*['"]editorjs['"]\s*\)/g, replacement: "getElementById('blok')" },
+];
+
+// Tool configuration transformations
+const TOOL_CONFIG_TRANSFORMS = [
+  // Handle class property syntax
+  { pattern: /class:\s*Header(?!Config)/g, replacement: 'class: Blok.Header' },
+  { pattern: /class:\s*Paragraph(?!Config)/g, replacement: 'class: Blok.Paragraph' },
+  // Handle standalone tool references in tools config (e.g., `paragraph: Paragraph`)
+  { pattern: /(\bheader\s*:\s*)Header(?!Config)(?=\s*[,}\n])/g, replacement: '$1Blok.Header' },
+  { pattern: /(\bparagraph\s*:\s*)Paragraph(?!Config)(?=\s*[,}\n])/g, replacement: '$1Blok.Paragraph' },
+];
+
+// Text transformations for "EditorJS" string references
+const TEXT_TRANSFORMS = [
+  // Replace exact "EditorJS" text (preserves case-sensitive matching)
+  { pattern: /EditorJS(?![a-zA-Z])/g, replacement: 'Blok' },
+  // Replace #editorjs with #blok (e.g., in CSS ID selectors or anchor links)
+  { pattern: /#editorjs(?![a-zA-Z0-9_-])/g, replacement: '#blok' },
+];
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+function log(message, verbose = false) {
+  if (verbose || !global.isVerbose) {
+    console.log(message);
+  }
+}
+
+function logVerbose(message) {
+  if (global.isVerbose) {
+    console.log(`  ${message}`);
+  }
+}
+
+function getAllFiles(dirPath, arrayOfFiles = []) {
+  const files = fs.readdirSync(dirPath);
+
+  files.forEach((file) => {
+    const fullPath = path.join(dirPath, file);
+
+    // Skip node_modules, dist, and hidden directories
+    if (file === 'node_modules' || file === 'dist' || file === 'build' || file.startsWith('.')) {
+      return;
+    }
+
+    if (fs.statSync(fullPath).isDirectory()) {
+      getAllFiles(fullPath, arrayOfFiles);
+    } else {
+      const ext = path.extname(file).toLowerCase();
+      if (FILE_EXTENSIONS.includes(ext)) {
+        arrayOfFiles.push(fullPath);
+      }
+    }
+  });
+
+  return arrayOfFiles;
+}
+
+function applyTransforms(content, transforms, fileName) {
+  let result = content;
+  const changes = [];
+
+  transforms.forEach(({ pattern, replacement, note }) => {
+    const matches = result.match(pattern);
+    if (matches) {
+      changes.push({
+        pattern: pattern.toString(),
+        count: matches.length,
+        note,
+      });
+      result = result.replace(pattern, replacement);
+    }
+  });
+
+  return { result, changes };
+}
+
+function transformFile(filePath, dryRun = false) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  let transformed = content;
+  const allChanges = [];
+
+  const ext = path.extname(filePath).toLowerCase();
+  const isStyleFile = ['.css', '.scss', '.less'].includes(ext);
+  const isHtmlFile = ext === '.html';
+  const isJsFile = ['.js', '.jsx', '.ts', '.tsx', '.vue', '.svelte'].includes(ext);
+
+  // Apply import transforms (JS/TS only)
+  if (isJsFile) {
+    const { result, changes } = applyTransforms(transformed, IMPORT_TRANSFORMS, filePath);
+    transformed = result;
+    allChanges.push(...changes.map((c) => ({ ...c, category: 'imports' })));
+  }
+
+  // Apply type transforms (JS/TS only)
+  if (isJsFile) {
+    const { result, changes } = applyTransforms(transformed, TYPE_TRANSFORMS, filePath);
+    transformed = result;
+    allChanges.push(...changes.map((c) => ({ ...c, category: 'types' })));
+  }
+
+  // Apply class name transforms (JS/TS only)
+  if (isJsFile) {
+    const { result, changes } = applyTransforms(transformed, CLASS_NAME_TRANSFORMS, filePath);
+    transformed = result;
+    allChanges.push(...changes.map((c) => ({ ...c, category: 'class-names' })));
+  }
+
+  // Apply CSS class transforms (all files)
+  {
+    const { result, changes } = applyTransforms(transformed, CSS_CLASS_TRANSFORMS, filePath);
+    transformed = result;
+    allChanges.push(...changes.map((c) => ({ ...c, category: 'css-classes' })));
+  }
+
+  // Apply data attribute transforms (JS/TS/HTML)
+  if (isJsFile || isHtmlFile) {
+    const { result, changes } = applyTransforms(transformed, DATA_ATTRIBUTE_TRANSFORMS, filePath);
+    transformed = result;
+    allChanges.push(...changes.map((c) => ({ ...c, category: 'data-attributes' })));
+  }
+
+  // Apply selector transforms (JS/TS)
+  if (isJsFile) {
+    const { result, changes } = applyTransforms(transformed, SELECTOR_TRANSFORMS, filePath);
+    transformed = result;
+    allChanges.push(...changes.map((c) => ({ ...c, category: 'selectors' })));
+  }
+
+  // Apply holder transforms (JS/TS/HTML)
+  if (isJsFile || isHtmlFile) {
+    const { result, changes } = applyTransforms(transformed, HOLDER_TRANSFORMS, filePath);
+    transformed = result;
+    allChanges.push(...changes.map((c) => ({ ...c, category: 'holder' })));
+  }
+
+  // Apply tool config transforms (JS/TS only)
+  if (isJsFile) {
+    const { result, changes } = applyTransforms(transformed, TOOL_CONFIG_TRANSFORMS, filePath);
+    transformed = result;
+    allChanges.push(...changes.map((c) => ({ ...c, category: 'tool-config' })));
+  }
+
+  // Apply text transforms (JS/TS/HTML) - replace "EditorJS" with "Blok"
+  if (isJsFile || isHtmlFile) {
+    const { result, changes } = applyTransforms(transformed, TEXT_TRANSFORMS, filePath);
+    transformed = result;
+    allChanges.push(...changes.map((c) => ({ ...c, category: 'text' })));
+  }
+
+  const hasChanges = transformed !== content;
+
+  if (hasChanges && !dryRun) {
+    fs.writeFileSync(filePath, transformed, 'utf8');
+  }
+
+  return {
+    filePath,
+    hasChanges,
+    changes: allChanges,
+  };
+}
+
+function updatePackageJson(packageJsonPath, dryRun = false) {
+  if (!fs.existsSync(packageJsonPath)) {
+    return { hasChanges: false, changes: [] };
+  }
+
+  const content = fs.readFileSync(packageJsonPath, 'utf8');
+  const pkg = JSON.parse(content);
+  const changes = [];
+
+  // Track dependencies to remove
+  const depsToRemove = ['@editorjs/editorjs', '@editorjs/header', '@editorjs/paragraph'];
+  const devDepsToRemove = [...depsToRemove];
+
+  // Check and update dependencies
+  if (pkg.dependencies) {
+    depsToRemove.forEach((dep) => {
+      if (pkg.dependencies[dep]) {
+        changes.push({ action: 'remove', type: 'dependencies', package: dep });
+        delete pkg.dependencies[dep];
+      }
+    });
+
+    // Add @jackuait/blok if not present
+    if (!pkg.dependencies['@jackuait/blok']) {
+      changes.push({ action: 'add', type: 'dependencies', package: '@jackuait/blok' });
+      pkg.dependencies['@jackuait/blok'] = 'latest';
+    }
+  }
+
+  // Check and update devDependencies
+  if (pkg.devDependencies) {
+    devDepsToRemove.forEach((dep) => {
+      if (pkg.devDependencies[dep]) {
+        changes.push({ action: 'remove', type: 'devDependencies', package: dep });
+        delete pkg.devDependencies[dep];
+      }
+    });
+  }
+
+  const hasChanges = changes.length > 0;
+
+  if (hasChanges && !dryRun) {
+    fs.writeFileSync(packageJsonPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+  }
+
+  return { hasChanges, changes };
+}
+
+// ============================================================================
+// Main Execution
+// ============================================================================
+
+function printHelp() {
+  console.log(`
+EditorJS to Blok Codemod
+
+Usage:
+  npx blok-codemod [path] [options]
+
+Arguments:
+  path          Directory or file to transform (default: current directory)
+
+Options:
+  --dry-run     Show changes without modifying files
+  --verbose     Show detailed output for each file
+  --help        Show this help message
+
+Examples:
+  npx blok-codemod ./src
+  npx blok-codemod ./src --dry-run
+  npx blok-codemod . --verbose
+
+What this codemod does:
+  • Transforms EditorJS imports to Blok imports
+  • Updates type names (EditorConfig → BlokConfig)
+  • Replaces 'new EditorJS()' with 'new Blok()'
+  • Converts CSS selectors (.ce-* → [data-blok-*])
+  • Updates data attributes (data-id → data-blok-id)
+  • Changes default holder from 'editorjs' to 'blok'
+  • Updates package.json dependencies
+  • Converts bundled tool imports (Header, Paragraph)
+
+Note: After running, you may need to manually:
+  • Update any custom tool implementations
+  • Review and test the changes
+  • Run 'npm install' or 'yarn' to update dependencies
+`);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+
+  // Parse arguments
+  const dryRun = args.includes('--dry-run');
+  const verbose = args.includes('--verbose');
+  const help = args.includes('--help') || args.includes('-h');
+
+  global.isVerbose = verbose;
+
+  if (help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  // Get target path
+  const targetPath = args.find((arg) => !arg.startsWith('--')) || '.';
+  const absolutePath = path.resolve(targetPath);
+
+  if (!fs.existsSync(absolutePath)) {
+    console.error(`Error: Path does not exist: ${absolutePath}`);
+    process.exit(1);
+  }
+
+  console.log('\n🔄 EditorJS to Blok Migration\n');
+  console.log(`📁 Target: ${absolutePath}`);
+  console.log(`🔍 Mode: ${dryRun ? 'Dry run (no changes will be made)' : 'Live'}\n`);
+
+  const stats = {
+    filesScanned: 0,
+    filesModified: 0,
+    totalChanges: 0,
+  };
+
+  // Get all files to process
+  let files = [];
+  if (fs.statSync(absolutePath).isDirectory()) {
+    files = getAllFiles(absolutePath);
+  } else {
+    files = [absolutePath];
+  }
+
+  stats.filesScanned = files.length;
+
+  console.log(`📝 Scanning ${files.length} files...\n`);
+
+  // Process each file
+  files.forEach((filePath) => {
+    const result = transformFile(filePath, dryRun);
+
+    if (result.hasChanges) {
+      stats.filesModified++;
+      stats.totalChanges += result.changes.length;
+
+      const relativePath = path.relative(absolutePath, filePath);
+      console.log(`✏️  ${relativePath}`);
+
+      if (verbose) {
+        result.changes.forEach((change) => {
+          console.log(`    - [${change.category}] ${change.count} occurrence(s)`);
+          if (change.note) {
+            console.log(`      Note: ${change.note}`);
+          }
+        });
+      }
+    }
+  });
+
+  // Process package.json
+  const packageJsonPath = path.join(
+    fs.statSync(absolutePath).isDirectory() ? absolutePath : path.dirname(absolutePath),
+    'package.json'
+  );
+
+  const pkgResult = updatePackageJson(packageJsonPath, dryRun);
+  if (pkgResult.hasChanges) {
+    console.log(`\n📦 package.json updates:`);
+    pkgResult.changes.forEach((change) => {
+      const symbol = change.action === 'add' ? '+' : '-';
+      console.log(`    ${symbol} ${change.package} (${change.type})`);
+    });
+  }
+
+  // Print summary
+  console.log('\n' + '─'.repeat(50));
+  console.log('\n📊 Summary:\n');
+  console.log(`   Files scanned:  ${stats.filesScanned}`);
+  console.log(`   Files modified: ${stats.filesModified}`);
+  console.log(`   Total changes:  ${stats.totalChanges}`);
+
+  if (dryRun) {
+    console.log('\n⚠️  Dry run complete. No files were modified.');
+    console.log('   Run without --dry-run to apply changes.\n');
+  } else {
+    console.log('\n✅ Migration complete!\n');
+    console.log('📋 Next steps:');
+    console.log('   1. Run `npm install` or `yarn` to update dependencies');
+    console.log('   2. Review the changes in your codebase');
+    console.log('   3. Test your application thoroughly');
+    console.log('   4. Check MIGRATION.md for any manual updates needed\n');
+  }
+}
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}
+
+// Export for testing
+module.exports = {
+  transformFile,
+  updatePackageJson,
+  applyTransforms,
+  IMPORT_TRANSFORMS,
+  TYPE_TRANSFORMS,
+  CLASS_NAME_TRANSFORMS,
+  CSS_CLASS_TRANSFORMS,
+  DATA_ATTRIBUTE_TRANSFORMS,
+  SELECTOR_TRANSFORMS,
+  HOLDER_TRANSFORMS,
+  TOOL_CONFIG_TRANSFORMS,
+  TEXT_TRANSFORMS,
+};