@ouroboros/brain-mui

Material-UI Components for interacting with the brain2_oc service. It uses @ouroboros/brain and @ouroboros/brain-react to handle the actual connections.

See Releases for changes from release to release.

Installation

foo@bar:~$ npm install @ouroboros/brain-mui

Using brain-mui

If you're using react with material-ui, this library provides components for searching and creating users, assigning permissions to different portals, and for the forgot password, setup, and email verification landing pages. It also provides sign in and account details dialogs.

Components

• AccountDialog
• ForgotPage
• SetupPage
• SignInDialog
• UserCreate
• UserSearch
• UsersPage
• VerificationPage
• TypeScript

AccountDialog

AccountDialog contains three forms allowing the currently signed in user to change password, change email, and change other details. It uses MUI Dialog to show the forms.

import { AccountDialog } from '@ouroboros/brain-mui';
import React, { useState } from 'react';
import { addError, addMessage } from 'your_module';
function MyComponent(props) {
  const [ acc, setAcc ] = useState(false);
  return <div>
    <button onClick={() => setAcc(true)}>My Account</button>
    {acc &&
      <AccountDialog
        onClose={() => setAcc(false)}
        onDetailsChanged={user => addMessage('Details changed!')}
        onEmailChanged={email => addMessage('E-Mail Address changed!')}
        onError={addError}
        onPasswdChanged={() => addMessage('Password changed!')}
        verificationUrl="https://mydomain.com/verify/{key}"
      />
    }
  </div>;
}

| Prop | Type | Optional | Description | | ---- | ---- | -------- | ----------- | | onClose | () => void | no | Callback for when the dialog is closed. | | onDetailsChanged | user => void | yes | Callback for when the user changes their details. user is an object with just the fields that changed. | | onEmailChanged | email => void | yes | Callback for when the user changes their email. email is a string. | | onError | error => void | yes | Callback for when an error occurs. error is a responseErrorStruct from @ouroboros/body. | | onPasswdChanged | () => void | yes | Callback for when the user changes their password. | | verificationUrl | string | no | The URL to send by email for the user to verify their e-mail address. Must contain the string "{key}" as a placeholder for the actual key. |

[ components ]

ForgotPage

ForgotPage is used in handling a request for a password change via a keyed url.

import { ForgotPage } from '@ouroboros/brain-mui';
import React from 'react';
import { useParams } from 'react-router-dom';
import { addMessage } from 'your_module';
function MyForgotPage(props) {
  const { key } = useParams();
  return <ForgotPage
    forgotKey={key}
    onSuccess={() => addMessage('Password reset!')}
  />
}

| Prop | Type | Optional | Description | | ---- | ---- | -------- | ----------- | | forgotKey | string | no | The forgot password key sent by email to verify the user and allow them to reset their password. | | onSuccess | () => void | yes | Callback for when the user successfully sets a new password. |

[ components ]

SetupPage

SetupPage is used in handling a request to continue setting up a new account via a keyed url.

import { SetupPage } from '@ouroboros/brain-mui';
import React from 'react';
import { useParams } from 'react-router-dom';
import { addMessage } from 'your_module';
function MySetupPage(props) {
  const { key } = useParams();
  return <SetupPage
    setupKey={key}
    onSuccess={() => addMessage('Setup complete!')}
  />
}

| Prop | Type | Optional | Description | | ---- | ---- | -------- | ----------- | | setupKey | string | no | The setup key sent by email to verify the user and allow them to set a password and update any details to complete their account setup. | | onSuccess | () => void | yes | Callback for when the user successfully finishes setting up their account. |

[ components ]

SignInDialog

SignInDialog shows a form with email and password for the user to sign in. It defaults to the "" (empty string) portal, which is generally used as the admin portal. It uses MUI Dialog to show the form.

SignInDialog uses signup from @ouroboros/brain-react which allows you to use the useUser hook, as well as the other hooks provided by brain-react.

import { SignInDialog } from '@ouroboros/brain-mui';
import { useUser } from '@ouroboros/brain-react';
import React from 'react';
import { addError, addMessage } from 'your_module';
function MyApp(props) {
  const user = useUser();
  return (
    <div>
      <h1>MyDomain</h1>
      {user === false ?
        <SignInDialog
          forgotUrl="https://mydomain.com/forgot/{key}"
          onError={addError}
          onForgot={() => {
            addMessage('Your forgot password request has been sent!');
          }}
          onSignIn={signin => {
            localStorage.setItem('session', signin.session);
            addMessage(`Welcome ${signin.user.first_name}!`);
          }}
        /> :
        <div>Members only content.</div>
      }
    <div>
  );
}

| Prop | Type | Optional | Description | | ---- | ---- | -------- | ----------- | | forgotUrl | string | no | The URL to send by email for a user who forgot their password. Must contain the string "{key}" as a placeholder for the actual key. | | onError | error => void | yes | Callback for when an error occurs. error is a responseErrorStruct from @ouroboros/body. | | onForgot | () => void | yes | Callback for when the use has initiated the forgot password process. | | onSignIn | signin => void | yes | Callback for when the user successfully signs in. signin is a signinReturn from @ouroboros/brain-react. |

[ components ]

UserCreate

UserCreate is a stand alone component which provides a form to create a new user in the system. It's loaded by UsersPage, but you could also load it to provide this functionality anywhere.

import { UserCreate } from '@ouroboros/brain-mui';
import React, { useState } from 'react';
import { addError, addMessage } from 'your_module';
function MyComponent(props) {
  const [ create, setCreate ] = useState(false);
  const [ records, setRecords ] = useState([ /* user records */ ]);
  return <div>
    <button onClick={() => setCreate(true)}>Add User</button>
    {create &&
      <UserCreate
        onError={addError}
        onCancel={() => setCreate(false)}
        onSuccess={user => {
          addMessage('New user created!');
          setRecords(l => [ ...l, user ])
        }}
        setupUrl="https://mydomain.com/setup/{key}"
      />
    }
    {records.map(o =>
      /* do something with record */
    )}
  <div>
}

| Prop | Type | Optional | Description | | ---- | ---- | -------- | ----------- | | onError | error => void | yes | Callback for when an error occurs. error is a responseErrorStruct from @ouroboros/body. | | onCancel | () => void | yes | Callback for when the user clicks the cancel button. | | onSuccess | user => void | yes | Callback for when a new user is created. | | setupUrl | string | no | The URL to send by email to the new user for them to complete the setup for their account. Must contain the string "{key}" as a placeholder for the actual key. |

[ components ]

UserSearch

UserSearch is a stand alone component which provides a form to search for existing users in the system. It's loaded by UsersPage, but you could also load it to provide this functionality anywhere.

import { UserSearch } from '@ouroboros/brain-mui';
import React, { useState } from 'react';
import { addError } from 'your_module';
function MyComponent(props) {
  const [ records, setRecords ] = useState(false);
  return <div>
    <UserSearch
      onError={addError}
      onSuccess={setRecords}
    />
    {records && records.length && records.map(o =>
      /* do something with record */
    )}
  <div>
}

| Prop | Type | Optional | Description | | ---- | ---- | -------- | ----------- | | onError | error => void | yes | Callback for when an error occurs. error is a responseErrorStruct from @ouroboros/body. | | onSuccess | records => void | yes | Callback for after the search is run. records is an array of user objects. |

[ components ]

UsersPage

UsersPage is an all in one page to create new users, search existing users, and then from the result, edit the user's details, change their password, and manage their permissions.

import { UsersPage } from '@ouroboros/brain-mui';
import { RIGHTS } from '@ouroboros/brain';
import React from 'react';
import { useParams } from 'react-router-dom';
import { addError, addMessage } from 'your_module';
const portals = {
  '': {
    title: 'Admin',
    permissions: [ {
      title: 'Authorization',
      rights: [ {
        name: 'brain_user',
        title: 'Users',
        allowed: RIGHTS.CREATE | RIGHTS.READ | RIGHTS.UPDATE
      }, {
        name: 'brain_permission',
        title: 'Permissions',
        allowed: RIGHTS.READ | RIGHTS.UPDATE
      } ]
    } ]
  },
  'my_app': {
    title: 'My App',
    permissions: [ {
      title: 'My Service Group',
      rights: [ {
        name: 'my_service_permission',
        title: 'My Service Permission',
        allowed: RIGHTS.ALL
      } ]
    }, {
      title: 'My Other Group',
      rights: [ {
        name: 'my_other_permission',
        title: 'My Other Permission',
        allowed: RIGHTS.READ
      } ]
    } ]
  }
}
function MyUsersPage(props) {
  const { key } = useParams();
  return <UsersPage
    onError={addError}
    onSuccess={(type, user) => {
	  /* type includes [
        'password', 'permissions', 'setup_sent',
        'setup_done', 'update'
      ] */
      addMessage(
        type === 'update' ?
          `Updated details for ${user._id}` :
          `${type} updated`
      )
    }}
    portals={portals}
  />
}

| Prop | Type | Optional | Description | | ---- | ---- | -------- | ----------- | | onError | error => void | yes | Callback for when an error occurs. error is a responseErrorStruct from @ouroboros/body. | | onSuccess | (type, user) => void | yes | Callback for when any of the following types happen: 'password', 'permissions', 'setup_sent', 'setup_done', and 'update'. user is not set unless type is 'update', in which case it contains an object with data that has changed. | | portals | object | yes | portals is an object with portal names for keys, and further objects with title and permissions, an array of sections to show in the UI for the portal. Each section consists of an object with title and rights, another array of objects with name (the actual permission string), title (what the user sees), and allowed (RIGHTS). |

[ components ]

VerificationPage

VerificationPage is used in handling a request to verify a user's new email, after having changed it, via a keyed url.

import { VerificationPage } from '@ouroboros/brain-mui';
import React from 'react';
import { useParams } from 'react-router-dom';
import { addMessage } from 'your_module';
function MyVerificationPage(props) {
  const { key } = useParams();
  return <VerificationPage
    onSuccess={() => addMessage('Setup complete!')}
    verificationKey={key}
  />
}

| Prop | Type | Optional | Description | | ---- | ---- | -------- | ----------- | | onSuccess | () => void | yes | Callback for when the user successfully verifies their changed email address. | | verificationKey | string | no | The verification key sent by email to verify the user. |

[ components ]

TypeScript

ouroboros/brain-mui exports the following types representing the props of each of the above components.

import type {
  AccountDialogProps,
  ForgotPageProps,
  SetupPageProps,
  SignInDialogProps,
  UserCreateProps,
  UserSearchProps,
  UsersPageProps,
  VerificationPageProps
} from '@ouroboros/brain-mui';

[ components ]