Merge pull request #25 from RZEROSTERN/feat/phase-4-quality-and-safety

Phase 4 completed: Code quality and safety

Author: RZEROSTERN

CHANGELOG.md

@@ -1,3 +1,27 @@
+## [0.4.0] - 2026-03-25 — Phase 4: Quality & Safety
+
+### Null-safety hardening
+* `JsonDocumentSource.parse()` now wraps `jsonDecode` in try/catch — invalid JSON returns an empty `BlockDocument` instead of throwing.
+* `HeaderMapper` — `level` field uses `is int` guard instead of a bare `as int?` cast.
+* `ImageMapper` — `file` object and all three `bool` fields (`withBorder`, `stretched`, `withBackground`) use safe type checks.
+* `AttachesMapper` — `file` object uses `is Map` guard; `size` handles both `int` and `num` (double) via switch expression.
+* `EmbedMapper` — `width` and `height` handle both `int` and `num` via switch expression.
+* `LinkToolMapper` — `image` sub-map uses `is Map` guard.
+* `TableMapper` — `withHeadings` uses `is bool` guard.
+* `ChecklistMapper` — `checked` uses `is bool` guard.
+
+### Unknown block type logging
+* `JsonDocumentSource` emits a `dart:developer` `log` entry (`name: 'EditorJSFlutter'`) when an unknown block type is silently dropped during parsing.
+
+### Tests (91 total)
+* **`test/unit/html_sanitizer_test.dart`** (9 tests) — script tags, iframes, event handlers, edge cases.
+* **`test/unit/mappers_test.dart`** (46 tests) — all 14 mappers; happy path, missing fields, wrong-type fields.
+* **`test/unit/editor_controller_test.dart`** (17 tests) — all mutations, full undo/redo state machine.
+* **`test/unit/json_document_source_test.dart`** — parse, unknown-type drop, invalid JSON, round-trip.
+* **`test/widget/renderers_test.dart`** (9 tests) — header, delimiter, code, warning, checklist, embed, attaches.
+
+---
+
 ## [0.3.0] - 2026-03-25 — Phase 3: Editor features
 
 ### Undo / redo

lib/src/data/datasources/json_document_source.dart

@@ -1,4 +1,5 @@
 import 'dart:convert';
+import 'dart:developer' as dev;
 
 import '../../domain/entities/block_document.dart';
 import '../../domain/entities/block_entity.dart';
@@ -13,15 +14,41 @@ class JsonDocumentSource implements DocumentRepository {
 
   @override
   BlockDocument parse(String jsonString) {
-    final Map<String, dynamic> root = jsonDecode(jsonString) as Map<String, dynamic>;
-    final rawBlocks = (root['blocks'] as List<dynamic>?) ?? [];
+    late final Map<String, dynamic> root;
+    try {
+      root = jsonDecode(jsonString) as Map<String, dynamic>;
+    } on FormatException catch (_) {
+      return BlockDocument(
+        time: DateTime.now().millisecondsSinceEpoch,
+        version: '',
+        blocks: const [],
+      );
+    } on TypeError catch (_) {
+      return BlockDocument(
+        time: DateTime.now().millisecondsSinceEpoch,
+        version: '',
+        blocks: const [],
+      );
+    }
+
+    final rawBlocks =
+        root['blocks'] is List ? root['blocks'] as List<dynamic> : <dynamic>[];
 
     final blocks = rawBlocks
         .whereType<Map<String, dynamic>>()
         .map((b) {
-          final type = (b['type'] as String?) ?? '';
-          final data = (b['data'] as Map<String, dynamic>?) ?? {};
-          return registry.parse(type, data);
+          final type = b['type'] is String ? b['type'] as String : '';
+          final data = b['data'] is Map<String, dynamic>
+              ? b['data'] as Map<String, dynamic>
+              : <String, dynamic>{};
+          final entity = registry.parse(type, data);
+          if (entity == null && type.isNotEmpty) {
+            dev.log(
+              'Unknown block type ignored: "$type"',
+              name: 'EditorJSFlutter',
+            );
+          }
+          return entity;
         })
         .whereType<BlockEntity>()
         .toList();

lib/src/data/mappers/attaches_mapper.dart

@@ -9,13 +9,19 @@ class AttachesMapper implements BlockMapper<AttachesBlock> {
 
   @override
   AttachesBlock fromJson(Map<String, dynamic> data) {
-    final file = data['file'] as Map<String, dynamic>?;
+    final file = data['file'] is Map ? data['file'] as Map<String, dynamic> : null;
     return AttachesBlock(
-      url: (file?['url'] as String?) ?? '',
-      name: file?['name'] as String?,
-      extension: file?['extension'] as String?,
-      size: file?['size'] as int?,
-      title: data['title'] as String?,
+      url: file != null && file['url'] is String ? file['url'] as String : '',
+      name: file != null && file['name'] is String ? file['name'] as String : null,
+      extension: file != null && file['extension'] is String
+          ? file['extension'] as String
+          : null,
+      size: switch (file?['size']) {
+        int v => v,
+        num v => v.toInt(),
+        _ => null,
+      },
+      title: data['title'] is String ? data['title'] as String : null,
     );
   }
 }

lib/src/data/mappers/checklist_mapper.dart

@@ -9,12 +9,13 @@ class ChecklistMapper implements BlockMapper<ChecklistBlock> {
 
   @override
   ChecklistBlock fromJson(Map<String, dynamic> data) {
-    final rawItems = (data['items'] as List<dynamic>?) ?? [];
+    final rawItems =
+        data['items'] is List ? data['items'] as List<dynamic> : <dynamic>[];
     return ChecklistBlock(
       items: rawItems.whereType<Map<String, dynamic>>().map((i) {
         return ChecklistItem(
-          text: (i['text'] as String?) ?? '',
-          checked: (i['checked'] as bool?) ?? false,
+          text: i['text'] is String ? i['text'] as String : '',
+          checked: i['checked'] is bool ? i['checked'] as bool : false,
         );
       }).toList(),
     );

lib/src/data/mappers/embed_mapper.dart

@@ -9,11 +9,20 @@ class EmbedMapper implements BlockMapper<EmbedBlock> {
 
   @override
   EmbedBlock fromJson(Map<String, dynamic> data) => EmbedBlock(
-        service: (data['service'] as String?) ?? '',
-        source: (data['source'] as String?) ?? '',
-        embed: (data['embed'] as String?) ?? '',
-        width: data['width'] as int?,
-        height: data['height'] as int?,
-        caption: data['caption'] as String?,
+        service: data['service'] is String ? data['service'] as String : '',
+        source: data['source'] is String ? data['source'] as String : '',
+        embed: data['embed'] is String ? data['embed'] as String : '',
+        width: switch (data['width']) {
+          int v => v,
+          num v => v.toInt(),
+          _ => null,
+        },
+        height: switch (data['height']) {
+          int v => v,
+          num v => v.toInt(),
+          _ => null,
+        },
+        caption:
+            data['caption'] is String ? data['caption'] as String : null,
       );
 }

lib/src/data/mappers/header_mapper.dart

@@ -9,7 +9,9 @@ class HeaderMapper implements BlockMapper<HeaderBlock> {
 
   @override
   HeaderBlock fromJson(Map<String, dynamic> data) => HeaderBlock(
-        text: (data['text'] as String?) ?? '',
-        level: (data['level'] as int?) ?? 1,
+        text: data['text'] is String
+            ? data['text'] as String
+            : (data['text']?.toString() ?? ''),
+        level: data['level'] is int ? data['level'] as int : 1,
       );
 }

lib/src/data/mappers/image_mapper.dart

@@ -9,13 +9,13 @@ class ImageMapper implements BlockMapper<ImageBlock> {
 
   @override
   ImageBlock fromJson(Map<String, dynamic> data) {
-    final file = data['file'] as Map<String, dynamic>?;
+    final file = data['file'] is Map ? data['file'] as Map<String, dynamic> : null;
     return ImageBlock(
-      url: (file?['url'] as String?) ?? '',
-      caption: data['caption'] as String?,
-      withBorder: (data['withBorder'] as bool?) ?? false,
-      stretched: (data['stretched'] as bool?) ?? false,
-      withBackground: (data['withBackground'] as bool?) ?? false,
+      url: file != null && file['url'] is String ? file['url'] as String : '',
+      caption: data['caption'] is String ? data['caption'] as String : null,
+      withBorder: data['withBorder'] is bool ? data['withBorder'] as bool : false,
+      stretched: data['stretched'] is bool ? data['stretched'] as bool : false,
+      withBackground: data['withBackground'] is bool ? data['withBackground'] as bool : false,
     );
   }
 }

lib/src/data/mappers/link_tool_mapper.dart

@@ -10,7 +10,7 @@ class LinkToolMapper implements BlockMapper<LinkToolBlock> {
   @override
   LinkToolBlock fromJson(Map<String, dynamic> data) {
     final rawMeta = data['meta'] as Map<String, dynamic>?;
-    final rawImage = rawMeta?['image'] as Map<String, dynamic>?;
+    final rawImage = rawMeta?['image'] is Map ? rawMeta!['image'] as Map<String, dynamic> : null;
 
     final meta = rawMeta == null
         ? null

lib/src/data/mappers/table_mapper.dart

@@ -9,9 +9,10 @@ class TableMapper implements BlockMapper<TableBlock> {
 
   @override
   TableBlock fromJson(Map<String, dynamic> data) {
-    final rawContent = (data['content'] as List<dynamic>?) ?? [];
+    final rawContent =
+        data['content'] is List ? data['content'] as List<dynamic> : <dynamic>[];
     return TableBlock(
-      withHeadings: (data['withHeadings'] as bool?) ?? false,
+      withHeadings: data['withHeadings'] is bool ? data['withHeadings'] as bool : false,
       content: rawContent.map((row) {
         final List<dynamic> rowList = row is List ? row : <dynamic>[];
         return rowList.map((cell) => cell.toString()).toList();

pubspec.yaml

@@ -1,6 +1,6 @@
 name: editorjs_flutter
 description: A new Flutter package project.
-version: 0.3.0
+version: 0.4.0
 homepage: https://github.com/RZEROSTERN/editorjs-flutter
 
 environment: