ui-material-angular-six

UI Material theming & style foundation for Angular applications

Goals

• Centralize styling + light behavior overrides for Angular Material across all SIX Group apps.
• Avoid wrapping every component: use native Angular Material API; only override tokens / CSS.
• Provide future extension point for a limited set of custom logic components if required.

Key Principles

• Functional providers (no NgModule boilerplate) via provideSixUiMaterial().
• Feature-first & minimal: this package only exposes what apps need globally.
• Zoneless-friendly: package does not depend on Zone.js.

Installation

npm install ui-material-angular-six

Usage

Step 1: Application Bootstrap (TypeScript)

Import the global provider in your application bootstrap (e.g. main.ts or app.config.ts):

import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app/app.component';
import { provideSixUiMaterial } from 'ui-material-angular-six';
import { provideAnimations } from '@angular/platform-browser/animations';

bootstrapApplication(AppComponent, {
  providers: [
    provideAnimations(), // or provideNoopAnimations() if desired
    provideSixUiMaterial({ 
      disableRipples: false // Optional: disable Material ripple effects
    })
  ]
});

Step 2: Configure Styles

You have two approaches for Material 3 theming:

Approach A: angular.json + styles.scss (Recommended - M3 Best Practice)

1. Add tokens to angular.json:

"styles": [
  "src/styles.scss",
  "ui-material-angular-six/tokens.scss"
],

2. Then in your styles.scss:

@use 'ui-material-angular-six/styles/theme' as theme;
@use 'ui-material-angular-six/styles' as six;

// Must wrap in html selector (Material 3 requirement)
html {
  // Apply theme
  @include theme.six-apply-m3-theme();

  // Apply component overrides
  @include six.six-material();
}

html, body { 
  height: 100%; 
  margin: 0; 
}

Approach B: All-in-One in styles.scss (Simpler)

// styles.scss
@use 'ui-material-angular-six/styles' as six;

// Must wrap in html selector (Material 3 requirement)
html {
  @include six.six-material-full();
}

html, body { 
  height: 100%; 
  margin: 0; 
}

Approach C: Granular Control

// styles.scss
@use 'ui-material-angular-six/styles/theme' as theme;
@use 'ui-material-angular-six/styles' as six;

// Must wrap in html selector (Material 3 requirement)
html {
  // 1. Apply Material 3 theme (colors, typography, density)
  @include theme.six-apply-m3-theme();

  // 2. Apply SIX component overrides (buttons, form fields, tables)
  @include six.six-material();
}

html, body { 
  height: 100%; 
  margin: 0; 
}

Approach D: Theme Only (Custom overrides)

// styles.scss
@use 'ui-material-angular-six/styles/theme' as theme;

// Must wrap in html selector (Material 3 requirement)
html {
  // Apply only the Material 3 theme
  @include theme.six-apply-m3-theme();
}

// Add your own custom overrides here
.my-custom-button {
  border-radius: 0;
}

Step 3: Using Components

SIX Form Field with Auto-Clear

The library provides a form field component with automatic clear button:

// In your component
import { SixFormFieldComponent } from 'ui-material-angular-six';

@Component({
  standalone: true,
  imports: [SixFormFieldComponent, ReactiveFormsModule],
  // ...
})

<!-- Basic usage -->
<six-form-field label="Client" formControlName="client"></six-form-field>

<!-- With placeholder -->
<six-form-field 
  label="Search" 
  placeholder="Enter search term"
  formControlName="search">
</six-form-field>

<!-- With search icon (shows search icon when empty, clear button when filled) -->
<six-form-field 
  label="Search" 
  placeholder="Type to search"
  [showSearchIcon]="true"
  formControlName="search">
</six-form-field>

<!-- Different input types -->
<six-form-field label="Email" type="email" formControlName="email"></six-form-field>
<six-form-field label="Password" type="password" formControlName="password"></six-form-field>

Features:

• ✅ Auto-clear button when field has value
• ✅ Optional search icon when field is empty
• ✅ Works with Reactive Forms (formControlName)
• ✅ Respects disabled state
• ✅ Supports all input types (text, email, password, etc.)
• ✅ Full Material Design styling

Step 4: Using Brand Color Utilities

The library provides utility classes for all SIX brand colors that work with any Material button type:

<!-- Primary -->
<button mat-raised-button class="six-btn-primary">Primary</button>
<button mat-outlined-button class="six-btn-primary">Primary Outlined</button>

<!-- Secondary -->
<button mat-raised-button class="six-btn-secondary">Secondary</button>

<!-- Tertiary -->
<button mat-raised-button class="six-btn-tertiary">Tertiary</button>

<!-- Other brand colors -->
<button mat-raised-button class="six-btn-neutral">Neutral</button>
<button mat-raised-button class="six-btn-highlight">Highlight</button>
<button mat-raised-button class="six-btn-success">Success</button>

<!-- Convenience classes for outlined variants -->
<button class="six-btn-outline-success">Success Outlined</button>
<button class="six-btn-outline-highlight">Highlight Outlined</button>

Advanced: Using Brand Colors in Custom Components

Import brand colors directly in your component styles:

// my-component.component.scss
@use 'ui-material-angular-six/styles/colors' as colors;

.my-custom-element {
  background-color: colors.$six-primary;
  border: 1px solid colors.$six-secondary;
  color: colors.$six-tertiary;
}

Package Exports

The library provides multiple entry points for flexibility:

// Main entry - component overrides
@use 'ui-material-angular-six/styles';

// Material 3 theme configuration
@use 'ui-material-angular-six/styles/theme';

// Design token overrides (advanced)
@use 'ui-material-angular-six/styles/tokens';

// Brand color variables
@use 'ui-material-angular-six/styles/colors';

Migration from Legacy Themes

If you're migrating from Angular Material's prebuilt themes:

1. Remove prebuilt theme imports:

   // ❌ Remove this
   @import '@angular/material/prebuilt-themes/indigo-pink.css';

2. Use this theme instead:

   // ✅ Add this
   @use 'ui-material-angular-six/styles' as six;
   @include six.six-material-full();

3. Update color references:

   • Replace color="primary" with class="six-btn-primary" for custom colors
   • Standard color="primary" still works with theme

Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)
• Supports all modern browsers with CSS custom properties

Requirements

• Angular 17+ (tested up to Angular 20)
• Angular Material 17+ (Material 3 support)
• Sass 1.70+
• TypeScript 5.0+

Architecture & Best Practices

Component Structure

All components in this library use inline templates and styles (no separate .html or .scss files). This is the recommended approach for Angular libraries because:

✅ Cross-platform compatibility - No build script dependencies on OS-specific commands
✅ Simpler distribution - TypeScript compiler handles everything automatically
✅ Type safety - Template expressions are checked by the TypeScript compiler
✅ Better tooling - IDE autocomplete and refactoring work seamlessly
✅ Easier debugging - Single file contains all component logic

Example:

@Component({
  selector: 'six-form-field',
  standalone: true,
  template: `
    <mat-form-field>
      <input matInput [value]="value()" />
    </mat-form-field>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
  // ...
})
export class SixFormFieldComponent { }

Extending

Adding Custom Component Overrides

1. Create a new partial in src/styles/ (e.g., _card-overrides.scss)
2. Define a mixin with your overrides:

   @mixin six-card-overrides() {
     .mat-mdc-card {
       border-radius: 0;
       // your overrides
     }
   }

3. Import and include it in src/styles/_index.scss:

   @use './card-overrides' as card;
      
   @mixin six-material() {
     // ...existing includes...
     @include card.six-card-overrides();
   }

Adding Behavioral Configuration

Add new options to SixUiMaterialConfig in src/lib/provide-ui-material.ts:

export interface SixUiMaterialConfig {
  readonly disableRipples?: boolean;
  readonly defaultDensity?: number; // New option
}

Publishing

For detailed publishing instructions, see PUBLISHING.md.

Quick reference:

npm run build
npm publish --access public  # First time only

License

MIT - See LICENSE file for details.