diff --git a/README.md b/README.md index c5bf2507e..94accffe0 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # HtmlWidget monorepo -![Flutter](https://github.com/daohoangson/flutter_widget_from_html/workflows/Flutter/badge.svg) +[![Flutter](https://github.com/daohoangson/flutter_widget_from_html/actions/workflows/flutter.yml/badge.svg)](https://github.com/daohoangson/flutter_widget_from_html/actions/workflows/flutter.yml) [![codecov](https://codecov.io/gh/daohoangson/flutter_widget_from_html/branch/master/graph/badge.svg)](https://codecov.io/gh/daohoangson/flutter_widget_from_html) This repo contains the source code for everything `HtmlWidget`-related. diff --git a/docs/migration.md b/docs/migration.md new file mode 100644 index 000000000..e9972d604 --- /dev/null +++ b/docs/migration.md @@ -0,0 +1,135 @@ +# Migration from v0.10 to v0.14 + +[PR #897](https://github.com/daohoangson/flutter_widget_from_html/pull/897) is a big change that might break things in existing app. We made it easier to understand how the package parses HTML into a Flutter widget tree. The main goals were: + +1. Merge `BuildMetadata` and `BuildTree`. +2. Simplify `BuildOp` callbacks +3. Clearly show which properties are inherited from parent elements and which are not. + +## BuildBit + +This core class has been greatly simplified and it no longer uses generic type arguments. + +```diff +-abstract class BuildBit { ++abstract class BuildBit { +- OutputType buildBit(InputType input); +- bool detach(); ++ void flatten(Flattened f); +- bool insertAfter(BuildBit another); +- bool insertBefore(BuildBit another); +} +``` + +### buildBit + +This method has been replaced with `flatten`. It will receive an object that looks like this: + +```dart +abstract class Flattened { + void inlineWidget({ required Widget child }); + void widget(Widget value); + void write({String? text, String? whitespace}); +} +``` + +In the past, the `buildBit` method returned results in a dynamic manner. The flattener would automatically interpret `String` as text, `WidgetSpan` as inline elements, and `Widget` as block elements. This approach was prone to errors and potentially risky. With the introduction of the `flatten` method, you are now required to call the specific method that corresponds to the intended action, making the process more controlled and less error-prone. + +### detach, insertAfter and insertBefore + +Initially, these methods were necessary to support features that required modifying the build tree. However, starting from version 0.14, you should utilize the `BuildOp.onParsed` callback and return the entirely new tree. + +
BeforeAfter
+ +```dart +final oldOp = BuildOp( + onTreeFlattening: (meta, tree) { + final foo = WidgetBit.inline(tree.parent!, Text('foo')); + foo.insertBefore(tree); + tree.detach(); + } +) +``` + + + +```dart +final newOp = BuildOp( + onParsed: (tree) { + final newTree = tree.parent.sub(); + newTree.append(WidgetBit.inline(tree, Text('foo'))); + return newTree; + } +) +``` + +
+ +## BuildOp + +### BuildOp.new + +We made changes to the `BuildOp` that allow you to use the old methods and properties, but they are marked as deprecated. It's a good idea to switch to the new methods as soon as possible. + +
BeforeAfter
+ +```dart +final oldOp = BuildOp({ + defaultStyles: (dom.Element element) { + final Map styles = {'color': 'red'}; + return styles; + }, + onChild: (BuildMetadata childMeta) {}, + onTree: (BuildMetadata meta, BuildTree tree) {}, + onTreeFlattening: (BuildMetadata meta, BuildTree tree) {}, + onWidgets: (BuildMetadata meta, Iterable widgets) { + final Iterable results = [Container()]; + return results; + }, + onWidgetsIsOptional: false, + priority: 10, +}) +``` + + + +```dart +final newOp = BuildOp( + alwaysRenderBlock: true, + debugLabel: 'v0.14', + defaultStyles: (dom.Element element) { + final StylesMap styles = {'color': 'red'}; + return styles; + }, + onParsed: (BuildTree tree) => tree, + onRenderBlock: (BuildTree tree, WidgetPlaceholder placeholder) { + return Container(); + }, + onRenderInline: (BuildTree tree) {}, + onRenderedBlock: (BuildTree tree, Widget block) {}, + onVisitChild: (BuildTree tree, BuildTree subTree) {}, + priority: 10, +) +``` + +
+ +- `BuildMetadata` and `BuildTree` have been merged together so the callback signatures no longer require two arguments +- The roles of the callbacks are mostly the same, but we've changed their names to make them easier to understand +- The `defaultStyles` callback still has the same signature, but now the styles are added at the end of the list instead of the beginning +- `onTree` is now `onParsed` and allow you to return a new tree +- `onWidgets` is now `onRenderBlock`, and children widgets have been parsed into a single `WidgetPlaceholder`. This callback can wrap the placeholder or returning a new one as needed + +### BuildOp.inline + +In this version, we've introduce a new factory to simplify the rendering of custom inline widgets. If you were previously using `onTree` along with `detach`, `insertAfter`, or `insertBefore` for this purpose, we suggest giving `BuildOp.inline` a try for a more app developer friendly approach. As we continue improving things in the future, `BuildOp.inline` should be kept up to date and running smoothly. + +## TextStyleHtml + +### InheritedProperties + +The entire `TextStyleHtml` class has been marked as deprecated, its successor is the `InheritedProperties` class. However, if you have legacy code using `TextStyleHtml`, it will continue to work. + +### getDependency + +Similarly, the `getDependency` method has been deprecated, and you should use `get` to retrieve values by their type. It's worth noting that, for performance reasons, `v0.14` no longer depends on `MediaQueryData` to avoid excessive rebuild. Therefore, attempting to use either `getDependency` or `get` will not work. diff --git a/packages/core/CHANGELOG.md b/packages/core/CHANGELOG.md index 920e29eb5..56a7282e1 100644 --- a/packages/core/CHANGELOG.md +++ b/packages/core/CHANGELOG.md @@ -10,16 +10,20 @@ - Fix padding is ignored on empty P tag (#906) - Fix `border-radius` error if border is not uniform (#910) - Fix inline `white-space: nowrap` (#944) +- Fix `TR` background color doesn't fill the whole row by #1049 - MIGRATE: Replace `WidgetPlaceholder.generator` with `.debugLabel` (#619) - MIGRATE: Replace `WidgetFactory.gestureTapCallback` with `.buildGestureRecognizer` (#732) - MIGRATE: Replace `RebuildTriggers` with `List` - MIGRATE: Replace `BuildBit.detach`, `.insertAfter` and `.insertBefore` with returning a new tree in `BuildOp.onParsed` (#732) +- BREAKING: Remove `HtmlWidget.webViewXxx` properties #615 - BREAKING: Remove support for `box-sizing` (#903) - BREAKING: Remove `WidgetPlaceholder.autoUnwrap` (#906) - BREAKING: `.getDependency()` no longer works (#911) - BREAKING: Append `defaultStyles` instead of prepend (#1055) - BREAKING: Change default alignment of inline widget from `bottom` to `baseline` (#1056) +See migration document: https://github.com/daohoangson/flutter_widget_from_html/blob/master/docs/migration.md + ## 0.10.6 - Fix border 0 is still being rendered (#1045) diff --git a/packages/core/README.md b/packages/core/README.md index b5bffb993..96a8f92cf 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -1,6 +1,6 @@ # Flutter Widget from HTML (core) -![Flutter](https://github.com/daohoangson/flutter_widget_from_html/workflows/Flutter/badge.svg) +[![Flutter](https://github.com/daohoangson/flutter_widget_from_html/actions/workflows/flutter.yml/badge.svg)](https://github.com/daohoangson/flutter_widget_from_html/actions/workflows/flutter.yml) [![codecov](https://codecov.io/gh/daohoangson/flutter_widget_from_html/branch/master/graph/badge.svg)](https://codecov.io/gh/daohoangson/flutter_widget_from_html) [![Pub](https://img.shields.io/pub/v/flutter_widget_from_html_core.svg)](https://pub.dev/packages/flutter_widget_from_html_core) diff --git a/packages/enhanced/CHANGELOG.md b/packages/enhanced/CHANGELOG.md index 64aefc767..ae3d31e8b 100644 --- a/packages/enhanced/CHANGELOG.md +++ b/packages/enhanced/CHANGELOG.md @@ -10,16 +10,20 @@ - Fix padding is ignored on empty P tag (#906) - Fix `border-radius` error if border is not uniform (#910) - Fix inline `white-space: nowrap` (#944) +- Fix `TR` background color doesn't fill the whole row by #1049 - MIGRATE: Replace `WidgetPlaceholder.generator` with `.debugLabel` (#619) - MIGRATE: Replace `WidgetFactory.gestureTapCallback` with `.buildGestureRecognizer` (#732) - MIGRATE: Replace `RebuildTriggers` with `List` - MIGRATE: Replace `BuildBit.detach`, `.insertAfter` and `.insertBefore` with returning a new tree in `BuildOp.onParsed` (#732) +- BREAKING: Remove `HtmlWidget.webViewXxx` properties #615 - BREAKING: Remove support for `box-sizing` (#903) - BREAKING: Remove `WidgetPlaceholder.autoUnwrap` (#906) - BREAKING: `.getDependency()` no longer works (#911) - BREAKING: Append `defaultStyles` instead of prepend (#1055) - BREAKING: Change default alignment of inline widget from `bottom` to `baseline` (#1056) +See migration document: https://github.com/daohoangson/flutter_widget_from_html/blob/master/docs/migration.md + # 0.10.6 - Fix border 0 is still being rendered (#1045) diff --git a/packages/enhanced/README.md b/packages/enhanced/README.md index 0044992dc..4d9543506 100644 --- a/packages/enhanced/README.md +++ b/packages/enhanced/README.md @@ -1,6 +1,6 @@ # Flutter Widget from HTML -![Flutter](https://github.com/daohoangson/flutter_widget_from_html/workflows/Flutter/badge.svg) +[![Flutter](https://github.com/daohoangson/flutter_widget_from_html/actions/workflows/flutter.yml/badge.svg)](https://github.com/daohoangson/flutter_widget_from_html/actions/workflows/flutter.yml) [![codecov](https://codecov.io/gh/daohoangson/flutter_widget_from_html/branch/master/graph/badge.svg)](https://codecov.io/gh/daohoangson/flutter_widget_from_html) [![Pub](https://img.shields.io/pub/v/flutter_widget_from_html.svg)](https://pub.dev/packages/flutter_widget_from_html) diff --git a/packages/fwfh_cached_network_image/README.md b/packages/fwfh_cached_network_image/README.md index 84c928732..6e2394cb0 100644 --- a/packages/fwfh_cached_network_image/README.md +++ b/packages/fwfh_cached_network_image/README.md @@ -1,6 +1,6 @@ # CachedNetworkImageFactory -![Flutter](https://github.com/daohoangson/flutter_widget_from_html/workflows/Flutter/badge.svg) +[![Flutter](https://github.com/daohoangson/flutter_widget_from_html/actions/workflows/flutter.yml/badge.svg)](https://github.com/daohoangson/flutter_widget_from_html/actions/workflows/flutter.yml) [![codecov](https://codecov.io/gh/daohoangson/flutter_widget_from_html/branch/master/graph/badge.svg)](https://codecov.io/gh/daohoangson/flutter_widget_from_html) [![Pub](https://img.shields.io/pub/v/fwfh_cached_network_image.svg)](https://pub.dev/packages/fwfh_cached_network_image) diff --git a/packages/fwfh_chewie/README.md b/packages/fwfh_chewie/README.md index b6c2b269d..7b63adfa2 100644 --- a/packages/fwfh_chewie/README.md +++ b/packages/fwfh_chewie/README.md @@ -1,6 +1,6 @@ # ChewieFactory -![Flutter](https://github.com/daohoangson/flutter_widget_from_html/workflows/Flutter/badge.svg) +[![Flutter](https://github.com/daohoangson/flutter_widget_from_html/actions/workflows/flutter.yml/badge.svg)](https://github.com/daohoangson/flutter_widget_from_html/actions/workflows/flutter.yml) [![codecov](https://codecov.io/gh/daohoangson/flutter_widget_from_html/branch/master/graph/badge.svg)](https://codecov.io/gh/daohoangson/flutter_widget_from_html) [![Pub](https://img.shields.io/pub/v/fwfh_chewie.svg)](https://pub.dev/packages/fwfh_chewie) diff --git a/packages/fwfh_just_audio/README.md b/packages/fwfh_just_audio/README.md index 7413613b8..9310b1b90 100644 --- a/packages/fwfh_just_audio/README.md +++ b/packages/fwfh_just_audio/README.md @@ -1,6 +1,6 @@ # JustAudioFactory -![Flutter](https://github.com/daohoangson/flutter_widget_from_html/workflows/Flutter/badge.svg) +[![Flutter](https://github.com/daohoangson/flutter_widget_from_html/actions/workflows/flutter.yml/badge.svg)](https://github.com/daohoangson/flutter_widget_from_html/actions/workflows/flutter.yml) [![codecov](https://codecov.io/gh/daohoangson/flutter_widget_from_html/branch/master/graph/badge.svg)](https://codecov.io/gh/daohoangson/flutter_widget_from_html) [![Pub](https://img.shields.io/pub/v/fwfh_just_audio.svg)](https://pub.dev/packages/fwfh_just_audio) diff --git a/packages/fwfh_svg/README.md b/packages/fwfh_svg/README.md index 34c59de9a..b6825f425 100644 --- a/packages/fwfh_svg/README.md +++ b/packages/fwfh_svg/README.md @@ -1,6 +1,6 @@ # SvgFactory -![Flutter](https://github.com/daohoangson/flutter_widget_from_html/workflows/Flutter/badge.svg) +[![Flutter](https://github.com/daohoangson/flutter_widget_from_html/actions/workflows/flutter.yml/badge.svg)](https://github.com/daohoangson/flutter_widget_from_html/actions/workflows/flutter.yml) [![codecov](https://codecov.io/gh/daohoangson/flutter_widget_from_html/branch/master/graph/badge.svg)](https://codecov.io/gh/daohoangson/flutter_widget_from_html) [![Pub](https://img.shields.io/pub/v/fwfh_svg.svg)](https://pub.dev/packages/fwfh_svg) diff --git a/packages/fwfh_url_launcher/README.md b/packages/fwfh_url_launcher/README.md index 32153b860..13ba52fcc 100644 --- a/packages/fwfh_url_launcher/README.md +++ b/packages/fwfh_url_launcher/README.md @@ -1,6 +1,6 @@ # UrlLauncherFactory -![Flutter](https://github.com/daohoangson/flutter_widget_from_html/workflows/Flutter/badge.svg) +[![Flutter](https://github.com/daohoangson/flutter_widget_from_html/actions/workflows/flutter.yml/badge.svg)](https://github.com/daohoangson/flutter_widget_from_html/actions/workflows/flutter.yml) [![codecov](https://codecov.io/gh/daohoangson/flutter_widget_from_html/branch/master/graph/badge.svg)](https://codecov.io/gh/daohoangson/flutter_widget_from_html) [![Pub](https://img.shields.io/pub/v/fwfh_url_launcher.svg)](https://pub.dev/packages/fwfh_url_launcher) diff --git a/packages/fwfh_webview/README.md b/packages/fwfh_webview/README.md index 31d0aa2e4..f986c2ada 100644 --- a/packages/fwfh_webview/README.md +++ b/packages/fwfh_webview/README.md @@ -1,6 +1,6 @@ # WebViewFactory -![Flutter](https://github.com/daohoangson/flutter_widget_from_html/workflows/Flutter/badge.svg) +[![Flutter](https://github.com/daohoangson/flutter_widget_from_html/actions/workflows/flutter.yml/badge.svg)](https://github.com/daohoangson/flutter_widget_from_html/actions/workflows/flutter.yml) [![codecov](https://codecov.io/gh/daohoangson/flutter_widget_from_html/branch/master/graph/badge.svg)](https://codecov.io/gh/daohoangson/flutter_widget_from_html) [![Pub](https://img.shields.io/pub/v/fwfh_webview.svg)](https://pub.dev/packages/fwfh_webview)