Improve multiline printing of record types and values (#7993)

* WIP

* Update tests

* Change how force_break is handled in type declaration printing

* Fix type declaration with spread

* Update tests

* Update more tests (ppx)

* Update CHANGELOG

* Add note on the formatter philosophy

---------

Co-authored-by: nojaf <florian.verdonck@outlook.com>

Author: shulhi

CHANGELOG.md

@@ -32,6 +32,8 @@
 
 #### :nail_care: Polish
 
+- Formatter: Improve multiline printing of record types and values. https://github.com/rescript-lang/rescript/pull/7993
+
 #### :house: Internal
 
 - Reanalyze: refactor DCE to pure pipeline architecture for order-independence and incremental update support. https://github.com/rescript-lang/rescript/pull/8043

compiler/syntax/src/res_printer.ml

@@ -1282,7 +1282,7 @@ and print_type_declaration ~state ~name ~equal_sign ~rec_flag i
           manifest;
           Doc.concat [Doc.space; Doc.text equal_sign; Doc.space];
           print_private_flag td.ptype_private;
-          print_record_declaration ~state lds cmt_tbl;
+          print_record_declaration ~record_loc:td.ptype_loc ~state lds cmt_tbl;
         ]
     | Ptype_variant cds ->
       let manifest =
@@ -1370,8 +1370,8 @@ and print_type_declaration2 ?inline_record_definitions ~state ~rec_flag
             manifest;
             Doc.concat [Doc.space; Doc.text equal_sign; Doc.space];
             print_private_flag td.ptype_private;
-            print_record_declaration ?inline_record_definitions ~state lds
-              cmt_tbl;
+            print_record_declaration ?inline_record_definitions
+              ~record_loc:td.ptype_loc ~state lds cmt_tbl;
           ]
     | Ptype_variant cds ->
       let manifest =
@@ -1465,12 +1465,22 @@ and print_type_param ~state (param : Parsetree.core_type * Asttypes.variance)
   Doc.concat [printed_variance; print_typ_expr ~state typ cmt_tbl]
 
 and print_record_declaration ?check_break_from_loc ?inline_record_definitions
-    ~state (lds : Parsetree.label_declaration list) cmt_tbl =
+    ?record_loc ~state (lds : Parsetree.label_declaration list) cmt_tbl =
+  let get_field_start_line (ld : Parsetree.label_declaration) =
+    (* For spread fields (...), use the type location instead of pld_loc
+       because pld_loc may incorrectly include preceding whitespace *)
+    if ld.pld_name.txt = "..." then ld.pld_type.ptyp_loc.loc_start.pos_lnum
+    else ld.pld_loc.loc_start.pos_lnum
+  in
   let force_break =
-    match (check_break_from_loc, lds, List.rev lds) with
+    match (check_break_from_loc, record_loc, lds) with
     | Some loc, _, _ -> loc.Location.loc_start.pos_lnum < loc.loc_end.pos_lnum
-    | _, first :: _, last :: _ ->
-      first.pld_loc.loc_start.pos_lnum < last.pld_loc.loc_end.pos_lnum
+    | None, Some loc, first :: _ ->
+      (* Check if first field is on a different line than the opening brace *)
+      loc.loc_start.pos_lnum < get_field_start_line first
+    | None, None, first :: _ ->
+      let last = List.hd (List.rev lds) in
+      get_field_start_line first < last.pld_loc.loc_end.pos_lnum
     | _, _, _ -> false
   in
   Doc.breakable_group ~force_break
@@ -3223,7 +3233,14 @@ and print_expression ~state (e : Parsetree.expression) cmt_tbl =
          *   b: 2,
          *  }` -> record is written on multiple lines, break the group *)
         let force_break =
-          e.pexp_loc.loc_start.pos_lnum < e.pexp_loc.loc_end.pos_lnum
+          match (spread_expr, rows) with
+          | Some expr, _ ->
+            (* If there's a spread, compare with spread expression's location *)
+            e.pexp_loc.loc_start.pos_lnum < expr.pexp_loc.loc_start.pos_lnum
+          | None, first_row :: _ ->
+            (* Otherwise, compare with the first row's location *)
+            e.pexp_loc.loc_start.pos_lnum < first_row.lid.loc.loc_start.pos_lnum
+          | None, [] -> false
         in
         let punning_allowed =
           match (spread_expr, rows) with

docs/Formatter.md

@@ -0,0 +1,48 @@
+# ReScript Formatter
+
+## Philosophy
+
+The ReScript formatter is **opinionated**. Formatting decisions are made by the core team based on our collective judgment and vision for the language. We do not aim to accommodate every stylistic preference or engage in extended debates about formatting choices.
+
+The formatter currently has **no configuration settings**, and we aspire to keep it that way. This ensures that ReScript code looks consistent across all projects and teams, eliminating style debates and configuration overhead.
+
+## Decision Making
+
+- **Core team consensus is final**: When the core team reaches consensus on a formatting decision, that decision stands. There is no requirement for community-wide agreement or extensive discussion.
+
+- **Community input is welcome but not binding**: We appreciate suggestions and feedback from the community, but these can be closed without extensive justification if the core team is not aligned with the proposal.
+
+- **No endless style discussions**: We are not interested in protracted debates about formatting preferences. The formatter exists to provide consistent, automated formatting—not to serve as a platform for style negotiations.
+
+## Prior Decisions
+
+The following are examples of formatting decisions the core team has made. This list is not exhaustive, and these decisions do not create binding precedents for future discussions. The core team retains full discretion to make different decisions in similar cases.
+
+- **Smart linebreaks for pipe chains**: The formatter preserves user-introduced linebreaks in pipe chains (`->`), allowing users to control multiline formatting. See [forum announcement](https://forum.rescript-lang.org/t/ann-smart-linebreaks-for-pipe-chains/4734).
+
+- **Preserve multilineness for records**: The formatter preserves multiline formatting for record types and values when users introduce linebreaks. See [issue #7961](https://github.com/rescript-lang/rescript/issues/7961).
+
+**Important**: These examples are provided for reference only. They do not establish rules or precedents that constrain future formatting decisions. The core team may choose different approaches in similar situations based on current consensus.
+
+## Guidelines for Contributors
+
+### Submitting Formatting Issues
+
+- You may open issues to report bugs or propose improvements
+- Understand that proposals may be closed if they don't align with core team vision
+- Avoid reopening closed issues unless there's new technical information
+- Respect that "the core team isn't feeling it" is a valid reason for closure
+
+### What We Consider
+
+- Technical correctness and consistency
+- Alignment with ReScript's design philosophy
+- Maintainability and simplicity of the formatter implementation
+- Core team consensus
+
+### What We Generally Avoid
+
+- Style preferences that don't align with our vision
+- Using comparisons to other formatters as the sole justification for changes (while we may align with other formatters on many decisions, we make choices based on our own judgment, not because another formatter does it)
+- Requests that would significantly complicate the formatter implementation
+- Debates about subjective formatting choices

tests/syntax_tests/data/ast-mapping/expected/JSXElements.res.txt

@@ -2,19 +2,9 @@ let emptyUnary = ReactDOM.jsx("input", {})
 
 let emptyNonunary = ReactDOM.jsx("div", {})
 
-let emptyUnaryWithAttributes = ReactDOM.jsx(
-  "input",
-  {
-    type_: "text",
-  },
-)
+let emptyUnaryWithAttributes = ReactDOM.jsx("input", {type_: "text"})
 
-let emptyNonunaryWithAttributes = ReactDOM.jsx(
-  "div",
-  {
-    className: "container",
-  },
-)
+let emptyNonunaryWithAttributes = ReactDOM.jsx("div", {className: "container"})
 
 let elementWithChildren = ReactDOM.jsxs(
   "div",

tests/syntax_tests/data/ppx/react/expected/aliasProps.res.txt

@@ -2,7 +2,10 @@
 
 module C0 = {
   @res.jsxComponentProps
-  type props<'priority, 'text> = {priority: 'priority, text?: 'text}
+  type props<'priority, 'text> = {
+    priority: 'priority,
+    text?: 'text,
+  }
 
   let make = ({priority: _, text: ?__text, _}: props<_, _>) => {
     let text = switch __text {
@@ -20,7 +23,10 @@ module C0 = {
 
 module C1 = {
   @res.jsxComponentProps
-  type props<'priority, 'text> = {priority: 'priority, text?: 'text}
+  type props<'priority, 'text> = {
+    priority: 'priority,
+    text?: 'text,
+  }
 
   let make = ({priority: p, text: ?__text, _}: props<_, _>) => {
     let text = switch __text {
@@ -38,7 +44,9 @@ module C1 = {
 
 module C2 = {
   @res.jsxComponentProps
-  type props<'foo> = {foo?: 'foo}
+  type props<'foo> = {
+    foo?: 'foo,
+  }
 
   let make = ({foo: ?__bar, _}: props<_>) => {
     let bar = switch __bar {
@@ -56,7 +64,11 @@ module C2 = {
 
 module C3 = {
   @res.jsxComponentProps
-  type props<'foo, 'a, 'b> = {foo?: 'foo, a?: 'a, b: 'b}
+  type props<'foo, 'a, 'b> = {
+    foo?: 'foo,
+    a?: 'a,
+    b: 'b,
+  }
 
   let make = ({foo: ?__bar, a: ?__a, b, _}: props<_, _, _>) => {
     let bar = switch __bar {
@@ -82,7 +94,10 @@ module C3 = {
 
 module C4 = {
   @res.jsxComponentProps
-  type props<'a, 'x> = {a: 'a, x?: 'x}
+  type props<'a, 'x> = {
+    a: 'a,
+    x?: 'x,
+  }
 
   let make = ({a: b, x: ?__x, _}: props<_, _>) => {
     let x = switch __x {
@@ -100,7 +115,10 @@ module C4 = {
 
 module C5 = {
   @res.jsxComponentProps
-  type props<'a, 'z> = {a: 'a, z?: 'z}
+  type props<'a, 'z> = {
+    a: 'a,
+    z?: 'z,
+  }
 
   let make = ({a: (x, y), z: ?__z, _}: props<_, _>) => {
     let z = switch __z {
@@ -124,7 +142,10 @@ module C6 = {
     let make: React.component<props>
   }
   @res.jsxComponentProps
-  type props<'comp, 'x> = {comp: 'comp, x: 'x}
+  type props<'comp, 'x> = {
+    comp: 'comp,
+    x: 'x,
+  }
 
   let make = ({comp: module(Comp: Comp), x: (a, b), _}: props<_, _>): React.element =>
     React.jsx(Comp.make, {})

tests/syntax_tests/data/ppx/react/expected/asyncAwait.res.txt

@@ -2,7 +2,9 @@ let f = a => Js.Promise.resolve(a + a)
 
 module C0 = {
   @res.jsxComponentProps
-  type props<'a> = {a: 'a}
+  type props<'a> = {
+    a: 'a,
+  }
 
   let make = async ({a, _}: props<_>) => {
     let a = await f(a)
@@ -17,7 +19,9 @@ module C0 = {
 
 module C1 = {
   @res.jsxComponentProps
-  type props<'status> = {status: 'status}
+  type props<'status> = {
+    status: 'status,
+  }
 
   let make = async ({status, _}: props<_>): React.element => {
     switch status {

tests/syntax_tests/data/ppx/react/expected/commentAtTop.res.txt

@@ -1,5 +1,7 @@
 @res.jsxComponentProps
-type props<'msg> = {msg: 'msg} // test React JSX file
+type props<'msg> = {
+  msg: 'msg, // test React JSX file
+}
 
 let make = ({msg, _}: props<_>): React.element => {
   ReactDOM.jsx("div", {children: ?ReactDOM.someElement({msg->React.string})})

tests/syntax_tests/data/ppx/react/expected/defaultValueProp.res.txt

@@ -1,6 +1,9 @@
 module C0 = {
   @res.jsxComponentProps
-  type props<'a, 'b> = {a?: 'a, b?: 'b}
+  type props<'a, 'b> = {
+    a?: 'a,
+    b?: 'b,
+  }
   let make = ({a: ?__a, b: ?__b, _}: props<_, _>) => {
     let a = switch __a {
     | Some(a) => a
@@ -20,7 +23,10 @@ module C0 = {
 
 module C1 = {
   @res.jsxComponentProps
-  type props<'a, 'b> = {a?: 'a, b: 'b}
+  type props<'a, 'b> = {
+    a?: 'a,
+    b: 'b,
+  }
 
   let make = ({a: ?__a, b, _}: props<_, _>) => {
     let a = switch __a {
@@ -39,7 +45,9 @@ module C1 = {
 module C2 = {
   let a = "foo"
   @res.jsxComponentProps
-  type props<'a> = {a?: 'a}
+  type props<'a> = {
+    a?: 'a,
+  }
 
   let make = ({a: ?__a, _}: props<_>) => {
     let a = switch __a {
@@ -57,7 +65,9 @@ module C2 = {
 
 module C3 = {
   @res.jsxComponentProps
-  type props<'disabled> = {disabled?: 'disabled}
+  type props<'disabled> = {
+    disabled?: 'disabled,
+  }
 
   let make = ({disabled: ?__everythingDisabled, _}: props<bool>) => {
     let everythingDisabled = switch __everythingDisabled {

tests/syntax_tests/data/ppx/react/expected/externalWithCustomName.res.txt

@@ -2,7 +2,10 @@
 
 module Foo = {
   @res.jsxComponentProps @live
-  type props<'a, 'b> = {a: 'a, b: 'b}
+  type props<'a, 'b> = {
+    a: 'a,
+    b: 'b,
+  }
 
   @module("Foo")
   external component: React.component<props<int, string>> = "component"

tests/syntax_tests/data/ppx/react/expected/fileLevelConfig.res.txt

@@ -2,7 +2,9 @@
 
 module V4A = {
   @res.jsxComponentProps
-  type props<'msg> = {msg: 'msg}
+  type props<'msg> = {
+    msg: 'msg,
+  }
 
   let make = ({msg, _}: props<_>): React.element => {
     ReactDOM.jsx("div", {children: ?ReactDOM.someElement({msg->React.string})})