react-semaphor 0.1.563 → 0.1.565

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 (139) 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 +4 -4
  7. package/dist/chunks/{assistant-chat-iIp02_77.js → assistant-chat-DNfb5fbF.js} +294 -294
  8. package/dist/chunks/{bookmark-impact-D4Kl4amw.js → bookmark-impact-CHr7b1J2.js} +2 -2
  9. package/dist/chunks/bookmark-state-ByODVqee.js +1613 -0
  10. package/dist/chunks/card-filter-builder-CcEcfaYz.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-CmqeP3QZ.js → dashboard-CtIfxycc.js} +1 -1
  14. package/dist/chunks/dashboard-briefing-launcher-D3mc6peE.js +4910 -0
  15. package/dist/chunks/{dashboard-controls-B253nJS-.js → dashboard-controls-BFv0zdws.js} +684 -674
  16. package/dist/chunks/{dashboard-json-osQuinUZ.js → dashboard-json-CXn_3OYb.js} +4 -4
  17. package/dist/chunks/{dates-DFY7Gfss.js → dates-DcRxw17S.js} +13 -13
  18. package/dist/chunks/{edit-dashboard-visual-CMar-NhA.js → edit-dashboard-visual-Y6HatqBd.js} +7704 -10337
  19. package/dist/chunks/filter-reach-copy-DbggA5B7.js +4673 -0
  20. package/dist/chunks/{filter-value-text-CPwFkrMz.js → filter-value-text-7zhmth1S.js} +2 -2
  21. package/dist/chunks/{index-CNGkfUp4.js → index-DDa_rklN.js} +69 -64
  22. package/dist/chunks/index-RNaTnE3m.js +585 -0
  23. package/dist/chunks/{layout-grid-BM65viQh.js → layout-grid-0hIlqEtk.js} +1 -1
  24. package/dist/chunks/{list-filter-BoeLBfL3.js → list-filter-DkgoCeBm.js} +1 -1
  25. package/dist/chunks/{matrix-analytical-definition-hEucouWM.js → matrix-analytical-definition-C9xB_T84.js} +18 -18
  26. package/dist/chunks/{matrix-card-CCh9JjP1.js → matrix-card-BSUeSXpD.js} +2 -2
  27. package/dist/chunks/{matrix-member-presentation-DsAUbuoL.js → matrix-member-presentation-DZNgQpUq.js} +1 -1
  28. package/dist/chunks/{matrix-operation-contract-DsLdFdSa.js → matrix-operation-contract-Eb6elidS.js} +1 -1
  29. package/dist/chunks/{metric-comparison-Bnso1cm1.js → metric-comparison-ChXUFaZu.js} +1 -1
  30. package/dist/chunks/{palette-p1XSJFgB.js → palette-4vf2BEEg.js} +1 -1
  31. package/dist/chunks/{pivot-result-contract-expectations-B53jqszr.js → pivot-result-contract-expectations-Ddh1rNz5.js} +4 -4
  32. package/dist/chunks/{pivot-result-identity-Dq5jm-EC.js → pivot-result-identity-BlbLrqaC.js} +1 -1
  33. package/dist/chunks/{report-preferences-dialog-l54wJyYE.js → report-preferences-dialog-Db-b04B4.js} +122 -131
  34. package/dist/chunks/{report-runtime-context-BITkNSDa.js → report-runtime-context-DnA_PiKo.js} +1 -1
  35. package/dist/chunks/resolve-dashboard-input-context-C18J-YZC.js +21394 -0
  36. package/dist/chunks/{save-CHV1B1fL.js → save-D6pHmSSP.js} +1 -1
  37. package/dist/chunks/saved-dashboard-context-DhC_EVus.js +629 -0
  38. package/dist/chunks/{selection-reducer-Bz5aywT4.js → selection-reducer-OaJ-N5uN.js} +1 -1
  39. package/dist/chunks/{semaphor-ready-indicator-C3EQEiD9.js → semaphor-ready-indicator-T6TsiBMT.js} +80879 -80744
  40. package/dist/chunks/{shelf-drop-preview-context-BODiBlqT.js → shelf-drop-preview-context-CNWL_b0S.js} +407 -407
  41. package/dist/chunks/{source-entity-resolution-DdDVXFB8.js → source-entity-resolution-DF6GulDn.js} +1 -1
  42. package/dist/chunks/stored-dashboard-IdmtrNkA.js +5026 -0
  43. package/dist/chunks/{table-export-sheet-bSXxGn-v.js → table-export-sheet--DUKWk6o.js} +1 -1
  44. package/dist/chunks/{temporal-input-presentation-sk9gqLi6.js → temporal-input-presentation--2r9BLr0.js} +392 -377
  45. package/dist/chunks/{token-types-BUK06hU2.js → token-types-C8JymO8s.js} +1 -1
  46. package/dist/chunks/{upload-BnmuyPqW.js → upload-Cf3wXZT8.js} +1 -1
  47. package/dist/chunks/{validators-BIM0FE31.js → validators-wtjw0aw6.js} +7 -7
  48. package/dist/chunks/variable-draft-3xseULxR.js +241 -0
  49. package/dist/dashboard/index.js +2 -2
  50. package/dist/dashboard-authoring/index.js +2226 -1704
  51. package/dist/data-app-sdk/index.js +4 -4
  52. package/dist/data-app-sdk-adapters/index.js +2 -2
  53. package/dist/data-app-sdk-validation/index.js +5 -5
  54. package/dist/format-utils/index.js +174 -167
  55. package/dist/index.js +190 -188
  56. package/dist/layouts/index.js +1 -1
  57. package/dist/pdf-export-policy/index.js +80 -28
  58. package/dist/pdf-table-layout/index.js +65 -65
  59. package/dist/report-runtime-context/index.js +1 -1
  60. package/dist/style.css +1 -1
  61. package/dist/surfboard/index.js +2 -2
  62. package/dist/types/briefings/attachment-outcomes.d.ts +1 -1
  63. package/dist/types/components/activity/activity-bell.d.ts +5 -1
  64. package/dist/types/components/activity/activity-types.d.ts +12 -4
  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/describe-card-execution-snapshot.d.ts +1 -0
  82. package/dist/types/lib/query-context/use-semantic-execution-payload-for-cards.d.ts +24 -0
  83. package/dist/types/lib/stores/dashboard-store.d.ts +36 -0
  84. package/dist/types/lib/text-variables/temporal-input-text.d.ts +28 -0
  85. package/dist/types/lib/text-variables/text-variable-types.d.ts +72 -0
  86. package/dist/types/lib/types/common-types.d.ts +155 -51
  87. package/dist/types/lib/utils/card-definition.d.ts +2 -2
  88. package/dist/types/shared/assistant-context/index.d.ts +1 -1
  89. package/dist/types/shared/assistant-context/saved-dashboard-context.d.ts +51 -1
  90. package/dist/types/shared/dashboard-authoring/card-query-request.d.ts +7 -1
  91. package/dist/types/shared/dashboard-authoring/card-settings/resolve-card-highlights.d.ts +10 -0
  92. package/dist/types/shared/dashboard-authoring/changes/card-query-part.d.ts +7 -1
  93. package/dist/types/shared/dashboard-authoring/changes/dashboard-change.d.ts +1088 -431
  94. package/dist/types/shared/dashboard-authoring/changes/diagnostics.d.ts +18 -1
  95. package/dist/types/shared/dashboard-authoring/changes/read-card-query.d.ts +8 -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-targets.d.ts +29 -0
  102. package/dist/types/shared/dashboard-authoring/dashboard-input-scope.d.ts +7 -4
  103. package/dist/types/shared/dashboard-authoring/dashboard-variable-card.d.ts +159 -0
  104. package/dist/types/shared/dashboard-authoring/dashboard-variable-changes.d.ts +61 -0
  105. package/dist/types/shared/dashboard-authoring/document-section-cards.d.ts +7 -0
  106. package/dist/types/shared/dashboard-authoring/filter-model/index.d.ts +2 -0
  107. package/dist/types/shared/dashboard-authoring/filter-model/read-dashboard-filter-model.d.ts +10 -0
  108. package/dist/types/shared/dashboard-authoring/index.d.ts +6 -0
  109. package/dist/types/shared/dashboard-authoring/measure-calculations/comparison.d.ts +2 -0
  110. package/dist/types/shared/dashboard-authoring/measure-calculations/schemas.d.ts +1 -1
  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 +2 -2
  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-TYlSW77S.js +0 -3828
  134. package/dist/chunks/filter-reach-copy-CvV7W5dd.js +0 -3965
  135. package/dist/chunks/global-date-filter-utils-N1kcsOFE.js +0 -16722
  136. package/dist/chunks/index-CJW5BdWT.js +0 -583
  137. package/dist/chunks/resolve-dashboard-input-context-DaDrZGuA.js +0 -8214
  138. package/dist/chunks/saved-dashboard-context-DFYBrE6O.js +0 -564
  139. package/dist/chunks/use-create-flow-overlay-state-BXY8-Cyz.js +0 -1436
@@ -0,0 +1,92 @@
1
+ import { SemaphorFilterReachEntry } from '../../shared/analytics-protocol/index.js';
2
+ import { UseQueryResult } from '@tanstack/react-query';
3
+ import { ControlDefinition, DashboardInputValues, TCard, TDashboard } from '../types/common-types.js';
4
+ import { CardConfig, PaginationConfig, PaginationMetadata, TableTotalsRequest } from '../types/explorer-types.js';
5
+ import { AutoJoinMetadata, ComparisonMetadataMap } from '../types/query-types.js';
6
+ import { CardQueryBlock } from '../query-context/compile-dashboard-card-filters.js';
7
+ import { SemanticExecutionPayloadAuthority } from '../query-context/use-semantic-execution-payload-for-cards.js';
8
+ import { TFilterValue } from '../../components/surfboard/filter/types.js';
9
+ import { ResolvedPrimaryDateField } from '../types/semantic-runtime-types.js';
10
+ import { DocumentTableDataPolicy } from '../document/document-table-data-policy.js';
11
+ import { CardQuerySourceRowProbe, TemporalResultOwner } from '../../shared/dashboard-authoring/index.js';
12
+ type QueryError = {
13
+ error: string;
14
+ sql: string;
15
+ };
16
+ type AdditionalState = {
17
+ isFilteringCard: boolean;
18
+ isSingleCardFrame: boolean;
19
+ queryKey: string[];
20
+ queryInputIdentity?: string;
21
+ effectivePaginationConfig?: PaginationConfig;
22
+ errorMessage: string;
23
+ errorSql: string;
24
+ pagination?: PaginationMetadata;
25
+ autoJoinMetadata?: AutoJoinMetadata;
26
+ comparisonMetadata?: ComparisonMetadataMap;
27
+ queryRequestPayload?: Record<string, unknown>;
28
+ /**
29
+ * The source-row evidence request this card's query sent (strict table
30
+ * print only), so the print view reads what was asked instead of deciding
31
+ * again (report attachment delivery RA-D15).
32
+ */
33
+ sourceRowProbe?: CardQuerySourceRowProbe;
34
+ resolvedPrimaryDateField?: ResolvedPrimaryDateField;
35
+ effectiveCardConfig?: CardConfig;
36
+ /**
37
+ * The card to render and format: the card queried with, its config as its
38
+ * rows were produced, and each column's live model format (`toRenderCard`,
39
+ * column formats CF-D5, CF-D17). Renderers format from this, never from the
40
+ * card they passed in.
41
+ */
42
+ renderCard: TCard;
43
+ resultOwner: TemporalResultOwner;
44
+ isCurrentQueryResult: boolean;
45
+ /**
46
+ * Required inputs this card's query is waiting for (the compiled
47
+ * `requiredInput` block, SPEC 4.8). When non-empty the query is disabled and
48
+ * will not run until they are set, so a Document renders it as blocked, not
49
+ * loading.
50
+ */
51
+ missingRequiredInputLabels: string[];
52
+ /**
53
+ * Why this card's query does not run, when the frame query refuses it: the
54
+ * compiled contract's block (`mapping` or `requiredInput`), or
55
+ * `sqlPaginationDisabled` for a Document SQL table without SQL pagination.
56
+ * Undefined when the query runs. A Document classifies its print failure
57
+ * from this, never from the error text (Document PDF reliability C1).
58
+ */
59
+ queryBlockedReason?: CardQueryBlockedReason;
60
+ /**
61
+ * Per filter, whether this card's query applied it and why not, as the
62
+ * server reported it (relationship filter reach RF-D13, RF-D22). Read once
63
+ * from the response; empty when the server sent none, and while the rows
64
+ * shown are retained from an earlier query (ledger R-26).
65
+ */
66
+ filterReach: SemaphorFilterReachEntry[];
67
+ };
68
+ /** Why the frame query refuses a card's query (`queryBlockedReason`). */
69
+ export type CardQueryBlockedReason = CardQueryBlock['reason'] | 'sqlPaginationDisabled';
70
+ export type DashboardCardQueryResult = UseQueryResult<any, Error> & AdditionalState;
71
+ export type DashboardCardQueryOptions = {
72
+ semanticPayloadAuthority?: SemanticExecutionPayloadAuthority;
73
+ /**
74
+ * The dashboard the cards run against instead of the store's: a draft the
75
+ * caller holds (the "Variable from data" dialog's preview, data variables
76
+ * 1b). Its inputs, mappings and variables are the ones the queries see.
77
+ */
78
+ dashboard?: TDashboard;
79
+ /** The dashboard tab the cards run at instead of the selected one (a preview on another tab). */
80
+ sheetId?: string;
81
+ runtimeContext?: 'dashboard' | 'documentSection';
82
+ documentSheetId?: string;
83
+ documentSectionId?: string;
84
+ documentTableDataPolicy?: DocumentTableDataPolicy;
85
+ documentFilterValues?: TFilterValue[];
86
+ documentControlDefinitions?: ControlDefinition[];
87
+ documentControlValues?: Record<string, unknown>;
88
+ documentDashboardInputValues?: DashboardInputValues;
89
+ tableTotalsRequest?: TableTotalsRequest;
90
+ };
91
+ export declare function useDashboardFrameQuery(cards: TCard[], options?: DashboardCardQueryOptions): DashboardCardQueryResult[];
92
+ export type { AdditionalState, QueryError };
@@ -63,6 +63,12 @@ export type CardQueryContext = {
63
63
  finalConfig: CardConfig;
64
64
  queryRelevantConfig: CardConfig;
65
65
  finalFiltersKey: string;
66
+ /**
67
+ * The rows a data variable's SQL query may return (data variables P1a-08):
68
+ * set by the assembly for a variable's projected card only, so no other
69
+ * SQL card's limit changes; the server applies it as the query's limit.
70
+ */
71
+ sqlRowLimit?: number;
66
72
  };
67
73
  export type CompiledCardQueryContext = Omit<CardQueryContext, 'filterCompilationInput'> & {
68
74
  cardFilterValues: TFilterValue[];
@@ -52,5 +52,6 @@ export declare const COMPILED_FACT_TREATMENT: {
52
52
  readonly globalDateComparison: "described";
53
53
  readonly globalDateComparisonSelection: "described";
54
54
  readonly dateComparisonInputs: "identity";
55
+ readonly sqlRowLimit: "named_not_described";
55
56
  };
56
57
  export declare function describeCardExecutionSnapshot(card: TCard, snapshot: CardExecutionSnapshotState, options: DescribeCardExecutionOptions): DescribedCardExecution;
@@ -0,0 +1,24 @@
1
+ import { TCard } from '../types/common-types.js';
2
+ import { CardConfig } from '../types/explorer-types.js';
3
+ import { SemanticExecutionPayload } from '../types/semantic-runtime-types.js';
4
+ export type SemanticExecutionPayloadAuthority = 'runtime' | 'editor';
5
+ export type SemanticExecutionPayloadCardState = {
6
+ status: 'ready' | 'loading' | 'error';
7
+ errorMessage: string | null;
8
+ };
9
+ export type SemanticExecutionPayloadForCardsResult = {
10
+ payload: SemanticExecutionPayload;
11
+ cardStatesById: Record<string, SemanticExecutionPayloadCardState>;
12
+ };
13
+ type QueryRelevantConfigsByCardId = Record<string, CardConfig | undefined>;
14
+ export declare function useSemanticExecutionPayloadForCards(cards: TCard[], options?: {
15
+ authority?: SemanticExecutionPayloadAuthority;
16
+ queryRelevantConfigsByCardId?: QueryRelevantConfigsByCardId;
17
+ /** Standalone authoring supplies its own authority instead of borrowing a dashboard session. */
18
+ environment?: {
19
+ token?: string;
20
+ apiServiceUrl?: string;
21
+ authorizationScope: string;
22
+ };
23
+ }): SemanticExecutionPayloadForCardsResult;
24
+ export {};
@@ -15,6 +15,8 @@ import { FilterGroup, Field } from '../types/explorer-types.js';
15
15
  import { DashboardControlsModelOptions } from '../controls/control-authoring-types.js';
16
16
  import { SemanticExecutionPayload } from '../types/semantic-runtime-types.js';
17
17
  import { DocumentPanelTarget } from '../document/document-panel-target.js';
18
+ import { DocumentSectionRuntime } from '../document/document-section-query-options.js';
19
+ import { VariableChange, VariableChangeResult } from '../../shared/dashboard-authoring/dashboard-variable-changes.js';
18
20
  import { DocumentEdit, DocumentEditResult } from '../document/document-edits.js';
19
21
  import { FilterSettingsChange, FilterSettingsSaveResult } from '../dashboard-inputs/filter-settings.js';
20
22
  import { FilterRef } from '../../shared/dashboard-authoring/filter-model/index.js';
@@ -26,6 +28,13 @@ import { DashboardNavigationEntry, DashboardNavigationState, DashboardTransientC
26
28
  import { CardViewStateMap, DrillStep } from '../dashboard-view-state/index.js';
27
29
  import { DashboardCardPaginationState } from '../dashboard-pagination/dashboard-card-pagination.js';
28
30
  export declare function mergeSemanticExecutionPayloadIntoTarget(target: SemanticExecutionPayload, incoming?: SemanticExecutionPayload): void;
31
+ /** What the "Variable from data" dialog opens on (data variables DV-D26). */
32
+ export type VariableEditorRequest = {
33
+ kind: 'new';
34
+ } | {
35
+ kind: 'edit';
36
+ variableId: string;
37
+ };
29
38
  type AddFrameOptions = {
30
39
  /** By intent; absent: placed by kind (RL-D12). A duplicate passes `{ position: { beside: originalId } }`. */
31
40
  placement?: FramePlacement;
@@ -124,6 +133,23 @@ export type DashboardStore = {
124
133
  selectedCard?: TCard | null;
125
134
  /** What each Document sheet's side panel shows; also its section selection. */
126
135
  documentPanelTargetBySheetId: Record<string, DocumentPanelTarget>;
136
+ /**
137
+ * The "Variable from data" dialog (data variables DV-D26): closed, a new
138
+ * variable, or one being edited. The toolbar's Variables launcher mounts the
139
+ * dialog; chips, the picker and the Document panel open it through here.
140
+ */
141
+ variableEditor: VariableEditorRequest | null;
142
+ /**
143
+ * The Data variables list, opened from the toolbar's ⋮ menu (both the
144
+ * package's and the app's); its host sits beside the ⋮ button.
145
+ */
146
+ variablesListOpen: boolean;
147
+ /**
148
+ * Each open Document tab's section runtime, as its own variable answers run
149
+ * it (DV-D29): the dialog's preview at a Document place reads it here
150
+ * instead of deriving the Document's values a second time.
151
+ */
152
+ documentSectionRuntimeBySheetId: Record<string, DocumentSectionRuntime>;
127
153
  documentInputRuntimeBySheetId: Record<string, DocumentInputRuntimeState>;
128
154
  /**
129
155
  * Pending sheet-wide frame rewrites produced while visual editing. These stay
@@ -358,6 +384,16 @@ type Actions = {
358
384
  */
359
385
  editDocument: (sheetId: string, edit: DocumentEdit) => DocumentEditResult;
360
386
  setDocumentPanelTarget: (sheetId: string, target: DocumentPanelTarget) => void;
387
+ setDocumentSectionRuntime: (sheetId: string, runtime: DocumentSectionRuntime | null) => void;
388
+ openVariableEditor: (request: VariableEditorRequest) => void;
389
+ closeVariableEditor: () => void;
390
+ setVariablesListOpen: (open: boolean) => void;
391
+ /**
392
+ * The one write of `dashboard.variables` from the editor (data variables
393
+ * M4, DV-INV-5): adds, updates or removes a variable through
394
+ * `applyVariableChange`. Nothing is written when the change is refused.
395
+ */
396
+ saveVariableChange: (change: VariableChange) => VariableChangeResult;
361
397
  setDocumentInputFilterValues: (sheetId: string, valuesByInputId: Record<string, TFilterValue | undefined>) => void;
362
398
  setDocumentInputFilterValue: (sheetId: string, inputId: string, filterValue: TFilterValue) => void;
363
399
  removeDocumentInputFilterValue: (sheetId: string, inputId: string) => void;
@@ -0,0 +1,28 @@
1
+ import { TFilterValue } from '../../components/surfboard/filter/types.js';
2
+ import { TemporalInputCalendar, TemporalInputPart, TemporalInputPresentation, TemporalInputValue } from '../../shared/format-utils/temporal-input-presentation.js';
3
+ import { ResolvedTemporalValueFormatPreferences } from '../../shared/value-format-preferences/index.js';
4
+ /** The viewer's temporal preferences and Calendar, for formatting inputs. */
5
+ export type TemporalTextPresentationContext = {
6
+ preferences: ResolvedTemporalValueFormatPreferences;
7
+ calendar: TemporalInputCalendar;
8
+ };
9
+ export declare function getTemporalTextPresentationContext(input: {
10
+ preferences?: ResolvedTemporalValueFormatPreferences | null;
11
+ calendar?: TemporalInputCalendar | null;
12
+ }): TemporalTextPresentationContext;
13
+ /** A date filter's current value as a temporal input value. */
14
+ export declare function getTemporalValueFromFilter(filterValue: TFilterValue | undefined): TemporalInputValue | undefined;
15
+ /** A date control's current value (one date) as a temporal input value. */
16
+ export declare function getTemporalValueFromControl(value: unknown): TemporalInputValue | undefined;
17
+ /** Which bound an input part shows. */
18
+ export declare function getTemporalInputPart(exportKey: string): TemporalInputPart;
19
+ /** A stored presentation, dropping (and reporting once) an invalid one. */
20
+ export declare function readTextVariablePresentation(stored: unknown): TemporalInputPresentation | undefined;
21
+ /** A date input's value as text; empty when it has no value. */
22
+ export declare function formatTemporalInputText({ inputId, value, exportKey, presentation, context, }: {
23
+ inputId: string;
24
+ value: TemporalInputValue | undefined;
25
+ exportKey: string;
26
+ presentation?: TemporalInputPresentation;
27
+ context: TemporalTextPresentationContext;
28
+ }): string;
@@ -0,0 +1,72 @@
1
+ import { TemporalInputPresentation } from '../../shared/format-utils/temporal-input-presentation.js';
2
+ /** What kind of value a variable holds; picks the chip's icon. */
3
+ export type TextVariableKind = 'filter' | 'date' | 'control' | 'report' | 'data';
4
+ /**
5
+ * A data variable's state at this place, for authors (DV-D27; readers never
6
+ * see it): the chip reads it after the name.
7
+ */
8
+ export type TextVariableChipState = {
9
+ kind: 'loading' | 'many' | 'empty' | 'held' | 'failed' | 'broken';
10
+ /** Brand-neutral words after the name: "more than one matches". */
11
+ label: string;
12
+ };
13
+ /** How one variable reference reads as a chip. */
14
+ export type TextVariableChipFace = {
15
+ /** The input's name ("State"), or "Missing input". */
16
+ name: string;
17
+ kind: TextVariableKind;
18
+ /** Shown after the name when the chip shows a part other than the default. */
19
+ partLabel?: string;
20
+ /** The reference points at an input or variable that no longer exists. */
21
+ missing?: boolean;
22
+ /** A data variable's state here, when it has no value to show. */
23
+ state?: TextVariableChipState;
24
+ };
25
+ /** One part of an input a chip can show, with what it holds now. */
26
+ export type TextVariablePart = {
27
+ key: string;
28
+ label: string;
29
+ preview?: string;
30
+ };
31
+ /** One input (or report value) the picker offers. */
32
+ export type TextVariableOption = {
33
+ id: string;
34
+ name: string;
35
+ kind: TextVariableKind;
36
+ parts: TextVariablePart[];
37
+ defaultPart: string;
38
+ /** A data variable text at this place already uses: listed first (DV-D3). */
39
+ usedHere?: boolean;
40
+ /** A date input: its value can be shown in a chosen format (Plan 08). */
41
+ temporal?: {
42
+ /** What `part` prints now in `presentation` (automatic when omitted). */
43
+ preview: (part: string, presentation?: TemporalInputPresentation) => string;
44
+ /** The selection has a period name now ("Today"). */
45
+ hasPeriodName: boolean;
46
+ };
47
+ };
48
+ /** What a chip shows: an option, one of its parts, and a date format. */
49
+ export type TextVariableSelection = {
50
+ optionId: string;
51
+ part: string;
52
+ /** A date input's pinned format; omission means automatic. */
53
+ temporal?: TemporalInputPresentation;
54
+ };
55
+ export declare const TEXT_VARIABLE_PART_LABELS: Record<string, string>;
56
+ /** A date part's label: the whole value reads as its dates. */
57
+ export declare const TEMPORAL_TEXT_VARIABLE_PART_LABELS: Record<string, string>;
58
+ /** A pinned date format, as the chip's suffix names it. */
59
+ export declare function temporalFormatLabel(presentation: TemporalInputPresentation | undefined): string | undefined;
60
+ /** The chip's suffix: a non-default part, then a pinned format. */
61
+ export declare function chipPartLabel(partLabel: string | undefined, presentation?: TemporalInputPresentation): string | undefined;
62
+ /** The picker's groups, in order (the product mock's: data used here, data elsewhere, filters, controls, report). */
63
+ export declare const TEXT_VARIABLE_GROUPS: readonly ["Data · used here", "Data · elsewhere", "Filters", "Controls", "Report"];
64
+ export type TextVariableGroup = (typeof TEXT_VARIABLE_GROUPS)[number];
65
+ /** The group a kind falls in; a data option's group depends on its use (`textVariableOptionGroup`). */
66
+ export declare function textVariableGroup(kind: TextVariableKind): TextVariableGroup;
67
+ export declare function textVariableOptionGroup(option: Pick<TextVariableOption, 'kind' | 'usedHere'>): TextVariableGroup;
68
+ /**
69
+ * Options whose name matches `query`, in the picker's order: filters, then
70
+ * controls, then report values.
71
+ */
72
+ export declare function filterTextVariableOptions(options: readonly TextVariableOption[], query: string): TextVariableOption[];
@@ -1141,28 +1141,90 @@ export type ResolvedDashboardInputContext = {
1141
1141
  /** Other cards' selections, resolved for this card. Empty without a card. */
1142
1142
  selections: ResolvedCardSelection[];
1143
1143
  };
1144
- export type DashboardInputVariableRef = {
1145
- source: 'dashboardInput';
1144
+ /** A report value a text can show: when it was generated, and its pages. */
1145
+ export type ReportValueKey = 'generatedAt' | 'pageNumber' | 'pageCount';
1146
+ /**
1147
+ * A variable in text, on text cards and Documents alike (data variables
1148
+ * DV-D12). `export` is the stored name of what the product calls a part.
1149
+ * Older text cards stored an input as `source: 'dashboardInput'`; loading
1150
+ * reads it as `input` (`src/lib/dashboard-variables/refs.ts`), so no other
1151
+ * module sees that shape.
1152
+ */
1153
+ export type VariableRef = {
1154
+ source: 'input';
1146
1155
  inputId: string;
1147
1156
  export: DashboardInputExportKey;
1148
1157
  } | {
1158
+ /** Older or imported text that names an input by its alias. */
1149
1159
  source: 'dashboardInputAlias';
1150
1160
  variableName: string;
1151
1161
  export?: DashboardInputExportKey;
1152
1162
  } | {
1153
1163
  source: 'documentMeta';
1154
- key: 'generatedAt' | 'pageNumber' | 'pageCount';
1164
+ key: ReportValueKey;
1165
+ } | {
1166
+ /** A part of a data variable on the dashboard (data variables 1a). */
1167
+ source: 'data';
1168
+ variableId: string;
1169
+ export: string;
1170
+ };
1171
+ /**
1172
+ * A data variable (data variables DV-D3, DV-D4): a named question with one
1173
+ * answer, derived like a card where its chip shows (DV-D29). Stored on the
1174
+ * dashboard beside its inputs. Its `id` is a filter target id: filter
1175
+ * mappings and scopes name it where they name a card (DV-D7).
1176
+ */
1177
+ export type DataVariable = {
1178
+ /** Stable; refs and filter mappings point at it. Never equal to a card id. */
1179
+ id: string;
1180
+ /** What text writes: `{{yard_address}}`. Unique across inputs and variables. */
1181
+ name: string;
1182
+ label?: string;
1183
+ query: VariableQuery;
1184
+ get: VariableGet;
1185
+ /** The presentation a new chip starts with. */
1186
+ presentation?: TextVariablePresentation;
1187
+ /** Shown where there is no answer. */
1188
+ emptyText?: string;
1189
+ };
1190
+ /**
1191
+ * The query part of a card, as the editor's builders and `card.add`'s
1192
+ * resolver write it (DV-D4, DV-D16). Conditions are `config.filters`; local
1193
+ * calculated fields are `calculatedFields`. `rowLimit` is never stored:
1194
+ * `get` decides it.
1195
+ */
1196
+ export type VariableQuery = Pick<TCard, 'connectionId' | 'dataSource' | 'sql' | 'calculatedFields'> & {
1197
+ config?: Pick<CardConfig, 'groupByColumns' | 'metricColumns' | 'sortByColumns' | 'filters' | 'joinPlan' | 'queryBaseSource'>;
1198
+ };
1199
+ /**
1200
+ * How one answer is taken from the rows (DV-D5): the only distinct row, the
1201
+ * first by the query's sort, a list of one grouped column, or one aggregate.
1202
+ * A comparison is stored on the measure, as a card's is (P3b-02).
1203
+ */
1204
+ export type VariableGet = {
1205
+ kind: 'only';
1206
+ } | {
1207
+ kind: 'first';
1208
+ } | {
1209
+ kind: 'list';
1210
+ limit?: number;
1211
+ separator?: string;
1212
+ } | {
1213
+ kind: 'aggregate';
1155
1214
  };
1215
+ /** Older text cards' typed text: words and variables, no formats. */
1156
1216
  export type DashboardInputTextContent = Array<{
1157
1217
  type: 'text';
1158
1218
  value: string;
1159
1219
  } | {
1160
1220
  type: 'variable';
1161
- ref: DashboardInputVariableRef;
1221
+ ref: VariableRef;
1162
1222
  }>;
1163
- export type TextCardInlineFormat = {
1223
+ /** Emphasis on a run of text or a variable, on text cards and Documents alike. */
1224
+ export type TextInlineFormat = {
1164
1225
  bold?: boolean;
1165
1226
  italic?: boolean;
1227
+ underline?: boolean;
1166
1228
  };
1167
1229
  /**
1168
1230
  * How a variable in text shows its input's value (Plan 08). Sparse: omission
@@ -1170,41 +1232,96 @@ export type TextCardInlineFormat = {
1170
1232
  */
1171
1233
  export type TextVariablePresentation = {
1172
1234
  temporal?: TemporalInputPresentation;
1235
+ /** A number's decimal places (data variables 1a). */
1236
+ decimals?: number;
1237
+ /**
1238
+ * Presentation words (data variables DV-D19, P3a-09), on a data variable's
1239
+ * number only, applied by `formatPresentedNumber`: the unit after the
1240
+ * number, singular when it shows as 1.
1241
+ */
1242
+ units?: [singular: string, plural: string];
1243
+ /** Words by the sign of the number shown; the zero word replaces the text when it shows as 0. */
1244
+ signWords?: [positive: string, negative: string, zero: string];
1245
+ /** The number without its sign. */
1246
+ absolute?: boolean;
1247
+ /** A ratio shown as a percent. */
1248
+ percent?: boolean;
1249
+ /**
1250
+ * Colours by rule (data variables DV-D23, P3b-06), on a chip: the KPI's
1251
+ * rules, each naming the chip's value as `{ kind: 'result', key: 'value' }`.
1252
+ */
1253
+ colorRules?: import('../../shared/dashboard-authoring/conditional-formatting/types.js').ConditionalRule[];
1173
1254
  };
1174
- export type TextCardRichInline = {
1255
+ /** Words or a variable: what a link holds, and all a Document's text holds until it takes links. */
1256
+ export type TextLeaf = {
1175
1257
  type: 'text';
1176
1258
  value: string;
1177
- format?: TextCardInlineFormat;
1259
+ format?: TextInlineFormat;
1178
1260
  } | {
1179
1261
  type: 'variable';
1180
- ref: DashboardInputVariableRef;
1181
- format?: TextCardInlineFormat;
1262
+ ref: VariableRef;
1263
+ format?: TextInlineFormat;
1182
1264
  presentation?: TextVariablePresentation;
1265
+ };
1266
+ /**
1267
+ * A part of a link's address (data variables DV-D24): literal characters, or
1268
+ * a variable whose value is filled in, URL-encoded, where the link shows.
1269
+ */
1270
+ export type LinkUrlPart = {
1271
+ type: 'text';
1272
+ value: string;
1183
1273
  } | {
1274
+ type: 'variable';
1275
+ ref: VariableRef;
1276
+ };
1277
+ /**
1278
+ * A link: words and variables, never a block (data variables P3a-05). Its
1279
+ * address is literal, or parts when it holds variables (DV-D24), stored by
1280
+ * ref so a renamed variable keeps the link.
1281
+ */
1282
+ export type TextLink = {
1184
1283
  type: 'link';
1185
- url: string;
1186
- children: Array<{
1187
- type: 'text';
1188
- value: string;
1189
- format?: TextCardInlineFormat;
1190
- } | {
1191
- type: 'variable';
1192
- ref: DashboardInputVariableRef;
1193
- format?: TextCardInlineFormat;
1194
- presentation?: TextVariablePresentation;
1195
- }>;
1284
+ url: string | LinkUrlPart[];
1285
+ children: TextLeaf[];
1196
1286
  };
1287
+ /**
1288
+ * A wording block's test (data variables DV-D20, P3a-10): one variable's
1289
+ * answer has a value, is empty, equals a literal, or is below or above a
1290
+ * number. `present` and `empty` are complements.
1291
+ */
1292
+ export type WordingTest = {
1293
+ ref: VariableRef;
1294
+ is: WordingTestKind;
1295
+ value?: string | number;
1296
+ };
1297
+ export type WordingTestKind = 'present' | 'empty' | 'equals' | 'below' | 'above';
1298
+ /**
1299
+ * A wording block: `then` shows when the test holds, `else` (if any)
1300
+ * otherwise. An `else` holding exactly one block is a chain ("otherwise
1301
+ * when"). A block sits inside one line: its branches hold no line break.
1302
+ */
1303
+ export interface TextWhen<T> {
1304
+ type: 'when';
1305
+ test: WordingTest;
1306
+ then: T[];
1307
+ else?: T[];
1308
+ }
1309
+ /**
1310
+ * A run of text, on text cards (data variables DV-D31): words, a variable, a
1311
+ * link holding either, or a wording block.
1312
+ */
1313
+ export type TextInline = TextLeaf | TextLink | TextWhen<TextInline>;
1197
1314
  export type TextCardRichBlock = {
1198
1315
  type: 'paragraph';
1199
- children: TextCardRichInline[];
1316
+ children: TextInline[];
1200
1317
  } | {
1201
1318
  type: 'heading';
1202
1319
  level: 1 | 2;
1203
- children: TextCardRichInline[];
1320
+ children: TextInline[];
1204
1321
  } | {
1205
1322
  type: 'list';
1206
1323
  style: 'bulleted' | 'numbered';
1207
- items: TextCardRichInline[][];
1324
+ items: TextInline[][];
1208
1325
  };
1209
1326
  export type TextCardRichContent = {
1210
1327
  version: 1;
@@ -1238,7 +1355,7 @@ export type DashboardCardReferenceRemapping = {
1238
1355
  inputIds?: Record<string, string>;
1239
1356
  controlIds?: Record<string, string>;
1240
1357
  filterIds?: Record<string, string>;
1241
- inputAliases?: Record<string, DashboardInputVariableRef>;
1358
+ inputAliases?: Record<string, VariableRef>;
1242
1359
  };
1243
1360
  export type TCard = {
1244
1361
  id: string;
@@ -1262,6 +1379,12 @@ export type TCard = {
1262
1379
  clickToFilter?: ClickToFilterSettings;
1263
1380
  /** Receiver side. false = this card ignores selections from every source card. Default true. */
1264
1381
  respondsToSelections?: boolean;
1382
+ /**
1383
+ * Set only on a data variable's projected card, never stored: the variable
1384
+ * it runs (data variables DV-D9, P3b-03). The browser's comparison rule
1385
+ * reads it through `variableCardKeepsComparison`.
1386
+ */
1387
+ dataVariableId?: string;
1265
1388
  /** Instance-level click-to-filter overrides for a linked library visual. */
1266
1389
  linkedClickToFilterOverrides?: LinkedClickToFilterOverrides;
1267
1390
  paginationConfig?: PaginationConfig;
@@ -1320,7 +1443,6 @@ export type DocumentPageSetup = {
1320
1443
  export type DocumentRuntimeSettings = {
1321
1444
  generatedAtFormat?: string;
1322
1445
  };
1323
- export type DocumentInputExportKey = 'label' | 'value' | 'start' | 'end' | 'range';
1324
1446
  export type DocumentInputDefinition = DocumentFilterInputDefinition | DocumentControlInputDefinition;
1325
1447
  export type DocumentInputBase = {
1326
1448
  id: string;
@@ -1333,12 +1455,12 @@ export type DocumentInputBase = {
1333
1455
  export type DocumentFilterInputDefinition = DocumentInputBase & {
1334
1456
  kind: 'filter';
1335
1457
  filter: TFilter;
1336
- exports?: DocumentInputExportKey[];
1458
+ exports?: DashboardInputExportKey[];
1337
1459
  };
1338
1460
  export type DocumentControlInputDefinition = DocumentInputBase & {
1339
1461
  kind: 'control';
1340
1462
  control: ControlDefinition;
1341
- exports?: DocumentInputExportKey[];
1463
+ exports?: DashboardInputExportKey[];
1342
1464
  };
1343
1465
  export type ResolvedDocumentInput = {
1344
1466
  inputId: string;
@@ -1392,30 +1514,10 @@ export type DocumentImageRegionBlock = DocumentRegionBlockBase & {
1392
1514
  alt?: string;
1393
1515
  widthPx?: number;
1394
1516
  };
1395
- export type DocumentTextContent = DocumentTextNode[];
1396
- export type DocumentTextNode = {
1397
- type: 'text';
1398
- value: string;
1399
- format?: DocumentTextInlineFormat;
1400
- } | {
1401
- type: 'variable';
1402
- ref: DocumentVariableRef;
1403
- format?: DocumentTextInlineFormat;
1404
- presentation?: TextVariablePresentation;
1405
- };
1406
- export type DocumentVariableRef = {
1407
- source: 'input';
1408
- inputId: string;
1409
- export: DocumentInputExportKey;
1410
- } | {
1411
- source: 'documentMeta';
1412
- key: 'generatedAt' | 'pageNumber' | 'pageCount';
1413
- };
1414
- export type DocumentTextInlineFormat = {
1415
- bold?: boolean;
1416
- italic?: boolean;
1417
- underline?: boolean;
1418
- };
1517
+ /** A run of Document text: words, a variable, a link (data variables DV-D24) or a wording block. */
1518
+ export type DocumentTextInline = TextLeaf | TextLink | TextWhen<DocumentTextInline>;
1519
+ /** A Document line or text section. */
1520
+ export type DocumentTextContent = DocumentTextInline[];
1419
1521
  export type DocumentTextStyle = {
1420
1522
  fontSize?: number;
1421
1523
  fontWeight?: 'normal' | 'medium' | 'semibold' | 'bold';
@@ -1643,6 +1745,8 @@ export type TDashboard = {
1643
1745
  defaultControlValues?: Record<string, unknown>;
1644
1746
  inputs?: DashboardInput[];
1645
1747
  defaultInputValues?: DashboardInputValues;
1748
+ /** Data variables (DV-D3). Absent reads as none. */
1749
+ variables?: DataVariable[];
1646
1750
  filterLayout?: FilterLayoutSettings;
1647
1751
  };
1648
1752
  type BaseCustomCard = {
@@ -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: "ready" | "absent";
21
+ status: "absent" | "ready";
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: "ready" | "absent" | "invalid";
31
+ status: "absent" | "invalid" | "ready";
32
32
  matrix: {
33
33
  presentation: {
34
34
  totals: {
@@ -6,4 +6,4 @@
6
6
  * case's context from a saved dashboard with `projectSavedDashboardContext`.
7
7
  */
8
8
  export { AssistantContextSourceError, projectAssistantContext, type AssistantContextSource, type AssistantContextSourceIssue, } from './project-context.js';
9
- export { assistantCardReplayFields, buildSavedCardRequest, cardReplayOf, projectSavedDashboardContext, projectSavedDashboardTurn, type AssistantCardReplayFields, type SavedCardHost, type SavedCardRequestRefusal, type SavedDashboardPlace, } from './saved-dashboard-context.js';
9
+ export { assistantCardReplayFields, buildSavedCardRequest, buildSavedVariableRequest, cardReplayOf, projectSavedDashboardContext, projectSavedDashboardTurn, type AssistantCardReplayFields, type SavedCardHost, type SavedCardRequestRefusal, type SavedVariableRequestRefusal, type SavedDashboardPlace, } from './saved-dashboard-context.js';