react-semaphor 0.1.606 → 0.1.608
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.
- package/dist/analytics-protocol/index.js +1 -1
- package/dist/appearance-runtime/index.js +1 -1
- package/dist/assistant-context/index.js +1 -1
- package/dist/assistant-protocol/index.js +1 -1
- package/dist/brand-studio/index.js +2 -2
- package/dist/briefings/index.js +1 -1
- package/dist/chunks/add-to-dashboard-Bu3M9DpP.js +12 -0
- package/dist/chunks/appearance-provider-BBYTKSjL.js +613 -0
- package/dist/chunks/appearance-runtime-provider-De2VZS4F.js +1 -0
- package/dist/chunks/assistant-chat-x3NCrm5n.js +53 -0
- package/dist/chunks/attachment-filter-line-ClTS4GvQ.js +1 -0
- package/dist/chunks/{bookmark-impact-BW30cm5E.js → bookmark-impact-xCmo8x3V.js} +1 -1
- package/dist/chunks/bookmark-state-BmbBu1th.js +1 -0
- package/dist/chunks/{brand-CL5xDiFH.js → brand-3m_qSMyC.js} +1 -1
- package/dist/chunks/card-filter-builder-CM3SZ4kO.js +11 -0
- package/dist/chunks/check-input-C7S2sNzB.js +151 -0
- package/dist/chunks/{comparison-window-caption-tguyN24S.js → comparison-window-caption-WzGsqv4n.js} +1 -1
- package/dist/chunks/compiler-XErOfUUx.js +1 -0
- package/dist/chunks/context-Cwj8Axgd.js +2 -0
- package/dist/chunks/currency-presentation-binding-s4PlA3Wu.js +1 -0
- package/dist/chunks/custom-visual-inputs-CUtxCe4T.js +1 -0
- package/dist/chunks/custom-visual-write-CH-k-4HE.js +1 -0
- package/dist/chunks/{dashboard-Cyhj9EOl.js → dashboard-BwuurlUI.js} +1 -1
- package/dist/chunks/{dashboard-briefing-launcher-CyOFddmD.js → dashboard-briefing-launcher-CX7mCnPi.js} +5 -5
- package/dist/chunks/{dashboard-controls-DpADfhr0.js → dashboard-controls-Bwjy9G1i.js} +8 -8
- package/dist/chunks/{dashboard-json-4xMChR2q.js → dashboard-json-B9lK28i0.js} +1 -1
- package/dist/chunks/dashboard-temporal-snapshot-CcndP6CF.js +1 -0
- package/dist/chunks/edit-dashboard-visual-BF3mfrWf.js +103 -0
- package/dist/chunks/{filter-line-WwUV5JzN.js → filter-line-W-qQAjke.js} +1 -1
- package/dist/chunks/filter-reach-preview-DSH_k8AJ.js +1 -0
- package/dist/chunks/{filter-value-text-DqTHe_vu.js → filter-value-text-DQwYZHz0.js} +1 -1
- package/dist/chunks/kpi-trend-rule-DDbguInc.js +1 -0
- package/dist/chunks/{layout-grid-Dtsioq4h.js → layout-grid-Bx0jBVXj.js} +1 -1
- package/dist/chunks/matrix-analytical-definition-jn075ooo.js +1 -0
- package/dist/chunks/{matrix-member-presentation-vVAv-aqg.js → matrix-member-presentation-Chz6uGYz.js} +1 -1
- package/dist/chunks/matrix-operation-contract-DceN49RX.js +1 -0
- package/dist/chunks/metric-formatting-DILSVxLq.js +1 -0
- package/dist/chunks/{numeric-range-options-C8tr-Bls.js → numeric-range-options-Drc1EZ6H.js} +1 -1
- package/dist/chunks/{palette-565cA0nh.js → palette-CZJ4ZCY9.js} +1 -1
- package/dist/chunks/pivot-result-contract-expectations-D_ane7I2.js +1 -0
- package/dist/chunks/{pivot-result-identity-B0eWVMXg.js → pivot-result-identity-DRhVJMsF.js} +1 -1
- package/dist/chunks/{raw-temporal-value-BHQ-ldpW.js → raw-temporal-value-B4Md6Xfb.js} +1 -1
- package/dist/chunks/report-preferences-dialog-EQNoTych.js +1 -0
- package/dist/chunks/{report-runtime-context-Cd1b5pku.js → report-runtime-context-CkxgMKr6.js} +1 -1
- package/dist/chunks/resolve-dashboard-input-context-B5yUS9ZM.js +8 -0
- package/dist/chunks/sandbox-host-WJXxpvz7.js +197 -0
- package/dist/chunks/saved-dashboard-context-DQlA4Mg0.js +1 -0
- package/dist/chunks/{selection-filter-compiler-kYsRugss.js → selection-filter-compiler-BxtEEB6Z.js} +1 -1
- package/dist/chunks/semaphor-ready-indicator-Cq3C2SNo.js +622 -0
- package/dist/chunks/set-wWdhgHSh.js +1 -0
- package/dist/chunks/slider-C4jUvJtd.js +599 -0
- package/dist/chunks/stored-dashboard-1x0q2cNx.js +1 -0
- package/dist/chunks/table-cell-text-DFHUGeG6.js +1 -0
- package/dist/chunks/{table-export-sheet-xaczzWZF.js → table-export-sheet-CthBUHu4.js} +1 -1
- package/dist/chunks/{token-types-1vzMWjI-.js → token-types-BM0mpZce.js} +1 -1
- package/dist/chunks/{validators-Dg2kyF4_.js → validators-U8IL8djK.js} +1 -1
- package/dist/chunks/{variable-draft-CRbSYdB6.js → variable-draft-CwX-b6Fs.js} +1 -1
- package/dist/dashboard/index.js +1 -1
- package/dist/dashboard-authoring/index.js +1 -1
- package/dist/extensions/index.js +1 -0
- package/dist/format-utils/index.js +1 -1
- package/dist/index.js +1 -1
- package/dist/report-runtime-context/index.js +1 -1
- package/dist/style.css +1 -1
- package/dist/surfboard/index.js +1 -1
- package/dist/types/components/assistant/assistant-store.d.ts +19 -0
- package/dist/types/components/assistant/use-assistant.d.ts +4 -0
- package/dist/types/components/visual/data-table/hooks/use-data-table-logic.d.ts +2 -3
- package/dist/types/components/visual/data-table/table-cell-text.d.ts +93 -0
- package/dist/types/components/visual/data-table/types/data-table.d.ts +0 -1
- package/dist/types/extensions.d.ts +2 -0
- package/dist/types/index.js +1 -1
- package/dist/types/lib/charts/types.d.ts +3 -1
- package/dist/types/lib/dashboard/semantic-dataset-references.d.ts +0 -2
- package/dist/types/lib/matrix-table/matrix-card-adapter.d.ts +12 -12
- package/dist/types/lib/matrix-table/matrix-delivery.d.ts +25 -25
- package/dist/types/lib/stores/dashboard-store.d.ts +33 -2
- package/dist/types/lib/stores/editor-store.d.ts +8 -0
- package/dist/types/lib/types/common-types.d.ts +3 -0
- package/dist/types/lib/utils/card-definition.d.ts +12 -12
- package/dist/types/lib/utils/card-type-change.d.ts +9 -0
- package/dist/types/shared/analytics-protocol/analytics-base-schemas.d.ts +6 -6
- package/dist/types/shared/analytics-protocol/execution-input-schemas.d.ts +10 -10
- package/dist/types/shared/analytics-protocol/matrix-definition-contract.d.ts +248 -248
- package/dist/types/shared/analytics-protocol/matrix-operation-contract.d.ts +10 -10
- package/dist/types/shared/analytics-protocol/matrix-operation-request.d.ts +8 -8
- package/dist/types/shared/analytics-protocol/matrix-window-contract.d.ts +2 -2
- package/dist/types/shared/assistant-protocol/context.d.ts +26 -26
- package/dist/types/shared/assistant-protocol/parts.d.ts +4 -0
- package/dist/types/shared/assistant-protocol/request.d.ts +2 -1
- package/dist/types/shared/dashboard-authoring/card-data-source/card-base.d.ts +16 -6
- package/dist/types/shared/dashboard-authoring/card-settings/custom-visual-write.d.ts +50 -0
- package/dist/types/shared/dashboard-authoring/card-settings/index.d.ts +1 -0
- package/dist/types/shared/dashboard-authoring/changes/card-query-part.d.ts +1 -0
- package/dist/types/shared/dashboard-authoring/changes/card-types.d.ts +2 -2
- package/dist/types/shared/dashboard-authoring/changes/custom-visual-change.d.ts +57 -0
- package/dist/types/shared/dashboard-authoring/changes/dashboard-change.d.ts +61 -54
- package/dist/types/shared/dashboard-authoring/changes/diagnostics.d.ts +5 -1
- package/dist/types/shared/dashboard-authoring/changes/read-card-query.d.ts +5 -1
- package/dist/types/shared/dashboard-authoring/changes/resolve-dashboard-changes.d.ts +10 -0
- package/dist/types/shared/dashboard-authoring/conditional-formatting/schema.d.ts +60 -60
- package/dist/types/shared/dashboard-authoring/control-execution-contract.d.ts +4 -4
- package/dist/types/shared/dashboard-authoring/matrix-delivery.d.ts +48 -48
- package/dist/types/shared/dashboard-authoring/operations/operation-sentences.d.ts +8 -2
- package/dist/types/shared/dashboard-authoring/operations/operation-types.d.ts +11 -0
- package/dist/types/shared/dashboard-authoring/outline/outline-dashboard.d.ts +7 -0
- package/dist/types/shared/dashboard-authoring/table-sheet-shape.d.ts +8 -0
- package/dist/types/shared/extensions/check-audits.d.ts +30 -0
- package/dist/types/shared/extensions/check-findings.d.ts +46 -0
- package/dist/types/shared/extensions/check-input.d.ts +23 -0
- package/dist/types/shared/extensions/check-renders.d.ts +44 -0
- package/dist/types/shared/extensions/check-runner.d.ts +19 -0
- package/dist/types/shared/extensions/index.d.ts +17 -0
- package/dist/types/shared/extensions/read-document.d.ts +18 -0
- package/dist/types/shared/extensions/sandbox-host.d.ts +63 -0
- package/dist/types/shared/extensions/saved-refs.d.ts +33 -0
- package/dist/types/shared/extensions/script-policy.d.ts +11 -0
- package/dist/types/shared/extensions/types.d.ts +186 -0
- package/dist/types/shared/extensions/visual-contract.d.ts +38 -0
- package/dist/types/shared/extensions/visual-payload.d.ts +75 -0
- package/dist/types/shared/extensions/visual-theme.d.ts +21 -0
- package/dist/types/shared/format-utils/formatters/number-formatter.d.ts +13 -6
- package/dist/types/shared/format-utils/matrix-continuation.d.ts +2 -2
- package/dist/types/shared/format-utils/matrix-export-presentation.d.ts +24 -24
- package/dist/types/shared/usage-events/details.d.ts +4 -4
- package/dist/types/shared/usage-events/envelope.d.ts +2 -2
- package/dist/usage-events/index.js +1 -1
- package/package.json +7 -2
- package/dist/chunks/add-to-dashboard-CEmZUf9o.js +0 -12
- package/dist/chunks/appearance-provider-fIhJSX6y.js +0 -613
- package/dist/chunks/appearance-runtime-provider-Bx8H-moR.js +0 -1
- package/dist/chunks/assistant-chat-SBKSrrEA.js +0 -51
- package/dist/chunks/attachment-filter-line-C_zHMhGh.js +0 -1
- package/dist/chunks/bookmark-state-DScd31KT.js +0 -1
- package/dist/chunks/card-filter-builder-CzScSOQY.js +0 -11
- package/dist/chunks/context-CntvtZwC.js +0 -2
- package/dist/chunks/dashboard-temporal-snapshot-w3SMiPKj.js +0 -1
- package/dist/chunks/edit-dashboard-visual-DlvY7au4.js +0 -73
- package/dist/chunks/filter-reach-preview-DAEIyrEG.js +0 -1
- package/dist/chunks/kpi-trend-rule-N1Xkwe_u.js +0 -1
- package/dist/chunks/matrix-analytical-definition-5T-2euHZ.js +0 -1
- package/dist/chunks/matrix-operation-contract-CWvcEsQ0.js +0 -1
- package/dist/chunks/pivot-result-contract-expectations-BNWhS8mv.js +0 -1
- package/dist/chunks/report-preferences-dialog-B2ZGPS9t.js +0 -1
- package/dist/chunks/resolve-dashboard-input-context-SlAAe4GF.js +0 -8
- package/dist/chunks/saved-dashboard-context-Bc2SVDr-.js +0 -1
- package/dist/chunks/semaphor-ready-indicator-Bj-cjkz-.js +0 -612
- package/dist/chunks/set-CACXVM2A.js +0 -1
- package/dist/chunks/slider-CWze9OEM.js +0 -4
- package/dist/chunks/stored-dashboard-CcNdU-mG.js +0 -1
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The checks' audits (custom visuals Plan 1, Phase 4; spec §3.9), moved here
|
|
3
|
+
* from the bench (`scripts/custom-visuals-bench`), which now imports them:
|
|
4
|
+
* one copy. `auditFrame` and `auditOverflow` run inside a rendered visual's
|
|
5
|
+
* frame; `lintSource` reads the HTML. `checkFindings` turns their results
|
|
6
|
+
* into the fix list (EXT-D17).
|
|
7
|
+
*/
|
|
8
|
+
export declare function auditFrame({ cardBg, brandFamily }: {
|
|
9
|
+
cardBg: any;
|
|
10
|
+
brandFamily: any;
|
|
11
|
+
}): {
|
|
12
|
+
textCount: number;
|
|
13
|
+
brandFont: number;
|
|
14
|
+
otherFonts: {};
|
|
15
|
+
below45: number;
|
|
16
|
+
min: number;
|
|
17
|
+
worst: never[];
|
|
18
|
+
};
|
|
19
|
+
export declare function auditOverflow(): {
|
|
20
|
+
pageScroll: number;
|
|
21
|
+
clipped: never[];
|
|
22
|
+
scrollRegions: never[];
|
|
23
|
+
overlaps: never[];
|
|
24
|
+
tinyText: number;
|
|
25
|
+
};
|
|
26
|
+
export declare function lintSource(html: any): {
|
|
27
|
+
hardcodedColours: any;
|
|
28
|
+
externalScripts: any[];
|
|
29
|
+
formatsNumbersItself: boolean;
|
|
30
|
+
};
|
|
@@ -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,38 @@
|
|
|
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, and `current`
|
|
7
|
+
* the visual it draws now, for an assistant asked to change it (P5G-09).
|
|
8
|
+
*/
|
|
9
|
+
export declare function visualContractText(card?: {
|
|
10
|
+
fields: readonly {
|
|
11
|
+
name: string;
|
|
12
|
+
kind: 'dimension' | 'measure';
|
|
13
|
+
type: string;
|
|
14
|
+
}[];
|
|
15
|
+
current?: string;
|
|
16
|
+
}): string;
|
|
17
|
+
/** One of a card's fields as the contract lists it. */
|
|
18
|
+
export type ContractField = {
|
|
19
|
+
name: string;
|
|
20
|
+
kind: 'dimension' | 'measure';
|
|
21
|
+
type: 'string' | 'number' | 'date' | 'boolean';
|
|
22
|
+
};
|
|
23
|
+
/**
|
|
24
|
+
* A config card's fields as the contract lists them, from its shelves and
|
|
25
|
+
* without running it: Rows are dimensions, Values measures, in the card's
|
|
26
|
+
* order (EXT-D6). A SQL card's columns are known only when it runs, so it
|
|
27
|
+
* lists none; the editor reads them from its result (`readVisualFields`).
|
|
28
|
+
*/
|
|
29
|
+
export declare function cardVisualFields(card: Pick<TCard, 'config' | 'sql'>): ContractField[];
|
|
30
|
+
/**
|
|
31
|
+
* Three illustrative rows for a card's fields, by field name: the shape of
|
|
32
|
+
* the values a visual receives, not the card's data (semaphor_analyze with
|
|
33
|
+
* fromCard returns that).
|
|
34
|
+
*/
|
|
35
|
+
export declare function sampleVisualRows(fields: readonly ContractField[]): Record<string, {
|
|
36
|
+
value: unknown;
|
|
37
|
+
text: string;
|
|
38
|
+
}>[];
|
|
@@ -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;
|