@careonbrasil/ng-charts

v14.0.6

Published

11 days ago

Biblioteca de componentes de gráficos SVG para Angular 14 da CareOn

0High
0Medium
0Low

careon_brasil

nasc02

sandro.maciel

@careon-brasil/charts

Biblioteca oficial de componentes de gráficos SVG reativos desenvolvida para o ecossistema CareOn.

Todos os componentes são construídos com SVG declarativo inline (sem dependências pesadas como D3 ou Chart.js), suporte nativo a ChangeDetectionStrategy.OnPush, validação estrita de schema em tempo de execução, tipagem TypeScript e eventos bidirecionais de interação.

Sumário

1. Instalação

Instale o pacote através do registro privado da CareOn via NPM ou Yarn:

npm install @careon-brasil/charts

Dependências de Peer

@angular/core: >=14.0.0 <15.0.0
@angular/common: >=14.0.0 <15.0.0
tslib: ^2.3.0

2. Configuração

Importe o módulo CareonChartsModule no seu módulo Angular (ex: AppModule ou feature module):

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { CareonChartsModule } from '@careon-brasil/charts';

import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    CareonChartsModule
  ],
  bootstrap: [AppComponent]
})
export class AppModule { }

3. Recursos Universais

Metadados e Tipagem Genérica (`id` e `payload`)

Todos os modelos de dados dos 5 gráficos estendem um contrato com suporte a genéricos <T = any>:

export interface BaseChartItem<T = any> {
  /** Identificador opcional do item (ex: ID no banco de dados) */
  id?: string | number;
  /** Objeto de domínio complementar (ex: entidade do backend, metadados de auditoria) */
  payload?: T;
}

Tipagem Segura: Diferente de um dicionário genérico [key: string]: any;, esta abordagem preserva a verificação de erros de digitação em tempo de compilação do TypeScript (ex: passar valeu: 10 em vez de value: 10 gerará um erro de compilação imediato), enquanto permite anexar com segurança qualquer entidade customizada via payload.

Evento de Seleção `(itemSelected)`

Todos os 5 gráficos emitem o evento @Output() itemSelected ao clicar em elementos gráficos (barras, pontos de linha, fatias, segmentos ou legendas). O evento retorna a referência exata do item passado no array de entrada [data]:

<careon-timeline-bar-chart
  [data]="points"
  (itemSelected)="onItemSelected($event)"
></careon-timeline-bar-chart>

import { TimelinePoint } from '@careon-brasil/charts';

onItemSelected(item: TimelinePoint): void {
  console.log('Item selecionado:', item.label);
  console.log('ID do registro:', item.id);
  console.log('Payload anexado:', item.payload);
}

Validação e Mensagens de Erro

Se o input [data] receber um valor nulo, indefinido, formato incompatível (ex: um objeto {} em vez de array []) ou itens sem as propriedades obrigatórias, o gráfico renderiza automaticamente um painel de alerta amigável de erro de validação com o diagnóstico exato do tipo recebido e a estrutura esperada.

4. Componentes

1. Timeline Bar Chart (`<careon-timeline-bar-chart>`)

Gráfico de barras temporais desenhado em SVG inline. Suporta hachurado listrado para períodos passados (isPast), destaque do dia atual (isCurrent), linha pontilhada de tendência conectando o topo das barras, tooltips flutuantes e navegação com scroll horizontal para mais de 7 itens.

Modelo de Dados: `TimelinePoint<T = any>`

export interface TimelinePoint<T = any> {
  /** Rótulo exibido no eixo X (ex: 'Seg', '15/09', 'Sem 1') */
  label: string;
  /** Valor numérico da barra */
  value: number;
  /** Indica se o ponto é do passado (aplica preenchimento listrado) */
  isPast?: boolean;
  /** Indica se é o dia/período corrente (aplica destaque de cor) */
  isCurrent?: boolean;
  /** Identificador único opcional */
  id?: string | number;
  /** Dados arbitrários de domínio */
  payload?: T;
}

Inputs e Outputs

Exemplo de Uso

<careon-timeline-bar-chart
  [data]="timelineData"
  [autoBarWidth]="true"
  [currentBarColor]="'#059669'"
  (itemSelected)="onTimelineSelect($event)"
></careon-timeline-bar-chart>

timelineData: TimelinePoint[] = [
  { label: 'Dom', value: 3, isPast: true, id: 1 },
  { label: 'Seg', value: 7, isPast: true, id: 2 },
  { label: 'Ter', value: 5, isPast: true, id: 3 },
  { label: 'Qua', value: 9, isPast: true, id: 4 },
  { label: 'Qui', value: 0, isPast: true, id: 5 },
  { label: 'Sex', value: 6, isPast: true, id: 6 },
  { label: 'Sáb', value: 11, isCurrent: true, id: 7, payload: { plantoesConfirmados: 11 } }
];

2. Comparison Bar Chart (`<careon-comparison-bar-chart>`)

Gráfico de barras comparativas verticais em SVG inline com ordenação alfabética automática em português (pt-BR), filtro Top 10, linha pontilhada de tendência conectando o topo das barras e rolagem suave com botões integrados de navegação.

Modelo de Dados: `ComparisonItem<T = any>`

export interface ComparisonItem<T = any> {
  /** Rótulo da categoria ou vaga (ex: 'Enfermeiro UTI') */
  label: string;
  /** Quantidade ou valor numérico */
  value: number;
  /** Identificador único opcional */
  id?: string | number;
  /** Dados arbitrários de domínio */
  payload?: T;
}

Inputs e Outputs

Exemplo de Uso

<careon-comparison-bar-chart
  [data]="vagas"
  [limitTop10]="true"
  [barWidth]="48"
  [itemSlotWidth]="110"
  (itemSelected)="onVagaClick($event)"
></careon-comparison-bar-chart>

3. Donut Chart (`<careon-donut-chart>`)

Gráfico circular tipo rosca desenhado através de arcos SVG reativos com stroke-dasharray. Suporta legenda interativa com valores absolutos e percentuais, tooltips no hover, orifício central com texto customizado e estado vazio elegante.

Modelo de Dados: `DonutChartItem<T = any>`

export interface DonutChartItem<T = any> {
  /** Rótulo da fatia (ex: 'Visualizações', 'Cardiologia') */
  label: string;
  /** Valor numérico */
  count: number;
  /** Cor hexadecimal específica para esta fatia (opcional) */
  color?: string;
  /** Identificador único opcional */
  id?: string | number;
  /** Dados arbitrários de domínio */
  payload?: T;
}

Inputs e Outputs

Exemplo de Uso

<careon-donut-chart
  [data]="candidaturas"
  [size]="130"
  [strokeWidth]="16"
  [showLegend]="true"
  [showLegendPercentage]="true"
  (itemSelected)="onDonutSelect($event)"
></careon-donut-chart>

4. Stacked Horizontal Bar (`<careon-stacked-horizontal-bar>`)

Barra horizontal proporcional empilhada desenhada em HTML/CSS Flexbox com cantos arredondados, legenda descritiva, contagem total agregada no cabeçalho e suporte completo a estado vazio customizável.

Modelo de Dados: `StackedBarItem<T = any>`

export interface StackedBarItem<T = any> {
  /** Rótulo do segmento (ex: 'Abertas', 'Encerradas') */
  label: string;
  /** Valor numérico daquele segmento */
  value: number;
  /** Cor de preenchimento hexadecimal */
  color: string;
  /** Identificador único opcional */
  id?: string | number;
  /** Dados arbitrários de domínio */
  payload?: T;
}

Inputs e Outputs

Exemplo de Uso

<careon-stacked-horizontal-bar
  [data]="statusVagas"
  [title]="'Vagas no Período'"
  [totalLabel]="'total de vagas'"
  [emptyText]="'nao existe comparativo'"
  (itemSelected)="onSegmentSelect($event)"
></careon-stacked-horizontal-bar>

5. Funnel Bar (`<careon-funnel-bar>`)

Funil horizontal de conversão. Cada etapa é representada por uma barra horizontal cuja largura é matematicamente dimensionada de forma proporcional ao valor da maior etapa do funil, calculando automaticamente as taxas de retenção percentual.

Modelo de Dados: `FunnelBarItem<T = any>`

export interface FunnelBarItem<T = any> {
  /** Nome da etapa do funil (ex: 'Visualizações', 'Candidaturas') */
  label: string;
  /** Quantidade numérica de registros */
  count: number;
  /** Cor customizada da barra da etapa (opcional) */
  barColor?: string;
  /** Cor da fonte do texto dentro da barra (opcional) */
  fontColor?: string;
  /** Identificador único opcional */
  id?: string | number;
  /** Dados arbitrários de domínio */
  payload?: T;
}

Inputs e Outputs

Exemplo de Uso

<careon-funnel-bar
  [data]="etapasFunil"
  [title]="'Funil de Conversão do Processo Seletivo'"
  [minBarWidth]="70"
  (itemSelected)="onFunnelClick($event)"
></careon-funnel-bar>

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@careon-brasil/charts

Sumário

1. Instalação

Dependências de Peer

2. Configuração

3. Recursos Universais

Metadados e Tipagem Genérica (id e payload)

Evento de Seleção (itemSelected)

Validação e Mensagens de Erro

4. Componentes

1. Timeline Bar Chart (<careon-timeline-bar-chart>)

Modelo de Dados: TimelinePoint<T = any>

Inputs e Outputs

Exemplo de Uso

2. Comparison Bar Chart (<careon-comparison-bar-chart>)

Modelo de Dados: ComparisonItem<T = any>

Inputs e Outputs

Exemplo de Uso

3. Donut Chart (<careon-donut-chart>)

Modelo de Dados: DonutChartItem<T = any>

Inputs e Outputs

Exemplo de Uso

4. Stacked Horizontal Bar (<careon-stacked-horizontal-bar>)

Modelo de Dados: StackedBarItem<T = any>

Inputs e Outputs

Exemplo de Uso

5. Funnel Bar (<careon-funnel-bar>)

Modelo de Dados: FunnelBarItem<T = any>

Inputs e Outputs

Exemplo de Uso

Metadados e Tipagem Genérica (`id` e `payload`)

Evento de Seleção `(itemSelected)`

1. Timeline Bar Chart (`<careon-timeline-bar-chart>`)

Modelo de Dados: `TimelinePoint<T = any>`

2. Comparison Bar Chart (`<careon-comparison-bar-chart>`)

Modelo de Dados: `ComparisonItem<T = any>`

3. Donut Chart (`<careon-donut-chart>`)

Modelo de Dados: `DonutChartItem<T = any>`

4. Stacked Horizontal Bar (`<careon-stacked-horizontal-bar>`)

Modelo de Dados: `StackedBarItem<T = any>`

5. Funnel Bar (`<careon-funnel-bar>`)

Modelo de Dados: `FunnelBarItem<T = any>`