ui-material-angular-six/README.md

UI Material theming & style foundation for Angular applications

# 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
```bash
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`):

```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`:**
```json
"styles": [
  "src/styles.scss",
  "ui-material-angular-six/tokens.scss"
],
```

**2. Then in your `styles.scss`:**
```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)

```scss
// 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

```scss
// 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)

```scss
// 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:

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

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

```html
<!-- 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:

```html
<!-- 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:

```scss
// 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:

```scss
// 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:**
   ```scss
   // ❌ Remove this
   @import '@angular/material/prebuilt-themes/indigo-pink.css';
   ```

2. **Use this theme instead:**
   ```scss
   // ✅ 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:**
```typescript
@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:
   ```scss
   @mixin six-card-overrides() {
     .mat-mdc-card {
       border-radius: 0;
       // your overrides
     }
   }
   ```
3. Import and include it in `src/styles/_index.scss`:
   ```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`:

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

## Publishing

For detailed publishing instructions, see [PUBLISHING.md](PUBLISHING.md).

**Quick reference:**
```bash
npm run build
npm publish --access public  # First time only
```

## License

MIT - See LICENSE file for details.