react-semaphor 0.1.601 → 0.1.603

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (123) hide show
  1. package/dist/analytics-protocol/index.js +415 -375
  2. package/dist/assistant-context/index.js +1 -1
  3. package/dist/assistant-protocol/index.js +5 -5
  4. package/dist/brand-studio/index.js +8 -8
  5. package/dist/briefings/index.js +5 -5
  6. package/dist/chunks/{add-to-dashboard-ClhEIFst.js → add-to-dashboard-CFF-wFU-.js} +1 -1
  7. package/dist/chunks/{analytics-base-schemas-DevrgqQb.js → analytics-base-schemas-DsUh5Q3C.js} +14 -12
  8. package/dist/chunks/{assistant-chat-BE0XXzZP.js → assistant-chat-B6hNQI1t.js} +146 -146
  9. package/dist/chunks/{bookmark-impact-DXDAN5AY.js → bookmark-impact-Ba2PLcGp.js} +3 -3
  10. package/dist/chunks/{bookmark-state-BMyB3Tb6.js → bookmark-state-n7AaNzR_.js} +517 -516
  11. package/dist/chunks/{card-filter-builder-CE0-YVN5.js → card-filter-builder-Y22HizVx.js} +474 -474
  12. package/dist/chunks/{comparison-window-caption-Dxj2CHOa.js → comparison-window-caption-Ck2TIbnR.js} +69 -69
  13. package/dist/chunks/{context-BJoEFgNl.js → context-UCQ7sere.js} +1 -1
  14. package/dist/chunks/{dashboard-mJKPFRbb.js → dashboard-BghI99oY.js} +1 -1
  15. package/dist/chunks/{dashboard-briefing-launcher-CntwKyiZ.js → dashboard-briefing-launcher-DtBAnGiH.js} +725 -716
  16. package/dist/chunks/{dashboard-controls-XO089DMg.js → dashboard-controls-CtFXlyjV.js} +53 -53
  17. package/dist/chunks/{dashboard-json-CQRiydUv.js → dashboard-json-DfGBUtCd.js} +5 -5
  18. package/dist/chunks/dates-BnrXF4bb.js +185 -0
  19. package/dist/chunks/{edit-dashboard-visual-f-Dm-BLR.js → edit-dashboard-visual-oxt3x1wb.js} +8081 -8268
  20. package/dist/chunks/{filter-line-CKNMyNTQ.js → filter-line-Cy5YYqRL.js} +27 -27
  21. package/dist/chunks/{filter-reach-copy-B8GGyVuR.js → filter-reach-copy-CE_ZX147.js} +1786 -2214
  22. package/dist/chunks/{filter-value-text-CRtKecI5.js → filter-value-text-fWvSDwkl.js} +11 -11
  23. package/dist/chunks/{index-DoPApnxg.js → index-D5rxbtS4.js} +24 -24
  24. package/dist/chunks/{layout-grid-CiSCZdIr.js → layout-grid-9LndRoLa.js} +1 -1
  25. package/dist/chunks/{matrix-analytical-definition-myf3D3Qx.js → matrix-analytical-definition-CCp48UCw.js} +496 -425
  26. package/dist/chunks/matrix-member-presentation-zNehruXR.js +391 -0
  27. package/dist/chunks/{matrix-operation-contract-C1SuOHLZ.js → matrix-operation-contract-DPBj69D8.js} +518 -514
  28. package/dist/chunks/{metric-comparison-Cm0G893W.js → metric-comparison-B0FR-Q8I.js} +184 -125
  29. package/dist/chunks/{paintbrush-DQIwqlck.js → paintbrush-58FQYY-y.js} +1 -1
  30. package/dist/chunks/{palette-Cun747Rg.js → palette-Be62Tkoa.js} +1 -1
  31. package/dist/chunks/{pivot-result-contract-expectations-C1Dyx8du.js → pivot-result-contract-expectations-BYqAmG9n.js} +1236 -1190
  32. package/dist/chunks/{pivot-result-identity-CBS-ssEp.js → pivot-result-identity-CAP4--iq.js} +1 -1
  33. package/dist/chunks/raw-temporal-value-Dg_MTFF7.js +3778 -0
  34. package/dist/chunks/{report-preferences-dialog-SDZEcG2x.js → report-preferences-dialog-uJp9GBTM.js} +219 -205
  35. package/dist/chunks/{report-runtime-context-BbedQdtc.js → report-runtime-context-c77_KF9v.js} +2 -2
  36. package/dist/chunks/{resolve-dashboard-input-context-DRBS0eRa.js → resolve-dashboard-input-context-Rtl1ffmE.js} +8808 -7291
  37. package/dist/chunks/{save-Dj5bjm7P.js → save-C5A0JnEV.js} +1 -1
  38. package/dist/chunks/{saved-dashboard-context-DWVlJcsa.js → saved-dashboard-context-tcyTU8jm.js} +199 -213
  39. package/dist/chunks/selection-filter-compiler-DNijjI5y.js +150 -0
  40. package/dist/chunks/{semaphor-ready-indicator-OFOoAY-A.js → semaphor-ready-indicator-FBvunj6S.js} +37894 -35726
  41. package/dist/chunks/{shelf-drop-preview-context-2swWypXu.js → shelf-drop-preview-context-QKStrcK9.js} +54 -54
  42. package/dist/chunks/{stored-dashboard-NtOuEX6a.js → stored-dashboard-CHozcAY9.js} +770 -743
  43. package/dist/chunks/{style-sheet-parts-Qv4UcLAo.js → style-sheet-parts-CDCG-8Ej.js} +258 -251
  44. package/dist/chunks/{table-export-sheet-Do7ZB0_F.js → table-export-sheet-ZFIvs6Sj.js} +1 -1
  45. package/dist/chunks/{token-types-Dy_aXO-U.js → token-types-XbM6QByy.js} +1 -1
  46. package/dist/chunks/{upload-Bq-puSVy.js → upload-H15d7uHK.js} +1 -1
  47. package/dist/chunks/{validators-C7DFk3QK.js → validators-Baf3VIf5.js} +5 -5
  48. package/dist/chunks/{variable-draft-Cy03qnEi.js → variable-draft-C2y8Jp6Z.js} +27 -28
  49. package/dist/dashboard/index.js +2 -2
  50. package/dist/dashboard-authoring/index.js +3392 -2761
  51. package/dist/format-utils/index.js +205 -204
  52. package/dist/index.js +73 -75
  53. package/dist/report-runtime-context/index.js +2 -2
  54. package/dist/style.css +1 -1
  55. package/dist/surfboard/index.js +2 -2
  56. package/dist/types/components/dashboard/dashboard-web-component.d.ts +7 -0
  57. package/dist/types/components/ui-custom/date-range-presets.d.ts +8 -0
  58. package/dist/types/index.js +5 -5
  59. package/dist/types/lib/dashboard-inputs/dashboard-input-target-context.d.ts +1 -1
  60. package/dist/types/lib/document/document-edits.d.ts +0 -4
  61. package/dist/types/lib/query-context/assemble-card-query.d.ts +6 -1
  62. package/dist/types/lib/stores/dashboard-store.d.ts +30 -1
  63. package/dist/types/lib/types/common-types.d.ts +0 -2
  64. package/dist/types/lib/types/explorer-types.d.ts +1 -1
  65. package/dist/types/shared/analytics-protocol/aggregate-expression.d.ts +15 -0
  66. package/dist/types/shared/analytics-protocol/analytics-base-schemas.d.ts +18 -0
  67. package/dist/types/shared/analytics-protocol/analyze-result-types.d.ts +3 -0
  68. package/dist/types/shared/analytics-protocol/comparison-choices.d.ts +92 -0
  69. package/dist/types/shared/analytics-protocol/comparison-placement.d.ts +30 -0
  70. package/dist/types/shared/analytics-protocol/contracts.d.ts +11 -5
  71. package/dist/types/shared/analytics-protocol/date-window.d.ts +105 -0
  72. package/dist/types/shared/analytics-protocol/filter-field-ownership.d.ts +27 -0
  73. package/dist/types/shared/analytics-protocol/fixtures.d.ts +4 -2
  74. package/dist/types/shared/analytics-protocol/index.d.ts +3 -0
  75. package/dist/types/shared/analytics-protocol/metric-comparison.d.ts +93 -11
  76. package/dist/types/shared/assistant-protocol/context.d.ts +16 -16
  77. package/dist/types/shared/dashboard-authoring/calculations/calculated-column.d.ts +52 -0
  78. package/dist/types/shared/dashboard-authoring/calculations/definition.d.ts +129 -0
  79. package/dist/types/shared/dashboard-authoring/calculations/resolve-dashboard-field-copies.d.ts +46 -0
  80. package/dist/types/shared/dashboard-authoring/calculations/tokens.d.ts +36 -0
  81. package/dist/types/shared/dashboard-authoring/card-settings/card-display-write.d.ts +8 -0
  82. package/dist/types/shared/dashboard-authoring/card-settings/card-kinds.d.ts +1 -1
  83. package/dist/types/shared/dashboard-authoring/card-settings/inputs.d.ts +2 -1
  84. package/dist/types/shared/dashboard-authoring/card-settings/resolved.d.ts +0 -3
  85. package/dist/types/shared/dashboard-authoring/changes/calculation-change.d.ts +399 -0
  86. package/dist/types/shared/dashboard-authoring/changes/dashboard-change.d.ts +165 -360
  87. package/dist/types/shared/dashboard-authoring/changes/diagnostics.d.ts +23 -2
  88. package/dist/types/shared/dashboard-authoring/changes/domain-change.d.ts +143 -266
  89. package/dist/types/shared/dashboard-authoring/changes/read-card-query.d.ts +2 -0
  90. package/dist/types/shared/dashboard-authoring/changes/resolve-dashboard-changes.d.ts +46 -0
  91. package/dist/types/shared/dashboard-authoring/conditional-formatting/schema.d.ts +10 -10
  92. package/dist/types/shared/dashboard-authoring/dashboard-variable-card.d.ts +2 -4
  93. package/dist/types/shared/dashboard-authoring/index.d.ts +7 -1
  94. package/dist/types/shared/dashboard-authoring/kpi-date-context.d.ts +2 -0
  95. package/dist/types/shared/dashboard-authoring/kpi-figure.d.ts +18 -0
  96. package/dist/types/shared/dashboard-authoring/measure-calculations/comparison.d.ts +8 -7
  97. package/dist/types/shared/dashboard-authoring/measure-calculations/dates.d.ts +11 -1
  98. package/dist/types/shared/dashboard-authoring/measure-calculations/index.d.ts +2 -2
  99. package/dist/types/shared/dashboard-authoring/measure-calculations/options.d.ts +4 -0
  100. package/dist/types/shared/dashboard-authoring/measure-calculations/read.d.ts +18 -1
  101. package/dist/types/shared/dashboard-authoring/measure-calculations/resolve.d.ts +2 -0
  102. package/dist/types/shared/dashboard-authoring/measure-calculations/schemas.d.ts +46 -88
  103. package/dist/types/shared/dashboard-authoring/operations/calculated-field-operations.d.ts +158 -0
  104. package/dist/types/shared/dashboard-authoring/operations/card-operations.d.ts +71 -0
  105. package/dist/types/shared/dashboard-authoring/operations/operation-types.d.ts +17 -6
  106. package/dist/types/shared/dashboard-authoring/outline/outline-dashboard.d.ts +21 -0
  107. package/dist/types/shared/dashboard-authoring/outline/outline-filters.d.ts +3 -0
  108. package/dist/types/shared/format-utils/comparison-detail.d.ts +34 -0
  109. package/dist/types/shared/format-utils/index.d.ts +1 -0
  110. package/dist/types/shared/format-utils/partial-period.d.ts +4 -2
  111. package/dist/types/shared/temporal/calendar-periods.d.ts +11 -0
  112. package/dist/types/shared/temporal/index.d.ts +2 -0
  113. package/dist/types/shared/temporal/temporal-text.d.ts +33 -0
  114. package/dist/types/shared/temporal/temporal.d.ts +27 -0
  115. package/dist/types/shared/temporal/zoned-wall-clock.d.ts +4 -3
  116. package/dist/types/shared/usage-events/details.d.ts +2 -2
  117. package/dist/types/shared/usage-events/envelope.d.ts +2 -2
  118. package/dist/usage-events/index.js +1 -1
  119. package/package.json +3 -2
  120. package/dist/chunks/dates-B-Urp5OD.js +0 -164
  121. package/dist/chunks/matrix-member-presentation-g0c_NpDW.js +0 -258
  122. package/dist/chunks/raw-temporal-value-DN_l-Tss.js +0 -454
  123. package/dist/chunks/selection-filter-compiler-DmAr7yqC.js +0 -131
@@ -905,12 +905,12 @@ export declare const conditionalRuleSchema: z.ZodObject<{
905
905
  kind: "matrixLevel";
906
906
  levelId: string;
907
907
  };
908
+ range: "auto" | "manual";
908
909
  colors: {
909
910
  max: string;
910
911
  min: string;
911
912
  mid?: string | undefined;
912
913
  };
913
- range: "auto" | "manual";
914
914
  max?: number | undefined;
915
915
  min?: number | undefined;
916
916
  mid?: number | undefined;
@@ -938,12 +938,12 @@ export declare const conditionalRuleSchema: z.ZodObject<{
938
938
  kind: "matrixLevel";
939
939
  levelId: string;
940
940
  };
941
+ range: "auto" | "manual";
941
942
  colors: {
942
943
  max: string;
943
944
  min: string;
944
945
  mid?: string | undefined;
945
946
  };
946
- range: "auto" | "manual";
947
947
  max?: number | undefined;
948
948
  min?: number | undefined;
949
949
  mid?: number | undefined;
@@ -1678,12 +1678,12 @@ export declare const conditionalRuleSchema: z.ZodObject<{
1678
1678
  kind: "matrixLevel";
1679
1679
  levelId: string;
1680
1680
  };
1681
+ range: "auto" | "manual";
1681
1682
  colors: {
1682
1683
  max: string;
1683
1684
  min: string;
1684
1685
  mid?: string | undefined;
1685
1686
  };
1686
- range: "auto" | "manual";
1687
1687
  max?: number | undefined;
1688
1688
  min?: number | undefined;
1689
1689
  mid?: number | undefined;
@@ -1948,12 +1948,12 @@ export declare const conditionalRuleSchema: z.ZodObject<{
1948
1948
  kind: "matrixLevel";
1949
1949
  levelId: string;
1950
1950
  };
1951
+ range: "auto" | "manual";
1951
1952
  colors: {
1952
1953
  max: string;
1953
1954
  min: string;
1954
1955
  mid?: string | undefined;
1955
1956
  };
1956
- range: "auto" | "manual";
1957
1957
  max?: number | undefined;
1958
1958
  min?: number | undefined;
1959
1959
  mid?: number | undefined;
@@ -2839,12 +2839,12 @@ export declare const cardConditionalFormattingSchema: z.ZodObject<{
2839
2839
  kind: "matrixLevel";
2840
2840
  levelId: string;
2841
2841
  };
2842
+ range: "auto" | "manual";
2842
2843
  colors: {
2843
2844
  max: string;
2844
2845
  min: string;
2845
2846
  mid?: string | undefined;
2846
2847
  };
2847
- range: "auto" | "manual";
2848
2848
  max?: number | undefined;
2849
2849
  min?: number | undefined;
2850
2850
  mid?: number | undefined;
@@ -2872,12 +2872,12 @@ export declare const cardConditionalFormattingSchema: z.ZodObject<{
2872
2872
  kind: "matrixLevel";
2873
2873
  levelId: string;
2874
2874
  };
2875
+ range: "auto" | "manual";
2875
2876
  colors: {
2876
2877
  max: string;
2877
2878
  min: string;
2878
2879
  mid?: string | undefined;
2879
2880
  };
2880
- range: "auto" | "manual";
2881
2881
  max?: number | undefined;
2882
2882
  min?: number | undefined;
2883
2883
  mid?: number | undefined;
@@ -3612,12 +3612,12 @@ export declare const cardConditionalFormattingSchema: z.ZodObject<{
3612
3612
  kind: "matrixLevel";
3613
3613
  levelId: string;
3614
3614
  };
3615
+ range: "auto" | "manual";
3615
3616
  colors: {
3616
3617
  max: string;
3617
3618
  min: string;
3618
3619
  mid?: string | undefined;
3619
3620
  };
3620
- range: "auto" | "manual";
3621
3621
  max?: number | undefined;
3622
3622
  min?: number | undefined;
3623
3623
  mid?: number | undefined;
@@ -3882,12 +3882,12 @@ export declare const cardConditionalFormattingSchema: z.ZodObject<{
3882
3882
  kind: "matrixLevel";
3883
3883
  levelId: string;
3884
3884
  };
3885
+ range: "auto" | "manual";
3885
3886
  colors: {
3886
3887
  max: string;
3887
3888
  min: string;
3888
3889
  mid?: string | undefined;
3889
3890
  };
3890
- range: "auto" | "manual";
3891
3891
  max?: number | undefined;
3892
3892
  min?: number | undefined;
3893
3893
  mid?: number | undefined;
@@ -4155,12 +4155,12 @@ export declare const cardConditionalFormattingSchema: z.ZodObject<{
4155
4155
  kind: "matrixLevel";
4156
4156
  levelId: string;
4157
4157
  };
4158
+ range: "auto" | "manual";
4158
4159
  colors: {
4159
4160
  max: string;
4160
4161
  min: string;
4161
4162
  mid?: string | undefined;
4162
4163
  };
4163
- range: "auto" | "manual";
4164
4164
  max?: number | undefined;
4165
4165
  min?: number | undefined;
4166
4166
  mid?: number | undefined;
@@ -4428,12 +4428,12 @@ export declare const cardConditionalFormattingSchema: z.ZodObject<{
4428
4428
  kind: "matrixLevel";
4429
4429
  levelId: string;
4430
4430
  };
4431
+ range: "auto" | "manual";
4431
4432
  colors: {
4432
4433
  max: string;
4433
4434
  min: string;
4434
4435
  mid?: string | undefined;
4435
4436
  };
4436
- range: "auto" | "manual";
4437
4437
  max?: number | undefined;
4438
4438
  min?: number | undefined;
4439
4439
  mid?: number | undefined;
@@ -2,7 +2,7 @@ import { TChartType } from '../../lib/charts/types.js';
2
2
  import { DataVariable, TCard, TextVariablePresentation } from '../../lib/types/common-types.js';
3
3
  import { QueryColumnKeyMap } from '../../lib/types/explorer-types.js';
4
4
  import { SemaphorFilterReachEntry, SemaphorResultColumn } from '../analytics-protocol/index.js';
5
- import { ComparisonUnavailableReason, MetricComparisonMetadataMap, MetricComparisonSpec } from '../analytics-protocol/metric-comparison.js';
5
+ import { ComparisonShiftSpec, ComparisonUnavailableReason, MetricComparisonMetadataMap } from '../analytics-protocol/metric-comparison.js';
6
6
  /**
7
7
  * The card type every answer runs as: non-paginated (`isPaginatedCardType`),
8
8
  * so the server applies `rowLimit` as the query's limit, and never the KPI
@@ -42,9 +42,7 @@ export declare function comparisonPartPresentation(part: string, presentation: T
42
42
  * measure as a card's is, on a numeric aggregate. Undefined for any other
43
43
  * variable, and for `off` or a target, which a variable is not offered.
44
44
  */
45
- export declare function variableComparison(variable: Pick<DataVariable, 'query' | 'get'>): Extract<MetricComparisonSpec, {
46
- kind: 'previous_period' | 'previous_year';
47
- }> | undefined;
45
+ export declare function variableComparison(variable: Pick<DataVariable, 'query' | 'get'>): ComparisonShiftSpec | undefined;
48
46
  /**
49
47
  * The card a variable runs as: its id, its name, its stored query and the
50
48
  * row limit its `get` needs. Memoized per variable object, so a variable keeps
@@ -50,7 +50,8 @@ export * from './changes/card-query-part.js';
50
50
  export * from './changes/read-card-query.js';
51
51
  export * from './changes/dashboard-change.js';
52
52
  export * from './changes/domain-change.js';
53
- export { resolveDashboardChanges, type CardSource, type ChangeServices, type ChangeRef, type ChangeResolution, } from './changes/resolve-dashboard-changes.js';
53
+ export * from './changes/calculation-change.js';
54
+ export { resolveDashboardChanges, type CalculationCompileRequest, type CalculationCompileResult, type CardSource, type ChangeServices, type ChangeRef, type ChangeResolution, } from './changes/resolve-dashboard-changes.js';
54
55
  export * from './changes/resolve-dashboard-create.js';
55
56
  export * from './text-card-words/index.js';
56
57
  export * from './outline/outline-filters.js';
@@ -88,3 +89,8 @@ export * from './filter-reach-copy.js';
88
89
  export * from './variable-draft.js';
89
90
  export * from './variable-editability.js';
90
91
  export * from './dashboard-style/index.js';
92
+ export * from './calculations/tokens.js';
93
+ export * from './calculations/calculated-column.js';
94
+ export * from './calculations/definition.js';
95
+ export * from './calculations/resolve-dashboard-field-copies.js';
96
+ export * from './operations/calculated-field-operations.js';
@@ -124,9 +124,11 @@ export type KpiDateContextView = {
124
124
  kind: PeriodComparisonKind;
125
125
  };
126
126
  /** Why the card's period comparison is off, when it is. */
127
+ /** `label`: the comparison's own words when the run names its request ("Same day last week"). */
127
128
  comparisonOff?: {
128
129
  kind: PeriodComparisonKind;
129
130
  reason: ComparisonUnavailableReason;
131
+ label?: string;
130
132
  };
131
133
  /**
132
134
  * Two applied windows narrow each other, so the number counts only their
@@ -55,6 +55,15 @@ export declare const KPI_MEASURES_SHOWN = 3;
55
55
  export declare function resolveKpiLayout(input: {
56
56
  config?: Pick<CardConfig, 'metricColumns' | 'groupByColumns'>;
57
57
  }): KpiLayout;
58
+ /**
59
+ * Whether a KPI compares its first metric with its second ("Other metric",
60
+ * compare-with CW-D29): the one reading of the pair setting. The pair shows
61
+ * only in the measures layout (`resolveKpiLayout`: exactly two metrics, no
62
+ * Trend By, no target) and not on a card saved hidden (CW-D28), so a stored
63
+ * setting the layout doesn't draw reads as no pair. The tile, the editor, the
64
+ * outline and the offer read it (ledger P4-14).
65
+ */
66
+ export declare function comparesMetricPair(card: Pick<TCard, 'type' | 'preferences' | 'config'>): boolean;
58
67
  /**
59
68
  * A config KPI's result rows. Every row names its measure; `current` is a
60
69
  * measure's value and `comparison` its prior or target, in every branch.
@@ -113,6 +122,15 @@ export type KpiComparison = {
113
122
  kind: 'previous_period' | 'previous_year' | 'target';
114
123
  /** "Previous", "Target" or `comparisonPresentation.labelName`. */
115
124
  label: string;
125
+ /**
126
+ * The comparison's own words as the run names it ("same day last week",
127
+ * "previous 7 days"; compare-with 4b), when the author set no label of
128
+ * their own: the tile reads "vs same day last week · 150". Today's saved
129
+ * default label "Previous" counts as none, so it follows the words.
130
+ */
131
+ words?: string;
132
+ /** The measure keeps its own comparison whatever the Date filter says (compare-with CW-D17, CW-D20): the tile shows a pin. */
133
+ pinned: boolean;
116
134
  /** False when the author turned it off (`comparisonPresentation.showComparison`). */
117
135
  shown: boolean;
118
136
  /** From `evaluateMetricComparison`, the only source of a change (KV-D8). */
@@ -2,17 +2,18 @@ import { MetricComparisonConfig } from '../../analytics-protocol/metric-comparis
2
2
  import { ExplicitComparison, MeasureComparison } from './schemas.js';
3
3
  /**
4
4
  * A measure's comparison between its public words and its stored field
5
- * (reports by conversation SPEC §3.2, S-6, S-7): the one mapping. Stored
6
- * minimal, as the editor stores it: `inherit` is no field, and an offset of
7
- * 1, `calendar` and a false `toDate` are absent.
5
+ * (reports by conversation SPEC §3.2, S-6, S-7; compare-with CW-D3, CW-D5):
6
+ * the one mapping. The words are the spec's own (`shift` or `target`); a
7
+ * stored shape from before Compare with is read through the one reader.
8
+ * Stored minimal: `inherit` is no field, and an offset of 1 is absent.
8
9
  */
9
10
  /** The stored comparison for public words; undefined for `inherit` (no field). */
10
11
  export declare function toStoredComparison(comparison: MeasureComparison): MetricComparisonConfig | undefined;
11
12
  /** The public words for a stored comparison, defaults left out; undefined when it has none of its own (`inherit`). */
12
13
  export declare function readStoredComparison(stored: MetricComparisonConfig | undefined): MeasureComparison | undefined;
13
- /** Whether a stated comparison means what the measure stores (equal by resolution, S-7). */
14
- export declare function sameComparison(stated: MeasureComparison, stored: MetricComparisonConfig | undefined): boolean;
15
- /** A comparison of the measure's own: a period, a year or a target (not `inherit` or `off`). */
14
+ /** Whether two comparisons say the same, read in full (`inherit` for none of its own, an offset of 1 for none; S-7). */
15
+ export declare function sameWords(left: MeasureComparison | undefined, right: MeasureComparison | undefined): boolean;
16
+ /** A comparison of the measure's own: a step back or a target (not `inherit` or `off`). */
16
17
  export declare const isExplicitComparison: (comparison: MeasureComparison | undefined) => comparison is ExplicitComparison;
17
- /** "the same period last year", "a target of 1,000,000": what a stored comparison compares with. */
18
+ /** "the previous period", "the same period last year, matching weekdays", "a target of 1,000,000": what a stored comparison compares with. */
18
19
  export declare function comparedWith(comparison: MetricComparisonConfig): string;
@@ -1,6 +1,7 @@
1
1
  import { TCard, TDashboard } from '../../../lib/types/common-types.js';
2
2
  import { SemanticExecutionPayload } from '../../../lib/types/semantic-runtime-types.js';
3
3
  import { CompiledDashboardCardFilters } from '../../../lib/query-context/compile-dashboard-card-filters.js';
4
+ import { ComparisonWindowShape } from '../../analytics-protocol/comparison-choices.js';
4
5
  import { ResolvedPrimaryDateField } from '../../analytics-protocol/contracts.js';
5
6
  import { CalendarContext } from '../../report-runtime-context/index.js';
6
7
  export type ComparisonDates = {
@@ -11,6 +12,14 @@ export type ComparisonDates = {
11
12
  } | null;
12
13
  /** Whether a date window applies to that date: the card's own window on it, or a dashboard date filter that reaches the card. */
13
14
  dateWindow: 'applies' | 'none' | 'unknown';
15
+ /**
16
+ * The shape of the window the comparison steps from, when exactly one range
17
+ * restricts the date after Global Date ownership (`withGlobalDateOwnership`,
18
+ * the run's own rule): a Global Date value replaces the card's own range,
19
+ * every other range intersects, so two ranges leave the window unknown and
20
+ * nothing is judged to overlap (compare-with CW-D16, CW16-R1).
21
+ */
22
+ window?: ComparisonWindowShape;
14
23
  };
15
24
  /**
16
25
  * What `readComparisonDates` reads of a compiled card query: the editor's
@@ -26,7 +35,7 @@ export type ComparisonCompilation = {
26
35
  resolvedPrimaryDateField?: ResolvedPrimaryDateField;
27
36
  };
28
37
  /** The two facts for a card, from its compiled query. */
29
- export declare function readComparisonDates(card: TCard, compiled: ComparisonCompilation): ComparisonDates;
38
+ export declare function readComparisonDates(card: TCard, compiled: ComparisonCompilation, calendar?: CalendarContext | null): ComparisonDates;
30
39
  /**
31
40
  * The same facts as a fresh viewer gets them (SPEC S-9): the dashboard's
32
41
  * default filter values, compiled with this calendar, through the assembly a
@@ -35,6 +44,7 @@ export declare function readComparisonDates(card: TCard, compiled: ComparisonCom
35
44
  */
36
45
  export declare function readDefaultComparisonDates(input: {
37
46
  dashboard: TDashboard;
47
+ /** A card's id, or a data variable's: a variable runs as its projected card at each sheet its text shows on (DV-D32). */
38
48
  cardId: string;
39
49
  semanticExecutionPayload: SemanticExecutionPayload | undefined;
40
50
  calendar: CalendarContext;
@@ -4,8 +4,8 @@
4
4
  * The outline, the change resolver, the reducer, the editor and
5
5
  * semaphor_analyze read and write them through these exports only.
6
6
  */
7
- export { explicitComparisonSchema, measureComparisonSchema, measureTransformSchema, transformOrderSchema, MEASURE_CALCULATION_SUMMARIES, type AnalyzeMeasureCalculations, type ExplicitComparison, type MeasureCalculations, type MeasureComparison, type MeasureTransform, type TransformOrder, } from './schemas.js';
8
- export { toStoredComparison } from './comparison.js';
7
+ export { comparisonShiftSchema, explicitComparisonSchema, MATCH_WEEKDAYS_ONLY_BY_YEARS, measureComparisonSchema, TO_DATE_IS_AUTOMATIC, measureTransformSchema, transformOrderSchema, MEASURE_CALCULATION_SUMMARIES, type AnalyzeMeasureCalculations, type ExplicitComparison, type MeasureCalculations, type MeasureComparison, type MeasureTransform, type TransformOrder, } from './schemas.js';
8
+ export { readStoredComparison, sameWords, toStoredComparison } from './comparison.js';
9
9
  export { readMeasureCalculations, type MeasureCalculationsRead } from './read.js';
10
10
  export { readComparisonDates, readDefaultComparisonDates, type ComparisonCompilation, type ComparisonDates } from './dates.js';
11
11
  export { measureCalculationOptions, transformGroupings, PUBLIC_TRANSFORM_KIND, type CalculationOffer, type CalculationRefusalCode, type MeasureCalculationOptions, type TransformGrouping, } from './options.js';
@@ -60,4 +60,8 @@ export declare function transformGroupings(card: TCard): {
60
60
  groupings: TransformGrouping[];
61
61
  defaultOrder: ColumnKey | null;
62
62
  };
63
+ /** Whether a card's measures show comparisons at all: a type that compares, built from fields (not SQL or Python). */
64
+ export declare function cardTakesComparisons(card: TCard): boolean;
65
+ /** Whether a measure can compare with the other metric: the first of a KPI's two metrics, where the layout draws the pair (`resolveKpiLayout`: no Trend By, no target; CW-D29, ledger P4-14). */
66
+ export declare function metricPairOffered(card: TCard, metric: MetricField): boolean;
63
67
  export declare function measureCalculationOptions(card: TCard, measure: ColumnKey, dates: ComparisonDates): MeasureCalculationOptions;
@@ -1,7 +1,7 @@
1
1
  import { TCard } from '../../../lib/types/common-types.js';
2
2
  import { GroupByField } from '../../../lib/types/explorer-types.js';
3
3
  import { FieldRef } from '../changes/dashboard-change.js';
4
- import { MeasureCalculations } from './schemas.js';
4
+ import { MeasureCalculations, MeasureComparison } from './schemas.js';
5
5
  export type MeasureCalculationsRead =
6
6
  /** Aligned with `config.metricColumns`; `{}` for a measure with none. */
7
7
  {
@@ -13,4 +13,21 @@ export type MeasureCalculationsRead =
13
13
  ok: false;
14
14
  detail: string;
15
15
  };
16
+ /**
17
+ * Each measure's comparison as it shows, aligned with `config.metricColumns`
18
+ * (compare-with CW-D18, CW-D21, CW-D28): its own step or target; `off` when it
19
+ * shows none, including every measure of a card saved with "Show comparison"
20
+ * off and one with none of its own on a card that stopped following;
21
+ * undefined when it follows the Date filter. The one reader decides, so the
22
+ * outline says what the card shows and no card switch is left to read. On a
23
+ * card that shows no comparisons (a pie, SQL) each reads as it is stored.
24
+ */
25
+ export declare function readMeasureComparisons(card: TCard): (MeasureComparison | undefined)[];
26
+ /**
27
+ * Whether a stated comparison changes nothing on this measure: equal to what
28
+ * the outline reads for it, not to what it stores (ledger CW15-03; CW-D21,
29
+ * CW-D28, CW-D29). Following on a card that stopped following, the stored step
30
+ * on a card saved hidden, or the other metric on a hidden pair, is a change.
31
+ */
32
+ export declare function comparisonUnchanged(card: TCard, stated: MeasureComparison, index: number): boolean;
16
33
  export declare function readMeasureCalculations(card: TCard, groupingRef: (grouping: GroupByField) => FieldRef): MeasureCalculationsRead;
@@ -55,6 +55,8 @@ export type ResolvedMeasureCalculations = {
55
55
  };
56
56
  /** What this write replaces, for its sentence (RC-D6, RC-INV-3). */
57
57
  replaces?: 'comparison' | 'transform';
58
+ /** The card compares its first metric with the second (`true`) or no longer does (`false`), compare-with CW-D29. */
59
+ metricPair?: boolean;
58
60
  };
59
61
  /** One `calculations` card update: the measures it changes, in card order. */
60
62
  export type MeasureCalculationsUpdate = {
@@ -1,36 +1,7 @@
1
1
  import { z } from 'zod';
2
- /** A comparison of the measure's own, in the stored spec's names: what `semaphor_analyze` takes. */
3
- export declare const explicitComparisonSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
4
- kind: z.ZodLiteral<"previous_period">;
5
- offsetPeriods: z.ZodOptional<z.ZodNumber>;
6
- alignment: z.ZodOptional<z.ZodEnum<["calendar", "weekday"]>>;
7
- toDate: z.ZodOptional<z.ZodBoolean>;
8
- }, "strict", z.ZodTypeAny, {
9
- kind: "previous_period";
10
- toDate?: boolean | undefined;
11
- alignment?: "calendar" | "weekday" | undefined;
12
- offsetPeriods?: number | undefined;
13
- }, {
14
- kind: "previous_period";
15
- toDate?: boolean | undefined;
16
- alignment?: "calendar" | "weekday" | undefined;
17
- offsetPeriods?: number | undefined;
18
- }>, z.ZodObject<{
19
- kind: z.ZodLiteral<"previous_year">;
20
- offsetYears: z.ZodOptional<z.ZodNumber>;
21
- alignment: z.ZodOptional<z.ZodEnum<["calendar", "weekday"]>>;
22
- toDate: z.ZodOptional<z.ZodBoolean>;
23
- }, "strict", z.ZodTypeAny, {
24
- kind: "previous_year";
25
- toDate?: boolean | undefined;
26
- alignment?: "calendar" | "weekday" | undefined;
27
- offsetYears?: number | undefined;
28
- }, {
29
- kind: "previous_year";
30
- toDate?: boolean | undefined;
31
- alignment?: "calendar" | "weekday" | undefined;
32
- offsetYears?: number | undefined;
33
- }>, z.ZodObject<{
2
+ /** Refused with its reason: every running window is compared to date (compare-with CW-D1, CW-D2). */
3
+ export declare const TO_DATE_IS_AUTOMATIC = "is not a setting: a comparison always matches the elapsed part of a window still running; leave it out";
4
+ declare const targetSchema: z.ZodObject<{
34
5
  kind: z.ZodLiteral<"target">;
35
6
  targetValue: z.ZodNumber;
36
7
  }, "strict", z.ZodTypeAny, {
@@ -39,60 +10,49 @@ export declare const explicitComparisonSchema: z.ZodDiscriminatedUnion<"kind", [
39
10
  }, {
40
11
  kind: "target";
41
12
  targetValue: number;
42
- }>]>;
43
- /** A card measure's comparison: its own, none (`off`), or the dashboard's (`inherit`). */
44
- declare const measureComparisonUnion: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
45
- kind: z.ZodLiteral<"inherit">;
46
- }, "strict", z.ZodTypeAny, {
47
- kind: "inherit";
48
- }, {
49
- kind: "inherit";
50
- }>, z.ZodObject<{
51
- kind: z.ZodLiteral<"off">;
52
- }, "strict", z.ZodTypeAny, {
53
- kind: "off";
54
- }, {
55
- kind: "off";
56
- }>, z.ZodObject<{
57
- kind: z.ZodLiteral<"previous_period">;
58
- offsetPeriods: z.ZodOptional<z.ZodNumber>;
59
- alignment: z.ZodOptional<z.ZodEnum<["calendar", "weekday"]>>;
60
- toDate: z.ZodOptional<z.ZodBoolean>;
61
- }, "strict", z.ZodTypeAny, {
62
- kind: "previous_period";
63
- toDate?: boolean | undefined;
64
- alignment?: "calendar" | "weekday" | undefined;
65
- offsetPeriods?: number | undefined;
66
- }, {
67
- kind: "previous_period";
68
- toDate?: boolean | undefined;
69
- alignment?: "calendar" | "weekday" | undefined;
70
- offsetPeriods?: number | undefined;
71
- }>, z.ZodObject<{
72
- kind: z.ZodLiteral<"previous_year">;
73
- offsetYears: z.ZodOptional<z.ZodNumber>;
74
- alignment: z.ZodOptional<z.ZodEnum<["calendar", "weekday"]>>;
75
- toDate: z.ZodOptional<z.ZodBoolean>;
76
- }, "strict", z.ZodTypeAny, {
77
- kind: "previous_year";
78
- toDate?: boolean | undefined;
79
- alignment?: "calendar" | "weekday" | undefined;
80
- offsetYears?: number | undefined;
81
- }, {
82
- kind: "previous_year";
83
- toDate?: boolean | undefined;
84
- alignment?: "calendar" | "weekday" | undefined;
85
- offsetYears?: number | undefined;
86
- }>, z.ZodObject<{
87
- kind: z.ZodLiteral<"target">;
88
- targetValue: z.ZodNumber;
13
+ }>;
14
+ /** Refused with its reason (compare-with CW-D4). */
15
+ export declare const MATCH_WEEKDAYS_ONLY_BY_YEARS = "matchWeekdays is true only on a step by years (52 weeks a year back)";
16
+ /**
17
+ * A step back (compare-with CW-D3): `unit` 'period' is the window's own
18
+ * length (the previous period), or a calendar unit; `offset` steps.
19
+ */
20
+ declare const shiftSchema: z.ZodObject<{
21
+ kind: z.ZodLiteral<"shift">;
22
+ unit: z.ZodEnum<["period", "day", "week", "month", "quarter", "year"]>;
23
+ offset: z.ZodOptional<z.ZodNumber>;
24
+ matchWeekdays: z.ZodOptional<z.ZodLiteral<true>>;
25
+ toDate: z.ZodOptional<z.ZodNever>;
89
26
  }, "strict", z.ZodTypeAny, {
90
- kind: "target";
91
- targetValue: number;
27
+ kind: "shift";
28
+ unit: "day" | "week" | "month" | "quarter" | "year" | "period";
29
+ toDate?: undefined;
30
+ offset?: number | undefined;
31
+ matchWeekdays?: true | undefined;
92
32
  }, {
93
- kind: "target";
94
- targetValue: number;
95
- }>]>;
33
+ kind: "shift";
34
+ unit: "day" | "week" | "month" | "quarter" | "year" | "period";
35
+ toDate?: undefined;
36
+ offset?: number | undefined;
37
+ matchWeekdays?: true | undefined;
38
+ }>;
39
+ /** A step back alone, as a dashboard date filter's default comparison takes it (IN-08); old words refused with the new ones. */
40
+ export declare const comparisonShiftSchema: z.ZodType<z.infer<typeof shiftSchema>>;
41
+ /** A comparison of the measure's own, in the stored spec's words: a step back or a target. */
42
+ export type ExplicitComparison = z.infer<typeof shiftSchema> | z.infer<typeof targetSchema>;
43
+ /**
44
+ * A card measure's comparison: its own, none (`off`), the dashboard's
45
+ * (`inherit`), or, on the first of a KPI's two metrics, the other metric
46
+ * (`metric`, compare-with CW-D29).
47
+ */
48
+ export type MeasureComparison = {
49
+ kind: 'inherit';
50
+ } | {
51
+ kind: 'off';
52
+ } | {
53
+ kind: 'metric';
54
+ } | ExplicitComparison;
55
+ export declare const explicitComparisonSchema: z.ZodType<ExplicitComparison>;
96
56
  /** The grouping a transform runs along; `field` is written as the query writes that grouping. */
97
57
  export declare const transformOrderSchema: z.ZodObject<{
98
58
  field: z.ZodUnion<[z.ZodString, z.ZodObject<{
@@ -905,8 +865,6 @@ declare const measureTransformUnion: z.ZodDiscriminatedUnion<"kind", [z.ZodObjec
905
865
  } | undefined;
906
866
  })[] | undefined;
907
867
  }>]>;
908
- export type ExplicitComparison = z.infer<typeof explicitComparisonSchema>;
909
- export type MeasureComparison = z.infer<typeof measureComparisonUnion>;
910
868
  export type TransformOrder = z.infer<typeof transformOrderSchema>;
911
869
  export type MeasureTransform = z.infer<typeof measureTransformUnion>;
912
870
  export declare const measureComparisonSchema: z.ZodType<MeasureComparison>;
@@ -917,7 +875,7 @@ export type MeasureCalculations = {
917
875
  /** null only in a card.update: removes the transform. */
918
876
  transform?: MeasureTransform | null;
919
877
  };
920
- /** One semaphor_analyze measure's calculations: no dashboard to inherit, nothing to remove. */
878
+ /** One semaphor_analyze measure's calculations: a card measure's own words (compare-with CW-D24); no dashboard to inherit, nothing to remove. */
921
879
  export type AnalyzeMeasureCalculations = {
922
880
  comparison?: ExplicitComparison;
923
881
  transform?: MeasureTransform;
@@ -928,7 +886,7 @@ export type AnalyzeMeasureCalculations = {
928
886
  * against the definition budget (RC-D1).
929
887
  */
930
888
  export declare const MEASURE_CALCULATION_SUMMARIES: {
931
- readonly comparison: "{ kind: 'inherit' (the dashboard's; default) | 'off' | 'previous_period' | 'previous_year' (offsetPeriods or offsetYears?: n, alignment?: 'calendar' | 'weekday', toDate?: true) | 'target' (targetValue: number) }. Targets on kpi and table. A period or year compares over the card's date grouping (a KPI's Trend By: dateField with timeGrain) or the dataset's primary date.";
889
+ readonly comparison: "{ kind: 'inherit' (follows the Date filter; default) | 'off' (none) | 'shift' (unit: 'period' (its length) | 'day' | 'week' | 'month' | 'quarter' | 'year', offset?: n, matchWeekdays?: true if 'year') | 'target' (targetValue: number) }. Targets on kpi and table. A shift compares over the card's date grouping (a KPI's Trend By: dateField with timeGrain) or the dataset's primary date.";
932
890
  readonly transform: "{ kind: 'running_total' | 'moving_average' (window?: 7, minPeriods?: 1) | 'difference_from_previous' (mode?: 'difference' | 'percent_change') | 'percent_of_total' (scope?: 'grand_total' | 'partition_total' + resetBy, output?: 'percent' | 'fraction'), orderBy?: { field, direction? } (default: first date grouping), resetBy?: [fields] (default: other groupings) }; null removes it. Not beside its own comparison.";
933
891
  };
934
892
  export {};