From 66ad8f5027599829d7d99452726b2260d35b7a3b Mon Sep 17 00:00:00 2001
From: beeps <hi+github@berly.kim>
Date: Fri, 26 Jul 2024 10:17:03 +0100
Subject: [PATCH] Add break-word typography helper

---
 CHANGELOG.md                                  | 16 +++++++
 .../src/govuk/helpers/_typography.scss        | 17 +++++++
 .../src/govuk/helpers/typography.unit.test.js | 44 +++++++++++++++++++
 .../src/govuk/overrides/_typography.scss      |  6 ++-
 4 files changed, 82 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0ea69a8c17..1d6523bc15 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,22 @@ For advice on how to use these release notes see [our guidance on staying up to
 
 ## Unreleased
 
+### New features
+
+#### Stop long words breaking out of components with `govuk-!-text-break-word`
+
+We've added a new override class to help display long or unpredictable words on narrow screens, such as an email address entered by a user.
+
+Wrapping the content with the `govuk-!-text-break-word` class forces words that are too long for the parent element to break onto a new line.
+
+```html
+A confirmation email will be sent to <span class="govuk-!-text-break-word">arthur_phillip_dent.42@peoplepersonalitydivision.siriuscyberneticscorporation.corp</span>.
+```
+
+Sass users can also use the `govuk-text-break-word` mixin.
+
+This change was introduced in [pull request #5159: Add break-word typography helper](https://github.com/alphagov/govuk-frontend/pull/5159).
+
 ### Fixes
 
 We've made fixes to GOV.UK Frontend in the following pull requests:
diff --git a/packages/govuk-frontend/src/govuk/helpers/_typography.scss b/packages/govuk-frontend/src/govuk/helpers/_typography.scss
index 124b887eea..2616dd189b 100644
--- a/packages/govuk-frontend/src/govuk/helpers/_typography.scss
+++ b/packages/govuk-frontend/src/govuk/helpers/_typography.scss
@@ -79,6 +79,23 @@
   font-variant-numeric: tabular-nums if($important, !important, null);
 }
 
+/// Word break helper
+///
+/// Forcibly breaks long words that lack spaces, such as email addresses,
+/// across multiple lines when they wouldn't otherwise fit.
+///
+/// @param {Boolean} $important [false] - Whether to mark declarations as
+///   `!important`. Generally used to create override classes.
+/// @access public
+
+@mixin govuk-text-break-word($important: false) {
+  // IE 11 and Edge 16–17 only support the non-standard `word-wrap` property
+  word-wrap: break-word if($important, !important, null);
+
+  // All other browsers support `overflow-wrap`
+  overflow-wrap: break-word if($important, !important, null);
+}
+
 /// Convert line-heights specified in pixels into a relative value, unless
 /// they are already unit-less (and thus already treated as relative values)
 /// or the units do not match the units used for the font size.
diff --git a/packages/govuk-frontend/src/govuk/helpers/typography.unit.test.js b/packages/govuk-frontend/src/govuk/helpers/typography.unit.test.js
index fc6e78ac1e..5e37906b73 100644
--- a/packages/govuk-frontend/src/govuk/helpers/typography.unit.test.js
+++ b/packages/govuk-frontend/src/govuk/helpers/typography.unit.test.js
@@ -170,6 +170,50 @@ describe('@mixin govuk-font-tabular-numbers', () => {
   })
 })
 
+describe('@mixin govuk-font-break-word', () => {
+  it('adds the word-wrap and overflow-wrap properties', async () => {
+    const sass = `
+      ${sassBootstrap}
+
+      .foo {
+        @include govuk-font-break-word;
+      }
+    `
+
+    const results = compileSassString(sass)
+
+    await expect(results).resolves.toMatchObject({
+      css: outdent`
+        .foo {
+          word-wrap: break-word;
+          overflow-wrap: break-word;
+        }
+      `
+    })
+  })
+
+  it('marks the properties as important if $important is set to true', async () => {
+    const sass = `
+      ${sassBootstrap}
+
+      .foo {
+        @include govuk-font-break-word($important: true);
+      }
+    `
+
+    const results = compileSassString(sass)
+
+    await expect(results).resolves.toMatchObject({
+      css: outdent`
+        .foo {
+          word-wrap: break-word !important;
+          overflow-wrap: break-word !important;
+        }
+      `
+    })
+  })
+})
+
 describe('@function _govuk-line-height', () => {
   it('preserves line-height if already unitless', async () => {
     const sass = `
diff --git a/packages/govuk-frontend/src/govuk/overrides/_typography.scss b/packages/govuk-frontend/src/govuk/overrides/_typography.scss
index 0f924b4f04..7099a78ccb 100644
--- a/packages/govuk-frontend/src/govuk/overrides/_typography.scss
+++ b/packages/govuk-frontend/src/govuk/overrides/_typography.scss
@@ -28,9 +28,13 @@
     @include govuk-typography-weight-bold($important: true);
   }
 
-  // Tabular numbers
+  // Typography helpers
 
   .govuk-\!-font-tabular-numbers {
     @include govuk-font-tabular-numbers($important: true);
   }
+
+  .govuk-\!-text-break-word {
+    @include govuk-text-break-word($important: true);
+  }
 }