@ons/design-system 74.0.0-next.1 → 74.0.0-next.10

package/components/question/example-question-interviewer-note.njk

@@ -23,7 +23,7 @@ layout: ~
     }
 %}
 
-{% block main %}
+{% block mainContent %}
     {%
         call onsQuestion({
             "title": "<mark>Interviewer note:</mark>Who to interview",

package/components/question/example-question-no-fieldset.njk

@@ -23,7 +23,7 @@ layout: ~
     }
 %}
 
-{% block main %}
+{% block mainContent %}
     {%
         call onsQuestion({
             "title": "How many visitors are staying overnight at 3 Severn Road on 13 May 2019?",

package/components/relationships/example-relationships-error.njk

@@ -25,7 +25,7 @@ layout: ~
     }
 %}
 
-{% block main %}
+{% block mainContent %}
 
     {%
         call onsPanel({

package/components/relationships/example-relationships-you.njk

@@ -23,7 +23,7 @@ layout: ~
     }
 %}
 
-{% block main %}
+{% block mainContent %}
     {%
         call onsQuestion({
             "title": "Joe Bloggs is your <strong>…</strong>",

package/components/relationships/example-relationships.njk

@@ -23,7 +23,7 @@ layout: ~
     }
 %}
 
-{% block main %}
+{% block mainContent %}
     {%
         call onsQuestion({
             "title": "Thinking of Joe Bloggs, Amanda Bloggs is their <strong>…</strong>",

package/components/table/_macro.njk

@@ -1,121 +1,148 @@
 {% macro onsTable(params) %}
     {% from "components/button/_macro.njk" import onsButton %}
     {% from "components/icon/_macro.njk" import onsIcon %}
+    {% from "components/figure/_macro.njk" import onsFigure %}
     {% set variants = params.variants if params.variants %}
 
-    <div class="ons-table-scrollable ons-table-scrollable--on">
-        <div
-            class="ons-table-scrollable__content"
-            tabindex="0"
-            role="region"
-            aria-label="{{ params.caption }}. {{ params.ariaLabel | default('Scrollable table') }}"
-        >
-            {# Uses multiple loops to set the rowspan class so that it can work in both nunjucks and jinja2 environments due to the scoping rules of each language #}
-            <table
-                {% if params.id %}id="{{ params.id }}"{% endif %}
-                class="ons-table{{ ' ' + params.tableClasses if params.tableClasses else '' }}{% for row in params.thList %}{% for th in row.ths %}{% if th.rowspan %}{{ ' ' }}ons-table--has-rowspan{% endif %}{% endfor %}{% endfor %}{% for row in params.trs %}{% for td in row.tds %}{% if td.rowspan %}{{ ' ' }}ons-table--has-rowspan{% endif %}{% endfor %}{% endfor %}{% if variants %}{% if variants is not string %}{% for variant in variants %}{{ ' ' }}ons-table--{{ variant }}{% endfor %}{% else %}{{ ' ' }}ons-table--{{ variants }}{% endif %}{% endif %}"
-                {% if params.sortBy and 'sortable' in variants %}
-                    data-aria-sort="{{ params.sortBy }}" data-aria-asc="{{ params.ariaAsc }}" data-aria-desc="{{ params.ariaDesc }}"
-                {% endif %}
+    {%
+        call onsFigure({
+            "useDivForRootElement": true,
+            "id": params.id,
+            "headingLevel": params.headingLevel,
+            "figureNumber": params.figureNumber,
+            "title": params.title,
+            "subtitle": params.subtitle,
+            "footnotes": params.footnotes,
+            "download": params.download,
+            "caption": params.sourceNote
+        })
+    %}
+        {% set tableClasses = "ons-table" %}
+
+        {# If there is no source note, footnotes or downloads after the table, add a bottom margin to the table to match the previous spacing #}
+        {# If there source note, footnotes or downloads after the table, the figure component handles the extra spacing #}
+        {% if not params.sourceNote and not params.footnotes and not params.download %}
+            {% set tableClasses = tableClasses + " ons-table--bottom-space" %}
+        {% endif %}
+
+        {% if params.tableClasses %}
+            {% set tableClasses = tableClasses + " " + params.tableClasses %}
+        {% endif %}
+
+        <div class="ons-table-scrollable ons-table-scrollable--on">
+            <div
+                class="ons-table-scrollable__content"
+                tabindex="0"
+                role="region"
+                {% if params.ariaLabel %}aria-label="{{ params.ariaLabel }}"{% endif %}
             >
-                {% if params.caption %}
-                    <caption class="ons-table__caption{{ ' ons-u-vh' if params.hideCaption }}">
-                        {{ params.caption }}
-                    </caption>
-                {% endif %}
-                <thead class="ons-table__head">
-                    {# Uses thList if multiple-row headers, otherwise wrap single ths array into a default group #}
-                    {% if params.thList %}
-                        {% set thGroups = params.thList %}
-                    {% else %}
-                        {% set thGroups = [ { "ths": params.ths } ] %}
+                {# Uses multiple loops to set the rowspan class so that it can work in both nunjucks and jinja2 environments due to the scoping rules of each language #}
+                <table
+                    class="{{ tableClasses }}{% for row in params.thList %}{% for th in row.ths %}{% if th.rowspan %}{{ ' ' }}ons-table--has-rowspan{% endif %}{% endfor %}{% endfor %}{% for row in params.trs %}{% for td in row.tds %}{% if td.rowspan %}{{ ' ' }}ons-table--has-rowspan{% endif %}{% endfor %}{% endfor %}{% if variants %}{% if variants is not string %}{% for variant in variants %}{{ ' ' }}ons-table--{{ variant }}{% endfor %}{% else %}{{ ' ' }}ons-table--{{ variants }}{% endif %}{% endif %}"
+                    {% if params.sortBy and 'sortable' in variants %}
+                        data-aria-sort="{{ params.sortBy }}" data-aria-asc="{{ params.ariaAsc }}" data-aria-desc="{{ params.ariaDesc }}"
                     {% endif %}
-                    {% for headerCols in thGroups %}
-                        <tr class="ons-table__row">
-                            {% for th in headerCols.ths %}
-                                <th
-                                    scope="col"
-                                    class="ons-table__header  ons-table__header--{{ th.valign | default('top') }}{{ ' ' + th.thClasses if th.thClasses else '' }}{{ ' ons-table__header--numeric' if th.numeric }}"
-                                    {% if th.colspan %}colspan="{{ th.colspan }}"{% endif %}
-                                    {% if th.rowspan %}rowspan="{{ th.rowspan }}"{% endif %}
-                                    {% if 'sortable' in variants %}aria-sort="{{ th.ariaSort | default('none') }}"{% endif %}
-                                    {% if th.widthPercentage %}width="{{ th.widthPercentage }}%"{% endif %}
-                                >
-                                    <span class="ons-table__header-text">{{ th.value | safe }}</span>
-                                    {% if 'sortable' in variants %}
-                                        {{-
-                                            onsIcon({
-                                                "iconType": "sort-sprite",
-                                                "id": th.value | replace(' ', '-'),
-                                                "classes": 'ons-u-d-no'
-                                            })
-                                        -}}
-                                    {% endif %}
-                                </th>
-                            {% endfor %}
-                        </tr>
-                    {% endfor %}
-                </thead>
-                <tbody class="ons-table__body">
-                    {% for tr in params.trs %}
-                        <tr
-                            class="ons-table__row{{ ' ons-table__row--highlight' if tr.highlight }}"
-                            {% if tr.id %}id="{{ tr.id }}"{% endif %}
-                        >
-                            {% for td in tr.tds %}
-                                {% if td.heading == true %}
-                                    {% set openingTag = '<th' %}
-                                    {% set closingTag = '</th>' %}
-                                {% else %}
-                                    {% set openingTag = '<td' %}
-                                    {% set closingTag = '</td>' %}
-                                {% endif %}
-                                {% set isFirstRow = loop.index == 0 and td.rowspan %}
-                                {% set rowSpan = isFirstRow and loop.index0 == rowspanCount %}
-                                {{ openingTag | safe }}
-                                class="ons-table__cell
-                                ons-table__cell--{{ td.valign | default('top') }}{{ ' ' + td.tdClasses if td.tdClasses else '' }}{{ ' ons-table__cell--numeric' if td.numeric }}"
-                                {% if td.id %}id="{{ td.id }}"{% endif %}
-                                {% if td.data %}{{ ' ' }}data-th="{{ td.data }}"{% endif %}
-                                {% if td.colspan %}colspan="{{ td.colspan }}"{% endif %}
-                                {% if td.rowspan %}rowspan="{{ td.rowspan }}"{% endif %}
-                                {% if td.dataSort %}{{ ' ' }}data-sort-value="{{ td.dataSort }}"{% endif %}
-                                {% if td.heading %}scope="row"{% endif %}
-                                >
-                                {% if td.form %}
-                                    <form action="{{ td.form.action }}" method="{{ td.form.method | default('POST') }}">
-                                        {{ onsButton(td.form.button) }}
-                                        {% if td.form.hiddenFormField %}
-                                            {% for hiddenField in td.form.hiddenFormField %}
-                                                <input
-                                                    type="hidden"
-                                                    {% if hiddenField.name %}name="{{ hiddenField.name }}"{% endif %}
-                                                    {% if hiddenField.value %}value="{{ hiddenField.value }}"{% endif %}
-                                                />
-                                            {% endfor %}
+                >
+                    {# Note that the caption is rendered inside the table element to be semantically correct, and we deliberately do not render it with the onsFigure caption option. We also have the option to visually hide it for the table. #}
+                    {% if params.caption %}
+                        <caption class="ons-table__caption{{ ' ons-u-vh' if params.hideCaption }}">
+                            {{ params.caption }}
+                        </caption>
+                    {% endif %}
+                    <thead class="ons-table__head">
+                        {# Uses thList if multiple-row headers, otherwise wrap single ths array into a default group #}
+                        {% if params.thList %}
+                            {% set thGroups = params.thList %}
+                        {% else %}
+                            {% set thGroups = [ { "ths": params.ths } ] %}
+                        {% endif %}
+                        {% for headerCols in thGroups %}
+                            <tr class="ons-table__row">
+                                {% for th in headerCols.ths %}
+                                    <th
+                                        scope="col"
+                                        class="ons-table__header  ons-table__header--{{ th.valign | default('top') }}{{ ' ' + th.thClasses if th.thClasses else '' }}{{ ' ons-table__header--numeric' if th.numeric }}"
+                                        {% if th.colspan %}colspan="{{ th.colspan }}"{% endif %}
+                                        {% if th.rowspan %}rowspan="{{ th.rowspan }}"{% endif %}
+                                        {% if 'sortable' in variants %}aria-sort="{{ th.ariaSort | default('none') }}"{% endif %}
+                                        {% if th.widthPercentage %}width="{{ th.widthPercentage }}%"{% endif %}
+                                    >
+                                        <span class="ons-table__header-text">{{ th.value | safe }}</span>
+                                        {% if 'sortable' in variants %}
+                                            {{-
+                                                onsIcon({
+                                                    "iconType": "sort-sprite",
+                                                    "id": th.value | replace(' ', '-'),
+                                                    "classes": 'ons-u-d-no'
+                                                })
+                                            -}}
                                         {% endif %}
-                                    </form>
-                                {% endif %}
-                                {% if td.value %}
-                                    {{ td.value | safe }}
-                                {% endif %}
-                                {{ closingTag | safe }}
-                            {% endfor %}
-                        </tr>
-                    {% endfor %}
-                </tbody>
-                {% if params.tfoot %}
-                    <tfoot class="ons-table__foot">
-                        <tr class="ons-table__row">
-                            {% for tfootCell in params.tfoot %}
-                                <td class="ons-table__cell ons-table__cell--{{ tfootCell.valign | default('top') }} ons-u-fs-s">
-                                    {{ tfootCell.value }}
-                                </td>
-                            {% endfor %}
-                        </tr>
-                    </tfoot>
-                {% endif %}
-            </table>
+                                    </th>
+                                {% endfor %}
+                            </tr>
+                        {% endfor %}
+                    </thead>
+                    <tbody class="ons-table__body">
+                        {% for tr in params.trs %}
+                            <tr
+                                class="ons-table__row{{ ' ons-table__row--highlight' if tr.highlight }}"
+                                {% if tr.id %}id="{{ tr.id }}"{% endif %}
+                            >
+                                {% for td in tr.tds %}
+                                    {% if td.heading == true %}
+                                        {% set openingTag = '<th' %}
+                                        {% set closingTag = '</th>' %}
+                                    {% else %}
+                                        {% set openingTag = '<td' %}
+                                        {% set closingTag = '</td>' %}
+                                    {% endif %}
+                                    {% set isFirstRow = loop.index == 0 and td.rowspan %}
+                                    {% set rowSpan = isFirstRow and loop.index0 == rowspanCount %}
+                                    {{ openingTag | safe }}
+                                    class="ons-table__cell
+                                    ons-table__cell--{{ td.valign | default('top') }}{{ ' ' + td.tdClasses if td.tdClasses else '' }}{{ ' ons-table__cell--numeric' if td.numeric }}"
+                                    {% if td.id %}id="{{ td.id }}"{% endif %}
+                                    {% if td.data %}{{ ' ' }}data-th="{{ td.data }}"{% endif %}
+                                    {% if td.colspan %}colspan="{{ td.colspan }}"{% endif %}
+                                    {% if td.rowspan %}rowspan="{{ td.rowspan }}"{% endif %}
+                                    {% if td.dataSort %}{{ ' ' }}data-sort-value="{{ td.dataSort }}"{% endif %}
+                                    {% if td.heading %}scope="row"{% endif %}
+                                    >
+                                    {% if td.form %}
+                                        <form action="{{ td.form.action }}" method="{{ td.form.method | default('POST') }}">
+                                            {{ onsButton(td.form.button) }}
+                                            {% if td.form.hiddenFormField %}
+                                                {% for hiddenField in td.form.hiddenFormField %}
+                                                    <input
+                                                        type="hidden"
+                                                        {% if hiddenField.name %}name="{{ hiddenField.name }}"{% endif %}
+                                                        {% if hiddenField.value %}value="{{ hiddenField.value }}"{% endif %}
+                                                    />
+                                                {% endfor %}
+                                            {% endif %}
+                                        </form>
+                                    {% endif %}
+                                    {% if td.value %}
+                                        {{ td.value | safe }}
+                                    {% endif %}
+                                    {{ closingTag | safe }}
+                                {% endfor %}
+                            </tr>
+                        {% endfor %}
+                    </tbody>
+                    {% if params.tfoot %}
+                        <tfoot class="ons-table__foot">
+                            <tr class="ons-table__row">
+                                {% for tfootCell in params.tfoot %}
+                                    <td class="ons-table__cell ons-table__cell--{{ tfootCell.valign | default('top') }} ons-u-fs-s">
+                                        {{ tfootCell.value }}
+                                    </td>
+                                {% endfor %}
+                            </tr>
+                        </tfoot>
+                    {% endif %}
+                </table>
+            </div>
         </div>
-    </div>
+    {% endcall %}
 {% endmacro %}

package/components/table/_macro.spec.js

@@ -7,6 +7,7 @@ import { mapAll } from '../../tests/helpers/cheerio';
 import { renderComponent, templateFaker } from '../../tests/helpers/rendering';
 
 const EXAMPLE_TABLE_MINIMAL = {
+    ariaLabel: 'Example table',
     ths: [],
     trs: [],
 };
@@ -32,7 +33,7 @@ describe('macro: table', () => {
         expect(results).toHaveNoViolations();
     });
 
-    it('has the provided `id` attribute', () => {
+    it('has the provided `id` on the wrapping element', () => {
         const $ = cheerio.load(
             renderComponent('table', {
                 ...EXAMPLE_TABLE,
@@ -40,7 +41,7 @@ describe('macro: table', () => {
             }),
         );
 
-        expect($('.ons-table').attr('id')).toBe('example-table');
+        expect($('.ons-figure').attr('id')).toBe('example-table');
     });
 
     it('has additionally provided style classes', () => {
@@ -67,27 +68,15 @@ describe('macro: table', () => {
         expect($('.ons-table-scrollable__content').length).toBe(1);
     });
 
-    it('renders an appropriate `aria-label` attribute on the "content" container element', () => {
+    it('renders the `aria-label` attribute on the "content" container element', () => {
         const $ = cheerio.load(
             renderComponent('table', {
                 ...EXAMPLE_TABLE,
-                caption: 'Example table caption',
-            }),
-        );
-
-        expect($('.ons-table-scrollable__content').attr('aria-label')).toBe('Example table caption. Scrollable table');
-    });
-
-    it('renders a custom `aria-label` attribute on the "content" container element', () => {
-        const $ = cheerio.load(
-            renderComponent('table', {
-                ...EXAMPLE_TABLE,
-                caption: 'Example table caption',
                 ariaLabel: 'Special table',
             }),
         );
 
-        expect($('.ons-table-scrollable__content').attr('aria-label')).toBe('Example table caption. Special table');
+        expect($('.ons-table-scrollable__content').attr('aria-label')).toBe('Special table');
     });
 
     describe('Vertical Alignment', () => {
@@ -680,4 +669,174 @@ describe('macro: table', () => {
             expect($('.ons-table__caption').hasClass('ons-u-vh')).toBe(true);
         });
     });
+
+    describe('bottom spacing', () => {
+        it('adds "ons-table--bottom-space" class when there are no footnotes, download or sourceNote', () => {
+            const $ = cheerio.load(renderComponent('table', EXAMPLE_TABLE));
+
+            expect($('.ons-table').hasClass('ons-table--bottom-space')).toBe(true);
+        });
+
+        it('does not add "ons-table--bottom-space" class when `sourceNote` is provided', () => {
+            const $ = cheerio.load(
+                renderComponent('table', {
+                    ...EXAMPLE_TABLE,
+                    sourceNote: 'Source: Office for National Statistics',
+                }),
+            );
+
+            expect($('.ons-table').hasClass('ons-table--bottom-space')).toBe(false);
+        });
+
+        it('does not add "ons-table--bottom-space" class when `footnotes` is provided', () => {
+            const $ = cheerio.load(
+                renderComponent('table', {
+                    ...EXAMPLE_TABLE,
+                    footnotes: {
+                        title: 'Footnotes',
+                        content: 'Data is seasonally adjusted.',
+                    },
+                }),
+            );
+
+            expect($('.ons-table').hasClass('ons-table--bottom-space')).toBe(false);
+        });
+
+        it('does not add "ons-table--bottom-space" class when `download` is provided', () => {
+            const $ = cheerio.load(
+                renderComponent('table', {
+                    ...EXAMPLE_TABLE,
+                    download: {
+                        title: 'Download this table',
+                        itemsList: [
+                            {
+                                text: 'Table data (CSV, 2KB)',
+                                url: '/data/table.csv',
+                                download: 'file',
+                            },
+                        ],
+                    },
+                }),
+            );
+
+            expect($('.ons-table').hasClass('ons-table--bottom-space')).toBe(false);
+        });
+    });
+
+    describe('figure wrapper', () => {
+        it('renders with a <div> root element instead of <figure>', () => {
+            const $ = cheerio.load(renderComponent('table', EXAMPLE_TABLE));
+
+            expect($('.ons-figure')[0].tagName).toBe('div');
+        });
+
+        it('passes `title` to the figure component', () => {
+            const faker = templateFaker();
+            const figureSpy = faker.spy('figure');
+
+            faker.renderComponent('table', {
+                ...EXAMPLE_TABLE,
+                title: 'Population by region',
+            });
+
+            expect(figureSpy.occurrences[0].title).toBe('Population by region');
+        });
+
+        it('passes `subtitle` to the figure component', () => {
+            const faker = templateFaker();
+            const figureSpy = faker.spy('figure');
+
+            faker.renderComponent('table', {
+                ...EXAMPLE_TABLE,
+                subtitle: 'Mid-year estimates, 2023',
+            });
+
+            expect(figureSpy.occurrences[0].subtitle).toBe('Mid-year estimates, 2023');
+        });
+
+        it('passes `headingLevel` to the figure component', () => {
+            const faker = templateFaker();
+            const figureSpy = faker.spy('figure');
+
+            faker.renderComponent('table', {
+                ...EXAMPLE_TABLE,
+                headingLevel: 3,
+            });
+
+            expect(figureSpy.occurrences[0].headingLevel).toBe(3);
+        });
+
+        it('passes `figureNumber` to the figure component', () => {
+            const faker = templateFaker();
+            const figureSpy = faker.spy('figure');
+
+            faker.renderComponent('table', {
+                ...EXAMPLE_TABLE,
+                figureNumber: 'Table 1',
+            });
+
+            expect(figureSpy.occurrences[0].figureNumber).toBe('Table 1');
+        });
+
+        it('passes `footnotes` to the figure component', () => {
+            const faker = templateFaker();
+            const figureSpy = faker.spy('figure');
+
+            const footnotes = {
+                title: 'Footnotes',
+                content: 'Data is seasonally adjusted.',
+            };
+
+            faker.renderComponent('table', {
+                ...EXAMPLE_TABLE,
+                footnotes,
+            });
+
+            expect(figureSpy.occurrences[0].footnotes).toEqual(footnotes);
+        });
+
+        it('passes `download` to the figure component', () => {
+            const faker = templateFaker();
+            const figureSpy = faker.spy('figure');
+
+            const download = {
+                title: 'Download this table',
+                itemsList: [
+                    {
+                        text: 'Table data (CSV, 2KB)',
+                        url: '/data/table.csv',
+                        download: 'file',
+                    },
+                ],
+            };
+
+            faker.renderComponent('table', {
+                ...EXAMPLE_TABLE,
+                download,
+            });
+
+            expect(figureSpy.occurrences[0].download).toEqual(download);
+        });
+
+        it('passes `sourceNote` to the figure component', () => {
+            const faker = templateFaker();
+            const figureSpy = faker.spy('figure');
+
+            faker.renderComponent('table', {
+                ...EXAMPLE_TABLE,
+                sourceNote: 'Source: Office for National Statistics',
+            });
+
+            expect(figureSpy.occurrences[0].caption).toBe('Source: Office for National Statistics');
+        });
+
+        it('sets `useDivForRootElement` on the figure component', () => {
+            const faker = templateFaker();
+            const figureSpy = faker.spy('figure');
+
+            faker.renderComponent('table', EXAMPLE_TABLE);
+
+            expect(figureSpy.occurrences[0].useDivForRootElement).toBe(true);
+        });
+    });
 });

package/components/table/_table.scss

@@ -1,7 +1,6 @@
 .ons-table {
     border-collapse: collapse;
     border-spacing: 0;
-    margin-bottom: 1rem;
     width: 100%;
 
     &__head {
@@ -241,4 +240,10 @@
             }
         }
     }
+
+    // Used when there is no source note, footnotes or downloads after the table, to match the previous bottom spacing
+    // If there source note, footnotes or downloads after the table, the figure component handles the extra spacing
+    &--bottom-space {
+        margin-bottom: 1rem;
+    }
 }

package/components/table/example-table-basic-no-caption.njk

@@ -0,0 +1,46 @@
+{% from "components/table/_macro.njk" import onsTable %}
+{{
+    onsTable({
+        "ariaLabel": "Basic table example",
+        "id": "basic-table",
+        "ths": [
+            {
+                "value": "Column A"
+            },
+            {
+                "value": "Column B"
+            },
+            {
+                "value": "Column C"
+            }
+        ],
+        "trs": [
+            {
+                "tds": [
+                    {
+                        "value": "Cell A1"
+                    },
+                    {
+                        "value": "Cell B1"
+                    },
+                    {
+                        "value": "Cell C1"
+                    }
+                ]
+            },
+            {
+                "tds": [
+                    {
+                        "value": "Cell A2"
+                    },
+                    {
+                        "value": "Cell B2"
+                    },
+                    {
+                        "value": "Cell C2"
+                    }
+                ]
+            }
+        ]
+    })
+}}

package/components/table/example-table-basic-visually-hidden-caption.njk

@@ -0,0 +1,47 @@
+{% from "components/table/_macro.njk" import onsTable %}
+{{
+    onsTable({
+        "caption": "A basic table with a visually hidden caption",
+        "hideCaption": true,
+        "id": "basic-table",
+        "ths": [
+            {
+                "value": "Column A"
+            },
+            {
+                "value": "Column B"
+            },
+            {
+                "value": "Column C"
+            }
+        ],
+        "trs": [
+            {
+                "tds": [
+                    {
+                        "value": "Cell A1"
+                    },
+                    {
+                        "value": "Cell B1"
+                    },
+                    {
+                        "value": "Cell C1"
+                    }
+                ]
+            },
+            {
+                "tds": [
+                    {
+                        "value": "Cell A2"
+                    },
+                    {
+                        "value": "Cell B2"
+                    },
+                    {
+                        "value": "Cell C2"
+                    }
+                ]
+            }
+        ]
+    })
+}}