(DOCSP-33534) Add authentication hooks to React Native docs #3037

krollins-mdb · 2023-10-02T18:48:27Z

Pull Request Info

This is a somewhat large PR, but don't let the lines changed intimidate you: that's mostly from the auto-generated package-lock.json file.

I only address some of the needed auth changes in this PR. I created a small Jira epic to track the other work.

Major changes:

New test files
- Link identities
- Anonymous login
- Email/pass login
Content pages
- Authenticate users
- Manage email/password users
- Link user identities

The test suite has an issue with randomly aborting. I have a Jira ticket to track fixing it.

Jira

https://jira.mongodb.org/browse/DOCSP-33534

Staged Changes

Much of the content and examples for the new hook reference tables comes from Andrew Meyer's additions to the Realm.js repo.

Authenticate Users
- Revamped these sections: Configure User Authentication in Client, Anonymous User, and Email/Password User.
- New reference table for useAuth.
Manage Email/Password Users
- Lots of updates to the examples and content throughout this page.
- New reference table for useEmailPasswordAuth.
Link User Identities
- New procedure with updated examples.
- Trying a new thing where I break a whole React Native component into a procedure. The idea here is to give devs an idea of what a user management component could look like.

Review Guidelines

REVIEWING.md

Animal Wearing a Hat

github-actions · 2023-10-02T18:49:41Z

Readability for Commit Hash: 7aa2f64

You can see any previous Readability scores (if they exist) by looking
at the comment's history.

Readability scores for changed documents:

source/sdk/react-native/manage-users/authenticate-users: Grade Level: 9.0, Reading Ease: 51.24
source/sdk/react-native/manage-users/manage-email-password-users: Grade Level: 9.2, Reading Ease: 50.84
source/sdk/react-native/manage-users/link-user-identities: Grade Level: 6.6, Reading Ease: 62.95

For Grade Level, aim for 8 or below.

For Reading Ease scores, aim for 60 or above:

Score	Difficulty
90-100	Very Easy
80-89	Easy
70-79	Fairly Easy
60-69	Medium
50-59	Fairly Hard
30-49	Hard
0-29	Very Hard

For help improving readability, try Hemingway App.

- Make LinkCredentials more idiomatic

- Add password reset example and test

- Change bluhawk script input directory - Test hook reference table

- Generate new snippets

- Update authenticate users page - Update link users page

takameyer

Great work here, but I have some requests that should be addressed before this goes live.

takameyer · 2023-10-16T06:51:38Z

source/sdk/react-native/manage-users/authenticate-users.txt

+#. In the component passed to the ``UserProvider.fallback`` prop, authenticate a
+   user with the ``useEmailPasswordAuth()`` hook.
+   This example uses email/password authentication, but you could use any of the
+   ``useAuth`` methods.


The following example is not showing usage of the useEmailPasswordAuth hook.

Thank you for noticing! I meant to alter this step and forgot to.

takameyer · 2023-10-16T06:53:42Z

source/sdk/react-native/manage-users/authenticate-users.txt

+#. Call ``logInWithAnonymous()`` without any arguments.
+#. Handle the ``result``.
+
+.. include:: /examples/generated/react-native/v12/LoginWithAnonymous.snippet.login-anonymous.tsx.rst


For these login examples, I think it may be worthwhile to wrap them in a functional component, just to make sure it's clear this is happening within a react component (should be obvious, but you never know).

takameyer · 2023-10-16T06:54:58Z

source/sdk/react-native/manage-users/authenticate-users.txt


+.. include:: /examples/generated/react-native/v12/LoginWithEmail.snippet.email-password-login.tsx.rst

 .. _react-native-api-key-login:
 .. _react-native-login-api-key:


There are hooks available for the following login strategies. Should we also show this?

I will! But this PR kept growing, so I wanted to break things up a bit. I created a small Jira epic to track the rest of the work: https://jira.mongodb.org/browse/DOCSP-27838

Part of why this is so much work is that we're currently pulling examples from the Node.js test suite. And those examples are old and weren't well put together to begin with. So, gotta write new components.

takameyer · 2023-10-16T06:58:05Z

source/sdk/react-native/manage-users/authenticate-users.txt

+
+.. _react-native-auth-hook:
+
+useAuth Hook


Really digging this table. Great reference

I do, however, think we should have an explanation about the "operation enum". Since nothing is awaitable, it's necessary to use the operation to determine which auth method is currently being processed.
Also it may be good to show the possible string values for operation, just in case someone has the gall to use plain JS instead of TypeScript.

Great points about the enum. I'll update!

+1 on the table!

takameyer · 2023-10-16T06:59:29Z

source/sdk/react-native/manage-users/manage-email-password-users.txt


-.. tabs-realm-languages::
+.. include:: /examples/generated/react-native/v12/RealmWrapper.snippet.configure-user-provider.tsx.rst


Same comment as above for useAuth. Perhaps if all the auth examples were wrapped in a Login component to show that this is what is being rendered in the fallback. We could simply say, the Login fallback examples are listed further down the document.

takameyer · 2023-10-16T07:00:37Z

source/sdk/react-native/manage-users/manage-email-password-users.txt

+#. Pass the user's email and password to ``register()`` as an object.
+#. Confirm the user's email address.
+
+.. include:: /examples/generated/react-native/v12/LoginWithEmail.snippet.email-password-register.tsx.rst


Should we also get the result in this example?

Since register is not yet "awaitable", perhaps showing this flow would be helpful:
https://github.com/realm/realm-js/blob/main/examples/rn-todo-list/frontend/app/screens/LoginScreen.tsx#L50-L54

Yep. Good catch!

takameyer · 2023-10-16T07:20:11Z

source/sdk/react-native/manage-users/manage-email-password-users.txt

-Calling the function in this example performs the entire password reset process.
+.. _react-native-email-pass-hook:
+
+useEmailPasswordAuth Hook


result should also be added here.

takameyer · 2023-10-16T07:21:07Z

source/sdk/react-native/manage-users/link-user-identities.txt

+   .. step:: Create UI and Link Identities
+
+         The following example renders the user ID for each identity associated
+         with the app's current user. Initially, only the anonymou user


Suggested change

with the app's current user. Initially, only the anonymou user

with the app's current user. Initially, only the anonymous user

takameyer · 2023-10-16T07:23:37Z

source/sdk/react-native/manage-users/link-user-identities.txt

+         identity renders, but you can create an email/password identity and
+         link it to the anonymous user.
+
+         .. include:: /examples/generated/react-native/v12/LinkIdentities.snippet.user-identities.tsx.rst


Upon reading this example, it occurred to me that we should probably have a linkCredentials method returned from useAuth.

That would be helpful, for sure!

- Add user auth errors section - Regenerate updated snippets

Andrew

cbullinger

overall LGTM -- a few typos and non-blocking suggestions

source/sdk/react-native/manage-users/authenticate-users.txt

cbullinger · 2023-10-17T14:56:40Z

source/sdk/react-native/manage-users/authenticate-users.txt


-.. literalinclude:: /examples/generated/node/authenticate.snippet.email-password-login.js
-   :language: javascript
+#. Destructure ``logIn`` and ``result`` from the ``useEmailPasswordAuth`` hook.


I know you mention it at the top of the page, but do we want to link out to the useEmailPasswordAuth hook table here too?

I've been trying to avoid links in procedure steps. Probably makes sense to include a mention of useEmailPasswordAuth in the intro and link to it. What do you think?

Yep, that makes sense! 👍

cbullinger · 2023-10-17T14:57:18Z

source/sdk/react-native/manage-users/authenticate-users.txt

+
+.. _react-native-auth-hook:
+
+useAuth Hook


+1 on the table!

cbullinger · 2023-10-17T15:04:10Z

source/sdk/react-native/manage-users/authenticate-users.txt

+#. Handle ``result``. If the authentication operation doesn't succeed, you can
+   write error handling based on ``result``.
+
+.. include:: /examples/generated/react-native/v12/Login.snippet.user-provider-fallback.tsx.rst

 User Sessions


Since there are so many H2s on this page, would it help to nest all of the auth methods as H3s under an "Authenticate Users" (or something) parent heading? to better visually group them and separate from the other headings?

I'll experiment! I was wondering the same thing at some point, but didn't get around to it.

examples/react-native/v12/TestApp/src/components/authentication/login/LoginWithEmail.tsx

examples/react-native/v12/TestApp/src/components/authentication/login/RealmWrapper.tsx

source/sdk/react-native/manage-users/manage-email-password-users.txt

cbullinger · 2023-10-17T16:00:36Z

source/sdk/react-native/manage-users/manage-email-password-users.txt

-application can call :js-sdk:`EmailPasswordAuth.resetPassword()
-<Realm.Auth.EmailPasswordAuth.html#resetPassword>` to complete the password 
-reset flow.
+application can use the :realm-react-sdk:`useEmailPasswordAuth hook 


I think this mostly applies to the Authenticate Users page, but it seemed like we weren't linking out to the API ref much/at all when referring to the useAuth and useUser hooks

Co-authored-by: cbullinger <[email protected]>

- Updated link identities sample - Figuring out new babel bug

takameyer

LGTM

takameyer · 2023-10-18T08:17:49Z

examples/react-native/v12/TestApp/src/components/authentication/login/LoginWithAnonymous.tsx

+      onPress={() => {
+        performAnonymousLogin();
+      }}


Suggested change

onPress={() => {

performAnonymousLogin();

}}

onPress={logInWithAnonymous}

This could be simplified.

Yeah, I've been omitting the UI bits of of components for the auth stuff. Bluehawk removes everything between :remove-start: and :remove-end: so that we get samples like what's on the page: https://preview-mongodbkrollinsmdb.gatsbyjs.io/realm/DOCSP-27838/sdk/react-native/manage-users/authenticate-users/#anonymous-user

In this case, we could probably include the UI, as there's not much. But in other cases, the UI can be a lot and isn't really what we're focusing on. I think I'll keep this one as-is so it's consistent with the other examples.

I'd be happy to hear your thoughts on the balance between concise examples and "complete" examples though!

I guess this urge to comment spawned on this block:

const performAnonymousLogin = () => { logInWithAnonymous(); };

One could simply provide logInWithAnonymous without wrapping it in a function.

Oh. Yeah, that's a great point. ha! Thank you. I'll update other spots in the code that follow this pattern. Not sure why I got so wrapper happy.

I think I initially misunderstood what you meant. Thank you for clarifying!

docs-builder-bot · 2023-10-19T20:45:36Z

✨ Staging URL: https://preview-mongodbmongodb.gatsbyjs.io/realm/master/

🪵 Logs

job log: 2e7a3ee6a692a1b7eda02088dd4b4c41277ae721

krollins-mdb added 2 commits September 29, 2023 21:10

Establish component bases

972764f

Add email/password example

7d0c328

krollins-mdb added 14 commits October 2, 2023 14:08

Add basic table for useEmailPasswordAuth

afe46c3

Add login and register example for email/pass

89401bb

Merge branch 'master' into DOCSP-27838

41e9089

Get link identities component and test workign

b7c0cb3

- Update realm and realm/react deps

5e80426

- Make LinkCredentials more idiomatic

- Refactor to use result

23d6e55

- Add password reset example and test

- Generate samples

3a68ae4

- Change bluhawk script input directory - Test hook reference table

Try code-block

d032cb6

Actually add directive

0ef8a95

Try 2 columns

e72727b

Add remaining hook method examples

9ba558c

Lots of content updates

b72a524

- Add reset password example

2defb1e

- Generate new snippets

Content clean up

4622717

krollins-mdb changed the title ~~(DOCSP-27838) Add authentication hooks to React Native docs~~ (DOCSP-33534) Add authentication hooks to React Native docs Oct 11, 2023

krollins-mdb added 6 commits October 11, 2023 09:45

Merge branch 'master' into DOCSP-27838

2238a26

A bit more content clean up

18d1d76

Fix typo

eb3e8b5

- Generate updated snippets

78038eb

- Update authenticate users page - Update link users page

Link identities updates

f19519f

Add useAuth reference table

06336cf

krollins-mdb marked this pull request as ready for review October 11, 2023 19:18

krollins-mdb requested review from takameyer and removed request for takameyer October 11, 2023 19:18

krollins-mdb added 2 commits October 11, 2023 14:28

Update configure user auth section

69e2be6

Add missing back ticks

d4b4995

krollins-mdb requested a review from takameyer October 12, 2023 15:07

Merge branch 'mongodb:master' into DOCSP-27838

d0b2e17

takameyer suggested changes Oct 16, 2023

View reviewed changes

krollins-mdb added 7 commits October 16, 2023 14:24

- Add fallback component section

a2cc38f

- Add user auth errors section - Regenerate updated snippets

Regenerate snippets

4380cc2

Minor updates

a3f4172

Remove examples from ordered list

0a10ace

Revert unintended changes

f9f43e6

Update inline code blocks

3aa3df7

Implement more feedback from

980fccb

Andrew

krollins-mdb requested a review from takameyer October 17, 2023 13:48

Merge branch 'master' into DOCSP-27838

6d78eb6

cbullinger approved these changes Oct 17, 2023

View reviewed changes

krollins-mdb and others added 3 commits October 17, 2023 12:49

Apply suggestions from code review

8df9e9d

Co-authored-by: cbullinger <[email protected]>

Implement Cory's feedback

a6b441c

- eslint and prettier config to one prop per line

835965f

- Updated link identities sample - Figuring out new babel bug

takameyer approved these changes Oct 18, 2023

View reviewed changes

Simplify anonymous sample

7aa2f64

krollins-mdb merged commit 2e7a3ee into mongodb:master Oct 19, 2023
5 of 6 checks passed

krollins-mdb deleted the DOCSP-27838 branch October 19, 2023 20:42


		.. tabs-realm-languages::
		.. include:: /examples/generated/react-native/v12/RealmWrapper.snippet.configure-user-provider.tsx.rst

	with the app's current user. Initially, only the anonymou user
	with the app's current user. Initially, only the anonymous user

(DOCSP-33534) Add authentication hooks to React Native docs #3037

(DOCSP-33534) Add authentication hooks to React Native docs #3037

Conversation

krollins-mdb commented Oct 2, 2023 • edited Loading

Pull Request Info

Jira

Staged Changes

Review Guidelines

Animal Wearing a Hat

github-actions bot commented Oct 2, 2023 • edited Loading

takameyer left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cbullinger left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

takameyer left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

docs-builder-bot commented Oct 19, 2023

🪵 Logs

krollins-mdb commented Oct 2, 2023 •

edited

Loading

github-actions bot commented Oct 2, 2023 •

edited

Loading