react-semaphor 0.1.564 → 0.1.566

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 (138) hide show
  1. package/DATA_APP_SDK.md +3 -3
  2. package/README.md +2 -2
  3. package/dist/analytics-protocol/index.js +8 -8
  4. package/dist/assistant-context/index.js +3 -2
  5. package/dist/brand-studio/index.js +28 -29
  6. package/dist/briefings/index.js +53 -49
  7. package/dist/chunks/{assistant-chat-D1BEEHUF.js → assistant-chat-DNKAYSQL.js} +204 -204
  8. package/dist/chunks/{bookmark-impact-XOsVUAqW.js → bookmark-impact-BeUbq0jc.js} +2 -2
  9. package/dist/chunks/bookmark-state-ByODVqee.js +1613 -0
  10. package/dist/chunks/card-filter-builder-SXaRWbKr.js +4100 -0
  11. package/dist/chunks/{switch-BW4yXSYs.js → code-editor-DJNOsgJH.js} +463 -442
  12. package/dist/chunks/{comparison-window-caption-D1EUXzaR.js → comparison-window-caption-CMLb3mut.js} +451 -419
  13. package/dist/chunks/{dashboard-DfYsASNd.js → dashboard-Cni7nGhg.js} +1 -1
  14. package/dist/chunks/dashboard-briefing-launcher-CXeXRTem.js +4910 -0
  15. package/dist/chunks/{dashboard-controls-CJ8Dz50D.js → dashboard-controls-CsqKybrf.js} +685 -675
  16. package/dist/chunks/{dashboard-json-D3uZxGO-.js → dashboard-json-WWmw3Piu.js} +4 -4
  17. package/dist/chunks/{dates-EvDtT25n.js → dates-DJRUS-he.js} +12 -12
  18. package/dist/chunks/{edit-dashboard-visual-CgHJXBQv.js → edit-dashboard-visual-BrIEaBhc.js} +7724 -10341
  19. package/dist/chunks/filter-reach-copy-D5LqgrUf.js +4667 -0
  20. package/dist/chunks/{filter-value-text-CPwFkrMz.js → filter-value-text-7zhmth1S.js} +2 -2
  21. package/dist/chunks/{index-CAgf2x4E.js → index-Bq9UbCGk.js} +653 -574
  22. package/dist/chunks/{layout-grid-BM65viQh.js → layout-grid-0hIlqEtk.js} +1 -1
  23. package/dist/chunks/{list-filter-BoeLBfL3.js → list-filter-DkgoCeBm.js} +1 -1
  24. package/dist/chunks/{matrix-analytical-definition-hEucouWM.js → matrix-analytical-definition-C9xB_T84.js} +18 -18
  25. package/dist/chunks/{matrix-card-CCh9JjP1.js → matrix-card-BSUeSXpD.js} +2 -2
  26. package/dist/chunks/{matrix-member-presentation-DsAUbuoL.js → matrix-member-presentation-DZNgQpUq.js} +1 -1
  27. package/dist/chunks/{matrix-operation-contract-DsLdFdSa.js → matrix-operation-contract-Eb6elidS.js} +1 -1
  28. package/dist/chunks/{metric-comparison-Bnso1cm1.js → metric-comparison-ChXUFaZu.js} +1 -1
  29. package/dist/chunks/{palette-p1XSJFgB.js → palette-4vf2BEEg.js} +1 -1
  30. package/dist/chunks/{pivot-result-contract-expectations-B53jqszr.js → pivot-result-contract-expectations-Ddh1rNz5.js} +4 -4
  31. package/dist/chunks/{pivot-result-identity-Dq5jm-EC.js → pivot-result-identity-BlbLrqaC.js} +1 -1
  32. package/dist/chunks/{report-preferences-dialog-DMqxSU4X.js → report-preferences-dialog-CeHioJwL.js} +122 -131
  33. package/dist/chunks/{report-runtime-context-BITkNSDa.js → report-runtime-context-DnA_PiKo.js} +1 -1
  34. package/dist/chunks/resolve-dashboard-input-context-CwS-2r-b.js +21419 -0
  35. package/dist/chunks/{save-CHV1B1fL.js → save-D6pHmSSP.js} +1 -1
  36. package/dist/chunks/saved-dashboard-context-c-MZZTx2.js +629 -0
  37. package/dist/chunks/{selection-reducer-Bz5aywT4.js → selection-reducer-OaJ-N5uN.js} +1 -1
  38. package/dist/chunks/{semaphor-ready-indicator-CFeCIuaw.js → semaphor-ready-indicator-B2NpYRE-.js} +81034 -80950
  39. package/dist/chunks/{shelf-drop-preview-context-cEyVkKTF.js → shelf-drop-preview-context-DM7yypwC.js} +407 -407
  40. package/dist/chunks/{source-entity-resolution-DdDVXFB8.js → source-entity-resolution-DF6GulDn.js} +1 -1
  41. package/dist/chunks/stored-dashboard-DTWc2pzt.js +5026 -0
  42. package/dist/chunks/{table-export-sheet-bSXxGn-v.js → table-export-sheet--DUKWk6o.js} +1 -1
  43. package/dist/chunks/{temporal-input-presentation-sk9gqLi6.js → temporal-input-presentation--2r9BLr0.js} +392 -377
  44. package/dist/chunks/{token-types-BUK06hU2.js → token-types-C8JymO8s.js} +1 -1
  45. package/dist/chunks/{upload-BnmuyPqW.js → upload-Cf3wXZT8.js} +1 -1
  46. package/dist/chunks/{validators-BIM0FE31.js → validators-wtjw0aw6.js} +7 -7
  47. package/dist/chunks/variable-draft-DFizFCJu.js +241 -0
  48. package/dist/dashboard/index.js +2 -2
  49. package/dist/dashboard-authoring/index.js +2324 -1796
  50. package/dist/data-app-sdk/index.js +4 -4
  51. package/dist/data-app-sdk-adapters/index.js +2 -2
  52. package/dist/data-app-sdk-validation/index.js +5 -5
  53. package/dist/format-utils/index.js +174 -167
  54. package/dist/index.js +189 -187
  55. package/dist/pdf-export-policy/index.js +80 -28
  56. package/dist/pdf-table-layout/index.js +65 -65
  57. package/dist/report-runtime-context/index.js +1 -1
  58. package/dist/style.css +1 -1
  59. package/dist/surfboard/index.js +2 -2
  60. package/dist/types/briefings/attachment-outcomes.d.ts +1 -1
  61. package/dist/types/briefings/delivery-outcome.d.ts +37 -0
  62. package/dist/types/briefings/index.d.ts +2 -0
  63. package/dist/types/briefings/run-outcomes.d.ts +6 -0
  64. package/dist/types/components/briefings/briefing-author/run-model.d.ts +9 -0
  65. package/dist/types/components/dashboard-variables/data-variables-menu.d.ts +8 -0
  66. package/dist/types/components/dashboard-variables/variable-editor-host.d.ts +1 -0
  67. package/dist/types/components/index.d.ts +2 -0
  68. package/dist/types/index.js +5 -5
  69. package/dist/types/lib/dashboard-inputs/build-normalized-dashboard-inputs.d.ts +62 -0
  70. package/dist/types/lib/dashboard-inputs/dashboard-filter-mapping-authoring.d.ts +33 -2
  71. package/dist/types/lib/dashboard-inputs/filter-settings.d.ts +7 -2
  72. package/dist/types/lib/dashboard-inputs/prepare-loaded-dashboard.d.ts +4 -2
  73. package/dist/types/lib/dashboard-variables/data-text.d.ts +33 -0
  74. package/dist/types/lib/dashboard-variables/types.d.ts +207 -0
  75. package/dist/types/lib/document/document-edits.d.ts +16 -1
  76. package/dist/types/lib/document/document-panel-target.d.ts +1 -1
  77. package/dist/types/lib/document/document-section-query-options.d.ts +29 -0
  78. package/dist/types/lib/document/document-table-data-policy.d.ts +0 -1
  79. package/dist/types/lib/hooks/use-dashboard-frame-query.d.ts +92 -0
  80. package/dist/types/lib/query-context/build-card-query-context.d.ts +6 -0
  81. package/dist/types/lib/query-context/dashboard-filter-mapping-resolution.d.ts +15 -3
  82. package/dist/types/lib/query-context/describe-card-execution-snapshot.d.ts +1 -0
  83. package/dist/types/lib/query-context/use-semantic-execution-payload-for-cards.d.ts +24 -0
  84. package/dist/types/lib/stores/dashboard-store.d.ts +36 -0
  85. package/dist/types/lib/text-variables/temporal-input-text.d.ts +28 -0
  86. package/dist/types/lib/text-variables/text-variable-types.d.ts +72 -0
  87. package/dist/types/lib/types/common-types.d.ts +155 -51
  88. package/dist/types/lib/utils/card-definition.d.ts +2 -2
  89. package/dist/types/shared/assistant-context/index.d.ts +1 -1
  90. package/dist/types/shared/assistant-context/saved-dashboard-context.d.ts +51 -1
  91. package/dist/types/shared/dashboard-authoring/card-query-request.d.ts +7 -1
  92. package/dist/types/shared/dashboard-authoring/card-settings/resolve-card-highlights.d.ts +10 -0
  93. package/dist/types/shared/dashboard-authoring/changes/card-query-part.d.ts +1 -0
  94. package/dist/types/shared/dashboard-authoring/changes/dashboard-change.d.ts +1087 -430
  95. package/dist/types/shared/dashboard-authoring/changes/diagnostics.d.ts +20 -1
  96. package/dist/types/shared/dashboard-authoring/changes/resolve-dashboard-changes.d.ts +1 -1
  97. package/dist/types/shared/dashboard-authoring/conditional-formatting/kpi.d.ts +10 -0
  98. package/dist/types/shared/dashboard-authoring/conditional-formatting/schema.d.ts +40 -40
  99. package/dist/types/shared/dashboard-authoring/control-execution-contract.d.ts +16 -16
  100. package/dist/types/shared/dashboard-authoring/dashboard-card-source-index.d.ts +1 -0
  101. package/dist/types/shared/dashboard-authoring/dashboard-filter-sql-subscription.d.ts +24 -0
  102. package/dist/types/shared/dashboard-authoring/dashboard-filter-targets.d.ts +29 -0
  103. package/dist/types/shared/dashboard-authoring/dashboard-input-scope.d.ts +7 -4
  104. package/dist/types/shared/dashboard-authoring/dashboard-variable-card.d.ts +159 -0
  105. package/dist/types/shared/dashboard-authoring/dashboard-variable-changes.d.ts +61 -0
  106. package/dist/types/shared/dashboard-authoring/document-section-cards.d.ts +7 -0
  107. package/dist/types/shared/dashboard-authoring/filter-model/index.d.ts +2 -0
  108. package/dist/types/shared/dashboard-authoring/filter-model/read-dashboard-filter-model.d.ts +10 -0
  109. package/dist/types/shared/dashboard-authoring/index.d.ts +6 -0
  110. package/dist/types/shared/dashboard-authoring/measure-calculations/comparison.d.ts +2 -0
  111. package/dist/types/shared/dashboard-authoring/operations/operation-sentences.d.ts +1 -1
  112. package/dist/types/shared/dashboard-authoring/operations/operation-types.d.ts +50 -3
  113. package/dist/types/shared/dashboard-authoring/outline/outline-dashboard.d.ts +48 -1
  114. package/dist/types/shared/dashboard-authoring/outline/outline-filters.d.ts +22 -6
  115. package/dist/types/shared/dashboard-authoring/text-card-words/blocks.d.ts +87 -13
  116. package/dist/types/shared/dashboard-authoring/text-card-words/chip-colors.d.ts +23 -0
  117. package/dist/types/shared/dashboard-authoring/text-card-words/index.d.ts +90 -8
  118. package/dist/types/shared/dashboard-authoring/text-card-words/rich-content.d.ts +31 -3
  119. package/dist/types/shared/dashboard-authoring/text-card-words/variable-words.d.ts +8 -0
  120. package/dist/types/shared/dashboard-authoring/variable-draft.d.ts +125 -0
  121. package/dist/types/shared/dashboard-authoring/variable-editability.d.ts +24 -0
  122. package/dist/types/shared/dashboard-authoring/variable-references.d.ts +39 -0
  123. package/dist/types/shared/format-utils/document-print.d.ts +4 -2
  124. package/dist/types/shared/format-utils/index.d.ts +1 -0
  125. package/dist/types/shared/format-utils/pdf-capacity-lines.d.ts +17 -0
  126. package/dist/types/shared/format-utils/pdf-delivery.d.ts +8 -1
  127. package/dist/types/shared/format-utils/pdf-export-policy.d.ts +74 -6
  128. package/dist/types/shared/format-utils/presentation-execution.d.ts +9 -0
  129. package/package.json +2 -2
  130. package/src/data-app-sdk/README.md +3 -3
  131. package/dist/chunks/bookmark-state-CWeoGbrx.js +0 -743
  132. package/dist/chunks/braces-DzgoQC64.js +0 -23
  133. package/dist/chunks/dashboard-briefing-launcher-lvYfJoUQ.js +0 -3878
  134. package/dist/chunks/filter-reach-copy-Cmb05jlE.js +0 -3965
  135. package/dist/chunks/global-date-filter-utils-ruJYwjgZ.js +0 -16733
  136. package/dist/chunks/resolve-dashboard-input-context-i_jCSYae.js +0 -8214
  137. package/dist/chunks/saved-dashboard-context-Dg3oDmH_.js +0 -564
  138. package/dist/chunks/use-create-flow-overlay-state-Dl6DCxh8.js +0 -1436
@@ -0,0 +1,159 @@
1
+ import { TChartType } from '../../lib/charts/types.js';
2
+ import { DataVariable, TCard, TextVariablePresentation } from '../../lib/types/common-types.js';
3
+ import { QueryColumnKeyMap } from '../../lib/types/explorer-types.js';
4
+ import { SemaphorFilterReachEntry, SemaphorResultColumn } from '../analytics-protocol/index.js';
5
+ import { ComparisonUnavailableReason, MetricComparisonMetadataMap, MetricComparisonSpec } from '../analytics-protocol/metric-comparison.js';
6
+ /**
7
+ * The card type every answer runs as: non-paginated (`isPaginatedCardType`),
8
+ * so the server applies `rowLimit` as the query's limit, and never the KPI
9
+ * type, whose route turns every value into a number (DV-D9, DV-D10).
10
+ */
11
+ export declare const VARIABLE_CARD_TYPE: TChartType;
12
+ /** The most distinct values a `list` reads; past it the text says "and more". */
13
+ export declare const VARIABLE_LIST_CAP = 100;
14
+ /** Shown from a `list` when the variable names no limit. */
15
+ export declare const VARIABLE_LIST_SHOWN = 10;
16
+ /** The dialog's preview (1b) counts matches up to the list cap (spec S-7). */
17
+ export type VariableQueryPurpose = 'answer' | 'preview';
18
+ /** The part every `aggregate` and `list` answer has (ledger P1a-02). */
19
+ export declare const VARIABLE_VALUE_PART = "value";
20
+ /**
21
+ * The parts a comparison adds to an aggregate (data variables DV-D22,
22
+ * P3b-04): the value of the window compared with, the change, and the change
23
+ * as a ratio of the previous value (0.06 for 6%; "As a percent" shows it so).
24
+ */
25
+ export declare const VARIABLE_COMPARISON_PARTS: readonly ["previous", "change", "percentChange"];
26
+ export type VariableComparisonPart = (typeof VARIABLE_COMPARISON_PARTS)[number];
27
+ export declare function isVariableComparisonPart(part: string | null | undefined): part is VariableComparisonPart;
28
+ /** The words a change reads in until the author picks others: "up 6%", "down 2%", "flat". */
29
+ export declare const COMPARISON_SIGN_WORDS: [string, string, string];
30
+ /**
31
+ * The reading a compared variable's part takes when an author picks it on a
32
+ * chip (the chip's Show control) or an agent places it without one: a change
33
+ * reads in words, without its sign ("up 6%", "down $8", "flat"), and a percent
34
+ * change as a percent; the value and the previous value read as numbers. A
35
+ * word the variable itself states (`inherited`) is left to it, so its own
36
+ * reading still shows. Only those three fields change; the chip's decimals,
37
+ * units, colours and the rest stay as they are.
38
+ */
39
+ export declare function comparisonPartPresentation(part: string, presentation: TextVariablePresentation | undefined, inherited?: TextVariablePresentation): TextVariablePresentation;
40
+ /**
41
+ * A variable's period comparison (DV-D22, P3b-02): stored on its one
42
+ * measure as a card's is, on a numeric aggregate. Undefined for any other
43
+ * variable, and for `off` or a target, which a variable is not offered.
44
+ */
45
+ export declare function variableComparison(variable: Pick<DataVariable, 'query' | 'get'>): Extract<MetricComparisonSpec, {
46
+ kind: 'previous_period' | 'previous_year';
47
+ }> | undefined;
48
+ /**
49
+ * The card a variable runs as: its id, its name, its stored query and the
50
+ * row limit its `get` needs. Memoized per variable object, so a variable keeps
51
+ * one card identity and one query key.
52
+ */
53
+ export declare function projectDataVariableToCard(variable: DataVariable, purpose?: VariableQueryPurpose): TCard;
54
+ /**
55
+ * Whether a card is a variable's projection whose period comparison the
56
+ * browser keeps (data variables P3b-03): the one predicate the comparison
57
+ * rule reads, so a text card the editor writes still takes none. A target is
58
+ * not a variable's comparison and is still dropped.
59
+ */
60
+ export declare function variableCardKeepsComparison(card: Pick<TCard, 'type' | 'dataVariableId'>): boolean;
61
+ /**
62
+ * The cell a part names in an answer (DV-D10, ledger P1a-22, P2-26): on a SQL
63
+ * variable the symbolic `value` is the first result column, ahead of any
64
+ * column that happens to be named `value`; every other part is its own
65
+ * column. The chip and the server's analyze read through this one rule.
66
+ */
67
+ export declare function variablePartCell(variable: Pick<DataVariable, 'query'>, parts: Readonly<Record<string, VariableCell>>, part: string): VariableCell | undefined;
68
+ /** One typed cell of an answer (DV-D10). */
69
+ export type VariableCell = {
70
+ value: string | number | boolean | null;
71
+ type: 'text' | 'number' | 'date' | 'datetime' | 'boolean';
72
+ };
73
+ /** Only on the dialog's preview: how many distinct values match, up to the cap. */
74
+ type PreviewMatches = {
75
+ matched?: number | 'beyondCap';
76
+ };
77
+ /** A variable's answer at one place (spec 2.7). */
78
+ export type VariableAnswer = {
79
+ status: 'loading';
80
+ } | ({
81
+ status: 'answered';
82
+ parts: Readonly<Record<string, VariableCell>>;
83
+ filterReach: readonly SemaphorFilterReachEntry[];
84
+ /**
85
+ * A comparison that had no window here (P3b-05): its parts read as no
86
+ * answer and the author's chip says why; `value` is unchanged.
87
+ */
88
+ comparisonUnavailable?: ComparisonUnavailableReason;
89
+ } & PreviewMatches) | ({
90
+ status: 'listed';
91
+ items: readonly VariableCell[];
92
+ more: number | 'beyondCap';
93
+ filterReach: readonly SemaphorFilterReachEntry[];
94
+ } & PreviewMatches) | ({
95
+ status: 'none';
96
+ why: 'noRows' | 'moreThanOne';
97
+ filterReach: readonly SemaphorFilterReachEntry[];
98
+ } & PreviewMatches)
99
+ /** A required filter has no value: nothing, never an earlier value. */
100
+ | {
101
+ status: 'held';
102
+ missingRequired: readonly string[];
103
+ }
104
+ /** The query no longer compiles against its mapping. */
105
+ | {
106
+ status: 'broken';
107
+ why: 'mapping';
108
+ }
109
+ /** The query failed: the warehouse, the network, or its source. */
110
+ | {
111
+ status: 'failed';
112
+ message: string;
113
+ };
114
+ /**
115
+ * The variable's parts, in order (spec 2.4): each grouped field, then a
116
+ * measure the sort names, by the field's name; `value` for an aggregate or a
117
+ * list, and an aggregate's comparison parts when it compares (P3b-04); a SQL
118
+ * variable's result columns. Derived, never stored.
119
+ */
120
+ export declare function variableParts(variable: DataVariable, sqlColumns?: readonly string[]): string[];
121
+ /**
122
+ * A part's type before any answer, from the stored query (data variables
123
+ * P3a-10): what the wording tests offered for it follow. `list` for a list's
124
+ * value; undefined when the query doesn't say (a SQL variable's columns, a
125
+ * field with no stored type), and then every test is offered.
126
+ */
127
+ export declare function variablePartType(variable: Pick<DataVariable, 'query' | 'get'>, part: string): VariableCell['type'] | 'list' | undefined;
128
+ /**
129
+ * What a variable's answer is read from (ledger P2-29): the rows, the column
130
+ * descriptors and key map the query route returns, and the per-filter reach
131
+ * it reports beside them. One view for the browser's frame query and the
132
+ * server's execution result, built by `variableQueryResponseOf`.
133
+ */
134
+ export type VariableQueryResponse = {
135
+ records?: unknown;
136
+ columns?: SemaphorResultColumn[];
137
+ columnKeyMap?: QueryColumnKeyMap;
138
+ filterReach?: SemaphorFilterReachEntry[];
139
+ /** A comparison's outputs by output id, as tables and charts read them (P3b-04). */
140
+ comparisonMetadata?: MetricComparisonMetadataMap;
141
+ /** The route's own failure, when the request ran and the warehouse refused it. */
142
+ error?: string;
143
+ };
144
+ /**
145
+ * The one adapter from an execution response to the view the reader reads
146
+ * (P2-29): the browser's frame query hands the response body, with the rows,
147
+ * columns and reach inline; the server's executor hands `{ data, filterReach,
148
+ * constraints }`, the reach beside the body. Either way the reader sees one
149
+ * object, so the chip and analyze read the same answer from the same run.
150
+ */
151
+ export declare function variableQueryResponseOf(response: unknown): VariableQueryResponse;
152
+ /**
153
+ * One answer from the rows the variable's card got (spec 3.2, DV-D5): `only`
154
+ * shows one distinct row or nothing, `first` the first row, `list` its first
155
+ * values and how many more, `aggregate` its one value. Pure; the browser and
156
+ * the server's analyze path read answers through it.
157
+ */
158
+ export declare function readVariableAnswer(variable: DataVariable, response: VariableQueryResponse, purpose?: VariableQueryPurpose): VariableAnswer;
159
+ export {};
@@ -0,0 +1,61 @@
1
+ import { DataVariable, TDashboard, TFrame } from '../../lib/types/common-types.js';
2
+ import { VariableReference } from '../../lib/dashboard-variables/types.js';
3
+ export type VariableChange = {
4
+ kind: 'add';
5
+ variable: DataVariable;
6
+ }
7
+ /** A new `name` is a rename: refs are by id, so text is untouched. */
8
+ | {
9
+ kind: 'update';
10
+ id: string;
11
+ patch: Partial<Omit<DataVariable, 'id'>>;
12
+ } | {
13
+ kind: 'remove';
14
+ id: string;
15
+ confirmed: boolean;
16
+ };
17
+ export type VariableIssueCode = 'nameInvalid' | 'nameTaken' | 'nameReserved' | 'idTaken' | 'queryMissing' | 'getNeedsColumns' | 'getNeedsSort' | 'listNeedsOneColumn' | 'aggregateNeedsOneMeasure' | 'sqlGetUnsupported' | 'unknownVariable' | 'inUse';
18
+ export type VariableIssue = {
19
+ code: VariableIssueCode;
20
+ /** Brand-neutral; names the variable. */
21
+ message: string;
22
+ /** What to do next. */
23
+ fix: string;
24
+ path?: string;
25
+ /** `inUse`: where it is used. */
26
+ places?: VariableReference[];
27
+ };
28
+ export type VariableChangeResult = {
29
+ ok: true;
30
+ dashboard: TDashboard;
31
+ removedMappings: number;
32
+ /**
33
+ * The frames whose queries this change added or changed, as the metadata
34
+ * loader takes them (ledger P2-28): the variable as the frame holding its
35
+ * card on an add, and on an update that changes its query. The dialog's
36
+ * Done and the reducer's operations both read it here; neither derives it.
37
+ */
38
+ queryFrames: TFrame[];
39
+ } | {
40
+ ok: false;
41
+ issues: VariableIssue[];
42
+ };
43
+ /** What text writes for a variable: a letter, then letters, digits or underscores. */
44
+ export declare const VARIABLE_NAME_PATTERN: RegExp;
45
+ /**
46
+ * Names text already resolves another way (spec S-1): `document` is the
47
+ * report namespace, and a bare report key reads as the report value.
48
+ */
49
+ export declare const RESERVED_VARIABLE_NAMES: ReadonlySet<string>;
50
+ /**
51
+ * The rules a data variable keeps (spec 2.4), against the dashboard it is in
52
+ * or joins. Pure, no network: the dialog shows the issues inline, the MCP
53
+ * turns them into refusals and the app's save validation refuses with them.
54
+ */
55
+ export declare function checkDataVariable(variable: DataVariable, dashboard: TDashboard): VariableIssue[];
56
+ /**
57
+ * Adds, updates or removes a data variable. It never touches an input and
58
+ * never rewrites text: a removed variable's chips read as placeholders
59
+ * (DV-D28). Returns a new dashboard object.
60
+ */
61
+ export declare function applyVariableChange(dashboard: TDashboard, change: VariableChange): VariableChangeResult;
@@ -44,6 +44,13 @@ export type DashboardCardLocation = {
44
44
  * then frame cards, then document section cards (every KPI card included).
45
45
  */
46
46
  export declare function listDashboardCardLocations(dashboard: Pick<TDashboard, 'sheets'>): readonly DashboardCardLocation[];
47
+ /**
48
+ * The dashboard as it reads with a draft of one card in place (data variables
49
+ * ledger P1b-16): the editor's unsaved card replaces its saved one, or joins
50
+ * the tab's cards when it is new. The same object comes back when the draft
51
+ * is the saved card, so readers cached per dashboard keep their entries.
52
+ */
53
+ export declare function withDraftCard<T extends Pick<TDashboard, 'sheets'>>(dashboard: T, sheetId: string | null | undefined, draft: TCard): T;
47
54
  /**
48
55
  * The dashboard with each card mapped, in `listDashboardCardLocations` order.
49
56
  * Returns the input object when no card changed, and likewise each sheet,
@@ -5,3 +5,5 @@ export * from './filter-values.js';
5
5
  export * from './filter-definitions.js';
6
6
  export * from './ad-hoc-filter-values.js';
7
7
  export { upgradeToStoredDashboard } from './stored-dashboard.js';
8
+ /** Every input the dashboard has at runtime, compatibility inputs named as the runtime names them (data variables P1a-21). */
9
+ export { listDashboardInputsTolerantly } from '../../../lib/dashboard-inputs/build-normalized-dashboard-inputs.js';
@@ -1,6 +1,7 @@
1
1
  import { TFilter } from '../../../components/surfboard/filter/types.js';
2
2
  import { DashboardInputScope, DashboardInputValues, EmbeddedFilterDashboardInput, NormalizedFilterDashboardInput, TDashboard } from '../../../lib/types/common-types.js';
3
3
  import { DashboardFilterMappingContractIssue } from '../dashboard-filter-mapping-contract.js';
4
+ import { ScopedDashboardInputTarget } from '../dashboard-input-scope.js';
4
5
  import { DashboardCardLocation } from '../document-section-cards.js';
5
6
  /**
6
7
  * The filter model (one filter model M1): every stored filter shape read as a
@@ -24,6 +25,11 @@ export type FilterInputEntry = {
24
25
  export type ReachedCard = DashboardCardLocation & {
25
26
  sheetKind: 'dashboard' | 'document';
26
27
  };
28
+ /** A data variable a filter reaches, and the places it reaches it at (DV-D35). */
29
+ export type ReachedVariable = {
30
+ variableId: string;
31
+ places: readonly ScopedDashboardInputTarget[];
32
+ };
27
33
  export type FilterModelIssueCode = 'contract' | 'duplicate_filter_owner' | 'compat_id_conflict' | 'duplicate_global_date';
28
34
  export type FilterModelIssue = {
29
35
  code: FilterModelIssueCode;
@@ -59,6 +65,10 @@ export type DashboardFilterModel = {
59
65
  reachedCards(ref: FilterRef, options?: {
60
66
  scope?: DashboardInputScope;
61
67
  }): readonly ReachedCard[];
68
+ /** Data variables the input reaches, each where it is used (DV-D30, DV-D35). */
69
+ reachedVariables(ref: FilterRef, options?: {
70
+ scope?: DashboardInputScope;
71
+ }): readonly ReachedVariable[];
62
72
  /** The template with every filter as an embedded input. The same object when `needsUpgrade` is false. Throws `FilterModelError` when `issues` is not empty. */
63
73
  toStoredDashboard(): TDashboard;
64
74
  };
@@ -12,6 +12,10 @@ export * from './dashboard-filter-sql-subscription.js';
12
12
  export * from './dashboard-filter-sql-target.js';
13
13
  export * from './dashboard-filter-mapping-contract.js';
14
14
  export * from './dashboard-input-scope.js';
15
+ export * from './dashboard-variable-card.js';
16
+ export * from './variable-references.js';
17
+ export * from './dashboard-filter-targets.js';
18
+ export * from './dashboard-variable-changes.js';
15
19
  export * from './filter-model/index.js';
16
20
  export * from './dashboard-filter-value-compatibility.js';
17
21
  export * from './card-reference-remapping.js';
@@ -70,3 +74,5 @@ export * from './filter-applicability.js';
70
74
  export * from './semantic-auto-join-card.js';
71
75
  export * from './filter-reach-preview.js';
72
76
  export * from './filter-reach-copy.js';
77
+ export * from './variable-draft.js';
78
+ export * from './variable-editability.js';
@@ -14,3 +14,5 @@ export declare function readStoredComparison(stored: MetricComparisonConfig | un
14
14
  export declare function sameComparison(stated: MeasureComparison, stored: MetricComparisonConfig | undefined): boolean;
15
15
  /** A comparison of the measure's own: a period, a year or a target (not `inherit` or `off`). */
16
16
  export declare const isExplicitComparison: (comparison: MeasureComparison | undefined) => comparison is ExplicitComparison;
17
+ /** "the same period last year", "a target of 1,000,000": what a stored comparison compares with. */
18
+ export declare function comparedWith(comparison: MetricComparisonConfig): string;
@@ -6,7 +6,7 @@ import { TCardPreferences } from '../../../lib/types/common-types.js';
6
6
  * type, query, rename, description, columns, display, highlight, detached. Sentences never name the
7
7
  * product.
8
8
  */
9
- export type ClauseKind = 'add' | 'remove' | 'type' | 'query' | 'calculation' | 'rename' | 'description' | 'columns' | 'display' | 'highlight' | 'dashboard' | 'sheet' | 'detached' | 'commit' | 'filter' | 'layout';
9
+ export type ClauseKind = 'add' | 'remove' | 'type' | 'query' | 'calculation' | 'rename' | 'description' | 'columns' | 'display' | 'highlight' | 'dashboard' | 'sheet' | 'detached' | 'commit' | 'filter' | 'layout' | 'variable' | 'document';
10
10
  export type SentenceClause = {
11
11
  kind: ClauseKind;
12
12
  /** How the clause reads when it opens the sentence. */
@@ -1,4 +1,5 @@
1
- import { EmbeddedFilterDashboardInput, TDashboard, TFrame, TextCardRichContent } from '../../../lib/types/common-types.js';
1
+ import { DataVariable, EmbeddedFilterDashboardInput, TDashboard, TFrame, TextCardRichContent } from '../../../lib/types/common-types.js';
2
+ import { DocumentEdit } from '../../../lib/document/document-edits.js';
2
3
  import { ResolvedCardSettings } from '../card-settings/resolved.js';
3
4
  import { MeasureCalculationsUpdate } from '../measure-calculations/resolve.js';
4
5
  import { FilterSettingsChange, FilterValueEffect } from '../../../lib/dashboard-inputs/filter-settings.js';
@@ -158,6 +159,34 @@ export type DashboardOperation = ({
158
159
  op: 'layout.untab';
159
160
  cardId: string;
160
161
  newFrameId: string;
162
+ }
163
+ /**
164
+ * A data variable, written as the dialog writes one, through the one writer
165
+ * (data variables DV-INV-5, AR-29): the record the resolver built, its id
166
+ * minted there. A new name on an update is a rename; refs are by id.
167
+ */
168
+ | {
169
+ op: 'variable.add';
170
+ variable: DataVariable;
171
+ }
172
+ /** A `null` clears a label, presentation or empty text, as `card.update`'s `description: null` does: the stored operation survives JSON (S-INV-16). */
173
+ | {
174
+ op: 'variable.update';
175
+ variableId: string;
176
+ patch: VariablePatch;
177
+ }
178
+ /** Refused while text still uses it: the resolver refuses first, with the places (DV-D28). */
179
+ | {
180
+ op: 'variable.remove';
181
+ variableId: string;
182
+ }
183
+ /** A Document line or text section, written through the Document editor's own writer (`applyDocumentEdit`, spec S-4). */
184
+ | {
185
+ op: 'document.text';
186
+ sheetId: string;
187
+ edit: Extract<DocumentEdit, {
188
+ type: 'updateText' | 'updateRegionText';
189
+ }>;
161
190
  }) & {
162
191
  /** Set by the resolver: the public change this operation came from. Descriptions group by it. */
163
192
  changeIndex?: number;
@@ -166,8 +195,12 @@ export type OperationContext = {
166
195
  /** The report calendar; filter defaults resolve in it. A proposal's has a fixed anchor (DE-D59). */
167
196
  calendar: CalendarContext | null;
168
197
  };
198
+ /** What `variable.update` changes: each field as stored, or `null` to clear an optional one. */
199
+ export type VariablePatch = {
200
+ [K in keyof Omit<DataVariable, 'id'>]?: DataVariable[K] | null;
201
+ };
169
202
  export type CreatedEntity = {
170
- kind: 'card' | 'filter' | 'sheet';
203
+ kind: 'card' | 'filter' | 'sheet' | 'variable';
171
204
  id: string;
172
205
  title: string;
173
206
  changeIndex?: number;
@@ -225,7 +258,11 @@ export type OperationFailureCode = 'sheet_not_found'
225
258
  /** A retype across the Matrix boundary without a catalog. */
226
259
  | 'catalog_loading'
227
260
  /** A card settings operation names a column the card no longer has (card appearance SPEC 4.3): a defect, since apply runs after the staleness check. */
228
- | 'setting_target_missing';
261
+ | 'setting_target_missing'
262
+ /** A data variable the one writer refuses (data variables spec 2.11); `details.issues` has its issues. */
263
+ | 'variable_invalid' | 'variable_not_found'
264
+ /** A Document edit its writer refuses (`DocumentEditError`), or a sheet that is no Document. */
265
+ | 'document_invalid';
229
266
  export type DashboardOperationResult = {
230
267
  ok: true;
231
268
  dashboard: TDashboard;
@@ -237,6 +274,16 @@ export type DashboardOperationResult = {
237
274
  * the dashboard's title, arranging).
238
275
  */
239
276
  touched: string[];
277
+ /**
278
+ * The frames whose queries the operations added or changed, each as the
279
+ * metadata loader takes it (`useResolveExistingFrameSemanticExecutionPayload`):
280
+ * the frames of created and touched cards, and each added or requeried
281
+ * data variable as the frame holding its card (ledger P2-28). A live
282
+ * apply loads their datasets' metadata before the write, so a card or
283
+ * variable on a dataset the dashboard had no metadata for keeps its date
284
+ * filter (P1b-31, P2-21). The reducer reports them; no caller derives them.
285
+ */
286
+ queryFrames: TFrame[];
240
287
  /** One plain sentence per public change (or per operation without a changeIndex). */
241
288
  descriptions: OperationDescription[];
242
289
  runtimeEffects: DashboardRuntimeEffect[];
@@ -1,7 +1,8 @@
1
1
  import { DashboardRelationshipReachResolver } from '../../../lib/query-context/dashboard-filter-mapping-resolution.js';
2
2
  import { TDashboard } from '../../../lib/types/common-types.js';
3
+ import { DocumentRegionTextRole } from '../../../lib/document/document-edits.js';
3
4
  import { FrameWidth } from '../../layouts/index.js';
4
- import { TextBlocks } from '../text-card-words/index.js';
5
+ import { RunPresentation, TextBlocks, TextRun } from '../text-card-words/index.js';
5
6
  import { CardTypeProperties } from '../changes/card-types.js';
6
7
  import { CardSettingsView } from '../card-settings/views.js';
7
8
  import { NotEditableReason, OutlineCardSource } from '../changes/read-card-query.js';
@@ -75,6 +76,44 @@ export type OutlineTextCard = {
75
76
  editorOnly?: string[];
76
77
  linkedVisualId?: string;
77
78
  };
79
+ /** A Document header or footer line, as `document.text.update` takes it (data variables DV-D13, DV-D31). */
80
+ export type OutlineDocumentLine = {
81
+ role: DocumentRegionTextRole;
82
+ text: TextRun[];
83
+ };
84
+ /** A Document text section: one line of runs (its content holds no blocks). */
85
+ export type OutlineDocumentTextSection = {
86
+ sectionId: string;
87
+ text: TextRun[];
88
+ };
89
+ /**
90
+ * A variable text may name (data variables DV-D13): an input's value, a report
91
+ * value, or a data variable with its question in words (DV-D14). Only a data
92
+ * variable on a semantic dataset (or SQL, with SQL access) is changed here.
93
+ */
94
+ export type OutlineVariable = {
95
+ name: string;
96
+ kind: 'input' | 'report' | 'data';
97
+ /** The question in words, from the words owner. */
98
+ words: string;
99
+ parts: string[];
100
+ /** Authored defaults a chip inherits, in the same presentation words as its run. */
101
+ presentation?: RunPresentation;
102
+ /** Where text shows it: a card, a Document header or footer line (by block id), or a text section. */
103
+ usedIn: Array<{
104
+ sheetId: string;
105
+ where: 'card' | 'header' | 'footer' | 'section';
106
+ id: string;
107
+ }>;
108
+ editable: boolean;
109
+ /** Why a data variable isn't changed here: SQL without SQL access, or a table or view source (DV-D33). */
110
+ notEditable?: {
111
+ reason: 'needs_sql_access' | 'table_source';
112
+ message: string;
113
+ };
114
+ /** Why its chips show nothing: the one writer's first issue with the stored record. */
115
+ broken?: string;
116
+ };
78
117
  export type OutlineSheet = {
79
118
  sheetId: string;
80
119
  title: string;
@@ -82,6 +121,10 @@ export type OutlineSheet = {
82
121
  kind: 'dashboard' | 'document';
83
122
  /** On a Document sheet, its sections' cards (never editable). */
84
123
  cards: OutlineCard[];
124
+ /** Document sheets only: the header and footer lines by role, and the text sections, each as runs (DV-D13). */
125
+ header?: OutlineDocumentLine[];
126
+ footer?: OutlineDocumentLine[];
127
+ textSections?: OutlineDocumentTextSection[];
85
128
  /**
86
129
  * Grid sheets only: the desktop layout as rows, top to bottom, from the
87
130
  * layout engine (responsive layouts RL-D10). Always the whole sheet, even
@@ -113,6 +156,10 @@ export type DashboardOutline = {
113
156
  }>;
114
157
  sheets: OutlineSheet[];
115
158
  filters: OutlineFilter[];
159
+ /** Every variable text may name: inputs, report values and data variables with their words and uses (DV-D13). */
160
+ variables: OutlineVariable[];
161
+ /** In the editor's words: what the dashboard holds that no change can state (the parity backlog, DV-D13). */
162
+ editorOnly?: string[];
116
163
  /** Queries left out because the dashboard has more than `maxQueryCards` cards (DE-D34). */
117
164
  truncated?: true;
118
165
  };
@@ -1,6 +1,5 @@
1
1
  import { TDashboard } from '../../../lib/types/common-types.js';
2
- import { DashboardRelationshipReachResolver } from '../../../lib/query-context/dashboard-filter-mapping-resolution.js';
3
- import { SemaphorSkippedConstraintReason } from '../../analytics-protocol/index.js';
2
+ import { DashboardFilterNotReachedReason, DashboardRelationshipReachResolver } from '../../../lib/query-context/dashboard-filter-mapping-resolution.js';
4
3
  import { FilterInputEntry } from '../filter-model/index.js';
5
4
  import { CalendarContext } from '../../report-runtime-context/index.js';
6
5
  import { FilterValue, TimeWindow } from '../changes/dashboard-change.js';
@@ -33,16 +32,19 @@ export type OutlineFilter = {
33
32
  exceptSheetIds?: string[];
34
33
  /** With "all": it also shows on Document sheets (their sections' cards). */
35
34
  includesDocumentSheets?: true;
36
- /** Card ids the filter applies to. */
35
+ /** The targets the filter applies to: card ids, and data variables' ids (DV-D30). */
37
36
  reaches: string[];
38
- /** Card ids excluded explicitly. */
37
+ /** Targets excluded explicitly. */
39
38
  excluded: string[];
40
- /** In scope, not matched; with a resolver (server side), the reason relationship reach gave. */
39
+ /**
40
+ * In scope, not matched; with a resolver (server side), the reason relationship reach gave.
41
+ * `sql_no_filter_reference`: a SQL card whose SQL names no filter, so it runs as written.
42
+ */
41
43
  notReached: Array<{
42
44
  cardId: string;
43
45
  title: string;
44
46
  datasetName?: string;
45
- reason?: SemaphorSkippedConstraintReason;
47
+ reason?: DashboardFilterNotReachedReason;
46
48
  }>;
47
49
  /** In scope, and blocked when the filter has a value: a binding the card can't run, or two fields it could take. */
48
50
  blocked?: Array<{
@@ -60,6 +62,16 @@ export type OutlineFilter = {
60
62
  title: string;
61
63
  datasetName?: string;
62
64
  }>;
65
+ /**
66
+ * In scope, a SQL card whose SQL names a filter other than through
67
+ * `{{ filters | where }}` or `{{ filters | and }}` (`filter('…')`, a
68
+ * helper with arguments): it may apply, as that SQL decides. Never
69
+ * counted as reached or as not reached.
70
+ */
71
+ sqlPending?: Array<{
72
+ cardId: string;
73
+ title: string;
74
+ }>;
63
75
  } | {
64
76
  filterId: string;
65
77
  label: string;
@@ -81,6 +93,10 @@ export type OutlineFilter = {
81
93
  title: string;
82
94
  datasetName?: string;
83
95
  }>;
96
+ sqlPending?: Array<{
97
+ cardId: string;
98
+ title: string;
99
+ }>;
84
100
  };
85
101
  /** Server-side readers resolve relationship reach the way the card query does (RF-D15). */
86
102
  export type OutlineReachOptions = {