Authentication documentation for useAuth hook on web side needs improvement

[dthyresson]

After a discussion on Discord about how to fetch the currently logged in user and their profile on the web side, I realized that while some of the useAuth hook is documented in the Authentication section and some in the RBAC cookbook, it is not easy to understand and there are no code examples to quickly realize how to the the hook.

See https://redwoodjs.com/docs/authentication#api which is mostly the provider api interface, but within it are the items helpful on the web side:

Need to document hook use and how can get and use:

• isAuthenticated
• hasRole
• currentUser
• userMetadata (and how that differs from currentUser)
• client (to use if need to access the third party auth api directly)

For example from RBAC cookbook, but needs s simpler example:

import { useAuth } from "@redwoodjs/auth";
import SidebarLayout from "src/layouts/SidebarLayout";

const SettingsPage = () => {
  const { isAuthenticated, userMetadata, hasRole } = useAuth();

  return (
    {isAuthenticated && (
      <div className="ml-4 flex-shrink-0">
        {hasRole("admin") && (
          <a
            href={`https://app.netlify.com/sites/${process.env.SITE_NAME}/identity/${userMetadata.id}`}
            target="_blank"
            rel="noreferrer"
          >
            Edit on Netlify
          </a>
        )}
      </div>
    )}
  )}
}