@govuk-one-login/frontend-ui 1.5.0 → 3.0.0

package/build/components/progress-button/template.njk

@@ -0,0 +1,120 @@
+{% set progressButton = params.translations %}
+
+
+{# Set classes for this component #}
+{%- set classNames = "govuk-button govuk-button--progress" -%}
+
+{%- if params.classes %}
+  {% set classNames = classNames + " " + params.classes %}
+{% endif %}
+{% if params.disabled %}
+  {% set classNames = classNames + " govuk-button--disabled" %}
+{% endif -%}
+
+{%- if params.element %}
+  {% set element = params.element | lower %}
+{% else %}
+  {% if params.href %}
+    {% set element = 'a' %}
+  {% else %}
+    {% set element = 'button' %}
+  {% endif %}
+{% endif -%}
+
+{% if params.isStartButton %}
+  {% set iconHtml %}
+{#- The SVG needs `focusable="false"` so that Internet Explorer does not
+treat it as an interactive element - without this it will be
+'focusable' when using the keyboard to navigate. #}
+<svg class="govuk-button__start-icon" xmlns="http://www.w3.org/2000/svg" width="17.5" height="19" viewBox="0 0 33 40" aria-hidden="true" focusable="false">
+  <path fill="currentColor" d="M0 0h13l20 20-20 20H0l20-20z"/>
+</svg>
+  {% endset %}
+  {% set classNames = classNames + " govuk-button--start" %}
+{% endif %}
+
+{#- Define common attributes that we can use across all element types #}
+
+{%- set commonAttributes %} class="{{ classNames }}" data-module="govuk-button"{% for attribute, value in params.attributes %} {{attribute}}="{{value}}"{% endfor %}{% if params.id %} id="{{ params.id }}"{% endif %}{% endset %}
+
+{#- Define common attributes we can use for both button and input types #}
+
+{%- set buttonAttributes %}{% if params.name %} name="{{ params.name }}"{% endif %}{% if params.disabled %} disabled="disabled" aria-disabled="true"{% endif %}{% if params.preventDoubleClick !== undefined %} data-prevent-double-click="{{params.preventDoubleClick}}"{% endif %}{% endset %}
+
+
+{%- if element == 'a' %}
+<a href="{{ params.href if params.href else '#' }}" role="button" draggable="false" {{- commonAttributes | safe }}
+aria-live="assertive"
+onclick="
+    this.blur();
+    this.dataPreventDoubleClick = 'true';
+    this.classList.add('govuk-button--progress-loading');
+    this.innerText = '{{ progressButton.waitingText }}';
+    this.ariaLabel = '{{ progressButton.waitingText }}';
+    setTimeout(() => {
+      this.innerText = '{{ progressButton.longWaitingText }}';
+      this.ariaLabel = '{{ progressButton.longWaitingText }}';
+    }, 5000);
+    setTimeout(() => {
+      window.location.href = '{{ params.errorPage | default('#') }}';
+    }, 10000);
+  ">
+  {% if params.html %}
+    {{ params.html | safe }}
+  {% elseif params.text %}
+    {{ params.text | safe }}
+  {% else %}
+    {{ progressButton.text }}
+  {% endif %}
+  {{- iconHtml | safe | trim | indent(2, true) if iconHtml -}}
+</a>
+
+{%- elseif element == 'button' %}
+<button {%- if params.value %} value="{{ params.value }}"{% endif %}{%- if params.type %} type="{{ params.type }}"{% endif %} {{- buttonAttributes | safe }} {{- commonAttributes | safe }}
+aria-live="assertive"
+onclick="
+    this.blur();
+    this.dataPreventDoubleClick = 'true';
+    this.classList.add('govuk-button--progress-loading');
+    this.innerText = '{{ progressButton.waitingText }}';
+    this.ariaLabel = '{{ progressButton.waitingText }}';
+    setTimeout(() => {
+      this.innerText = '{{ progressButton.longWaitingText }}';
+      this.ariaLabel = '{{ progressButton.longWaitingText }}';
+    }, 5000);
+    setTimeout(() => {
+      window.location.href = '{{ params.errorPage | default('#') }}';
+    }, 10000);
+  ">
+  {% if params.html %}
+    {{ params.html | safe }}
+  {% elseif params.text %}
+    {{ params.text | safe }}
+  {% else %}
+    {{ progressButton.text }}
+  {% endif %}
+  {{- iconHtml | safe | trim | indent(2, true) if iconHtml -}}
+
+</button>
+
+{%- elseif element == 'input' %}
+<input value="{{ params.value }}" type="{{ params.type if params.type else 'submit'}}"{{- buttonAttributes | safe }} {{- commonAttributes | safe }}
+  aria-live="assertive"
+  onclick="
+    this.blur();
+    this.dataPreventDoubleClick = 'true';
+    this.classList.add('govuk-button--progress-loading');
+    this.value = '{{ progressButton.waitingText }}';
+    this.ariaLabel = '{{ progressButton.waitingText }}';
+    setTimeout(() => {
+      this.value = '{{ progressButton.longWaitingText }}';
+      this.ariaLabel = '{{ progressButton.longWaitingText }}';
+    }, 5000);
+    setTimeout(() => {
+      window.location.href = '{{ params.errorPage | default('#') }}';
+    }, 10000);
+    return false;
+  "
+>
+{{- iconHtml | safe | trim | indent(2, true) if iconHtml -}}
+{% endif %}

package/build/components/spinner/README.md

@@ -1,47 +1,82 @@
 # Spinner
 
-This component can be imported to be displayed before the page loads. Currently the logic has been set up to **display** the spinner.
-
-Should you need to ensure it displays before the page renders any data, this should be done within the app.
-
-## Timer
+This component:
+- Displays an animated spinner graphic
+- Repeatedly calls a supplied function
+- Stops the spinner animation when the function returns success, failure, or doesn't return either after a certain amount of time
+- Displays different HTML for the different phases of its lifecycle
+
+It consists of code in `../../frontend-src/spinner/spinner.ts` and styling in `_index.scss`
+
+## Requirements
+
+For the spinner to perform correctly it requires the following:
+- A container `div` to display within
+- A polling function to call repeatedly until it returns success or failure
+- An optional success function to call once if the polling function returns success
+- An optional error function to call once if the polling function returns failure, or we reach the abort duration
+- A div with id `no-js-content`. This should contain the HTML to display if the user has JS disabled
+- An optional div with id `wait-content`. This should contain the default HTML to display under the spinner
+- An optional div with id `long-wait-content`. This should contain the HTML to display under the spinner once it has been spinning for the specified long wait duration
+- An optional div with id `success-content`. This should contain the HTML to display under the spinner once the polling function returns success
+- An optional div with id `error-content`. This should contain the HTML to display under the spinner if the polling function returns failure, or doesn't return success before the abort duration is reached
+- An optional data attribute `data-ms-before-informing-of-long-wait` to set the amount of time the spinner will spin before displaying the `long-wait-content`
+- An optional data attribute `data-ms-before-abort` to set the amount of time the spinner will spin before displaying the `error-content` and calling the `errorFunction`
+- An optional data attribute `data-ms-between-dom-update` to set the amount of time between updates to the spinner UI
+- An optional data attribute `data-ms-between-requests` to set the amount of time between calls to the `pollingFunction`
+- An optional data attribute `data-hide-spinner-on-error` to hide the spinner graphic on error (defaults to false)
+- An optional data attribute `aria-alert-completion-text`. If supplied this text will be set as an aria alert if the spinner completes successfully
+
+For example:
+
+```html
+<div id="spinner-container"
+     data-ms-before-informing-of-long-wait="10000"
+     data-ms-before-abort="30000"
+     data-ms-between-dom-update="1000"
+     data-ms-between-requests="2000"
+     data-hide-spinner-on-error="true"
+     data-aria-alert-completion-text="Task completed successfully, you may now continue">
+  <div id="no-js-content"><p class="centre govuk-body">JS is disabled</p></div>
+  <div id="wait-content" style="display:none"><p class="centre govuk-body">Waiting</p></div>
+  <div id="long-wait-content" style="display:none"><p class="centre govuk-body">Still waiting</p></div>
+  <div id="success-content" style="display:none"><p class="centre govuk-body">Success!</p></div>
+  <div id="error-content" style="display:none"><p class="centre govuk-body">Error :(</p></div>
+</div>
+```
 
-The timer is set to two seconds and this is done in the route. There is a file called `api.njk` and this binds the data attributes that are needed for the script to be run.
+Note that the content divs (except for the no-js div) have `style="display:none"` to hide them until they are needed.
 
-```njk
-{% extends "layouts/main.njk" %}
+```typescript
+async function pollFunction(abortSignal): PollResult {
+  // Check for success
+}
 
-{% set url = "/api" %}
+function successFunction(): void {
+  // Optionally do stuff, e.g. enable a button, redirect, etc
+}
 
-{% block content %}
-  <div id="spinner-container"
-     data-initial-heading="Initial heading text"
-     data-initial-spinnerStateText="Initial spinner state text"
-     data-initial-spinnerState="pending"
-     data-error-heading="Error heading"
-     data-error-messageText="Error message text"
-     data-error-whatYouCanDo-heading="Error what you can do heading"
-     data-error-whatYouCanDo-message-text1="Error what you can do message text1"
-     data-error-whatYouCanDo-message-link-href="Error what you can do message link href"
-     data-error-whatYouCanDo-message-link-text="Error what you can do message link text"
-     data-error-whatYouCanDo-message-text2="Error what you can do message link text2"
-     data-complete-spinnerState="complete"
-     data-longWait-spinnerStateText="Long wait spinner state">
-  </div>
+function errorFunction(): void {
+  // Optionally do stuff, e.g. enable a button, redirect, etc
+}
 
-{% endblock %}
+useSpinner("spinner-container", pollingFunction, successFunction, errorFunction);
+```
 
-{% block pageScripts %}
+## Lifecycle
 
-{% endblock %}
+The spinner starts in the waiting state and displays the `wait` content under the animated spinner graphic content.
+If a call to the polling function returns `success` the spinner will stop animating, display the `success-content` content, and call the `successFunction` (if specified)
+If a call to the polling function returns `failure` the spinner will stop animating, display the `error-content` content, and call the `errorFunction` (if specified)
+If the spinner waits past the `long-wait` duration while the polling function keeps returning `pending` the spinner will display the `long-wait-content` content
+If the spinner waits past the `abort` duration while the polling function keeps returning `pending` the spinner will stop animating, display the `error-content` content, and call the `errorFunction` (if specified)
 
+### Page refreshes
 
-```
+When the spinner starts for the first time it stores the current time in session storage. If the page is refreshed the spinner will retrieve the initial start time from session storage and update itself appropriately. 
 
 ## Scripts
 
-The script finds the DOM element of the ID `spinner-container` and then runs the animation, it has the flexibility for an error state to be handled or for spinner to take longer/shorter.
-
 Within the frontend-ui package, this script is bundled within `frontend-src`, so that it can be used in the alpha-app.
 
 Please note that in the `package.json` file of the frontend-ui repo the files needed for the spinner are exported as follows:
@@ -63,11 +98,13 @@ The default import is at the top and the one at the bottom ensures, the correct
 
 Configurations to the alpha-app have also been made to ensure these script files work accordingly however this should not affect any users wanting to use the spinner component from the frontend-ui package.
 
-## Routes
+## Manual Testing
+
+The nunjucks files in this folder are to allow automated accessibility testing, most users of the spinner component will only need the CSS and script files.
 
-The way testing is done for visual purposes of the components within the frontend-ui package is through the alpha-app.
+There is a `/spinner` page in the alpha-app that will display the spinner component.
 
-The routes are set with Express and it is important to note, this route setting is important within the user's application to ensure the spinner works effectively.
+An endpoint has been created in the alpha-app at `/api` that will return a pending result for a specified number of requests before returning a success response.
 
 ```js
 let counter = 0;
@@ -86,22 +123,3 @@ app.get("/api", (req, res) => {
   }
 });
 ```
-
-This block of code is used **before** any middleware is set, to ensure the params at the end of the route can be captured. This is also helpful as usually the spinner is the first thing to render, whilst the page waits for data to be loaded.
-
-There is a counter set here and within `template.njk` the url sets the processing time (defaulted to 2 currently).
-
-```njk
-{% block content %}
-
-{% set url = "/api?processingTime=2" %}
-
-
-<div id="spinner-container" data-api-route="{{ url }}">
-
-</div>
-
-{% endblock %}
-```
-
-It is important that the url is set and the page uses the correct ID.

package/build/components/spinner/_index.scss

@@ -6,7 +6,7 @@
   border-style: solid;
   border-color: #dee0e2;
   border-top-color: #005ea5;
-  margin-bottom: govuk-spacing(3);
+  margin-bottom: 15px;
 
   @media (forced-colors: active) {
     forced-color-adjust: none;
@@ -22,22 +22,13 @@
     transform: rotate(0.125turn);
   }
 
-  &__ready {
+  &__finished {
     border-color: #005ea5;
     -webkit-animation: none;
     animation: none;
   }
 }
 
-#spinner-container {
-  &__error {
-    .spinner,
-    .spinner-state-text {
-      display: none;
-    }
-  }
-}
-
 @-webkit-keyframes spin {
   0% {
     -webkit-transform: rotate(0deg);

package/build/components/spinner/template.njk

@@ -1,11 +1,18 @@
+{# This template is for use in accessbility testing. #}
 {% block content %}
 
-{% set url = "/api?processingTime=2" %}
+<main>
+  <div id="spinner-container"
+       data-ms-before-informing-of-long-wait="4000"
+       data-ms-before-abort="9000"
+       data-ms-between-dom-update="1000"
+       data-ms-between-requests="3000">
+    <div id="no-js-content"><p class="centre govuk-body">JS is disabled</p></div>
+    <div id="wait-content" style="display:none"><p class="centre govuk-body">Waiting</p></div>
+    <div id="long-wait-content" style="display:none"><p class="centre govuk-body">Still waiting</p></div>
+    <div id="success-content" style="display:none"><p class="centre govuk-body">Success!</p></div>
+    <div id="error-content" style="display:none"><p class="centre govuk-body">Error :(</p></div>
+  </div>
+</main>
 
-
-<div id="spinner-container" data-api-route="{{ url }}">
-   
-</div>
-
-
-{% endblock %}
+{% endblock %}

package/build/esm/backend/index.d.ts

@@ -91,6 +91,11 @@ export declare const frontendUiTranslationEn: {
     skipLink: {
         title: string;
     };
+    progressButton: {
+        text: string;
+        waitingText: string;
+        longWaitingText: string;
+    };
 };
 export declare const frontendUiTranslationCy: {
     cookieBanner: {
@@ -149,6 +154,11 @@ export declare const frontendUiTranslationCy: {
     skipLink: {
         title: string;
     };
+    progressButton: {
+        text: string;
+        waitingText: string;
+        longWaitingText: string;
+    };
 };
 export {};
 //# sourceMappingURL=index.d.ts.map

package/build/esm/backend/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAQ1D,UAAU,QAAQ;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE;QACL,IAAI,EAAE;YAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;SAAE,CAAC;KAClC,CAAC;CACH;AAED,UAAU,cAAe,SAAQ,OAAO;IACtC,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED,UAAU,eAAgB,SAAQ,QAAQ;IACxC,MAAM,EAAE;QACN,YAAY,EAAE,OAAO,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,UAAU,YAAY;IACpB,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED,UAAU,aAAa;IACrB,MAAM,EAAE;QACN,YAAY,EAAE,OAAO,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAGD,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,cAAc,EACnB,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE,YAAY,GACjB,IAAI,CAAC;AAER,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,YAAY,GACjB,IAAI,CAAC;AAaR,eAAO,MAAM,yBAAyB,GAAI,cAAc,OAAO,OAAO,SAerE,CAAC;AAGF,eAAO,MAAM,kCAAkC,GAC7C,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,MAAM,YAAY,SAUnB,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,UAU3D;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,iBAkBhE;AAED,eAAO,MAAM,mBAAmB,GAC9B,cAAc,OAAO,OAAO,EAC5B,WAAW,MAAM,SASlB,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,MAAM,EACd,WAAW,MAAM,KAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAuBxB,CAAC;AAEF,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAgB,CAAC;AACrD,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAQ1D,UAAU,QAAQ;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE;QACL,IAAI,EAAE;YAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;SAAE,CAAC;KAClC,CAAC;CACH;AAED,UAAU,cAAe,SAAQ,OAAO;IACtC,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED,UAAU,eAAgB,SAAQ,QAAQ;IACxC,MAAM,EAAE;QACN,YAAY,EAAE,OAAO,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,UAAU,YAAY;IACpB,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED,UAAU,aAAa;IACrB,MAAM,EAAE;QACN,YAAY,EAAE,OAAO,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAGD,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,cAAc,EACnB,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE,YAAY,GACjB,IAAI,CAAC;AAER,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,YAAY,GACjB,IAAI,CAAC;AAaR,eAAO,MAAM,yBAAyB,GAAI,cAAc,OAAO,OAAO,SAerE,CAAC;AAGF,eAAO,MAAM,kCAAkC,GAC7C,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,MAAM,YAAY,SAUnB,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,UAU3D;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,iBAkBhE;AAED,eAAO,MAAM,mBAAmB,GAC9B,cAAc,OAAO,OAAO,EAC5B,WAAW,MAAM,SASlB,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,MAAM,EACd,WAAW,MAAM,KAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAuBxB,CAAC;AAEF,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAgB,CAAC;AACrD,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAgB,CAAC"}

package/build/esm/backend/index.js

@@ -71,13 +71,19 @@ var phaseBanner$1 = {
 var skipLink$1 = {
 	title: "Neidio i'r prif gynnwys"
 };
+var progressButton$1 = {
+	text: "Parhau",
+	waitingText: "Aros",
+	longWaitingText: "Parhau i aros"
+};
 var translationCy = {
 	cookieBanner: cookieBanner$1,
 	footer: footer$1,
 	header: header$1,
 	languageSelect: languageSelect$1,
 	phaseBanner: phaseBanner$1,
-	skipLink: skipLink$1
+	skipLink: skipLink$1,
+	progressButton: progressButton$1
 };
 
 var cookieBanner = {
@@ -150,13 +156,19 @@ var phaseBanner = {
 var skipLink = {
 	title: "Skip to main content"
 };
+var progressButton = {
+	text: "Continue",
+	waitingText: "Wait",
+	longWaitingText: "Keep waiting"
+};
 var translationEn = {
 	cookieBanner: cookieBanner,
 	footer: footer,
 	header: header,
 	languageSelect: languageSelect,
 	phaseBanner: phaseBanner,
-	skipLink: skipLink
+	skipLink: skipLink,
+	progressButton: progressButton
 };
 
 // Implementation

package/build/esm/frontend/index.d.ts

@@ -1,2 +1,3 @@
-export { useSpinner } from "./spinner/spinner";
+export { useSpinner, PollResult } from "./spinner/spinner";
+export type { PollingFunction } from "./spinner/spinner";
 //# sourceMappingURL=index.d.ts.map

package/build/esm/frontend/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../frontend-src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../frontend-src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC3D,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}