@wibi-global/sdk 0.1.2 → 0.1.3

package/dist/instructions/AGENTS.md

@@ -65,6 +65,53 @@ Consulte APENAS estes arquivos locais antes de gerar widgets, queries ou layout:
 12. Use o mesmo fluxo de validacao e serializacao tanto para geracao inicial quanto para refinamento incremental.
 13. Nao inclua na resposta final secoes de encerramento como `Proximos Passos`, `Ajustes Recomendados` ou listas operacionais de CLI quando isso ja estiver coberto pelo frontend `DashboardStudio`.
 
+## Filtros Internos no progress-list
+
+O widget `progress-list` suporta ate 2 filtros dropdown internos (`filter1`, `filter2`) que permitem segmentacao interativa dos dados sem nova query ao banco (filtro client-side).
+
+### Quando usar
+
+- Quando o usuario precisa filtrar o ranking por uma dimensao (ex: filial, vendedor, periodo, categoria) sem trocar o widget.
+- Cada filtro tem sua propria query SQL para popular as opcoes do select.
+
+### Regras obrigatorias
+
+1. **`filterField`** deve ser alias camelCase EXATAMENTE igual ao campo nos dados principais (rawData da query `query_id` do widget).
+2. **`valueField`** e **`labelField`** devem ser aliases camelCase dos campos retornados pela query do filtro.
+3. As SQLs de `filter1.sql` e `filter2.sql` suportam as mesmas variaveis da query principal: `${startDate}`, `${endDate}`, `${empresaId}`, `${companyFilter:alias}`.
+4. `showInternalFilters` pode ser omitido (padrao `true` quando filter1/filter2 definidos) ou `false` para ocultar os selects.
+5. O filtro NAO reexecuta a query principal — ele filtra localmente os dados ja carregados.
+
+### Exemplo completo
+
+```json
+{
+  "widget_type": "progress-list",
+  "properties": {
+    "labelField": "nomeCliente",
+    "valueField": "valorVendas",
+    "maxItems": 15,
+    "valueFormat": "currency",
+    "colorScheme": "gradient",
+    "showInternalFilters": true,
+    "filter1": {
+      "label": "Filial",
+      "sql": "SELECT filialId AS value, nomeFilial AS label FROM vw_filiais WHERE empresaId = ${empresaId} ORDER BY nomeFilial",
+      "valueField": "value",
+      "labelField": "label",
+      "filterField": "filialId"
+    },
+    "filter2": {
+      "label": "Vendedor",
+      "sql": "SELECT vendedorId AS value, nomeVendedor AS label FROM vw_vendedores WHERE empresaId = ${empresaId} ORDER BY nomeVendedor",
+      "valueField": "value",
+      "labelField": "label",
+      "filterField": "vendedorId"
+    }
+  }
+}
+```
+
 ## Checklist de requisitos
 
 Antes de editar `dashboard.serialized.json`, confirme:

package/dist/instructions/CLAUDE.md

@@ -47,6 +47,15 @@ Veja regras detalhadas em `AGENTS.md`.
 - Em refinamentos, evite recriar o dashboard inteiro; preserve a base existente e aplique diffs pequenos e localizados.
 - A resposta final nao deve incluir blocos como `Proximos Passos` ou `Ajustes Recomendados`.
 
+## Filtros Internos no progress-list
+
+O widget `progress-list` suporta `filter1` e `filter2`: selects discretos dentro do widget que filtram os dados localmente.
+
+- Consulte `AGENTS.md` para as regras completas e exemplo de uso.
+- `filterField` deve ser alias camelCase existente nos dados da query principal do widget.
+- `filter1.sql` / `filter2.sql` suportam `${startDate}`, `${endDate}`, `${empresaId}`, `${companyFilter:alias}`.
+- O filtro e client-side — nao dispara nova query ao banco.
+
 ## Preferencias de autoria
 
 - Prefira editar `dashboard.serialized.json` preservando a estrutura canonica do schema oficial.

package/dist/sdk/src/dashboard-spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dashboard-spec.d.ts","sourceRoot":"","sources":["../../../src/dashboard-spec.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAGV,mBAAmB,EAepB,MAAM,uDAAuD,CAAA;AAE9D,MAAM,MAAM,aAAa,GAAG,mBAAmB,CAAA;AAE/C,MAAM,MAAM,4BAA4B,GAAG;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,6BAA6B,GACrC;IACE,EAAE,EAAE,IAAI,CAAA;IACR,MAAM,EAAE,EAAE,CAAA;CACX,GACD;IACE,EAAE,EAAE,KAAK,CAAA;IACT,MAAM,EAAE,4BAA4B,EAAE,CAAA;CACvC,CAAA;AAEL,eAAO,MAAM,2BAA2B,EAAG,OAAgB,CAAA;AAC3D,eAAO,MAAM,+BAA+B,EAAG,eAAwB,CAAA;AACvE,eAAO,MAAM,uCAAuC,+BAAgC,CAAA;AACpF,eAAO,MAAM,sCAAsC,EAAG,IAAa,CAAA;AACnE,eAAO,MAAM,sCAAsC,sNAYzC,CAAA;AAqkCV,eAAO,MAAM,qBAAqB,GAAI,MAAM,aAAa,KAAG,6BAmD3D,CAAA;AAED,eAAO,MAAM,wBAAwB,GAAI,MAAM,aAAa,KAAG,aAS9D,CAAA;AAED,eAAO,MAAM,mBAAmB,GAAI,MAAM,aAAa,KAAG,aAEzD,CAAA"}
+{"version":3,"file":"dashboard-spec.d.ts","sourceRoot":"","sources":["../../../src/dashboard-spec.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAGV,mBAAmB,EAiBpB,MAAM,uDAAuD,CAAA;AAE9D,MAAM,MAAM,aAAa,GAAG,mBAAmB,CAAA;AAE/C,MAAM,MAAM,4BAA4B,GAAG;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,6BAA6B,GACrC;IACE,EAAE,EAAE,IAAI,CAAA;IACR,MAAM,EAAE,EAAE,CAAA;CACX,GACD;IACE,EAAE,EAAE,KAAK,CAAA;IACT,MAAM,EAAE,4BAA4B,EAAE,CAAA;CACvC,CAAA;AAEL,eAAO,MAAM,2BAA2B,EAAG,OAAgB,CAAA;AAC3D,eAAO,MAAM,+BAA+B,EAAG,eAAwB,CAAA;AACvE,eAAO,MAAM,uCAAuC,+BAAgC,CAAA;AACpF,eAAO,MAAM,sCAAsC,EAAG,IAAa,CAAA;AACnE,eAAO,MAAM,sCAAsC,sNAYzC,CAAA;AAwwCV,eAAO,MAAM,qBAAqB,GAAI,MAAM,aAAa,KAAG,6BAmD3D,CAAA;AAED,eAAO,MAAM,wBAAwB,GAAI,MAAM,aAAa,KAAG,aAS9D,CAAA;AAED,eAAO,MAAM,mBAAmB,GAAI,MAAM,aAAa,KAAG,aAEzD,CAAA"}

package/dist/sdk/src/dashboard-spec.js

@@ -21,20 +21,40 @@ export const WIBI_DASHBOARD_REQUIRED_INITIAL_FIELDS = [
 ];
 const STABLE_ID_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 const FILTER_ID_PATTERN = /^filter-[a-z0-9]+(?:-[a-z0-9]+)*$/;
-const SECTION_ID_PATTERN = /^section-[a-z0-9]+(?:-[a-z0-9]+)*$/;
-const QUERY_ID_PATTERN = /^query-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SECTION_ID_PATTERN = /^(?:section|sec)-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const QUERY_ID_PATTERN = /^(?:query|q)-[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const ISO_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
-const WIDGET_TYPES = new Set(['kpi', 'chart', 'grid', 'progress-list', 'panel', 'date', 'companies', 'heading', 'text', 'image', 'divider', 'spacer']);
+const WIDGET_TYPES = new Set([
+    'kpi',
+    'chart',
+    'grid',
+    'pivot',
+    'pivotgrid',
+    'progress-list',
+    'panel',
+    'date',
+    'companies',
+    'heading',
+    'text',
+    'image',
+    'divider',
+    'spacer',
+]);
 /** Widget types that are decorative — no data query required */
 const DECORATIVE_WIDGET_TYPES = new Set(['date', 'companies', 'heading', 'text', 'image', 'divider', 'spacer']);
 const OFFICIAL_DASHBOARD_ITEM_TYPES = new Set((widgetSchemaJson.dashboardItemType?.fields?.type?.values ?? []).filter(Boolean));
 const OFFICIAL_WIDGET_CATALOG = (widgetSchemaJson.widgets ?? {});
-const OFFICIAL_CHART_VARIANTS = new Set(Object.entries(OFFICIAL_WIDGET_CATALOG)
-    .filter(([, definition]) => definition.render === 'EChartsChart')
-    .map(([type]) => type));
+const OFFICIAL_CHART_VARIANTS = new Set([
+    ...Object.entries(OFFICIAL_WIDGET_CATALOG)
+        .filter(([, definition]) => definition.render === 'EChartsChart')
+        .map(([type]) => type),
+    ...((widgetSchemaJson.widgets ?? {}).chart?.propertiesDetailed?.chart_type?.values ?? []),
+].filter(Boolean));
 const SERIALIZED_WIDGET_TO_OFFICIAL_TYPES = {
     chart: ['chart'],
     grid: ['grid'],
+    pivot: ['pivot'],
+    pivotgrid: ['pivotgrid', 'pivot'],
     kpi: ['kpi'],
     'progress-list': ['progress-list'],
     panel: ['card'],
@@ -78,6 +98,8 @@ const CHART_ALLOWED_PROPERTY_KEYS = new Set([
     'orientation',
     'bar_width',
     'rotate_labels',
+    'x_axis_label_rotate',
+    'x_axis_date_format',
     'enable_zoom',
     'smooth',
     'show_symbol',
@@ -111,6 +133,33 @@ const GRID_ALLOWED_PROPERTY_KEYS = new Set([
     'empty_message',
     'loading_message',
 ]);
+const PIVOT_ALLOWED_PROPERTY_KEYS = new Set([
+    'row_field',
+    'rowField',
+    'col_field',
+    'column_field',
+    'colField',
+    'columnField',
+    'value_field',
+    'valueField',
+    'aggregation',
+    'show_totals',
+    'showTotals',
+    'format',
+    'value_format',
+    'valueFormat',
+    'decimals',
+    'currency',
+    'locale',
+    'searchable',
+    'search_placeholder',
+    'searchPlaceholder',
+    'loading_message',
+    'loadingMessage',
+    'empty_message',
+    'emptyMessage',
+]);
+const PIVOTGRID_ALLOWED_PROPERTY_KEYS = new Set([...PIVOT_ALLOWED_PROPERTY_KEYS]);
 const PANEL_ALLOWED_PROPERTY_KEYS = new Set([
     'panel_type',
     'title',
@@ -123,17 +172,32 @@ const PANEL_ALLOWED_PROPERTY_KEYS = new Set([
 ]);
 const PROGRESS_LIST_ALLOWED_PROPERTY_KEYS = new Set([
     'labelField',
+    'label_field',
     'valueField',
+    'value_field',
     'aggregation',
     'maxItems',
+    'max_items',
     'showValues',
+    'show_values',
     'showPercentage',
+    'show_percentage',
     'valueFormat',
+    'value_format',
     'barHeight',
+    'bar_height',
     'colorScheme',
+    'color_scheme',
     'primaryColor',
+    'primary_color',
     'sortBy',
+    'sort_by',
     'sortOrder',
+    'sort_order',
+    'title',
+    'showInternalFilters',
+    'filter1',
+    'filter2',
 ]);
 const DATE_WIDGET_ALLOWED_PROPERTY_KEYS = new Set([
     'label',
@@ -195,6 +259,8 @@ const ACCEPTED_QUERY_PLACEHOLDER_PATTERNS = [
     /^\$\{companyFilter:[a-zA-Z_][a-zA-Z0-9_]*\}$/,
     /^\{\{start_date\}\}$/,
     /^\{\{end_date\}\}$/,
+    /^\{\{startDate\}\}$/,
+    /^\{\{endDate\}\}$/,
     /^\{\{year\}\}$/,
     /^\{\{date_limit_2y\}\}$/,
 ];
@@ -202,12 +268,30 @@ const ALLOWED_MANUAL_QUERY_SOURCES = new Set(['manual-bootstrap']);
 const pushIssue = (issues, path, message) => {
     issues.push({ path, message });
 };
-const isNonEmptyString = (value) => value.trim().length > 0;
+const isNonEmptyString = (value) => typeof value === 'string' && value.trim().length > 0;
 const validateNonEmptyString = (issues, path, value, label) => {
     if (!isNonEmptyString(value)) {
         pushIssue(issues, path, `${label} must be a non-empty string.`);
     }
 };
+const getStringAlias = (record, ...keys) => {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === 'string' && value.trim().length > 0) {
+            return value;
+        }
+    }
+    return undefined;
+};
+const getNumberAlias = (record, ...keys) => {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === 'number' && Number.isFinite(value)) {
+            return value;
+        }
+    }
+    return undefined;
+};
 const validateUniqueStrings = (issues, values, path, label) => {
     const seen = new Set();
     values.forEach((value, index) => {
@@ -335,6 +419,62 @@ const validateGridProperties = (properties, issues, path) => {
         pushIssue(issues, path, 'Official grid definition is missing from widgets.wbx.');
     }
 };
+const validatePivotBaseProperties = (properties, issues, path, widgetType) => {
+    validateAllowedPropertyKeys(issues, path, properties, widgetType === 'pivot' ? PIVOT_ALLOWED_PROPERTY_KEYS : PIVOTGRID_ALLOWED_PROPERTY_KEYS, widgetType);
+    const propertyRecord = properties;
+    const rowField = getStringAlias(propertyRecord, 'row_field', 'rowField');
+    const columnField = getStringAlias(propertyRecord, 'col_field', 'column_field', 'colField', 'columnField');
+    const valueField = getStringAlias(propertyRecord, 'value_field', 'valueField');
+    const aggregation = getStringAlias(propertyRecord, 'aggregation');
+    const showTotals = propertyRecord.show_totals ?? propertyRecord.showTotals;
+    const format = getStringAlias(propertyRecord, 'format');
+    const valueFormat = getStringAlias(propertyRecord, 'value_format', 'valueFormat');
+    const decimals = getNumberAlias(propertyRecord, 'decimals');
+    const currency = getStringAlias(propertyRecord, 'currency');
+    const locale = getStringAlias(propertyRecord, 'locale');
+    validateNonEmptyString(issues, `${path}.row_field`, rowField, `${widgetType} row_field`);
+    validateNonEmptyString(issues, `${path}.col_field`, columnField, `${widgetType} col_field`);
+    validateNonEmptyString(issues, `${path}.value_field`, valueField, `${widgetType} value_field`);
+    if (aggregation !== undefined) {
+        const validAggregations = new Set(['sum', 'avg', 'count', 'min', 'max']);
+        if (!validAggregations.has(aggregation)) {
+            pushIssue(issues, `${path}.aggregation`, `${widgetType} aggregation must be one of sum, avg, count, min or max.`);
+        }
+    }
+    if (showTotals !== undefined && typeof showTotals !== 'boolean') {
+        pushIssue(issues, `${path}.show_totals`, `${widgetType} show_totals must be a boolean when provided.`);
+    }
+    if (format !== undefined || valueFormat !== undefined) {
+        const effectiveFormat = format ?? valueFormat;
+        const validFormats = new Set(['number', 'currency', 'percent']);
+        if (typeof effectiveFormat !== 'string' || !validFormats.has(effectiveFormat)) {
+            pushIssue(issues, `${path}.format`, `${widgetType} format must be one of number, currency or percent.`);
+        }
+    }
+    if (decimals !== undefined && (!Number.isInteger(decimals) || decimals < 0)) {
+        pushIssue(issues, `${path}.decimals`, `${widgetType} decimals must be a non-negative integer when provided.`);
+    }
+    if (currency !== undefined) {
+        validateNonEmptyString(issues, `${path}.currency`, currency, `${widgetType} currency`);
+    }
+    if (locale !== undefined) {
+        validateNonEmptyString(issues, `${path}.locale`, locale, `${widgetType} locale`);
+    }
+};
+const validatePivotProperties = (properties, issues, path) => {
+    validatePivotBaseProperties(properties, issues, path, 'pivot');
+    const officialPivot = OFFICIAL_WIDGET_CATALOG.pivot;
+    if (!officialPivot) {
+        pushIssue(issues, path, 'Official pivot definition is missing from widgets.wbx.');
+    }
+};
+const validatePivotGridProperties = (properties, issues, path) => {
+    validatePivotBaseProperties(properties, issues, path, 'pivotgrid');
+    const officialPivotGrid = OFFICIAL_WIDGET_CATALOG.pivotgrid;
+    if (!officialPivotGrid) {
+        pushIssue(issues, path, 'Official pivotgrid definition is missing from widgets.wbx.');
+    }
+};
 const validatePanelProperties = (properties, issues, path) => {
     validateAllowedPropertyKeys(issues, path, properties, PANEL_ALLOWED_PROPERTY_KEYS, 'panel');
     validateNonEmptyString(issues, `${path}.title`, properties.title, 'Panel title');
@@ -360,32 +500,40 @@ const validatePanelProperties = (properties, issues, path) => {
 };
 const validateProgressListProperties = (properties, issues, path) => {
     validateAllowedPropertyKeys(issues, path, properties, PROGRESS_LIST_ALLOWED_PROPERTY_KEYS, 'progress-list');
-    validateNonEmptyString(issues, `${path}.labelField`, properties.labelField, 'ProgressList labelField');
-    validateNonEmptyString(issues, `${path}.valueField`, properties.valueField, 'ProgressList valueField');
-    if (properties.maxItems !== undefined && (!Number.isInteger(properties.maxItems) || properties.maxItems <= 0)) {
+    const propertyRecord = properties;
+    const labelField = getStringAlias(propertyRecord, 'labelField', 'label_field');
+    const valueField = getStringAlias(propertyRecord, 'valueField', 'value_field');
+    const maxItems = getNumberAlias(propertyRecord, 'maxItems', 'max_items');
+    const valueFormat = getStringAlias(propertyRecord, 'valueFormat', 'value_format');
+    const colorScheme = getStringAlias(propertyRecord, 'colorScheme', 'color_scheme');
+    const sortBy = getStringAlias(propertyRecord, 'sortBy', 'sort_by');
+    const sortOrder = getStringAlias(propertyRecord, 'sortOrder', 'sort_order');
+    validateNonEmptyString(issues, `${path}.labelField`, labelField, 'ProgressList labelField');
+    validateNonEmptyString(issues, `${path}.valueField`, valueField, 'ProgressList valueField');
+    if (maxItems !== undefined && (!Number.isInteger(maxItems) || maxItems <= 0)) {
         pushIssue(issues, `${path}.maxItems`, 'ProgressList maxItems must be a positive integer when provided.');
     }
-    if (properties.valueFormat !== undefined) {
+    if (valueFormat !== undefined) {
         const validFormats = new Set(['number', 'currency', 'compact', 'percentage']);
-        if (!validFormats.has(properties.valueFormat)) {
+        if (!validFormats.has(valueFormat)) {
             pushIssue(issues, `${path}.valueFormat`, 'ProgressList valueFormat must be one of: number, currency, compact, percentage.');
         }
     }
-    if (properties.colorScheme !== undefined) {
+    if (colorScheme !== undefined) {
         const validSchemes = new Set(['gradient', 'single', 'custom']);
-        if (!validSchemes.has(properties.colorScheme)) {
+        if (!validSchemes.has(colorScheme)) {
             pushIssue(issues, `${path}.colorScheme`, 'ProgressList colorScheme must be one of: gradient, single, custom.');
         }
     }
-    if (properties.sortBy !== undefined) {
+    if (sortBy !== undefined) {
         const validSortBy = new Set(['value', 'label', 'none']);
-        if (!validSortBy.has(properties.sortBy)) {
+        if (!validSortBy.has(sortBy)) {
             pushIssue(issues, `${path}.sortBy`, 'ProgressList sortBy must be one of: value, label, none.');
         }
     }
-    if (properties.sortOrder !== undefined) {
+    if (sortOrder !== undefined) {
         const validSortOrder = new Set(['asc', 'desc']);
-        if (!validSortOrder.has(properties.sortOrder)) {
+        if (!validSortOrder.has(sortOrder)) {
             pushIssue(issues, `${path}.sortOrder`, 'ProgressList sortOrder must be one of: asc, desc.');
         }
     }
@@ -488,6 +636,12 @@ const validateWidgetProperties = (widget, issues, path) => {
         case 'grid':
             validateGridProperties(widget.properties, issues, `${path}.properties`);
             break;
+        case 'pivot':
+            validatePivotProperties(widget.properties, issues, `${path}.properties`);
+            break;
+        case 'pivotgrid':
+            validatePivotGridProperties(widget.properties, issues, `${path}.properties`);
+            break;
         case 'progress-list':
             validateProgressListProperties(widget.properties, issues, `${path}.properties`);
             break;