1 | # \<kwc-auth\>
|
2 |
|
3 | ## Purpose
|
4 | Front end for Kano's authentication flow.
|
5 |
|
6 | **27/02/2019**: Starting refactor to allow for new GDPR and COPPA compliant flow. This will involve the following tasks:
|
7 | * remove unnecessary properties
|
8 | * remove unnecessary styles
|
9 | * Align with brand styles
|
10 | * Remove Polymer dependency
|
11 | * Add lit-html dependency
|
12 | * Investigation on need for typescript
|
13 | * Remove Behaviour dep
|
14 | * Move behaviour / validation into utility
|
15 | * Ensure tabbing and accessability is as expected
|
16 | * Show/hide password feature
|
17 | * Check username available on blur
|
18 | * Validation of other inputs on blur
|
19 |
|
20 | **24/05/2018**: The README is out of date. Please proceed with caution.
|
21 |
|
22 | This component implements view according to the current User Login Journey as descibe in this [working document](https://docs.google.com/a/kano.me/drawings/d/1TJx_Y6rA6tQYHww99x2aJy4qxoWrQZzoOjYEnQUh5f0/edit?usp=sharing). **Please note** _this link is not guarenteed to be in sync with the component but should be a good guide_.
|
23 |
|
24 | ## Properties
|
25 | |
26 | * errors: Keeps track of error messages.
|
27 | * email: Input value.
|
28 | * firstName: Input value.
|
29 | * isForceSignup: Flags if modal can be closed or not. If `isForceSignup` is `true` then the `kwc-modal` shouldn't be closable.
|
30 | * newsletter: Flags if user wants to subscribe to newsletter.
|
31 | * opened: Flags modal is opened
|
32 | * password: Input value.
|
33 | * processing: Flags if component is waiting an answer from server or parent component.
|
34 | * terms: Flags if user has accepted terms and conditions.
|
35 | * username: Input value.
|
36 | * worldUrl: Kano world URL.
|
37 | * view: Login view to show
|
38 | * _motifUrl: Computed value of jukoka-face url
|
39 | * _linkArrowIcon: Computed value of arrow SVG -->
|
40 |
|
41 |
|
42 |
|
43 | ## API
|
44 |
|
45 | A [ronseal](http://media-assets-02.thedrum.com/cache/images/thedrum-prod/public-news-tmp-56351-1806130_orig--default--300.jpg) function. It does what it says on the tin.
|
46 | ### kwc-auth#open([defaultview])
|
47 | Open the `kwc-auth` modal. The default view is the [`login`](#login) view. This can be overidden if a valid view name is passed.
|
48 | #### Arguments
|
49 | * defaultview: one of `login`, `signup`, `grownups`, `password-reset` or `username-reminder`. -->
|
50 | ### kwc-auth#reset()
|
51 | Reset the internal state of the auth modal. Essentially
|
52 |
|
53 | kwc-auth.errors = {};
|
54 | kwc-auth.firstName = null;
|
55 | kwc-auth.username = null;
|
56 | kwc-auth.password = null;
|
57 | kwc-auth.email = null;
|
58 | kwc-auth.terms = true;
|
59 | kwc-auth.newsletter = false;
|
60 | ``` -->
|
61 | ### kwc-auth#show*
|
62 |
|
63 | * `showLogin()`
|
64 | * `showSignup()`
|
65 | * `showGrownup()`
|
66 | * `showEmail()`
|
67 | * `showDone()`
|
68 | * `showPasswordReset()`
|
69 | * `showResetConfirmation()`
|
70 | * `showUsernameReminder()` -->
|
71 |
|
72 | ## Auth Flows and Views
|
73 | This component is very specific to the authentication flow as it is currently specified for the `kano` apps. It does not contain any logic for completing the authentication flows, that is defered the the context in which the component is used. The views are for collecting the relevant user data so any parent (probably app specific) component can complete the communicaiton with the api and process any responses.
|
74 | ### Login | Signup
|
75 |
|
76 |
|
77 | The `kwc-auth` component implements views for [login](#login) and [signup](#signup) with links between the two. -->
|
78 | #### login
|
79 |
|
80 | * On submit event: [`login`](#login). -->
|
81 | #### signup
|
82 |
|
83 | * On submit event: [`submit-signup-info`](#submit-signup-info). -->
|
84 | #### grownups
|
85 |
|
86 | * On submit event: [`submit-signup-email`](#submit-signup-email). -->
|
87 |
|
88 | ### Forget credentials
|
89 | The `kwc-auth` component implements two views to allow a user to enter information in order to recover forgotten credentials. Username recovery flow accepts a valid email address and password recovery asks for a username. (See [here](https://docs.google.com/a/kano.me/drawings/d/1TJx_Y6rA6tQYHww99x2aJy4qxoWrQZzoOjYEnQUh5f0/edit?usp=sharing) for more detail.)
|
90 |
|
91 | #### password-reset
|
92 | * Fields: username.
|
93 | * On submit event: [`forgot-password`](#forgot-password).
|
94 | #### username-reminder
|
95 | * Fields: email.
|
96 | * On submit event: [`forgot-username`](#forgot-username).
|
97 |
|
98 | This component fires the following custom events:
|
99 |
|
100 | ### cancel
|
101 | This event is fired when the modal close button or the skip button are clicked.
|
102 | ### change-*
|
103 | `kw-auth` exposes the `on-change-[email|firstname|password|username]` events for the input fields on the auth forms. This allows for parent components to apply context specific validations on user inputs. For example we could check username availability as a user types.
|
104 | ```js
|
105 | const authElem = document.querySelector('#auth');
|
106 | authElm.addEventListener('change-username', (e) => {
|
107 |
|
108 | if(this.delayTimer){
|
109 | clearTimeout(this.delayTimer);
|
110 | }
|
111 | this.delayTimer = setTimeout((function(value) {
|
112 | return fetch(`${API_URL}/users/username/${value}`)
|
113 | .then((res) => {
|
114 | if(res.ok){
|
115 | authElm.errors.username = "This one is already taken."
|
116 | }
|
117 | });
|
118 | },
|
119 | }).bind( this, e.detail ), 1000);
|
120 | });
|
121 | ```
|
122 | The `detail` property of the event will contain only the current value of the targeted input.
|
123 | ### done
|
124 | Fired when the `done` button is clicked on the final auth modal view. No data is passed.
|
125 | ### forgot-password
|
126 | The event is passed the following detail:
|
127 | ```js
|
128 | {
|
129 | type: 'object',
|
130 | properties: {
|
131 | username: {
|
132 | type: 'string'
|
133 | }
|
134 | }
|
135 | }
|
136 | ```
|
137 | ### forgot-username
|
138 | The event is passed the following detail:
|
139 | ```js
|
140 | {
|
141 | type: 'object',
|
142 | properties: {
|
143 | password: {
|
144 | type: 'string'
|
145 | }
|
146 | }
|
147 | }
|
148 | ```
|
149 | ### login
|
150 | The event is passed the following detail:
|
151 | ```js
|
152 | {
|
153 | type: 'object',
|
154 | properties: {
|
155 | username: {
|
156 | type: 'string'
|
157 | },
|
158 | password: {
|
159 | type: 'string'
|
160 | }
|
161 | }
|
162 | }
|
163 | ```
|
164 | ### skip
|
165 | The event is passed no data and is followed by a [`cancel`](#cancel) event.
|
166 | ### submit-signup-email
|
167 | The event is passed the following detail:
|
168 | ```js
|
169 | {
|
170 | type: 'object',
|
171 | properties: {
|
172 | firstName: {
|
173 | type: 'string'
|
174 | },
|
175 | username: {
|
176 | type: 'string'
|
177 | },
|
178 | password: {
|
179 | type: 'string'
|
180 | },
|
181 | email: {
|
182 | type: 'string',
|
183 | format: 'email'
|
184 | },
|
185 | newsletter: {
|
186 | type: 'boolean'
|
187 | }
|
188 | }
|
189 | }
|
190 | ```
|
191 | ### submit-signup-info
|
192 | The event is passed the following detail:
|
193 | ```js
|
194 | {
|
195 | type: 'object',
|
196 | properties: {
|
197 | firstName: {
|
198 | type: 'string'
|
199 | },
|
200 | username: {
|
201 | type: 'string'
|
202 | },
|
203 | password: {
|
204 | type: 'string'
|
205 | }
|
206 | }
|
207 | } -->
|
208 | ```
|
209 | ## Installation
|
210 | * Clone this repository.
|
211 | * Run `yarn`
|
212 |
|
213 | * To serve locally `yarn serve` - the site will be served on http://localhost:4000/demo
|
214 |
|
215 | * If you'd like to change the port that it's running on use `yarn serve --port=4040`
|
216 |
|
217 | * yarn add --dev typescript
|
218 | * Watch file changes: yarn tsc --watch
|
219 |
|
220 | ## Running Tests
|
221 |
|
222 | ```
|
223 | $ yarn test
|
224 | ```
|
225 | or to serve your tests while you work
|
226 | ```
|
227 | $ yarn serve-test
|
228 | ```
|