@wibi-global/sdk 0.1.0 → 0.1.2

package/dist/sdk/src/data/widgets.wbx

@@ -0,0 +1,2477 @@
+{
+    "__CONTEXT_BLOCK__": {
+        "block_name": "WIDGET_SCHEMA",
+        "block_role": "SOURCE_OF_TRUTH_FOR_WIDGETS_COMPONENTS_AND_PROPS",
+        "llm_instruction": "Este bloco define contratos válidos de widgets, componentes e props que o TSX pode usar. Para dashboard.serialized.json, cada widget (chart, grid, kpi, progress-list) é sempre um elemento INDEPENDENTE e DIRETO na section — NUNCA embrulhe dois ou mais widgets dentro de um group, container ou div com título. PROIBIDO criar seções aglutinadoras como 'Evolução Temporal' que contêm múltiplos charts. Cada chart tem sua própria entrada em widgets[] com seu próprio title em properties. SHOW_TITLE: sections SEMPRE com show_title: false — o title da section é ID interno, nunca visual. Um section com show_title: true renderiza um container com header que envolve todos os widgets dentro — isso é PROIBIDO.",
+        "last_synced_from": "wibi/src/pages/bi/designer/config/widgetSchemas.ts",
+        "last_synced_date": "2026-03-20"
+    },
+    "__SQL_TEMPLATE_RULES__": {
+        "block_name": "SQL_TEMPLATE_RULES",
+        "block_role": "REGRAS_CRITICAS_PARA_GERACAO_DE_SQL_NO_dashboard.serialized.json",
+        "llm_instruction": "LEIA ESTE BLOCO ANTES DE ESCREVER QUALQUER sql_template. Ele define as únicas variáveis aceitas pelo resolveSqlTemplate() do renderer.",
+
+        "variaveis_substituidas_pelo_renderer": {
+            "{{startDate}}": "Data de início do período selecionado pelo usuário. Formato: 'YYYY-MM-DD'. Aliases aceitos: {{start_date}}, ${startDate}.",
+            "{{endDate}}": "Data de fim do período selecionado pelo usuário. Formato: 'YYYY-MM-DD'. Aliases aceitos: {{end_date}}, ${endDate}.",
+            "{{year}}": "Ano de início extraído de startDate (4 dígitos). Ex: 2025.",
+            "{{dsoStartDate}}": "Data de início ampliada (2 anos atrás) para janelas DSO. Alias aceito: {{date_limit_2y}}.",
+            "${companyFilter:alias}": "Injeta 'AND alias.id_empresa = N' quando empresa está selecionada, ou string vazia. N = empresaId selecionado.",
+            "${empresaId}": "ID numérico da empresa selecionada (0 se nenhuma). Aliases: ${companyId}, ${companyIds}."
+        },
+
+        "filtros_de_dropdown_NAO_vao_no_SQL": {
+            "REGRA_ABSOLUTA": "O dropdown filtra os dados NO CLIENTE (browser) DEPOIS que a query retornou. A query SQL não sabe que existe um dropdown. NUNCA crie variáveis de dropdown no sql_template.",
+            "COMO_FUNCIONA": "1. A query executa no banco e retorna TODOS os registros do período. 2. O widget dropdown lê os valores únicos do campo filter_field desse resultado. 3. Quando o usuário seleciona um valor, o renderer filtra as linhas localmente. 4. Todos os widgets com a mesma query_id passam a ver apenas as linhas filtradas. Nenhuma nova query é disparada.",
+            "PROIBIDO_ABSOLUTAMENTE": [
+                "{{#estado}}...{{/estado}} — Mustache condicional — NÃO EXISTE no renderer — causa SYNTAX_ERROR no banco",
+                "{{estado}} como filtro — a variável {{estado}} NÃO É substituída pelo renderer — chega literal no banco — causa SYNTAX_ERROR",
+                "AND (estado IN ({{estado}}) OR {{estado}} IS NULL) — PROIBIDO — mesma razão",
+                "AND campo = '{{valorDropdown}}' — PROIBIDO — valores de dropdown nunca são injetados no SQL",
+                "{% if campo %}...{% endif %} — Jinja — NÃO É suportado",
+                "qualquer tentativa de tornar o SQL condicional baseado em seleção de dropdown"
+            ],
+            "CORRETO": "A query retorna TODOS os dados. O dropdown filtra localmente. Ponto final."
+        },
+
+        "padrao_correto_de_query_com_dropdown": {
+            "explicacao": "Dashboard com dropdown de 'estado' filtrando charts e grid. A query NÃO menciona estado em nenhuma variável — apenas usa {{startDate}} e {{endDate}}.",
+            "query_CORRETA": {
+                "id": "q-vendas",
+                "sql_template": "SELECT estado, produto, sum(valor) AS total FROM vw_vendas WHERE data >= '{{startDate}}' AND data <= '{{endDate}}' GROUP BY estado, produto ORDER BY total DESC"
+            },
+            "query_ERRADA_nao_fazer": {
+                "id": "q-vendas",
+                "sql_template": "SELECT estado, produto, sum(valor) AS total FROM vw_vendas WHERE data >= '{{startDate}}' AND data <= '{{endDate}}' AND (estado IN ({{estado}}) OR {{estado}} IS NULL) GROUP BY estado, produto ORDER BY total DESC",
+                "motivo_do_erro": "{{estado}} não é substituída pelo renderer. Chega literal no banco. ClickHouse retorna SYNTAX_ERROR."
+            },
+            "dropdown_widget": {
+                "id": "w-filtro-estado",
+                "widget_type": "dropdown",
+                "query_id": "q-vendas",
+                "properties": {
+                    "filter_field": "estado",
+                    "label": "Filtrar por Estado",
+                    "allow_multiple": true
+                }
+            },
+            "chart_widget": {
+                "id": "w-chart-vendas",
+                "widget_type": "chart",
+                "query_id": "q-vendas",
+                "properties": { "chart_type": "bar", "x_field": "estado", "y_field": "total" }
+            },
+            "resultado": "Dropdown e chart compartilham query_id='q-vendas'. Ao selecionar 'SP' no dropdown, o chart exibe só SP — sem nova query SQL."
+        },
+
+        "variaveis_NAO_suportadas": [
+            "{{#campo}}...{{/campo}} — Mustache condicional — NÃO EXISTE",
+            "{{campo}} como valor de filtro de dropdown — NÃO É substituída",
+            "qualquer variável além das listadas em variaveis_substituidas_pelo_renderer"
+        ],
+
+        "como_filtrar_por_empresa_no_sql": {
+            "padrao": "Use ${companyFilter:alias} para injetar o filtro de empresa automaticamente.",
+            "exemplo": "SELECT * FROM vw_vendas v WHERE v.data >= '{{startDate}}' AND v.data <= '{{endDate}}' ${companyFilter:v}",
+            "resultado_com_empresa": "SELECT * FROM vw_vendas v WHERE v.data >= '2025-01-01' AND v.data <= '2025-03-31' AND v.id_empresa = 42",
+            "resultado_sem_empresa": "SELECT * FROM vw_vendas v WHERE v.data >= '2025-01-01' AND v.data <= '2025-03-31' "
+        },
+
+        "resumo_regras_de_ouro": [
+            "1. sql_template só aceita {{startDate}}, {{endDate}}, {{year}}, {{dsoStartDate}}, ${companyFilter:alias}, ${empresaId}.",
+            "2. Filtros de dropdown NÃO entram no SQL — são aplicados no cliente.",
+            "3. NUNCA use {{#campo}}...{{/campo}} — causa SYNTAX_ERROR no banco.",
+            "4. A query deve sempre retornar todos os dados do período; o dropdown filtra localmente.",
+            "5. Para filtrar por empresa no SQL, use ${companyFilter:alias} — nunca uma variável de dropdown."
+        ]
+    },
+    "__WIDGET_SELECTION_GUIDE__": {
+        "block_name": "WIDGET_SELECTION_GUIDE",
+        "block_role": "LLM_INTELLIGENCE — guia de escolha do widget_type certo para cada situação",
+        "llm_instruction": "Use esta tabela para decidir o widget_type mais adequado antes de criar qualquer widget no dashboard.serialized.json.",
+        "by_use_case": {
+            "indicador_unico": "widget_type='kpi' — para exibir UM número em destaque (faturamento total, qtd pedidos). Use múltiplos 'kpi' em seção multi-coluna para painel de indicadores.",
+            "indicador_com_tendencia": "widget_type='sparkline' — KPI com mini gráfico de tendência embutido.",
+            "varios_kpis_configurados": "widget_type='multi-card' — vários indicadores com ícone/cor em um único widget.",
+            "barras_verticais": "widget_type='chart' com chart_type='bar'",
+            "barras_horizontais": "widget_type='chart' com chart_type='horizontal_bar'",
+            "barras_empilhadas": "widget_type='chart' com chart_type='stacked_bar'",
+            "linha_de_tendencia": "widget_type='chart' com chart_type='line'",
+            "area_volume": "widget_type='chart' com chart_type='area'",
+            "pizza_proporcao": "widget_type='chart' com chart_type='pie'",
+            "donut_proporcao": "widget_type='chart' com chart_type='pie' e inner_radius > 0",
+            "ranking_com_barra": "widget_type='progress-list' — top N itens com barra proporcional",
+            "tabela_de_dados": "widget_type='grid' — tabela paginável com formatação por coluna",
+            "tabela_cruzada": "widget_type='pivot' — linhas × colunas com valor agregado",
+            "velocimetro_meta": "widget_type='gauge' — medidor circular com escala",
+            "funil_conversao": "widget_type='funnel' — etapas de pipeline decrescentes",
+            "cascata_contribuicao": "widget_type='waterfall' — parcelas positivas/negativas para um total",
+            "dispersao_correlacao": "widget_type='scatter' — dois campos numéricos X×Y",
+            "mapa_calor_matriz": "widget_type='heatmap' — grade colorida por intensidade",
+            "hierarquia_retangulos": "widget_type='treemap' — blocos proporcionais ao valor",
+            "hierarquia_aneis": "widget_type='sunburst' — anéis concêntricos hierárquicos",
+            "hierarquia_arvore": "widget_type='tree' — nós pai-filho com setas",
+            "fluxo_entre_nos": "widget_type='sankey' — diagrama de fluxo entre categorias",
+            "rede_relacionamentos": "widget_type='graph' — nós conectados por arestas",
+            "comparacao_multivariada": "widget_type='radar' — aranha com múltiplos eixos",
+            "velas_financeiras": "widget_type='candlestick' — OHLC financeiro",
+            "distribuicao_estatistica": "widget_type='boxplot' — mediana, quartis, outliers",
+            "fluxo_tematico_tempo": "widget_type='themeriver' — categorias evoluindo ao longo do tempo",
+            "eventos_cronologicos": "widget_type='timeline' — linha do tempo de eventos",
+            "pontos_no_mapa": "widget_type='map' — marcadores lat/lon no mapa",
+            "regioes_coloridas": "widget_type='filled-map' — coroplético por estado/país",
+            "rotas_geograficas": "widget_type='lines' — fluxo animado entre dois pontos geo",
+            "filtro_combobox": "widget_type='dropdown' — seleção de valor de um campo para filtrar",
+            "filtro_slicer": "widget_type='filter' — painel de filtro visual com botões",
+            "filtro_periodo": "widget_type='date' — seletor de período (Dia/Semana/Mês/Ano)",
+            "filtro_empresa": "widget_type='companies' — seletor de empresa",
+            "titulo_secao": "widget_type='heading' — H1/H2/H3/H4 decorativo",
+            "texto_livre": "widget_type='text' — bloco de texto/markdown",
+            "imagem_logo": "widget_type='image' — imagem estática",
+            "separador": "widget_type='divider' — linha separadora",
+            "espacamento": "widget_type='spacer' — espaço vertical"
+        },
+        "height_recommendations": {
+            "kpi": 120,
+            "sparkline": 150,
+            "multi-card": 160,
+            "chart": 400,
+            "grid": 350,
+            "pivot": 380,
+            "progress-list": 350,
+            "gauge": 320,
+            "funnel": 350,
+            "waterfall": 400,
+            "scatter": 380,
+            "heatmap": 380,
+            "treemap": 360,
+            "sunburst": 400,
+            "tree": 420,
+            "sankey": 400,
+            "graph": 420,
+            "radar": 380,
+            "candlestick": 380,
+            "boxplot": 360,
+            "parallel": 380,
+            "themeriver": 380,
+            "timeline": 400,
+            "map": 380,
+            "filled-map": 400,
+            "lines": 400
+        }
+    },
+    "dashboardStyling": {
+        "llm_instruction": "O dashboard.serialized.json suporta propriedades de estilização global (em metadata) e por seção (em layout.sections[]). A organização visual deve acontecer com sections, heading/text/divider e widgets diretos. NUNCA use group para agrupar charts. CADA chart é um widget independente em widgets[] com title em properties.title — não existe 'container de charts'. Dois charts side-by-side = dois widgets na mesma section com col_span adequado. Um chart por linha = um widget com col_span igual ao número de colunas da section. CRÍTICO: show_title nas sections é SEMPRE false — o title da section é um identificador interno, NUNCA um cabeçalho visual. O título visível de um chart vai SOMENTE em properties.title do widget.",
+        "metadata_styling_properties": {
+            "background_color": {
+                "type": "string",
+                "description": "Cor de fundo global do dashboard. Aceita hex (#f0f4f8), rgb(240,244,248), ou CSS gradient (linear-gradient(135deg, #667eea, #764ba2)).",
+                "example": "#f8fafc"
+            },
+            "text_color": {
+                "type": "string",
+                "description": "Cor do texto padrão do dashboard.",
+                "example": "#1e293b"
+            },
+            "font_family": {
+                "type": "string",
+                "description": "Fonte customizada. Ex: 'Inter, sans-serif'"
+            },
+            "section_gap": {
+                "type": "number",
+                "description": "Espaçamento vertical entre seções em px. Padrão: 26.",
+                "example": 32
+            },
+            "padding": {
+                "type": "number",
+                "description": "Padding geral do canvas em px. Padrão: 24.",
+                "example": 16
+            }
+        },
+        "section_styling_properties": {
+            "background_color": { "type": "string", "description": "Cor de fundo da seção." },
+            "text_color": { "type": "string", "description": "Cor do texto da seção." },
+            "border_radius": { "type": "number", "description": "Raio de borda em px." },
+            "padding": { "type": "number", "description": "Padding interno em px." },
+            "show_title": { "type": "boolean", "default": false, "description": "SEMPRE false — oculta o título da seção. O título de cada chart/widget vai em properties.title do próprio widget, NUNCA no title da section. REGRA: show_title deve ser false em TODAS as sections do dashboard.serialized.json." }
+        },
+        "section_llm_rules": {
+            "llm_instruction": "REGRA CRÍTICA DE SECTIONS: show_title DEVE ser sempre false. O 'title' do SerializedSection é apenas um identificador interno — NUNCA é renderizado visualmente. Título visível de um chart/grid/kpi vai EXCLUSIVAMENTE em properties.title do widget. Uma section com title='Evolução Temporal' e show_title=true renderiza como um CONTAINER VISUAL com header 'Evolução Temporal' envolvendo todos os widgets — isso é PROIBIDO. Padrão correto: { id: 'sec-charts', title: 'charts', show_title: false, columns: 2, items: ['w-chart-1', 'w-chart-2'] } — cada widget declara seu próprio title em properties."
+        },
+        "widget_styling_properties": {
+            "llm_instruction": "Todo widget (data ou decorativo) pode ter estas propriedades opcionais de estilização:",
+            "background_color": { "type": "string", "description": "Cor de fundo do widget." },
+            "text_color": { "type": "string", "description": "Cor do texto do widget." },
+            "border_radius": { "type": "number", "description": "Raio de borda em px." },
+            "borderless": { "type": "boolean", "default": false, "description": "Se true, remove borda e sombra do widget." }
+        }
+    },
+    "implicitDataProperties": {
+        "description": "Propriedades injetadas automaticamente por getDefaultProperties() em TODO widget que NÃO está na lista NO_DATA_WIDGETS. Fonte: widgetSchemas.ts → getDefaultProperties()",
+        "NO_DATA_WIDGETS": ["text", "image", "group", "date", "companies"],
+        "injectedProps": {
+            "sql": {
+                "type": "string",
+                "defaultValue": "",
+                "description": "Query SQL que alimenta o widget. Pode ser definida pelo designer ou pela LLM via customSQL."
+            },
+            "connectionConfig": {
+                "type": "object | null",
+                "defaultValue": null,
+                "description": "Configuração de conexão BI (connectionId, host, etc). Geralmente vem do DataSource vinculado."
+            },
+            "biConnectionId": {
+                "type": "number",
+                "defaultValue": 0,
+                "description": "ID da conexão BI usada para executar a query SQL. 0 = não configurado."
+            }
+        },
+        "llm_instruction": "Todo widget que carrega dados possui implicitamente sql, connectionConfig e biConnectionId em properties. Widgets com noData:true NÃO possuem essas props."
+    },
+    "tsxContracts": {
+        "EChartsChart": {
+            "import": "@/pages/bi/designer/components/items/EChartsChart",
+            "component": "EChartsChart",
+            "requiredProps": [
+                "item",
+                "data"
+            ],
+            "optionalProps": [
+                "theme",
+                "onUpdate",
+                "isDesignMode",
+                "enableTypeSwitcher",
+                "showZoomButton",
+                "onCrossFilterTrigger"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ],
+            "itemShape": {
+                "type": "DashboardItem",
+                "required": [
+                    "id",
+                    "type",
+                    "position",
+                    "size",
+                    "properties"
+                ],
+                "optional": [
+                    "title",
+                    "dataSource",
+                    "zIndex",
+                    "locked",
+                    "children",
+                    "category",
+                    "widgetFields",
+                    "customSQL"
+                ],
+                "properties": {
+                    "type": "chart",
+                    "properties": [
+                        "option",
+                        "theme",
+                        "xField",
+                        "yFields",
+                        "chartType",
+                        "aggregation"
+                    ]
+                }
+            },
+            "notes": [
+                "usar item, nunca widget",
+                "preferir properties.option para dashboards gerados",
+                "data deve ser array",
+                "xField, yFields e aggregation são gerenciados pelo WidgetFieldDropZone no designer"
+            ]
+        },
+        "GridComponent": {
+            "import": "@/pages/bi/designer/components/items/GridComponent",
+            "component": "GridComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "theme",
+                "onUpdate",
+                "isDesignMode"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ],
+            "notes": [
+                "widget de tabela dentro do Designer",
+                "usar item.properties.selectedColumns para definir colunas visíveis"
+            ]
+        },
+        "KpiComponent": {
+            "import": "@/pages/bi/designer/components/items/KpiComponent",
+            "component": "KpiComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "isDesignMode",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "CardComponent": {
+            "import": "@/pages/bi/designer/components/items/CardComponent",
+            "component": "CardComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "isDesignMode",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "MultiCardComponent": {
+            "import": "@/pages/bi/designer/components/items/MultiCardComponent",
+            "component": "MultiCardComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "isDesignMode",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "SparklineComponent": {
+            "import": "@/pages/bi/designer/components/items/SparklineComponent",
+            "component": "SparklineComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "isDesignMode",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "FunnelComponent": {
+            "import": "@/pages/bi/designer/components/items/FunnelComponent",
+            "component": "FunnelComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "theme",
+                "onUpdate",
+                "isDesignMode"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "GaugeComponent": {
+            "import": "@/pages/bi/designer/components/items/GaugeComponent",
+            "component": "GaugeComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "EChartsGauge": {
+            "import": "@/pages/bi/designer/components/items/EChartsGauge",
+            "component": "EChartsGauge",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "theme",
+                "onUpdate",
+                "isDesignMode"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ],
+            "notes": [
+                "versão ECharts do velocímetro, alternativa ao GaugeComponent"
+            ]
+        },
+        "WaterfallComponent": {
+            "import": "@/pages/bi/designer/components/items/WaterfallComponent",
+            "component": "WaterfallComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "theme",
+                "onUpdate",
+                "isDesignMode"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "PivotComponent": {
+            "import": "@/pages/bi/designer/components/items/PivotComponent",
+            "component": "PivotComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ],
+            "notes": [
+                "tabela pivot para análise cruzada de dados"
+            ]
+        },
+        "ScatterComponent": {
+            "import": "@/pages/bi/designer/components/items/ScatterComponent",
+            "component": "ScatterComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "theme",
+                "onUpdate",
+                "isDesignMode",
+                "onCrossFilterTrigger"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "HeatmapComponent": {
+            "import": "@/pages/bi/designer/components/items/HeatmapComponent",
+            "component": "HeatmapComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "isDesignMode",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "RadarComponent": {
+            "import": "@/pages/bi/designer/components/items/RadarComponent",
+            "component": "RadarComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "isDesignMode",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "TreemapComponent": {
+            "import": "@/pages/bi/designer/components/items/TreemapComponent",
+            "component": "TreemapComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "isDesignMode",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "BoxplotComponent": {
+            "import": "@/pages/bi/designer/components/items/BoxplotComponent",
+            "component": "BoxplotComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "isDesignMode",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "CandlestickComponent": {
+            "import": "@/pages/bi/designer/components/items/CandlestickComponent",
+            "component": "CandlestickComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "isDesignMode",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "SankeyComponent": {
+            "import": "@/pages/bi/designer/components/items/SankeyComponent",
+            "component": "SankeyComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "isDesignMode",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "GraphComponent": {
+            "import": "@/pages/bi/designer/components/items/GraphComponent",
+            "component": "GraphComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "isDesignMode",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "SunburstComponent": {
+            "import": "@/pages/bi/designer/components/items/SunburstComponent",
+            "component": "SunburstComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "isDesignMode",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "TreeChartComponent": {
+            "import": "@/pages/bi/designer/components/items/TreeChartComponent",
+            "component": "TreeChartComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "isDesignMode",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "ParallelComponent": {
+            "import": "@/pages/bi/designer/components/items/ParallelComponent",
+            "component": "ParallelComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "isDesignMode",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "ThemeRiverComponent": {
+            "import": "@/pages/bi/designer/components/items/ThemeRiverComponent",
+            "component": "ThemeRiverComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "isDesignMode",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "EffectScatterComponent": {
+            "import": "@/pages/bi/designer/components/items/EffectScatterComponent",
+            "component": "EffectScatterComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "isDesignMode",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "PictorialBarComponent": {
+            "import": "@/pages/bi/designer/components/items/PictorialBarComponent",
+            "component": "PictorialBarComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "isDesignMode",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "MapComponent": {
+            "import": "@/pages/bi/designer/components/items/MapComponent",
+            "component": "MapComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "isDesignMode",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "FilledMapComponent": {
+            "import": "@/pages/bi/designer/components/items/FilledMapComponent",
+            "component": "FilledMapComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "isDesignMode",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "LinesComponent": {
+            "import": "@/pages/bi/designer/components/items/LinesComponent",
+            "component": "LinesComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "isDesignMode",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "TextComponent": {
+            "import": "@/pages/bi/designer/components/items/TextComponent",
+            "component": "TextComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "theme",
+                "isDesignMode"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "ImageComponent": {
+            "import": "@/pages/bi/designer/components/items/ImageComponent",
+            "component": "ImageComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ],
+            "notes": [
+                "não recebe data — é widget estático"
+            ]
+        },
+        "FilterComponent": {
+            "import": "@/pages/bi/designer/components/items/FilterComponent",
+            "component": "FilterComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "DropdownComponent": {
+            "import": "@/pages/bi/designer/components/items/DropdownComponent",
+            "component": "DropdownComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "isDesignMode",
+                "onFilterChange",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "TimelineComponent": {
+            "import": "@/pages/bi/designer/components/items/TimelineComponent",
+            "component": "TimelineComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "isDesignMode",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "ProgressListComponent": {
+            "import": "@/pages/bi/designer/components/items/ProgressListComponent",
+            "component": "ProgressListComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "isDesignMode",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ]
+        },
+        "GroupComponent": {
+            "import": "@/pages/bi/designer/components/items/GroupComponent",
+            "component": "GroupComponent",
+            "requiredProps": [
+                "item"
+            ],
+            "optionalProps": [
+                "data",
+                "onUpdate",
+                "isDesignMode",
+                "dataSources",
+                "allItems",
+                "onItemUpdate",
+                "onItemDelete",
+                "onItemSelect",
+                "selectedItem",
+                "viewMode",
+                "getAggregatedData",
+                "theme"
+            ],
+            "forbiddenProps": [
+                "widget"
+            ],
+            "notes": [
+                "container que agrupa widgets filhos",
+                "viewMode aceita 'design' | 'preview'"
+            ]
+        },
+        "DataGrid": {
+            "import": "@/components/DataGrid",
+            "component": "DataGrid",
+            "requiredProps": [
+                "data"
+            ],
+            "recommendedProps": [
+                "title",
+                "loading",
+                "error",
+                "pageSize",
+                "enableSearch",
+                "enableFilters",
+                "enableExport",
+                "enablePagination",
+                "enableSort",
+                "customColumns",
+                "columnLabels",
+                "defaultVisibleColumns",
+                "defaultSortColumn",
+                "defaultSortDirection",
+                "rowIdField"
+            ],
+            "llmContract": {
+                "requiredProps": [
+                    "columns",
+                    "data"
+                ],
+                "columnShape": [
+                    "field",
+                    "header",
+                    "width"
+                ],
+                "forbiddenProps": [
+                    "widget"
+                ]
+            },
+            "sourceProps": [
+                "data",
+                "loading",
+                "error",
+                "title",
+                "subtitle",
+                "onRefresh",
+                "enableFilters",
+                "enableSearch",
+                "searchPlaceholder",
+                "enableExport",
+                "enablePagination",
+                "enableSort",
+                "enableColumnResize",
+                "enableColumnReorder",
+                "enableAggregation",
+                "enableFullscreen",
+                "enableColumnSettings",
+                "theme",
+                "enableHeader",
+                "fullWidthColumns",
+                "pageSize",
+                "totalRows",
+                "currentPage",
+                "onPageChange",
+                "onPageSizeChange",
+                "customColumns",
+                "columnLabels",
+                "columnAliases",
+                "defaultVisibleColumns",
+                "defaultSortColumn",
+                "defaultSortDirection",
+                "canNextPage",
+                "canPreviousPage",
+                "enableAdd",
+                "onAdd",
+                "addButtonText",
+                "onRowClick",
+                "enableEditing",
+                "rowIdField",
+                "onEditsChange",
+                "columnIcons",
+                "columnAggregationDefaults",
+                "defaultColumnWidths"
+            ],
+            "notes": [
+                "o system prompt exige columns+data para geração TSX",
+                "o componente fonte atual expõe data e props de configuração de colunas",
+                "nunca usar widget"
+            ]
+        },
+        "DataGridV2": {
+            "import": "@/components/DataGridV2",
+            "component": "DataGridV2",
+            "requiredProps": [
+                "data",
+                "columns",
+                "rowKey"
+            ],
+            "optionalProps": [
+                "loading",
+                "loadingMessage",
+                "emptyMessage",
+                "onRowClick",
+                "rowClassName",
+                "footer",
+                "pagination",
+                "sortDescriptor",
+                "onSortChange",
+                "initialSort"
+            ],
+            "columnShape": {
+                "type": "DataGridV2Column<T>",
+                "required": [
+                    "id",
+                    "header"
+                ],
+                "optional": [
+                    "render",
+                    "accessor",
+                    "transform",
+                    "formatOptions",
+                    "inferFormat",
+                    "headerClassName",
+                    "cellClassName",
+                    "sortable",
+                    "width",
+                    "minWidth"
+                ]
+            },
+            "paginationShape": {
+                "type": "DataGridV2Pagination",
+                "fields": [
+                    "currentPage",
+                    "totalPages",
+                    "totalRecords",
+                    "pageSize",
+                    "onPageChange"
+                ]
+            },
+            "notes": [
+                "grid v2 com tipagem genérica <T>",
+                "rowKey é função (row, index) => string",
+                "columns usa accessor + formatOptions ou render customizado",
+                "preferir DataGrid (v1) para uso genérico; DataGridV2 para grids fortemente tipados"
+            ]
+        },
+        "WidgetDate": {
+            "import": "@/components/widgets/WidgetDate",
+            "typeImport": "@/components/widgets/WidgetDate#DatePeriod",
+            "component": "WidgetDate",
+            "canonical": true,
+            "preferredImportPattern": "import WidgetDate, { type DatePeriod } from '@/components/widgets/WidgetDate'",
+            "llmDirective": "Sempre use este WidgetDate como seletor de período padrão do WiBi quando a página precisar de filtro temporal.",
+            "requiredProps": [],
+            "recommendedProps": [
+                "value",
+                "onChange",
+                "className"
+            ],
+            "valueShape": {
+                "type": "DatePeriod",
+                "fields": [
+                    "type",
+                    "startDate",
+                    "endDate"
+                ],
+                "periodTypes": [
+                    "SP",
+                    "D",
+                    "S",
+                    "M",
+                    "T",
+                    "SE",
+                    "A",
+                    "CUSTOM"
+                ]
+            },
+            "notes": [
+                "este é o WidgetDate canônico do projeto WiBi",
+                "usado para filtro de período",
+                "onChange retorna DatePeriod",
+                "preferir exatamente o import '@/components/widgets/WidgetDate'",
+                "seguir o padrão usado em HomeFinanceiro.tsx e DashboardVendas01.tsx"
+            ]
+        },
+        "WidgetEmpresas": {
+            "import": "@/components/widgets/WidgetEmpresas",
+            "component": "WidgetEmpresas",
+            "requiredProps": [
+                "onChange"
+            ],
+            "recommendedProps": [
+                "value",
+                "placeholder",
+                "showIcon",
+                "className",
+                "disabled",
+                "autoSelectFirst"
+            ],
+            "valueShape": {
+                "type": "number|string|array|null"
+            },
+            "notes": [
+                "usado para filtro de empresa",
+                "onChange recebe empresaId:number"
+            ]
+        },
+        "WidgetTipos": {
+            "import": "@/components/widgets/WidgetTipos",
+            "component": "WidgetTipos",
+            "requiredProps": [
+                "tgId",
+                "onChange"
+            ],
+            "optionalProps": [
+                "value",
+                "placeholder",
+                "showIcon",
+                "className",
+                "disabled",
+                "autoSelectFirst",
+                "reloadKey"
+            ],
+            "notes": [
+                "seletor de tipos genérico (ex: tipo de pagamento, tipo de documento)",
+                "tgId identifica o grupo de tipos no banco",
+                "onChange recebe tipoId:number"
+            ]
+        },
+        "WidgetCaixas": {
+            "import": "@/components/widgets/WidgetCaixas",
+            "component": "WidgetCaixas",
+            "requiredProps": [
+                "emCodigo",
+                "onChange"
+            ],
+            "optionalProps": [
+                "value",
+                "placeholder",
+                "showIcon",
+                "className",
+                "disabled",
+                "autoSelectFirst",
+                "onSelect"
+            ],
+            "valueShape": {
+                "type": "number",
+                "description": "cxId do caixa selecionado"
+            },
+            "onSelectShape": {
+                "type": "Caixa | null",
+                "fields": [
+                    "cxId",
+                    "cxData",
+                    "cxHora",
+                    "usCodigo",
+                    "cxFechado",
+                    "cxDataFinal",
+                    "emCodigo",
+                    "cxCaixaConf",
+                    "cxBancoConf",
+                    "cxHoraFinal",
+                    "dataHora"
+                ]
+            },
+            "notes": [
+                "seletor de caixas financeiros por empresa",
+                "emCodigo filtra caixas da empresa selecionada",
+                "onChange recebe caixaId:number",
+                "onSelect recebe o objeto Caixa completo ou null"
+            ]
+        }
+    },
+    "dashboardItemType": {
+        "description": "Tipo universal usado por todos os componentes de widget no Designer",
+        "type": "DashboardItem",
+        "import": "@/pages/bi/designer/types",
+        "fields": {
+            "id": { "type": "string", "required": true },
+            "type": { "type": "string", "required": true, "values": [
+                "chart", "grid", "table", "card", "filter", "text", "image", "line", "pie", "gauge", "pivot", "map",
+                "area", "scatter", "treemap", "multi-card", "kpi", "sparkline", "funnel", "waterfall",
+                "filled-map", "dropdown", "timeline", "group",
+                "radar", "heatmap", "candlestick", "boxplot", "sankey", "graph", "sunburst", "tree",
+                "parallel", "themeriver", "effectScatter", "pictorialBar", "lines", "progress-list",
+                "date", "companies"
+            ]},
+            "position": { "type": "{ x: number; y: number }", "required": true },
+            "size": { "type": "{ width: number; height: number }", "required": true },
+            "title": { "type": "string", "required": false },
+            "dataSource": { "type": "string | null", "required": false },
+            "properties": { "type": "Record<string, any>", "required": false },
+            "zIndex": { "type": "number", "required": false },
+            "locked": { "type": "boolean", "required": false },
+            "children": { "type": "DashboardItem[]", "required": false, "description": "Para widget Group — widgets filhos" },
+            "category": { "type": "'basic' | 'advanced' | 'hierarchical' | 'data' | 'specialized'", "required": false },
+            "widgetFields": { "type": "any[]", "required": false, "description": "Campos configurados do widget (para WidgetFactoryService)" },
+            "customSQL": { "type": "string", "required": false, "description": "SQL customizado da LLM (substitui WidgetSQLBuilder)" }
+        }
+    },
+    "designSystemPatterns": {
+        "canonicalWidgets": {
+            "periodFilter": {
+                "component": "WidgetDate",
+                "import": "@/components/widgets/WidgetDate",
+                "directive": "Quando houver filtro temporal, use WidgetDate como componente padrão."
+            },
+            "empresaFilter": {
+                "component": "WidgetEmpresas",
+                "import": "@/components/widgets/WidgetEmpresas",
+                "directive": "Quando houver filtro de empresa, use WidgetEmpresas como componente padrão."
+            },
+            "tiposFilter": {
+                "component": "WidgetTipos",
+                "import": "@/components/widgets/WidgetTipos",
+                "directive": "Quando houver filtro de tipo genérico (pagamento, documento, etc), use WidgetTipos."
+            },
+            "caixasFilter": {
+                "component": "WidgetCaixas",
+                "import": "@/components/widgets/WidgetCaixas",
+                "directive": "Quando houver filtro de caixa financeiro, use WidgetCaixas."
+            }
+        },
+        "pageLayout": {
+            "sources": [
+                "wibi/src/pages/home/HomeFinanceiro.tsx",
+                "wibi/src/pages/bi/comercial/DashboardVendas01.tsx",
+                "wibi/src/pages/bi/EChartsPlayground.tsx"
+            ],
+            "rules": [
+                "usar container raiz com w-full h-full flex flex-col",
+                "usar header fixo com bg-bg-primary border-b border-border px-4 py-3",
+                "usar área de conteúdo com overflow-auto e espaçamento p-3 ou p-4",
+                "organizar blocos em cards com bg-bg-primary ou bg-bg-secondary border border-border rounded-lg",
+                "usar títulos com text-sm ou text-base font-semibold text-text-primary",
+                "usar textos de apoio com text-xs ou text-[10px] text-text-secondary/text-text-muted",
+                "usar grids responsivos com gap-2, gap-3 ou gap-4",
+                "usar ícones lucide com cores semânticas como text-accent-primary, text-accent-success, text-accent-warning e text-accent-danger"
+            ]
+        },
+        "kpiCards": {
+            "rules": [
+                "usar cards compactos com rounded-lg border border-border p-3",
+                "mostrar título pequeno, valor em destaque e texto auxiliar curto",
+                "usar realce semântico de cor somente quando houver contexto de alerta ou destaque"
+            ]
+        },
+        "chartsAndTables": {
+            "rules": [
+                "combinar DataGrid e EChartsChart em grids de 1 ou 2 colunas",
+                "usar alturas definidas como h-[240px], h-[280px], h-[320px], h-[430px], h-[450px] ou h-[500px] conforme a densidade",
+                "REGRA ABSOLUTA: cada chart ou grid é um widget INDEPENDENTE na section — NUNCA embrulhar dois ou mais charts em um group/container/div com título",
+                "PROIBIDO: criar uma section ou group chamado 'Evolução Temporal', 'Análise', 'Gráficos' etc. para conter múltiplos charts — cada chart tem sua própria section ou aparece diretamente como widget isolado",
+                "quando precisar de título para um chart, use a propriedade title dentro de properties do próprio widget chart, ou um widget heading/text separado na mesma section ANTES do chart",
+                "NUNCA usar group como container de charts — group só existe para composição explicitamente solicitada pelo usuário"
+            ]
+        },
+        "sectionGroupTitles": {
+            "source": "wibi/src/pages/home/HomeComercial.tsx",
+            "description": "Padrão canônico de bloco composto — APENAS para combinar ProgressList + Chart ou Grid + Chart lado a lado dentro de um mesmo card visual. NUNCA usar para embrulhar charts individuais.",
+            "llm_instruction": "ATENÇÃO: este padrão é EXCLUSIVO para blocos compostos que combinam ProgressList + Chart ou Grid + Chart lado a lado (ex: Top Fornecedores lista + pizza). Para charts individuais (bar, line, area, pie sozinhos) NÃO use este padrão — declare o widget diretamente em widgets[] com title em properties.title. No dashboard.serialized.json, um chart por si só NUNCA vai dentro de um container com título. Dois charts side-by-side = dois widgets separados na mesma section, cada um com seu col_span.",
+            "cardContainer": {
+                "className": "bg-bg-primary border border-border rounded-lg p-3",
+                "description": "Card visual opcional para bloco composto. Nao usar como wrapper generico por widget isolado."
+            },
+            "groupHeader": {
+                "className": "flex items-center justify-between mb-3",
+                "title": {
+                    "tag": "h2",
+                    "className": "text-xs font-semibold text-text-primary flex items-center gap-1.5",
+                    "icon": {
+                        "className": "w-3.5 h-3.5 text-accent-primary",
+                        "source": "lucide-react",
+                        "examples": ["BarChart3", "Users", "Package", "Target", "TrendingUp", "ShoppingCart", "DollarSign", "Activity"]
+                    }
+                }
+            },
+            "contentGrid": {
+                "description": "Grid interno para combinar ProgressList + Chart ou Grid + Chart lado a lado",
+                "className": "grid grid-cols-1 lg:grid-cols-2 gap-4 h-[260px]",
+                "variants": {
+                    "tall": "h-[320px]",
+                    "medium": "h-[260px]",
+                    "short": "h-[200px]"
+                },
+                "innerList": "overflow-auto",
+                "innerChart": "h-full"
+            },
+            "realExamples": [
+                {
+                    "title": "Faturamento {ano} — Mês a Mês",
+                    "icon": "BarChart3",
+                    "layout": "lg:col-span-2 (2/3 width) + col simples (1/3 width) para Top 8 Clientes",
+                    "outerGrid": "grid grid-cols-1 lg:grid-cols-3 gap-4",
+                    "content": "EChartsChart (bar) + ProgressListComponent"
+                },
+                {
+                    "title": "Performance de Vendedores",
+                    "icon": "Users",
+                    "layout": "2 colunas iguais dentro do card: ProgressList à esquerda, pie chart à direita",
+                    "innerGrid": "grid grid-cols-1 lg:grid-cols-2 gap-4 h-[260px]",
+                    "content": "ProgressListComponent + EChartsChart (pie)"
+                },
+                {
+                    "title": "Top 10 Produtos",
+                    "icon": "Package",
+                    "layout": "2 colunas iguais: ProgressList à esquerda, barras horizontais à direita",
+                    "innerGrid": "grid grid-cols-1 lg:grid-cols-2 gap-4 h-[260px]",
+                    "content": "ProgressListComponent + EChartsChart (horizontal_bar)"
+                },
+                {
+                    "title": "Indicadores de Saúde Comercial",
+                    "icon": "Target",
+                    "layout": "grid de 5 cards compactos (2 cols mobile, 3 cols tablet, 5 cols desktop)",
+                    "innerGrid": "grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-5 gap-2",
+                    "content": "CardComponent (compact=true) com cores semânticas por threshold"
+                }
+            ],
+            "codePattern": {
+                "description": "Template de JSX para um bloco composto com titulo + chart/list combo. Nao aplicar este padrao a widget unico.",
+                "jsx": "<div className=\"bg-bg-primary border border-border rounded-lg p-3\"><div className=\"flex items-center justify-between mb-3\"><h2 className=\"text-xs font-semibold text-text-primary flex items-center gap-1.5\"><{Icon} className=\"w-3.5 h-3.5 text-accent-primary\" />{Título do Grupo}</h2></div><div className=\"grid grid-cols-1 lg:grid-cols-2 gap-4 h-[260px]\"><div className=\"overflow-auto\">{/* ProgressListComponent ou GridComponent */}</div><div className=\"h-full\">{/* EChartsChart */}</div></div></div>"
+            },
+            "kpiRowPattern": {
+                "description": "Linha de KPIs compactos — padrão da faixa superior e dos indicadores de saúde",
+                "kpiRow": "grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-6 gap-2",
+                "kpiItem": "bg-bg-secondary border border-border rounded-lg p-1.5",
+                "saúdeRow": "grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-5 gap-2",
+                "jsx": "<div className=\"grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-6 gap-2\"><div className=\"bg-bg-secondary border border-border rounded-lg p-1.5\"><CardComponent item={cardItem} data={[{...}]} theme={theme} /></div></div>"
+            }
+        }
+    },
+    "widgets": {
+        "chart": {
+            "name": "Gráfico (ECharts)",
+            "category": "basic",
+            "description": "Componente unificado de gráficos ECharts. Use chart_type para definir o tipo visual: bar, line, area, pie, donut, horizontal_bar, stacked_bar. Todas as propriedades são passadas via properties{} no JSON serializado usando snake_case.",
+            "icon": "📊",
+            "render": "EChartsChart",
+            "defaultSize": { "width": 720, "height": 480 },
+            "default_widget_height": 400,
+            "llm_instruction": "No dashboard.serialized.json, use widget_type='chart' e defina chart_type dentro de properties. SEMPRE defina height no widget chart — o valor padrão recomendado é 400 (ex: { \"height\": 400 }). Para charts que precisam de mais espaço (muitos dados, labels longos, horizontal_bar) use height: 450 ou 500. NUNCA omita height num widget chart — sem ele o gráfico fica pequeno. As cores do gráfico vêm automaticamente da paleta do tema (azul, verde, laranja, vermelho, roxo, ciano, rosa, índigo). Para barras com COR DIFERENTE POR BARRA, use alternate_colors=true. NÃO invente propriedades como color_palette, colors, color_list — elas NÃO existem. A paleta de cores é fixa e gerenciada pelo tema. NUNCA gere enable_zoom: true salvo pedido EXPLÍCITO do usuário. Para rotacionar labels do eixo X use x_axis_label_rotate (número de graus, ex: 45 ou 90) em vez de rotate_labels. Para formatar datas no eixo X use x_axis_date_format com tokens: dd=dia, MM=mês numérico, yyyy/yy=ano, MMMM=mês por extenso, MMM=mês abreviado (ex: 'MMMM/yy' → Março/25, 'MMM/yy' → Mar/25, 'dd/MM/yyyy' → 01/03/2025).",
+            "propertiesDetailed": {
+                "chart_type": {
+                    "type": "string",
+                    "required": true,
+                    "values": ["bar", "line", "area", "pie", "donut", "horizontal_bar", "stacked_bar"],
+                    "default": "bar",
+                    "description": "Tipo visual do gráfico. 'bar'=barras verticais, 'line'=linhas, 'area'=área preenchida, 'pie'=pizza, 'donut'=rosca (pie com innerRadius), 'horizontal_bar'=barras horizontais, 'stacked_bar'=barras empilhadas."
+                },
+                "x_field": {
+                    "type": "string",
+                    "required": true,
+                    "description": "Nome do campo nos dados que será usado como eixo X (categorias). Ex: 'mes', 'nomeVendedor'."
+                },
+                "y_field": {
+                    "type": "string",
+                    "required": false,
+                    "description": "Campo de valor do eixo Y (quando há apenas uma série). Alternativa a y_fields."
+                },
+                "y_fields": {
+                    "type": "string[]",
+                    "required": false,
+                    "description": "Array de campos de valor para o eixo Y. Usar quando há múltiplas séries. Ex: ['faturamento', 'custos']."
+                },
+                "group_by_field": {
+                    "type": "string",
+                    "required": false,
+                    "description": "Campo para agrupar os dados em séries automáticas. Ex: group_by_field='regiao' cria uma série para cada região."
+                },
+                "aggregation": {
+                    "type": "string",
+                    "required": false,
+                    "values": ["sum", "avg", "count", "min", "max", "first", "last"],
+                    "default": "sum",
+                    "description": "Tipo de agregação quando há duplicatas no x_field."
+                },
+                "top_n": {
+                    "type": "number",
+                    "required": false,
+                    "description": "Limitar aos top N registros. Os demais são descartados."
+                },
+                "sort_order": {
+                    "type": "string",
+                    "required": false,
+                    "values": ["asc", "desc"],
+                    "default": "desc",
+                    "description": "Ordenação dos dados: ascendente ou descendente."
+                },
+                "alternate_colors": {
+                    "type": "boolean",
+                    "required": false,
+                    "default": false,
+                    "description": "IMPORTANTE: Quando true, cada barra/fatia recebe uma cor diferente da paleta do tema (azul, verde, laranja, vermelho, roxo...). Quando false (padrão), todas as barras de uma mesma série têm a mesma cor. Use true para rankings, top N, comparações entre categorias."
+                },
+                "orientation": {
+                    "type": "string",
+                    "required": false,
+                    "values": ["vertical", "horizontal"],
+                    "default": "vertical",
+                    "description": "Orientação do gráfico de barras. 'horizontal' inverte os eixos. Alternativa a usar chart_type='horizontal_bar'."
+                },
+                "bar_width": {
+                    "type": "number",
+                    "required": false,
+                    "default": 60,
+                    "description": "Largura máxima das barras em porcentagem (1-100). Ex: 60 = barras ocupam 60% do espaço."
+                },
+                "show_data_labels": {
+                    "type": "boolean",
+                    "required": false,
+                    "default": false,
+                    "description": "Exibir rótulos com valores em cima de cada barra/ponto/fatia."
+                },
+                "show_legend": {
+                    "type": "boolean",
+                    "required": false,
+                    "default": true,
+                    "description": "Exibir legenda do gráfico. Útil desabilitar quando há apenas uma série."
+                },
+                "enable_zoom": {
+                    "type": "boolean",
+                    "required": false,
+                    "default": false,
+                    "llm_rule": "NUNCA gere enable_zoom: true salvo quando o usuário pedir EXPLICITAMENTE zoom ou rolagem no gráfico.",
+                    "description": "Habilitar zoom interativo (dataZoom) no gráfico. Padrão: false. Só usar se o usuário pedir explicitamente."
+                },
+                "rotate_labels": {
+                    "type": "boolean",
+                    "required": false,
+                    "default": false,
+                    "deprecated": "Use x_axis_label_rotate com valor numérico de graus.",
+                    "description": "Rotacionar labels do eixo X em 45 graus. Deprecated — prefira x_axis_label_rotate."
+                },
+                "x_axis_label_rotate": {
+                    "type": "number",
+                    "required": false,
+                    "default": 0,
+                    "description": "Ângulo de rotação dos labels do eixo X em graus (ex: 45, 90, -45). Use quando o usuário pedir labels inclinados ou verticais."
+                },
+                "x_axis_date_format": {
+                    "type": "string",
+                    "required": false,
+                    "values": ["dd/MM/yyyy", "dd/MM/yy", "MM/yyyy", "MM/yy", "MMMM/yy", "MMM/yy", "yyyy-MM-dd"],
+                    "description": "Formato de exibição das datas no eixo X. Tokens: dd=dia, MM=mês numérico, yyyy=ano 4 dígitos, yy=ano 2 dígitos, MMMM=mês por extenso (ex: Março), MMM=mês abreviado (ex: Mar). Exemplos: 'dd/MM/yyyy' → 01/03/2025 | 'MMMM/yy' → Março/25 | 'MMM/yy' → Mar/25 | 'MM/yyyy' → 03/2025."
+                },
+                "smooth": {
+                    "type": "boolean",
+                    "required": false,
+                    "default": false,
+                    "description": "Suavizar linhas (para chart_type='line' ou 'area'). Curvas ao invés de retas."
+                },
+                "show_symbol": {
+                    "type": "boolean",
+                    "required": false,
+                    "default": true,
+                    "description": "Mostrar pontos/símbolos nos vértices das linhas."
+                },
+                "symbol_size": {
+                    "type": "number",
+                    "required": false,
+                    "default": 6,
+                    "description": "Tamanho dos símbolos/pontos nas linhas."
+                },
+                "line_style": {
+                    "type": "string",
+                    "required": false,
+                    "values": ["solid", "dashed", "dotted"],
+                    "default": "solid",
+                    "description": "Estilo da linha (para chart_type='line')."
+                },
+                "area_opacity": {
+                    "type": "number",
+                    "required": false,
+                    "default": 0.5,
+                    "description": "Opacidade do preenchimento da área (0 a 1). Para chart_type='area'."
+                },
+                "gradient": {
+                    "type": "boolean",
+                    "required": false,
+                    "default": true,
+                    "description": "Usar gradiente no preenchimento da área. Para chart_type='area'."
+                },
+                "radius": {
+                    "type": "number",
+                    "required": false,
+                    "default": 75,
+                    "description": "Raio externo da pizza/donut em porcentagem. Para chart_type='pie' ou 'donut'."
+                },
+                "inner_radius": {
+                    "type": "number",
+                    "required": false,
+                    "default": 0,
+                    "description": "Raio interno (furo) da rosca em porcentagem. Usar > 0 para criar donut. Ex: 40."
+                },
+                "rose_type": {
+                    "type": "string|boolean",
+                    "required": false,
+                    "values": ["radius", "area", "none", false],
+                    "default": false,
+                    "description": "Tipo rose (raios diferentes por valor). 'radius'=raio proporcional, 'area'=área proporcional, false=pizza normal."
+                },
+                "start_angle": {
+                    "type": "number",
+                    "required": false,
+                    "default": 90,
+                    "description": "Ângulo inicial da pizza em graus."
+                },
+                "min_angle": {
+                    "type": "number",
+                    "required": false,
+                    "default": 0,
+                    "description": "Ângulo mínimo de cada fatia (evita fatias invisíveis)."
+                },
+                "show_percentage": {
+                    "type": "boolean",
+                    "required": false,
+                    "default": true,
+                    "description": "Exibir porcentagem nos labels da pizza."
+                },
+                "label_position": {
+                    "type": "string",
+                    "required": false,
+                    "values": ["outside", "inside", "center"],
+                    "default": "outside",
+                    "description": "Posição dos labels na pizza."
+                },
+                "max_categories": {
+                    "type": "number",
+                    "required": false,
+                    "default": 10,
+                    "description": "Máximo de categorias na pizza. Excedentes são agrupados."
+                },
+                "sort_by": {
+                    "type": "string",
+                    "required": false,
+                    "values": ["value", "name"],
+                    "default": "value",
+                    "description": "Critério de ordenação para pizza."
+                },
+                "title": {
+                    "type": "string",
+                    "required": false,
+                    "description": "Título exibido no widget."
+                },
+                "description": {
+                    "type": "string",
+                    "required": false,
+                    "description": "Descrição curta abaixo do título."
+                },
+                "empty_state": {
+                    "type": "string",
+                    "required": false,
+                    "default": "Sem dados",
+                    "description": "Texto quando não há dados para exibir."
+                }
+            },
+            "forbiddenProperties": [
+                "color_palette",
+                "colors",
+                "color_list",
+                "custom_colors",
+                "series_colors",
+                "bar_colors"
+            ],
+            "dataFields": ["xField", "yFields", "aggregation"],
+            "notes": [
+                "As cores são gerenciadas automaticamente pelo tema. A paleta padrão é: #3b82f6 (azul), #10b981 (verde), #f59e0b (laranja), #ef4444 (vermelho), #8b5cf6 (roxo), #06b6d4 (ciano), #ec4899 (rosa), #6366f1 (índigo).",
+                "Para barras com cores alternadas (cada barra uma cor), use alternate_colors: true.",
+                "NÃO existe propriedade color_palette, colors, ou similar. Não inventar propriedades de cores.",
+                "No JSON serializado, usar snake_case: chart_type, x_field, y_fields, show_data_labels, alternate_colors, etc.",
+                "O renderer converte snake_case para camelCase internamente."
+            ]
+        },
+        "line": {
+            "name": "Gráfico de Linhas",
+            "category": "basic",
+            "description": "Gráfico de linhas para tendências. Usa o mesmo componente EChartsChart com chart_type='line'.",
+            "icon": "📈",
+            "render": "EChartsChart",
+            "defaultSize": { "width": 720, "height": 480 },
+            "llm_instruction": "Para gráfico de linhas, use widget_type='chart' com chart_type='line' dentro de properties. NÃO use widget_type='line'.",
+            "propertiesDetailed": "Mesmas propriedades de 'chart'. Propriedades específicas de linhas: smooth, show_symbol, symbol_size, line_style.",
+            "dataFields": ["xField", "yFields", "aggregation"]
+        },
+        "area": {
+            "name": "Gráfico de Área",
+            "category": "basic",
+            "description": "Gráfico de área para visualizar volume/magnitude. Usa o mesmo componente EChartsChart com chart_type='area'.",
+            "icon": "📉",
+            "render": "EChartsChart",
+            "defaultSize": { "width": 720, "height": 480 },
+            "llm_instruction": "Para gráfico de área, use widget_type='chart' com chart_type='area' dentro de properties. NÃO use widget_type='area'.",
+            "propertiesDetailed": "Mesmas propriedades de 'chart'. Propriedades específicas de área: area_opacity, smooth, gradient.",
+            "dataFields": ["xField", "yFields", "aggregation"]
+        },
+        "pie": {
+            "name": "Gráfico de Pizza",
+            "category": "basic",
+            "description": "Gráfico de pizza ou rosca para visualizar proporções. Usa o mesmo componente EChartsChart com chart_type='pie'.",
+            "icon": "🥧",
+            "render": "EChartsChart",
+            "defaultSize": { "width": 720, "height": 480 },
+            "llm_instruction": "Para pizza, use widget_type='chart' com chart_type='pie'. Para donut, use chart_type='pie' com inner_radius > 0 (ex: 40). NÃO use widget_type='pie'.",
+            "propertiesDetailed": "Mesmas propriedades de 'chart'. Propriedades específicas de pizza: radius, inner_radius, rose_type, start_angle, min_angle, show_percentage, label_position, max_categories, sort_by, sort_order.",
+            "dataFields": ["categoryField", "valueField", "aggregation"]
+        },
+        "scatter": {
+            "name": "Dispersão",
+            "category": "advanced",
+            "description": "Gráfico de dispersão para correlação entre dois campos numéricos.",
+            "icon": "⚫",
+            "render": "ScatterComponent",
+            "defaultSize": { "width": 720, "height": 480 },
+            "llm_instruction": "Use widget_type='scatter' para mostrar correlação entre dois campos numéricos. Defina x_field e y_field. Opcional: size_field para bolhas, color_field para colorir por categoria.",
+            "propertiesDetailed": {
+                "x_field": { "type": "string", "required": true, "description": "Campo do eixo X (numérico)." },
+                "y_field": { "type": "string", "required": true, "description": "Campo do eixo Y (numérico)." },
+                "size_field": { "type": "string", "required": false, "description": "Campo para variar o tamanho dos pontos (bubble chart)." },
+                "color_field": { "type": "string", "required": false, "description": "Campo para colorir por categoria." },
+                "symbol_size": { "type": "number", "required": false, "default": 10 },
+                "show_regression": { "type": "boolean", "required": false, "default": false, "description": "Mostrar linha de tendência." },
+                "enable_zoom": { "type": "boolean", "required": false, "default": false }
+            },
+            "dataFields": ["xField", "yField"]
+        },
+        "effect-scatter": {
+            "name": "Dispersão com Efeito",
+            "category": "advanced",
+            "description": "Scatter com efeito ripple animado nos pontos. Ideal para destacar localizações geográficas ou pontos de atenção.",
+            "icon": "✨",
+            "render": "EffectScatterComponent",
+            "defaultSize": { "width": 450, "height": 380 },
+            "llm_instruction": "Use widget_type='effect-scatter' para dispersão com efeito de onda animado. Bom para mapas com pontos destacados.",
+            "propertiesDetailed": {
+                "x_field": { "type": "string", "required": true },
+                "y_field": { "type": "string", "required": true },
+                "symbol_size": { "type": "number", "required": false, "default": 10 },
+                "ripple_effect": { "type": "boolean", "required": false, "default": true }
+            }
+        },
+        "gauge": {
+            "name": "Velocímetro",
+            "category": "advanced",
+            "description": "Velocímetro/medidor para exibir um valor único em uma escala. Ex: percentual de meta atingida, temperatura, score.",
+            "icon": "⏱️",
+            "render": "GaugeComponent",
+            "defaultSize": { "width": 350, "height": 350 },
+            "llm_instruction": "Use widget_type='gauge' para exibir um valor único em escala de velocímetro. OBRIGATÓRIO: value_field (campo numérico). Opcionais: min, max, target_value, unit.",
+            "propertiesDetailed": {
+                "value_field": { "type": "string", "required": true, "description": "Campo numérico do valor a exibir." },
+                "min": { "type": "number", "required": false, "default": 0, "description": "Valor mínimo da escala." },
+                "max": { "type": "number", "required": false, "default": 100, "description": "Valor máximo da escala." },
+                "target_value": { "type": "number", "required": false, "description": "Valor alvo/meta (mostrado como ponteiro secundário)." },
+                "unit": { "type": "string", "required": false, "description": "Unidade do valor. Ex: '%', 'pts', 'R$'." },
+                "format": { "type": "string", "required": false, "values": ["number", "currency", "percent"], "default": "number" },
+                "aggregation": { "type": "string", "required": false, "default": "sum", "values": ["sum", "avg", "count", "min", "max", "first", "last"] }
+            },
+            "dataFields": ["valueField", "aggregation"]
+        },
+        "funnel": {
+            "name": "Funil",
+            "category": "advanced",
+            "description": "Funil de conversão para visualizar etapas de um processo com redução progressiva de volume.",
+            "icon": "🔻",
+            "render": "FunnelComponent",
+            "defaultSize": { "width": 400, "height": 350 },
+            "llm_instruction": "Use widget_type='funnel' para pipeline/funil de conversão (ex: leads → qualificados → oportunidades → clientes). OBRIGATÓRIO: category_field (nome da etapa) e value_field (volume).",
+            "propertiesDetailed": {
+                "category_field": { "type": "string", "required": true, "description": "Campo com o nome de cada etapa do funil." },
+                "value_field": { "type": "string", "required": true, "description": "Campo numérico com o volume de cada etapa." },
+                "sort": { "type": "string", "required": false, "values": ["descending", "ascending", "none"], "default": "descending" },
+                "show_percentage": { "type": "boolean", "required": false, "default": true },
+                "show_labels": { "type": "boolean", "required": false, "default": true },
+                "gap": { "type": "number", "required": false, "default": 2 }
+            },
+            "dataFields": ["categoryField", "valueField"]
+        },
+        "waterfall": {
+            "name": "Cascata",
+            "category": "advanced",
+            "description": "Gráfico de cascata (waterfall) para mostrar contribuição de parcelas a um total. Ex: receitas, despesas e lucro.",
+            "icon": "💧",
+            "render": "WaterfallComponent",
+            "defaultSize": { "width": 720, "height": 480 },
+            "llm_instruction": "Use widget_type='waterfall' para mostrar como valores positivos e negativos somados chegam a um total. OBRIGATÓRIO: category_field e value_field. Valores positivos sobem, negativos descem.",
+            "propertiesDetailed": {
+                "category_field": { "type": "string", "required": true, "description": "Campo com o nome de cada item/etapa." },
+                "value_field": { "type": "string", "required": true, "description": "Campo numérico (positivo=incremento, negativo=decremento)." },
+                "show_total": { "type": "boolean", "required": false, "default": true, "description": "Exibir barra de total ao final." },
+                "show_labels": { "type": "boolean", "required": false, "default": true },
+                "positive_color": { "type": "string", "required": false, "default": "#10b981" },
+                "negative_color": { "type": "string", "required": false, "default": "#ef4444" },
+                "total_color": { "type": "string", "required": false, "default": "#3b82f6" }
+            },
+            "dataFields": ["categoryField", "valueField"]
+        },
+        "kpi": {
+            "name": "KPI",
+            "category": "data",
+            "description": "Cartão de indicador chave (KPI) com valor principal, comparação e sparkline opcional.",
+            "icon": "💰",
+            "render": "KpiComponent",
+            "defaultSize": { "width": 350, "height": 180 },
+            "llm_instruction": "Use widget_type='kpi' para exibir um único indicador numérico em destaque (faturamento, total de pedidos, ticket médio, etc.). OBRIGATÓRIO: value_field. Opcional: comparison_type para comparar com meta ou período anterior, sparkline_field para mini-gráfico de tendência.",
+            "propertiesDetailed": {
+                "value_field": { "type": "string", "required": true, "description": "Campo numérico a exibir como KPI principal." },
+                "aggregation": { "type": "string", "required": false, "default": "sum", "values": ["sum", "avg", "count", "min", "max", "first", "last"] },
+                "format": { "type": "string", "required": false, "values": ["number", "currency", "percent", "decimal"], "default": "number", "description": "Formato do valor." },
+                "prefix": { "type": "string", "required": false, "description": "Prefixo do valor. Ex: 'R$'." },
+                "suffix": { "type": "string", "required": false, "description": "Sufixo do valor. Ex: '%', 'un'." },
+                "label": { "type": "string", "required": false, "description": "Rótulo/legenda do indicador." },
+                "comparison_type": { "type": "string", "required": false, "values": ["none", "target", "previous"], "default": "none", "description": "Tipo de comparação: 'target'=vs meta, 'previous'=vs período anterior." },
+                "target_field": { "type": "string", "required": false, "description": "Campo com o valor alvo/meta (para comparison_type='target')." },
+                "previous_field": { "type": "string", "required": false, "description": "Campo com o valor do período anterior (para comparison_type='previous')." },
+                "sparkline_field": { "type": "string", "required": false, "description": "Campo numérico para o mini-gráfico de tendência no card." },
+                "icon": { "type": "string", "required": false, "description": "Nome do ícone Lucide. Ex: 'DollarSign', 'TrendingUp'." },
+                "color": { "type": "string", "required": false, "description": "Cor de destaque (hex)." }
+            },
+            "dataFields": ["valueField", "aggregation"]
+        },
+        "grid": {
+            "name": "Tabela",
+            "category": "data",
+            "description": "Tabela de dados. Suporta dois modos: legado (DataGrid com columns + column_labels) e v2 (DataGridV2 com column_defs tipadas). Para ativar o DataGridV2, use use_grid_v2: true e forneça column_defs.",
+            "icon": "📊",
+            "render": "GridComponent",
+            "defaultSize": { "width": 980, "height": 400 },
+            "properties": [
+                "selectedColumns",
+                "enableSorting",
+                "enableFiltering",
+                "enablePagination",
+                "pageSize",
+                "striped",
+                "rowHeight"
+            ],
+            "serialized_properties": {
+                "title": { "type": "string", "required": true },
+                "page_size": { "type": "number", "required": true, "default": 20 },
+                "columns": { "type": "string[]", "required": false, "description": "Lista de campos a exibir (modo legado). Opcional se column_defs estiver presente." },
+                "column_labels": { "type": "Record<string, string>", "required": false, "description": "Labels das colunas (modo legado)." },
+                "enable_filters": { "type": "boolean", "default": false },
+                "enable_export": { "type": "boolean", "default": false },
+                "enable_pagination": { "type": "boolean", "default": true },
+                "enable_column_settings": { "type": "boolean", "default": false },
+                "enable_fullscreen": { "type": "boolean", "default": false },
+                "enable_aggregation": { "type": "boolean", "default": false },
+                "use_grid_v2": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Se true, usa DataGridV2 (mais leve, tipado, com resize e reorder de colunas). Requer column_defs."
+                },
+                "column_defs": {
+                    "type": "SerializedGridColumnDef[]",
+                    "required": false,
+                    "description": "Definições avançadas por coluna para DataGridV2. Cada item define id, header, width, min_width, sortable, format (type, decimals, currency, locale, notation).",
+                    "example": [
+                        { "id": "nome", "header": "Nome", "width": 200, "sortable": true },
+                        { "id": "valor", "header": "Valor", "width": 150, "format": { "type": "currency", "decimals": 2, "currency": "BRL" } },
+                        { "id": "percentual", "header": "%", "width": 100, "format": { "type": "percentage", "decimals": 1 } },
+                        { "id": "data", "header": "Data", "width": 120, "format": { "type": "date" } }
+                    ]
+                },
+                "default_sort": {
+                    "type": "{ column_id: string, direction: 'asc' | 'desc' }",
+                    "required": false,
+                    "description": "Ordenação inicial. Ex: { column_id: 'valor', direction: 'desc' }"
+                },
+                "empty_message": { "type": "string", "required": false, "default": "Nenhum registro encontrado." },
+                "loading_message": { "type": "string", "required": false, "default": "Carregando..." }
+            },
+            "llm_instruction": "Para grids no dashboard.serialized.json, SEMPRE prefira use_grid_v2: true com column_defs quando souber os campos antecipadamente. O DataGridV2 é mais leve, suporta formatação por coluna (currency, percentage, date, etc.), resize e reorder de colunas nativo. Se não souber os campos, use o modo legado (columns + column_labels) que auto-detecta."
+        },
+        "pivot": {
+            "name": "Pivot",
+            "category": "data",
+            "description": "Tabela pivot (dinâmica) para análise cruzada — linhas × colunas com valores agregados.",
+            "icon": "📋",
+            "render": "PivotComponent",
+            "defaultSize": { "width": 980, "height": 400 },
+            "llm_instruction": "Use widget_type='pivot' para tabela cruzada (ex: vendas por vendedor × mês). OBRIGATÓRIO: row_field (dimensão das linhas), col_field (dimensão das colunas), value_field (métrica). Aggregation padrão: sum.",
+            "propertiesDetailed": {
+                "row_field": { "type": "string", "required": true, "description": "Campo das linhas da tabela pivot. Ex: 'vendedor', 'produto'." },
+                "col_field": { "type": "string", "required": true, "description": "Campo das colunas da tabela pivot. Ex: 'mes', 'ano', 'categoria'." },
+                "value_field": { "type": "string", "required": true, "description": "Campo numérico com o valor a agregar." },
+                "aggregation": { "type": "string", "required": false, "default": "sum", "values": ["sum", "avg", "count", "min", "max"] },
+                "show_totals": { "type": "boolean", "required": false, "default": true, "description": "Mostrar linha/coluna de totais." },
+                "format": { "type": "string", "required": false, "values": ["number", "currency", "percent"], "default": "number" }
+            }
+        },
+        "sparkline": {
+            "name": "Sparkline",
+            "category": "data",
+            "description": "KPI compacto com mini gráfico de tendência embutido. Combina valor principal + variação + sparkline em um só card.",
+            "icon": "⚡",
+            "render": "SparklineComponent",
+            "defaultSize": { "width": 350, "height": 180 },
+            "llm_instruction": "Use widget_type='sparkline' para card KPI com mini gráfico de tendência. Ideal para métricas com histórico temporal (ex: faturamento mês a mês). OBRIGATÓRIO: value_field (métrica principal) e x_field (eixo de tempo para o sparkline).",
+            "propertiesDetailed": {
+                "value_field": { "type": "string", "required": true, "description": "Campo numérico do valor principal do KPI." },
+                "x_field": { "type": "string", "required": true, "description": "Campo de data/período para o eixo do sparkline." },
+                "chart_type": { "type": "string", "required": false, "values": ["line", "area", "bar"], "default": "area" },
+                "label": { "type": "string", "required": false, "description": "Rótulo/título do card." },
+                "format": { "type": "string", "required": false, "values": ["number", "currency", "percent"], "default": "number" },
+                "show_area": { "type": "boolean", "required": false, "default": true },
+                "show_stats": { "type": "boolean", "required": false, "default": true, "description": "Mostrar min/max/avg abaixo do sparkline." },
+                "color": { "type": "string", "required": false, "description": "Cor da linha/área (hex)." }
+            },
+            "dataFields": ["valueField", "xField"]
+        },
+        "card": {
+            "name": "Cartão",
+            "category": "data",
+            "description": "Cartão customizável com ícone",
+            "icon": "🎯",
+            "render": "CardComponent",
+            "defaultSize": { "width": 350, "height": 180 },
+            "properties": [
+                "format",
+                "subtitle",
+                "icon",
+                "color",
+                "sparkline",
+                "solidBackground"
+            ],
+            "dataFields": ["valueField", "aggregation"]
+        },
+        "multi-card": {
+            "name": "Multi-Cards",
+            "category": "data",
+            "description": "Múltiplos cartões KPI em grade, cada um exibindo uma métrica diferente da mesma query. Ideal para painel de indicadores.",
+            "icon": "📋",
+            "render": "MultiCardComponent",
+            "defaultSize": { "width": 700, "height": 400 },
+            "llm_instruction": "Use widget_type='multi-card' para exibir vários KPIs em grade (ex: Faturamento, Pedidos, Ticket Médio, Margem). Defina cards[] com cada indicador. Alternativa: usar múltiplos widget_type='kpi' em seção com várias colunas.",
+            "propertiesDetailed": {
+                "cards": {
+                    "type": "array",
+                    "required": true,
+                    "description": "Lista de cards, cada um com: { label, value_field, format, aggregation, icon, color }",
+                    "itemShape": {
+                        "label": "string — rótulo do card",
+                        "value_field": "string — campo numérico",
+                        "format": "number | currency | percent",
+                        "aggregation": "sum | avg | count | min | max | first | last",
+                        "icon": "string — nome ícone Lucide",
+                        "color": "string — cor hex"
+                    }
+                },
+                "layout": { "type": "string", "required": false, "values": ["grid", "horizontal"], "default": "grid" },
+                "show_trend": { "type": "boolean", "required": false, "default": false }
+            },
+            "dataFields": ["valueFields", "aggregation"]
+        },
+        "text": {
+            "name": "Texto",
+            "category": "data",
+            "description": "Widget de texto/markdown",
+            "icon": "📝",
+            "render": "TextComponent",
+            "defaultSize": { "width": 480, "height": 200 },
+            "properties": [
+                "content",
+                "fontSize",
+                "textAlign",
+                "fontWeight"
+            ],
+            "noData": true
+        },
+        "image": {
+            "name": "Imagem",
+            "category": "data",
+            "description": "Widget de imagem estática",
+            "icon": "🖼️",
+            "render": "ImageComponent",
+            "defaultSize": { "width": 480, "height": 300 },
+            "properties": [
+                "src",
+                "alt",
+                "objectFit"
+            ],
+            "noData": true
+        },
+        "timeline": {
+            "name": "Linha do Tempo",
+            "category": "data",
+            "description": "Linha do tempo vertical para eventos históricos ou atividades. Cada linha da query vira um evento na timeline.",
+            "icon": "📅",
+            "render": "TimelineComponent",
+            "defaultSize": { "width": 980, "height": 400 },
+            "llm_instruction": "Use widget_type='timeline' para mostrar eventos em ordem cronológica (ex: histórico de pedidos, atividades, entregas). OBRIGATÓRIO: date_field (data do evento) e title_field (título/descrição).",
+            "propertiesDetailed": {
+                "date_field": { "type": "string", "required": true, "description": "Campo de data do evento." },
+                "title_field": { "type": "string", "required": true, "description": "Campo com o título/nome do evento." },
+                "description_field": { "type": "string", "required": false, "description": "Campo com descrição detalhada do evento." },
+                "color_field": { "type": "string", "required": false, "description": "Campo para colorir eventos por categoria." },
+                "format": { "type": "string", "required": false, "values": ["dd/MM/yyyy", "dd/MM/yyyy HH:mm", "MM/yyyy"], "default": "dd/MM/yyyy" },
+                "show_quick_filters": { "type": "boolean", "required": false, "default": true }
+            },
+            "dataFields": ["dateField", "titleField"]
+        },
+        "progress-list": {
+            "name": "Lista de Progresso",
+            "category": "data",
+            "description": "Lista com barras de progresso, valores e percentuais. Exibe rankings de itens (top clientes, produtos, fornecedores, etc.) com barra proporcional ao valor.",
+            "icon": "📊",
+            "render": "ProgressListComponent",
+            "defaultSize": { "width": 480, "height": 400 },
+            "llm_instruction": "Use widget_type='progress-list' para rankings com barra de progresso (ex: top clientes, top produtos, top cidades). OBRIGATÓRIO definir labelField (nome da categoria) e valueField (campo numérico). Os dados vêm da query SQL via query_id. NÃO use widget_type='kpi' ou 'panel' para este caso. Exemplo: { \"widget_type\": \"progress-list\", \"properties\": { \"labelField\": \"nomeFornecedor\", \"valueField\": \"valorTotal\", \"maxItems\": 10, \"valueFormat\": \"currency\", \"colorScheme\": \"gradient\" } }. IMPORTANTE: labelField e valueField devem corresponder EXATAMENTE aos aliases camelCase da query SQL.",
+            "properties": [
+                "labelField",
+                "valueField",
+                "aggregation",
+                "maxItems",
+                "showValues",
+                "showPercentage",
+                "valueFormat",
+                "barHeight",
+                "colorScheme",
+                "primaryColor",
+                "sortBy",
+                "sortOrder"
+            ]
+        },
+        "treemap": {
+            "name": "Treemap",
+            "category": "hierarchical",
+            "description": "Mapa de árvore hierárquico — retângulos proporcionais ao valor. Ideal para mostrar participação de itens em um total (ex: produtos por categoria).",
+            "icon": "🗺️",
+            "render": "TreemapComponent",
+            "defaultSize": { "width": 480, "height": 350 },
+            "llm_instruction": "Use widget_type='treemap' para visualizar hierarquia com área proporcional ao valor. OBRIGATÓRIO: name_field (rótulo do item) e value_field (tamanho do bloco). Opcional: group_field para agrupamento de nível superior.",
+            "propertiesDetailed": {
+                "name_field": { "type": "string", "required": true, "description": "Campo com o nome/rótulo de cada item." },
+                "value_field": { "type": "string", "required": true, "description": "Campo numérico (define o tamanho do bloco)." },
+                "group_field": { "type": "string", "required": false, "description": "Campo de agrupamento de nível superior (cria hierarquia de 2 níveis)." },
+                "show_labels": { "type": "boolean", "required": false, "default": true },
+                "color_scheme": { "type": "string", "required": false, "values": ["theme", "random", "gradient"], "default": "theme" },
+                "roam": { "type": "boolean", "required": false, "default": false, "description": "Permitir zoom/pan." }
+            }
+        },
+        "sankey": {
+            "name": "Sankey",
+            "category": "hierarchical",
+            "description": "Diagrama de fluxo Sankey para visualizar transferência de volume entre nós. Ex: origem → canal → conversão.",
+            "icon": "🌊",
+            "render": "SankeyComponent",
+            "defaultSize": { "width": 580, "height": 400 },
+            "llm_instruction": "Use widget_type='sankey' para fluxos entre categorias (ex: origem de tráfego → produto → conversão). Requer dados no formato { source, target, value }. Defina source_field, target_field, value_field.",
+            "propertiesDetailed": {
+                "source_field": { "type": "string", "required": true, "description": "Campo com o nó de origem do fluxo." },
+                "target_field": { "type": "string", "required": true, "description": "Campo com o nó de destino do fluxo." },
+                "value_field": { "type": "string", "required": true, "description": "Campo numérico com o volume do fluxo." },
+                "orient": { "type": "string", "required": false, "values": ["horizontal", "vertical"], "default": "horizontal" },
+                "node_width": { "type": "number", "required": false, "default": 20 },
+                "node_gap": { "type": "number", "required": false, "default": 8 }
+            }
+        },
+        "graph": {
+            "name": "Grafo de Rede",
+            "category": "hierarchical",
+            "description": "Grafo de nós e arestas para representar redes, relacionamentos e dependências.",
+            "icon": "🕸️",
+            "render": "GraphComponent",
+            "defaultSize": { "width": 480, "height": 400 },
+            "llm_instruction": "Use widget_type='graph' para redes de relacionamento (ex: fornecedores ↔ produtos, clientes ↔ vendedores). Requer dados com nós (node_id_field, node_name_field) e arestas (source_field, target_field).",
+            "propertiesDetailed": {
+                "node_id_field": { "type": "string", "required": true, "description": "Campo com ID único do nó." },
+                "node_name_field": { "type": "string", "required": true, "description": "Campo com o nome/rótulo do nó." },
+                "source_field": { "type": "string", "required": true, "description": "Campo com o ID do nó de origem da aresta." },
+                "target_field": { "type": "string", "required": true, "description": "Campo com o ID do nó de destino da aresta." },
+                "layout": { "type": "string", "required": false, "values": ["force", "circular", "none"], "default": "force" },
+                "repulsion": { "type": "number", "required": false, "default": 100 }
+            }
+        },
+        "sunburst": {
+            "name": "Sunburst",
+            "category": "hierarchical",
+            "description": "Gráfico sunburst hierárquico em anéis concêntricos. Ideal para hierarquias com 2-3 níveis (ex: país → estado → cidade).",
+            "icon": "☀️",
+            "render": "SunburstComponent",
+            "defaultSize": { "width": 420, "height": 400 },
+            "llm_instruction": "Use widget_type='sunburst' para hierarquias multi-nível em anéis (ex: categoria → subcategoria → produto). Defina: level1_field (nível externo), level2_field (nível interno), value_field.",
+            "propertiesDetailed": {
+                "level1_field": { "type": "string", "required": true, "description": "Campo de nível 1 (anel externo)." },
+                "level2_field": { "type": "string", "required": false, "description": "Campo de nível 2 (anel do meio)." },
+                "level3_field": { "type": "string", "required": false, "description": "Campo de nível 3 (anel central)." },
+                "value_field": { "type": "string", "required": true, "description": "Campo numérico com o valor de cada folha." },
+                "radius": { "type": "number", "required": false, "default": 75 }
+            }
+        },
+        "tree": {
+            "name": "Árvore",
+            "category": "hierarchical",
+            "description": "Gráfico de árvore hierárquica com nós e conexões. Ideal para organogramas, categorias de produtos, estruturas hierárquicas.",
+            "icon": "🌳",
+            "render": "TreeChartComponent",
+            "defaultSize": { "width": 440, "height": 400 },
+            "llm_instruction": "Use widget_type='tree' para estruturas pai-filho (ex: organograma, categorias). Requer dados com id_field e parent_field para construir a hierarquia.",
+            "propertiesDetailed": {
+                "id_field": { "type": "string", "required": true, "description": "Campo com o ID único do nó." },
+                "parent_field": { "type": "string", "required": true, "description": "Campo com o ID do nó pai (null/vazio = raiz)." },
+                "name_field": { "type": "string", "required": true, "description": "Campo com o nome/rótulo do nó." },
+                "orient": { "type": "string", "required": false, "values": ["LR", "RL", "TB", "BT"], "default": "LR", "description": "Orientação: LR=esquerda-direita, TB=cima-baixo." },
+                "expand_and_collapse": { "type": "boolean", "required": false, "default": true },
+                "symbol_size": { "type": "number", "required": false, "default": 7 }
+            }
+        },
+        "radar": {
+            "name": "Radar",
+            "category": "specialized",
+            "description": "Gráfico radar/aranha para comparar múltiplas dimensões simultaneamente. Ex: comparar desempenho de equipes em várias métricas.",
+            "icon": "🕸️",
+            "render": "RadarComponent",
+            "defaultSize": { "width": 450, "height": 380 },
+            "llm_instruction": "Use widget_type='radar' para comparar entidades em múltiplas dimensões (ex: vendedor A vs B em: volume, ticket médio, conversão, atendimentos). Defina indicators[] com as dimensões e series[] com os valores.",
+            "propertiesDetailed": {
+                "indicators": {
+                    "type": "array",
+                    "required": true,
+                    "description": "Lista de { name, max } com cada dimensão do radar.",
+                    "example": [{"name": "Volume", "max": 100}, {"name": "Margem", "max": 50}]
+                },
+                "name_field": { "type": "string", "required": true, "description": "Campo com o nome de cada série (ex: nome do vendedor)." },
+                "value_fields": { "type": "string[]", "required": true, "description": "Campos dos valores de cada dimensão, na mesma ordem dos indicators." },
+                "shape": { "type": "string", "required": false, "values": ["polygon", "circle"], "default": "polygon" },
+                "split_number": { "type": "number", "required": false, "default": 5 }
+            }
+        },
+        "heatmap": {
+            "name": "Mapa de Calor",
+            "category": "specialized",
+            "description": "Mapa de calor (grade X×Y colorida por intensidade). Ex: volume de vendas por dia da semana × hora, temperatura por mês × ano.",
+            "icon": "🔥",
+            "render": "HeatmapComponent",
+            "defaultSize": { "width": 520, "height": 380 },
+            "llm_instruction": "Use widget_type='heatmap' para matrizes de calor. OBRIGATÓRIO: x_field (eixo horizontal), y_field (eixo vertical), value_field (intensidade da cor).",
+            "propertiesDetailed": {
+                "x_field": { "type": "string", "required": true, "description": "Campo do eixo X (ex: dia da semana, mês)." },
+                "y_field": { "type": "string", "required": true, "description": "Campo do eixo Y (ex: hora, ano)." },
+                "value_field": { "type": "string", "required": true, "description": "Campo numérico que define a intensidade da cor." },
+                "min": { "type": "number", "required": false, "description": "Valor mínimo para a escala de cores." },
+                "max": { "type": "number", "required": false, "description": "Valor máximo para a escala de cores." },
+                "color_range": { "type": "string[]", "required": false, "description": "Array de cores [mín, máx]. Ex: ['#f0f9ff', '#0369a1']." }
+            }
+        },
+        "candlestick": {
+            "name": "Candlestick",
+            "category": "specialized",
+            "description": "Gráfico de velas (OHLC) para análise financeira de ativos — abertura, máxima, mínima, fechamento.",
+            "icon": "📈",
+            "render": "CandlestickComponent",
+            "defaultSize": { "width": 480, "height": 380 },
+            "llm_instruction": "Use widget_type='candlestick' para análise financeira de ativos (ações, câmbio). OBRIGATÓRIO: date_field, open_field, close_field, low_field, high_field.",
+            "propertiesDetailed": {
+                "date_field": { "type": "string", "required": true, "description": "Campo de data/período." },
+                "open_field": { "type": "string", "required": true, "description": "Campo de preço de abertura." },
+                "close_field": { "type": "string", "required": true, "description": "Campo de preço de fechamento." },
+                "low_field": { "type": "string", "required": true, "description": "Campo de mínima." },
+                "high_field": { "type": "string", "required": true, "description": "Campo de máxima." },
+                "up_color": { "type": "string", "required": false, "default": "#10b981" },
+                "down_color": { "type": "string", "required": false, "default": "#ef4444" }
+            }
+        },
+        "boxplot": {
+            "name": "Box Plot",
+            "category": "specialized",
+            "description": "Gráfico de caixa para distribuição estatística — mediana, quartis e outliers. Ex: distribuição de ticket por categoria.",
+            "icon": "📦",
+            "render": "BoxplotComponent",
+            "defaultSize": { "width": 450, "height": 380 },
+            "llm_instruction": "Use widget_type='boxplot' para visualizar distribuição estatística de valores por grupo. OBRIGATÓRIO: group_field (categoria) e value_field (valor numérico a distribuir).",
+            "propertiesDetailed": {
+                "group_field": { "type": "string", "required": true, "description": "Campo de agrupamento (eixo X)." },
+                "value_field": { "type": "string", "required": true, "description": "Campo numérico para calcular a distribuição." },
+                "box_width": { "type": "number", "required": false, "default": 30 }
+            }
+        },
+        "parallel": {
+            "name": "Coordenadas Paralelas",
+            "category": "specialized",
+            "description": "Coordenadas paralelas para análise multivariada — cada linha representa um registro cruzando múltiplos eixos.",
+            "icon": "📊",
+            "render": "ParallelComponent",
+            "defaultSize": { "width": 650, "height": 380 },
+            "llm_instruction": "Use widget_type='parallel' para análise de padrões em dados multivariados. Cada registro é uma linha que atravessa os eixos. Defina axis_fields[] com os campos a incluir.",
+            "propertiesDetailed": {
+                "axis_fields": { "type": "string[]", "required": true, "description": "Lista de campos numéricos a usar como eixos paralelos." },
+                "name_field": { "type": "string", "required": false, "description": "Campo para identificar/colorir cada linha." },
+                "line_opacity": { "type": "number", "required": false, "default": 0.5 }
+            }
+        },
+        "themeriver": {
+            "name": "Theme River",
+            "category": "specialized",
+            "description": "Rio temático — evolução do volume de múltiplos temas/categorias ao longo do tempo. Ex: evolução de vendas por linha de produto mês a mês.",
+            "icon": "🌊",
+            "render": "ThemeRiverComponent",
+            "defaultSize": { "width": 650, "height": 380 },
+            "llm_instruction": "Use widget_type='themeriver' para mostrar como múltiplas categorias evoluem no tempo (similar a stacked area). OBRIGATÓRIO: date_field, theme_field (categoria) e value_field.",
+            "propertiesDetailed": {
+                "date_field": { "type": "string", "required": true, "description": "Campo de data (eixo do tempo)." },
+                "theme_field": { "type": "string", "required": true, "description": "Campo de categoria/tema (cada um vira uma faixa)." },
+                "value_field": { "type": "string", "required": true, "description": "Campo numérico com o volume." }
+            }
+        },
+        "pictorial-bar": {
+            "name": "Barra Pictórica",
+            "category": "specialized",
+            "description": "Barras com ícones/símbolos repetidos proporcionalmente ao valor. Mais visual e ilustrativo que barras convencionais.",
+            "icon": "🎨",
+            "render": "PictorialBarComponent",
+            "defaultSize": { "width": 480, "height": 350 },
+            "llm_instruction": "Use widget_type='pictorial-bar' para barras decorativas com ícones. OBRIGATÓRIO: category_field e value_field. O símbolo padrão é uma pessoa/círculo.",
+            "propertiesDetailed": {
+                "category_field": { "type": "string", "required": true, "description": "Campo de categorias (eixo X)." },
+                "value_field": { "type": "string", "required": true, "description": "Campo numérico (quantidade de símbolos)." },
+                "symbol": { "type": "string", "required": false, "default": "circle", "description": "Símbolo: 'circle', 'rect', 'roundRect', 'triangle', 'diamond' ou SVG path." },
+                "symbol_repeat": { "type": "boolean", "required": false, "default": true },
+                "symbol_size": { "type": "number[]", "required": false, "description": "[largura, altura] do símbolo. Ex: [18, 28]." }
+            }
+        },
+        "map": {
+            "name": "Mapa com Pontos",
+            "category": "geo",
+            "description": "Mapa geográfico com pontos/marcadores em coordenadas lat/lon. Ideal para distribuição geográfica de clientes, lojas, entregas.",
+            "icon": "🗺️",
+            "render": "MapComponent",
+            "defaultSize": { "width": 520, "height": 350 },
+            "llm_instruction": "Use widget_type='map' para plotar pontos em mapa (requer lat/lon). OBRIGATÓRIO: lat_field e lon_field. Opcional: label_field (tooltip) e value_field (tamanho do ponto).",
+            "propertiesDetailed": {
+                "lat_field": { "type": "string", "required": true, "description": "Campo de latitude." },
+                "lon_field": { "type": "string", "required": true, "description": "Campo de longitude." },
+                "label_field": { "type": "string", "required": false, "description": "Campo para o rótulo/tooltip do ponto." },
+                "value_field": { "type": "string", "required": false, "description": "Campo numérico para variar o tamanho do ponto." },
+                "show_connections": { "type": "boolean", "required": false, "default": false, "description": "Desenhar linhas de conexão entre os pontos." }
+            }
+        },
+        "filled-map": {
+            "name": "Mapa Coroplético",
+            "category": "geo",
+            "description": "Mapa com regiões preenchidas por intensidade de cor (coroplético). Ex: vendas por estado, usuários por país.",
+            "icon": "🗺️",
+            "render": "FilledMapComponent",
+            "defaultSize": { "width": 520, "height": 350 },
+            "llm_instruction": "Use widget_type='filled-map' para colorir regiões geográficas por valor. OBRIGATÓRIO: region_field (nome do estado/país) e value_field (intensidade da cor).",
+            "propertiesDetailed": {
+                "region_field": { "type": "string", "required": true, "description": "Campo com o nome da região (estado, país). Deve corresponder ao GeoJSON." },
+                "value_field": { "type": "string", "required": true, "description": "Campo numérico para a intensidade da cor." },
+                "color_range": { "type": "string[]", "required": false, "description": "Cores [mínimo, máximo]. Ex: ['#dbeafe', '#1d4ed8']." },
+                "map_type": { "type": "string", "required": false, "values": ["brazil", "world"], "default": "brazil" }
+            }
+        },
+        "lines": {
+            "name": "Linhas de Fluxo Geo",
+            "category": "geo",
+            "description": "Linhas animadas sobre mapa para mostrar fluxos geográficos (ex: rotas de entrega, origem-destino).",
+            "icon": "➡️",
+            "render": "LinesComponent",
+            "defaultSize": { "width": 520, "height": 350 },
+            "llm_instruction": "Use widget_type='lines' para rotas/fluxos entre dois pontos geográficos. OBRIGATÓRIO: from_lat, from_lon, to_lat, to_lon. Opcional: value_field para variar a espessura.",
+            "propertiesDetailed": {
+                "from_lat_field": { "type": "string", "required": true, "description": "Latitude do ponto de origem." },
+                "from_lon_field": { "type": "string", "required": true, "description": "Longitude do ponto de origem." },
+                "to_lat_field": { "type": "string", "required": true, "description": "Latitude do ponto de destino." },
+                "to_lon_field": { "type": "string", "required": true, "description": "Longitude do ponto de destino." },
+                "value_field": { "type": "string", "required": false, "description": "Campo numérico (espessura da linha)." },
+                "effect": { "type": "boolean", "required": false, "default": true, "description": "Animação de fluxo na linha." }
+            }
+        },
+        "filter": {
+            "name": "Filtro / Slicer",
+            "category": "filter",
+            "description": "Painel de filtro interativo (Slicer) com lista de valores selecionáveis — similar a um slicer do Excel/Power BI. Mais visual que dropdown para poucos valores.",
+            "icon": "🎚️",
+            "render": "FilterComponent",
+            "defaultSize": { "width": 240, "height": 320 },
+            "llm_instruction": "Use widget_type='filter' para slicer visual com botões clicáveis (máx ~10 valores). Para listas longas (>10 valores) prefira widget_type='dropdown'. OBRIGATÓRIO: filter_field e query_id.",
+            "propertiesDetailed": {
+                "filter_field": { "type": "string", "required": true, "description": "Campo cujos valores únicos serão listados como opções." },
+                "filter_type": { "type": "string", "required": false, "values": ["dropdown", "buttons", "checkbox"], "default": "dropdown" },
+                "multi_select": { "type": "boolean", "required": false, "default": false },
+                "show_search": { "type": "boolean", "required": false, "default": false }
+            }
+        },
+        "dropdown": {
+            "name": "Dropdown / Combobox",
+            "category": "filter",
+            "description": "Filtro interativo tipo combobox — exibe uma lista de valores únicos extraídos de uma query para o usuário selecionar. Filtra os demais widgets que compartilham a mesma query_id. Suporta seleção simples ou múltipla. O estado do filtro é preservado ao recarregar a página.",
+            "icon": "🔽",
+            "render": "DropdownComponent",
+            "defaultSize": { "width": 250, "height": 60 },
+            "llm_instruction": "Use widget_type='dropdown' para criar filtros interativos de seleção. O widget carrega os valores únicos do campo 'filter_field' via query_id e filtra os outros widgets. OBRIGATÓRIO: definir filter_field (nome do campo) e query_id (mesma query dos widgets que serão filtrados). O label é o rótulo exibido acima do dropdown. Use allow_multiple=true para seleção múltipla. Exemplo: um dropdown de 'categoria' filtrando um chart e um grid que usam a mesma query de produtos.",
+            "propertiesDetailed": {
+                "filter_field": {
+                    "type": "string",
+                    "required": true,
+                    "description": "Nome do campo cujos valores únicos serão listados no dropdown. Ex: 'categoria', 'vendedor', 'regiao'."
+                },
+                "label": {
+                    "type": "string",
+                    "required": false,
+                    "description": "Rótulo exibido acima do dropdown. Ex: 'Filtrar por Categoria'."
+                },
+                "allow_multiple": {
+                    "type": "boolean",
+                    "required": false,
+                    "default": false,
+                    "description": "Permitir seleção de múltiplos valores. false=seleção única, true=multi-seleção com badges."
+                },
+                "placeholder": {
+                    "type": "string",
+                    "required": false,
+                    "default": "Selecione...",
+                    "description": "Texto exibido quando nenhum valor está selecionado."
+                }
+            },
+            "notes": [
+                "O filtro é aplicado localmente nos dados já carregados — não refaz a query SQL.",
+                "Para filtrar múltiplos widgets, todos devem usar a mesma query_id que o dropdown.",
+                "O valor selecionado é preservado no sessionStorage (persiste no refresh da página).",
+                "Coloque o dropdown na mesma section ou em section separada no topo, com col_span adequado."
+            ]
+        },
+        "group": {
+            "name": "Grupo",
+            "category": "data",
+            "description": "Container que agrupa widgets filhos",
+            "icon": "📦",
+            "render": "GroupComponent",
+            "defaultSize": { "width": 980, "height": 600 },
+            "properties": [
+                "backgroundColor",
+                "padding",
+                "borderRadius"
+            ],
+            "noData": true,
+            "llm_instruction": "NUNCA usar group para agrupar charts, grids ou KPIs no dashboard.serialized.json. É estritamente proibido criar um group com título ('Evolução Temporal', 'Análise Mensal', 'Gráficos', etc.) e colocar widgets dentro. Cada widget deve ser declarado diretamente em widgets[] com sua própria section_id. O title do chart vai em properties.title do próprio widget. Group só existe para casos explicitamente solicitados pelo usuário com filhos declarados."
+        },
+        "date": {
+            "name": "Período",
+            "category": "data",
+            "description": "Seletor de período de datas (Dia, Semana, Mês, Ano)",
+            "icon": "📅",
+            "render": "WidgetDate",
+            "defaultSize": { "width": 720, "height": 60 },
+            "properties": [
+                "field",
+                "defaultPeriod"
+            ],
+            "noData": true
+        },
+        "companies": {
+            "name": "Empresas",
+            "category": "data",
+            "description": "Seletor de empresas (multi-empresa)",
+            "icon": "🏢",
+            "render": "WidgetEmpresas",
+            "defaultSize": { "width": 250, "height": 60 },
+            "properties": [
+                "field",
+                "placeholder",
+                "showIcon",
+                "autoSelectFirst"
+            ],
+            "noData": true
+        },
+        "dataGrid": {
+            "name": "DataGrid",
+            "category": "data",
+            "description": "Tabela de dados completa (standalone, fora do Designer)",
+            "icon": "📊",
+            "render": "DataGrid",
+            "properties": [
+                "data",
+                "loading",
+                "error",
+                "title",
+                "subtitle",
+                "onRefresh",
+                "enableFilters",
+                "enableSearch",
+                "searchPlaceholder",
+                "enableExport",
+                "enablePagination",
+                "enableSort",
+                "enableColumnResize",
+                "enableColumnReorder",
+                "enableAggregation",
+                "enableFullscreen",
+                "enableColumnSettings",
+                "theme",
+                "enableHeader",
+                "fullWidthColumns",
+                "pageSize",
+                "totalRows",
+                "currentPage",
+                "onPageChange",
+                "onPageSizeChange",
+                "customColumns",
+                "columnLabels",
+                "columnAliases",
+                "defaultVisibleColumns",
+                "defaultSortColumn",
+                "defaultSortDirection",
+                "canNextPage",
+                "canPreviousPage",
+                "enableAdd",
+                "onAdd",
+                "addButtonText",
+                "onRowClick",
+                "enableEditing",
+                "rowIdField",
+                "onEditsChange",
+                "columnIcons",
+                "columnAggregationDefaults",
+                "defaultColumnWidths"
+            ]
+        },
+        "dataGridV2": {
+            "name": "DataGridV2",
+            "category": "data",
+            "description": "Tabela de dados v2 com tipagem genérica (standalone)",
+            "icon": "📊",
+            "render": "DataGridV2",
+            "properties": [
+                "data",
+                "columns",
+                "rowKey",
+                "loading",
+                "loadingMessage",
+                "emptyMessage",
+                "onRowClick",
+                "rowClassName",
+                "footer",
+                "pagination",
+                "sortDescriptor",
+                "onSortChange",
+                "initialSort"
+            ]
+        },
+        "widgetEmpresas": {
+            "name": "WidgetEmpresas",
+            "category": "data",
+            "description": "Seletor de empresa standalone",
+            "render": "WidgetEmpresas",
+            "llm_instruction": "No dashboard.serialized.json, use widget_type='companies' para declarar este controle no layout. Nao depender de barra fixa no renderer.",
+            "properties": [
+                "value",
+                "onChange",
+                "placeholder",
+                "showIcon",
+                "className",
+                "disabled",
+                "autoSelectFirst"
+            ],
+            "noData": true
+        },
+        "widgetDate": {
+            "name": "WidgetDate",
+            "category": "data",
+            "description": "Seletor de período standalone",
+            "render": "WidgetDate",
+            "llm_instruction": "No dashboard.serialized.json, use widget_type='date' para declarar este controle no layout. Nao depender de barra fixa no renderer.",
+            "properties": [
+                "value",
+                "onChange",
+                "className"
+            ],
+            "noData": true
+        },
+        "widgetTipos": {
+            "name": "WidgetTipos",
+            "category": "data",
+            "description": "Seletor de tipos genérico standalone",
+            "render": "WidgetTipos",
+            "properties": [
+                "tgId",
+                "value",
+                "onChange",
+                "placeholder",
+                "showIcon",
+                "className",
+                "disabled",
+                "autoSelectFirst",
+                "reloadKey"
+            ],
+            "noData": true
+        },
+        "__SERIALIZED_DECORATIVE_WIDGETS__": {
+            "llm_instruction": "Os widgets abaixo são elementos DECORATIVOS disponíveis apenas no dashboard.serialized.json. Eles NÃO precisam de query_id (devem usar query_id: null). Permitem criar dashboards mais livres com títulos, textos explicativos, imagens, separadores e espaçamentos."
+        },
+        "heading": {
+            "name": "Título / Heading",
+            "category": "decorative",
+            "description": "Elemento de título (H1, H2, H3, H4) para organizar visualmente o dashboard. Suporta subtítulo, cor customizada e alinhamento.",
+            "icon": "📝",
+            "render": "TextComponent",
+            "defaultSize": { "width": 980, "height": 80 },
+            "noData": true,
+            "serialized_only": true,
+            "propertiesDetailed": {
+                "level": {
+                    "type": "string",
+                    "required": true,
+                    "values": ["h1", "h2", "h3", "h4"],
+                    "default": "h1",
+                    "description": "Nível do heading. h1=título principal, h2=subtítulo de seção, h3=grupo, h4=rótulo menor."
+                },
+                "content": {
+                    "type": "string",
+                    "required": true,
+                    "description": "Texto do heading. Ex: 'Visão Geral de Vendas'"
+                },
+                "align": {
+                    "type": "string",
+                    "required": false,
+                    "values": ["left", "center", "right"],
+                    "default": "left",
+                    "description": "Alinhamento horizontal do texto."
+                },
+                "color": {
+                    "type": "string",
+                    "required": false,
+                    "description": "Cor do texto (hex, rgb, nome CSS). Ex: '#1e293b'"
+                },
+                "subtitle": {
+                    "type": "string",
+                    "required": false,
+                    "description": "Texto secundário menor abaixo do heading."
+                },
+                "subtitle_color": {
+                    "type": "string",
+                    "required": false,
+                    "description": "Cor do subtítulo. Ex: '#64748b'"
+                },
+                "icon": {
+                    "type": "string",
+                    "required": false,
+                    "description": "Nome de ícone Lucide para exibir ao lado do heading."
+                }
+            }
+        },
+        "sdk-text": {
+            "name": "Bloco de Texto",
+            "category": "decorative",
+            "description": "Bloco de texto livre para descrições, notas, instruções ou contexto no dashboard. Suporta markdown básico (**bold**, *italic*, [links]). Pode ter fundo colorido, borda e padding.",
+            "icon": "📄",
+            "render": "TextComponent",
+            "defaultSize": { "width": 980, "height": 120 },
+            "noData": true,
+            "serialized_only": true,
+            "llm_instruction": "No dashboard.serialized.json, use widget_type='text'. NÃO confundir com o widget 'text' do Designer (que é TextComponent interno). Este é o tipo serializado para blocos de texto decorativos.",
+            "propertiesDetailed": {
+                "content": {
+                    "type": "string",
+                    "required": true,
+                    "description": "Conteúdo do texto. Suporta markdown básico: **negrito**, *itálico*, [link](url)."
+                },
+                "align": {
+                    "type": "string",
+                    "required": false,
+                    "values": ["left", "center", "right", "justify"],
+                    "default": "left"
+                },
+                "font_size": {
+                    "type": "string",
+                    "required": false,
+                    "values": ["xs", "sm", "base", "lg", "xl"],
+                    "default": "base",
+                    "description": "Tamanho da fonte: xs=11px, sm=13px, base=15px, lg=18px, xl=22px."
+                },
+                "color": { "type": "string", "required": false },
+                "background_color": { "type": "string", "required": false },
+                "padding": { "type": "number", "required": false, "description": "Padding interno em px." },
+                "border_radius": { "type": "number", "required": false },
+                "border_color": { "type": "string", "required": false, "description": "Se definido, aplica borda de 1px solid." }
+            }
+        },
+        "sdk-image": {
+            "name": "Imagem Decorativa",
+            "category": "decorative",
+            "description": "Imagem decorativa para logos, banners, ilustrações. Suporta link clicável e legenda.",
+            "icon": "🖼️",
+            "render": "ImageComponent",
+            "defaultSize": { "width": 480, "height": 300 },
+            "noData": true,
+            "serialized_only": true,
+            "llm_instruction": "No dashboard.serialized.json, use widget_type='image'. Sempre forneça src e alt.",
+            "propertiesDetailed": {
+                "src": { "type": "string", "required": true, "description": "URL da imagem." },
+                "alt": { "type": "string", "required": true, "description": "Texto alternativo para acessibilidade." },
+                "object_fit": {
+                    "type": "string",
+                    "required": false,
+                    "values": ["cover", "contain", "fill", "none"],
+                    "default": "cover"
+                },
+                "height": { "type": "number", "required": false, "description": "Altura fixa em px." },
+                "border_radius": { "type": "number", "required": false },
+                "href": { "type": "string", "required": false, "description": "Link ao clicar na imagem." },
+                "caption": { "type": "string", "required": false, "description": "Legenda abaixo da imagem." }
+            }
+        },
+        "divider": {
+            "name": "Separador / Divider",
+            "category": "decorative",
+            "description": "Linha separadora horizontal para dividir visualmente seções do dashboard. Pode ter label opcional no centro.",
+            "icon": "➖",
+            "render": "TextComponent",
+            "defaultSize": { "width": 980, "height": 40 },
+            "noData": true,
+            "serialized_only": true,
+            "propertiesDetailed": {
+                "style": { "type": "string", "values": ["solid", "dashed", "dotted"], "default": "solid" },
+                "color": { "type": "string", "required": false, "description": "Cor da linha." },
+                "thickness": { "type": "number", "required": false, "default": 1, "description": "Espessura em px." },
+                "margin": { "type": "number", "required": false, "default": 16, "description": "Margem vertical em px." },
+                "label": { "type": "string", "required": false, "description": "Texto opcional no centro do divider." }
+            }
+        },
+        "spacer": {
+            "name": "Espaçador",
+            "category": "decorative",
+            "description": "Espaçamento vertical vazio para separar elementos no dashboard.",
+            "icon": "↕️",
+            "render": "none",
+            "defaultSize": { "width": 980, "height": 32 },
+            "noData": true,
+            "serialized_only": true,
+            "propertiesDetailed": {
+                "height": { "type": "number", "required": true, "description": "Altura do espaçamento em px." }
+            }
+        },
+        "widgetCaixas": {
+            "name": "WidgetCaixas",
+            "category": "data",
+            "description": "Seletor de caixas financeiros standalone",
+            "render": "WidgetCaixas",
+            "properties": [
+                "emCodigo",
+                "value",
+                "onChange",
+                "placeholder",
+                "showIcon",
+                "className",
+                "disabled",
+                "autoSelectFirst",
+                "onSelect"
+            ],
+            "noData": true
+        }
+    }
+}