oasis-ui-components

OASIS UI Components

Overview

oasis-ui-components is a design system UI component library built with React, TypeScript, Material-UI (MUI), and Emotion. It provides reusable components (e.g., StyledChip) and a theme system using OASISThemeProvider. Storybook is integrated for developing, testing, and documenting components in isolation. Additionally, the library includes a robust localization system using i18next and react-i18next to support multiple languages.

This library is intended to be consumed by other projects, such as the web-portal application, to provide a consistent design system across applications with multilingual support.

Project Structure

.
├── dist/                     # Build output
├── node_modules/             # Dependencies
├── src/                      # Source code
│   ├── common/              # Shared utilities, types and interfaces
│   ├── components/          # React components (e.g., StyledChip)
│   ├── localization/        # Localization setup
│   │   ├── locales/        # Translation files (e.g., en/common.json, es/common.json)
│   │   ├── index.ts        # i18next configuration
│   │   ├── localesWrapper.tsx # Localization wrapper component
│   │   └── useTranslations.ts # Custom hook for simplified translation access
│   ├── models/              # Data models
│   ├── theme/               # Theme setup (OASISThemeProvider)
│   │   ├── index.ts        # Theme exports and entry point
│   │   ├── oasis-theme.ts  # Core theme definitions and configurations
│   │   ├── theme-adapter.ts # Adapter for integrating theme with external systems
│   │   ├── theme.tsx       # Theme provider component (OASISThemeProvider)
│   │   └── emotion-theme.d.ts # Emotion theme type definitions
│   ├── types/               # Emotion - theme declaration
│   ├── utils/               # Utility functions
│   └── styles.css           # Global styles
├── .eslintrc                # ESLint configuration
├── .gitignore               # Git ignore rules
├── .npmignore               # npm ignore rules
├── .prettierignore          # Prettier ignore rules
├── .prettierrc              # Prettier configuration
├── jest.config.ts           # Jest configuration
├── jest.preset.js           # Jest presets
├── package-lock.json        # Dependency lock file
├── package.json             # Package metadata and scripts
├── storybook/               # Storybook configuration
├── tsconfig.json            # TypeScript configuration
├── tsup.config.ts           # tsup (build tool) configuration
└── vite.config.ts           # Vite configuration

Prerequisites

• Node.js: Version 18.x or higher
• npm: Version 8.x or higher

Installation

1. Clone the Repository

git clone <repository-url>
cd oasis-ui-components

2. Install Dependencies

Install the project dependencies:

npm install

Running Storybook

Storybook is used to develop and test UI components in isolation.

Start Storybook

npm run storybook

• Storybook will start at http://localhost:6006.
• You can view and interact with components like StyledChip and test different theme configurations.

Troubleshooting Storybook

• Error: "No story files found for the specified pattern: src/**/*.mdx"

  • Ensure there are .stories.tsx or .mdx files in the src/ directory.

  • Check the Storybook configuration in .storybook/main.ts to verify the stories field includes the correct file patterns, e.g.:

    module.exports = {
      stories: ['../src/**/*.stories.@(ts|tsx)'],
      // Other configurations
    };
    

  • Create a sample story if none exist. Example: src/components/StyledChip.stories.tsx:

    import { StyledChip } from './StyledChip';
    
    export default {
      title: 'Components/StyledChip',
      component: StyledChip,
    };
    
    export const Default = () => <StyledChip size="medium" status="good">Good Status</StyledChip>;
    

Building the Library

To build the library for use in other projects (e.g., web-portal):

npm run build

• The build output will be in the dist/ directory.
• The build uses tsup to generate ES modules (dist/index.js) and TypeScript declaration files (dist/index.d.ts).

Localization Setup

The library includes a localization system to support multiple languages using i18next and react-i18next. It provides a LocalesWrapper component for easy integration, lazy-loaded translations, and automatic language detection.

Using LocalesWrapper

The LocalesWrapper component (src/localization/localesWrapper.tsx) wraps your application or components to provide i18n context and handle language switching.

Props

• children: The React components to render within the wrapper.
• locale (optional): Specify a language (e.g., en, es). Defaults to the detected language or en.
• fallback (optional): A custom fallback UI to display while translations are loading. Defaults to <div>Loading...</div>.

Example Usage with Theme & Localization

Wrap your app with both OASISThemeProvider and LocalesWrapper to enable theming and localization:

import React from 'react';
import ReactDOM from 'react-dom/client';
import { CacheProvider } from '@emotion/react';
import createCache from '@emotion/cache';
import { OASISThemeProvider, oasisLightTheme } from 'oasis-ui-components';
import { LocalesWrapper } from 'oasis-ui-components';
import App from './App';

// Create an Emotion cache to ensure a single Emotion instance
const emotionCache = createCache({ key: 'css' });

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <CacheProvider value={emotionCache}>
      <OASISThemeProvider theme={oasisLightTheme}>
        <LocalesWrapper locale="es">
          <App />
        </LocalesWrapper>
      </OASISThemeProvider>
    </CacheProvider>
  </React.StrictMode>
);

Accessing Translations with useTranslations

To simplify accessing translations across multiple namespaces, use the useTranslations hook (src/localization/useTranslations.ts). This hook allows you to load multiple namespaces at once and returns an array of t functions, one for each namespace, which you can destructure.

Example

import React from 'react';
import { useTranslations } from 'oasis-ui-components';
import { OasisChip } from 'oasis-ui-components';

function App() {
  const { t: [tCommon, tStatus] } = useTranslations(['common', 'status']);
  return (
    <div>
      <h1>{tCommon('welcome')}</h1>
      <p>{tStatus('error')}</p>
      <OasisChip tagValue={'30'} status="warning" label={tStatus('warning')} />
    </div>
  );
}

export default App;

• useTranslations(['common', 'status']) returns an array of t functions: [tCommon, tStatus].
• tCommon is for the common namespace, and tStatus is for the status namespace.
• The order of the t functions matches the order of the namespaces passed to useTranslations.
• If you have more namespaces (e.g., 10 namespaces), you can extend the destructuring: const { t: [tCommon, tStatus, tNamespace3, ...] } = useTranslations(['common', 'status', 'namespace3', ...]);.

Supported Languages

The library supports:

• en (English)
• es (Spanish)
• es-MX (Mexican Spanish)
• es-AR (Argentinian Spanish)

If a specific variant (e.g., es-MX) is unavailable, it falls back to es, and finally to en.

Adding New Translations

To add a new language:

• Create a new directory under src/localization/locales (e.g., locales/fr for French).
• Add translation files (e.g., common.json, status.json) with key-value pairs.
• Update the supportedLngs array in src/localization/index.ts to include the new language (e.g., fr).

Example locales/fr/common.json:

{
  "welcome": "Bienvenue"
}

Development Notes for Localization

• Debugging: Enable debug: true in src/localization/index.ts for detailed logs.
• Namespaces: Default namespace is common. Add new namespaces in the ns array in index.ts.
• Performance: Translations are lazy-loaded. Optimize translation files for size to reduce load times.

Using in Other Projects

Linking for Development

To use oasis-ui-components in another project (e.g., web-portal) during development, you can link it locally instead of installing from npm. This allows you to test changes in oasis-ui-components live in your project.

1. Link oasis-ui-components

In the oasis-ui-components directory, create a global symlink:

cd oasis-ui-components
npm link

2. Link in Your Project

In your other project (e.g., web-portal), link to the local oasis-ui-components:

cd ../web-portal
npm link oasis-ui-components

• This sets up oasis-ui-components as a dependency in web-portal, using the local version for development.

3. Build and Watch for Changes

To ensure changes in oasis-ui-components are reflected in web-portal, run the development build in watch mode:

cd oasis-ui-components
npm run dev

• This uses tsup to watch for changes and rebuild the library automatically.

4. Unlink After Development

Once development is complete and you’re ready to use the published version, unlink oasis-ui-components:

cd ../web-portal
npm unlink oasis-ui-components
cd ../oasis-ui-components
npm unlink

Then, install the published version in web-portal:

cd ../web-portal
npm install oasis-ui-components@0.0.8

Theme Setup

The library provides a theme system using OASISThemeProvider. Wrap your app with OASISThemeProvider to apply the theme to all components. See the "Using LocalesWrapper" section above for an example of combining it with localization.

Example in a React app (web-portal):

import React from 'react';
import ReactDOM from 'react-dom/client';
import { CacheProvider } from '@emotion/react';
import createCache from '@emotion/cache';
import { OASISThemeProvider, oasisLightTheme, StyledChip } from 'oasis-ui-components';
import App from './App';

// Create an Emotion cache to ensure a single Emotion instance
const emotionCache = createCache({ key: 'css' });

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <CacheProvider value={emotionCache}>
      <OASISThemeProvider theme={oasisLightTheme}>
        <App />
      </OASISThemeProvider>
    </CacheProvider>
  </React.StrictMode>
);

In your App.tsx:

import React from 'react';
import { useTheme } from '@emotion/react';
import { OasisChip } from 'oasis-ui-components';

function ThemeDebugger() {
  const theme = useTheme();
  console.log('Theme in App:', theme);
  return null;
}

function App() {
  return (
    <div>
      <ThemeDebugger />
      <h1>Web Portal</h1>
      <OasisChip tagValue={'30'} status={StatusEnum.WARNING}></OasisChip>
    </div>
  );
}

export default App;

Troubleshooting Theme Issues

• If components (e.g., StyledChip) log an empty theme ({}):
  • Ensure @emotion/react versions match between oasis-ui-components and your project (e.g., ^11.14.0).
  • Verify OASISThemeProvider wraps your app at the root level.
  • Use CacheProvider to avoid Emotion context issues.

Development

Running in Development Mode

To watch for changes and rebuild the library:

npm run dev

• This uses tsup to watch for changes in src/ and rebuild the library.

Testing

Run tests using Vitest:

npm run test

• Tests are configured in jest.config.ts (used by Vitest for compatibility).

Contributing

• Create a new branch: git checkout -b feature/your-feature-name
• Make changes and commit: git commit -m "Add your message"
• Push to the branch: git push origin feature/your-feature-name
• Create a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for details.