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

package/components/document-list/_macro.spec.js

@@ -277,6 +277,61 @@ describe('FOR: Macro: Document list', () => {
                 expect(fileInfo).toBe('PDF, 499KB, 1 page');
             });
         });
+
+        describe('WHEN: file configuration is missing optional fileSize and filePages', () => {
+            const $ = cheerio.load(
+                renderComponent('document-list', {
+                    documents: [
+                        {
+                            ...EXAMPLE_DOCUMENT_LIST_BASIC,
+                            metadata: {
+                                file: {
+                                    fileType: 'PDF',
+                                },
+                            },
+                        },
+                    ],
+                }),
+            );
+
+            test('THEN: has visually hidden file information without stray separators', () => {
+                const hiddenText = $('.ons-document-list__item-title a .ons-u-vh').text().trim();
+                expect(hiddenText).toBe(', PDF document download');
+            });
+
+            test('THEN: has file information without stray separators', () => {
+                const fileInfo = $('.ons-document-list__item-attribute').text().trim();
+                expect(fileInfo).toBe('PDF');
+            });
+        });
+
+        describe('WHEN: file configuration is missing optional filePages', () => {
+            const $ = cheerio.load(
+                renderComponent('document-list', {
+                    documents: [
+                        {
+                            ...EXAMPLE_DOCUMENT_LIST_BASIC,
+                            metadata: {
+                                file: {
+                                    fileType: 'PDF',
+                                    fileSize: '499KB',
+                                },
+                            },
+                        },
+                    ],
+                }),
+            );
+
+            test('THEN: has visually hidden file information without stray separators', () => {
+                const hiddenText = $('.ons-document-list__item-title a .ons-u-vh').text().trim();
+                expect(hiddenText).toBe(', PDF document download, 499KB');
+            });
+
+            test('THEN: has file information without stray separators', () => {
+                const fileInfo = $('.ons-document-list__item-attribute').text().trim();
+                expect(fileInfo).toBe('PDF, 499KB');
+            });
+        });
     });
 
     describe('GIVEN: Params: object', () => {

package/components/featured-article/_macro.njk

@@ -1,6 +1,3 @@
-{% from "components/chart/_macro.njk" import onsChart %}
-{% from "components/image/_macro.njk" import onsImage %}
-
 {% macro onsFeaturedArticle(params) %}
     {% set headingLevel = params.headingLevel | default(2) %}
     {% set openingArticleTitleTag = "<h" ~ headingLevel %}
@@ -32,41 +29,10 @@
             </ul>
         {% endif %}
 
+        {# The media (a nested figure containing a chart or image) is provided via the caller
+           block, so the article does not need to know how the content is rendered. #}
         <div class="ons-featured__media">
-            {% if params.chart %}
-                {{
-                    onsChart({
-                        "chartType": params.chart.chartType,
-                        "description": params.chart.description,
-                        "theme": params.chart.theme,
-                        "title": params.chart.title,
-                        "id": params.chart.id,
-                        "headingLevel": headingLevel + 1,
-                        "legend": params.chart.legend,
-                        "xAxis": params.chart.xAxis,
-                        "yAxis": params.chart.yAxis,
-                        "series": params.chart.series,
-                        "annotations": params.chart.annotations,
-                        "rangeAnnotations": params.chart.rangeAnnotations,
-                        "referenceLineAnnotations": params.chart.referenceLineAnnotations,
-                        "estimateLineLabel": params.chart.estimateLineLabel,
-                        "uncertaintyRangeLabel": params.chart.uncertaintyRangeLabel,
-                        "isChartInverted": params.chart.isChartInverted,
-                        "useStackedLayout": params.chart.useStackedLayout,
-                        "percentageHeightDesktop": params.chart.percentageHeightDesktop,
-                        "percentageHeightMobile": params.chart.percentageHeightMobile
-                    })
-                }}
-            {% elif params.image %}
-                <div class="ons-featured__image">
-                    {{
-                        onsImage({
-                            "src": params.image.src,
-                            "alt": params.image.alt
-                        })
-                    }}
-                </div>
-            {% endif %}
+            {{ caller() if caller }}
         </div>
 
         {% if params.description %}

package/components/featured-article/example-featured-article-with-chart.njk

@@ -1,6 +1,8 @@
 {% from "components/featured-article/_macro.njk" import onsFeaturedArticle %}
-{{
-    onsFeaturedArticle({
+{% from "components/chart/_macro.njk" import onsChart %}
+
+{%
+    call onsFeaturedArticle({
         "title": {
             "text": 'Retail sales, Great Britain: July 2024',
             "url": '#0'
@@ -15,14 +17,22 @@
             }
         },
         "headingLevel": 3,
-        "chart": {
+        "description": "<ul>
+                <li>Retail sales volumes increased by 0.4% in July 2024, following a 0.2% increase in June 2024.</li>
+                <li>Retail sales values increased by 0.5% in July 2024, following a 0.3% increase in June 2024.</li>
+                <li>The annual rate of inflation for the Consumer Prices Index including owner occupiers’ housing costs (CPIH) was 2.8% in July 2024, up from 2.6% in June 2024.</li>
+            </ul>"
+    })
+%}
+
+    {{
+        onsChart({
             "chartType": "line",
-            "description": "Line chart showing the annual rate of inflation for the Consumer Prices Index including owner occupiers’ housing costs (CPIH) and its components.",
             "theme": "primary",
+            "headingLevel": 4,
             "title": "Sales volumes and values saw moderate growth in July 2024",
-            "subtitle": "Figure 6: Upward contribution from housing and household services (including energy) saw the annual CPIH inflation rate rise",
+            "audioDescription": "Line chart showing the annual rate of inflation for the Consumer Prices Index including owner occupiers’ housing costs (CPIH) and its components.",
             "id": "id",
-            "headingLevel": 4,
             "legend": true,
             "xAxis": {
                 "title": "Year",
@@ -213,11 +223,6 @@
             ],
             "percentageHeightDesktop": 35,
             "percentageHeightMobile": 90
-        },
-        "description": "<ul>
-                <li>Retail sales volumes increased by 0.4% in July 2024, following a 0.2% increase in June 2024.</li>
-                <li>Retail sales values increased by 0.5% in July 2024, following a 0.3% increase in June 2024.</li>
-                <li>The annual rate of inflation for the Consumer Prices Index including owner occupiers’ housing costs (CPIH) was 2.8% in July 2024, up from 2.6% in June 2024.</li>
-            </ul>"
-    })
-}}
+        })
+    }}
+{% endcall %}

package/components/featured-article/example-featured-article-with-image.njk

@@ -1,6 +1,8 @@
 {% from "components/featured-article/_macro.njk" import onsFeaturedArticle %}
-{{
-    onsFeaturedArticle({
+{% from "components/image/_macro.njk" import onsImage %}
+
+{%
+    call onsFeaturedArticle({
         "title": {
             "text": 'Retail sales, Great Britain: July 2024',
             "url": '#0'
@@ -15,10 +17,13 @@
             }
         },
         "headingLevel": 3,
-        "image": {
-            "src": '/img/small/census-monuments-lights-featured.jpg',
-            "alt": 'census monuments lights featured'
-        },
         "description": "Retail sales volumes and values saw moderate growth in July 2024, with the annual rate of inflation for the Consumer Prices Index including owner occupiers’ housing costs (CPIH) rising to 2.8%."
     })
-}}
+%}
+    {{
+        onsImage({
+            "src": '/img/small/census-monuments-lights-featured.jpg',
+            "alt": 'census monuments lights featured'
+        })
+    }}
+{% endcall %}

package/components/featured-article/featured-article.scss

@@ -6,7 +6,7 @@
     outline: 2px solid transparent;
     outline-offset: -2px;
 
-    &__image {
+    &__media {
         .ons-image__img {
             width: 100%;
             max-width: $grid-max-width;

package/components/featured-article/macro.spec.js

@@ -3,12 +3,12 @@
 import * as cheerio from 'cheerio';
 import axe from '../../tests/helpers/axe';
 import { renderComponent } from '../../tests/helpers/rendering';
-import { EXAMPLE_FEATURED_ARTICLE_WITH_CHART, EXAMPLE_FEATURED_ARTICLE_WITH_IMAGE } from './_test-examples';
+import { EXAMPLE_FEATURED_ARTICLE_PARAMS, EXAMPLE_CHART_CALLER_CONTENT, EXAMPLE_IMAGE_CALLER_CONTENT } from './_test-examples';
 
 describe('Macro: Featured Article', () => {
     describe('GIVEN: Params: required', () => {
-        describe('WHEN: chart is provided and image is not', () => {
-            const $ = cheerio.load(renderComponent('featured-article', EXAMPLE_FEATURED_ARTICLE_WITH_CHART));
+        describe('WHEN: chart content is provided via caller', () => {
+            const $ = cheerio.load(renderComponent('featured-article', EXAMPLE_FEATURED_ARTICLE_PARAMS, EXAMPLE_CHART_CALLER_CONTENT));
 
             test('THEN: it passes accessibility checks', async () => {
                 const results = await axe($.html());
@@ -23,8 +23,8 @@ describe('Macro: Featured Article', () => {
                 expect($('.ons-featured__title a').attr('href')).toBe('/economy/economic-trends-2024');
             });
 
-            test('THEN: it renders the onsChart component', () => {
-                expect($('[data-highcharts-base-chart]').length).toBe(1);
+            test('THEN: it renders the caller content in the media area', () => {
+                expect($('.ons-featured__media [data-highcharts-base-chart]').length).toBe(1);
             });
 
             test('THEN: the chart has the correct id', () => {
@@ -36,8 +36,8 @@ describe('Macro: Featured Article', () => {
             });
         });
 
-        describe('WHEN: image is provided and chart is not', () => {
-            const $ = cheerio.load(renderComponent('featured-article', EXAMPLE_FEATURED_ARTICLE_WITH_IMAGE));
+        describe('WHEN: image content is provided via caller', () => {
+            const $ = cheerio.load(renderComponent('featured-article', EXAMPLE_FEATURED_ARTICLE_PARAMS, EXAMPLE_IMAGE_CALLER_CONTENT));
 
             test('THEN: it passes accessibility checks', async () => {
                 const results = await axe($.html());
@@ -45,78 +45,50 @@ describe('Macro: Featured Article', () => {
             });
 
             test('THEN: it displays the correct title text', () => {
-                expect($('.ons-featured__title').text().trim()).toBe('Population Insights');
+                expect($('.ons-featured__title').text().trim()).toBe('Economic Trends 2024');
             });
 
             test('THEN: the title has the correct url link', () => {
-                expect($('.ons-featured__title a').attr('href')).toBe('/people/population/insights');
+                expect($('.ons-featured__title a').attr('href')).toBe('/economy/economic-trends-2024');
             });
 
             test('THEN: it renders image with correct src attribute', () => {
-                expect($('.ons-image__img').attr('src')).toBe('example.png');
+                expect($('.ons-featured__media .ons-image__img').attr('src')).toBe('example.png');
             });
 
             test('THEN: it renders image with correct alt text', () => {
-                expect($('.ons-image__img').attr('alt')).toBe('Example alt text');
+                expect($('.ons-featured__media .ons-image__img').attr('alt')).toBe('Example alt text');
             });
         });
 
-        describe('WHEN: both chart and image is provided', () => {
-            const $ = cheerio.load(renderComponent('featured-article', EXAMPLE_FEATURED_ARTICLE_WITH_CHART));
+        describe('WHEN: no caller content is provided', () => {
+            const $ = cheerio.load(renderComponent('featured-article', EXAMPLE_FEATURED_ARTICLE_PARAMS));
 
-            test('THEN: it renders the onsChart component', () => {
-                expect($('[data-highcharts-base-chart]').length).toBe(1);
-            });
-            test('THEN: it does not render the onsImage component', () => {
-                expect($('.ons-image__img').length).toBe(0);
+            test('THEN: the media area is empty', () => {
+                expect($('.ons-featured__media').html().trim()).toBe('');
             });
         });
     });
 
     describe('GIVEN: Param: metadata', () => {
-        describe('WHEN: chart is provided', () => {
-            const $ = cheerio.load(
-                renderComponent('featured-article', {
-                    ...EXAMPLE_FEATURED_ARTICLE_WITH_CHART,
-                    metadata: {
-                        date: {
-                            prefix: 'Released',
-                            showPrefix: true,
-                            iso: '2024-05-01',
-                            short: '1 May 2024',
-                        },
-                        text: 'Bulletin',
-                    },
-                }),
-            );
-
-            test('THEN: it renders ISO date value correctly', () => {
-                expect($('time').attr('datetime')).toBe('2024-05-01');
-            });
-
-            test('THEN: it renders short date label correctly', () => {
-                expect($('time').text()).toBe('1 May 2024');
-            });
-
-            test('THEN: it displays metadata text', () => {
-                expect($('.ons-featured__item-attribute span').text()).toContain('Bulletin');
-            });
-        });
-
-        describe('WHEN: image is provided', () => {
+        describe('WHEN: metadata is provided', () => {
             const $ = cheerio.load(
-                renderComponent('featured-article', {
-                    ...EXAMPLE_FEATURED_ARTICLE_WITH_IMAGE,
-                    metadata: {
-                        date: {
-                            prefix: 'Released',
-                            showPrefix: true,
-                            iso: '2024-05-01',
-                            short: '1 May 2024',
+                renderComponent(
+                    'featured-article',
+                    {
+                        ...EXAMPLE_FEATURED_ARTICLE_PARAMS,
+                        metadata: {
+                            date: {
+                                prefix: 'Released',
+                                showPrefix: true,
+                                iso: '2024-05-01',
+                                short: '1 May 2024',
+                            },
+                            text: 'Bulletin',
                         },
-                        text: 'Bulletin',
                     },
-                }),
+                    EXAMPLE_CHART_CALLER_CONTENT,
+                ),
             );
 
             test('THEN: it renders ISO date value correctly', () => {
@@ -133,10 +105,7 @@ describe('Macro: Featured Article', () => {
         });
 
         describe('WHEN: metadata is not provided', () => {
-            const articleWithoutMetadata = {
-                ...EXAMPLE_FEATURED_ARTICLE_WITH_CHART,
-            };
-            const $ = cheerio.load(renderComponent('featured-article', articleWithoutMetadata));
+            const $ = cheerio.load(renderComponent('featured-article', EXAMPLE_FEATURED_ARTICLE_PARAMS, EXAMPLE_CHART_CALLER_CONTENT));
 
             test('THEN: metadata section is not rendered', () => {
                 expect($('.ons-featured__item-metadata').length).toBe(0);
@@ -148,7 +117,11 @@ describe('Macro: Featured Article', () => {
         describe('WHEN: description is provided', () => {
             test('THEN: has expected description', () => {
                 const $ = cheerio.load(
-                    renderComponent('featured-article', { ...EXAMPLE_FEATURED_ARTICLE_WITH_CHART, description: 'Some description' }),
+                    renderComponent(
+                        'featured-article',
+                        { ...EXAMPLE_FEATURED_ARTICLE_PARAMS, description: 'Some description' },
+                        EXAMPLE_CHART_CALLER_CONTENT,
+                    ),
                 );
                 const title = $('.ons-featured__description').html().trim();
                 expect(title).toBe('Some description');
@@ -159,10 +132,14 @@ describe('Macro: Featured Article', () => {
     describe('GIVEN: Param: headingLevel', () => {
         describe('WHEN: heading level is provided', () => {
             const $ = cheerio.load(
-                renderComponent('featured-article', {
-                    ...EXAMPLE_FEATURED_ARTICLE_WITH_CHART,
-                    headingLevel: 3,
-                }),
+                renderComponent(
+                    'featured-article',
+                    {
+                        ...EXAMPLE_FEATURED_ARTICLE_PARAMS,
+                        headingLevel: 3,
+                    },
+                    EXAMPLE_CHART_CALLER_CONTENT,
+                ),
             );
 
             test('THEN: title is rendered using correct heading tag', () => {

package/components/figure/_figure.scss

@@ -0,0 +1,31 @@
+.ons-figure {
+    margin: 0;
+
+    &__number {
+        color: var(--ons-color-text-light);
+        font-size: 1.125rem;
+        font-weight: $font-weight-bold;
+        line-height: 1.3;
+    }
+
+    &__title {
+        font-size: 1.25rem;
+        line-height: 1.6;
+        font-weight: $font-weight-bold;
+        margin-bottom: 0.5rem;
+    }
+
+    &__subtitle {
+        font-size: 1.125rem;
+        line-height: 1.6;
+        font-weight: $font-weight-regular;
+    }
+
+    &__caption {
+        color: var(--ons-color-text-light);
+        font-size: 0.875rem;
+        line-height: 1.7;
+        display: block;
+        margin-bottom: 1.5rem;
+    }
+}

package/components/figure/_macro.njk

@@ -0,0 +1,98 @@
+{% from "components/list/_macro.njk" import onsList %}
+{% from "components/details/_macro.njk" import onsDetails %}
+
+{% macro onsFigure(params) %}
+    {# The heading levels are configurable so the figure slots into the correct place in the
+       document outline, but the title and subtitle always render at the same visual size
+       via the utility font-size classes below. #}
+    {% set headingLevel = params.headingLevel | default(2, true) %}
+    {% set openingTitleTag = '<h' ~ headingLevel ~ ' class="ons-figure__title">' %}
+    {% set closingTitleTag = "</h" ~ headingLevel ~ ">" %}
+    {% set openingSubtitleTag = '<h' ~ (headingLevel + 1) ~ ' class="ons-figure__subtitle">' %}
+    {% set closingSubtitleTag = "</h" ~ (headingLevel + 1) ~ ">" %}
+    {% if params.title and params.subtitle %}
+        {% set childHeadingLevel = headingLevel + 2 %}
+    {% elif params.title %}
+        {% set childHeadingLevel = headingLevel + 1 %}
+    {% else %}
+        {% set childHeadingLevel = headingLevel %}
+    {% endif %}
+    {% set audioDescriptionId = "figure-audio-description-" ~ params.id %}
+    {% set rootElement = 'div' if params.useDivForRootElement else 'figure' %}
+    {% set openingRootTag = '<' ~ rootElement %}
+    {% if params.audioDescription %}
+        {% set openingRootTag = openingRootTag ~ ' aria-describedby="' ~ audioDescriptionId ~ '"' %}
+    {% endif %}
+    {% set openingRootTag = openingRootTag ~ ' class="ons-figure' ~ (' ' ~ params.classes if params.classes else '') ~ '"' %}
+    {% if params.id %}
+        {% set openingRootTag = openingRootTag ~ ' id="' ~ params.id ~ '"' %}
+    {% endif %}
+    {% set openingRootTag = openingRootTag ~ '>' %}
+    {% set closingRootTag = '</' ~ rootElement ~ '>' %}
+    {% set contentHasTopMargin = true if params.figureNumber or params.title or params.subtitle else false %}
+    {% set contentHasBottomMargin = true if params.caption or params.footnotes or params.download else false %}
+
+    {{ openingRootTag | safe }}
+    {% if params.figureNumber %}
+        <span class="ons-figure__number">{{ params.figureNumber }}</span>
+    {% endif %}
+    {% if params.title %}
+        {{ openingTitleTag | safe }}{{ params.title }}{{ closingTitleTag | safe }}
+    {% endif %}
+    {% if params.subtitle and params.title %}
+        {{ openingSubtitleTag | safe }}{{ params.subtitle }}{{ closingSubtitleTag | safe }}
+    {% endif %}
+
+    {# A visually-hidden description of the nested content for screen reader users. #}
+    {% if params.audioDescription %}
+        <p class="ons-u-vh" id="{{ audioDescriptionId }}">{{ params.audioDescription }}</p>
+    {% endif %}
+
+    <div
+        class="
+                ons-figure__content
+                {% if contentHasTopMargin %}ons-u-mt-l{% endif %}
+                {% if contentHasBottomMargin %}ons-u-mb-l{% endif %}
+            "
+    >
+        {# The nested content appears here #}
+        {{ caller() if caller else '' }}
+    </div>
+
+    {% if params.caption %}
+        {% if rootElement == 'figure' %}
+            <figcaption class="ons-figure__caption">{{ params.caption }}</figcaption>
+        {% else %}
+            <span class="ons-figure__caption">{{ params.caption }}</span>
+        {% endif %}
+    {% endif %}
+    {{ closingRootTag | safe }}
+
+    {% if params.footnotes %}
+        {% set footnotesId = ["figure-footnotes--", params.id] | join %}
+        {{
+            onsDetails({
+                "id": footnotesId,
+                "title": params.footnotes.title,
+                "content": params.footnotes.content,
+                "headingLevel": childHeadingLevel,
+                "classes": "ons-u-mb-l"
+            })
+        }}
+    {% endif %}
+
+    {% if params.download.title and params.download.itemsList | length > 0 %}
+        {% set downloadsId = ["figure-downloads--", params.id] | join %}
+        {{
+            onsDetails({
+                "id": downloadsId,
+                "title": params.download.title,
+                "content": onsList({
+                    "itemsList": params.download.itemsList,
+                    "variants": "bare"
+                }),
+                "headingLevel": childHeadingLevel
+            })
+        }}
+    {% endif %}
+{% endmacro %}