vanilla-framework 4.15.0 → 4.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vanilla-framework",
-  "version": "4.15.0",
+  "version": "4.16.0",
   "author": {
     "email": "webteam@canonical.com",
     "name": "Canonical Webteam"
@@ -29,8 +29,9 @@
   "scripts": {
     "start": "yarn build && yarn serve",
     "build": "yarn build-scss && yarn build-js && yarn build-class-references",
-    "build-scss": "sass --load-path=node_modules --embed-sources --style=compressed scss:build/css && postcss --use autoprefixer --replace 'build/css/**/*.css' --map",
-    "build:essential": "yarn run build-js && sass --load-path=node_modules --embed-sources --style=compressed scss/build.scss:build/css/build.css scss/docs:build/css/docs && postcss --use autoprefixer --replace 'build/css/**/*.css' --map",
+    "build-tokens": "((style-dictionary build --verbose --config ./sd.config.json) || true)",
+    "build-scss": "yarn build-tokens && sass --load-path=node_modules --embed-sources --style=compressed --silence-deprecation=mixed-decls scss:build/css && postcss --use autoprefixer --replace 'build/css/**/*.css' --map",
+    "build:essential": "yarn run build-js && sass --load-path=node_modules --embed-sources --style=compressed --silence-deprecation=mixed-decls scss/build.scss:build/css/build.css scss/docs:build/css/docs && postcss --use autoprefixer --replace 'build/css/**/*.css' --map",
     "build-js": "mkdir -p build/js/modules && cp node_modules/@canonical/cookie-policy/build/js/cookie-policy.js build/js/modules && cp node_modules/@canonical/latest-news/dist/latest-news.js build/js/modules && cp node_modules/js-beautify/js/lib/beautify.js node_modules/js-beautify/js/lib/beautify-html.js node_modules/js-beautify/js/lib/beautify-css.js build/js/modules",
     "build-class-references": "node scripts/create-class-references.js",
     "cypress:open": "cypress open",
@@ -41,8 +42,8 @@
     "test": "yarn lint-scss && yarn lint-prettier &&  yarn test-spelling && yarn test-scss && yarn jest",
     "lint-prettier": "prettier -c .",
     "lint-scss": "stylelint 'scss/**/*.scss'",
-    "watch:scss": "sass --load-path=node_modules --embed-sources --style=compressed scss:build/css --watch",
-    "watch:essential": "sass --load-path=node_modules --embed-sources --style=compressed scss/build.scss:build/css/build.css --watch",
+    "watch:scss": "sass --load-path=node_modules --embed-sources --style=compressed --silence-deprecation=mixed-decls scss:build/css --watch",
+    "watch:essential": "sass --load-path=node_modules --embed-sources --style=compressed --silence-deprecation=mixed-decls scss/build.scss:build/css/build.css --watch",
     "watch": "yarn build && yarn watch:scss",
     "clean": "rm -rf build docs/static/css node_modules/ yarn-error.log",
     "percy": "percy snapshot snapshots.js",
@@ -57,20 +58,21 @@
   "devDependencies": {
     "@canonical/cookie-policy": "3.6.4",
     "@canonical/latest-news": "1.5.0",
-    "@percy/cli": "1.29.0",
+    "@percy/cli": "1.29.3",
     "@testing-library/cypress": "10.0.2",
-    "autoprefixer": "10.4.19",
-    "cypress": "13.13.2",
+    "autoprefixer": "10.4.20",
+    "cypress": "13.14.1",
     "jest": "29.7.0",
     "js-beautify": "1.15.1",
     "markdown-spellcheck": "1.3.1",
     "parker": "0.0.10",
-    "postcss": "8.4.40",
+    "postcss": "8.4.44",
     "postcss-cli": "11.0.0",
     "postcss-scss": "4.0.9",
     "prettier": "3.3.3",
     "sass": "1.77.8",
-    "stylelint": "16.8.1",
+    "style-dictionary": "4.1.0",
+    "stylelint": "16.9.0",
     "stylelint-config-recommended-scss": "14.1.0",
     "stylelint-order": "6.0.4",
     "stylelint-prettier": "5.0.2",

package/scss/_base_button.scss

@@ -15,7 +15,7 @@
 
   %vf-button-base {
     @include vf-transition(#{background-color, border-color}, snap, in);
-    @include vf-focus;
+    @include vf-focus-themed;
 
     border-style: solid;
     border-width: $input-border-thickness;

package/scss/_base_details.scss

@@ -7,7 +7,7 @@
 
   summary {
     @extend %common-default-text-properties;
-    @include vf-focus;
+    @include vf-focus-themed;
 
     margin-bottom: $spv-nudge; //push subsequent text onto baseline
     max-width: $text-max-width;

package/scss/_base_forms.scss

@@ -13,7 +13,7 @@
   // Default form input element styles
   %vf-input-elements {
     @extend %bordered-text-vertical-padding;
-    @include vf-focus($has-validation: true);
+    @include vf-focus-themed($has-validation: true);
     @include vf-animation(#{background-color}, fast);
 
     // stylelint-disable property-no-vendor-prefix
@@ -145,7 +145,7 @@
 
   [type='file'] {
     @extend %bordered-text-vertical-padding;
-    @include vf-focus;
+    @include vf-focus-themed;
 
     margin-bottom: $input-margin-bottom;
     width: 100%;
@@ -225,5 +225,11 @@
     margin-right: 0;
     padding: calc($spv--large - $input-border-thickness);
   }
+
+  legend {
+    &.is-required::before {
+      content: '* ';
+    }
+  }
   // stylelint-enable selector-max-type
 }

package/scss/_base_hr.scss

@@ -27,10 +27,8 @@
   // stylelint-disable selector-max-type -- base styles can use type selectors
   hr {
     @extend %hr;
-    background: $colors--theme--border-default;
-
-    margin-bottom: calc($spv--small - 1px);
 
+    // DEPRECATED: use `.p-rule--muted` instead
     &.is-muted {
       background-color: $colors--theme--border-low-contrast;
     }
@@ -40,6 +38,7 @@
       @extend %u-no-margin--bottom--hr;
     }
 
+    // DEPRECATED: use rule component inside of the grid instead
     &.is-fixed-width {
       @extend %fixed-width-hr;
     }

package/scss/_base_links.scss

@@ -8,7 +8,7 @@
   }
 
   %vf-link-base {
-    @include vf-focus;
+    @include vf-focus-themed;
 
     color: $colors--theme--link-default;
     text-decoration: none;

package/scss/_base_placeholders.scss

@@ -98,8 +98,10 @@
   }
 
   %hr {
+    background: $colors--theme--border-default;
     border: 0;
     height: 1px;
+    margin-bottom: calc($spv--small - 1px);
     margin-top: 0;
     position: relative;
     width: 100%;

package/scss/_base_typography-definitions.scss

@@ -1,7 +1,7 @@
 @mixin vf-b-typography-definitions {
   %vf-is-accent {
     &.is-accent {
-      color: $color-accent;
+      color: $colors--theme--accent;
     }
   }
 

package/scss/_global_functions.scss

@@ -60,16 +60,22 @@
   }
 }
 
-// Adds visual focus to elements on :focus-visible,
-// or :focus if the browser doesn't support the former
-@mixin vf-focus($color: $colors--theme--focus, $width: $bar-thickness, $has-validation: false) {
+// Adds visual focus to elements on :focus-visible or :focus if the browser
+// doesn't support the former
+@mixin vf-focus-themed($light-color: $colors--light-theme--focus, $dark-color: $colors--dark-theme--focus, $width: $bar-thickness, $has-validation: false) {
+  --vf-focus-outline-color: #{$light-color};
+
+  .is-dark & {
+    --vf-focus-outline-color: #{$dark-color};
+  }
+
   &:focus {
-    outline: $width solid $color;
+    outline: $width solid var(--vf-focus-outline-color);
     outline-offset: -#{$width};
   }
 
   &:focus-visible {
-    outline: $width solid $color;
+    outline: $width solid var(--vf-focus-outline-color);
     outline-offset: -#{$width};
   }
 
@@ -93,6 +99,12 @@
   }
 }
 
+// This mixin is deprecated and will be removed in a future version of Vanilla.
+// Please use vf-focus-themed instead.
+@mixin vf-focus($color: $colors--theme--focus, $width: $bar-thickness, $has-validation: false) {
+  @include vf-focus-themed($light-color: $color, $width: $width, $has-validation: $has-validation);
+}
+
 // Raises a number to a power (https://css-tricks.com/snippets/sass/power-function/)
 @function pow($number, $exponent) {
   $value: 1;

package/scss/_layouts_fluid-breakout.scss

@@ -149,7 +149,7 @@
       grid-column: 2 / -1;
       grid-template-columns: repeat(2, minmax(0, 1fr));
 
-      @media (max-width: $threshold-4-6-col - 1) {
+      @media (width < $threshold-4-6-col) {
         grid-template-columns: repeat(1, minmax(0, 1fr));
         width: $l-fluid-breakout-main-child-width;
       }
@@ -163,7 +163,7 @@
       &:nth-child(2) {
         justify-content: flex-end;
 
-        @media (max-width: $threshold-4-6-col - 1) {
+        @media (width < $threshold-4-6-col) {
           justify-content: flex-start;
         }
       }

package/scss/_patterns_accordion.scss

@@ -17,7 +17,7 @@
 
   .p-accordion__tab {
     @extend %single-border-text-vpadding--scaling;
-    @include vf-focus;
+    @include vf-focus-themed;
 
     background-color: inherit;
     border: 0;

package/scss/_patterns_article-pagination.scss

@@ -55,7 +55,7 @@
     padding-left: $sp-xx-large;
     text-align: left;
 
-    @media (max-width: $breakpoint-x-small - 1) {
+    @media (width < $breakpoint-x-small) {
       margin-right: 0;
       width: auto;
 
@@ -84,7 +84,7 @@
     padding-right: $sp-xx-large;
     text-align: right;
 
-    @media (max-width: $breakpoint-x-small - 1) {
+    @media (width < $breakpoint-x-small) {
       width: 100%;
     }
 

package/scss/_patterns_buttons.scss

@@ -80,7 +80,7 @@
       $button-disabled-border-color: $colors--theme--button-positive-default,
       $button-text-color: $colors--theme--button-positive-text
     );
-    @include vf-focus($colors--theme--positive-focus);
+    @include vf-focus-themed($light-color: $color-focus-positive);
   }
 }
 

package/scss/_patterns_chip.scss

@@ -1,22 +1,21 @@
 @use 'sass:math';
 @import 'settings';
-$chip-border-thickness: 1px;
 
 @mixin vf-p-chip {
   %vf-chip {
     @extend %small-text;
     @include vf-transition(#{background-color, border-color}, snap, out);
-    @include vf-focus;
+    @include vf-focus-themed;
 
     align-items: baseline;
     border-radius: 1rem;
     display: inline-flex;
     margin: 0 $sph--small $input-margin-bottom 0;
     max-width: 100%;
-    padding: calc($spv--x-small - $chip-border-thickness) $sph--small; // account for border thickness using calc
+    padding: calc($spv--x-small - $input-border-thickness) $sph--small; // account for border thickness using calc
     position: relative;
     user-select: none;
-    vertical-align: calc($chip-border-thickness - map-get($nudges, p));
+    vertical-align: calc($input-border-thickness - map-get($nudges, p));
     white-space: nowrap;
 
     .p-chip__lead,
@@ -78,7 +77,7 @@ $chip-border-thickness: 1px;
     @extend %vf-chip;
 
     background-color: $colors--theme--background-neutral-default;
-    border: $chip-border-thickness solid $colors--theme--border-neutral;
+    border: $input-border-thickness solid $colors--theme--border-neutral;
     border-color: $colors--theme--border-neutral;
   }
 
@@ -115,7 +114,7 @@ $chip-border-thickness: 1px;
     @extend %vf-chip;
 
     background-color: $colors--theme--background-positive-default;
-    border: $chip-border-thickness solid $colors--theme--border-positive;
+    border: $input-border-thickness solid $colors--theme--border-positive;
     border-color: $colors--theme--border-positive;
   }
 
@@ -152,7 +151,7 @@ $chip-border-thickness: 1px;
     @extend %vf-chip;
 
     background-color: $colors--theme--background-caution-default;
-    border: $chip-border-thickness solid $colors--theme--border-caution;
+    border: $input-border-thickness solid $colors--theme--border-caution;
     border-color: $colors--theme--border-caution;
   }
 
@@ -189,7 +188,7 @@ $chip-border-thickness: 1px;
     @extend %vf-chip;
 
     background-color: $colors--theme--background-negative-default;
-    border: $chip-border-thickness solid $colors--theme--border-negative;
+    border: $input-border-thickness solid $colors--theme--border-negative;
     border-color: $colors--theme--border-negative;
   }
 
@@ -226,7 +225,7 @@ $chip-border-thickness: 1px;
     @extend %vf-chip;
 
     background-color: $colors--theme--background-information-default;
-    border: $chip-border-thickness solid $colors--theme--border-information;
+    border: $input-border-thickness solid $colors--theme--border-information;
     border-color: $colors--theme--border-information;
   }
 

package/scss/_patterns_code-snippet.scss

@@ -9,7 +9,7 @@
 
     Code block:
         .p-code-snippet__block:
-            Code block without any additonal styling elements.
+            Code block without any additional styling elements.
         "&.is-wrapped":
             Code block with wrapped content in lines.
         .p-code-snippet__block--icon:

package/scss/_patterns_contextual-menu.scss

@@ -66,7 +66,7 @@
   }
 
   .p-contextual-menu__link {
-    @include vf-focus;
+    @include vf-focus-themed;
 
     border: 0;
     clear: both;

package/scss/_patterns_cta.scss

@@ -4,6 +4,8 @@
     CTA Block:
       .p-cta-block:
         Main element of the CTA block.
+      "&.is-borderless":
+        Borderless variant, to be used to hide top border and padding.
 */
 
 @import 'settings';
@@ -16,5 +18,10 @@
     flex-wrap: wrap;
     padding-bottom: $spv--x-large;
     padding-top: $spv--small;
+
+    &.is-borderless {
+      border: none;
+      padding-top: 0;
+    }
   }
 }

package/scss/_patterns_equal-height-row.scss

@@ -1,12 +1,36 @@
+/*
+  @classreference
+  equal-height-row:
+    Equal height row:
+      .p-equal-height-row:
+        Main element of the equal height row component.
+      "&.has-divider-1":
+        Cross-column divider shown between the first and second grid rows.
+      "&.has-divider-2":
+        Cross-column divider shown between the second and third grid rows.
+      "&.has-divider-3":
+        Cross-column divider shown between the third and fourth grid rows.
+      .p-equal-height-row--wrap:
+        Wraps contents such that two items appear per row on medium screen sizes.
+    Column:
+      .p-equal-height-row__col:
+        Column element within an equal height row.
+    Item:
+      .p-equal-height-row__item:
+        Item element within an equal height row column.
+*/
+
 @import 'settings';
 
 @mixin vf-p-equal-height-row {
-  .p-equal-height-row {
+  .p-equal-height-row,
+  .p-equal-height-row--wrap {
     @extend %vf-row;
+
     position: relative;
 
     .p-equal-height-row__col {
-      // smaller screens each column will have border top by default
+      // At smaller sizes, each column will have top border by default
       border-top-color: $colors--theme--border-low-contrast;
       border-top-style: solid;
       border-top-width: 1px;
@@ -15,21 +39,24 @@
       grid-row: span 4;
       grid-template-rows: subgrid;
       margin-bottom: $spv--small;
-      margin-top: -1px;
       position: relative;
 
       @media screen and ($breakpoint-small <= width < $breakpoint-large) {
         grid-column: span $grid-columns-medium;
         grid-template-columns: subgrid;
 
-        // for medium screen, each column item will take half of the available cols from the parent grid
+        // At medium size, each column item will take half of the available
+        // cols from the parent grid
         .p-equal-height-row__item {
           grid-column: span calc($grid-columns-medium / 2);
         }
 
-        // for medium screen, position the first column item on the left of the grid
+        // At medium size, position the first column item on the left of the
+        // grid
         .p-equal-height-row__item:first-child {
-          grid-row: span 100; // this needs to be sufficiently large so remaining column items won't get stretched
+          // This needs to be sufficiently large so remaining column items won't
+          // get stretched
+          grid-row: span 100;
         }
       }
 
@@ -42,63 +69,80 @@
 
     // DIVIDERS
 
-    // For each row or column grid we only have access to two pseudo elements
-    // if 1st-divider (::before) is present, assume 2nd-divider (::after) isn't, then 3rd-divider must be (::after)
-    // if 2nd-divider (::after) is present, assume 1st-divider (::before) isn't, then 3rd-divider must be (::before)
+    // For each row or column grid we only have access to two pseudo elements:
+    // If 1st-divider (::before) is present, assume 2nd-divider (::after) isn't, then 3rd-divider must be (::after)
+    // If 2nd-divider (::after) is present, assume 1st-divider (::before) isn't, then 3rd-divider must be (::before)
     &.has-divider-1::before,
     &.has-divider-2::after,
     &.has-divider-3:not(.has-divider-1)::before,
     &.has-divider-3:not(.has-divider-2)::after {
-      // row level dividers are not visible on smaller screen sizes
       @extend %vf-pseudo-border;
-      background-color: $colors--theme--border-low-contrast; // override border color to be low contrast
+
+      // Override border color to be low contrast
+      background-color: $colors--theme--border-low-contrast;
+      // Row-level dividers are not visible on smaller screen sizes
       display: none;
-    }
+      grid-column-end: span 12;
+      grid-column-start: 1;
+      margin: auto;
 
-    @media screen and (width >= $breakpoint-large) {
-      &.has-divider-1::before,
-      &.has-divider-2::after,
-      &.has-divider-3:not(.has-divider-1)::before,
-      &.has-divider-3:not(.has-divider-2)::after {
+      @media screen and (width >= $breakpoint-large) {
         display: block;
-        grid-column-end: span 12;
-        grid-column-start: 1;
-        margin: auto;
       }
+    }
 
-      &.has-divider-1::before {
-        grid-row: 2;
-      }
+    &.has-divider-1::before {
+      grid-row: 2;
+    }
 
-      &.has-divider-2::after {
-        grid-row: 3;
-      }
+    &.has-divider-2::after {
+      grid-row: 3;
+    }
 
-      // when 3rd-divider is present and 1st-divider is not present
-      &.has-divider-3:not(.has-divider-1)::before,
-      // when 3rd-divider is present and 2nd-divider is not present
-      &.has-divider-3:not(.has-divider-2)::after,
-      // when only 3rd-divider is present
-      &.has-divider-3:not(.has-divider-1):not(.has-divider-2)::before {
-        grid-row: 4;
-      }
+    // When 3rd-divider is present and 1st-divider is not present
+    &.has-divider-3:not(.has-divider-1)::before,
+    // When 3rd-divider is present and 2nd-divider is not present
+    &.has-divider-3:not(.has-divider-2)::after,
+    // When only 3rd-divider is present
+    &.has-divider-3:not(.has-divider-1):not(.has-divider-2)::before {
+      grid-row: 4;
+    }
 
-      &.has-divider-3:not(.has-divider-1):not(.has-divider-2)::after {
-        display: none;
-      }
+    &.has-divider-3:not(.has-divider-1):not(.has-divider-2)::after {
+      display: none;
     }
   }
 
-  // support for 25-75 split on large screen size for this pattern
-  .row--25-75-on-large > .col,
-  .row > .col-9 {
-    & .p-equal-height-row {
-      grid-template-columns: repeat($grid-columns-small, minmax(0, 1fr));
+  // WRAP VARIANT
 
+  // This variant displays multiple columns side-by-side and wraps them at
+  // medium size; we have to unset some grid properties from the default
+  // variant to enable this functionality
+  .p-equal-height-row--wrap {
+    .p-equal-height-row__col {
       @media screen and ($breakpoint-small <= width < $breakpoint-large) {
-        grid-template-columns: repeat($grid-columns-medium, minmax(0, 1fr));
+        // Fit 2 columns onto each row at medium size
+        grid-column: span calc($grid-columns-medium / 2);
+        grid-template-columns: none;
+
+        .p-equal-height-row__item {
+          grid-column: auto;
+        }
+
+        .p-equal-height-row__item:first-child {
+          grid-row: auto;
+        }
       }
+    }
+  }
 
+  // ADVANCED GRID SUPPORT
+
+  // Support for 25-75 split on large screen size
+  .row--25-75-on-large > .col,
+  .row > .col-9 {
+    & .p-equal-height-row,
+    & .p-equal-height-row--wrap {
       @media screen and (width >= $breakpoint-large) {
         grid-template-columns: repeat(9, minmax(0, 1fr));
       }

package/scss/_patterns_image.scss

@@ -18,6 +18,8 @@
         Wraps contents in a container with an aspect ratio of 2.4:1.
       .p-image-container--square:
         Wraps contents in a container with an aspect ratio of 1:1.
+      .p-image-container--(16-9|3-2|2-3|cinematic|square)-on-(small|medium|large):
+        Wraps contents in a container with the specified aspect ratio on the specified breakpoint.
     Image:
       .p-image-container__image:
         Image element within an image container.
@@ -25,6 +27,54 @@
 
 @import 'settings';
 
+// Mapping of aspect ratio class names to their `aspect-ratio` values (width / height).
+$aspect-ratios: (
+  '16-9': calc(16 / 9),
+  '3-2': calc(3 / 2),
+  '2-3': calc(2 / 3),
+  'cinematic': 2.4,
+  'square': 1,
+);
+
+@mixin aspect-ratio-classes {
+  @each $aspect-ratio, $aspect-ratio-value in $aspect-ratios {
+    .p-image-container--#{$aspect-ratio} {
+      aspect-ratio: $aspect-ratio-value;
+    }
+  }
+
+  @each $breakpoint-name, $breakpoint-bounds-pair in $breakpoint-bounds {
+    $min-width: map-get($breakpoint-bounds-pair, min);
+    $max-width: map-get($breakpoint-bounds-pair, max);
+
+    @if $min-width and $max-width {
+      @media ($min-width <= width < $max-width) {
+        @each $aspect-ratio, $aspect-ratio-value in $aspect-ratios {
+          .p-image-container--#{$aspect-ratio}-on-#{$breakpoint-name} {
+            aspect-ratio: $aspect-ratio-value;
+          }
+        }
+      }
+    } @else if $min-width {
+      @media (width >= $min-width) {
+        @each $aspect-ratio, $aspect-ratio-value in $aspect-ratios {
+          .p-image-container--#{$aspect-ratio}-on-#{$breakpoint-name} {
+            aspect-ratio: $aspect-ratio-value;
+          }
+        }
+      }
+    } @else if $max-width {
+      @media (width < $max-width) {
+        @each $aspect-ratio, $aspect-ratio-value in $aspect-ratios {
+          .p-image-container--#{$aspect-ratio}-on-#{$breakpoint-name} {
+            aspect-ratio: $aspect-ratio-value;
+          }
+        }
+      }
+    }
+  }
+}
+
 @mixin vf-p-image {
   .p-image-container,
   [class^='p-image-container--'] {
@@ -54,21 +104,7 @@
     }
   }
 
-  .p-image-container--16-9 {
-    aspect-ratio: 16/9;
-  }
-  .p-image-container--3-2 {
-    aspect-ratio: 3/2;
-  }
-  .p-image-container--2-3 {
-    aspect-ratio: 2/3;
-  }
-  .p-image-container--cinematic {
-    aspect-ratio: 2.4/1;
-  }
-  .p-image-container--square {
-    aspect-ratio: 1/1;
-  }
+  @include aspect-ratio-classes;
 
   // Deprecated; will be removed in v5
   .p-image--bordered {

package/scss/_patterns_links.scss

@@ -41,7 +41,7 @@
     top: -999px;
 
     &:focus {
-      @include vf-focus;
+      @include vf-focus-themed;
 
       left: 0;
       padding: $spv--x-small;