@wibi-global/sdk 0.1.0

package/dist/dashboard-spec.js

@@ -0,0 +1,754 @@
+import widgetSchemaJson from './data/widgets.wbx' with { type: 'json' };
+export const WIBI_DASHBOARD_SPEC_VERSION = '1.0.0';
+export const WIBI_DASHBOARD_SPEC_EXPORT_NAME = 'dashboardSpec';
+export const WIBI_DASHBOARD_TEMPLATE_ALLOWED_IMPORTS = ['@wibi-global/sdk'];
+export const WIBI_DASHBOARD_OPTIONAL_DEFAULT_EXPORT = true;
+export const WIBI_DASHBOARD_REQUIRED_INITIAL_FIELDS = [
+    'metadata.name',
+    'metadata.description',
+    'metadata.schema_version',
+    'metadata.generated_at',
+    'metadata.category',
+    'metadata.is_public',
+    'filters',
+    'layout.mode',
+    'layout.sections',
+    'widgets',
+    'queries',
+];
+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 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']);
+/** 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 SERIALIZED_WIDGET_TO_OFFICIAL_TYPES = {
+    chart: ['chart'],
+    grid: ['grid'],
+    kpi: ['kpi'],
+    'progress-list': ['progress-list'],
+    panel: ['card'],
+    date: ['date'],
+    companies: ['companies'],
+    heading: ['text'],
+    text: ['text'],
+    image: ['image'],
+    divider: ['text'],
+    spacer: ['text'],
+};
+const KPI_ALLOWED_PROPERTY_KEYS = new Set([
+    'widget_variant',
+    'label',
+    'value_field',
+    'value_format',
+    'currency',
+    'decimals',
+    'caption',
+    'icon',
+    'tone',
+    'thresholds',
+    'card_properties',
+]);
+const CHART_ALLOWED_PROPERTY_KEYS = new Set([
+    'chart_type',
+    'x_field',
+    'y_field',
+    'y_fields',
+    'group_by_field',
+    'aggregation',
+    'top_n',
+    'sort_order',
+    'sort_by',
+    'title',
+    'description',
+    'show_legend',
+    'show_data_labels',
+    'empty_state',
+    'alternate_colors',
+    'orientation',
+    'bar_width',
+    'rotate_labels',
+    'enable_zoom',
+    'smooth',
+    'show_symbol',
+    'symbol_size',
+    'line_style',
+    'area_opacity',
+    'gradient',
+    'radius',
+    'inner_radius',
+    'rose_type',
+    'start_angle',
+    'min_angle',
+    'show_percentage',
+    'label_position',
+    'max_categories',
+]);
+const GRID_ALLOWED_PROPERTY_KEYS = new Set([
+    'title',
+    'page_size',
+    'columns',
+    'column_labels',
+    'enable_filters',
+    'enable_export',
+    'enable_pagination',
+    'enable_column_settings',
+    'enable_fullscreen',
+    'enable_aggregation',
+    'column_defs',
+    'default_sort',
+    'use_grid_v2',
+    'empty_message',
+    'loading_message',
+]);
+const PANEL_ALLOWED_PROPERTY_KEYS = new Set([
+    'panel_type',
+    'title',
+    'score_field',
+    'score_format',
+    'score_thresholds',
+    'diagnostic_fields',
+    'actions',
+    'sources',
+]);
+const PROGRESS_LIST_ALLOWED_PROPERTY_KEYS = new Set([
+    'labelField',
+    'valueField',
+    'aggregation',
+    'maxItems',
+    'showValues',
+    'showPercentage',
+    'valueFormat',
+    'barHeight',
+    'colorScheme',
+    'primaryColor',
+    'sortBy',
+    'sortOrder',
+]);
+const DATE_WIDGET_ALLOWED_PROPERTY_KEYS = new Set([
+    'label',
+    'default_period_type',
+    'fallback_days',
+]);
+const COMPANIES_WIDGET_ALLOWED_PROPERTY_KEYS = new Set([
+    'placeholder',
+    'show_icon',
+    'auto_select_first',
+    'default_value',
+]);
+const HEADING_ALLOWED_PROPERTY_KEYS = new Set([
+    'level',
+    'content',
+    'align',
+    'color',
+    'subtitle',
+    'subtitle_color',
+    'icon',
+]);
+const TEXT_ALLOWED_PROPERTY_KEYS = new Set([
+    'content',
+    'align',
+    'font_size',
+    'color',
+    'background_color',
+    'padding',
+    'border_radius',
+    'border_color',
+]);
+const IMAGE_ALLOWED_PROPERTY_KEYS = new Set([
+    'src',
+    'alt',
+    'object_fit',
+    'height',
+    'border_radius',
+    'href',
+    'caption',
+]);
+const DIVIDER_ALLOWED_PROPERTY_KEYS = new Set([
+    'style',
+    'color',
+    'thickness',
+    'margin',
+    'label',
+]);
+const SPACER_ALLOWED_PROPERTY_KEYS = new Set([
+    'height',
+]);
+const DATE_FILTER_PLACEHOLDERS = ['startDate', 'endDate'];
+const EMPRESA_FILTER_PLACEHOLDERS = ['empresaId', 'companyId', 'companies', 'companyIds'];
+const ACCEPTED_QUERY_PLACEHOLDER_PATTERNS = [
+    /^\$\{startDate\}$/,
+    /^\$\{endDate\}$/,
+    /^\$\{empresaId\}$/,
+    /^\$\{companyId\}$/,
+    /^\$\{companyIds\}$/,
+    /^\$\{companyFilter:[a-zA-Z_][a-zA-Z0-9_]*\}$/,
+    /^\{\{start_date\}\}$/,
+    /^\{\{end_date\}\}$/,
+    /^\{\{year\}\}$/,
+    /^\{\{date_limit_2y\}\}$/,
+];
+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 validateNonEmptyString = (issues, path, value, label) => {
+    if (!isNonEmptyString(value)) {
+        pushIssue(issues, path, `${label} must be a non-empty string.`);
+    }
+};
+const validateUniqueStrings = (issues, values, path, label) => {
+    const seen = new Set();
+    values.forEach((value, index) => {
+        if (seen.has(value)) {
+            pushIssue(issues, `${path}[${index}]`, `${label} "${value}" is duplicated.`);
+            return;
+        }
+        seen.add(value);
+    });
+};
+const validateStableId = (issues, path, value, pattern, label) => {
+    if (!pattern.test(value)) {
+        pushIssue(issues, path, `${label} must use lowercase kebab-case ASCII and follow the official naming rule.`);
+    }
+};
+const validateUniqueIds = (issues, values, label) => {
+    const seen = new Map();
+    for (const value of values) {
+        const firstPath = seen.get(value.id);
+        if (firstPath) {
+            pushIssue(issues, value.path, `${label} "${value.id}" is duplicated. First declared at ${firstPath}.`);
+            continue;
+        }
+        seen.set(value.id, value.path);
+    }
+};
+const validateOfficialWidgetType = (issues, path, widgetType) => {
+    // Decorative widgets don't require widgets.wbx mapping
+    if (DECORATIVE_WIDGET_TYPES.has(widgetType)) {
+        return;
+    }
+    const officialTypes = SERIALIZED_WIDGET_TO_OFFICIAL_TYPES[widgetType] ?? [];
+    const hasOfficialType = officialTypes.some((type) => OFFICIAL_DASHBOARD_ITEM_TYPES.has(type));
+    if (!hasOfficialType) {
+        pushIssue(issues, path, `Widget type "${widgetType}" has no compatible mapping in widgets.wbx dashboardItemType.`);
+    }
+};
+const validateAllowedPropertyKeys = (issues, path, properties, allowedKeys, widgetType) => {
+    const record = properties;
+    Object.keys(record).forEach((key) => {
+        if (!allowedKeys.has(key)) {
+            pushIssue(issues, `${path}.${key}`, `Property "${key}" is not supported for widget type "${widgetType}" in the current TSX contract.`);
+        }
+    });
+};
+const validateKpiProperties = (properties, issues, path) => {
+    validateAllowedPropertyKeys(issues, path, properties, KPI_ALLOWED_PROPERTY_KEYS, 'kpi');
+    validateNonEmptyString(issues, `${path}.label`, properties.label, 'KPI label');
+    validateNonEmptyString(issues, `${path}.value_field`, properties.value_field, 'KPI value_field');
+    validateNonEmptyString(issues, `${path}.caption`, properties.caption, 'KPI caption');
+    validateNonEmptyString(issues, `${path}.icon`, properties.icon, 'KPI icon');
+    if (properties.decimals !== undefined && (!Number.isInteger(properties.decimals) || properties.decimals < 0)) {
+        pushIssue(issues, `${path}.decimals`, 'KPI decimals must be a non-negative integer when provided.');
+    }
+    const officialKpi = OFFICIAL_WIDGET_CATALOG.kpi;
+    if (!officialKpi) {
+        pushIssue(issues, path, 'Official KPI definition is missing from widgets.wbx.');
+    }
+};
+const validateChartProperties = (properties, issues, path) => {
+    validateAllowedPropertyKeys(issues, path, properties, CHART_ALLOWED_PROPERTY_KEYS, 'chart');
+    validateNonEmptyString(issues, `${path}.x_field`, properties.x_field, 'Chart x_field');
+    if (properties.title !== undefined) {
+        validateNonEmptyString(issues, `${path}.title`, properties.title, 'Chart title');
+    }
+    const yFields = properties.y_fields ?? [];
+    if (yFields.length === 0 && !properties.y_field) {
+        pushIssue(issues, `${path}.y_fields`, 'Chart must have y_field or y_fields with at least one field.');
+    }
+    validateUniqueStrings(issues, yFields, `${path}.y_fields`, 'Chart y_field');
+    yFields.forEach((field, index) => {
+        validateNonEmptyString(issues, `${path}.y_fields[${index}]`, field, 'Chart y_field');
+    });
+    if (!OFFICIAL_CHART_VARIANTS.has(properties.chart_type)) {
+        pushIssue(issues, `${path}.chart_type`, `Chart type "${properties.chart_type}" is not registered in widgets.wbx.`);
+    }
+    const officialChart = OFFICIAL_WIDGET_CATALOG.chart;
+    if (!officialChart) {
+        pushIssue(issues, path, 'Official chart definition is missing from widgets.wbx.');
+    }
+};
+const validateGridProperties = (properties, issues, path) => {
+    validateAllowedPropertyKeys(issues, path, properties, GRID_ALLOWED_PROPERTY_KEYS, 'grid');
+    validateNonEmptyString(issues, `${path}.title`, properties.title, 'Grid title');
+    if (!Number.isInteger(properties.page_size) || properties.page_size <= 0) {
+        pushIssue(issues, `${path}.page_size`, 'Grid page_size must be a positive integer.');
+    }
+    // When column_defs is provided, columns + column_labels become optional
+    const hasColumnDefs = Array.isArray(properties.column_defs) && properties.column_defs.length > 0;
+    if (!hasColumnDefs) {
+        if (properties.columns.length === 0) {
+            pushIssue(issues, `${path}.columns`, 'Grid columns must contain at least one field (or use column_defs).');
+        }
+        validateUniqueStrings(issues, properties.columns, `${path}.columns`, 'Grid column');
+        properties.columns.forEach((column, index) => {
+            validateNonEmptyString(issues, `${path}.columns[${index}]`, column, 'Grid column');
+            if (!Object.prototype.hasOwnProperty.call(properties.column_labels, column)) {
+                pushIssue(issues, `${path}.column_labels`, `Grid column_labels must include a label for column "${column}".`);
+            }
+        });
+    }
+    if (hasColumnDefs) {
+        const columnDefIds = properties.column_defs.map((def) => def.id);
+        validateUniqueStrings(issues, columnDefIds, `${path}.column_defs`, 'Grid column_defs id');
+        properties.column_defs.forEach((def, index) => {
+            validateNonEmptyString(issues, `${path}.column_defs[${index}].id`, def.id, 'column_defs id');
+            validateNonEmptyString(issues, `${path}.column_defs[${index}].header`, def.header, 'column_defs header');
+            if (def.format?.type !== undefined) {
+                const validTypes = new Set(['text', 'number', 'currency', 'percentage', 'date', 'datetime', 'boolean']);
+                if (!validTypes.has(def.format.type)) {
+                    pushIssue(issues, `${path}.column_defs[${index}].format.type`, `column_defs format.type must be one of: ${[...validTypes].join(', ')}.`);
+                }
+            }
+        });
+    }
+    if (properties.default_sort) {
+        validateNonEmptyString(issues, `${path}.default_sort.column_id`, properties.default_sort.column_id, 'Grid default_sort.column_id');
+        const validDirections = new Set(['asc', 'desc']);
+        if (!validDirections.has(properties.default_sort.direction)) {
+            pushIssue(issues, `${path}.default_sort.direction`, 'Grid default_sort.direction must be asc or desc.');
+        }
+    }
+    const officialGrid = OFFICIAL_WIDGET_CATALOG.grid;
+    if (!officialGrid) {
+        pushIssue(issues, path, 'Official grid 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');
+    if (properties.diagnostic_fields) {
+        validateUniqueStrings(issues, properties.diagnostic_fields, `${path}.diagnostic_fields`, 'Panel diagnostic field');
+        properties.diagnostic_fields.forEach((field, index) => {
+            validateNonEmptyString(issues, `${path}.diagnostic_fields[${index}]`, field, 'Panel diagnostic field');
+        });
+    }
+    if (properties.sources) {
+        validateUniqueStrings(issues, properties.sources, `${path}.sources`, 'Panel source');
+        properties.sources.forEach((source, index) => {
+            validateNonEmptyString(issues, `${path}.sources[${index}]`, source, 'Panel source');
+        });
+    }
+    if (properties.actions) {
+        properties.actions.forEach((action, index) => {
+            validateNonEmptyString(issues, `${path}.actions[${index}].path`, action.path, 'Panel action path');
+            validateNonEmptyString(issues, `${path}.actions[${index}].title`, action.title, 'Panel action title');
+            validateNonEmptyString(issues, `${path}.actions[${index}].description`, action.description, 'Panel action description');
+        });
+    }
+};
+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)) {
+        pushIssue(issues, `${path}.maxItems`, 'ProgressList maxItems must be a positive integer when provided.');
+    }
+    if (properties.valueFormat !== undefined) {
+        const validFormats = new Set(['number', 'currency', 'compact', 'percentage']);
+        if (!validFormats.has(properties.valueFormat)) {
+            pushIssue(issues, `${path}.valueFormat`, 'ProgressList valueFormat must be one of: number, currency, compact, percentage.');
+        }
+    }
+    if (properties.colorScheme !== undefined) {
+        const validSchemes = new Set(['gradient', 'single', 'custom']);
+        if (!validSchemes.has(properties.colorScheme)) {
+            pushIssue(issues, `${path}.colorScheme`, 'ProgressList colorScheme must be one of: gradient, single, custom.');
+        }
+    }
+    if (properties.sortBy !== undefined) {
+        const validSortBy = new Set(['value', 'label', 'none']);
+        if (!validSortBy.has(properties.sortBy)) {
+            pushIssue(issues, `${path}.sortBy`, 'ProgressList sortBy must be one of: value, label, none.');
+        }
+    }
+    if (properties.sortOrder !== undefined) {
+        const validSortOrder = new Set(['asc', 'desc']);
+        if (!validSortOrder.has(properties.sortOrder)) {
+            pushIssue(issues, `${path}.sortOrder`, 'ProgressList sortOrder must be one of: asc, desc.');
+        }
+    }
+};
+const validateDateWidgetProperties = (properties, issues, path) => {
+    validateAllowedPropertyKeys(issues, path, properties, DATE_WIDGET_ALLOWED_PROPERTY_KEYS, 'date');
+    if (properties.label !== undefined) {
+        validateNonEmptyString(issues, `${path}.label`, properties.label, 'Date widget label');
+    }
+    if (properties.default_period_type !== undefined) {
+        const validPeriods = new Set(['D', 'S', 'M', 'T', 'SE', 'A', 'W', 'Q', 'Y', 'SP', 'CUSTOM']);
+        if (!validPeriods.has(properties.default_period_type)) {
+            pushIssue(issues, `${path}.default_period_type`, 'Date widget default_period_type must be one of D, S, M, T, SE, A, W, Q, Y, SP or CUSTOM.');
+        }
+    }
+    if (properties.fallback_days !== undefined && (!Number.isInteger(properties.fallback_days) || properties.fallback_days < 0)) {
+        pushIssue(issues, `${path}.fallback_days`, 'Date widget fallback_days must be a non-negative integer when provided.');
+    }
+};
+const validateCompaniesWidgetProperties = (properties, issues, path) => {
+    validateAllowedPropertyKeys(issues, path, properties, COMPANIES_WIDGET_ALLOWED_PROPERTY_KEYS, 'companies');
+    if (properties.placeholder !== undefined) {
+        validateNonEmptyString(issues, `${path}.placeholder`, properties.placeholder, 'Companies widget placeholder');
+    }
+    if (properties.default_value !== undefined && typeof properties.default_value !== 'number') {
+        pushIssue(issues, `${path}.default_value`, 'Companies widget default_value must be a number when provided.');
+    }
+};
+const validateHeadingProperties = (properties, issues, path) => {
+    validateAllowedPropertyKeys(issues, path, properties, HEADING_ALLOWED_PROPERTY_KEYS, 'heading');
+    validateNonEmptyString(issues, `${path}.content`, properties.content, 'Heading content');
+    const validLevels = new Set(['h1', 'h2', 'h3', 'h4']);
+    if (!validLevels.has(properties.level)) {
+        pushIssue(issues, `${path}.level`, 'Heading level must be one of h1, h2, h3, h4.');
+    }
+    if (properties.align !== undefined) {
+        const validAligns = new Set(['left', 'center', 'right']);
+        if (!validAligns.has(properties.align)) {
+            pushIssue(issues, `${path}.align`, 'Heading align must be one of left, center, right.');
+        }
+    }
+};
+const validateTextProperties = (properties, issues, path) => {
+    validateAllowedPropertyKeys(issues, path, properties, TEXT_ALLOWED_PROPERTY_KEYS, 'text');
+    validateNonEmptyString(issues, `${path}.content`, properties.content, 'Text content');
+    if (properties.align !== undefined) {
+        const validAligns = new Set(['left', 'center', 'right', 'justify']);
+        if (!validAligns.has(properties.align)) {
+            pushIssue(issues, `${path}.align`, 'Text align must be one of left, center, right, justify.');
+        }
+    }
+    if (properties.font_size !== undefined) {
+        const validSizes = new Set(['xs', 'sm', 'base', 'lg', 'xl']);
+        if (!validSizes.has(properties.font_size)) {
+            pushIssue(issues, `${path}.font_size`, 'Text font_size must be one of xs, sm, base, lg, xl.');
+        }
+    }
+};
+const validateImageProperties = (properties, issues, path) => {
+    validateAllowedPropertyKeys(issues, path, properties, IMAGE_ALLOWED_PROPERTY_KEYS, 'image');
+    validateNonEmptyString(issues, `${path}.src`, properties.src, 'Image src');
+    validateNonEmptyString(issues, `${path}.alt`, properties.alt, 'Image alt');
+    if (properties.object_fit !== undefined) {
+        const validFits = new Set(['cover', 'contain', 'fill', 'none']);
+        if (!validFits.has(properties.object_fit)) {
+            pushIssue(issues, `${path}.object_fit`, 'Image object_fit must be one of cover, contain, fill, none.');
+        }
+    }
+    if (properties.height !== undefined && (!Number.isInteger(properties.height) || properties.height <= 0)) {
+        pushIssue(issues, `${path}.height`, 'Image height must be a positive integer when provided.');
+    }
+};
+const validateDividerProperties = (properties, issues, path) => {
+    validateAllowedPropertyKeys(issues, path, properties, DIVIDER_ALLOWED_PROPERTY_KEYS, 'divider');
+    if (properties.style !== undefined) {
+        const validStyles = new Set(['solid', 'dashed', 'dotted']);
+        if (!validStyles.has(properties.style)) {
+            pushIssue(issues, `${path}.style`, 'Divider style must be one of solid, dashed, dotted.');
+        }
+    }
+    if (properties.thickness !== undefined && (!Number.isInteger(properties.thickness) || properties.thickness <= 0)) {
+        pushIssue(issues, `${path}.thickness`, 'Divider thickness must be a positive integer when provided.');
+    }
+};
+const validateSpacerProperties = (properties, issues, path) => {
+    validateAllowedPropertyKeys(issues, path, properties, SPACER_ALLOWED_PROPERTY_KEYS, 'spacer');
+    if (!Number.isInteger(properties.height) || properties.height <= 0) {
+        pushIssue(issues, `${path}.height`, 'Spacer height must be a positive integer.');
+    }
+};
+const validateWidgetProperties = (widget, issues, path) => {
+    validateOfficialWidgetType(issues, `${path}.widget_type`, widget.widget_type);
+    switch (widget.widget_type) {
+        case 'kpi':
+            validateKpiProperties(widget.properties, issues, `${path}.properties`);
+            break;
+        case 'chart':
+            validateChartProperties(widget.properties, issues, `${path}.properties`);
+            break;
+        case 'grid':
+            validateGridProperties(widget.properties, issues, `${path}.properties`);
+            break;
+        case 'progress-list':
+            validateProgressListProperties(widget.properties, issues, `${path}.properties`);
+            break;
+        case 'panel':
+            validatePanelProperties(widget.properties, issues, `${path}.properties`);
+            break;
+        case 'date':
+            validateDateWidgetProperties(widget.properties, issues, `${path}.properties`);
+            break;
+        case 'companies':
+            validateCompaniesWidgetProperties(widget.properties, issues, `${path}.properties`);
+            break;
+        case 'heading':
+            validateHeadingProperties(widget.properties, issues, `${path}.properties`);
+            break;
+        case 'text':
+            validateTextProperties(widget.properties, issues, `${path}.properties`);
+            break;
+        case 'image':
+            validateImageProperties(widget.properties, issues, `${path}.properties`);
+            break;
+        case 'divider':
+            validateDividerProperties(widget.properties, issues, `${path}.properties`);
+            break;
+        case 'spacer':
+            validateSpacerProperties(widget.properties, issues, `${path}.properties`);
+            break;
+        default:
+            break;
+    }
+};
+const validateRequiredFilters = (spec, issues) => {
+    const hasDateFilter = spec.filters.some((filter) => filter.type === 'date');
+    const hasEmpresaFilter = spec.filters.some((filter) => filter.type === 'empresa');
+    const sqlTemplates = spec.queries.map((query) => query.sql_template.toLowerCase());
+    const dependsOnDate = sqlTemplates.some((sql) => DATE_FILTER_PLACEHOLDERS.some((placeholder) => sql.includes(placeholder.toLowerCase())));
+    const dependsOnEmpresa = sqlTemplates.some((sql) => EMPRESA_FILTER_PLACEHOLDERS.some((placeholder) => sql.includes(placeholder.toLowerCase())));
+    if (dependsOnDate && !hasDateFilter) {
+        pushIssue(issues, 'filters', 'Dashboard queries use date placeholders, so at least one filter of type "date" is required.');
+    }
+    if (dependsOnEmpresa && !hasEmpresaFilter) {
+        pushIssue(issues, 'filters', 'Dashboard queries use company placeholders, so at least one filter of type "empresa" is required.');
+    }
+};
+const validateFilters = (filters, issues) => {
+    validateUniqueIds(issues, filters.map((filter, index) => ({ id: filter.id, path: `filters[${index}].id` })), 'Filter id');
+    filters.forEach((filter, index) => {
+        validateStableId(issues, `filters[${index}].id`, filter.id, FILTER_ID_PATTERN, 'Filter id');
+        validateNonEmptyString(issues, `filters[${index}].label`, filter.label, 'Filter label');
+        if (filter.type === 'date' && filter.binds_to.length === 0) {
+            pushIssue(issues, `filters[${index}].binds_to`, 'Date filters must bind at least one runtime parameter.');
+        }
+        if (filter.type === 'date') {
+            validateUniqueStrings(issues, filter.binds_to, `filters[${index}].binds_to`, 'Date filter binding');
+            filter.binds_to.forEach((binding, bindingIndex) => {
+                validateNonEmptyString(issues, `filters[${index}].binds_to[${bindingIndex}]`, binding, 'Date filter binding');
+            });
+        }
+        if (filter.type === 'empresa') {
+            validateNonEmptyString(issues, `filters[${index}].placeholder`, filter.placeholder, 'Empresa filter placeholder');
+            validateNonEmptyString(issues, `filters[${index}].sql_template`, filter.sql_template, 'Empresa filter sql_template');
+        }
+    });
+};
+const validateSections = (sections, issues) => {
+    if (sections.length === 0) {
+        pushIssue(issues, 'layout.sections', 'At least one section is required in the official TSX signature.');
+    }
+    validateUniqueIds(issues, sections.map((section, index) => ({ id: section.id, path: `layout.sections[${index}].id` })), 'Section id');
+    sections.forEach((section, index) => {
+        validateStableId(issues, `layout.sections[${index}].id`, section.id, SECTION_ID_PATTERN, 'Section id');
+        validateNonEmptyString(issues, `layout.sections[${index}].title`, section.title, 'Section title');
+        if (!Number.isInteger(section.columns) || section.columns <= 0) {
+            pushIssue(issues, `layout.sections[${index}].columns`, 'Section columns must be a positive integer.');
+        }
+        const responsiveEntries = Object.entries(section.responsive ?? {});
+        responsiveEntries.forEach(([breakpoint, value]) => {
+            if (value !== undefined && (!Number.isInteger(value) || value <= 0)) {
+                pushIssue(issues, `layout.sections[${index}].responsive.${breakpoint}`, 'Responsive section columns must be positive integers.');
+            }
+        });
+        validateUniqueStrings(issues, section.items, `layout.sections[${index}].items`, 'Section item');
+    });
+};
+const validateQueries = (queries, issues) => {
+    validateUniqueIds(issues, queries.map((query, index) => ({ id: query.id, path: `queries[${index}].id` })), 'Query id');
+    queries.forEach((query, index) => {
+        validateStableId(issues, `queries[${index}].id`, query.id, QUERY_ID_PATTERN, 'Query id');
+        validateNonEmptyString(issues, `queries[${index}].description`, query.description, 'Query description');
+        validateNonEmptyString(issues, `queries[${index}].sql_template`, query.sql_template, 'Query sql_template');
+        if (query.sources.length === 0) {
+            pushIssue(issues, `queries[${index}].sources`, 'Queries must declare at least one normative source.');
+        }
+        if (query.output_fields.length === 0) {
+            pushIssue(issues, `queries[${index}].output_fields`, 'Queries must declare at least one output field.');
+        }
+        validateUniqueStrings(issues, query.sources, `queries[${index}].sources`, 'Query source');
+        validateUniqueStrings(issues, query.output_fields, `queries[${index}].output_fields`, 'Query output field');
+        query.sources.forEach((source, sourceIndex) => {
+            validateNonEmptyString(issues, `queries[${index}].sources[${sourceIndex}]`, source, 'Query source');
+        });
+        query.output_fields.forEach((field, fieldIndex) => {
+            validateNonEmptyString(issues, `queries[${index}].output_fields[${fieldIndex}]`, field, 'Query output field');
+        });
+    });
+};
+const validateQueryPlaceholders = (queries, issues) => {
+    queries.forEach((query, index) => {
+        const placeholders = query.sql_template.match(/\$\{[^}]+\}|\{\{[^}]+\}\}/g) ?? [];
+        placeholders.forEach((placeholder, placeholderIndex) => {
+            const isAccepted = ACCEPTED_QUERY_PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(placeholder));
+            if (!isAccepted) {
+                pushIssue(issues, `queries[${index}].sql_template`, `Placeholder "${placeholder}" is not allowed by the current WiBi SQL conventions (match #${placeholderIndex + 1}).`);
+            }
+        });
+    });
+};
+const validateSerializedDashboardShape = (spec, issues) => {
+    if (typeof spec.metadata.is_public !== 'boolean') {
+        pushIssue(issues, 'metadata.is_public', 'metadata.is_public must be a boolean.');
+    }
+    spec.filters.forEach((filter, index) => {
+        if (filter.type === 'date') {
+            if (!['D', 'S', 'M', 'T', 'SE', 'A', 'W', 'Q', 'Y', 'SP', 'CUSTOM'].includes(filter.default_period_type)) {
+                pushIssue(issues, `filters[${index}].default_period_type`, 'Date filter default_period_type must be one of D, S, M, T, SE, A, W, Q, Y, SP or CUSTOM.');
+            }
+        }
+        if (filter.type === 'empresa' && typeof filter.default_value !== 'number') {
+            pushIssue(issues, `filters[${index}].default_value`, 'Empresa filter default_value must be a number.');
+        }
+    });
+    spec.layout.sections.forEach((section, index) => {
+        if (!Array.isArray(section.items)) {
+            pushIssue(issues, `layout.sections[${index}].items`, 'Section items must be an array.');
+        }
+    });
+    spec.widgets.forEach((widget, index) => {
+        if (widget.query_id !== null && typeof widget.query_id !== 'string') {
+            pushIssue(issues, `widgets[${index}].query_id`, 'Widget query_id must be a string or null.');
+        }
+        if (typeof widget.properties !== 'object' || widget.properties === null || Array.isArray(widget.properties)) {
+            pushIssue(issues, `widgets[${index}].properties`, 'Widget properties must be an object.');
+        }
+    });
+    spec.queries.forEach((query, index) => {
+        if (!Array.isArray(query.sources)) {
+            pushIssue(issues, `queries[${index}].sources`, 'Query sources must be an array.');
+        }
+        if (!Array.isArray(query.output_fields)) {
+            pushIssue(issues, `queries[${index}].output_fields`, 'Query output_fields must be an array.');
+        }
+    });
+};
+const validateWidgets = (sections, widgets, issues, sectionIds, queryIds) => {
+    validateUniqueIds(issues, widgets.map((widget, index) => ({ id: widget.id, path: `widgets[${index}].id` })), 'Widget id');
+    const sectionOrders = new Map();
+    const sectionColumns = new Map(sections.map((section) => [section.id, section.columns]));
+    widgets.forEach((widget, index) => {
+        validateStableId(issues, `widgets[${index}].id`, widget.id, STABLE_ID_PATTERN, 'Widget id');
+        validateNonEmptyString(issues, `widgets[${index}].title`, widget.title, 'Widget title');
+        if (!WIDGET_TYPES.has(widget.widget_type)) {
+            pushIssue(issues, `widgets[${index}].widget_type`, `Widget type "${widget.widget_type}" is not supported by the official TSX signature.`);
+        }
+        if (!sectionIds.has(widget.section_id)) {
+            pushIssue(issues, `widgets[${index}].section_id`, `Widget section_id "${widget.section_id}" does not match any declared layout section.`);
+        }
+        if (widget.query_id && !queryIds.has(widget.query_id)) {
+            pushIssue(issues, `widgets[${index}].query_id`, `Widget query_id "${widget.query_id}" does not match any declared query.`);
+        }
+        if (!DECORATIVE_WIDGET_TYPES.has(widget.widget_type) && widget.widget_type !== 'panel' && !widget.query_id) {
+            pushIssue(issues, `widgets[${index}].query_id`, `Widget type "${widget.widget_type}" must declare a query_id.`);
+        }
+        if (!Number.isInteger(widget.order) || widget.order < 0) {
+            pushIssue(issues, `widgets[${index}].order`, 'Widget order must be a non-negative integer.');
+        }
+        if (!Number.isInteger(widget.col_span) || widget.col_span <= 0) {
+            pushIssue(issues, `widgets[${index}].col_span`, 'Widget col_span must be a positive integer.');
+        }
+        const maxColumns = sectionColumns.get(widget.section_id);
+        if (maxColumns !== undefined && widget.col_span > maxColumns) {
+            pushIssue(issues, `widgets[${index}].col_span`, `Widget col_span ${widget.col_span} exceeds section "${widget.section_id}" columns (${maxColumns}).`);
+        }
+        if (widget.height !== undefined && (!Number.isInteger(widget.height) || widget.height <= 0)) {
+            pushIssue(issues, `widgets[${index}].height`, 'Widget height must be a positive integer when provided.');
+        }
+        validateWidgetProperties(widget, issues, `widgets[${index}]`);
+        const existingOrders = sectionOrders.get(widget.section_id) ?? new Set();
+        if (existingOrders.has(widget.order)) {
+            pushIssue(issues, `widgets[${index}].order`, `Widget order ${widget.order} is duplicated inside section "${widget.section_id}".`);
+        }
+        existingOrders.add(widget.order);
+        sectionOrders.set(widget.section_id, existingOrders);
+    });
+};
+const validateLayoutItems = (sections, widgets, issues) => {
+    const widgetIds = new Set(widgets.map((widget) => widget.id));
+    const widgetsBySection = new Map();
+    widgets.forEach((widget) => {
+        const ids = widgetsBySection.get(widget.section_id) ?? new Set();
+        ids.add(widget.id);
+        widgetsBySection.set(widget.section_id, ids);
+    });
+    sections.forEach((section, sectionIndex) => {
+        const declaredItems = new Set(section.items);
+        const expectedItems = widgetsBySection.get(section.id) ?? new Set();
+        if (section.items.length === 0 && expectedItems.size > 0) {
+            pushIssue(issues, `layout.sections[${sectionIndex}].items`, 'Section items must reference at least one widget.');
+        }
+        section.items.forEach((itemId, itemIndex) => {
+            if (!widgetIds.has(itemId)) {
+                pushIssue(issues, `layout.sections[${sectionIndex}].items[${itemIndex}]`, `Section item "${itemId}" does not match any declared widget.`);
+            }
+        });
+        for (const widgetId of expectedItems) {
+            if (!declaredItems.has(widgetId)) {
+                pushIssue(issues, `layout.sections[${sectionIndex}].items`, `Section "${section.id}" must include widget "${widgetId}" in layout.items.`);
+            }
+        }
+    });
+};
+export const validateDashboardSpec = (spec) => {
+    const issues = [];
+    validateNonEmptyString(issues, 'metadata.name', spec.metadata.name, 'metadata.name');
+    validateNonEmptyString(issues, 'metadata.description', spec.metadata.description, 'metadata.description');
+    validateNonEmptyString(issues, 'metadata.category', spec.metadata.category, 'metadata.category');
+    if (spec.layout.mode !== 'sections') {
+        pushIssue(issues, 'layout.mode', 'layout.mode must be "sections" for the current TSX signature.');
+    }
+    if (spec.metadata.schema_version !== WIBI_DASHBOARD_SPEC_VERSION) {
+        pushIssue(issues, 'metadata.schema_version', `metadata.schema_version must be "${WIBI_DASHBOARD_SPEC_VERSION}" for the current TSX signature.`);
+    }
+    if (!ISO_TIMESTAMP_PATTERN.test(spec.metadata.generated_at)) {
+        pushIssue(issues, 'metadata.generated_at', 'metadata.generated_at must be an ISO-8601 UTC timestamp, for example 2026-03-12T00:00:00.000Z.');
+    }
+    validateFilters(spec.filters, issues);
+    validateSections(spec.layout.sections, issues);
+    validateQueries(spec.queries, issues);
+    validateRequiredFilters(spec, issues);
+    validateQueryPlaceholders(spec.queries, issues);
+    validateSerializedDashboardShape(spec, issues);
+    const sectionIds = new Set(spec.layout.sections.map((section) => section.id));
+    const queryIds = new Set(spec.queries.map((query) => query.id));
+    validateWidgets(spec.layout.sections, spec.widgets, issues, sectionIds, queryIds);
+    validateLayoutItems(spec.layout.sections, spec.widgets, issues);
+    if (issues.length > 0) {
+        return {
+            ok: false,
+            issues,
+        };
+    }
+    return {
+        ok: true,
+        issues: [],
+    };
+};
+export const assertValidDashboardSpec = (spec) => {
+    const result = validateDashboardSpec(spec);
+    if (!result.ok) {
+        const details = result.issues.map((issue) => `${issue.path}: ${issue.message}`).join('\n');
+        throw new Error(`Invalid WiBi dashboardSpec.\n${details}`);
+    }
+    return spec;
+};
+export const defineDashboardSpec = (spec) => {
+    return assertValidDashboardSpec(spec);
+};
+//# sourceMappingURL=dashboard-spec.js.map