Replace white-space utilities with text-wrap utilities, add new ones

Author: mdo

scss/_utilities.scss

@@ -624,20 +624,22 @@ $utilities: map.merge(
       class: text,
       values: lowercase uppercase capitalize
     ),
-    "white-space": (
-      property: white-space,
-      class: text,
-      values: (
-        wrap: normal,
-        nowrap: nowrap,
-      )
-    ),
     "word-wrap": (
       property: word-wrap word-break,
       class: text,
       values: (break: break-word),
       rtl: false
     ),
+    "text-wrap": (
+      property: text-wrap,
+      class: text,
+      values: (
+        balance: balance,
+        nowrap: nowrap,
+        pretty: pretty,
+        wrap: wrap,
+      )
+    ),
     // scss-docs-end utils-text
     // scss-docs-start utils-color
     "color-attr": (

site/src/content/docs/utilities/text.mdx

@@ -120,12 +120,12 @@ Easily realign text to components with text alignment classes. For start, end, a
 Note that we don’t provide utility classes for justified text. While, aesthetically, justified text might look more appealing, it does make word-spacing more random and therefore harder to read.
 </Callout>
 
-## Text wrapping and overflow
+## Text wrap
 
 Wrap text with a `.text-wrap` class.
 
-<Example code={`<div class="badge text-bg-primary text-wrap" style="width: 6rem;">
-    This text should wrap.
+<Example code={`<div class="text-wrap bg-body-secondary border" style="width: 8rem;">
+    This snippet of text should wrap.
   </div>`} />
 
 Prevent text from wrapping with a `.text-nowrap` class.
@@ -134,6 +134,18 @@ Prevent text from wrapping with a `.text-nowrap` class.
     This text should overflow the parent.
   </div>`} />
 
+Use `.text-balance` to balance evenly distribute text across multiple lines. This is computationally expensive and is thus limited by the Chromium to six lines and by Firefox to ten lines.
+
+<Example code={`<div class="text-balance mx-auto" style="width: 20rem;">
+    This text should be balanced. Here we’re writing a longer snippet of text to form a paragraph and demonstrate how the text wraps.
+  </div>`} />
+
+Use `.text-pretty` to prevent single words their own line (orphans). **Pretty text wrapping is not fully supported in Safari and Firefox at the moment.**
+
+<Example code={`<div class="text-pretty mx-auto" style="width: 20rem;">
+    This text should be pretty. Here we’re writing a longer snippet of text to form a paragraph and demonstrate how the text wraps.
+  </div>`} />
+
 ## Word break
 
 Prevent long strings of text from breaking your components’ layout by using `.text-break` to set `word-wrap: break-word` and `word-break: break-word`. We use `word-wrap` instead of the more common `overflow-wrap` for wider browser support, and add the deprecated `word-break: break-word` to avoid issues with flex containers.