@jackuait/blok 0.4.1 → 0.4.3-beta.1

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

@@ -34,14 +34,30 @@ npx migrate-from-editorjs ./src --dry-run
 
 ### Import Transformations
 
+**EditorJS → Blok:**
 ```diff
 - import EditorJS from '@editorjs/editorjs';
-+ import Blok from '@jackuait/blok';
++ import { Blok } from '@jackuait/blok';
+
+- import EditorJS, { EditorConfig } from '@editorjs/editorjs';
++ import { Blok, BlokConfig } 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
+- import List from '@editorjs/list';
++ import { Header, Paragraph, List } from '@jackuait/blok/tools';
+```
+
+**Blok default imports → named imports** (Blok only exports named exports):
+```diff
+- import Blok from '@jackuait/blok';
++ import { Blok } from '@jackuait/blok';
+
+- import Editor from '@jackuait/blok';
++ import { Blok as Editor } from '@jackuait/blok';
+
+- import Blok, { BlokConfig } from '@jackuait/blok';
++ import { Blok, BlokConfig } from '@jackuait/blok';
 ```
 
 ### Type Transformations
@@ -96,15 +112,25 @@ npx migrate-from-editorjs ./src --dry-run
 
 ### Tool Configuration Transformations
 
+Old Blok static property references are converted to direct imports:
 ```diff
 tools: {
--   header: Header,
--   paragraph: Paragraph,
-+   header: Blok.Header,
-+   paragraph: Blok.Paragraph,
+-   header: Blok.Header,
+-   paragraph: Blok.Paragraph,
+-   list: Blok.List,
++   header: Header,
++   paragraph: Paragraph,
++   list: List,
 }
 ```
 
+Combined Blok imports are split into core and tools:
+```diff
+- import { Blok, Header, Paragraph, List } from '@jackuait/blok';
++ import { Blok } from '@jackuait/blok';
++ import { Header, Paragraph, List } from '@jackuait/blok/tools';
+```
+
 ### package.json Updates
 
 ```diff
@@ -113,6 +139,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 +151,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`