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
@@ -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;
@@ -1,12 +1,25 @@
1
- import { TextCardRichContent } from '../../../lib/types/common-types.js';
1
+ import { LinkUrlPart, TextLink, TextCardRichContent, WordingTest, WordingTestKind } from '../../../lib/types/common-types.js';
2
2
  /**
3
3
  * A text card's stored rich content (`preferences.textVisualOptions.richContent`):
4
4
  * the shape check and the link rule, pure and server-safe, so the renderer
5
5
  * (`src/lib/dashboard-inputs/text-card-rich-content.ts`), the editor and the
6
6
  * words owner (building a report SPEC §1) read them from one place.
7
7
  */
8
+ /** Every wording test a stored block may hold, in the order the editor offers them (P3a-10). */
9
+ export declare const WORDING_TESTS: readonly WordingTestKind[];
10
+ /**
11
+ * Whether a test is complete (ledger P3a-41): `equals` compares with a value,
12
+ * `below` and `above` with a number. The editor stores a block only with a
13
+ * complete test, and the run checker refuses an incomplete one, by this one
14
+ * rule. Readers stay tolerant: an incomplete stored test holds nothing.
15
+ */
16
+ export declare function isCompleteWordingTest(test: Pick<WordingTest, 'is' | 'value'> | undefined): boolean;
8
17
  export declare function isTextCardRichContent(value: unknown): value is TextCardRichContent;
9
- /** Whether the content holds any words: a paragraph of only spacing holds none (V-8). */
18
+ /**
19
+ * Whether the content holds any words: a paragraph of only spacing holds
20
+ * none (V-8). A wording block holds words when either branch does, so a card
21
+ * holding only a block is not taken for an empty one (P3a-01).
22
+ */
10
23
  export declare function hasTextCardRichWords(value: unknown): boolean;
11
24
  /**
12
25
  * The editor's link rule. Mirrors the DOMPurify default URL policy: http(s),
@@ -15,4 +28,19 @@ export declare function hasTextCardRichWords(value: unknown): boolean;
15
28
  * to link, or '' to drop the link and keep its words.
16
29
  */
17
30
  export declare function sanitizeTextCardUrl(rawUrl: string): string;
18
- export declare function isDashboardInputExportKey(value: unknown): value is 'label' | 'value' | 'start' | 'end' | 'range';
31
+ /** A link's address as parts: a literal address is one text part (DV-D24). */
32
+ export declare function linkUrlParts(url: TextLink['url'] | undefined): LinkUrlPart[];
33
+ /** Whether a link's address holds a variable (DV-D24). */
34
+ export declare function linkUrlHasVariables(url: TextLink['url'] | undefined): url is LinkUrlPart[];
35
+ /**
36
+ * An address as stored (DV-D24): literal when it holds no variable, else its
37
+ * parts with neighbouring words joined and empty words dropped.
38
+ */
39
+ export declare function storedLinkUrl(parts: readonly LinkUrlPart[]): TextLink['url'];
40
+ /**
41
+ * The editor's link rule over an address with variables (DV-D24): each
42
+ * variable stands as a value, so the address itself must be one the rule
43
+ * takes; a value is URL-encoded when it is filled in, so it can't change
44
+ * the scheme. '' when the rule refuses it.
45
+ */
46
+ export declare function sanitizeLinkUrlTemplate(url: TextLink['url']): string;
@@ -0,0 +1,8 @@
1
+ import { DataVariable } from '../../../lib/types/common-types.js';
2
+ /** The dataset, table or connection the query reads, as the source inventory names it. */
3
+ export declare function variableSourceWords(variable: DataVariable): string | undefined;
4
+ /**
5
+ * The question a variable answers, in words. A SQL variable's words name its
6
+ * query, never its text (DV-INV-3).
7
+ */
8
+ export declare function variableWords(variable: DataVariable): string;
@@ -0,0 +1,125 @@
1
+ import { DataVariable, TDashboard, TextVariablePresentation } from '../../lib/types/common-types.js';
2
+ import { AggregateFunction, DataSource, Field, FilterGroup } from '../../lib/types/explorer-types.js';
3
+ import { MetricComparisonConfig } from '../analytics-protocol/metric-comparison.js';
4
+ /**
5
+ * The only value, the first by an order, a list, one aggregate function, or
6
+ * an aggregate calculation's own value (`calculation`: the field owns its
7
+ * aggregate, so none is put over it; ledger P1b-21).
8
+ */
9
+ export type VariableGetChoice = 'only' | 'first' | 'list' | 'calculation' | AggregateFunction;
10
+ export type VariableDraft = {
11
+ id: string;
12
+ /** As typed; empty takes the field's name on save. */
13
+ name: string;
14
+ label?: string;
15
+ mode: 'data' | 'sql';
16
+ dataSource?: DataSource;
17
+ /** SQL mode: the connection the query runs on. */
18
+ connectionId?: string;
19
+ sql: string;
20
+ /** The field the variable reads (its catalog field, before any shelf role). */
21
+ field?: Field;
22
+ get: VariableGetChoice;
23
+ sortField?: Field;
24
+ sortDirection: 'asc' | 'desc';
25
+ listLimit?: number;
26
+ listSeparator?: string;
27
+ conditions?: FilterGroup | null;
28
+ /** Calculated fields the author made here, as a card keeps them. */
29
+ calculatedFields?: Field[];
30
+ presentation?: TextVariablePresentation;
31
+ emptyText?: string;
32
+ /**
33
+ * "Compare with" (data variables DV-D22, P3b-02): the period before or the
34
+ * same period last year, as `toStoredComparison` writes a card measure's.
35
+ * Written only where `variableTakesComparison` offers it.
36
+ */
37
+ comparison?: MetricComparisonConfig;
38
+ };
39
+ export type VariableGetOption = {
40
+ value: VariableGetChoice;
41
+ label: string;
42
+ hint: string;
43
+ };
44
+ /** A calculation that is its own aggregate (`SUM({sold})`): the one owner's answer (P1b-21). */
45
+ export declare function ownsItsAggregate(field: Field | undefined): boolean;
46
+ /** The Get choices a field offers (DV-D5); an aggregate calculation offers its own value, no aggregate over it. */
47
+ export declare function variableGetOptions(field: Field | undefined): VariableGetOption[];
48
+ /** Default Get for a field (DV-D5): `only` for text and dates, the natural aggregate for numbers. */
49
+ export declare function defaultVariableGet(field: Field): VariableGetChoice;
50
+ export declare function isAggregateGet(get: VariableGetChoice): get is AggregateFunction | 'calculation';
51
+ /**
52
+ * Whether a variable compares with an earlier period (DV-D22): an aggregate
53
+ * whose value is a number (a count, or a numeric field's total, average,
54
+ * lowest or highest, or a numeric calculation), on a dataset rather than
55
+ * SQL. Text and date aggregates, and the only, first and list values, don't.
56
+ */
57
+ export declare function variableTakesComparison(draft: Pick<VariableDraft, 'mode' | 'field' | 'get'>): boolean;
58
+ /** A fresh variable id. Card and variable ids share one namespace (DV-D35); `checkDataVariable` refuses a clash. */
59
+ export declare function newVariableId(): string;
60
+ export declare function newVariableDraft(): VariableDraft;
61
+ /**
62
+ * Every key a shelf field can carry, classed (ledger P3b-18, H-18): `catalog`
63
+ * is the field itself, kept when the dialog reopens a variable; `shelf` is a
64
+ * setting of the measure, column or sort that the draft states on its own
65
+ * (its role, aggregate and their provenance, a comparison, a sort's
66
+ * direction, a table calculation). A new key fails the type check here until
67
+ * it is classed.
68
+ */
69
+ export declare const SHELF_FIELD_KEYS: {
70
+ readonly id: "catalog";
71
+ readonly name: "catalog";
72
+ readonly label: "catalog";
73
+ readonly derivedLabel: "catalog";
74
+ readonly alias: "catalog";
75
+ readonly sourceField: "catalog";
76
+ readonly source: "catalog";
77
+ readonly qualifiedFieldName: "catalog";
78
+ readonly dataType: "catalog";
79
+ readonly nativeDataType: "catalog";
80
+ readonly description: "catalog";
81
+ readonly qualifiedEntityName: "catalog";
82
+ readonly dateFormat: "catalog";
83
+ readonly customFormat: "catalog";
84
+ readonly granularity: "catalog";
85
+ readonly entityId: "catalog";
86
+ readonly entityName: "catalog";
87
+ readonly entityType: "catalog";
88
+ readonly expression: "catalog";
89
+ readonly calculatedFormula: "catalog";
90
+ readonly derivedField: "catalog";
91
+ readonly format: "catalog";
92
+ readonly semanticTemporalPresentation: "catalog";
93
+ readonly calculationRepresentation: "catalog";
94
+ readonly calculatedFieldOrigin: "catalog";
95
+ readonly labelOrigin: "catalog";
96
+ readonly formatOrigin: "catalog";
97
+ readonly fieldScope: "catalog";
98
+ readonly timeDrillPath: "catalog";
99
+ readonly aliasTemplate: "catalog";
100
+ readonly valueAliases: "catalog";
101
+ readonly isPreAggregated: "catalog";
102
+ readonly role: "shelf";
103
+ readonly aggregate: "shelf";
104
+ readonly aggregateOrigin: "shelf";
105
+ readonly semanticAggregate: "shelf";
106
+ readonly effectiveAggregate: "shelf";
107
+ readonly aggregateSource: "shelf";
108
+ readonly comparison: "shelf";
109
+ readonly comparisonPolarity: "shelf";
110
+ readonly semanticComparisonPolarity: "shelf";
111
+ readonly parameters: "shelf";
112
+ readonly direction: "shelf";
113
+ };
114
+ /** The dialog's draft for a saved variable. */
115
+ export declare function draftFromVariable(variable: DataVariable): VariableDraft;
116
+ /**
117
+ * A name text can write, free in the dashboard's one namespace of inputs
118
+ * and variables (DV-D18): the typed name, else the field's, with a counter
119
+ * when taken. Validation of the result stays `checkDataVariable`'s.
120
+ */
121
+ export declare function defaultVariableName(dashboard: Pick<TDashboard, 'inputs' | 'sheets' | 'variables'>, draft: Pick<VariableDraft, 'id' | 'name' | 'field' | 'mode'> & Pick<Partial<VariableDraft>, 'label'>): string;
122
+ /** The variable the draft saves: its query as the shelves write a card's. */
123
+ export declare function variableFromDraft(draft: VariableDraft, dashboard: Pick<TDashboard, 'inputs' | 'sheets' | 'variables'>): DataVariable;
124
+ /** What the draft still needs before it can be saved, in the author's words. */
125
+ export declare function draftBlocker(draft: VariableDraft): string | undefined;
@@ -0,0 +1,24 @@
1
+ import { DataVariable } from '../../lib/types/common-types.js';
2
+ import { OutlineCardSource } from './changes/read-card-query.js';
3
+ /**
4
+ * Whether an agent may change a data variable (data variables DV-D13,
5
+ * DV-D33), decided as a card's editability is: a variable on a semantic
6
+ * dataset is changed here; one written in SQL needs SQL access, which the
7
+ * resolver records as a requirement checked again at apply; one on a table or
8
+ * view is changed in the editor (the parity backlog, `editorOnly`). One rule,
9
+ * read by the outline and the resolver (ledger P2-16).
10
+ */
11
+ export type VariableEditability = {
12
+ editable: true;
13
+ source: OutlineCardSource | undefined;
14
+ } | {
15
+ editable: false;
16
+ reason: 'needs_sql_access' | 'table_source';
17
+ message: string;
18
+ source: OutlineCardSource | undefined;
19
+ };
20
+ /** The source a data variable reads, through the one target list (DV-INV-2). */
21
+ export declare function readVariableSource(variable: DataVariable): OutlineCardSource | undefined;
22
+ export declare function readVariableEditability(variable: DataVariable, options: {
23
+ sql: boolean;
24
+ }): VariableEditability;
@@ -0,0 +1,39 @@
1
+ import { DocumentDefinition, TDashboard, TextInline, VariableRef } from '../../lib/types/common-types.js';
2
+ import { VariablePlace, VariableReference } from '../../lib/dashboard-variables/types.js';
3
+ import { ScopedDashboardInputTarget } from './dashboard-input-scope.js';
4
+ type StoredInline = TextInline | {
5
+ type: 'text' | 'variable';
6
+ ref?: unknown;
7
+ };
8
+ /**
9
+ * Every ref in stored text, a wording block's test and both its branches and
10
+ * a link's words and address included (DV-D25, P3a-02, P4-06): the one
11
+ * collector of text's refs, read by demand, usage and the Document editor
12
+ * (ledger P4-22); any other stored shape holds none (DV-INV-12: text never
13
+ * fails a page).
14
+ */
15
+ export declare function storedTextRefs(inlines: readonly StoredInline[] | unknown): VariableRef[];
16
+ /**
17
+ * Every reference to a variable (inputs and report values included) in text
18
+ * at `place`, or at every place: a tab's text cards, a Document's header,
19
+ * footer and text sections. Memoized per dashboard object.
20
+ */
21
+ export declare function collectVariableReferences(dashboard: Pick<TDashboard, 'sheets'>, place?: VariablePlace): VariableReference[];
22
+ /** The places that reference a data variable, each once. */
23
+ export declare function listDataVariablePlaces(dashboard: Pick<TDashboard, 'sheets'>, variableId: string): VariablePlace[];
24
+ /** The data variables text at a place references, by id, each once. */
25
+ export declare function listReferencedDataVariableIds(dashboard: Pick<TDashboard, 'sheets'>, place: VariablePlace): string[];
26
+ /** Where a Document shows an input: its header, its footer and how many text sections. */
27
+ export declare function documentInputTextUsage(document: DocumentDefinition, inputId: string): {
28
+ header: boolean;
29
+ footer: boolean;
30
+ textSections: number;
31
+ };
32
+ /**
33
+ * Where a scope is checked for a data variable when no place is in hand
34
+ * (DV-D35): at each place text uses it, as the runtime checks it there; a
35
+ * variable used nowhere as if on every dashboard tab, so it can be bound
36
+ * before it is placed.
37
+ */
38
+ export declare function listVariableScopeTargets(dashboard: Pick<TDashboard, 'sheets'>, variableId: string): ScopedDashboardInputTarget[];
39
+ export {};
@@ -24,7 +24,7 @@ export type DocumentPrintLayout = {
24
24
  pageCount: number | null;
25
25
  };
26
26
  /** Every reason a Document cannot print (C1). Lowercase, as the page and the worker report them. */
27
- export declare const DOCUMENT_PRINT_FAILURE_CODES: readonly ["document_matrix_too_large", "document_matrix_unavailable", "document_matrix_too_wide", "document_kpi_value_overflow", "print_inputs_not_captured", "document_section_setup", "document_input_missing", "document_section_query_failed", "document_table_completeness_unverified", "document_row_limit_exceeded", "document_section_render_failed", "document_page_overflow", "document_sheet_not_found", "document_print_timed_out"];
27
+ export declare const DOCUMENT_PRINT_FAILURE_CODES: readonly ["document_matrix_too_large", "document_matrix_unavailable", "document_matrix_too_wide", "document_kpi_value_overflow", "print_inputs_not_captured", "document_section_setup", "document_input_missing", "document_section_query_failed", "document_table_completeness_unverified", "document_row_limit_exceeded", "document_section_render_failed", "document_page_overflow", "document_sheet_not_found", "document_print_timed_out", "document_page_limit_exceeded"];
28
28
  export type DocumentPrintFailureCode = (typeof DOCUMENT_PRINT_FAILURE_CODES)[number];
29
29
  export declare function isDocumentPrintFailureCode(value: unknown): value is DocumentPrintFailureCode;
30
30
  /**
@@ -57,8 +57,10 @@ export type DocumentPrintFailureFacts = {
57
57
  measuredRowCount?: number;
58
58
  /** W1 only. */
59
59
  totalRowCount?: number;
60
- /** W1 only. */
60
+ /** W1, and the page limit. */
61
61
  pageCount?: number;
62
+ /** The page limit only. More than 0. */
63
+ pageLimit?: number;
62
64
  };
63
65
  /** What a source passes to the attribute writer (C1). */
64
66
  export type DocumentPrintFailure = {
@@ -23,6 +23,7 @@ export * from './matrix-print.js';
23
23
  export { fromSemanticFormat } from './semantic-format.js';
24
24
  export type * from './table-structure.js';
25
25
  export * from './pdf-export-policy.js';
26
+ export * from './pdf-capacity-lines.js';
26
27
  export * from './pdf-delivery.js';
27
28
  export * from './document-print.js';
28
29
  export * from './numeric-presentation.js';
@@ -0,0 +1,17 @@
1
+ import { PDF_NUMBER_COLUMN_TOO_WIDE, PDF_SAFETY_LIMIT_EXCEEDED, PdfCapacityRefusalCode } from './pdf-export-policy.js';
2
+ export type PdfRefusalLineCode = PdfCapacityRefusalCode | typeof PDF_SAFETY_LIMIT_EXCEEDED | typeof PDF_NUMBER_COLUMN_TOO_WIDE;
3
+ /**
4
+ * `facts` are the refusal's (parsed here, so any reader may pass them raw);
5
+ * a missing count reads as "more than the limit". `subject` names what is
6
+ * refused: a Document section's title for its rows ("Register" has …), or
7
+ * "This document" for its pages; it defaults to the table or the PDF.
8
+ * `dataExport` says whether what is refused can also be exported as CSV or
9
+ * Excel: a table can; a Document, a dashboard or a sheet can't, so its line
10
+ * offers a filter only (Document PDF reliability C2). Every caller decides.
11
+ */
12
+ export declare function pdfCapacityRefusalLine(input: {
13
+ code: PdfRefusalLineCode;
14
+ facts?: unknown;
15
+ subject?: string;
16
+ dataExport: boolean;
17
+ }): string;
@@ -1,6 +1,13 @@
1
+ /**
2
+ * A PDF the server refused at a limit or for a layout it cannot print: final,
3
+ * never retried another way. `message` is the customer line the app wrote.
4
+ */
1
5
  export declare class PdfSafetyLimitError extends Error {
2
- readonly code: "PDF_SAFETY_LIMIT_EXCEEDED";
6
+ readonly code: string;
7
+ constructor(message: string, code?: string);
3
8
  }
9
+ /** A refusal the server decided, whatever path made the PDF (PDF capacity contract PC-INV-3). */
10
+ export declare function isPdfRefusalCode(code: unknown): code is string;
4
11
  export declare function readPdfErrorResponse(response: Response): Promise<{
5
12
  message: string;
6
13
  code?: string;