@nice-digital/nds-core 1.3.4-alpha.0 → 2.0.1-alpha.0

package/scss/media-queries/vendor/_mq.scss

@@ -0,0 +1,307 @@
+// v6.0.0
+// Vendored in much the same way as https://github.com/nhsuk/nhsuk-frontend/pull/601 and https://github.com/alphagov/govuk-frontend/pull/657
+
+@use 'sass:math';
+@use 'sass:map';
+@use 'sass:list';
+
+/// Breakpoint list
+///
+/// Name your breakpoints in a way that creates a ubiquitous language
+/// across team members. It will improve communication between
+/// stakeholders, designers, developers, and testers.
+///
+/// @type Map
+/// @link https://github.com/sass-mq/sass-mq#seeing-the-currently-active-breakpoint Full documentation and examples
+$breakpoints: (
+  mobile: 320px,
+  tablet: 740px,
+  desktop: 980px,
+  wide: 1300px
+) !default;
+
+/// Show breakpoints in the top right corner
+///
+/// If you want to display the currently active breakpoint in the top
+/// right corner of your site during development, add the breakpoints
+/// to this list, ordered by width. For example: (mobile, tablet, desktop).
+///
+/// @example scss
+///   @use 'path/to/mq' with ($show-breakpoints: ('mobile', 'tablet', 'desktop'));
+///
+///
+/// @type map
+$show-breakpoints: () !default;
+
+/// Customize the media type (for example: `@media screen` or `@media print`)
+/// By default sass-mq uses an "all" media type (`@media all and …`)
+///
+/// If you want to overried the media type, you can use this option.
+/// @example scss
+///   @use 'path/to/mq' with ($media-type: 'screen');
+///
+/// @type String
+/// @link https://github.com/sass-mq/sass-mq#changing-media-type Full documentation and example
+$media-type: all !default;
+
+/// Convert pixels to ems
+///
+/// @param {Number} $px - value to convert
+///
+/// @example scss
+///  $font-size-in-ems: px2em(16px);
+///  p { font-size: px2em(16px); }
+///
+/// @returns {Number}
+
+@function px2em($px) {
+  @if math.is-unitless($px) {
+    @warn "Assuming #{$px} to be in pixels, attempting to convert it into pixels.";
+    @return px2em($px * 1px);
+  }
+  // if $px is compatible with em units, then return value unchanged
+  @if math.compatible($px, 1em) {
+    @return $px;
+  }
+  @return math.div($px, 16px) * 1em;
+}
+
+/// Get a breakpoint's width
+///
+/// @param {String} $name - Name of the breakpoint. One of $breakpoints
+///
+/// @example scss
+///  $tablet-width: get-breakpoint-width(tablet);
+///  @media (min-width: get-breakpoint-width(tablet)) {}
+///
+/// @requires {Variable} $breakpoints
+///
+/// @returns {Number} Value in pixels
+@function get-breakpoint-width($name, $breakpoints: $breakpoints) {
+  @if map.has-key($breakpoints, $name) {
+    @return map.get($breakpoints, $name);
+  } @else {
+    @warn "Breakpoint #{$name} wasn't found in $breakpoints.";
+    @return null;
+  }
+}
+
+/// Media Query mixin
+///
+/// @param {String | Boolean} $from [false] - One of $breakpoints
+/// @param {String | Boolean} $until [false] - One of $breakpoints
+/// @param {String | Boolean} $and [false] - Additional media query parameters
+/// @param {String} $media-type [$media-type] - Media type: screen, print…
+///
+/// @ignore Undocumented API, for advanced use only:
+/// @ignore @param {Map} $breakpoints [$breakpoints]
+///
+/// @content styling rules, wrapped into a @media query when $responsive is true
+///
+/// @requires {Variable} $media-type
+/// @requires {Variable} $breakpoints
+/// @requires {function} px2em
+/// @requires {function} get-breakpoint-width
+///
+/// @link https://github.com/sass-mq/sass-mq#responsive-mode-on-default Full documentation and examples
+///
+/// @example scss
+///  @use 'path/to/mq' as *;
+///  .element {
+///    @include mq($from: mobile) {
+///      color: red;
+///    }
+///    @include mq($until: tablet) {
+///      color: blue;
+///    }
+///    @include mq(mobile, tablet) {
+///      color: green;
+///    }
+///    @include mq($from: tablet, $and: '(orientation: landscape)') {
+///      color: teal;
+///    }
+///    @include mq(950px) {
+///      color: hotpink;
+///    }
+///    @include mq(tablet, $media-type: screen) {
+///      color: hotpink;
+///    }
+///    // Advanced use:
+///    $my-breakpoints: (L: 900px, XL: 1200px);
+///    @include mq(L, $breakpoints: $my-breakpoints) {
+///      color: hotpink;
+///    }
+///  }
+@mixin mq(
+  $from: false,
+  $until: false,
+  $and: false,
+  $media-type: $media-type,
+  $breakpoints: $breakpoints
+) {
+  $min-width: 0;
+  $max-width: 0;
+  $media-query: '';
+
+  // From: this breakpoint (inclusive)
+  @if $from {
+    @if type-of($from) == number {
+      $min-width: px2em($from);
+    } @else {
+      $min-width: px2em(get-breakpoint-width($from, $breakpoints));
+    }
+  }
+
+  // Until: that breakpoint (exclusive)
+  @if $until {
+    @if type-of($until) == number {
+      $max-width: px2em($until);
+    } @else {
+      $max-width: px2em(get-breakpoint-width($until, $breakpoints)) - 0.01em;
+    }
+  }
+
+  @if $min-width != 0 {
+    $media-query: '#{$media-query} and (min-width: #{$min-width})';
+  }
+  @if $max-width != 0 {
+    $media-query: '#{$media-query} and (max-width: #{$max-width})';
+  }
+  @if $and {
+    $media-query: '#{$media-query} and #{$and}';
+  }
+
+  // Remove unnecessary media query prefix 'all and '
+  @if ($media-type == 'all' and $media-query != '') {
+    $media-type: '';
+    $media-query: str-slice(unquote($media-query), 6);
+  }
+
+  @media #{$media-type + $media-query} {
+    @content;
+  }
+}
+
+/// Quick sort
+///
+/// @author Sam Richards
+/// @access private
+/// @param {List} $list - List to sort
+/// @returns {List} Sorted List
+@function _quick-sort($list) {
+  $less: ();
+  $equal: ();
+  $large: ();
+
+  @if length($list) > 1 {
+    $seed: list.nth($list, math.ceil(math.div(length($list), 2)));
+
+    @each $item in $list {
+      @if ($item == $seed) {
+        $equal: list.append($equal, $item);
+      } @else if ($item < $seed) {
+        $less: list.append($less, $item);
+      } @else if ($item > $seed) {
+        $large: list.append($large, $item);
+      }
+    }
+
+    @return join(join(_quick-sort($less), $equal), _quick-sort($large));
+  }
+
+  @return $list;
+}
+
+/// Sort a map by values (works with numbers only)
+///
+/// @access private
+/// @param {Map} $map - Map to sort
+/// @returns {Map} Map sorted by value
+@function _map-sort-by-value($map) {
+  $map-sorted: ();
+  $map-keys: map.keys($map);
+  $map-values: map.values($map);
+  $map-values-sorted: _quick-sort($map-values);
+
+  // Reorder key/value pairs based on key values
+  @each $value in $map-values-sorted {
+    $index: index($map-values, $value);
+    $key: list.nth($map-keys, $index);
+    $map-sorted: map.merge(
+      $map-sorted,
+      (
+        $key: $value
+      )
+    );
+
+    // Unset the value in $map-values to prevent the loop
+    // from finding the same index twice
+    $map-values: list.set-nth($map-values, $index, 0);
+  }
+
+  @return $map-sorted;
+}
+
+/// Add a breakpoint
+///
+/// @param {String} $name - Name of the breakpoint
+/// @param {Number} $width - Width of the breakpoint
+///
+/// @requires {Variable} $breakpoints
+///
+/// @example scss
+///  @include add-breakpoint(tvscreen, 1920px);
+///  @include mq(tvscreen) {}
+@mixin add-breakpoint($name, $width) {
+  $new-breakpoint: (
+    $name: $width
+  );
+  $breakpoints: map.merge($breakpoints, $new-breakpoint) !global;
+  $breakpoints: _map-sort-by-value($breakpoints) !global;
+}
+
+/// Show the active breakpoint in the top right corner of the viewport
+/// @link https://github.com/sass-mq/sass-mq#seeing-the-currently-active-breakpoint
+///
+/// @param {List} $show-breakpoints [$show-breakpoints] - List of breakpoints to show in the top right corner
+/// @param {Map} $breakpoints [$breakpoints] - Breakpoint names and sizes
+///
+/// @requires {Variable} $breakpoints
+/// @requires {Variable} $show-breakpoints
+///
+/// @example scss
+///  // Show breakpoints using global settings
+///  @include show-breakpoints;
+///
+///  // Show breakpoints using custom settings
+///  @include show-breakpoints((L, XL), (S: 300px, L: 800px, XL: 1200px));
+@mixin show-breakpoints(
+  $show-breakpoints: $show-breakpoints,
+  $breakpoints: $breakpoints
+) {
+  body:before {
+    background-color: #fcf8e3;
+    border-bottom: 1px solid #fbeed5;
+    border-left: 1px solid #fbeed5;
+    color: #c09853;
+    font: small-caption;
+    padding: 3px 6px;
+    pointer-events: none;
+    position: fixed;
+    right: 0;
+    top: 0;
+    z-index: 100;
+
+    // Loop through the breakpoints that should be shown
+    @each $show-breakpoint in $show-breakpoints {
+      $width: get-breakpoint-width($show-breakpoint, $breakpoints);
+      @include mq($show-breakpoint, $breakpoints: $breakpoints) {
+        content: '#{$show-breakpoint} ≥ #{$width} (#{px2em($width)})';
+      }
+    }
+  }
+}
+
+@if list.length($show-breakpoints) > 0 {
+  @include show-breakpoints;
+}

package/scss/{settings/_settings-modular-scale.scss → modular-scale/_index.scss}

@@ -1,4 +1,6 @@
-@use "sass:math";
+@use 'sass:math';
+
+// stylelint-disable number-max-precision
 
 /// Modular scale values
 /// @link http://www.modularscale.com/
@@ -19,7 +21,7 @@
 /// @prop {Number} major-second[1.125]
 /// @prop {Number} minor-second[1.066666667]
 /// @since 0.1.0
-$nds-scales: (
+$scales: (
   golden: 1.618034,
   double-octave: 4,
   major-twelfth: 3,
@@ -40,14 +42,14 @@ $nds-scales: (
 );
 
 /// Gets a module scale ratio with the given name. Looks
-/// inside the $nds-scales map to find a ratio.
+/// inside the $scales map to find a ratio.
 /// @param $scale The name of the scale
 /// @returns {Number} The numeric scale ratio for the given name
 /// @since 0.1.0
-@function nds-get-ratio($scale) {
-  @if map-has-key($nds-scales, $scale) {
-    @return map-get($nds-scales, $scale);
+@function get-ratio($scale) {
+  @if map-has-key($scales, $scale) {
+    @return map-get($scales, $scale);
   } @else {
-    @error 'Scale with name #{$scale} could not be found in the $nds-scales map';
+    @error 'Scale with name #{$scale} could not be found in the $scales map';
   }
 }

package/scss/spacing/_index.scss

@@ -0,0 +1,31 @@
+////
+/// @group spacing
+////
+
+/// Extra extra small spacing
+/// @since 0.2.0
+$xx-small: 2;
+
+/// Extra small spacing
+/// @since 0.2.0
+$x-small: 4;
+
+/// Small spacing
+/// @since 0.2.0
+$small: 8;
+
+/// Medium spacing
+/// @since 0.2.0
+$medium: 16;
+
+/// Large spacing
+/// @since 0.2.0
+$large: 32;
+
+/// Extra large spacing
+/// @since 0.2.0
+$x-large: 48;
+
+/// Extra extra large spacing
+/// @since 0.2.0
+$xx-large: 64;

package/scss/typography/{_typography-headings.scss → _headings.scss}

@@ -1,3 +1,5 @@
+@use 'helpers';
+
 ////
 /// @group Typography
 ////
@@ -5,24 +7,21 @@
 /// Primary heading. Used for h1 tag but can be used directly
 /// for semantic classes for visual styling.
 /// @since 0.1.0
-@mixin nds-h1 {
-  @include nds-font(h1);
+@mixin h1 {
+  @include helpers.font(h1);
   clear: both;
-  font-family: nds-get-font-family(serif);
+  font-family: helpers.get-font-family(serif);
   font-weight: 600;
-  // Letter spacing and text shadow to mimic 900 weight, see https://github.com/nice-digital/nice-design-system/issues/240
-  letter-spacing: 0.5px;
   max-width: 66ch;
-  text-shadow: 1.5px 0 0 currentColor;
 }
 
 /// Secondary heading. Used for h2 tag but can be used directly
 /// for semantic classes for visual styling.
 /// @since 0.1.0
-@mixin nds-h2 {
-  @include nds-font(h2);
+@mixin h2 {
+  @include helpers.font(h2);
   clear: both;
-  font-family: nds-get-font-family(serif);
+  font-family: helpers.get-font-family(serif);
   font-weight: 600;
   max-width: 66ch;
 }
@@ -30,10 +29,10 @@
 /// Tertiary heading. Used for h3 tag but can be used directly
 /// for semantic classes for visual styling.
 /// @since 0.1.0
-@mixin nds-h3 {
-  @include nds-font(h3);
+@mixin h3 {
+  @include helpers.font(h3);
   clear: both;
-  font-family: nds-get-font-family(serif);
+  font-family: helpers.get-font-family(serif);
   font-weight: 600;
   max-width: 66ch;
 }
@@ -41,10 +40,10 @@
 /// Fourth level heading. Used for h4 tag but can be used directly
 /// for semantic classes for visual styling.
 /// @since 0.1.0
-@mixin nds-h4 {
-  @include nds-font(h4);
+@mixin h4 {
+  @include helpers.font(h4);
   clear: both;
-  font-family: nds-get-font-family(serif);
+  font-family: helpers.get-font-family(serif);
   font-weight: 600;
   max-width: 66ch;
 }
@@ -52,9 +51,10 @@
 /// Fifth level heading. Used for h5 tag but can be used directly
 /// for semantic classes for visual styling.
 /// @since 0.1.0
-@mixin nds-h5 {
-  @include nds-font(h5);
+@mixin h5 {
+  @include helpers.font(h5);
   clear: both;
+  font-family: helpers.get-font-family(sans);
   font-weight: 700;
   max-width: 66ch;
 }
@@ -62,9 +62,10 @@
 /// Sixth level heading. Used for h6 tag but can be used directly
 /// for semantic classes for visual styling.
 /// @since 0.1.0
-@mixin nds-h6 {
-  @include nds-font(h6);
+@mixin h6 {
+  @include helpers.font(h6);
   clear: both;
+  font-family: helpers.get-font-family(sans);
   font-weight: 700;
   max-width: 66ch;
 }

package/scss/typography/_helpers.scss

@@ -0,0 +1,172 @@
+@use 'sass:map';
+@use 'settings' as typography-settings;
+@use '../spacing';
+@use '../colours';
+@use '../utils';
+
+////
+/// @group Typography
+////
+
+/// Gets a font family from the `$font-families` map, given a name
+/// @param {String} $stack The stack name e.g. sans, serif or mono
+/// @since 0.1.0
+@function get-font-family($stack) {
+  $result: map.get(typography-settings.$font-families, $stack);
+  @return unquote($result);
+}
+
+/// Gets a numeric scale
+/// @param $scale {Integer|Name} The integer ratio or named font-size.
+/// @since 0.1.0
+@function get-scale-integer($scale) {
+  @if map-has-key(typography-settings.$named-font-sizes, $scale) {
+    @return map.get(typography-settings.$named-font-sizes, $scale);
+  } @else if is-integer($scale) {
+    @return $scale;
+  }
+
+  @error '`$scale` must either be an integer or exist as a named font size in `$named-font-sizes`';
+}
+
+/// Gets a numeric font size (in px) from a given scale multiplier.
+/// Usually not used directly - the font-size or font mixin is usually used instead.
+/// @param $scale {Integer|Name} The integer ratio or named font-size.
+/// @return {Number} Numeric font size (in px)
+/// @example
+///   $font-size: get-font-size(2)
+/// @example
+///   $font-size: get-font-size(h1)
+/// @since 0.1.0
+@function get-font-size($scale) {
+  $scale-integer: get-scale-integer($scale);
+  $font-map: map.get(typography-settings.$font-sizes, $scale-integer);
+  @return map.get($font-map, fs);
+}
+
+/// Gets a numeric line height (in px) from a given scale multiplier.
+/// Usually not used directly - the font-size or font mixin is usually used instead.
+/// @param $scale {Integer|Name} The integer ratio or named font-size.
+/// @return {Number} Numeric line-height (in px)
+/// @example
+///   $line-height: get-line-height(2)
+/// @example
+///   $line-height: get-line-height(h1)
+/// @since 0.1.0
+@function get-line-height($scale) {
+  $scale-integer: get-scale-integer($scale);
+  $font-map: map.get(typography-settings.$font-sizes, $scale-integer);
+  @return map.get($font-map, lh);
+}
+
+/// Applies font size and line-height for the given scale.
+/// @param $scale {Integer|Name} The integer ratio or named font-size.
+/// @param $important {Boolean} Whether to add an important declaration to the CSS rules.
+/// @example
+///   .test {
+///     @include font-size(-2);
+///   }
+/// @example
+///   .test {
+///     @include font-size(h1, true);
+///   }
+/// @since 0.1.0
+@mixin font-size($scale: 0, $important: false) {
+  $font-size: get-font-size($scale);
+  $line-height: get-line-height($scale);
+
+  @if $important {
+    font-size: utils.rem($font-size) !important;
+    line-height: utils.rem($line-height) !important;
+  } @else {
+    font-size: utils.rem($font-size);
+    line-height: utils.rem($line-height);
+  }
+}
+
+/// Nice font: includes font size, line height, and margins.
+/// @param $scale {Integer|Name} The integer ratio or named font-size.
+/// @param $important {Boolean} Whether to add an important declaration to the CSS rules.
+/// @example
+///   .test {
+///     @include font(3);
+///   }
+/// @example
+///   .test {
+///     @include font(h1, true);
+///   }
+/// @since 0.1.0
+@mixin font($scale, $important: false) {
+  $scale-integer: get-scale-integer($scale);
+  $font-map: map.get(typography-settings.$font-sizes, $scale-integer);
+  @include font-size($scale, $important);
+
+  @if $important {
+    margin-bottom: utils.rem(map.get($font-map, mb)) !important;
+    margin-top: utils.rem(map.get($font-map, mt)) !important;
+  } @else {
+    margin-bottom: utils.rem(map.get($font-map, mb));
+    margin-top: utils.rem(map.get($font-map, mt));
+  }
+}
+
+/// Default paragraph style
+/// @since 0.5.2
+@mixin p {
+  @include font(p);
+  font-feature-settings: 'kern', 'onum', 'liga';
+  font-weight: normal;
+  max-width: 66ch;
+}
+
+/// Lead paragraph style
+/// @since 0.2.12
+@mixin lead {
+  @include font(lead);
+  font-weight: normal;
+  max-width: 66ch;
+}
+
+/// Base list style
+/// @since 0.1.0
+@mixin list {
+  font-feature-settings: 'kern', 'onum', 'liga';
+  margin-left: utils.rem(spacing.$medium);
+  max-width: 66ch;
+  padding: 0;
+}
+
+/// Text truncate
+/// Requires inline-block or block for proper styling
+/// @since 0.1.0
+@mixin text-truncate {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/// Set and element to display as block and align
+/// centrally via auto left/right margins
+/// @since 0.1.0
+@mixin center-block {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+// TODO: default-error-style probably belongs elsewhere?
+
+/// The highlight style used for elements like inputs and textareas
+/// if there's an error on the field
+/// @param {Boolean} $rounded whether to use box shadow for border (outline can't be styled to have radius corners)
+/// @output default styling for form elements in an errored state
+/// @since 1.0
+@mixin default-error-style($rounded: false) {
+  @if $rounded {
+    box-shadow: 0 0 0 utils.rem(spacing.$x-small) colours.$error;
+    outline: spacing.$x-small solid transparent;
+    outline-offset: spacing.$x-small;
+  } @else {
+    outline: utils.rem(spacing.$x-small) solid colours.$error;
+  }
+}

package/scss/typography/_index.scss

@@ -0,0 +1,4 @@
+@forward 'settings';
+@forward 'helpers';
+@forward 'links';
+@forward 'headings';