@ouroboros/brain-mui v2.3.4

@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>;
}

[ 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!')}
  />
}

[ 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!')}
  />
}

[ 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>
  );
}

[ 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>
}

[ 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>
}

[ 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}
  />
}

[ 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}
  />
}

[ 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 ]