package:dart_style v3.1.0

This release contains a fairly large number of style changes in response to feedback we got from shipping the new tall style formatter.

Features

• Allow preserving trailing commas and forcing the surrounding construct to split even when it would otherwise fit on one line. This is off by default (because it breaks reversibility among other reasons) but can be enabled by adding this to a surrounding analysis_options.yaml file:

  formatter:
    trailing_commas: preserve

  This is similar to how trailing commas work in the old short style formatter applied to code before language version 3.7.

Bug fixes

• Don't add a trailing comma in lists that don't allow it, even when there is a trailing comment (#1639).

Style changes

The following style changes are language versioned and only affect code whose language version is 3.8 or later. Dart code at 3.7 or earlier is formatted the same as it was before.

• Allow more code on the same line as a named argument or => (#1536, #1545, #1668, #1679).

  // Before:
  function(
    name:
        (param, another) =>
            veryLongBody,
  );
  
  function(
    name:
        (param) => another(
          argument1,
          argument2,
          argument3,
        ),
  );
  
  // After:
  function(
    name: (param, another) =>
        veryLongBody,
  );
  
  function(
    name: (param) => another(
      argument1,
      argument2,
      argument3,
    ),
  );

• Avoid splitting chains containing only properties.

  // Before:
  variable = target
      .property
      .another;
  
  // After:
  variable =
      target.property.another;

  Note that this only applies to . chains that are only properties. If there are method calls in the chain, then it prefers to split the chain instead of splitting at =, :, or =>.

• Allow the target or property chain part of a split method chain on the RHS of =, :, and => (#1466).

  // Before:
  variable =
      target.property
          .method()
          .another();
  
  // After:
  variable = target.property
      .method()
      .another();

• Allow the condition part of a split conditional expression on the RHS of =, :, and => (#1465).

  // Before:
  variable =
      condition
      ? longThenBranch
      : longElseBranch;
  
  // After:
  variable = condition
      ? longThenBranch
      : longElseBranch;

• Don't indent conditional branches redundantly after =, :, and =>.

  // Before:
  function(
    argument:
        condition
            ? thenBranch
            : elseBranch,
  )
  
  // After:
  function(
    argument:
        condition
        ? thenBranch
        : elseBranch,
  )

• Indent conditional branches past the operators (#1534).

  // Before:
  condition
      ? thenBranch +
          anotherOperand
      : elseBranch(
        argument,
      );
  
  // After:
  condition
      ? thenBranch +
            anotherOperand
      : elseBranch(
          argument,
        );

• Block format record types in typedefs (#1651):

  // Before:
  typedef ExampleRecordTypedef =
      (
        String firstParameter,
        int secondParameter,
        String thirdParameter,
        String fourthParameter,
      );
  
  // After:
  typedef ExampleRecordTypedef = (
    String firstParameter,
    int secondParameter,
    String thirdParameter,
    String fourthParameter,
  );

• Eagerly split argument lists whose contents are complex enough to be easier to read spread across multiple lines even if they would otherwise fit on a single line (#1660). The rules are basically:

  • If an argument list contains at least three named arguments, at least one of which must be directly in the argument list and at least one of which must be nested in an inner argument list, then force the outer one to split. We make an exception where a named argument whose expression is a simple number, Boolean, or null literal doesn't count as a named argument.

  • If a list, set, or map literal is the immediate expression in a named argument and contains any argument lists with a named argument, then force the collection to split.

  // Before:
  TabBar(tabs: [Tab(text: 'A'), Tab(text: 'B')], labelColor: Colors.white70);
  
  // After:
  TabBar(
    tabs: [
      Tab(text: 'A'),
      Tab(text: 'B'),
    ],
    labelColor: Colors.white70,
  );