Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
4ae4d7e
Add lossless round-trip with EditorJS 2.31 and harden parsing
RZEROSTERN Nov 10, 2026
91181e8
Merge pull request #34 from DEV1-Softworks/feat/lossless-roundtrip
RZEROSTERN Nov 10, 2026
9f4de68
Add List 2.x support: checklist style and ordered numbering options
RZEROSTERN Nov 10, 2026
702ed96
Offer both checklist kinds in the editor toolbar
RZEROSTERN Nov 10, 2026
ba07138
Merge pull request #35 from DEV1-Softworks/feat/list-v2
RZEROSTERN Nov 10, 2026
12c02ca
Improve viewer fidelity: visible tables, inline HTML, tappable links
RZEROSTERN Nov 10, 2026
30281ca
Open only web links by default; make tables full width
RZEROSTERN Nov 10, 2026
10a5fbf
Merge pull request #36 from DEV1-Softworks/feat/viewer-fidelity
RZEROSTERN Nov 10, 2026
3d9a754
Let the header editor change the heading level
RZEROSTERN Nov 10, 2026
0ff8e9a
Make the editor toolbar buttons configurable
RZEROSTERN Nov 10, 2026
c9ce974
Rework the image editor: upload hook, URL, caption and options
RZEROSTERN Nov 10, 2026
d021161
Make nested list items editable
RZEROSTERN Nov 10, 2026
d8e4894
Document the editor improvements
RZEROSTERN Nov 10, 2026
77ecb95
Merge pull request #37 from DEV1-Softworks/feat/editor-improvements
RZEROSTERN Nov 10, 2026
4519314
Remove a list item's children together with the item
RZEROSTERN Nov 10, 2026
dcc3352
Add editors for embed, link, attachment and raw blocks
RZEROSTERN Nov 10, 2026
0be8fb6
Add, edit and remove links from the paragraph format bar
RZEROSTERN Nov 10, 2026
cfba92d
Merge pull request #38 from DEV1-Softworks/fix/list-remove-children
RZEROSTERN Nov 10, 2026
8ee4fbb
Merge pull request #39 from DEV1-Softworks/feat/block-editors
RZEROSTERN Nov 10, 2026
446ea21
Merge pull request #40 from DEV1-Softworks/feat/inline-link-editing
RZEROSTERN Nov 10, 2026
1e7ac3c
Make all editor and viewer text translatable
RZEROSTERN Nov 10, 2026
00004c7
Bundle Spanish and French translations and document adding more
RZEROSTERN Nov 10, 2026
ba7c908
Merge pull request #41 from DEV1-Softworks/feat/editor-localization
RZEROSTERN Nov 10, 2026
79e41c5
Release 1.0.0
RZEROSTERN Nov 10, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@ name: CI

on:
push:
branches: [master]
branches: [master, develop]
pull_request:
branches: [master]
branches: [master, develop]

jobs:
test:
Expand Down
68 changes: 68 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,71 @@
## [1.0.0] - 2026-11-10 — EditorJS 2.31 parity

### Lossless round-trip with current EditorJS (2.31)
* **Block ids and tunes are preserved.** `id` and `tunes` are read into the new `BlockDocument.metadata` (`BlockMetadata`) and written back on serialize. `EditorController.blockIds` now holds the EditorJS ids (kept from the document, generated in EditorJS's own 10-character format for new blocks) and the new `EditorController.blockTunes` exposes each block's tunes. Both follow their block through update, move and undo/redo.
* **Unknown blocks are no longer deleted.** A block with no registered mapper — or whose mapper throws — is kept verbatim as the new `UnknownBlock` entity and written back untouched. The viewer skips it (without leaving a gap) and the editor shows the existing "Unsupported block" placeholder.
* **Backend-defined fields survive.** `TableBlock.stretched`, `ImageBlock.fileExtras`, `AttachesBlock.fileExtras` and `LinkToolMeta.extras` carry fields such as image `width`/`height` or link `site_name` through a round-trip.
* **Version stamp updated.** `getContent()` writes `"version": "2.31.7"` (`BlockDocument.editorJsVersion`) instead of the hard-coded `2.19.0`.

### List 2.x (`@editorjs/list` 2.x: nested lists and checklists in one block)
* **Checklist style.** `ListStyle.checklist` is read, rendered (a tick box per item, at every nesting level), edited and written back; the ticked state lives in the new `ListItem.checked`. Previously a `checklist`-style list was turned into a bullet list and its ticks were lost.
* **Ordered list numbering.** New `ListBlock.start` and `ListBlock.counterType` (`ListCounterType`: numeric, lower/upper roman, lower/upper alpha) are read, rendered and written back. Nested items are numbered `1.1.`, `1.2.`, … as EditorJS renders them, instead of restarting at `1.`.
* **List editor.** A style selector switches a list between unordered, ordered and checklist; ordered lists get "Start with" and counter-type options; checklist items get a tick box.
* **Two checklist buttons in the toolbar.** "Checklist" now adds a list 2.x checklist (a `list` block with `style: "checklist"`); "Checklist (legacy)" adds the older `checklist` block that the button used to create. Which one a site can read depends on the tools installed in its EditorJS instance.
* **Legacy formats are still read:** `@editorjs/list` 1.x string items, `@editorjs/nested-list` items, and old checklist `{text, checked}` items stored under a list block.

### Viewer fidelity
* **Tables are now visible.** The table renderer laid its columns out at zero width, so every table showed as a thin strip with one letter per line. As in EditorJS, a table now spans the full width with equal columns and wraps the text in its cells. A table with too many columns to keep them 96 px wide scrolls sideways instead of squeezing them.
* **Inline formatting and entities are rendered everywhere.** Headers, table cells, legacy checklist items, warning title and message, and image, embed and quote captions showed markup such as `<b>` and `&amp;` literally. All text now goes through one widget, so bold, italic, links, marker, inline code and entities render in every block.
* **Links can be tapped.** `<a>` links did nothing. Web links (`http`, `https`) now open in the external application; other schemes are opt-in through the new `EditorConfig.allowedLinkSchemes` (for example `{'http', 'https', 'mailto', 'tel'}`). To handle taps yourself, pass the new `EditorConfig.onLinkTap`. Link, embed and attachment cards go through the same path. Custom renderers can join in with `EditorLinkScope.open(context, url)`.
* **Blocks line up.** Paragraph, quote and raw text had an extra 8 px left and right margin that headers and tables did not; list markers sat about 6 px above their item's text. Both are fixed, and list items are spaced 8 px apart.

### Editor improvements
* **Image editor.** New `EditorConfig.imageUploader` stores a picked image and returns its public URL (and any extra file fields), like the uploader of the EditorJS image tool; without one the path of the file on the device is stored, as before. The editor gained fields for the image URL and the caption, toggles for border, stretch and background, an upload progress bar, and error messages for failed picks and uploads. Picking a new image no longer resets the caption and the display options.
* **Links in paragraphs.** The paragraph format bar has a "Link" button: it links the selected text (or inserts the address as a link when nothing is selected), and when the caret is in an existing link it edits or removes that link. A bare address such as `example.com` is completed to `https://example.com`.
* **Heading level.** The header editor has an H1–H6 selector; the level used to be fixed when the block was created.
* **Nested lists.** Every list item is editable, at any depth: items can be indented under the one above, outdented, and removed (removing an item removes its children too). Enter adds an item below the current one. Nested items used to be invisible in the editor.
* **Configurable toolbar.** `EditorConfig.toolbarItems` takes the `EditorToolbarItem` buttons to show, in order; the default is every button.
* New `ImageBlock.copyWith`.
* **Editors for embed, link, attachment and raw blocks.** These four were viewer-only and showed an "Unsupported block" placeholder in the editor; each now has an editor and a toolbar button (`EditorToolbarItem.embed`, `linkPreview`, `attachment`, `rawHtml`).
* *Embed:* give a link; the service and embed URL are worked out with the patterns of `@editorjs/embed` (YouTube, Vimeo, X/Twitter, Instagram, CodePen, Figma and others).
* *Link:* link, title, description and preview image; the new `EditorConfig.linkPreviewFetcher` adds a "Fetch preview" button, the counterpart of the link tool's backend endpoint.
* *Attachment:* file URL and title; the new `EditorConfig.attachmentPicker` adds a "Choose file" button for apps that bring their own file picker and upload.
* *Raw:* the HTML source.

### Translatable text
* **Every label, tooltip, hint and message can be translated or reworded.** New `EditorConfig.strings` takes an `EditorStrings`, which holds all 104 texts the editor and the viewer show on their own, with English defaults; override only the ones you need. Texts that include a value (a heading level, a file size) are functions. Until now all text was hard-coded in English.
* **Spanish and French are bundled.** `EditorTranslations.es` and `EditorTranslations.fr` are complete translations; `EditorTranslations.forLanguage(code)` picks one from a language code or locale tag and falls back to English. The README explains how to add another language, in an app or in the package.

### Requirements and dependencies
* **The minimum is now declared as Flutter 3.27 (Dart 3.6).** Earlier releases declared Flutter 3.10 but already used `Color.withValues`, which arrived in 3.27, so on an older Flutter the package installed and then failed to compile. Nothing changes for apps that could build it.
* **`html` is capped below 0.15.7.** `html` 0.15.7 removed a function that `flutter_html` 3.0.0 calls, so an app that resolved to it failed to compile. The package now depends on `html: ">=0.15.5 <0.15.7"` until `flutter_html` supports the newer version. An app that needs `html` 0.15.7 or later for another package will get a version conflict.
* `flutter_html`: `^3.0.0-beta.2` → `^3.0.0`. The pre-release versions are no longer accepted.

### CI and workflow
* CI also runs on pushes and pull requests to `develop`.
* `CLAUDE.md` and the README describe the git flow the project uses: work branches from `develop`, releases from `release/<version>` into `master`.

### Parser hardening
* A field of the wrong type no longer throws out of `EditorJSView` / `EditorController.fromJson`. Every built-in mapper now reads through tolerant helpers; previously `linkTool.meta: []`, a non-string list `style`, a non-string paragraph `text` and a non-integer document `time` each raised a `TypeError`.
* `time` accepts integers, doubles and numeric strings; header `level` accepts doubles.

### Behaviour changes
* `BlockDocument.blocks`, `EditorController.blocks` and `blockCount` now include `UnknownBlock`s for unrecognised types, where such blocks used to be dropped.
* `EditorController.blockIds` values are EditorJS-style ids rather than `b0`, `b1`, …
* `getContent()` output now contains `id` on every block, `tunes` where present, and `stretched` on tables.
* `BlockRendererRegistry.buildRenderer` / `buildEditor` return `null` for an `UnknownBlock` even when a builder is registered for its type string.
* Blocks with a missing or non-string `type` are still dropped: they cannot be written back.
* The toolbar's "Checklist" button creates a `list` block with the checklist style, no longer a `checklist` block; the previous behaviour moved to the new "Checklist (legacy)" button.
* Link, embed and attachment cards no longer raise an unhandled error when the platform cannot open a link.
* Paragraph, quote and raw blocks are 16 px wider (no horizontal margin) and list rows are closer together.
* `ListStyle` has a third value, `checklist`: an exhaustive `switch` over `ListStyle` in consumer code needs a new case.
* Lists are always written in the list 2.x shape: `ListBlock.toJson()` adds a root `meta`, and `ListItem.toJson()` adds a per-item `meta`.

### Tests
* Added `test/unit/lossless_roundtrip_test.dart`, `editor_controller_metadata_test.dart`, `json_reader_test.dart`, `list_v2_test.dart`, `embed_services_test.dart` and `translations_test.dart`; and `test/widget/unknown_block_test.dart`, `list_v2_test.dart`, `viewer_fidelity_test.dart`, `header_level_test.dart`, `toolbar_items_test.dart`, `image_editor_test.dart`, `nested_list_editor_test.dart`, `media_block_editors_test.dart`, `paragraph_link_test.dart` and `localization_test.dart` (469 tests in total, 95 % line coverage).

---

## [0.5.0] - 2026-03-25 — Publication readiness

### New API
Expand Down
69 changes: 42 additions & 27 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ fvm flutter test test/editorjs_flutter_test.dart

## Architecture

The package follows **Clean Architecture** with three strict layers. Dependencies only flow inward (presentation → data → domain). No new external dependencies — only `flutter_html`, `image_picker`, `url_launcher`, and Flutter's built-in `ChangeNotifier`.
The package follows **Clean Architecture** with three strict layers. Dependencies only flow inward (presentation → data → domain). No new external dependencies — only `flutter_html`, `image_picker`, `url_launcher`, and Flutter's built-in `ChangeNotifier`. (`html` is listed in `pubspec.yaml` only to cap the version `flutter_html` resolves to; the package does not import it.)

```
lib/src/
Expand Down Expand Up @@ -109,33 +109,33 @@ final config = EditorConfig(

| Block | Viewer | Editor | Notes |
|---|---|---|---|
| `header` | H1–H6 | ✅ | |
| `paragraph` | HTML via flutter_html | ✅ | Inline format bar (B/I/U/S/code/mark) |
| `list` | Ordered / unordered / nested | ✅ | |
| `header` | H1–H6, inline HTML | ✅ | |
| `paragraph` | HTML via flutter_html | ✅ | Inline format bar (B/I/U/S/code/mark/link); the link button adds, edits and removes `<a>` |
| `list` | Ordered (start, counter type) / unordered / checklist / nested | ✅ | `@editorjs/list` 2.x format; legacy list, nested-list and checklist data is read too. Nested items are edited as an outline (indent / outdent) |
| `delimiter` | Divider | ✅ | |
| `image` | Network URL | ✅ | caption/border/stretch parsed; image_picker not wired |
| `image` | Network URL, caption, border / stretch / background | ✅ | Editor picks from camera or gallery and uploads through `EditorConfig.imageUploader`; without an uploader the local file path is stored |
| `quote` | With alignment | ✅ | |
| `code` | Monospace + copy button | ✅ | |
| `checklist` | Checked / unchecked | ✅ | |
| `table` | With optional heading row | ✅ | |
| `warning` | Title + message | ✅ | |
| `embed` | Tappable card | Viewer only | |
| `linkTool` | Link preview card | Viewer only | |
| `attaches` | File download card | Viewer only | |
| `raw` | Sanitized HTML | Viewer only | |
| `checklist` | Checked / unchecked | ✅ | Legacy `@editorjs/checklist` block; toolbar button "Checklist (legacy)". The toolbar's "Checklist" button creates a `list` block with the checklist style |
| `table` | Optional heading row, inline HTML in cells | ✅ | Full width with equal columns, text wraps; scrolls horizontally when columns would be narrower than 96 px. `stretched` is preserved but has no visual effect |
| `warning` | Title + message, inline HTML | ✅ | |
| `embed` | Tappable card | ✅ | Service and embed URL derived from the link with the `@editorjs/embed` patterns (`data/utils/embed_services.dart`) |
| `linkTool` | Link preview card | ✅ | Preview fields typed by hand or fetched through `EditorConfig.linkPreviewFetcher` |
| `attaches` | File download card | ✅ | File given as a URL or through `EditorConfig.attachmentPicker` (no bundled file picker) |
| `raw` | Sanitized HTML | ✅ | Editor shows the HTML source |

---

## Public API

`lib/editorjs_flutter.dart` is the sole entry point. It exports:

- **Widgets**: `EditorJSView`, `EditorJSEditor`
- **Widgets**: `EditorJSView`, `EditorJSEditor`, `EditorLinkScope` (lets custom renderers open links through `EditorConfig.onLinkTap`)
- **Controller**: `EditorController`
- **Config**: `EditorConfig`
- **Config**: `EditorConfig`, `EditorToolbarItem`, `ImageUploader` / `PickedImage` / `UploadedImage`, `LinkPreviewFetcher`, `AttachmentPicker`, `EditorStrings`, `EditorTranslations` (bundled `es` and `fr`)
- **Registries**: `BlockTypeRegistry`, `BlockRendererRegistry`
- **Contracts** (for custom block authors): `BlockMapper`, `BlockRenderer`, `BlockEditor`, `BlockEntity`, `BlockDocument`, `StyleConfig`
- **Built-in entities**: `HeaderBlock`, `ParagraphBlock`, `ListBlock`, `DelimiterBlock`, `ImageBlock`
- **Contracts** (for custom block authors): `BlockMapper`, `BlockRenderer`, `BlockEditor`, `BlockEntity`, `BlockDocument`, `BlockMetadata`, `StyleConfig`
- **Built-in entities**: `HeaderBlock`, `ParagraphBlock`, `ListBlock`, `DelimiterBlock`, `ImageBlock`, and the other block entities; `UnknownBlock` holds any block the package cannot interpret so it round-trips untouched

Nothing from `lib/src/` should be imported directly by consumers.

Expand All @@ -159,7 +159,7 @@ When building new features, always work bottom-up:
- `lib/src/data/registry/block_type_registry.dart` — JSON parsing extension point
- `lib/src/presentation/registry/block_renderer_registry.dart` — rendering extension point
- `lib/src/presentation/controller/editor_controller.dart` — editor state + `getContent()`
- `lib/src/presentation/widgets/` — thin shell widgets
- `lib/src/presentation/widgets/` — thin shell widgets, plus `inline_html.dart`: the one widget every renderer uses to show EditorJS text (sanitizing, styling, link taps)
- `demo/lib/main.dart` — viewer usage example
- `demo/lib/createnote.dart` — editor usage example
- `demo/test_data/` — sample EditorJS JSON and styles JSON
Expand All @@ -172,30 +172,37 @@ When building new features, always work bottom-up:
4. Run `fvm flutter test --coverage` locally and verify the coverage threshold.
5. Follow the Clean Architecture layer rules: no Flutter imports in `domain/`, no direct widget dependencies in `data/`.
6. New block types must be added bottom-up: entity → mapper → renderer → (editor) → register in both registries → export from barrel.
7. No hard-coded user-visible text in widgets. Add a field to `EditorStrings` and read it with `EditorConfigScope.stringsOf(context)`; `test/widget/localization_test.dart` fails when a widget shows text that did not come from there. Every new text must also be added to each file in `lib/src/presentation/config/translations/`; `test/unit/translations_test.dart` fails when a bundled translation is incomplete.

## Git Workflow

**This repo has branch protection. Direct commits to `master` are not allowed.**
**This repo follows git flow. Direct commits to `master` or `develop` are not allowed.**

- `master` holds released versions only.
- `develop` is the integration branch: every feature, fix and chore is merged here first.
- `release/<version>` is cut from `develop` when a version is ready, and is merged into `master`.

### Before starting any coding task

1. Ensure `master` is up to date and create a new branch:
1. Ensure `develop` is up to date and create a new branch from it:
```bash
git checkout master
git checkout develop
git pull
git checkout -b <prefix>/<short-description>
```
Always branch from `develop`, never from another work branch: one branch and one PR per task.
2. Use these branch name prefixes:
- `feat/` — new feature or block type
- `fix/` — bug fix
- `refactor/` — internal restructuring with no behaviour change
- `chore/` — dependency bumps, tooling, docs
- `release/` — release branch, named after the version (`release/1.0.0`)

### Before finishing any coding task

1. Run `fvm flutter analyze` — must report **no issues** before marking work done.
2. Generate a `PR_DESCRIPTION.md` file at the repo root (see template below).
3. All changes go to `master` via Pull Request only — never push directly.
3. All changes go to `develop` via Pull Request only — never push directly. Only a release branch is merged into `master`.
4. Delete `PR_DESCRIPTION.md` after the PR is merged.

### PR_DESCRIPTION.md template
Expand Down Expand Up @@ -226,22 +233,30 @@ When building new features, always work bottom-up:
- [ ] Demo app tested manually on at least one platform
```

### Releasing

1. Cut `release/<version>` from `develop`.
2. On that branch, set the version in `pubspec.yaml`, turn the `[Unreleased]` section of `CHANGELOG.md` into the entry for the version, and update the version references in `README.md` and in this file. Apart from that, only fixes found while preparing the release go on this branch.
3. Open a PR from the release branch into `master`. CI must pass.
4. After the merge, merge `master` back into `develop`.

---

## Versioning

Current version: `0.5.0` (in `pubspec.yaml`).
Current version: `1.0.0` (in `pubspec.yaml`).

When making changes, always update `CHANGELOG.md` with a new entry at the top following the existing format:
- Bump the patch version for bug fixes
- Bump the minor version for new features or breaking API changes
The package follows semantic versioning. When making changes, add a note to the `## [Unreleased]` section at the top of `CHANGELOG.md` (create it if it is missing), following the existing format. Do not change the version on a work branch; it is set on the release branch:
- Patch version for bug fixes
- Minor version for new features
- Major version for breaking changes to the public API
- Keep `pubspec.yaml` version in sync with `CHANGELOG.md`

## Known Issues / Backlog

- `image_picker` is declared as a dependency but `ImageEditor` only accepts a URL string — picker not wired up
- `ImageEditor` imports `dart:io` for the local-file preview; on the web it falls back to `Image.network`, but this path is untested
- No `EditorController` content persistence to local storage (save/load)
- No inline link editor in paragraph (currently inserts a `<a>` paragraph block via dialog)
- The paragraph editor shows the HTML source (tags are visible while editing); the format bar inserts tags rather than styling text in place
- No drag-to-reorder for blocks (only up/down buttons)
- Typing history not tracked by undo/redo (only structural operations are undoable)
- pub.dev publication pending — description, topics, and example are ready but package has not been published yet
Loading
Loading