Add info about MultilineBracketStyle to docs, fix issue with icons

docs/content/webcomponents.js

@@ -1,7 +1,7 @@
 import {html} from 'https://cdn.skypack.dev/lit';
 import {component} from 'https://cdn.skypack.dev/haunted';
 
-function FantomasSettingIcon(type) {
+function FantomasSettingIcon({type}) {
     let settingType
     switch (type) {
         case 'green':
@@ -20,7 +20,9 @@ function FantomasSettingIcon(type) {
             break;
         case 'red':
             settingType = {
-                icon: "bi-x-circle-fill", color: "red-recommendation", tooltip: "You shouldn't use this setting."
+                icon: "bi-x-circle-fill", 
+                color: "red-recommendation", 
+                tooltip: "You shouldn't use this setting."
             }
             break;
         case 'gr':
@@ -33,7 +35,7 @@ function FantomasSettingIcon(type) {
                              data-bs-title="${tooltip}"
                              src="${root}/images/gresearch.svg" alt="G-Research logo"/>`;
         default:
-            throw "The \"type\" can only be \"green\", \"orange\", \"red\" or \"gr\"";
+            throw `The "type" can only be "green", "orange", "red" or "gr". Found "${type}"`;
     }
     return html`<i class="bi ${settingType.icon} ${settingType.color} me-2"
                    data-bs-toggle="tooltip" data-bs-custom-class="${type}-tooltip"
@@ -51,21 +53,25 @@ function Navigation({next, previous}) {
         </div>`;
 }
 
-function FantomasSetting({name, green, orange, red, gr}) {
+function FantomasSetting({name, green, orange, red, gr, deprecated}) {
     return html`
         <div class="d-flex align-items-center my-2">
-            ${green && FantomasSettingIcon('green')}
-            ${orange && FantomasSettingIcon('orange')}
-            ${red && FantomasSettingIcon('red')}
-            ${gr && FantomasSettingIcon('gr')}
+            ${green && FantomasSettingIcon({type: "green"})}
+            ${orange && FantomasSettingIcon({type: "orange"})}
+            ${red && FantomasSettingIcon({type: "red"})}
+            ${gr && FantomasSettingIcon({type: "gr"})}
+            ${red && FantomasSettingIcon({type: "red"})}
             <h4 id="${name}" class="m-0">
                 <a href="#${name}">${name}</a>
             </h4>
         </div>`
 }
 
+customElements.define('fantomas-setting-icon', component(FantomasSettingIcon, {
+    useShadowDOM: false, observedAttributes: ['type']
+}));
 customElements.define('fantomas-setting', component(FantomasSetting, {
-    useShadowDOM: false, observedAttributes: ['name', 'green', 'orange', 'red', 'gr']
+    useShadowDOM: false, observedAttributes: ['name', 'green', 'orange', 'red', 'gr', 'deprecated']
 }));
 
 customElements.define('fantomas-nav', component(Navigation, {

docs/docs/end-users/Configuration.fsx

@@ -28,8 +28,7 @@ fsharp_bar_before_discriminated_union_declaration = true
 
 #\ Apply specific settings for a targeted subfolder
 [src/Elmish/View.fs]
-fsharp_multiline_block_brackets_on_same_column = true
-fsharp_experimental_stroustrup_style = true
+fsharp_multiline_bracket_style = experimental_stroustrup
 ```
 *)
 
@@ -56,15 +55,15 @@ However, there are settings that we do not recommend and generally should not be
 <p><fantomas-setting-icon type="green"></fantomas-setting-icon><strong>Safe to change:</strong> Settings that aren't attached to any guidelines. Depending on your team or your own preferences, feel free to change these as it's been agreed on the codebase, however, you can always use it's defaults.</p>
 <p><fantomas-setting-icon type="orange"></fantomas-setting-icon><strong>Use with caution:</strong> Settings where it is not recommended to change the default value. They might lead to incomplete results.</p>
 <p><fantomas-setting-icon type="red"></fantomas-setting-icon><strong>Do not use:</strong> Settings that don't follow any guidelines.</p>
-<p><fantomas-setting-icon-gresearch></fantomas-setting-icon-gresearch><strong>G-Research:</strong> G-Research styling guide. If you use one of these, for consistency reasons you should use all of them.</p>
+<p><fantomas-setting-icon type="gr"></fantomas-setting-icon><strong>G-Research:</strong> G-Research styling guide. If you use one of these, for consistency reasons you should use all of them.</p>
 *)
 
 (**
 ## Auxiliary settings
 
 <fantomas-setting name="indent_size" orange></fantomas-setting>
 
-` indent_size` has to be between 1 and 10.
+`indent_size` has to be between 1 and 10.
 
 This preference sets the indentation
 The common values are 2 and 4.  
@@ -573,46 +572,67 @@ formatCode
 (*** include-it ***)
 
 (**
-## G-Research style
+<fantomas-setting name="fsharp_multiline_bracket_style" green></fantomas-setting>
 
-A series of settings required to conform with the [G-Research style guide](https://github.com/G-Research/fsharp-formatting-conventions).  
-From a consistency point of view, it is recommend to enable all these settings instead of cherry-picking a few.
+How to format bracketted expressions (e.g. records, arrays, lists, etc.) that span multiple lines. 
 
-<fantomas-setting name="fsharp_multiline_block_brackets_on_same_column" green gr></fantomas-setting>
+_This setting replaces the deprecated settings `fsharp_multiline_block_brackets_on_same_column` and `fsharp_experimental_stroustrup_style`._
 
-Alternative way of formatting records, arrays and lists. This will align the braces at the same column level.
+Possible values:
 
-Default = false.
+* `cramped`
+* `aligned`
+* `experimental_stroustrup`
+
+Default = `cramped`.
 *)
 
+(**
+**Cramped** - The default way in F# to format brackets.  
+*)
 formatCode
     """ 
-    let myRecord =
-        { Level = 1
-          Progress = "foo"
-          Bar = "bar"
-          Street = "Bakerstreet"
-          Number = 42 }
+    let band = { Vocals = "John"; Bass = "Paul"; Guitar = "George"; Drums = "Ringo" }
+    let songs = [ "Come Together"; "Hey Jude"; "Yesterday"; "Yellow Submarine"; "Here Comes the Sun" ]
+    """
+    { FormatConfig.Default with
+        MultilineBracketStyle = Cramped }
+(*** include-it ***)
 
-    type Range =
-        { From: float
-          To: float
-          FileName: string }
+(**
+**Aligned** - Alternative way of formatting brackets. This will align the braces at the same column level.
+*)
 
-    let a =
-        [| (1, 2, 3)
-           (4, 5, 6)
-           (7, 8, 9)
-           (10, 11, 12)
-           (13, 14, 15)
-           (16, 17,18)
-           (19, 20, 21) |]
+formatCode
+    """ 
+    let band = { Vocals = "John"; Bass = "Paul"; Guitar = "George"; Drums = "Ringo" }
+    let songs = [ "Come Together"; "Hey Jude"; "Yesterday"; "Yellow Submarine"; "Here Comes the Sun" ]
     """
     { FormatConfig.Default with
         MultilineBracketStyle = Aligned }
 (*** include-it ***)
 
 (**
+**ExperimentalStroustrup** - Experimental setting. Places the opening brace on the same line as the binding, and the closing brace on its own line.
+
+_Please contribute to [fsprojects/fantomas#1408](https://github.com/fsprojects/fantomas/issues/1408) and engage in [fsharp/fslang-design#706](https://github.com/fsharp/fslang-design/issues/706)._
+*)
+
+formatCode
+    """ 
+    let band = { Vocals = "John"; Bass = "Paul"; Guitar = "George"; Drums = "Ringo" }
+    let songs = [ "Come Together"; "Hey Jude"; "Yesterday"; "Yellow Submarine"; "Here Comes the Sun" ]
+    """
+    { FormatConfig.Default with
+        MultilineBracketStyle = ExperimentalStroustrup }
+(*** include-it ***)
+
+(**
+## G-Research style
+
+A series of settings required to conform with the [G-Research style guide](https://github.com/G-Research/fsharp-formatting-conventions).  
+From a consistency point of view, it is recommend to enable all these settings instead of cherry-picking a few.
+
 <fantomas-setting name="fsharp_newline_between_type_definition_and_members" green gr></fantomas-setting>
 
 Adds a new line between a type definition and its first member.
@@ -767,27 +787,6 @@ formatCode
 
 Some additional settings that don't fit into any style guide.
 
-<fantomas-setting name="fsharp_experimental_stroustrup_style" orange></fantomas-setting>
-
-Please contribute to [fsprojects/fantomas#1408](https://github.com/fsprojects/fantomas/issues/1408) and engage in [fsharp/fslang-design#706](https://github.com/fsharp/fslang-design/issues/706).
-
-Default = false.
-
-Requires `fsharp_multiline_block_brackets_on_same_column` to be `true` to take effect.
-*)
-
-formatCode
-    """
-type PostalAddress =
-    { Address: string
-      City: string
-      Zip: string }
-"""
-    { FormatConfig.Default with
-        MultilineBracketStyle = MultilineBracketStyle.ExperimentalStroustrup }
-(*** include-it ***)
-
-(**
 <fantomas-setting name="fsharp_blank_lines_around_nested_multiline_expressions" green></fantomas-setting>
 
 Surround **nested** multi-line expressions with blank lines.  

fantomas.sln

@@ -16,6 +16,7 @@ EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{29F22904-C9E0-40AA-B971-9AE377C17F59}"
 	ProjectSection(SolutionItems) = preProject
 		docs\index.html = docs\index.html
+		docs\.README.md = docs\.README.md
 	EndProjectSection
 EndProject
 Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "Fantomas.Client", "src\Fantomas.Client\Fantomas.Client.fsproj", "{AA895F94-CCF2-4FCF-A9BB-E16987B57535}"