react-semaphor 0.1.602 → 0.1.604

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 (211) hide show
  1. package/dist/activity/index.js +1 -73
  2. package/dist/analytics-protocol/index.js +1 -1451
  3. package/dist/appearance/index.js +1 -12
  4. package/dist/appearance-runtime/index.js +1 -5
  5. package/dist/assistant-context/index.js +1 -11
  6. package/dist/assistant-protocol/index.js +1 -152
  7. package/dist/brand-studio/index.js +4 -1594
  8. package/dist/briefings/index.js +1 -70
  9. package/dist/chunks/add-to-dashboard-DeHEBEqG.js +12 -0
  10. package/dist/chunks/analytics-base-schemas-BREc5WGv.js +1 -0
  11. package/dist/chunks/appearance-context-BqBZrijL.js +1 -0
  12. package/dist/chunks/appearance-runtime-provider-DmbCrOOG.js +1 -0
  13. package/dist/chunks/applied-constraints-CinevlKD.js +1 -0
  14. package/dist/chunks/assistant-chat-CjYrwVDa.js +56 -0
  15. package/dist/chunks/attribution-BEFSsbNn.js +1 -0
  16. package/dist/chunks/availability-3AIOf6Z-.js +1 -0
  17. package/dist/chunks/bookmark-impact-C89zBLq3.js +1 -0
  18. package/dist/chunks/bookmark-state-69YYnRql.js +1 -0
  19. package/dist/chunks/brand-DCaZyRt6.js +1 -0
  20. package/dist/chunks/card-filter-builder-CTp6RAz1.js +17 -0
  21. package/dist/chunks/column-bands-DwxbZ6UI.js +1 -0
  22. package/dist/chunks/comparison-window-caption-C312mn3s.js +1 -0
  23. package/dist/chunks/context-ALdccLHw.js +2 -0
  24. package/dist/chunks/conversation-JMK2kyTK.js +1 -0
  25. package/dist/chunks/dashboard-BX28ld6s.js +1 -0
  26. package/dist/chunks/dashboard-briefing-launcher-qo7GH4EO.js +37 -0
  27. package/dist/chunks/dashboard-controls-DhRjB7MA.js +42 -0
  28. package/dist/chunks/dashboard-json-9cHzhSjC.js +1 -0
  29. package/dist/chunks/dates-D-KP8G-z.js +1 -0
  30. package/dist/chunks/edit-DEAK0UZo.js +1 -0
  31. package/dist/chunks/edit-dashboard-visual-Duq_QkB_.js +93 -0
  32. package/dist/chunks/export-file-format-B-wQNHIn.js +4 -0
  33. package/dist/chunks/filter-line-CwQrqORc.js +1 -0
  34. package/dist/chunks/filter-reach-preview-gixPFlZj.js +1 -0
  35. package/dist/chunks/filter-value-text-B3tXakhd.js +1 -0
  36. package/dist/chunks/index-B-VF1ogs.js +1 -0
  37. package/dist/chunks/index-BE1DfxNs.js +1 -0
  38. package/dist/chunks/index-DViPGDFj.js +1 -0
  39. package/dist/chunks/layout-grid-BWtlgw0T.js +6 -0
  40. package/dist/chunks/matrix-analytical-definition-CtFqWyCK.js +1 -0
  41. package/dist/chunks/matrix-member-presentation-Q0MCJ-YK.js +1 -0
  42. package/dist/chunks/matrix-operation-contract-D1RC1bfi.js +1 -0
  43. package/dist/chunks/metric-comparison-DEZYXROZ.js +1 -0
  44. package/dist/chunks/normalize-dashboard-for-dirty-check-ILKfqgL3.js +1 -0
  45. package/dist/chunks/paintbrush-BjS3SbrH.js +6 -0
  46. package/dist/chunks/palette-BzC-CGOc.js +6 -0
  47. package/dist/chunks/pickers-DuBrUht0.js +1 -0
  48. package/dist/chunks/pivot-result-contract-expectations-DTQAgr4n.js +1 -0
  49. package/dist/chunks/pivot-result-identity-DTNCB--h.js +1 -0
  50. package/dist/chunks/raw-temporal-value-DeyEhL0S.js +1 -0
  51. package/dist/chunks/rendered-file-BbvwaU6z.js +1 -0
  52. package/dist/chunks/report-preferences-dialog-B_gUmCzG.js +1 -0
  53. package/dist/chunks/report-runtime-context-BWzIHCKK.js +1 -0
  54. package/dist/chunks/resolve-dashboard-input-context-B-TtRqxu.js +8 -0
  55. package/dist/chunks/resolver-AN9ChBfZ.js +1 -0
  56. package/dist/chunks/save-DdFUZcbi.js +6 -0
  57. package/dist/chunks/saved-dashboard-context-BAJ5tWiq.js +1 -0
  58. package/dist/chunks/schema-MC0cQSAb.js +4 -0
  59. package/dist/chunks/selection-filter-compiler-CCoCD25M.js +1 -0
  60. package/dist/chunks/semaphor-ready-indicator-DzjorP3t.js +999 -0
  61. package/dist/chunks/set-DuJfGkbY.js +1 -0
  62. package/dist/chunks/shelf-drop-preview-context-BlLJ5RsT.js +6 -0
  63. package/dist/chunks/stored-dashboard-Ctcpkllg.js +1 -0
  64. package/dist/chunks/style-sheet-parts-BRGt9O05.js +178 -0
  65. package/dist/chunks/table-export-sheet-rC5pKmXg.js +2 -0
  66. package/dist/chunks/token-types-Bj9iMy0w.js +1 -0
  67. package/dist/chunks/validators-CqV3Yka1.js +1 -0
  68. package/dist/chunks/variable-draft-DJrfUyhv.js +1 -0
  69. package/dist/chunks/visual-choice-DgEFfkE-.js +1 -0
  70. package/dist/dashboard/index.js +1 -7
  71. package/dist/dashboard-authoring/index.js +1 -4491
  72. package/dist/format-utils/index.js +1 -424
  73. package/dist/index.js +1 -554
  74. package/dist/layouts/index.js +1 -7
  75. package/dist/live-channel/index.js +1 -124
  76. package/dist/pdf-export-policy/index.js +1 -92
  77. package/dist/pdf-table-layout/index.js +1 -993
  78. package/dist/report-runtime-context/index.js +1 -9
  79. package/dist/shared/index.js +1 -6
  80. package/dist/style.css +1 -1
  81. package/dist/surfboard/index.js +1 -9
  82. package/dist/types/components/ui-custom/date-range-presets.d.ts +8 -0
  83. package/dist/types/index.js +1 -88
  84. package/dist/types/lib/document/document-edits.d.ts +0 -4
  85. package/dist/types/lib/filter-values/build-card-filter-definition.d.ts +32 -0
  86. package/dist/types/lib/query-context/dashboard-filter-mapping-resolution.d.ts +9 -0
  87. package/dist/types/lib/stores/dashboard-store.d.ts +0 -1
  88. package/dist/types/lib/stores/explorer-actions.d.ts +7 -6
  89. package/dist/types/lib/types/common-types.d.ts +0 -2
  90. package/dist/types/lib/types/explorer-types.d.ts +1 -1
  91. package/dist/types/lib/types/semantic-types.d.ts +6 -10
  92. package/dist/types/lib/utils/field-state-calculator.d.ts +7 -19
  93. package/dist/types/shared/analytics-protocol/analytics-base-schemas.d.ts +18 -0
  94. package/dist/types/shared/analytics-protocol/analyze-result-types.d.ts +3 -0
  95. package/dist/types/shared/analytics-protocol/comparison-choices.d.ts +92 -0
  96. package/dist/types/shared/analytics-protocol/comparison-placement.d.ts +30 -0
  97. package/dist/types/shared/analytics-protocol/contracts.d.ts +11 -5
  98. package/dist/types/shared/analytics-protocol/date-window.d.ts +105 -0
  99. package/dist/types/shared/analytics-protocol/filter-field-ownership.d.ts +27 -0
  100. package/dist/types/shared/analytics-protocol/fixtures.d.ts +4 -2
  101. package/dist/types/shared/analytics-protocol/index.d.ts +3 -0
  102. package/dist/types/shared/analytics-protocol/metric-comparison.d.ts +93 -11
  103. package/dist/types/shared/assistant-protocol/context.d.ts +16 -16
  104. package/dist/types/shared/dashboard-authoring/calculations/calculated-column.d.ts +1 -1
  105. package/dist/types/shared/dashboard-authoring/calculations/definition.d.ts +13 -0
  106. package/dist/types/shared/dashboard-authoring/card-data-source/card-base.d.ts +125 -0
  107. package/dist/types/shared/dashboard-authoring/card-data-source/card-field-folders.d.ts +55 -0
  108. package/dist/types/shared/dashboard-authoring/card-data-source/card-joins.d.ts +114 -0
  109. package/dist/types/shared/dashboard-authoring/card-data-source/card-prune.d.ts +12 -0
  110. package/dist/types/shared/dashboard-authoring/card-data-source/filter-field-catalog.d.ts +60 -0
  111. package/dist/types/shared/dashboard-authoring/card-data-source/filter-field-folders.d.ts +132 -0
  112. package/dist/types/shared/dashboard-authoring/card-data-source/index.d.ts +7 -0
  113. package/dist/types/shared/dashboard-authoring/card-data-source/join-reach.d.ts +42 -0
  114. package/dist/types/shared/dashboard-authoring/card-field-places.d.ts +28 -0
  115. package/dist/types/shared/dashboard-authoring/card-settings/card-display-write.d.ts +8 -0
  116. package/dist/types/shared/dashboard-authoring/card-settings/card-kinds.d.ts +1 -1
  117. package/dist/types/shared/dashboard-authoring/card-settings/inputs.d.ts +2 -1
  118. package/dist/types/shared/dashboard-authoring/card-settings/resolved.d.ts +0 -3
  119. package/dist/types/shared/dashboard-authoring/changes/dashboard-change.d.ts +21 -358
  120. package/dist/types/shared/dashboard-authoring/changes/diagnostics.d.ts +2 -0
  121. package/dist/types/shared/dashboard-authoring/conditional-formatting/schema.d.ts +10 -10
  122. package/dist/types/shared/dashboard-authoring/dashboard-variable-card.d.ts +2 -4
  123. package/dist/types/shared/dashboard-authoring/field-folders/field-folders.d.ts +115 -0
  124. package/dist/types/shared/dashboard-authoring/field-folders/index.d.ts +1 -0
  125. package/dist/types/shared/dashboard-authoring/filter-reach-decision.d.ts +11 -0
  126. package/dist/types/shared/dashboard-authoring/index.d.ts +6 -1
  127. package/dist/types/shared/dashboard-authoring/kpi-date-context.d.ts +2 -0
  128. package/dist/types/shared/dashboard-authoring/kpi-figure.d.ts +18 -0
  129. package/dist/types/shared/dashboard-authoring/measure-calculations/comparison.d.ts +8 -7
  130. package/dist/types/shared/dashboard-authoring/measure-calculations/dates.d.ts +11 -1
  131. package/dist/types/shared/dashboard-authoring/measure-calculations/index.d.ts +2 -2
  132. package/dist/types/shared/dashboard-authoring/measure-calculations/options.d.ts +4 -0
  133. package/dist/types/shared/dashboard-authoring/measure-calculations/read.d.ts +18 -1
  134. package/dist/types/shared/dashboard-authoring/measure-calculations/resolve.d.ts +2 -0
  135. package/dist/types/shared/dashboard-authoring/measure-calculations/schemas.d.ts +46 -88
  136. package/dist/types/shared/dashboard-authoring/operations/calculated-field-operations.d.ts +33 -8
  137. package/dist/types/shared/dashboard-authoring/operations/operation-types.d.ts +0 -2
  138. package/dist/types/shared/dashboard-authoring/outline/outline-filters.d.ts +5 -0
  139. package/dist/types/shared/dashboard-authoring/see-records/result.d.ts +7 -22
  140. package/dist/types/shared/format-utils/comparison-detail.d.ts +34 -0
  141. package/dist/types/shared/format-utils/index.d.ts +1 -0
  142. package/dist/types/shared/format-utils/partial-period.d.ts +4 -2
  143. package/dist/types/shared/temporal/calendar-periods.d.ts +11 -0
  144. package/dist/types/shared/temporal/index.d.ts +2 -0
  145. package/dist/types/shared/temporal/temporal-text.d.ts +33 -0
  146. package/dist/types/shared/temporal/temporal.d.ts +27 -0
  147. package/dist/types/shared/temporal/zoned-wall-clock.d.ts +4 -3
  148. package/dist/usage-events/index.js +1 -285
  149. package/dist/value-format-preferences/index.js +1 -635
  150. package/package.json +6 -2
  151. package/dist/chunks/add-to-dashboard-ClhEIFst.js +0 -291
  152. package/dist/chunks/analytics-base-schemas-DevrgqQb.js +0 -678
  153. package/dist/chunks/appearance-context-BwBp25ZG.js +0 -162
  154. package/dist/chunks/appearance-runtime-provider-BRHYELkC.js +0 -80
  155. package/dist/chunks/applied-constraints-DU-wndZ7.js +0 -47
  156. package/dist/chunks/assistant-chat-BWF3GYip.js +0 -6115
  157. package/dist/chunks/attribution-BvoKvhcj.js +0 -32
  158. package/dist/chunks/availability-Bp5Gfu1I.js +0 -44
  159. package/dist/chunks/bookmark-impact-BF3iRx5a.js +0 -76
  160. package/dist/chunks/bookmark-state-CBSTdW6q.js +0 -1666
  161. package/dist/chunks/brand-BoUV0iHF.js +0 -54
  162. package/dist/chunks/card-filter-builder-B8XHwMY6.js +0 -4069
  163. package/dist/chunks/column-bands-RdM-kjDe.js +0 -47
  164. package/dist/chunks/comparison-window-caption-W83qB4V5.js +0 -741
  165. package/dist/chunks/context-BJoEFgNl.js +0 -369
  166. package/dist/chunks/conversation-sQiWYUOb.js +0 -16
  167. package/dist/chunks/dashboard-DG5EIYYB.js +0 -14
  168. package/dist/chunks/dashboard-briefing-launcher-CBSrhyWZ.js +0 -4875
  169. package/dist/chunks/dashboard-controls-D6ECO4N1.js +0 -2290
  170. package/dist/chunks/dashboard-json-DrJftBSL.js +0 -66
  171. package/dist/chunks/dates-Bz-qM5px.js +0 -164
  172. package/dist/chunks/edit-9df1zOWe.js +0 -226
  173. package/dist/chunks/edit-dashboard-visual-BDYAJIbb.js +0 -18605
  174. package/dist/chunks/export-file-format-C-tJsxsf.js +0 -111
  175. package/dist/chunks/filter-line-BXT6y303.js +0 -703
  176. package/dist/chunks/filter-reach-copy-BukhZmzm.js +0 -5250
  177. package/dist/chunks/filter-value-text-D3-bf3_b.js +0 -153
  178. package/dist/chunks/index-BVKzKl5d.js +0 -90
  179. package/dist/chunks/index-BW0yozjs.js +0 -2795
  180. package/dist/chunks/index-CV_Kzou0.js +0 -595
  181. package/dist/chunks/layout-grid-Ds0diMeY.js +0 -16
  182. package/dist/chunks/matrix-analytical-definition-CgQgVeeI.js +0 -1162
  183. package/dist/chunks/matrix-member-presentation-DSBIIudt.js +0 -258
  184. package/dist/chunks/matrix-operation-contract--DkNCOzd.js +0 -1412
  185. package/dist/chunks/metric-comparison-zMylnIkc.js +0 -541
  186. package/dist/chunks/normalize-dashboard-for-dirty-check-XKgH3GFX.js +0 -119
  187. package/dist/chunks/paintbrush-CX8pao1j.js +0 -27
  188. package/dist/chunks/palette-CuA0HlzF.js +0 -23
  189. package/dist/chunks/pickers-DkqmtnTL.js +0 -2403
  190. package/dist/chunks/pivot-result-contract-expectations-C8KL7hPx.js +0 -5046
  191. package/dist/chunks/pivot-result-identity-C1AOH1PS.js +0 -77
  192. package/dist/chunks/raw-temporal-value-E416F-0L.js +0 -454
  193. package/dist/chunks/rendered-file-D8xEuVVx.js +0 -108
  194. package/dist/chunks/report-preferences-dialog-CbuVNDGi.js +0 -1637
  195. package/dist/chunks/report-runtime-context-E7USjN7E.js +0 -388
  196. package/dist/chunks/resolve-dashboard-input-context-CULCE_hM.js +0 -25172
  197. package/dist/chunks/resolver-DG_tfEpt.js +0 -156
  198. package/dist/chunks/save-BKHlDONy.js +0 -21
  199. package/dist/chunks/saved-dashboard-context-C1WlOx5z.js +0 -632
  200. package/dist/chunks/schema-C9NPiIru.js +0 -2568
  201. package/dist/chunks/selection-filter-compiler-ifT8JCXS.js +0 -131
  202. package/dist/chunks/semaphor-ready-indicator-CBIRcDWs.js +0 -145326
  203. package/dist/chunks/shelf-drop-preview-context-xR69SMA8.js +0 -2466
  204. package/dist/chunks/stored-dashboard-BuM8vnWf.js +0 -4070
  205. package/dist/chunks/style-sheet-parts-Bt9ZNre8.js +0 -8674
  206. package/dist/chunks/table-export-sheet-DVljtHkG.js +0 -949
  207. package/dist/chunks/token-types-D_xKgyVS.js +0 -8
  208. package/dist/chunks/upload-Dll_M7XQ.js +0 -15
  209. package/dist/chunks/validators-ClWHpYql.js +0 -3686
  210. package/dist/chunks/variable-draft-CDGGl53R.js +0 -242
  211. package/dist/chunks/visual-choice-DDfHfHvY.js +0 -172
@@ -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
  };
@@ -13,6 +13,9 @@ export * from './physical-source-resolution.js';
13
13
  export * from './source-entity-resolution.js';
14
14
  export * from './fixtures.js';
15
15
  export * from './metric-comparison.js';
16
+ export * from './comparison-choices.js';
17
+ export * from './date-window.js';
18
+ export * from './comparison-placement.js';
16
19
  export * from './applied-constraints.js';
17
20
  export * from './filter-field-ownership.js';
18
21
  export * from './click-reach-filter-id.js';
@@ -1,6 +1,30 @@
1
1
  import { SemaphorFieldRef, SemaphorTimeGrain, SemaphorValidationResult } from './contracts.js';
2
2
  import { TemporalShift } from '../temporal/calendar-periods.js';
3
- export type MetricComparisonSpec = {
3
+ import { ComparisonWindowShape } from './comparison-choices.js';
4
+ /**
5
+ * How far back a comparison steps (compare-with CW-D3): the window's own
6
+ * length (`period`, the previous period) or a fixed calendar unit.
7
+ */
8
+ export type ComparisonUnit = 'period' | 'day' | 'week' | 'month' | 'quarter' | 'year';
9
+ export declare const COMPARISON_UNITS: readonly ["period", "day", "week", "month", "quarter", "year"];
10
+ /** A step back: `offset` units (1 when absent); only a step by years may match weekdays (364 days a year, CW-D4). */
11
+ export type ComparisonShiftSpec = {
12
+ kind: 'shift';
13
+ unit: ComparisonUnit;
14
+ offset?: number;
15
+ matchWeekdays?: true;
16
+ };
17
+ /** What a measure is compared with: a step back, or a fixed number. */
18
+ export type MetricComparisonSpec = ComparisonShiftSpec | {
19
+ kind: 'target';
20
+ targetValue: number;
21
+ };
22
+ /**
23
+ * The period shapes saved before Compare with (CW-D5): still on stored cards,
24
+ * Date filter selections, bookmarks and variables, read through
25
+ * `readMetricComparisonSpec` and never written.
26
+ */
27
+ export type LegacyPeriodComparisonSpec = {
4
28
  kind: 'previous_period';
5
29
  offsetPeriods?: number;
6
30
  alignment?: 'calendar' | 'weekday';
@@ -10,16 +34,29 @@ export type MetricComparisonSpec = {
10
34
  offsetYears?: number;
11
35
  alignment?: 'calendar' | 'weekday';
12
36
  toDate?: boolean;
13
- } | {
14
- kind: 'target';
15
- targetValue: number;
16
37
  };
38
+ /** A comparison as stored: the spec, or a shape saved before Compare with. */
39
+ export type StoredMetricComparisonSpec = MetricComparisonSpec | LegacyPeriodComparisonSpec;
17
40
  export type MetricComparisonConfig = {
18
41
  mode: 'off';
19
42
  } | {
20
43
  mode: 'explicit';
21
- spec: MetricComparisonSpec;
44
+ spec: StoredMetricComparisonSpec;
22
45
  };
46
+ /**
47
+ * The one reader of a stored comparison (CW-D5, CW-INV-4): an old period
48
+ * shape becomes a step back (`previous_period` by the window's own length,
49
+ * `previous_year` by years, matching weekdays when it aligned by weekday); a
50
+ * stored `toDate` says nothing (CW-D2); a weekday alignment on a previous
51
+ * period is dropped (no saved card has one, ledger IN-03). An offset of 1 is
52
+ * left out.
53
+ */
54
+ export declare function readMetricComparisonSpec(spec: StoredMetricComparisonSpec): MetricComparisonSpec;
55
+ /** What a comparison is called in results and metadata (CW-D13): a step by years is the previous year. */
56
+ export type ComparisonFamily = 'previous_period' | 'previous_year' | 'target';
57
+ export declare function comparisonFamily(spec: StoredMetricComparisonSpec): ComparisonFamily;
58
+ /** How many steps back (1 when absent). */
59
+ export declare function comparisonOffset(spec: ComparisonShiftSpec): number;
23
60
  export type MetricComparisonPolarity = 'higher_is_better' | 'lower_is_better' | 'neutral';
24
61
  export declare const DEFAULT_METRIC_COMPARISON_POLARITY: "higher_is_better";
25
62
  export type ComparisonPresentationSpec = {
@@ -55,14 +92,15 @@ export declare const COMPARISON_PRESENTATION_DEFAULTS: {
55
92
  readonly showColor: true;
56
93
  readonly conditionalLabel: false;
57
94
  };
58
- export type ViewerPeriodComparisonSpec = Extract<MetricComparisonSpec, {
59
- kind: 'previous_period' | 'previous_year';
60
- }>;
95
+ /** A comparison a dashboard date can carry: a step back, never a target. */
96
+ export type ViewerPeriodComparisonSpec = ComparisonShiftSpec;
97
+ /** A dashboard date's comparison as stored: a step back, or a period shape saved before Compare with. */
98
+ export type StoredViewerPeriodComparisonSpec = ComparisonShiftSpec | LegacyPeriodComparisonSpec;
61
99
  export type GlobalDateComparisonSelection = {
62
100
  mode: 'off';
63
101
  } | {
64
102
  mode: 'period';
65
- spec: ViewerPeriodComparisonSpec;
103
+ spec: StoredViewerPeriodComparisonSpec;
66
104
  };
67
105
  export type DashboardDateComparisonOwner = {
68
106
  kind: 'global_date';
@@ -84,6 +122,39 @@ export type ResolvedMetricComparisonRequest = {
84
122
  spec: ViewerPeriodComparisonSpec;
85
123
  owner?: DashboardDateComparisonOwner;
86
124
  };
125
+ /**
126
+ * What a measure compares with, as one of three states (compare-with CW-D17):
127
+ * `pinned` to its own step or target (any stored comparison reads as pinned,
128
+ * CW-D20), `off`, or `follow` the Date filter's comparison. A measure with no
129
+ * comparison of its own on a card saved with "Inherit Global Date comparison"
130
+ * off reads as off, what it showed (CW-D21); the card switch is read here and
131
+ * nowhere else.
132
+ */
133
+ export type MeasureComparisonState = {
134
+ state: 'follow';
135
+ } | {
136
+ state: 'pinned';
137
+ spec: MetricComparisonSpec;
138
+ } | {
139
+ state: 'off';
140
+ };
141
+ export declare function readMeasureComparisonState(input: {
142
+ metricComparison?: MetricComparisonConfig;
143
+ inheritGlobalComparison?: false;
144
+ /**
145
+ * The card's comparisons are saved hidden ("Show comparison" off): every
146
+ * measure reads as off and none runs (compare-with CW-D28).
147
+ */
148
+ hidden?: boolean;
149
+ }): MeasureComparisonState;
150
+ /** Whether a card's comparisons are saved hidden ("Show comparison" off), the one reading of it (CW-D28). */
151
+ export declare function comparisonsHidden(presentation: Pick<ComparisonPresentationSpec, 'showComparison'> | undefined): boolean;
152
+ /**
153
+ * The comparison a measure runs with, from its state alone (CW-D17): pinned
154
+ * runs its own, follow runs the Date filter's comparison when there is one,
155
+ * off runs none. What asks decides what reaches it: a text variable gets no
156
+ * Date filter comparison (CW-D22), so it never follows.
157
+ */
87
158
  export declare function resolveMetricComparisonRequest(input: {
88
159
  metricComparison?: MetricComparisonConfig;
89
160
  inheritGlobalComparison?: false;
@@ -96,7 +167,9 @@ export type ResolvedDateWindow = {
96
167
  };
97
168
  export type ComparisonUnavailableReason = 'finite_current_window_required' | 'current_window_not_started'
98
169
  /** The date ranges the run applies to the field have no instant in common. */
99
- | 'current_window_empty' | 'temporal_binding_missing' | 'temporal_binding_ambiguous' | 'temporal_binding_invalid' | 'unsupported_output_shape' | 'unsupported_raw_sql' | 'insufficient_history' | 'invalid_comparison_spec' | 'comparison_execution_failed';
170
+ | 'current_window_empty' | 'temporal_binding_missing' | 'temporal_binding_ambiguous' | 'temporal_binding_invalid' | 'unsupported_output_shape' | 'unsupported_raw_sql' | 'insufficient_history'
171
+ /** A fixed step shorter than the window: the earlier window would overlap it (compare-with CW-D7). */
172
+ | 'overlaps_current_window' | 'invalid_comparison_spec' | 'comparison_execution_failed';
100
173
  export type ComparisonAvailability = {
101
174
  status: 'available';
102
175
  } | {
@@ -110,7 +183,15 @@ export type MetricComparisonOutputBase = {
110
183
  metricAlias: string;
111
184
  currentColumnKey: string;
112
185
  windowGrain?: MetricComparisonWindowGrain;
186
+ /** The current window as the run filtered it: cut at the run instant while it is still running (CW-D1). */
113
187
  currentWindow?: ResolvedDateWindow;
188
+ /**
189
+ * What the current window is, for naming its comparison (CW-D12, CW-D15):
190
+ * the window the user picked (This month), or a range whole and on the
191
+ * report calendar, worked out once where the run plans it. A running month
192
+ * then reads "Previous month", not its elapsed days (ledger P4-11).
193
+ */
194
+ windowShape?: ComparisonWindowShape;
114
195
  comparisonWindow?: ResolvedDateWindow;
115
196
  /**
116
197
  * How far back `comparisonWindow` sits from `currentWindow`: the one step a
@@ -158,7 +239,8 @@ export type MetricComparisonOutput = MetricComparisonOutputBase & ({
158
239
  comparisonSourceBucketColumnKey?: never;
159
240
  });
160
241
  export type MetricComparisonMetadataEntry = {
161
- type: MetricComparisonSpec['kind'];
242
+ /** The comparison's family (CW-D13), not the spec's kind. */
243
+ type: ComparisonFamily;
162
244
  displayName?: string;
163
245
  displayLabel?: string;
164
246
  output: MetricComparisonOutput;
@@ -625,15 +625,15 @@ export declare const assistantContextSchema: z.ZodEffects<z.ZodObject<{
625
625
  title: string;
626
626
  unsavedEdits: boolean;
627
627
  } | undefined;
628
- sheet?: {
629
- id: string;
630
- title: string;
631
- } | undefined;
632
628
  omitted?: {
633
629
  cards?: number | undefined;
634
630
  otherSheets?: number | undefined;
635
631
  activeInputs?: number | undefined;
636
632
  } | undefined;
633
+ sheet?: {
634
+ id: string;
635
+ title: string;
636
+ } | undefined;
637
637
  selectedCard?: {
638
638
  id: string;
639
639
  description: {
@@ -717,15 +717,15 @@ export declare const assistantContextSchema: z.ZodEffects<z.ZodObject<{
717
717
  title: string;
718
718
  unsavedEdits: boolean;
719
719
  } | undefined;
720
- sheet?: {
721
- id: string;
722
- title: string;
723
- } | undefined;
724
720
  omitted?: {
725
721
  cards?: number | undefined;
726
722
  otherSheets?: number | undefined;
727
723
  activeInputs?: number | undefined;
728
724
  } | undefined;
725
+ sheet?: {
726
+ id: string;
727
+ title: string;
728
+ } | undefined;
729
729
  selectedCard?: {
730
730
  id: string;
731
731
  description: {
@@ -809,15 +809,15 @@ export declare const assistantContextSchema: z.ZodEffects<z.ZodObject<{
809
809
  title: string;
810
810
  unsavedEdits: boolean;
811
811
  } | undefined;
812
- sheet?: {
813
- id: string;
814
- title: string;
815
- } | undefined;
816
812
  omitted?: {
817
813
  cards?: number | undefined;
818
814
  otherSheets?: number | undefined;
819
815
  activeInputs?: number | undefined;
820
816
  } | undefined;
817
+ sheet?: {
818
+ id: string;
819
+ title: string;
820
+ } | undefined;
821
821
  selectedCard?: {
822
822
  id: string;
823
823
  description: {
@@ -901,15 +901,15 @@ export declare const assistantContextSchema: z.ZodEffects<z.ZodObject<{
901
901
  title: string;
902
902
  unsavedEdits: boolean;
903
903
  } | undefined;
904
- sheet?: {
905
- id: string;
906
- title: string;
907
- } | undefined;
908
904
  omitted?: {
909
905
  cards?: number | undefined;
910
906
  otherSheets?: number | undefined;
911
907
  activeInputs?: number | undefined;
912
908
  } | undefined;
909
+ sheet?: {
910
+ id: string;
911
+ title: string;
912
+ } | undefined;
913
913
  selectedCard?: {
914
914
  id: string;
915
915
  description: {
@@ -22,7 +22,7 @@ export type CalculatedColumnKind = 'domain_reference' | 'dashboard_copy' | 'no_d
22
22
  /**
23
23
  * What a calculated column is, in this order: a domain reference (the run
24
24
  * path rebuilds it from the domain), a copy of one of the dashboard's fields
25
- * (the run path runs it as stored), or a column without a definition (a
25
+ * (the run path rebuilds it from its field's definition, MC-D21), or a column without a definition (a
26
26
  * frozen copy, a raw SQL copy, a card-field copy, a dashboard copy whose
27
27
  * field is gone).
28
28
  */
@@ -127,3 +127,16 @@ export declare function dashboardFieldFromCompiled(input: {
127
127
  description?: string;
128
128
  id: string;
129
129
  }): MetricField | GroupByField;
130
+ /** The semantic domain a dashboard calculated field's inputs read, when they name one. */
131
+ export declare function calculatedFieldDomainId(field: Field): string | undefined;
132
+ /**
133
+ * The one domain dataset a calculated field reads, when it reads exactly one:
134
+ * its inputs' dataset and their semantic domain (source identity is domain
135
+ * plus dataset). The MCP outline lists a dashboard calculation by it, and the
136
+ * filter pickers put the field in that dataset's folder (dashboard filter
137
+ * fields, review P6-04). Undefined for a field over several datasets or none.
138
+ */
139
+ export declare function calculatedFieldSemanticSource(field: Field): {
140
+ domainId: string;
141
+ datasetName: string;
142
+ } | undefined;
@@ -0,0 +1,125 @@
1
+ import { TCard } from '../../../lib/types/common-types.js';
2
+ import { DataSource, DatabaseEntityReference, Field, MetricField } from '../../../lib/types/explorer-types.js';
3
+ import { SemaphorSourceRef } from '../../analytics-protocol/index.js';
4
+ type Entity = DatabaseEntityReference;
5
+ /** The base first, then each other entity once, in the order given. */
6
+ export declare function cardSelectedEntities<E extends {
7
+ name: string;
8
+ }>(base: E, reads: readonly E[], same?: (a: E, b: E) => boolean): E[];
9
+ /**
10
+ * The card's base as it is saved (OB-D11, OB-D17): the selected entity
11
+ * `queryBaseSource` names, else its own join plan's base, else the base the
12
+ * server resolved for its last query, else the first selected.
13
+ */
14
+ export declare function cardBaseEntity(card: Pick<TCard, 'type' | 'config' | 'dataSource'>, resolvedBaseName?: string): Entity | undefined;
15
+ /**
16
+ * A dataset the base reaches, as a selected entity: the base's connection
17
+ * and domain, the dataset's own name, label and table (the joinability
18
+ * response's `datasets`).
19
+ */
20
+ export declare function reachedDatasetEntity(base: Entity, dataset: {
21
+ name: string;
22
+ label?: string | null;
23
+ table?: string | null;
24
+ schema?: string | null;
25
+ catalog?: string | null;
26
+ type?: string;
27
+ }): Entity;
28
+ /**
29
+ * The domain dataset a saved selection's name stands for (ledger P0-02,
30
+ * P4-08): the name itself, then by case, by label, then a qualified name's
31
+ * last part. The one reader of a selection's spellings; a name no dataset
32
+ * answers comes back as it is.
33
+ */
34
+ export declare function resolveDatasetName(name: string, datasets: readonly {
35
+ name: string;
36
+ label?: string | null;
37
+ }[] | undefined): string;
38
+ /** The source reference a base states as `config.queryBaseSource`. */
39
+ export declare function cardBaseSource(base: Entity, dataSource: Pick<DataSource, 'connectionId' | 'connectionType' | 'mode' | 'semanticDomainId'>): SemaphorSourceRef | undefined;
40
+ /** The datasets a field reads, by name (a calculated field's through its inputs). */
41
+ export declare function fieldDatasets(field: Field): string[];
42
+ /**
43
+ * The same source (ledger P7-13): inside a card, datasets and tables go by
44
+ * name, so wherever a source enters the card (a new base, a join's new table)
45
+ * its whole identity is compared here: a dataset's domain and name (never its
46
+ * connection, AGENTS source identity), a table's connection, database, schema
47
+ * and name. A coordinate one side doesn't state doesn't tell them apart.
48
+ */
49
+ export declare function sameSource(a: Entity | undefined, b: Entity | undefined): boolean;
50
+ /** The same base: the same kind of source and the same identity (`sameSource`). */
51
+ export declare function sameBaseEntity(a: Entity | undefined, b: Entity | undefined): boolean;
52
+ export type CardBaseSwitch = {
53
+ card: TCard;
54
+ /** Placed fields that stayed, as they were placed. */
55
+ kept: Field[];
56
+ /** Placed fields that were removed. */
57
+ removed: Field[];
58
+ /** The card had joins of its own; they were removed with the old base. */
59
+ removedJoins: boolean;
60
+ /** Measures that stayed but lost a table calculation the new base can't run (P9-03). */
61
+ calculations: MetricField[];
62
+ };
63
+ /**
64
+ * The card on `nextBase` (OB-D3): a field of the old base stays when the new
65
+ * base has a column of the same name and kind (it takes that column's
66
+ * identity); a field of another dataset stays when the new base is that
67
+ * dataset or reaches it; everything else is removed, from every place. The
68
+ * card's own joins belong to the old base and are removed. The selection is
69
+ * the new base and the datasets the kept fields read; `queryBaseSource`
70
+ * states the new base.
71
+ */
72
+ export declare function switchCardBase(input: {
73
+ card: TCard;
74
+ /** The old base. */
75
+ base: Entity;
76
+ nextBase: Entity;
77
+ /** The new data source (mode, connection, domain); its selection is rebuilt here. */
78
+ dataSource: DataSource;
79
+ /** The new base's columns. */
80
+ columns: readonly Field[];
81
+ /** Datasets the new base reaches (its folders). */
82
+ reaches: (dataset: string) => boolean;
83
+ /** The selected entity for a dataset the kept fields read. */
84
+ entityOf: (dataset: string) => Entity | undefined;
85
+ }): CardBaseSwitch;
86
+ /**
87
+ * A semantic card's selection with each dataset a write newly made it read
88
+ * (OB-D17): a field placed from a folder adds its dataset after the base, as
89
+ * the MCP's selection lists each dataset a card reads. Only datasets the
90
+ * card didn't read before the write are added, so a sort or format change
91
+ * adds nothing, and nothing is ever removed (OB-INV-1; ledger P4-09). The
92
+ * entity takes the dataset's table coordinates from the field's own catalog
93
+ * identity. Matrix and direct cards (whose joins write their selection) are
94
+ * left as they are. A card is semantic by its base, a dataset, whether or not
95
+ * its source states a mode (a new visual's states none; ledger P7-01).
96
+ */
97
+ export declare function withReadDatasetsSelected(card: TCard, previous: TCard | undefined,
98
+ /**
99
+ * The domain's datasets, as the joinability response lists them (name,
100
+ * label, type, table, schema, catalog), when the caller has them: each
101
+ * added dataset is built from its entry by the one builder the base switch
102
+ * uses (`reachedDatasetEntity`), so its type and coordinates are the
103
+ * domain's, never parsed from a field's name (ledger P9-04). Without them,
104
+ * the entity carries the identity the server stamped on the field (domain,
105
+ * dataset, label) and no coordinates: the server fills those from the
106
+ * domain (canonicalize-semantic-card).
107
+ */
108
+ datasets?: readonly ReachedDatasetInfo[]): TCard;
109
+ /** A domain dataset's entry, as the joinability response lists it. */
110
+ export type ReachedDatasetInfo = {
111
+ name: string;
112
+ label?: string | null;
113
+ table?: string | null;
114
+ schema?: string | null;
115
+ catalog?: string | null;
116
+ type?: string;
117
+ };
118
+ /**
119
+ * A placed field's words on its chip (OB-D5): a field of another dataset than
120
+ * the base names the folder it was picked from first ("Customer › Segment"
121
+ * from the Customer folder; ledger P7-03). Without a folder for its dataset,
122
+ * the dataset's label stands in.
123
+ */
124
+ export declare function placedFieldLabel(field: Field, label: string, baseName: string | undefined, folderOf?: (dataset: string) => string | undefined): string;
125
+ export {};
@@ -0,0 +1,55 @@
1
+ import { Join } from '../../../lib/types/explorer-types.js';
2
+ import { FieldFolder, FieldFolderColumn } from '../field-folders/index.js';
3
+ import { JoinReach } from './join-reach.js';
4
+ export type CardFieldFolderRole =
5
+ /** The card's base. */
6
+ 'base'
7
+ /** Reached through the domain's relationships (OB-D6). */
8
+ | 'related'
9
+ /** Joined by the card's own join (OB-D7, OB-D9). */
10
+ | 'join'
11
+ /** Reached only through a relationship that doesn't join automatically (OB-D9). */
12
+ | 'needsSetup'
13
+ /** On the card's saved selection, but neither the base nor reached from it (OB-D18): remove only. */
14
+ | 'alsoOnCard';
15
+ export type CardFieldFolder<C extends FieldFolderColumn = FieldFolderColumn> = FieldFolder<C> & {
16
+ role: CardFieldFolderRole;
17
+ /** A join folder's join. */
18
+ joinId?: string;
19
+ };
20
+ /**
21
+ * A card with joins of its own reads only those: the server skips automatic
22
+ * joining whenever a card states its own plan (auto-join-resolver). So a
23
+ * related dataset its plan doesn't reach needs setup (one step from a table
24
+ * on the card) or isn't reachable, in the folders and in field placement
25
+ * alike (ledger P4-10, P9-02).
26
+ */
27
+ /**
28
+ * The folders a filter on the card reaches: its base, Related and joined
29
+ * datasets. A dataset that needs setup, or one the card names but doesn't
30
+ * reach, would never filter it (dashboard filter fields DF-D8).
31
+ */
32
+ export declare const CARD_FILTER_FOLDER_ROLES: ReadonlySet<CardFieldFolderRole>;
33
+ export declare function cardReadsOnlyOwnJoins(joins: readonly Join[] | undefined): boolean;
34
+ /** The dataset a join entity stands for: its alias, else its name. */
35
+ export declare const joinEntityName: (entity: {
36
+ alias?: string;
37
+ name?: string;
38
+ } | undefined) => string;
39
+ export declare function cardFieldFolders<C extends FieldFolderColumn>(input: {
40
+ base: string;
41
+ /** Semantic: what the base reaches (the joinability response's `reach[base]`). */
42
+ reach?: readonly JoinReach[];
43
+ /** The card's authored joins (a direct card's, or a saved semantic card's own). */
44
+ joins?: readonly Join[];
45
+ /** The datasets the card's saved selection names, already resolved to dataset names. */
46
+ selected?: readonly string[];
47
+ columnsOf: (dataset: string) => readonly C[];
48
+ labelOf: (dataset: string) => string;
49
+ /**
50
+ * Name a semantic folder after its key ("Customer ID" → "Customer") when
51
+ * the key refers to that dataset's rows (`towardKey`). Off for tables,
52
+ * whose folders keep the table's name.
53
+ */
54
+ keyLabels?: boolean;
55
+ }): CardFieldFolder<C>[];