mapa-library-ui

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

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):

"@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:

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:

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):

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. O surface público da raiz está em 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 (novo secondary entry point) e, se for surface público da raiz, em 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

# 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).