@microsoft/rayfin-semantic-model-pack 1.1.0 → 2.1.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 (39) hide show
  1. package/CHANGELOG +9 -0
  2. package/README.md +16 -5
  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/kit/hooks/use-semantic-model-query.spec.ts +51 -34
  6. package/kit/hooks/use-semantic-model-query.ts +30 -49
  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 +122 -25
  14. package/package.json +1 -1
  15. package/skills/analytics/SKILL.md +126 -422
  16. package/skills/dax-authoring/SKILL.md +98 -31
  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 +89 -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 +197 -0
  30. package/kit/scripts/rayfin-connector.mjs +0 -265
  31. package/kit/scripts/rayfin-connector.test.mjs +0 -243
  32. package/kit/scripts/schema-sql-batch.test.mjs +0 -2097
  33. package/kit/scripts/schema-sql-cli.test.mjs +0 -488
  34. package/kit/scripts/schema-sql.mjs +0 -2650
  35. package/kit/scripts/schema-sql.test.mjs +0 -1387
  36. package/kit/scripts/schema.mjs +0 -166
  37. package/kit/scripts/schema.test.mjs +0 -271
  38. package/skills/query-design/references/filter-strategy.md +0 -68
  39. package/skills/query-design/references/highlight-queries.md +0 -122
package/CHANGELOG CHANGED
@@ -5,6 +5,15 @@ 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.1.0 - 2026-11-17
9
+
10
+ - [Template] Bump to rayfin 2.0.0
11
+ - Add new selectColumns helper to parse out unused measures from highlight helpers
12
+
13
+ ## 2.0.0 - 2026-11-11
14
+
15
+ - [Rayfin Packs] Unify Lyra skills in shared rayfin pack npm packages
16
+
8
17
  ## 1.1.0 - 2026-11-05
9
18
 
10
19
  - [Rayfin Packs] Update semantic-model and visuals packs with data-app template fixes
package/README.md CHANGED
@@ -8,7 +8,7 @@ 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`, plus the `analytics` install layer: `pack.json` and `kit/`
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
@@ -16,16 +16,18 @@ Agent skills and starter code for Power BI semantic-model analytics in Rayfin ap
16
16
  The package has no entry point. It has two layers:
17
17
 
18
18
  - `skills/` is the agent content. Each folder is one skill and maps 1:1 to
19
- `.agents/skills/<name>/` in an app. This is what both app templates share.
19
+ `.agents/skills/<name>/` in an app. The published `analytics` skill combines
20
+ shared guidance with Universal App installation and runtime instructions.
20
21
  - `pack.json` and `kit/` at the package root are the Rayfin Universal App's
21
22
  install layer for the `analytics` skill, the one named in `pack.json`.
22
23
 
23
24
  | Skill | Contents |
24
25
  | --- | --- |
25
- | `analytics` | Reading a semantic model from the app. Installed by the root `pack.json`, whose `kit/` holds the semantic-model query hook and the 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 |
26
27
  | `dax-authoring` | Writing and testing DAX queries |
27
- | `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 |
28
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 |
29
31
 
30
32
  `pack.json` tells a template how to apply the pack, such as which dependencies
31
33
  to add and which kit files to copy where. Its `copy` sources are relative to
@@ -37,6 +39,14 @@ layout.
37
39
 
38
40
  Resolve `@microsoft/rayfin-semantic-model-pack/package.json`, then copy each
39
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.
40
50
 
41
51
  A template that applies packs with `npm run pack:add`, such as the Rayfin
42
52
  Universal App, also copies `pack.json` and `kit/` into
@@ -50,7 +60,8 @@ template without `pack:add` takes `skills/` and doesn't read `pack.json`.
50
60
  - The skills link to `visuals` from `@microsoft/rayfin-visuals-pack`, and to
51
61
  `app-design` and `app-validation`, which the app template
52
62
  provides.
53
- - 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.
54
65
  - A copier that takes only `skills/<name>/` folders leaves `analytics` without
55
66
  its `pack.json`, so `npm run pack:add -- analytics` can't find it. The
56
67
  Universal App's copier must also mount the root `pack.json` and `kit/`.
@@ -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,12 +190,10 @@ 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
- it('directs an unknown connector to the CLI registration flow', async () => {
196
+ it('names an unregistered connector as a wiring mistake', async () => {
181
197
  // The proxy throws for a name with no config. Left untranslated that
182
198
  // surfaces as a generic transport failure, sending the builder to look at
183
199
  // Fabric instead of at their own registration.
@@ -187,8 +203,8 @@ describe('useSemanticModelQuery', () => {
187
203
 
188
204
  await waitFor(() => expect(result.current.error).toBeDefined());
189
205
  expect(result.current.error?.message).toBe(
190
- `No connector named "model". Check that the name matches rayfin/rayfin.yml, ` +
191
- `or add it with \`npx rayfin connector add\`.`
206
+ 'No connector named "model". Check that the name matches rayfin/rayfin.yml, ' +
207
+ 'or add it with `npx rayfin connector add`.'
192
208
  );
193
209
  // The original is kept so the SDK's own code is still recoverable.
194
210
  expect((result.current.error?.cause as { code?: string })?.code).toBe(
@@ -197,23 +213,24 @@ describe('useSemanticModelQuery', () => {
197
213
  expect(executeQuery).not.toHaveBeenCalled();
198
214
  });
199
215
 
200
- it('gives the same CLI guidance when a connector lookup returns undefined', async () => {
216
+ it('normalizes an undefined connector lookup without invoking a query', async () => {
201
217
  connectors.model = undefined;
202
-
203
218
  const { result } = render();
204
219
 
205
220
  await waitFor(() => expect(result.current.error).toBeDefined());
206
- expect(result.current.error?.message).toBe(
207
- `No connector named "model". Check that the name matches rayfin/rayfin.yml, ` +
208
- `or add it with \`npx rayfin connector add\`.`
209
- );
210
- expect(result.current.error?.cause).toBeUndefined();
211
- expect(result.current.data).toBeUndefined();
212
- expect(result.current.isLoading).toBe(false);
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
+ });
213
230
  expect(executeQuery).not.toHaveBeenCalled();
214
231
  });
215
232
 
216
- it('says so when the app never wired ConnectorsRayfinClient', async () => {
233
+ it('says so when the app never registered connectorsService', async () => {
217
234
  // The base template builds a plain RayfinClient with no `connectors`, and no
218
235
  // pack rewrites that file. Without this the first symptom is an unrelated
219
236
  // TypeError deep in the hook.
@@ -222,7 +239,7 @@ describe('useSemanticModelQuery', () => {
222
239
  const { result } = render();
223
240
 
224
241
  await waitFor(() => expect(result.current.error).toBeDefined());
225
- expect(result.current.error?.message).toContain('ConnectorsRayfinClient');
242
+ expect(result.current.error?.message).toContain('connectorsService');
226
243
  expect(executeQuery).not.toHaveBeenCalled();
227
244
  });
228
245