barbican-reset 2.34.0 → 2.36.0

package/README.md

@@ -8,10 +8,10 @@ The Barbican Reset is an NPM module created to maintain consistency between the
 
 1. Setup
 2. Component library
-3. SCSS patterns
-4. Pattern library
-5. Font library
-6. SVG library
+3. SCSS documentation
+4. JS documentation
+5. Pattern library
+6. Font library
 
 ## 1. Setup
 
@@ -31,17 +31,15 @@ Spektrix iframe development: `@import "../../node_modules/barbican-reset/scss/in
 
 #### SCSS Mixins
 
-Vue.js: `@import "~barbican-reset/helpers";`
+Vue.js: `@import "~barbican-reset/scss/helpers";`
 
 > The Barbican ticketing site makes SCSS mixins globally available via the `vue.config.js` file
 
-Drupal: `@import "../node_modules/barbican-reset/helpers/index";`
-
-... fonts
+Drupal: `@import "../node_modules/barbican-reset/scss/helpers/index";`
 
 ## 2. Component library
 
-The component library is **only available to Vue.js** apps.
+The component library is currently **only available to Vue.js** apps.
 
 > Many components are available globally within the Barbican ticketing app. Check the main.js file to see which components are currently available. These won't need an additional import statement.
 
@@ -92,11 +90,25 @@ The BR naming convention imitates the Bootstrap example. This format is useful f
 2. It forces components to use a two word syntax, which is the recommended format for custom components. For example, <br-header> instead of <header>, which avoids clashing with native HTML5 components.
 ```
 
-## 3. SCSS patterns
+## 3. SCSS documentation
+
+We use SassDoc to document our SCSS. Here's some useful commands for working with this documentation:
+
+- To output the latest documentation and watch for changes to scss, run `gulp watch:css`
+- To view the documentation, open the file `sassdoc/index.html` in your browser. You will need to refresh this page to view any additional changes that you make.
 
 Most components have corresponding SCSS classes (and mixins) which allow us to implement consistent styling across our various frontends, irrespective of their HTML structure.
 
-## 4. Pattern library
+## 4. JS documentation
+
+We use JSDoc to document our Javascript. Here's some useful commands for working with this documentation:
+
+- To output the latest documentation and watch for changes to javascript, run `gulp watch:js`
+- To manually output documentation using gulp, run `gulp doc:js`
+- To manually output documentation using jsdoc, run `jsdoc gulpfile.js`
+- To view the documentation, open the file `out/index.html` in your browser. You will need to refresh this page to view any additional changes that you make.
+
+## 5. Pattern library
 
 The Barbican Reset includes a pattern library. This provides a single source of truth for all the SCSS contained within and allows us to view a whole family of Barbican styles alongside each other.
 
@@ -136,12 +148,8 @@ Mixins are useful for printing repetitive code, such as loops to the page. The p
 
 The pattern library was created as a single source of truth for Barbican styles and components. Unfortunately the components are only compatible with Vue.js currently and so the HTML markup is duplicated.
 
-## 5. Font library
-
-The Barbican Reset includes a SCSS mixin called `font-face` which constructs font paths...
-
-#### Future intent
+## 6. Font library
 
-To have this available on a url for assets... ie. assets.barbican.org.uk/supreme
+The Barbican Reset includes a SCSS mixin called `font-face` which defaults font-face urls to `https://www.barbican.org.uk/themes/barb22/fonts/`. This means none of digital projects need to host additional font files.
 
-## 6. SVG library
+> If you do need to host fonts locally, you can overwrite the path parameter in the `font-face` mixin to point to a local asset.

package/components/card_display.vue

@@ -6,7 +6,7 @@
         <live-icon :class="$style.svg" />
       </div>
     </div>
-    <img :class="$style.image" :src="image">
+    <img :class="$style.image" :src="image" />
     <div v-if="expired" :class="$style.title">
       <h4>Expired</h4>
     </div>
@@ -14,7 +14,7 @@
 </template>
 
 <script>
-import { LiveIcon } from 'barbican-reset/icons/stream'
+import { LiveIcon } from "barbican-reset/icons/stream";
 export default {
   name: "CardDisplay",
   components: { LiveIcon },
@@ -33,28 +33,31 @@ export default {
     },
     type: {
       type: String,
-      default: 'concert',
+      default: "concert",
     },
   },
   computed: {
     styleComponent() {
       const style = this.$style;
       let output = [style.component];
-      if (this.hero) { output.push(style.hero); }
+      if (this.hero) {
+        output.push(style.hero);
+      }
       return output;
     },
     styleButton() {
       const style = this.$style;
       let output = [style.button];
-      if (this.hero) { output.push(style.hero); }
+      if (this.hero) {
+        output.push(style.hero);
+      }
       return output;
-    }
-  }
-}
+    },
+  },
+};
 </script>
 
 <style lang="scss" scoped>
-
 .btn.btn-secondary {
   &:not(.hero) {
     border-radius: 50%;
@@ -68,12 +71,10 @@ export default {
     gap: 0.5rem;
   }
 }
-
 </style>
 
 <style lang="scss" module>
-
-@import "../helpers";
+@import "../scss/helpers";
 
 .svg {
   fill: white;
@@ -112,12 +113,11 @@ export default {
     right: 1.5rem;
     top: 1.5rem;
   }
-  
+
   .title {
     h4 {
       font-size: $h2-font-size;
     }
   }
 }
-
-</style>
+</style>

package/components/fluid_iframe.vue

@@ -5,26 +5,26 @@
       allowfullscreen
       frameborder="0"
       height="100%"
-      width="100%" 
-      :src="src" />
+      width="100%"
+      :src="src"
+    />
   </div>
 </template>
 
 <script>
 export default {
-  name: 'FluidIframe',
+  name: "FluidIframe",
   props: {
     src: {
       type: String,
-      required: true
-    }
-  }
+      required: true,
+    },
+  },
 };
 </script>
 
 <style lang="scss" module>
-
-@import "../helpers";
+@import "../scss/helpers";
 
 .component {
   border-radius: $border-radius-lg;
@@ -37,5 +37,4 @@ export default {
   position: absolute;
   @include inset(0);
 }
-
 </style>

package/package.json

@@ -64,15 +64,14 @@
     "gulp-sass": "^5.0.0",
     "gulp-sourcemaps": "^3.0.0",
     "gulp-uglify": "^3.0.2",
+    "js-doc": "^0.5.0",
     "luxon": "^3.2.1",
     "node-sass-tilde-importer": "^1.0.2",
     "nodemon": "^3.1.0",
-    "placeholder-loading": "^0.4.0",
     "pug": "^3.0.2",
     "sass": "^1.41.0",
-    "save-dev": "^0.0.1-security",
-    "serve-favicon": "^2.5.0",
-    "vue-slick-carousel": "^1.0.6"
+    "sassdoc": "^2.7.4",
+    "serve-favicon": "^2.5.0"
   },
   "devDependencies": {
     "bootstrap": "^5.1.3"
@@ -83,7 +82,6 @@
     "components/**/*",
     "dist/**/*",
     "fonts/*",
-    "helpers/**/*",
     "icons/**/*",
     "patterns/**/*",
     "logos/*",
@@ -106,5 +104,5 @@
     "build:patterns": "cd patterns && rm -rf html && pug views --out html"
   },
   "style": "dist/css/barbican-reset.css",
-  "version": "2.34.0"
+  "version": "2.36.0"
 }

package/patterns/scss/styles.scss

@@ -2,7 +2,7 @@
 @import "../../node_modules/bootstrap/scss/variables";
 @import "../../node_modules/bootstrap/scss/mixins";
 
-@import "../../helpers/index";
+@import "../../scss/helpers/index";
 
 @import "../../scss/br-alert";
 @import "../../scss/br-button";

package/scss/_atomic.scss

@@ -3,32 +3,57 @@ $text-aligns: 'left', 'center', 'right';
 $margins05: 'margin-top', 'margin-bottom', 'margin-right', 'margin-left';
 $paddings05: 'padding-top', 'padding-bottom', 'padding-right', 'padding-left';
 
-@each $gap in $gaps {
-  @for $i from 1 to 5 {
-    .#{$gap}-#{$i} {
-      #{$gap}: 1rem * $i;
+/// @group Atomic
+/// Generator for gap classes. Creates 5 variations
+/// @example .margin-top-1, .margin-top-2, .margin-top-3, .margin-top-4, .margin-top-5
+@mixin printGapClasses {
+  @each $gap in $gaps {
+    @for $i from 1 to 5 {
+      .#{$gap}-#{$i} {
+        #{$gap}: 1rem * $i;
+      }
     }
   }
 }
 
-@each $align in $text-aligns {
-  .text-align-#{$align} {
-    text-align: #{$align};
+/// @group Atomic
+/// Generator for text-align classes. Creates 3 variations
+/// @example .text-align-left, .text-align-center, .text-align-right
+@mixin printTextAlignClasses {
+  @each $align in $text-aligns {
+    .text-align-#{$align} {
+      text-align: #{$align};
+    }
   }
 }
 
-@each $margin in $margins05 {
-  .#{$margin}-05 {
-    #{$margin}: 0.5rem;
+/// @group Atomic
+/// Generator for margin half classes. Creates 4 variations
+/// @example .margin-top-05, .margin-bottom-05, .margin-right-05, .margin-left-05
+@mixin printMarginClasses {
+  @each $margin in $margins05 {
+    .#{$margin}-05 {
+      #{$margin}: 0.5rem;
+    }
   }
 }
 
-@each $padding in $paddings05 {
-  .#{$padding}-05 {
-    #{$padding}: 0.5rem;
+/// @group Atomic
+/// Generator for padding half classes. Creates 4 variations
+/// @example .padding-top-05, .padding-bottom-05, .padding-right-05, .padding-left-05
+@mixin printPaddingClasses {
+  @each $padding in $paddings05 {
+    .#{$padding}-05 {
+      #{$padding}: 0.5rem;
+    }
   }
 }
 
+@include printGapClasses;
+@include printTextAlignClasses;
+@include printMarginClasses;
+@include printPaddingClasses;
+
 .font-weight-700 {
   @include fontfamily-black;
 }
@@ -91,6 +116,7 @@ $paddings05: 'padding-top', 'padding-bottom', 'padding-right', 'padding-left';
   min-width: 3rem;
 }
 
+/// Class for visually hiding markup, while still allowing screen readers to parse the content
 .sr-only {
   @include sr-only;
-}
+}

package/scss/_br-alert.scss

@@ -1,4 +1,6 @@
-
+/// @group Components
+/// BrAlert component class
+/// @example .br-alert.center .wrap.inline.error
 .br-alert {
   @include br-alert--setup;
 
@@ -10,14 +12,16 @@
     @include br-alert-wrap--colors($neutral_wrap...);
     @include br-alert-wrap--setup;
 
-    .btn.btn-link, a {
+    .btn.btn-link,
+    a {
       @include br-alert-link($neutral_focus...);
     }
 
     &.error {
       @include br-alert-wrap--colors($error_wrap...);
 
-      .btn.btn-link, a {
+      .btn.btn-link,
+      a {
         @include br-alert-link($error_focus...);
       }
     }
@@ -25,7 +29,8 @@
     &.success {
       @include br-alert-wrap--colors($success_wrap...);
 
-      .btn.btn-link, a {
+      .btn.btn-link,
+      a {
         @include br-alert-link($success_focus...);
       }
     }
@@ -41,7 +46,7 @@
     p {
       margin-bottom: 0;
 
-      + p {
+      +p {
         margin-top: 1rem;
       }
     }

package/scss/_br-button.scss

@@ -1,74 +1,120 @@
+/// Button component setup class. 
+/// Used in combination with a button style class
+/// @group Buttons
+/// @example .btn.btn-primary
 .btn {
   @include setup-button;
+}
+
+/// Primary button. 
+/// Defaults to solid orange. Borders orange on focus.
+/// @group Buttons
+.btn.btn-primary {
+  @include btn-primary;
+}
+
+/// Primary outline button. 
+/// Defaults to orange outline. Fills orange on focus
+/// @group Buttons
+.btn.btn-outline-primary {
+  @include btn-outline-primary;
+}
+
+/// Primary outline header button. 
+/// Defaults to white outline. Fills white on focus
+/// @group Buttons
+.btn.btn-outline-header {
+  @include btn-outline-header;
+}
+
+/// Info button. 
+/// Defaults to solid blue. Borders blue on focus.
+/// @group Buttons
+.btn.btn-info {
+  @include btn-info;
+}
+
+/// Primary outline info button. 
+/// Defaults to blue outline. Fills blue on focus
+/// @group Buttons
+.btn.btn-outline-info {
+  @include btn-outline-info;
+}
+
+/// Secondary button. 
+/// Defaults to solid grey. Borders grey on focus.
+/// @group Buttons
+.btn.btn-secondary {
+  @include btn-secondary;
+}
+
+/// Primary outline info button. 
+/// Defaults to grey outline. Fills grey on focus
+/// @group Buttons
+.btn.btn-outline-secondary {
+  @include btn-outline-secondary;
+}
+
+/// Input edit button. 
+/// Semi circular control for lockable input fields. 
+/// Defaults to grey outline. Fills grey on focus.
+/// @group Buttons
+.btn.btn-input-edit {
+  @include btn-input-edit;
+}
+
+/// Remove button. 
+/// Used only by StreamDonation.vue component. Could be deprecated.
+/// Defaults to slim solid grey. Borders grey on focus.
+/// @group Buttons
+.btn.btn-remove {
+  @include btn-remove;
+}
+
+/// Link button.
+/// Imitates the appearance of an anchor link. 
+/// Defaults to transparent fill. Fills grey on focus.
+/// @group Buttons
+.btn.btn-link {
+  @include btn-link;
+}
+
+/// Video help button.
+/// Apparently no longer used. Could be deprecated.
+/// @group Buttons
+.btn.btn-video-help {
+  @include btn-video-help;
+}
+
+/// Exit button.
+/// Circular close button. Used in the BrAlert component.
+/// @group Buttons
+.btn.btn-exit {
+  @include btn-exit;
+}
+
+/// Remove ticket button.
+/// Used in the basket to remove items or donations.
+/// @group Buttons
+.btn.btn-remove-ticket {
+  @include btn-remove-ticket;
+}
+
+/// Remove gift button.
+/// Used in the basket to remove items or donations.
+/// @group Buttons
+.btn.btn-remove-gift {
+  @include btn-remove-gift;
+}
+
+/// Membership card button.
+/// Used for membership renewals.
+/// @group Buttons
+.btn.btn-membership-card {
+  @include btn-membership-card;
+}
 
-  &.btn-primary {
-    // solid orange
-    @include btn-primary;
-  }
-
-  &.btn-outline-primary {
-    // orange outline, fill on focus
-    @include btn-outline-primary;
-  }
-
-  &.btn-outline-header {
-    // orange outline, fill on focus
-    @include btn-outline-header;
-  }
-
-  &.btn-info {
-    // solid blue
-    @include btn-info;
-  }
-
-  &.btn-outline-info {
-    // blue outline, fill on focus
-    @include btn-outline-info;
-  }
-
-  &.btn-secondary {
-    // solid grey
-    @include btn-secondary;
-  }
-
-  &.btn-outline-secondary {
-    // grey outline, fill on focus
-    @include btn-outline-secondary;
-  }
-
-  &.btn-input-edit {
-    @include btn-input-edit;
-  }
-
-  &.btn-remove {
-    // solid grey, slim
-    @include btn-remove;
-  }
-
-  &.btn-link {
-    @include btn-link;
-  }
-
-  &.btn-video-help {
-    @include btn-video-help;
-  }
-
-  &.btn-exit {
-    @include btn-exit;
-  }
-
-  &.btn-remove-ticket {
-    @include btn-remove-ticket;
-  }
-
-  &.btn-remove-gift {
-    @include btn-remove-gift;
-  }
-
-  &.btn-membership-card {
-    @include btn-membership-card;
-  }
-
+.btn {
   &.btn-video-login {
     @include btn-video-login;
   }

package/{helpers → scss/helpers}/mixins/_font.scss

@@ -1,4 +1,4 @@
-@mixin font-face($name: "SupremeLLWeb", $path: "/fonts/") {
+@mixin font-face($name: "SupremeLLWeb", $path: "https://www.barbican.org.uk/themes/barb22/fonts/") {
   @font-face {
     font-family: "Supreme-Light";
     src: url("#{$path}#{$name}-Light.woff") format("woff"),

package/{helpers → scss/helpers}/mixins/_headings.scss

@@ -1,3 +1,5 @@
+/// Generic margin/font weight reset for title headings
+/// @param {String} $margin [0] - pixel value 
 @mixin br-heading($margin: 0) {
   @include fontfamily-black;
   margin: $margin;

package/scss/helpers/variables/colors/_brand.scss

@@ -0,0 +1,96 @@
+/// $c-brand-art
+$c-brand-art: hsl(329, 100%, 45%);
+/// $c-brand-cinema
+$c-brand-cinema: hsl(126, 62%, 33%);
+/// $c-brand-classical
+$c-brand-classical: hsl(38, 53%, 38%);
+/// $c-brand-contemporary
+$c-brand-contemporary: hsl(254, 44%, 33%);
+$c-brand-generic: hsl(21, 100%, 41%);
+$c-brand-membership: hsl(217, 72%, 53%);
+$c-brand-programme: $c-grey-l21;
+$c-brand-shop: hsl(168, 75%, 30%);
+$c-brand-talks: hsl(214, 30%, 49%);
+$c-brand-theatre: hsl(192, 99%, 31%);
+
+$c-patron: $c-grey-l44;
+$c-patron-light: hsl(0, 0%, 60%);
+$c-principle: $c-brand-classical;
+$c-principle-light: hsl(38, 53%, 53%);
+
+/// see map-merge for example usage. talks--workshops is deprecated, use talks--events instead.
+$setup: (
+  contemporary-music: $c-brand-contemporary,
+  membership--support: $c-brand-membership,
+  tours--public-spaces: $c-brand-generic,
+  classical-music: $c-brand-classical,
+  talks--workshops: $c-brand-talks,
+  theatre--dance: $c-brand-theatre,
+  talks--events: $c-brand-talks,
+  art--design: $c-brand-art,
+  generic: $c-brand-generic,
+  library: $c-brand-generic,
+  cinema: $c-brand-cinema,
+  hire: $c-brand-generic,
+  programme: $c-brand-programme,
+  shop: $c-brand-shop,
+); 
+
+/// brands map will contain a shade map for each color variable
+$brands: ();
+
+/// map-brands automates the process of creating tints/shades for individual colors.
+@function map-brands($color) {
+  $map: (
+    shade-65: shade($color, 65%),
+    shade-20: shade($color, 20%),
+    shade-10: shade($color, 10%),
+    base: $color,
+    tint-40: tint($color, 40%),
+    tint-70: tint($color, 70%),
+    tint-85: tint($color, 85%),
+    tint-95: tint($color, 95%),
+    tint-98: tint($color, 98%),
+  );
+@return $map;
+}
+
+/// this process loops through the $setup map and creates a mappable value for each item, then merges the item into the $brands map
+@each $key, $value in $setup { 
+  $map: ();
+  $map: map-merge($map, ($key: map-brands($value)));
+  $brands: map-merge($brands, $map);
+}
+
+/// utility function for referencing a color variant from the brands map
+/// @param {Map} $name - color reference from the $setup map 
+/// @param {String} $variant - shade reference from the map-brands function
+@function brandColor($name, $variant: base) {
+  @return map-get(map-get($brands, $name), $variant); 
+}
+
+$c-background-alt: brandColor(generic, tint-95);
+
+/// @deprecated $c-brand-cinema-dark
+$c-brand-cinema-dark: brandColor(cinema, shade-20);
+/// @deprecated $c-brand-shop-light
+$c-brand-shop-light: brandColor(shop, tint-85);
+/// @deprecated $c-brand-shop-dark
+$c-brand-shop-dark: brandColor(shop, shade-20);
+
+/// @deprecated $c-brand-faint?
+$c-brand-generic-s60-l99: brandColor(generic, tint-95);
+/// @deprecated $c-brand-light?
+$c-brand-generic-s100-l95: brandColor(generic, tint-85);
+/// @deprecated $c-brand-shade?
+$c-brand-generic-s50-l90: brandColor(generic, tint-70);
+/// @deprecated $c-brand-dark?
+$c-brand-generic-s100-l38: brandColor(generic, shade-10);
+/// @deprecated $c-brand-x-dark?
+$c-brand-generic-s100-l15: brandColor(generic, shade-65);
+/// @deprecated $c-brand-classical-light
+$c-brand-classical-light: brandColor(classical-music, tint-95);
+/// @deprecated $c-brand-classical-dark
+$c-brand-classical-dark: brandColor(classical-music, shade-20);
+
+$c-brand-membership-dark: hsl(223, 87%, 21%);

package/scss/index.scss

@@ -1,7 +1,8 @@
 @import "node_modules/bootstrap/scss/functions";
 @import "node_modules/bootstrap/scss/variables";
 @import "node_modules/bootstrap/scss/mixins";
-@import "../helpers/index";
+
+@import "helpers/index";
 
 @include font-face;
 
@@ -105,8 +106,8 @@ p+p {
   margin-top: 1rem;
 }
 
+/// b tag in use on iframes
 strong,
 b {
-  // b tag in use on iframes
   @include fontfamily-black;
 }

package/helpers/variables/colors/_brand.scss

@@ -1,79 +0,0 @@
-$c-brand-art: hsl(329, 100%, 45%);
-$c-brand-cinema: hsl(126, 62%, 33%);
-$c-brand-classical: hsl(38, 53%, 38%);
-$c-brand-contemporary: hsl(254, 44%, 33%);
-$c-brand-generic: hsl(21, 100%, 41%);
-$c-brand-membership: hsl(217, 72%, 53%);
-$c-brand-programme: $c-grey-l21;
-$c-brand-shop: hsl(168, 75%, 30%);
-$c-brand-talks: hsl(214, 30%, 49%);
-$c-brand-theatre: hsl(192, 99%, 31%);
-
-$c-patron: $c-grey-l44;
-$c-patron-light: hsl(0, 0%, 60%);
-$c-principle: $c-brand-classical;
-$c-principle-light: hsl(38, 53%, 53%);
-
-$setup: (
-  contemporary-music: $c-brand-contemporary,
-  membership--support: $c-brand-membership,
-  tours--public-spaces: $c-brand-generic,
-  classical-music: $c-brand-classical,
-  talks--workshops: $c-brand-talks,
-  // deprecated
-  theatre--dance: $c-brand-theatre,
-  talks--events: $c-brand-talks,
-  art--design: $c-brand-art,
-  generic: $c-brand-generic,
-  library: $c-brand-generic,
-  cinema: $c-brand-cinema,
-  hire: $c-brand-generic,
-  programme: $c-brand-programme,
-  shop: $c-brand-shop,
-);
-
-$brands: (
-);
-
-@function map-brands($color) {
-  $map: (
-    shade-65: shade($color, 65%),
-    shade-20: shade($color, 20%),
-    shade-10: shade($color, 10%),
-    base: $color,
-    tint-40: tint($color, 40%),
-    tint-70: tint($color, 70%),
-    tint-85: tint($color, 85%),
-    tint-95: tint($color, 95%),
-    tint-98: tint($color, 98%),
-  );
-@return $map;
-}
-
-@each $key, $value in $setup {
-  $map: (
-  );
-$map: map-merge($map,
-    ($key: map-brands($value),
-    ));
-$brands: map-merge($brands, $map);
-}
-
-@function brandColor($name, $variant: base) {
-  @return map-get(map-get($brands, $name), $variant);
-}
-
-$c-background-alt: brandColor(generic, tint-95);
-
-$c-brand-cinema-dark: brandColor(cinema, shade-20); // deprecated
-$c-brand-shop-light: brandColor(shop, tint-85); // deprecated
-$c-brand-shop-dark: brandColor(shop, shade-20); // deprecated
-$c-brand-generic-s60-l99: brandColor(generic, tint-95); // faint deprecated
-$c-brand-generic-s100-l95: brandColor(generic, tint-85); // light deprecated
-$c-brand-generic-s50-l90: brandColor(generic, tint-70); // shade deprecated
-$c-brand-generic-s100-l38: brandColor(generic, shade-10); // dark deprecated
-$c-brand-generic-s100-l15: brandColor(generic, shade-65); // x-dark deprecated
-
-$c-brand-classical-light: brandColor(classical-music, tint-95); // deprecated
-$c-brand-classical-dark: brandColor(classical-music, shade-20); // deprecated
-$c-brand-membership-dark: hsl(223, 87%, 21%);