@praxisui/charts 8.0.0-beta.11 → 8.0.0-beta.12

package/README.md

@@ -378,6 +378,39 @@ This first published version is focused on the core runtime:
 - declarative `selectionChange` and `crossFilter` actions emitted from selected chart points
 - `distinct-count` aggregation mapped to canonical `praxis.stats` `DISTINCT_COUNT`
 - host-owned remote data resolution through `remoteDataResolver`
+- executable agentic authoring manifest for `praxis-chart`, exported as `PRAXIS_CHARTS_AUTHORING_MANIFEST`
+
+## Agentic Authoring Contract
+
+`@praxisui/charts` publishes a component-level authoring manifest for `praxis-chart`.
+The manifest is an executable backend/tooling contract for canonical
+`PraxisXUiChartContract` documents, not prompt-routing documentation.
+
+The governed authoring targets are:
+
+- `chartType`
+- `series`
+- `axis`
+- `dataBinding`
+- `queryContext`
+- `crossFilter`
+- `drilldown`
+- `selection`
+- `legend`
+- `tooltip`
+
+Remote resource and field binding must come from governed API metadata,
+`availableResources` and `availableFields`. Cross-filter, drilldown and
+selection authoring persists structured `events.*` actions instead of command
+strings or raw prompt examples. The visual editor remains the canonical
+round-trip surface for this document: open, edit, apply/save, reset and reopen
+must preserve the same `x-ui.chart` shape consumed by the runtime.
+
+Each manifest operation declares its own editable target, resolver,
+ambiguity policy, preconditions, validators, affected paths, effects and
+`submissionImpact`. Chart document, type, series and axis changes are
+`config-only`; remote data binding, query context and event mappings
+`affect-remote-binding`; legend and tooltip changes are `visual-only`.
 
 ## Current Non-Goals
 

package/fesm2022/praxisui-charts.mjs

@@ -6119,6 +6119,375 @@ var praxisChartConfigEditor = /*#__PURE__*/Object.freeze({
     PraxisChartConfigEditor: PraxisChartConfigEditor
 });
 
+const chartDocumentSchema = {
+    type: 'object',
+    required: ['version', 'kind', 'source'],
+    properties: {
+        version: { const: '0.1.0' },
+        kind: { enum: ['bar', 'combo', 'horizontal-bar', 'line', 'pie', 'donut', 'area', 'stacked-bar', 'stacked-area', 'scatter'] },
+        chartId: { type: 'string' },
+        title: { oneOf: [{ type: 'string' }, { type: 'object' }] },
+        subtitle: { oneOf: [{ type: 'string' }, { type: 'object' }] },
+        source: {
+            type: 'object',
+            required: ['kind'],
+            properties: {
+                kind: { enum: ['praxis.stats', 'derived'] },
+                resource: { type: 'string' },
+                operation: { enum: ['group-by', 'timeseries', 'distribution'] },
+                options: { type: 'object' },
+            },
+        },
+        dimensions: { type: 'array', items: { type: 'object' } },
+        metrics: { type: 'array', items: { type: 'object' } },
+        events: { type: 'object' },
+    },
+};
+const PRAXIS_CHARTS_AUTHORING_MANIFEST = {
+    schemaVersion: '1.0.0',
+    componentId: 'praxis-chart',
+    ownerPackage: '@praxisui/charts',
+    configSchemaId: 'PraxisXUiChartContract',
+    manifestVersion: '1.0.0',
+    runtimeInputs: [
+        { name: 'chartDocument', type: 'PraxisXUiChartContract | null', description: 'Canonical x-ui.chart document used as the authoring source of truth.' },
+        { name: 'config', type: 'PraxisChartConfig', description: 'Runtime chart configuration mapped from or supplied beside the canonical chart document.' },
+        { name: 'queryContext', type: 'PraxisChartQueryContext | null', description: 'Declarative query context merged into remote datasource requests.' },
+        { name: 'remoteDataResolver', type: 'PraxisChartRemoteDataResolver | null', description: 'Host-governed remote row resolver for integrations outside the default praxis.stats client.' },
+        { name: 'availableResources', type: 'ChartEditorResourceOption[]', description: 'Governed remote resource catalog exposed to the config editor.' },
+        { name: 'availableFields', type: 'ChartEditorFieldOption[]', description: 'Governed semantic field catalog exposed to the config editor.' },
+        { name: 'availableTargets', type: 'ChartEditorTargetOption[]', description: 'Governed widget or route targets exposed to chart event authoring.' },
+    ],
+    editableTargets: [
+        { kind: 'chartType', resolver: 'x-ui-chart-kind', description: 'Canonical `kind` field in PraxisXUiChartContract.' },
+        { kind: 'series', resolver: 'x-ui-chart-metric-by-field', description: 'Metric-backed series definition in `metrics[]`, keyed by field.' },
+        { kind: 'axis', resolver: 'x-ui-chart-dimension-or-metric-axis', description: 'Dimension role, metric axis and chart orientation semantics.' },
+        { kind: 'dataBinding', resolver: 'x-ui-chart-source-and-field-catalog', description: 'Source, dimensions, metrics and resource/field bindings.' },
+        { kind: 'queryContext', resolver: 'praxis-chart-query-context', description: 'Runtime queryContext contract for filters, sort, limit and page.' },
+        { kind: 'crossFilter', resolver: 'x-ui-chart-events-cross-filter', description: 'Cross-filter event mapping emitted as structured query-context filters.' },
+        { kind: 'drilldown', resolver: 'x-ui-chart-events-drill-down', description: 'Drilldown event mapping and governed target.' },
+        { kind: 'selection', resolver: 'x-ui-chart-events-selection-change', description: 'Selection event enablement and mapping semantics.' },
+        { kind: 'legend', resolver: 'x-ui-chart-legend-feature', description: 'Legend visibility through boolean or toggleable feature object.' },
+        { kind: 'tooltip', resolver: 'x-ui-chart-tooltip-feature', description: 'Tooltip visibility through boolean or toggleable feature object.' },
+    ],
+    operations: [
+        {
+            operationId: 'chart.document.set',
+            title: 'Set chart document',
+            scope: 'global',
+            targetKind: 'dataBinding',
+            target: { kind: 'dataBinding', resolver: 'x-ui-chart-document-root', ambiguityPolicy: 'fail', required: false },
+            inputSchema: chartDocumentSchema,
+            effects: [{ kind: 'set-value', path: 'chartDocument' }],
+            destructive: false,
+            requiresConfirmation: false,
+            validators: ['chart-document-shape', 'chart-version-supported', 'chart-type-series-axis-compatible', 'editor-runtime-round-trip'],
+            affectedPaths: ['chartDocument'],
+            submissionImpact: 'config-only',
+            preconditions: ['config-initialized'],
+        },
+        {
+            operationId: 'chart.type.set',
+            title: 'Set chart type',
+            scope: 'global',
+            targetKind: 'chartType',
+            target: { kind: 'chartType', resolver: 'x-ui-chart-kind', ambiguityPolicy: 'fail', required: false },
+            inputSchema: { type: 'object', required: ['kind'], properties: { kind: { enum: ['bar', 'combo', 'horizontal-bar', 'line', 'pie', 'donut', 'area', 'stacked-bar', 'stacked-area', 'scatter'] }, orientation: { enum: ['vertical', 'horizontal'] } } },
+            effects: [{ kind: 'merge-object', path: 'chartDocument' }],
+            destructive: false,
+            requiresConfirmation: false,
+            validators: ['chart-type-supported', 'chart-type-series-axis-compatible', 'pie-single-metric', 'combo-minimum-series', 'editor-runtime-round-trip'],
+            affectedPaths: ['chartDocument.kind', 'chartDocument.orientation', 'chartDocument.metrics[]', 'chartDocument.dimensions[]'],
+            submissionImpact: 'config-only',
+            preconditions: ['config-initialized'],
+        },
+        {
+            operationId: 'series.add',
+            title: 'Add chart series',
+            scope: 'dataBinding',
+            targetKind: 'series',
+            target: { kind: 'series', resolver: 'x-ui-chart-metric-by-field', ambiguityPolicy: 'fail', required: false },
+            inputSchema: {
+                type: 'object',
+                required: ['field'],
+                properties: {
+                    field: { type: 'string' },
+                    label: { oneOf: [{ type: 'string' }, { type: 'object' }] },
+                    aggregation: { enum: ['sum', 'avg', 'min', 'max', 'count', 'distinct-count'] },
+                    seriesKind: { enum: ['bar', 'line', 'area'] },
+                    axis: { enum: ['primary', 'secondary'] },
+                    color: { type: 'string' },
+                    format: { type: 'string' },
+                    afterField: { type: 'string' },
+                },
+            },
+            effects: [{ kind: 'compile-domain-patch', handler: 'chart-series-add', handlerContract: {
+                        reads: ['chartDocument.kind', 'chartDocument.metrics[]', 'availableFields[]'],
+                        writes: ['chartDocument.metrics[]'],
+                        identityKeys: ['chartDocument.metrics[].field'],
+                        inputSchema: {
+                            type: 'object',
+                            required: ['field'],
+                            properties: {
+                                field: { type: 'string' },
+                                label: { oneOf: [{ type: 'string' }, { type: 'object' }] },
+                                aggregation: { enum: ['sum', 'avg', 'min', 'max', 'count', 'distinct-count'] },
+                                seriesKind: { enum: ['bar', 'line', 'area'] },
+                                axis: { enum: ['primary', 'secondary'] },
+                                color: { type: 'string' },
+                                format: { type: 'string' },
+                                afterField: { type: 'string' },
+                            },
+                        },
+                        failureModes: ['field-not-in-catalog', 'duplicate-series-field', 'aggregation-not-supported', 'chart-type-series-incompatible'],
+                        description: 'Adds a metric-backed series by semantic field, validating it against availableFields and chart kind compatibility before patching metrics[].',
+                    } }],
+            destructive: false,
+            requiresConfirmation: false,
+            validators: ['series-field-exists', 'series-field-aggregable', 'series-id-unique', 'chart-type-series-axis-compatible', 'editor-runtime-round-trip'],
+            affectedPaths: ['chartDocument.metrics[]'],
+            submissionImpact: 'config-only',
+            preconditions: ['config-initialized'],
+        },
+        {
+            operationId: 'series.remove',
+            title: 'Remove chart series',
+            scope: 'dataBinding',
+            targetKind: 'series',
+            target: { kind: 'series', resolver: 'x-ui-chart-metric-by-field', ambiguityPolicy: 'fail', required: true },
+            inputSchema: { type: 'object', required: ['field'], properties: { field: { type: 'string' }, replacementField: { type: 'string' } } },
+            effects: [{ kind: 'remove-by-key', path: 'chartDocument.metrics[]', key: 'field' }],
+            destructive: true,
+            requiresConfirmation: true,
+            validators: ['series-exists', 'destructive-series-removal-confirmed', 'chart-keeps-required-metric', 'editor-runtime-round-trip'],
+            affectedPaths: ['chartDocument.metrics[]'],
+            submissionImpact: 'config-only',
+            preconditions: ['config-initialized', 'target-series-exists', 'confirmation-collected'],
+        },
+        {
+            operationId: 'axis.configure',
+            title: 'Configure chart axis',
+            scope: 'dataBinding',
+            targetKind: 'axis',
+            target: { kind: 'axis', resolver: 'x-ui-chart-dimension-or-metric-axis', ambiguityPolicy: 'fail', required: true },
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    dimensionField: { type: 'string' },
+                    dimensionRole: { enum: ['category', 'series', 'segment', 'time', 'value'] },
+                    metricField: { type: 'string' },
+                    metricAxis: { enum: ['primary', 'secondary'] },
+                    orientation: { enum: ['vertical', 'horizontal'] },
+                },
+            },
+            effects: [{ kind: 'compile-domain-patch', handler: 'chart-axis-configure', handlerContract: {
+                        reads: ['chartDocument.kind', 'chartDocument.dimensions[]', 'chartDocument.metrics[]', 'availableFields[]'],
+                        writes: ['chartDocument.dimensions[]', 'chartDocument.metrics[]', 'chartDocument.orientation'],
+                        identityKeys: ['chartDocument.dimensions[].field', 'chartDocument.metrics[].field'],
+                        inputSchema: { type: 'object', properties: { dimensionField: { type: 'string' }, dimensionRole: { enum: ['category', 'series', 'segment', 'time', 'value'] }, metricField: { type: 'string' }, metricAxis: { enum: ['primary', 'secondary'] }, orientation: { enum: ['vertical', 'horizontal'] } } },
+                        failureModes: ['field-not-in-catalog', 'secondary-axis-non-combo', 'missing-required-dimension', 'axis-role-incompatible'],
+                        description: 'Configures dimensions and metric axes using semantic fields, preserving combo-only secondary axis constraints.',
+                    } }],
+            destructive: false,
+            requiresConfirmation: false,
+            validators: ['axis-field-exists', 'secondary-axis-combo-only', 'cartesian-dimension-required', 'editor-runtime-round-trip'],
+            affectedPaths: ['chartDocument.dimensions[]', 'chartDocument.metrics[].axis', 'chartDocument.orientation'],
+            submissionImpact: 'config-only',
+            preconditions: ['config-initialized'],
+        },
+        {
+            operationId: 'data.resource.bind',
+            title: 'Bind chart data resource',
+            scope: 'dataBinding',
+            targetKind: 'dataBinding',
+            target: { kind: 'dataBinding', resolver: 'x-ui-chart-source-and-field-catalog', ambiguityPolicy: 'fail', required: false },
+            inputSchema: {
+                type: 'object',
+                required: ['sourceKind'],
+                properties: {
+                    sourceKind: { enum: ['praxis.stats', 'derived'] },
+                    resource: { type: 'string' },
+                    operation: { enum: ['group-by', 'timeseries', 'distribution'] },
+                    dimensions: { type: 'array', items: { type: 'object', required: ['field'], properties: { field: { type: 'string' }, role: { type: 'string' } } } },
+                    metrics: { type: 'array', items: { type: 'object', required: ['field'], properties: { field: { type: 'string' }, label: { oneOf: [{ type: 'string' }, { type: 'object' }] }, aggregation: { enum: ['sum', 'avg', 'min', 'max', 'count', 'distinct-count'] }, seriesKind: { enum: ['bar', 'line', 'area'] }, axis: { enum: ['primary', 'secondary'] }, color: { type: 'string' }, format: { type: 'string' }, afterField: { type: 'string' } } } },
+                },
+            },
+            effects: [{ kind: 'compile-domain-patch', handler: 'chart-data-resource-bind', handlerContract: {
+                        reads: ['availableResources[]', 'availableFields[]', 'chartDocument.source', 'chartDocument.dimensions[]', 'chartDocument.metrics[]'],
+                        writes: ['chartDocument.source', 'chartDocument.dimensions[]', 'chartDocument.metrics[]'],
+                        identityKeys: ['availableResources[].path', 'availableResources[].id', 'availableFields[].field'],
+                        inputSchema: { type: 'object', required: ['sourceKind'], properties: { sourceKind: { enum: ['praxis.stats', 'derived'] }, resource: { type: 'string' }, operation: { enum: ['group-by', 'timeseries', 'distribution'] }, dimensions: { type: 'array' }, metrics: { type: 'array' } } },
+                        failureModes: ['resource-not-in-api-metadata', 'field-not-in-schema', 'stats-operation-not-supported', 'remote-binding-incomplete'],
+                        description: 'Binds a derived or praxis.stats source using the governed resource and field catalogs instead of free-form prompt examples.',
+                    } }],
+            destructive: false,
+            requiresConfirmation: false,
+            validators: ['remote-resource-in-api-metadata', 'bound-fields-exist', 'stats-operation-supported', 'editor-runtime-round-trip'],
+            affectedPaths: ['chartDocument.source', 'chartDocument.dimensions[]', 'chartDocument.metrics[]'],
+            submissionImpact: 'affects-remote-binding',
+            preconditions: ['config-initialized'],
+        },
+        {
+            operationId: 'queryContext.set',
+            title: 'Set chart query context',
+            scope: 'dataBinding',
+            targetKind: 'queryContext',
+            target: { kind: 'queryContext', resolver: 'praxis-chart-query-context', ambiguityPolicy: 'fail', required: false },
+            inputSchema: { type: 'object', properties: { filters: { type: 'object' }, sort: { type: 'array', items: { type: 'string' } }, limit: { type: 'number' }, page: { type: 'object' }, meta: { type: 'object' } } },
+            effects: [{ kind: 'set-value', path: 'queryContext' }],
+            destructive: false,
+            requiresConfirmation: false,
+            validators: ['query-context-structured', 'query-context-fields-exist', 'query-context-safe-values', 'editor-runtime-round-trip'],
+            affectedPaths: ['queryContext'],
+            submissionImpact: 'config-only',
+            preconditions: ['config-initialized'],
+        },
+        {
+            operationId: 'crossFilter.configure',
+            title: 'Configure chart cross-filter',
+            scope: 'eventMapping',
+            targetKind: 'crossFilter',
+            target: { kind: 'crossFilter', resolver: 'x-ui-chart-events-cross-filter', ambiguityPolicy: 'fail', required: false },
+            inputSchema: { type: 'object', required: ['event', 'action'], properties: { event: { enum: ['pointClick', 'selectionChange', 'drillDown', 'crossFilter'] }, action: { enum: ['filter-widget', 'open-detail', 'navigate', 'update-context', 'emit'] }, target: { type: 'string' }, mapping: { type: 'object', additionalProperties: { type: 'string' } } } },
+            effects: [{ kind: 'compile-domain-patch', handler: 'chart-event-cross-filter-configure', handlerContract: {
+                        reads: ['chartDocument.events.crossFilter', 'chartDocument.dimensions[]', 'availableTargets[]'],
+                        writes: ['chartDocument.events.crossFilter'],
+                        identityKeys: ['availableTargets[].id'],
+                        inputSchema: { type: 'object', required: ['event', 'action'], properties: { event: { enum: ['pointClick', 'selectionChange', 'drillDown', 'crossFilter'] }, action: { enum: ['filter-widget', 'open-detail', 'navigate', 'update-context', 'emit'] }, target: { type: 'string' }, mapping: { type: 'object', additionalProperties: { type: 'string' } } } },
+                        failureModes: ['target-not-in-catalog', 'mapping-source-field-missing', 'mapping-target-invalid', 'unsafe-event-action'],
+                        description: 'Configures crossFilter as a structured event action that emits safe query-context filters to a governed target.',
+                    } }],
+            destructive: false,
+            requiresConfirmation: false,
+            validators: ['cross-filter-output-structured', 'event-target-governed', 'event-mapping-fields-exist', 'editor-runtime-round-trip'],
+            affectedPaths: ['chartDocument.events.crossFilter'],
+            submissionImpact: 'config-only',
+            preconditions: ['config-initialized'],
+        },
+        {
+            operationId: 'drilldown.configure',
+            title: 'Configure chart drilldown',
+            scope: 'eventMapping',
+            targetKind: 'drilldown',
+            target: { kind: 'drilldown', resolver: 'x-ui-chart-events-drill-down', ambiguityPolicy: 'fail', required: false },
+            inputSchema: { type: 'object', required: ['event', 'action'], properties: { event: { enum: ['pointClick', 'selectionChange', 'drillDown', 'crossFilter'] }, action: { enum: ['filter-widget', 'open-detail', 'navigate', 'update-context', 'emit'] }, target: { type: 'string' }, mapping: { type: 'object', additionalProperties: { type: 'string' } } } },
+            effects: [{ kind: 'compile-domain-patch', handler: 'chart-event-drilldown-configure', handlerContract: {
+                        reads: ['chartDocument.events.drillDown', 'chartDocument.dimensions[]', 'availableTargets[]'],
+                        writes: ['chartDocument.events.drillDown'],
+                        identityKeys: ['availableTargets[].id'],
+                        inputSchema: { type: 'object', required: ['event', 'action'], properties: { event: { enum: ['pointClick', 'selectionChange', 'drillDown', 'crossFilter'] }, action: { enum: ['filter-widget', 'open-detail', 'navigate', 'update-context', 'emit'] }, target: { type: 'string' }, mapping: { type: 'object', additionalProperties: { type: 'string' } } } },
+                        failureModes: ['target-not-in-catalog', 'mapping-source-field-missing', 'drilldown-target-invalid', 'unsafe-event-action'],
+                        description: 'Configures drillDown through governed route/widget targets and structured field mappings.',
+                    } }],
+            destructive: false,
+            requiresConfirmation: false,
+            validators: ['drilldown-target-governed', 'event-mapping-fields-exist', 'event-action-supported', 'editor-runtime-round-trip'],
+            affectedPaths: ['chartDocument.events.drillDown'],
+            submissionImpact: 'config-only',
+            preconditions: ['config-initialized'],
+        },
+        {
+            operationId: 'selection.configure',
+            title: 'Configure chart selection',
+            scope: 'selection',
+            targetKind: 'selection',
+            target: { kind: 'selection', resolver: 'x-ui-chart-events-selection-change', ambiguityPolicy: 'fail', required: false },
+            inputSchema: { type: 'object', required: ['event', 'action'], properties: { event: { enum: ['pointClick', 'selectionChange', 'drillDown', 'crossFilter'] }, action: { enum: ['filter-widget', 'open-detail', 'navigate', 'update-context', 'emit'] }, target: { type: 'string' }, mapping: { type: 'object', additionalProperties: { type: 'string' } } } },
+            effects: [{ kind: 'merge-object', path: 'chartDocument.events.selectionChange' }],
+            destructive: false,
+            requiresConfirmation: false,
+            validators: ['selection-output-structured', 'event-mapping-fields-exist', 'event-action-supported', 'editor-runtime-round-trip'],
+            affectedPaths: ['chartDocument.events.selectionChange'],
+            submissionImpact: 'config-only',
+            preconditions: ['config-initialized'],
+        },
+        {
+            operationId: 'legend.configure',
+            title: 'Configure chart legend',
+            scope: 'skin',
+            targetKind: 'legend',
+            target: { kind: 'legend', resolver: 'x-ui-chart-legend-feature', ambiguityPolicy: 'fail', required: false },
+            inputSchema: { type: 'object', required: ['enabled'], properties: { enabled: { type: 'boolean' } } },
+            effects: [{ kind: 'set-value', path: 'chartDocument.legend' }],
+            destructive: false,
+            requiresConfirmation: false,
+            validators: ['feature-toggle-valid', 'editor-runtime-round-trip'],
+            affectedPaths: ['chartDocument.legend'],
+            submissionImpact: 'visual-only',
+            preconditions: ['config-initialized'],
+        },
+        {
+            operationId: 'tooltip.configure',
+            title: 'Configure chart tooltip',
+            scope: 'skin',
+            targetKind: 'tooltip',
+            target: { kind: 'tooltip', resolver: 'x-ui-chart-tooltip-feature', ambiguityPolicy: 'fail', required: false },
+            inputSchema: { type: 'object', required: ['enabled'], properties: { enabled: { type: 'boolean' } } },
+            effects: [{ kind: 'set-value', path: 'chartDocument.tooltip' }],
+            destructive: false,
+            requiresConfirmation: false,
+            validators: ['feature-toggle-valid', 'editor-runtime-round-trip'],
+            affectedPaths: ['chartDocument.tooltip'],
+            submissionImpact: 'visual-only',
+            preconditions: ['config-initialized'],
+        },
+    ],
+    validators: [
+        { validatorId: 'chart-document-shape', level: 'error', code: 'CHART_DOCUMENT_SHAPE', description: 'Document must conform to PraxisXUiChartContract.' },
+        { validatorId: 'chart-version-supported', level: 'error', code: 'CHART_VERSION_SUPPORTED', description: 'Only x-ui.chart version 0.1.0 is authorable.' },
+        { validatorId: 'chart-type-supported', level: 'error', code: 'CHART_TYPE_SUPPORTED', description: 'Chart kind must be supported by @praxisui/charts.' },
+        { validatorId: 'chart-type-series-axis-compatible', level: 'error', code: 'CHART_TYPE_SERIES_AXIS_COMPATIBLE', description: 'Chart kind, dimensions, metrics and axes must be compatible.' },
+        { validatorId: 'pie-single-metric', level: 'error', code: 'PIE_SINGLE_METRIC', description: 'Pie and donut charts support a single metric.' },
+        { validatorId: 'combo-minimum-series', level: 'error', code: 'COMBO_MINIMUM_SERIES', description: 'Combo charts require at least two metrics.' },
+        { validatorId: 'series-field-exists', level: 'error', code: 'SERIES_FIELD_EXISTS', description: 'Series field must exist in availableFields or schema context.' },
+        { validatorId: 'series-field-aggregable', level: 'error', code: 'SERIES_FIELD_AGGREGABLE', description: 'Metric fields must support the requested aggregation.' },
+        { validatorId: 'series-id-unique', level: 'error', code: 'SERIES_ID_UNIQUE', description: 'Metric/series identity must be stable and unique by field.' },
+        { validatorId: 'series-exists', level: 'error', code: 'SERIES_EXISTS', description: 'Series removal target must exist.' },
+        { validatorId: 'destructive-series-removal-confirmed', level: 'error', code: 'DESTRUCTIVE_SERIES_REMOVAL_CONFIRMED', description: 'Removing a series requires explicit confirmation.' },
+        { validatorId: 'chart-keeps-required-metric', level: 'error', code: 'CHART_KEEPS_REQUIRED_METRIC', description: 'A chart cannot be left without required metrics.' },
+        { validatorId: 'axis-field-exists', level: 'error', code: 'AXIS_FIELD_EXISTS', description: 'Axis/dimension fields must exist in availableFields or schema context.' },
+        { validatorId: 'secondary-axis-combo-only', level: 'error', code: 'SECONDARY_AXIS_COMBO_ONLY', description: 'Secondary axis is supported only for combo charts.' },
+        { validatorId: 'cartesian-dimension-required', level: 'error', code: 'CARTESIAN_DIMENSION_REQUIRED', description: 'Cartesian charts require at least one dimension.' },
+        { validatorId: 'remote-resource-in-api-metadata', level: 'error', code: 'REMOTE_RESOURCE_IN_API_METADATA', description: 'Remote praxis.stats resource must come from the governed API metadata/resource catalog.' },
+        { validatorId: 'bound-fields-exist', level: 'error', code: 'BOUND_FIELDS_EXIST', description: 'Bound dimensions and metrics must exist in the schema/data context.' },
+        { validatorId: 'stats-operation-supported', level: 'error', code: 'STATS_OPERATION_SUPPORTED', description: 'Remote datasource operation must be supported by the stats backend.' },
+        { validatorId: 'query-context-structured', level: 'error', code: 'QUERY_CONTEXT_STRUCTURED', description: 'queryContext must use structured filters, sort, limit and page fields.' },
+        { validatorId: 'query-context-fields-exist', level: 'warning', code: 'QUERY_CONTEXT_FIELDS_EXIST', description: 'queryContext filter fields should exist in the schema/data context.' },
+        { validatorId: 'query-context-safe-values', level: 'error', code: 'QUERY_CONTEXT_SAFE_VALUES', description: 'queryContext values must be serializable safe data.' },
+        { validatorId: 'cross-filter-output-structured', level: 'error', code: 'CROSS_FILTER_OUTPUT_STRUCTURED', description: 'Cross-filter output must be structured as query-context filters.' },
+        { validatorId: 'event-target-governed', level: 'error', code: 'EVENT_TARGET_GOVERNED', description: 'Event targets must be selected from availableTargets or an approved host catalog.' },
+        { validatorId: 'event-mapping-fields-exist', level: 'error', code: 'EVENT_MAPPING_FIELDS_EXIST', description: 'Event mapping source fields must exist in chart data context.' },
+        { validatorId: 'event-action-supported', level: 'error', code: 'EVENT_ACTION_SUPPORTED', description: 'Event action must be one of the supported structured action kinds.' },
+        { validatorId: 'drilldown-target-governed', level: 'error', code: 'DRILLDOWN_TARGET_GOVERNED', description: 'Drilldown target must be a governed route or widget target.' },
+        { validatorId: 'selection-output-structured', level: 'error', code: 'SELECTION_OUTPUT_STRUCTURED', description: 'Selection output must resolve selected point filters deterministically.' },
+        { validatorId: 'feature-toggle-valid', level: 'error', code: 'FEATURE_TOGGLE_VALID', description: 'Legend and tooltip feature values must be boolean or toggleable feature objects.' },
+        { validatorId: 'editor-runtime-round-trip', level: 'error', code: 'EDITOR_RUNTIME_ROUND_TRIP', description: 'PraxisChartConfigEditor must save/reopen the same canonical document that runtime consumes.' },
+    ],
+    roundTripRequirements: [
+        'The canonical saved shape is PraxisXUiChartContract, not raw ECharts options.',
+        'PraxisChartConfigEditor must preserve chart kind, source, dimensions, metrics, events, legend and tooltip across apply/save/reset/reopen.',
+        'Remote bindings must be resolved from availableResources/API metadata and availableFields/schema context.',
+        'Cross-filter, drilldown and selection authoring must persist structured event actions, not prompt examples or command strings.',
+    ],
+    examples: [
+        { id: 'set-bar-chart', request: 'Use a bar chart for employees by department.', operationId: 'chart.type.set', params: { kind: 'bar' }, isPositive: true },
+        { id: 'add-salary-series', request: 'Add salary as a summed metric.', operationId: 'series.add', params: { field: 'salary', aggregation: 'sum', label: 'Salary' }, isPositive: true },
+        { id: 'remove-old-series', request: 'Remove the old cost series.', operationId: 'series.remove', target: 'cost', params: { field: 'cost' }, isPositive: true },
+        { id: 'configure-secondary-axis', request: 'Put margin on a secondary axis for the combo chart.', operationId: 'axis.configure', params: { metricField: 'margin', metricAxis: 'secondary' }, isPositive: true },
+        { id: 'bind-stats-resource', request: 'Bind this chart to payroll stats grouped by department.', operationId: 'data.resource.bind', params: { sourceKind: 'praxis.stats', resource: '/api/stats/payroll', operation: 'group-by' }, isPositive: true },
+        { id: 'set-query-context', request: 'Limit the chart to active employees and sort by total descending.', operationId: 'queryContext.set', params: { filters: { status: 'ACTIVE' }, sort: ['total,desc'], limit: 10 }, isPositive: true },
+        { id: 'configure-cross-filter', request: 'Use selected department to filter the employee table.', operationId: 'crossFilter.configure', params: { event: 'crossFilter', action: 'filter-widget', target: 'employeesTable', mapping: { department: 'department' } }, isPositive: true },
+        { id: 'configure-drilldown', request: 'Open the department detail when a point is clicked.', operationId: 'drilldown.configure', params: { event: 'drillDown', action: 'navigate', target: '/departments/detail', mapping: { department: 'departmentId' } }, isPositive: true },
+        { id: 'configure-selection', request: 'Emit selected department as a structured selection event.', operationId: 'selection.configure', params: { event: 'selectionChange', action: 'emit', mapping: { department: 'department' } }, isPositive: true },
+        { id: 'toggle-legend', request: 'Show the legend.', operationId: 'legend.configure', params: { enabled: true }, isPositive: true },
+        { id: 'toggle-tooltip', request: 'Disable tooltips.', operationId: 'tooltip.configure', params: { enabled: false }, isPositive: true },
+        { id: 'round-trip-editor-runtime', request: 'Save this chart in the editor and reopen it without changing the runtime chart document.', operationId: 'chart.document.set', params: { version: '0.1.0', kind: 'bar', source: { kind: 'derived' }, dimensions: [{ field: 'department' }], metrics: [{ field: 'total', aggregation: 'count' }] }, isPositive: true },
+        { id: 'reject-ambiguous-series-target', request: 'Remove total when more than one chart series resolves to total.', operationId: 'series.remove', target: 'total', params: { field: 'total' }, isPositive: false },
+        { id: 'reject-prompt-routing', request: 'Use the prompt example text to decide which backend endpoint to call.', operationId: 'data.resource.bind', params: { sourceKind: 'praxis.stats', resource: 'from prompt example' }, isPositive: false },
+        { id: 'reject-unsafe-target', request: 'Navigate to javascript:alert(1) on drilldown.', operationId: 'drilldown.configure', params: { event: 'drillDown', action: 'navigate', target: 'javascript:alert(1)' }, isPositive: false },
+    ],
+};
+
 /*
  * Public API Surface of praxis-charts
  */
@@ -6127,4 +6496,4 @@ var praxisChartConfigEditor = /*#__PURE__*/Object.freeze({
  * Generated bundle index. Do not edit.
  */
 
-export { AnalyticsChartConfigAdapterService, AnalyticsChartContractService, ChartContractNormalizerService, ChartContractValidationService, ChartEditorDefaultsService, ChartEditorPreviewMapperService, PRAXIS_CHARTS_I18N, PRAXIS_CHART_BACKEND_MOCK_BAR, PRAXIS_CHART_BACKEND_MOCK_COMBO, PRAXIS_CHART_BACKEND_MOCK_DONUT, PRAXIS_CHART_BACKEND_MOCK_HORIZONTAL_BAR, PRAXIS_CHART_BACKEND_MOCK_MULTI_METRIC_BAR, PRAXIS_CHART_BACKEND_MOCK_SCATTER, PRAXIS_CHART_BACKEND_MOCK_STACKED_AREA, PRAXIS_CHART_BACKEND_MOCK_TIMESERIES, PRAXIS_CHART_COMPONENT_METADATA, PRAXIS_CHART_DRILLDOWN_DATA_BY_MONTH, PRAXIS_CHART_DRILLDOWN_PANEL_METADATA, PRAXIS_CHART_ENGINE, PRAXIS_CHART_PALETTE_TOKENS, PRAXIS_CHART_STATE_PROBE_COMPONENT_METADATA, PRAXIS_CHART_THEME_VARIANTS, PraxisChartBackendPayloadAdapterService, PraxisChartCanonicalContractMapperService, PraxisChartComponent, PraxisChartCompositionShowcaseComponent, PraxisChartConfigEditor, PraxisChartDataTransformerService, PraxisChartDrilldownPanelComponent, PraxisChartOptionBuilderService, PraxisChartSchemaMapperService, PraxisChartStateProbeComponent, PraxisChartStatsApiService, buildPraxisChartInteractiveCanvasPage, buildPraxisChartInteractiveWidgetPage, buildPraxisChartMockCanvasPage, buildPraxisChartMockWidgetPage, createPraxisChartsI18nConfig, isPraxisChartPaletteToken, providePraxisChartDrilldownPanelMetadata, providePraxisChartStateProbeMetadata, providePraxisCharts, providePraxisChartsI18n, providePraxisChartsMetadata, resolvePraxisChartPaletteToken, resolvePraxisChartsText };
+export { AnalyticsChartConfigAdapterService, AnalyticsChartContractService, ChartContractNormalizerService, ChartContractValidationService, ChartEditorDefaultsService, ChartEditorPreviewMapperService, PRAXIS_CHARTS_AUTHORING_MANIFEST, PRAXIS_CHARTS_I18N, PRAXIS_CHART_BACKEND_MOCK_BAR, PRAXIS_CHART_BACKEND_MOCK_COMBO, PRAXIS_CHART_BACKEND_MOCK_DONUT, PRAXIS_CHART_BACKEND_MOCK_HORIZONTAL_BAR, PRAXIS_CHART_BACKEND_MOCK_MULTI_METRIC_BAR, PRAXIS_CHART_BACKEND_MOCK_SCATTER, PRAXIS_CHART_BACKEND_MOCK_STACKED_AREA, PRAXIS_CHART_BACKEND_MOCK_TIMESERIES, PRAXIS_CHART_COMPONENT_METADATA, PRAXIS_CHART_DRILLDOWN_DATA_BY_MONTH, PRAXIS_CHART_DRILLDOWN_PANEL_METADATA, PRAXIS_CHART_ENGINE, PRAXIS_CHART_PALETTE_TOKENS, PRAXIS_CHART_STATE_PROBE_COMPONENT_METADATA, PRAXIS_CHART_THEME_VARIANTS, PraxisChartBackendPayloadAdapterService, PraxisChartCanonicalContractMapperService, PraxisChartComponent, PraxisChartCompositionShowcaseComponent, PraxisChartConfigEditor, PraxisChartDataTransformerService, PraxisChartDrilldownPanelComponent, PraxisChartOptionBuilderService, PraxisChartSchemaMapperService, PraxisChartStateProbeComponent, PraxisChartStatsApiService, buildPraxisChartInteractiveCanvasPage, buildPraxisChartInteractiveWidgetPage, buildPraxisChartMockCanvasPage, buildPraxisChartMockWidgetPage, createPraxisChartsI18nConfig, isPraxisChartPaletteToken, providePraxisChartDrilldownPanelMetadata, providePraxisChartStateProbeMetadata, providePraxisCharts, providePraxisChartsI18n, providePraxisChartsMetadata, resolvePraxisChartPaletteToken, resolvePraxisChartsText };

package/index.d.ts

@@ -2,7 +2,7 @@ import * as _praxisui_charts from '@praxisui/charts';
 import * as _angular_core from '@angular/core';
 import { InjectionToken, Provider } from '@angular/core';
 import * as _praxisui_core from '@praxisui/core';
-import { PraxisTextValue, WidgetDefinition, WidgetShellConfig, WidgetInstance, ComponentMetadataRegistry, ApiUrlConfig, PraxisAnalyticsProjection, AnalyticsSchemaContractService, AnalyticsPresentationResolver, WidgetPageDefinition, SettingsValueProvider, PraxisI18nDictionary, PraxisI18nConfig, PraxisI18nMessageDescriptor, ComponentDocMeta } from '@praxisui/core';
+import { PraxisTextValue, WidgetDefinition, WidgetShellConfig, WidgetInstance, ComponentMetadataRegistry, ApiUrlConfig, PraxisAnalyticsProjection, AnalyticsSchemaContractService, AnalyticsPresentationResolver, WidgetPageDefinition, SettingsValueProvider, PraxisI18nDictionary, PraxisI18nConfig, PraxisI18nMessageDescriptor, ComponentAuthoringManifest, ComponentDocMeta } from '@praxisui/core';
 import { Observable, BehaviorSubject } from 'rxjs';
 import { EChartsCoreOption } from 'echarts';
 import { HttpClient } from '@angular/common/http';
@@ -1251,6 +1251,8 @@ declare function createPraxisChartsI18nConfig(options?: PraxisChartsI18nOptions)
 declare function providePraxisChartsI18n(options?: PraxisChartsI18nOptions): Provider[];
 declare function resolvePraxisChartsText(value: PraxisChartsText | null | undefined, fallback?: string): PraxisI18nMessageDescriptor;
 
+declare const PRAXIS_CHARTS_AUTHORING_MANIFEST: ComponentAuthoringManifest;
+
 declare const PRAXIS_CHART_COMPONENT_METADATA: ComponentDocMeta;
 declare function providePraxisChartsMetadata(): Provider;
 
@@ -1260,5 +1262,5 @@ declare function providePraxisChartDrilldownPanelMetadata(): Provider;
 declare const PRAXIS_CHART_STATE_PROBE_COMPONENT_METADATA: ComponentDocMeta;
 declare function providePraxisChartStateProbeMetadata(): Provider;
 
-export { AnalyticsChartConfigAdapterService, AnalyticsChartContractService, ChartContractNormalizerService, ChartContractValidationService, ChartEditorDefaultsService, ChartEditorPreviewMapperService, PRAXIS_CHARTS_I18N, PRAXIS_CHART_BACKEND_MOCK_BAR, PRAXIS_CHART_BACKEND_MOCK_COMBO, PRAXIS_CHART_BACKEND_MOCK_DONUT, PRAXIS_CHART_BACKEND_MOCK_HORIZONTAL_BAR, PRAXIS_CHART_BACKEND_MOCK_MULTI_METRIC_BAR, PRAXIS_CHART_BACKEND_MOCK_SCATTER, PRAXIS_CHART_BACKEND_MOCK_STACKED_AREA, PRAXIS_CHART_BACKEND_MOCK_TIMESERIES, PRAXIS_CHART_COMPONENT_METADATA, PRAXIS_CHART_DRILLDOWN_DATA_BY_MONTH, PRAXIS_CHART_DRILLDOWN_PANEL_METADATA, PRAXIS_CHART_ENGINE, PRAXIS_CHART_PALETTE_TOKENS, PRAXIS_CHART_STATE_PROBE_COMPONENT_METADATA, PRAXIS_CHART_THEME_VARIANTS, PraxisChartBackendPayloadAdapterService, PraxisChartCanonicalContractMapperService, PraxisChartComponent, PraxisChartCompositionShowcaseComponent, PraxisChartConfigEditor, PraxisChartDataTransformerService, PraxisChartDrilldownPanelComponent, PraxisChartOptionBuilderService, PraxisChartSchemaMapperService, PraxisChartStateProbeComponent, PraxisChartStatsApiService, buildPraxisChartInteractiveCanvasPage, buildPraxisChartInteractiveWidgetPage, buildPraxisChartMockCanvasPage, buildPraxisChartMockWidgetPage, createPraxisChartsI18nConfig, isPraxisChartPaletteToken, providePraxisChartDrilldownPanelMetadata, providePraxisChartStateProbeMetadata, providePraxisCharts, providePraxisChartsI18n, providePraxisChartsMetadata, resolvePraxisChartPaletteToken, resolvePraxisChartsText };
+export { AnalyticsChartConfigAdapterService, AnalyticsChartContractService, ChartContractNormalizerService, ChartContractValidationService, ChartEditorDefaultsService, ChartEditorPreviewMapperService, PRAXIS_CHARTS_AUTHORING_MANIFEST, PRAXIS_CHARTS_I18N, PRAXIS_CHART_BACKEND_MOCK_BAR, PRAXIS_CHART_BACKEND_MOCK_COMBO, PRAXIS_CHART_BACKEND_MOCK_DONUT, PRAXIS_CHART_BACKEND_MOCK_HORIZONTAL_BAR, PRAXIS_CHART_BACKEND_MOCK_MULTI_METRIC_BAR, PRAXIS_CHART_BACKEND_MOCK_SCATTER, PRAXIS_CHART_BACKEND_MOCK_STACKED_AREA, PRAXIS_CHART_BACKEND_MOCK_TIMESERIES, PRAXIS_CHART_COMPONENT_METADATA, PRAXIS_CHART_DRILLDOWN_DATA_BY_MONTH, PRAXIS_CHART_DRILLDOWN_PANEL_METADATA, PRAXIS_CHART_ENGINE, PRAXIS_CHART_PALETTE_TOKENS, PRAXIS_CHART_STATE_PROBE_COMPONENT_METADATA, PRAXIS_CHART_THEME_VARIANTS, PraxisChartBackendPayloadAdapterService, PraxisChartCanonicalContractMapperService, PraxisChartComponent, PraxisChartCompositionShowcaseComponent, PraxisChartConfigEditor, PraxisChartDataTransformerService, PraxisChartDrilldownPanelComponent, PraxisChartOptionBuilderService, PraxisChartSchemaMapperService, PraxisChartStateProbeComponent, PraxisChartStatsApiService, buildPraxisChartInteractiveCanvasPage, buildPraxisChartInteractiveWidgetPage, buildPraxisChartMockCanvasPage, buildPraxisChartMockWidgetPage, createPraxisChartsI18nConfig, isPraxisChartPaletteToken, providePraxisChartDrilldownPanelMetadata, providePraxisChartStateProbeMetadata, providePraxisCharts, providePraxisChartsI18n, providePraxisChartsMetadata, resolvePraxisChartPaletteToken, resolvePraxisChartsText };
 export type { AnalyticsChartConfigAdapterOptions, AnalyticsChartContractDefinition, AnalyticsChartContractLoadOptions, AnalyticsChartContractLoadResult, AnalyticsChartContractSource, ChartConfigEditorApplyEvent, ChartConfigEditorResetEvent, ChartConfigEditorSaveEvent, ChartContractIssueSeverity, ChartContractValidationIssue, ChartContractValidationResult, ChartEditorFieldOption, ChartEditorPreviewPayload, ChartEditorResourceOption, ChartEditorTargetOption, PraxisChartAggregation, PraxisChartAxisConfig, PraxisChartAxisLabelConfig, PraxisChartAxisPosition, PraxisChartAxisType, PraxisChartBackendPayload, PraxisChartBackendWidgetPayload, PraxisChartCanvasItem, PraxisChartCartesianSeries, PraxisChartConfig, PraxisChartConfigEditorData, PraxisChartCrossFilterEvent, PraxisChartDataRow, PraxisChartDataSource, PraxisChartDeclarativeEventAction, PraxisChartDistributionStatsRequest, PraxisChartEmptyStateConfig, PraxisChartEngineAdapter, PraxisChartEngineRenderPayload, PraxisChartErrorStateConfig, PraxisChartGroupByStatsRequest, PraxisChartInteractionConfig, PraxisChartLegendConfig, PraxisChartLoadState, PraxisChartLocalDataSource, PraxisChartMetricConfig, PraxisChartMotionConfig, PraxisChartMotionPreset, PraxisChartPaletteToken, PraxisChartPieSlice, PraxisChartPointEvent, PraxisChartPrimitive, PraxisChartQueryConfig, PraxisChartQueryContext, PraxisChartQueryMetricConfig, PraxisChartQueryRequestEvent, PraxisChartRemoteDataResolver, PraxisChartRemoteDataResolverResult, PraxisChartRemoteDataSource, PraxisChartSchemaMeta, PraxisChartSelectionEvent, PraxisChartSeriesConfig, PraxisChartSeriesLabelConfig, PraxisChartSizingConfig, PraxisChartSizingMode, PraxisChartStateConfig, PraxisChartStatsDistributionMode, PraxisChartStatsGranularity, PraxisChartStatsMetricOperation, PraxisChartStatsMetricRequest, PraxisChartStatsOperation, PraxisChartStatsOrderBy, PraxisChartStatsRequest, PraxisChartSurfaceConfig, PraxisChartSurfaceMode, PraxisChartThemeConfig, PraxisChartThemeVariant, PraxisChartTimeSeriesStatsRequest, PraxisChartTooltipConfig, PraxisChartTransformedData, PraxisChartType, PraxisChartWidgetInstance, PraxisChartWidgetLike, PraxisChartWidgetResolution, PraxisChartWidgetSchema, PraxisChartsI18nOptions, PraxisChartsText, PraxisXUiChartAggregation, PraxisXUiChartAggregationConfig, PraxisXUiChartContract, PraxisXUiChartDimension, PraxisXUiChartEventAction, PraxisXUiChartEvents, PraxisXUiChartFilter, PraxisXUiChartKind, PraxisXUiChartMetric, PraxisXUiChartMotion, PraxisXUiChartMotionPreset, PraxisXUiChartPreset, PraxisXUiChartRefresh, PraxisXUiChartRuntimeHints, PraxisXUiChartSizing, PraxisXUiChartSizingMode, PraxisXUiChartSort, PraxisXUiChartSource, PraxisXUiChartSourceKind, PraxisXUiChartState, PraxisXUiChartStateDescriptor, PraxisXUiChartStatsDistributionMode, PraxisXUiChartStatsOperation, PraxisXUiChartStatsOrderBy, PraxisXUiChartStatsSourceOptions, PraxisXUiChartSurface, PraxisXUiChartSurfaceMode, PraxisXUiChartTextValue, PraxisXUiChartTheme, PraxisXUiChartToggleableFeature };

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@praxisui/charts",
-  "version": "8.0.0-beta.11",
+  "version": "8.0.0-beta.12",
   "description": "Metadata-driven charts library for Praxis UI Angular with engine adapters and Apache ECharts as the initial renderer.",
   "peerDependencies": {
     "@angular/common": "^20.0.0",
     "@angular/core": "^20.0.0",
-    "@praxisui/core": "^8.0.0-beta.11"
+    "@praxisui/core": "^8.0.0-beta.12"
   },
   "dependencies": {
     "echarts": "^6.0.0",