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
@@ -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;
@@ -1,17 +1,85 @@
1
1
  /**
2
- * Shared structured Fast PDF routing and safety policy.
2
+ * Shared PDF policy: the PDF capacity contract and the structured Fast PDF
3
+ * path's own routing limits.
3
4
  *
4
5
  * These values are product policy, not deployment configuration. Keep this
5
6
  * module React-free so browser, app, and renderer adapters can enforce the
6
7
  * same limits at their trust boundaries.
7
8
  */
9
+ /**
10
+ * The PDF capacity contract (PDF capacity contract PC-D1): what one PDF
11
+ * holds, whatever path builds it (the fast path, the rendered path, a
12
+ * Document print, an all-sheets PDF, a delivery). Every enforcement point
13
+ * reads these values; none keeps its own copy (PC-INV-2).
14
+ */
15
+ export declare const PDF_CAPACITY: Readonly<{
16
+ /**
17
+ * Pages in one paginated PDF, a table or a Document, whatever its paper
18
+ * size or orientation (PC-D3, PC-D11). Measured on the worker (plan
19
+ * Phase 0).
20
+ */
21
+ maxPages: 300;
22
+ /**
23
+ * Rows in one table of a PDF, whatever prints it: a Table or Detail Table
24
+ * card, a scheduled table, a Matrix and a Document's Table section (PC-D2,
25
+ * PC-D9). Phase 0 measured 5,000 fitting every path on a 6 GB worker
26
+ * (PC-D15); more needs printing from data (PC-D16).
27
+ */
28
+ maxTableRows: 5000;
29
+ /**
30
+ * Bytes in one PDF file as a recipient gets it, encrypted or not, merged
31
+ * or not (PC-D5): 50 MiB, the delivery guard's size.
32
+ */
33
+ maxFileBytes: 52428800;
34
+ }>;
35
+ /**
36
+ * The structured fast path's own routing limit: the request it posts. Over
37
+ * it, the rendered path prints the table (PC-D14).
38
+ */
8
39
  export declare const FAST_PDF_POLICY: Readonly<{
9
- maxRows: 5000;
10
40
  maxRequestBytes: 2621440;
11
- maxPages: 100;
12
- maxOutputBytes: 52428800;
13
41
  }>;
42
+ /**
43
+ * The fast path's code before the capacity contract's typed codes (below). An
44
+ * older worker still sends it for a row, page or size refusal; readers treat
45
+ * it as a capacity refusal without facts.
46
+ */
14
47
  export declare const PDF_SAFETY_LIMIT_EXCEEDED: "PDF_SAFETY_LIMIT_EXCEEDED";
48
+ /**
49
+ * Why a PDF over the capacity contract was refused (PDF capacity contract
50
+ * PC-D8, PC-INV-3): one code per limit, the same on every path. The first
51
+ * three are also the delivery omission codes, so a delivery reads them
52
+ * straight through. A Document reports its own codes for the same limits
53
+ * (`document_row_limit_exceeded`, `document_page_limit_exceeded`), whose lines
54
+ * read the same.
55
+ */
56
+ export declare const PDF_CAPACITY_REFUSAL_CODES: readonly ["PDF_ROW_LIMIT_EXCEEDED", "PDF_PAGE_LIMIT_EXCEEDED", "PDF_SIZE_LIMIT_EXCEEDED", "PDF_CAPTURE_TOO_TALL"];
57
+ export type PdfCapacityRefusalCode = (typeof PDF_CAPACITY_REFUSAL_CODES)[number];
58
+ export declare function isPdfCapacityRefusalCode(value: unknown): value is PdfCapacityRefusalCode;
59
+ /**
60
+ * A table's numbers cannot fit its PDF columns without clipping: a layout
61
+ * failure, not a capacity one, with its own code.
62
+ */
63
+ export declare const PDF_NUMBER_COLUMN_TOO_WIDE: "PDF_NUMBER_COLUMN_TOO_WIDE";
64
+ /** What a capacity refusal says: the measure and its limit, counts only. */
65
+ export type PdfCapacityFacts = {
66
+ rowCount?: number;
67
+ rowLimit?: number;
68
+ pageCount?: number;
69
+ pageLimit?: number;
70
+ bytes?: number;
71
+ byteLimit?: number;
72
+ /** Logs only. */
73
+ heightPx?: number;
74
+ /** Logs only. */
75
+ heightLimitPx?: number;
76
+ };
77
+ /**
78
+ * The one parser of capacity facts: reads the JSON (or an object) and keeps
79
+ * only whole, non-negative counts of the known keys. Every reader parses with
80
+ * it; every writer writes its output.
81
+ */
82
+ export declare function readPdfCapacityFacts(value: unknown): PdfCapacityFacts;
15
83
  /**
16
84
  * Card types a PDF prints as a table, across pages, in table mode. The one
17
85
  * list every reader uses: the interactive download and export dialog, the
@@ -25,5 +93,5 @@ export declare function isPdfTableCardType(cardType: unknown): cardType is PdfTa
25
93
  export declare function getUtf8ByteLength(value: string): number;
26
94
  export declare function isFastPdfRowCountEligible(rowCount: number): boolean;
27
95
  export declare function isFastPdfRequestSizeEligible(byteLength: number): boolean;
28
- export declare function isFastPdfPageCountEligible(pageCount: number): boolean;
29
- export declare function isFastPdfOutputSizeEligible(byteLength: number): boolean;
96
+ /** A paginated PDF's page count within the contract's page cap (PC-D3). */
97
+ export declare function isPdfPageCountWithinCapacity(pageCount: number): boolean;
@@ -83,6 +83,15 @@ export declare function createPresentationExecutionSnapshot(input: {
83
83
  reportContext: ReportRuntimeContext;
84
84
  resolvedFormats: readonly ResolvedPresentationEntry[];
85
85
  }): PresentationExecutionSnapshot;
86
+ /**
87
+ * The snapshot with `entries` added only where it holds no entry for the same
88
+ * scope and target: its own entries always win, so nothing it already
89
+ * formats changes. For a recurring report whose dashboard now shows cards or
90
+ * columns its saved snapshot never captured; the caller resolves `entries`
91
+ * from the snapshot's own report context, never live preferences (value
92
+ * formatting Plan 05). Returns the snapshot itself when nothing is missing.
93
+ */
94
+ export declare function withMissingPresentationEntries(snapshot: PresentationExecutionSnapshot, entries: readonly ResolvedPresentationEntry[]): PresentationExecutionSnapshot;
86
95
  export declare function findResolvedNumericFormat(input: {
87
96
  snapshot: PresentationExecutionSnapshot;
88
97
  scope: PresentationScope;
package/package.json CHANGED
@@ -5,7 +5,7 @@
5
5
  "email": "support@semaphor.cloud"
6
6
  },
7
7
  "license": "MIT",
8
- "version": "0.1.563",
8
+ "version": "0.1.565",
9
9
  "description": "Fully interactive and customizable dashboards for your apps.",
10
10
  "keywords": [
11
11
  "react",
@@ -127,7 +127,7 @@
127
127
  "build": "node scripts/build.mjs",
128
128
  "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
129
129
  "lint:regressions": "node scripts/lint-regressions.mjs",
130
- "check:guards": "node scripts/card-config-consumers.mjs && node scripts/components-entry-imports.mjs && node scripts/types-entry-imports.mjs && node scripts/card-query-assembly-imports.mjs && node scripts/matrix-conversion-imports.mjs && node scripts/legacy-table-type-references.mjs && node scripts/assistant-chat-imports.mjs && node scripts/filter-model-reads.mjs && node scripts/kpi-figure-reads.mjs && node scripts/layout-engine.mjs",
130
+ "check:guards": "node scripts/card-config-consumers.mjs && node scripts/components-entry-imports.mjs && node scripts/types-entry-imports.mjs && node scripts/card-query-assembly-imports.mjs && node scripts/matrix-conversion-imports.mjs && node scripts/legacy-table-type-references.mjs && node scripts/assistant-chat-imports.mjs && node scripts/filter-model-reads.mjs && node scripts/kpi-figure-reads.mjs && node scripts/layout-engine.mjs && node scripts/text-variable-refs.mjs && node scripts/data-variable-derivation.mjs && node scripts/variable-name-allocation.mjs",
131
131
  "preview": "vite preview",
132
132
  "test": "vitest run",
133
133
  "test:changed": "vitest run --changed",
@@ -1,8 +1,8 @@
1
1
  # Data App SDK Quick Reference
2
2
 
3
- > Frozen: no new work goes into this SDK. A replacement built on the shared
4
- > analytics protocol replaces it in place (semaphor-app
5
- > `docs/implementation-plans/analytics-mcp-and-sdk/PLAN-3-ANALYTICS-SDK.md`).
3
+ > Frozen: no new work goes into this SDK. A false start, to be retired; no
4
+ > replacement SDK is planned for custom looks (they go through the dashboard
5
+ > runtime).
6
6
 
7
7
  Use this file as the public contract quick reference for Data App SDK code.
8
8
  Do not inspect SDK implementation internals to discover these patterns.