mapa-library-ui 1.4.1 → 1.5.0

package/README.md

@@ -1,3 +1,238 @@
-# MapaLibraryUi
+# mapa-library-ui
 
-Library of components used for Mapa - Human Data Science
+Design system do **Mapa — Human Data Science**: componentes Angular Material customizados,
+serviços, pipes e utilitários consumidos pelo shell e por todos os remotes do ecossistema.
+
+Construído com **ng-packagr** (Angular 20.3). Distribuído em **subpacotes** (_secondary entry points_)
+para que cada consumidor importe apenas o que usa.
+
+- Pacote npm: `mapa-library-ui`
+- Versão atual: **1.5.0**
+- Componentes: **standalone** (sem `NgModule`), prefixo de seletor `mapa-*`
+
+---
+
+## Instalação
+
+```bash
+npm install mapa-library-ui
+```
+
+A biblioteca declara Angular e demais bibliotecas como **`peerDependencies`** — o consumidor é quem
+fixa as versões. Garanta que o app já tenha (ou instale):
+
+```jsonc
+"@angular/animations": "^20.3.0",
+"@angular/cdk":        "^20.2.0",
+"@angular/common":     "^20.3.0",
+"@angular/core":       "^20.3.0",
+"@angular/forms":      "^20.3.0",
+"@angular/localize":   "^20.3.0",
+"@angular/material":   "^20.2.0",
+"@angular/router":     "^20.3.0",
+"apexcharts":          "^5.10.3",
+"ng-apexcharts":       "^2.3.0",
+"ngx-mask":            "^20.0.3",
+"ngx-mat-select-search": "^8.0.4",
+"mapa-frontend-i18n":  "^2.0.0",
+"rxjs":                "^7.8.2",
+"ts-md5":              "^1.3.1"
+```
+
+> A lib usa **`mapa-frontend-i18n`** para os textos de UI. Mudanças que dependem de novas strings
+> exigem publicar o `mapa-frontend-i18n` **antes**.
+
+### Pré-requisitos no app consumidor
+
+- **Animações** habilitadas: `provideAnimations()` (necessário para Material).
+- Tema do **Angular Material** configurado no app.
+- Para datepickers, definir `MAT_DATE_FORMATS` (a lib trabalha no formato `DD/MM/YYYY`).
+
+---
+
+## Uso
+
+Os componentes são **standalone** — importe diretamente da subpath correspondente e adicione ao
+array `imports` do seu componente/rota:
+
+```ts
+import { Component } from '@angular/core';
+import { ButtonComponent } from 'mapa-library-ui/button';
+import { MapaTableComponent } from 'mapa-library-ui/table';
+import { TableColumn } from 'mapa-library-ui'; // interfaces/utilitários vêm da raiz
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [ButtonComponent, MapaTableComponent],
+  template: `
+    <mapa-button color="primary" (clicked)="onClick()">Salvar</mapa-button>
+    <mapa-table [columns]="columns" [data]="rows"></mapa-table>
+  `,
+})
+export class ExampleComponent {
+  columns: TableColumn[] = [/* ... */];
+  rows = [/* ... */];
+  onClick() {}
+}
+```
+
+> **Importe sempre da subpath** (`mapa-library-ui/button`, `mapa-library-ui/table`, …).
+> **Interfaces, elements, pipes e helpers de i18n** ficam na raiz (`mapa-library-ui`).
+
+### Internacionalização (i18n)
+
+Os textos padrão são **pt-BR**. Para sobrescrevê-los, há dois caminhos:
+
+**1. Estático, na inicialização** — via provider:
+
+```ts
+import { provideMapaUiTexts } from 'mapa-library-ui';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideMapaUiTexts({
+      filters: { clear: 'Clear filters', submit: 'Filter' },
+      validation: { required: 'Required field' },
+    }),
+  ],
+};
+```
+
+**2. Dinâmico, em runtime** — via `MapaI18nService` (ex.: troca de idioma):
+
+```ts
+import { MapaI18nService, PartialMapaUiTexts } from 'mapa-library-ui';
+
+constructor(private i18n: MapaI18nService) {}
+
+setEnglish() {
+  const texts: PartialMapaUiTexts = { common: { selectAll: 'Select all' } };
+  this.i18n.setTexts(texts); // faz merge sobre os defaults pt-BR
+}
+```
+
+Os textos informados sofrem _merge_ sobre os defaults — você só precisa enviar as chaves que quer
+alterar. Grupos disponíveis: `common`, `filters`, `datepicker`, `capability`, `paginator`,
+`warning`, `table`, `validation`.
+
+---
+
+## Subpacotes (secondary entry points)
+
+Cada componente/recurso é importado por uma subpath própria. Por isso os remotes compartilham a lib
+com `includeSecondaries: true` no Module Federation.
+
+| Subpath | Seletor / export principal | Descrição |
+|---|---|---|
+| `mapa-library-ui` | interfaces, `elements`, pipes, utils, helpers de i18n | Tipos e utilitários transversais (`TableColumn`, `DialogData`, `ElementOption`, `provideMapaUiTexts`, `MapaI18nService`, pipes de CPF/data…) |
+| `/authorize` | guard de rota | Guard de autorização (`canActivate`) |
+| `/benchmarking` | `<mapa-benchmark-chart>`, `<mapa-benchmark-indicator>` | Gráfico e indicador de benchmarking |
+| `/breadcrumb` | `<mapa-breadcrumb>` | Trilha de navegação |
+| `/button` | `<mapa-button>` | Botão (`color`, `disabled`, `clicked`) |
+| `/button-icon` | `<mapa-button-icon>` | Botão com ícone |
+| `/capability` | `<mapa-capability-*>` | Família de componentes de competências (comparativo, indicadores, intervalos, detalhe…) |
+| `/chart` | `<mapa-chart>` | Gráfico genérico (ApexCharts) |
+| `/checkbox` | `<mapa-checkbox>` | Checkbox |
+| `/datepicker` | `<mapa-datepicker>` | Seletor de data |
+| `/datepicker-range` | `<mapa-datepicker-range>` | Seletor de intervalo de datas |
+| `/dialog` | `<mapa-dialog>`, `openDialog()` | Diálogo + helper para abrir via `MatDialog` |
+| `/dropdown` | `<mapa-dropdown>` | Select com busca |
+| `/dropdown-tree` | `<mapa-dropdown-tree>`, `DataNode` | Select em árvore |
+| `/empty` | `<mapa-empty>` | Estado vazio |
+| `/filters` | `<mapa-filters>` | Barra de filtros |
+| `/form` | `<mapa-form>` | Formulário dinâmico |
+| `/group-report` | `<mapa-group-report>` | Relatório de grupo |
+| `/icon` | `<mapa-icon>` | Ícone |
+| `/input` | `<mapa-input>` | Campo de texto |
+| `/menu` | `<mapa-menu>`, `MenuItem`, `MenuActionEvent` | Menu de ações |
+| `/nav-list` | `<mapa-nav-list>` | Lista de navegação |
+| `/radio-button` | `<mapa-radio-button>` | Radio button |
+| `/report-item` | `<mapa-report-item>` | Item de relatório |
+| `/scale` | `<mapa-scale>`, `<mapa-progressbar>`, `<mapa-details>` | Escala e barras de progresso |
+| `/scale-parameterization` | `<mapa-scale-parameterization>` | Parametrização de escalas |
+| `/services` | `LoaderService` | Serviços de infraestrutura (loader) |
+| `/slide-toggle` | `<mapa-slide-toggle>` | Slide toggle |
+| `/svg-icon` | `<mapa-svg-icon>` | Ícone SVG inline |
+| `/table` | `<mapa-table>`, `customPaginatorFactory` | Tabela com paginação, ordenação e seleção |
+| `/tag` | `<mapa-tag>` | Tag/chip |
+| `/textarea` | `<mapa-textarea>` | Área de texto |
+| `/tooltip` | diretiva + componente de tooltip | Tooltip customizado |
+| `/warning` | `<mapa-warning>` | Aviso/alerta |
+
+> A lista canônica de subpaths está no campo `exports` de
+> [`package.json`](package.json). O surface público da raiz está em
+> [`src/public-api.ts`](src/public-api.ts).
+
+---
+
+## Desenvolvimento
+
+Não há dev server da própria biblioteca. Desenvolve-se através do app de **documentação** (vitrine de
+componentes) ou via `watch` + consumidor linkado.
+
+Comandos (rodar a partir da **raiz do workspace**, `mapa-frontend-library/`):
+
+| Comando | O que faz |
+|---|---|
+| `ng serve --project=documentation` | Sobe o app de documentação em **http://localhost:4444/** (hot reload) |
+| `npm run build:lib` | Build da lib → `dist/mapa-library-ui` |
+| `npm run watch` | Build da lib em watch (`--configuration development`) |
+| `npm test` | Testes (Karma + Jasmine) |
+
+### Adicionar um novo componente
+
+1. `ng generate component components/<nome> --project=mapa-library-ui --no-standalone` (ou standalone — o padrão atual da lib é **standalone**).
+2. Crie a pasta `src/` dentro de `components/<nome>` e mova os arquivos do componente para ela.
+3. Copie `ng-package.json` e `public-api.ts` de um componente existente, ajustando os caminhos/exports para o novo componente.
+4. Registre o componente no `exports` de [`package.json`](package.json) (novo secondary entry point) e, se for surface público da raiz, em [`src/public-api.ts`](src/public-api.ts).
+5. Documente o componente no projeto `documentation` (adicione a entrada no `drawer` e a rota).
+
+> Exports só ficam acessíveis ao consumidor se entrarem no **secondary entry point** correto
+> (`ng-package.json` + `public-api.ts`) **e** no `exports` do `package.json`.
+
+---
+
+## Build & publicação
+
+```bash
+# 1. Suba a versão em projects/mapa-library-ui/package.json
+# 2. Build
+npm run build:lib
+
+# 3. Publique a partir do artefato gerado
+npm publish ./dist/mapa-library-ui
+
+# 4. Suba a dependência nos consumidores (shell + remotes)
+```
+
+> A publicação também roda na pipeline (`azure-pipelines.yml`) ao integrar em `develop`:
+> build → `npm pack` → publish no registro NPM da Mapa.
+
+Ao depender de novas strings de UI, **publique `mapa-frontend-i18n` antes** de publicar esta lib.
+
+---
+
+## Fluxo de trabalho (branch / PR)
+
+Branch a partir de `develop` (`feature/{taskid}` ou `bugfix/{taskid}`) → PR para `develop` com o work
+item vinculado. Lembre de **publicar a nova versão** quando o consumo depender dela.
+
+---
+
+## Estrutura
+
+```
+projects/mapa-library-ui/
+├── src/
+│   ├── public-api.ts                 # surface público da raiz
+│   ├── <subpath>.ts                  # reexport de cada secondary entry point
+│   └── lib/
+│       ├── components/<nome>/        # componentes (cada um com ng-package.json + public-api.ts)
+│       └── core/                     # elements, interfaces, services, pipes, directives, i18n, utils
+├── ng-package.json                   # config ng-packagr (saída: dist/mapa-library-ui)
+├── package.json                      # nome/versão, peerDependencies, exports (subpaths)
+└── tsconfig.lib(.prod).json
+```
+
+O app de demonstração fica em `projects/documentation/` (porta **4444**).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mapa-library-ui",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "peerDependencies": {
     "@angular/animations": "^20.3.0",
     "@angular/cdk": "^20.2.0",
@@ -11,7 +11,7 @@
     "@angular/material": "^20.2.0",
     "@angular/router": "^20.3.0",
     "apexcharts": "^5.10.3",
-    "mapa-frontend-i18n": "^1.3.4",
+    "mapa-frontend-i18n": "^2.0.0",
     "ng-apexcharts": "^2.3.0",
     "ngx-mask": "^20.0.3",
     "ngx-mat-select-search": "^8.0.4",