flutter_html_css_all

pub version pipeline license GitLab

One dependency and one import for the flutter_html extension packages of this family, in the registration order their own rules require. It re-exports twenty-one packages and registers nineteen of them. The classes are the siblings' own, so the Bootstrap and Vuetify registries still recognise each one.

Contents

Features

  • const BundledCssExtensions() is the nineteen, a List<HtmlExtension>, in the load order the siblings state. That order is fixed here by hand from their fourteen rules and pinned by this package's tests. kBundledCssExtensions is the same const instance; bundledCssExtensions() is the function form.
  • Your own extensions go in through before, after and inserts, all const, or through a plain list spread, [...const BundledCssExtensions(), ...].
  • Nothing is wrapped. runtimeType.toString() is unchanged for every class.
  • Arguments for the settings that change what renders: resolvePercentages, rootFontSize, viewportSize, extraCursors, imgAlt and the image arguments. Each reaches every extension that reads it, including all three that resolve a rem and both that read an <img> source.

Getting started

dependencies:
  flutter_html: ^3.0.0
  flutter_html_css_all: ^0.2.0

Usage

import 'package:flutter_html/flutter_html.dart';
import 'package:flutter_html_css_all/flutter_html_css_all.dart';

Html(
  data: '<div style="border-radius: 12px; overflow: hidden; width: 50%;">'
      'Card</div>',
  extensions: const BundledCssExtensions(),
);

Three arguments change what the bundle registers:

  • stylesheetExtension: pass a CssStylesheetHtmlExtension() when the document carries <style> blocks or you load a stylesheet string. It is off by default, because it takes over the cascade for <style> blocks and empties each block it reads, so flutter_html itself renders differently once it is on.
  • utilityClassExtensions: pass a list holding a BootstrapUtilitiesHtmlExtension(), a VuetifyHtmlExtension() or both, when the markup uses those classes. Add each package to your own pubspec.yaml; this package depends on neither, because a reader picks. Both can be registered together. Three class names are defined by both frameworks, rounded, border and text-truncate, and they resolve to different CSS: Bootstrap's rounded is a border-radius of 0.375rem, Vuetify's is 4px. Each extension appends its declarations to the element's inline style, so for a shared class name the one registered later wins, because its declaration is appended last. The single-valued utilityClassExtension is deprecated; it still works and is registered ahead of the list.
  • rootFontSize: pass your app's base size when it is not flutter_html's 14. It reaches all three extensions that resolve a rem.
  • viewportSize: pass a size and vw, vh, vmin and vmax resolve against it instead of against MediaQuery, which is what CssUnitsHtmlExtension reads by default.
Html(
  data: '<style>.card { letter-spacing: 0.1em }</style>'
      '<div class="card p-3">Card</div>',
  extensions: const BundledCssExtensions(
    stylesheetExtension: CssStylesheetHtmlExtension(),
    utilityClassExtensions: [BootstrapUtilitiesHtmlExtension()],
    rootFontSize: 16,
  ),
);

Before you register it

Your own extensions go in through before and after, or through a spread, [...const BundledCssExtensions(), TagExtension(...)]:

extensions: BundledCssExtensions(
  before: [
    ImageExtension(
      assetSchema: 'bundle:',
      builder: (context) =>
          Image.asset(context.attributes['src']!.replaceFirst('bundle:', '')),
    ), // before, or the alt-text extension claims the image first
  ],
  after: [
    TagExtension(tagsToExtend: const {'v-card'}, child: const Text('Card')),
  ], // after, or it wins the step twelve of the nineteen need
),

An ImageExtension with a custom assetSchema renders a source the built-in renderer declines. ImgAltHtmlExtension is the last bundled entry and claims exactly those, so listed after it the image renders as its alt text. There is no error and no warning. imgAlt: false is the other way out.

A TagExtension matches on the tag name at every step and builds the element outright. Listed before a bundled extension, it wins the step that extension needs, and the property is dropped. There is no error and no warning.

An extension that must run at a fixed point goes in with Insert.before(CssBorderRadiusHtmlExtension, [...]), Insert.after or Insert.at, which takes a function from the current list to an index. An anchor that is not in the list throws, so a typo cannot land the entry at the end.

extensions: const BundledCssExtensions(
  inserts: [Insert.before(CssBorderRadiusHtmlExtension, [MyCornerExtension()])],
),

doc/order.md lists the fourteen ordering rules and the render failure each one prevents.

Limitations

This package adds no CSS of its own. Each property renders through its sibling, under that sibling's limits. The three that reach every user of the bundle:

  • A utility-class extension suppresses a declaration whose companion it does not recognise. Bootstrap 0.1.3 recognises nine of the nineteen and Vuetify 0.1.2 eight, so only the border longhands and overflow classes stay suppressed and are named through FlutterError. Write those properties into an inline style. Colour and line-height need no entry: neither package suppresses them.
  • A percentage width or max-width inserts a LayoutBuilder, which cannot do dry layout. Pass resolvePercentages: false under an IntrinsicHeight or an IntrinsicWidth.
  • <div style="width: 50%; max-width: 100px"> renders 50 logical pixels in a containing block of 784. CSS says 100. No order of the two extensions gives 100; this one keeps the clamp and errs small.

More details, per package:

kFlutterHtmlRootFontSize is the family's root font size, and it is 14. This package hides flutter_html_css_size_constraints's older kFlutterHtmlDefaultFontSize, which its 0.1.1 deprecates.

Additional information

Repository: gitlab.com/Chaos02_Flutter/flutter_html_css_all. The twenty-one siblings are on pub.flutter-io.cn and in the same GitLab group, each with its own README.

CI, publishing and Renovate are described in CONTRIBUTING.md.

Libraries

flutter_html_css_all
One dependency and one import for the flutter_html extension packages of this family, plus the registration order they have to be listed in.