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: 2.2.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.2.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 o datepicker, instalar os peers ngxsmk-datepicker (^3.0.0) e luxon (^3.0.0). O formato de data segue o idioma ativo (DD/MM/YYYY em pt-BR/es, MM/DD/YYYY em en); não é necessário configurar MAT_DATE_FORMATS.

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, report, 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 (items, separator, ariaLabel) | | /button | <mapa-button> | Botão (color, shape, fullWidth, 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 | | /classification-tag | <mapa-classification-tag> | Classificação dinâmica com contraste e fallback neutro | | /conclusion-card | <mapa-conclusion-card> | Apresentação de conclusão, metadados e evento edit | | /datepicker | <mapa-datepicker> | Seletor de data nos modos single, range e multiple (via element.mode) | | /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-group-profile | <mapa-report-group-profile-widget> | Perfil de grupo: filtros no topo, pílula contínua por dimensão e legenda | | /report-item | <mapa-report-item> | Item de relatório | | /report-ranking-table | <mapa-report-ranking-table-widget> | Ranqueamento de dimensões com alternância de visão e ordenação | | /report-legend | <mapa-report-legend> | Legenda expansível de direções e faixas | | /result-track | <mapa-result-track> | Barra linear ou divergente com semântica de meter | | /report-scale | <mapa-report-scale-widget> | Escalas nos modos summarized e detailed | | /report-indicators | <mapa-report-indicators-widget> | Indicadores nos modos list, chart e detailed | | /report-psychosocial | <mapa-report-psychosocial-widget> | Média, fatores e dimensões psicossociais | | /report-points | <mapa-report-points-widget> | Pontos fortes e de atenção resumidos ou detalhados | | /report-socioemotional | <mapa-report-socioemotional-widget> | Competências, legendas, vulnerabilidades e gauge segmentado | | /report-widgets | todos os widgets acima | Subpath agregadora para composições 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.

Widgets de relatório

Os widgets recebem contratos próprios (MapaReportHeading, grupos, dimensões, indicadores, pontos e classificações) exportados pela raiz. Eles não dependem de modelos ou serviços do projeto consumidor. Os modos são controláveis por [(mode)], com os padrões summarized para escalas e pontos e list para indicadores.

O tema pode ser ajustado no contêiner do relatório por meio dos tokens --mapa-report-accent, --mapa-report-accent-soft, --mapa-report-surface, --mapa-report-surface-muted, --mapa-report-border, --mapa-report-text, --mapa-report-muted, --mapa-report-radius e --mapa-report-space.

Widgets de grupo (v2)

<mapa-report-group-profile-widget> e <mapa-report-ranking-table-widget> são a versão nova dos widgets de grupo, para consumo pelo mv-v2-frontend. Os equivalentes antigos — <mapa-capability-comparative> e <mapa-group-report> — continuam intactos para o mv-frontend.

Perfil de grupo

<mapa-report-group-profile-widget [data]="profile" [heading]="heading">
  <ng-container mapaReportGroupProfileFilters>
    <mapa-dropdown [element]="groupDropdown" [formControl]="groupControl" />
    <mapa-dropdown [element]="testDropdown" [formControl]="testControl" />
    <mapa-dropdown [element]="scaleDropdown" [formControl]="scaleControl" />
  </ng-container>
</mapa-report-group-profile-widget>

• heading (MapaReportHeading) renderiza título e descrição acima dos filtros.
• O conteúdo projetado com o atributo mapaReportGroupProfileFilters fica no topo, em grid de até 3 colunas. Sem projeção o slot não ocupa espaço.
• data (MapaReportGroupProfileData): cada dimensão vira uma pílula contínua em que as fatias (slices) mudam de cor; os percentuais aparecem alinhados à direita, acima da pílula. Fatias com value: 0 são descartadas.
• slice.highlighted marca a posição de uma pessoa dentro do grupo.
• A legenda sai abaixo do gráfico, montada a partir das fatias efetivamente desenhadas; use legend para sobrescrever ou showLegend="false" para ocultar.
• Só existe média do grupo (data.average, controlada por showAverage).
• distributionLabel e averageLabel são inputs com padrão pt-BR porque mapa-frontend-i18n ainda não publica essas chaves.

Ranqueamento

<mapa-report-ranking-table-widget
  [heading]="heading"
  [views]="views"
  [(view)]="view"
  [showAverage]="true"
  [note]="note"
/>

• views (MapaReportRankingView[]) alimenta a alternância Grupo/Avaliados; o switch só aparece quando mais de uma visão tem entradas, e a primeira coluna é nomeada pela visão ativa (ou por entryColumnLabel).
• Monta as colunas a partir das dimensões das entradas e ordena por classification.classificationId, não pelo texto do chip.
• As classificações usam <mapa-classification-tag appearance="solid"> — o chip é autocontido, sem depender de CSS do app consumidor.
• showScoreOnHover (padrão false): com true, passar o mouse sobre a célula troca o chip pela nota e pela direção. Desligado, a célula mostra só o chip.
• note renderiza a nota de rodapé abaixo da tabela.

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