@praxisui/charts 9.0.0-beta.74 → 9.0.0-beta.76

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@praxisui/charts",
-  "version": "9.0.0-beta.74",
+  "version": "9.0.0-beta.76",
   "description": "Metadata-driven charts library for Praxis UI Angular with engine adapters and Apache ECharts as the initial renderer.",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
     "@angular/core": "^21.0.0",
-    "@praxisui/core": "^9.0.0-beta.74",
+    "@praxisui/core": "^9.0.0-beta.76",
     "@angular/forms": "^21.0.0",
     "@angular/material": "^21.0.0",
-    "@praxisui/table": "^9.0.0-beta.74",
+    "@praxisui/table": "^9.0.0-beta.76",
     "rxjs": "~7.8.0"
   },
   "dependencies": {

package/types/praxisui-charts.d.ts

@@ -2,7 +2,7 @@ import * as _praxisui_charts from '@praxisui/charts';
 import * as _angular_core from '@angular/core';
 import { InjectionToken, Provider, OnChanges, OnDestroy, SimpleChanges } from '@angular/core';
 import * as _praxisui_core from '@praxisui/core';
-import { PraxisAnalyticsComparisonStatsRequest, PraxisDataQueryContext, PraxisTextValue, PraxisPresentationVisualizationConfig, PraxisPresentationVisualizationPoint, PraxisPresentationVisualizationSegment, PraxisPresentationVisualizationThreshold, WidgetDefinition, WidgetShellConfig, WidgetInstance, ApiUrlConfig, PraxisI18nService, PraxisAnalyticsProjection, AnalyticsSchemaContractService, AnalyticsPresentationResolver, WidgetPageDefinition, SettingsValueProvider, ComponentConfigEditorContextResult, ResourceCapabilitySnapshot, PraxisI18nDictionary, PraxisI18nConfig, PraxisI18nMessageDescriptor, ComponentAuthoringManifest, ComponentDocMeta } from '@praxisui/core';
+import { PraxisAnalyticsComparisonStatsRequest, PraxisDataQueryContext, PraxisTextValue, PraxisPresentationVisualizationConfig, PraxisPresentationVisualizationPoint, PraxisPresentationVisualizationSegment, PraxisPresentationVisualizationThreshold, WidgetDefinition, WidgetShellConfig, WidgetInstance, PraxisI18nService, ApiUrlConfig, PraxisAnalyticsProjection, AnalyticsSchemaContractService, AnalyticsPresentationResolver, WidgetPageDefinition, SettingsValueProvider, ComponentConfigEditorContextResult, ResourceCapabilitySnapshot, PraxisI18nDictionary, PraxisI18nConfig, PraxisI18nMessageDescriptor, ComponentAuthoringManifest, ComponentDocMeta } from '@praxisui/core';
 import { Observable, BehaviorSubject } from 'rxjs';
 import { HttpClient } from '@angular/common/http';
 
@@ -281,9 +281,11 @@ type PraxisXUiChartTextValue = string | {
     fallback?: string;
 };
 type PraxisXUiChartSourceKind = 'praxis.stats' | 'derived';
-type PraxisXUiChartStatsOperation = 'group-by' | 'timeseries' | 'distribution';
+type PraxisXUiChartStatsOperation = 'group-by' | 'timeseries' | 'distribution' | 'comparison';
 type PraxisXUiChartStatsDistributionMode = 'terms' | 'histogram';
 type PraxisXUiChartStatsOrderBy = 'key-asc' | 'key-desc' | 'value-asc' | 'value-desc';
+type PraxisXUiChartComparisonPeriodPreset = 'TODAY' | 'YESTERDAY' | 'LAST_7_DAYS' | 'LAST_30_DAYS' | 'THIS_MONTH' | 'LAST_MONTH' | 'THIS_QUARTER' | 'THIS_YEAR';
+type PraxisXUiChartComparisonPeriodMode = 'PREVIOUS_ALIGNED' | 'PREVIOUS_CALENDAR_PERIOD';
 type PraxisXUiChartAggregation = 'sum' | 'avg' | 'min' | 'max' | 'count' | 'distinct-count';
 interface PraxisXUiChartFilter {
     field: string;
@@ -315,6 +317,12 @@ interface PraxisXUiChartAggregationConfig {
     operation: PraxisXUiChartAggregation;
     as?: string;
 }
+interface PraxisXUiChartComparisonPeriod {
+    field: string;
+    timezone: string;
+    preset: PraxisXUiChartComparisonPeriodPreset;
+    mode: PraxisXUiChartComparisonPeriodMode;
+}
 interface PraxisXUiChartStatsSourceOptions {
     granularity?: 'day' | 'week' | 'month';
     fillGaps?: boolean;
@@ -323,6 +331,7 @@ interface PraxisXUiChartStatsSourceOptions {
     bucketCount?: number;
     orderBy?: PraxisXUiChartStatsOrderBy;
     limit?: number;
+    comparisonPeriod?: PraxisXUiChartComparisonPeriod;
 }
 interface PraxisXUiChartRefresh {
     strategy?: 'manual' | 'interval' | 'on-context-change';
@@ -783,6 +792,7 @@ declare class ChartContractValidationService {
     private validateSource;
     private validateTheme;
     private validateMetrics;
+    private validateComparison;
     private validateSizing;
     private validateKinds;
     private validateDistribution;
@@ -800,7 +810,8 @@ declare class ChartContractValidationService {
 declare class PraxisChartCanonicalContractMapperService {
     private readonly normalizer;
     private readonly validator;
-    constructor(normalizer?: ChartContractNormalizerService, validator?: ChartContractValidationService);
+    private readonly i18n?;
+    constructor(normalizer?: ChartContractNormalizerService, validator?: ChartContractValidationService, i18n?: PraxisI18nService | undefined);
     toPraxisChartConfig(contract: PraxisXUiChartContract): PraxisChartConfig;
     private buildAxes;
     private buildSeries;
@@ -831,7 +842,9 @@ declare class PraxisChartCanonicalContractMapperService {
     private mapStatsGranularityToBackend;
     private mapDistributionModeToBackend;
     private mapStatsMetricOperation;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<PraxisChartCanonicalContractMapperService, never>;
+    private comparisonMetricField;
+    private comparisonPeriodLabel;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<PraxisChartCanonicalContractMapperService, [null, null, { optional: true; }]>;
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<PraxisChartCanonicalContractMapperService>;
 }
 
@@ -1160,7 +1173,7 @@ type ChartEditorSection = 'general' | 'data' | 'analytics' | 'appearance' | 'mot
 type ChartFeatureKey = 'legend' | 'labels' | 'tooltip';
 type ChartStateKey = 'empty' | 'loading' | 'error';
 type ChartEventKey = ChartEditorEventKey;
-type ChartFieldRole = 'dimension' | 'metric';
+type ChartFieldRole = 'dimension' | 'metric' | 'time';
 declare class PraxisChartConfigEditor implements SettingsValueProvider {
     readonly documentInput: _angular_core.InputSignal<PraxisXUiChartContract | null>;
     readonly modeInput: _angular_core.InputSignal<"create" | "edit">;
@@ -1185,6 +1198,8 @@ declare class PraxisChartConfigEditor implements SettingsValueProvider {
     readonly operations: PraxisXUiChartStatsOperation[];
     readonly timeGranularities: readonly ["day", "week", "month"];
     readonly distributionModes: PraxisXUiChartStatsDistributionMode[];
+    readonly comparisonPeriodPresets: PraxisXUiChartComparisonPeriodPreset[];
+    readonly comparisonPeriodModes: PraxisXUiChartComparisonPeriodMode[];
     readonly dimensionRoles: NonNullable<PraxisXUiChartDimension['role']>[];
     readonly metricAggregations: PraxisXUiChartAggregation[];
     readonly metricAxes: Array<NonNullable<PraxisXUiChartMetric['axis']>>;
@@ -1250,6 +1265,10 @@ declare class PraxisChartConfigEditor implements SettingsValueProvider {
     setDistributionMode(value: PraxisXUiChartStatsDistributionMode): void;
     setBucketSize(value: string): void;
     setBucketCount(value: string): void;
+    setComparisonPeriodField(field: string): void;
+    setComparisonPeriodTimezone(timezone: string): void;
+    setComparisonPeriodPreset(preset: PraxisXUiChartComparisonPeriodPreset): void;
+    setComparisonPeriodMode(mode: PraxisXUiChartComparisonPeriodMode): void;
     addDimension(): void;
     removeDimension(index: number): void;
     setDimensionField(index: number, field: string): void;
@@ -1288,6 +1307,10 @@ declare class PraxisChartConfigEditor implements SettingsValueProvider {
     distributionModeValue(): PraxisXUiChartStatsDistributionMode;
     bucketSizeValue(): string;
     bucketCountValue(): string;
+    comparisonPeriodFieldValue(): string;
+    comparisonPeriodTimezoneValue(): string;
+    comparisonPeriodPresetValue(): PraxisXUiChartComparisonPeriodPreset;
+    comparisonPeriodModeValue(): PraxisXUiChartComparisonPeriodMode;
     heightValue(): string;
     sizingModeValue(): PraxisXUiChartSizingMode;
     sizingMinHeightValue(): string;
@@ -1315,6 +1338,7 @@ declare class PraxisChartConfigEditor implements SettingsValueProvider {
     showMetricSeriesKindControls(): boolean;
     showTimeseriesControls(): boolean;
     showDistributionControls(): boolean;
+    showComparisonControls(): boolean;
     showComboPanel(): boolean;
     showPieDonutPanel(): boolean;
     showScatterPanel(): boolean;
@@ -1335,6 +1359,8 @@ declare class PraxisChartConfigEditor implements SettingsValueProvider {
     private fieldMatchesOperation;
     private fieldMatchesDistributionMode;
     private fieldMatchesRole;
+    private updateComparisonPeriod;
+    private defaultComparisonPeriodField;
     private catalogError;
     private normalizeSizingSizeInput;
     private mergeTheme;
@@ -1525,6 +1551,36 @@ declare const PRAXIS_CHART_AUTHORING_COVERAGE: readonly [{
     readonly owner: "chart-config-editor";
     readonly rationale: "Histogram bucket count is a supported distribution option.";
     readonly proof: ["praxis-chart-config-editor.spec.ts"];
+}, {
+    readonly path: "chartDocument.source.options.comparisonPeriod";
+    readonly mode: "visual-editable";
+    readonly owner: "chart-config-editor";
+    readonly rationale: "Comparison period is a canonical operation binding edited as one governed group instead of independent endpoint calls.";
+    readonly proof: ["praxis-chart-config-editor.spec.ts", "chart-canonical-contract-mapper.service.spec.ts"];
+}, {
+    readonly path: "chartDocument.source.options.comparisonPeriod.field";
+    readonly mode: "visual-editable";
+    readonly owner: "chart-config-editor";
+    readonly rationale: "The comparison period field is selected only from time-series eligible capability-backed fields.";
+    readonly proof: ["praxis-chart-config-editor.spec.ts", "chart-resource-capability-catalog.adapter.spec.ts"];
+}, {
+    readonly path: "chartDocument.source.options.comparisonPeriod.timezone";
+    readonly mode: "visual-editable";
+    readonly owner: "chart-config-editor";
+    readonly rationale: "Timezone is an explicit canonical input required for deterministic period resolution by the backend.";
+    readonly proof: ["praxis-chart-config-editor.spec.ts", "chart-contract-validation.service.spec.ts"];
+}, {
+    readonly path: "chartDocument.source.options.comparisonPeriod.preset";
+    readonly mode: "visual-editable";
+    readonly owner: "chart-config-editor";
+    readonly rationale: "The period preset is constrained to the canonical backend vocabulary and persisted without local date arithmetic.";
+    readonly proof: ["praxis-chart-config-editor.spec.ts", "chart-contract-validation.service.spec.ts"];
+}, {
+    readonly path: "chartDocument.source.options.comparisonPeriod.mode";
+    readonly mode: "visual-editable";
+    readonly owner: "chart-config-editor";
+    readonly rationale: "Comparison mode is selected from the canonical aligned or calendar-period semantics resolved by the backend.";
+    readonly proof: ["praxis-chart-config-editor.spec.ts", "chart-contract-validation.service.spec.ts"];
 }, {
     readonly path: "chartDocument.source.options.orderBy";
     readonly mode: "preserved-only";
@@ -1763,7 +1819,9 @@ declare class ChartResourceCapabilityCatalogAdapter {
     private resolveDimensionOperations;
     private resolveAggregations;
     private resolveDistributionModes;
+    private resolveResourceOperations;
     private mapMetric;
+    private mapType;
     private toCountOption;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ChartResourceCapabilityCatalogAdapter, never>;
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<ChartResourceCapabilityCatalogAdapter>;
@@ -1792,4 +1850,4 @@ declare const PRAXIS_CHART_STATE_PROBE_COMPONENT_METADATA: ComponentDocMeta;
 declare function providePraxisChartStateProbeMetadata(): Provider;
 
 export { AnalyticsChartConfigAdapterService, AnalyticsChartContractService, ChartContractNormalizerService, ChartContractValidationService, ChartEditorDefaultsService, ChartEditorPreviewMapperService, ChartResourceCapabilityCatalogAdapter, PRAXIS_CHARTS_AUTHORING_MANIFEST, PRAXIS_CHARTS_I18N, PRAXIS_CHART_AUTHORING_COVERAGE, 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_ENGINE_FACTORY, PRAXIS_CHART_PALETTE_TOKENS, PRAXIS_CHART_STATE_PROBE_COMPONENT_METADATA, PRAXIS_CHART_THEME_VARIANTS, PRAXIS_X_UI_CHART_AUTHORABLE_VERSION, PraxisChartBackendPayloadAdapterService, PraxisChartCanonicalContractMapperService, PraxisChartComponent, PraxisChartCompositionShowcaseComponent, PraxisChartConfigEditor, PraxisChartDataTransformerService, PraxisChartDrilldownPanelComponent, PraxisChartSchemaMapperService, PraxisChartStateProbeComponent, PraxisChartStatsApiService, PraxisChartWidgetConfigEditor, PraxisMicroVisualizationComponent, 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, ChartEditorEventKey, ChartEditorFieldOption, ChartEditorPreviewPayload, ChartEditorResourceOption, ChartEditorTargetOption, PraxisChartAggregation, PraxisChartAuthoringCoverageMode, PraxisChartAuthoringCoverageOwner, PraxisChartAuthoringCoverageRow, PraxisChartAxisConfig, PraxisChartAxisLabelConfig, PraxisChartAxisPosition, PraxisChartAxisType, PraxisChartBackendPayload, PraxisChartBackendWidgetPayload, PraxisChartCanvasItem, PraxisChartCartesianSeries, PraxisChartConfig, PraxisChartConfigEditorData, PraxisChartCrossFilterEvent, PraxisChartDataRow, PraxisChartDataSource, PraxisChartDeclarativeEventAction, PraxisChartDistributionStatsRequest, PraxisChartDrillDownEvent, PraxisChartEmptyStateConfig, PraxisChartEngineAdapter, PraxisChartEngineFactory, PraxisChartEngineRenderPayload, PraxisChartErrorStateConfig, PraxisChartGroupByStatsRequest, PraxisChartInteractionConfig, PraxisChartLegendConfig, PraxisChartLoadState, PraxisChartLocalDataSource, PraxisChartMetricConfig, PraxisChartMotionConfig, PraxisChartMotionPreset, PraxisChartPaletteToken, PraxisChartPieSlice, PraxisChartPointActionEvent, 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, PraxisChartWidgetEditorContext, PraxisChartWidgetEditorInputs, PraxisChartWidgetEditorValue, PraxisChartWidgetInstance, PraxisChartWidgetLike, PraxisChartWidgetResolution, PraxisChartWidgetSchema, PraxisChartsI18nOptions, PraxisChartsProviderOptions, 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 };
+export type { AnalyticsChartConfigAdapterOptions, AnalyticsChartContractDefinition, AnalyticsChartContractLoadOptions, AnalyticsChartContractLoadResult, AnalyticsChartContractSource, ChartConfigEditorApplyEvent, ChartConfigEditorResetEvent, ChartConfigEditorSaveEvent, ChartContractIssueSeverity, ChartContractValidationIssue, ChartContractValidationResult, ChartEditorEventKey, ChartEditorFieldOption, ChartEditorPreviewPayload, ChartEditorResourceOption, ChartEditorTargetOption, PraxisChartAggregation, PraxisChartAuthoringCoverageMode, PraxisChartAuthoringCoverageOwner, PraxisChartAuthoringCoverageRow, PraxisChartAxisConfig, PraxisChartAxisLabelConfig, PraxisChartAxisPosition, PraxisChartAxisType, PraxisChartBackendPayload, PraxisChartBackendWidgetPayload, PraxisChartCanvasItem, PraxisChartCartesianSeries, PraxisChartConfig, PraxisChartConfigEditorData, PraxisChartCrossFilterEvent, PraxisChartDataRow, PraxisChartDataSource, PraxisChartDeclarativeEventAction, PraxisChartDistributionStatsRequest, PraxisChartDrillDownEvent, PraxisChartEmptyStateConfig, PraxisChartEngineAdapter, PraxisChartEngineFactory, PraxisChartEngineRenderPayload, PraxisChartErrorStateConfig, PraxisChartGroupByStatsRequest, PraxisChartInteractionConfig, PraxisChartLegendConfig, PraxisChartLoadState, PraxisChartLocalDataSource, PraxisChartMetricConfig, PraxisChartMotionConfig, PraxisChartMotionPreset, PraxisChartPaletteToken, PraxisChartPieSlice, PraxisChartPointActionEvent, 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, PraxisChartWidgetEditorContext, PraxisChartWidgetEditorInputs, PraxisChartWidgetEditorValue, PraxisChartWidgetInstance, PraxisChartWidgetLike, PraxisChartWidgetResolution, PraxisChartWidgetSchema, PraxisChartsI18nOptions, PraxisChartsProviderOptions, PraxisChartsText, PraxisXUiChartAggregation, PraxisXUiChartAggregationConfig, PraxisXUiChartComparisonPeriod, PraxisXUiChartComparisonPeriodMode, PraxisXUiChartComparisonPeriodPreset, 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 };