@metromobilite/m-ui

M-UI

M-UI | M-THEME

M-UI is a component library built on top of Angular Material 19, designed to extend its capabilities while leveraging M-Theme for styling consistency. It provides:

• Ready-to-use Angular components tailored for specific use cases.
• An intuitive API for developers, enabling seamless integration.
• Theming support out-of-the-box, powered by M-Theme.

---

Motivation

While working on various projects, especially when building Angular applications, I noticed a common need for:

1. A unified theming system that simplifies the customization of Angular Material components.
2. A component library that goes beyond the basic Angular Material design system to meet specific business needs.

Other solutions often fell short:

• Writing custom themes manually was repetitive and prone to errors.
• Extending Angular Material components often required complex configurations.
• Integrating theming and custom components into a single cohesive package was challenging.

M-Theme and M-UI address these gaps:

• M-Theme simplifies theming by centralizing styles, reducing repetitive code, and offering pre-built palettes and functions.
• M-UI extends Angular Material with additional components, allowing developers to create rich, feature-complete applications faster.

How does it work?

M-Theme

• Provides SCSS files for defining light and dark themes.
• Offers pre-configured variables and helper functions to make styling Angular Material components easier.
• Works seamlessly with Angular's build process, requiring only the addition of the necessary imports in your main SCSS file.

M-ui

• Built as a library of Angular components that extend Angular Material's functionality.
• Components are designed to be modular:
  • Import only the components you need or the entire library.
  • All components are styled consistently using M-Theme.
• Supports standalone usage and integration into existing Angular projects.

Peer dependencies

M-UI depends on Angular Material and Angular CDK. We need to install these dependencies before installing M-UI.

Peer Dependency	Version
@angular/common	19.1.5
@angular/cdk	19.1.5
@angular/core	19.1.5
@angular/material	19.1.5

Configuration/installation

Installing the Library

1. Install via npm

Run the following command to install the latest version of the library:

npm i @metromobilite/m-ui@latest

Configuration

M-Theme Setup

Step 1: Add stylePreprocessorOptions in angular.json

Note The stylePreprocessorOptions in angular.json allows you to define custom paths for Sass to search for files during @use or @import.

Adding 'includePaths': ['node_modules'] lets Sass resolve imports from node_modules directly, enabling simplified imports for libraries.

{
	"projects": {
		"project-name": {
			"architect": {
				"build": {
					"options": {
						"stylePreprocessorOptions": {
							"includePaths": ["node_modules"]
						}
					}
				}
			}
		}
	}	
}

---

Step 2: Add Assets in angular.json

To ensure that theme-related assets are properly loaded, include the following in the assets array of angular.json:

{
	"assets": [
		{
			"glob": "**/*",
			"input": "./node_modules/@metromobilite/m-ui/assets/",
			"output": "./assets/"
		}
	]	
}

---

Step 3: Import Styles in styles.scss

In your main SCSS file (e.g., src/styles.scss), import the M-Theme styles. You can choose to import all styles or only specific ones.

Import Styles

@use "@metromobilite/m-ui/Mtheme" as Mtheme;

:root{
	@include Mtheme.init();
}

---

M-UI Setup

Add Icon Assets in angular.json

To use the icon library provided by M-UI, include the following configuration in angular.json under the assets array:

{
	"assets": [
		{
			"glob": "**/*",
			"input": "node_modules/@metromobilite/m-ui/assets",
			"output": "/assets/"
		}
	]	
}

Usage

M-Theme

Importing Styles

Add this line in styles.scss to apply Material styles and colors:

@use "@metromobilite/m-ui/Mtheme" as Mtheme;

Note This: Loads the dark theme by default. Automatically switches to the light theme based on the user's system preferences (prefers-color-scheme: light). Applies Angular Material global styles and typography.

Initializing the Theme

Mtheme automatically handles theme switching based on:

html{
	@include Mtheme.init();
}

Note Testing the Installation

1. Ensure all configurations in angular.json are correctly applied.
2. Use the imported SCSS variables and functions in your components to verify that they work as expected.
3. If icons or assets aren't loading, double-check the assets array in angular.json.

Switching Themes Dynamically

Notes User preferences (dark mode is enabled by default)

Forcing Light/Dark Mode Add the .light or .dark class to the

element:

<body class="dark">
	<!-- Your content here -->
</body>

Customizing the Theme

If your application requires theme-specific styling for components, use @content inside the Mtheme.init() call.

Adding Custom Styles for Themed Components

Inject additional styles into Mtheme.init() as follows:

@include Mtheme.init() using($theme) {
	@include demo.all-component-themes($theme);
};

How to get current theme

Use the mat.get-theme-type() function to get the current theme type. This function returns either dark or light.

mat.get-theme-type($theme);

Exemple demo.all-component-themes($theme)

@mixin all-component-themes($theme) {
	$themeType: mat.get-theme-type($theme);
	
	// $themeType is dark or light
}

M-ui

All library components are prefixed with m- and are designed as standalone components.

<m-icons type="accident" class="m-icon"></m-icons>

Default import

We can import the entire library in our Angular module.

import {MIcons} from '@metromobilite/m-ui';

@NgModule({
  declarations: [AppComponent], 
  imports: [MIcons], 
  bootstrap: [AppComponent]
})
export class AppModule {}

Import unitary components

We can also import the components individually.

import {MIcons} from '@metromobilite/m-ui/m-icons';

Note Add this in your tsconfig.json

"compilerOptions": {
  "paths": {
    "@metromobilite/m-ui/*": [
      "node_modules/@metromobilite/m-ui",
      "node_modules/@metromobilite/m-ui/lib/*"
    ]
  } 
}

More docs

show more informations