@jackuait/blok 0.4.1-beta.5 → 0.4.1-beta.6

package/README.md

@@ -34,36 +34,155 @@ or
 yarn add @jackuait/blok
 ```
 
-## Migrating from EditorJS
+## Quick Start
+
+Blok uses a modular architecture for optimal bundle size. Import tools separately from the core:
+
+```typescript
+import { Blok } from '@jackuait/blok';
+import { Header, Paragraph, List, Bold, Italic, Link } from '@jackuait/blok/tools';
+
+const editor = new Blok({
+  holder: 'editor',
+  tools: {
+    header: Header,
+    paragraph: { class: Paragraph, inlineToolbar: true },
+    list: { class: List, inlineToolbar: true },
+  },
+  inlineTools: {
+    bold: Bold,
+    italic: Italic,
+    link: Link,
+  },
+});
+
+// Save content as JSON
+const data = await editor.save();
+```
+
+### Entry Points
+
+| Entry Point | Description |
+|-------------|-------------|
+| `@jackuait/blok` | Core editor (no tools included) |
+| `@jackuait/blok/tools` | Built-in tools: Header, Paragraph, List, Bold, Italic, Link, Convert |
+| `@jackuait/blok/locales` | Locale loading utilities |
 
-If you're migrating from EditorJS, Blok provides a seamless transition path:
+This modular approach means you only bundle the tools you use, resulting in smaller bundles for your users.
 
-### Automated Migration
+## Migrating from EditorJS
+
+Blok is designed as a drop-in replacement for EditorJS. The included codemod automatically transforms your imports, selectors, and configuration—so you can switch over in minutes, not hours.
 
-Run the codemod to automatically update your codebase:
+### Quick Start
 
 ```bash
-# Preview changes (recommended first)
+# 1. Preview what will change (recommended first)
 npx -p @jackuait/blok migrate-from-editorjs ./src --dry-run
 
-# Apply changes
+# 2. Apply the changes
 npx -p @jackuait/blok migrate-from-editorjs ./src
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Preview changes without modifying files |
+| `--verbose` | Show detailed output for each file processed |
+| `--use-library-i18n` | Use Blok's built-in translations (36 languages) instead of custom i18n |
+
+### Supported Files
+
+The codemod processes: `.js`, `.jsx`, `.ts`, `.tsx`, `.vue`, `.svelte`, `.html`, `.css`, `.scss`, `.less`
+
+### What Gets Transformed
+
+- **Imports** — `@editorjs/editorjs` → `@jackuait/blok`
+- **Tool imports** — `@editorjs/header` → `@jackuait/blok/tools`
+- **Types** — `EditorConfig` → `BlokConfig`
+- **CSS selectors** — `.ce-block`, `.ce-toolbar` → `[data-blok-*]` attributes
+- **Data attributes** — `data-id` → `data-blok-id`
+- **Default holder** — `#editorjs` → `#blok`
+
+The codemod also handles **existing Blok users** upgrading to the modular architecture:
+- Splits combined imports: `{ Blok, Header }` from `@jackuait/blok` → separate imports
+- Updates static property access: `Blok.Header` → `Header`
+
+### Limitations
 
-# Process the entire project
-npx -p @jackuait/blok migrate-from-editorjs .
+Some patterns require manual attention:
+- Dynamic imports with variable paths
+- Complex nested CSS selectors
+- Custom EditorJS plugins (need API adaptation)
+
+### Learn More
+
+- [MIGRATION.md](./MIGRATION.md) — Full list of breaking changes and manual steps
+- [codemod/README.md](./codemod/README.md) — Programmatic usage and detailed examples
+
+## Localization
+
+Blok supports 68 languages with lazy loading—only English is bundled by default (~3KB). Additional locales are loaded on-demand, keeping your initial bundle small.
+
+### Default Behavior
+
+Out of the box, Blok uses English and auto-detects the user's browser language:
+
+```typescript
+import { Blok } from '@jackuait/blok';
+
+new Blok({
+  holder: 'editor',
+  // Uses English by default, auto-detects browser language
+});
 ```
 
-The codemod handles:
-- Import updates (`@editorjs/editorjs` → `@jackuait/blok`)
-- Type renames (`EditorConfig` → `BlokConfig`)
-- CSS selector updates (`.ce-*` → `[data-blok-*]`)
-- Data attribute updates (`data-id` → `data-blok-id`)
-- Bundled tool migrations (Header & Paragraph are now included)
 
-### Migration Guide
+### Preloading Locales
 
-For a complete list of breaking changes and manual migration steps, see [MIGRATION.md](./MIGRATION.md).
+By default, locales are loaded on-demand. If you need to ensure locales are available before initializing the editor—for example, to avoid any loading delay or to support offline usage—you can preload them:
+
+```typescript
+import { Blok } from '@jackuait/blok';
+import { preloadLocales, buildRegistry } from '@jackuait/blok/locales';
+
+// Preload during app startup (triggers network requests and caches the locales)
+await preloadLocales(['en', 'fr', 'de']);
+
+// Build registry from preloaded locales (instant, no network request)
+const locales = await buildRegistry(['en', 'fr', 'de']);
+
+new Blok({
+  holder: 'editor',
+  i18n: {
+    locales,
+    locale: 'auto',
+  }
+});
+```
+
+**When to preload:**
+- Offline support (preload all needed locales before going offline)
+- Eliminating any loading delay during editor initialization
+- Progressive web apps that cache resources upfront
+
+**When not to preload:**
+- Most apps—just use `buildRegistry()` directly and accept the ~50-100ms loading time
+- The on-demand loading is usually imperceptible
+
+### Setting a Specific Locale
+
+```typescript
+new Blok({
+  holder: 'editor',
+  i18n: {
+    locale: 'fr',         // Use French
+    defaultLocale: 'en',  // Fallback if 'fr' unavailable
+  }
+});
+```
 
 ## Documentation
 
-📚 **Documentation is coming soon!** We're working hard to provide comprehensive guides, API references, and examples. Stay tuned for updates.
+📚 **Complete Documentation is coming soon!** We're working hard to provide comprehensive guides, API references, and examples. Stay tuned for updates.

package/codemod/README.md

@@ -40,8 +40,10 @@ npx migrate-from-editorjs ./src --dry-run
 
 - import Header from '@editorjs/header';
 - import Paragraph from '@editorjs/paragraph';
+- import List from '@editorjs/list';
 + // Header is now bundled with Blok: use Blok.Header
 + // Paragraph is now bundled with Blok: use Blok.Paragraph
++ // List is now bundled with Blok: use Blok.List
 ```
 
 ### Type Transformations
@@ -100,8 +102,10 @@ npx migrate-from-editorjs ./src --dry-run
 tools: {
 -   header: Header,
 -   paragraph: Paragraph,
+-   list: List,
 +   header: Blok.Header,
 +   paragraph: Blok.Paragraph,
++   list: Blok.List,
 }
 ```
 
@@ -113,6 +117,7 @@ tools: {
 -   "@editorjs/editorjs": "^2.28.0",
 -   "@editorjs/header": "^2.8.0",
 -   "@editorjs/paragraph": "^2.11.0",
+-   "@editorjs/list": "^1.9.0",
 +   "@jackuait/blok": "latest"
   }
 }
@@ -124,8 +129,19 @@ tools: {
 |--------|-------------|
 | `--dry-run` | Preview changes without modifying files |
 | `--verbose` | Show detailed output for each file |
+| `--use-library-i18n` | Remove custom i18n messages and use Blok's built-in translations |
 | `--help` | Show help message |
 
+### Using `--use-library-i18n`
+
+If your EditorJS project had custom translations, the codemod will by default convert them to Blok's flat format. However, Blok now ships with built-in translations for 36 languages. If you prefer to use these library translations instead of maintaining your own, use the `--use-library-i18n` flag:
+
+```bash
+npx -p @jackuait/blok migrate-from-editorjs ./src --use-library-i18n
+```
+
+This will remove the `messages` property from your i18n config, allowing Blok to auto-detect the user's locale from the browser and use the appropriate built-in translations.
+
 ## Supported File Types
 
 - JavaScript: `.js`, `.jsx`