@ons/design-system 74.0.0-next.6 → 74.0.0-next.7

package/components/figure/_macro.spec.js

@@ -0,0 +1,520 @@
+/** @jest-environment jsdom */
+
+import * as cheerio from 'cheerio';
+
+import axe from '../../tests/helpers/axe';
+import { renderComponent, templateFaker } from '../../tests/helpers/rendering';
+
+const EXAMPLE_FIGURE_BASIC = {
+    title: 'Figure title',
+    id: 'example-figure',
+};
+
+const EXAMPLE_FIGURE_FULL = {
+    id: 'example-figure',
+    headingLevel: 3,
+    figureNumber: 'Figure 1',
+    title: 'Remote working trends, 2019 to 2023',
+    subtitle: 'Percentage of workforce working from home at least one day per week',
+    caption: 'Source: Office for National Statistics',
+    audioDescription: 'A line chart showing the percentage of workers working from home rising from 12% in 2019 to 28% in 2023',
+    footnotes: {
+        title: 'Footnotes',
+        content: 'Data is seasonally adjusted.',
+    },
+    download: {
+        title: 'Download this chart',
+        itemsList: [
+            {
+                text: 'Remote working trends (CSV format, 2KB)',
+                url: '/data/remote-working.csv',
+                download: 'file',
+            },
+        ],
+    },
+};
+
+const CALLER_CONTENT = '<div class="test-content">Nested content</div>';
+
+describe('macro: figure', () => {
+    it('passes jest-axe checks', async () => {
+        const $ = cheerio.load(renderComponent('figure', EXAMPLE_FIGURE_FULL, CALLER_CONTENT));
+
+        const results = await axe($.html());
+        expect(results).toHaveNoViolations();
+    });
+
+    describe('figure element', () => {
+        it('renders a <figure> element', () => {
+            const $ = cheerio.load(renderComponent('figure', EXAMPLE_FIGURE_BASIC, CALLER_CONTENT));
+
+            expect($('figure.ons-figure').length).toBe(1);
+        });
+
+        it('has the provided `id` attribute', () => {
+            const $ = cheerio.load(renderComponent('figure', EXAMPLE_FIGURE_BASIC, CALLER_CONTENT));
+
+            expect($('.ons-figure').attr('id')).toBe('example-figure');
+        });
+
+        it('renders caller content inside the content area', () => {
+            const $ = cheerio.load(renderComponent('figure', EXAMPLE_FIGURE_BASIC, CALLER_CONTENT));
+
+            expect($('.ons-figure__content .test-content').length).toBe(1);
+            expect($('.ons-figure__content .test-content').text()).toBe('Nested content');
+        });
+    });
+
+    describe('useDivForRootElement', () => {
+        it('defaults to a <figure> element', () => {
+            const $ = cheerio.load(renderComponent('figure', EXAMPLE_FIGURE_BASIC, CALLER_CONTENT));
+
+            expect($('.ons-figure')[0].tagName).toBe('figure');
+        });
+
+        it('renders a <div> when useDivForRootElement is true', () => {
+            const $ = cheerio.load(
+                renderComponent(
+                    'figure',
+                    {
+                        ...EXAMPLE_FIGURE_BASIC,
+                        useDivForRootElement: true,
+                    },
+                    CALLER_CONTENT,
+                ),
+            );
+
+            expect($('.ons-figure')[0].tagName).toBe('div');
+        });
+
+        it('renders caption in a <figcaption> by default', () => {
+            const $ = cheerio.load(
+                renderComponent(
+                    'figure',
+                    {
+                        ...EXAMPLE_FIGURE_BASIC,
+                        caption: 'A caption',
+                    },
+                    CALLER_CONTENT,
+                ),
+            );
+
+            expect($('.ons-figure__caption')[0].tagName).toBe('figcaption');
+        });
+
+        it('renders caption in a <span> when useDivForRootElement is true', () => {
+            const $ = cheerio.load(
+                renderComponent(
+                    'figure',
+                    {
+                        ...EXAMPLE_FIGURE_BASIC,
+                        useDivForRootElement: true,
+                        caption: 'A caption',
+                    },
+                    CALLER_CONTENT,
+                ),
+            );
+
+            expect($('.ons-figure__caption')[0].tagName).toBe('span');
+            expect($('.ons-figure__caption').text().trim()).toBe('A caption');
+        });
+    });
+
+    // Caption rendering is covered by the useDivForRootElement tests above
+    it('does not render a figcaption when caption is not provided', () => {
+        const $ = cheerio.load(renderComponent('figure', EXAMPLE_FIGURE_BASIC, CALLER_CONTENT));
+
+        expect($('figcaption').length).toBe(0);
+    });
+
+    describe('figure number', () => {
+        it('renders the figure number when provided', () => {
+            const $ = cheerio.load(
+                renderComponent(
+                    'figure',
+                    {
+                        ...EXAMPLE_FIGURE_BASIC,
+                        figureNumber: 'Figure 1',
+                    },
+                    CALLER_CONTENT,
+                ),
+            );
+
+            expect($('.ons-figure__number').text()).toBe('Figure 1');
+        });
+
+        it('does not render the figure number when not provided', () => {
+            const $ = cheerio.load(renderComponent('figure', EXAMPLE_FIGURE_BASIC, CALLER_CONTENT));
+
+            expect($('.ons-figure__number').length).toBe(0);
+        });
+    });
+
+    describe('title', () => {
+        it('renders the title', () => {
+            const $ = cheerio.load(renderComponent('figure', EXAMPLE_FIGURE_BASIC, CALLER_CONTENT));
+
+            expect($('.ons-figure__title').text()).toBe('Figure title');
+        });
+
+        it('does not render the title when not provided', () => {
+            const $ = cheerio.load(
+                renderComponent(
+                    'figure',
+                    {
+                        id: 'example-figure',
+                    },
+                    CALLER_CONTENT,
+                ),
+            );
+
+            expect($('.ons-figure__title').length).toBe(0);
+        });
+    });
+
+    describe('subtitle', () => {
+        it('renders the subtitle when title is also provided', () => {
+            const $ = cheerio.load(
+                renderComponent(
+                    'figure',
+                    {
+                        ...EXAMPLE_FIGURE_BASIC,
+                        subtitle: 'A subtitle',
+                    },
+                    CALLER_CONTENT,
+                ),
+            );
+
+            expect($('.ons-figure__subtitle').text()).toBe('A subtitle');
+        });
+
+        it('does not render the subtitle when not provided', () => {
+            const $ = cheerio.load(renderComponent('figure', EXAMPLE_FIGURE_BASIC, CALLER_CONTENT));
+
+            expect($('.ons-figure__subtitle').length).toBe(0);
+        });
+
+        it('does not render the subtitle when title is not provided', () => {
+            const $ = cheerio.load(
+                renderComponent(
+                    'figure',
+                    {
+                        id: 'example-figure',
+                        subtitle: 'A subtitle',
+                    },
+                    CALLER_CONTENT,
+                ),
+            );
+
+            expect($('.ons-figure__subtitle').length).toBe(0);
+        });
+    });
+
+    describe('heading levels', () => {
+        it('defaults to h2 for the title and h3 for the subtitle', () => {
+            const $ = cheerio.load(
+                renderComponent(
+                    'figure',
+                    {
+                        ...EXAMPLE_FIGURE_BASIC,
+                        subtitle: 'A subtitle',
+                    },
+                    CALLER_CONTENT,
+                ),
+            );
+
+            expect($('.ons-figure__title')[0].tagName).toBe('h2');
+            expect($('.ons-figure__subtitle')[0].tagName).toBe('h3');
+        });
+
+        it('uses the provided headingLevel for the title', () => {
+            const $ = cheerio.load(
+                renderComponent(
+                    'figure',
+                    {
+                        ...EXAMPLE_FIGURE_BASIC,
+                        headingLevel: 3,
+                    },
+                    CALLER_CONTENT,
+                ),
+            );
+
+            expect($('.ons-figure__title')[0].tagName).toBe('h3');
+        });
+
+        it('renders the subtitle one level below the title', () => {
+            const $ = cheerio.load(
+                renderComponent(
+                    'figure',
+                    {
+                        ...EXAMPLE_FIGURE_BASIC,
+                        headingLevel: 4,
+                        subtitle: 'A subtitle',
+                    },
+                    CALLER_CONTENT,
+                ),
+            );
+
+            expect($('.ons-figure__title')[0].tagName).toBe('h4');
+            expect($('.ons-figure__subtitle')[0].tagName).toBe('h5');
+        });
+
+        it('renders footnotes heading two levels below when title and subtitle are provided', () => {
+            const faker = templateFaker();
+            const detailsSpy = faker.spy('details');
+
+            faker.renderComponent(
+                'figure',
+                {
+                    ...EXAMPLE_FIGURE_BASIC,
+                    headingLevel: 3,
+                    subtitle: 'A subtitle',
+                    footnotes: {
+                        title: 'Footnotes',
+                        content: 'Some notes.',
+                    },
+                },
+                CALLER_CONTENT,
+            );
+
+            expect(detailsSpy.occurrences[0].headingLevel).toBe(5);
+        });
+
+        it('renders footnotes heading one level below when only title is provided', () => {
+            const faker = templateFaker();
+            const detailsSpy = faker.spy('details');
+
+            faker.renderComponent(
+                'figure',
+                {
+                    ...EXAMPLE_FIGURE_BASIC,
+                    headingLevel: 3,
+                    footnotes: {
+                        title: 'Footnotes',
+                        content: 'Some notes.',
+                    },
+                },
+                CALLER_CONTENT,
+            );
+
+            expect(detailsSpy.occurrences[0].headingLevel).toBe(4);
+        });
+
+        it('renders footnotes at the base heading level when no title or subtitle is provided', () => {
+            const faker = templateFaker();
+            const detailsSpy = faker.spy('details');
+
+            faker.renderComponent(
+                'figure',
+                {
+                    id: 'example-figure',
+                    headingLevel: 3,
+                    footnotes: {
+                        title: 'Footnotes',
+                        content: 'Some notes.',
+                    },
+                },
+                CALLER_CONTENT,
+            );
+
+            expect(detailsSpy.occurrences[0].headingLevel).toBe(3);
+        });
+
+        it('renders download heading two levels below when title and subtitle are provided', () => {
+            const faker = templateFaker();
+            const detailsSpy = faker.spy('details');
+
+            faker.renderComponent(
+                'figure',
+                {
+                    ...EXAMPLE_FIGURE_BASIC,
+                    headingLevel: 3,
+                    subtitle: 'A subtitle',
+                    download: {
+                        title: 'Downloads',
+                        itemsList: [{ text: 'A file', url: '/file.csv', download: 'file' }],
+                    },
+                },
+                CALLER_CONTENT,
+            );
+
+            expect(detailsSpy.occurrences[0].headingLevel).toBe(5);
+        });
+
+        it('renders download heading one level below when only title is provided', () => {
+            const faker = templateFaker();
+            const detailsSpy = faker.spy('details');
+
+            faker.renderComponent(
+                'figure',
+                {
+                    ...EXAMPLE_FIGURE_BASIC,
+                    headingLevel: 3,
+                    download: {
+                        title: 'Downloads',
+                        itemsList: [{ text: 'A file', url: '/file.csv', download: 'file' }],
+                    },
+                },
+                CALLER_CONTENT,
+            );
+
+            expect(detailsSpy.occurrences[0].headingLevel).toBe(4);
+        });
+
+        it('renders download at the base heading level when no title or subtitle is provided', () => {
+            const faker = templateFaker();
+            const detailsSpy = faker.spy('details');
+
+            faker.renderComponent(
+                'figure',
+                {
+                    id: 'example-figure',
+                    headingLevel: 3,
+                    download: {
+                        title: 'Downloads',
+                        itemsList: [{ text: 'A file', url: '/file.csv', download: 'file' }],
+                    },
+                },
+                CALLER_CONTENT,
+            );
+
+            expect(detailsSpy.occurrences[0].headingLevel).toBe(3);
+        });
+    });
+
+    describe('audio description', () => {
+        it('renders a visually hidden description with the correct id', () => {
+            const $ = cheerio.load(
+                renderComponent(
+                    'figure',
+                    {
+                        ...EXAMPLE_FIGURE_BASIC,
+                        audioDescription: 'A detailed description of the content',
+                    },
+                    CALLER_CONTENT,
+                ),
+            );
+
+            expect($('.ons-u-vh').text()).toBe('A detailed description of the content');
+            expect($('.ons-u-vh').attr('id')).toBe('figure-audio-description-example-figure');
+        });
+
+        it('sets aria-describedby on the figure element', () => {
+            const $ = cheerio.load(
+                renderComponent(
+                    'figure',
+                    {
+                        ...EXAMPLE_FIGURE_BASIC,
+                        audioDescription: 'A detailed description of the content',
+                    },
+                    CALLER_CONTENT,
+                ),
+            );
+
+            expect($('.ons-figure').attr('aria-describedby')).toBe('figure-audio-description-example-figure');
+        });
+
+        it('does not render audio description when not provided', () => {
+            const $ = cheerio.load(renderComponent('figure', EXAMPLE_FIGURE_BASIC, CALLER_CONTENT));
+
+            expect($('.ons-u-vh').length).toBe(0);
+            expect($('.ons-figure').attr('aria-describedby')).toBeUndefined();
+        });
+    });
+
+    describe('footnotes', () => {
+        it('renders footnotes using the details component', () => {
+            const faker = templateFaker();
+            const detailsSpy = faker.spy('details');
+
+            faker.renderComponent(
+                'figure',
+                {
+                    ...EXAMPLE_FIGURE_BASIC,
+                    footnotes: {
+                        title: 'Footnotes',
+                        content: 'Some footnote content.',
+                    },
+                },
+                CALLER_CONTENT,
+            );
+
+            expect(detailsSpy.occurrences[0]).toEqual(
+                expect.objectContaining({
+                    id: 'figure-footnotes--example-figure',
+                    title: 'Footnotes',
+                    content: 'Some footnote content.',
+                }),
+            );
+        });
+
+        it('does not render footnotes when not provided', () => {
+            const faker = templateFaker();
+            const detailsSpy = faker.spy('details');
+
+            faker.renderComponent('figure', EXAMPLE_FIGURE_BASIC, CALLER_CONTENT);
+
+            expect(detailsSpy.occurrences.filter(Boolean).length).toBe(0);
+        });
+    });
+
+    describe('download', () => {
+        it('renders downloads using the details and list components', () => {
+            const faker = templateFaker();
+            const detailsSpy = faker.spy('details');
+
+            faker.renderComponent(
+                'figure',
+                {
+                    ...EXAMPLE_FIGURE_BASIC,
+                    download: {
+                        title: 'Download this image',
+                        itemsList: [
+                            {
+                                text: 'Image (JPG, 1.2MB)',
+                                url: '/img/example.jpg',
+                                download: 'file',
+                            },
+                        ],
+                    },
+                },
+                CALLER_CONTENT,
+            );
+
+            expect(detailsSpy.occurrences[0]).toEqual(
+                expect.objectContaining({
+                    id: 'figure-downloads--example-figure',
+                    title: 'Download this image',
+                }),
+            );
+        });
+
+        it('does not render downloads when not provided', () => {
+            const faker = templateFaker();
+            const detailsSpy = faker.spy('details');
+
+            faker.renderComponent('figure', EXAMPLE_FIGURE_BASIC, CALLER_CONTENT);
+
+            expect(detailsSpy.occurrences.filter(Boolean).length).toBe(0);
+        });
+
+        it('does not render downloads when itemsList is empty', () => {
+            const faker = templateFaker();
+            const detailsSpy = faker.spy('details');
+
+            faker.renderComponent(
+                'figure',
+                {
+                    ...EXAMPLE_FIGURE_BASIC,
+                    download: {
+                        title: 'Download this image',
+                        itemsList: [],
+                    },
+                },
+                CALLER_CONTENT,
+            );
+
+            expect(detailsSpy.occurrences.filter(Boolean).length).toBe(0);
+        });
+    });
+});

package/components/figure/example-figure-heading-level-2.njk

@@ -0,0 +1,34 @@
+{% from "components/figure/_macro.njk" import onsFigure %}
+
+{%
+    call onsFigure({
+        "headingLevel": 2,
+        "figureNumber": "Figure 1",
+        "title": "Image 1: Working from home",
+        "subtitle": "A growing proportion of the workforce now works remotely",
+        "id": "figure-with-image",
+        "caption": "Image 1 - Woman in a purple dress shirt using a laptop",
+        "download": {
+            "title": "Download this image",
+            "itemsList": [
+                {
+                    "text": "High resolution image (JPG format, 1.2MB)",
+                    "url": "/img/small/woman-in-purple-dress-shirt.jpg",
+                    "download": "file"
+                },
+                {
+                    "text": "High resolution image (JPG format, 1.2MB)",
+                    "url": "/img/small/woman-in-purple-dress-shirt.jpg",
+                    "download": "file"
+                }
+            ]
+        },
+        "footnotes": {
+            "title": "Footnotes",
+            "content": "Image is for illustrative purposes only."
+        }
+    })
+%}
+    {# Note that for the sake if the example the image here is rendered directly in an image tag, because onsImage already renders using the figure component #}
+    <img class="ons-image__img" src="/img/small/woman-in-purple-dress-shirt.jpg" alt="Woman in a purple dress shirt using a laptop" />
+{% endcall %}

package/components/figure/example-figure-with-div.njk

@@ -0,0 +1,29 @@
+{% from "components/figure/_macro.njk" import onsFigure %}
+
+{%
+    call onsFigure({
+        "useDivForRootElement": true,
+        "headingLevel": 3,
+        "figureNumber": "Figure 1",
+        "title": "Image 1: Working from home",
+        "subtitle": "A growing proportion of the workforce now works remotely",
+        "id": "figure-with-div",
+        "caption": "Image 1 - Woman in a purple dress shirt using a laptop",
+        "download": {
+            "title": "Download this image",
+            "itemsList": [
+                {
+                    "text": "High resolution image (JPG format, 1.2MB)",
+                    "url": "/img/small/woman-in-purple-dress-shirt.jpg",
+                    "download": "file"
+                }
+            ]
+        },
+        "footnotes": {
+            "title": "Footnotes",
+            "content": "Image is for illustrative purposes only."
+        }
+    })
+%}
+    <img class="ons-image__img" src="/img/small/woman-in-purple-dress-shirt.jpg" alt="Woman in a purple dress shirt using a laptop" />
+{% endcall %}

package/components/figure/example-figure-without-footer.njk

@@ -0,0 +1,12 @@
+{% from "components/figure/_macro.njk" import onsFigure %}
+
+{%
+    call onsFigure({
+        "headingLevel": 3,
+        "figureNumber": "Figure 1",
+        "title": "Image 1: Working from home",
+        "subtitle": "A growing proportion of the workforce now works remotely"
+    })
+%}
+    <img class="ons-image__img" src="/img/small/woman-in-purple-dress-shirt.jpg" alt="Woman in a purple dress shirt using a laptop" />
+{% endcall %}

package/components/figure/example-figure-without-header.njk

@@ -0,0 +1,24 @@
+{% from "components/figure/_macro.njk" import onsFigure %}
+
+{%
+    call onsFigure({
+        "id": "figure-without-header",
+        "caption": "Image 1 - Woman in a purple dress shirt using a laptop",
+        "footnotes": {
+            "title": "Footnotes",
+            "content": "Image is for illustrative purposes only."
+        },
+        "download": {
+            "title": "Download this image",
+            "itemsList": [
+                {
+                    "text": "High resolution image (JPG format, 1.2MB)",
+                    "url": "/img/small/woman-in-purple-dress-shirt.jpg",
+                    "download": "file"
+                }
+            ]
+        }
+    })
+%}
+    <img class="ons-image__img" src="/img/small/woman-in-purple-dress-shirt.jpg" alt="Woman in a purple dress shirt using a laptop" />
+{% endcall %}

package/components/figure/example-figure.njk

@@ -0,0 +1,34 @@
+{% from "components/figure/_macro.njk" import onsFigure %}
+
+{%
+    call onsFigure({
+        "headingLevel": 3,
+        "figureNumber": "Figure 1",
+        "title": "Image 1: Working from home",
+        "subtitle": "A growing proportion of the workforce now works remotely",
+        "id": "figure-with-image",
+        "caption": "Image 1 - Woman in a purple dress shirt using a laptop",
+        "download": {
+            "title": "Download this image",
+            "itemsList": [
+                {
+                    "text": "High resolution image (JPG format, 1.2MB)",
+                    "url": "/img/small/woman-in-purple-dress-shirt.jpg",
+                    "download": "file"
+                },
+                {
+                    "text": "High resolution image (JPG format, 1.2MB)",
+                    "url": "/img/small/woman-in-purple-dress-shirt.jpg",
+                    "download": "file"
+                }
+            ]
+        },
+        "footnotes": {
+            "title": "Footnotes",
+            "content": "Image is for illustrative purposes only."
+        }
+    })
+%}
+    {# Note that for the sake if the example the image here is rendered directly in an image tag, because onsImage already renders using the figure component #}
+    <img class="ons-image__img" src="/img/small/woman-in-purple-dress-shirt.jpg" alt="Woman in a purple dress shirt using a laptop" />
+{% endcall %}

package/components/image/_image.scss

@@ -7,11 +7,4 @@
         display: block;
         max-width: 100%;
     }
-
-    &__caption {
-        @extend .ons-u-fs-s;
-
-        display: block;
-        padding: 0.5rem 0 0;
-    }
 }