react-semaphor 0.1.560 → 0.1.561

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 (107) hide show
  1. package/dist/analytics-protocol/index.js +353 -349
  2. package/dist/assistant-context/index.js +1 -1
  3. package/dist/assistant-protocol/index.js +5 -5
  4. package/dist/brand-studio/index.js +9 -9
  5. package/dist/briefings/index.js +5 -5
  6. package/dist/chunks/{analytics-base-schemas-CHLxsPfX.js → analytics-base-schemas-CB3oFAXk.js} +199 -171
  7. package/dist/chunks/{assistant-chat-Bu2fFm_I.js → assistant-chat-DiVHY3Hw.js} +27 -28
  8. package/dist/chunks/bookmark-impact-CR09dpkn.js +75 -0
  9. package/dist/chunks/bookmark-state-BusLpkb7.js +743 -0
  10. package/dist/chunks/{braces-Da41xfUd.js → braces-u8VorWJc.js} +1 -1
  11. package/dist/chunks/{comparison-window-caption-4FNkMrzE.js → comparison-window-caption-DDsIWJYT.js} +108 -108
  12. package/dist/chunks/{context-BgPDzLHZ.js → context-TUjw9eqr.js} +1 -1
  13. package/dist/chunks/{custom-visual-inputs-Dz-enUNR.js → custom-visual-inputs-DfolidZ9.js} +1 -1
  14. package/dist/chunks/{dashboard-_MeBuy67.js → dashboard-BRdZBPqr.js} +1 -1
  15. package/dist/chunks/{dashboard-briefing-launcher-CEi4Pr_v.js → dashboard-briefing-launcher-CgvTLndW.js} +161 -162
  16. package/dist/chunks/{dashboard-controls-Bi7fyG-4.js → dashboard-controls-B4vfSzTF.js} +881 -945
  17. package/dist/chunks/{dashboard-json-B1mU_OMa.js → dashboard-json-Y3MF59g7.js} +5 -5
  18. package/dist/chunks/document-dashboard-inputs-CvBbFTUA.js +1718 -0
  19. package/dist/chunks/{edit-dashboard-visual-0CJN31Y3.js → edit-dashboard-visual-DwjZcxj-.js} +6112 -6146
  20. package/dist/chunks/{filter-reach-copy-BF4w4kI2.js → filter-reach-copy-bijwf_-b.js} +1250 -1392
  21. package/dist/chunks/{filter-value-text-CRC-K_l_.js → filter-value-text-DFnhwuEW.js} +3 -3
  22. package/dist/chunks/global-date-filter-utils-BXgCpvQM.js +15142 -0
  23. package/dist/chunks/{index-DtHidOPV.js → index-ClwbY3BL.js} +197 -198
  24. package/dist/chunks/{layout-grid-BvsH4RY2.js → layout-grid-CtvCBfOm.js} +1 -1
  25. package/dist/chunks/{list-filter-Dg0otx5E.js → list-filter-BklYgciR.js} +1 -1
  26. package/dist/chunks/{matrix-analytical-definition-CM18W8w6.js → matrix-analytical-definition-pU51-JmY.js} +4 -4
  27. package/dist/chunks/{matrix-card-HPskLaPy.js → matrix-card-CUorIB7Q.js} +3 -3
  28. package/dist/chunks/{matrix-member-presentation-Bbrfrke4.js → matrix-member-presentation-Df5UgCGN.js} +1 -1
  29. package/dist/chunks/{matrix-operation-contract-WPv4R-H_.js → matrix-operation-contract-BSiGEXVC.js} +255 -248
  30. package/dist/chunks/{metric-comparison-ljMKYZKa.js → metric-comparison-95aC0uEO.js} +6 -6
  31. package/dist/chunks/{model-change-Ccn1zaxl.js → model-change-B5wQhg5G.js} +1 -1
  32. package/dist/chunks/{palette-Bsh376zO.js → palette-DTnMhipt.js} +1 -1
  33. package/dist/chunks/pivot-result-contract-expectations-Bo-86vwS.js +56 -0
  34. package/dist/chunks/{pivot-result-identity-vS9TSh4f.js → pivot-result-identity-olvXJoB9.js} +1 -1
  35. package/dist/chunks/{report-preferences-dialog-BV8L0SeS.js → report-preferences-dialog-C2YUIwKG.js} +14 -14
  36. package/dist/chunks/{report-runtime-context-BZQh9ywy.js → report-runtime-context-DoIUr3MP.js} +2 -2
  37. package/dist/chunks/resolve-dashboard-input-context-q_iiNXE1.js +6503 -0
  38. package/dist/chunks/{save-B5EAsgQF.js → save-DH4RyrnG.js} +1 -1
  39. package/dist/chunks/{saved-dashboard-context-n2Wn11cV.js → saved-dashboard-context-8jqfI7hI.js} +12 -12
  40. package/dist/chunks/{selection-reducer-D0YnaAD9.js → selection-reducer-CV7K4FI6.js} +1 -1
  41. package/dist/chunks/{semaphor-ready-indicator-XLBLOJ2V.js → semaphor-ready-indicator-E2XWyibu.js} +30253 -31076
  42. package/dist/chunks/{shelf-drop-preview-context-DHMa54a-.js → shelf-drop-preview-context-C29EUzDp.js} +7 -7
  43. package/dist/chunks/{source-entity-resolution-dUG5VWRm.js → source-entity-resolution-BXI3nQ5Z.js} +1 -1
  44. package/dist/chunks/{switch-ByxH4M7t.js → switch-balDSHc7.js} +3 -3
  45. package/dist/chunks/{table-export-sheet-C_GdeTYU.js → table-export-sheet-CK8tvh4d.js} +1 -1
  46. package/dist/chunks/temporal-input-presentation-B77JsAzU.js +5002 -0
  47. package/dist/chunks/{token-types-CQtXUVMy.js → token-types-DhYH5YKb.js} +1 -1
  48. package/dist/chunks/{upload-wbR-NVzq.js → upload-Ufj8vjyn.js} +1 -1
  49. package/dist/chunks/{use-create-flow-overlay-state-CEBaLOKC.js → use-create-flow-overlay-state-9WsnzEO5.js} +6 -6
  50. package/dist/chunks/{validators-CXTneCA4.js → validators-BtaCFIEB.js} +37 -37
  51. package/dist/chunks/{zoned-wall-clock-B1n_WjW3.js → zoned-wall-clock-CGLVI40Q.js} +1 -1
  52. package/dist/dashboard/index.js +2 -2
  53. package/dist/dashboard-authoring/index.js +2400 -1856
  54. package/dist/data-app-sdk/index.js +20 -20
  55. package/dist/data-app-sdk-adapters/index.js +3 -3
  56. package/dist/data-app-sdk-validation/index.js +10 -10
  57. package/dist/format-utils/index.js +257 -256
  58. package/dist/index.js +214 -215
  59. package/dist/report-runtime-context/index.js +2 -2
  60. package/dist/style.css +1 -1
  61. package/dist/surfboard/index.js +2 -2
  62. package/dist/types/components/dashboard/summary-number-formatter.d.ts +6 -0
  63. package/dist/types/index.js +50 -51
  64. package/dist/types/lib/formatters/kpi-number-formatter.d.ts +41 -0
  65. package/dist/types/lib/stores/editor-store.d.ts +9 -1
  66. package/dist/types/lib/stores/table-actions.d.ts +0 -2
  67. package/dist/types/shared/analytics-protocol/analytics-base-schemas.d.ts +10 -0
  68. package/dist/types/shared/analytics-protocol/measure-aggregation-profile.d.ts +12 -0
  69. package/dist/types/shared/dashboard-authoring/card-settings/apply-card-settings.d.ts +11 -0
  70. package/dist/types/shared/dashboard-authoring/card-settings/card-display-write.d.ts +52 -0
  71. package/dist/types/shared/dashboard-authoring/card-settings/card-kinds.d.ts +14 -0
  72. package/dist/types/shared/dashboard-authoring/card-settings/carry-column-settings.d.ts +3 -0
  73. package/dist/types/shared/dashboard-authoring/card-settings/column-format-write.d.ts +8 -0
  74. package/dist/types/shared/dashboard-authoring/card-settings/column-names.d.ts +51 -0
  75. package/dist/types/shared/dashboard-authoring/card-settings/column-sources.d.ts +14 -0
  76. package/dist/types/shared/dashboard-authoring/card-settings/confirm-class.d.ts +9 -0
  77. package/dist/types/shared/dashboard-authoring/card-settings/highlight-inputs.d.ts +19 -0
  78. package/dist/types/shared/dashboard-authoring/card-settings/index.d.ts +15 -0
  79. package/dist/types/shared/dashboard-authoring/card-settings/inputs.d.ts +102 -0
  80. package/dist/types/shared/dashboard-authoring/card-settings/read-card-settings.d.ts +10 -0
  81. package/dist/types/shared/dashboard-authoring/card-settings/resolve-card-highlights.d.ts +14 -0
  82. package/dist/types/shared/dashboard-authoring/card-settings/resolve-card-settings.d.ts +59 -0
  83. package/dist/types/shared/dashboard-authoring/card-settings/resolved.d.ts +40 -0
  84. package/dist/types/shared/dashboard-authoring/card-settings/views.d.ts +28 -0
  85. package/dist/types/shared/dashboard-authoring/changes/card-query-part.d.ts +6 -0
  86. package/dist/types/shared/dashboard-authoring/changes/card-types.d.ts +32 -0
  87. package/dist/types/shared/dashboard-authoring/changes/dashboard-change.d.ts +539 -22
  88. package/dist/types/shared/dashboard-authoring/changes/diagnostics.d.ts +27 -8
  89. package/dist/types/shared/dashboard-authoring/changes/resolve-dashboard-changes.d.ts +25 -1
  90. package/dist/types/shared/dashboard-authoring/conditional-formatting/kpi.d.ts +1 -8
  91. package/dist/types/shared/dashboard-authoring/conditional-formatting/schema.d.ts +10 -10
  92. package/dist/types/shared/dashboard-authoring/index.d.ts +3 -0
  93. package/dist/types/shared/dashboard-authoring/kpi-figure.d.ts +123 -0
  94. package/dist/types/shared/dashboard-authoring/operations/operation-types.d.ts +21 -1
  95. package/dist/types/shared/dashboard-authoring/outline/outline-dashboard.d.ts +10 -4
  96. package/dist/types/shared/dashboard-viewer/bookmark-impact.d.ts +33 -0
  97. package/dist/types/shared/format-utils/formatters/matrix-formatter.d.ts +8 -1
  98. package/dist/types/shared/format-utils/raw-temporal.d.ts +16 -0
  99. package/package.json +2 -2
  100. package/dist/chunks/bookmark-state-BFY9oNmr.js +0 -111
  101. package/dist/chunks/document-dashboard-inputs-CkWfDB8c.js +0 -3010
  102. package/dist/chunks/global-date-filter-utils-D8365uPH.js +0 -12889
  103. package/dist/chunks/pivot-result-contract-expectations-Bl5suy4-.js +0 -1832
  104. package/dist/chunks/raw-temporal-presentation-BHm7s-hz.js +0 -540
  105. package/dist/chunks/resolve-dashboard-input-context-CAMiWvyR.js +0 -5280
  106. package/dist/chunks/table-settings-Imz0FgWi.js +0 -637
  107. package/dist/chunks/temporal-input-presentation-uvNK_tM0.js +0 -3228
@@ -1,9 +1,4 @@
1
- /**
2
- * Problems and warnings for dashboard changes (MCP dashboard editing SPEC
3
- * 3.2). One shape for both: a refusal lists problems, a proposal carries
4
- * warnings. Messages are one sentence a person can read and never name the
5
- * product; `fix` tells the agent what to do next.
6
- */
1
+ import { ProposedChange } from './dashboard-change.js';
7
2
  export type ChangeProblemCode = 'invalid_change' | 'invalid_change_target' | 'copy_required' | 'not_permitted' | 'dashboard_not_found' | 'card_not_found' | 'filter_not_found' | 'sheet_not_found' | 'sheet_required' | 'sheet_not_a_grid' | 'field_not_found'
8
3
  /**
9
4
  * The card's datasets aren't joined by the domain's relationships, so the
@@ -14,7 +9,25 @@ export type ChangeProblemCode = 'invalid_change' | 'invalid_change_target' | 'co
14
9
  /** filter.update or filter.bind on a filter the outline marks read only. */
15
10
  | 'filter_not_editable'
16
11
  /** The changed dashboard fails the save's own validation (propose or apply). */
17
- | 'document_invalid';
12
+ | 'document_invalid'
13
+ /** A setting the card's kind doesn't take (SPEC 3.4). */
14
+ | 'setting_not_for_card'
15
+ /** No column of the card has that name. */
16
+ | 'column_not_found'
17
+ /** The name matches two columns. */
18
+ | 'column_ambiguous'
19
+ /** A SQL table's result columns couldn't be read to check a column name. */
20
+ | 'columns_unavailable'
21
+ /** A format that fails the stored format's schema, has nothing to merge onto, or doesn't fit the column's data. */
22
+ | 'format_invalid'
23
+ /** A date format finer than the column's grain. */
24
+ | 'date_finer_than_grain'
25
+ /** Not a theme color name or `#rrggbb`. */
26
+ | 'color_unknown'
27
+ /** No highlight rule on the card has that id. */
28
+ | 'highlight_not_found'
29
+ /** A width, range or title that can't be stored, or two labels for one column. */
30
+ | 'value_invalid';
18
31
  export type ChangeWarningCode =
19
32
  /** In-scope cards the filter doesn't reach. */
20
33
  'filter_not_reaching_cards'
@@ -37,7 +50,9 @@ export type ChangeWarningCode =
37
50
  * dashboard already fails the save's own check, so the change wasn't
38
51
  * checked against it; the person's Save reports what it finds.
39
52
  */
40
- | 'document_not_checked';
53
+ | 'document_not_checked'
54
+ /** A change removes something viewers' bookmarks or remembered table settings use (card appearance CA-D17). */
55
+ | 'viewer_settings_affected';
41
56
  export type ChangeDiagnostic = {
42
57
  code: ChangeProblemCode | ChangeWarningCode;
43
58
  /** One sentence, safe to show an end user. */
@@ -48,4 +63,8 @@ export type ChangeDiagnostic = {
48
63
  fix?: string;
49
64
  /** E.g. `{ sheets }`, `{ available }`, `{ suggestedFields }`. */
50
65
  details?: Record<string, unknown>;
66
+ /** What this card or setting accepts, in the input words (card appearance CA-D9). */
67
+ allowed?: readonly string[];
68
+ /** A change the agent can send as written (CA-D9). */
69
+ suggestedChange?: ProposedChange;
51
70
  };
@@ -1,4 +1,4 @@
1
- import { TDashboard } from '../../../lib/types/common-types.js';
1
+ import { TCard, TDashboard } from '../../../lib/types/common-types.js';
2
2
  import { DataSource, Field } from '../../../lib/types/explorer-types.js';
3
3
  import { TChartType } from '../../../lib/charts/types.js';
4
4
  import { CalendarContext } from '../../report-runtime-context/index.js';
@@ -7,6 +7,7 @@ import { DashboardOperation, OperationContext, OperationDescription } from '../o
7
7
  import { CardQueryPart } from './card-query-part.js';
8
8
  import { FieldRef, MetricCardQuery, RecordsCardQuery } from './dashboard-change.js';
9
9
  import { ChangeDiagnostic } from './diagnostics.js';
10
+ import { ModelFormats } from '../../format-utils/resolve-column-format.js';
10
11
  /**
11
12
  * Public dashboard changes to resolved operations (MCP dashboard editing SPEC
12
13
  * 3.7, DE-D48). Every rule the schema can't state lives here; everything that
@@ -66,6 +67,25 @@ export type ChangeServices = {
66
67
  * RF-D15). Without one, those cards read as decided when they run.
67
68
  */
68
69
  relationshipReach?: DashboardRelationshipReachResolver;
70
+ /**
71
+ * A SQL card's result keys, read by running it on this dashboard (card
72
+ * appearance SPEC 5, V-9); null when it can't run or returns no rows.
73
+ * Called only when a change names a SQL card's columns.
74
+ */
75
+ readSqlResultColumns?(input: {
76
+ cardId: string;
77
+ dashboard: TDashboard;
78
+ }): Promise<readonly string[] | null>;
79
+ /**
80
+ * The model format each of a card's columns shows, by column id (a config
81
+ * field's id, a Matrix level's or measure's), as the query gives it to the
82
+ * renderer: a config card's `modelFormats` (CF-D23), a Matrix's bound
83
+ * catalog formats. Called only when a change states a format; null when it
84
+ * can't be read (card appearance ledger P2-20).
85
+ */
86
+ readModelFormats?(input: {
87
+ card: TCard;
88
+ }): Promise<ModelFormats | null>;
69
89
  };
70
90
  export type ChangeRef = {
71
91
  ref: string;
@@ -73,6 +93,8 @@ export type ChangeRef = {
73
93
  id: string;
74
94
  title: string;
75
95
  changeIndex: number;
96
+ /** A highlight rule a `highlight.add` made, minted at resolve (card appearance SPEC 5); never in a sentence (S-10). */
97
+ ruleId?: string;
76
98
  };
77
99
  export type ChangeResolution = {
78
100
  ok: true;
@@ -84,6 +106,8 @@ export type ChangeResolution = {
84
106
  /** Handle or existing id to final id, in change order; a handle-less card.add gets $card_1, $card_2... */
85
107
  refs: ChangeRef[];
86
108
  descriptions: OperationDescription[];
109
+ /** The dry run detached a library visual (`DashboardOperationResult.detaches`). */
110
+ detaches: boolean;
87
111
  /** Cards whose query part or type changed, and added cards, in change order: the preview runs the first five. */
88
112
  changedCardIds: string[];
89
113
  /** Every capability the resolution relied on (DE-D60). */
@@ -1,14 +1,7 @@
1
1
  import { TCard } from '../../../lib/types/common-types.js';
2
- import { CardColumnRef } from './types.js';
3
2
  export type KpiValueStyle = {
4
3
  color?: string;
5
4
  backgroundColor?: string;
6
5
  };
7
- /**
8
- * The column a KPI's value rules name: a SQL KPI's value, else its first
9
- * measure (or the one named). The renderers color it, and the KPI rule panel
10
- * offers only it, so a rule can't be saved where it never shows (ledger P4-16).
11
- */
12
- export declare function kpiValueColumn(card: Pick<TCard, 'sql' | 'config'>, metricId?: string): CardColumnRef | undefined;
13
6
  /** The colors the card's rules give this value. */
14
- export declare function resolveKpiValueStyle(card: Pick<TCard, 'sql' | 'config' | 'preferences'>, value: unknown, metricId?: string): KpiValueStyle;
7
+ export declare function resolveKpiValueStyle(card: Pick<TCard, 'sql' | 'config' | 'preferences'>, value: unknown): KpiValueStyle;
@@ -1443,9 +1443,9 @@ export declare const conditionalRuleSchema: z.ZodObject<{
1443
1443
  color: string;
1444
1444
  showValue: boolean;
1445
1445
  } | undefined;
1446
+ fontWeight?: "bold" | "medium" | "normal" | "semibold" | undefined;
1446
1447
  backgroundColor?: string | undefined;
1447
1448
  textColor?: string | undefined;
1448
- fontWeight?: "bold" | "medium" | "normal" | "semibold" | undefined;
1449
1449
  italic?: boolean | undefined;
1450
1450
  textDecoration?: "none" | "underline" | "line-through" | undefined;
1451
1451
  icon?: "warning" | "arrowUp" | "arrowDown" | "check" | "x" | undefined;
@@ -1454,9 +1454,9 @@ export declare const conditionalRuleSchema: z.ZodObject<{
1454
1454
  color: string;
1455
1455
  showValue: boolean;
1456
1456
  } | undefined;
1457
+ fontWeight?: "bold" | "medium" | "normal" | "semibold" | undefined;
1457
1458
  backgroundColor?: string | undefined;
1458
1459
  textColor?: string | undefined;
1459
- fontWeight?: "bold" | "medium" | "normal" | "semibold" | undefined;
1460
1460
  italic?: boolean | undefined;
1461
1461
  textDecoration?: "none" | "underline" | "line-through" | undefined;
1462
1462
  icon?: "warning" | "arrowUp" | "arrowDown" | "check" | "x" | undefined;
@@ -1723,9 +1723,9 @@ export declare const conditionalRuleSchema: z.ZodObject<{
1723
1723
  color: string;
1724
1724
  showValue: boolean;
1725
1725
  } | undefined;
1726
+ fontWeight?: "bold" | "medium" | "normal" | "semibold" | undefined;
1726
1727
  backgroundColor?: string | undefined;
1727
1728
  textColor?: string | undefined;
1728
- fontWeight?: "bold" | "medium" | "normal" | "semibold" | undefined;
1729
1729
  italic?: boolean | undefined;
1730
1730
  textDecoration?: "none" | "underline" | "line-through" | undefined;
1731
1731
  icon?: "warning" | "arrowUp" | "arrowDown" | "check" | "x" | undefined;
@@ -1993,9 +1993,9 @@ export declare const conditionalRuleSchema: z.ZodObject<{
1993
1993
  color: string;
1994
1994
  showValue: boolean;
1995
1995
  } | undefined;
1996
+ fontWeight?: "bold" | "medium" | "normal" | "semibold" | undefined;
1996
1997
  backgroundColor?: string | undefined;
1997
1998
  textColor?: string | undefined;
1998
- fontWeight?: "bold" | "medium" | "normal" | "semibold" | undefined;
1999
1999
  italic?: boolean | undefined;
2000
2000
  textDecoration?: "none" | "underline" | "line-through" | undefined;
2001
2001
  icon?: "warning" | "arrowUp" | "arrowDown" | "check" | "x" | undefined;
@@ -3377,9 +3377,9 @@ export declare const cardConditionalFormattingSchema: z.ZodObject<{
3377
3377
  color: string;
3378
3378
  showValue: boolean;
3379
3379
  } | undefined;
3380
+ fontWeight?: "bold" | "medium" | "normal" | "semibold" | undefined;
3380
3381
  backgroundColor?: string | undefined;
3381
3382
  textColor?: string | undefined;
3382
- fontWeight?: "bold" | "medium" | "normal" | "semibold" | undefined;
3383
3383
  italic?: boolean | undefined;
3384
3384
  textDecoration?: "none" | "underline" | "line-through" | undefined;
3385
3385
  icon?: "warning" | "arrowUp" | "arrowDown" | "check" | "x" | undefined;
@@ -3388,9 +3388,9 @@ export declare const cardConditionalFormattingSchema: z.ZodObject<{
3388
3388
  color: string;
3389
3389
  showValue: boolean;
3390
3390
  } | undefined;
3391
+ fontWeight?: "bold" | "medium" | "normal" | "semibold" | undefined;
3391
3392
  backgroundColor?: string | undefined;
3392
3393
  textColor?: string | undefined;
3393
- fontWeight?: "bold" | "medium" | "normal" | "semibold" | undefined;
3394
3394
  italic?: boolean | undefined;
3395
3395
  textDecoration?: "none" | "underline" | "line-through" | undefined;
3396
3396
  icon?: "warning" | "arrowUp" | "arrowDown" | "check" | "x" | undefined;
@@ -3657,9 +3657,9 @@ export declare const cardConditionalFormattingSchema: z.ZodObject<{
3657
3657
  color: string;
3658
3658
  showValue: boolean;
3659
3659
  } | undefined;
3660
+ fontWeight?: "bold" | "medium" | "normal" | "semibold" | undefined;
3660
3661
  backgroundColor?: string | undefined;
3661
3662
  textColor?: string | undefined;
3662
- fontWeight?: "bold" | "medium" | "normal" | "semibold" | undefined;
3663
3663
  italic?: boolean | undefined;
3664
3664
  textDecoration?: "none" | "underline" | "line-through" | undefined;
3665
3665
  icon?: "warning" | "arrowUp" | "arrowDown" | "check" | "x" | undefined;
@@ -3927,9 +3927,9 @@ export declare const cardConditionalFormattingSchema: z.ZodObject<{
3927
3927
  color: string;
3928
3928
  showValue: boolean;
3929
3929
  } | undefined;
3930
+ fontWeight?: "bold" | "medium" | "normal" | "semibold" | undefined;
3930
3931
  backgroundColor?: string | undefined;
3931
3932
  textColor?: string | undefined;
3932
- fontWeight?: "bold" | "medium" | "normal" | "semibold" | undefined;
3933
3933
  italic?: boolean | undefined;
3934
3934
  textDecoration?: "none" | "underline" | "line-through" | undefined;
3935
3935
  icon?: "warning" | "arrowUp" | "arrowDown" | "check" | "x" | undefined;
@@ -4200,9 +4200,9 @@ export declare const cardConditionalFormattingSchema: z.ZodObject<{
4200
4200
  color: string;
4201
4201
  showValue: boolean;
4202
4202
  } | undefined;
4203
+ fontWeight?: "bold" | "medium" | "normal" | "semibold" | undefined;
4203
4204
  backgroundColor?: string | undefined;
4204
4205
  textColor?: string | undefined;
4205
- fontWeight?: "bold" | "medium" | "normal" | "semibold" | undefined;
4206
4206
  italic?: boolean | undefined;
4207
4207
  textDecoration?: "none" | "underline" | "line-through" | undefined;
4208
4208
  icon?: "warning" | "arrowUp" | "arrowDown" | "check" | "x" | undefined;
@@ -4473,9 +4473,9 @@ export declare const cardConditionalFormattingSchema: z.ZodObject<{
4473
4473
  color: string;
4474
4474
  showValue: boolean;
4475
4475
  } | undefined;
4476
+ fontWeight?: "bold" | "medium" | "normal" | "semibold" | undefined;
4476
4477
  backgroundColor?: string | undefined;
4477
4478
  textColor?: string | undefined;
4478
- fontWeight?: "bold" | "medium" | "normal" | "semibold" | undefined;
4479
4479
  italic?: boolean | undefined;
4480
4480
  textDecoration?: "none" | "underline" | "line-through" | undefined;
4481
4481
  icon?: "warning" | "arrowUp" | "arrowDown" | "check" | "x" | undefined;
@@ -52,6 +52,9 @@ export * from './upgrade-card-presentation.js';
52
52
  export * from './card-formats/sql-date-pattern.js';
53
53
  export * from './retired-presentation-fields.js';
54
54
  export * from './conditional-formatting/index.js';
55
+ export * from './kpi-figure.js';
56
+ export * from './card-settings/index.js';
57
+ export { bookmarkImpactSentence, describeBookmarkImpact, type BookmarkImpactItem, } from '../dashboard-viewer/bookmark-impact.js';
55
58
  export { prepareLoadedDashboard } from '../../lib/dashboard-inputs/prepare-loaded-dashboard.js';
56
59
  export { buildFilterInputFromField, buildFilterInputFromDefinition, applyFilterSettingsChange } from '../../lib/dashboard-inputs/filter-settings.js';
57
60
  export { relationshipRouteTarget } from '../../lib/dashboard-inputs/dashboard-filter-value-identity.js';
@@ -0,0 +1,123 @@
1
+ import { TCard } from '../../lib/types/common-types.js';
2
+ import { CardConfig, MetricField } from '../../lib/types/explorer-types.js';
3
+ import { ComparisonMetadataMap } from '../../lib/types/query-types.js';
4
+ import { MetricComparisonEvaluation, MetricComparisonPolarity } from '../analytics-protocol/index.js';
5
+ type KpiCard = Pick<TCard, 'sql' | 'config' | 'preferences'>;
6
+ /**
7
+ * Which column is the value, by source. The shape reads ids, never formats, so
8
+ * it is the same for the saved card and the render card; formats, rules,
9
+ * currency targets and the settings panels need only this.
10
+ */
11
+ export type KpiShape = {
12
+ source: 'sql';
13
+ /** A SQL KPI's value is positional: its result's first numeric column (CF-D24). */
14
+ value: {
15
+ kind: 'sqlKpiValue';
16
+ };
17
+ /** `preferences.sqlKpiValue.comparisonPolarity`, else the default. */
18
+ polarity: MetricComparisonPolarity;
19
+ } | {
20
+ source: 'config';
21
+ /** Built from `measure`: always `{ kind: 'field', fieldId: measure.id }`. */
22
+ value: {
23
+ kind: 'field';
24
+ fieldId: string;
25
+ };
26
+ /** The value measure: the card's first. */
27
+ measure: MetricField;
28
+ /** The measure's polarity. */
29
+ polarity: MetricComparisonPolarity;
30
+ };
31
+ /** A KPI's value column, or another measure of a config KPI. */
32
+ export type KpiColumn = KpiShape['value'];
33
+ /** SQL text means a SQL KPI (KV-D2), as the server runs it. */
34
+ export declare function isSqlKpi(card: Pick<TCard, 'sql'>): boolean;
35
+ /** Undefined for a card with no value to show: a config KPI with no measure. */
36
+ export declare function resolveKpiShape(card: KpiCard): KpiShape | undefined;
37
+ /**
38
+ * What sits beside the value. `value`: the value and, when the card compares,
39
+ * its comparison (a previous period or a target). `measures`: the value and
40
+ * the card's second and third measures.
41
+ */
42
+ export type KpiLayout = 'value' | 'measures';
43
+ /** How many measures the measures layout shows: the value and the next two. The server queries no more. */
44
+ export declare const KPI_MEASURES_SHOWN = 3;
45
+ /**
46
+ * The one layout rule (KV-D7, option B): `measures` for two or more measures,
47
+ * no group-by and no target comparison; else `value`. A period comparison, the
48
+ * card's own or the dashboard's, never changes it. The server calls it and
49
+ * writes the answer on the response (`kpiLayout`), so no reader guesses which
50
+ * branch ran; `readKpiFigure` applies it to the card only before a response
51
+ * arrives.
52
+ */
53
+ export declare function resolveKpiLayout(input: {
54
+ config?: Pick<CardConfig, 'metricColumns' | 'groupByColumns'>;
55
+ }): KpiLayout;
56
+ /**
57
+ * A config KPI's result rows. Every row names its measure; `current` is a
58
+ * measure's value and `comparison` its prior or target, in every branch.
59
+ */
60
+ export type KpiResultSegment = {
61
+ segment: 'current' | 'comparison';
62
+ value: number | string | null;
63
+ metricId: string;
64
+ };
65
+ /** The metadata a config KPI response carries beside its rows. */
66
+ export type KpiResultMetadata = {
67
+ kpiLayout: KpiLayout;
68
+ comparisonMetadata?: ComparisonMetadataMap;
69
+ };
70
+ /** The id a row names its measure by (`id`, else `name`): the server writes it, the owner reads it. */
71
+ export declare function kpiSegmentMetricId(metric: Pick<MetricField, 'id' | 'name'>): string;
72
+ export type KpiComparison = {
73
+ /** A SQL KPI's prior (its second numeric column) reads as the previous period. */
74
+ kind: 'previous_period' | 'previous_year' | 'target';
75
+ /** "Previous", "Target" or `comparisonPresentation.labelName`. */
76
+ label: string;
77
+ /** False when the author turned it off (`comparisonPresentation.showComparison`). */
78
+ shown: boolean;
79
+ /** From `evaluateMetricComparison`, the only source of a change (KV-D8). */
80
+ evaluation: MetricComparisonEvaluation;
81
+ };
82
+ export type KpiFigure = {
83
+ /** Undefined for a config KPI with no measure. */
84
+ shape?: KpiShape;
85
+ /** `value` for a SQL KPI; the response's `kpiLayout` for a config KPI. */
86
+ layout: KpiLayout;
87
+ /** Null when the response has no number for the value (and the surface gave no `missingValue`). */
88
+ value: number | null;
89
+ /** Why the response has no number: none at all, or values that aren't numbers. */
90
+ missing?: 'no_value' | 'not_numeric';
91
+ /** The `value` layout's comparison, when the card compares and the response has one. */
92
+ comparison?: KpiComparison;
93
+ /** The `measures` layout's second and third measures and their values. */
94
+ others: ReadonlyArray<{
95
+ measure: MetricField;
96
+ value: number | null;
97
+ /** Against the value, when the author turned on the pair comparison (exactly two measures). */
98
+ evaluation?: MetricComparisonEvaluation;
99
+ }>;
100
+ /** A SQL KPI's result keys: the first numeric column is the value, the second the prior. */
101
+ resultKeys: {
102
+ value?: string;
103
+ previous?: string;
104
+ };
105
+ };
106
+ type KpiRecords = readonly Record<string, unknown>[] | null | undefined;
107
+ /** A finite number from a numeric value or a numeric string (thousands commas allowed). */
108
+ export declare function toFiniteKpiNumber(value: unknown): number | null;
109
+ /** A SQL KPI's result keys: its first numeric column is the value, the second the prior. */
110
+ export declare function sqlKpiResultKeys(records: KpiRecords): KpiFigure['resultKeys'];
111
+ /**
112
+ * The render card and its query response: what every renderer shows. A surface
113
+ * that shows a missing value as a number (the dashboard tiles show `0`) passes
114
+ * it as `missingValue`, and the value's evaluations use it too.
115
+ */
116
+ export declare function readKpiFigure(input: {
117
+ /** The query result's `renderCard` (live model formats included), never the saved card (column formats P5-12, P5-19). */
118
+ renderCard: KpiCard;
119
+ records?: KpiRecords;
120
+ metadata?: Partial<KpiResultMetadata>;
121
+ missingValue?: number;
122
+ }): KpiFigure;
123
+ export {};
@@ -1,4 +1,5 @@
1
1
  import { EmbeddedFilterDashboardInput, TDashboard, TFrame } from '../../../lib/types/common-types.js';
2
+ import { ResolvedCardSettings } from '../card-settings/resolved.js';
2
3
  import { FilterSettingsChange, FilterValueEffect } from '../../../lib/dashboard-inputs/filter-settings.js';
3
4
  import { DashboardFilterBoundCardApplication } from '../dashboard-filter-mapping-types.js';
4
5
  import { Field } from '../../../lib/types/explorer-types.js';
@@ -40,6 +41,11 @@ export type CardUpdate =
40
41
  | {
41
42
  kind: 'relabel';
42
43
  labels: StatedLabel[];
44
+ }
45
+ /** How the card's columns read and show, resolved by the card settings owner (card appearance CA-D10, SPEC 3.6). */
46
+ | {
47
+ kind: 'settings';
48
+ settings: ResolvedCardSettings;
43
49
  };
44
50
  /** Everything the editor's "Done", Save & Apply and Apply Local commit persists, as one operation (DE-D13). */
45
51
  export type FrameCommit = {
@@ -105,6 +111,12 @@ export type DashboardOperation = ({
105
111
  op: 'filter.exclude';
106
112
  filterId: string;
107
113
  cardId: string;
114
+ }
115
+ /** The dashboard's own title and description (card appearance); a null description removes it. */
116
+ | {
117
+ op: 'dashboard.update';
118
+ title?: string;
119
+ description?: string | null;
108
120
  }) & {
109
121
  /** Set by the resolver: the public change this operation came from. Descriptions group by it. */
110
122
  changeIndex?: number;
@@ -168,7 +180,9 @@ export type OperationFailureCode = 'sheet_not_found'
168
180
  /** A conversion asked for more ids than the operation carries. */
169
181
  | 'ids_exhausted'
170
182
  /** A retype across the Matrix boundary without a catalog. */
171
- | 'catalog_loading';
183
+ | 'catalog_loading'
184
+ /** A card settings operation names a column the card no longer has (card appearance SPEC 4.3): a defect, since apply runs after the staleness check. */
185
+ | 'setting_target_missing';
172
186
  export type DashboardOperationResult = {
173
187
  ok: true;
174
188
  dashboard: TDashboard;
@@ -176,6 +190,12 @@ export type DashboardOperationResult = {
176
190
  /** One plain sentence per public change (or per operation without a changeIndex). */
177
191
  descriptions: OperationDescription[];
178
192
  runtimeEffects: DashboardRuntimeEffect[];
193
+ /**
194
+ * An edit made a card that showed a library visual the dashboard's own:
195
+ * never applied without a yes (card appearance P2-36). From each
196
+ * operation's outcome; its sentence says so too, but is never read for it.
197
+ */
198
+ detaches: boolean;
179
199
  } | {
180
200
  ok: false;
181
201
  failedAt: {
@@ -1,6 +1,8 @@
1
1
  import { DashboardRelationshipReachResolver } from '../../../lib/query-context/dashboard-filter-mapping-resolution.js';
2
2
  import { TDashboard } from '../../../lib/types/common-types.js';
3
3
  import { FrameWidth } from '../../layouts/index.js';
4
+ import { CardTypeProperties } from '../changes/card-types.js';
5
+ import { CardSettingsView } from '../card-settings/views.js';
4
6
  import { NotEditableReason, OutlineCardSource } from '../changes/read-card-query.js';
5
7
  import { CardQuery, MatrixColumns } from '../changes/dashboard-change.js';
6
8
  import { OutlineFilter } from './outline-filters.js';
@@ -34,10 +36,10 @@ export type OutlineViewer = {
34
36
  */
35
37
  relationshipReach?: DashboardRelationshipReachResolver;
36
38
  };
37
- export type OutlineCard = {
39
+ export type OutlineCard = ({
38
40
  cardId: string;
39
41
  title: string;
40
- /** The public type name (DE-D43). */
42
+ /** The public type name (DE-D43): one of the eight, a variant as properties beside it (card appearance CA-D6). */
41
43
  type: string;
42
44
  source: OutlineCardSource;
43
45
  /** Shows a library visual; changing it makes it local (DE-D50). */
@@ -46,7 +48,9 @@ export type OutlineCard = {
46
48
  /** Absent only when the outline is truncated. */
47
49
  query?: CardQuery;
48
50
  matrix?: MatrixColumns;
49
- } | {
51
+ } & CardTypeProperties &
52
+ /** How the card reads and shows, in the shape a change takes; absent when the outline is truncated (card appearance SPEC 3.2). */
53
+ Partial<CardSettingsView>) | ({
50
54
  cardId: string;
51
55
  title: string;
52
56
  type: string;
@@ -58,7 +62,7 @@ export type OutlineCard = {
58
62
  message: string;
59
63
  detail?: string;
60
64
  };
61
- };
65
+ } & CardTypeProperties);
62
66
  export type OutlineSheet = {
63
67
  sheetId: string;
64
68
  title: string;
@@ -83,6 +87,8 @@ export type OutlineLayoutRow = {
83
87
  export type DashboardOutline = {
84
88
  dashboardId: string;
85
89
  title: string;
90
+ /** The dashboard's description, when it has one: what `dashboard.update` sets. */
91
+ description?: string;
86
92
  updatedAt: string;
87
93
  access: {
88
94
  canEdit: boolean;
@@ -0,0 +1,33 @@
1
+ import { TDashboard } from '../../lib/types/common-types.js';
2
+ import { BookmarkUsage } from './viewer-contract.js';
3
+ export type BookmarkImpactItem = {
4
+ readonly target: 'input' | 'sheet' | 'table' | 'column';
5
+ readonly id: string;
6
+ /** For a column: its table. */
7
+ readonly cardId?: string;
8
+ /** From the saved dashboard, where the removed part still has its name. */
9
+ readonly label: string;
10
+ readonly bookmarks: number;
11
+ /** Viewers with remembered settings that name it (tables and columns). */
12
+ readonly remembered: number;
13
+ };
14
+ /**
15
+ * What an edit removes that saved bookmarks or remembered settings use: parts
16
+ * of the saved dashboard that the draft no longer has, with how many use each.
17
+ * Removed parts don't break anything (opening reports a note, PLAN B24); this
18
+ * tells the author before they save. "No longer has" is decided by the same
19
+ * checks a bookmark is reconciled with when it opens. Builder table columns
20
+ * only: a SQL or Python table's columns are known only from a result. Pure.
21
+ */
22
+ export declare function describeBookmarkImpact(input: {
23
+ readonly saved: TDashboard;
24
+ readonly draft: TDashboard;
25
+ readonly usage: BookmarkUsage;
26
+ }): readonly BookmarkImpactItem[];
27
+ /** How the editor names an affected part and what uses it: ("Revenue", "2 bookmarks, 1 remembered layout"). */
28
+ export declare function describeBookmarkImpactItem(item: BookmarkImpactItem): {
29
+ name: string;
30
+ uses: string;
31
+ };
32
+ /** One sentence for a proposal: what it removes that viewers saved, in the editor's words (card appearance CA-D17). */
33
+ export declare function bookmarkImpactSentence(item: BookmarkImpactItem): string;
@@ -1,6 +1,6 @@
1
1
  import { MatrixPath, MatrixPresentation, MatrixWindow, SemaphorScalarValue, SemaphorValueFormat } from '../../analytics-protocol/index.js';
2
2
  import { ReportRuntimeContext } from '../../report-runtime-context/index.js';
3
- import { MeasureCanonicalFormat } from '../types/index.js';
3
+ import { MeasureCanonicalFormat, RawTemporalFormat } from '../types/index.js';
4
4
  /** Null hierarchy members stay identifiable even when null cells render blank. */
5
5
  export declare function matrixMemberLabel(path: MatrixPath, levels?: ReadonlyMap<string, (value: SemaphorScalarValue) => string>): string;
6
6
  /**
@@ -34,6 +34,13 @@ export declare function matrixLevelLabels(input: {
34
34
  * override, else its catalog (model) format, in the one precedence
35
35
  * (`pickColumnFormat`). Arithmetic, precision and temporal rules stay shared.
36
36
  */
37
+ /**
38
+ * A Matrix raw date level's authored format: what its cells draw of a stored
39
+ * date format (a pattern or preset, and the time zones). Relative time, a
40
+ * prefix and a suffix aren't drawn; card settings read that from here
41
+ * (card appearance CA-D24).
42
+ */
43
+ export declare function matrixRawDateFormat(stored: SemaphorValueFormat | undefined): RawTemporalFormat | undefined;
37
44
  export declare function resolveMatrixValueFormat(override: SemaphorValueFormat | undefined, semantic: SemaphorValueFormat | undefined): import('../semantic-format.js').AdaptedCanonicalFormatSpec | undefined;
38
45
  /** One card's prepared formats: every Matrix surface (screen, Layout CSV, Flat CSV, PDF) formats through it. */
39
46
  export type MatrixFormatting = ReturnType<typeof prepareMatrixFormatting>;
@@ -116,3 +116,19 @@ export declare function formatRawTemporalValue(input: {
116
116
  metadata: RawTemporalValueMetadata;
117
117
  format: ResolvedRawTemporalFormat;
118
118
  }): RawTemporalFormatResult;
119
+ /**
120
+ * One raw date column's formatter, as every raw-date renderer prepares it
121
+ * (a detail table, a SQL table, a Matrix level): the authored format resolved
122
+ * against the viewer's preferences, then prepared for the column's value
123
+ * kind. Throws when the column can't show the format; card settings call it
124
+ * to decide whether a format is usable (card appearance CA-D24).
125
+ */
126
+ export declare function prepareRawDateColumn(input: {
127
+ authored: RawTemporalFormat | undefined;
128
+ metadata: RawTemporalValueMetadata;
129
+ preferences: ResolvedValueFormatPreferences;
130
+ calendar: Pick<CalendarContext, 'tz'>;
131
+ }): {
132
+ format: ResolvedRawTemporalFormat;
133
+ formatValue: PreparedRawTemporalFormatter;
134
+ };
package/package.json CHANGED
@@ -5,7 +5,7 @@
5
5
  "email": "support@semaphor.cloud"
6
6
  },
7
7
  "license": "MIT",
8
- "version": "0.1.560",
8
+ "version": "0.1.561",
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/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",
131
131
  "preview": "vite preview",
132
132
  "test": "vitest run",
133
133
  "test:changed": "vitest run --changed",