@wildo-ai/saas-models 1.0.1

package/dist/esm/config/frontend/chart-definition.shared.schemas.js

@@ -0,0 +1,998 @@
+import { z } from 'zod';
+import { AggregationQuerySchema } from '../../charts/aggregation-query.shared.schemas.js';
+import { RequiredFeaturesConfigSchema } from '../../features/feature-definition.shared.schemas.js';
+/** ──────────────────────────────────────────────────────────────
+ * ChartView – Core primitives (ECharts-oriented)
+ * ────────────────────────────────────────────────────────────── */
+// ── Chart Types ──────────────────────────────────────────────
+// Full taxonomy covering all ECharts-backed chart types.
+// Sparklines and mini-charts use existing Recharts wrappers (not part of ChartView).
+export var ChartType;
+(function (ChartType) {
+    // Comparisons & Rankings
+    ChartType["BAR"] = "bar";
+    ChartType["HORIZONTAL_BAR"] = "horizontal_bar";
+    ChartType["GROUPED_BAR"] = "grouped_bar";
+    ChartType["STACKED_BAR"] = "stacked_bar";
+    ChartType["WATERFALL"] = "waterfall";
+    // Trends & Time Series
+    ChartType["LINE"] = "line";
+    ChartType["AREA"] = "area";
+    ChartType["STACKED_AREA"] = "stacked_area";
+    ChartType["STEP_LINE"] = "step_line";
+    // Part-of-Whole
+    ChartType["PIE"] = "pie";
+    ChartType["DONUT"] = "donut";
+    ChartType["SUNBURST"] = "sunburst";
+    ChartType["TREEMAP"] = "treemap";
+    // Correlation & Distribution
+    ChartType["SCATTER"] = "scatter";
+    ChartType["BUBBLE"] = "bubble";
+    ChartType["HEATMAP"] = "heatmap";
+    ChartType["BOXPLOT"] = "boxplot";
+    // Multi-Dimensional
+    ChartType["RADAR"] = "radar";
+    ChartType["PARALLEL"] = "parallel";
+    // Business / Process
+    ChartType["FUNNEL"] = "funnel";
+    ChartType["GAUGE"] = "gauge";
+    ChartType["SANKEY"] = "sankey";
+    // Composed / Mixed
+    ChartType["COMPOSED"] = "composed";
+})(ChartType || (ChartType = {}));
+// ── Chart Point Shape ────────────────────────────────────────
+export var ChartPointShape;
+(function (ChartPointShape) {
+    ChartPointShape["CIRCLE"] = "circle";
+    ChartPointShape["SQUARE"] = "square";
+    ChartPointShape["TRIANGLE"] = "triangle";
+    ChartPointShape["DIAMOND"] = "diamond";
+    ChartPointShape["PIN"] = "pin";
+    ChartPointShape["ARROW"] = "arrow";
+    ChartPointShape["NONE"] = "none";
+})(ChartPointShape || (ChartPointShape = {}));
+// ── Series Style Schema ──────────────────────────────────────
+// ECharts-oriented style properties for individual series.
+export const ChartSeriesStyleSchema = z.object({
+    /** Override series color (hex). Falls back to palette. */
+    color: z.string().optional(),
+    /** Line width in pixels (line/area charts). Default: 2 */
+    lineWidth: z.number().positive().optional(),
+    /** Line dash type. Default: 'solid' */
+    lineType: z.enum(['solid', 'dashed', 'dotted']).optional(),
+    /** Area opacity (0-1, for area charts). Default: 0.3 */
+    areaOpacity: z.number().min(0).max(1).optional(),
+    /** Point shape on data points */
+    pointShape: z.enum(ChartPointShape).optional(),
+    /** Point size in pixels. Default: 4. Set to 0 to hide. */
+    pointSize: z.number().min(0).optional(),
+    /** Smooth interpolation (line/area). Default: false */
+    smooth: z.boolean().optional(),
+    /** Bar width (pixels or percentage string like '60%'). Default: auto */
+    barWidth: z.union([z.number().positive(), z.string()]).optional(),
+    /** Opacity of the series (0-1). Default: 1 */
+    opacity: z.number().min(0).max(1).optional(),
+    // ── Universal properties (apply to multiple chart types) ──
+    /** Connect null/missing data points with a line. Default: false (line/area) */
+    connectNulls: z.boolean().optional(),
+    /** Step line type. Default: 'start' (step_line charts) */
+    step: z.enum(['start', 'middle', 'end']).optional(),
+    /** Show data labels on points/bars/slices. Default: varies by chart type */
+    showLabel: z.boolean().optional(),
+    /** Label position. Default: varies by chart type */
+    labelPosition: z.enum(['top', 'bottom', 'left', 'right', 'inside', 'outside', 'center']).optional(),
+    /** Label formatter string (ECharts formatter syntax). Default: varies */
+    labelFormatter: z.string().optional(),
+    /** Scale emphasis effect on hover. Default: varies by chart type */
+    emphasisScale: z.boolean().optional(),
+    // ── Mark Lines (reference lines on series) ──
+    /**
+     * Reference lines drawn on this series (e.g., average, min, max, threshold).
+     * Each entry renders a horizontal/vertical reference line on the chart.
+     */
+    markLines: z.array(z.object({
+        /** Type of built-in line, or omit for custom value */
+        type: z.enum(['average', 'min', 'max']).optional(),
+        /** Custom Y value for the line (when type is not set) */
+        yValue: z.number().optional(),
+        /** Custom X value for the line (when type is not set) */
+        xValue: z.union([z.number(), z.string()]).optional(),
+        /** Line label text. Supports i18n key if prefixed with 'i18n:' */
+        label: z.string().optional(),
+        /** Line color. Default: from theme */
+        color: z.string().optional(),
+        /** Line type. Default: 'dashed' */
+        lineType: z.enum(['solid', 'dashed', 'dotted']).optional(),
+    })).optional(),
+    // ── Mark Points (data point markers on series) ──
+    /**
+     * Highlighted data points on this series (e.g., max, min, custom).
+     */
+    markPoints: z.array(z.object({
+        /** Type of built-in point */
+        type: z.enum(['min', 'max', 'average']).optional(),
+        /** Point label. Supports i18n key if prefixed with 'i18n:' */
+        label: z.string().optional(),
+        /** Symbol shape. Default: 'pin' */
+        symbol: z.enum(['circle', 'rect', 'roundRect', 'triangle', 'diamond', 'pin', 'arrow']).optional(),
+        /** Symbol size. Default: 50 */
+        symbolSize: z.number().optional(),
+    })).optional(),
+});
+// ── Split Config Schema ──────────────────────────────────────
+// Configuration for splitting a series by dimension values (stacked/grouped charts).
+export const ChartSplitConfigSchema = z.object({
+    /** Explicit color per dimension value. Values not in the map use palette colors. */
+    colorMap: z.record(z.string(), z.string()).optional(),
+    /** Explicit order for dimension values in the legend and stack. */
+    order: z.array(z.string()).optional(),
+    /** Exclude specific dimension values from rendering. */
+    exclude: z.array(z.string()).optional(),
+    /** Custom labels per dimension value (overrides raw value). */
+    labelMap: z.record(z.string(), z.string()).optional(),
+});
+// ── Series Definition Schema ─────────────────────────────────
+// Visual mapping: "take this measure from DataQuery results and render it."
+export const ChartSeriesDefinitionSchema = z.object({
+    /** Unique ref within this chart */
+    ref: z.string(),
+    /** Display name (legend label). Used as fallback when i18n key is not resolved. */
+    name: z.string(),
+    /**
+     * i18n labelling key for the series name.
+     *
+     * When set, the chart system resolves this key via the i18n service
+     * at render time and uses the result as the legend label and tooltip series name.
+     * Falls back to `name` if the key is not found in the translations.
+     *
+     * Common pattern: `resources.{resource}.fields.{measureRef}.display.label`
+     * to reuse existing resource field labels.
+     */
+    nameKey: z.string().optional(),
+    /** Which measure ref from DataQuery to render */
+    measureRef: z.string(),
+    /** Override chart type for this series (for composed charts) */
+    chartType: z.enum(ChartType).optional(),
+    /** Which Y axis (0 = left, 1 = right) for dual-axis */
+    yAxisIndex: z.number().optional(),
+    /** Visual style */
+    style: ChartSeriesStyleSchema.optional(),
+    /** Show/hide by default (toggleable via legend) */
+    hidden: z.boolean().optional(),
+    /** Split this series into sub-series by a dimension's values (for stacked/grouped) */
+    splitByDimension: z.string().optional(),
+    /** Configuration for split sub-series */
+    splitConfig: ChartSplitConfigSchema.optional(),
+});
+// ── Chart Series Schema (includes runtime fields) ───────────
+// Full series including runtime-only fields stripped from persisted definitions.
+export const ChartSeriesSchema = ChartSeriesDefinitionSchema.extend({
+    /** Runtime data points (not persisted in definitions) */
+    data: z.array(z.record(z.string(), z.unknown())).optional(),
+});
+// ── Chart Input Contract ─────────────────────────────────────
+// Explicit chart inputs replace the old raw filter override seam.
+export var ChartInputValueType;
+(function (ChartInputValueType) {
+    ChartInputValueType["STRING"] = "string";
+    ChartInputValueType["NUMBER"] = "number";
+    ChartInputValueType["BOOLEAN"] = "boolean";
+    ChartInputValueType["STRING_ARRAY"] = "string-array";
+    ChartInputValueType["NUMBER_ARRAY"] = "number-array";
+})(ChartInputValueType || (ChartInputValueType = {}));
+export const ChartInputValueSchema = z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.array(z.string()),
+    z.array(z.number()),
+]);
+export const ChartInputValuesSchema = z.record(z.string(), ChartInputValueSchema);
+export function getChartInputValueTypeSchema(valueType) {
+    switch (valueType) {
+        case ChartInputValueType.STRING:
+            return z.string();
+        case ChartInputValueType.NUMBER:
+            return z.number();
+        case ChartInputValueType.BOOLEAN:
+            return z.boolean();
+        case ChartInputValueType.STRING_ARRAY:
+            return z.array(z.string());
+        case ChartInputValueType.NUMBER_ARRAY:
+            return z.array(z.number());
+    }
+}
+export var ChartInputBindingTargetKind;
+(function (ChartInputBindingTargetKind) {
+    ChartInputBindingTargetKind["FILTER"] = "filter";
+})(ChartInputBindingTargetKind || (ChartInputBindingTargetKind = {}));
+export var ChartInputFilterOperator;
+(function (ChartInputFilterOperator) {
+    ChartInputFilterOperator["EQUALS"] = "equals";
+    ChartInputFilterOperator["IN"] = "in";
+    ChartInputFilterOperator["GREATER_THAN_OR_EQUAL"] = "gte";
+    ChartInputFilterOperator["LESS_THAN_OR_EQUAL"] = "lte";
+})(ChartInputFilterOperator || (ChartInputFilterOperator = {}));
+/**
+ * Declares the only query seam a chart input can influence.
+ *
+ * This intentionally avoids exposing arbitrary query fragments to callers.
+ * The author chooses explicit binding points, and runtime input application can
+ * only write into those declared seams.
+ */
+export const ChartInputBindingSchema = z.object({
+    targetKind: z.enum(ChartInputBindingTargetKind).default(ChartInputBindingTargetKind.FILTER),
+    filterField: z.string().min(1),
+    operator: z.enum(ChartInputFilterOperator).default(ChartInputFilterOperator.EQUALS),
+});
+export const ChartInputDefinitionSchema = z.object({
+    ref: z.string().min(1),
+    valueType: z.enum(ChartInputValueType),
+    required: z.boolean().default(false),
+    description: z.string().optional(),
+    defaultValue: ChartInputValueSchema.optional(),
+    binding: ChartInputBindingSchema,
+}).superRefine((definition, ctx) => {
+    if (definition.defaultValue === undefined) {
+        return;
+    }
+    const parsed = getChartInputValueTypeSchema(definition.valueType).safeParse(definition.defaultValue);
+    if (!parsed.success) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `defaultValue does not match declared chart input valueType "${definition.valueType}".`,
+            path: ['defaultValue'],
+        });
+    }
+});
+/**
+ * Runtime request payload for chart data execution.
+ *
+ * Unknown fields are intentionally stripped by Zod so deprecated raw `filters`
+ * payloads cannot widen queries through this boundary anymore.
+ */
+export const ChartDataRequestBodySchema = z.object({
+    inputs: ChartInputValuesSchema.optional(),
+    contextResourceIdentifiers: z.record(z.string(), z.string()).optional(),
+});
+export function buildChartInputValuesSchema(definitions) {
+    return ChartInputValuesSchema.optional().superRefine((inputValues, ctx) => {
+        const definitionsByRef = new Map(definitions.map((definition) => [definition.ref, definition]));
+        if (!inputValues) {
+            for (const definition of definitions) {
+                if (definition.required && definition.defaultValue === undefined) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        message: `Missing required chart input "${definition.ref}".`,
+                        path: [definition.ref],
+                    });
+                }
+            }
+            return;
+        }
+        for (const [inputRef, value] of Object.entries(inputValues)) {
+            const definition = definitionsByRef.get(inputRef);
+            if (!definition) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: `Unknown chart input "${inputRef}".`,
+                    path: [inputRef],
+                });
+                continue;
+            }
+            const parsed = getChartInputValueTypeSchema(definition.valueType).safeParse(value);
+            if (!parsed.success) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: `Chart input "${inputRef}" does not match declared valueType "${definition.valueType}".`,
+                    path: [inputRef],
+                });
+            }
+        }
+        for (const definition of definitions) {
+            if (definition.required && definition.defaultValue === undefined && inputValues[definition.ref] === undefined) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: `Missing required chart input "${definition.ref}".`,
+                    path: [definition.ref],
+                });
+            }
+        }
+    });
+}
+function isObjectLike(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function compareFilterScalars(left, right) {
+    if ((typeof left === 'number' && typeof right === 'number')
+        || (typeof left === 'string' && typeof right === 'string')) {
+        if (left < right)
+            return -1;
+        if (left > right)
+            return 1;
+        return 0;
+    }
+    return null;
+}
+function cloneFilterValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => cloneFilterValue(item));
+    }
+    if (isObjectLike(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, nestedValue]) => [key, cloneFilterValue(nestedValue)]));
+    }
+    return value;
+}
+function applyFilterBinding(params) {
+    const field = params.binding.filterField;
+    const existingValue = params.filters[field];
+    switch (params.binding.operator) {
+        case ChartInputFilterOperator.EQUALS: {
+            if (existingValue === undefined) {
+                params.filters[field] = params.value;
+                return;
+            }
+            if (Array.isArray(existingValue)) {
+                if (existingValue.includes(params.value)) {
+                    params.filters[field] = params.value;
+                    return;
+                }
+                throw new Error(`Chart input conflicts with authored array filter on "${field}".`);
+            }
+            if (!isObjectLike(existingValue)) {
+                if (existingValue === params.value) {
+                    return;
+                }
+                throw new Error(`Chart input conflicts with authored equality filter on "${field}".`);
+            }
+            const nextFilterValue = { ...existingValue };
+            const existingEquals = nextFilterValue.$eq;
+            if (existingEquals !== undefined && existingEquals !== params.value) {
+                throw new Error(`Chart input conflicts with authored equality filter on "${field}".`);
+            }
+            const existingIn = nextFilterValue.$in;
+            if (Array.isArray(existingIn) && !existingIn.includes(params.value)) {
+                throw new Error(`Chart input conflicts with authored inclusion filter on "${field}".`);
+            }
+            nextFilterValue.$eq = params.value;
+            params.filters[field] = nextFilterValue;
+            return;
+        }
+        case ChartInputFilterOperator.IN: {
+            const inputValues = Array.isArray(params.value) ? params.value : [params.value];
+            if (existingValue === undefined) {
+                params.filters[field] = { $in: inputValues };
+                return;
+            }
+            if (Array.isArray(existingValue)) {
+                const intersection = existingValue.filter((candidate) => inputValues.includes(candidate));
+                if (intersection.length === 0) {
+                    throw new Error(`Chart input conflicts with authored array filter on "${field}".`);
+                }
+                params.filters[field] = { $in: intersection };
+                return;
+            }
+            if (!isObjectLike(existingValue)) {
+                if (inputValues.includes(existingValue)) {
+                    return;
+                }
+                throw new Error(`Chart input conflicts with authored equality filter on "${field}".`);
+            }
+            const nextFilterValue = { ...existingValue };
+            const existingEquals = nextFilterValue.$eq;
+            if (existingEquals !== undefined) {
+                if (inputValues.includes(existingEquals)) {
+                    return;
+                }
+                throw new Error(`Chart input conflicts with authored equality filter on "${field}".`);
+            }
+            const existingIn = nextFilterValue.$in;
+            if (Array.isArray(existingIn)) {
+                const intersection = existingIn.filter((candidate) => inputValues.includes(candidate));
+                if (intersection.length === 0) {
+                    throw new Error(`Chart input conflicts with authored inclusion filter on "${field}".`);
+                }
+                nextFilterValue.$in = intersection;
+                params.filters[field] = nextFilterValue;
+                return;
+            }
+            nextFilterValue.$in = inputValues;
+            params.filters[field] = nextFilterValue;
+            return;
+        }
+        case ChartInputFilterOperator.GREATER_THAN_OR_EQUAL:
+        case ChartInputFilterOperator.LESS_THAN_OR_EQUAL: {
+            const operatorKey = params.binding.operator === ChartInputFilterOperator.GREATER_THAN_OR_EQUAL
+                ? '$gte'
+                : '$lte';
+            if (existingValue === undefined) {
+                params.filters[field] = { [operatorKey]: params.value };
+                return;
+            }
+            if (!isObjectLike(existingValue)) {
+                const comparison = compareFilterScalars(existingValue, params.value);
+                if (comparison === null) {
+                    throw new Error(`Chart input cannot narrow authored scalar filter on "${field}".`);
+                }
+                const satisfiesConstraint = params.binding.operator === ChartInputFilterOperator.GREATER_THAN_OR_EQUAL
+                    ? comparison >= 0
+                    : comparison <= 0;
+                if (!satisfiesConstraint) {
+                    throw new Error(`Chart input conflicts with authored equality filter on "${field}".`);
+                }
+                return;
+            }
+            const nextFilterValue = { ...existingValue };
+            const existingOperatorValue = nextFilterValue[operatorKey];
+            if (existingOperatorValue !== undefined) {
+                const comparison = compareFilterScalars(existingOperatorValue, params.value);
+                if (comparison === null) {
+                    throw new Error(`Chart input cannot combine with authored range filter on "${field}".`);
+                }
+                nextFilterValue[operatorKey] = params.binding.operator === ChartInputFilterOperator.GREATER_THAN_OR_EQUAL
+                    ? (comparison >= 0 ? existingOperatorValue : params.value)
+                    : (comparison <= 0 ? existingOperatorValue : params.value);
+            }
+            else {
+                nextFilterValue[operatorKey] = params.value;
+            }
+            const lowerBound = nextFilterValue.$gte;
+            const upperBound = nextFilterValue.$lte;
+            if (lowerBound !== undefined && upperBound !== undefined) {
+                const comparison = compareFilterScalars(lowerBound, upperBound);
+                if (comparison !== null && comparison > 0) {
+                    throw new Error(`Chart input produces an impossible range filter on "${field}".`);
+                }
+            }
+            params.filters[field] = nextFilterValue;
+            return;
+        }
+    }
+}
+/**
+ * Applies explicit chart inputs to an aggregation query through the authored
+ * chart-input bindings only.
+ *
+ * This intentionally narrows the query through declared filter fields rather
+ * than exposing a raw caller-writable filter seam.
+ */
+export function applyChartInputsToAggregationQuery(params) {
+    const parsedInputs = buildChartInputValuesSchema(params.chartDefinition.inputs ?? []).parse(params.inputs);
+    const effectiveInputs = {
+        ...Object.fromEntries((params.chartDefinition.inputs ?? [])
+            .filter((inputDefinition) => inputDefinition.defaultValue !== undefined)
+            .map((inputDefinition) => [inputDefinition.ref, inputDefinition.defaultValue])),
+        ...(parsedInputs ?? {}),
+    };
+    const query = cloneFilterValue(params.chartDefinition.dataQuery);
+    if (Object.keys(effectiveInputs).length === 0) {
+        return query;
+    }
+    const filters = (query.filters ??= {});
+    const inputDefinitionsByRef = new Map((params.chartDefinition.inputs ?? []).map((inputDefinition) => [inputDefinition.ref, inputDefinition]));
+    for (const [inputRef, inputValue] of Object.entries(effectiveInputs)) {
+        const inputDefinition = inputDefinitionsByRef.get(inputRef);
+        if (!inputDefinition) {
+            continue;
+        }
+        applyFilterBinding({
+            filters,
+            binding: inputDefinition.binding,
+            value: inputValue,
+        });
+    }
+    return query;
+}
+// ── Access Control Schema ────────────────────────────────────
+export const ChartAccessControlSchema = z.object({
+    /** Restrict to specific roles (must be a subset of LIST roles) */
+    roles: z.array(z.string()).optional(),
+});
+// ── Chart Appearance Schema ──────────────────────────────────
+// Per-chart appearance overrides (Layer 2 in the precedence model).
+// These override the theme's ChartStylePreset for this specific chart.
+export const ChartAppearanceSchema = z.object({
+    /** Override color palette for this chart (array of hex color strings) */
+    colorPalette: z.array(z.string()).optional(),
+    /** Override grid padding (partial — only specified sides are overridden) */
+    gridPadding: z.object({
+        top: z.number().optional(),
+        right: z.number().optional(),
+        bottom: z.number().optional(),
+        left: z.number().optional(),
+    }).optional(),
+    /** Show/hide legend (overrides auto-detection) */
+    showLegend: z.boolean().optional(),
+    /** Show/hide tooltip */
+    showTooltip: z.boolean().optional(),
+    /** Enable/disable animation */
+    animated: z.boolean().optional(),
+    /** Background: 'transparent' | 'surface' | hex color */
+    background: z.string().optional(),
+    // ── Title ──────────────────────────────────────────────────
+    /** Chart title configuration */
+    title: z.object({
+        /** Main title text. Supports i18n key via `i18n.titleKey` */
+        text: z.string().optional(),
+        /** Subtitle text */
+        subtext: z.string().optional(),
+        /** Horizontal position. Default: 'left' */
+        left: z.union([z.string(), z.number()]).optional(),
+        /** Vertical position. Default: 'auto' */
+        top: z.union([z.string(), z.number()]).optional(),
+        /** Text alignment. Default: 'auto' */
+        textAlign: z.enum(['auto', 'left', 'center', 'right']).optional(),
+    }).optional(),
+    // ── Animation overrides ────────────────────────────────────
+    /** Animation duration in ms (overrides theme preset for this chart) */
+    animationDuration: z.number().optional(),
+    /** Animation easing function (overrides theme preset for this chart) */
+    animationEasing: z.string().optional(),
+    // ── Legend details ─────────────────────────────────────────
+    /** Detailed legend configuration (beyond show/hide) */
+    legend: z.object({
+        /** Legend orientation. Default: 'horizontal' */
+        orient: z.enum(['horizontal', 'vertical']).optional(),
+        /** Position: top, bottom, left, right, or px/%. Default: bottom:0 */
+        position: z.enum(['top', 'bottom', 'left', 'right']).optional(),
+        /** Legend type. Default: 'scroll' */
+        type: z.enum(['plain', 'scroll']).optional(),
+        /** Max legend items before scrolling. Default: auto */
+        pageSize: z.number().optional(),
+        /** Item gap in px. Default: 10 */
+        itemGap: z.number().optional(),
+    }).optional(),
+    // ── Tooltip details ────────────────────────────────────────
+    /** Detailed tooltip configuration (beyond show/hide) */
+    tooltip: z.object({
+        /** Trigger mode override. Default: auto-detected per chart type */
+        trigger: z.enum(['item', 'axis', 'none']).optional(),
+        /** Confine tooltip to chart container. Default: true */
+        confine: z.boolean().optional(),
+        /** Custom tooltip formatter (ECharts formatter syntax) */
+        formatter: z.string().optional(),
+        /** Axis pointer type. Default: 'line' */
+        axisPointerType: z.enum(['line', 'shadow', 'cross', 'none']).optional(),
+    }).optional(),
+    // ── Toolbox ────────────────────────────────────────────────
+    /** ECharts toolbox configuration (save as image, data view, etc.) */
+    toolbox: z.object({
+        /** Show toolbox. Default: false */
+        show: z.boolean().optional(),
+        /** Save as image feature */
+        saveAsImage: z.boolean().optional(),
+        /** Data view (raw data table) feature */
+        dataView: z.boolean().optional(),
+        /** Restore (reset zoom/filter) feature */
+        restore: z.boolean().optional(),
+        /** Magic type switching (line <-> bar, etc.) */
+        magicType: z.array(z.enum(['line', 'bar', 'stack'])).optional(),
+        /** Toolbox position. Default: right:10, top:10 */
+        right: z.union([z.string(), z.number()]).optional(),
+        top: z.union([z.string(), z.number()]).optional(),
+    }).optional(),
+    // ── Data Zoom ──────────────────────────────────────────────
+    /** Data zoom (slider/inside) for navigating large datasets */
+    dataZoom: z.object({
+        /** Enable data zoom. Default: false */
+        enabled: z.boolean().optional(),
+        /** Zoom type. Default: ['slider'] */
+        type: z.array(z.enum(['slider', 'inside'])).optional(),
+        /** Apply to axis. Default: 'x' */
+        axis: z.enum(['x', 'y', 'both']).optional(),
+        /** Initial start percentage (0-100). Default: 0 */
+        start: z.number().optional(),
+        /** Initial end percentage (0-100). Default: 100 */
+        end: z.number().optional(),
+    }).optional(),
+    // ── Emphasis ───────────────────────────────────────────────
+    /** Global emphasis shadow style (used by pie, heatmap, etc.) */
+    emphasisShadow: z.object({
+        /** Shadow blur radius in px. Default: 10 */
+        blur: z.number().optional(),
+        /** Shadow color. Default: 'rgba(0,0,0,0.2)' */
+        color: z.string().optional(),
+        /** Shadow X offset. Default: 0 */
+        offsetX: z.number().optional(),
+    }).optional(),
+});
+// ── Chart Type Config Schemas ────────────────────────────────
+// Per-family type-specific configuration. Each chart type family
+// gets its own strongly-typed config schema. These override
+// hardcoded builder defaults for chart-type-specific behavior.
+//
+// Every property is optional — builders fall back to their
+// current built-in defaults when not specified.
+/** Line/Area family: LINE, AREA, STACKED_AREA, STEP_LINE */
+export const ChartTypeConfig_LineSchema = z.object({
+    /** Max data points before symbols auto-hide. Default: 30 */
+    symbolVisibilityThreshold: z.number().optional(),
+    /** i18n key for the densified overlay series name suffix. Default: '(filled)' */
+    densifiedOverlayNameKey: z.string().optional(),
+    /** Densified (filled) data overlay styling */
+    densifiedOverlay: z.object({
+        /** Item opacity. Default: 0.4 */
+        itemOpacity: z.number().min(0).max(1).optional(),
+        /** Line opacity. Default: 0.5 */
+        lineOpacity: z.number().min(0).max(1).optional(),
+        /** Line width. Default: 1 */
+        lineWidth: z.number().optional(),
+        /** Area opacity for area charts. Default: 0.1 */
+        areaOpacity: z.number().min(0).max(1).optional(),
+        /** Line type for overlay. Default: 'dashed' */
+        lineType: z.enum(['solid', 'dashed', 'dotted']).optional(),
+        /** Show symbol on overlay series. Default: false */
+        showSymbol: z.boolean().optional(),
+    }).optional(),
+});
+/** Bar family: BAR, HORIZONTAL_BAR, GROUPED_BAR, STACKED_BAR, WATERFALL */
+export const ChartTypeConfig_BarSchema = z.object({
+    /** Gap between bars in the same category (px or %). Default: auto */
+    barGap: z.union([z.number(), z.string()]).optional(),
+    /** Gap between bar categories (px or %). Default: auto */
+    barCategoryGap: z.union([z.number(), z.string()]).optional(),
+    /** Waterfall chart configuration */
+    waterfall: z.object({
+        /** Color for positive (gain) bars. Default: palette[0] */
+        gainColor: z.string().optional(),
+        /** Color for negative (loss) bars. Default: '#ee6666' */
+        lossColor: z.string().optional(),
+        /** Legend label for gain series. Default: 'Increase' */
+        gainLabel: z.string().optional(),
+        /** Legend label for loss series. Default: 'Decrease' */
+        lossLabel: z.string().optional(),
+        /** i18n key for gain label (overrides gainLabel when resolved) */
+        gainLabelKey: z.string().optional(),
+        /** i18n key for loss label (overrides lossLabel when resolved) */
+        lossLabelKey: z.string().optional(),
+    }).optional(),
+});
+/** Pie/Donut family: PIE, DONUT */
+export const ChartTypeConfig_PieSchema = z.object({
+    /** Radius — string ('70%') or tuple (['40%', '70%'] for donut). Default: varies */
+    radius: z.union([z.string(), z.tuple([z.string(), z.string()])]).optional(),
+    /** Start angle in degrees. Default: 90 */
+    startAngle: z.number().optional(),
+    /** Minimum slice angle in degrees (prevents tiny slices). Default: 0 */
+    minAngle: z.number().optional(),
+    /** Rose (nightingale) mode. Disabled by default */
+    roseType: z.enum(['radius', 'area']).optional(),
+    /** Label position. Default: 'outside' */
+    labelPosition: z.enum(['inside', 'outside', 'center']).optional(),
+    /** Label formatter (ECharts formatter syntax). Default: '{b}: {d}%' */
+    labelFormatter: z.string().optional(),
+    /** Show labels on slices. Default: true */
+    showLabel: z.boolean().optional(),
+    /** Center position [x, y] as percentage strings. Default: ['50%', '50%'] */
+    center: z.tuple([z.string(), z.string()]).optional(),
+    /** Border width between slices in px. Default: from preset.series.pieBorderWidth */
+    borderWidth: z.number().optional(),
+    /** Border color between slices. Default: from theme background */
+    borderColor: z.string().optional(),
+    /**
+     * i18n key for the fallback item name pattern when data items lack names.
+     * Default text: 'Item {idx}'. Use i18n to localize.
+     */
+    itemNameFallbackKey: z.string().optional(),
+});
+/** Scatter/Bubble family: SCATTER, BUBBLE */
+export const ChartTypeConfig_ScatterSchema = z.object({
+    /** Bubble size range [min, max] in px. Default: [4, 60] */
+    bubbleSizeRange: z.tuple([z.number(), z.number()]).optional(),
+    /** Symbol shape. Default: 'circle' */
+    symbolShape: z.enum(['circle', 'rect', 'roundRect', 'triangle', 'diamond', 'pin', 'arrow']).optional(),
+    /** Show regression line. Default: false */
+    showRegressionLine: z.boolean().optional(),
+});
+/** Gauge: GAUGE */
+export const ChartTypeConfig_GaugeSchema = z.object({
+    /** Minimum value. Default: 0 */
+    min: z.number().optional(),
+    /** Maximum value. Default: 100 */
+    max: z.number().optional(),
+    /** Number of gauge segments. Default: 10 */
+    splitNumber: z.number().optional(),
+    /** Show progress arc. Default: true */
+    showProgress: z.boolean().optional(),
+    /** Detail value formatter. Default: '{value}' */
+    detailFormatter: z.string().optional(),
+    /** Detail font size. Default: 20 */
+    detailFontSize: z.number().optional(),
+    /** Gauge radius (string %). Default: '75%' */
+    radius: z.string().optional(),
+    /** Start angle in degrees. Default: 225 */
+    startAngle: z.number().optional(),
+    /** End angle in degrees. Default: -45 */
+    endAngle: z.number().optional(),
+    /** Pointer style. Default: auto */
+    pointer: z.object({
+        /** Show pointer. Default: true */
+        show: z.boolean().optional(),
+        /** Pointer length (% of radius). Default: '60%' */
+        length: z.string().optional(),
+        /** Pointer width in px. Default: 6 */
+        width: z.number().optional(),
+    }).optional(),
+    /** Axis line width in px. Default: 30 */
+    axisLineWidth: z.number().optional(),
+    /** Color segments [[proportion, color], ...] for axis line */
+    axisLineColors: z.array(z.tuple([z.number(), z.string()])).optional(),
+});
+/** Funnel: FUNNEL */
+export const ChartTypeConfig_FunnelSchema = z.object({
+    /** Sort direction. Default: 'descending' */
+    sort: z.enum(['ascending', 'descending', 'none']).optional(),
+    /** Gap between funnel items in px. Default: 2 */
+    gap: z.number().optional(),
+    /** Label position. Default: 'inside' */
+    labelPosition: z.enum(['inside', 'outside', 'left', 'right', 'leftTop', 'rightTop']).optional(),
+    /** Horizontal alignment. Default: 'center' */
+    funnelAlign: z.enum(['left', 'center', 'right']).optional(),
+    /** Show label. Default: true */
+    showLabel: z.boolean().optional(),
+    /** Left position (string %). Default: '10%' */
+    left: z.string().optional(),
+    /** Width (string %). Default: '80%' */
+    width: z.string().optional(),
+    /** Min/max size for the narrowest/widest part. Default: '0%' / '100%' */
+    minSize: z.string().optional(),
+    maxSize: z.string().optional(),
+});
+/** Radar: RADAR */
+export const ChartTypeConfig_RadarSchema = z.object({
+    /** Radar shape. Default: 'polygon' */
+    shape: z.enum(['polygon', 'circle']).optional(),
+    /** Area fill opacity. Default: 0.2 */
+    areaOpacity: z.number().min(0).max(1).optional(),
+    /** Radar center position [x, y]. Default: ['50%', '50%'] */
+    center: z.tuple([z.string(), z.string()]).optional(),
+    /** Radar radius (string %). Default: '75%' */
+    radius: z.string().optional(),
+    /** Start angle in degrees. Default: 90 */
+    startAngle: z.number().optional(),
+    /** Show split area (alternating region fills). Default: false */
+    showSplitArea: z.boolean().optional(),
+    /** Name gap (distance between indicator name and axis). Default: 15 */
+    nameGap: z.number().optional(),
+});
+/** Heatmap: HEATMAP */
+export const ChartTypeConfig_HeatmapSchema = z.object({
+    /** Show cell value labels. Default: true */
+    showLabel: z.boolean().optional(),
+    /** Visual map orientation. Default: 'horizontal' */
+    visualMapOrient: z.enum(['horizontal', 'vertical']).optional(),
+    /** Visual map position. Default: 'bottom' */
+    visualMapPosition: z.enum(['top', 'bottom', 'left', 'right']).optional(),
+    /** Visual map calculable (interactive dragging). Default: true */
+    visualMapCalculable: z.boolean().optional(),
+    /** Min value override for visual map range. Default: auto-detected from data */
+    visualMapMin: z.number().optional(),
+    /** Max value override for visual map range. Default: auto-detected from data */
+    visualMapMax: z.number().optional(),
+    /** In-range color gradient stops. Default: from theme palette */
+    visualMapInRange: z.array(z.string()).optional(),
+    /** Show axis split area (alternating background). Default: true */
+    showSplitArea: z.boolean().optional(),
+});
+/** Sankey: SANKEY */
+export const ChartTypeConfig_SankeySchema = z.object({
+    /** Emphasis focus mode. Default: 'adjacency' */
+    emphasisFocus: z.enum(['adjacency', 'self', 'none']).optional(),
+    /** Node width in px. Default: 20 */
+    nodeWidth: z.number().optional(),
+    /** Gap between nodes in px. Default: 8 */
+    nodeGap: z.number().optional(),
+    /** Orient (layout direction). Default: 'horizontal' */
+    orient: z.enum(['horizontal', 'vertical']).optional(),
+    /** Draggable nodes. Default: true */
+    draggable: z.boolean().optional(),
+    /** Label position. Default: 'right' */
+    labelPosition: z.enum(['left', 'right', 'top', 'bottom']).optional(),
+});
+/** Parallel: PARALLEL */
+export const ChartTypeConfig_ParallelSchema = z.object({
+    /** Line width. Default: 2 */
+    lineWidth: z.number().optional(),
+    /** Line opacity. Default: 0.6 */
+    lineOpacity: z.number().min(0).max(1).optional(),
+    /** Emphasis line width. Default: 4 */
+    emphasisLineWidth: z.number().optional(),
+    /** Emphasis opacity. Default: 1 */
+    emphasisOpacity: z.number().min(0).max(1).optional(),
+    /** Layout margins (%) */
+    layoutMargins: z.object({
+        left: z.string().optional(),
+        right: z.string().optional(),
+        top: z.string().optional(),
+        bottom: z.string().optional(),
+    }).optional(),
+});
+/** Hierarchical family: SUNBURST, TREEMAP */
+export const ChartTypeConfig_HierarchicalSchema = z.object({
+    /** Sunburst radius range (e.g., ['15%', '90%']). Default: ['15%', '90%'] */
+    sunburstRadius: z.tuple([z.string(), z.string()]).optional(),
+    /** Sunburst emphasis focus. Default: 'ancestor' */
+    sunburstEmphasisFocus: z.enum(['ancestor', 'descendant', 'self', 'none']).optional(),
+    /** Sunburst level label configuration (overrides auto-computed per-level styles) */
+    sunburstLevels: z.object({
+        /** Level 1 (innermost ring) label rotation. Default: 'tangential' */
+        level1LabelRotate: z.enum(['tangential', 'radial', 'none']).optional(),
+        /** Level 2 label alignment. Default: 'right' */
+        level2LabelAlign: z.enum(['left', 'right', 'center']).optional(),
+        /** Level 3 (outermost ring) label position. Default: 'outside' */
+        level3LabelPosition: z.enum(['inside', 'outside']).optional(),
+        /** Level 3 label padding. Default: 3 */
+        level3LabelPadding: z.number().optional(),
+    }).optional(),
+    /** Treemap leaf depth (drill-down levels). Default: auto */
+    treemapLeafDepth: z.number().optional(),
+    /** Treemap minimum visible area in px². Default: 300 */
+    treemapVisibleMin: z.number().optional(),
+    /** Show treemap breadcrumb. Default: true */
+    showBreadcrumb: z.boolean().optional(),
+    /** Label formatter for treemap. Default: '{b}' */
+    treemapLabelFormatter: z.string().optional(),
+    /** Show treemap labels. Default: true */
+    treemapShowLabel: z.boolean().optional(),
+    /** Treemap upper label (level header) height in px. Default: 30 */
+    treemapUpperLabelHeight: z.number().optional(),
+    /** Show treemap upper labels. Default: true */
+    treemapShowUpperLabel: z.boolean().optional(),
+});
+/** Boxplot: BOXPLOT */
+export const ChartTypeConfig_BoxplotSchema = z.object({
+    /** Boundary gap on category axis. Default: true */
+    boundaryGap: z.boolean().optional(),
+    /** Box width (px or string %). Default: auto */
+    boxWidth: z.union([z.number(), z.string()]).optional(),
+    /** Show outlier points. Default: true */
+    showOutliers: z.boolean().optional(),
+});
+// ── Chart Type Config Union ──────────────────────────────────
+/**
+ * Union of all chart-type-specific config schemas.
+ *
+ * Each member uses `z.looseObject()` so that Zod doesn't strip keys
+ * belonging to other families when the union tries members in order
+ * (all properties are optional → the first schema would always match
+ * and silently drop unknown keys without loose parsing).
+ */
+export const ChartTypeConfigSchema = z.union([
+    z.looseObject(ChartTypeConfig_LineSchema.shape),
+    z.looseObject(ChartTypeConfig_BarSchema.shape),
+    z.looseObject(ChartTypeConfig_PieSchema.shape),
+    z.looseObject(ChartTypeConfig_ScatterSchema.shape),
+    z.looseObject(ChartTypeConfig_GaugeSchema.shape),
+    z.looseObject(ChartTypeConfig_FunnelSchema.shape),
+    z.looseObject(ChartTypeConfig_RadarSchema.shape),
+    z.looseObject(ChartTypeConfig_HeatmapSchema.shape),
+    z.looseObject(ChartTypeConfig_SankeySchema.shape),
+    z.looseObject(ChartTypeConfig_ParallelSchema.shape),
+    z.looseObject(ChartTypeConfig_HierarchicalSchema.shape),
+    z.looseObject(ChartTypeConfig_BoxplotSchema.shape),
+]);
+function getChartTypeConfigSchemaForChartType(chartType) {
+    switch (chartType) {
+        case ChartType.LINE:
+        case ChartType.AREA:
+        case ChartType.STACKED_AREA:
+        case ChartType.STEP_LINE:
+            return ChartTypeConfig_LineSchema.strict();
+        case ChartType.BAR:
+        case ChartType.HORIZONTAL_BAR:
+        case ChartType.GROUPED_BAR:
+        case ChartType.STACKED_BAR:
+        case ChartType.WATERFALL:
+            return ChartTypeConfig_BarSchema.strict();
+        case ChartType.PIE:
+        case ChartType.DONUT:
+            return ChartTypeConfig_PieSchema.strict();
+        case ChartType.SCATTER:
+        case ChartType.BUBBLE:
+            return ChartTypeConfig_ScatterSchema.strict();
+        case ChartType.GAUGE:
+            return ChartTypeConfig_GaugeSchema.strict();
+        case ChartType.FUNNEL:
+            return ChartTypeConfig_FunnelSchema.strict();
+        case ChartType.RADAR:
+            return ChartTypeConfig_RadarSchema.strict();
+        case ChartType.HEATMAP:
+            return ChartTypeConfig_HeatmapSchema.strict();
+        case ChartType.SANKEY:
+            return ChartTypeConfig_SankeySchema.strict();
+        case ChartType.PARALLEL:
+            return ChartTypeConfig_ParallelSchema.strict();
+        case ChartType.SUNBURST:
+        case ChartType.TREEMAP:
+            return ChartTypeConfig_HierarchicalSchema.strict();
+        case ChartType.BOXPLOT:
+            return ChartTypeConfig_BoxplotSchema.strict();
+        case ChartType.COMPOSED:
+            return z.strictObject({});
+    }
+}
+// ── Chart View Options Schema ────────────────────────────────
+// Visual configuration options for chart rendering.
+export const ChartViewOptionsSchema = z.object({
+    type: z.enum(ChartType).optional(),
+    title: z.string().optional(),
+    subtitle: z.string().optional(),
+    showLegend: z.boolean().optional(),
+    showTooltip: z.boolean().optional(),
+    animated: z.boolean().optional(),
+    chartTypeConfig: ChartTypeConfigSchema.optional(),
+});
+// ── Chart Definition Schema ──────────────────────────────────
+// The shared chart definition: identity + data query + visual encoding.
+// View wiring (scope, addressability, launcher) is added by ChartViewDefinition in saas-frontend-lib.
+export const ChartDefinitionSchema = z.object({
+    /** Unique chart reference (used for registry lookup and the backend data endpoint `/charts/:chartRef/data`) */
+    ref: z.string().min(1),
+    /** Default chart type (series can override) */
+    chartType: z.enum(ChartType),
+    /** Data query specification (aggregation engine) */
+    dataQuery: AggregationQuerySchema,
+    /** Chart series — visual mapping from data query results to rendered elements */
+    series: z.array(ChartSeriesDefinitionSchema),
+    /**
+     * Explicit runtime inputs the chart accepts.
+     *
+     * These definitions declare the public caller contract and the narrow query
+     * binding points each input may affect.
+     */
+    inputs: z.array(ChartInputDefinitionSchema).optional(),
+    /** Access control (narrows LIST roles) */
+    accessControl: ChartAccessControlSchema.optional(),
+    /** Canonical auto-refresh interval in ms for frontend polling */
+    refreshInterval: z.number().positive().optional(),
+    /** Required features — gates access via feature availability policy */
+    requiredFeatures: RequiredFeaturesConfigSchema.optional(),
+    /** Per-chart appearance overrides (takes precedence over theme's ChartStylePreset) */
+    appearance: ChartAppearanceSchema.optional(),
+    /** Chart-type-specific configuration (typed per chart family) */
+    chartTypeConfig: ChartTypeConfigSchema.optional(),
+    /**
+     * i18n labelling key map for chart-level text.
+     *
+     * Each key maps a chart text slot to an i18n translation key.
+     * When the key resolves to a translated string, it replaces the
+     * hardcoded default. Falls back to built-in text when unresolved.
+     */
+    i18n: z.object({
+        /** i18n key for chart title text */
+        titleKey: z.string().optional(),
+        /** i18n key for chart subtitle text */
+        subtitleKey: z.string().optional(),
+        /** i18n key for the X axis label */
+        xAxisLabelKey: z.string().optional(),
+        /** i18n key for the Y axis label */
+        yAxisLabelKey: z.string().optional(),
+        /** i18n key for the secondary Y axis label (dual-axis charts) */
+        yAxisSecondaryLabelKey: z.string().optional(),
+        /** i18n key for the tooltip title pattern */
+        tooltipTitleKey: z.string().optional(),
+        /** i18n key for the empty state message */
+        emptyStateKey: z.string().optional(),
+        /**
+         * i18n keys for split dimension values.
+         * Maps raw split values to i18n keys for translation.
+         * Falls back to splitConfig.labelMap, then raw value.
+         */
+        splitValueKeys: z.record(z.string(), z.string()).optional(),
+    }).optional(),
+}).superRefine((definition, ctx) => {
+    if (definition.chartTypeConfig === undefined) {
+        return;
+    }
+    const chartTypeConfigSchema = getChartTypeConfigSchemaForChartType(definition.chartType);
+    const parsedChartTypeConfig = chartTypeConfigSchema.safeParse(definition.chartTypeConfig);
+    if (parsedChartTypeConfig.success) {
+        return;
+    }
+    ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `chartTypeConfig contains invalid options for chartType "${definition.chartType}".`,
+        path: ['chartTypeConfig'],
+    });
+});
+//# sourceMappingURL=chart-definition.shared.schemas.js.map