@microsoft/rayfin-semantic-model-pack 1.0.0 → 2.0.0

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 (41) hide show
  1. package/CHANGELOG +8 -0
  2. package/README.md +34 -10
  3. package/kit/hooks/use-query-factory-target.spec.ts +191 -0
  4. package/kit/hooks/use-query-factory-target.ts +123 -0
  5. package/{skills/analytics/kit → kit}/hooks/use-semantic-model-query.spec.ts +59 -23
  6. package/{skills/analytics/kit → kit}/hooks/use-semantic-model-query.ts +30 -54
  7. package/kit/lib/query-factory.spec.ts +97 -0
  8. package/kit/lib/query-factory.ts +68 -0
  9. package/kit/lib/semantic-model-errors.spec.ts +131 -0
  10. package/kit/lib/semantic-model-errors.ts +110 -0
  11. package/kit/lib/to-data-table.spec.ts +444 -0
  12. package/kit/lib/to-data-table.ts +221 -0
  13. package/pack.json +141 -0
  14. package/package.json +3 -1
  15. package/skills/analytics/SKILL.md +126 -421
  16. package/skills/dax-authoring/SKILL.md +99 -34
  17. package/skills/query-design/SKILL.md +22 -29
  18. package/skills/query-design/references/anti-patterns.md +13 -11
  19. package/skills/query-design/references/format-strings.md +6 -12
  20. package/skills/query-design/references/multi-grain-patterns.md +121 -108
  21. package/skills/schema-discovery/SKILL.md +197 -368
  22. package/skills/schema-discovery/references/discovery-queries.md +6 -8
  23. package/skills/visual-interactivity/SKILL.md +68 -0
  24. package/skills/visual-interactivity/references/advanced-query-shapes.md +155 -0
  25. package/skills/visual-interactivity/references/filter-aware-grid-totals.md +101 -0
  26. package/skills/visual-interactivity/references/highlight-queries.md +88 -0
  27. package/skills/visual-interactivity/references/interaction-manager.md +127 -0
  28. package/skills/visual-interactivity/references/native-selections.md +20 -0
  29. package/skills/visual-interactivity/references/query-factories.md +169 -0
  30. package/skills/analytics/kit/lib/connectors.ts +0 -94
  31. package/skills/analytics/kit/scripts/rayfin-connector.mjs +0 -265
  32. package/skills/analytics/kit/scripts/rayfin-connector.test.mjs +0 -243
  33. package/skills/analytics/kit/scripts/schema-sql-batch.test.mjs +0 -2097
  34. package/skills/analytics/kit/scripts/schema-sql-cli.test.mjs +0 -488
  35. package/skills/analytics/kit/scripts/schema-sql.mjs +0 -2650
  36. package/skills/analytics/kit/scripts/schema-sql.test.mjs +0 -1387
  37. package/skills/analytics/kit/scripts/schema.mjs +0 -166
  38. package/skills/analytics/kit/scripts/schema.test.mjs +0 -271
  39. package/skills/analytics/pack.json +0 -49
  40. package/skills/query-design/references/filter-strategy.md +0 -68
  41. package/skills/query-design/references/highlight-queries.md +0 -122
package/CHANGELOG CHANGED
@@ -5,6 +5,14 @@ All notable changes to `@microsoft/rayfin-semantic-model-pack` will be documente
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## 2.0.0 - 2026-11-11
9
+
10
+ - [Rayfin Packs] Unify Lyra skills in shared rayfin pack npm packages
11
+
12
+ ## 1.1.0 - 2026-11-05
13
+
14
+ - [Rayfin Packs] Update semantic-model and visuals packs with data-app template fixes
15
+
8
16
  ## 1.0.0 - Initial release
9
17
 
10
18
  - Add the `analytics` capability pack and the `dax-authoring`, `query-design`, and `schema-discovery` skills.
package/README.md CHANGED
@@ -8,39 +8,63 @@ Agent skills and starter code for Power BI semantic-model analytics in Rayfin ap
8
8
  > **Purpose**: Capability pack that teaches a coding agent to query a Power BI semantic model from a Rayfin app: connect the model, discover its schema, write DAX, and shape queries for visuals.
9
9
  > **Use when**: A Rayfin app template adds semantic-model analytics to an app.
10
10
  > **Do NOT use when**: You need a runtime library (use `@microsoft/rayfin-connector-fabric-semanticmodel`), or charts and tables (use `@microsoft/rayfin-visuals-pack`).
11
- > **Contents**: `skills/analytics`, `skills/dax-authoring`, `skills/query-design`, `skills/schema-discovery`
11
+ > **Contents**: `skills/analytics`, `skills/dax-authoring`, `skills/query-design`, `skills/schema-discovery`, `skills/visual-interactivity`, plus the `analytics` install layer: `pack.json` and `kit/`
12
12
  > **Install**: `npm install @microsoft/rayfin-semantic-model-pack`
13
13
 
14
14
  ## Contents
15
15
 
16
- The package has no entry point. Each folder under `skills/` is one agent skill
17
- and maps 1:1 to `.agents/skills/<name>/` in an app.
16
+ The package has no entry point. It has two layers:
17
+
18
+ - `skills/` is the agent content. Each folder is one skill and maps 1:1 to
19
+ `.agents/skills/<name>/` in an app. The published `analytics` skill combines
20
+ shared guidance with Universal App installation and runtime instructions.
21
+ - `pack.json` and `kit/` at the package root are the Rayfin Universal App's
22
+ install layer for the `analytics` skill, the one named in `pack.json`.
18
23
 
19
24
  | Skill | Contents |
20
25
  | --- | --- |
21
- | `analytics` | Capability pack: `SKILL.md`, `pack.json`, and `kit/` (semantic-model query hook, connector wiring, schema scripts) |
26
+ | `analytics` | Reading a semantic model from the app. The root `pack.json` installs semantic-model tools and the kit's query hooks, error normalization, table conversion and managed query-factory loading |
22
27
  | `dax-authoring` | Writing and testing DAX queries |
23
- | `query-design` | Splitting work between DAX and TypeScript, including multi-grain and cross-highlight queries |
28
+ | `query-design` | Splitting work between DAX and TypeScript, including multi-grain queries |
24
29
  | `schema-discovery` | Exploring a model's tables, columns, measures, and relationships |
30
+ | `visual-interactivity` | Managed visual selections, cross-filtering, cross-highlighting, filter-aware grid totals and runtime query factories |
25
31
 
26
32
  `pack.json` tells a template how to apply the pack, such as which dependencies
27
- to add and which kit files to copy where. The Rayfin universal template applies
28
- it with `npm run pack:add -- analytics`, and the copy targets assume that
29
- template's layout.
33
+ to add and which kit files to copy where. Its `copy` sources are relative to
34
+ the package root. The Rayfin Universal App applies it with
35
+ `npm run pack:add -- analytics`, and the copy targets assume that template's
36
+ layout.
30
37
 
31
38
  ## Usage
32
39
 
33
40
  Resolve `@microsoft/rayfin-semantic-model-pack/package.json`, then copy each
34
41
  `skills/<name>/` folder next to it into the app's `.agents/skills/<name>/`.
42
+ For Universal App installation, also copy the package-root `pack.json` and
43
+ `kit/` into `.agents/skills/analytics/`. The resulting analytics skill folder
44
+ contains both the guidance and install layer. Then run
45
+ `npm run pack:add -- analytics` after applying the template's `connectors` pack.
46
+
47
+ The Lyra data-app takes only shared guidance directly from the workspace's
48
+ `skills/`, without the sibling `universal-app/` fragment, and follows its own
49
+ runtime setup. It doesn't read `pack.json` or use the composed npm skill.
50
+
51
+ A template that applies packs with `npm run pack:add`, such as the Rayfin
52
+ Universal App, also copies `pack.json` and `kit/` into
53
+ `.agents/skills/<name>/`, where `<name>` is the `name` in `pack.json`. A
54
+ template without `pack:add` takes `skills/` and doesn't read `pack.json`.
35
55
 
36
56
  ## Key Constraints & Gotchas
37
57
 
38
58
  - Apply the template's `connectors` pack first. It installs the
39
59
  `@/lib/rayfin-client` that the kit imports.
40
60
  - The skills link to `visuals` from `@microsoft/rayfin-visuals-pack`, and to
41
- `app-design`, `fabric-sdk`, and `app-validation`, which the app template
61
+ `app-design` and `app-validation`, which the app template
42
62
  provides.
43
- - The schema scripts need Node.js 22.13 or later.
63
+ - Schema tools need Node.js 22.13 or later and a supported stable or prerelease Rayfin CLI.
64
+ - `connectors.ts` belongs to the CLI/connectors pack, not analytics.
65
+ - A copier that takes only `skills/<name>/` folders leaves `analytics` without
66
+ its `pack.json`, so `npm run pack:add -- analytics` can't find it. The
67
+ Universal App's copier must also mount the root `pack.json` and `kit/`.
44
68
 
45
69
  ## Trademarks
46
70
 
@@ -0,0 +1,191 @@
1
+ //-----------------------------------------------------------------------
2
+ // <copyright company="Microsoft Corporation">
3
+ // Copyright (c) Microsoft Corporation. All rights reserved.
4
+ // Licensed under the MIT license. See LICENSE file in the project root for full license information.
5
+ // </copyright>
6
+ //-----------------------------------------------------------------------
7
+
8
+ import { beforeEach, describe, expect, expectTypeOf, it, vi } from "vitest";
9
+ import { renderHook } from "@testing-library/react";
10
+ import type { DataTable } from "@microsoft/fabric-visuals-core";
11
+ import type {
12
+ CompiledDaxFilters,
13
+ DaxFilterMode,
14
+ InteractionTargetData,
15
+ InteractionTargetLoadContext,
16
+ InteractionTargetLoader,
17
+ ManagedQueryFactoryParams,
18
+ ManagedTargetLoadState,
19
+ } from "@microsoft/fabric-interaction-manager";
20
+ import { useQueryFactoryTarget } from "./use-query-factory-target";
21
+ import type { HighlightAlignment, HighlightData, QueryFactoryTargetState } from "./use-query-factory-target";
22
+ import type { DataQuery } from "@/lib/query-factory";
23
+
24
+ const { useManagedInteractionTarget, createHighlightData, executeQueryFactory } = vi.hoisted(() => ({
25
+ useManagedInteractionTarget: vi.fn<typeof import("@microsoft/fabric-interaction-manager/react").useManagedInteractionTarget>(),
26
+ createHighlightData: vi.fn(),
27
+ executeQueryFactory: vi.fn<(factory: DataQuery) => Promise<DataTable>>(),
28
+ }));
29
+ vi.mock("@microsoft/fabric-interaction-manager/react", () => ({ useManagedInteractionTarget }));
30
+ vi.mock("@microsoft/fabric-interaction-manager", () => ({ createHighlightData }));
31
+ vi.mock("@/lib/query-factory", () => ({ executeQueryFactory }));
32
+
33
+ interface SalesParams extends ManagedQueryFactoryParams {
34
+ readonly region: string;
35
+ }
36
+
37
+ // The query text records the factory inputs so each test can see which filters reached the factory.
38
+ function salesByCategory({ region, interactionFilters = [] }: SalesParams): DataQuery {
39
+ return { connection: "sales", query: JSON.stringify({ region, interactionFilters }), columnMetadata: {} };
40
+ }
41
+
42
+ function tableFor(factory: DataQuery): DataTable {
43
+ return { columns: [{ name: "Query" }], rows: [[factory.query]] };
44
+ }
45
+
46
+ function contextFor(isCrossHighlightActive: boolean): InteractionTargetLoadContext {
47
+ const compiledFilters: CompiledDaxFilters = {
48
+ getFilters: (mode: DaxFilterMode): readonly string[] => [`${mode} filter`],
49
+ } as CompiledDaxFilters;
50
+ return { isCrossHighlightActive, compiledFilters };
51
+ }
52
+
53
+ function latestLoader(): InteractionTargetLoader {
54
+ return useManagedInteractionTarget.mock.lastCall![1];
55
+ }
56
+
57
+ const alignment: HighlightAlignment = {
58
+ groupingFields: ["Category"],
59
+ missingMeasureReplacementValues: { Value: 0 },
60
+ plottedMeasureFields: ["Value"],
61
+ };
62
+
63
+ beforeEach(() => {
64
+ useManagedInteractionTarget.mockReset().mockReturnValue({ status: "loading" });
65
+ createHighlightData.mockReset().mockImplementation((all: DataTable, highlighted: DataTable) => ({ all, highlighted }));
66
+ executeQueryFactory.mockReset().mockImplementation(async (factory: DataQuery) => tableFor(factory));
67
+ });
68
+
69
+ describe("useQueryFactoryTarget", () => {
70
+ it("preserves the manager's complete load-state contract", () => {
71
+ expectTypeOf<QueryFactoryTargetState<InteractionTargetData>>().toExtend<ManagedTargetLoadState>();
72
+ expectTypeOf<ManagedTargetLoadState>().toExtend<QueryFactoryTargetState<InteractionTargetData>>();
73
+ });
74
+
75
+ it("retains a filter-only target's table and exposes a refresh error", () => {
76
+ const data: DataTable = tableFor(salesByCategory({ region: "West" }));
77
+ const error: Error = new Error("Refresh failed");
78
+ const loadState: ManagedTargetLoadState = { status: "refresh-error", data, isCrossHighlightActive: false, error };
79
+ useManagedInteractionTarget.mockReturnValue(loadState);
80
+
81
+ const { result } = renderHook(() => useQueryFactoryTarget("salesGrid", salesByCategory, { region: "West" }));
82
+
83
+ expect(result.current).toBe(loadState);
84
+ expect(result.current.status).toBe("refresh-error");
85
+ if (result.current.status === "refresh-error") {
86
+ expectTypeOf(result.current.data).toEqualTypeOf<DataTable>();
87
+ expectTypeOf(result.current.error).toEqualTypeOf<Error>();
88
+ expect(result.current.data).toBe(data);
89
+ expect(result.current.error).toBe(error);
90
+ expect(result.current.isCrossHighlightActive).toBe(false);
91
+ }
92
+ });
93
+
94
+ it("retains both highlight datasets and their flag when a refresh fails", () => {
95
+ const data: HighlightData = {
96
+ all: tableFor(salesByCategory({ region: "West" })),
97
+ highlighted: tableFor(salesByCategory({ region: "West", interactionFilters: ["highlight filter"] })),
98
+ };
99
+ const error: Error = new Error("Highlight refresh failed");
100
+ const loadState: ManagedTargetLoadState = { status: "refresh-error", data, isCrossHighlightActive: true, error };
101
+ useManagedInteractionTarget.mockReturnValue(loadState);
102
+
103
+ const { result } = renderHook(() => useQueryFactoryTarget("salesChart", salesByCategory, { region: "West" }, alignment));
104
+
105
+ expect(result.current).toBe(loadState);
106
+ expect(result.current.status).toBe("refresh-error");
107
+ if (result.current.status === "refresh-error") {
108
+ expectTypeOf(result.current.data).toEqualTypeOf<HighlightData>();
109
+ expectTypeOf(result.current.error).toEqualTypeOf<Error>();
110
+ expect(result.current.data).toBe(data);
111
+ expect(result.current.error).toBe(error);
112
+ expect(result.current.isCrossHighlightActive).toBe(true);
113
+ }
114
+ });
115
+
116
+ it("loads a filter-only target from the factory under the baseline filters", async () => {
117
+ renderHook(() => useQueryFactoryTarget("salesGrid", salesByCategory, { region: "West" }));
118
+
119
+ expect(useManagedInteractionTarget.mock.lastCall![0]).toBe("salesGrid");
120
+ await expect(latestLoader()(contextFor(true))).resolves.toEqual(
121
+ tableFor(salesByCategory({ region: "West", interactionFilters: ["baseline filter"] })),
122
+ );
123
+ expect(executeQueryFactory).toHaveBeenCalledTimes(1);
124
+ });
125
+
126
+ it("returns the baseline as both datasets when no highlight is active", async () => {
127
+ const { result, rerender } = renderHook(() => useQueryFactoryTarget("salesChart", salesByCategory, { region: "West" }, alignment));
128
+
129
+ const all: DataTable = tableFor(salesByCategory({ region: "West", interactionFilters: ["baseline filter"] }));
130
+ const loaded: InteractionTargetData = await latestLoader()(contextFor(false));
131
+ useManagedInteractionTarget.mockReturnValue({ status: "ready", data: loaded, isCrossHighlightActive: false });
132
+ rerender();
133
+ const state: QueryFactoryTargetState<HighlightData> = result.current;
134
+ if (state.status === "loading" || state.status === "error") throw new Error("Expected loaded highlight data");
135
+ const data: Record<string, DataTable> = state.data;
136
+ expect(data).toEqual({ all, highlighted: all });
137
+ expect(executeQueryFactory).toHaveBeenCalledTimes(1);
138
+ expect(createHighlightData).not.toHaveBeenCalled();
139
+ });
140
+
141
+ it("aligns the factory's highlighted subset with its baseline during a cross-highlight", async () => {
142
+ renderHook(() => useQueryFactoryTarget("salesChart", salesByCategory, { region: "West" }, alignment));
143
+
144
+ await latestLoader()(contextFor(true));
145
+ expect(createHighlightData).toHaveBeenCalledWith(
146
+ tableFor(salesByCategory({ region: "West", interactionFilters: ["baseline filter"] })),
147
+ tableFor(salesByCategory({ region: "West", interactionFilters: ["highlight filter"] })),
148
+ ["Category"],
149
+ { Value: 0 },
150
+ ["Value"],
151
+ );
152
+ });
153
+
154
+ it("returns real aligned highlight rows, preserving baseline keys missing from the selection", async () => {
155
+ const actual = await vi.importActual<typeof import("@microsoft/fabric-interaction-manager")>(
156
+ "@microsoft/fabric-interaction-manager",
157
+ );
158
+ createHighlightData.mockImplementation(actual.createHighlightData);
159
+ const all: DataTable = {
160
+ columns: [{ name: "Category" }, { name: "Value" }],
161
+ rows: [["Bikes", 100], ["Accessories", 50]],
162
+ };
163
+ const subset: DataTable = { columns: all.columns, rows: [["Accessories", 20]] };
164
+ executeQueryFactory.mockResolvedValueOnce(all).mockResolvedValueOnce(subset);
165
+ renderHook(() => useQueryFactoryTarget("salesChart", salesByCategory, { region: "West" }, alignment));
166
+
167
+ await expect(latestLoader()(contextFor(true))).resolves.toEqual({
168
+ all,
169
+ highlighted: { columns: all.columns, rows: [["Bikes", 0], ["Accessories", 20]] },
170
+ });
171
+ });
172
+
173
+ it("keeps the loader while inline inputs have the same contents", () => {
174
+ const { rerender } = renderHook(
175
+ ({ region }: { region: string }) => useQueryFactoryTarget(
176
+ "salesChart",
177
+ salesByCategory,
178
+ { region },
179
+ { ...alignment, groupingFields: [...alignment.groupingFields] },
180
+ ),
181
+ { initialProps: { region: "West" } },
182
+ );
183
+ const initialLoader: InteractionTargetLoader = latestLoader();
184
+
185
+ rerender({ region: "West" });
186
+ expect(latestLoader()).toBe(initialLoader);
187
+
188
+ rerender({ region: "East" });
189
+ expect(latestLoader()).not.toBe(initialLoader);
190
+ });
191
+ });
@@ -0,0 +1,123 @@
1
+ //-----------------------------------------------------------------------
2
+ // <copyright company="Microsoft Corporation">
3
+ // Copyright (c) Microsoft Corporation. All rights reserved.
4
+ // Licensed under the MIT license. See LICENSE file in the project root for full license information.
5
+ // </copyright>
6
+ //-----------------------------------------------------------------------
7
+
8
+ import { useMemo, useState } from "react";
9
+ import type { DataTable } from "@microsoft/fabric-visuals-core";
10
+ import { createHighlightData } from "@microsoft/fabric-interaction-manager";
11
+ import type {
12
+ InteractionTargetData,
13
+ InteractionTargetLoadContext,
14
+ InteractionTargetLoader,
15
+ ManagedQueryFactoryParams,
16
+ ManagedTargetLoadState,
17
+ } from "@microsoft/fabric-interaction-manager";
18
+ import { useManagedInteractionTarget } from "@microsoft/fabric-interaction-manager/react";
19
+ import { executeQueryFactory } from "@/lib/query-factory";
20
+ import type { DataQuery } from "@/lib/query-factory";
21
+
22
+ /** The `createHighlightData` settings that align a highlighted subset with its baseline. */
23
+ export interface HighlightAlignment {
24
+ /** Every group and series key column, including hidden identifiers. */
25
+ readonly groupingFields: readonly string[];
26
+ /** The value for each measure column in baseline groups absent from the highlighted subset. */
27
+ readonly missingMeasureReplacementValues: Readonly<Record<string, number | null>>;
28
+ /** The measure columns the chart draws. */
29
+ readonly plottedMeasureFields: readonly string[];
30
+ }
31
+
32
+ /** The baseline and aligned highlighted datasets of a highlight-capable target. */
33
+ export type HighlightData = {
34
+ readonly all: DataTable;
35
+ readonly highlighted: DataTable;
36
+ };
37
+
38
+ /** A managed target load state whose data has the shape this hook's loader returns. */
39
+ export type QueryFactoryTargetState<TData extends InteractionTargetData> = {
40
+ // Preserve every manager state and its fields, narrowing only the loader's data shape.
41
+ [TState in ManagedTargetLoadState as TState["status"]]: TState extends { readonly data: InteractionTargetData }
42
+ ? Omit<TState, "data"> & { readonly data: TData }
43
+ : TState;
44
+ }[ManagedTargetLoadState["status"]];
45
+
46
+ /**
47
+ * Loads a managed interaction target from a query factory. The hook passes the target's baseline
48
+ * filters to the factory and returns one table. With a highlight alignment, it also runs the factory
49
+ * under the highlight filters during an active cross-highlight and returns `{ all, highlighted }`.
50
+ * `params` are the factory's app inputs other than `interactionFilters`.
51
+ */
52
+ export function useQueryFactoryTarget<TParams extends ManagedQueryFactoryParams>(
53
+ targetId: string,
54
+ factory: (params: TParams) => DataQuery,
55
+ params: Omit<TParams, "interactionFilters">,
56
+ ): QueryFactoryTargetState<DataTable>;
57
+ export function useQueryFactoryTarget<TParams extends ManagedQueryFactoryParams>(
58
+ targetId: string,
59
+ factory: (params: TParams) => DataQuery,
60
+ params: Omit<TParams, "interactionFilters">,
61
+ highlightAlignment: HighlightAlignment,
62
+ ): QueryFactoryTargetState<HighlightData>;
63
+ export function useQueryFactoryTarget<TParams extends ManagedQueryFactoryParams>(
64
+ targetId: string,
65
+ factory: (params: TParams) => DataQuery,
66
+ params: Omit<TParams, "interactionFilters">,
67
+ highlightAlignment?: HighlightAlignment,
68
+ ): QueryFactoryTargetState<InteractionTargetData> {
69
+ // Keep track of the loader inputs and only update them when the JSON-serialized key changes.
70
+ // This prevents unnecessary reloads when inline objects are used.
71
+ const inputsKey: string = JSON.stringify([params, highlightAlignment ?? null]);
72
+ const [loaderInputs, setLoaderInputs] = useState({ inputsKey, params, highlightAlignment });
73
+ if (loaderInputs.inputsKey !== inputsKey) {
74
+ setLoaderInputs({ inputsKey, params, highlightAlignment });
75
+ }
76
+
77
+ const loader: InteractionTargetLoader = useMemo(
78
+ (): InteractionTargetLoader => createQueryFactoryLoader(factory, loaderInputs.params, loaderInputs.highlightAlignment),
79
+ [factory, loaderInputs],
80
+ );
81
+
82
+ return useManagedInteractionTarget(targetId, loader);
83
+ }
84
+
85
+ function createQueryFactoryLoader<TParams extends ManagedQueryFactoryParams>(
86
+ factory: (params: TParams) => DataQuery,
87
+ params: Omit<TParams, "interactionFilters">,
88
+ highlightAlignment: HighlightAlignment | undefined,
89
+ ): InteractionTargetLoader {
90
+ // `params` holds every factory input except `interactionFilters`, so adding the filters gives the
91
+ // factory its complete input. TypeScript cannot prove that `Omit<TParams, "interactionFilters">`
92
+ // plus `interactionFilters` equals a generic `TParams`, so the cast states it.
93
+ const loadTable = (interactionFilters: readonly string[]): Promise<DataTable> =>
94
+ executeQueryFactory(factory({ ...params, interactionFilters } as TParams));
95
+
96
+ return async ({ isCrossHighlightActive, compiledFilters }: InteractionTargetLoadContext): Promise<InteractionTargetData> => {
97
+ if (highlightAlignment) {
98
+ if (isCrossHighlightActive) {
99
+ // Both queries come from the same factory, so they share grouping keys, measures,
100
+ // aliases, and app filters; only the interaction filter scope differs.
101
+ const [all, highlightedSubset]: [DataTable, DataTable] = await Promise.all([
102
+ loadTable(compiledFilters.getFilters("baseline")),
103
+ loadTable(compiledFilters.getFilters("highlight")),
104
+ ]);
105
+
106
+ return createHighlightData(
107
+ all,
108
+ highlightedSubset,
109
+ highlightAlignment.groupingFields,
110
+ highlightAlignment.missingMeasureReplacementValues,
111
+ highlightAlignment.plottedMeasureFields,
112
+ );
113
+ }
114
+
115
+ // If cross-highlight is not active, just load the baseline table and use it for both all and highlighted.
116
+ const all: DataTable = await loadTable(compiledFilters.getFilters("baseline"));
117
+ return { all, highlighted: all };
118
+ }
119
+
120
+ // Cross-highlight is not enabled, so just load the baseline table (which includes cross filters if any)
121
+ return loadTable(compiledFilters.getFilters("baseline"));
122
+ };
123
+ }
@@ -14,8 +14,12 @@
14
14
 
15
15
  import { renderHook, act, waitFor } from '@testing-library/react';
16
16
  import { describe, it, expect, vi, beforeEach } from 'vitest';
17
+ import { NetworkError } from '@microsoft/rayfin-lib';
18
+ import type { WorkloadFailure } from '@microsoft/rayfin-lib';
19
+ import { ConnectorsError } from '@microsoft/rayfin-connectors';
17
20
 
18
21
  import { useSemanticModelQuery } from '@/hooks/use-semantic-model-query';
22
+ import { isThrottlingError } from '@/lib/semantic-model-errors';
19
23
 
20
24
  const executeQuery = vi.fn();
21
25
  const connectors: Record<string, unknown> = {};
@@ -28,10 +32,7 @@ const connectors: Record<string, unknown> = {};
28
32
  const connectorsProxy = new Proxy(connectors, {
29
33
  get(target, key: string) {
30
34
  if (!(key in target)) {
31
- throw Object.assign(
32
- new Error(`Connector "${key}" was accessed but has no configuration.`),
33
- { code: 'UNKNOWN_CONNECTOR' }
34
- );
35
+ throw new ConnectorsError(`Connector "${key}" was accessed but has no configuration.`, 'UNKNOWN_CONNECTOR');
35
36
  }
36
37
  return target[key];
37
38
  },
@@ -122,7 +123,7 @@ describe('useSemanticModelQuery', () => {
122
123
  expect(result.current.error).toBeUndefined();
123
124
  });
124
125
 
125
- it('reports a failure Power BI returned on the data channel only', async () => {
126
+ it('mirrors a returned query failure onto error without losing its category', async () => {
126
127
  executeQuery.mockResolvedValue({
127
128
  status: 'Succeeded',
128
129
  output: { tables: [], queryError: { message: 'bad DAX' } },
@@ -137,25 +138,42 @@ describe('useSemanticModelQuery', () => {
137
138
  expect(
138
139
  result.current.data?.status === 'error' && result.current.data.error
139
140
  ).toMatchObject({ category: 'query', message: 'bad DAX' });
140
- // `error` must stay clear, or a caller checking it first never reaches the
141
- // structured branch and the category is unreachable.
142
- expect(result.current.error).toBeUndefined();
141
+ expect(result.current.error?.message).toBe('bad DAX');
143
142
  });
144
143
 
145
- it('surfaces the thrown error itself, not a copy of its message', async () => {
146
- // Re-wrapping into a fresh Error keeps only the message and drops the
147
- // status and service code — exactly what separates an auth failure from a
148
- // malformed query.
149
- const thrown = Object.assign(new Error('401 Unauthorized'), {
150
- status: 401,
151
- });
144
+ it('normalizes thrown API failures with diagnostics and original cause', async () => {
145
+ const thrown = new NetworkError('401 Unauthorized', 401, 'AccessDenied');
152
146
  executeQuery.mockRejectedValue(thrown);
153
147
 
154
148
  const { result } = render();
155
149
 
156
150
  await waitFor(() => expect(result.current.error).toBeDefined());
157
- expect(result.current.error).toBe(thrown);
158
- expect((result.current.error as { status?: number }).status).toBe(401);
151
+ expect(result.current.error?.cause).toBe(thrown);
152
+ expect(result.current.data?.status).toBe('error');
153
+ if (result.current.data?.status === 'error') {
154
+ expect(result.current.data.error).toMatchObject({
155
+ category: 'api', code: 'AccessDenied', cause: thrown,
156
+ });
157
+ }
158
+ });
159
+
160
+ it.each([429, 500])('preserves structured throttle diagnostics on the convenience error for HTTP %s', async (httpStatus: number): Promise<void> => {
161
+ const workload: WorkloadFailure = {
162
+ errorCode: 'WorkloadException', subErrorCode: 'TooManyRequests', status: 'Failed',
163
+ };
164
+ const thrown: NetworkError = Object.assign(new NetworkError('Invocation failed', httpStatus, 'InvocationFailure'), { workload });
165
+ executeQuery.mockRejectedValue(thrown);
166
+
167
+ const { result } = render();
168
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
169
+
170
+ expect(result.current.error).toMatchObject({
171
+ category: 'api', code: 'InvocationFailure', httpStatus, workload, cause: thrown,
172
+ });
173
+ expect(isThrottlingError(result.current.error)).toBe(true);
174
+ expect(result.current.data).toMatchObject({
175
+ status: 'error', error: { httpStatus, workload, cause: thrown },
176
+ });
159
177
  });
160
178
 
161
179
  it('clears a stale result when a later query throws', async () => {
@@ -172,9 +190,7 @@ describe('useSemanticModelQuery', () => {
172
190
  rerender({ query: 'EVALUATE ROW(2)' });
173
191
 
174
192
  await waitFor(() => expect(result.current.error).toBeDefined());
175
- // A throw is not something Power BI returned, so it must not be dressed up
176
- // as a result either.
177
- expect(result.current.data).toBeUndefined();
193
+ expect(result.current.data?.status).toBe('error');
178
194
  });
179
195
 
180
196
  it('names an unregistered connector as a wiring mistake', async () => {
@@ -186,7 +202,10 @@ describe('useSemanticModelQuery', () => {
186
202
  const { result } = render();
187
203
 
188
204
  await waitFor(() => expect(result.current.error).toBeDefined());
189
- expect(result.current.error?.message).toContain('connectorRuntimes');
205
+ expect(result.current.error?.message).toBe(
206
+ 'No connector named "model". Check that the name matches rayfin/rayfin.yml, ' +
207
+ 'or add it with `npx rayfin connector add`.'
208
+ );
190
209
  // The original is kept so the SDK's own code is still recoverable.
191
210
  expect((result.current.error?.cause as { code?: string })?.code).toBe(
192
211
  'UNKNOWN_CONNECTOR'
@@ -194,7 +213,24 @@ describe('useSemanticModelQuery', () => {
194
213
  expect(executeQuery).not.toHaveBeenCalled();
195
214
  });
196
215
 
197
- it('says so when the app never wired ConnectorsRayfinClient', async () => {
216
+ it('normalizes an undefined connector lookup without invoking a query', async () => {
217
+ connectors.model = undefined;
218
+ const { result } = render();
219
+
220
+ await waitFor(() => expect(result.current.error).toBeDefined());
221
+ const message: string =
222
+ 'No connector named "model". Check that the name matches rayfin/rayfin.yml, ' +
223
+ 'or add it with `npx rayfin connector add`.';
224
+ expect(result.current.error?.message).toBe(message);
225
+ expect(result.current.error?.cause).toMatchObject({ code: 'UNKNOWN_CONNECTOR', message });
226
+ expect(result.current.data).toMatchObject({
227
+ status: 'error',
228
+ error: { category: 'unknown', code: 'UNKNOWN_CONNECTOR' },
229
+ });
230
+ expect(executeQuery).not.toHaveBeenCalled();
231
+ });
232
+
233
+ it('says so when the app never registered connectorsService', async () => {
198
234
  // The base template builds a plain RayfinClient with no `connectors`, and no
199
235
  // pack rewrites that file. Without this the first symptom is an unrelated
200
236
  // TypeError deep in the hook.
@@ -203,7 +239,7 @@ describe('useSemanticModelQuery', () => {
203
239
  const { result } = render();
204
240
 
205
241
  await waitFor(() => expect(result.current.error).toBeDefined());
206
- expect(result.current.error?.message).toContain('ConnectorsRayfinClient');
242
+ expect(result.current.error?.message).toContain('connectorsService');
207
243
  expect(executeQuery).not.toHaveBeenCalled();
208
244
  });
209
245