npm package: @gipisistemas/ngx-core
Description: Componentes e utilitários para projetos da GIPI Sistemas.
Author: GIPI Sistemas
Latest version: 1.0.23

# GIPI - ngx-core

Este projeto foi gerado utilizando o [Angular CLI](https://github.com/angular/angular-cli) - _versão `19.2.0`_.

## 📝 Sobre

A biblioteca `ngx-core` fornece utilitários, temas e componentes reutilizáveis para projetos Angular, facilitando o desenvolvimento de interfaces consistentes e responsivas.

## 🧩 Pré-requisitos

-   [Node](https://nodejs.org/en/download) - _vesão `^18.19.1 || ^20.11.1 || ^22.0.0`._
-   [Angular](https://angular.dev/) - _versão `20.x.x`._
-   [Angular Material](https://material.angular.io/) - _versão `20.x.x`_.

## ⚠️ Estrutura de Commits (Conventional Commits)

Este projeto utiliza **Semantic Release** para gerar versões automaticamente.
A versão (`patch`, `minor`, `major`) é definida de acordo com o **tipo do commit**.

### 🔑 Regras principais
- **fix:** incrementa **patch** → `1.0.0 → 1.0.1`
- **feat:** incrementa **minor** → `1.0.0 → 1.1.0`
- **feat!:** ou qualquer commit com **BREAKING CHANGE** no corpo → incrementa **major** → `1.0.0 → 2.0.0`

### ✅ Exemplos de commits válidos
- `fix: corrige bug no botão de login`
- `feat: adiciona novo componente de avatar`
- `feat!: altera API de autenticação`
- `chore: atualiza dependências (não gera release)`
- `docs: adiciona instruções no README (não gera release)`

### ⚠️ Importante
Sempre coloque dois pontos e um espaço depois do tipo.
- ✅ fix: descrição
- ❌ fix:descrição

Somente commits fix, feat ou com BREAKING CHANGE geram versão.
Outros tipos (chore, docs, refactor, etc.) não geram release automaticamente.

## 🛠️ Desenvolvimento

Para compilar a biblioteca em modo de desenvolvimento, execute:

```bash
npm run watch
```

Isso executará o comando:

```bash
ng build --watch --configuration development
```

Uma vez compilada. A biblioteca será recarregada automaticamente sempre que houver modificações nos arquivos.

## 🖥️ Utilização no aplicativo

Para utilizar esta biblioteca, siga os passos abaixo:

### 1️⃣ Instalar a biblioteca no aplicativo

Instale a biblioteca no seu aplicativo Angular executando:

```bash
npm install caminho-da-lib\\dist\\ngx-core
```

Substitua `caminho-da-lib` pelo caminho correto onde a biblioteca foi compilada.

### 2️⃣ Configurar `preserveSymlinks`

É necessário definir `preserveSymlinks: true` no arquivo `angular.json` para evitar o seguinte erro:

```plaintext
core.mjs:7195 ERROR RuntimeError: NG0203: inject() must be called from an injection context...
```

🔹 No `angular.json`, dentro de `projects -> nome-do-projeto -> architect -> build -> options`, adicione:

```json
"preserveSymlinks": true
```

### 3️⃣ Adicionar os providers necessários

Esses providers são essenciais para o funcionamento da biblioteca.
No `main.ts` ou no arquivo de configuração `app.config.ts`, adicione os seguintes providers:

```typescript
import { bootstrapApplication } from "@angular/platform-browser";
import { AppComponent } from "./app/app.component";
import { importProvidersFrom } from "@angular/core";
import { MatSnackBarModule } from "@angular/material/snack-bar";
import { provideHttpClient, withInterceptorsFromDi } from "@angular/common/http";
import { provideAppMessages, DEFAULT_MESSAGES } from "@gipisistemas/ngx-core";

bootstrapApplication(AppComponent, {
    providers: [
        // ...outros providers
        importProvidersFrom(MatSnackBarModule),
        provideHttpClient(withInterceptorsFromDi()),
        provideAppMessages(DEFAULT_MESSAGES),
    ],
}).catch((err) => console.error(err));
```

### 4️⃣ Temas e estilos globais

Definição de temas:

🔹 Se não informar o `$custom-theme` no mixin `all-component-themes` a biblioteca irá aderir as paletas de cores, fontes e densidades padrão.

##### Palettes

-   primary: `$palette-primary`
-   secondary: `$palette-secondary`
-   success: `$palette-success`
-   information: `$palette-information`
-   warning: `$palette-warning`
-   danger: `$palette-danger`
-   white: `$palette-white`
-   black: `$palette-black`
-   pastels: `$palette-pastels`

##### Typography

-   font-family: `'Roboto, sans-serif'`
-   font-size: `1.4rem`
-   font-base: `62.5%` - _100% equivale a 16px; Logo 62.5% de 16px = 10px; Assim 1rem equivale 10px;_

##### Density

-   scale: `0`

Utilizando tema customizado:

```scss
@use "@gipisistemas/ngx-core" as ngx-core;

$custom-theme: ngx-core.define-theme(
    (
        palettes: (
            primary: $palette-primary,
            secondary: $palette-secondary,
            // ... other palettes
        ),
        typography: (
            font-family: "Roboto, sans-serif",
            font-size: 1.4rem,
            font-base: 62.5%,
        ),
    )
);

@include ngx-core.all-component-themes($custom-theme);
```

Utilizando tema padrão:

```scss
@use "@gipisistemas/ngx-core" as ngx-core;
@include ngx-core.all-component-themes();
```

## 🚀 Produção
Ainda será implementado