@ons/design-system 74.0.0-next.3 → 74.0.0-next.5

package/README.md

@@ -143,11 +143,21 @@ Checkout the branch locally and run:
 
 `yarn test-visual` - This will run the same tests locally as were run in Github Actions. After they have completed the report will open in your default browser.
 
+### Handling VR test failures
+
+If the VR tests fail locally, you can review the changes in your browser. Note that the error you'll see if the VR tests fail starts with `Error: docker run --rm -i --add-host=host.docker.internal:host-gateway...`
+
+`npx http-server backstop_data/html_report -p 8080` - View the results of the yarn visual tests in your browser. Using http-server rather than simply opening the file ensures the associated JavaScript runs.
+
+### Approving VR test reference image changes
+
 `yarn test-visual:approve` - This will approve the failures/diff caught by the tests.
 
-`git lfs push --all origin` - First commit the files in the normal way then run the command. This will push the new reference images to Git LFS.
+Commit and approve the file changes in the normal way.
+
+`git lfs push --all origin` - This will push the new reference images to Git LFS.
 
-You can then commit and push the updated references and your changes to your branch. The test images that would have been created when you ran `yarn test-visual` are gitignored and the new references images will be pushed to Git LFS.
+You can then push the updated references and your changes to your branch. The test images that would have been created when you ran `yarn test-visual` are gitignored and the new references images will be pushed to Git LFS.
 
 If your local tests are failing but you have approved them, run `yarn test-visual:reference`. This will update the reference images locally on your machine.
 
@@ -176,7 +186,7 @@ yarn add @ons/design-system@next
 
 ### Publishing the stable major
 
-1. Merge `next` into `main`.
+1. Merge `next` into `main`. **Do not squash; use a regular merge commit to preserve history.**
 2. Create a normal release tag, for example: `74.0.0`.
 3. Publish the GitHub Release (not marked as a pre-release).
 

package/components/access-code/example-access-code-error.njk

@@ -14,7 +14,7 @@ layout: ~
     }
 %}
 
-{% block main %}
+{% block mainContent %}
     {%
         call onsPanel({
             "title": "There is a problem with this page",

package/components/access-code/example-access-code.njk

@@ -16,7 +16,7 @@ layout: ~
     }
 %}
 
-{% block main %}
+{% block mainContent %}
     <h1 class="ons-u-mt-2xl">Start study</h1>
 
     {{

package/components/back-to-top/example-full-page-back-to-top.njk

@@ -30,7 +30,7 @@ layout: ~
     }
 %}
 
-{% block main %}
+{% block mainContent %}
     <h1 class="ons-u-fs-2xl">
         <span class="ons-u-fs-m ons-u-db ons-u-mb-2xs ons-u-lighter">Press releases</span>
         <span class="ons-u-vh">: </span>

package/components/breadcrumbs/_breadcrumbs.scss

@@ -3,7 +3,7 @@ $breadcrumb-chevron-height: 0.65rem;
 .ons-breadcrumbs-wrapper {
     position: relative;
     z-index: 10;
-    margin-bottom: -2rem;
+    margin-bottom: -1rem;
     &--grey {
         background-color: var(--ons-color-banner-bg);
     }
@@ -14,9 +14,9 @@ $breadcrumb-chevron-height: 0.65rem;
 
     &--navy-blue {
         background-color: var(--ons-color-navy-blue-light);
-        margin-bottom: -1.75rem;
+        margin-bottom: -0.75rem;
         @include mq(l) {
-            margin-bottom: -3.25rem;
+            margin-bottom: -2.25rem;
         }
     }
 
@@ -48,15 +48,12 @@ $breadcrumb-chevron-height: 0.65rem;
     &--pale-blue {
         background-color: var(--ons-color-pale-blue);
     }
-    .ons-breadcrumbs {
-        padding: 1rem;
-    }
 }
 
 .ons-breadcrumbs {
     align-items: center;
     display: flex;
-    padding: 1rem 0;
+    padding: 1rem 0 0;
 
     &__items {
         margin: 0;

package/components/breadcrumbs/_macro.njk

@@ -1,33 +1,37 @@
 {% from "components/icon/_macro.njk" import onsIcon %}
 {% macro onsBreadcrumbs(params) %}
     {% set breadcrumbs %}
-        <nav
-            class="ons-breadcrumbs{{ ' ons-container' if params.variant }}{{ ' ' + params.classes if params.classes else '' }}"
-            aria-label="{{ params.ariaLabel | default('Breadcrumbs') }}"
-            {% if params.id %}id="{{ params.id }}"{% endif %}
+        <div
+            class="ons-container{{ ' ons-container--full-width' if params.fullWidth else "" }}{{ ' ons-container--wide' if params.wide else "" }}"
         >
-            <ol class="ons-breadcrumbs__items ons-u-fs-s">
-                {%- for item in params.itemsList -%}
-                    <li
-                        class="ons-breadcrumbs__item{{ ' ' + item.itemClasses if item.itemClasses else '' }}"
-                        id="breadcrumb-{{ loop.index }}"
-                    >
-                        <a
-                            class="ons-breadcrumbs__link{{ ' ' + item.linkClasses if item.linkClasses else '' }}"
-                            href="{% if not isDesignSystemExample %}{{ item.url }}{% else %}#0{% endif %}"
-                            {% if item.id %}{{ ' ' }}id='{{ item.id }}'{% endif %}
-                            {% if item.attributes %}{% for attribute, value in (item.attributes.items() if item.attributes is mapping and item.attributes.items else item.attributes) %}{{ ' ' }}{{ attribute }}="{{ value }}"{% endfor %}{% endif %}
-                            >{{ item.text }}</a
+            <nav
+                class="ons-breadcrumbs{{ ' ' + params.classes if params.classes else '' }}"
+                aria-label="{{ params.ariaLabel | default('Breadcrumbs') }}"
+                {% if params.id %}id="{{ params.id }}"{% endif %}
+            >
+                <ol class="ons-breadcrumbs__items ons-u-fs-s">
+                    {%- for item in params.itemsList -%}
+                        <li
+                            class="ons-breadcrumbs__item{{ ' ' + item.itemClasses if item.itemClasses else '' }}"
+                            id="breadcrumb-{{ loop.index }}"
                         >
-                        {{-
-                            onsIcon({
-                                "iconType": "chevron"
-                            })
-                        -}}
-                    </li>
-                {%- endfor -%}
-            </ol>
-        </nav>
+                            <a
+                                class="ons-breadcrumbs__link{{ ' ' + item.linkClasses if item.linkClasses else '' }}"
+                                href="{% if not isDesignSystemExample %}{{ item.url }}{% else %}#0{% endif %}"
+                                {% if item.id %}{{ ' ' }}id='{{ item.id }}'{% endif %}
+                                {% if item.attributes %}{% for attribute, value in (item.attributes.items() if item.attributes is mapping and item.attributes.items else item.attributes) %}{{ ' ' }}{{ attribute }}="{{ value }}"{% endfor %}{% endif %}
+                                >{{ item.text }}</a
+                            >
+                            {{-
+                                onsIcon({
+                                    "iconType": "chevron"
+                                })
+                            -}}
+                        </li>
+                    {%- endfor -%}
+                </ol>
+            </nav>
+        </div>
     {% endset %}
     {% if params.variant %}
         <div class="ons-breadcrumbs-wrapper ons-breadcrumbs-wrapper--{{ params.variant }}">{{ breadcrumbs | safe }}</div>

package/components/breadcrumbs/_macro.spec.js

@@ -133,6 +133,45 @@ describe('FOR: Macro: Breadcrumbs', () => {
         });
     });
 
+    describe('GIVEN: Params: fullWidth', () => {
+        describe('WHEN: fullWidth is not provided', () => {
+            const $ = cheerio.load(renderComponent('breadcrumbs', EXAMPLE_BREADCRUMBS_REQUIRED_PARAMS));
+            test('THEN: renders container without full-width class', () => {
+                expect($('.ons-container').hasClass('ons-container--full-width')).toBe(false);
+            });
+        });
+        describe('WHEN: fullWidth is set to true', () => {
+            const $ = cheerio.load(
+                renderComponent('breadcrumbs', {
+                    ...EXAMPLE_BREADCRUMBS_REQUIRED_PARAMS,
+                    fullWidth: true,
+                }),
+            );
+            test('THEN: renders container with full-width class', () => {
+                expect($('.ons-container').hasClass('ons-container--full-width')).toBe(true);
+            });
+        });
+    });
+    describe('GIVEN: Params: wide', () => {
+        describe('WHEN: wide is not provided', () => {
+            const $ = cheerio.load(renderComponent('breadcrumbs', EXAMPLE_BREADCRUMBS_REQUIRED_PARAMS));
+            test('THEN: renders container without wide class', () => {
+                expect($('.ons-container').hasClass('ons-container--wide')).toBe(false);
+            });
+        });
+        describe('WHEN: wide is set to true', () => {
+            const $ = cheerio.load(
+                renderComponent('breadcrumbs', {
+                    ...EXAMPLE_BREADCRUMBS_REQUIRED_PARAMS,
+                    wide: true,
+                }),
+            );
+            test('THEN: renders container with wide class', () => {
+                expect($('.ons-container').hasClass('ons-container--wide')).toBe(true);
+            });
+        });
+    });
+
     describe('GIVEN: Params: variant', () => {
         describe('WHEN: variant is provided', () => {
             const $ = cheerio.load(

package/components/header/_macro.njk

@@ -6,6 +6,7 @@
     {% set titleTag = "h1" if params.titleAsH1 else "div" %}
     {% set openingTag = "<" + titleTag %}
     {% set closingTag = "</" + titleTag + ">" %}
+    {% set rootElementTag = "div" if params.useDivForRootElement else "header" %}
     {% set currentLanguageIsoCode = "en" %}
     {% set logoAltText = params.mastheadLogoAltText or params.mastheadLogo.altText %}
 
@@ -13,10 +14,11 @@
         {% set currentLanguage = params.language.languages | selectattr("current") | first %}
         {% set currentLanguageIsoCode = currentLanguage.isoCode %}
     {% endif %}
-
-    <header
+    <!-- prettier-ignore-start -->
+    <{{ rootElementTag | safe }}
         class="ons-header{{ ' '+ params.classes if params.classes }}{% if params.variants is not string %}{% for variant in params.variants %}{{ ' ' }}ons-header--{{ variant }}{% endfor %}{% else %}{{ ' ' }}ons-header--{{ params.variants }}{% endif %}"
     >
+    <!-- prettier-ignore-end -->
         {{
             onsBrowserBanner({
                 "lang": currentLanguageIsoCode,
@@ -535,5 +537,7 @@
         {% if params.navigation %}
             {{ onsNavigation(params) }}
         {% endif %}
-    </header>
+    <!-- prettier-ignore-start -->
+    </{{ rootElementTag | safe }}>
+    <!-- prettier-ignore-end -->
 {% endmacro %}

package/components/header/_macro.spec.js

@@ -36,6 +36,33 @@ describe('FOR: Macro: Header', () => {
         });
     });
 
+    describe('GIVEN: Params: useDivForRootElement', () => {
+        describe('WHEN: useDivForRootElement is not set', () => {
+            const $ = cheerio.load(
+                renderComponent('header', {
+                    ...EXAMPLE_HEADER_BASIC,
+                }),
+            );
+            test('THEN: renders the root element as a header tag', () => {
+                expect($('header.ons-header').length).toBe(1);
+            });
+        });
+        describe('WHEN: useDivForRootElement is set to true', () => {
+            const $ = cheerio.load(
+                renderComponent('header', {
+                    ...EXAMPLE_HEADER_BASIC,
+                    useDivForRootElement: true,
+                }),
+            );
+            test('THEN: renders the root element as a div tag', () => {
+                expect($('div.ons-header').length).toBe(1);
+            });
+            test('THEN: does not render a header tag as the root element', () => {
+                expect($('header.ons-header').length).toBe(0);
+            });
+        });
+    });
+
     describe('Accessibility: search heading', () => {
         test('THEN: axe passes when search heading is present (params.search.links.heading)', async () => {
             const params = {

package/components/hero/_macro.njk

@@ -21,7 +21,9 @@
                 {% endfor %}
             </div>
         {% endif %}
-        <div class="ons-hero__container ons-container{{ ' ons-container--wide' if params.wide }}">
+        <div
+            class="ons-hero__container ons-container{{ ' ons-container--wide' if params.wide }}{{ ' ons-container--full-width' if params.fullWidth }}"
+        >
             <div class="ons-hero__details ons-grid__col ons-col-{{ detailsColumns }}@m col-10@s@m">
                 <div class="ons-hero__content">
                     <div class="ons-hero__title-container">
@@ -44,7 +46,6 @@
                         {% elif params.richText %}
                             <div class="ons-hero__richtext">{{ params.richText | safe }}</div>
                         {% endif %}
-
                     </div>
 
                     {% if params.variants == "grey" and params.officialStatisticsBadge == true %}

package/components/hero/_macro.spec.js

@@ -34,6 +34,42 @@ describe('macro: hero', () => {
         expect($('.ons-hero--variant-b').length).toBe(1);
     });
 
+    it('has the `ons-container--wide` class on the container when `wide` is true', () => {
+        const $ = cheerio.load(renderComponent('hero', { ...EXAMPLE_HERO, wide: true }));
+
+        expect($('.ons-hero__container').hasClass('ons-container--wide')).toBe(true);
+    });
+
+    it('does not have the `ons-container--wide` class on the container when `wide` is false', () => {
+        const $ = cheerio.load(renderComponent('hero', { ...EXAMPLE_HERO, wide: false }));
+
+        expect($('.ons-hero__container').hasClass('ons-container--wide')).toBe(false);
+    });
+
+    it('does not have the `ons-container--wide` class on the container when `wide` is not set', () => {
+        const $ = cheerio.load(renderComponent('hero', EXAMPLE_HERO));
+
+        expect($('.ons-hero__container').hasClass('ons-container--wide')).toBe(false);
+    });
+
+    it('has the `ons-container--full-width` class on the container when `fullWidth` is true', () => {
+        const $ = cheerio.load(renderComponent('hero', { ...EXAMPLE_HERO, fullWidth: true }));
+
+        expect($('.ons-hero__container').hasClass('ons-container--full-width')).toBe(true);
+    });
+
+    it('does not have the `ons-container--full-width` class on the container when `fullWidth` is false', () => {
+        const $ = cheerio.load(renderComponent('hero', { ...EXAMPLE_HERO, fullWidth: false }));
+
+        expect($('.ons-hero__container').hasClass('ons-container--full-width')).toBe(false);
+    });
+
+    it('does not have the `ons-container--full-width` class on the container when `fullWidth` is not set', () => {
+        const $ = cheerio.load(renderComponent('hero', EXAMPLE_HERO));
+
+        expect($('.ons-hero__container').hasClass('ons-container--full-width')).toBe(false);
+    });
+
     it('has expected `title`', () => {
         const $ = cheerio.load(renderComponent('hero', EXAMPLE_HERO));
 

package/components/hero/example-hero-dark-wide.njk

@@ -0,0 +1,17 @@
+---
+'fullWidth': true
+---
+
+{% from "components/hero/_macro.njk" import onsHero %}
+{{
+    onsHero({
+        "title": 'Design and build digital services for the ONS',
+        "text": 'Everything you need to make accessible, consistent digital products',
+        "button": {
+            "url": '#0',
+            "text": 'Get started'
+        },
+        "variants": 'dark',
+        "wide": true
+    })
+}}

package/components/hero/example-hero-dark-with-external-breadcrumbs.njk

@@ -4,7 +4,6 @@ layout: ~
 ---
 
 {% from "components/hero/_macro.njk" import onsHero %}
-{% from "components/breadcrumbs/_macro.njk" import onsBreadcrumbs %}
 {% extends "layout/_template.njk" %}
 {%
     set pageConfig = {
@@ -162,12 +161,8 @@ layout: ~
                     }
                 ]
             }
-        }
-    }
-%}
-{% block pageContent %}
-    {{
-        onsBreadcrumbs({
+        },
+        "breadcrumbs": {
             "ariaLabel": 'Breadcrumbs',
             "variant": "dark",
             "itemsList": [
@@ -175,20 +170,21 @@ layout: ~
                     "url": '/',
                     "text": 'Home'
                 }
-            ]
+             ]
+        }
+    }
+%}
+
+{% block hero %}
+    {{
+        onsHero({
+            "title": 'Design and build digital services for the ONS',
+            "text": 'Everything you need to make accessible, consistent digital products',
+            "button": {
+                "url": '#0',
+                "text": 'Get started'
+            },
+            "variants": 'dark'
         })
     }}
-    <main id="main-content">
-        {{
-            onsHero({
-                "title": 'Design and build digital services for the ONS',
-                "text": 'Everything you need to make accessible, consistent digital products',
-                "button": {
-                    "url": '#0',
-                    "text": 'Get started'
-                },
-                "variants": 'dark'
-            })
-        }}
-    </main>
 {% endblock %}

package/components/hero/example-hero-default-full-width.njk

@@ -0,0 +1,16 @@
+---
+'fullWidth': true
+---
+
+{% from "components/hero/_macro.njk" import onsHero %}
+{{
+    onsHero({
+        "title": 'Design and build digital services for the ONS',
+        "text": 'Everything you need to make accessible, consistent digital products',
+        "button": {
+            "url": '#0',
+            "text": 'Get started'
+        },
+        "fullWidth": true
+    })
+}}