pwa-auth 3.6.0 → 3.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. package/README.md +140 -485
  2. package/base/export/drawer.d.ts +2 -0
  3. package/base/export/drawer.d.ts.map +1 -0
  4. package/base/export/drawer.js +2 -0
  5. package/base/export/drawer.js.map +1 -0
  6. package/base/export/icon.d.ts +2 -0
  7. package/base/export/icon.d.ts.map +1 -0
  8. package/base/export/icon.js +2 -0
  9. package/base/export/icon.js.map +1 -0
  10. package/base/export/login.d.ts +2 -0
  11. package/base/export/login.d.ts.map +1 -0
  12. package/base/export/login.js +2 -0
  13. package/base/export/login.js.map +1 -0
  14. package/base/export/reset.d.ts +2 -0
  15. package/base/export/reset.d.ts.map +1 -0
  16. package/base/export/reset.js +2 -0
  17. package/base/export/reset.js.map +1 -0
  18. package/base/export/settings.d.ts +2 -0
  19. package/base/export/settings.d.ts.map +1 -0
  20. package/base/export/settings.js +2 -0
  21. package/base/export/settings.js.map +1 -0
  22. package/base/webcomponents/css/animation.d.ts.map +1 -1
  23. package/base/webcomponents/css/animation.js +35 -63
  24. package/base/webcomponents/css/animation.js.map +1 -1
  25. package/base/webcomponents/drawer/css/drawer.d.ts.map +1 -1
  26. package/base/webcomponents/drawer/css/drawer.js +12 -14
  27. package/base/webcomponents/drawer/css/drawer.js.map +1 -1
  28. package/base/webcomponents/drawer/css/exit.js +1 -1
  29. package/base/webcomponents/drawer/css/paragraph.d.ts.map +1 -1
  30. package/base/webcomponents/drawer/css/paragraph.js +10 -3
  31. package/base/webcomponents/drawer/css/paragraph.js.map +1 -1
  32. package/base/webcomponents/drawer/drawer.d.ts +25 -0
  33. package/base/webcomponents/drawer/drawer.d.ts.map +1 -1
  34. package/base/webcomponents/drawer/drawer.js +298 -17
  35. package/base/webcomponents/drawer/drawer.js.map +1 -1
  36. package/base/webcomponents/form/css/button.d.ts.map +1 -1
  37. package/base/webcomponents/form/css/button.js +15 -16
  38. package/base/webcomponents/form/css/button.js.map +1 -1
  39. package/base/webcomponents/form/css/input.d.ts.map +1 -1
  40. package/base/webcomponents/form/css/input.js +10 -1
  41. package/base/webcomponents/form/css/input.js.map +1 -1
  42. package/base/webcomponents/form/css/label.d.ts.map +1 -1
  43. package/base/webcomponents/form/css/label.js +19 -1
  44. package/base/webcomponents/form/css/label.js.map +1 -1
  45. package/base/webcomponents/form/css/list.d.ts.map +1 -1
  46. package/base/webcomponents/form/css/list.js +2 -1
  47. package/base/webcomponents/form/css/list.js.map +1 -1
  48. package/base/webcomponents/form/css/notice.js +3 -3
  49. package/base/webcomponents/form/css/status.d.ts.map +1 -1
  50. package/base/webcomponents/form/css/status.js +18 -5
  51. package/base/webcomponents/form/css/status.js.map +1 -1
  52. package/base/webcomponents/form/css/toggle.d.ts.map +1 -1
  53. package/base/webcomponents/form/css/toggle.js +7 -0
  54. package/base/webcomponents/form/css/toggle.js.map +1 -1
  55. package/base/webcomponents/form/forgot.d.ts.map +1 -1
  56. package/base/webcomponents/form/forgot.js +5 -4
  57. package/base/webcomponents/form/forgot.js.map +1 -1
  58. package/base/webcomponents/form/login.js +1 -1
  59. package/base/webcomponents/form/signup.js +1 -1
  60. package/base/webcomponents/icon/css/icon.d.ts.map +1 -1
  61. package/base/webcomponents/icon/css/icon.js +9 -0
  62. package/base/webcomponents/icon/css/icon.js.map +1 -1
  63. package/base/webcomponents/login/css/auth.d.ts.map +1 -1
  64. package/base/webcomponents/login/css/auth.js +9 -4
  65. package/base/webcomponents/login/css/auth.js.map +1 -1
  66. package/base/webcomponents/login/page.d.ts +20 -1
  67. package/base/webcomponents/login/page.d.ts.map +1 -1
  68. package/base/webcomponents/login/page.js +182 -6
  69. package/base/webcomponents/login/page.js.map +1 -1
  70. package/base/webcomponents/settings/css/navigation.js +3 -3
  71. package/base/webcomponents/settings/input/delete.d.ts.map +1 -1
  72. package/base/webcomponents/settings/input/delete.js +7 -1
  73. package/base/webcomponents/settings/input/delete.js.map +1 -1
  74. package/base/webcomponents/settings/input/uploader.d.ts.map +1 -1
  75. package/base/webcomponents/settings/input/uploader.js +8 -4
  76. package/base/webcomponents/settings/input/uploader.js.map +1 -1
  77. package/base/webcomponents/settings/input/verify.d.ts.map +1 -1
  78. package/base/webcomponents/settings/input/verify.js +24 -7
  79. package/base/webcomponents/settings/input/verify.js.map +1 -1
  80. package/base/webcomponents/settings/settings.d.ts +19 -1
  81. package/base/webcomponents/settings/settings.d.ts.map +1 -1
  82. package/base/webcomponents/settings/settings.js +177 -12
  83. package/base/webcomponents/settings/settings.js.map +1 -1
  84. package/docs/drawer-slide.md +206 -0
  85. package/docs/sliders.md +38 -31
  86. package/package.json +48 -10
  87. package/source/pwa-auth.js +408 -267
  88. package/source/pwa-styles.css +0 -8
  89. package/firebase.md +0 -125
  90. package/intro.md +0 -19
package/README.md CHANGED
@@ -1,540 +1,195 @@
1
1
  # pwa-auth
2
2
 
3
- [![npm version](https://img.shields.io/npm/v/pwa-auth)](https://www.npmjs.com/package/pwa-auth)
4
- [![license](https://img.shields.io/badge/license-MIT-blue)](license)
3
+ Sign-in elements for a site that keeps its own pages. [Demo](https://pwa-authentic.firebaseapp.com).
5
4
 
6
- Site owners can start with [a short introduction](intro.md).
5
+ Five tags. They share one sign-in. MIT.
7
6
 
8
- Jack's Publishing maintains sign-in and account components so a site can stay on its own interface. [Live demo](https://pwa-authentic.firebaseapp.com).
9
-
10
- Five elements: `user-icon`, `user-drawer`, `user-login`, `user-settings`, and `email-reset`. They sign a person up, sign them in, and let them change name, email, password, and photo, or delete the account. Email and password only. Sign-up sends a verification email. Sign-in still succeeds when that address is unverified. One Firebase session, shared by every tag on the page.
11
-
12
- Place the tags. Set Firebase with the script or `initialize()`. Listen for `pwa-` events, or call the small API (`getCurrentUser`, `onUserChanged`, `openDrawer`, `closeDrawer`, `toggleDrawer`). Restyle with `--pwa_` variables.
13
-
14
- Peers: `lit` ^3.3.0 and `firebase` ^12.0.0. The package is ESM (`"type": "module"`).
15
-
16
- ## Contents
17
-
18
- - [Quick start](#quick-start)
19
- - [Install & entries](#install--entries)
20
- - [Firebase](firebase.md)
21
- - [Elements](#elements)
22
- - [Page examples](#page-examples)
23
- - [Events](#events)
24
- - [API](#api)
25
- - [Exports](#exports)
26
- - [Theme](#theme)
27
- - [Parts](#parts)
28
- - [Drawer behaviour](#drawer-behaviour)
29
- - [Slides](docs/sliders.md)
30
- - [Data ownership](#data-ownership)
31
- - [Contributing](#contributing)
32
- - [Feedback](#feedback)
33
-
34
- ## Quick start
35
-
36
- Install the package and the peers. Serve this page from the project root. Do not open it with `file://`.
37
-
38
- ```bash
39
- npm install pwa-auth lit firebase
40
- ```
41
-
42
- ```html
43
- <user-icon></user-icon>
44
- <user-drawer></user-drawer>
45
- <script>
46
- window.process = { env: { FIREBASE_CONFIG: JSON.stringify({
47
- apiKey: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
48
- authDomain: "xxxxxxx.xxxxxxx.xxx",
49
- databaseURL: "https://xxxxxxx.xxxxxxx.xxx",
50
- projectId: "xxxxxxx",
51
- storageBucket: "xxxxxxx.xxxxxxx.xxx",
52
- messagingSenderId: "xxxxxxxxxxx",
53
- appId: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
54
- measurementId: "xxxxxxxxxxx"
55
- }) } };
56
- </script>
57
- <script type="module" src="./node_modules/pwa-auth/source/pwa-auth.js"></script>
58
- ```
59
-
60
- The module script loads the production bundle. Lit and Firebase are already in the file. A bundler imports `pwa-auth` instead. See [Install & entries](#install--entries). Setup for that script, including `initialize({ config })`, is in [firebase.md](firebase.md).
61
-
62
- ## Install & entries
7
+ ## Install
63
8
 
64
9
  ```bash
65
- npm install pwa-auth lit firebase
10
+ npm install pwa-auth
66
11
  ```
67
12
 
68
- `lit` and `firebase` are peers. Redux ships inside the package.
69
-
70
- Two entries.
71
-
72
- A bundler (Vite, Rollup, webpack) loads the tsc graph. The peers stay outside the bundle. Install them.
13
+ `lit` and `firebase` come along automatically as peer dependencies (npm 7+).
73
14
 
74
15
  ```javascript
75
16
  import 'pwa-auth';
76
17
  ```
77
18
 
78
- `pwa-auth` resolves to `base/export/pwa-auth.js`.
79
-
80
- A plain module script loads one file. Lit and Firebase are inside it. From the project root:
81
-
82
- ```html
83
- <script type="module" src="./node_modules/pwa-auth/source/pwa-auth.js"></script>
84
- ```
85
-
86
- The same file, when a bundler asks for it:
19
+ That turns on all five tags. One tag at a time:
87
20
 
88
21
  ```javascript
89
- import 'pwa-auth/production';
22
+ import 'pwa-auth/icon';
23
+ import 'pwa-auth/drawer';
24
+ import 'pwa-auth/login';
25
+ import 'pwa-auth/settings';
26
+ import 'pwa-auth/reset';
90
27
  ```
91
28
 
92
- `pwa-auth/production` resolves to `source/pwa-auth.js`.
93
-
94
- ## Firebase
95
-
96
- Project setup, `initialize({ config })`, `FIREBASE_CONFIG`, rules, and emulators are in [firebase.md](firebase.md).
97
-
98
- ## Elements
99
-
100
- Importing the package defines all five.
101
-
102
- ### `<user-icon>`
103
-
104
- The button that opens the drawer.
105
-
106
- | Attribute | |
107
- |---|---|
108
- | `subscribe` | Logged-out label is Subscribe. Without it, the label is Login. |
109
- | `empty` | Image URL used when the account has no photo and no name or email to initial. |
110
-
111
- Logged in, the button shows the photo. With no photo, it shows initials from the display name, or from the email. `empty` is the last fallback. The click opens or closes the drawer. Style it with `user-icon::part(button)`, `user-icon::part(photo)`, and `user-icon::part(initials)`.
112
-
113
- ### `<user-drawer>`
114
-
115
- Drops open from the top. Timing is in [Drawer behaviour](#drawer-behaviour).
116
-
117
- | Attribute | |
118
- |---|---|
119
- | `subscribe` | Starts on the sign-up form. Without it, starts on sign-in. |
120
- | `url` | `href` of the Settings control shown after sign-in. Set it only when that page is a real route. Leave it unset when `<user-settings>` is already on this page. |
121
- | `drawer` | Reflects the open state. Redux overwrites it. Do not treat it as an input. |
122
-
123
- Logged out, the header reads Subscribe or Login to match the form. The slots are in the signed-in block, so they are not shown until someone is signed in. Logged in, the header shows the display name, or the email when the account has no name, then, in this order:
124
-
125
- The slots are where the host passes its own links, such as a link to wherever its own settings page lives. The `before` slot places links top down from the top of the drawer, above Settings, and the default slot places them lower, before Log out.
126
-
127
- 1. slot `before`
128
- 2. Settings (`url`, or the button that stays on this page)
129
- 3. the default slot
130
- 4. Log out
131
-
132
- There is no slot named `within`. The second slot is the default slot.
133
-
134
- Each slot has fallback text so the host can see where a link will sit: `slotted - before` in the before slot, `slotted - default` in the default slot. Pass a link or a button and that marker is replaced.
29
+ A page with no build step. Lit and Firebase are already in this file.
135
30
 
136
31
  ```html
137
- <user-drawer>
138
- <a slot="before" href="/account">Account</a>
139
- <a href="/archive" aria-current="page">Archive</a>
140
- </user-drawer>
141
- ```
142
-
143
- `::slotted(a)` and `::slotted(button)` share one style: a full-width row, the line colour, and a 44px tap target. `aria-current` on either one uses the nav highlight. A click on a slotted link or button closes the drawer, the same as Settings. Call `preventDefault()` on that click to leave the drawer open.
144
-
145
- `url` is only the Settings control. It is not the slot. Leave `url` unset when `<user-settings>` is on this page. Set `url` when Settings is a real route. Slotted links are the host's own pages.
146
-
147
- Slotted links can flash before the element upgrades. Hide them:
148
-
149
- ```css
150
- /* Optional - hide slotted links until user-drawer upgrades */
151
- user-drawer:not(:defined) { display: none; }
32
+ <script type="module" src="./node_modules/pwa-auth/source/pwa-auth.js"></script>
152
33
  ```
153
34
 
154
- Settings does not assume a `/settings` route. With `url` unset, it is a button. The click closes the drawer, scrolls to `<user-settings>` when that element is on the page, and dispatches `pwa-settings` with `{ url: '' }`. The event is cancelable. Call `preventDefault()` to keep the drawer open and skip the scroll. With `url` set, Settings is a link to that href, and the same event carries `{ url }`.
155
-
156
- ### `<user-login>`
157
-
158
- The same forms, in the page instead of the drawer.
35
+ `import 'pwa-auth/production'` is that same file.
159
36
 
160
- | Attribute | |
161
- |---|---|
162
- | `subscribe` | Starts on sign-up. Without it, starts on sign-in. |
37
+ | Import | What you get |
38
+ | --- | --- |
39
+ | `pwa-auth` | All five tags, and the functions below |
40
+ | `pwa-auth/icon` | `<user-icon>` only. Class `UserIcon` |
41
+ | `pwa-auth/drawer` | `<user-drawer>` only. Class `UserDrawer` |
42
+ | `pwa-auth/login` | `<user-login>` only. Class `UserLogin` |
43
+ | `pwa-auth/settings` | `<user-settings>` only. Class `UserSettings` |
44
+ | `pwa-auth/reset` | `<email-reset>` only. Class `EmailReset` |
45
+ | `pwa-auth/production` | The single file. Same functions as `pwa-auth` |
163
46
 
164
- Continue with Google is on the sign-in form and the sign-up form. The first Google sign-in creates the Firebase user. A Google account is already verified, so the checkmark shows. `hide-google` on `<user-login>` or `<user-drawer>` removes the button. The default is to show it.
47
+ Works in current Chrome, Edge, Firefox, and Safari. The fields fit any layout, from a phone to a desktop.
165
48
 
166
- Sign-in calls `signInWithEmailAndPassword` and sends the password as typed. Sign-up rejects a new password shorter than 8 characters or longer than 128. Spaces and other characters are allowed. The field hint reads "At least 8 characters. A passphrase works well." A failed sign-in or sign-up writes one sentence into an `aria-live` region (`::part(status)`). The button is disabled and reads Signing in… or Creating account… while the request is in flight.
167
-
168
- Forgot password? sits on the sign-in form. It calls `sendPasswordResetEmail` for the address already in the email field. Success shows the same sentence as `<email-reset>`: "If an account uses that email, a reset link is on its way." A missing account gets that sentence too. The page dispatches `pwa-reset-sent`.
169
-
170
- Sign-up calls `sendEmailVerification`. `actionCodeSettings` from `initialize` is passed through when it is set. The form shows "Check your inbox for the verification email. You can still sign in." The same notice stays on `<user-login>` and in the drawer until the address is verified.
171
-
172
- Each password field has a Show control. Logged in, the forms are replaced by slot `content`.
49
+ ## Tags
173
50
 
174
51
  ```html
52
+ <user-icon subscribe></user-icon>
53
+ <user-drawer subscribe></user-drawer>
175
54
  <user-login>
176
- <div slot="content">
177
- <p>Page content</p>
178
- </div>
55
+ <p slot="content">Signed in.</p>
179
56
  </user-login>
180
- ```
181
-
182
- ### `<user-settings>`
183
-
184
- Four tabs: Icon, Profile, Password, Delete.
185
-
186
- | Attribute | |
187
- |---|---|
188
- | `empty` | Fallback photo, passed through to the uploader as `emptyArtwork`. |
189
-
190
- Signed out, the element shows one line: sign in to change the photo, name, email, or password. The tabs and fields are not in the tree.
191
-
192
- Profile saves the display name with `updateProfile`. The icon, the drawer, and this panel read that name back. A saved name is still there after the next sign-in.
193
-
194
- The photo uploads to `pwa-auth/{uid}/`. On completion the status reads Photo saved. and the same URL is the account photo. Initials stand in until a photo exists.
195
-
196
- A failed action writes a sentence into that tab's `aria-live` region and dispatches `pwa-auth-error`. The Update, Delete, and upload controls disable and read a busy label while the request is in flight.
197
-
198
- When the signed-in address is unverified:
199
-
200
- - That tab shows the address, the words Not verified (`::part(unverified)`), and a Resend verification email button (`::part(verify-submit)`).
201
- - The same words and the same button are in the drawer, next to the name or email.
202
- - The status (`::part(verify-status)`) is an `aria-live` region.
203
- - The button reads Sending… while the request is in flight, then waits 45 seconds. The confirmation is "Check your inbox for the verification email."
204
- - `auth/too-many-requests` and `auth/network-request-failed` write a short sentence into the status region and dispatch `pwa-auth-error`.
205
- - A verified address shows a check (`::part(verified)`, aria-label Email verified) beside the email in settings and beside the name or email in the drawer. The colour is `--pwa_verified_color`.
206
- - Opening the drawer, or focusing the window, calls `user.reload()`. When that reload sees the address become verified, the page fires `pwa-email-verified`.
207
- - Sign-in is not blocked either way.
208
- - Changing the email calls `verifyBeforeUpdateEmail`. `actionCodeSettings` from `initialize` is passed through. If the address still on the account is unverified, `sendEmailVerification` runs as well.
209
-
210
- Email, password, and delete ask for the current password and call `reauthenticate` first.
211
-
212
- - Email then calls `verifyBeforeUpdateEmail`. On success the page dispatches `pwa-email-changed` on `window` with `{ email }`. The old `userEmailChanged` event still fires and is deprecated.
213
- - Password requires the verify field to match. A new password is 8 to 128 characters, the same rule as sign-up. On success the page dispatches `pwa-password-changed` on `window` with `{ uid }`.
214
- - Delete removes this user's files under `pwa-auth/{uid}`, calls `logAccountDelete`, then deletes the auth user. It does not delete `users/{uid}`. See [Data ownership](#data-ownership).
215
- - A failed action writes a short sentence into the status region and dispatches `pwa-auth-error`.
216
-
217
- ### `<email-reset>`
218
-
219
- Sends a password reset for the address in the field. The address is checked before `sendPasswordResetEmail`. An empty or short address fires `pwa-auth-error` with `pwa/missing-email`. A malformed address uses `pwa/invalid-email`.
220
-
221
- While the request is in flight the button is disabled and reads Sending…. Success shows one sentence either way, including when Firebase returns `auth/user-not-found`: "If an account uses that email, a reset link is on its way." The page dispatches `pwa-reset-sent` on `window` with `{ email }`. The button then waits 45 seconds.
222
-
223
- `auth/invalid-email`, `auth/too-many-requests`, and `auth/network-request-failed` write a short sentence into the status region and dispatch `pwa-auth-error`. The event still carries the Firebase code.
224
-
225
- If a sign-in form on the page already has an email, the field starts with that address until someone types in the reset field. Back to sign in opens `<user-drawer>` on the sign-in form. With no drawer, it shows the sign-in form in `<user-login>`.
226
-
227
- | Attribute | |
228
- |---|---|
229
- | `active` | Required. The element renders nothing until `active` is set. |
230
-
231
- ```html
57
+ <user-settings></user-settings>
232
58
  <email-reset active></email-reset>
233
59
  ```
234
60
 
235
- ## Page examples
236
-
237
- ### Drawer page
238
-
239
- ```html
240
- <style>
241
- /* Optional - hide slotted links until user-drawer upgrades */
242
- user-drawer:not(:defined) { display: none; }
243
- </style>
244
-
245
- <body>
246
- <header>
247
- <user-icon subscribe></user-icon>
248
- </header>
249
-
250
- <user-drawer subscribe>
251
- <a slot="before" href="#settings">Settings</a>
252
- <a href="./elsewhere">Another link</a>
253
- </user-drawer>
254
-
255
- <main>
256
- <user-settings id="settings"></user-settings>
257
- </main>
258
- </body>
259
- ```
260
-
261
- ### Sign-in page
262
-
263
- ```html
264
- <body>
265
- <header>
266
- <user-icon subscribe></user-icon>
267
- </header>
268
-
269
- <main>
270
- <user-login subscribe>
271
- <div slot="content">
272
- <p>Page content</p>
273
- </div>
274
- </user-login>
275
-
276
- <user-settings></user-settings>
277
- </main>
278
- </body>
279
- ```
61
+ | Tag | What you set | What it sets | Slots |
62
+ | --- | --- | --- | --- |
63
+ | `user-icon` | `subscribe` starts the label on Subscribe. `empty` is the picture when there is no photo and no initials. `firebase-config` is the Firebase JSON | | |
64
+ | `user-drawer` | `subscribe` starts on sign-up. `hide-google` removes Continue with Google. `url` is the Settings link; leave it off to stay on this page. `firebase-config` as above. Put the tag where it should open. It unrolls down from that spot and does not push the page | `drawer` while open. `sliding` while it moves | `before`, and the default slot, for your own links |
65
+ | `user-login` | `subscribe` and `hide-google`, same as the drawer. `firebase-config` as above | | `content` replaces the form after sign-in |
66
+ | `user-settings` | `empty` is the picture when the account has none. `firebase-config` as above. Signed out, one line and no fields | | |
67
+ | `email-reset` | `active`, or the form stays blank. Then it emails a reset link for the address in the field | | |
280
68
 
281
69
  ## Events
282
70
 
283
- Global events fire on `window`. `pwa-drawer-toggle` fires on `<user-drawer>`, bubbles, and is `composed`. Every event is a `CustomEvent` with `bubbles: true` and `composed: true`. Names and detail types live in `typescript/events/names.ts` and `typescript/events/types.ts`.
284
-
285
- - `pwa-auth-changed` — every `onAuthStateChanged`. Detail: `{ user: { uid, displayName, email, photoURL, emailVerified } | null }`
286
- - `pwa-login` — email sign-in succeeded. Detail: `{ user: { uid, displayName, email, photoURL, emailVerified } }`
287
- - `pwa-logout` — `logOut()` finished. Detail: `{ user: null }`
288
- - `pwa-signup` — `createUserWithEmailAndPassword` succeeded. Detail: `{ user: { uid, displayName, email, photoURL, emailVerified } }`
289
- - `pwa-account-deleted` — the auth user was deleted. Detail: `{ uid }`. The host deletes its own `users/{uid}` document.
290
- - `pwa-profile-updated` — display name or photo saved. Detail: `{ uid, displayName, photoURL }`
291
- - `pwa-email-changed` — `verifyBeforeUpdateEmail` accepted the address. Detail: `{ email }`
292
- - `pwa-password-changed` — `updatePassword` succeeded. Detail: `{ uid }`. The new password is not included.
293
- - `pwa-reset-sent` — `sendPasswordResetEmail` finished, or the address has no account. Detail: `{ email }`. The same event either way.
294
- - `pwa-drawer-toggle` — the drawer open flag changed. Detail: `{ open }`
295
- - `pwa-settings` — Settings was chosen. Detail: `{ url }`. `url` is empty when the control stays on this page. Cancel the event to handle it yourself.
296
- - `pwa-auth-error` — an account action failed. Detail: `{ code, message }`
297
- - `pwa-verification-sent` — `sendEmailVerification` accepted the message. Detail: `{ email }`
298
- - `pwa-email-verified` — a reload saw `emailVerified` become true. Detail: `{ user }` with `user.emailVerified === true`
299
-
300
- `userEmailChanged` still fires on `window` with `{ email }`. Deprecated. Listen for `pwa-email-changed`.
71
+ Listen on `window`. `pwa-drawer-toggle` and `pwa-settings` also fire on `user-drawer`. Cancel `pwa-settings` to keep the drawer open. `userEmailChanged` is the old name for `pwa-email-changed`.
301
72
 
302
- ```javascript
303
- import { pwaAuthChanged, pwaDrawerToggleName } from 'pwa-auth';
73
+ A user is `{ uid, displayName, email, photoURL, emailVerified }` or `null`.
304
74
 
305
- window.addEventListener(pwaAuthChanged, (event) => {
306
- const user = event.detail.user;
307
- console.log(user && user.uid);
308
- });
75
+ | Event | Detail |
76
+ | --- | --- |
77
+ | `pwa-auth-changed` | `{ user }` on every sign-in change. `user` is `null` when signed out |
78
+ | `pwa-login` | `{ user }` |
79
+ | `pwa-logout` | `{ user: null }` |
80
+ | `pwa-signup` | `{ user }` |
81
+ | `pwa-account-deleted` | `{ uid }` |
82
+ | `pwa-profile-updated` | `{ uid, displayName, photoURL }` |
83
+ | `pwa-email-changed` | `{ email }` |
84
+ | `pwa-password-changed` | `{ uid }` |
85
+ | `pwa-reset-sent` | `{ email }`. Same event if no account uses that address |
86
+ | `pwa-verification-sent` | `{ email }` |
87
+ | `pwa-email-verified` | `{ user }` when the address becomes verified |
88
+ | `pwa-auth-error` | `{ code, message }` |
89
+ | `pwa-drawer-toggle` | `{ open }` |
90
+ | `pwa-settings` | `{ url }`. `url` is empty when Settings stays on this page |
91
+ | `userEmailChanged` | `{ email }`. Old name |
309
92
 
310
- window.addEventListener(pwaDrawerToggleName, (event) => {
311
- console.log(event.detail.open);
312
- });
313
- ```
93
+ `eventName` is those strings in one object. `PwaEventMap` pairs each name with its event.
314
94
 
315
- ## API
95
+ ## Functions
316
96
 
317
97
  ```javascript
318
- import {
319
- initialize,
320
- getCurrentUser,
321
- onUserChanged,
322
- sendVerification,
323
- isEmailVerified,
324
- openDrawer,
325
- closeDrawer,
326
- toggleDrawer,
327
- eventName
328
- } from 'pwa-auth';
329
-
330
- initialize({ config });
331
-
332
- const stop = onUserChanged((user) => {
333
- console.log(user && user.emailVerified);
334
- });
335
- stop();
336
-
337
- getCurrentUser();
338
- await sendVerification();
339
- await isEmailVerified();
340
- openDrawer();
341
- closeDrawer();
342
- toggleDrawer();
343
-
344
- window.addEventListener(eventName.login, (event) => {
345
- console.log(event.detail.user.email);
346
- });
347
- ```
348
-
349
- | Export | |
350
- |---|---|
351
- | `initialize({ app, config, actionCodeSettings })` | See [firebase.md](firebase.md). |
352
- | `getCurrentUser()` | `{ uid, displayName, email, photoURL, emailVerified }` or `null`. |
353
- | `onUserChanged(callback)` | Calls back with that same shape. Returns `unsubscribe`. |
354
- | `sendVerification()` | Sends the verification email for the signed-in user. Resolves `true` when Firebase accepts it. Fires `pwa-verification-sent` with `{ email }`. The constant is `pwaVerificationSent`, and `eventName.verificationSent` is the same string. |
355
- | `isEmailVerified()` | Reloads the signed-in user and resolves `emailVerified`. Fires `pwa-email-verified` when that flag becomes true. The constant is `pwaEmailVerified`, and `eventName.emailVerified` is the same string. |
356
- | `openDrawer()` | Opens the drawer. |
357
- | `closeDrawer()` | Closes the drawer. |
358
- | `toggleDrawer()` | Flips the drawer. |
359
- | `eventName` | The `pwa-` strings. `eventName.drawerToggle` is `pwa-drawer-toggle`. |
360
- | `pwaAuthChanged`, `pwaLogin`, `pwaLogout`, `pwaSignup`, `pwaAccountDeleted`, `pwaProfileUpdated`, `pwaEmailChanged`, `pwaPasswordChanged`, `pwaResetSent`, `pwaDrawerToggleName`, `pwaSettings`, `pwaAuthError` | The same strings, one constant each. `pwaDrawerToggleName` is the event. `pwaDrawerToggle()` is the older close function. `pwaSettings` is `pwa-settings`. |
361
-
362
- `import { store } from 'pwa-auth'` is not a public export. Use `getCurrentUser`, `onUserChanged`, and the events. Account fields stay inside the package.
363
-
364
- ## Exports
365
-
366
- ```javascript
367
- import 'pwa-auth';
368
-
369
- import {
370
- auth, db, storage, application, firebaseConfig, user
371
- } from 'pwa-auth';
372
-
373
- import {
374
- logOut, logAccount, logAccountDelete, deleteDocument, pwaDrawerToggle, reauthenticate
375
- } from 'pwa-auth';
376
- ```
377
-
378
- | Export | |
379
- |---|---|
380
- | `auth` | See [firebase.md](firebase.md). |
381
- | `db` | See [firebase.md](firebase.md). |
382
- | `storage` | See [firebase.md](firebase.md). |
383
- | `application` | See [firebase.md](firebase.md). |
384
- | `firebaseConfig` | See [firebase.md](firebase.md). |
385
- | `user` | Deprecated. Snapshot of `auth.currentUser` taken when `initialize` runs. It stays `null`. Read `getCurrentUser()` at call time. |
386
- | `logOut()` | `signOut(auth)`. Then `pwa-logout`. |
387
- | `logAccount()` | Analytics event `create_account`, after Analytics is ready. No event when Analytics is unsupported. |
388
- | `logAccountDelete()` | Analytics event `delete_account`. It does not delete the account. |
389
- | `deleteDocument(collect, item)` | Deletes one Firestore document. |
390
- | `pwaDrawerToggle()` | Closes the drawer. It does not toggle. Prefer `closeDrawer()`. |
391
- | `reauthenticate(password)` | Confirms the current password before email, password, and delete. Returns true when it succeeds. |
392
-
393
- `pwa-auth` and `pwa-auth/production` both resolve types to `base/export/pwa-auth.d.ts`. The production entry is the rollup bundle. `lit` and `firebase` are peer dependencies. Redux ships inside the package. `sideEffects` is true because the entry registers the elements. The published `files` list is `base/`, the production bundle, `source/pwa-styles.css`, `source/empty.jpg`, the readme, `intro.md`, `firebase.md`, and the licenses.
394
-
395
- ## Theme
396
-
397
- Optional. Link the sheet or set the variables on `:root`. Names below are the ones the components read.
398
-
399
- ```html
400
- <link rel="stylesheet" href="./path_to/pwa-styles.css">
401
- ```
402
-
403
- The published sheet is `node_modules/pwa-auth/source/pwa-styles.css`.
98
+ import { initialize, getCurrentUser, onUserChanged, openDrawer, closeDrawer } from 'pwa-auth';
99
+ ```
100
+
101
+ | Function | Returns |
102
+ | --- | --- |
103
+ | `initialize({ config, app, actionCodeSettings })` | The Firebase app. Pass `config`, or an `app` you already started. `actionCodeSettings` is the link in the verification email |
104
+ | `getCurrentUser()` | The user object, or `null` |
105
+ | `onUserChanged(fn)` | Calls `fn` with the user object. Returns a function that stops the calls |
106
+ | `openDrawer()` | Opens the drawer |
107
+ | `closeDrawer()` | Closes the drawer |
108
+ | `toggleDrawer()` | Opens it if shut, closes it if open |
109
+ | `sendVerification()` | `true` if the verification email went out, `false` if it was already verified |
110
+ | `isEmailVerified()` | `true` or `false` after a reload |
111
+ | `logOut()` | Signs out |
112
+ | `reauthenticate(password)` | `true` if that password matches the current account |
113
+ | `logAccount()` | Counts a new account, if Analytics is on |
114
+ | `logAccountDelete()` | Counts a deleted account, if Analytics is on |
115
+ | `deleteDocument(collection, id)` | Deletes that Firestore document |
116
+ | `pwaDrawerToggle()` | Closes the drawer |
117
+
118
+ Also exported: `firebaseConfig`, `application`, `db`, `storage`, `auth`. `user` is only a snapshot from startup. Use `getCurrentUser()`.
119
+
120
+ ## Look
121
+
122
+ Set these on the element. `--pwa_background` replaces the older background names `--pwa_drawer_background_color`, `--pwa_settings_background_color`, and `--section_background_color`.
123
+
124
+ | Variable | What it does | Default |
125
+ | --- | --- | --- |
126
+ | `--pwa_inset` | Space between the element's edge and its fields | `0` |
127
+ | `--pwa_max_width` | Widest the form gets. Centered | `400px` |
128
+ | `--pwa_slide` | Animation length. `0s` when the visitor prefers less motion | `2s` |
129
+ | `--pwa_background` | Background | white |
130
+ | `--pwa_input_background_color` | Field fill | white |
131
+ | `--pwa_drawer_text_color` | Text | `#1c2430` |
132
+ | `--pwa_label_text_color` | Labels | `#1c2430` |
133
+ | `--pwa_header_color` | Settings title | `#1c2430` |
134
+ | `--pwa_line_color` | Borders | `#e3daca` |
135
+ | `--pwa_nav_button_color` | Quiet text | `#4e5b6a` |
136
+ | `--pwa_nav_highlight_color` | Selected tab text | `#1c2430` |
137
+ | `--pwa_nav_on_background` | Selected tab and notice | `#f2f2f2` |
138
+ | `--pwa_action_text_color` | Button text | white |
139
+ | `--pwa_action_background_color` | Green buttons and links | `#2a6b45` |
140
+ | `--pwa_action_border_color` | Button border | `#214f34` |
141
+ | `--pwa_close_color` | Close mark and errors | `#9a3b32` |
142
+ | `--pwa_verified_color` | Verified check | the button green |
143
+ | `--pwa_tap` | Shortest a control can be | `44px` |
144
+ | `--pwa_icon_background_color` | Icon button | `#2a6b45` |
145
+ | `--pwa_icon_hover_color` | Icon button, pointer over it | `#214f34` |
146
+ | `--pwa_icon_border` | Icon button border | `0` |
147
+ | `--pwa_icon_height` | Signed-out button height | `44px` |
148
+ | `--pwa_icon_padding` | Signed-out button padding | `0 18px` |
149
+ | `--pwa_icon_radius` | Signed-out button corners | `10px` |
150
+ | `--pwa_icon_font` | Signed-out button font | `"Avenir Next", "Segoe UI", system-ui, sans-serif` |
151
+ | `--pwa_icon_diameter` | Signed-in button size | `44px` |
152
+ | `--pwa_drawer_position` | Drawer placement. `sticky` or `fixed` if you need that | `relative` |
153
+ | `--pwa_drawer_border` | Line under the drawer | `0` |
154
+ | `--pwa_drawer_z-index` | Drawer stacking | `3` |
155
+ | `--pwa_drawer_border-radius` | Drawer corners | `0 0 18px 18px` |
404
156
 
405
157
  ```css
406
- :root {
407
- /* Required - minimum tap target */
408
- --pwa_tap: 44px;
409
-
410
- /* <user-icon> */
411
- --pwa_icon_background_color: #2a6b45;
412
- --pwa_icon_hover_color: #214f34;
413
- --pwa_icon_border: 0;
414
- --pwa_icon_radius: 10px;
415
- --pwa_icon_padding: 0 18px;
416
- --pwa_icon_font: "Avenir Next", "Segoe UI", system-ui, sans-serif;
417
- --pwa_icon_height: 44px; /* logged out, sync to diameter */
418
- --pwa_icon_diameter: 44px; /* logged in, sync to height */
419
-
420
- /* <user-drawer> */
421
- --pwa_drawer_position: absolute;
422
- --pwa_drawer_background_color: #fffdf8;
423
- --pwa_drawer_text_color: #1c2430;
424
- --pwa_drawer_border: 0;
425
- --pwa_drawer_border-radius: 0 0 18px 18px;
426
- --pwa_drawer_z-index: 3;
427
- --pwa_close_color: #9a3b32;
428
-
429
- /* <user-settings> and <user-login> */
430
- --pwa_settings_background_color: #fffdf8;
431
- --section_background_color: #fffdf8;
432
- --pwa_header_color: #1c2430;
433
- --pwa_nav_button_color: #4e5b6a;
434
- --pwa_nav_highlight_color: #1c2430;
435
- --pwa_nav_on_background: #f3efe6;
436
- --pwa_divider_color: #e3daca;
437
- --pwa_line_color: #e3daca;
438
- --pwa_label_text_color: #1c2430;
439
- --pwa_input_background_color: #f3efe6;
440
- --pwa_action_text_color: #fff;
441
- --pwa_action_background_color: #2a6b45;
442
- --pwa_action_border_color: #214f34;
443
-
444
- /* Email verified check */
445
- --pwa_verified_color: #2a6b45;
158
+ user-drawer, user-login, user-settings, email-reset {
159
+ --pwa_inset: 16px;
160
+ --pwa_max_width: 400px;
446
161
  }
447
162
  ```
448
163
 
449
- `--pwa_tap` is the minimum size of the drawer close control, the sign-in and sign-up buttons, the settings tabs, and the delete control.
450
-
451
- ## Parts
452
-
453
- Hosts style the controls with `::part`. Nested fields are forwarded with `exportparts`, so the host does not enter a shadow root.
454
-
455
- - `user-icon`: `button`, `photo`, `initials`
456
- - `user-drawer`: `panel`, `header`, `title`, `close`, `settings`, `notice`, `verified`, `unverified`, `verify-submit`, `verify-status`, `logout`, `login-google`, `signup-google`, `login-email`, `login-password`, `login-submit`, `login-switch`, `login-forgot`, `login-status`, `login-reveal`, `signup-email`, `signup-password`, `signup-submit`, `signup-switch`, `signup-status`, `signup-reveal`, `signup-notice`
457
- - `user-login`: `panel`, `header`, `title`, `notice`, `login-google`, `signup-google`, and the same `login-*` and `signup-*` field parts
458
- - `user-settings`: `tab`, `panel`, `signed-out`, `name`, `name-submit`, `email`, `email-submit`, `verified`, `unverified`, `verify-submit`, `verify-status`, `password`, `verify`, `password-submit`, `progress`, `file`, `preview`, `delete`
459
- - `email-reset`: `email`, `submit`, `status`, `back`
460
-
461
- ```css
462
- user-icon::part(button) { border-radius: 8px; }
463
- user-drawer::part(panel) { background: #fff; }
464
- user-drawer::part(login-submit) { letter-spacing: 0.02em; }
465
- ```
466
-
467
- ## Drawer behaviour
468
-
469
- The drawer loads hidden at the top (`max-height: 0`). A press on `user-icon` slides it down.
470
-
471
- Sign-in and sign-up share one grid area, `pages`. They slide past each other. The closed form is translated `translate3d(0, -100%, 0)`, `visibility: hidden`, and `inert`.
472
-
473
- The slide is shared. See [Slides](docs/sliders.md). Max-height is `1.4s` `ease-in-out`. Transform times stay `1.5s`, `2.2s`, and `2s`. `prefers-reduced-motion: reduce` sets those durations to `0s`.
474
-
475
- While the drawer is open it covers `user-icon`. Close it with the ✕ button or Escape. The drawer is a dialog. Tab stays inside while it is open, and focus returns to the control that opened it. Off-screen forms are `inert`. The panel is `inert` while it is closed.
476
-
477
- Slotted links can flash before the element upgrades. Hide them:
478
-
479
- ```css
480
- /* Optional - hide slotted links until user-drawer upgrades */
481
- user-drawer:not(:defined) { display: none; }
482
- ```
483
-
484
- ## Data ownership
485
-
486
- The host app owns its Firestore documents. Contractors Centre creates `users/{uid}` on signup and deletes that document when it hears `pwa-account-deleted`.
164
+ The drawer unrolls downward and its buttons ride the bottom edge. Nothing animates on page load. Less motion makes that instant. [The roll](docs/drawer-slide.md).
487
165
 
488
- Sign-up calls `sendEmailVerification` and fires `pwa-verification-sent` with `{ email }`. Sign-in still succeeds when `emailVerified` is false. pwa-auth does not block an unverified account. The host, including Contractors Centre, decides whether a feature needs a verified email. Read `emailVerified` from `getCurrentUser()`, `onUserChanged`, and `pwa-auth-changed`. Call `isEmailVerified()` to reload. When that reload sees the address become verified, the page fires `pwa-email-verified`.
489
-
490
- pwa-auth does not write `users/{uid}`. Account deletion removes this user's Storage files under `pwa-auth/{uid}`, calls `logAccountDelete`, deletes the Auth user, and fires `pwa-account-deleted` with `{ uid }`.
491
-
492
- `deleteDocument(collect, item)` is still exported. The host can call it. The package does not call it for `users/{uid}`.
493
-
494
- ## Contributing
495
-
496
- ### Project layout
497
-
498
- Edit `typescript/` only. That folder is the source.
499
-
500
- `npm run build` runs tsc. The emit lands in `base/`. `base/export/pwa-auth.js` is the default package entry. Do not hand-edit `base/`.
501
-
502
- Rollup reads that emit. `npm run rollup` writes `source/pwa-auth.js` (the npm production bundle) and `website/javascript/pwa-auth.js` (the site bundle). Do not hand-edit those files.
503
-
504
- `demonstration/` is the dev demo. It imports `../base/export/pwa-auth.js`. `npm run demo` serves `demonstration/index.html`.
505
-
506
- `website/` is the hosted site at [pwa-authentic.firebaseapp.com](https://pwa-authentic.firebaseapp.com). It loads `website/javascript/pwa-auth.js`. `npm run website` serves `website/index.html`.
166
+ ## Firebase
507
167
 
508
- Retired code lives in `typescript/deprecated/`. It is not called.
168
+ Turn on Email/Password. Turn on Google if that button stays. Photos go to Storage at `pwa-auth/{uid}/`. Let the signed-in person read and write that folder. The elements do not write Firestore.
509
169
 
510
- ### Build & test
170
+ 1. `initialize()` is the one to use.
511
171
 
512
- ```bash
513
- npm run build # tsc writes base/, then restores @deprecated notes tsc drops
514
- npm run rollup # writes source/pwa-auth.js and website/javascript/pwa-auth.js
515
- npm run demo # serves demonstration/index.html
516
- npm run website # serves website/index.html
517
- npm test # vitest
172
+ ```javascript
173
+ import { initialize } from 'pwa-auth';
174
+
175
+ initialize({
176
+ config: {
177
+ apiKey: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
178
+ authDomain: 'xxxxxxx.xxxxxxx.xxx',
179
+ projectId: 'xxxxxxx',
180
+ storageBucket: 'xxxxxxx.xxxxxxx.xxx',
181
+ messagingSenderId: 'xxxxxxxxxxx',
182
+ appId: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
183
+ }
184
+ });
518
185
  ```
519
186
 
520
- Auth, Firestore, and Storage emulators are in [firebase.md](firebase.md).
521
-
522
- A pull request runs `.github/workflows/ci.yml`: `npm ci`, `npm run build`, `npm run rollup`, `npm test`.
523
-
524
- ### Publish
525
-
526
- `npm publish` runs `prepublishOnly`, which is `npm run build` then `npm run rollup`. The action runs those two commands on their own as well, so the log shows them. No `NPM_TOKEN`.
527
-
528
- One-time setup on npmjs.com. Package settings, Trusted Publisher, GitHub Actions. Organization or user: `busynest`. Repository: `user`. Workflow filename: `publish.yml`. Leave the environment name empty. Allow direct `npm publish`. A trusted publisher created now only stages unless you allow publish. Merge `publish.yml` to `master` first. npm drops a publisher that has not published within two days.
187
+ 2. Or put that same JSON in `firebase-config` on `user-icon`, `user-drawer`, `user-login`, or `user-settings`.
529
188
 
530
- Release. Bump `version` in `package.json`. Tag that version (`v3.5.1` or `3.5.1`). Publish a GitHub release for the tag. The published release starts `.github/workflows/publish.yml`. The tag, without a leading `v`, must match `package.json`. The action runs `npm ci`, `npm run build`, `npm run rollup`, `npm test`, then `npm publish --provenance --access public`. A version already on npm is skipped. `workflow_dispatch` skips the tag check.
189
+ 3. Or set `window.process.env.FIREBASE_CONFIG` to that JSON string before pwa-auth loads. If `window.process` is already there, add the value on it.
531
190
 
532
- `3.5.0` is staged from a CLI stage-only token. It is not live. Promote it on npm, or discard it and let this workflow publish `3.5.0`.
191
+ Use one of these. Once Firebase is connected, another one leaves it as it is.
533
192
 
534
- ## Feedback
193
+ ## License
535
194
 
536
- * [Jack's Publishing](https://www.jackspublishing.com)
537
- * [contractor's centre](https://www.contractorscentre.com)
538
- * [npm](https://www.npmjs.com/package/pwa-auth)
539
- * [Sponsor Jacek Markiewicz](https://github.com/sponsors/busynest)
540
- * [Issues](https://github.com/busynest/user/issues)
195
+ MIT. See [license](license). Third-party notices are in [LICENSES.txt](LICENSES.txt).