HDS UI Library

Overview

This project is a comprehensive UI library for a design system. It contains reusable components, styles, and guidelines to ensure consistent and efficient UI development across projects.

File Structure

The project's file structure is as follows:

• components/: Contains reusable UI components.
• styles/: Contains global styles and theme configuration and CSS for antd components.
• utils/: Contains utility functions and helpers.
• charts/: Contains exports from chart libraries.
• docs/: Contains documentation files for the UI library.
  • component: Contains individual documentation files for each component.
  • style-guide.md: Provides guidelines and best practices for using the UI library.

Documentation

• Components

  • Avatar
  • AvatarGroup
  • Button
  • SideNav
  • Tile
  • UserCard

• Utility Functions

• Icons

• Charts

• Styles

License

This project is licensed under the MIT License.

Using the Project

To use the UI Library, follow these steps:

1. Ensure that you have Node.js v20.15.0 and yarn or npm installed on your machine.
2. Open a terminal and navigate to the project's root directory.
3. Run the following command to install the project dependencies:

   yarn install hds-ui / npm i hds-ui

4. Once the dependencies are installed, you can use the library as given in the documentation:

That's it! You can now start using and exploring the HDS UI Library.

Docs with Example

Avatar

The Avatar component is a customizable avatar component built using React and Ant Design. It allows you to display user avatars with various sizes, images, and fallback initials.

AvatarProps

size: string

The size of the avatar. Can be one of "xs", "sm", "md", "lg", "xl", "xxl"

className: String (optional)

Additional CSS classes to apply to the component. Default is ''.

src: string (optional)

The source URL of the avatar image. Default is ''.

alt: string (optional)

The alternative text for the avatar image. Default is ''.

children: ReactNode (optional)

The content to be rendered inside the avatar.

restProps: AvatarProps (optional)

Additional props to be passed to the underlying Antd Avatar component.

Example Usage

import React from 'react';
import { Avatar } from 'hds-ui/components';
//OR
import Avatar from 'hds-ui/components/Avatar';

const App = () => (
  <div>
    <Avatar size="md" src="avatar.jpg" alt="John Doe">
      JD
    </Avatar>
  </div>
);

export default App;

AvatarGroup

The AvatarGroup component displays a group of avatars with optional tooltips and a limit on the number of visible avatars.

AvatarGroupProps

users: Array

An array of user objects, each containing:

• name: String - The name of the user.
• profilePic: String - The URL or path to the user's profile picture.

className: String (optional)

Additional CSS classes to apply to the component.

renderTooltip: Function (optional)

A function to render the tooltip content. Receives the list of users as an argument.

showTooltip: Boolean (optional)

Whether to show tooltips on avatar hover. Default is false.

maxVisible: Number (optional)

The maximum number of avatars to display. Additional avatars will be grouped into a "+X" indicator. Default is 4.

avatarSize: String (optional)

The size of the avatars. Possible values are "sm", "md", "lg". Default is "md".

Example Usage

import React from 'react';
import { Avatar } from 'hds-ui/components';
//OR
import Avatar from 'hds-ui/components/Avatar';

const users = [
  { name: 'John Doe', profilePic: 'john.jpg' },
  { name: 'Jane Smith', profilePic: 'jane.jpg' },
  // more users...
];

const renderTooltip = (users) => (
  <div>
    {users.map((user) => (
      <div key={user.name}>{user.name}</div>
    ))}
  </div>
);

const App = () => (
  <Avatar.Group
    users={users}
    className=""
    renderTooltip={renderTooltip}
    showTooltip={true}
    maxVisible={4}
    avatarSize="md"
  />
);

export default App;

Button

The Button component is a customizable button built on top of Ant Design's Button component. It supports additional styling and size options.

ButtonProps

type: Array

The type of the button. Possible values are 'primaryBlack', 'primaryGreen', 'default', 'text', 'link'. Default is 'default'.

className: String (optional)

Additional CSS classes to apply to the component. Default is ''

size: Function (optional)

The size of the Button. Can be one of "sm", "md", "lg".

children: ReactNode (optional)

The content to be rendered inside the avatar.

restProps: ButtonProps (optional)

Additional props to be passed to the underlying Antd Button component.

Example Usage

import React from 'react';
import { Button } from 'hds-ui/components';
// OR
import Button from 'hds-ui/components/Button';

const App = () => (
  <Button type="primary" size="lg" className="custom-class">
    Click Me
  </Button>
);

export default App;

SideNav

The SideNav component represents a side navigation menu that can be used in your application. It is built using React and includes various customization options.

SideNavProps

className: string (optional)

A custom CSS class to apply to the SideNav component.

options: Array<{ key: string, label: string, icon: React.ReactNode }> (optional)

An array of objects representing the navigation options. Each object should have the following properties:

• key: A unique identifier for the option.
• label: The text label for the option.
• icon: A React node representing the icon for the option.

activeKey: string

The key of the currently active navigation option.

Example Usage

import { HomeIcon, ProfileIcon, SettingsIcon } from 'hds-ui/icons';
import { SideNav } from 'hds-ui/components';
// OR
import SideNav from 'hds-ui/components/SideNav';

<SideNav
  className="custom-sidenav"
  options={[
    { key: 'home', label: 'Home', icon: <HomeIcon /> },
    { key: 'profile', label: 'Profile', icon: <ProfileIcon /> },
    { key: 'settings', label: 'Settings', icon: <SettingsIcon /> },
  ]}
  activeKey="home"
/>;

Tile

The Tile component is a custom wrapper around the AntdCard component from Ant Design. It provides additional styling and functionality.

TileProps

title: string

The title of the tile.

children: React.ReactNode

The content to be displayed inside the tile.

className: string, optional, default: ''

A custom CSS class to apply to the tile.

headingSeperator: boolean, optional, default: false

If true, a separator line will be added below the heading.

...restProps: CardProps

Additional props to be passed to the Antd Card component.

Example Usage

import React from 'react';
import { Tile } from 'hds-ui/components';
// OR
import Tile from 'hds-ui/components/Tile';

<Tile title="My Tile">
  <p>This is the content of the tile.</p>
</Tile>;

UserCard

The UserCard component is a React component that displays a user's profile information, including their profile picture, title, subtitle, description, and band. It also supports a loading state and customizable image size and hover zoom effect.

UserCardProps

profilePic : string

URL of the user's profile picture.

title : string

User's title or name.

subTitle : string

User's subtitle or position.

description : string

Description of the user.

band : string

User's band or role.

loading : boolean

Indicates if the component is in a loading state. Default is false.

imgSize : string

Size of the profile image. Possible values: 'sm', 'md', 'lg'. Default is md.

imgHoverZoom : boolean

Enables or disables the hover zoom effect on the profile image. Default is false.

Example Usage

import React from 'react';
import { UserCard } from 'hds-ui/components';
// OR
import UserCard from 'hds-ui/components/UserCard';

<UserCard
  profilePic="https://example.com/profile.jpg"
  description="Lorem ipsum dolor sit amet"
  band="Admin"
  title="John Doe"
  subTitle="Software Engineer"
  loading={false}
  imgSize="md"
  imgHoverZoom={false}
/>;

Utils Module

The utils module provides a set of utility functions that can be used throughout the application. Below is the detailed documentation for each function available in utils/index.ts.

isNullOrUndefined

Checks whether the given item is null or undefined.

Parameters:

• item: any - Any value to be checked.

Returns:

• Boolean - true if the item is null or undefined, otherwise false.

Example:

import { isNullOrUndefined } from 'hds-ui/utils';

console.log(isNullOrUndefined(null)); // Output: true
console.log(isNullOrUndefined(undefined)); // Output: true
console.log(isNullOrUndefined(0)); // Output: false

ifElse

The ifElse function is used to replace the ternary operator.

Parameters:

• condition: boolean | Boolean - The condition to be evaluated.
• ifReturn: any - Value to be returned if the condition is true or a function to be executed when the condition is true.
• elseReturn: any - Value to be returned if the condition is false or a function to be executed when the condition is false.

Returns:

• any - The value of ifReturn if the condition is true, the value of elseReturn if the condition is false, or void if both ifReturn and elseReturn are functions.

Example:

import { ifElse } from 'hds-ui/utils';

const result = ifElse(true, 'Yes', 'No');
console.log(result); // Output: Yes

isEmpty

Checks whether the given item is empty.

Parameters:

• item: any - Any value to be checked.

Returns:

• Boolean - true if the item is empty, otherwise false.

Example:

import { isEmpty } from 'hds-ui/utils';

console.log(isEmpty(null)); // Output: true
console.log(isEmpty({})); // Output: true
console.log(isEmpty([])); // Output: true
console.log(isEmpty('')); // Output: true
console.log(isEmpty({ a: 1 })); // Output: false

andCheck

Performs a logical AND operation on two conditions.

Parameters:

• condition1: any - The first condition to check.
• condition2: any - The second condition to check.

Returns:

• any - The result of the logical AND operation.

Example:

import { andCheck } from 'hds-ui/utils';

const result = andCheck(true, false);
console.log(result); // Output: false

orCheck

Performs a logical OR operation between two conditions.

Parameters:

• condition: any - The first condition to check.
• condition2: any - The second condition to check.

Returns:

• any - The result of the logical OR operation.

Example:

import { orCheck } from 'hds-ui/utils';

const result = orCheck(true, false);
console.log(result); // Output: true

classNames

classNames Function to generate class names based on input arguments.

Parameters:

• args: any[] - Arguments to be processed. Can be a string or an object with keys as class names and values as booleans. If the value is true, the class name will be appended to the string, otherwise it will be ignored.

Returns:

• string - String of class names.

Example:

import { classNames } from 'hds-ui/utils';

const classes = classNames('btn', {
  'btn-primary': true,
  'btn-disabled': false,
});
console.log(classes); // Output: "btn btn-primary"

Exports

The utils/index.ts file exports the following functions:

• isNullOrUndefined
• ifElse
• isEmpty
• andCheck
• orCheck
• classNames

These functions can be imported and used in other parts of the application as needed.

Example:

import {
  isNullOrUndefined,
  ifElse,
  isEmpty,
  andCheck,
  orCheck,
  classNames,
} from 'hds-ui/utils';

Icons

To use icons from the lucide-react library in your components, you can use the following import statement:

import { IconName } from 'hds-ui/icons';

Replace IconName with the specific icon you want to import.

Example:

Here's an example of how you can use the imported icon in Markdown:

import { Search } from 'hds-ui/icons';

<Search />;

Remember to replace IconName with the actual icon name you want to use.

Reference for all Icons

Stroke width is to be 1.5px in all Icons

Charts

• All Chart related packages are being export in 'hds-ui/charts'
• Chart from 'chart-js' is exported as 'Chart'
• Chart from 'react-chartjs-2' is exported as 'ReactChart'
• All other components from both libraries are exported without any changes to their declaration

Styles

• Colors.scss
• index.scss

Example

@use 'hds-ui/styles/colors.scss' as color;

selector {
  background-color: color.$black;
}

App.tsx;

import 'hds-ui/styles/index.scss';