react-semaphor 0.1.606 → 0.1.607

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 (149) hide show
  1. package/dist/analytics-protocol/index.js +1 -1
  2. package/dist/appearance-runtime/index.js +1 -1
  3. package/dist/assistant-context/index.js +1 -1
  4. package/dist/assistant-protocol/index.js +1 -1
  5. package/dist/brand-studio/index.js +2 -2
  6. package/dist/briefings/index.js +1 -1
  7. package/dist/chunks/add-to-dashboard-Bu3M9DpP.js +12 -0
  8. package/dist/chunks/appearance-provider-C4lPZcaN.js +613 -0
  9. package/dist/chunks/appearance-runtime-provider-De2VZS4F.js +1 -0
  10. package/dist/chunks/assistant-chat-B7Fngg8U.js +53 -0
  11. package/dist/chunks/attachment-filter-line-wJRB0GSP.js +1 -0
  12. package/dist/chunks/{bookmark-impact-BW30cm5E.js → bookmark-impact-DjrrJomS.js} +1 -1
  13. package/dist/chunks/bookmark-state-x9hJS83D.js +1 -0
  14. package/dist/chunks/{brand-CL5xDiFH.js → brand-DgFcvKJI.js} +1 -1
  15. package/dist/chunks/{card-filter-builder-CzScSOQY.js → card-filter-builder-CvxygmsE.js} +8 -3
  16. package/dist/chunks/check-input-7DVPUuco.js +1 -0
  17. package/dist/chunks/{comparison-window-caption-tguyN24S.js → comparison-window-caption-zUZDe4tL.js} +1 -1
  18. package/dist/chunks/compiler-XErOfUUx.js +1 -0
  19. package/dist/chunks/context-Cwj8Axgd.js +2 -0
  20. package/dist/chunks/currency-presentation-binding-w9WDUk3b.js +1 -0
  21. package/dist/chunks/custom-visual-inputs-D8U98aBz.js +1 -0
  22. package/dist/chunks/{dashboard-Cyhj9EOl.js → dashboard-BEd6i29E.js} +1 -1
  23. package/dist/chunks/{dashboard-briefing-launcher-CyOFddmD.js → dashboard-briefing-launcher-DMDYM9IA.js} +9 -14
  24. package/dist/chunks/{dashboard-controls-DpADfhr0.js → dashboard-controls-5B2vCIjJ.js} +8 -8
  25. package/dist/chunks/{dashboard-json-4xMChR2q.js → dashboard-json-C6r30x-5.js} +1 -1
  26. package/dist/chunks/dashboard-temporal-snapshot-Wki-YACw.js +1 -0
  27. package/dist/chunks/edit-dashboard-visual-F2w7v4iB.js +83 -0
  28. package/dist/chunks/{filter-line-WwUV5JzN.js → filter-line-COFQaF4_.js} +1 -1
  29. package/dist/chunks/filter-reach-preview-BWRGfSmb.js +1 -0
  30. package/dist/chunks/filter-value-text-BSAMEgve.js +1 -0
  31. package/dist/chunks/kpi-trend-rule-BcnKbY7d.js +1 -0
  32. package/dist/chunks/{layout-grid-Dtsioq4h.js → layout-grid-DahW4ClC.js} +1 -1
  33. package/dist/chunks/matrix-analytical-definition-Bd-dXB8q.js +1 -0
  34. package/dist/chunks/{matrix-member-presentation-vVAv-aqg.js → matrix-member-presentation-CfvxPV-i.js} +1 -1
  35. package/dist/chunks/matrix-operation-contract-Cw7U53Ao.js +1 -0
  36. package/dist/chunks/metric-formatting-QDqXfQGY.js +1 -0
  37. package/dist/chunks/{numeric-range-options-C8tr-Bls.js → numeric-range-options-s6i_nDXg.js} +1 -1
  38. package/dist/chunks/{palette-565cA0nh.js → palette-CYvJHSqP.js} +1 -1
  39. package/dist/chunks/pivot-result-contract-expectations-BX5gLcze.js +1 -0
  40. package/dist/chunks/{pivot-result-identity-B0eWVMXg.js → pivot-result-identity-DOISzHU4.js} +1 -1
  41. package/dist/chunks/{raw-temporal-value-BHQ-ldpW.js → raw-temporal-value-Cssny3RJ.js} +1 -1
  42. package/dist/chunks/report-preferences-dialog-BNpB9byP.js +1 -0
  43. package/dist/chunks/{report-runtime-context-Cd1b5pku.js → report-runtime-context-B8HuY0bu.js} +1 -1
  44. package/dist/chunks/resolve-dashboard-input-context-B-0tONJg.js +8 -0
  45. package/dist/chunks/sandbox-host-Drf58_oU.js +197 -0
  46. package/dist/chunks/saved-dashboard-context-dbdbQ5bB.js +1 -0
  47. package/dist/chunks/{selection-filter-compiler-kYsRugss.js → selection-filter-compiler-DK8KkS9g.js} +1 -1
  48. package/dist/chunks/semaphor-ready-indicator-BSFsqsBJ.js +617 -0
  49. package/dist/chunks/set-oJDaJdtI.js +1 -0
  50. package/dist/chunks/slider-DAvAdfMC.js +599 -0
  51. package/dist/chunks/stored-dashboard-DmgJQcyZ.js +1 -0
  52. package/dist/chunks/table-cell-text-2x6r_oHO.js +1 -0
  53. package/dist/chunks/{table-export-sheet-xaczzWZF.js → table-export-sheet-CWqKiQu4.js} +1 -1
  54. package/dist/chunks/{token-types-1vzMWjI-.js → token-types-BSyWn2pb.js} +1 -1
  55. package/dist/chunks/{validators-Dg2kyF4_.js → validators-BPGmPz8-.js} +1 -1
  56. package/dist/chunks/{variable-draft-CRbSYdB6.js → variable-draft-DGA22H2g.js} +1 -1
  57. package/dist/chunks/visual-contract-DQPKg5QW.js +143 -0
  58. package/dist/dashboard/index.js +1 -1
  59. package/dist/dashboard-authoring/index.js +1 -1
  60. package/dist/extensions/index.js +1 -0
  61. package/dist/format-utils/index.js +1 -1
  62. package/dist/index.js +1 -1
  63. package/dist/report-runtime-context/index.js +1 -1
  64. package/dist/style.css +1 -1
  65. package/dist/surfboard/index.js +1 -1
  66. package/dist/types/components/assistant/assistant-store.d.ts +19 -0
  67. package/dist/types/components/assistant/use-assistant.d.ts +4 -0
  68. package/dist/types/components/visual/data-table/hooks/use-data-table-logic.d.ts +2 -3
  69. package/dist/types/components/visual/data-table/table-cell-text.d.ts +93 -0
  70. package/dist/types/components/visual/data-table/types/data-table.d.ts +0 -1
  71. package/dist/types/extensions.d.ts +2 -0
  72. package/dist/types/index.js +1 -1
  73. package/dist/types/lib/charts/types.d.ts +3 -1
  74. package/dist/types/lib/dashboard/semantic-dataset-references.d.ts +0 -2
  75. package/dist/types/lib/matrix-table/matrix-card-adapter.d.ts +12 -12
  76. package/dist/types/lib/matrix-table/matrix-delivery.d.ts +25 -25
  77. package/dist/types/lib/stores/dashboard-store.d.ts +33 -2
  78. package/dist/types/lib/stores/editor-store.d.ts +8 -0
  79. package/dist/types/lib/types/common-types.d.ts +3 -0
  80. package/dist/types/lib/utils/card-definition.d.ts +12 -12
  81. package/dist/types/lib/utils/card-type-change.d.ts +9 -0
  82. package/dist/types/shared/analytics-protocol/analytics-base-schemas.d.ts +6 -6
  83. package/dist/types/shared/analytics-protocol/execution-input-schemas.d.ts +10 -10
  84. package/dist/types/shared/analytics-protocol/matrix-definition-contract.d.ts +248 -248
  85. package/dist/types/shared/analytics-protocol/matrix-operation-contract.d.ts +10 -10
  86. package/dist/types/shared/analytics-protocol/matrix-operation-request.d.ts +8 -8
  87. package/dist/types/shared/analytics-protocol/matrix-window-contract.d.ts +2 -2
  88. package/dist/types/shared/assistant-protocol/context.d.ts +26 -26
  89. package/dist/types/shared/assistant-protocol/parts.d.ts +4 -0
  90. package/dist/types/shared/assistant-protocol/request.d.ts +2 -1
  91. package/dist/types/shared/dashboard-authoring/card-data-source/card-base.d.ts +16 -6
  92. package/dist/types/shared/dashboard-authoring/card-settings/custom-visual-write.d.ts +44 -0
  93. package/dist/types/shared/dashboard-authoring/card-settings/index.d.ts +1 -0
  94. package/dist/types/shared/dashboard-authoring/changes/card-query-part.d.ts +1 -0
  95. package/dist/types/shared/dashboard-authoring/changes/card-types.d.ts +2 -2
  96. package/dist/types/shared/dashboard-authoring/changes/custom-visual-change.d.ts +57 -0
  97. package/dist/types/shared/dashboard-authoring/changes/dashboard-change.d.ts +61 -54
  98. package/dist/types/shared/dashboard-authoring/changes/diagnostics.d.ts +5 -1
  99. package/dist/types/shared/dashboard-authoring/changes/read-card-query.d.ts +5 -1
  100. package/dist/types/shared/dashboard-authoring/changes/resolve-dashboard-changes.d.ts +10 -0
  101. package/dist/types/shared/dashboard-authoring/conditional-formatting/schema.d.ts +60 -60
  102. package/dist/types/shared/dashboard-authoring/control-execution-contract.d.ts +4 -4
  103. package/dist/types/shared/dashboard-authoring/matrix-delivery.d.ts +48 -48
  104. package/dist/types/shared/dashboard-authoring/operations/operation-sentences.d.ts +8 -2
  105. package/dist/types/shared/dashboard-authoring/operations/operation-types.d.ts +11 -0
  106. package/dist/types/shared/dashboard-authoring/outline/outline-dashboard.d.ts +7 -0
  107. package/dist/types/shared/extensions/check-audits.d.ts +30 -0
  108. package/dist/types/shared/extensions/check-findings.d.ts +46 -0
  109. package/dist/types/shared/extensions/check-input.d.ts +23 -0
  110. package/dist/types/shared/extensions/check-renders.d.ts +44 -0
  111. package/dist/types/shared/extensions/check-runner.d.ts +19 -0
  112. package/dist/types/shared/extensions/index.d.ts +17 -0
  113. package/dist/types/shared/extensions/read-document.d.ts +18 -0
  114. package/dist/types/shared/extensions/sandbox-host.d.ts +63 -0
  115. package/dist/types/shared/extensions/saved-refs.d.ts +33 -0
  116. package/dist/types/shared/extensions/script-policy.d.ts +11 -0
  117. package/dist/types/shared/extensions/types.d.ts +186 -0
  118. package/dist/types/shared/extensions/visual-contract.d.ts +36 -0
  119. package/dist/types/shared/extensions/visual-payload.d.ts +75 -0
  120. package/dist/types/shared/extensions/visual-theme.d.ts +21 -0
  121. package/dist/types/shared/format-utils/formatters/number-formatter.d.ts +13 -6
  122. package/dist/types/shared/format-utils/matrix-continuation.d.ts +2 -2
  123. package/dist/types/shared/format-utils/matrix-export-presentation.d.ts +24 -24
  124. package/dist/types/shared/usage-events/details.d.ts +4 -4
  125. package/dist/types/shared/usage-events/envelope.d.ts +2 -2
  126. package/dist/usage-events/index.js +1 -1
  127. package/package.json +7 -2
  128. package/dist/chunks/add-to-dashboard-CEmZUf9o.js +0 -12
  129. package/dist/chunks/appearance-provider-fIhJSX6y.js +0 -613
  130. package/dist/chunks/appearance-runtime-provider-Bx8H-moR.js +0 -1
  131. package/dist/chunks/assistant-chat-SBKSrrEA.js +0 -51
  132. package/dist/chunks/attachment-filter-line-C_zHMhGh.js +0 -1
  133. package/dist/chunks/bookmark-state-DScd31KT.js +0 -1
  134. package/dist/chunks/context-CntvtZwC.js +0 -2
  135. package/dist/chunks/dashboard-temporal-snapshot-w3SMiPKj.js +0 -1
  136. package/dist/chunks/edit-dashboard-visual-DlvY7au4.js +0 -73
  137. package/dist/chunks/filter-reach-preview-DAEIyrEG.js +0 -1
  138. package/dist/chunks/filter-value-text-DqTHe_vu.js +0 -1
  139. package/dist/chunks/kpi-trend-rule-N1Xkwe_u.js +0 -1
  140. package/dist/chunks/matrix-analytical-definition-5T-2euHZ.js +0 -1
  141. package/dist/chunks/matrix-operation-contract-CWvcEsQ0.js +0 -1
  142. package/dist/chunks/pivot-result-contract-expectations-BNWhS8mv.js +0 -1
  143. package/dist/chunks/report-preferences-dialog-B2ZGPS9t.js +0 -1
  144. package/dist/chunks/resolve-dashboard-input-context-SlAAe4GF.js +0 -8
  145. package/dist/chunks/saved-dashboard-context-Bc2SVDr-.js +0 -1
  146. package/dist/chunks/semaphor-ready-indicator-Bj-cjkz-.js +0 -612
  147. package/dist/chunks/set-CACXVM2A.js +0 -1
  148. package/dist/chunks/slider-CWze9OEM.js +0 -4
  149. package/dist/chunks/stored-dashboard-CcNdU-mG.js +0 -1
@@ -0,0 +1,46 @@
1
+ import { CheckFinding } from './types.js';
2
+ /** One render of a visual in the checks: where, how it ended, and what the audits found (spec §3.9). */
3
+ export type RenderOutcome = {
4
+ where: {
5
+ brand: string;
6
+ mode: 'light' | 'dark';
7
+ size: {
8
+ width: number;
9
+ height: number;
10
+ };
11
+ };
12
+ state: 'ready' | 'no_hello' | 'not_ready' | 'threw' | 'blank' | 'reported_error';
13
+ detail?: string;
14
+ /** Requests the frame's CSP blocked. */
15
+ blocked: {
16
+ url: string;
17
+ directive: string;
18
+ }[];
19
+ /** `auditFrame`'s result, after a ready render. */
20
+ frame?: {
21
+ textCount: number;
22
+ brandFont: number;
23
+ worst: {
24
+ text: string;
25
+ ratio: number;
26
+ }[];
27
+ };
28
+ /** `auditOverflow`'s result, after a ready render. */
29
+ overflow?: {
30
+ pageScroll: number;
31
+ clipped: string[];
32
+ };
33
+ };
34
+ /**
35
+ * The fix list from the renders (EXT-D17). Errors are what a viewer would
36
+ * only ever see as the table: it throws, never says ready, draws nothing,
37
+ * or reaches for the network. Warnings are a working visual's flaws: text
38
+ * below 4.5:1, content cut off at the smallest size, the brand font not
39
+ * used. One finding per kind, the first render that shows it.
40
+ */
41
+ export declare function renderFindings(outcomes: readonly RenderOutcome[], smallest: {
42
+ width: number;
43
+ height: number;
44
+ }): CheckFinding[];
45
+ /** Warnings read from the code itself: colours written into it instead of the theme's (EXT-D17). */
46
+ export declare function sourceFindings(html: string): CheckFinding[];
@@ -0,0 +1,23 @@
1
+ import { TCard } from '../../lib/types/common-types.js';
2
+ import { CustomVisualCardSpec, SettingValue } from './types.js';
3
+ import { ContractField } from './visual-contract.js';
4
+ /**
5
+ * What a visual's render checks run on (review P5D-04): its HTML, the card's
6
+ * fields, a slot moved from its place (by the name of its field) and its
7
+ * settings. The editor's check and the save's are the same check because
8
+ * both build it here; the editor's result belongs to this whole input, so a
9
+ * slot or setting changed since is checked again.
10
+ */
11
+ export type ExtensionCheckInput = {
12
+ html: string;
13
+ fields: ContractField[];
14
+ slots?: Record<string, string>;
15
+ settings?: Record<string, SettingValue>;
16
+ };
17
+ type CheckedCard = Pick<TCard, 'config' | 'sql'> & {
18
+ customVisual?: CustomVisualCardSpec;
19
+ };
20
+ export declare function extensionCheckInput(card: CheckedCard, html: string): ExtensionCheckInput;
21
+ /** One key per check input: the editor shows a result only for the input it was run on. */
22
+ export declare function extensionCheckKey(input: ExtensionCheckInput): string;
23
+ export {};
@@ -0,0 +1,44 @@
1
+ import { AppearanceSpec } from '../../lib/appearance/types.js';
2
+ import { ContractField } from './visual-contract.js';
3
+ import { SettingValue, VisualManifest, VisualPayload, VisualTheme } from './types.js';
4
+ /** The sizes a visual is checked at (EXT-D16), the smallest first: cut-off content is looked for there. */
5
+ export declare const CHECK_SIZES: readonly {
6
+ width: number;
7
+ height: number;
8
+ }[];
9
+ export type CheckRender = {
10
+ where: {
11
+ brand: string;
12
+ mode: 'light' | 'dark';
13
+ size: {
14
+ width: number;
15
+ height: number;
16
+ };
17
+ };
18
+ theme: VisualTheme;
19
+ payload: VisualPayload;
20
+ };
21
+ /**
22
+ * What the checks render (custom visuals Plan 1, Phase 4; spec §3.9): the
23
+ * organization's brand when given and the default, light and dark, at each
24
+ * size, each with its theme and a payload of sample rows, built by the
25
+ * viewers' own theme and payload owners. Pure and server-safe; the worker
26
+ * renders them.
27
+ */
28
+ export declare function buildCheckRenders(input: {
29
+ manifest: VisualManifest;
30
+ /** The card's fields, for a realistic sample; absent, one generic field per slot. */
31
+ fields?: readonly ContractField[];
32
+ /** The card's own choices: a slot's field by its name in `fields`, and settings (P4R-03). */
33
+ slots?: Readonly<Record<string, string>>;
34
+ settings?: Readonly<Record<string, SettingValue>>;
35
+ organizationAppearance?: AppearanceSpec | null;
36
+ }): CheckRender[];
37
+ /**
38
+ * A sample of what a visual receives for a card's fields (EXT-D12): the
39
+ * payload's own shape, rows keyed by slot id, built by the payload owner
40
+ * over a default manifest whose `many` slots take the card's dimensions
41
+ * (`category`, `category_2`…) and measures (`value`, `value_2`…), so the
42
+ * sample shows how ids repeat. Values are illustrative, not the card's data.
43
+ */
44
+ export declare function sampleVisualPayload(fields: readonly ContractField[]): Pick<VisualPayload, 'fields' | 'rows'>;
@@ -0,0 +1,19 @@
1
+ import { RenderOutcome } from './check-findings.js';
2
+ import { VisualPayload, VisualTheme } from './types.js';
3
+ /**
4
+ * One render of a visual for the checks (custom visuals Plan 1, Phase 4):
5
+ * the viewers' own host (`createSandboxHost`, EXT-D9), with its frame, CSP,
6
+ * bridge and watchdogs, in a box of the given size. It settles when the
7
+ * visual is ready or has failed, and leaves the frame in place so the
8
+ * caller can audit it. Browser only, with no top-level DOM use: the PDF
9
+ * worker bundles it into the page it checks in (its entry sets the global).
10
+ */
11
+ export declare function runExtensionCheck(input: {
12
+ html: string;
13
+ theme: VisualTheme;
14
+ payload: VisualPayload;
15
+ size: {
16
+ width: number;
17
+ height: number;
18
+ };
19
+ }): Promise<Pick<RenderOutcome, 'state' | 'detail' | 'blocked'>>;
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Custom visuals 2.0 (Plan 1): server-safe entry, `react-semaphor/extensions`.
3
+ * Nothing here touches the DOM when imported. `runExtensionCheck` and the
4
+ * audits use it when called, in a browser page (the PDF worker's checks).
5
+ */
6
+ export * from './types.js';
7
+ export { readExtensionDocument, isAllowedScript, isHexColor, isThemeColorName, THEME_COLOR_NAMES } from './read-document.js';
8
+ export { visualContractText, cardVisualFields, sampleVisualRows, type ContractField } from './visual-contract.js';
9
+ export { extensionCheckInput, extensionCheckKey, type ExtensionCheckInput } from './check-input.js';
10
+ export { toVisualPayload, readVisualFields, resolveVisualSlots, type VisualResult, type VisualFieldCandidate } from './visual-payload.js';
11
+ export { withSavedCustomVisuals, type SavedCustomVisual } from './saved-refs.js';
12
+ export { toVisualTheme, resolveColorSetting, contrastRatio } from './visual-theme.js';
13
+ export { auditFrame, auditOverflow, lintSource } from './check-audits.js';
14
+ export { renderFindings, sourceFindings, type RenderOutcome } from './check-findings.js';
15
+ export { runExtensionCheck } from './check-runner.js';
16
+ export { buildSrcdoc, VISUAL_SCRIPT_ORIGINS, type SandboxState, type FallbackReason } from './sandbox-host.js';
17
+ export { buildCheckRenders, CHECK_SIZES, sampleVisualPayload, type CheckRender } from './check-renders.js';
@@ -0,0 +1,18 @@
1
+ import { ExtensionDocumentReading, ThemeColorName } from './types.js';
2
+ /**
3
+ * The one reader of a visual's HTML (PLAN-1-SPEC.md §3.1): the manifest, the
4
+ * size in UTF-8 bytes, the contract version and the static checks. The
5
+ * editor's paste, the save step and the MCP resolver all call it, so they
6
+ * agree on what is valid. Every finding here is an error (EXT-D17). The
7
+ * content hash is the server's (`prepareExtensionDrafts`), since a browser
8
+ * can't hash synchronously.
9
+ */
10
+ export declare function readExtensionDocument(html: string, expect: {
11
+ kind: 'visual';
12
+ }): ExtensionDocumentReading;
13
+ /** The theme colour names a colour setting may name, in the order the editor lists them. */
14
+ export declare const THEME_COLOR_NAMES: readonly ThemeColorName[];
15
+ export declare function isThemeColorName(value: string): value is ThemeColorName;
16
+ export declare function isHexColor(value: string): boolean;
17
+ /** An allowed CDN, over https, with an exact version in the path (`pkg@1.2.3`, or cdnjs `/libs/<name>/<version>/`). */
18
+ export declare function isAllowedScript(src: string): boolean;
@@ -0,0 +1,63 @@
1
+ import { VisualPayload, VisualTheme } from './types.js';
2
+ import { VISUAL_SCRIPT_ORIGINS } from './script-policy.js';
3
+ export type FallbackReason = 'no_hello' | 'not_ready' | 'threw' | 'blank' | 'reported_error';
4
+ export type SandboxState = {
5
+ status: 'loading';
6
+ } | {
7
+ status: 'ready';
8
+ drawnAt: number;
9
+ redrawing?: true;
10
+ } | {
11
+ status: 'failed';
12
+ reason: FallbackReason;
13
+ detail?: string;
14
+ redrawing?: true;
15
+ };
16
+ export type SandboxHost = {
17
+ update(next: {
18
+ payload?: VisualPayload;
19
+ theme?: VisualTheme;
20
+ }): void;
21
+ destroy(): void;
22
+ };
23
+ export type SandboxHostOptions = {
24
+ html: string;
25
+ theme: VisualTheme;
26
+ payload: VisualPayload;
27
+ onState: (state: SandboxState) => void;
28
+ timeouts?: {
29
+ hello?: number;
30
+ ready?: number;
31
+ };
32
+ /** Called with blocked requests (the CSP), for checks and diagnostics. */
33
+ onBlocked?: (blocked: {
34
+ url: string;
35
+ directive: string;
36
+ }) => void;
37
+ };
38
+ export { VISUAL_SCRIPT_ORIGINS };
39
+ /**
40
+ * The sandbox for one visual (PLAN-1-SPEC.md §3.5, EXT-D9). Framework-free
41
+ * and browser only. It owns the frame (`sandbox="allow-scripts"`,
42
+ * `srcdoc`), the CSP, the bridge, fonts, colour scheme, watchdogs and the
43
+ * blank check, and reports one state (review P5C-01, the state table in
44
+ * `sandbox-host.test.ts`):
45
+ *
46
+ * - `loading` until the first drawing settles; the frame must say hello,
47
+ * then draw within the watchdogs.
48
+ * - Every payload is a drawing with its own number and watchdog. While one
49
+ * runs, the last outcome stays (`ready` or `failed`) marked `redrawing`,
50
+ * so the screen keeps what it showed and a print waits for the new one.
51
+ * - A drawing settles on its own `ready` (drawn, or blank: failed), on an
52
+ * error while it runs, or on its watchdog (failed). A `ready` for a
53
+ * replaced payload settles nothing.
54
+ * - A theme isn't a drawing (its colours restyle what is drawn), but an
55
+ * error thrown in a theme callback fails. An error once nothing is
56
+ * drawing (a hover handler, say) keeps what was drawn.
57
+ *
58
+ * Failures are never final: the next drawing that draws recovers. The caller
59
+ * recreates the host when the HTML changes.
60
+ */
61
+ export declare function createSandboxHost(container: HTMLElement, options: SandboxHostOptions): SandboxHost;
62
+ /** The document the frame loads: CSP, theme variables and the bridge, then the visual's own HTML. */
63
+ export declare function buildSrcdoc(html: string, theme: VisualTheme): string;
@@ -0,0 +1,33 @@
1
+ import { TCard, TDashboard } from '../../lib/types/common-types.js';
2
+ /** What a save made of one card's draft (EXT-D3): the version it now names. */
3
+ export type SavedCustomVisual = {
4
+ cardId: string;
5
+ extensionId: string;
6
+ version: number;
7
+ };
8
+ /**
9
+ * The dashboard with each saved draft replaced by its reference (EXT-D3,
10
+ * EXT-INV-1). The server calls it to build the document it stores; the
11
+ * editor calls it after a save so its next save names the same version
12
+ * instead of making a new extension. A card whose draft changed after the
13
+ * save was sent (its HTML differs from `sent`) keeps its draft. Returns the
14
+ * input when nothing changed.
15
+ */
16
+ export declare function withSavedCustomVisuals<T extends Pick<TDashboard, 'sheets'>>(dashboard: T, input: {
17
+ saved: readonly SavedCustomVisual[];
18
+ sent?: Pick<TDashboard, 'sheets'>;
19
+ }): T;
20
+ /**
21
+ * A frame as Copy puts it on the clipboard (review P5A-03): each saved
22
+ * visual becomes a draft of its HTML, and an unsaved edit keeps its draft
23
+ * without the visual it edits, each keeping its slots and settings, so the
24
+ * paste works on any dashboard. There it is that dashboard's own new visual,
25
+ * saved and checked like any new code (CV2-D10: a visual belongs to one
26
+ * dashboard). `load` reads a version's HTML; a failure is the caller's.
27
+ */
28
+ export declare function withCustomVisualDrafts<F extends {
29
+ cards: TCard[];
30
+ }>(frame: F, load: (ref: {
31
+ extensionId: string;
32
+ version: number;
33
+ }) => Promise<string>): Promise<F>;
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Where a visual's scripts may load from (EXT-INV-2, review P5F-02): the one
3
+ * list the save's reader validates against (`isAllowedScript`), the frame's
4
+ * CSP enforces (`buildSrcdoc`) and the contract tells authors, so acceptance
5
+ * at save and enforcement at run time can't drift apart. Server-safe.
6
+ */
7
+ export declare const VISUAL_SCRIPT_ORIGINS: readonly ["https://cdn.jsdelivr.net", "https://cdnjs.cloudflare.com", "https://unpkg.com"];
8
+ /** The allowed hosts, for the reader's check. */
9
+ export declare const VISUAL_SCRIPT_HOSTS: ReadonlySet<string>;
10
+ /** The hosts in words, for messages and the contract: "a, b or c". */
11
+ export declare function visualScriptHostsText(format?: (host: string) => string): string;
@@ -0,0 +1,186 @@
1
+ import { MeasureCanonicalFormat } from '../format-utils/types/format-types.js';
2
+ /**
3
+ * Shapes of custom visuals 2.0 (Plan 1, PLAN-1-SPEC.md §2). Server-safe: no
4
+ * React, no DOM. The card stores a reference to a saved extension version, or
5
+ * a draft while the document is unsaved; the visual's manifest declares its
6
+ * slots and settings; the payload and theme are what the sandboxed document
7
+ * receives.
8
+ */
9
+ /** The contract version this package speaks. */
10
+ export declare const VISUAL_CONTRACT_VERSION: 2;
11
+ /** A visual's HTML is at most this many UTF-8 bytes (EXT-D18). */
12
+ export declare const MAX_EXTENSION_HTML_BYTES: number;
13
+ /** At most this many drafts are saved at once (EXT-D21). */
14
+ export declare const MAX_EXTENSION_DRAFTS_PER_SAVE = 8;
15
+ export type SlotId = string;
16
+ export type SettingId = string;
17
+ export type SettingValue = boolean | number | string;
18
+ /** A field of the card's own result: a config field by id, or a result column by key. */
19
+ export type FieldRef = {
20
+ fieldId: string;
21
+ } | {
22
+ column: string;
23
+ };
24
+ /**
25
+ * `TCard.customVisual`, set when `type` is `'customVisual'` (EXT-D2).
26
+ * Saved: `extensionId` and `version`, no `draft`. Unsaved: `draft`, plus
27
+ * `extensionId` when it edits an existing visual, never `version`.
28
+ */
29
+ export type CustomVisualCardSpec = {
30
+ extensionId?: string;
31
+ version?: number;
32
+ draft?: {
33
+ html: string;
34
+ };
35
+ /** Only the slots the author or agent reassigned (EXT-D6). */
36
+ slots?: Record<SlotId, FieldRef>;
37
+ /** Only the settings changed from the manifest's defaults. */
38
+ settings?: Record<SettingId, SettingValue>;
39
+ };
40
+ export type ThemeColorName = 'palette-1' | 'palette-2' | 'palette-3' | 'palette-4' | 'palette-5' | 'palette-6' | 'palette-7' | 'palette-8' | 'primary' | 'accent' | 'positive' | 'negative' | 'warning' | 'selection' | 'fg' | 'muted-fg';
41
+ export type SettingDefinition = {
42
+ type: 'boolean';
43
+ label: string;
44
+ default: boolean;
45
+ } | {
46
+ type: 'number';
47
+ label: string;
48
+ default: number;
49
+ min?: number;
50
+ max?: number;
51
+ step?: number;
52
+ } | {
53
+ type: 'string';
54
+ label: string;
55
+ default: string;
56
+ maxLength?: number;
57
+ } | {
58
+ type: 'select';
59
+ label: string;
60
+ default: string;
61
+ options: {
62
+ value: string;
63
+ label: string;
64
+ }[];
65
+ } | {
66
+ type: 'color';
67
+ label: string;
68
+ default: string;
69
+ };
70
+ export type VisualSlot = {
71
+ id: SlotId;
72
+ label: string;
73
+ kind: 'dimension' | 'measure';
74
+ optional?: boolean;
75
+ /** Takes every remaining field of its kind, in order. At most one per kind. */
76
+ many?: boolean;
77
+ };
78
+ /** The first `<script type="application/json" id="semaphor-visual">` of the document. */
79
+ export type VisualManifest = {
80
+ name: string;
81
+ contract: typeof VISUAL_CONTRACT_VERSION;
82
+ kind?: 'visual';
83
+ slots: VisualSlot[];
84
+ settings?: Record<SettingId, SettingDefinition>;
85
+ minSize?: {
86
+ width: number;
87
+ height: number;
88
+ };
89
+ };
90
+ export type PayloadFieldType = 'string' | 'number' | 'date' | 'boolean';
91
+ /**
92
+ * How the frame formats a number for one field (`semaphor.format`): the
93
+ * field's own format in format-utils' canonical form, written by the same
94
+ * formatter as the cells' `text` (review P5A-01).
95
+ */
96
+ export type FieldNumberFormat = MeasureCanonicalFormat;
97
+ export type PayloadField = {
98
+ /** The slot id, or `${slot}_2`, `${slot}_3`… for the extra fields of a `many` slot. */
99
+ id: string;
100
+ slot: SlotId;
101
+ label: string;
102
+ type: PayloadFieldType;
103
+ kind: 'dimension' | 'measure';
104
+ /** For `semaphor.format(fieldId, n)` in the frame; absent for text and date dimensions. */
105
+ numberFormat?: FieldNumberFormat;
106
+ /**
107
+ * A measure's rows add up (review P5D-01): `true` for a sum or a count,
108
+ * `false` for an average, a ratio, a distinct count, a median or a table
109
+ * calculation, absent when unknown (a SQL column). A visual that adds rows
110
+ * (a Sankey's nodes, a Waterfall's running total) refuses `false`.
111
+ */
112
+ adds?: boolean;
113
+ };
114
+ export type PayloadCell = {
115
+ value: string | number | boolean | null;
116
+ text: string;
117
+ };
118
+ export type VisualPayload = {
119
+ contract: typeof VISUAL_CONTRACT_VERSION;
120
+ kind: 'visual';
121
+ fields: PayloadField[];
122
+ rows: Record<string, PayloadCell>[];
123
+ /** Per measure field, when the card's result carries totals; otherwise empty. */
124
+ totals: Record<string, PayloadCell>;
125
+ truncated: boolean;
126
+ /** Every manifest setting, defaults filled in; `color` settings as `#rrggbb` for this brand and mode. */
127
+ settings: Record<SettingId, SettingValue>;
128
+ size: {
129
+ width: number;
130
+ height: number;
131
+ };
132
+ locale: string;
133
+ printing: boolean;
134
+ };
135
+ export type VisualFontFace = {
136
+ family: string;
137
+ weight: number;
138
+ style: 'normal' | 'italic';
139
+ src: string;
140
+ };
141
+ export type VisualTheme = {
142
+ mode: 'light' | 'dark';
143
+ /** Public variables set on the frame's `:root` (`--sv-*`). */
144
+ vars: Record<string, string>;
145
+ /** Named colours, `#rrggbb` where the brand gave one, for colour settings and `semaphor.theme`. */
146
+ colors: Record<ThemeColorName | 'bg' | 'page' | 'muted' | 'border' | 'primary-fg' | 'grid' | 'axis' | 'axis-label' | 'legend' | 'halo', string>;
147
+ palette: string[];
148
+ paletteFg: string[];
149
+ sequential: {
150
+ steps: string[];
151
+ text: string[];
152
+ };
153
+ font: {
154
+ family: string;
155
+ size: number;
156
+ };
157
+ radius: number;
158
+ fontFaces: VisualFontFace[];
159
+ };
160
+ export type CheckCode = 'too_large' | 'manifest_missing' | 'manifest_invalid' | 'contract_unsupported' | 'kind_unsupported' | 'script_not_allowed' | 'throws' | 'never_ready' | 'blank' | 'network_blocked' | 'low_contrast' | 'cut_off' | 'font_not_applied' | 'hardcoded_color' | 'not_checked';
161
+ export type CheckFinding = {
162
+ code: CheckCode;
163
+ severity: 'error' | 'warning';
164
+ /** One sentence an author or agent can act on. Never names the product. */
165
+ message: string;
166
+ /** What to change, in the contract's words. */
167
+ fix?: string;
168
+ where?: {
169
+ brand?: string;
170
+ mode?: 'light' | 'dark';
171
+ size?: {
172
+ width: number;
173
+ height: number;
174
+ };
175
+ };
176
+ };
177
+ export type ExtensionDocumentReading = {
178
+ ok: true;
179
+ manifest: VisualManifest;
180
+ contract: typeof VISUAL_CONTRACT_VERSION;
181
+ sizeBytes: number;
182
+ findings: CheckFinding[];
183
+ } | {
184
+ ok: false;
185
+ findings: CheckFinding[];
186
+ };
@@ -0,0 +1,36 @@
1
+ import { TCard } from '../../lib/types/common-types.js';
2
+ /**
3
+ * The custom visual contract (version 2) as one text (PLAN-1-SPEC.md §3.2):
4
+ * what the editor's Copy prompt copies and what
5
+ * `semaphor_get_extension_contract` returns. One owner, two callers. It
6
+ * never names the product. `card` adds the card's own fields.
7
+ */
8
+ export declare function visualContractText(card?: {
9
+ fields: readonly {
10
+ name: string;
11
+ kind: 'dimension' | 'measure';
12
+ type: string;
13
+ }[];
14
+ }): string;
15
+ /** One of a card's fields as the contract lists it. */
16
+ export type ContractField = {
17
+ name: string;
18
+ kind: 'dimension' | 'measure';
19
+ type: 'string' | 'number' | 'date' | 'boolean';
20
+ };
21
+ /**
22
+ * A config card's fields as the contract lists them, from its shelves and
23
+ * without running it: Rows are dimensions, Values measures, in the card's
24
+ * order (EXT-D6). A SQL card's columns are known only when it runs, so it
25
+ * lists none; the editor reads them from its result (`readVisualFields`).
26
+ */
27
+ export declare function cardVisualFields(card: Pick<TCard, 'config' | 'sql'>): ContractField[];
28
+ /**
29
+ * Three illustrative rows for a card's fields, by field name: the shape of
30
+ * the values a visual receives, not the card's data (semaphor_analyze with
31
+ * fromCard returns that).
32
+ */
33
+ export declare function sampleVisualRows(fields: readonly ContractField[]): Record<string, {
34
+ value: unknown;
35
+ text: string;
36
+ }>[];
@@ -0,0 +1,75 @@
1
+ import { ComparisonMetadataMap } from '../../lib/types/query-types.js';
2
+ import { TCard } from '../../lib/types/common-types.js';
3
+ import { SemaphorResultColumn } from '../analytics-protocol/contracts.js';
4
+ import { QueryColumnKeyMap } from '../format-utils/pivot-result-identity.js';
5
+ import { TableTextContext } from '../../components/visual/data-table/table-cell-text.js';
6
+ import { FieldRef, PayloadFieldType, SlotId, VisualManifest, VisualPayload, VisualTheme } from './types.js';
7
+ export type VisualResult = {
8
+ records: readonly Record<string, unknown>[];
9
+ columns?: readonly SemaphorResultColumn[];
10
+ columnKeyMap?: QueryColumnKeyMap;
11
+ /** Totals keyed by result column key, when the card's result has them. */
12
+ totals?: Record<string, unknown>;
13
+ truncated?: boolean;
14
+ /** The card's comparison outputs, when it has any: names the columns a comparison adds. */
15
+ comparisonMetadata?: ComparisonMetadataMap;
16
+ };
17
+ /**
18
+ * What a custom visual receives (PLAN-1-SPEC.md §3.3, EXT-D7). Slots are
19
+ * filled by position, the way charts read a card (EXT-D6): the card's
20
+ * dimensions fill dimension slots and its measures fill measure slots, in
21
+ * the card's order, after the card's own overrides. Every `text` is what
22
+ * the card's own table shows in that cell (`createTableCellText`, review
23
+ * P5C-02), in the viewer's `table` context when given, never written by the
24
+ * visual. Pure and deterministic. `unfilled` lists required slots with no field.
25
+ */
26
+ export declare function toVisualPayload(input: {
27
+ /** The result's `renderCard` (the card queried with, with its live model formats). */
28
+ card: TCard;
29
+ result: VisualResult;
30
+ manifest: VisualManifest;
31
+ theme: VisualTheme;
32
+ size: {
33
+ width: number;
34
+ height: number;
35
+ };
36
+ locale: string;
37
+ printing: boolean;
38
+ /** Where the card is shown: the viewer's preferences, currencies and time zone (`useTableTextContext`). */
39
+ table?: TableTextContext;
40
+ }): {
41
+ payload: VisualPayload;
42
+ unfilled: SlotId[];
43
+ };
44
+ /** One of the card's fields a slot can take (EXT-D6). */
45
+ export type VisualFieldCandidate = {
46
+ /** The result column's key. */
47
+ key: string;
48
+ /** How an override names it: a config field by id, a SQL column by key. */
49
+ ref: FieldRef;
50
+ label: string;
51
+ kind: 'dimension' | 'measure';
52
+ type: PayloadFieldType;
53
+ };
54
+ /**
55
+ * The card's fields a visual can draw, by kind, in the card's order: what
56
+ * slots fill from, what the slot pickers offer and what the copied prompt
57
+ * lists. A config card's roles come from its shelves, as the charts read
58
+ * them; a SQL card's from the result columns' own role and type (positional
59
+ * chart roles would take every column after the first as a value, P1-01).
60
+ */
61
+ export declare function readVisualFields(card: TCard, result: VisualResult): VisualFieldCandidate[];
62
+ /**
63
+ * Which of the card's fields fill each slot (EXT-D6): the card's overrides
64
+ * first, then by position within each kind; a `many` slot takes the rest of
65
+ * its kind. `unfilled` lists required slots with no field.
66
+ */
67
+ export declare function resolveVisualSlots(input: {
68
+ card: TCard;
69
+ result: VisualResult;
70
+ manifest: VisualManifest;
71
+ }): {
72
+ candidates: VisualFieldCandidate[];
73
+ assigned: Map<SlotId, string[]>;
74
+ unfilled: SlotId[];
75
+ };
@@ -0,0 +1,21 @@
1
+ import { CompiledAppearance } from '../../lib/appearance/types.js';
2
+ import { VisualFontFace, VisualTheme } from './types.js';
3
+ /**
4
+ * The theme a custom visual wears (PLAN-1-SPEC.md §3.4, EXT-D8): the public
5
+ * `--sv-*` variables, named colours for colour settings, the palette, the
6
+ * sequential scale and fonts, from the dashboard's compiled appearance.
7
+ * Every text colour reaches 4.5:1 on the card and the page; where the
8
+ * brand's own colour doesn't, it is moved until it does (the bench's rules,
9
+ * kept here as the one owner). Brand Studio is unchanged.
10
+ */
11
+ export declare function toVisualTheme(appearance: CompiledAppearance, fontFaces?: VisualFontFace[]): VisualTheme;
12
+ /** A colour setting's value for this theme: a theme colour name or `#rrggbb` as `#rrggbb`. */
13
+ export declare function resolveColorSetting(value: string, theme: VisualTheme): string;
14
+ /**
15
+ * The brand font's faces the frame must load: the host page's `@font-face`
16
+ * rules for the family, with absolute URLs (browser only). The app serves
17
+ * `/fonts/*` with CORS, since the frame's origin is opaque.
18
+ */
19
+ export declare function collectFontFaces(doc: Document, family: string): VisualFontFace[];
20
+ /** WCAG contrast ratio of two `#rrggbb` colours. */
21
+ export declare function contrastRatio(a: string, b: string): number;
@@ -42,11 +42,7 @@ export declare function formatNumericCanonical(value: number | ExactNumericValue
42
42
  * through `formatNumericCanonical`, durations through the duration formatter.
43
43
  */
44
44
  export declare function formatMeasureCanonical(value: number | ExactNumericValue | null | undefined, format: MeasureCanonicalFormat): string;
45
- /**
46
- * Format a number value based on ColumnSettings.numberFormat
47
- * Used for export formatting
48
- */
49
- export declare function formatNumberWithColumnSettings(value: number | ExactNumericValue | null | undefined, numberFormat: {
45
+ type ColumnSettingsNumberFormat = {
50
46
  style?: ColumnNumberStyle;
51
47
  currency?: string;
52
48
  locale?: string;
@@ -60,7 +56,18 @@ export declare function formatNumberWithColumnSettings(value: number | ExactNume
60
56
  prefix?: string;
61
57
  suffix?: string;
62
58
  duration?: ColumnDurationFormat;
63
- } | undefined, defaultLocale?: string): string;
59
+ };
60
+ /**
61
+ * A column's settings number format as the canonical format it is written
62
+ * with: the one mapping, so anything that formats the same column (a custom
63
+ * visual's frame, P5C-02) writes the same text.
64
+ */
65
+ export declare function columnSettingsNumberCanonical(numberFormat: ColumnSettingsNumberFormat | undefined, defaultLocale?: string): MeasureCanonicalFormat;
66
+ /**
67
+ * Format a number value based on ColumnSettings.numberFormat
68
+ * Used for export formatting
69
+ */
70
+ export declare function formatNumberWithColumnSettings(value: number | ExactNumericValue | null | undefined, numberFormat: ColumnSettingsNumberFormat | undefined, defaultLocale?: string): string;
64
71
  /**
65
72
  * Legacy wrapper for backward compatibility with existing code
66
73
  * @deprecated Use formatNumber, formatCurrency, or formatPercent directly
@@ -19,14 +19,14 @@ export declare const matrixBatchInputSchema: z.ZodObject<{
19
19
  sequence: z.ZodEffects<z.ZodNumber, number, number>;
20
20
  deadlineAt: z.ZodNumber;
21
21
  }, "strip", z.ZodTypeAny, {
22
- sequence: number;
23
22
  acquisition: "continuation";
24
23
  jobId: string;
24
+ sequence: number;
25
25
  deadlineAt: number;
26
26
  }, {
27
- sequence: number;
28
27
  acquisition: "continuation";
29
28
  jobId: string;
29
+ sequence: number;
30
30
  deadlineAt: number;
31
31
  }>;
32
32
  export type MatrixBatchInput = z.infer<typeof matrixBatchInputSchema>;