Mondra Visual / UI Components

• The motive of this project is to keep all Mondra branded Web UI elements and patterns together in single place and reduce the third party dependencies for each project under mondra umbrella.
• Which helps to maintain and scale easily across different projects.
• This helps each project to align with brand guidelines.
• This also helps to deliver new applications at much faster pace.

Pillers & Inspiration

• This project is primarily built using React, Typescript, Webpack, Pro - Tailwind CSS utitlity framework & Tailwind UI Component designs.
• However we as a team decided not to reinvent the wheel to create accessible web elements from scracth, well not everything but planned to built on top of tailwind org sponsored project called Headeless UI. This project is maintained under Tailwind labs and here is the link for the same Accessible React UI Components.
• Most of the components are custom built based on the best practices and follows the ux from Tailwind UI components.
• Each component is unit tested visually using Storybooks, Jest & React Testing library, which ensures code quality and consistency.
• This project also export default theme to outside world so that the consumers can extend the CSS framework based on the needs
• Yet to do theme enablement in future, We believe that is not too complex to include as we have got good back up from Tailwind CSS framework community.
• However we are not limited to the above UI component library, but always review the famous npm modules and include in this project and consume in actual web development.

Showcase - Play Ground

Mondra Web UI Storybook - Variaty of UI components, style guide is documented with live examples in here.

Design - UI / UX

The entire designs are custom made for mondra brand. All designs & style guides are available in figma web design tool. Below are some reference and there is huge chances that each page in figma rapidly changes :).

• https://www.figma.com/files/project/32463286/Foundation?fuid=770605902857213879
• https://www.figma.com/file/fsbeOpaGB7IIvboz2g1niG/Style-Guide
• https://www.figma.com/file/US1KZwqcRcjHnaZNSVjBcA/Product-Demo
• https://www.figma.com/file/bLCOy7YDStJJUbwlDdB7Ak/V2-Clac

Styling, CSS (from version 5.0.0)

We use Tailwind CSS v4 for styling.

Tailwind v4 introduces a faster, more modern approach to styling using native CSS features such as custom properties (CSS variables) and @layer. This eliminates the need for JavaScript-based runtime theming and enables better performance and flexibility.

Theme via CSS Variables

All theme values like colors, spacing, and font sizes are exposed as CSS variables in styles/theme.css under @theme directive. You can use them directly in your custom CSS:

.my-box {
  background-color: var(--color-primary-500);
  padding: var(--spacing-4);
}

Extending or Overriding Theme Values

To override or extend theme variables (like colors), you can use the @theme directive in your CSS:

@theme {
  --color-primary-500: #1e40af;
}

Or if you need to override theme variables under certain class

@layer base {
    .acme {
        --color-primary-50: #fffbeb;
        --color-primary-100: #fef3c7;
    }
}

Installation

npm i @mondra/ui-components --save

Usage

Here is a quick example to get you started, it's all you need:

import * as React from 'react'
import ReactDOM from 'react-dom'
import { Input } from '@mondra/ui-components'

function App() {
    return <Input placeholder="Sample mondra text input" />
}

ReactDOM.render(<App />, document.querySelector('#app'))

Contribute

Version Management & Release Strategy

Mondra team members can contribute to development of new components or modify existing components while maintaining multiple version lines for different project needs.

Current Version Lines

We maintain multiple version lines to support different project requirements:

1. Latest Version (main branch) - Current: v5.x.x

   • Latest features and breaking changes
   • Used by projects ready for upgrades (e.g., SaaS)

2. Legacy Version (v2.x.x-legacy branch) - Current: v2.x.x

   • Backward compatibility for older projects
   • Used by projects not ready for breaking changes (e.g., CorP)

3. Hotfix Versions - For critical fixes to older minor versions

   • Example: v5.2.17 hotfix when latest is v5.3.0

Publishing Strategy

For Latest Features (main branch):

npm publish  # Goes to "latest" tag (default install)

For Legacy Support (v2.x.x-legacy branch):

npm publish --tag legacy  # Install with: npm i @mondra/ui-components@legacy

For Hotfixes to Older Minor Versions:

npm publish --tag hotfix-5.2  # Install with: npm i @mondra/[email protected]
# or simply
npm publish  # Version available but doesn't change "latest" tag

Development Workflow

Latest Version Development (main branch):

• Create PR to main branch
• Features and bug fixes for current version
• Bump version appropriately (major.minor.patch)
• Publish with npm publish

Legacy Version Development (v2.x.x-legacy branch):

• Checkout to v2.x.x-legacy branch and create new branch from it
• Remove node_modules and reinstall (different package-lock.json)
• Create PR with legacy-compatible changes
• Bump minor or patch version under v2.x.x
• Build and publish with npm publish --tag legacy

Hotfix Development:

• Checkout to appropriate version branch or tag
• Apply critical fixes only
• Bump patch version (e.g., 5.2.16 → 5.2.17)
• Publish with appropriate tag strategy
• Consider backporting to main branch if applicable

Installation Guide for Consumers

# Latest version (default)
npm install @mondra/ui-components

# Legacy version (for older projects)
npm install @mondra/ui-components@legacy

# Specific hotfix version
npm install @mondra/[email protected]

# From hotfix tag
npm install @mondra/[email protected]

This strategy allows us to support multiple project timelines while maintaining a clear upgrade path.

Develop

• Clone components project from here - [email protected]/ProArchITSolutions/Mondra/_git/Mondra.UIComponents
• npm install in the root directoy
• npm run storybook:watch-css to see the all the components in action in local enviroment

• Checkout to your own branch feature/<branch-name> or bug/<branch-name> from main or master branch
• What are you waiting for :smile: , go ahead and do some JSX, update any component or add new component to src/components directory
• Write stories for the respective component in *.stories.js|ts file
• Add tests
• Update CHANGELOG.md
• Bump the version appropriately in package.json X.X.X - Major.Minor.Patch
• Once changes are commit & complete the PR with title matching above version number. Also include storybook screenshot related to changes

Add Icons

• Create a folder svgs under scripts
• Find the svg icon in https://www.figma.com/design/ifsZuF4IVvO86CjWK9dIBO/A.-Mondra-Design-Elements?node-id=1-32
• Export the svg icon or Place all the svg files in the above folder, must follow files names as x.svg or x-y.svg or x-y-z.svg
• Plan is to add the default to add 16px viewbox.
• run command in the root folder node scripts/generatePaths.js
• run command npm run formatter
• verify the pending changes before you commit

Build

Now master branch is upto date as per latest features or bug fixes

• npm run build -- Build the binaries
• npm publish -- This will publish the latest version of the library into npmjs.com or
• npm run publish-lib -- which will do same as above

Publishing a Beta Version

To publish a beta version of your package, follow these steps:

1. Update the Version: Ensure your package.json includes a version with a -beta suffix (or similar). For example:

   {
       "version": "1.0.0-beta.1"
   }

2. Publish the Beta Version: Use the following command to publish the package under the beta tag:

   npm publish --tag beta

   This ensures that the beta version will not be installed by default when users run npm install, unless they explicitly request it.

3. Verify the Published Version: After publishing, you can verify the published version using:

   npm info @mondra/ui-components

4. Additional notes:

• To update the beta version, increment the version number (e.g., 1.0.0-beta.2) and run the npm publish --tag beta command again.
• Once you're ready to release the stable version, simply publish without the --tag flag:

  npm publish

Test

Each component must have set of unit tests to confirm the user experience & behaviour. Unit tests are run using Jest runner & @testing-library/react is used for tests which has gread dom testing utils API and also by extends jest API.

• npm run test -- Verifies all unit test cases
• npm run test:watch -- To run tests while development mode

Code smells & formatting

Each typescript, react component file is being validated or formatted before the git commit. EsLint & Prettier are doing their job to keep code validated, formatted uniform across development team. Husky adds more features on top of git commands to achieve this.

• git commit -am "Check what happens" -- This runs both eslint & prettier formatting before commiting changes

Lint

This project uses @mondra/code-format-config library which defines some set of rules in ESLint and Prettier. These rules should be passed before you can commit any code.

Developer can use rvest.vs-code-prettier-eslint extension in VS-Code which will auto-format the file and fix most of the list related issues automatically.

Translated Labels Approach

If you use any labels or text in your component, please follow this approach:

• Add unified optional labels prop to your component:

labels?: IEmissionOvertimeLabels

• Add defaults labels and export type for those labels to meet correct structure

const DEFAULT_LABELS = {title: 'Emissions', leftAxisLabel: 'CO₂ eq.'}, tooltip: {}, legend: {}
export type IEmissionOvertimeLabels = typeof DEFAULT_CHART_LABELS

• Use in the component like {labels.chart.title}
• When importing the component in client application provide translated labels by extracting translation file with the same structure

t('namespace', { returnObjects: true })

Potential issues while developing apps

• Issues with hooks when lib used in the react app, could be because of the multiple react instances running when we use npm link. This needs to be addressed

License

See in LICENSE.md