@prosperitainova/dumbo-react-native/README.md

Dumbo for React Native Library

<h1 align="center">
  Dumbo for React Native
</h1>

> The React Native implementation of the Dumbo Design System (Fork of [Carbon Design System](https://github.com/carbon-design-system/carbon))

<p align="center">
  <a href="https://github.com/carbon-design-system/carbon-react-native/blob/main/LICENSE">
    <img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="Carbon is released under the Apache-2.0 license" />
  </a>
  <a href="https://github.com/carbon-design-system/carbon-react-native/blob/main/.github/CONTRIBUTING.md">
    <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs welcome" />
  </a>
</p>

Component and shared patterns for React Native apps using Carbon. Styles are based on the [Carbon Native Mobile](https://carbondesignsystem.com/designing/design-resources/#native-mobile) designs. Color (`g10` for light theme and `g100` for dark theme) and typography tokens are based on Carbon v11.

## Documentation

Documentation can be found [here](https://carbon-design-system.github.io/carbon-react-native/). This documentation is auto generated by the TypeScript files. To use the documentations you can find each component on the left side as a `Class`. Each component has a link to the example app code and the Props (`Component<ItemProps>`) which can be jumped to by clicking the ItemProps. Props will indicate all props this component supports with documentation. Links will jump to related to type declarations.

## Getting started

To install `@prosperitainova/dumbo-react-native` in your project, you will need to run the following
command using [npm](https://www.npmjs.com/):

```bash
npm install -S @prosperitainova/dumbo-react-native
```

If you prefer [Yarn](https://yarnpkg.com/en/), use the following command
instead:

```bash
yarn add @prosperitainova/dumbo-react-native
```

1. Go into the `ios` directory and run `pod install` (be sure to use the system Ruby on Mac if you are using rvm or similar tool)
1. Create or edit `react-native.config.js` file to be:
   ```javascript
   module.exports = {
     project: {
       ios: {},
       android: {},
     },
     assets: [
       './node_modules/@prosperitainova/dumbo-react-native/src/assets/fonts/', // This needs to be added if file already exists
     ],
   };
   ```
1. Run `npx react-native-asset` to link the fonts (install this package if not already).
1. Install the following peer dependencies (install as dependencies. [See dependecies here for tested versions](example/package.json)):
   - `@carbon/themes`
   - `@carbon/icons`
   - `@carbon/icon-helpers`
   - `react-native-svg`
   - `react-native-webview`
   - `react-native-safe-area-context`

**Important**: This library does not support EXPO by default. This library is designed and developed without EXPO.  If you are using EXPO you will need to do additioanl items to alter the build and setup to make it work. Please do not open tickets about issues with EXPO, the app is only tested to run with React Native.

## Recommended Settings

For best experience with navigation we recommend for Android setting `android:windowSoftInputMode="adjustPan"` in your AndroidManifest file. This will prevent the bottom navigation from pushing up. Other known mechanisms exist and you should consider keyboard overlay for developing input areas.

## Usage

### Components

```js
import { Button } from '@prosperitainova/dumbo-react-native';

<Button kind="primary" text="My Button" onPress={() => {}} />;
```

### Colors

You can use `getColor` to retrieve a color token using the system theme for Carbon colors. You can pass a second param to force a theme (light/dark).

```js
import { getColor } from '@prosperitainova/dumbo-react-native';

const styles = StyleSheet.create({
  example: {
    padding: 16,
    color: getColor('textPrimary'),
    backgroundColor: getColor('background'),
  },
});
```

Color scheme will follow the OS. You can request specific colors at any point via second param on get Color. If you wish to use a theme for your app you will need to set the theme globally. This means that any color you use in your own styling will need to be done via a getter (and have this component reload its state). For changing your own colors on the fly you need to ensure getters are used for those styles using color. You can use the `forceTheme` function to change the theme and trigger a state update to change the color.

### Icons

You can use icons from `@carbon/icons` to pass to components. We do not bundle all icons in this library to reduce size. You can import specific icons from that library directly as needed. An example of how to pass icons to the React Native components is below.

```javascript
import AddIcon from '@carbon/icons/es/add/20';

// Using an icon with a component that supports Carbon Icons.
<Button icon={AddIcon} />

// Using an icon directly in your own component. You can use our helper.  See `createIcon` params for options.
<View>{createIcon(icon, 20, 20)}</View>
```

### Overriding Themes

You can override the default Carbon theme (Carbon Colors and IBM Plex) by using the built in theme override calls. These should be done first in your app during a loading state or initial load. If done after app load any component already rendered needs to redraw state.

#### Overriding colors

Colors can be overridden by using `overrideLightTheme` or `overrideDarkTheme`. If you wish to use only one theme for your app you can simply `forceTheme` as well to lock the app to a single theme. Colors are written in camelCase and follow the tokens found at [Carbon Design Systems](https://carbondesignsystem.com/guidelines/color/tokens).

#### Overriding fonts

Fonts can be overridden on individual components by overriding the styles (`fontFamily`, `fontWeight`). However, you can also override them globally. By calling `overrideFonts` which takes in a family and weight for each of the internal font groups components use. If you use a font be sure to use one that is supported on the OS you are running. Android and iOS have different supported fonts. You can also use custom fonts as long as you bundle them as part of your app.  It is a similar process to how we add Plex above in the "Getting started" section.

## Contributing

See the [contributing guide](/.github/CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.

## <picture><source height="20" width="20" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-dark.svg"><source height="20" width="20" media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-light.svg"><img height="20" width="20" alt="IBM Telemetry" src="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-light.svg"></picture> IBM Telemetry

This package uses IBM Telemetry to collect de-identified and anonymized metrics data. By installing
this package as a dependency you are agreeing to telemetry collection. To opt out, see
[Opting out of IBM Telemetry data collection](https://github.com/ibm-telemetry/telemetry-js/tree/main#opting-out-of-ibm-telemetry-data-collection).
For more information on the data being collected, please see the
[IBM Telemetry documentation](https://github.com/ibm-telemetry/telemetry-js/tree/main#ibm-telemetry-collection-basics).