<commit_before># CASL React

[![@casl/react NPM version](https://badge.fury.io/js/%40casl%2Freact.svg)](https://badge.fury.io/js/%40casl%2Freact)
[![](https://img.shields.io/npm/dm/%40casl%2Freact.svg)](https://www.npmjs.com/package/%40casl%2Freact)
[![CASL Join the chat](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/stalniy-casl/casl)

This package allows to integrate `@casl/ability` with [React] application. It provides `Can` component that allow to hide or show UI elements based on user ability to see them.

> `@casl/react` perfectly works with [React Native](https://reactnative.dev/)

## Installation

```sh
npm install @casl/react @casl/ability
# or
yarn add @casl/react @casl/ability
# or
pnpm add @casl/react @casl/ability
```

## Can component

It accepts children and 6 properties:

* `do` - name of the action (e.g., `read`, `update`). Has an alias `I`
* `on` - checked subject. Has `a`, `an`, `this` aliases
* `field` - checked field

  ```jsx
  export default ({ post }) => <Can I="read" this={post} field="title">
    Yes, you can do this! ;)
  </Can>
  ```

* `not` - inverts ability check and show UI if user cannot do some action:

  ```jsx
  export default () => <Can not I="create" a="Post">
    You are not allowed to create a post
  </Can>
  ```

* `passThrough` - renders children in spite of what `ability.can` returns. This is useful for creating custom components based on `Can`. For example, if you need to disable button based on user permissions:

  ```jsx
  export default () => (
    <Can I="create" a="Post" passThrough>
      {allowed => <button disabled={!allowed}>Save</button>}
    </Can>
  )
  ```

* `ability` - an instance of `Ability` which will be used to check permissions
* `children` - elements to hide or render. May be either a render function:

  ```jsx
  export default () => <Can I="create" a="Post" ability={ability}>
    {() => <button onClick={this.createPost}>Create Post</button>}
  </Can>
  ```

  or React elements:

  ```jsx
  export default () => <Can I="create" a="Post" ability={ability}>
    <button onClick={this.createPost}>Create Post</button>
  </Can>
  ```

> it's better to pass children as a render function because it will not create additional React elements if user doesn't have ability to do some action (in the case above `read Post`)

Don't be scared by the amount of properties component takes, we will talk about how to bind some of them.

### Bind Can to a particular Ability instance

It'd be inconvenient to pass `ability` in every `Can` component. That's why there are 2 function which allow to bind `Can` to use a particular instance of `Ability`:

* `createCanBoundTo`\
  This function was created to support version of React < 16.4.0, those versions doesn't have [Context API][react-ctx-api]. Can be used like this:

  ```js @{data-filename="Can.js"}
  import { createCanBoundTo } from '@casl/react';
  import ability from './ability';

  export const Can = createCanBoundTo(ability);
  ```
* `createContextualCan`\
  This function is created to support [React's Context API][react-ctx-api] and can be used like this:

  ```js @{data-filename="Can.js"}
  import { createContext } from 'react';
  import { createContextualCan } from '@casl/react';

  export const AbilityContext = createContext();
  export const Can = createContextualCan(AbilityContext.Consumer);
  ```

The 2 methods are almost the same, the 2nd one is slightly better because it will allow you to provide different `Ability` instances to different parts of your app and inject ability using [`contextType` static property](https://reactjs.org/docs/context.html#classcontexttype). Choose your way based on the version of React you use.
<commit_msg>docs(react): fixes an incorrect description (#374)<commit_after># CASL React

[![@casl/react NPM version](https://badge.fury.io/js/%40casl%2Freact.svg)](https://badge.fury.io/js/%40casl%2Freact)
[![](https://img.shields.io/npm/dm/%40casl%2Freact.svg)](https://www.npmjs.com/package/%40casl%2Freact)
[![CASL Join the chat](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/stalniy-casl/casl)

This package allows to integrate `@casl/ability` with [React] application. It provides `Can` component that allow to hide or show UI elements based on user ability to see them.

> `@casl/react` perfectly works with [React Native](https://reactnative.dev/)

## Installation

```sh
npm install @casl/react @casl/ability
# or
yarn add @casl/react @casl/ability
# or
pnpm add @casl/react @casl/ability
```

## Can component

It accepts children and 6 properties:

* `do` - name of the action (e.g., `read`, `update`). Has an alias `I`
* `on` - checked subject. Has `a`, `an`, `this` aliases
* `field` - checked field

  ```jsx
  export default ({ post }) => <Can I="read" this={post} field="title">
    Yes, you can do this! ;)
  </Can>
  ```

* `not` - inverts ability check and show UI if user cannot do some action:

  ```jsx
  export default () => <Can not I="create" a="Post">
    You are not allowed to create a post
  </Can>
  ```

* `passThrough` - renders children in spite of what `ability.can` returns. This is useful for creating custom components based on `Can`. For example, if you need to disable button based on user permissions:

  ```jsx
  export default () => (
    <Can I="create" a="Post" passThrough>
      {allowed => <button disabled={!allowed}>Save</button>}
    </Can>
  )
  ```

* `ability` - an instance of `Ability` which will be used to check permissions
* `children` - elements to hide or render. May be either a render function:

  ```jsx
  export default () => <Can I="create" a="Post" ability={ability}>
    {() => <button onClick={this.createPost}>Create Post</button>}
  </Can>
  ```

  or React elements:

  ```jsx
  export default () => <Can I="create" a="Post" ability={ability}>
    <button onClick={this.createPost}>Create Post</button>
  </Can>
  ```

> it's better to pass children as a render function because it will not create additional React elements if user doesn't have ability to do some action (in the case above `create Post`)

Don't be scared by the amount of properties component takes, we will talk about how to bind some of them.

### Bind Can to a particular Ability instance

It'd be inconvenient to pass `ability` in every `Can` component. That's why there are 2 function which allow to bind `Can` to use a particular instance of `Ability`:

* `createCanBoundTo`\
  This function was created to support version of React < 16.4.0, those versions doesn't have [Context API][react-ctx-api]. Can be used like this:

  ```js @{data-filename="Can.js"}
  import { createCanBoundTo } from '@casl/react';
  import ability from './ability';

  export const Can = createCanBoundTo(ability);
  ```
* `createContextualCan`\
  This function is created to support [React's Context API][react-ctx-api] and can be used like this:

  ```js @{data-filename="Can.js"}
  import { createContext } from 'react';
  import { createContextualCan } from '@casl/react';

  export const AbilityContext = createContext();
  export const Can = createContextualCan(AbilityContext.Consumer);
  ```

The 2 methods are almost the same, the 2nd one is slightly better because it will allow you to provide different `Ability` instances to different parts of your app and inject ability using [`contextType` static property](https://reactjs.org/docs/context.html#classcontexttype). Choose your way based on the version of React you use.

{'fraction_non_alphanumeric': 0.13401096696536044, 'fraction_numerical': 0.006285943560251438, 'mean_word_length': 4.171507607192255, 'pattern_counts': {'":': 0, '<': 37, '<?xml version=': 0, '>': 53, 'https://': 16, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2949128', 'n_tokens_mistral': 2339, 'n_tokens_neox': 2243, 'n_words': 867}