react-semaphor 0.1.564 → 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 (132) 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-D1BEEHUF.js → assistant-chat-DNfb5fbF.js} +204 -204
  8. package/dist/chunks/{bookmark-impact-XOsVUAqW.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-DfYsASNd.js → dashboard-CtIfxycc.js} +1 -1
  14. package/dist/chunks/dashboard-briefing-launcher-D3mc6peE.js +4910 -0
  15. package/dist/chunks/{dashboard-controls-CJ8Dz50D.js → dashboard-controls-BFv0zdws.js} +692 -682
  16. package/dist/chunks/{dashboard-json-D3uZxGO-.js → dashboard-json-CXn_3OYb.js} +4 -4
  17. package/dist/chunks/{dates-EvDtT25n.js → dates-DcRxw17S.js} +12 -12
  18. package/dist/chunks/{edit-dashboard-visual-CgHJXBQv.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-CAgf2x4E.js → index-DDa_rklN.js} +68 -63
  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-Db-b04B4.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-C18J-YZC.js +21394 -0
  35. package/dist/chunks/{save-CHV1B1fL.js → save-D6pHmSSP.js} +1 -1
  36. package/dist/chunks/saved-dashboard-context-DhC_EVus.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-T6TsiBMT.js} +80634 -80503
  39. package/dist/chunks/{shelf-drop-preview-context-cEyVkKTF.js → shelf-drop-preview-context-CNWL_b0S.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-IdmtrNkA.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-3xseULxR.js +241 -0
  48. package/dist/dashboard/index.js +2 -2
  49. package/dist/dashboard-authoring/index.js +2206 -1705
  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/components/dashboard-variables/data-variables-menu.d.ts +8 -0
  62. package/dist/types/components/dashboard-variables/variable-editor-host.d.ts +1 -0
  63. package/dist/types/components/index.d.ts +2 -0
  64. package/dist/types/index.js +5 -5
  65. package/dist/types/lib/dashboard-inputs/build-normalized-dashboard-inputs.d.ts +62 -0
  66. package/dist/types/lib/dashboard-inputs/dashboard-filter-mapping-authoring.d.ts +33 -2
  67. package/dist/types/lib/dashboard-inputs/filter-settings.d.ts +7 -2
  68. package/dist/types/lib/dashboard-inputs/prepare-loaded-dashboard.d.ts +4 -2
  69. package/dist/types/lib/dashboard-variables/data-text.d.ts +33 -0
  70. package/dist/types/lib/dashboard-variables/types.d.ts +207 -0
  71. package/dist/types/lib/document/document-edits.d.ts +16 -1
  72. package/dist/types/lib/document/document-panel-target.d.ts +1 -1
  73. package/dist/types/lib/document/document-section-query-options.d.ts +29 -0
  74. package/dist/types/lib/document/document-table-data-policy.d.ts +0 -1
  75. package/dist/types/lib/hooks/use-dashboard-frame-query.d.ts +92 -0
  76. package/dist/types/lib/query-context/build-card-query-context.d.ts +6 -0
  77. package/dist/types/lib/query-context/describe-card-execution-snapshot.d.ts +1 -0
  78. package/dist/types/lib/query-context/use-semantic-execution-payload-for-cards.d.ts +24 -0
  79. package/dist/types/lib/stores/dashboard-store.d.ts +36 -0
  80. package/dist/types/lib/text-variables/temporal-input-text.d.ts +28 -0
  81. package/dist/types/lib/text-variables/text-variable-types.d.ts +72 -0
  82. package/dist/types/lib/types/common-types.d.ts +155 -51
  83. package/dist/types/lib/utils/card-definition.d.ts +2 -2
  84. package/dist/types/shared/assistant-context/index.d.ts +1 -1
  85. package/dist/types/shared/assistant-context/saved-dashboard-context.d.ts +51 -1
  86. package/dist/types/shared/dashboard-authoring/card-query-request.d.ts +7 -1
  87. package/dist/types/shared/dashboard-authoring/card-settings/resolve-card-highlights.d.ts +10 -0
  88. package/dist/types/shared/dashboard-authoring/changes/card-query-part.d.ts +1 -0
  89. package/dist/types/shared/dashboard-authoring/changes/dashboard-change.d.ts +1087 -430
  90. package/dist/types/shared/dashboard-authoring/changes/diagnostics.d.ts +18 -1
  91. package/dist/types/shared/dashboard-authoring/changes/resolve-dashboard-changes.d.ts +1 -1
  92. package/dist/types/shared/dashboard-authoring/conditional-formatting/kpi.d.ts +10 -0
  93. package/dist/types/shared/dashboard-authoring/conditional-formatting/schema.d.ts +40 -40
  94. package/dist/types/shared/dashboard-authoring/control-execution-contract.d.ts +16 -16
  95. package/dist/types/shared/dashboard-authoring/dashboard-card-source-index.d.ts +1 -0
  96. package/dist/types/shared/dashboard-authoring/dashboard-filter-targets.d.ts +29 -0
  97. package/dist/types/shared/dashboard-authoring/dashboard-input-scope.d.ts +7 -4
  98. package/dist/types/shared/dashboard-authoring/dashboard-variable-card.d.ts +159 -0
  99. package/dist/types/shared/dashboard-authoring/dashboard-variable-changes.d.ts +61 -0
  100. package/dist/types/shared/dashboard-authoring/document-section-cards.d.ts +7 -0
  101. package/dist/types/shared/dashboard-authoring/filter-model/index.d.ts +2 -0
  102. package/dist/types/shared/dashboard-authoring/filter-model/read-dashboard-filter-model.d.ts +10 -0
  103. package/dist/types/shared/dashboard-authoring/index.d.ts +6 -0
  104. package/dist/types/shared/dashboard-authoring/measure-calculations/comparison.d.ts +2 -0
  105. package/dist/types/shared/dashboard-authoring/operations/operation-sentences.d.ts +1 -1
  106. package/dist/types/shared/dashboard-authoring/operations/operation-types.d.ts +50 -3
  107. package/dist/types/shared/dashboard-authoring/outline/outline-dashboard.d.ts +48 -1
  108. package/dist/types/shared/dashboard-authoring/outline/outline-filters.d.ts +2 -2
  109. package/dist/types/shared/dashboard-authoring/text-card-words/blocks.d.ts +87 -13
  110. package/dist/types/shared/dashboard-authoring/text-card-words/chip-colors.d.ts +23 -0
  111. package/dist/types/shared/dashboard-authoring/text-card-words/index.d.ts +90 -8
  112. package/dist/types/shared/dashboard-authoring/text-card-words/rich-content.d.ts +31 -3
  113. package/dist/types/shared/dashboard-authoring/text-card-words/variable-words.d.ts +8 -0
  114. package/dist/types/shared/dashboard-authoring/variable-draft.d.ts +125 -0
  115. package/dist/types/shared/dashboard-authoring/variable-editability.d.ts +24 -0
  116. package/dist/types/shared/dashboard-authoring/variable-references.d.ts +39 -0
  117. package/dist/types/shared/format-utils/document-print.d.ts +4 -2
  118. package/dist/types/shared/format-utils/index.d.ts +1 -0
  119. package/dist/types/shared/format-utils/pdf-capacity-lines.d.ts +17 -0
  120. package/dist/types/shared/format-utils/pdf-delivery.d.ts +8 -1
  121. package/dist/types/shared/format-utils/pdf-export-policy.d.ts +74 -6
  122. package/dist/types/shared/format-utils/presentation-execution.d.ts +9 -0
  123. package/package.json +2 -2
  124. package/src/data-app-sdk/README.md +3 -3
  125. package/dist/chunks/bookmark-state-CWeoGbrx.js +0 -743
  126. package/dist/chunks/braces-DzgoQC64.js +0 -23
  127. package/dist/chunks/dashboard-briefing-launcher-lvYfJoUQ.js +0 -3878
  128. package/dist/chunks/filter-reach-copy-Cmb05jlE.js +0 -3965
  129. package/dist/chunks/global-date-filter-utils-ruJYwjgZ.js +0 -16733
  130. package/dist/chunks/resolve-dashboard-input-context-i_jCSYae.js +0 -8214
  131. package/dist/chunks/saved-dashboard-context-Dg3oDmH_.js +0 -564
  132. package/dist/chunks/use-create-flow-overlay-state-Dl6DCxh8.js +0 -1436
@@ -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
  };
@@ -33,9 +33,9 @@ export type OutlineFilter = {
33
33
  exceptSheetIds?: string[];
34
34
  /** With "all": it also shows on Document sheets (their sections' cards). */
35
35
  includesDocumentSheets?: true;
36
- /** Card ids the filter applies to. */
36
+ /** The targets the filter applies to: card ids, and data variables' ids (DV-D30). */
37
37
  reaches: string[];
38
- /** Card ids excluded explicitly. */
38
+ /** Targets excluded explicitly. */
39
39
  excluded: string[];
40
40
  /** In scope, not matched; with a resolver (server side), the reason relationship reach gave. */
41
41
  notReached: Array<{
@@ -1,17 +1,65 @@
1
+ import { TextVariablePresentation, WordingTestKind } from '../../../lib/types/common-types.js';
1
2
  /**
2
3
  * A text card's words as a change and the outline give them (building a
3
4
  * report SPEC §2.4, BR-D11 as revised by OQ-1): blocks shaped like the
4
5
  * stored rich text, with shorter names. Text is taken literally: nothing is
5
6
  * parsed or printed, so `**` in a run is two asterisks.
6
7
  */
7
- /** Plain text, or one run of text or a variable with its emphasis and link. */
8
- export type TextRun = string | {
8
+ /** A chip's colour in the highlight words card highlights use (data variables P3b-08). */
9
+ export type ChipColor = {
10
+ when: {
11
+ operator: '=' | '!=' | '>' | '>=' | '<' | '<=';
12
+ value: number | string;
13
+ };
14
+ color: string;
15
+ };
16
+ /**
17
+ * A variable run's presentation: the chip's stored presentation (P3a-07),
18
+ * with its colour rules stated as highlight words (P3b-08).
19
+ */
20
+ export type RunPresentation = Omit<TextVariablePresentation, 'colorRules'> & {
21
+ colors?: ChipColor[];
22
+ };
23
+ /**
24
+ * A link's address as a run states it (data variables DV-D24): literal, or
25
+ * words and variables by name (`{ variable: 'name.part' }`), each value
26
+ * URL-encoded where the link shows.
27
+ */
28
+ export type LinkRun = string | Array<string | {
29
+ variable: string;
30
+ }>;
31
+ /** One address in one form, to compare two runs' links. */
32
+ export declare function linkRunKey(link: LinkRun | undefined): string | undefined;
33
+ /**
34
+ * Words or a variable, with emphasis and a link. A variable run may carry its
35
+ * chip's presentation (data variables P3a-07).
36
+ */
37
+ export type TextLeafRun = {
9
38
  text?: string;
10
39
  variable?: string;
11
40
  bold?: boolean;
12
41
  italic?: boolean;
13
- link?: string;
42
+ underline?: boolean;
43
+ link?: LinkRun;
44
+ presentation?: RunPresentation;
14
45
  };
46
+ /** A wording block's test: one variable, by name or `name.part` (data variables DV-D20). */
47
+ export type TextWhenTest = {
48
+ variable: string;
49
+ is: WordingTestKind;
50
+ value?: string | number;
51
+ };
52
+ /**
53
+ * A wording block (DV-D20): `then` shows when the test holds, `else` (if any)
54
+ * otherwise. An `else` holding exactly one block is a chain.
55
+ */
56
+ export type TextWhenRun = {
57
+ when: TextWhenTest;
58
+ then: TextRun[];
59
+ else?: TextRun[];
60
+ };
61
+ /** Plain text, one run of text or a variable, or a wording block. */
62
+ export type TextRun = string | TextLeafRun | TextWhenRun;
15
63
  export type TextBlock = {
16
64
  type: 'heading';
17
65
  level: 1 | 2;
@@ -32,27 +80,53 @@ export type TextRunObject = {
32
80
  variable?: string;
33
81
  bold?: true;
34
82
  italic?: true;
35
- link?: string;
83
+ underline?: true;
84
+ link?: LinkRun;
85
+ presentation?: RunPresentation;
36
86
  };
87
+ /** Whether a run is a wording block. */
88
+ export declare function isWhenRun(run: TextRun | undefined): run is TextWhenRun;
37
89
  /**
38
- * A run as an object. A string is plain text; a run naming a variable is
39
- * that variable (`name` alone is `name.label`); `false` flags are dropped.
90
+ * A run as an object. A string is plain text; a run naming a variable keeps
91
+ * the name as sent (the catalog supplies a default part, data variables
92
+ * DV-D12); `false` flags are dropped.
40
93
  */
41
- export declare function runObject(run: TextRun): TextRunObject;
94
+ export declare function runObject(run: string | TextLeafRun): TextRunObject;
42
95
  /**
43
96
  * Runs in their one form (SPEC §2.4): empty text dropped, neighbouring text
44
- * of one emphasis and link joined, and a run with no emphasis or link a
45
- * string.
97
+ * of one emphasis and link joined, a run with no emphasis or link a string,
98
+ * and each wording block's branches in their one form.
46
99
  */
47
100
  export declare function oneFormRuns(runs: readonly TextRun[]): TextRun[];
48
101
  /** Blocks in their one form: what the outline reads, and what a change is compared and stored as. */
49
102
  export declare function oneForm(blocks: readonly TextBlock[]): TextBlocks;
50
- /** A block's runs, with each one's path under the block's own. */
51
- export declare function blockRuns(block: TextBlock, at: string): Array<{
103
+ /** One run with its path, and whether it sits in a wording block's branch. */
104
+ export type RunAt = {
52
105
  run: TextRun;
53
106
  path: string;
54
- }>;
55
- /** The characters of text in the blocks (variables count none). */
107
+ inBlock: boolean;
108
+ };
109
+ /** Every run of some runs, each wording block and then its branches' runs, with their paths (P3a-04). */
110
+ export declare function eachRun(runs: readonly TextRun[], at: string, inBlock?: boolean): RunAt[];
111
+ /** A block's runs, wording blocks' branches included, with each one's path under the block's own. */
112
+ export declare function blockRuns(block: TextBlock, at: string): RunAt[];
113
+ /** The characters of text in the blocks, both branches of a wording block included (variables count none). */
56
114
  export declare function textLength(blocks: readonly TextBlock[]): number;
115
+ /** The first words of one line of runs (a Document line or text section). */
116
+ export declare function runsExcerpt(runs: readonly TextRun[], length?: number): string;
57
117
  /** The first words of a text card, for the sentence that adds it. */
58
118
  export declare function blocksExcerpt(blocks: readonly TextBlock[], length?: number): string;
119
+ /**
120
+ * A wording block as an agent reads it back (DV-D20, "What an agent reads
121
+ * back"; ledger P3a-18): `when variance is below 0, show "…"; otherwise "…"`.
122
+ * A branch that is only the tested variable reads "show it" ("show that"
123
+ * further down a chain); an `else` holding one block reads "otherwise when …".
124
+ * A clause, for a sentence that holds it; `blockSentence` is the sentence.
125
+ */
126
+ export declare function blockClause(run: TextWhenRun): string;
127
+ /** A wording block as its own sentence: "When variance is below 0, show "…"; otherwise "…"." */
128
+ export declare function blockSentence(run: TextWhenRun): string;
129
+ /** The wording blocks some runs hold, as one clause for the sentence that writes them; undefined when none. */
130
+ export declare function wordingClauses(runs: readonly TextRun[]): string | undefined;
131
+ /** Every wording block in some blocks, outermost first (a chain is one), for the sentences that write them. */
132
+ export declare function wordingBlocks(blocks: readonly TextBlock[]): TextWhenRun[];
@@ -0,0 +1,23 @@
1
+ import { TextVariablePresentation } from '../../../lib/types/common-types.js';
2
+ import { ConditionalRule } from '../conditional-formatting/types.js';
3
+ import { ChangeDiagnostic } from '../changes/diagnostics.js';
4
+ import { ChipColor, RunPresentation } from './blocks.js';
5
+ /**
6
+ * Stored rules as colours, and whether every rule has words (a rule with a
7
+ * style or a condition the words can't say, from the editor, is kept and
8
+ * named in `editorOnly`).
9
+ */
10
+ export declare function readChipColors(rules: readonly ConditionalRule[] | undefined): {
11
+ colors: ChipColor[];
12
+ complete: boolean;
13
+ };
14
+ /** Colours as the rules the rule panel writes for the same choices, on the chip's value. */
15
+ export declare function writeChipColors(colors: readonly ChipColor[], label: string): ConditionalRule[];
16
+ /** Colours a highlight doesn't take, refused with the colours it does. */
17
+ export declare function chipColorProblems(colors: readonly ChipColor[] | undefined, at: string): ChangeDiagnostic[];
18
+ /**
19
+ * A run's presentation as stored (S-9): its colours as rules, or, when they
20
+ * are the colours the chip's rules read as, the chip's rules unchanged (a rule
21
+ * the words can't say is kept).
22
+ */
23
+ export declare function storedRunPresentation(run: RunPresentation, stored: TextVariablePresentation | undefined, label: string): TextVariablePresentation;
@@ -1,15 +1,23 @@
1
- import { TCard, TDashboard, TextCardRichContent } from '../../../lib/types/common-types.js';
1
+ import { DataVariable, DocumentInputDefinition, TCard, TDashboard, TextCardRichContent, TextInline, TextVariablePresentation } from '../../../lib/types/common-types.js';
2
+ import { VariableCatalog } from '../../../lib/dashboard-variables/types.js';
2
3
  import { ChangeDiagnostic } from '../changes/diagnostics.js';
3
- import { TextBlocks } from './blocks.js';
4
+ import { TextBlocks, TextRun, RunPresentation } from './blocks.js';
5
+ export { chipOverVariable } from '../../../lib/dashboard-variables/data-text.js';
6
+ export { storedRunPresentation } from './chip-colors.js';
4
7
  export { hasTextCardRichWords, isTextCardRichContent, sanitizeTextCardUrl } from './rich-content.js';
5
- export type { TextBlock, TextBlocks, TextRun } from './blocks.js';
8
+ export type { ChipColor, LinkRun, RunPresentation, TextBlock, TextBlocks, TextLeafRun, TextRun, TextWhenRun, TextWhenTest } from './blocks.js';
9
+ export { blockClause, blockSentence, isWhenRun, wordingBlocks, wordingClauses } from './blocks.js';
10
+ export { variableSourceWords, variableWords } from './variable-words.js';
6
11
  /**
7
12
  * The one reader and writer of a text card's words for a change (building a
8
13
  * report S-10, BR-D11, BR-D12, SPEC §5.3, §5.4): the outline reads them here,
9
14
  * and the resolver resolves a change to them here. The words are blocks
10
15
  * shaped like the stored rich text (SPEC §2.4), read and written field by
11
- * field; variables are the card's own (S-9); a change keeps every block it
12
- * leaves as it reads (S-8). Pure: no DOM, no Markdown package (V-7).
16
+ * field; a change keeps every block it leaves as it reads (S-8). A run may
17
+ * name any variable the catalog offers at the text's place (data variables
18
+ * DV-D13): the inputs that reach it, the dashboard's data variables and the
19
+ * place's report values; a variable the text already holds keeps its stored
20
+ * chip (S-9). Pure: no DOM, no Markdown package (V-7).
13
21
  */
14
22
  export type TextCardWordsForm = 'rich' | 'legacy_runs' | 'legacy_html' | 'empty';
15
23
  export type TextCardWordsRead = {
@@ -26,7 +34,78 @@ export declare const DYNAMIC_TEXT_MESSAGE = "Its words come from a query. Change
26
34
  /** At most this many characters of text in a change (SPEC §2.2). */
27
35
  export declare const MAX_TEXT_WORDS = 10000;
28
36
  type Inputs = TDashboard['inputs'];
29
- export declare function readTextCardWords(card: TCard, inputs: Inputs): TextCardWordsRead;
37
+ /**
38
+ * The names stored text reads with. With a `catalog`, the place's catalog
39
+ * (`textCatalogAt`): every input the place resolves, controls included. The
40
+ * other fields read a card or line with no place: the dashboard's inputs, a
41
+ * Document's own inputs, and the data variables, by id.
42
+ */
43
+ export type TextNames = {
44
+ catalog?: VariableCatalog;
45
+ inputs?: Inputs;
46
+ documentInputs?: readonly DocumentInputDefinition[];
47
+ variables?: readonly DataVariable[];
48
+ };
49
+ /** Where text sits, for the names a change may add (DV-D29): a text card on a tab, or a Document. */
50
+ export type TextPlace = {
51
+ kind: 'sheet';
52
+ sheetId: string;
53
+ cardId?: string;
54
+ } | {
55
+ kind: 'document';
56
+ sheetId: string;
57
+ };
58
+ /** What a change's runs resolve against: the dashboard as the change leaves it, and the text's place. */
59
+ export type TextWordsContext = {
60
+ dashboard: Pick<TDashboard, 'inputs' | 'sheets' | 'variables' | 'controls'>;
61
+ place: TextPlace;
62
+ };
63
+ /**
64
+ * The catalog of a place, built as the editor builds it (DV-D12, ledger
65
+ * P2-24): a text card's inputs are its target's, resolved by the one input
66
+ * context (dashboard filters and controls, the card's own controls and inline
67
+ * filters, compatibility aliases included); a Document's are its input bar's
68
+ * (the dashboard's inputs that reach it, else its own); every data variable
69
+ * (DV-D3); the place's report values. No value is read.
70
+ */
71
+ export declare function textCatalogAt(context: TextWordsContext): VariableCatalog;
72
+ /**
73
+ * A chip's presentation as a run states it: the fields a change takes, a date
74
+ * format the reader can't read left out (it shows automatic dates), so the
75
+ * words read back are words a change accepts.
76
+ */
77
+ export declare function readablePresentation(stored: TextVariablePresentation | undefined, editorOnly?: Set<string>): RunPresentation | undefined;
78
+ /** What one writer takes besides the rules every run keeps (P3a-04): links, and line breaks between lines. */
79
+ export type RunRules = {
80
+ links: boolean;
81
+ lineBreaks: boolean;
82
+ };
83
+ /**
84
+ * A Document line's or text section's words as runs in their one form, its
85
+ * underline kept (data variables DV-D31). The outline reads Document text
86
+ * here; the Document text change writes it through `writeTextWords`.
87
+ */
88
+ export declare function readTextWords(content: readonly TextInline[], names: TextNames | Inputs): TextRun[];
89
+ export type TextWordsWrite = {
90
+ ok: true;
91
+ content: TextInline[];
92
+ } | {
93
+ ok: false;
94
+ problems: ChangeDiagnostic[];
95
+ };
96
+ /**
97
+ * Runs back to stored text (a Document line or text section), through the
98
+ * one run checker (P3a-04): a variable the text already holds keeps its chip
99
+ * (S-9); any other names an entry at the place, else the change is refused
100
+ * (`variable_unknown`, spec 4.3). Links are refused where the text takes
101
+ * none (a Document, until Phase 4). A line break in a run is how the
102
+ * Document editor stores a new paragraph (ledger P2-19), never inside a block.
103
+ */
104
+ export declare function writeTextWords(runs: readonly TextRun[], stored: readonly TextInline[], context: TextWordsContext & {
105
+ path: string;
106
+ links: boolean;
107
+ }): TextWordsWrite;
108
+ export declare function readTextCardWords(card: TCard, names: TextNames | Inputs): TextCardWordsRead;
30
109
  export type TextWordsResolution = {
31
110
  ok: true;
32
111
  unchanged: true;
@@ -42,7 +121,8 @@ export type TextWordsResolution = {
42
121
  export declare function resolveTextCardWords(request: {
43
122
  text: TextBlocks;
44
123
  card?: TCard;
45
- inputs: Inputs;
124
+ /** The dashboard as the change leaves it, and the card's place: what a run may name (DV-D13). */
125
+ context: TextWordsContext;
46
126
  path: string;
47
127
  /**
48
128
  * Store an older card's words as rich text even when they come back as
@@ -51,5 +131,7 @@ export declare function resolveTextCardWords(request: {
51
131
  */
52
132
  storeAsRichText?: boolean;
53
133
  }): TextWordsResolution;
134
+ /** The wording blocks a text card's content holds, as a clause for the sentence that writes it (P3a-18); undefined when none. */
135
+ export declare function textCardWordingClauses(content: TextCardRichContent | undefined, names?: TextNames | Inputs): string | undefined;
54
136
  /** The first words of rich content, for the sentence that adds or changes a card. */
55
- export declare function textCardExcerpt(content: TextCardRichContent | undefined, inputs?: Inputs): string;
137
+ export declare function textCardExcerpt(content: TextCardRichContent | undefined, names?: TextNames | Inputs): string;