react-semaphor 0.1.585 → 0.1.587

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 (49) hide show
  1. package/dist/analytics-protocol/index.js +102 -100
  2. package/dist/assistant-context/index.js +1 -1
  3. package/dist/briefings/index.js +1 -1
  4. package/dist/chunks/{assistant-chat-BdbLmAnK.js → assistant-chat-pfJK-T0b.js} +6 -6
  5. package/dist/chunks/{bookmark-impact-BhT3k379.js → bookmark-impact-BSpGQL1M.js} +1 -1
  6. package/dist/chunks/{card-filter-builder-CEcKF6Fw.js → card-filter-builder-C8PbhHjq.js} +165 -165
  7. package/dist/chunks/{dashboard-MPku_x1M.js → dashboard-CVj1oMoW.js} +1 -1
  8. package/dist/chunks/{dashboard-briefing-launcher-CkFNlkr1.js → dashboard-briefing-launcher-TqA58rKz.js} +7 -7
  9. package/dist/chunks/{dashboard-controls-Clt4ovXS.js → dashboard-controls-DQ8FsxAz.js} +7 -7
  10. package/dist/chunks/{dashboard-json-DSmXazIg.js → dashboard-json-DM88pmk2.js} +1 -1
  11. package/dist/chunks/dates-5z3b9Loo.js +136 -0
  12. package/dist/chunks/{edit-dashboard-visual-Dn2ECRbX.js → edit-dashboard-visual-BpRnU_6G.js} +2291 -2265
  13. package/dist/chunks/{filter-reach-copy-CmJpPa4G.js → filter-reach-copy-0Xp97cLk.js} +879 -862
  14. package/dist/chunks/{index-0WYn6RMz.js → index-D_QSeVKy.js} +1 -1
  15. package/dist/chunks/{matrix-analytical-definition-QjBgUYhP.js → matrix-analytical-definition-DOVSFFuf.js} +179 -169
  16. package/dist/chunks/{report-preferences-dialog-BRaeufEi.js → report-preferences-dialog-CXKmWyLm.js} +7 -7
  17. package/dist/chunks/{resolve-dashboard-input-context-Cn9jumxl.js → resolve-dashboard-input-context-zEXuitoF.js} +10328 -10237
  18. package/dist/chunks/{saved-dashboard-context-CfqkUMzR.js → saved-dashboard-context-Cll5LipJ.js} +75 -72
  19. package/dist/chunks/{semaphor-ready-indicator-D6WjdTGl.js → semaphor-ready-indicator-Bnj3H0Dm.js} +23983 -23726
  20. package/dist/chunks/{shelf-drop-preview-context-Bbbrr9u4.js → shelf-drop-preview-context-B8rmn6BD.js} +2 -2
  21. package/dist/chunks/{stored-dashboard-sPkTjxYf.js → stored-dashboard-CURqJgoa.js} +600 -595
  22. package/dist/chunks/{variable-draft-D1RotIEG.js → variable-draft-DIv-9y6Q.js} +3 -3
  23. package/dist/chunks/{visual-choice-JiJ-_3bi.js → visual-choice-BBPizkRo.js} +74 -72
  24. package/dist/dashboard/index.js +1 -1
  25. package/dist/dashboard-authoring/index.js +1201 -1182
  26. package/dist/index.js +11 -11
  27. package/dist/style.css +1 -1
  28. package/dist/surfboard/index.js +1 -1
  29. package/dist/types/lib/dashboard-inputs/dashboard-filter-mapping-authoring.d.ts +86 -3
  30. package/dist/types/lib/dashboard-inputs/resolve-selection-input.d.ts +49 -27
  31. package/dist/types/lib/query-context/compile-dashboard-card-filters.d.ts +7 -0
  32. package/dist/types/lib/query-context/dashboard-filter-mapping-resolution.d.ts +30 -2
  33. package/dist/types/lib/types/explorer-types.d.ts +11 -4
  34. package/dist/types/shared/analytics-protocol/click-reach-filter-id.d.ts +9 -0
  35. package/dist/types/shared/analytics-protocol/filter-field-ownership.d.ts +3 -1
  36. package/dist/types/shared/analytics-protocol/index.d.ts +1 -0
  37. package/dist/types/shared/dashboard-authoring/card-settings/card-display-write.d.ts +10 -3
  38. package/dist/types/shared/dashboard-authoring/card-settings/card-kinds.d.ts +1 -1
  39. package/dist/types/shared/dashboard-authoring/card-settings/inputs.d.ts +5 -2
  40. package/dist/types/shared/dashboard-authoring/card-settings/resolved.d.ts +5 -2
  41. package/dist/types/shared/dashboard-authoring/changes/card-query-part.d.ts +1 -0
  42. package/dist/types/shared/dashboard-authoring/click-to-filter-card-decision.d.ts +102 -0
  43. package/dist/types/shared/dashboard-authoring/filter-reach-copy.d.ts +13 -1
  44. package/dist/types/shared/dashboard-authoring/index.d.ts +2 -0
  45. package/dist/types/shared/dashboard-authoring/kpi-figure.d.ts +12 -12
  46. package/dist/types/shared/dashboard-authoring/kpi-trend-rule.d.ts +74 -0
  47. package/dist/types/shared/dashboard-authoring/semantic-auto-join-card.d.ts +13 -0
  48. package/package.json +2 -2
  49. package/dist/chunks/dates-CYZW9owO.js +0 -92
@@ -1,4 +1,4 @@
1
- import { a, R as s, D as o } from "../chunks/report-preferences-dialog-BRaeufEi.js";
1
+ import { a, R as s, D as o } from "../chunks/report-preferences-dialog-CXKmWyLm.js";
2
2
  import { C as f, E as D } from "../chunks/bookmark-state-CL4WEpgB.js";
3
3
  export {
4
4
  f as CONTROL_CARD_DEFAULT_VALUE,
@@ -1,6 +1,6 @@
1
1
  import { TFilter } from '../../components/surfboard/filter/types.js';
2
- import { DashboardInputScope, DataVariable, TCard, TDashboard } from '../types/common-types.js';
3
- import { DashboardFilterApplication, DashboardFilterCardApplication, DashboardFilterRelationshipTarget, DashboardFilterFieldTarget, DashboardFilterTarget, DashboardFilterTargetField, DashboardFilterOptionSource, FilterReachPreviewCard, FilterReachCardPreview, FilterReachPathOption } from '../../shared/dashboard-authoring/index.js';
2
+ import { DashboardInputScope, DataVariable, NormalizedFilterDashboardInput, TCard, TDashboard } from '../types/common-types.js';
3
+ import { DashboardFilterApplication, DashboardFilterCardApplication, DashboardFilterRelationshipTarget, DashboardFilterFieldTarget, DashboardFilterTarget, DashboardFilterTargetField, DashboardFilterOptionSource, FilterReachPreviewCard, FilterReachCardOutcome, FilterReachCardPreview, FilterReachPathOption } from '../../shared/dashboard-authoring/index.js';
4
4
  import { SemaphorRelationshipRoute, SemaphorSkippedConstraintReason } from '../../shared/analytics-protocol/index.js';
5
5
  import { FilterRef, ReachedCard } from '../../shared/dashboard-authoring/filter-model/index.js';
6
6
  /**
@@ -59,6 +59,15 @@ export type DashboardFilterCardOutcome =
59
59
  kind: 'appliesThroughPath';
60
60
  route: SemaphorRelationshipRoute;
61
61
  }
62
+ /**
63
+ * A click through the domain's relationships where the preview, asked as a
64
+ * toolbar filter, names no route (it keeps the value's dataset, or the
65
+ * filter wouldn't take that card's relationships): the click still follows
66
+ * them (click relationship reach CR-D16).
67
+ */
68
+ | {
69
+ kind: 'appliesThroughRelationships';
70
+ }
62
71
  /** The card's query already uses the value's dataset, so no path is needed (ledger R-05). */
63
72
  | {
64
73
  kind: 'appliesOnOwnData';
@@ -138,7 +147,7 @@ export type DashboardFilterCardState = {
138
147
  outcome: Extract<DashboardFilterCardOutcome, {
139
148
  kind: 'appliesOnField';
140
149
  how: 'automatic' | 'sql';
141
- }> | OutcomeOf<'appliesThroughPath' | 'appliesOnOwnData' | 'needsPath' | 'needsField' | 'notApplied' | 'blocked' | 'checking' | 'unavailable'>;
150
+ }> | OutcomeOf<'appliesThroughPath' | 'appliesThroughRelationships' | 'appliesOnOwnData' | 'needsPath' | 'needsField' | 'notApplied' | 'blocked' | 'checking' | 'unavailable'>;
142
151
  } | {
143
152
  decision: Extract<DashboardFilterCardDecision, {
144
153
  kind: 'field';
@@ -169,6 +178,15 @@ export type DashboardFilterMappingRowState = 'pendingSource' | 'automatic' | 'su
169
178
  /** Where a row's card is. */
170
179
  /** The Cards tab's Variables band: a reserved group id no sheet has (data variables DV-D35, 1b). */
171
180
  export declare const VARIABLES_MAPPING_GROUP_ID = "__variables__";
181
+ type DashboardFilterMappingRowLocation = {
182
+ /** A data variable's row: the target is the variable, `card` its projected card. */
183
+ variable?: DataVariable;
184
+ card: TCard;
185
+ sheetId: string;
186
+ sheetKind: 'dashboard' | 'document';
187
+ sectionId?: string;
188
+ sectionTitle?: string;
189
+ };
172
190
  /**
173
191
  * One card in the Cards tab: the author's decision and what runs for it
174
192
  * (`DashboardFilterCardState`), made only by `cardRow`. Every reader (the
@@ -237,6 +255,10 @@ export type DashboardFilterAutoDescription = {
237
255
  } | {
238
256
  kind: 'route';
239
257
  route: SemaphorRelationshipRoute;
258
+ }
259
+ /** A click that follows the domain's relationships on a route the preview doesn't name (CR-D16). */
260
+ | {
261
+ kind: 'throughRelationships';
240
262
  } | {
241
263
  kind: 'ownData';
242
264
  } | {
@@ -500,7 +522,11 @@ export declare function buildDashboardFilterMappingDraftRowForValueField(params:
500
522
  borrowedTarget?: DashboardFilterFieldTarget;
501
523
  /** What a card with no matching field gets (`cardRow`'s `unmatchedField`). */
502
524
  unmatchedField?: 'choose' | 'notApplied';
525
+ /** The card reaches the value's dataset through the domain's relationships (`cardRow`'s `relationship`). */
526
+ relationship?: Parameters<typeof cardRow>[0]['relationship'];
503
527
  }): DashboardFilterMappingDraftRow;
528
+ /** The server's answer for a card's decision. */
529
+ type CardReachAnswer = FilterReachCardOutcome;
504
530
  /** The decision that saves a target the author picked: a field, or a path. */
505
531
  export declare function dashboardFilterCardDecisionForTarget(target: DashboardFilterTarget): DashboardFilterCardDecision;
506
532
  /**
@@ -512,6 +538,63 @@ export declare function draftCardDecision(staged: DashboardFilterCardDecision |
512
538
  decision: DashboardFilterCardDecision;
513
539
  origin: DashboardFilterDecisionOrigin;
514
540
  };
541
+ /**
542
+ * One card's row: its decision and what runs for it, decided in one place
543
+ * for every pair (relationship filter reach S-D, RF-INV-14); each return is
544
+ * a typed pair, so no other pair can be made. The card's source comes
545
+ * first, then the decision: "Don't apply", a chosen path (the server's
546
+ * answer for it), a bound field, and Auto: the server's answer on a card the
547
+ * domain's relationships reach, then the card's fields when it skips.
548
+ * Surfaces that differ (a click) pass their differences in as inputs.
549
+ */
550
+ declare function cardRow(params: {
551
+ location: DashboardFilterMappingRowLocation;
552
+ executionKind: DashboardFilterMappingDraftRow['executionKind'];
553
+ filter: TFilter;
554
+ card: TCard;
555
+ catalog: DashboardFilterMappingCandidateCatalog | undefined;
556
+ selectionField: (Pick<DashboardFilterTargetField, 'name' | 'sourceField'> & Partial<Pick<DashboardFilterTargetField, 'source'>>) | undefined;
557
+ automaticSelectionSources?: DashboardFilterTargetField['source'][];
558
+ selectionDataType?: string;
559
+ decision: DashboardFilterCardDecision;
560
+ origin: DashboardFilterDecisionOrigin;
561
+ persistedApplication: DashboardFilterCardApplication | undefined;
562
+ acceptedTargets: DashboardFilterTarget[];
563
+ revalidatePersistedTarget: boolean;
564
+ /**
565
+ * The card runs the filter through the domain's relationships when it has
566
+ * no entry (the card target decision says `relationship`, row 7r), and
567
+ * the server's answer for it and its tied paths, once they came.
568
+ */
569
+ relationship?: {
570
+ candidate: boolean;
571
+ answer?: CardReachAnswer;
572
+ paths: FilterReachPathOption[];
573
+ /** The preview request failed (ledger R-08). */
574
+ failed?: boolean;
575
+ /**
576
+ * A click's row (click relationship reach CR-D9, CR-D16): no path can be
577
+ * chosen, so a tie is a skip, as the server skips a click's value with no
578
+ * route; and an answer only a toolbar filter gets (`kept`,
579
+ * `notRelationship`) still means the click follows the relationships.
580
+ */
581
+ forClick?: true;
582
+ };
583
+ /** The filter input as the draft stands, for a chosen path's value field (ledger R-12). */
584
+ input?: NormalizedFilterDashboardInput;
585
+ /**
586
+ * A binding a filter already accepted for this value field on the card:
587
+ * Auto applies it before matching on its own, as the click runtime does,
588
+ * and blocks when it no longer fits the card (ledger R-27).
589
+ */
590
+ borrowedTarget?: DashboardFilterFieldTarget;
591
+ /**
592
+ * A card with fields, none of which matches the value field: a choice for
593
+ * a filter that reaches it ('choose', the default), or a field a click
594
+ * drops ('notApplied': a click carries several and a card matches only some).
595
+ */
596
+ unmatchedField?: 'choose' | 'notApplied';
597
+ }): DashboardFilterMappingDraftRow;
515
598
  /**
516
599
  * What a row shows, counts as and offers, read from its decision and
517
600
  * outcome only (relationship filter reach S-D, RF-INV-14).
@@ -1,20 +1,24 @@
1
- import { SelectionField, SelectionInputValue } from '../../shared/analytics-protocol/selection-contract.js';
2
- import { DashboardFilterFieldTarget } from '../../shared/dashboard-authoring/index.js';
3
- import { ScopedDashboardInputTarget } from '../../shared/dashboard-authoring/dashboard-input-scope.js';
1
+ import { SelectionCondition, SelectionField, SelectionInputValue } from '../../shared/analytics-protocol/selection-contract.js';
2
+ import { ClickToFilterBlockReason, ClickToFilterCardSkipReason, ClickToFilterTargetLocation, DashboardFilterFieldTarget } from '../../shared/dashboard-authoring/index.js';
3
+ import { TFilterValue } from '../../components/surfboard/filter/types.js';
4
4
  import { NormalizedFilterDashboardInput, SelectionDashboardInput, TCard } from '../types/common-types.js';
5
5
  import { FilterCondition } from '../types/explorer-types.js';
6
- export type SelectionSkipReason =
7
- /** A card never filters itself. */
8
- 'sourceCard'
9
- /** card.respondsToSelections === false */
10
- | 'receiverOptedOut'
11
- /** settings.targets does not include the card */
12
- | 'outsideTargets'
6
+ /**
7
+ * Why a related clicked field leaves every tuple on a card it would reach
8
+ * through relationships: a shape one filter value per field can't say
9
+ * (click relationship reach CR-D6).
10
+ */
11
+ export type SelectionRelationshipNotAppliedReason =
12
+ /** Several clicked rows, and more than one field applies on this card: an OR of rows. */
13
+ 'severalRowsAcrossFields'
14
+ /** A (Blank) value: the source's (Blank) row counts rows with no related row, which a semi-join can't keep. */
15
+ | 'blankAcrossRelationship'
16
+ /** A clicked bucket, several date-times, or several dates on a date-time column. */
17
+ | 'datePeriodAcrossRelationship';
18
+ export type SelectionSkipReason = ClickToFilterCardSkipReason
13
19
  /** An 'excluded' card mapping */
14
- | 'excludedCard'
15
- /** No automatic, bound, or borrowed target */
16
- | 'notApplicable';
17
- export type SelectionBlockReason = 'ambiguousAutomaticTarget' | 'staleBinding' | 'incompatibleValueType';
20
+ | 'excludedCard' | SelectionRelationshipNotAppliedReason;
21
+ export type SelectionBlockReason = ClickToFilterBlockReason;
18
22
  /** What one clicked field does on one target card. */
19
23
  export type SelectionConditionDisposition = {
20
24
  status: 'apply';
@@ -23,6 +27,15 @@ export type SelectionConditionDisposition = {
23
27
  provenance: 'automatic' | 'bound' | 'borrowedFromFilter';
24
28
  /** Set when provenance is 'borrowedFromFilter'. */
25
29
  borrowedFromInputId?: string;
30
+ }
31
+ /**
32
+ * The card reaches the clicked field's dataset through the domain's
33
+ * relationships: the field is one of `filterValues`, and the server decides
34
+ * the route and reports it in `filterReach` (CR-D8). Never a condition.
35
+ */
36
+ | {
37
+ status: 'relationship';
38
+ clickedFieldKey: string;
26
39
  } | {
27
40
  status: 'skip';
28
41
  clickedFieldKey: string;
@@ -39,31 +52,38 @@ export type ResolvedCardSelection = {
39
52
  tuples: Array<{
40
53
  conditions: FilterCondition[];
41
54
  }>;
55
+ /**
56
+ * One dashboard filter value per clicked field the card reaches through
57
+ * relationships (CR-D4, CR-D5): the card's filter compiler appends them,
58
+ * and the server runs them as it runs a toolbar filter's.
59
+ */
60
+ filterValues: TFilterValue[];
42
61
  /** One per distinct clicked field in the value, in first-seen order. */
43
62
  dispositions: SelectionConditionDisposition[];
44
- /** 'apply' when at least one tuple survived projection. */
63
+ /** 'apply' when a tuple survived projection or a filter value was made. */
45
64
  status: 'apply' | 'skip';
46
65
  };
47
66
  /** Where the target card sits. `cardId` always comes from the card itself. */
48
- export type SelectionTargetLocation = Omit<ScopedDashboardInputTarget, 'cardId'>;
67
+ export type SelectionTargetLocation = ClickToFilterTargetLocation;
49
68
  /**
50
- * The binding a toolbar filter already accepted for the clicked field on this
51
- * card. Runtime and authoring both read it here, so "Same as the Region
52
- * filter" in the review dialog is exactly what a click will borrow.
69
+ * A clicked field's filter value on a card that reaches it through
70
+ * relationships: the toolbar's value on that field (`=` one value, `in`
71
+ * several), under the click's own id. The runtime sends it; the click review
72
+ * previews the same field with it (CR-D16), so both ask the server one thing.
53
73
  */
54
- export declare function findBorrowedSelectionBinding(params: {
55
- cardId: string;
74
+ export declare function clickReachFilterValue(params: {
75
+ input: Pick<SelectionDashboardInput, 'sourceCardId' | 'label'>;
56
76
  clicked: SelectionField;
57
- filterInputs: NormalizedFilterDashboardInput[];
58
- }): {
59
- inputId: string;
60
- target: DashboardFilterFieldTarget;
61
- } | undefined;
77
+ values: ReadonlyArray<string | number>;
78
+ rawTemporal?: SelectionCondition['rawTemporal'];
79
+ }): TFilterValue;
62
80
  /**
63
81
  * Decides what one source card's selection does on one target card. A viewer's
64
82
  * click must never take a card down: a blocked condition is dropped exactly
65
83
  * like a skipped one, and its disposition is kept so authoring can show why.
66
- * Tuple shape is preserved, so two rows stay (A AND B) OR (C AND D).
84
+ * Tuple shape is preserved, so two rows stay (A AND B) OR (C AND D). A field
85
+ * the card reaches through relationships leaves the tuples and becomes one
86
+ * filter value (CR-D4).
67
87
  */
68
88
  export declare function resolveSelectionInputForCard(params: {
69
89
  /** The target card. */
@@ -74,4 +94,6 @@ export declare function resolveSelectionInputForCard(params: {
74
94
  value: SelectionInputValue;
75
95
  /** Toolbar filters, for borrowed bindings. */
76
96
  filterInputs: NormalizedFilterDashboardInput[];
97
+ /** A carried click (drill-through, an insight): never through relationships (RF-D17). */
98
+ requireFieldProof?: boolean;
77
99
  }): ResolvedCardSelection;
@@ -19,6 +19,13 @@ export type DashboardCardFilterCompilationInput = {
19
19
  adHocFilterValues: TFilterValue[];
20
20
  selectedSheetId: string | null | undefined;
21
21
  inlineFilterValues: TFilterValue[];
22
+ /**
23
+ * The filter values of clicked fields that reach this card through the
24
+ * domain's relationships, from every selection on it (click relationship
25
+ * reach CR-D5). Appended whatever the dashboard's inputs or a carried
26
+ * context: a click made here narrows the card as its chip says.
27
+ */
28
+ selectionFilterValues?: TFilterValue[];
22
29
  shouldApplyDashboardFilters: boolean;
23
30
  dashboardInputContext?: DashboardFilterCompilationContext;
24
31
  globalDateComparisonSelection?: GlobalDateComparisonSelection;
@@ -1,7 +1,7 @@
1
- import { TFilterValue } from '../../components/surfboard/filter/types.js';
1
+ import { StoredRelativeDate, TemporalPrecision, TFilterValue } from '../../components/surfboard/filter/types.js';
2
2
  import { NormalizedFilterDashboardInput, ResolvedDashboardInput, TCard } from '../types/common-types.js';
3
3
  import { DashboardFilterLogicalValueField, DashboardFilterFieldTarget, DashboardFilterTargetField, DashboardFilterTargetSource, buildDashboardCardSourceIndex } from '../../shared/dashboard-authoring/index.js';
4
- import { SemaphorRelationshipRoute, SemaphorSkippedConstraintReason } from '../../shared/analytics-protocol/index.js';
4
+ import { SemaphorRelationshipRoute, SemaphorSkippedConstraintReason, TemporalBucketMetadata } from '../../shared/analytics-protocol/index.js';
5
5
  import { Field } from '../types/explorer-types.js';
6
6
  export type DashboardFilterMappingSkipReason = 'outsideScope' | 'noSelection' | 'explicitlyExcluded' | 'notApplicable';
7
7
  export type DashboardFilterMappingBlockReason = 'ambiguousAutomaticTarget' | 'staleBinding' | 'invalidSelection' | 'incompatibleValueType' | 'unsupportedTarget';
@@ -30,6 +30,23 @@ export type DashboardFilterMappingResolution = {
30
30
  status: 'blocked';
31
31
  dispositions: DashboardFilterMappingDisposition[];
32
32
  };
33
+ type MappedFilterTemporalMetadata = {
34
+ relativeMeta?: StoredRelativeDate;
35
+ temporalPrecision?: TemporalPrecision;
36
+ temporalBucket?: TemporalBucketMetadata;
37
+ rawTemporal?: TFilterValue['rawTemporal'];
38
+ };
39
+ export type MappedFilterSelection = ({
40
+ filterId: TFilterValue['filterId'];
41
+ operation: 'is null' | 'is not null';
42
+ values: [];
43
+ } | {
44
+ filterId: TFilterValue['filterId'];
45
+ operation: Exclude<TFilterValue['operation'], 'is null' | 'is not null'>;
46
+ values: Exclude<TFilterValue, {
47
+ operation: 'is null' | 'is not null';
48
+ }>['values'];
49
+ }) & MappedFilterTemporalMetadata;
33
50
  /**
34
51
  * The explorer field a `FilterCondition` needs to address a mapping target.
35
52
  * Entity identity comes from the same source projection mapped toolbar filters
@@ -37,6 +54,16 @@ export type DashboardFilterMappingResolution = {
37
54
  * grounded executable source when validation returned one.
38
55
  */
39
56
  export declare function explorerFieldFromMappingTarget(target: DashboardFilterFieldTarget, source?: DashboardFilterTargetField['source']): Field;
57
+ /**
58
+ * A filter value on a field target, as the server reads a toolbar filter's:
59
+ * the mapped toolbar value, and a click on a related field (click
60
+ * relationship reach CR-D5), which passes the clicked column's database type.
61
+ */
62
+ export declare function materializeMappedFilterValue(selection: MappedFilterSelection, target: DashboardFilterFieldTarget, source: DashboardFilterTargetField['source'],
63
+ /** The input's title, carried for describing the condition (P3-100). */
64
+ label: string | undefined, executionIdentifier?: string,
65
+ /** The column's database type, when the value comes from that same column. */
66
+ nativeDataType?: string): TFilterValue;
40
67
  /** Date and datetime are interchangeable; every other type must match exactly. */
41
68
  export declare function dashboardFilterDataTypesAreCompatible(sourceType: string, targetType: DashboardFilterTargetField['dataType']): boolean;
42
69
  /**
@@ -231,3 +258,4 @@ export declare function resolveDashboardFilterMappings({ card, inputs, resolvedI
231
258
  activeFilterValues?: TFilterValue[];
232
259
  shouldApplyDashboardFilters: boolean;
233
260
  }): DashboardFilterMappingResolution;
261
+ export {};
@@ -620,11 +620,18 @@ export interface CardConfig {
620
620
  breakdownDimensions?: GroupByField[];
621
621
  };
622
622
  /**
623
- * A KPI's band (KPI tile layout KL-D29): `trend` shows the value's last
624
- * periods under it, `none` shows nothing; absent, the band follows the
625
- * card's summary and target. Written by `writeKpiBand`.
623
+ * A KPI's Trend switch (KPI trend window KT-D16): `trend` draws the value's
624
+ * trend under it; absent, the band follows the card's summary and target.
625
+ * Written by `writeKpiTrend`.
626
626
  */
627
- kpiBand?: 'trend' | 'none';
627
+ kpiBand?: 'trend';
628
+ /**
629
+ * The grain of a KPI's trend when it has no Trend By (KPI trend window
630
+ * KT-D2): absent is Automatic, picked from the period the KPI counts. A
631
+ * Trend By's own grain wins over it. Read by the server's trend; its writer
632
+ * comes with the editor's Grain control (KT-D12).
633
+ */
634
+ kpiTrendGrain?: 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
628
635
  rowAggregates?: Array<{
629
636
  label?: string;
630
637
  function: AggregateFunction;
@@ -0,0 +1,9 @@
1
+ import { SelectionField } from './selection-contract.js';
2
+ /**
3
+ * The filter id of a clicked field that reaches a card through relationships
4
+ * (CR-D5): one per source card and clicked field, short enough for usage
5
+ * telemetry. The compiler writes it; filter info looks the reach up by it.
6
+ */
7
+ export declare function clickReachFilterId(sourceCardId: string, clicked: SelectionField): string;
8
+ /** Whether a compiled filter value is a click's, never a dashboard input's (CR-D15, CR-INV-10). */
9
+ export declare function isClickReachFilterId(filterId: string | undefined): boolean;
@@ -36,7 +36,9 @@ export declare function unconditionalConditions(filters: FilterGroup | null | un
36
36
  * same object when nothing is owned. Pass only the filter values that apply
37
37
  * to the card. A value with no qualified identity (a dashboard filter by
38
38
  * column) is applied by its column name, so it owns the card's field of that
39
- * name.
39
+ * name. A click's value on a related field owns nothing: a click is
40
+ * transient, and must never remove a saved condition (click relationship
41
+ * reach CR-D15).
40
42
  */
41
43
  export declare function withDashboardFilterOwnership<T extends {
42
44
  filters?: FilterGroup | null;
@@ -15,6 +15,7 @@ export * from './fixtures.js';
15
15
  export * from './metric-comparison.js';
16
16
  export * from './applied-constraints.js';
17
17
  export * from './filter-field-ownership.js';
18
+ export * from './click-reach-filter-id.js';
18
19
  export * from './sort-target.js';
19
20
  export * from './dashboard-date-comparison-definition.js';
20
21
  export * from './dashboard-input-contract.js';
@@ -1,3 +1,4 @@
1
+ import { KpiTrendGrain } from '../kpi-trend-rule.js';
1
2
  import { TChartType } from '../../../lib/charts/types.js';
2
3
  import { AxisConfig, TCard, TCardPreferences, TLegendOptions } from '../../../lib/types/common-types.js';
3
4
  import { SemaphorValueFormat } from '../../analytics-protocol/contracts.js';
@@ -30,10 +31,16 @@ export declare function writeChartOrientation<T extends Pick<TCard, 'type' | 'pr
30
31
  */
31
32
  export declare function writeCardVariant<T extends Pick<TCard, 'type' | 'preferences'>>(card: T, variant: CardVariant): T;
32
33
  /**
33
- * A KPI's band (KPI tile layout KL-D29), as the KPI settings' band control
34
- * writes it: `trend` or `none`, or null for Automatic, which stores nothing.
34
+ * A KPI's Trend switch (KPI trend window KT-D16), as the editor's switch and
35
+ * the MCP's `trend` write it: on stores `kpiBand: 'trend'`, off stores nothing.
35
36
  */
36
- export declare function writeKpiBand<T extends Pick<TCard, 'config'>>(card: T, band: 'trend' | 'none' | null): T;
37
+ export declare function writeKpiTrend<T extends Pick<TCard, 'config'>>(card: T, on: boolean): T;
38
+ /**
39
+ * A KPI trend's grain when it has no Trend By (KPI trend window KT-D2,
40
+ * KT-D12), as the editor's Grain control and the MCP's `trendGrain` write it:
41
+ * a grain, or null for Automatic, which stores nothing.
42
+ */
43
+ export declare function writeKpiTrendGrain<T extends Pick<TCard, 'config'>>(card: T, grain: KpiTrendGrain | null): T;
37
44
  /**
38
45
  * A config table's totals (table overall totals OT-D16): the row on or off,
39
46
  * and each named measure's total, keyed by its result alias. Overall is the
@@ -1,6 +1,6 @@
1
1
  import { TCard } from '../../../lib/types/common-types.js';
2
2
  import { CardType } from '../changes/card-types.js';
3
- export type SettingName = 'columns.label' | 'columns.format' | 'columns.hidden' | 'columns.width' | 'orientation' | 'stack' | 'donut' | 'totals' | 'dataLabels' | 'legend' | 'axes' | 'highlights' | 'columns.polarity' | 'comparisonDisplay' | 'inheritComparison' | 'band' | 'seeRecords';
3
+ export type SettingName = 'columns.label' | 'columns.format' | 'columns.hidden' | 'columns.width' | 'orientation' | 'stack' | 'donut' | 'totals' | 'dataLabels' | 'legend' | 'axes' | 'highlights' | 'columns.polarity' | 'comparisonDisplay' | 'inheritComparison' | 'trend' | 'trendGrain' | 'seeRecords';
4
4
  export declare const SETTINGS_BY_KIND: Readonly<Record<CardType, readonly SettingName[]>>;
5
5
  export type CardSettingsKind = {
6
6
  type: CardType;
@@ -1,3 +1,4 @@
1
+ import { KpiTrendGrain } from '../kpi-trend-rule.js';
1
2
  import { MetricComparisonPolarity } from '../../analytics-protocol/metric-comparison.js';
2
3
  import { TableColumnTotal } from '../measure-calculations/table-column-total.js';
3
4
  import { SemaphorDateValueFormat, SemaphorDurationValueFormat, SemaphorNumericValueFormat, SemaphorValueFormat, TemporalBucketFormat } from '../../analytics-protocol/contracts.js';
@@ -74,8 +75,10 @@ export type CardSettingsInput = {
74
75
  comparisonDisplay?: ComparisonDisplayInput;
75
76
  /** false: measures without a comparison of their own ignore the dashboard's; true removes the stored opt-out (RC-D16). */
76
77
  inheritComparison?: boolean;
77
- /** A KPI's band (KPI tile layout KL-D29): `trend` needs a Trend By; `automatic` follows the summary and target. */
78
- band?: 'automatic' | 'trend' | 'none';
78
+ /** A KPI's Trend switch (KPI trend window KT-D16): on draws its trend on the date it counts (KT-D1); off follows the summary and target. */
79
+ trend?: boolean;
80
+ /** A KPI trend's grain when it has no Trend By (KT-D2, KT-D12): `automatic` fits it to the period the KPI counts. */
81
+ trendGrain?: 'automatic' | KpiTrendGrain;
79
82
  /** false: viewers can't open the records behind the card's numbers; true removes the stored opt-out (see-records SR-D4). */
80
83
  seeRecords?: boolean;
81
84
  };
@@ -1,3 +1,4 @@
1
+ import { KpiTrendGrain } from '../kpi-trend-rule.js';
1
2
  import { SemaphorValueFormat } from '../../analytics-protocol/contracts.js';
2
3
  import { CardColumnRef, ConditionalRule } from '../conditional-formatting/types.js';
3
4
  import { AxisConfigKey, CardVariant } from './card-display-write.js';
@@ -51,8 +52,10 @@ export type ResolvedCardSettings = {
51
52
  comparisonDisplay?: ResolvedComparisonDisplay;
52
53
  /** Whether measures without a comparison of their own follow the dashboard's (RC-D16). */
53
54
  inheritComparison?: boolean;
54
- /** A KPI's band (KL-D29); null returns it to Automatic. */
55
- band?: 'trend' | 'none' | null;
55
+ /** A KPI's Trend switch (KT-D16). */
56
+ trend?: boolean;
57
+ /** A KPI trend's grain (KT-D12); null returns it to Automatic. */
58
+ trendGrain?: KpiTrendGrain | null;
56
59
  /** Whether viewers can open the records behind the card's numbers (see-records SR-D4). */
57
60
  seeRecords?: boolean;
58
61
  };
@@ -153,6 +153,7 @@ export declare const CARD_CONFIG_KEY_CLASSES: {
153
153
  readonly detailTableBackup: "presentation";
154
154
  readonly summary: "presentation";
155
155
  readonly kpiBand: "presentation";
156
+ readonly kpiTrendGrain: "presentation";
156
157
  readonly rowAggregates: "presentation";
157
158
  readonly columnAggregates: "presentation";
158
159
  };
@@ -0,0 +1,102 @@
1
+ import { SelectionField } from '../analytics-protocol/selection-contract.js';
2
+ import { NormalizedFilterDashboardInput, SelectionDashboardInput, TCard } from '../../lib/types/common-types.js';
3
+ import { DashboardCardFilterSourceInventory } from './dashboard-card-source-index.js';
4
+ import { DashboardFilterFieldTarget } from './dashboard-filter-mapping-types.js';
5
+ import { ScopedDashboardInputTarget } from './dashboard-input-scope.js';
6
+ /**
7
+ * What a click does on a card, decided once (click relationship reach
8
+ * CR-D14): the runtime (`resolveSelectionInputForCard`) and the click review
9
+ * read the same answer, so the review can never promise what a click won't do.
10
+ */
11
+ /** Why a card takes nothing from a click, before any field is looked at. */
12
+ export type ClickToFilterCardSkipReason =
13
+ /** A card never filters itself. */
14
+ 'sourceCard'
15
+ /** `card.respondsToSelections === false` */
16
+ | 'receiverOptedOut'
17
+ /** `settings.targets` does not reach the card. */
18
+ | 'outsideTargets'
19
+ /** SQL and unconfigured cards: a click compiles to conditions and values only config cards run. */
20
+ | 'notApplicable';
21
+ export type ClickToFilterBlockReason = 'ambiguousAutomaticTarget' | 'staleBinding' | 'incompatibleValueType';
22
+ /** Where the target card sits. `cardId` always comes from the card itself. */
23
+ export type ClickToFilterTargetLocation = Omit<ScopedDashboardInputTarget, 'cardId'>;
24
+ export type ClickToFilterCardLevelDecision = {
25
+ status: 'listening';
26
+ }
27
+ /** An 'excluded' card mapping: the author chose "Don't apply to this card". */
28
+ | {
29
+ status: 'excluded';
30
+ } | {
31
+ status: 'skip';
32
+ reason: ClickToFilterCardSkipReason;
33
+ };
34
+ export type ClickToFilterFieldDecision =
35
+ /** The clicked field applies to a field of the card's own data. */
36
+ {
37
+ status: 'field';
38
+ target: DashboardFilterFieldTarget;
39
+ provenance: 'automatic' | 'bound' | 'borrowedFromFilter';
40
+ /** Set when provenance is 'borrowedFromFilter'. */
41
+ borrowedFromInputId?: string;
42
+ }
43
+ /**
44
+ * The card executes no source of the clicked field's dataset but plans
45
+ * joins in its domain: the clicked field travels as a filter value and the
46
+ * server decides the route (CR-D1, row 7r).
47
+ */
48
+ | {
49
+ status: 'relationship';
50
+ } | {
51
+ status: 'excluded';
52
+ } | {
53
+ status: 'skip';
54
+ reason: ClickToFilterCardSkipReason;
55
+ } | {
56
+ status: 'block';
57
+ reason: ClickToFilterBlockReason;
58
+ /** Set when a toolbar filter's binding blocks: the review shows that field as invalid. */
59
+ borrowed?: {
60
+ inputId: string;
61
+ target: DashboardFilterFieldTarget;
62
+ };
63
+ };
64
+ type ClickInput = Pick<SelectionDashboardInput, 'sourceCardId' | 'settings'>;
65
+ /** The card-level steps: the source card, the receiver's opt-out, the targets, the author's exclusion, the card kind. */
66
+ export declare function decideClickToFilterCardLevel(params: {
67
+ card: TCard;
68
+ location: ClickToFilterTargetLocation;
69
+ input: ClickInput;
70
+ sourceIndex?: DashboardCardFilterSourceInventory;
71
+ }): ClickToFilterCardLevelDecision;
72
+ /**
73
+ * The binding a toolbar filter already accepted for the clicked field on this
74
+ * card. Runtime and authoring both read it here, so "Same as the Region
75
+ * filter" in the review dialog is exactly what a click will borrow.
76
+ */
77
+ export declare function findBorrowedSelectionBinding(params: {
78
+ cardId: string;
79
+ clicked: SelectionField;
80
+ filterInputs: NormalizedFilterDashboardInput[];
81
+ }): {
82
+ inputId: string;
83
+ target: DashboardFilterFieldTarget;
84
+ } | undefined;
85
+ /**
86
+ * One clicked field on one card, in order: the card-level steps, the
87
+ * author's binding, a binding a toolbar filter accepted, the automatic match
88
+ * on the card's own copy of the clicked dataset, then the domain's
89
+ * relationships (CR-D1). A carried click (drill-through, an insight) needs
90
+ * field proof, so it never reaches a card through relationships (RF-D17).
91
+ */
92
+ export declare function decideClickToFilterField(params: {
93
+ card: TCard;
94
+ location: ClickToFilterTargetLocation;
95
+ input: ClickInput;
96
+ clicked: SelectionField;
97
+ /** Toolbar filters, for borrowed bindings. */
98
+ filterInputs: NormalizedFilterDashboardInput[];
99
+ requireFieldProof?: boolean;
100
+ sourceIndex?: DashboardCardFilterSourceInventory;
101
+ }): ClickToFilterFieldDecision;
102
+ export {};
@@ -1,4 +1,4 @@
1
- import { SemaphorRelationshipRoute, SemaphorSkippedConstraintReason } from '../analytics-protocol/index.js';
1
+ import { SemaphorFilterReachEntry, SemaphorRelationshipRoute, SemaphorSkippedConstraintReason } from '../analytics-protocol/index.js';
2
2
  /** "Project" to "Projects", "Category" to "Categories"; a label ending in "s" stays. */
3
3
  export declare function pluralDatasetLabel(label: string): string;
4
4
  /**
@@ -16,3 +16,15 @@ export declare function describeRelationshipSkip(reason: SemaphorSkippedConstrai
16
16
  name: string;
17
17
  label?: string;
18
18
  }): string;
19
+ /** A line under a filter in the card's filter info: muted, or asking for attention. */
20
+ export type FilterReachNote = {
21
+ text: string;
22
+ tone: 'muted' | 'attention';
23
+ };
24
+ /**
25
+ * The server's word on a filter for this card (RF-D13): applied through
26
+ * relationships, left out, or blocked. A toolbar filter and a click on a
27
+ * related field read their entries the same way (click relationship reach
28
+ * CR-D12). None for a value applied on the card's own data.
29
+ */
30
+ export declare function describeFilterReachEntry(entry: SemaphorFilterReachEntry | undefined): FilterReachNote | undefined;
@@ -22,6 +22,7 @@ export * from './card-reference-remapping.js';
22
22
  export * from './apply-group-by-override.js';
23
23
  export * from './click-to-filter-settings.js';
24
24
  export * from './linked-click-to-filter-overrides.js';
25
+ export * from './click-to-filter-card-decision.js';
25
26
  export * from './matrix-definition.js';
26
27
  export * from './matrix-authoring.js';
27
28
  export * from './field-aggregations.js';
@@ -56,6 +57,7 @@ export * from './card-formats/sql-date-pattern.js';
56
57
  export * from './retired-presentation-fields.js';
57
58
  export * from './conditional-formatting/index.js';
58
59
  export * from './kpi-figure.js';
60
+ export * from './kpi-trend-rule.js';
59
61
  export * from './kpi-date-context.js';
60
62
  export * from './see-records/index.js';
61
63
  export * from './card-settings/index.js';