@vista.io/react-vista-js/README.md

NodeJS implementation of the Vista API.

# Vista-powered React Components

Vista has React components that streamline adding permissions to your platform:

* VistaCheck: dynamically adjusts UI based on permissions checks
* VistaGrant: 'control panel' that allows your admins to grant teammates roles (can be scoped by orgId). This component can be styled to your needs.
* VistaRoles: Component that shows list of Roles (can be scoped by orgId). This component can be styled to your needs.


## Reference

- [Vista API Documentation](https://docs.govista.io/Guides/React%20Components/Intro)

## Installation

1. You'll need to use the read token generated by our API, see the [Vista API Documentation](https://docs.govista.io/api/).

2. Install the package:

```
npm install @vista.io/react-vista-js @emotion/react @emotion/styled
```

## VistaCheck Component

The `VistaCheck` component dynamically hides child components if the current user does not have the specified permissions. You can optionally render an alternate component if access is denied.

```js
import { VistaProvider, VistaCheck } from '@vista.io/react-vista-js';

// how to generate 'read tokens' https://docs.govista.io/Guides/React%20Components/Authentication
<VistaProvider secret={read_token}>
    <VistaCheck
        userId={user_id}
        action={action}
        resourceType={resource_type}
        resourceId={resource_id}
        branch="test"

        // optional
        denyComponent={<React.Fragment />} // rendered if permission denied
        handleError={(err) => console.log(err)}>
            <WrappedComponent></WrappedComponent>
    </VistaCheck>
</VistaProvider>
```

See the [client library docs](https://docs.govista.io/Guides/React%20Components/Authentication) on how to generate 'token'.

## VistaGrant Component

The `VistaGrant` component allows your admins to grant teammates roles.

```js
import { VistaProvider, VistaGrant } from '@vista.io/react-vista-js';
<VistaProvider secret={read_token}>
    <VistaGrant
        // map of user_id to names for display purposes
        userIdMap={{
            u1: 'u1',
            u2: 'u2',
            u3: 'u3',
            '6675_user_1': 'Sid',
        }}
        orgId="test_org_2"
        branch="test"
        resourceType="res"
        resourceId="*"

        // called when a role is granted or changed for a teammate
        onGrant={async (userId: string, roleId: string, orgId: string, branch: string) => {
            const success = await sendToGrantRoute(data);
            return true;
        }}

        onRevoke={async (userId: string, roleId: string, orgId: string, branch: string) => {

        }}

        // optional
        styles={{
            grantButton: {
                backgroundColor: 'red',
            }
        }}
        onGrantError={async(e) => console.log(e)} />
</VistaProvider>
```

### Styling
The `VistaGrant` component can be styled at all levels (See the [MaterialUI Customization Guide](https://mui.com/customization/how-to-customize/#1-one-off-customization)):
```js
// pass this in the 'styles' attribute
const styles = {
    container: { // component container element
        height: '500px',
    },
    title: { // title text
        marginTop: '0px',
    },
    newGrantRow: { // top row containing 'select user', 'select role', and 'grant' button
        display: 'flex',
        marginBottom: '20px',
    },
    userSelect: { // user select dropdown
        flexGrow: '1',
        marginRight: '10px',
    },
    roleSelect: { // role select dropdown
        marginRight: '10px',
    },
    grantButton: {}, // grant role button
    grantList: { // list of teammates with granted roles
        flexGrow: '1',
        width: '100%',
        padding: '0',
        border: '1px solid lightgray',
        overflow: 'scroll',
        margin: '0',
    },
    grantRow: { // each grant row containing user_id and role_id
        height: '75px'
    },
    grantRoleSelect: {}, // role dropdown in a 'grantRow'
};
```

## VistaRoles Component

The `VistaRoles` component allows your admins to view all created roles and the permissions associated.

```js
import { VistaProvider, VistaGrant } from '@vista.io/react-vista-js';
<VistaProvider secret={read_token}>
    <VistaRoles
        branch="test"

        // optional
        orgId='customer_12312' // scopes fetched roles by customer (includes global roles)
        styles={{
            grantButton: {
                backgroundColor: 'red',
            }
        }}
    />
</VistaProvider>
```

### Styling
The `VistaRoles` component can be styled at all levels (See the [MaterialUI Customization Guide](https://mui.com/customization/how-to-customize/#1-one-off-customization)):
```js
// pass this in the 'styles' attribute
const styles = {
  container: { // VistaRoles container
    height: '500px',
    width: '1000px',
    display: 'flex',
    border: 'solid',
    borderColor: 'lightgray',
    borderWidth: '1px',
  },
  title: { // Title text
    marginTop: '0px',
  },
  rolesList: { // List with all Roles
    height: '100%',
    width: '200px',
    overflow: 'scroll',
    borderRight: '1px solid lightgray',
  },
  rolesListRow: { // Row in rolesList
    height: '60px',
  },
  permissionsTable: { // Table that lists all permissions for the selected role
    height: '100%',
    flexGrow: '1',
  },
  permissionsTableRow: {}, // Row in permissionsTable
  permissionsTableRowInherited: { // Row in permissionsTable if permission is inherited
    color: 'grey',
  },
};
```