forlogic-core 2.0.3 → 2.0.5

package/docs/design-system/charts-dashboards.md

@@ -0,0 +1,547 @@
+<!-- ⚠️ ARQUIVO GERADO AUTOMATICAMENTE — NÃO EDITAR MANUALMENTE -->
+<!-- Fonte: src/design-system/docs/ | Regenerar: npx tsx scripts/generate-ds-docs.ts -->
+
+# Gráficos & Dashboards
+
+Categoria: **Gráficos & Dashboards** | 11 componentes
+
+### Chart
+
+Sistema de gráficos baseado em Recharts com suporte a temas e tooltips customizados. Inclui barras, linhas, áreas, pizza, radar e mais.
+
+**Uso:**
+```tsx
+import { ChartContainer, ChartTooltip, ChartTooltipContent, ChartLegend, ChartLegendContent } from "forlogic-core"
+import { Bar, BarChart, XAxis, YAxis, CartesianGrid } from "recharts"
+
+const chartConfig = {
+  desktop: { label: "Desktop", color: "hsl(var(--primary))" },
+  mobile: { label: "Mobile", color: "hsl(var(--secondary))" },
+}
+
+<ChartContainer config={chartConfig} className="h-[300px]">
+  <BarChart data={data}>
+    <CartesianGrid strokeDasharray="3 3" vertical={false} />
+    <XAxis dataKey="month" tickLine={false} axisLine={false} />
+    <YAxis tickLine={false} axisLine={false} />
+    <ChartTooltip content={<ChartTooltipContent />} />
+    <ChartLegend content={<ChartLegendContent />} />
+    <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
+    <Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
+  </BarChart>
+</ChartContainer>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `config` | `ChartConfig` | - | Configuração de cores e labels para cada série de dados. |
+| `className` | `string` | - | Classes CSS para dimensionamento do container. |
+| `ChartTooltip` | `Component` | - | Componente de tooltip customizado para exibir valores. |
+| `ChartTooltipContent` | `Component` | - | Conteúdo do tooltip com formatação automática. |
+| `ChartLegend` | `Component` | - | Componente de legenda customizado. |
+| `ChartLegendContent` | `Component` | - | Conteúdo da legenda com cores e labels. |
+
+**Exemplos:**
+```tsx
+<BarChart data={data}>
+  <Bar dataKey=
+```
+
+**Acessibilidade:**
+- Cores configuráveis via design tokens para consistência visual
+- Tooltips acessíveis com informações detalhadas
+- Suporte a temas claro/escuro automático
+- Responsivo via ResponsiveContainer interno
+- Legendas clicáveis para filtrar séries
+
+**Notas:**
+- Utiliza a biblioteca **Recharts** internamente
+- As cores são definidas via CSS variables (
+- )
+- Suporte automático a temas light/dark
+- Configure 
+-  para definir cores e labels de cada série
+- Use 
+-  com 
+-  para grids mais limpos
+- Remova 
+-  e 
+-  para visual mais moderno
+
+> Fonte: `src\design-system\docs\components\ChartDoc.tsx`
+
+---
+
+### Dashboards — Visão Geral
+
+Módulo completo de dashboards portado do qex-dashboards Angular. Inclui 14 tipos de painéis com Recharts, grid responsivo com drag-and-drop via @dnd-kit, lista com filtros, formulário multilíngue e visualizador com toolbar.
+
+**Uso:**
+```tsx
+import {
+  // Orquestrador principal
+  DashboardGeneralView,
+
+  // Componentes de página
+  DashboardView,
+  DashboardList,
+  DashboardForm,
+  DashboardGrid,
+  DashboardPanelRenderer,
+
+  // Painéis individuais
+  NumericPanel, TextPanel, ListPanel,
+  CartesianPanel, PiePanel, ParetoPanel,
+  BurndownPanel, PerformancePanel, MatrixRiskPanel,
+
+  // Shared de painel
+  PanelHeader, PanelError, PanelLoader, PanelNoData, PanelUnavailable,
+
+  // Types & Helpers
+  DashboardPanelType, PanelState, AggregationType,
+  type PanelConfig, type Dashboard, type DashboardPanel,
+  getDefaultPanelSize, getMinPanelSize,
+  currencyFormatter, processUrl, getLinkFromRow,
+} from 'forlogic-core';
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `DashboardGeneralView` | `Component` | - | Página orquestradora — integra List → View → Form com máquina de estados, carousel auto-advance e suporte a General View. |
+| `DashboardView` | `Component` | - | Viewer com toolbar (refresh, fullscreen, favorito, share), tabs de páginas e grid de painéis. |
+| `DashboardList` | `Component` | - | Lista/tabela com busca, filtros rápidos, favoritos e menu de contexto. |
+| `DashboardForm` | `Component` | - | Formulário com títulos multilíngue, configurações e aba de compartilhamento. |
+| `DashboardGrid` | `Component` | - | Grid de 8 colunas com @dnd-kit para posicionamento via drag-and-drop. |
+| `DashboardPanelRenderer` | `Component` | - | Mapeia DashboardPanelType → componente React (14 tipos). |
+| `PanelConfig` | `Interface` | - | Configuração base compartilhada por todos os painéis (título, tipo, query, cores, etc.). |
+| `PanelState` | `Enum` | - | Loading (0), Loaded (1), Error (3), NoData (4), Unavailable (5). |
+
+**Exemplos:**
+```tsx
+// O renderer mapeia typeId → componente automaticamente
+<DashboardPanelRenderer
+  config={{ ...panelConfig, typeId: DashboardPanelType.Column }}
+  state={PanelState.Loaded}
+  cartesianData={chartData}
+  cartesianSeries={[{ dataKey:
+```
+
+> Fonte: `src\design-system\docs\components\dashboards\DashboardOverviewDoc.tsx`
+
+---
+
+### DashboardGeneralView
+
+Componente orquestrador que gerencia todo o ciclo de vida do módulo de Dashboards. Integra DashboardList, DashboardView e DashboardForm através de uma máquina de estados, com suporte a carousel auto-advance e General View.
+
+**Uso:**
+```tsx
+import { DashboardGeneralView } from 'forlogic-core';
+
+// Uso básico (uncontrolled — gerencia estado internamente)
+<DashboardGeneralView
+  dashboards={dashboards}
+  limit={{ maxDashboards: 50, countDashboards: 12 }}
+  canAdd canEdit canRemove
+  activePanels={panels}
+  activePages={pages}
+  getPanelData={(panelId) => ({
+    state: PanelState.Loaded,
+    data: panelData[panelId],
+  })}
+  onOpen={(d) => loadPanels(d.id)}
+  onSave={(values) => createDashboard(values)}
+  onUpdate={(id, values) => updateDashboard(id, values)}
+  onRemove={(d) => removeDashboard(d.id)}
+  onToggleFavorite={(d) => toggleFav(d.id)}
+/>
+
+// Uso controlado (com react-router)
+const [viewState, setViewState] = useState({ mode: 'list' });
+
+<DashboardGeneralView
+  dashboards={dashboards}
+  viewState={viewState}
+  onViewStateChange={(state) => {
+    setViewState(state);
+    if (state.mode === 'view') navigate(\`/dashboards/\${state.dashboardId}\`);
+    if (state.mode === 'list') navigate('/dashboards');
+  }}
+  // ... demais props
+/>
+```
+
+**Exemplos:**
+```tsx
+// DashboardViewState
+type DashboardViewState =
+  | { mode:
+```
+
+> Fonte: `src\design-system\docs\components\dashboards\DashboardGeneralViewDoc.tsx`
+
+---
+
+### DashboardList
+
+Lista/tabela de dashboards com busca integrada, filtros rápidos (Todos / Meus / Favoritos), toggle de favorito, status ativo/inativo, ícone de compartilhamento e menu de contexto por linha.
+
+**Uso:**
+```tsx
+import { DashboardList, QuickFilterDashboard } from 'forlogic-core';
+
+<DashboardList
+  dashboards={dashboards}
+  limit={{ maxDashboards: 50, countDashboards: 12 }}
+  language={DashboardLanguage.PtBr}
+  canAdd canEdit canRemove
+  onOpen={(d) => navigate(\`/dashboards/\${d.id}\`)}
+  onEdit={(d) => navigate(\`/dashboards/\${d.id}/edit\`)}
+  onShare={(d) => openShareDialog(d)}
+  onDuplicate={(d) => duplicateDashboard(d.id)}
+  onRemove={(d) => removeDashboard(d.id)}
+  onAdd={() => navigate('/dashboards/new')}
+  onToggleFavorite={(d) => toggleFavorite(d.id)}
+  onSearch={(q) => setSearch(q)}
+  onQuickFilterChange={(f) => setFilter(f)}
+/>
+```
+
+**Exemplos:**
+```tsx
+<DashboardList
+  dashboards={dashboards}
+  limit={{ maxDashboards: 50, countDashboards: 12 }}
+  canAdd canEdit canRemove
+  onOpen={(d) => openDashboard(d)}
+  onToggleFavorite={(d) => toggleFav(d.id)}
+  onSearch={(q) => fetchFiltered(q)}
+  onQuickFilterChange={(filter) => {
+    // QuickFilterDashboard.All | OnlyMine | Favorites
+    refetch(filter);
+  }}
+/>
+```
+```tsx
+// As ações são controladas por callbacks
+<DashboardList
+  canEdit={true}
+  canRemove={true}
+  onOpen={(d) => navigate(\
+```
+
+> Fonte: `src\design-system\docs\components\dashboards\DashboardListDoc.tsx`
+
+---
+
+### DashboardForm
+
+Formulário de criação/edição de dashboards com títulos multilíngue (PT-BR, EN-US, ES-ES), intervalo de atualização, tipo de visualização (Normal/Carousel), switch de situação e aba de compartilhamento com três modos.
+
+**Uso:**
+```tsx
+import { DashboardForm, type DashboardFormValues } from 'forlogic-core';
+
+// Criação
+<DashboardForm
+  onSave={(values: DashboardFormValues) => {
+    // values: { titlePtBr, titleEnUs, titleEsEs, isActive,
+    //           idUpdateTime, idViewType, idPageTime,
+    //           idShare, groups?, places?, collaborators? }
+    createDashboard(values);
+  }}
+  onCancel={() => navigate('/dashboards')}
+/>
+
+// Edição
+<DashboardForm
+  dashboard={existingDashboard}
+  users={usersList}
+  groups={groupsList}
+  places={placesList}
+  collaborators={collaboratorsList}
+  isSaving={mutation.isPending}
+  onSave={(values) => updateDashboard(dashboard.id, values)}
+  onCancel={() => goBack()}
+/>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `dashboard` | `Dashboard | null` | - | Dashboard existente para edição. null para criação. |
+| `initialTab` | `DashboardFormTab` | - | Aba inicial (General ou Share). Default: General. |
+| `isSaving` | `boolean` | - | Desabilita o botão salvar e mostra spinner. |
+| `isQualitfy` | `boolean` | - | Dashboard padrão Qualitfy — bloqueia campos de configuração. |
+| `users` | `Array<{ id, name }>` | - | Lista para seletor de responsável. |
+| `groups / places / collaborators` | `Array<{ id, name }>` | - | Listas para aba de compartilhamento. |
+| `onSave` | `(values: DashboardFormValues) => void` | - | Chamado ao clicar Salvar com valores válidos. |
+| `onCancel` | `() => void` | - | Chamado ao clicar Cancelar. |
+
+**Exemplos:**
+```tsx
+<DashboardForm
+  dashboard={null} // null = criação
+  users={[
+    { id:
+```
+
+> Fonte: `src\design-system\docs\components\dashboards\DashboardFormDoc.tsx`
+
+---
+
+### DashboardView
+
+*Documentação não extraída automaticamente. Consulte o Design System interativo em `/ds`.*
+
+---
+
+### DashboardGrid
+
+Grid de 8 colunas com posicionamento por col/row e dimensão por sizeX/sizeY. Suporta drag-and-drop via @dnd-kit quando allowDragging é true. Cada painel é renderizado como um card com header arrastável.
+
+**Uso:**
+```tsx
+import { DashboardGrid, getDefaultPanelSize, getMinPanelSize } from 'forlogic-core';
+
+<DashboardGrid
+  panels={[
+    { id: 'p1', col: 0, row: 0, sizeX: 4, sizeY: 2 },
+    { id: 'p2', col: 4, row: 0, sizeX: 4, sizeY: 2 },
+    { id: 'p3', col: 0, row: 2, sizeX: 8, sizeY: 2 },
+  ]}
+  columns={8}          // padrão: 8
+  cellHeight={160}     // padrão: 160px
+  cellGap={10}         // padrão: 10px
+  allowDragging={canEdit}
+  showGridLines={canEdit}
+  renderPanel={(panelId) => <MyPanelComponent id={panelId} />}
+  onLayoutChange={(updatedPanels) => saveLayout(updatedPanels)}
+/>
+```
+
+**Exemplos:**
+```tsx
+<DashboardGrid
+  panels={[
+    { id:
+```
+
+> Fonte: `src\design-system\docs\components\dashboards\DashboardGridDoc.tsx`
+
+---
+
+### DashboardPanelRenderer
+
+Componente de roteamento que mapeia DashboardPanelType para o componente React correto. Recebe config + state e props de dados especializadas, delegando a renderização ao painel apropriado.
+
+**Uso:**
+```tsx
+import { DashboardPanelRenderer, PanelState, DashboardPanelType } from 'forlogic-core';
+
+// O renderer resolve automaticamente qual componente usar
+<DashboardPanelRenderer
+  config={{
+    id: 'p1',
+    title: 'Ocorrências por Mês',
+    typeId: DashboardPanelType.Column,
+    // ... demais campos de PanelConfig
+  }}
+  state={PanelState.Loaded}
+  cartesianData={[
+    { key: 'Jan', value: 42 },
+    { key: 'Fev', value: 58 },
+  ]}
+  cartesianSeries={[{ dataKey: 'value', name: 'Total' }]}
+/>
+
+// Para NumericPanel, use numericValue:
+<DashboardPanelRenderer
+  config={{ ...config, typeId: DashboardPanelType.Numeric }}
+  state={PanelState.Loaded}
+  numericValue={1247}
+/>
+
+// Para MatrixRisk, use matrixRule + matrixRisks:
+<DashboardPanelRenderer
+  config={{ ...config, typeId: DashboardPanelType.RiskMatrix }}
+  state={PanelState.Loaded}
+  matrixRule={rule}
+  matrixRisks={risks}
+/>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `config` | `PanelConfig` | - | Configuração do painel — inclui typeId que determina qual componente renderizar. |
+| `state` | `PanelState` | - | Estado atual do painel (Loading, Loaded, Error, NoData, Unavailable). |
+
+> Fonte: `src\design-system\docs\components\dashboards\DashboardPanelRendererDoc.tsx`
+
+---
+
+### Painéis Básicos
+
+Os três painéis não-gráficos do módulo de dashboards: NumericPanel (valor numérico agregado com formatação de moeda), TextPanel (HTML rico via dangerouslySetInnerHTML) e ListPanel (tabela de dados com colunas dinâmicas e links de navegação).
+
+**Uso:**
+```tsx
+import { NumericPanel, TextPanel, ListPanel, PanelState } from 'forlogic-core';
+
+// Painel Numérico
+<NumericPanel
+  config={panelConfig}
+  state={PanelState.Loaded}
+  value={1247}
+  label="Contagem"    // override do label automático
+  onClick={() => openPopover()}
+/>
+
+// Painel de Texto
+<TextPanel
+  config={{ ...panelConfig, textTypeString: '<h3>Título</h3><p>Conteúdo</p>' }}
+  state={PanelState.Loaded}
+/>
+
+// Painel de Lista
+<ListPanel
+  config={panelConfig}
+  state={PanelState.Loaded}
+  data={rows}
+  columns={columnDefinitions}
+  enableRowLinks={true}
+  onRowClick={(row) => openDetail(row)}
+/>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `NumericPanel.value` | `number | string | null` | - | Valor numérico a exibir. Formatado automaticamente como moeda quando o campo é de custo. |
+| `NumericPanel.label` | `string` | - | Override do label de agregação. Sem ele, usa o mapa interno (Count→Contagem, Sum→Soma, etc.). |
+| `NumericPanel.onClick` | `() => void` | - | Torna o valor clicável (cursor pointer + hover). |
+| `TextPanel.htmlContent` | `string` | - | HTML alternativo. Sem ele, usa config.textTypeString. |
+
+**Exemplos:**
+```tsx
+// Contagem simples
+<NumericPanel config={config} state={PanelState.Loaded} value={1247} />
+
+// Com formatação de moeda (detectado pelo campo
+```
+```tsx
+<TextPanel
+  config={{
+    ...config,
+    textTypeString:
+```
+```tsx
+<ListPanel
+  config={config}
+  state={PanelState.Loaded}
+  data={[
+    { code:
+```
+```tsx
+OC-002
+```
+
+> Fonte: `src\design-system\docs\components\dashboards\DashboardPanelsBasicDoc.tsx`
+
+---
+
+### Painéis Cartesianos
+
+CartesianPanel é um componente unificado que renderiza 6 variantes de gráfico (Bar, Column, StackedColumn, Area, Line, EvolutionLine) via a prop variant. Todos usam Recharts internamente e compartilham a mesma API de dados.
+
+**Uso:**
+```tsx
+import { CartesianPanel, PanelState, type CartesianSeries } from 'forlogic-core';
+
+// Uso básico — série única
+<CartesianPanel
+  config={panelConfig}
+  variant="column"   // 'bar' | 'column' | 'stacked-column' | 'area' | 'line' | 'evolution-line'
+  state={PanelState.Loaded}
+  data={[
+    { key: 'Jan', value: 42 },
+    { key: 'Fev', value: 58 },
+  ]}
+/>
+
+// Múltiplas séries
+<CartesianPanel
+  config={panelConfig}
+  variant="column"
+  state={PanelState.Loaded}
+  data={data}
+  series={[
+    { dataKey: 'opened', name: 'Abertas', color: '#4e79a7' },
+    { dataKey: 'closed', name: 'Fechadas', color: '#59a14f' },
+  ]}
+  categoryKey="month"         // chave do eixo X (default: 'key')
+  yAxisFormat="R$ {value}"    // formato do eixo Y
+  onPointClick={(data, index) => openDetail(data)}
+/>
+```
+
+**Exemplos:**
+```tsx
+<CartesianPanel
+  config={config}
+  variant=
+```
+
+> Fonte: `src\design-system\docs\components\dashboards\DashboardPanelsCartesianDoc.tsx`
+
+---
+
+### Painéis Especiais
+
+Cinco painéis especializados: PiePanel (pizza com percentuais), ParetoPanel (barras + linha cumulativa), BurndownPanel (execução vs planejamento), PerformancePanel (barras comparativas) e MatrixRiskPanel (grid de criticidade com tooltips).
+
+**Uso:**
+```tsx
+import {
+  PiePanel, ParetoPanel, BurndownPanel,
+  PerformancePanel, MatrixRiskPanel,
+  PanelState, MatrixViewType,
+} from 'forlogic-core';
+
+// Pie
+<PiePanel config={config} state={PanelState.Loaded} data={pieData} />
+
+// Pareto
+<ParetoPanel config={config} state={PanelState.Loaded} data={paretoData} />
+
+// Burndown
+<BurndownPanel config={config} state={PanelState.Loaded} data={burndownData} />
+
+// Performance
+<PerformancePanel config={config} state={PanelState.Loaded} data={performanceData} />
+
+// Matrix Risk
+<MatrixRiskPanel
+  config={config}
+  state={PanelState.Loaded}
+  rule={matrixRule}
+  risks={risks}
+  matrixViewType={MatrixViewType.Quantity}
+/>
+```
+
+**Exemplos:**
+```tsx
+<PiePanel
+  config={config}
+  state={PanelState.Loaded}
+  data={[
+    { key:
+```
+
+> Fonte: `src\design-system\docs\components\dashboards\DashboardPanelsSpecialDoc.tsx`
+
+---