@uxpractice/ruc-lib

ruclib

A collection of reusable Angular components for enhanced application development.

This library provides a set of well-crafted and customizable Angular components to streamline your development process. It includes components for common UI elements and functionalities, reducing boilerplate code and improving code maintainability.

INSTALLATION

Prerequisites:

Ensure you have Node.js and npm (or yarn) installed on your system.

Installation:

Navigate to your Angular project's root directory in your terminal and run the following command:

npm install @uxpractice/ruc-lib

yarn add @uxpractice/ruc-lib

Importing Modules

The components in ruclib are organized into individual modules. To import a specific component into your Angular module, follow these steps:

Import the desired module:

import { RuclibContextMenuModule } from '@uxpractice/ruc-lib/context-menu'; // Example for ContextMenu

// Similarly, import modules for other components like DataFlowModule, etc.

Add the module to your imports array:

@NgModule({
imports: [
// Other imports
RuclibContextMenuModule // Example for ContextMenu
// Add other required modules here
],
//
})
export class AppModule {}

Using Components

Once the necessary module is imported, you can utilize the components within your Angular components' templates:

<uxp-ruclib-context-menu [trigger]="triggerElement" (itemClick)="onItemClick($event)"></uxp-ruclib-context-menu>

Component Documentation

For detailed usage instructions, properties, and methods of each component, refer to the below readme files for the installation. [Context-Menu] (https://www.npmjs.com/package/@ruc-lib/context-menu)
[Data-Flow] (https://www.npmjs.com/package/@ruc-lib/data-flow)
[Data-Grid] (https://www.npmjs.com/package/@ruc-lib/data-grid)
[Dialog] (https://www.npmjs.com/package/@ruc-lib/dialog)
[Metaform] (https://www.npmjs.com/package/@ruc-lib/metaform)
[Multi-File-Upload] (https://www.npmjs.com/package/@ruc-lib/multi-file-upload)
[Multi-Select] (https://www.npmjs.com/package/@ruc-lib/multi-select)
[Tab] (https://www.npmjs.com/package/@ruc-lib/tab)

Custom theme implementation

Angular Material offers a robust theming system that allows you to personalize the appearance of your application beyond the default Material Design styles. You can define palettes for primary, accent, and warn colors, as well as various typography and component-specific styles.

CREATING A CUSTOM THEME:

If we want to create our own custom theme as per our requirement below are the steps:

We will provide a single stand alone .scss file. Which user need to put inside the main project folder and import it to styles.scss file.

STEP 1:

Create a theme.scss file inside app folder parallel to styles.scss

Inside theme.scss file we can provide our custom theme background and foreground palettes:

EXAMPLE:

$custom-theme-background: (
  status-bar: green,
  app-bar:    map_get($mat-blue, 900),
  background: orange,
  hover:      rgba(rgb(39, 24, 172), 0.04),
  card:       map_get($mat-red, 800),
  dialog:     map_get($mat-grey, 800),
  disabled-button: $white-12-opacity,
  raised-button: map-get($mat-grey, 800),
  focused-button: $black-6-opacity,
  selected-button: map_get($mat-grey, 900),
  selected-disabled-button: map_get($mat-grey, 800),
  disabled-button-toggle: black,
  unselected-chip: map_get($mat-grey, 700),
  disabled-list-option: black,
);

$custom-theme-foreground: (
  base:              rgb(27, 27, 13),
  divider:           $black-12-opacity,
  dividers:          $black-12-opacity,
  disabled:          rgba(rgb(165, 23, 23), 0.3),
  disabled-button:   rgba(rgb(146, 22, 22), 0.3),
  disabled-text:     rgba(rgb(143, 30, 30), 0.3),
  hint-text:         rgba(rgb(156, 28, 28), 0.3),
  secondary-text:    rgba(rgb(148, 38, 38), 0.7),
  icon:              rgb(28, 209, 22),
  icons:             rgb(109, 4, 4),
  text:              rgb(20, 20, 7),
  slider-min:        rgb(99, 5, 5),
  slider-off:        rgba(rgb(22, 18, 18), 0.3),
  slider-off-active: rgba(rgb(20, 14, 14), 0.3),
);

STEP 2:

Instead of creating a theme with default theme, we will create our own theme-creating function that lets us apply our own foreground and background palettes. Add below code inside theme.scss file.

@function create-custom-theme($primary, $accent, $warn: mat-palette($mat-red)) {
  @return (
    primary: $primary,
    accent: $accent,
    warn: $warn,
    is-dark: false,
    foreground: $custom-theme-foreground,
    background: $custom-theme-background,
  );
}

$custom-theme-primary: mat-palette($mat-grey);
$custom-theme-accent: mat-palette($mat-blue);
$custom-theme-warn: mat-palette($mat-red);

$custom-theme: create-custom-theme($custom-theme-primary, $custom-theme-accent, $custom-theme-warn);

STEP 3:

Import theme.scss file inside styles.scss file. Create a class and include angular-material-theme from theme.scss file.

.custom-theme {
    @include angular-material-theme($custom-theme);
  }

STEP 4:

Declare a variable for class name inside app.component.ts customTheme = "custom-theme"

Pass variable to app.component.html inside library tag
[customTheme] = "customTheme"

CREATING/UTILIZING A THEME FROM ANGULAR MATERIAL THEME:

Define Palettes:

Write below imports and palette's in styles.scss file and Use the mat.define-palette function to create custom color palettes for your theme. You can customize hues, lightness, and darkness values to achieve the desired look and feel.

//Inside styles.scss file

@use 'sass:map';
@use '@angular/material' as mat;
@import '@angular/material/theming';

$dark-theme-primary: mat.define-palette(mat.$pink-palette); // Example using pink palette
$dark-theme-accent: mat.define-palette(mat.$pink-palette, A200, A100, A400);
$dark-theme-warn: mat.define-palette(mat.$red-palette);

Create Theme Object:

Utilize the mat.define-dark-theme function to construct a theme object in styles.scss file. This object holds configurations for primary, accent, warn colors (optional), and any other theming systems you might utilize.

//Inside styles.scss file

Example of Dark Theme:
$dark-theme: mat.define-dark-theme((
  color: (
    primary: $dark-theme-primary,
    accent: $dark-theme-accent,
    warn: $dark-theme-warn,
  )
));

Apply Theme to Components (Optional)

To Apply defined theme to all Angular Material Components write the class and add a include linked to the theme we have create in the styles.scss file, ensuring consistency throughout your application.

//Inside styles.scss file

.dark-theme {
  @include mat.all-component-themes($dark-theme);
}

Custom CSS Class (Preferred):

Create a CSS class (e.g., my-dark-theme) and include angular-material-theme($dark-theme) within the styles.scss file. Apply this class to the appropriate element (e.g., the root body element) in your application to activate the theme. This approach offers greater flexibility for targeting specific components or sections.

//Inside styles.scss file

.my-dark-theme {
  @include angular-material-theme($dark-theme);
}

/* Apply the theme class to your desired element */
body {
  @extend .my-dark-theme;
}

Declare a variable for class name inside app.component.ts customTheme = "my-dark-theme"

Pass variable to app.component.html inside library tag
[customTheme] = "customTheme"

Refer to the official Angular Material documentation for a comprehensive guide on theming: https://material.angular.io/guide/theming