Eworldes-ui-toolkit NPM

Eworlds-ui-toolkit

🚀 eworlds-ui-toolkit: A React-based UI component library designed specifically to build and manage CSS (Child Support Services) portal with a focus on modern, accessible, and customizable UI components.

Introduction

The eworlds-ui-toolkit is crafted to streamline the development of CSS (Child Support Services) portal by providing reusable, customizable, and highly flexible components. It extends Material-UI (MUI) to allow for an enhanced design system that is tailored for internal tools, dashboards, and web applications. This toolkit simplifies UI development by ensuring design consistency, accessibility, and ease of customization.

It includes pre-designed layouts, essential UI components, and a unified theme system to keep the UI cohesive across the portal. By leveraging hooks and context utilities, it ensures an efficient and organized way to manage the state and interactions within the portal, ultimately improving the developer and user experience.

Key Features

Customizable Components: The toolkit builds on MUI’s powerful theming and customization capabilities, providing easy-to-use components that can be tailored to your internal portal's unique design requirements.
Prebuilt Layouts & Custom Components: Includes commonly used layouts and custom UI elements like modals, tables, forms, and navigation components—designed to speed up development for internal portal features.
Unified Theme System: Ensures consistent styling and design across the portal by using a centralized theme system, making design changes easier to apply.
Utility Hooks & Contexts: Custom React hooks and context utilities help manage state and component interactions in an efficient and scalable way, making it easier to develop complex portal functionalities.
Responsive: The components are fully responsive, offering a smooth user experience on all devices, from desktops to mobile screens.

Purpose

Extend and Customize MUI: Enhance MUI’s base components with additional customization options to cater to the needs of internal portal development.
Prebuilt Layouts & Components: Provide a suite of ready-made components and layouts for developers, speeding up the creation of CSS portals with common internal tool features.
Design Consistency: Foster a consistent look and feel across the entire portal by using a unified theme system and standardized components.
Simplify Development: Enable a faster, more efficient development process with utility hooks, context utilities, and pre-built components tailored for portal development.
Promote Best Practices: Encourage the adoption of best practices in accessibility, design, and performance, while offering flexible customization to meet your portal’s specific requirements.

By utilizing eworlds-ui-toolkit, developers can quickly create and maintain a high-quality, scalable, and visually consistent CSS portal with minimal effort.

Library & Dependencies

Core Dependencies

React: ^18.2.0
React is the foundation for building UI components and managing component state.
Material-UI (MUI):
- @mui/material: ^6.2.1
- @mui/icons-material: ^6.3.0
- @mui/lab: 6.0.0-beta.22
- @mui/x-data-grid: ^7.23.5
- @mui/x-date-pickers: ^7.23.3
  MUI is the core design system used in eworlds-ui-toolkit, providing the base UI components and design patterns for building modern web apps.
Styled Components: ^6.0.7
A library for writing CSS in JavaScript, enabling a styled-component approach for styling your application.
@emotion/react: ^11.14.0
A library for writing CSS styles in JavaScript, commonly used with MUI for styling purposes.
@emotion/styled: ^11.14.0
Provides a styled component API for defining and using CSS styles.
React Router DOM: ^7.1.1
A library for managing navigation and routing in React applications.
React Big Calendar: ^1.17.1
A flexible calendar component for React, supporting event handling and display.
@iconify/react: ^5.1.0
A library for using icon sets in your React applications.

Development Dependencies

Storybook:
- @storybook/react: ^7.4.1
- @storybook/addon-essentials: ^7.4.1
- @storybook/addon-interactions: ^7.4.1
  Storybook is used for developing and testing UI components in isolation.
Testing Libraries:
- @testing-library/react: ^14.0.0
- @testing-library/jest-dom: ^6.1.3
- @storybook/testing-library: ^0.2.0
- vitest: ^0.34.4
  These libraries help with testing React components and ensuring UI quality.
ESLint & Prettier:
- eslint: ^8.49.0
- eslint-plugin-react: ^7.33.2
- eslint-plugin-react-hooks: ^4.6.0
- eslint-config-prettier: ^9.0.0
- eslint-plugin-prettier: ^5.0.0
- prettier: ^3.0.3
  These are used to enforce code quality standards and maintain consistent code formatting across the project.
TypeScript: ^5.2.2
A superset of JavaScript, TypeScript is used to add type safety to the project.
Vite: ^4.4.9
A build tool and development server for fast and optimized React applications.
Husky: ^8.0.3
A tool to manage Git hooks, ensuring that code is properly formatted and linted before committing.
Lint-staged: ^14.0.1
Runs linters on pre-commit staged files to ensure code quality before commits.

Peer Dependencies

react: ^18.2.0
react-router-dom: ^7.1.1
These are required by eworlds-ui-toolkit for compatibility with React and routing functionalities.

Additional Dependencies

date-fns: ^4.1.0
A library for date manipulation and formatting.
dayjs: ^1.11.13
A lightweight library for working with dates, often used as an alternative to Moment.js.
moment: ^2.30.1
A popular library for working with dates and times in JavaScript.
invariant: ^2.2.4
A small utility for throwing errors when conditions aren’t met, commonly used to enforce runtime conditions.
path-to-regexp: ^8.2.0
A utility to convert route patterns into regular expressions for routing purposes.
is-lite: ^1.2.1
A small utility to check the type of a value.

Installation

npm install eworlds-ui-toolkit
# or
yarn add eworlds-ui-toolkit
# or
pnpm add eworlds-ui-toolkit

Usage

Import Components

import { Button } from 'eworlds-ui-toolkit';

const App = () => (
  <Button variant="contained">Click Me</Button>
);

Developer Guide

Getting Started

Clone the repository:

git clone ./eworlds-ui-toolkit.git
cd eworlds-ui-toolkit

Install dependencies:

pnpm install

Start the development server:

pnpm dev

Run Storybook:

pnpm storybook

Testing

Run tests:

pnpm test

Building the Library

Build for production:

pnpm build

Publishing

Publish the package to npm:

npm publish

Technical Design Structure

Project Structure

src/
├── assets       # Static assets (images, icons, etc.)
├── components   # Core, Layout, and Custom components
├── context      # React context providers
├── enums        # Enumerations for constants
├── helpers      # Utility functions
├── hooks        # Custom React hooks
├── themes       # Theme configurations
├── types        # TypeScript type definitions
├── utils        # Shared utility functions
└── index.ts     # Entry point for the library

Core Components

Layout Components

Additional Components

Component Documentation

Accordion

The Accordion component provides a way to display collapsible content panels for presenting information in a limited space.

AccountMenu

The AccountMenu component is a dropdown menu typically used for user account-related actions.

Alert

The Alert component is used to display feedback messages to the user.

Autocomplete

The Autocomplete component provides a user-friendly way to input text with suggestions.

Avatar

The Avatar component is used to display a user’s profile picture or an icon.

Badge

The Badge component displays a small badge to provide additional information, like a notification count.

Box

The Box component acts as a wrapper to apply layout and styling.

Breadcrumbs

The Breadcrumbs component displays a navigation path to indicate the user’s location.

Button

The Button component triggers an action or event when clicked.

CalendarEvent

The CalendarEvent component displays event details in a calendar layout.

Card

The Card component is used to display content and actions related to a single subject.

Checkbox

The Checkbox component allows users to select one or more options.

Chip

The Chip component represents an item or attribute, often with actions or states.

CircularProgress

The CircularProgress component indicates loading progress in a circular form.

Collapse

The Collapse component allows content to expand and collapse with an animation.

Container

The Container component is a layout component for structuring content.

Dashboard

The Dashboard component serves as a main interface to display metrics and information.

DataTable

The DataTable component is used for displaying data in a tabular format.

Datepicker

The Datepicker component allows users to select dates using an intuitive interface.

DialogComp

The DialogComp component displays modal dialogs for interaction.

Divider

The Divider component is used to separate content with a line.

Drawer

The Drawer component slides in content from the side of the screen.

Footer

The Footer component is used to display information at the bottom of the page.

FormControl

The FormControl component provides context for form inputs.

FormControlLabel

The FormControlLabel component combines a label with a control, such as a checkbox.

FormHelpText

The FormHelpText component provides additional help text for a form field.

Grid

The Grid component provides a flexible layout system for arranging elements.

Header

The Header component is typically used for the top navigation or branding area.

Icon

The Icon component displays a graphic symbol or glyph.

IconButton

The IconButton component is a button with an icon inside.

IconifyIcon

The IconifyIcon component is used for scalable vector icons.

InputLabel

The InputLabel component is used to label input fields.

InputWrapper

The InputWrapper component is used to style and position input elements.

LanguageMenu

The LanguageMenu component is used for language selection.

LinearProgress

The LinearProgress component indicates progress in a horizontal bar.

Link

The Link component is used for navigation between pages or sections.

List

The List component displays a list of items.

MenuItem

The MenuItem component represents a single item within a menu.

Modal

The Modal component displays content in a modal overlay.

PageLoader

The PageLoader component shows a loading indicator for pages.

Pagination

The Pagination component handles navigation between paginated content.

Paper

The Paper component provides a surface for content with shadows.

Radio

The Radio component allows users to select one option from a set.

ReadonlyField

The ReadonlyField component displays information that cannot be edited.

Schedular

The Schedular component handles event scheduling.

SectionWizardView

The SectionWizardView component displays multi-step wizards for workflows.

Select

The Select component provides a dropdown for selecting options.

SidebarNavigation

The SidebarNavigation component displays a collapsible navigation menu.

Snackbar

The Snackbar component displays brief messages at the bottom of the screen.

Stack

The Stack component arranges elements in a vertical or horizontal stack.

Statistics

The Statistics component displays statistical metrics or insights.

Stepper

The Stepper component displays progress through a sequence of steps.

StyledButton

The StyledButton component is a customizable button with extended styling options.

SwipeableDrawer

The SwipeableDrawer component provides a drawer that can be swiped open or closed.

Tabs

The Tabs component organizes content into separate views using a tabbed navigation system.

TextField

The TextField component is used to input and edit text.

Timeline

The Timeline component visually represents a sequence of events in chronological order.

Toggle

The Toggle component is a switch to toggle between two states.

Toolbar

The Toolbar component is used to organize and display actions and controls at the top of a page or section.

Tooltip

The Tooltip component displays additional information when hovering over an element.

Typography

The Typography component is used to style and display text elements.

Context

Overview

The context directory contains React Context Providers used for managing and sharing state or configurations across the application. Context is useful for avoiding prop drilling and ensuring a unified state management approach.

Key Contexts:

ThemeContext: Provides theme-related information.
AuthContext: Manages user authentication state.
LanguageContext: Handles localization and language selection.

Example Usage

ThemeContext

import { ThemeProvider, useTheme } from 'eworlds-ui-toolkit';

const App = () => {
  const theme = useTheme();
  return (
    <ThemeProvider>
      <div style={{ backgroundColor: theme.palette.background.default }}>
        Hello, World!
      </div>
    </ThemeProvider>
  );
};

AuthContext

import { AuthProvider, useAuth } from 'eworlds-ui-toolkit';

const App = () => {
  const { user, login, logout } = useAuth();
  return (
    <AuthProvider>
      <div>
        {user ? (
          <button onClick={logout}>Logout</button>
        ) : (
          <button onClick={() => login('username', 'password')}>Login</button>
        )}
      </div>
    </AuthProvider>
  );
};

Enums

The enums directory defines a set of enumerations to ensure consistency and maintainability when working with constant values throughout the library. Enums help avoid hardcoding values and provide meaningful labels to code constructs.

Key Enums:

ThemeModes: Defines the possible theme modes (e.g., light, dark).
UserRoles: Lists various user roles in the application.
HttpStatusCodes: Enum for HTTP response status codes.
ButtonVariants: Defines the button styling variants.
Status: Represents an entity's current state (e.g., Active, Inactive).
YesNo: Represents binary yes/no options (e.g., Yes, No).

Example Usage

Status Enum

The Status enum is used to represent an entity's current state, such as whether it's active or inactive.

import { Status } from 'eworlds-ui-toolkit';

const userStatus = Status.Active;

const App = () => (
  <div>
    User is currently: {userStatus}
  </div>
);

import { YesNo } from 'eworlds-ui-toolkit';

const answer = YesNo.Yes;

const App = () => (
  <div>
    Answer: {answer}
  </div>
);

Helpers

The helpers directory contains utility functions that provide commonly used functionality across the application. These helpers improve code reusability and maintainability by centralizing logic that might otherwise be repeated throughout the project.

Key Helpers:

async.ts: Contains utility functions for handling asynchronous operations such as promises and async/await patterns.
codec.ts: Includes functions for encoding and decoding data, such as Base64 or JSON encoding.
navigation.ts: Provides functions for navigation-related tasks, such as routing or managing the browser history.
pxTorem.ts: A utility for converting pixel values to rem units, making it easier to manage responsive typography and layout.
storage.ts: Includes functions for managing data stored in the browser's localStorage or sessionStorage.
xhrApi.ts: Contains functions for making XMLHttpRequest (XHR) or fetch-based API calls to interact with backend services.

Example Usage

async.ts

The async.ts file includes functions for working with asynchronous operations.

import { delay } from 'eworlds-ui-toolkit/helpers/async';

const fetchData = async () => {
  await delay(1000); 
  console.log('Data fetched');
};

fetchData();

import { encodeBase64, decodeBase64 } from 'eworlds-ui-toolkit/helpers/codec';

const encoded = encodeBase64('Hello, World!');
console.log(encoded); 

const decoded = decodeBase64(encoded);
console.log(decoded);

import { navigateTo } from 'eworlds-ui-toolkit/helpers/navigation';

const goToHomePage = () => {
  navigateTo('/home');
};

import { pxToRem } from 'eworlds-ui-toolkit/helpers/pxTorem';

const remValue = pxToRem(16);
remValue //1rem

import { setItem, getItem } from 'eworlds-ui-toolkit/helpers/storage';

setItem('user', { name: 'John Doe' });
const user = getItem('user');
console.log(user);

import { getRequest, postRequest } from 'eworlds-ui-toolkit/helpers/xhrApi';

const fetchData = async () => {
  const data = await getRequest('https://api.example.com/data');
  console.log(data);
};

const sendData = async () => {
  const response = await postRequest('https://api.example.com/data', { name: 'John' });
  console.log(response);
};

Hooks

The hooks directory contains custom React hooks that provide reusable logic for common functionality. These hooks allow you to encapsulate logic in a clean and manageable way, promoting code reuse and simplifying component development.

Key Hooks:

useActivePage: A hook that tracks the active page or route in your application.
useCreateTheme: A hook for creating and managing custom themes in your application.
useLocalStorage: A hook that simplifies interacting with the browser's localStorage API.
usePrevious: A hook that tracks the previous value of a given state or prop.
useStorageState: A hook that manages state with support for localStorage or sessionStorage persistence.
useTimeout: A hook that allows you to handle timeouts and intervals easily.
useUpdateEffect: A hook that runs an effect only when a specific value changes, similar to useEffect but skipping the initial render.

Example Usage

useActivePage

The useActivePage hook tracks the current active page in your application.

import { useActivePage } from 'eworlds-ui-toolkit/hooks';

const App = () => {
  const activePage = useActivePage();
  
  return <div>Current Page: {activePage}</div>;
};

Themes

The Themes section in the eworlds-ui-toolkit provides a convenient wrapper component for managing and applying available themes in your application. The toolkit includes pre-defined themes that help maintain a consistent look and feel across your entire app, supporting both light and dark modes.

Available Themes

The eworlds-ui-toolkit offers predefined themes that you can easily apply using the ThemeProvider component. These themes are designed to work seamlessly with Material-UI components, ensuring a cohesive design system.

Light Theme

The light theme is designed with brighter backgrounds and darker text colors, making it ideal for well-lit environments. It uses a set of colors and typography styles that work well for general use, offering excellent legibility and a clean, modern look.

Dark Theme

The dark theme is optimized for low-light environments, using darker backgrounds and lighter text colors to reduce eye strain. It’s perfect for users who prefer a dark mode experience, especially on devices with OLED screens where battery life can be improved.

Using the ThemeProvider

To apply a theme globally to your application, you can use the ThemeProvider component. This component is imported from eworlds-ui-toolkit and allows you to wrap your app with the chosen theme, ensuring that all Material-UI components and custom components use the provided styles.

Example Usage:

import { ThemeProvider } from 'eworlds-ui-toolkit';
import { lightTheme } from 'eworlds-ui-toolkit'; 

const App = () => (
  <ThemeProvider theme={lightTheme}> {/* Or darkTheme */}
    <YourComponent />
  </ThemeProvider>
);

Types

The Types section in eworlds-ui-toolkit defines TypeScript type definitions to ensure type safety and improve the developer experience when using the library. These types are used throughout the toolkit and help to enforce consistency, reduce errors, and improve autocompletion and documentation.

Purpose of Types

Types are crucial in large-scale applications as they:

Provide type safety across the codebase.
Help developers understand the structure and expected values for various objects.
Improve maintainability by enforcing consistent interfaces and reducing bugs.

The eworlds-ui-toolkit provides a set of reusable types that can be used across different components, hooks, and utilities.

Utils

The Utils section in eworlds-ui-toolkit provides a collection of utility functions and helpers that simplify common tasks in JavaScript and TypeScript development. These utility functions are designed to reduce boilerplate code, improve code readability, and boost productivity by providing solutions to frequently encountered problems.

Purpose of Utils

Utility functions are essential in software development because they:

Encapsulate repetitive logic into reusable functions.
Reduce the risk of introducing errors by providing well-tested and standardized solutions.
Enhance code readability and maintainability by abstracting complex operations.

The eworlds-ui-toolkit offers a wide range of utilities to assist with tasks like working with dates, managing state, manipulating strings, and handling arrays. These utilities can save time and effort when writing code.

@emotion/react @emotion/styled @hookform/resolvers @iconify/react @mui/icons-material @mui/lab @mui/material @mui/x-data-grid @mui/x-date-pickers invariant is-lite path-to-regexp react-big-calendar react-hook-form yup

3 months ago

4 months ago

4 months ago

4 months ago

5 months ago

5 months ago

5 months ago

5 months ago

5 months ago

5 months ago

5 months ago

5 months ago

5 months ago

6 months ago

6 months ago

Eworlds-ui-toolkit

Introduction

Key Features

Purpose

Library & Dependencies

Core Dependencies

Development Dependencies

Peer Dependencies

Additional Dependencies

Installation

Usage

Import Components

Developer Guide

Getting Started

Testing

Building the Library

Publishing

Technical Design Structure

Project Structure

Table of Contents

Core Components

Layout Components

Additional Components

Component Documentation

Accordion

AccountMenu

Alert

Autocomplete

Avatar

Badge

Box

Breadcrumbs

Button

CalendarEvent

Card

Checkbox

Chip

CircularProgress

Collapse

Container

Dashboard

DataTable

Datepicker

DialogComp

Divider

Drawer

Footer

FormControl

FormControlLabel

FormHelpText

Grid

Header

Icon

IconButton

IconifyIcon

InputLabel

InputWrapper

LanguageMenu

LinearProgress

Link

List

Menu

MenuItem

Modal

PageLoader

Pagination

Paper

Radio

ReadonlyField

Schedular

SectionWizardView

Select

SidebarNavigation

Snackbar

Stack

Statistics

Stepper

StyledButton

SwipeableDrawer

Tabs