gazelle-component-ui

Gazelle components / hooks library

🧩 Components

Gazelle Component UI is a library of reusable UI components for Next.js & React applications. This library aims to provide a set of well-designed and accessible components to speed up the development process and ensure consistency across the Gazelle application.

📁 Refer to src/components to see the list of available components or check them out directly on the Storybook page.

🪝 Custom Hooks

Additionally, our component library provides a set of generic hooks that can seamlessly integrate into your applications. These hooks offer versatile functionality, enhancing flexibility and extensibility.

📁 Refer to src/hooks to see the list of available hooks.

⚠️ This library is intended to be used with Next.js application.

⚠️ *Note: This library is actively maintained and regularly updated with new features and improvements. So do not forget to upgrade the library.*

📦 Installation

You can install the gazelle-component-ui package via npm:

npm install gazelle-component-ui

🧑‍💻 Usage

To use the components from gazelle-component-ui in your React application, import the desired component and use it like any other React component.

A simple button component with various customization options.

Required Props

Prop	Type	Description
id	string	Id for automatic test
children	node	Content of the button.
type	union	button
title	string	Title attribute for the button.
ariaLabel	string	ARIA label for accessibility.
variant	union	primary, secondary or validation

Here is an example demonstrating how to use a Button component from the library:

import React from "react";
import { Button } from "gazelle-component-ui";

const App = () => {
  return (
    <div>
      <h1>Welcome to Gazelle Component UI</h1>
      <Button id={id} type={type} title={title} aria-label={ariaLabel} onClick={() => alert("Button clicked!")} variant={primary}>
        Click Me
      </Button>
    </div>
  );
};

export default App;

✅ Unit testing component with vitest

🔍 1. Run Tests:

Use the basic test command to execute all unit tests

npm run test

📊 2. Generate Coverage Reports:

To generate a code coverage report, use:

npm run test:coverage

This will output the test coverage details, indicating how much of your code is tested.

🌐 3. Interactive Coverage Report:

For an interactive user interface to explore test coverage, run:

npm run vitest:coverage

This starts Vitest’s UI with test and coverage details accessible in the browser.

📖 Storybook Documentation

We use Storybook to document and showcase the components provided by Gazelle Component UI. Storybook provides an interactive UI environment where you can browse, view, and test components in isolation.

🚀 Running Storybook

To view the documentation and interact with the components in Storybook:

1. Clone the repository:

git clone https://gitlab.inria.fr/gazelle/private/new-gazelle/user-interface/gazelle-component-lib.git

2. Install dependencies:

npm install

3. Start Storybook:

npm run storybook

4. Open Storybook in your browser:

Navigate to http://localhost:6006 to view the Storybook interface.

Using Storybook

In the Storybook interface, you can:

• Browse Components: Navigate through the list of available components.

• View Documentation: Read detailed documentation for each component, including props and usage examples.

• Interact with Components: Test and interact with components in real-time.

🚢 Test & publish the library

In order to use this library in all other Next-JS projects, we need to publish the components on a registry.

For registry, we are using https://www.npmjs.com.

Prerequisites

• Check that you are authenticated to the registry (npm whoami), if not, use the command npm adduser.

• Check the version in your package.json. You can't push a library on an existing version.

Test your component before publishing to npm

Two methods are available to test your new component in your current application, follow these steps:

Method 1: Using NPM Link

1. Build your component

Ensure your component is built and ready for use by running:

npm run build

2. Link the component locally

Link your component globally in your development environment:

npm link

3. Link the component in your application

In the application or repository where you want to test the component, run:

npm link gazelle-component-ui

Method 2: Using NPM Pack (Recommended)

1. Build your component

Ensure your component is built and ready for use by running:

npm run build

2. Create a tarball package

Create a local tarball package of your component library:

npm pack

This command will generate a file named gazelle-component-ui-{VERSION}.tgz in your project root directory, where {VERSION} matches the version in your package.json.

3. Install the package in your application

In the application where you want to test the component, install the local package using the absolute path to the tarball:

# If using npm
npm install /absolute/path/to/gazelle-component-ui-{VERSION}.tgz

# If using pnpm
pnpm install /absolute/path/to/gazelle-component-ui-{VERSION}.tgz

Replace /absolute/path/to/ with the actual path to your component library directory.

Note: This approach creates a more realistic testing environment as it exactly replicates how the package would behave when installed from the npm registry.

Publishing Your Component

Once you’ve tested your component and are ready to publish a new version to the npm registry, follow these steps:

1. Update the version

Use the following command to update your package version:

npm version patch

2. Publish to the npm registry

Publish the new version of your package:

npm publish

✅ Don't forget to push your changes to the library repository to ensure the latest updates are tracked and shared.

3. Verify the publication

Once published, verify the package on the npm registry:

• Visit the package page on npm.
• Install the package in another project using:

npm install gazelle-component-ui

Once the library is pushed, you can go to your Next-JS application to change the library version in the package.json. Execute the npm install command. You can now use the components you developed.

📝 License

    Copyright 2022-2025 IHE International

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.