flutter_html_css_border

pub version pipeline license GitLab

A flutter_html extension that renders the CSS border longhands. flutter_html 3.0.0 parses five border properties, all shorthands: border, border-top, border-right, border-bottom and border-left. It drops the other 39 property names, and there is no error and no warning. It rewrites the longhands into those five shorthands before flutter_html parses the style. List it after a utility-class extension and before CssBorderRadiusHtmlExtension.

Contents

Features

  • At the preStyling step the extension resolves the cascade of every border declaration in the inline style, removes them all, and appends the result as the five shorthands. flutter_html then renders the border itself; nothing here paints. Declarations it does not consume keep their text and their order.
  • It reads 39 property names: border-width, border-style, border-color, the twelve per-side longhands and every logical form, listed in doc/properties.md.
  • It reads the five shorthands too, so border: 1px solid red; border-top-width: 6px gives a six-pixel top side and one-pixel sides elsewhere.
  • dashed, dotted, double, groove, ridge, inset and outset render as one solid line. Flutter's BorderSide.style has solid and none only.
  • A side with no colour uses the element's own inline color. With none, it renders black; a color on an ancestor is not visible at this step. There is no error and no warning.
  • An element whose inline style carries no border longhand gets no change.

Getting started

dependencies:
  flutter_html: ^3.0.0
  flutter_html_css_border: ^0.2.0

Usage

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

Html(
  data: '''
    <div style="border-width: 2px; border-style: solid; border-color: #0d6efd;
                padding: 12px;">
      Two pixels of blue.
    </div>
  ''',
  extensions: const [CssBorderHtmlExtension()],
);

Before you register it

This extension matches on the inline style, never on the tag name. It cannot make flutter_html render a tag that has no renderer. A TagExtension does that.

A utility-class extension, this extension and CssBorderRadiusHtmlExtension all write to the same style attribute at the preStyling step. flutter_html runs them in registration order. Use this one:

// Also needs flutter_html_bootstrap and
// flutter_html_css_border_radius.
Html(
  data: '<div class="p-3" '
      'style="border-radius: 8px; border-width: 2px; border-style: solid;">'
      'Card</div>',
  extensions: const [
    BootstrapUtilitiesHtmlExtension(), // renders `p-3`
    CssBorderHtmlExtension(),          // resolves the border
    CssBorderRadiusHtmlExtension(),    // rounds and clips
  ],
);

Listed before the utility-class extension, this extension reads the style attribute before those classes expand into it. It misses the longhands they add, and flutter_html drops them. There is no error and no warning.

Listed after CssBorderRadiusHtmlExtension, it never sees the border. That extension strips every border declaration that is not a radius, and it reads no border-style:

Html(
  data: '<div style="border-radius: 12px; border-width: 2px; border-style: none;">'
      'Card</div>',
  extensions: const [
    CssBorderRadiusHtmlExtension(), // renders a 2px border; CSS renders none
    CssBorderHtmlExtension(),
  ],
);

The order matrix has all four arrangements measured.

Released flutter_html_bootstrap 0.1.1 and flutter_html_vuetify 0.1.0 do not recognise CssBorderHtmlExtension. Both therefore still suppress the classes this extension could render. Write the border into an inline style attribute until a release of theirs lists it.

Limitations

  • border-width on its own renders nothing, as in CSS, where border-style starts at none. Declare border-style beside the width. hidden renders nothing too.
  • Next to CssBorderRadiusHtmlExtension, a rounded element renders only the side that occurs most often. That extension reads the border shorthand and no per-side declaration. There is no error and no warning.
  • flutter_html renders a border only for a list item, or a block or inline-block element with children. A plain <span> or an empty <div> renders none, with this extension and without it. There is no error and no warning.
  • A TagExtension builds its own widget and never reads a Style, so an element it builds has no border. Use a TagWrapExtension instead.
  • Widths follow flutter_html's arithmetic. thin, medium and thick are 2, 4 and 6 pixels, where a browser uses 1, 3 and 5. Every length unit is read as its bare number, so 0.5rem is half a pixel. The rounded border that flutter_html_css_border_radius draws resolves the same 0.5rem against a root font size of 14, so it is 7 pixels there. flutter_html_css_font_size will close this gap.
  • An eight-digit #rrggbbaa colour renders with its channels transposed. flutter_html reads it as #aarrggbb. There is no error and no warning.
  • The extension does not read border-image, border-collapse, border-spacing or border-radius.
  • The extension reads the inline style only. It does not read <style> blocks or stylesheets.

The full reasoning for each one is on the symbol that implements it.

Additional information

Issues and merge requests go to the GitLab repository. Rounding the same element's corners is flutter_html_css_border_radius's job.

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

Libraries

flutter_html_css_border