MatchaComponents

Repository

Link to the project.

This library was generated with Angular CLI version 18.0.0. | Node Version - lts/iron -> v20.12.2

How to create a component

Create a new module

To generate a new module run the command:

Terminal: ng g m test-component --project matcha-components

Create a new Component

To generate a component inside of your module run the command:

Terminal: ng g c test-component/my-test-component --project matcha-components

Update your new module file

Import the component file inside of created module.

Path: design-system/projects/matcha-components/src/lib/test-component/test-component.module.ts

import { MyTestComponentComponent } from './test-component/my-test-component.component';

Declare the new component

Path: design-system/projects/matcha-components/src/lib/test-component/test-component.module.ts

declarations: [MyTestComponentComponent],

Export the new component

Path: design-system/projects/matcha-components/src/lib/test-component/test-component.module.ts

exports: [MyTestComponentComponent],

Update your new component file

We are working with modules and by default the angular-cli create components to working with standalone. Update your component decorator to look like this:

Path: design-system/projects/matcha-components/src/lib/test-component/my-test-component.component.ts

@Component({
  selector: 'lib-my-test-component',
  templateUrl: './my-test-component.component.html',
  styleUrl: './my-test-component.component.scss'
})

Update MatchaComponentsModule

Update the core module of library matcha-components. Import the module of the component file inside of created module.

Path: design-system/projects/matcha-components/src/lib/test-component/matcha-components.module.ts

import { TestComponentModule } from './test-component/test-component.module';`

Import the new module

Path: design-system/projects/matcha-components/src/lib/test-component/matcha-components.module.ts

imports: [TestComponentModule, ...`

Export the new module

Path: design-system/projects/matcha-components/src/lib/test-component/matcha-components.module.ts

exports: [TestComponentModule, ...`

Update Public API File

Add the export for your new component

Path: design-system/projects/matcha-components/src/public-api.ts

export * from './lib/test-component/my-test-component/my-test-component.component';

Add the export for your new module

Path: design-system/projects/matcha-components/src/public-api.ts

export * from './lib/test-component/test-component.module';

How to test a component before publish

Update AppModule

Go to the main project folder src and find the app.modules.ts file.

Import the module file inside app.module.

Path: design-system/src/app/app.modules.ts

import { TestComponentModule } from '../../projects/matcha-components/src/public-api';

Import the module

Path: design-system/src/app/app.modules.ts

imports: [TestComponentModule, ...

Call the component tag somewhere in your test aplication

Add the component tag inside of template file

Path: design-system/src/app/dashboard/dashboard.component.html

<lib-my-test-component></lib-my-test-component>

Run the test project

Run the serve command

Terminal: ng s

How to publish

Update Version

Inside of projects folder in find the package.json of matcha-components and update the version

Path: design-system/projects/matcha-components/package.json

{
    "name": "matcha-components",
    "version": "x.x.xx",
    "peerDependencies": {},
    "dependencies": {},
    "sideEffects": false
}

Build the matcha-component project

The build artifacts will be stored in the dist/ directory. Run the build command

Terminal: ng build matcha-components

Publicação do pacote

In the terminal change the directory to the bundle folder of matcha-components inside of dist folder. This is the folder that will be published in NPM.

Terminal: cd dist/matcha-components

Now we can do the package publication command:

Terminal: npm publish

Test published component

In the terminal go back to the root of design-system

Terminal: cd ../..

Now you must remove the previous installation of matcha-components to ensure the new installation.

Terminal: npm uninstall matcha-components

Than install the new version of matcha-components

Terminal: npm i matcha-components

Update the imports in app.modules to the matcha-component from node_modules.

Path: design-system/src/app/app.modules.ts

import { TestComponentModule } from 'matcha-components';

Run the serve command:

Terminal: ng s

Storybook

Run ng run matcha-components:storybook or npm run storybookto execute the storybook aplication and see the documentation of all components via storybook.

Scaffold

You can also use ng g directive|pipe|service|class|guard|interface|enum|module --project matcha-components, in case of nested components you can use ng g c component-name/child-component --project matcha-component.

Note: Don't forget to add --project matcha-components or else it will be added to the default project in your angular.json file.

Running example aplication

Run ng s --project matcha-design-system to execute an angular aplication that you can for exemple test your components or directives in pratice.

Unit tests

Run ng test matcha-components to execute the unit tests via Karma.

Matcha-Theme

Theming Matcha Components

Place the class (.theme-default-light) that you define in theme file, inside of body tag. This way you can cover the whole application with the theme.

Some like this <body class=".theme-default-light">.

// app.theme.scss

@use "../lib/main.scss" as matcha;

//MATCHA THEME - LIGHT
// palettes
$default-light-primary: matcha.palette(matcha.$blue-grey, 500, 400, 600);
$default-light-accent: matcha.palette(matcha.$lime, 500, 200, 900);
$default-light-warn: matcha.palette(matcha.$red, 900, 200, 900);
// typography
$matcha-default-typography: matcha.matcha-typography-config(
    $font-family: "Arial",
);
// theme
$matcha-default-theme: matcha.light-theme($default-light-primary, $default-light-accent, $default-light-warn);

.theme-default-light {
    @include matcha.matcha-components($matcha-default-theme);
    @include matcha.matcha-typography($matcha-default-typography);
}

Light and dark themes examples

You must create some code to do the class toggle from .theme-default-light to .theme-default-dark inside the <body> tag.

@use "../lib/main.scss" as matcha;

//MATCHA THEME - LIGHT
// palettes
$default-light-primary: matcha.palette(matcha.$blue-grey, 500, 400, 600);
$default-light-accent: matcha.palette(matcha.$lime, 500, 200, 900);
$default-light-warn: matcha.palette(matcha.$red, 900, 200, 900);
// typography
$matcha-default-typography: matcha.matcha-typography-config(
    $font-family: "Arial",
);
// theme
$matcha-default-theme: matcha.light-theme($default-light-primary, $default-light-accent, $default-light-warn);

.theme-default-light {
    @include matcha.matcha-components($matcha-default-theme);
    @include matcha.matcha-typography($matcha-default-typography);
}

// You can set how much themes you need...

//MATCHA THEME - DARK
// palette
$default-dark-primary: matcha.palette(matcha.$blue-grey, 100, 50, 200);
$default-dark-accent: matcha.palette(matcha.$lime, A400, A200, A700);
$default-dark-warn: matcha.palette(matcha.$red, 200, 50, 300);
// typography
$matcha-default-typography: matcha.matcha-typography-config(
    $font-family: "Arial",
);
// theme
$matcha-default-theme: matcha.dark-theme($default-dark-primary, $default-dark-accent, $default-dark-warn);

.theme-default-dark {
    @include matcha.matcha-components($matcha-default-theme);
    @include matcha.matcha-typography($matcha-default-typography);
}

Theming both Angular Material and Matcha Components

@use "@angular/material" as mat;
@use "../lib/main.scss" as matcha;
@include mat.core();

//MATCHA THEME - LIGHT
// palettes
$default-light-primary: matcha.palette(matcha.$blue-grey, 500, 400, 600);
$default-light-accent: matcha.palette(matcha.$lime, 500, 200, 900);
$default-light-warn: matcha.palette(matcha.$red, 900, 200, 900);
// typography
$matcha-default-typography: matcha.matcha-typography-config(
    $font-family: "Arial",
);
$mat-default-typography: mat.define-typography-config(
    $font-family: "Arial",
);
// theme
$matcha-default-theme: matcha.light-theme($default-light-primary, $default-light-accent, $default-light-warn);
$mat-default-theme: mat.define-light-theme(
    (
        color: (
            primary: $default-light-primary,
            accent: $default-light-accent,
            warn: $default-light-warn,
        ),
        typography: $mat-default-typography,
    )
);

.theme-default-light {
    @include mat.all-component-themes($mat-default-theme);
    @include matcha.matcha-components($matcha-default-theme);
    @include matcha.matcha-typography($matcha-default-typography);
}

• Theming Matcha Components

@use "../lib/main.scss" as matcha;

//MATCHA THEME - DARK
// palette
$default-dark-primary: matcha.palette(matcha.$blue-grey, 100, 50, 200);
$default-dark-accent: matcha.palette(matcha.$lime, A400, A200, A700);
$default-dark-warn: matcha.palette(matcha.$red, 200, 50, 300);
// typography
$matcha-default-typography: matcha.matcha-typography-config(
    $font-family: "Arial",
);
// theme
$matcha-default-theme: matcha.dark-theme($default-dark-primary, $default-dark-accent, $default-dark-warn);

.theme-default-dark {
    @include matcha.matcha-components($matcha-default-theme);
    @include matcha.matcha-typography($matcha-default-typography);
}

Further help

To get more help on the Angular CLI use ng help or go check out the Angular CLI Overview and Command Reference page. To get more help on the Storybook stories

Roadmap

Alpha components are in-development and may have many frequent breaking changes.

Beta components are mostly polished and ready for use, but may still have breaking changes.

Stable components are reviewed, documented, and API complete.

• ❌ Not started
• 🟡 In progress
• ✅ Complete

v1.0.0 (2023)

| Component | Alpha | Beta | Stable | | ----------------------------- | :---: | :--: | :----: | | Button | ✅ | ✅ | ✅ | | FAB | ✅ | ✅ | ✅ | | Icon button | ✅ | ✅ | ✅ | | Card | ✅ | ✅ | ✅ | | Checkbox | ✅ | ✅ | ✅ | | Chips | ✅ | ✅ | ✅ | | Dialog | ✅ | ✅ | ✅ | | Divider | ✅ | ✅ | ✅ | | Elevation | ✅ | ✅ | ✅ | | Focus ring | ✅ | ✅ | ✅ | | Field | ✅ | ✅ | ✅ | | Icon | ✅ | ✅ | ✅ | | List | ✅ | ✅ | ✅ | | Menu | ✅ | ✅ | ✅ | | Progress indicator (circular) | ✅ | ✅ | ✅ | | Progress indicator (linear) | ✅ | ✅ | ✅ | | Radio button | ✅ | ✅ | ✅ | | Ripple | ✅ | ✅ | ✅ | | Select | ✅ | ✅ | ✅ | | Slider | ✅ | ✅ | ✅ | | Switch | ✅ | ✅ | ✅ | | Tabs | ✅ | ✅ | ✅ | | Title | ✅ | ✅ | ✅ | | Text field | ✅ | ✅ | ✅ |

Future

These features are planned for a future release.

| Component | Alpha | Beta | Stable | | ----------------- | :---: | :--: | :----: | | Autocomplete | ✅ | ✅ | ✅ | | Badge | ✅ | ✅ | ✅ | | Banner | ✅ | ✅ | ✅ | | Bottom app bar | ✅ | ✅ | ✅ | | Bottom sheet | ✅ | ✅ | ✅ | | Segmented button | ✅ | ✅ | ✅ | | Card | ✅ | ✅ | ✅ | | Data table | ✅ | ✅ | ✅ | | Date picker | ✅ | ✅ | ✅ | | Navigation bar | ✅ | ✅ | ✅ | | Navigation drawer | ✅ | ✅ | ✅ | | Navigation rail | ✅ | ✅ | ✅ | | Search | ✅ | ✅ | ✅ | | Snackbar | ✅ | ✅ | ✅ | | Time picker | ✅ | ✅ | ✅ | | Tooltip | ✅ | ✅ | ✅ | | Top app bar | ✅ | ✅ | ✅ |

Base CLASSES CSS

✅TYPOGRAPHY
✅SPACING
✅BORDER
✅COLORS
✅SIZES

Atomic Components

FORM
    ✅autocomplete
    ✅checkbox
    ✅datepicker
    ✅form field
    ✅input
    ✅radio button
    ✅select
    ✅slider
    ✅slide toggle

NAVIGATION
    ✅menu
    ✅sidebar
    ✅toolbar
    ✅header

LAYOUT
    ✅badge
    ✅bottom sheet
    ✅card
    ✅divider
    ✅elevation
    ✅expansion panel
    ✅display grid
    ✅display flex
    ✅list
    ✅stepper
    ✅tabs
    ✅titles
    ✅tree

BUTTONS/INDICATORS
    ✅button
    ✅button toggle
    ✅chips
    ✅icon
    ✅progress spinner
    ✅progress bar
    ✅ripple

POPUP/MODALS
    ✅dialog
    ✅snackbar
    ✅tooltip

DATATABLE
    ✅paginator
    ✅sort header
    ✅table

At moment we have 6 bases and 42 atoms to make documentation 1 component equals to 2,083% do progresso

Molecular Components

Autocomplete de membros

Organisms Components

Header de buscas

Pages Components

List page