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
@@ -1,5 +1,5 @@
1
- import { a, R as s, D as o } from "../chunks/report-preferences-dialog-SDZEcG2x.js";
2
- import { C as f, E as D } from "../chunks/bookmark-state-BMyB3Tb6.js";
1
+ import { a, R as s, D as o } from "../chunks/report-preferences-dialog-uJp9GBTM.js";
2
+ import { C as f, E as D } from "../chunks/bookmark-state-n7AaNzR_.js";
3
3
  export {
4
4
  f as CONTROL_CARD_DEFAULT_VALUE,
5
5
  a as DisplayFormatPreferencesFields,
@@ -1 +1,8 @@
1
+ /**
2
+ * The dashboard as a custom element, for a host to register in the browser
3
+ * (`customElements.define('semaphor-dashboard', DashboardWC)`). Built only
4
+ * where `HTMLElement` exists: the class extends it, and a server that imports
5
+ * this package (a host's server render) has no DOM and registers no elements,
6
+ * so there it is undefined. The build's server import check guards this.
7
+ */
1
8
  export declare const DashboardWC: CustomElementConstructor;
@@ -1,6 +1,7 @@
1
1
  import { DefaultDateFilter, FixedDayDefaultDateFilter, FixedMonthDefaultDateFilter } from '../surfboard/filter/types.js';
2
2
  import { WeekStart } from '../../lib/types/token-types.js';
3
3
  import { CalendarContext } from '../../shared/report-runtime-context/index.js';
4
+ import { ComparisonWindowShape } from '../../shared/analytics-protocol/comparison-choices.js';
4
5
  /** Calendar inputs for defaults, including reproducible and fiscal reports. */
5
6
  export type DefaultDateCalendar = Pick<CalendarContext, 'tz' | 'weekStart'> & Partial<Pick<CalendarContext, 'anchor' | 'fiscalCalendar'>>;
6
7
  export declare const isFixedMonthDefaultDateFilter: (value: unknown) => value is FixedMonthDefaultDateFilter;
@@ -26,4 +27,11 @@ export declare const isSingleDayDefaultDateFilter: (value: DefaultDateFilter | u
26
27
  * other window would filter on dates the control doesn't show.
27
28
  */
28
29
  export declare const isSingleMonthDefaultDateFilter: (value: DefaultDateFilter | undefined) => boolean;
30
+ /**
31
+ * A date default's window for the Compare with menu (compare-with CW-D7): a
32
+ * relative default's shape, a fixed day, or a fixed calendar month. Read from
33
+ * the stored default itself, so a fixed default is never unknown (review
34
+ * P2R-05: a fixed month offered a week back that overlaps it).
35
+ */
36
+ export declare function defaultDateFilterComparisonShape(meta: DefaultDateFilter | undefined): ComparisonWindowShape | undefined;
29
37
  export declare function resolveDefaultDateFilterForDefaults(meta: DefaultDateFilter, calendar: string | DefaultDateCalendar, weekStart?: WeekStart): [Date, Date] | undefined;
@@ -1,8 +1,8 @@
1
- import { B as t, z as r, C as l, E as o, V as i, j as n, c as d, g as m, f as u, b as c, e as E, d as C, a as T, y as p, x as D, o as A, h as I, q as _, w as F, v as S, m as b, n as L, l as f, p as N, k as y, s as R, u as h, i as g, r as x, t as M } from "../chunks/bookmark-state-BMyB3Tb6.js";
2
- import { C as V, D as w, L as z, d as U, g as k, e as B, h as K, f as v, c as Y, a as q, i as G, b as P, n as Q, s as W } from "../chunks/validators-C7DFk3QK.js";
3
- import { D as J } from "../chunks/token-types-Dy_aXO-U.js";
4
- import { r as H, a as Z } from "../chunks/pivot-result-identity-CBS-ssEp.js";
5
- import { D as ee } from "../chunks/report-runtime-context-BbedQdtc.js";
1
+ import { B as t, z as r, C as l, E as o, V as i, j as n, c as d, g as m, f as u, b as c, e as E, d as C, a as T, y as p, x as D, o as A, h as I, q as _, w as F, v as S, m as b, n as L, l as f, p as N, k as y, s as R, u as h, i as g, r as x, t as M } from "../chunks/bookmark-state-n7AaNzR_.js";
2
+ import { C as V, D as w, L as z, d as U, g as k, e as B, h as K, f as v, c as Y, a as q, i as G, b as P, n as Q, s as W } from "../chunks/validators-Baf3VIf5.js";
3
+ import { D as J } from "../chunks/token-types-XbM6QByy.js";
4
+ import { r as H, a as Z } from "../chunks/pivot-result-identity-CAP4--iq.js";
5
+ import { D as ee } from "../chunks/report-runtime-context-c77_KF9v.js";
6
6
  const e = [
7
7
  "concatenate",
8
8
  "conditional-category",
@@ -79,7 +79,7 @@ export type DashboardInputTargetContext = {
79
79
  knownFilterIds: ReadonlySet<string>;
80
80
  };
81
81
  export type BuildDashboardInputTargetContextInput = {
82
- dashboard: Pick<TDashboard, 'inputs' | 'filters' | 'controls' | 'sheets' | 'defaultInputValues'>;
82
+ dashboard: Pick<TDashboard, 'inputs' | 'filters' | 'controls' | 'sheets' | 'defaultInputValues' | 'calculatedFields'>;
83
83
  filter: TFilter;
84
84
  scope: DashboardInputTargetScope;
85
85
  /** The card a card-local target belongs to; lifts its inline inputs. */
@@ -1,5 +1,4 @@
1
1
  import { DocumentDefinition, DocumentKpiSection, DocumentSection, DocumentTableSection, DocumentTextContent, DocumentTextRegionBlock, DocumentTextStyle, TCard, TDashboard } from '../types/common-types.js';
2
- import { Field } from '../types/explorer-types.js';
3
2
  import { DashboardCardLocation } from '../../shared/dashboard-authoring/document-section-cards.js';
4
3
  import { DocumentPanelTarget } from './document-panel-target.js';
5
4
  import { DocumentIdFactory, DocumentSectionKindId } from './document-section-kinds.js';
@@ -71,7 +70,6 @@ export type DocumentEdit = {
71
70
  sectionId: string;
72
71
  oldCardId: string;
73
72
  card: TCard;
74
- calculatedFields?: Field[];
75
73
  }
76
74
  /** A placeholder KPI when neither `card` nor `source` is given. */
77
75
  | {
@@ -100,8 +98,6 @@ export type DocumentEditResult = {
100
98
  document: DocumentDefinition;
101
99
  /** Where the panel goes next: the inserted, moved or edited section, or a removed section's neighbor. */
102
100
  target: DocumentPanelTarget;
103
- /** The sheet's full calculated fields after a copy brought new ones; persist as the sheet's list. */
104
- calculatedFields?: Field[];
105
101
  /** Card ids removed (`to: null`) or replaced by a new id, for reference cleanup. */
106
102
  retargetedCardIds?: Array<{
107
103
  from: string;
@@ -1,7 +1,7 @@
1
1
  import { TFilterValue } from '../../components/surfboard/filter/types.js';
2
2
  import { CardViewStateMap } from '../dashboard-view-state/index.js';
3
3
  import { DashboardInputValues, ResolvedDashboardInputContext, TCard, TDashboard } from '../types/common-types.js';
4
- import { PaginationConfig } from '../types/explorer-types.js';
4
+ import { Field, PaginationConfig } from '../types/explorer-types.js';
5
5
  import { ResolvedPrimaryDateField, SemanticExecutionPayload } from '../types/semantic-runtime-types.js';
6
6
  import { TransientInputContext } from '../dashboard-inputs/transient-input-context.js';
7
7
  import { prepareMatrixCard, MatrixCardCatalog } from '../matrix-table/matrix-card-adapter.js';
@@ -63,6 +63,11 @@ export type CardQuerySource = {
63
63
  */
64
64
  editor?: {
65
65
  inlineFilterValuesMap: Record<string, TFilterValue[] | undefined>;
66
+ /**
67
+ * The dashboard fields as the editor holds them (its pending list while a
68
+ * card is open): the preview runs the definitions being edited (MC-D21).
69
+ */
70
+ calculatedFields?: readonly Field[];
66
71
  };
67
72
  };
68
73
  /** Where a card runs: a sheet of the dashboard, or a Document section with its own runtime. */
@@ -11,6 +11,7 @@ import { MissingPrintInputs } from '../print/print-inputs.js';
11
11
  import { default as ReactGridLayout } from 'react-grid-layout';
12
12
  import { CustomizableBreakpoint, EditableBreakpoint, FramePlacement, GridEditBreakpoint, LayoutItem } from '../../shared/layouts/index.js';
13
13
  import { DashboardOperation, OperationContext } from '../../shared/dashboard-authoring/operations/apply-dashboard-operations.js';
14
+ import { CalculatedFieldOperation } from '../../shared/dashboard-authoring/operations/calculated-field-operations.js';
14
15
  import { DashboardStyle } from '../../shared/dashboard-authoring/dashboard-style/types.js';
15
16
  import { FilterGroup, Field } from '../types/explorer-types.js';
16
17
  import { DashboardControlsModelOptions } from '../controls/control-authoring-types.js';
@@ -40,6 +41,12 @@ type AddFrameOptions = {
40
41
  /** By intent; absent: placed by kind (RL-D12). A duplicate passes `{ position: { beside: originalId } }`. */
41
42
  placement?: FramePlacement;
42
43
  semanticExecutionPayload?: SemanticExecutionPayload;
44
+ /**
45
+ * The frame is the visual editor's card saved as a copy (Save as): the
46
+ * editor's queued dashboard-field changes commit with it, all or nothing,
47
+ * and a refusal throws its reason with nothing changed (ledger P4-49).
48
+ */
49
+ withEditorFieldChanges?: boolean;
43
50
  };
44
51
  /**
45
52
  * A proposal the assistant applied in this edit session (analytics agent
@@ -162,6 +169,8 @@ export type DashboardStore = {
162
169
  * current frame.
163
170
  */
164
171
  visualEditPendingDashboardCalculatedFields?: Field[];
172
+ /** The dashboard-field operations the open card's edit made, applied with its commit (calculated fields one core MC-D11). */
173
+ visualEditPendingCalculatedFieldOps?: CalculatedFieldOperation[];
165
174
  /** Live edit-session check for host navigation; owned by dashboard controls. */
166
175
  checkUnsavedDashboardChanges: (() => boolean) | null;
167
176
  isDashboardEditing: boolean;
@@ -471,8 +480,28 @@ type Actions = {
471
480
  updateFrame: (sheetId: string, frame: TFrame, options?: {
472
481
  semanticExecutionPayload?: SemanticExecutionPayload;
473
482
  }) => void;
474
- updateSheetCalculatedFields: (sheetId: string, calculatedFields: Field[]) => void;
475
483
  updateDashboardCalculatedFields: (calculatedFields: Field[]) => void;
484
+ /** Whether the field changes a Document section card's edit made would apply with that card committed; asked before writing it. */
485
+ checkCalculatedFieldOps: (card: TCard, replacingCardId: string) => {
486
+ ok: true;
487
+ } | {
488
+ ok: false;
489
+ reason: string;
490
+ };
491
+ /** Whether `addFrame` with these options would apply, nothing changed: Save as asks before it creates a library visual (ledger P4-50). */
492
+ checkAddFrame: (sheetId: string, frame: TFrame, options?: AddFrameOptions) => {
493
+ ok: true;
494
+ } | {
495
+ ok: false;
496
+ reason: string;
497
+ };
498
+ /** Applies the field changes a Document section card's edit made, after its commit. */
499
+ commitCalculatedFieldOps: (editedCardId: string) => {
500
+ ok: true;
501
+ } | {
502
+ ok: false;
503
+ reason: string;
504
+ };
476
505
  setVisualEditPendingFrameRewrites: (sheetId: string, frames: TFrame[]) => void;
477
506
  clearVisualEditPendingFrameRewrites: (sheetId?: string) => void;
478
507
  updateCard: (sheetId: string, card: TCard) => void;
@@ -1431,7 +1431,6 @@ export type TFrame = {
1431
1431
  filterId?: string;
1432
1432
  cards: TCard[];
1433
1433
  activeCardId: string;
1434
- calculatedFields?: Field[];
1435
1434
  };
1436
1435
  export type DocumentPageSetup = {
1437
1436
  size: 'letter' | 'a4';
@@ -1626,7 +1625,6 @@ export type TSheet = {
1626
1625
  customizedBreakpoints?: CustomizableBreakpoint[];
1627
1626
  cards?: TCard[];
1628
1627
  frames?: TFrame[];
1629
- calculatedFields?: Field[];
1630
1628
  document?: DocumentDefinition;
1631
1629
  };
1632
1630
  export type TEvent = {
@@ -28,7 +28,7 @@ import { StoredRelativeDate } from '../../shared/analytics-protocol/relative-dat
28
28
  export declare const CALCULATED_FIELD_ENTITY_MARKER: "SEMAPHOR_CALCULATED_FIELD";
29
29
  export declare const LEGACY_CALCULATED_FIELD_ENTITY_MARKER: "calculated_fields";
30
30
  export type CardMode = 'explorer' | 'dev';
31
- export type FieldScope = 'card' | 'sheet' | 'dashboard' | 'domain';
31
+ export type FieldScope = 'card' | 'dashboard' | 'domain';
32
32
  export type SemanticTemporalPresentation = {
33
33
  granularity: SemaphorTimeGrain;
34
34
  format: TemporalBucketFormat;
@@ -38,6 +38,12 @@ export type ScannedAggregateCall = {
38
38
  };
39
39
  argumentCount: number;
40
40
  filtered: boolean;
41
+ /** Each FILTER (...) or OVER (...) after the call: the offsets inside its parentheses. */
42
+ suffixes: Array<{
43
+ kind: 'filter' | 'over';
44
+ start: number;
45
+ end: number;
46
+ }>;
41
47
  };
42
48
  export type ScannedAggregateExpression = {
43
49
  calls: ScannedAggregateCall[];
@@ -46,6 +52,15 @@ export type ScannedAggregateExpression = {
46
52
  windowed: boolean;
47
53
  /** Input tokens that occur outside every aggregate call, in order. */
48
54
  tokensOutsideAggregates: string[];
55
+ /**
56
+ * Each OVER (...) after a call that is not an aggregate (LAG, RANK,
57
+ * ROW_NUMBER, ...): the offsets inside its parentheses. An aggregate's own
58
+ * OVER is in its call's `suffixes`.
59
+ */
60
+ windowClauses: Array<{
61
+ start: number;
62
+ end: number;
63
+ }>;
49
64
  /** All data reads belong to recognized aggregate calls; the rest consists
50
65
  * only of literals, operators and understood scalar composition. */
51
66
  aggregateInputsComplete: boolean;
@@ -1431,16 +1431,22 @@ export declare const semaphorMetricResultSchema: z.ZodObject<{
1431
1431
  missingMeasures: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
1432
1432
  comparison: z.ZodOptional<z.ZodObject<{
1433
1433
  kind: z.ZodEnum<["previous_period", "previous_year", "target"]>;
1434
+ /** What it compared with, as a card names it (compare-with CW-D24). */
1435
+ words: z.ZodOptional<z.ZodString>;
1434
1436
  value: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString, z.ZodNull]>>;
1435
1437
  delta: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodNull]>>;
1436
1438
  deltaPercent: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodNull]>>;
1437
1439
  }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
1438
1440
  kind: z.ZodEnum<["previous_period", "previous_year", "target"]>;
1441
+ /** What it compared with, as a card names it (compare-with CW-D24). */
1442
+ words: z.ZodOptional<z.ZodString>;
1439
1443
  value: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString, z.ZodNull]>>;
1440
1444
  delta: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodNull]>>;
1441
1445
  deltaPercent: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodNull]>>;
1442
1446
  }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
1443
1447
  kind: z.ZodEnum<["previous_period", "previous_year", "target"]>;
1448
+ /** What it compared with, as a card names it (compare-with CW-D24). */
1449
+ words: z.ZodOptional<z.ZodString>;
1444
1450
  value: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString, z.ZodNull]>>;
1445
1451
  delta: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodNull]>>;
1446
1452
  deltaPercent: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodNull]>>;
@@ -1481,16 +1487,22 @@ export declare const semaphorMetricResultSchema: z.ZodObject<{
1481
1487
  missingMeasures: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
1482
1488
  comparison: z.ZodOptional<z.ZodObject<{
1483
1489
  kind: z.ZodEnum<["previous_period", "previous_year", "target"]>;
1490
+ /** What it compared with, as a card names it (compare-with CW-D24). */
1491
+ words: z.ZodOptional<z.ZodString>;
1484
1492
  value: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString, z.ZodNull]>>;
1485
1493
  delta: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodNull]>>;
1486
1494
  deltaPercent: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodNull]>>;
1487
1495
  }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
1488
1496
  kind: z.ZodEnum<["previous_period", "previous_year", "target"]>;
1497
+ /** What it compared with, as a card names it (compare-with CW-D24). */
1498
+ words: z.ZodOptional<z.ZodString>;
1489
1499
  value: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString, z.ZodNull]>>;
1490
1500
  delta: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodNull]>>;
1491
1501
  deltaPercent: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodNull]>>;
1492
1502
  }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
1493
1503
  kind: z.ZodEnum<["previous_period", "previous_year", "target"]>;
1504
+ /** What it compared with, as a card names it (compare-with CW-D24). */
1505
+ words: z.ZodOptional<z.ZodString>;
1494
1506
  value: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString, z.ZodNull]>>;
1495
1507
  delta: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodNull]>>;
1496
1508
  deltaPercent: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodNull]>>;
@@ -1531,16 +1543,22 @@ export declare const semaphorMetricResultSchema: z.ZodObject<{
1531
1543
  missingMeasures: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
1532
1544
  comparison: z.ZodOptional<z.ZodObject<{
1533
1545
  kind: z.ZodEnum<["previous_period", "previous_year", "target"]>;
1546
+ /** What it compared with, as a card names it (compare-with CW-D24). */
1547
+ words: z.ZodOptional<z.ZodString>;
1534
1548
  value: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString, z.ZodNull]>>;
1535
1549
  delta: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodNull]>>;
1536
1550
  deltaPercent: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodNull]>>;
1537
1551
  }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
1538
1552
  kind: z.ZodEnum<["previous_period", "previous_year", "target"]>;
1553
+ /** What it compared with, as a card names it (compare-with CW-D24). */
1554
+ words: z.ZodOptional<z.ZodString>;
1539
1555
  value: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString, z.ZodNull]>>;
1540
1556
  delta: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodNull]>>;
1541
1557
  deltaPercent: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodNull]>>;
1542
1558
  }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
1543
1559
  kind: z.ZodEnum<["previous_period", "previous_year", "target"]>;
1560
+ /** What it compared with, as a card names it (compare-with CW-D24). */
1561
+ words: z.ZodOptional<z.ZodString>;
1544
1562
  value: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString, z.ZodNull]>>;
1545
1563
  delta: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodNull]>>;
1546
1564
  deltaPercent: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodNull]>>;
@@ -5,6 +5,7 @@ export declare const SEMAPHOR_ANALYZE_RESULT_FIELD_CONTRACT: {
5
5
  readonly responseDetail: "responseDetail";
6
6
  readonly mode: "string";
7
7
  readonly comparisonKind: "string";
8
+ readonly comparisonWords: "string";
8
9
  readonly executionResult: "executionResult";
9
10
  readonly compiledQuery: "unknown";
10
11
  readonly data: "unknown";
@@ -66,6 +67,8 @@ export type SemaphorAnalyzeResult = Partial<Record<SemaphorAnalyzeResultFieldNam
66
67
  responseDetail?: SemaphorAnalyzeResponseDetail;
67
68
  mode?: string;
68
69
  comparisonKind?: string;
70
+ /** What the comparison compared with, as a card names it: "Same day last week · Nov 6, until 8:06 AM" (compare-with CW-D24). */
71
+ comparisonWords?: string;
69
72
  executionResult?: SemaphorAnalyticsExecutionResult;
70
73
  compiledQuery?: SemaphorCompiledQuery;
71
74
  data?: unknown;
@@ -0,0 +1,92 @@
1
+ import { ComparisonShiftSpec, ComparisonUnit, ResolvedDateWindow } from './metric-comparison.js';
2
+ import { DateUnit, RelativeDateUnit, RelativeDateWindow } from './relative-date/index.js';
3
+ import { TemporalCalendar } from '../temporal/calendar-periods.js';
4
+ /** A calendar unit a comparison can step by. */
5
+ export type ComparisonCalendarUnit = Exclude<ComparisonUnit, 'period'>;
6
+ /**
7
+ * What the choices need to know about a window: the days it covers (a
8
+ * month counts its average length), and the calendar period it is when it is exactly one (Today, This month,
9
+ * Last quarter). Absent with no window.
10
+ */
11
+ export type ComparisonWindowShape = {
12
+ days: number;
13
+ period?: DateUnit;
14
+ /** A window counted in some unit other than days (the last 3 months, the last 6 hours): its count and unit, for its words (review P2R-02). */
15
+ count?: number;
16
+ unit?: RelativeDateUnit;
17
+ /**
18
+ * The fewest days the window can span, when that is less than `days` (a
19
+ * month 28, three months 89, twelve months 365): "certainly overlaps" is
20
+ * judged on it, so a step that fits in a short month is never refused.
21
+ */
22
+ fewestDays?: number;
23
+ };
24
+ /**
25
+ * What a surface has for the window a comparison applies to (compare-with
26
+ * CW-D15): a relative window as stored, a fixed day or month default, two
27
+ * dates as a filter stores them (the end included: a picked range's last
28
+ * instant, or a date-only day), or a run's resolved window (end exclusive).
29
+ */
30
+ export type ComparisonWindowSource = {
31
+ kind: 'relative';
32
+ window: unknown;
33
+ } | {
34
+ kind: 'fixedDay';
35
+ }
36
+ /** `month` 0 to 11, as the month picker saves it. */
37
+ | {
38
+ kind: 'fixedMonth';
39
+ year: number;
40
+ month: number;
41
+ }
42
+ /** `calendar`, when the caller knows the report's: a range that is exactly one calendar period is named by it, as placement steps it. */
43
+ | {
44
+ kind: 'range';
45
+ start: unknown;
46
+ end: unknown;
47
+ calendar?: TemporalCalendar | null;
48
+ } | {
49
+ kind: 'resolved';
50
+ window: ResolvedDateWindow;
51
+ calendar?: TemporalCalendar | null;
52
+ };
53
+ /**
54
+ * The one owner of a comparison window's shape (compare-with CW-D15, hotspot
55
+ * H-1): every surface (the Date filter's footer, chip and configuration
56
+ * panel, the card editor, the MCP) maps what it has to a source and asks
57
+ * here, so the days counted, the end included and the unit a window is named
58
+ * in are decided once. Undefined when the source has no finite window.
59
+ */
60
+ export declare function comparisonWindowShape(source: ComparisonWindowSource | undefined): ComparisonWindowShape | undefined;
61
+ /**
62
+ * What a current window is, for naming its comparison, where the run plans it
63
+ * (compare-with CW-D12, CW-D15; ledger P4-11): the window the user picked when
64
+ * one governs, else the whole range on the report calendar. Never the window
65
+ * the run counted: that is cut at the run instant while it is still running,
66
+ * and would name a running month "Previous 13 days".
67
+ */
68
+ export declare function plannedWindowShape(input: {
69
+ picked?: RelativeDateWindow;
70
+ whole?: ResolvedDateWindow;
71
+ calendar?: TemporalCalendar | null;
72
+ }): ComparisonWindowShape | undefined;
73
+ /**
74
+ * Whether a step back certainly lands on days the window still covers, for
75
+ * the control's note: previous period never does; a fixed step does when even
76
+ * its longest step is shorter than the window (a week back from This month).
77
+ * Placement decides on the dates (a month back from the last 30 days may
78
+ * fit); unknown with no window: false.
79
+ */
80
+ export declare function comparisonOverlaps(spec: ComparisonShiftSpec, shape: ComparisonWindowShape | undefined): boolean;
81
+ /**
82
+ * The steps a window is offered, in menu order (CW-D7, CW-D14): previous
83
+ * period always; then each calendar unit one step of which is longer than
84
+ * the window (so it cannot overlap, nor equal the previous period) and which
85
+ * is not the window's own period (a week back from
86
+ * This week is the previous period). A day step is never listed: on a day
87
+ * it is the previous period, on anything longer it overlaps. With no window,
88
+ * every unit.
89
+ */
90
+ export declare function offeredComparisons(shape: ComparisonWindowShape | undefined): ComparisonShiftSpec[];
91
+ /** The units a custom step may name, in menu order. */
92
+ export declare const CUSTOM_COMPARISON_UNITS: readonly ComparisonCalendarUnit[];
@@ -0,0 +1,30 @@
1
+ import { TemporalCalendar, TemporalShift } from '../temporal/calendar-periods.js';
2
+ import { DateColumnKind, DateWindowBasis } from './date-window.js';
3
+ import { ResolvedDateWindow, StoredViewerPeriodComparisonSpec } from './metric-comparison.js';
4
+ export type ComparisonWindowPlacementResult = {
5
+ status: 'resolved';
6
+ currentWindow: ResolvedDateWindow;
7
+ comparisonWindow: ResolvedDateWindow;
8
+ /** How far back the comparison window sits (CK-D4). */
9
+ step: TemporalShift;
10
+ } | {
11
+ status: 'unavailable';
12
+ reason: 'finite_current_window_required' | 'current_window_not_started' | 'temporal_binding_invalid' | 'insufficient_history' | 'overlaps_current_window';
13
+ };
14
+ /** The comparison window for a step back from the current window, or why there is none. */
15
+ export declare function placeComparisonWindow(input: {
16
+ currentWindow: ResolvedDateWindow | undefined;
17
+ /** A step back, in any stored shape: read through the one reader here (compare-with CW-D5). */
18
+ spec: StoredViewerPeriodComparisonSpec;
19
+ /** The date column the windows filter: a DATE column counts whole days. */
20
+ column: DateColumnKind;
21
+ referenceTime: Date;
22
+ /**
23
+ * What the current window is (CK-D2). An `anchored` window (Year to last
24
+ * completed month) compares with the same completed subperiods `offset`
25
+ * spans earlier (relative-date-as-of SPEC 3.3, AO-D26).
26
+ */
27
+ basis: DateWindowBasis;
28
+ weekStart: 0 | 1 | 2 | 3 | 4 | 5 | 6;
29
+ fiscalCalendar?: TemporalCalendar['fiscalCalendar'];
30
+ }): ComparisonWindowPlacementResult;
@@ -4,6 +4,7 @@ import { matrixResultSchema } from './matrix-window-contract.js';
4
4
  import { CalendarContext } from '../report-runtime-context/index.js';
5
5
  import { RelativeDateWindowInput } from './relative-date/index.js';
6
6
  import { SemaphorQueryConstraints } from './applied-constraints.js';
7
+ import { ComparisonFamily, MetricComparisonSpec } from './metric-comparison.js';
7
8
  export type SemaphorProtocolVersion = 1;
8
9
  export type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
9
10
  export type SemaphorSourceLevel = 'database' | 'schema' | 'table';
@@ -419,10 +420,12 @@ export type SemaphorMetricIntent = {
419
420
  timeWindow?: SemaphorTimeWindow;
420
421
  dimensions?: SemaphorFieldRef[];
421
422
  filters?: SemaphorAnalyticsFilter[];
422
- comparison?: {
423
- kind: 'previous_period' | 'previous_year' | 'target';
424
- targetValue?: number;
425
- };
423
+ /**
424
+ * One comparison for the analysis, in the words a card measure takes
425
+ * (compare-with CW-D24): a step back (`{ kind: 'shift', unit, offset?,
426
+ * matchWeekdays? }`) or a target.
427
+ */
428
+ comparison?: MetricComparisonSpec;
426
429
  analysis?: SemaphorMetricAnalysis;
427
430
  orderBy?: {
428
431
  field: SemaphorFieldRef;
@@ -633,7 +636,10 @@ export type SemaphorMetricResult = SemaphorAnalyticsResultBase & {
633
636
  primaryValue: number | string | null;
634
637
  missingMeasures?: string[];
635
638
  comparison?: {
636
- kind: NonNullable<SemaphorMetricIntent['comparison']>['kind'];
639
+ /** previous_year for a step by years, previous_period for any other step, or target. */
640
+ kind: ComparisonFamily;
641
+ /** What it compared with, named for the window (`describeComparison`): "Same day last week". */
642
+ words?: string;
637
643
  value?: number | string | null;
638
644
  delta?: number | null;
639
645
  deltaPercent?: number | null;
@@ -0,0 +1,105 @@
1
+ import { Duration, ZonedDateTime } from '../temporal/temporal.js';
2
+ import { DateUnit, RelativeDateWindow } from './relative-date/index.js';
3
+ export type { ZonedDateTime } from '../temporal/temporal.js';
4
+ /** What a window's column can tell apart: an instant, or only the day. */
5
+ export type DateColumnKind = 'date' | 'timestamp';
6
+ /** The units a calendar window counts and a calendar step moves by. */
7
+ export type CalendarStepUnit = 'day' | 'week' | 'month' | 'quarter' | 'year';
8
+ /**
9
+ * What a window is (comparison kernel CK-D2): it decides how its previous
10
+ * period is placed and how its length is counted.
11
+ */
12
+ export type DateWindowBasis =
13
+ /** A count of calendar units ("Last 7 days", "This month", "This month, to date"). */
14
+ {
15
+ kind: 'calendar';
16
+ unit: DateUnit;
17
+ n: number;
18
+ toDate: boolean;
19
+ window: RelativeDateWindow;
20
+ }
21
+ /** A rolling minute or hour span on a timestamp column: elapsed time. */
22
+ | {
23
+ kind: 'elapsed';
24
+ window: RelativeDateWindow;
25
+ }
26
+ /** As of the end of the last complete period: compares by span (relative-date-as-of AO-D26). */
27
+ | {
28
+ kind: 'anchored';
29
+ window: RelativeDateWindow;
30
+ }
31
+ /** Picked dates or instants, no window behind them. */
32
+ | {
33
+ kind: 'range';
34
+ };
35
+ export type ZonedDateWindow = {
36
+ /** The first instant, in the window's zone. */
37
+ readonly start: ZonedDateTime;
38
+ /** The first instant after the window. */
39
+ readonly endExclusive: ZonedDateTime;
40
+ readonly column: DateColumnKind;
41
+ readonly basis: DateWindowBasis;
42
+ };
43
+ /**
44
+ * The basis of a window: what it was picked as (CK-D2). A window picked to an
45
+ * instant becomes a range on a DATE column, where the instant is a day; a
46
+ * sub-day window on a timestamp is elapsed time.
47
+ */
48
+ export declare function dateWindowBasis(window: RelativeDateWindow | undefined, column: DateColumnKind): DateWindowBasis;
49
+ /** An instant read into a zone: the zoned time every window operation takes. */
50
+ export declare function zonedAt(instant: Date, zone: string): ZonedDateTime;
51
+ /**
52
+ * The one constructor. Bounds are half-open; on a DATE column both widen to
53
+ * whole days (the start's day from its midnight, the last instant's day to
54
+ * the next midnight), as the run filters a date.
55
+ */
56
+ export declare function dateWindowOf(input: {
57
+ start: Date;
58
+ endExclusive: Date;
59
+ zone: string;
60
+ column: DateColumnKind;
61
+ /** What the window is (`dateWindowBasis`, or a range when another date filter narrows a picked window). */
62
+ basis: DateWindowBasis;
63
+ }): ZonedDateWindow;
64
+ /** Whether the window is whole calendar months (a month, a quarter, a year): both ends on a month's first midnight. */
65
+ export declare function isWholeMonths(window: Pick<ZonedDateWindow, 'start' | 'endExclusive'>): boolean;
66
+ /**
67
+ * The window cut at the run instant, what has elapsed of it (compare-with
68
+ * CW-D1): to the instant on a timestamp, through the whole of today on a DATE
69
+ * column. Null before it starts; the window itself when nothing is left to
70
+ * run.
71
+ */
72
+ export declare function windowCutAt(window: ZonedDateWindow, now: Date): ZonedDateWindow | null;
73
+ /** The window's length in calendar time: local days and the time of day, as a wall clock counts it. */
74
+ export declare function calendarLength(window: Pick<ZonedDateWindow, 'start' | 'endExclusive'>): Duration;
75
+ /** The window's length in elapsed time. */
76
+ export declare function elapsedLength(window: Pick<ZonedDateWindow, 'start' | 'endExclusive'>): number;
77
+ /** `amount` units on the calendar from a zoned time, keeping the time of day and clamping a month's day (January 31 to February 28). */
78
+ export declare function calendarShift(at: ZonedDateTime, amount: number, unit: CalendarStepUnit): ZonedDateTime;
79
+ /**
80
+ * A window `amount` units back on the calendar. Whole calendar months (both
81
+ * ends on a month's first midnight: a month, a quarter, a year) move their
82
+ * exclusive end, so April stays all of March; any other window moves its last
83
+ * included instant, keeping the time of day and clamping to a shorter month's
84
+ * last day (analytics kernel K6, ledger EXT-01): March 31 reaches February 28.
85
+ */
86
+ export declare function windowStepBack(window: Pick<ZonedDateWindow, 'start' | 'endExclusive'>, amount: number, unit: CalendarStepUnit, options: {
87
+ toDate: boolean;
88
+ }): {
89
+ start: ZonedDateTime;
90
+ endExclusive: ZonedDateTime;
91
+ };
92
+ /**
93
+ * A comparison never covers more time than the window it compares
94
+ * (compare-with CW-INV-1, CW-D26): a window that is not whole calendar months
95
+ * keeps its comparison to its own length from the stepped-back start, counted
96
+ * as the calendar does (local days and time of day) so a clock change keeps
97
+ * the same hour; an elapsed window (a rolling hour span) counts elapsed time.
98
+ * Whole months, quarters and years keep their own lengths.
99
+ */
100
+ export declare function noLongerThan<T extends {
101
+ start: ZonedDateTime;
102
+ endExclusive: ZonedDateTime;
103
+ }>(comparison: T, window: Pick<ZonedDateWindow, 'start' | 'endExclusive'>, options: {
104
+ elapsed: boolean;
105
+ }): T;
@@ -15,6 +15,33 @@ export declare function filterValueTargetsField(filter: TFilterValue, field: {
15
15
  name: string;
16
16
  qualifiedFieldName?: string;
17
17
  }): boolean;
18
+ /** A dashboard filter value that is the Global Date: it owns the range of every field it targets. */
19
+ export declare function isGlobalDateValue(filter: TFilterValue): boolean;
20
+ /**
21
+ * Global Date replaces the card's own range on the field it targets; every
22
+ * other dashboard date filter intersects with it (analytics kernel P2a-01).
23
+ * The one rule for which date ranges restrict a card: the run applies it
24
+ * before it builds the query (the app's `withGlobalDateOwnership` adapter),
25
+ * and authoring reads the window a comparison will step from through it
26
+ * (`readComparisonDates`, compare-with CW16-R1), so the two never disagree.
27
+ *
28
+ * Returns the card config without its own range conditions on every field an
29
+ * applicable Global Date value targets. Only the root group's conditions
30
+ * count, and only when the root is unconditional: removing a condition from an
31
+ * OR or negated group would change what the rest of the group means. The same
32
+ * object when nothing is owned. Pass only the filters that apply to the card.
33
+ * Never owned: a latest-value condition (Global Date scopes its lookup instead,
34
+ * K12, K13), a viewer's zoom (it narrows the dashboard's dates on one chart,
35
+ * chart date zoom DZ-D5), and a condition the run resolved from a data anchor
36
+ * (`resolvedAtRun`: ownership was decided for its marker before resolution,
37
+ * and a second pass must not undo that; only the run has such conditions, and
38
+ * only it can read the marker, temporal predicate contract E2).
39
+ */
40
+ export declare function withGlobalDateOwnership<T extends {
41
+ filters?: FilterGroup | null;
42
+ }>(cardConfig: T, activeFilters: readonly TFilterValue[], options?: {
43
+ resolvedAtRun?: (condition: FilterCondition) => boolean;
44
+ }): T;
18
45
  /**
19
46
  * Whether every condition of this group must hold for a row: it is not
20
47
  * negated, and it joins with AND (or has at most one child, so its operator
@@ -20,7 +20,8 @@ export declare const SEMAPHOR_ANALYTICS_INTENT_FIXTURES: {
20
20
  role: "measure";
21
21
  };
22
22
  comparison: {
23
- kind: "previous_period";
23
+ kind: "shift";
24
+ unit: "period";
24
25
  };
25
26
  limit: number;
26
27
  };
@@ -137,7 +138,8 @@ export declare const SEMAPHOR_ANALYTICS_INTENT_FIXTURES: {
137
138
  };
138
139
  timeGrain: "week";
139
140
  comparison: {
140
- kind: "previous_period";
141
+ kind: "shift";
142
+ unit: "period";
141
143
  };
142
144
  limit: number;
143
145
  };