From 05e2f017ae297654684df210d6a1c91b23584b40 Mon Sep 17 00:00:00 2001
From: Miki <miki@amazon.com>
Date: Fri, 16 Aug 2024 08:43:36 -0700
Subject: [PATCH] Introduce `$ouiLegibilityMaxWidth` variable and
 `ouiLegibilityMaxWidth` mixin

Signed-off-by: Miki <miki@amazon.com>
---
 CHANGELOG.md                                       |  1 +
 src/global_styling/mixins/_typography.scss         | 14 ++++++++++++++
 src/global_styling/variables/_typography.scss      |  4 ++++
 .../global_styling/mixins/_typography.scss         | 14 ++++++++++++++
 .../global_styling/variables/_typography.scss      |  4 ++++
 .../v9/global_styling/mixins/_typography.scss      | 14 ++++++++++++++
 .../v9/global_styling/variables/_typography.scss   |  4 ++++
 7 files changed, 55 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b254645746..0a2b6b9942 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,7 @@
 - Add V9 Theme ([#1344](https://github.com/opensearch-project/oui/pull/1344))
 - Add history icon and alias it as recent ([#1346](https://github.com/opensearch-project/oui/pull/1346))
 - Introduce compressed OuiSearchBar ([#1354](https://github.com/opensearch-project/oui/pull/1354))
+- Introduce `$ouiLegibilityMaxWidth` variable and `ouiLegibilityMaxWidth` mixin ([#1359](https://github.com/opensearch-project/oui/pull/1359))
 
 ### 🐛 Bug Fixes
 
diff --git a/src/global_styling/mixins/_typography.scss b/src/global_styling/mixins/_typography.scss
index 2d5ab518e0..f6844cfde9 100644
--- a/src/global_styling/mixins/_typography.scss
+++ b/src/global_styling/mixins/_typography.scss
@@ -147,6 +147,19 @@
   }
 }
 
+// Lowest max-width
+//
+// Legibility research specific to digital text has shown that line length can affect reading
+// speed. If lines are too long it is difficult for the reader to quickly return to the start
+// of the next line, whereas if lines are too short more scrolling or paging will be required.
+//
+// This mixin will choose the lesser of the magic $ouiLegibilityMaxWidth number and the
+// supplied $maxWidth to allow controlling the max-width without needing media-queries.
+
+@mixin ouiLegibilityMaxWidth($maxWidth) {
+  max-width: min($ouiLegibilityMaxWidth, $maxWidth);
+}
+
 
 
 /* OUI -> EUI Aliases */
@@ -165,4 +178,5 @@
 @mixin euiTextTruncate { @include ouiTextTruncate; }
 @mixin euiNumberFormat { @include ouiNumberFormat; }
 @mixin euiTextShift($fontWeight: $ouiFontWeightBold, $attr: 'data-text') { @include ouiTextShift($fontWeight, $attr); }
+@mixin euiLegibilityMaxWidth($maxWidth) { @include ouiLegibilityMaxWidth($maxWidth); }
 /* End of Aliases */
diff --git a/src/global_styling/variables/_typography.scss b/src/global_styling/variables/_typography.scss
index 124150577b..70f644896d 100644
--- a/src/global_styling/variables/_typography.scss
+++ b/src/global_styling/variables/_typography.scss
@@ -56,6 +56,9 @@ $ouiFontSizeL:      $ouiFontSize * nth($ouiTextScale, 3) !default; // 20px
 $ouiFontSizeXL:     $ouiFontSize * nth($ouiTextScale, 2) !default; // 28px
 $ouiFontSizeXXL:    $ouiFontSize * nth($ouiTextScale, 1) !default; // 36px
 
+// This value is impacted by font-size
+$ouiLegibilityMaxWidth: 80ch !default;
+
 // Line height
 $ouiLineHeight:     1.5 !default;
 $ouiBodyLineHeight: 1 !default;
@@ -122,6 +125,7 @@ $euiFontSizeM: $ouiFontSizeM;
 $euiFontSizeL: $ouiFontSizeL;
 $euiFontSizeXL: $ouiFontSizeXL;
 $euiFontSizeXXL: $ouiFontSizeXXL;
+$euiLegibilityMaxWidth: $ouiLegibilityMaxWidth;
 $euiLineHeight: $ouiLineHeight;
 $euiBodyLineHeight: $ouiBodyLineHeight;
 $euiFontWeightLight: $ouiFontWeightLight;
diff --git a/src/themes/oui-next/global_styling/mixins/_typography.scss b/src/themes/oui-next/global_styling/mixins/_typography.scss
index 2780a0f72b..cff3c65928 100644
--- a/src/themes/oui-next/global_styling/mixins/_typography.scss
+++ b/src/themes/oui-next/global_styling/mixins/_typography.scss
@@ -147,6 +147,19 @@
   }
 }
 
+// Lowest max-width
+//
+// Legibility research specific to digital text has shown that line length can affect reading
+// speed. If lines are too long it is difficult for the reader to quickly return to the start
+// of the next line, whereas if lines are too short more scrolling or paging will be required.
+//
+// This mixin will choose the lesser of the magic $ouiLegibilityMaxWidth number and the
+// supplied $maxWidth to allow controlling the max-width without needing media-queries.
+
+@mixin ouiLegibilityMaxWidth($maxWidth) {
+  max-width: min($ouiLegibilityMaxWidth, $maxWidth);
+}
+
 
 
 /* OUI -> EUI Aliases */
@@ -165,4 +178,5 @@
 @mixin euiTextTruncate { @include ouiTextTruncate; }
 @mixin euiNumberFormat { @include ouiNumberFormat; }
 @mixin euiTextShift($fontWeight: $ouiFontWeightBold, $attr: 'data-text') { @include ouiTextShift($fontWeight, $attr); }
+@mixin euiLegibilityMaxWidth($maxWidth) { @include ouiLegibilityMaxWidth($maxWidth); }
 /* End of Aliases */
diff --git a/src/themes/oui-next/global_styling/variables/_typography.scss b/src/themes/oui-next/global_styling/variables/_typography.scss
index 7e76324e95..79402264d8 100644
--- a/src/themes/oui-next/global_styling/variables/_typography.scss
+++ b/src/themes/oui-next/global_styling/variables/_typography.scss
@@ -57,6 +57,9 @@ $ouiFontSizeL:      $ouiFontSize * nth($ouiTextScale, 3) !default; // 20px
 $ouiFontSizeXL:     $ouiFontSize * nth($ouiTextScale, 2) !default; // 28px
 $ouiFontSizeXXL:    $ouiFontSize * nth($ouiTextScale, 1) !default; // 36px
 
+// This value is impacted by font-size
+$ouiLegibilityMaxWidth: 80ch !default;
+
 // Line height
 $ouiLineHeight:     1.333333 !default;
 $ouiBodyLineHeight: 1 !default;
@@ -125,6 +128,7 @@ $euiFontSizeM: $ouiFontSizeM;
 $euiFontSizeL: $ouiFontSizeL;
 $euiFontSizeXL: $ouiFontSizeXL;
 $euiFontSizeXXL: $ouiFontSizeXXL;
+$euiLegibilityMaxWidth: $ouiLegibilityMaxWidth;
 $euiLineHeight: $ouiLineHeight;
 $euiBodyLineHeight: $ouiBodyLineHeight;
 $euiFontWeightLight: $ouiFontWeightLight;
diff --git a/src/themes/v9/global_styling/mixins/_typography.scss b/src/themes/v9/global_styling/mixins/_typography.scss
index 2780a0f72b..cff3c65928 100644
--- a/src/themes/v9/global_styling/mixins/_typography.scss
+++ b/src/themes/v9/global_styling/mixins/_typography.scss
@@ -147,6 +147,19 @@
   }
 }
 
+// Lowest max-width
+//
+// Legibility research specific to digital text has shown that line length can affect reading
+// speed. If lines are too long it is difficult for the reader to quickly return to the start
+// of the next line, whereas if lines are too short more scrolling or paging will be required.
+//
+// This mixin will choose the lesser of the magic $ouiLegibilityMaxWidth number and the
+// supplied $maxWidth to allow controlling the max-width without needing media-queries.
+
+@mixin ouiLegibilityMaxWidth($maxWidth) {
+  max-width: min($ouiLegibilityMaxWidth, $maxWidth);
+}
+
 
 
 /* OUI -> EUI Aliases */
@@ -165,4 +178,5 @@
 @mixin euiTextTruncate { @include ouiTextTruncate; }
 @mixin euiNumberFormat { @include ouiNumberFormat; }
 @mixin euiTextShift($fontWeight: $ouiFontWeightBold, $attr: 'data-text') { @include ouiTextShift($fontWeight, $attr); }
+@mixin euiLegibilityMaxWidth($maxWidth) { @include ouiLegibilityMaxWidth($maxWidth); }
 /* End of Aliases */
diff --git a/src/themes/v9/global_styling/variables/_typography.scss b/src/themes/v9/global_styling/variables/_typography.scss
index 05c657fa1f..73ed85b225 100644
--- a/src/themes/v9/global_styling/variables/_typography.scss
+++ b/src/themes/v9/global_styling/variables/_typography.scss
@@ -57,6 +57,9 @@ $ouiFontSizeL:      $ouiFontSize * nth($ouiTextScale, 3) !default; // 20px
 $ouiFontSizeXL:     $ouiFontSize * nth($ouiTextScale, 2) !default; // 28px
 $ouiFontSizeXXL:    $ouiFontSize * nth($ouiTextScale, 1) !default; // 36px
 
+// This value is impacted by font-size
+$ouiLegibilityMaxWidth: 80ch !default;
+
 // Line height
 $ouiLineHeight:     1.5 !default;
 $ouiBodyLineHeight: 1 !default;
@@ -125,6 +128,7 @@ $euiFontSizeM: $ouiFontSizeM;
 $euiFontSizeL: $ouiFontSizeL;
 $euiFontSizeXL: $ouiFontSizeXL;
 $euiFontSizeXXL: $ouiFontSizeXXL;
+$euiLegibilityMaxWidth: $ouiLegibilityMaxWidth;
 $euiLineHeight: $ouiLineHeight;
 $euiBodyLineHeight: $ouiBodyLineHeight;
 $euiFontWeightLight: $ouiFontWeightLight;