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
  • IconTile
  • Tag
  • SearchBar
  • Timeline
  • Toaster
  • CollapsibleCard
  • StepperForm
  • WeeklyCalender

• 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.

tooltipProps: PopoverProps (optional)

Props for the popover if needed to be sent

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}
    tooltipProps={{
      placement: 'right',
    }}
    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<OptionType> (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: number | string | bigint

The key of the currently active navigation option.

onMenuCLick: (key: number | string | bigint, label: string) => void (Optional)

Function to be triggered when the sidenav is clicked

subMenuPopoverPosition: top | left | right | bottom | topLeft | topRight | bottomLeft | bottomRight | leftTop | leftBottom | rightTop | rightBottom; (Default: rightTop)

Position of the subMenu popover to be shown

OptionType

key: number | string | bigint;

Unique key for each option, Used to highlight active key

icon: React.ReactNode;

Icon for each option

label: string (Optional);

Label for each option

onClick: (MouseEventHandler) => void (Optional When subMenu is passed)

OnClick Function for Each option provided

subMenu: Array<{ label: string, onClick: MouseEventHandler}>

SubMenu to be shown on Hovering the option with 2 required fields, Will also trigger the onMenuClick with the option's key

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}
/>;

IconTile

The IconTile component is a React component that displays a tile with an icon. The icon can be positioned either at the left bottom or right bottom of the tile.

IconTileProps

icon: React.ReactNode

The icon to be displayed within the tile.

children: React.ReactNode

The content to be displayed inside the tile.

iconPosition: string

The position of the icon within the tile. Possible values include 'leftBottom' and 'rightBottom'. Default is 'rightBottom'

className: string

Additional CSS classes to apply to the tile. Default: ''

...restProps: React.HTMLAttributes<HTMLDivElement>

Any other props will be passed down to the Tile component.

Example Usage

import React from 'react';
import { IconTile } from 'hds-ui/components';
// OR
import IconTile from 'hds-ui/components/IconTile';
import Icon from 'hds-ui/icons';

<IconTile icon={<Icon name="heart" />} iconPosition="leftBottom">
  This is the content of the IconTile.
</IconTile>;

Tag

The Tag component is a custom tag component that extends the Tag component from Ant Design. It allows for additional customization such as background color, text color, and custom class names. It also retains CheckableTag within it from the Ant Design.

TagProps

bgColor: string

The background color of the tag.

color: string (Overidden Antd's Tag's color prop)

The text color of the tag.

className: string

Additional class name for the tag. Default is ''

children: React.ReactNode

The content of the tag.

icon: React.ReactNode

Icon to display, Suggested Size for Icons would be 15

...restProps: React.HTMLAttributes<HTMLSpanElement>

Any other props will be passed down to the antd Tag component.

More Info

Example

<Tag bgColor="blue" color="white">
  Tag Text
</Tag>

SearchBar

The SearchBar component is a reusable search input field with an integrated search icon in the placeholder. It is built using React and Ant Design's Input component.

SearchBarProps

onSearch : (value: string, event: React.KeyboardEvent<HTMLInputElement>) => void

Function triggered on pressing enter

Example

<SearchBar placeholder="Search..." onSearch={() => {}} />

Timeline

The Timeline component is designed to display a list of items in a vertical timeline format. It allows for customization of the timeline's size and the individual items within it.

TimelineProps

className: string (optional)

Optional CSS class name for the timeline component.

items: Array<{ icon?: React.ReactNode; bgColor?: #${string}; heading?: React.ReactNode; subHeading?: React.ReactNode; content?: React.ReactNode }>

Array of objects representing the timeline items. Each item object should have a title, description, and an icon property.

size: number

• Description: Size of the timeline and the items. This prop also determines the size of the icons within the timeline items.

Example

import { Icon } from 'hds-ui/icons';
import { Timeline } from 'hds-ui/components';
// OR
import Timeline from 'hds-ui/components/Timeline';

<Timeline
  className="custom-timeline"
  items={[
    {
      heading: 'Event 1',
      subHeading: 'Description 1',
      icon: <Icon name="event" size={24} />,
    },
    {
      heading: 'Event 2',
      subHeading: 'Description 2',
      icon: <Icon name="event" size={24} />,
    },
    {
      heading: 'Event 3',
      subHeading: 'Description 3',
      icon: <Icon name="event" size={24} />,
    },
  ]}
  size={24}
/>;

Toaster

The Toast is a collection of functions to show the toasters respectively

Below are the options which can be passed to the toast functions

ToastOptions

msg: string

The Main message to be shown in bold

desc: string (Optional)

The Description which will be shown beside the msg, Default is ''

showClose: Boolean (Optional)

Boolean variable to either show the close Icon or not, Default is true

action: { title: string, onClick: Function} | boolean (Optional)

Any action to be performed, The title for the same with onClick handlers, Default is false. No Action related content will be shown

Example

import {toast} from "hds-ui/components";
//OR
import toast from from "hds-ui/components/Toaster";

toast.info({
  msg: "Message Saved",
})

toast.success({
  msg: "Save Successfull!",
  desc: "Form Submitted",
})

toast.error({
  msg: "Upload Failed",
  action: {
    title: "Retry",
    onClick: () => {},
  }
})

CollapsibleCard

CollapsibleCardProps

title: ReactNode

The Title of the Collapsible Card

children: ReactNode (Optional)

The Content of the Collapsible Card

className: string

Classname for the component

expandIconPosition: 'left' | 'right' | 'start' | 'end' (Default: 'right')

The position of the Expand Icon

Example

<CollapsibleCard title="Card Heading">
  <p>Content Paragraph</p>
  <div> Some more Content </div>
</CollapsibleCard>

StepperForm

StepperFormProps

className: string

Classname for the Stepper Form

direction: horizontal | vertical (Default: 'vertical')

The way the stepper forms steps are shown

items: StepperFormStepProps

Array of Items for each step

onChange: (currentStep: number, formValues, allFormValues: Array) => void

Function called when the step is changed with the newStep, formValues of the step from which it was changed and Array of all formValues of all steps

stepProps: StepProps excluding direction, items, onChange

StepperFormStepProps

formProps: (form: FormInstance, goNext: Func, goPrev: Func, goTo: (step: number) => void) => FormProps (excluding form)

Function which has 4 arguments named above which returns an object with Form Props excluding form

renderForm: (form: FormInstance, option: { goNext: EventHandler, goPrev: EventHandler, goTo: (step: number) => void }) => ReactNode

Function which has 2 arguments which should return the content of the step, No need to wrap it in form as the StepperForm internally handles it

WeeklyCalender

WeeklyCalenderProps

className: string (Optional)

Classname for the calender

extra: ReactNode (Optional)

Extra Content to be shown in Right of Calender header

onEmptyClick: (hour: number, date: Date) => void

Function to be triggered when clicking on empty calender space, will get the hour 24hrs format and date of clicked space

date: Date (Optional)

Date to be passed to be utilized to set the date in week picker

onDateChange: (date: Date) => void

Function to be triggered when there is week change

hightlightToday: boolean (Optional) Default: false

Boolean value to whether highlight today in the WeeklyCalender

popUpRender: (event: any) => ReactNode

Function which recieves the event passed in items props to render content inside the popup on clicking an event

popoverProps: PopoverProps of Antd except overlayClassName

Object having all props other than overlayClassName for the popover of the events

items: ItemType[]

List of events

ItemType

title: string

Title of the event

startTime: Date

Start Time of the event in Date format

endTime: Date

End time of the event in Date Format

date: Date

Date of the event

className: string (Optional)

Classname for the event container

Others

It can be any key value pair which will be send back in popUpRender as the event

Example

<WeeklyCalender
  onEmptyClick={(hour, date) => {
    console.log('doubt clicked', date, hour);
  }}
  items={[
    {
      endTime: new Date('09-18-2024 12:00'),
      startTime: new Date('09-18-2024 11:00'),
      date: new Date('09-18-2024'),
      title: 'Sample Event',
    },
    {
      endTime: new Date('09-18-2024 11:30'),
      startTime: new Date('09-18-2024 11:00'),
      date: new Date('09-18-2024'),
      title: 'Sample Event 2',
    },
    {
      endTime: new Date('09-18-2024 11:45'),
      startTime: new Date('09-18-2024 11:15'),
      date: new Date('09-18-2024'),
      title: 'Sample Event 2',
    },
    {
      endTime: new Date('09-18-2024 18:00'),
      startTime: new Date('09-18-2024 17:00'),
      date: new Date('09-18-2024'),
      title: 'Sample Event 3',
    },
    {
      endTime: new Date('09-15-2024 13:00'),
      startTime: new Date('09-15-2024 10:00'),
      date: new Date('09-15-2024'),
      title: 'Sample Event ',
    },

    {
      endTime: new Date('09-16-2024 12:00'),
      startTime: new Date('09-16-2024 10:00'),
      date: new Date('09-16-2024'),
      title: 'Sample Event ',
    },
    {
      endTime: new Date('09-16-2024 16:30'),
      startTime: new Date('09-16-2024 15:00'),
      date: new Date('09-16-2024'),
      title: 'Sample Event ',
    },
  ]}
  extra={<>Extra Content</>}
  highlightToday={true}
  popUpRender={(event) => <>PopOver content</>}
/>

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"

getProperty

getProperty Retrieves the value of a nested property from an object. If the object is empty or the property is not found, it returns the default value.

Parameters:

• obj: Object - The object to retrieve the property from.
• property: Array<string> - An array of strings representing the nested property path.
• defaultValue: any - The default value to return if the property is not found.

Returns:

• any - The value of the nested property or the default value.

Example:

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

const obj = {
  property1: {
    property2: {
      property2: 100,
    },
  },
};

const res1 = getProperty(obj, ['property1', 'property2', 'property3'], 0);
const res2 = getProperty(obj, ['property1', 'property2', 'property4'], 99);
console.log(res1); // Output: 100
console.log(res2); // Output: 99

Exports

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

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

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

Example:

import {
  isNullOrUndefined,
  ifElse,
  isEmpty,
  andCheck,
  orCheck,
  classNames,
  getProperty,
} 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';