barbican-reset 3.30.0 → 3.31.0

package/README.md

@@ -2,154 +2,236 @@
 
 ## Introduction
 
-The Barbican Reset is an NPM module created to maintain consistency between the various digital projects run by the Barbican.
+Barbican Reset is an NPM package that provides a shared design system for Barbican digital projects — including SCSS utilities, Vue components, icons, animations, logos, and JS helpers.
 
 ## Contents
 
-1. Setup
-2. Component library
-3. SCSS documentation
-4. JS documentation
-5. Pattern library
-6. Font library
+- [Barbican Reset](#barbican-reset)
+  - [Introduction](#introduction)
+  - [Contents](#contents)
+  - [1. Setup](#1-setup)
+  - [2. Component library](#2-component-library)
+  - [3. SCSS](#3-scss)
+    - [Full stylesheet](#full-stylesheet)
+    - [Individual stylesheets](#individual-stylesheets)
+    - [Mixins](#mixins)
+    - [SCSS documentation](#scss-documentation)
+  - [4. Icons](#4-icons)
+  - [5. Animations](#5-animations)
+  - [6. Logos](#6-logos)
+  - [7. Scripts](#7-scripts)
+  - [8. Pattern library](#8-pattern-library)
+    - [Setup](#setup)
+    - [New pages](#new-pages)
+    - [Extending layouts](#extending-layouts)
+    - [Including components (mixins)](#including-components-mixins)
+  - [9. Font library](#9-font-library)
 
 ## 1. Setup
 
-You can install the Barbican Reset into any project by running `npm i barbican-reset` inside your project root folder.
+Install the package into any project:
 
-You can then manually import a component using `import { BrExample } from barbican-reset`
+```sh
+npm i barbican-reset
+```
 
-#### SCSS Stylesheet
+Import a component:
 
-Vue.js: `@import '~barbican-reset';`
+```js
+import { BrAlert } from 'barbican-reset'
+```
 
-> Use the ~ in Vue.js to import assets from the project root
+## 2. Component library
 
-Drupal: `@import "../node_modules/barbican-reset/scss/index";`
+The component library is **Vue 3 only**.
+
+> Many components are registered globally within the Barbican ticketing app. Check `main.js` to see which are available without an additional import.
+
+| Component                   | File                            |
+| --------------------------- | ------------------------------- |
+| `<br-alert>`                | BrAlert.vue                     |
+| `<br-anchor>`               | BrAnchor.vue                    |
+| `<br-button>`               | BrButton.vue                    |
+| `<br-card>`                 | BrCard.vue                      |
+| `<br-card-body>`            | BrCardBody.vue                  |
+| `<br-card-subtitle>`        | BrCardSubtitle.vue              |
+| `<br-card-tearoff>`         | BrCardTearoff.vue               |
+| `<br-card-text>`            | BrCardText.vue                  |
+| `<br-card-title>`           | BrCardTitle.vue                 |
+| `<br-collapse-button>`      | BrCollapse/Button.vue           |
+| `<br-collapse-content>`     | BrCollapse/Content.vue          |
+| `<br-confirm-done>`         | BrConfirmDone.vue               |
+| `<br-confirm-email>`        | BrConfirmEmail.vue              |
+| `<br-container>`            | BrContainer.vue                 |
+| `<br-details>`              | BrDetails.vue                   |
+| `<br-footer-lower>`         | BrFooterLower.vue               |
+| `<br-footer-upper>`         | BrFooterUpper.vue               |
+| `<br-form-block>`           | BrFormBlock.vue                 |
+| `<br-form-checkbox>`        | BrFormCheckbox.vue              |
+| `<br-form-checkbox-group>`  | BrFormCheckboxGroup.vue         |
+| `<br-form-date>`            | BrFormDate.vue                  |
+| `<br-form-edit>`            | BrFormEdit.vue                  |
+| `<br-form-email>`           | BrFormEmail.vue                 |
+| `<br-form-fieldset>`        | BrFormFieldset.vue              |
+| `<br-form-input>`           | BrFormInput.vue                 |
+| `<br-form-password>`        | BrFormPassword.vue              |
+| `<br-form-radio>`           | BrFormRadio.vue                 |
+| `<br-form-radio-group>`     | BrFormRadioGroup.vue            |
+| `<br-form-row>`             | BrFormRow.vue                   |
+| `<br-form-tel>`             | BrFormTel.vue                   |
+| `<br-form-textarea>`        | BrFormTextarea.vue              |
+| `<br-form-toggle>`          | BrFormToggle.vue                |
+| `<br-form-update>`          | BrFormUpdate.vue                |
+| `<br-form-visible>`         | BrFormVisible.vue               |
+| `<br-link>`                 | BrLink.vue                      |
+| `<br-loader>`               | BrLoader.vue                    |
+| `<br-overlay>`              | BrOverlay.vue                   |
+| `<br-skiplink>`             | BrSkiplink.vue                  |
+| `<br-status-bars>`          | BrStatusBars.vue                |
+| `<br-table-header>`         | BrTableHeader.vue               |
+| `<br-wrap>`                 | BrWrap.vue                      |
+
+> The `br-` prefix makes it immediately clear that a component is from Barbican Reset and not native to the app. It also ensures two-word component names, which is the recommended format for custom elements (e.g. `<br-header>` rather than `<header>`).
+
+## 3. SCSS
+
+### Full stylesheet
+
+```scss
+// Vite / webpack (resolves from node_modules automatically)
+@import 'barbican-reset/scss';
+
+// Explicit node_modules path (e.g. Drupal)
+@import '../node_modules/barbican-reset/scss';
+```
 
-Spektrix iframe development: `@import "../../node_modules/barbican-reset/scss/index.scss";`
+### Individual stylesheets
 
-#### SCSS Mixins
+The package exposes several standalone stylesheets:
 
-Vue.js: `@import "~barbican-reset/scss/helpers";`
+| Export                          | Description                        |
+| ------------------------------- | ---------------------------------- |
+| `barbican-reset/scss`           | Full stylesheet                    |
+| `barbican-reset/reset`          | CSS reset only                     |
+| `barbican-reset/typography`     | Typography styles                  |
+| `barbican-reset/lists`          | List styles                        |
+| `barbican-reset/supreme`        | Supreme font styles                |
 
-> The Barbican ticketing site makes SCSS mixins globally available via the `vue.config.js` file
+### Mixins
 
-Drupal: `@import "../node_modules/barbican-reset/scss/helpers/index";`
+```scss
+// Vite / webpack
+@import 'barbican-reset/scss/mixins';
 
-## 2. Component library
+// Explicit node_modules path
+@import '../node_modules/barbican-reset/scss/mixins';
+```
 
-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.
-
-> When manually importing components into Vue.js, be sure to declare the import as a Vue component as well
-
-You can reference any of the following components:
-
-| Component            | Filename            | SCSS Class           | SCSS Mixin       | Previously    |
-| -------------------- | ------------------- | -------------------- | ---------------- | ------------- |
-| `<br-alert>`         | BrAlert.vue         | .br-alert            | br-alert--setup  | -             |
-| `<br-anchor>`        | BrAnchor.vue        | .btn                 | setup-button     | -             |
-| `<br-button>`        | BrButton.vue        | .br-form-checkbox         | br-form-checkbox      | -             |
-| `<br-confirm-done>`  | BrConfirmDone.vue   | -                    | -                | -             |
-| `<br-confirm-email>` | BrConfirmEmail.vue  | -                    | -                | -             |
-| `<br-container>`     | BrContainer.vue     | .br-container--outer | -                | -             |
-| `<br-footer-lower>`  | br_footer_lower.vue | .br-footer-lower     | br-footer-lower  | -             |
-| `<br-footer-upper>`  | br_footer_upper.vue | .br-footer-upper     | br-footer-upper  | -             |
-| `<br-form-block>`    | BrFormBlock.vue     | -                    | -                | -             |
-| `<br-form-password>` | BrFormPassword.vue  | .br-form-password    | br-form-password | -             |
-| `<br-form-row>`      | BrFormRow.vue       | .br-form-row         | br-form-row      | -             |
-| `<br-form-update>`   | BrFormUpdate.vue    | .br-form-update      | br-form-update   | -             |
-| `<br-loader>`        | BrLoader.vue        | .br-loader           | -                | -             |
-| `<br-skiplink>`      | BrSkiplink.vue      | -                    | -                | `<skip-link>` |
-| `<br-wrap>`          | BrWrap.vue          | .br-wrap             | -                | -             |
-
-The following component titles are deprecated. You can still use them, but they will migrate to the BR naming convention in future.
-
-| Component         | Filename          | SCSS Class | SCSS Mixin |
-| ----------------- | ----------------- | ---------- | ---------- |
-| `<account-title>` | AccountTitle.vue  | -          | -          |
-| `<card-display>`  | card_display.vue  | -          | -          |
-| `<event-summary>` | EventSummary.vue  | -          | -          |
-| `<fluid-iframe>`  | FluidIframe.vue   | -          | -          |
-| `<help-row>`      | help_row.vue      | -          | -          |
-| `<placeholder>`   | placeholder.vue   | -          | -          |
-| `<payment-logo>`  | payment_logo.vue  | -          | -          |
-| `<related-card>`  | related_card.vue  | -          | -          |
-| `<related-title>` | related_title.vue | -          | -          |
-| `<related-row>`   | related_row.vue   | -          | -          |
-| `<type-text>`     | type_text.vue     | -          | -          |
-| `<video-content>` | VideoContent.vue  | -          | -          |
+> The Barbican ticketing site makes SCSS mixins globally available via `vue.config.js`, so individual component files do not need to import them explicitly.
 
+### SCSS documentation
+
+We use SassDoc to document SCSS. To generate and watch for changes:
+
+```sh
+npm run build:css
 ```
-The BR naming convention imitates the Bootstrap example. This format is useful for two reasons:
 
-1. It is immediately obvious that the component is imported from the Barbican Reset and is not native to the app.
+Open `sassdoc/index.html` in your browser to view the output.
+
+## 4. Icons
 
-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.
+Icons are Vue components exported from the `barbican-reset/icons` path.
+
+```js
+import { Cart, Close } from 'barbican-reset/icons'
 ```
 
-## 3. SCSS documentation
+Icon sub-groups are available at their own export paths:
 
-We use SassDoc to document our SCSS. Here's some useful commands for working with this documentation:
+```js
+import { Edit } from 'barbican-reset/icons/account'
+import { Done }  from 'barbican-reset/icons/confirm'
+import { Live }  from 'barbican-reset/icons/stream'
+```
 
-- 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.
+## 5. Animations
 
-Most components have corresponding SCSS classes (and mixins) which allow us to implement consistent styling across our various frontends, irrespective of their HTML structure.
+GSAP animation helpers are exported from `barbican-reset/animations`.
 
-## 4. JS documentation
+```js
+import { confirm } from 'barbican-reset/animations'
+```
+
+## 6. Logos
+
+SVG logo files are located in the `logos/` directory:
+
+- `barbican.svg`
+- `arts-council-england.svg`
+- `city-of-london.svg`
+- `lso.svg`
+
+## 7. Scripts
 
-We use JSDoc to document our Javascript. Here's some useful commands for working with this documentation:
+JS helper utilities are available at two export paths:
 
-- 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.
+```js
+// Top-level helpers barrel
+import helpers from 'barbican-reset/scripts/helpers'
 
-## 5. Pattern library
+// Vue composition API mixins (input helpers)
+import { useInput } from 'barbican-reset/mixins'
+```
 
-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.
+## 8. Pattern library
 
-#### Setup
+The pattern library provides a single source of truth for all SCSS styles and lets you view the full family of Barbican styles alongside each other.
 
-> If this is your first time viewing the pattern library, navigate to the **patterns** subfolder and run `npm i`
+### Setup
 
-From the root folder, run `npm run serve:patterns` and visit `https://localhost:3000` in the web browser
+> If this is your first time, navigate to the `patterns` subfolder and run `npm i`.
 
-#### New pages
+From the root folder:
 
-> Begin instructions from the **patterns** subfolder.
+```sh
+npm run serve:patterns
+```
 
-To create a new page in the pattern library, navigate to the **views** subfolder.
+Then open `http://localhost:3000` in your browser.
 
-Duplicate the `index.pug` file and rename it.
+### New pages
 
-#### Extending layouts
+> Run the following from the `patterns` subfolder.
 
-The first line of your new page reads `extends ../layouts/main`
+Navigate to the `views` subfolder and duplicate `index.pug`, then rename it.
 
-If you navigate to the `layouts` subfolder you will see a `main.pug` file. Pug syntax looks like abbreviated HTML markup but also includes `block content`. Blocks describe which areas the page can use to output content.
+### Extending layouts
 
-Layouts are useful for creating page templates, allowing pages to focus on content and removing the need for repetitive scafolding code.
+The first line of your page reads:
 
-#### Including components (mixins)
+```pug
+extends ../layouts/main
+```
 
-The second line of your new page reads `include ../components/samples`
+The `layouts/main.pug` file defines `block content` — the area your page can write into. Layouts are useful for page templates, removing the need for repetitive scaffolding code.
 
-If you navigate to the `components` subfolder you will see a `samples.pug` file. Pug syntax looks like abbreviated HTML markup but also includes `mixin Samples()`. Mixins can accept parameters, which they use to print HTML markup on the page.
+### Including components (mixins)
 
-To call the samples mixin from your new page, you might write `+Samples('Contemporary','contemporary-music')`
+The second line of your page reads:
 
-Mixins are useful for printing repetitive code, such as loops to the page. The parameters they accept are quite narrow though, so if you need more flexibility, it's best to extend a layout instead.
+```pug
+include ../components/samples
+```
 
-#### Future intent
+The `components/samples.pug` file defines `mixin Samples()`. Call it from your page like so:
 
-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.
+```pug
++Samples('Contemporary', 'contemporary-music')
+```
 
-## 6. Font library
+Mixins are useful for rendering repetitive markup. For more flexibility, extend a layout instead.
 
-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.
+## 9. Font 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.
+The package includes a `font-face` SCSS mixin that defaults font URLs to `https://static.barbican.org.uk/systems-public/fonts/subset/`, so no digital project needs to host its own font files.

package/animations/confirm.js

@@ -1,59 +1,61 @@
-import gsap from "gsap";
+import gsap from 'gsap'
 
+/** @type {gsap.TweenVars} Fade-in vars: animates element from transparent with a short delay */
 const fadeIn = {
   duration: 0.3,
   opacity: 0,
   delay: 0.3,
-};
+}
 
+/** @type {gsap.TweenVars} Explode vars: scales element up and fades it out */
 const explode = {
-  ease: "power1.out",
+  ease: 'power1.out',
   opacity: 0,
   scale: 1.5,
-};
+}
 
+/** @type {gsap.TimelineVars} Default timeline settings shared across all confirm animations */
 const defaults = {
   duration: 0.6,
-  ease: "power1.in",
-  transformOrigin: "center",
-};
-
+  ease: 'power1.in',
+  transformOrigin: 'center',
+}
+
+/**
+ * Animates the email confirmation card.
+ * Fades in the title, draws the envelope outline and fold SVG paths,
+ * explodes a cloned title, then slides in the arrow.
+ */
 export const animateEmail = () => {
-  const query = (target) => document.querySelector(`.card[email] ${target}`);
-  const title = query(".card-title");
-  const outline = query(".outline");
-  const arrow = query(".arrow");
-  const fold = query(".fold");
-  const tl = gsap.timeline({ defaults });
-
-  const clone = title.cloneNode(true);
-  clone.classList.add("clone");
-  title.after(clone);
-
-  tl.set(arrow, { opacity: 0 })
-    .from(title, fadeIn)
-    .set(clone, { opacity: 0.4 })
-    .from(outline, { drawSVG: "0%" }, "start")
-    .from(fold, { drawSVG: "0%", duration: 0.3 }, "start")
-    .to(clone, explode, "start")
-    .set(arrow, { opacity: 1 })
-    .from(arrow, { x: -6, ease: "power1.out" });
-};
-
+  const query = (target) => document.querySelector(`.card[email] ${target}`)
+  const title = query('.card-title')
+  const outline = query('.outline')
+  const arrow = query('.arrow')
+  const fold = query('.fold')
+  const tl = gsap.timeline({ defaults })
+
+  const clone = title.cloneNode(true)
+  clone.classList.add('clone')
+  title.after(clone)
+
+  tl.set(arrow, { opacity: 0 }).from(title, fadeIn).set(clone, { opacity: 0.4 }).from(outline, { drawSVG: '0%' }, 'start').from(fold, { drawSVG: '0%', duration: 0.3 }, 'start').to(clone, explode, 'start').set(arrow, { opacity: 1 }).from(arrow, { x: -6, ease: 'power1.out' })
+}
+
+/**
+ * Animates the done confirmation card.
+ * Fades in the title, draws the circle outline and tick SVG paths,
+ * and explodes a cloned title.
+ */
 export const animateDone = () => {
-  const query = (target) => document.querySelector(`.card[done] ${target}`);
-  const title = query(".card-title");
-  const outline = query(".outline");
-  const tick = query(".tick");
-  const tl = gsap.timeline({ defaults });
-
-  const clone = title.cloneNode(true);
-  clone.classList.add("clone");
-  title.after(clone);
-
-  tl.from(title, fadeIn)
-    .set(clone, { opacity: 0.4 })
-    .from(outline, { drawSVG: "0%" }, "start")
-    .from(tick, { drawSVG: "0%", duration: 0.3 }, "start+=0.3")
-    .to(clone, explode, "start");
-};
+  const query = (target) => document.querySelector(`.card[done] ${target}`)
+  const title = query('.card-title')
+  const outline = query('.outline')
+  const tick = query('.tick')
+  const tl = gsap.timeline({ defaults })
+
+  const clone = title.cloneNode(true)
+  clone.classList.add('clone')
+  title.after(clone)
+
+  tl.from(title, fadeIn).set(clone, { opacity: 0.4 }).from(outline, { drawSVG: '0%' }, 'start').from(tick, { drawSVG: '0%', duration: 0.3 }, 'start+=0.3').to(clone, explode, 'start')
+}

package/components/BrFormCheckbox.vue

@@ -1,5 +1,5 @@
 <template>
-  <div class="br-form-checkbox">
+  <div :class="['br-form-checkbox', { block }]">
     <br-form-label
       :class="[{ success }, { error }]"
       :disabled="disabled"
@@ -11,7 +11,7 @@
         v-bind="$attrs"
         type="checkbox"
         :error="error" />
-      <span class="label-text">
+      <span v-if="$slots.default" class="label-text">
         <slot />
       </span>
     </br-form-label>
@@ -29,21 +29,11 @@ defineOptions({
 })
 
 const props = defineProps({
-  id: {
-    type: String,
-  },
-  disabled: {
-    default: false,
-    type: Boolean,
-  },
-  success: {
-    default: false,
-    type: Boolean,
-  },
-  error: {
-    default: false,
-    type: Boolean,
-  },
+  id: String,
+  disabled: Boolean,
+  success: Boolean,
+  error: Boolean,
+  block: Boolean,
 })
 
 // @description Returns a string for the "id" attribute

package/components/BrFormCheckboxGroup.vue

@@ -8,6 +8,7 @@
       :value="option.value"
       :success="success"
       v-model="model"
+      :block="block"
       :error="error"
       :name="name">
       <slot v-if="$slots.default" v-bind="option" />
@@ -31,13 +32,8 @@ const model = defineModel()
 const props = defineProps({
   options: Array,
   name: String,
-  success: {
-    default: false,
-    type: Boolean,
-  },
-  error: {
-    default: false,
-    type: Boolean,
-  },
+  success: Boolean,
+  error: Boolean,
+  block: Boolean,
 })
 </script>

package/components/BrSkiplink.vue

@@ -1,6 +1,6 @@
 <template>
   <a :href="href" class="br-skiplink">
-    <slot></slot>
+    <slot />
   </a>
 </template>
 
@@ -12,5 +12,5 @@ export default {
       required: true,
     },
   },
-};
+}
 </script>

package/index.js

@@ -28,6 +28,7 @@ import BrFormEdit from '#components/BrFormEdit.vue'
 import BrFormEmail from '#components/BrFormEmail.vue'
 import BrFormFieldset from '#components/BrFormFieldset.vue'
 import BrFormInput from '#components/BrFormInput.vue'
+import BrFormLabel from '#components/BrFormLabel.vue'
 import BrFormPassword from '#components/BrFormPassword.vue'
 import BrFormRadio from '#components/BrFormRadio.vue'
 import BrFormRadioGroup from '#components/BrFormRadioGroup.vue'
@@ -73,6 +74,7 @@ export {
   BrFormEmail,
   BrFormFieldset,
   BrFormInput,
+  BrFormLabel,
   BrFormPassword,
   BrFormRadio,
   BrFormRadioGroup,

package/mixins/inputs.js

@@ -1,5 +1,14 @@
+/**
+ * Mixin providing common computed properties and methods for input components.
+ * Handles v-model binding, autocomplete attributes, data-test attributes,
+ * input type normalization, label association, and ID generation.
+ */
 export default {
   computed: {
+    /**
+     * Two-way binding for the component's modelValue prop.
+     * @type {*}
+     */
     value: {
       get() {
         return this.modelValue
@@ -8,6 +17,12 @@ export default {
         this.$emit('update:modelValue', value)
       },
     },
+
+    /**
+     * Derives the HTML autocomplete attribute value based on the input's id,
+     * type, or explicit autocomplete prop.
+     * @returns {string|null} Kebab-cased autocomplete token, or null if not applicable.
+     */
     generateAutoComplete() {
       let result = null
 
@@ -21,6 +36,11 @@ export default {
 
       return result && this.createKebabCase(result)
     },
+
+    /**
+     * Derives the data-test attribute value from the id or explicit dataTest prop.
+     * @returns {string|null} Kebab-cased test identifier, or null if neither prop is set.
+     */
     generateDataTest() {
       let result = null
 
@@ -30,6 +50,11 @@ export default {
 
       return result && this.createKebabCase(result)
     },
+
+    /**
+     * Normalizes the input type, defaulting to "text" if no type prop is provided.
+     * @returns {string} Kebab-cased input type string.
+     */
     generateType() {
       let result = 'text'
 
@@ -37,6 +62,12 @@ export default {
 
       return this.createKebabCase(result)
     },
+
+    /**
+     * Derives the `for` attribute value to associate a label with its input.
+     * Prefers id over label text. Returns null if no label is present.
+     * @returns {string|null} Kebab-cased for attribute value, or null if no label.
+     */
     generateFor() {
       let result = null
 
@@ -48,6 +79,12 @@ export default {
 
       return result && this.createKebabCase(result)
     },
+
+    /**
+     * Derives the input's id attribute, falling back to a random integer-based
+     * value if no id prop is provided.
+     * @returns {string} Kebab-cased id string.
+     */
     generateID() {
       let result = 'random_' + Math.ceil(Math.random() * 1000000)
 
@@ -57,6 +94,11 @@ export default {
     },
   },
   methods: {
+    /**
+     * Converts a string to kebab-case by lowercasing and replacing spaces with hyphens.
+     * @param {string} [value=''] - The string to convert.
+     * @returns {string} The kebab-cased string.
+     */
     createKebabCase(value = '') {
       value = String(value)
       return value.toLowerCase().split(' ').join('-')