@opub-cdl/ui

OPub UI

Welcome to our OPub UI. This component library is based on a React, designed to provide a collection of reusable UI components for Open Data Platforms.

Getting Started

To get started with the component library, install the package via npm:

npm install @opub-cdl/ui --save

If you prefer Yarn:

yarn add @opub-cdl/ui

Usage

The following steps are required before you can start using components:

1. Import the CSS into the project. In the case of Nextjs, it's _app.tsx file.

import '@opub-cdl/ui/dist/assets/styles.css';

2. This step is for SSR apps. We use React Aria for some components. To ensure it works correctly in Next.js, you must wrap the App with SSRProvider. More Info

import { SSRProvider } from 'react-aria';

<SSRProvider>
  <Component {...pageProps} />
</SSRProvider>;

3. Once you complete the initial setup, you can import components into your project as needed:

import { Badge, Button, Menu } from 'opub-cdl/ui';

When using with NextJs you will need to transpile the packages More Info, add this inside next.config.js :

transpilePackages: ['@opub-cdl/ui']

Components

You can view the complete list of available components on Storybook. The list will grow, and there can be breaking changes at this stage of development.

Development

The source code is under the src directory. The structure is as follows:

src/
┣ components/
┣ tokens/
┣ types/
┣ utils/
┣ index.ts

Components

All components reside in this directory. This is the structure we follow for components, e.g., Checkbox:

Checkbox/
┣ Checkbox.tsx/
┣ Checkbox.module.scss/
┣ Checkbox.stories.tsx/
┣ Checkbox.test.tsx/
┣ index.ts

We use Vitest for unit testing and Storybook for developing components in isolation.

As you notice in the directory, we use Sass Modules for styling.

Tokens

Although we have a css based token file at assets/tokens.css which relies on CSS Variables. This directory stores those tokens in objects. One use-case of its usage is the Box component.

Types

In this directory, we store the type files of components that aid in type checking and other helpful typescript features.

Utils

This directory stores helpers, custom hooks, and other utility functions to aid development.

Bundling

We use Rollup to bundle the src for publishing on npm. We also copy the assets into the bundled dist directory during this step. You can check out the config file at ./rollup.config.mjs.

We only bundle into ESM Modules.

Contributing

Pull requests are welcome. See the contribution guidelines for more information.

Credits

Thanks to the following projects for developing in the open and sharing their work with the community:

1. Shopify Polaris
2. Radix UI
3. React Spectrum
4. React Hook Form
5. AriaKit
6. Tabler Icons

Licenses

The source code is under MIT License unless otherwise stated. This project uses multiple open-source libraries and projects. You can review the dependencies in the package.json file and check their Licenses from their GitHub repo.