npm package: @nokkel/components
Description: Nokkel component library for React-based applications
Author: Nokkel Technologies Ltd
Latest version: 3.5.69

## React Components

A repository for re-usable, React-based components for use across web applications within the Nokkel ecosystem.

## Pre-requisites

- [asdf](https://asdf-vm.com/guide/getting-started.html)

## Integration

To use this component library in your application, you need to set up i18next for internationalization support and react-router-dom for navigation components.

### Installing i18next

```bash
npm install i18next react-i18next
```

### Setting up i18next

Create an `i18n.ts` file in your project:

```typescript
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import { getResources } from '@nokkel/react-components';

const resources = getResources();

i18n.use(initReactI18next).init({
  debug: false,
  lng: 'en',
  fallbackLng: 'en',
  interpolation: {
    escapeValue: false,
  },
  resources,
});

export default i18n;
```

### Installing react-router-dom (Required for navigation components)

Some components use `react-router-dom`'s Link component for navigation. Install it as a dependency:

```bash
npm install react-router-dom
```

**Important**: Components that use routing require your application to be wrapped in a Router provider (BrowserRouter, HashRouter, etc.).

### Setting up react-router-dom

Wrap your application with a Router provider. Choose the appropriate router for your use case:

```tsx
import React from 'react';
import { BrowserRouter } from 'react-router-dom';

function App() {
  return <BrowserRouter>{/* Your app content */}</BrowserRouter>;
}

export default App;
```

## Contributing

To create a component directory, run `npm run create:component --name="INSERT NAME HERE"

To create an icon, run `npm run create:icon --name="INSERT NAME HERE"

Nokkel components are structured like so:

```
src/
├── components/
│   └── [Component]/
│       ├── [Component].css
│       ├── [Component].stories.tsx
│       ├── [Component].tsx
│       ├── index.ts
│       └── types.ts
├── content/
│   └── [namespace]/
│       ├── index.json
│       └── [provider].json
├── context/
│   ├── [context].tsx
│   └── index.ts
├── hooks/
│   ├── [hook].ts
│   └── index.ts
├── icons/
│   ├── [Icon]
|   ├── [Icon].stories.tsx
│   └── index.ts
├── styles/
│   └── global.css
├── sections/
│   └── [Section]/
│       ├── [Section].css
│       ├── [Section].stories.tsx
│       ├── [Section].tsx
│       ├── index.ts
│       └── types.ts
├── utils/
│   ├── [Util].ts
│   └── index.ts
└── index.ts
```

- `Component.css` is where the component classes are stored. We use tailwind styles with the @apply for styles.
  - For brands, use the `[data-theme="[brand]"]` selector in order to change that specific class for brands.
  - See Button.css for a good example.
- `Component.stories.tsx` is where the story for Storybook is stored.
  - Decorators may be used for containers in the case of responsive components.
  - Note: Storybook documentation oftentimes has a type issue with the `satisfies Meta<typeof [Component]>`. It's suggested to use the same pattern in Button.stories.tsx
  - The first story is used as the top example in Autodocs so it's best to ensure it has all the needed controls (though this can be manually added).
- `Component.tsx` contains the actual component.
  - Using a Multi-line comment before the main export will be used by Autodocs in Storybook.
  - Add a `data-testid=[component]` for testing purposes and identification of component.
  - MaterialUI is used as a base for many components.
  - Button.tsx is a model component.
- `types.ts` contains all the types such as props.
  - Comments before each props will be documented in storybook to help design know the fields that can be edited.
- `index.ts` exports the component and types. We use this to export the component to the parent folder.
- `[namespace]/index.json` is the translation file for the text content using i18next formatting.
- `[namespace]/[provider].json` is the provider-specific variant translation file that overrides the default translations.