@ons/design-system 62.0.2 → 62.1.0

package/README.md

@@ -43,65 +43,6 @@ yarn start
 
 Once the server has started, navigate to <http://localhost:3030>
 
-## Mixed Markdown/Nunjucks syntax in .njk pages
-
-The design system documentation is authored with files that contain a mix of Markdown and Nunjucks syntax. These files begin with frontmatter and then contain Markdown syntax; for example:
-
-```markdown
----
-title: Foo
----
-
-## Some section
-
-A simple paragraph of _markdown_.
-```
-
-Simple Nunjucks placeholders/variables can be added into these files without any special syntax; for example:
-
-```markdown
-A paragraph of _markdown_ with some template value {{ foo.bar }}.
-
-{{
-    patternlibExample({"path": "components/foo/examples/foo/index.njk"})
-}}
-```
-
-For the most part no special syntax is needed when mixing Nunjucks templating into the markdown syntax. If syntax contains nested character sequence `}}` then it must be wrapped within `+++` fences. The `{% ... %}` syntax must also be wrapped within `+++` fences. This applies for things like imports, calling macros, defining blocks, etc:
-
-```markdown
-+++
-{% from "views/partials/example/_macro.njk" import patternlibExample %}
-{% from "components/external-link/_macro.njk" import onsExternalLink %}
-+++
-```
-
-As a rule of thumb; code highlight blocks should always be wrapped with `+++` fences:
-
-```markdown
-+++
-{% from "components/code-highlight/_macro.njk" import onsCodeHighlight %}
-{{ onsCodeHighlight({
-"code": '[
-  {
-    "en": "England"
-  },
-  {
-    "en": "Wales"
-  },
-  {
-    "en": "Scotland"
-  },
-  {
-    "en": "Northern Ireland"
-  },
-]'
-}) }}
-+++
-```
-
-Mixed markdown files are easier to maintain when each section that is fenced with `+++` is a standalone unit. For example, each code example should have it's own `+++` fence even if they immediately follow one another. This is because content can be edited around these fenced units.
-
 ## Testing
 
 This project uses [jest](https://jestjs.io/docs/cli) and supports its command line options.
@@ -158,10 +99,6 @@ It is sometimes useful to adjust the following settings when writing tests or di
 
 - `testTimeout` in 'jest.config.js' - set to a high value such as `1000000` to prevent tests from timing out when doing the above.
 
-## Run visual regression tests
-
-To run visual regression (VR) tests on pull requests using our VR testing tool [percy.io](https://percy.io) you must include `[test-visual]` in your commit message e.g. `git commit -m "Update button border width [test-visual]"`. This prevents unnecessary builds and saves the limited quota we have available.
-
 ## Build
 
 Generate a build into `./build`.

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

@@ -0,0 +1,87 @@
+---
+title: "Example: Access code error"
+layout: ~
+---
+{% extends "layout/_template.njk" %}
+{% from "components/access-code/_macro.njk" import onsUACInput %}
+{% from "components/button/_macro.njk" import onsButton %}
+{% from "components/panel/_macro.njk" import onsPanel %}
+{% from "components/details/_macro.njk" import onsDetails %}
+
+{% set pageConfig = {
+  "title": "Study title"
+} %}
+
+{% block main %}
+    {% call
+        onsPanel({
+            title: "There is a problem with this page",
+            type: "error"
+        })
+    %}
+
+        {% from "components/lists/_macro.njk" import onsList %}
+        {{
+            onsList({
+                "element": "ol",
+                "itemsList": [
+                    {
+                        "text": "Enter an access code",
+                        "url": "#uac-error",
+                        "variants": "inPageLink"
+                    }
+                ]
+            })
+        }}
+    {% endcall %}
+
+    <h1 class="ons-u-mt-l">Start study</h1>
+
+    {{ onsUACInput({
+        "id": "uac",
+        "name": "uac",
+        "postTextboxLinkText": "Where to find your access code",
+        "postTextboxLinkUrl": "#0",
+        "label": {
+            "text": "Enter your 16-character access code",
+            "description": "Keep this code safe. You will need to enter it every time you access your survey"
+        },
+        "securityMessage": "Your personal information is protected by law and will be kept confidential",
+        "error": {
+            "id": "uac-error",
+            "text": "Enter an access code"
+        }
+    }) }}
+
+    {{ onsButton({
+        "text": "Access study",
+        "classes": "ons-u-mb-xl"
+    }) }}
+
+    <h2>If you don’t have an access code</h2>
+    <p>
+        You can <a href="#0">request a new access code</a> to start a new study if you have lost or not received an access code. This can be sent to you by text or post.
+    </p>
+
+    {% set content %}
+        <p>If you need to answer separately from the people you live with, you can <a href='#0'>request an individual access code</a> to start a separate study.</p>
+        {% call onsPanel({
+                "type": "warn"
+            })
+        %}
+            Someone in your household must still complete a study using a household access code
+        {% endcall %}
+    {% endset %}
+
+    {% call onsDetails({
+            "id": "details",
+            "title": "Need to answer separately from your household?",
+            "button": {
+                "close": "Hide this",
+                "contextSuffix": "content"
+            }
+        })
+    %}
+        {{ content | safe }}
+    {% endcall %}
+{% endblock %}

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

@@ -0,0 +1,63 @@
+---
+title: "Example: Access code"
+layout: ~
+---
+{% extends "layout/_template.njk" %}
+{% from "components/access-code/_macro.njk" import onsUACInput %}
+{% from "components/button/_macro.njk" import onsButton %}
+{% from "components/panel/_macro.njk" import onsPanel %}
+{% from "components/details/_macro.njk" import onsDetails %}
+
+{% set pageConfig = {
+    "header": {
+        "title": "Study title"
+    }
+} %}
+
+{% block main %}
+    <h1 class="ons-u-mt-l">Start study</h1>
+
+    {{ onsUACInput({
+        "id": "uac",
+        "name": "uac",
+        "postTextboxLinkText": "Where to find your access code",
+        "postTextboxLinkUrl": "#0",
+        "label": {
+            "text": "Enter your 16-character access code",
+            "description": "Keep this code safe. You will need to enter it every time you access your study"
+        },
+        "securityMessage": "Your personal information is protected by law and will be kept confidential"
+    }) }}
+
+    {{ onsButton({
+        "text": "Access study",
+        "classes": "ons-u-mb-xl"
+    }) }}
+
+    <h2>If you don’t have an access code</h2>
+    <p>
+        You can <a href="#0">request a new access code</a> to start a new study if you have lost or not received an access code. This can be sent to you by text or post.
+    </p>
+
+    {% set content %}
+        <p>If you need to answer separately from the people you live with, you can <a href='#0'>request an individual access code</a> to start a separate study.</p>
+        {% call onsPanel({
+                type: "warn"
+            })
+        %}
+            Someone in your household must still complete a study using a household access code
+        {% endcall %}
+    {% endset %}
+
+    {% call onsDetails({
+            id: "details",
+            title: "Need to answer separately from your household?",
+            button: {
+                "close": "Hide this",
+                "contextSuffix": "content"
+            }
+        })
+    %}
+        {{ content | safe }}
+    {% endcall %}
+{% endblock %}

package/components/accordion/example-accordion-open.njk

@@ -0,0 +1,126 @@
+{% from "components/accordion/_macro.njk" import onsAccordion %}
+{% from "components/checkboxes/_macro.njk" import onsCheckboxes %}
+
+
+{% set content1 %}
+    {{
+        onsCheckboxes({
+            "checkboxesLabel": "Show only:",
+            "legend": "Content type",
+            "legendClasses": "ons-u-vh",
+            "classes": "ons-u-mb-s",
+            "borderless": true,
+            "name": "dietary",
+            "checkboxes": [
+                {
+                    "id": "data",
+                    "label": {
+                        "text": "Data (309)"
+                    },
+                    "value": "data"
+                },
+                {
+                    "id": "publications",
+                    "label": {
+                        "text": "Publications (137)"
+                    },
+                    "value": "publications",
+                    "other": {
+                        "otherType": "checkboxes",
+                        "selectAllChildren": true,
+                        "legend": "Publication type",
+                        "legendClasses": "ons-u-vh",
+                        "name": "name",
+                        "checkboxes": [
+                            {
+                                "id": "datasets",
+                                "label": {
+                                    "text": "Datasets (100)"
+                                },
+                                "value": "datasets"
+                            },
+                            {
+                                "id": "timeseries",
+                                "label": {
+                                    "text": "Timeseries (20)"
+                                },
+                                "value": "timeseries"
+                            },
+                            {
+                                "id": "requested",
+                                "label": {
+                                    "text": "User requested data (16)"
+                                },
+                                "value": "requested"
+                            }
+                        ]
+                    }
+                },
+                {
+                    "id": "areas",
+                    "label": {
+                        "text": "Areas (0)"
+                    },
+                    "value": "areas"
+                }       
+            ]
+        })
+    }}
+{% endset %}
+{% set content2 %}
+    {{
+        onsCheckboxes({
+            "checkboxesLabel": "Show only:",
+            "legend": "Topic",
+            "legendClasses": "ons-u-vh",
+            "classes": "ons-u-mb-s",
+            "borderless": true,
+            "name": "dietary",
+            "checkboxes": [
+                {
+                    "id": "crime",
+                    "label": {
+                        "text": "Crime (200)"
+                    },
+                    "value": "crime",
+                    "checked": true
+                },
+                {
+                    "id": "education",
+                    "label": {
+                        "text": "Education (55)"
+                    },
+                    "value": "education"
+                },
+                {
+                    "id": "disability",
+                    "label": {
+                        "text": "Disability (67)"
+                    },
+                    "value": "disability"
+                }       
+            ]
+        })
+    }}
+{% endset %}
+
+<div class="ons-grid">
+    <div class="ons-grid__col ons-col-3@xs">
+        {{
+            onsAccordion({
+                "id": "accordion",
+                "open": true,
+                "itemsList": [
+                    {
+                        "title": "Content type",
+                        "content": content1
+                    },
+                    {
+                        "title": "Topic",
+                        "content": content2
+                    }
+                ]
+            })
+        }}
+    </div>
+</div>

package/components/accordion/example-accordion.njk

@@ -0,0 +1,25 @@
+{% from "components/accordion/_macro.njk" import onsAccordion %}
+
+{{
+    onsAccordion({
+        "id": "accordion",
+        "allButton": {
+            "open": "Show all",
+            "close": "Hide all"
+        },
+        "itemsList": [
+            {
+                "title": "Total retail turnover",
+                "content": "<h3 class=\"ons-u-fs-r\">Include:</h3><ul class=\"ons-list\"><li class=\"ons-list__item\">VAT</li><li class=\"ons-list__item\">internet sales</li><li class=\"ons-list__item\">retail sales from outlets in Great Britain to <a href=\"#\">customers abroad</a></li></ul><h3 class=\"ons-u-fs-r\">Exclude:</h3><ul class=\"ons-list\"><li class=\"ons-list__item\">revenue from mobile phone network commission and top-up</li><li class=\"ons-list__item\">sales from catering facilities used by customers</li><li class=\"ons-list__item\">lottery sales and commission from lottery sales</li><li class=\"ons-list__item\">sales of car accessories and motor vehicles</li><li class=\"ons-list__item\">NHS receipts</li><li class=\"ons-list__item\">automotive fuel</li></ul>"
+            },
+            {
+                "title": "Food sales",
+                "content": "<h3 class=\"ons-u-fs-r\">Include:</h3><ul class=\"ons-list\"><li class=\"ons-list__item\">all fresh food</li><li class=\"ons-list__item\">other food for human consumption (except chocolate and sugar confectionery)</li><li class=\"ons-list__item\">soft drinks</li></ul><h3 class=\"ons-u-fs-r\">Exclude:</h3><ul class=\"ons-list\"><li class=\"ons-list__item\">sales from catering facilities used by customers</li></ul>"
+            },
+            {
+                "title": "Alcohol, confectionery, soft drinks and tobacco sales",
+                "content": "<h3 class=\"ons-u-fs-r\">Include:</h3><ul class=\"ons-list\"><li class=\"ons-list__item\">chocolate and sugar confectionery</li><li class=\"ons-list__item\">tobacco and smokers’ requisites</li></ul>"
+            }
+        ]
+    })
+}}

package/components/address-input/example-address-input-editable.njk

@@ -0,0 +1,52 @@
+{% from "components/address-input/_macro.njk" import onsAddressInput %}
+
+{{ onsAddressInput({
+    "id": "address",
+    "dontWrap": true,
+    "label": {
+        "text": "Enter address or postcode and select from results",
+        "id": "address-label"
+    },
+    "isEditable": true,
+    "mandatory": true,
+    "APIDomain": "#",
+    'APIDomainBearerToken': "some_token",
+    "instructions": "Use up and down keys to navigate suggestions once you\'ve typed more than two characters. Use the enter key to select a suggestion. Touch device users, explore by touch or with swipe gestures.",
+    "ariaYouHaveSelected": "You have selected",
+    "ariaMinChars": "Enter 3 or more characters for suggestions.",
+    "ariaOneResult": "There is one suggestion available.",
+    "ariaNResults": "There are {n} suggestions available.",
+    "ariaLimitedResults": "Results have been limited to 10 suggestions. Type more characters to improve your search",
+    "ariaGroupedResults": "There are {n} for {x}",
+    "groupCount": "{n} addresses",
+    "moreResults": "Enter more of the address to improve results",
+    "resultsTitle": "Select an address",
+    "resultsTitleId": "address-results",
+    "noResults": "No results found. Try entering a different part of the address",
+    "tooManyResults": "{n} results found. Enter more of the address to improve results",
+    "typeMore": "Enter more of the address to get results",
+    "autocomplete": "off",
+    "errorTitle": "There is a problem with your answer",
+    "errorMessageEnter": "Enter an address",
+    "errorMessageSelect": "Select an address",
+    "errorMessageAPI": "Sorry, there is a problem loading addresses.",
+    "errorMessageAPILinkText": "Enter address manually",
+    "options": {
+        "regionCode": "gb-eng",
+        "addressType": "residential"
+    },
+    "line1": {
+        "label": "Address line 1"
+    },
+    "line2": {
+        "label": "Address line 2"
+    },
+    "town": {
+        "label": "Town or city"
+    },
+    "postcode": {
+        "label": "Postcode"
+    },
+    "searchButton": "Search for an address",
+    "manualLinkText": "Manually enter address"
+}) }}

package/components/address-input/example-address-input-manual.njk

@@ -0,0 +1,23 @@
+{% from "components/address-input/_macro.njk" import onsAddressInput %}
+
+{{ onsAddressInput({
+    "id": "address",
+    "dontWrap": true,
+    "manualEntry": true,
+    "label": {
+        "text": "Enter address or postcode and select from results",
+        "id": "address-label"
+    },
+    "line1": {
+        "label": "Address line 1"
+    },
+    "line2": {
+        "label": "Address line 2"
+    },
+    "town": {
+        "label": "Town or city"
+    },
+    "postcode": {
+        "label": "Postcode"
+    }
+}) }}

package/components/address-input/example-address-input.njk

@@ -0,0 +1,40 @@
+{% from "components/address-input/_macro.njk" import onsAddressInput %}
+
+{{ onsAddressInput({
+    "id": "address",
+    "dontWrap": true,
+    "label": {
+        "text": "Enter address or postcode and select from results",
+        "id": "address-label"
+    },
+    "isEditable": false,
+    "mandatory": true,
+    "externalInitialiser": true,
+    "autocomplete": "off",
+    "APIDomain": "#",
+    'APIDomainBearerToken': "some_token",
+    "instructions": "Use up and down keys to navigate suggestions once you\'ve typed more than two characters. Use the enter key to select a suggestion. Touch device users, explore by touch or with swipe gestures.",
+    "ariaYouHaveSelected": "You have selected",
+    "ariaMinChars": "Enter 3 or more characters for suggestions.",
+    "ariaOneResult": "There is one suggestion available.",
+    "ariaNResults": "There are {n} suggestions available.",
+    "ariaLimitedResults": "Results have been limited to 10 suggestions. Type more characters to improve your search",
+    "ariaGroupedResults": "There are {n} for {x}",
+    "groupCount": "{n} addresses",
+    "moreResults": "Enter more of the address to improve results",
+    "resultsTitle": "Select an address",
+    "resultsTitleId": "address-results",
+    "noResults": "No results found. Try entering a different part of the address",
+    "tooManyResults": "{n} results found. Enter more of the address to improve results",
+    "typeMore": "Enter more of the address to get results",
+    "errorTitle": "There is a problem with your answer",
+    "errorMessageEnter": "Enter an address",
+    "errorMessageSelect": "Select an address",
+    "errorMessageAPI": "Sorry, there is a problem. We are working to fix it. Please try again later or",
+    "errorMessageAPILinkText": "contact us for more help",
+    "errorMessageAPILink": "#0",
+    "options": {
+        "regionCode": "gb-eng",
+        "addressType": "residential"
+    }
+}) }}

package/components/autosuggest/example-autosuggest-country-multiple.njk

@@ -0,0 +1,30 @@
+{% from "components/autosuggest/_macro.njk" import onsAutosuggest %}
+
+<div class="ons-grid ons-grid--gutterless">
+    <div class="ons-grid__col ons-col-8@m">
+
+        {{ onsAutosuggest({
+            "id": "country-of-birth",
+            "label": {
+                "text": "Passport",
+                "id": "country-of-birth-label",
+                "description": "Enter your own answer or select from suggestions. You can enter multiple countries if you have a passport for more than one."
+            },
+            "autocomplete": "off",
+            "instructions": "Use up and down keys to navigate suggestions once you\'ve typed more than two characters. Use the enter key to select a suggestion. Touch device users, explore by touch or with swipe gestures.",
+            "ariaYouHaveSelected": "You have selected",
+            "ariaMinChars": "Enter 3 or more characters for suggestions.",
+            "ariaOneResult": "There is one suggestion available.",
+            "ariaNResults": "There are {n} suggestions available.",
+            "ariaLimitedResults": "Results have been limited to 10 suggestions. Type more characters to improve your search",
+            "moreResults": "Continue entering to improve suggestions",
+            "resultsTitle": "Suggestions",
+            "resultsTitleId": "country-of-birth-suggestions",
+            "allowMultiple": true,
+            "autosuggestData": "/examples/data/country-of-birth.json",
+            "noResults": "No suggestions found. You can enter your own answer",
+            "typeMore": "Continue entering to get suggestions"
+        }) }}
+
+    </div>
+</div>

package/components/autosuggest/example-autosuggest-country.njk

@@ -0,0 +1,29 @@
+{% from "components/autosuggest/_macro.njk" import onsAutosuggest %}
+
+<div class="ons-grid ons-grid--gutterless">
+    <div class="ons-grid__col ons-col-8@m">
+
+        {{ onsAutosuggest({
+            "id": "country-of-birth",
+            "label": {
+                "text": "Current name of country",
+                "description": "Enter your own answer or select from suggestions",
+                "id": "country-of-birth-label"
+            },
+            "autocomplete": "off",
+            "instructions": "Use up and down keys to navigate suggestions once you\'ve typed more than two characters. Use the enter key to select a suggestion. Touch device users, explore by touch or with swipe gestures.",
+            "ariaYouHaveSelected": "You have selected",
+            "ariaMinChars": "Enter 3 or more characters for suggestions.",
+            "ariaOneResult": "There is one suggestion available.",
+            "ariaNResults": "There are {n} suggestions available.",
+            "ariaLimitedResults": "Results have been limited to 10 suggestions. Type more characters to improve your search",
+            "moreResults": "Continue entering to improve suggestions",
+            "resultsTitle": "Suggestions",
+            "resultsTitleId": "country-of-birth-suggestions",
+            "autosuggestData": "/examples/data/country-of-birth.json",
+            "noResults": "No suggestions found. You can enter your own answer",
+            "typeMore": "Continue entering to get suggestions"
+        }) }}
+
+    </div>
+</div>

package/components/back-link/example-back-link.njk

@@ -0,0 +1,17 @@
+{% from "components/breadcrumbs/_macro.njk" import onsBreadcrumbs %}
+
+{{
+    onsBreadcrumbs({
+        "ariaLabel": 'Back',
+        "itemsList": [
+            {
+                "url": '/',
+                "id": "back",
+                "text": 'Back',
+                "attributes": {
+                    "data-attribute": "Example attribute"
+                }
+            }
+        ]
+    })
+}}

package/components/breadcrumbs/example-breadcrumbs-single.njk

@@ -0,0 +1,13 @@
+{% from "components/breadcrumbs/_macro.njk" import onsBreadcrumbs %}
+
+{{
+    onsBreadcrumbs({
+        "ariaLabel": 'Breadcrumbs',
+        "itemsList": [
+            {
+                "url": '/',
+                "text": 'Home'
+            }
+        ]
+    })
+}}

package/components/breadcrumbs/example-breadcrumbs.njk

@@ -0,0 +1,17 @@
+{% from "components/breadcrumbs/_macro.njk" import onsBreadcrumbs %}
+
+{{
+    onsBreadcrumbs({
+        "ariaLabel": 'Breadcrumbs',
+        "itemsList": [
+            {
+                "url": '/',
+                "text": 'Home'
+            },
+            {
+                "url": '/components',
+                "text": 'Components'
+            }
+        ]
+    })
+}}

package/components/button/example-button-custom.njk

@@ -0,0 +1,20 @@
+{% from "components/button/_macro.njk" import onsButton %}
+
+<div class="ons-u-mb-m">
+    {{
+        onsButton({
+            "type": 'button',
+            "text": 'Done',
+            "iconType": 'check'
+        })
+    }}
+</div>
+<div>
+    {{
+        onsButton({
+            "text": 'Search',
+            "iconType": 'search',
+            "variants": ['secondary', 'small']
+        })
+    }}
+</div>

package/components/button/example-button-disabled.njk

@@ -0,0 +1,7 @@
+{% from "components/button/_macro.njk" import onsButton %}
+{{
+    onsButton({
+        "text": 'Submit',
+        "variants": 'disabled'
+    })
+}}

package/components/button/example-button-download.njk

@@ -0,0 +1,9 @@
+{% from "components/button/_macro.njk" import onsButton %}
+{{
+    onsButton({
+        "text": 'Save answers as PDF',
+        "url": '#0',
+        "variants": ['download', 'small', 'secondary'],
+        "removeDownloadAttribute": true
+    })
+}}

package/components/button/example-button-ghost.njk

@@ -0,0 +1,15 @@
+---
+fullWidth: true
+---
+{% from "components/button/_macro.njk" import onsButton %}
+<div style="padding: 1.5rem; background: #206095">
+    {{
+        onsButton({
+            "text": 'Save and sign out',
+            "url": '#0',
+            "variants": 'ghost',
+            "iconType": "exit",
+            "iconPosition": "after"
+        })
+    }}
+</div>