M-UI

M-UI is a component library built on top of Angular Material 15, 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 | 15.2.0 | | @angular/cdk | 15.2.0 | | @angular/core | 15.2.0 | | @angular/material | 15.2.8 |

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/theme/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.

Option 1: Import All Styles

$assets-path: '/assets'; // Define the assets path
@use "@metromobilite/m-ui/theme/style";

Option 2: Import Specific Files

If you need more control over the imported styles, you can import them one by one:

@import 'reset';
@import 'variables';
@import 'font';
@import '@metromobilite/m-ui/theme/theme';
@import 'classes';
@import 'components/index';

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/src/assets",
			"output": "/assets/"
		}
	]	
}

Usage

M-Theme

To enable light or dark themes, add the dark-theme or light-theme class to the <body> tag in your index.html:

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

This theme provide custom palettes and provides the following variables:

• $light-theme-background
• $light-theme-foreground
• $dark-theme-background
• $dark-theme-foreground

Example:

.my-container {
  color: map-get($dark-theme-foreground, text);
}

Some helper functions are also provided:

• dark-color-overlay($elevation)
• light-color-overlay($elevation)

$elevation must be a value in [0, 1, 2, 3, 4, 6, 8, 12, 16, 24]

Example:

.my-container {
	background: dark-color-overlay(16);
}

Helper Functions and Variables

Variables

M-Theme provides pre-defined variables for customizing the look and feel of your app:

• $light-theme-background
• $light-theme-foreground
• $dark-theme-background
• $dark-theme-foreground

Example:

.my-container {
  color: map-get($dark-theme-foreground, text);
}

Helper Functions

Use helper functions for overlays and dynamic styles:

• dark-color-overlay($elevation)
• light-color-overlay($elevation)

Note $elevation must be one of [0, 1, 2, 3, 4, 6, 8, 12, 16, 24].

Example:

.my-container {
  background: dark-color-overlay(16);
}

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.

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