# eWorldES-ui-toolkit ## License eWorldES Proprietary Software Copyright (C) 2025 eWorldES. All rights reserved. This software is proprietary to eWorldES and is protected by copyright laws and international treaties. You may not use, copy, modify, distribute, or disclose this software without explicit written permission from eWorldES. Any unauthorized use or reproduction of this software is strictly prohibited and may result in legal action. License Agreement: By using this software, you agree to be bound by the terms of the eWorldES Proprietary Software License Agreement. For a copy of the agreement, visit https://eworldes.com/ or contact eWorldES directly for more information. This software is provided "AS IS" without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, or non-infringement. In no event shall eWorldES be liable for any damages arising out of the use of this software, even if eWorldES has been advised of the possibility of such damages. For inquiries or requests regarding this software, please contact eWorldES at: - **Email:** info@eworldes.com - **Website:** https://eworldes.com/ 🚀 **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 ```sh npm install eworlds-ui-toolkit # or yarn add eworlds-ui-toolkit # or pnpm add eworlds-ui-toolkit ``` ## Usage ### Import Components ```tsx import { Button } from 'eworlds-ui-toolkit'; const App = () => ( ); ``` ## Developer Guide ### Getting Started Clone the repository: ```sh git clone ./eworlds-ui-toolkit.git cd eworlds-ui-toolkit ``` Install dependencies: ```sh pnpm install ``` Start the development server: ```sh pnpm dev ``` Run Storybook: ```sh pnpm storybook ``` ### Testing Run tests: ```sh pnpm test ``` ### Building the Library Build for production: ```sh pnpm build ``` ### Publishing Publish the package to npm: ```sh npm publish ``` ## Technical Design Structure ### Project Structure ```plaintext 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 ``` ## Table of Contents ### Core Components - [Accordion](#accordion) - [AccountMenu](#accountmenu) - [Alert](#alert) - [Autocomplete](#autocomplete) - [Avatar](#avatar) - [Badge](#badge) - [Box](#box) - [Breadcrumbs](#breadcrumbs) - [Button](#button) - [CalendarEvent](#calendarevent) - [Card](#card) - [Checkbox](#checkbox) - [Chip](#chip) - [CircularProgress](#circularprogress) - [Collapse](#collapse) - [Container](#container) - [Dashboard](#dashboard) - [DataTable](#datatable) - [Datepicker](#datepicker) - [DialogComp](#dialogcomp) - [Divider](#divider) - [Drawer](#drawer) - [Footer](#footer) - [FormControl](#formcontrol) - [FormControlLabel](#formcontrollabel) - [FormHelpText](#formhelptext) ### Layout Components - [Grid](#grid) - [Header](#header) - [Icon](#icon) - [IconButton](#iconbutton) - [IconifyIcon](#iconifyicon) - [InputLabel](#inputlabel) - [InputWrapper](#inputwrapper) - [LanguageMenu](#languagemenu) - [LinearProgress](#linearprogress) - [Link](#link) - [List](#list) - [Menu](#menu) - [MenuItem](#menuitem) - [Modal](#modal) - [PageLoader](#pageloader) - [Pagination](#pagination) - [Paper](#paper) - [Radio](#radio) - [ReadonlyField](#readonlyfield) - [Schedular](#schedular) - [SectionWizardView](#sectionwizardview) - [Select](#select) - [SidebarNavigation](#sidebarnavigation) - [Snackbar](#snackbar) - [Stack](#stack) - [Statistics](#statistics) ### Additional Components - [Stepper](#stepper) - [StyledButton](#styledbutton) - [SwipeableDrawer](#swipeabledrawer) - [Tabs](#tabs) - [TextField](#textfield) - [Timeline](#timeline) - [Toggle](#toggle) - [Toolbar](#toolbar) - [Tooltip](#tooltip) - [Typography](#typography) ## 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. ### Menu The `Menu` component displays a menu of actions or options. ### 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 ```tsx import { ThemeProvider, useTheme } from 'eworlds-ui-toolkit'; const App = () => { const theme = useTheme(); return (
Hello, World!
); }; ``` #### AuthContext ```tsx import { AuthProvider, useAuth } from 'eworlds-ui-toolkit'; const App = () => { const { user, login, logout } = useAuth(); return (
{user ? ( ) : ( )}
); }; ``` ## 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. ```tsx import { Status } from 'eworlds-ui-toolkit'; const userStatus = Status.Active; const App = () => (
User is currently: {userStatus}
); ``` ```tsx import { YesNo } from 'eworlds-ui-toolkit'; const answer = YesNo.Yes; const App = () => (
Answer: {answer}
); ``` ## Helpers ## 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. ```ts import { delay } from 'eworlds-ui-toolkit/helpers/async'; const fetchData = async () => { await delay(1000); console.log('Data fetched'); }; fetchData(); ``` ```ts import { encodeBase64, decodeBase64 } from 'eworlds-ui-toolkit/helpers/codec'; const encoded = encodeBase64('Hello, World!'); console.log(encoded); const decoded = decodeBase64(encoded); console.log(decoded); ``` ```ts import { navigateTo } from 'eworlds-ui-toolkit/helpers/navigation'; const goToHomePage = () => { navigateTo('/home'); }; ``` ```ts import { pxToRem } from 'eworlds-ui-toolkit/helpers/pxTorem'; const remValue = pxToRem(16); remValue //1rem ``` ```ts import { setItem, getItem } from 'eworlds-ui-toolkit/helpers/storage'; setItem('user', { name: 'John Doe' }); const user = getItem('user'); console.log(user); ``` ```ts 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. ```tsx import { useActivePage } from 'eworlds-ui-toolkit/hooks'; const App = () => { const activePage = useActivePage(); return
Current Page: {activePage}
; }; ``` ## 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: ```tsx import { ThemeProvider } from 'eworlds-ui-toolkit'; import { lightTheme } from 'eworlds-ui-toolkit'; const App = () => ( {/* Or darkTheme */} ); ``` ## Types ## 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.