react-semaphor 0.1.568 → 0.1.569

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 (126) hide show
  1. package/README.md +0 -7
  2. package/dist/analytics-protocol/index.js +434 -454
  3. package/dist/assistant-context/index.js +1 -1
  4. package/dist/brand-studio/index.js +10 -12
  5. package/dist/briefings/index.js +4 -4
  6. package/dist/chunks/{_commonjsHelpers-DimLPMtv.js → _commonjsHelpers-Bid1ZNYj.js} +271 -222
  7. package/dist/chunks/{assistant-chat-BN5I8KuN.js → assistant-chat-Dzf2Mbph.js} +107 -109
  8. package/dist/chunks/{bookmark-impact-CJ-65omV.js → bookmark-impact-Czg6FGt5.js} +2 -2
  9. package/dist/chunks/{bookmark-state-Du3s13_V.js → bookmark-state-CflS88gq.js} +251 -250
  10. package/dist/chunks/{card-filter-builder-BBuB99GZ.js → card-filter-builder-BS982X7x.js} +986 -985
  11. package/dist/chunks/{code-editor-DJNOsgJH.js → code-editor-BsxHzm9u.js} +43 -45
  12. package/dist/chunks/{comparison-window-caption-CMLb3mut.js → comparison-window-caption-lLTgzOkM.js} +252 -253
  13. package/dist/chunks/{dashboard-YnWZC4dK.js → dashboard-BiYSbxZv.js} +1 -1
  14. package/dist/chunks/{dashboard-briefing-launcher-BF89TU2h.js → dashboard-briefing-launcher-Bdj7luOr.js} +158 -159
  15. package/dist/chunks/{dashboard-controls-atHc1EjP.js → dashboard-controls-TViDsnb8.js} +17 -19
  16. package/dist/chunks/dashboard-json-Dg9dQd9U.js +66 -0
  17. package/dist/chunks/{dates-CKO05ino.js → dates-BsPrWZIP.js} +8 -8
  18. package/dist/chunks/{edit-dashboard-visual-DdmTfn-J.js → edit-dashboard-visual-C6hoIeEJ.js} +20 -21
  19. package/dist/chunks/{filter-reach-copy-jZGzK_IH.js → filter-reach-copy-hcQ4os0u.js} +695 -699
  20. package/dist/chunks/filter-value-text-CVxEEDVl.js +146 -0
  21. package/dist/chunks/{index-CPNZW0mu.js → index-G4q89J6O.js} +74 -76
  22. package/dist/chunks/{layout-grid-0hIlqEtk.js → layout-grid-BIcoFfdS.js} +1 -1
  23. package/dist/chunks/{list-filter-DkgoCeBm.js → list-filter-C6tYkHyv.js} +1 -1
  24. package/dist/chunks/matrix-analytical-definition-dkS8szLM.js +1253 -0
  25. package/dist/chunks/matrix-member-presentation-DRa-9e6Q.js +169 -0
  26. package/dist/chunks/{matrix-operation-contract-Eb6elidS.js → matrix-operation-contract-DCVinw1o.js} +122 -122
  27. package/dist/chunks/{metric-comparison-ChXUFaZu.js → metric-comparison-n9NsIa-2.js} +175 -128
  28. package/dist/chunks/{palette-4vf2BEEg.js → palette-NjHOE_6B.js} +1 -1
  29. package/dist/chunks/pivot-result-contract-expectations-DkmueDTW.js +55 -0
  30. package/dist/chunks/{pivot-result-identity-BlbLrqaC.js → pivot-result-identity-B89X5xjb.js} +1 -1
  31. package/dist/chunks/raw-temporal-value-DdT0s47W.js +159 -0
  32. package/dist/chunks/{report-preferences-dialog-Mbd-I0wV.js → report-preferences-dialog-Xc8_GFju.js} +26 -28
  33. package/dist/chunks/{report-runtime-context-DnA_PiKo.js → report-runtime-context-BhPzLTbS.js} +1 -1
  34. package/dist/chunks/{resolve-dashboard-input-context-Du0fjN3h.js → resolve-dashboard-input-context-KqvcLcTM.js} +4784 -4764
  35. package/dist/chunks/{save-D6pHmSSP.js → save-C6VmEJTA.js} +1 -1
  36. package/dist/chunks/{saved-dashboard-context-y8N6RvjS.js → saved-dashboard-context-BeXXyoD4.js} +6 -6
  37. package/dist/chunks/{semaphor-ready-indicator-BSEdUq40.js → semaphor-ready-indicator-BNkaANsG.js} +28395 -28384
  38. package/dist/chunks/{shelf-drop-preview-context-D7QqPl36.js → shelf-drop-preview-context-C_issPBA.js} +18 -20
  39. package/dist/chunks/{stored-dashboard-d3xQYxBD.js → stored-dashboard-B6_StAty.js} +263 -265
  40. package/dist/chunks/{table-export-sheet--DUKWk6o.js → table-export-sheet-BWP2joD1.js} +1 -1
  41. package/dist/chunks/{temporal-input-presentation--2r9BLr0.js → temporal-input-presentation-scSWQXAB.js} +4 -4
  42. package/dist/chunks/{token-types-C8JymO8s.js → token-types-iKMplaBL.js} +1 -1
  43. package/dist/chunks/{upload-Cf3wXZT8.js → upload-BRW4Mwrd.js} +1 -1
  44. package/dist/chunks/validators-B8fpdinG.js +3651 -0
  45. package/dist/chunks/{variable-draft-DOX03R4A.js → variable-draft-BQ3OMjvy.js} +4 -4
  46. package/dist/dashboard/index.js +2 -2
  47. package/dist/dashboard-authoring/index.js +1527 -1517
  48. package/dist/format-utils/index.js +230 -231
  49. package/dist/index.js +236 -237
  50. package/dist/report-runtime-context/index.js +1 -1
  51. package/dist/style.css +1 -1
  52. package/dist/surfboard/index.js +2 -2
  53. package/dist/types/components/surfboard/filter/types.d.ts +5 -4
  54. package/dist/types/components/ui-custom/date-range-presets.d.ts +1 -17
  55. package/dist/types/index.js +9 -9
  56. package/dist/types/lib/hooks/use-date-filter.d.ts +3 -3
  57. package/dist/types/lib/matrix-table/matrix-card-adapter.d.ts +1 -1
  58. package/dist/types/lib/types/explorer-types.d.ts +2 -2
  59. package/dist/types/lib/types/index.d.ts +1 -1
  60. package/dist/types/lib/utils/card-definition.d.ts +7 -7
  61. package/dist/types/shared/analytics-protocol/agent-time-window.d.ts +84 -0
  62. package/dist/types/shared/analytics-protocol/applied-constraints.d.ts +2 -2
  63. package/dist/types/shared/analytics-protocol/contracts.d.ts +8 -17
  64. package/dist/types/shared/analytics-protocol/fixtures.d.ts +3 -2
  65. package/dist/types/shared/analytics-protocol/index.d.ts +2 -4
  66. package/dist/types/shared/analytics-protocol/matrix-definition-contract.d.ts +4 -4
  67. package/dist/types/shared/analytics-protocol/relative-date/describe.d.ts +18 -0
  68. package/dist/types/shared/analytics-protocol/relative-date/index.d.ts +7 -0
  69. package/dist/types/shared/analytics-protocol/relative-date/limits.d.ts +3 -0
  70. package/dist/types/shared/analytics-protocol/relative-date/presets.d.ts +11 -0
  71. package/dist/types/shared/analytics-protocol/relative-date/resolve.d.ts +49 -0
  72. package/dist/types/shared/analytics-protocol/relative-date/schemas.d.ts +76 -0
  73. package/dist/types/shared/analytics-protocol/relative-date/traits.d.ts +51 -0
  74. package/dist/types/shared/analytics-protocol/relative-date/window.d.ts +111 -0
  75. package/dist/types/shared/analytics-protocol/selection-contract.d.ts +1 -1
  76. package/dist/types/shared/assistant-protocol/context.d.ts +12 -12
  77. package/dist/types/shared/dashboard-authoring/changes/card-query-part.d.ts +0 -2
  78. package/dist/types/shared/dashboard-authoring/changes/dashboard-change.d.ts +155 -1753
  79. package/dist/types/shared/dashboard-authoring/changes/read-card-query.d.ts +8 -4
  80. package/dist/types/shared/dashboard-authoring/conditional-formatting/schema.d.ts +74 -74
  81. package/dist/types/shared/dashboard-authoring/control-execution-contract.d.ts +20 -20
  82. package/dist/types/shared/dashboard-authoring/outline/outline-dashboard.d.ts +3 -0
  83. package/dist/types/shared/dashboard-authoring/outline/outline-filters.d.ts +10 -2
  84. package/dist/types/shared/format-utils/filter-detail.d.ts +2 -8
  85. package/dist/types/shared/format-utils/filter-line.d.ts +2 -2
  86. package/dist/types/shared/format-utils/matrix-continuation.d.ts +3 -3
  87. package/dist/types/shared/temporal/index.d.ts +0 -2
  88. package/dist/types/shared/temporal/temporal-parity-fixtures.d.ts +2 -2
  89. package/package.json +2 -24
  90. package/DATA_APP_SDK.md +0 -339
  91. package/dist/chunks/dashboard-json-Cxp3inxd.js +0 -68
  92. package/dist/chunks/filter-value-text-7zhmth1S.js +0 -163
  93. package/dist/chunks/index-CuHybtft.js +0 -51
  94. package/dist/chunks/matrix-analytical-definition-C9xB_T84.js +0 -717
  95. package/dist/chunks/matrix-card-BSUeSXpD.js +0 -42
  96. package/dist/chunks/matrix-member-presentation-DZNgQpUq.js +0 -105
  97. package/dist/chunks/operators-B3zZoskU.js +0 -66
  98. package/dist/chunks/pivot-result-contract-expectations-Ddh1rNz5.js +0 -56
  99. package/dist/chunks/raw-temporal-value-Bqz8wc7L.js +0 -242
  100. package/dist/chunks/selection-reducer-OaJ-N5uN.js +0 -46
  101. package/dist/chunks/source-entity-resolution-DF6GulDn.js +0 -607
  102. package/dist/chunks/validators-wtjw0aw6.js +0 -3332
  103. package/dist/data-app-sdk/index.js +0 -1412
  104. package/dist/data-app-sdk-adapters/index.js +0 -361
  105. package/dist/data-app-sdk-validation/index.js +0 -1031
  106. package/dist/types/data-app-sdk/adapters.d.ts +0 -35
  107. package/dist/types/data-app-sdk/builders.d.ts +0 -62
  108. package/dist/types/data-app-sdk/contracts.d.ts +0 -419
  109. package/dist/types/data-app-sdk/executor.d.ts +0 -5
  110. package/dist/types/data-app-sdk/field-catalog-validation.d.ts +0 -29
  111. package/dist/types/data-app-sdk/hooks.d.ts +0 -11
  112. package/dist/types/data-app-sdk/index.d.ts +0 -9
  113. package/dist/types/data-app-sdk/provider.d.ts +0 -8
  114. package/dist/types/data-app-sdk/relationship-aware-field-policy.d.ts +0 -21
  115. package/dist/types/data-app-sdk/selection.d.ts +0 -2
  116. package/dist/types/data-app-sdk/validation.d.ts +0 -58
  117. package/dist/types/data-app-sdk-adapters.d.ts +0 -2
  118. package/dist/types/data-app-sdk-validation.d.ts +0 -2
  119. package/dist/types/data-app-sdk.d.ts +0 -2
  120. package/dist/types/shared/analytics-protocol/relative-date-filter.d.ts +0 -68
  121. package/dist/types/shared/analytics-protocol/relative-date-label.d.ts +0 -20
  122. package/dist/types/shared/analytics-protocol/time-window-schema.d.ts +0 -314
  123. package/dist/types/shared/analytics-protocol/time-window.d.ts +0 -52
  124. package/dist/types/shared/temporal/relative-date.d.ts +0 -21
  125. package/dist/types/shared/temporal/time-window-periods.d.ts +0 -21
  126. package/src/data-app-sdk/README.md +0 -402
@@ -1,5 +1,5 @@
1
- import { a, R as s, D as o } from "../chunks/report-preferences-dialog-Mbd-I0wV.js";
2
- import { C as f, E as D } from "../chunks/bookmark-state-Du3s13_V.js";
1
+ import { a, R as s, D as o } from "../chunks/report-preferences-dialog-Xc8_GFju.js";
2
+ import { C as f, E as D } from "../chunks/bookmark-state-CflS88gq.js";
3
3
  export {
4
4
  f as CONTROL_CARD_DEFAULT_VALUE,
5
5
  a as DisplayFormatPreferencesFields,
@@ -2,7 +2,7 @@ import { DashboardInputTargetContext } from '../../../lib/dashboard-inputs/dashb
2
2
  import { NormalizedDashboardInput } from '../../../lib/types/common-types.js';
3
3
  import { CalculatedFieldFormula, Field } from '../../../lib/types/explorer-types.js';
4
4
  import { RawTemporalSelection, TemporalBucketMetadata } from '../../../shared/analytics-protocol/contracts.js';
5
- import { DateUnit, RelativeDateFilter, RelativeDateUnit, SubDayDateUnit } from '../../../shared/analytics-protocol/relative-date-filter.js';
5
+ import { DateUnit, RelativeDateUnit, RelativeDateWindow, StoredRelativeDate, SubDayDateUnit } from '../../../shared/analytics-protocol/relative-date/index.js';
6
6
  export type DateSelectionMode = 'range' | 'months' | 'day';
7
7
  export type DateComparisonOperation = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'between' | 'not between' | 'is null' | 'is not null';
8
8
  export type FilterLocation = 'dashboard' | 'frame' | 'sheet' | undefined;
@@ -13,7 +13,7 @@ export type ComboBoxOption = {
13
13
  [key: string]: FilterOptionValue;
14
14
  };
15
15
  export type TSelectedRecord = ComboBoxOption;
16
- export type { DateUnit, RelativeDateFilter, RelativeDateUnit, SubDayDateUnit, };
16
+ export type { DateUnit, RelativeDateUnit, RelativeDateWindow, StoredRelativeDate, SubDayDateUnit, };
17
17
  export type TemporalPrecision = 'minute';
18
18
  /**
19
19
  * Options for a relative date pick ("Today", "Last 7 days"). The pick is a
@@ -44,7 +44,7 @@ export type FixedDayDefaultDateFilter = {
44
44
  unit: 'day';
45
45
  date: string;
46
46
  };
47
- export type DefaultDateFilter = RelativeDateFilter | FixedMonthDefaultDateFilter | FixedDayDefaultDateFilter;
47
+ export type DefaultDateFilter = StoredRelativeDate | FixedMonthDefaultDateFilter | FixedDayDefaultDateFilter;
48
48
  export type FilterKind = 'field' | 'global-date';
49
49
  /**
50
50
  * Target column configuration for multi-field filters.
@@ -176,7 +176,8 @@ type FilterForBetween = BaseFilter & {
176
176
  type FilterForDate = BaseFilter & {
177
177
  operation: 'between' | 'not between' | '=' | '!=' | '>' | '<' | '>=' | '<=';
178
178
  values: [Date | string, Date | string] | [Date | string];
179
- relativeMeta?: RelativeDateFilter;
179
+ /** The relative window the dates come from, as stored; read it with `readRelativeDate` (relative-date-as-of SPEC 2.2). */
180
+ relativeMeta?: StoredRelativeDate;
180
181
  temporalPrecision?: TemporalPrecision;
181
182
  };
182
183
  type FilterForNull = BaseFilter & {
@@ -1,10 +1,8 @@
1
- import { DefaultDateFilter, FixedDayDefaultDateFilter, FixedMonthDefaultDateFilter, RelativeDateFilter } from '../surfboard/filter/types.js';
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
4
  /** Calendar inputs for defaults, including reproducible and fiscal reports. */
5
5
  export type DefaultDateCalendar = Pick<CalendarContext, 'tz' | 'weekStart'> & Partial<Pick<CalendarContext, 'anchor' | 'fiscalCalendar'>>;
6
- /** A valid relative date, read by the shared protocol reader. */
7
- export declare const isRelativeDateFilter: (value: unknown) => value is RelativeDateFilter;
8
6
  export declare const isFixedMonthDefaultDateFilter: (value: unknown) => value is FixedMonthDefaultDateFilter;
9
7
  export declare const isFixedDayDefaultDateFilter: (value: unknown) => value is FixedDayDefaultDateFilter;
10
8
  /**
@@ -22,17 +20,3 @@ export declare function resolveCalendarDayRange(date: string, timezone: string):
22
20
  */
23
21
  export declare const isSingleDayDefaultDateFilter: (value: DefaultDateFilter | undefined) => boolean;
24
22
  export declare function resolveDefaultDateFilterForDefaults(meta: DefaultDateFilter, calendar: string | DefaultDateCalendar, weekStart?: WeekStart): [Date, Date] | undefined;
25
- /**
26
- * The window a relative date names at `now` in the timezone, from the shared
27
- * date module (analytics kernel Phase 3), so a preview matches what the server
28
- * runs. Callers here have no fiscal calendar, so quarters and years are
29
- * calendar periods; previews show those as labels only (K8).
30
- *
31
- * @param meta - The relative date filter metadata
32
- * @param timezone - IANA timezone string (e.g., "America/New_York", "UTC")
33
- * @param weekStart - Day the week starts on (0=Sunday, 1=Monday). Defaults to 1 (Monday/ISO).
34
- * @param now - The anchor instant; a pinned calendar anchor passes its own.
35
- * @returns `[start, inclusive end]`
36
- */
37
- export declare function resolveRelativeDateForDefaults(meta: RelativeDateFilter, timezone: string, weekStart?: WeekStart, now?: Date): [Date, Date];
38
- export { findPresetLabel, getRelativeDateLabel, getRelativeOffsetLabel, presetMetadata, relativeMetaEquals, } from '../../shared/analytics-protocol/relative-date-label.js';
@@ -1,8 +1,8 @@
1
- import { B as s, y 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, x as p, w as D, l as A, h as I, o as _, v as F, u as S, m as b, n as L, p as f, k as N, q as y, s as R, i as h, r as g, t as x } from "../chunks/bookmark-state-Du3s13_V.js";
2
- import { C as O, D as V, L as w, e as k, g as U, j as z, h as B, k as K, d as v, b as Y, i as q, c as G, n as P, f as Q } from "../chunks/validators-wtjw0aw6.js";
3
- import { D as W } from "../chunks/token-types-C8JymO8s.js";
4
- import { r as X, a as H } from "../chunks/pivot-result-identity-BlbLrqaC.js";
5
- import { D as $ } from "../chunks/report-runtime-context-DnA_PiKo.js";
1
+ import { B as t, y 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, x as p, w as D, l as A, h as I, o as _, v as F, u as S, m as b, n as L, p as f, k as N, q as y, s as R, i as h, r as g, t as x } from "../chunks/bookmark-state-CflS88gq.js";
2
+ import { C as O, D as V, L as w, d as U, g as k, e as z, h as B, f as K, c as v, a as Y, i as q, b as G, n as P, s as Q } from "../chunks/validators-B8fpdinG.js";
3
+ import { D as j } from "../chunks/token-types-iKMplaBL.js";
4
+ import { r as X, a as H } from "../chunks/pivot-result-identity-B89X5xjb.js";
5
+ import { D as $ } from "../chunks/report-runtime-context-BhPzLTbS.js";
6
6
  const e = [
7
7
  "concatenate",
8
8
  "conditional-category",
@@ -36,14 +36,14 @@ const e = [
36
36
  "is-blank"
37
37
  ];
38
38
  export {
39
- s as BOOKMARK_STATE_VERSION,
39
+ t as BOOKMARK_STATE_VERSION,
40
40
  r as BOOKMARK_VISIBILITIES,
41
41
  O as CALCULATED_FIELD_ENTITY_MARKER,
42
42
  e as CALCULATED_FIELD_TEMPLATE_IDS,
43
43
  l as CONTROL_CARD_DEFAULT_VALUE,
44
44
  V as DATE_FORMAT_VALUES,
45
45
  $ as DEFAULT_CALENDAR_CONTEXT,
46
- W as DEFAULT_SEMANTIC_DOMAIN_ACCESS,
46
+ j as DEFAULT_SEMANTIC_DOMAIN_ACCESS,
47
47
  o as EMPTY_SELECTION,
48
48
  w as LEGACY_CALCULATED_FIELD_ENTITY_MARKER,
49
49
  i as VIEWER_LIMITS,
@@ -55,9 +55,9 @@ export {
55
55
  E as collectQualifiedDatasetNamesFromExplorerField,
56
56
  C as datasetRefFromSource,
57
57
  T as dependencyDisplayIdentity,
58
- k as getCalculatedFieldComputeStage,
58
+ U as getCalculatedFieldComputeStage,
59
59
  p as getCustomizableTableCardIds,
60
- U as getFieldRuntimeColumnName,
60
+ k as getFieldRuntimeColumnName,
61
61
  D as getSortableTableCardIds,
62
62
  z as hasCalculatedFieldMarker,
63
63
  B as hasCalculatedFormulaInputs,
@@ -1,4 +1,4 @@
1
- import { TFilter, TFilterValue, RelativeDateFilter, DateComparisonOperation, FilterStorageOptions, RelativeDateChangeOptions, TemporalPrecision } from '../../components/surfboard/filter/types.js';
1
+ import { TFilter, TFilterValue, RelativeDateWindow, DateComparisonOperation, FilterStorageOptions, RelativeDateChangeOptions, TemporalPrecision } from '../../components/surfboard/filter/types.js';
2
2
  import { DateRange } from 'react-day-picker';
3
3
  type UseDateFilterOptions = FilterStorageOptions;
4
4
  type DateFilterChangeOptions = {
@@ -20,7 +20,7 @@ export declare function useDateFilterHook(filterId: string): {
20
20
  handleClear: () => void;
21
21
  handleChange: (date: DateRange | undefined, operation?: DateComparisonOperation, options?: DateFilterChangeOptions) => void;
22
22
  handleNullOperation: (operation: "is null" | "is not null") => void;
23
- handleRelativeChange: (date: DateRange | undefined, relativeMeta: RelativeDateFilter, options?: RelativeDateChangeOptions) => void;
23
+ handleRelativeChange: (date: DateRange | undefined, relativeMeta: RelativeDateWindow, options?: RelativeDateChangeOptions) => void;
24
24
  handleReset: () => void;
25
25
  };
26
26
  export declare function useDateFilter(filter: TFilter, options?: UseDateFilterOptions): {
@@ -35,7 +35,7 @@ export declare function useDateFilter(filter: TFilter, options?: UseDateFilterOp
35
35
  handleClear: () => void;
36
36
  handleChange: (date: DateRange | undefined, operation?: DateComparisonOperation, options?: DateFilterChangeOptions) => void;
37
37
  handleNullOperation: (operation: "is null" | "is not null") => void;
38
- handleRelativeChange: (date: DateRange | undefined, relativeMeta: RelativeDateFilter, options?: RelativeDateChangeOptions) => void;
38
+ handleRelativeChange: (date: DateRange | undefined, relativeMeta: RelativeDateWindow, options?: RelativeDateChangeOptions) => void;
39
39
  handleReset: () => void;
40
40
  };
41
41
  export {};
@@ -66,6 +66,7 @@ export declare function prepareMatrixCard(card: TCard, catalog: MatrixCardCatalo
66
66
  levelFormats: Readonly<Record<string, SemaphorValueFormat>>;
67
67
  measureFormats: Readonly<Record<string, SemaphorValueFormat>>;
68
68
  };
69
+ version: 1;
69
70
  spec: {
70
71
  source: {
71
72
  kind: "semantic";
@@ -149,7 +150,6 @@ export declare function prepareMatrixCard(card: TCard, catalog: MatrixCardCatalo
149
150
  } | undefined;
150
151
  measureFilters?: readonly import('../../shared/analytics-protocol/index.js').MatrixMeasureFilter[] | undefined;
151
152
  };
152
- version: 1;
153
153
  defaultView: {
154
154
  columns: {
155
155
  depth: number;
@@ -2,7 +2,7 @@ import { TimeDrillStep } from './interaction-types.js';
2
2
  import { SemaphorDerivedFieldDefinition, MatrixConfig, SemaphorSourceRef, SemaphorResultColumn, SemaphorPivotValue, SemaphorTimeGrain, SemanticGroupedTemporalInput, RawTemporalSelection, TemporalBucketMetadata, TemporalBucketFormat, SemaphorScalarValueFormat, SemaphorValueFormat, MetricComparisonConfig, MetricComparisonPolarity, SemaphorConnectionType } from '../../shared/analytics-protocol/index.js';
3
3
  import { FlatTableExportTotalsBehavior, FlatTableExportTotalsRequest, QueryColumnKeyMap as SharedQueryColumnKeyMap } from '../../shared/format-utils/index.js';
4
4
  import { CardQuerySourceRowEvidence, TemporalResultOwner } from '../../shared/dashboard-authoring/index.js';
5
- import { RelativeDateFilter } from '../../shared/analytics-protocol/relative-date-filter.js';
5
+ import { StoredRelativeDate } from '../../shared/analytics-protocol/relative-date/index.js';
6
6
  /**
7
7
  * Special entity name marker for calculated fields.
8
8
  *
@@ -451,7 +451,7 @@ export interface FilterCondition {
451
451
  * the server resolves it on every run and `value` only keeps the range seen
452
452
  * when it was saved. Valid only with `between` and `not between`.
453
453
  */
454
- relativeMeta?: RelativeDateFilter;
454
+ relativeMeta?: StoredRelativeDate;
455
455
  /**
456
456
  * "Equals the latest value of this field" (analytics kernel K13). With `=`
457
457
  * on a date or timestamp field only. The server resolves it on every run
@@ -7,6 +7,6 @@ export * from './briefing-types.js';
7
7
  export type { AppearanceSpec } from '../appearance/types.js';
8
8
  export type { TChartType } from '../charts/types.js';
9
9
  export type { CanonicalFormatSpec } from '../formatters/canonical-format-adapter.js';
10
- export type { DateUnit, DateSelectionMode, FilterFieldMeta, FilterLocation, FilterSemanticContext, Operation, RelativeDateFilter, RelativeDateUnit, SubDayDateUnit, TFilter, TFilterValue, } from '../../components/surfboard/filter/types.js';
10
+ export type { DateUnit, DateSelectionMode, FilterFieldMeta, FilterLocation, FilterSemanticContext, Operation, RelativeDateWindow, StoredRelativeDate, RelativeDateUnit, SubDayDateUnit, TFilter, TFilterValue, } from '../../components/surfboard/filter/types.js';
11
11
  export type DateComparisonOperation = Extract<import('../../components/surfboard/filter/types.js').Operation, '=' | '!=' | '>' | '>=' | '<' | '<=' | 'between' | 'not between' | 'is null' | 'is not null'>;
12
12
  export * from '../../shared/dashboard-viewer/index.js';
@@ -18,7 +18,7 @@ export declare function readShelfCardFields(card: ShelfDefinitionCard): Authored
18
18
  /** Read-only definition capabilities. Execution and lifecycle remain separate. */
19
19
  export declare function getCardDefinition(card: DefinitionCard, catalog?: MatrixCardCatalog): {
20
20
  kind: "shelf";
21
- status: "absent" | "ready";
21
+ status: "ready" | "absent";
22
22
  fields: AuthoredCardFields;
23
23
  filters: import('../types/explorer-types.js').FilterGroup | undefined;
24
24
  joinPlan: import('../types/explorer-types.js').JoinPlan | undefined;
@@ -28,7 +28,7 @@ export declare function getCardDefinition(card: DefinitionCard, catalog?: Matrix
28
28
  error?: undefined;
29
29
  } | {
30
30
  kind: "matrix";
31
- status: "absent" | "invalid" | "ready";
31
+ status: "ready" | "absent" | "invalid";
32
32
  matrix: {
33
33
  presentation: {
34
34
  totals: {
@@ -74,6 +74,7 @@ export declare function getCardDefinition(card: DefinitionCard, catalog?: Matrix
74
74
  levelFormats: Readonly<Record<string, import('../../shared/analytics-protocol/index.js').SemaphorValueFormat>>;
75
75
  measureFormats: Readonly<Record<string, import('../../shared/analytics-protocol/index.js').SemaphorValueFormat>>;
76
76
  };
77
+ version: 1;
77
78
  spec: {
78
79
  source: {
79
80
  kind: "semantic";
@@ -99,10 +100,10 @@ export declare function getCardDefinition(card: DefinitionCard, catalog?: Matrix
99
100
  aggregate: "SUM" | "COUNT" | "AVG" | "MIN" | "MAX" | "MEDIAN" | "DISTINCT";
100
101
  field: Omit<import('../../shared/analytics-protocol/index.js').SemaphorExecutionFieldRef, "source" | "aggregate" | "derivedField"> & {
101
102
  source?: import('../../shared/analytics-protocol/index.js').SemaphorMatrixSourceRef;
102
- derivedField?: Omit<import('../../data-app-sdk.js').SemaphorDerivedFieldDefinition, "inputs"> & {
103
+ derivedField?: Omit<import('../../shared/analytics-protocol/index.js').SemaphorDerivedFieldDefinition, "inputs"> & {
103
104
  inputs: Record<string, {
104
105
  kind: "field";
105
- field: Omit<import('../../data-app-sdk.js').SemaphorFieldRef, "source"> & {
106
+ field: Omit<import('../../shared/analytics-protocol/index.js').SemaphorFieldRef, "source"> & {
106
107
  source?: import('../../shared/analytics-protocol/index.js').SemaphorMatrixSourceRef;
107
108
  };
108
109
  aggregate?: import('../../shared/analytics-protocol/index.js').SemaphorAggregateFunction;
@@ -112,10 +113,10 @@ export declare function getCardDefinition(card: DefinitionCard, catalog?: Matrix
112
113
  } | {
113
114
  id: string;
114
115
  kind: "calculated";
115
- definition: Omit<import('../../data-app-sdk.js').SemaphorDerivedFieldDefinition, "inputs"> & {
116
+ definition: Omit<import('../../shared/analytics-protocol/index.js').SemaphorDerivedFieldDefinition, "inputs"> & {
116
117
  inputs: Record<string, {
117
118
  kind: "field";
118
- field: Omit<import('../../data-app-sdk.js').SemaphorFieldRef, "source"> & {
119
+ field: Omit<import('../../shared/analytics-protocol/index.js').SemaphorFieldRef, "source"> & {
119
120
  source?: import('../../shared/analytics-protocol/index.js').SemaphorMatrixSourceRef;
120
121
  };
121
122
  aggregate?: import('../../shared/analytics-protocol/index.js').SemaphorAggregateFunction;
@@ -157,7 +158,6 @@ export declare function getCardDefinition(card: DefinitionCard, catalog?: Matrix
157
158
  } | undefined;
158
159
  measureFilters?: readonly import('../../shared/analytics-protocol/matrix-definition-contract.js').MatrixMeasureFilter[] | undefined;
159
160
  };
160
- version: 1;
161
161
  defaultView: {
162
162
  columns: {
163
163
  depth: number;
@@ -0,0 +1,84 @@
1
+ import { z } from 'zod';
2
+ import { SemaphorAbsoluteTimeWindow, SemaphorTimeWindow } from './contracts.js';
3
+ import { RelativeDateWindow } from './relative-date/index.js';
4
+ declare const checkedAbsolute: unique symbol;
5
+ /** An absolute window that passed the reader: both instants parse, start <= end. */
6
+ export type CheckedAbsoluteTimeWindow = SemaphorAbsoluteTimeWindow & {
7
+ readonly [checkedAbsolute]: true;
8
+ };
9
+ /** Every window an agent can state, checked. Only readAgentTimeWindow makes one. */
10
+ export type AgentTimeWindow = RelativeDateWindow | CheckedAbsoluteTimeWindow;
11
+ /** Where a window is going. Each use allows a subset of windows (SPEC-B 3.2). */
12
+ export type AgentTimeWindowUse = 'analysis' | 'cardFilter' | 'filterDefault';
13
+ export type AgentTimeWindowRefusalReason = 'old_form' | 'missing_anchor' | 'seconds' | 'sub_day_periods' | 'sub_day_on_date' | 'over_limit' | 'not_a_window' | 'rolling_days_saved' | 'data_anchor_default' | 'absolute_default' | 'absolute_invalid';
14
+ /** One refusal, worded for an agent: what is wrong and what to send instead (RB-INV-5). */
15
+ export type AgentTimeWindowRefusal = {
16
+ reason: AgentTimeWindowRefusalReason;
17
+ /** One sentence. */
18
+ message: string;
19
+ /** What to send instead, as a window or a choice of windows. Always present. */
20
+ fix: string;
21
+ /**
22
+ * The windows `fix` names, in order, as JSON. Each passes readAgentTimeWindow with the same
23
+ * context (A4). Empty when the fix names no window (old_form, absolute_invalid, some not_a_window).
24
+ */
25
+ suggestions: SemaphorTimeWindow[];
26
+ /** Relative to the window ('anchor', 'n', 'from'); callers prefix the field's path. */
27
+ path?: string;
28
+ };
29
+ export type AgentTimeWindowResult = {
30
+ ok: true;
31
+ window: AgentTimeWindow;
32
+ } | {
33
+ ok: false;
34
+ refusal: AgentTimeWindowRefusal;
35
+ };
36
+ export type AgentTimeWindowContext = {
37
+ use: AgentTimeWindowUse;
38
+ /**
39
+ * For cardFilter and filterDefault: whether the window's date column has a
40
+ * time of day, by the editor's rule. False refuses minute and hour windows
41
+ * (sub_day_on_date). Omitted for analysis, and for a saved use at a tool
42
+ * schema parse, before the field is known.
43
+ */
44
+ columnHasTime?: boolean;
45
+ };
46
+ /** Narrowing helper, the only `kind` test callers need. */
47
+ export declare function isAbsoluteAgentTimeWindow(window: AgentTimeWindow): window is CheckedAbsoluteTimeWindow;
48
+ /**
49
+ * Whether two checked windows are the same window (SPEC-B 3.6): relative
50
+ * windows through the owner's `relativeDatesEqual`, absolute ones by instant.
51
+ * Missing on both sides is the same; on one side, not.
52
+ */
53
+ export declare function sameAgentTimeWindow(left: AgentTimeWindow | undefined, right: AgentTimeWindow | undefined): boolean;
54
+ /** The one reader of an agent's time window. Never throws. */
55
+ export declare function readAgentTimeWindow(input: unknown, context: AgentTimeWindowContext): AgentTimeWindowResult;
56
+ /**
57
+ * The refusal a write of this stored window would get, for readback (SPEC-B
58
+ * 3.6). Undefined when the use accepts it. Its message is the reader's, then
59
+ * "It stays while <field> is left out."
60
+ */
61
+ export declare function storedTimeWindowRefusal(stored: RelativeDateWindow, context: AgentTimeWindowContext, field: 'defaultPeriod' | 'timeWindow'): AgentTimeWindowRefusal | undefined;
62
+ /**
63
+ * The Zod schema for every tool argument that takes a window (SPEC-B 3.3):
64
+ * the strict window shapes and the absolute shape, so a tool's JSON schema
65
+ * lists every shape an agent may send. The reader decides every input once,
66
+ * before the shapes: a refused input is one issue in the reader's words (with
67
+ * its fix), never a shape's ("Unrecognized key(s)"), and an accepted one comes
68
+ * out as the checked window. `columnHasTime` isn't known here; saved uses read
69
+ * again with it. A schema shared by several fields takes the use from the
70
+ * field's path, so the JSON schema lists it once.
71
+ */
72
+ export declare function agentTimeWindowSchema(use: AgentTimeWindowUse | ((path: ReadonlyArray<string | number>) => AgentTimeWindowUse)): z.ZodType<AgentTimeWindow, z.ZodTypeDef, SemaphorTimeWindow>;
73
+ /** A refusal as one issue message, for every surface that reports it (SPEC-B 3.2): "<message> Fix: <fix>". */
74
+ export declare function agentTimeWindowIssueMessage(refusal: AgentTimeWindowRefusal): string;
75
+ /**
76
+ * The message and fix of an issue message `agentTimeWindowIssueMessage`
77
+ * wrote, for a surface that reports them apart (a ChangeDiagnostic); undefined
78
+ * for any other message.
79
+ */
80
+ export declare function splitAgentTimeWindowIssueMessage(message: string): {
81
+ message: string;
82
+ fix: string;
83
+ } | undefined;
84
+ export {};
@@ -1,6 +1,6 @@
1
1
  import { FilterGroup } from '../../lib/types/explorer-types.js';
2
2
  import { MetricComparisonWindowGrain, ResolvedDateWindow } from './metric-comparison.js';
3
- import { RelativeDateFilter } from './relative-date-filter.js';
3
+ import { RelativeDateWindow } from './relative-date/index.js';
4
4
  /**
5
5
  * What a governed query applied, as evidence (analytics agent Plan 1, Phase
6
6
  * 3b, ledger D3b-4): the public conditions of the executed query, decided
@@ -53,7 +53,7 @@ export type AppliedFilterCondition = {
53
53
  values: unknown[];
54
54
  valueType: 'string' | 'number' | 'date' | 'boolean';
55
55
  /** A relative window, with the bounds it resolved to in `values`. */
56
- relative?: RelativeDateFilter;
56
+ relative?: RelativeDateWindow;
57
57
  /**
58
58
  * On a date condition: the calendar zone the query ran in, which its
59
59
  * bounds' day boundaries are in. Bounds that span whole days in it read as
@@ -2,7 +2,7 @@ import { z } from 'zod';
2
2
  import { matrixAnalyticalIntentSchema } from './matrix-definition-contract.js';
3
3
  import { matrixResultSchema } from './matrix-window-contract.js';
4
4
  import { CalendarContext } from '../report-runtime-context/index.js';
5
- import { DateUnit } from './relative-date-filter.js';
5
+ import { RelativeDateWindowInput } from './relative-date/index.js';
6
6
  import { SemaphorQueryConstraints } from './applied-constraints.js';
7
7
  export type SemaphorProtocolVersion = 1;
8
8
  export type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
@@ -340,27 +340,18 @@ export declare const TEMPORAL_BUCKET_CONTRACT_ERROR_CODES: {
340
340
  readonly invalidValue: "invalid_temporal_bucket_value";
341
341
  };
342
342
  export type TemporalBucketContractErrorCode = (typeof TEMPORAL_BUCKET_CONTRACT_ERROR_CODES)[keyof typeof TEMPORAL_BUCKET_CONTRACT_ERROR_CODES];
343
- export type SemaphorRelativeTimeWindow = {
344
- kind?: 'relative';
345
- unit: SemaphorTimeGrain;
346
- value: number;
347
- anchor?: 'now' | 'latest_available';
348
- completeness?: 'include_partial' | 'complete_periods';
349
- };
350
- /** A whole calendar period, such as this month or the previous quarter. */
351
- export type SemaphorCalendarTimeWindow = {
352
- kind: 'calendar';
353
- unit: DateUnit;
354
- period: 'this' | 'previous';
355
- /** Only with period "this": the period so far, ending at the anchor. */
356
- toDate?: boolean;
357
- };
343
+ /** Two instants an agent names. */
358
344
  export type SemaphorAbsoluteTimeWindow = {
359
345
  kind: 'absolute';
360
346
  start: string;
361
347
  end: string;
362
348
  };
363
- export type SemaphorTimeWindow = SemaphorRelativeTimeWindow | SemaphorCalendarTimeWindow | SemaphorAbsoluteTimeWindow;
349
+ /**
350
+ * A date window as an agent sends it (relative-date-as-of Plan B, SPEC-B 2.1):
351
+ * the editor's window input, or two absolute instants. Not checked: read it
352
+ * with `readAgentTimeWindow` or `agentTimeWindowSchema`.
353
+ */
354
+ export type SemaphorTimeWindow = RelativeDateWindowInput | SemaphorAbsoluteTimeWindow;
364
355
  export type SemaphorPaginationRequest = {
365
356
  page: number;
366
357
  pageSize: number;
@@ -167,9 +167,10 @@ export declare const SEMAPHOR_ANALYTICS_INTENT_FIXTURES: {
167
167
  dataType: "date";
168
168
  };
169
169
  timeWindow: {
170
+ kind: "rolling";
170
171
  unit: "month";
171
- value: number;
172
- anchor: "latest_available";
172
+ n: number;
173
+ anchor: "latest_data";
173
174
  };
174
175
  dimensions: {
175
176
  name: string;
@@ -23,8 +23,7 @@ export * from './selection-filter-compiler.js';
23
23
  export * from './temporal-context.js';
24
24
  export * from './temporal-bucket-contract.js';
25
25
  export * from './raw-temporal-contract.js';
26
- export * from './relative-date-filter.js';
27
- export * from './relative-date-label.js';
26
+ export * from './relative-date/index.js';
28
27
  export * from './operation-temporal-state.js';
29
28
  export * from './aggregate-expression.js';
30
29
  export * from './measure-aggregation-profile.js';
@@ -39,8 +38,7 @@ export * from './visual-choice.js';
39
38
  */
40
39
  export { filterGroupSchema as savedFilterGroupSchema } from './explorer-input-schemas.js';
41
40
  export * from '../temporal/index.js';
42
- export * from './time-window.js';
43
- export * from './time-window-schema.js';
41
+ export * from './agent-time-window.js';
44
42
  export * from './scalar-value.js';
45
43
  export * from './matrix-window-contract.js';
46
44
  export * from './matrix-member-presentation.js';
@@ -1885,6 +1885,7 @@ declare const configShape: z.ZodObject<{
1885
1885
  levelFormats: Readonly<Record<string, import('./contracts.js').SemaphorValueFormat>>;
1886
1886
  measureFormats: Readonly<Record<string, import('./contracts.js').SemaphorValueFormat>>;
1887
1887
  };
1888
+ version: 1;
1888
1889
  spec: {
1889
1890
  source: {
1890
1891
  kind: "semantic";
@@ -1954,7 +1955,6 @@ declare const configShape: z.ZodObject<{
1954
1955
  } | undefined;
1955
1956
  measureFilters?: readonly MatrixMeasureFilter[] | undefined;
1956
1957
  };
1957
- version: 1;
1958
1958
  defaultView: {
1959
1959
  columns: {
1960
1960
  depth: number;
@@ -2042,6 +2042,7 @@ declare const configShape: z.ZodObject<{
2042
2042
  levelFormats: Readonly<Record<string, import('./contracts.js').SemaphorValueFormat>>;
2043
2043
  measureFormats: Readonly<Record<string, import('./contracts.js').SemaphorValueFormat>>;
2044
2044
  };
2045
+ version: 1;
2045
2046
  spec: {
2046
2047
  source: {
2047
2048
  kind: "semantic";
@@ -2111,7 +2112,6 @@ declare const configShape: z.ZodObject<{
2111
2112
  } | undefined;
2112
2113
  measureFilters?: readonly MatrixMeasureFilter[] | undefined;
2113
2114
  };
2114
- version: 1;
2115
2115
  defaultView: {
2116
2116
  columns: {
2117
2117
  depth: number;
@@ -2209,6 +2209,7 @@ declare const authoringConfigShape: z.ZodObject<{
2209
2209
  levelFormats: Readonly<Record<string, import('./contracts.js').SemaphorValueFormat>>;
2210
2210
  measureFormats: Readonly<Record<string, import('./contracts.js').SemaphorValueFormat>>;
2211
2211
  };
2212
+ version: 1;
2212
2213
  spec: {
2213
2214
  source: {
2214
2215
  kind: "semantic";
@@ -2278,7 +2279,6 @@ declare const authoringConfigShape: z.ZodObject<{
2278
2279
  } | undefined;
2279
2280
  measureFilters?: readonly MatrixMeasureFilter[] | undefined;
2280
2281
  };
2281
- version: 1;
2282
2282
  defaultView: {
2283
2283
  columns: {
2284
2284
  depth: number;
@@ -2366,6 +2366,7 @@ declare const authoringConfigShape: z.ZodObject<{
2366
2366
  levelFormats: Readonly<Record<string, import('./contracts.js').SemaphorValueFormat>>;
2367
2367
  measureFormats: Readonly<Record<string, import('./contracts.js').SemaphorValueFormat>>;
2368
2368
  };
2369
+ version: 1;
2369
2370
  spec: {
2370
2371
  source: {
2371
2372
  kind: "semantic";
@@ -2435,7 +2436,6 @@ declare const authoringConfigShape: z.ZodObject<{
2435
2436
  } | undefined;
2436
2437
  measureFilters?: readonly MatrixMeasureFilter[] | undefined;
2437
2438
  };
2438
- version: 1;
2439
2439
  defaultView: {
2440
2440
  columns: {
2441
2441
  depth: number;
@@ -0,0 +1,18 @@
1
+ import { RelativeDatePresetId } from './presets.js';
2
+ import { RelativeDateWindow } from './window.js';
3
+ export type RelativeDateDescription = {
4
+ /** A preset's label, or generated wording ("Last 3 months", "Today to 2 days ahead"). */
5
+ label: string;
6
+ /** Set when the window equals a preset's window. */
7
+ presetId?: RelativeDatePresetId;
8
+ /** What the window covers, naming its anchor ("the current month up to now"). */
9
+ definition: string;
10
+ };
11
+ /** The label, preset and definition of a window. */
12
+ export declare function describeRelativeDate(window: RelativeDateWindow): RelativeDateDescription;
13
+ /**
14
+ * Whether two stored values name the same window. Windows compare by their
15
+ * canonical form; two values that aren't windows (fixed defaults, unreadable
16
+ * values) compare as equal stored values; a window never equals a non-window.
17
+ */
18
+ export declare function relativeDatesEqual(a: unknown, b: unknown): boolean;
@@ -0,0 +1,7 @@
1
+ export { allowsRelativeDate, explainRelativeDateInput, readRelativeDate, type DateUnit, type ReadRelativeDateOptions, type RelativeDateProblem, type RelativeDateAnchor, type RelativeDateModeShape, type RelativeDateUnit, type RelativeDateWindow, type RelativeDateWindowInput, type RelativeMonthDayWindowInput, type RelativePeriodsWindowInput, type RelativeRollingWindowInput, type StoredRelativeDate, type SubDayDateUnit, } from './window.js';
2
+ export { RelativeDateUsageError, resolveRelativeDate, type RelativeDateInstants, type RelativeDateResolveOptions, type ResolvedRelativeDate, } from './resolve.js';
3
+ export { describeRelativeDate, relativeDatesEqual, type RelativeDateDescription, } from './describe.js';
4
+ export { relativeDateTraits, type RelativeDateTraits } from './traits.js';
5
+ export { RELATIVE_DATE_PRESETS, type RelativeDatePreset, type RelativeDatePresetCategory, type RelativeDatePresetId, } from './presets.js';
6
+ export { relativeDateWindowSchema, relativeDateWindowShapes, storedRelativeDateSchema } from './schemas.js';
7
+ export { SEMAPHOR_TIME_WINDOW_MAX_VALUE } from './limits.js';
@@ -0,0 +1,3 @@
1
+ import { RelativeDateUnit } from './window.js';
2
+ /** The largest rolling window per unit: ten years. */
3
+ export declare const SEMAPHOR_TIME_WINDOW_MAX_VALUE: Readonly<Record<RelativeDateUnit, number>>;
@@ -0,0 +1,11 @@
1
+ import { RelativeDateWindow } from './window.js';
2
+ export type RelativeDatePresetCategory = 'time' | 'day' | 'week' | 'month' | 'quarter' | 'year';
3
+ export type RelativeDatePresetId = 'last_30_minutes' | 'last_1_hour' | 'last_4_hours' | 'last_12_hours' | 'last_24_hours' | 'today' | 'yesterday' | 'first_day_of_month' | 'last_day_of_month' | 'last_7_days' | 'last_30_days' | 'last_90_days' | 'this_week' | 'last_week' | 'last_2_weeks' | 'this_month' | 'last_month' | 'last_3_months' | 'last_6_months' | 'last_9_months' | 'last_12_months' | 'this_quarter' | 'last_quarter' | 'last_4_quarters' | 'this_year' | 'last_year' | 'year_to_last_completed_month';
4
+ export type RelativeDatePreset = {
5
+ id: RelativeDatePresetId;
6
+ label: string;
7
+ category: RelativeDatePresetCategory;
8
+ window: RelativeDateWindow;
9
+ };
10
+ /** Every preset, in picker order within each category, in canonical form. */
11
+ export declare const RELATIVE_DATE_PRESETS: readonly RelativeDatePreset[];
@@ -0,0 +1,49 @@
1
+ import { RelativeDateWindow } from './window.js';
2
+ import { TemporalCalendar } from '../../temporal/calendar-periods.js';
3
+ /** Inclusive instants: `end` is the last millisecond the window covers. */
4
+ export type ResolvedRelativeDate = {
5
+ start: Date;
6
+ end: Date;
7
+ };
8
+ /** What resolution needs besides the window. */
9
+ export type RelativeDateInstants = {
10
+ /** The report calendar: time zone, week start, fiscal year. */
11
+ calendar: TemporalCalendar;
12
+ /** The run instant: the clock, or a pinned instant for reproducible runs. */
13
+ now: Date;
14
+ /** The data anchor (K11); a data-anchored window counts back from it, else from `now`. */
15
+ latestData?: Date;
16
+ };
17
+ export type RelativeDateResolveOptions = {
18
+ /**
19
+ * Resolve the comparison window `spansBack` spans before the current one
20
+ * (SPEC 3.3). Only for windows whose trait `comparesBySpan` is true.
21
+ * Default 0, the current window.
22
+ */
23
+ spansBack?: number;
24
+ };
25
+ /**
26
+ * A programming error, never a data error: `spansBack` on a window whose
27
+ * `comparesBySpan` is false, or a `spansBack` that is not a whole number of
28
+ * spans.
29
+ */
30
+ export declare class RelativeDateUsageError extends Error {
31
+ constructor(message: string);
32
+ }
33
+ /**
34
+ * The instants a window covers in the calendar (SPEC 3.2):
35
+ * - `periods`: from the start of period `from` to the end of period `to`,
36
+ * both counted from the period containing the anchor; with `toDate`, to
37
+ * the anchor itself;
38
+ * - `rolling`: back from the anchor by `n` units (minutes and hours count
39
+ * elapsed time; days and longer, the same wall-clock time `n` units earlier);
40
+ * - `monthDay`: the first or last day of the month containing `now`.
41
+ * The anchor is `now`; the data anchor for a window anchored at the latest
42
+ * data, when the caller passes one; or the last millisecond before the
43
+ * `lastComplete` period containing `now`. Weeks start on the calendar's week
44
+ * start; quarters and years follow its fiscal calendar when it has one.
45
+ *
46
+ * With `spansBack`, the window `spansBack` spans earlier by the comparison
47
+ * rule (SPEC 3.3).
48
+ */
49
+ export declare function resolveRelativeDate(window: RelativeDateWindow, at: RelativeDateInstants, options?: RelativeDateResolveOptions): ResolvedRelativeDate;