forlogic-core 3.0.10 → 4.0.0

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

@@ -1,547 +0,0 @@
-<!-- ⚠️ 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`
-
----