Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
refactor: compose workspace setup guide from reusable scenarios (#21303)
ecmadao8ddb9d00e0fa
diff --git a/docs/agents/frontend-ux.md b/docs/agents/frontend-ux.mdindex 69a0451b75..05db7def5e 100644--- a/docs/agents/frontend-ux.md+++ b/docs/agents/frontend-ux.md@@ -76,6 +76,11 @@ The `size` prop on shared controls selects the complete base contract.Consumers MUST NOT override base dimensions or resize a managed iconindependently. A layout owner MAY use standard breakpoint-prefixed classes toapply a complete responsive size contract; do not override only the height.+A specialized content-sized control MAY use `h-auto` when its height is+intentionally derived from its content and padding. This includes inline text+actions with no control padding and composite controls with an explicit padding+and typography contract. Icon-only controls MUST retain a shared size contract.+Do not replace the managed height with another fixed `h-*` or `size-*` value.| Size | Height | Inline padding | Text | Icon | Internal gap || --- | ---: | ---: | --- | ---: | ---: |@@ -421,8 +426,8 @@ node frontend/scripts/check-ui-guideline.mjsThe scanner enforces raw and literal colors, manual dark variants, `space-*`,arbitrary and off-scale gaps, unsupported radii, native feature controls, raw-feature tables, shared `Button` height/size overrides, arbitrary typography,-and ad hoc sheet widths. The committed+feature tables, fixed shared `Button` height/size overrides, arbitrary+typography, and ad hoc sheet widths. The committed`frontend/scripts/ui-guideline-legacy-debt.json` file records each temporarylegacy exception by file, rule, token, and occurrence count.diff --git a/frontend/scripts/check-react-i18n.mjs b/frontend/scripts/check-react-i18n.mjsindex 318c3e38da..8367262864 100644--- a/frontend/scripts/check-react-i18n.mjs+++ b/frontend/scripts/check-react-i18n.mjs@@ -53,6 +53,10 @@ const DYNAMIC_PREFIXES = [// Role-grant expiration presets, rendered via t(preset.labelKey) in// MembersPage.tsx (EXPIRATION_PRESETS), not as literal t("…") calls."project.members.expiration-presets.",+ // Workspace setup guide step definitions store label and description keys;+ // the presentation translates them via t(step.definition.<key>).+ "workspace-setup-guide.descriptions.",+ "workspace-setup-guide.steps.",// MCP mode cards and the broken-ceiling banner, rendered via// t(`settings.mcp.policy.mode.${key}.title`) and a ternary over two key// strings in MCPAccessPolicySection.tsx, not as literal t("…") calls.diff --git a/frontend/scripts/check-ui-guideline.mjs b/frontend/scripts/check-ui-guideline.mjsindex 659ae23905..8cdfc4f1c5 100644--- a/frontend/scripts/check-ui-guideline.mjs+++ b/frontend/scripts/check-ui-guideline.mjs@@ -257,11 +257,12 @@ const scanButtonDimensions = (node, path, counts) => {if (isSharedPrimitive(path) || getTagName(node.tagName) !== "Button") return;for (const token of attributeTokens(node, new Set(["class", "className"]))) {const isDimensionOverride = /(?:^|:)(?:h|size)-/.test(token);+ const isIntrinsicHeight = token === "h-auto";const isResponsiveOverride =/^(?:sm|md|lg|xl|2xl|max-(?:sm|md|lg|xl|2xl)):(?:h|size)-/.test(token);- if (isDimensionOverride && !isResponsiveOverride) {+ if (isDimensionOverride && !isIntrinsicHeight && !isResponsiveOverride) {addViolation(counts, path, "no-button-dimension-override", token);}}diff --git a/frontend/scripts/check-ui-guideline.test.mjs b/frontend/scripts/check-ui-guideline.test.mjsindex 4d63bdc7ab..9eef20a4f5 100644--- a/frontend/scripts/check-ui-guideline.test.mjs+++ b/frontend/scripts/check-ui-guideline.test.mjs@@ -244,13 +244,14 @@ const styles = { borderRadius };expect(scanSource(source, "src/types/proto-es/generated.ts")).toEqual([]);});- test("allows responsive Button sizing but flags other dimension overrides", () => {+ test("allows intrinsic and responsive Button sizing but flags fixed dimension overrides", () => {const violations = scanSource(`export function Feature() {return (<>- <Button size="sm" className="w-full" />+ <Button appearance="link" className="h-auto p-0" />+ <Button className="h-auto px-2 py-1" /><ButtonclassName={cn("h-8",diff --git a/frontend/scripts/ui-guideline-legacy-debt.json b/frontend/scripts/ui-guideline-legacy-debt.jsonindex 1ccb8b0ac0..6541a13cca 100644--- a/frontend/scripts/ui-guideline-legacy-debt.json+++ b/frontend/scripts/ui-guideline-legacy-debt.json@@ -150,18 +150,6 @@"token": "bg-gray-200","count": 1},- {- "path": "src/components/BannersWrapper.tsx",- "rule": "no-raw-color",- "token": "bg-white",- "count": 1- },- {- "path": "src/components/BannersWrapper.tsx",- "rule": "no-raw-color",- "token": "hover:bg-indigo-50",- "count": 1- },{"path": "src/components/BannersWrapper.tsx","rule": "no-raw-color",@@ -420,12 +408,6 @@"token": "text-[10px]","count": 2},- {- "path": "src/components/header/HeaderBreadcrumb.tsx",- "rule": "no-button-dimension-override",- "token": "h-auto",- "count": 3- },{"path": "src/components/header/HeaderBreadcrumb.tsx","rule": "no-button-dimension-override",@@ -924,12 +906,6 @@"token": "text-white","count": 1},- {- "path": "src/components/UserCell.tsx",- "rule": "no-button-dimension-override",- "token": "h-auto",- "count": 1- },{"path": "src/components/UserHoverCard.tsx","rule": "no-off-scale-gap",@@ -942,18 +918,6 @@"token": "rgba(","count": 2},- {- "path": "src/components/WorkspaceSetupGuide.tsx",- "rule": "no-button-dimension-override",- "token": "h-auto",- "count": 1- },- {- "path": "src/components/WorkspaceSetupGuide.tsx",- "rule": "no-raw-color",- "token": "bg-white",- "count": 1- },{"path": "src/modules/agent/components/AgentChat.tsx","rule": "no-raw-color",@@ -1446,12 +1410,6 @@"token": "size-6","count": 1},- {- "path": "src/modules/sql-editor/components/ResultView/ResultStatusBar.tsx",- "rule": "no-button-dimension-override",- "token": "h-auto",- "count": 1- },{"path": "src/modules/sql-editor/components/ResultView/SelectionCopyTooltips.tsx","rule": "no-button-dimension-override",diff --git a/frontend/src/app/layouts/BodyLayout.tsx b/frontend/src/app/layouts/BodyLayout.tsxindex b560b27417..bb2cd0eb81 100644--- a/frontend/src/app/layouts/BodyLayout.tsx+++ b/frontend/src/app/layouts/BodyLayout.tsx@@ -11,7 +11,7 @@ import { DashboardBodyShell } from "@/components/DashboardBodyShell";import { DashboardSidebar } from "@/components/DashboardSidebar";import { ProjectSidebar } from "@/components/ProjectSidebar";import { RoutePermissionGuardShell } from "@/components/RoutePermissionGuardShell";-import { WorkspaceSetupGuide } from "@/components/WorkspaceSetupGuide";+import { WorkspaceSetupGuide } from "@/modules/workspace-setup-guide/WorkspaceSetupGuide";// Ported from `src/layouts/BodyLayout.vue`. Mounts the workspace// `DashboardBodyShell` (header + sidebar slot + body slot) and portals thediff --git a/frontend/src/components/BannersWrapper.test.tsx b/frontend/src/components/BannersWrapper.test.tsxindex 4547e5fb0f..6fb54cb3d9 100644--- a/frontend/src/components/BannersWrapper.test.tsx+++ b/frontend/src/components/BannersWrapper.test.tsx@@ -199,8 +199,12 @@ describe("BannersWrapper", () => {);const configureButtonClasses =configureButton?.className.split(/\s+/) ?? [];- expect(configureButtonClasses).toContain("bg-white");+ expect(configureButtonClasses).toContain("h-10");+ expect(configureButtonClasses).toContain("bg-background");+ expect(configureButtonClasses).toContain("hover:bg-control-bg");expect(configureButtonClasses).toContain("text-accent");+ expect(configureButtonClasses).not.toContain("h-auto");+ expect(configureButtonClasses).not.toContain("bg-white");expect(configureButtonClasses).not.toContain("bg-accent");expect(configureButtonClasses).not.toContain("text-accent-text");diff --git a/frontend/src/components/BannersWrapper.tsx b/frontend/src/components/BannersWrapper.tsxindex 1aa2173e23..1d96c27fec 100644--- a/frontend/src/components/BannersWrapper.tsx+++ b/frontend/src/components/BannersWrapper.tsx@@ -97,12 +97,13 @@ function BannerExternalUrl() {}}className={buttonVariants({appearance: "secondary",+ size: "lg",className:- "h-auto bg-white py-2 pr-2 pl-4 text-base font-medium text-accent shadow-xs hover:bg-indigo-50",+ "bg-background pr-2 text-base text-accent shadow-xs hover:bg-control-bg",})}>{t("common.configure-now")}- <Wrench className="ml-1 size-5" />+ <Wrench className="size-5" /></RouterLink></div>) : null}diff --git a/frontend/src/components/WorkspaceSetupGuide.test.tsx b/frontend/src/components/WorkspaceSetupGuide.test.tsxdeleted file mode 100644index 483057fe3c..0000000000--- a/frontend/src/components/WorkspaceSetupGuide.test.tsx+++ /dev/null@@ -1,1969 +0,0 @@-import type { ReactElement, ReactNode } from "react";-import { act } from "react";-import { createRoot } from "react-dom/client";-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";-import {- DATABASE_ROUTE_DASHBOARD,- INSTANCE_ROUTE_DATABASE_DETAIL,- PROJECT_V1_ROUTE_DATABASE_DETAIL,- SQL_EDITOR_DATABASE_MODULE,-} from "@/app/router/handles";-import { sqlEditorEvents } from "@/modules/sql-editor/model/events";--(- globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }-).IS_REACT_ACT_ENVIRONMENT = true;--const mocks = vi.hoisted(() => ({- projectsByName: {} as Record<string, unknown>,- instancesByName: {} as Record<string, unknown>,- databasesByName: {} as Record<string, unknown>,- fetchProjectList: vi.fn(async (_?: { pageToken?: string }) => ({- projects: [] as unknown[],- nextPageToken: "",- })),- fetchInstanceList: vi.fn(- async (_?: { parent?: string; pageToken?: string }) => ({- instances: [] as unknown[],- nextPageToken: "",- })- ),- fetchDatabases: vi.fn(- async (_?: { parent?: string; pageToken?: string }) => ({- databases: [] as unknown[],- nextPageToken: "",- })- ),- introState: {} as Record<string, boolean>,- getIntroStateByKey: vi.fn((_key: string) => false),- saveIntroStateByKey: vi.fn(- (_: { key: string; newState: boolean }) => undefined- ),- introStateVersion: 0,- searchQueryHistories: vi.fn(async (_?: { pageToken?: string }) => ({- queryHistories: [] as unknown[],- nextPageToken: "",- })),- workspacePolicy: {- bindings: [{ role: "roles/workspaceAdmin", members: ["[email protected]"] }],- },- hasWorkspacePermissionV2: vi.fn(() => true),- preCreateIssue: vi.fn(),- currentRoute: { name: "workspace.home" } as {- name?: string;- params?: Record<string, string | undefined>;- query?: Record<string, string | undefined>;- },- routerPush: vi.fn(),- captureMetric: vi.fn(),- defaultProjectName: "projects/default",- userCountInIam: 1,- hideQuickStart: false,- workspaceName: "workspaces/default",- productModelContent: "guide content" as string | undefined,-}));--const dismissedIntroStateKey = "workspace-setup-guide.dismissed";-const databaseExploredIntroStateKey =- "workspace-setup-guide.database-explored";-const queryExecutedIntroStateKey = "workspace-setup-guide.query-executed";--vi.mock("react-i18next", () => ({- initReactI18next: { type: "3rdParty", init: () => {} },- useTranslation: () => ({- t: (key: string) => key,- i18n: { resolvedLanguage: "en-US" },- }),-}));--vi.mock("@/components/RouterLink", () => ({- RouterLink: ({- children,- to,- ...props- }: {- children: ReactNode;- to: {- name?: string;- params?: Record<string, string>;- query?: Record<string, string>;- hash?: string;- };- }) => (- <a- data-route-name={to.name}- data-route-params={JSON.stringify(to.params ?? {})}- data-query={to.query?.intro}- data-query-project={to.query?.project}- data-hash={to.hash}- {...props}- >- {children}- </a>- ),-}));--vi.mock("@/app/router", () => ({- router: {- push: mocks.routerPush,- },- useCurrentRoute: () => mocks.currentRoute,- SQL_EDITOR_DATABASE_MODULE: "sql-editor.database",- SQL_EDITOR_HOME_MODULE: "sql-editor.home",- SQL_EDITOR_PROJECT_MODULE: "sql-editor.project",-}));--vi.mock("@/app/analytics/provider", () => ({- behaviorAnalytics: {- captureMetric: mocks.captureMetric,- },-}));--vi.mock("@/stores/app", () => {- const getState = () => ({- projectsByName: mocks.projectsByName,- instancesByName: mocks.instancesByName,- databasesByName: mocks.databasesByName,- currentUserName: "users/[email protected]",- currentUser: {- name: "users/[email protected]",- email: "[email protected]",- workspace: "workspaces/default",- },- workspace: { name: "workspaces/default" },- workspaceResourceName: () => mocks.workspaceName,- workspacePolicy: mocks.workspacePolicy,- hasWorkspacePermission: mocks.hasWorkspacePermissionV2,- serverInfo: {- defaultProject: mocks.defaultProjectName,- },- introStateVersion: mocks.introStateVersion,- getIntroStateByKey: mocks.getIntroStateByKey,- workspaceSetupGuideEnabled: () =>- !mocks.hideQuickStart &&- mocks.userCountInIam === 1 &&- ["bb.projects.list", "bb.instances.list", "bb.databases.list"].every(- mocks.hasWorkspacePermissionV2- ),- });- const useAppStore = (selector?: (s: ReturnType<typeof getState>) => unknown) =>- selector ? selector(getState()) : getState();- useAppStore.getState = () => ({- ...getState(),- fetchProjectList: mocks.fetchProjectList,- fetchInstanceList: mocks.fetchInstanceList,- fetchDatabases: mocks.fetchDatabases,- saveIntroStateByKey: mocks.saveIntroStateByKey,- });- return { useAppStore };-});--vi.mock("@/api", () => ({- queryHistoryServiceClientConnect: {- searchQueryHistories: mocks.searchQueryHistories,- },-}));--vi.mock("@/utils", () => ({- autoSQLEditorDatabaseRoute: (database: {- name: string;- project: string;- }) => {- const match = database.name.match(- /^(?:projects\/[^/]+\/)?instances\/(?<instance>[^/]+)\/databases\/(?<database>[^/]+)$/- );- return {- name: "sql-editor.database",- params: {- project: database.project.replace(/^projects\//, ""),- instance: match?.groups?.instance ?? "",- database: match?.groups?.database ?? "",- },- };- },- extractDatabaseResourceName: (name: string) => {- const match = name.match(- /^(?<instance>(?:projects\/[^/]+\/)?instances\/(?<instanceName>[^/]+))\/databases\/(?<databaseName>[^/]+)$/- );- return {- instance: match?.groups?.instance ?? "",- instanceName: match?.groups?.instanceName ?? "",- databaseName: match?.groups?.databaseName ?? "",- };- },- extractInstanceResourceName: (name: string) =>- name.replace(/^instances\//, ""),- extractProjectResourceName: (name: string) =>- name.replace(/^projects\//, ""),- hasWorkspacePermissionV2: mocks.hasWorkspacePermissionV2,-}));--vi.mock("@/lib/plan/issue", () => ({- preCreateIssue: mocks.preCreateIssue,-}));--vi.mock("@/components/HowBytebaseWorksSheet", () => ({- getHowBytebaseWorksGuideContent: () => mocks.productModelContent,- HowBytebaseWorksSheet: ({- open,- onOpenChange,- }: {- open: boolean;- onOpenChange: (open: boolean) => void;- }) =>- open ? (- <div data-testid="product-model-sheet">- <button- data-testid="close-product-model"- type="button"- onClick={() => onOpenChange(false)}- >- Close- </button>- </div>- ) : null,-}));--import { WorkspaceSetupGuide } from "./WorkspaceSetupGuide";--let container: HTMLDivElement;-let root: ReturnType<typeof createRoot>;--beforeEach(() => {- vi.clearAllMocks();- mocks.introState = {};- mocks.introStateVersion = 0;- mocks.getIntroStateByKey.mockImplementation(- (key: string) => mocks.introState[key] ?? false- );- mocks.saveIntroStateByKey.mockImplementation(({ key, newState }) => {- mocks.introState[key] = newState;- mocks.introStateVersion += 1;- });- mocks.projectsByName = {};- mocks.instancesByName = {};- mocks.databasesByName = {};- mocks.fetchProjectList.mockResolvedValue({- projects: [],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [],- nextPageToken: "",- });- mocks.searchQueryHistories.mockResolvedValue({- queryHistories: [],- nextPageToken: "",- });- mocks.workspacePolicy = {- bindings: [{ role: "roles/workspaceAdmin", members: ["[email protected]"] }],- };- mocks.hasWorkspacePermissionV2.mockReturnValue(true);- mocks.currentRoute = { name: "workspace.home" };- mocks.defaultProjectName = "projects/default";- mocks.userCountInIam = 1;- mocks.hideQuickStart = false;- mocks.workspaceName = "workspaces/default";- mocks.productModelContent = "guide content";- container = document.createElement("div");- document.body.appendChild(container);- root = createRoot(container);-});--afterEach(() => {- vi.useRealTimers();- act(() => {- root.unmount();- });- document.body.removeChild(container);-});--const render = async (element: ReactElement) => {- await act(async () => {- root.render(element);- await Promise.resolve();- await Promise.resolve();- await Promise.resolve();- await Promise.resolve();- });-};--describe("WorkspaceSetupGuide", () => {- it("opens the product model once for a new eligible guide", async () => {- await render(<WorkspaceSetupGuide />);-- expect(- container.querySelector('[data-testid="product-model-sheet"]')- ).not.toBeNull();- });-- it("does not auto-open the product model over a contextual intro", async () => {- mocks.currentRoute = {- name: "workspace.project.database",- query: { intro: "connect-database" },- };-- await render(<WorkspaceSetupGuide />);-- expect(- container.querySelector('[data-testid="product-model-sheet"]')- ).toBeNull();- });-- it("does not auto-open a product model that was already seen", async () => {- mocks.introState["workspace-setup-guide.product-model-seen"] = true;-- await render(<WorkspaceSetupGuide />);-- expect(- container.querySelector('[data-testid="product-model-sheet"]')- ).toBeNull();- });-- it("disables the product model drawer when localized content is missing", async () => {- mocks.productModelContent = undefined;-- await render(<WorkspaceSetupGuide />);-- expect(- container.querySelector('[data-testid="open-product-model"]')- ).toBeNull();- expect(- container.querySelector('[data-testid="product-model-sheet"]')- ).toBeNull();- });-- it("persists seen state when the product model closes", async () => {- await render(<WorkspaceSetupGuide />);-- act(() => {- container- .querySelector<HTMLButtonElement>(- '[data-testid="close-product-model"]'- )- ?.click();- });-- expect(mocks.saveIntroStateByKey).toHaveBeenCalledWith({- key: "workspace-setup-guide.product-model-seen",- newState: true,- });- });-- it("uses the shared product model label for the guide control", async () => {- await render(<WorkspaceSetupGuide />);-- expect(- container.querySelector('[data-testid="open-product-model"]')- ).toHaveAttribute("aria-label", "workspace-setup-guide.product-model");- });-- it("reopens the product model from the guide control", async () => {- mocks.introState["workspace-setup-guide.product-model-seen"] = true;-- await render(<WorkspaceSetupGuide />);-- act(() => {- container- .querySelector<HTMLButtonElement>('[data-testid="open-product-model"]')- ?.click();- });-- expect(- container.querySelector('[data-testid="product-model-sheet"]')- ).not.toBeNull();- expect(mocks.captureMetric).toHaveBeenCalledWith({- event: "setup guide action clicked",- properties: {- action: "product_model_open",- source: "guide_bar",- },- });- });-- it("shows the first incomplete setup action", async () => {- await render(<WorkspaceSetupGuide />);-- expect(container.textContent).toContain(- "workspace-setup-guide.self"- );- expect(container.textContent).toContain(- "workspace-setup-guide.steps.project"- );- expect(container.textContent).toContain(- "workspace-setup-guide.steps.instance"- );- expect(container.textContent).toContain(- "workspace-setup-guide.steps.database"- );- expect(container.textContent).toContain(- "workspace-setup-guide.steps.query"- );- expect(- container.querySelector("[data-testid='setup-step-hasInstance']")?.tagName- ).toBe("BUTTON");- expect(- container.querySelector("[data-testid='setup-step-hasExploredDatabase']")- ?.tagName- ).toBe("BUTTON");- expect(- container.querySelector("[data-testid='setup-step-hasFirstQuery']")- ?.tagName- ).toBe("BUTTON");- expect(container.querySelector("[data-testid='active-action']")).toBeNull();- expect(- container.textContent?.match(/workspace-setup-guide\.steps\.query/g)- ?.length- ).toBe(1);- expect(container.textContent).toContain(- "workspace-setup-guide.steps.project›workspace-setup-guide.steps.instance"- );- expect(container.textContent).not.toContain(- "workspace-setup-guide.steps.project/workspace-setup-guide.steps.instance"- );-- await act(async () => {- (- container.querySelector(- "[data-testid='setup-step-hasInstance']"- ) as HTMLButtonElement | null- )?.click();- await Promise.resolve();- });-- expect(mocks.routerPush).toHaveBeenCalledWith({- name: "workspace.instance",- query: { intro: "create-instance" },- });- });-- it("uses caller-owned responsive button sizing", async () => {- await render(<WorkspaceSetupGuide />);-- expect(container.firstElementChild?.getAttribute("class")).toContain(- "py-2"- );- expect(container.firstElementChild?.getAttribute("class")).toContain(- "2xl:py-4"- );- const projectStep = container.querySelector(- "[data-testid='setup-step-hasProject']"- );- expect(projectStep?.getAttribute("class")).toContain("text-sm");- expect(projectStep?.getAttribute("class")).toContain("2xl:text-base");- expect(projectStep?.getAttribute("class")).toContain("py-1");- expect(projectStep?.getAttribute("class")).toContain("2xl:py-2");- expect(- container- .querySelector("[data-testid='dismiss-guide']")- ?.getAttribute("class")- ).toContain("h-7");- expect(- container- .querySelector("[data-testid='dismiss-guide']")- ?.getAttribute("class")- ).toContain("2xl:h-9");- });-- it("hides when the workspace has more than one member", async () => {- mocks.userCountInIam = 2;-- await render(<WorkspaceSetupGuide />);-- expect(container.textContent).toBe("");- expect(mocks.fetchProjectList).not.toHaveBeenCalled();- });-- it.each([0, 2])("hides when IAM user count is %s", async (count) => {- mocks.userCountInIam = count;-- await render(<WorkspaceSetupGuide />);-- expect(container.textContent).toBe("");- expect(mocks.fetchProjectList).not.toHaveBeenCalled();- });-- it("hides when the quick-start feature is disabled", async () => {- mocks.hideQuickStart = true;-- await render(<WorkspaceSetupGuide />);-- expect(container.textContent).toBe("");- expect(mocks.fetchProjectList).not.toHaveBeenCalled();- });-- it("hides when the user cannot list instances", async () => {- mocks.hasWorkspacePermissionV2.mockReturnValue(false);-- await render(<WorkspaceSetupGuide />);-- expect(container.textContent).toBe("");- expect(mocks.fetchProjectList).not.toHaveBeenCalled();- expect(mocks.fetchInstanceList).not.toHaveBeenCalled();- expect(mocks.fetchDatabases).not.toHaveBeenCalled();- });-- it("shows setup step descriptions in tooltips", async () => {- vi.useFakeTimers();- await render(<WorkspaceSetupGuide />);-- expect(container.textContent).not.toContain(- "workspace-setup-guide.descriptions.project"- );-- const projectStep = container.querySelector(- "[data-testid='setup-step-hasProject']"- );-- await act(async () => {- projectStep?.dispatchEvent(new FocusEvent("focusin", { bubbles: true }));- vi.advanceTimersByTime(100);- await Promise.resolve();- });-- expect(- document.getElementById("bb-react-layer-overlay")?.textContent- ).toContain("workspace-setup-guide.descriptions.project");- expect(container.textContent).not.toContain(- "workspace-setup-guide.descriptions.project"- );- });-- it("shows previous-step guidance in tooltips for disabled setup steps", async () => {- vi.useFakeTimers();- await render(<WorkspaceSetupGuide />);-- const prepareDatabaseStep = container.querySelector(- "[data-testid='setup-step-hasExploredDatabase']"- ) as HTMLButtonElement | null;-- expect(prepareDatabaseStep).toBeDisabled();-- await act(async () => {- prepareDatabaseStep?.parentElement?.dispatchEvent(- new FocusEvent("focusin", { bubbles: true })- );- vi.advanceTimersByTime(100);- await Promise.resolve();- });-- expect(- document.getElementById("bb-react-layer-overlay")?.textContent- ).toContain("workspace-setup-guide.previous-step-required");- });-- it("can be dismissed for the current workspace and user", async () => {- await render(<WorkspaceSetupGuide />);-- expect(container.textContent).toContain(- "workspace-setup-guide.self"- );-- const dismissButton = container.querySelector(- "[data-testid='dismiss-guide']"- ) as HTMLButtonElement | null;-- await act(async () => {- dismissButton?.click();- await Promise.resolve();- });-- expect(mocks.saveIntroStateByKey).toHaveBeenCalledWith({- key: dismissedIntroStateKey,- newState: true,- });- expect(mocks.captureMetric).toHaveBeenCalledWith({- event: "setup guide dismissed",- properties: {- step: "hasProject",- },- });- expect(mocks.introState[dismissedIntroStateKey]).toBe(true);-- await render(<WorkspaceSetupGuide />);-- expect(container.textContent).toBe("");- });-- it("captures the selected setup guide action", async () => {- await render(<WorkspaceSetupGuide />);-- const instanceStep = container.querySelector(- "[data-testid='setup-step-hasInstance']"- ) as HTMLButtonElement | null;-- await act(async () => {- instanceStep?.click();- await Promise.resolve();- });-- expect(mocks.captureMetric).toHaveBeenCalledWith({- event: "setup guide action clicked",- properties: {- step: "hasInstance",- },- });- });-- it("stays hidden after it is dismissed", async () => {- mocks.introState[dismissedIntroStateKey] = true;-- await render(<WorkspaceSetupGuide />);-- expect(container.textContent).toBe("");- expect(mocks.fetchProjectList).not.toHaveBeenCalled();- });-- it("connects an instance from the selected project's instance page", async () => {- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- expect(container.querySelector("[data-testid='active-action']")).toBeNull();- const instanceStep = container.querySelector(- "[data-testid='setup-step-hasInstance']"- );- expect(instanceStep?.tagName).toBe("BUTTON");- await act(async () => {- (instanceStep as HTMLButtonElement | null)?.click();- await Promise.resolve();- });- expect(mocks.routerPush).toHaveBeenCalledWith({- name: "workspace.project.instance",- params: { projectId: "project-a" },- query: { intro: "create-instance" },- });- expect(- container.querySelector("[data-testid='setup-step-hasFirstQuery']")- ?.tagName- ).toBe("BUTTON");- });-- it("keeps the setup project when the first database belongs elsewhere", async () => {- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [- {- name: "instances/sample/databases/employee",- project: "projects/default",- },- ],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- await act(async () => {- (- container.querySelector(- "[data-testid='setup-step-hasInstance']"- ) as HTMLButtonElement | null- )?.click();- await Promise.resolve();- });-- expect(mocks.routerPush).toHaveBeenCalledWith({- name: "workspace.project.instance",- params: { projectId: "project-a" },- query: { intro: "create-instance" },- });- });-- it("disables the prepare database step until a project and instance exist", async () => {- await render(<WorkspaceSetupGuide />);-- expect(- container.querySelector(- "[data-testid='setup-step-hasExploredDatabase']"- )- ).toBeDisabled();-- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- expect(- container.querySelector(- "[data-testid='setup-step-hasExploredDatabase']"- )- ).toBeDisabled();- });-- it("opens workspace databases with transfer guidance when the project has no databases", async () => {- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "instances/instance-a" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- const prepareStep = container.querySelector(- "[data-testid='setup-step-hasExploredDatabase']"- ) as HTMLButtonElement | null;-- expect(prepareStep).not.toBeDisabled();-- await act(async () => {- prepareStep?.click();- await Promise.resolve();- });-- expect(mocks.routerPush).toHaveBeenCalledWith({- name: "workspace.database",- query: {- intro: "prepare-database",- tip: "transfer-databases-to-project",- },- });- });-- it("opens project databases with query and change guidance when the project has a database", async () => {- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "instances/instance-a" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [- {- name: "instances/instance-a/databases/db-a",- project: "projects/project-a",- },- ],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- const prepareStep = container.querySelector(- "[data-testid='setup-step-hasExploredDatabase']"- ) as HTMLButtonElement | null;-- expect(prepareStep).not.toBeDisabled();-- await act(async () => {- prepareStep?.click();- await Promise.resolve();- });-- expect(mocks.routerPush).toHaveBeenCalledWith({- name: "workspace.project.database",- params: { projectId: "project-a" },- query: {- intro: "project-instance-synced",- },- });- });-- it("does not replay create guidance from completed steps", async () => {- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "instances/instance-a" }],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- await act(async () => {- (- container.querySelector(- "[data-testid='setup-step-hasProject']"- ) as HTMLButtonElement | null- )?.click();- await Promise.resolve();- });-- expect(mocks.routerPush).not.toHaveBeenCalled();- });-- it("highlights the setup step matching the current route", async () => {- mocks.currentRoute = { name: "workspace.instance" };-- await render(<WorkspaceSetupGuide />);-- expect(- container- .querySelector("[data-testid='setup-step-hasInstance']")- ?.getAttribute("class")- ).toContain("bg-accent/10");-- expect(container.querySelector("[data-testid='active-action']")).toBeNull();- });-- it("stays visible and asks for a project when an instance exists first", async () => {- mocks.currentRoute = { name: "workspace.instance.detail" };- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/default" }],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "instances/instance-a" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [- {- name: "instances/instance-a/databases/db-a",- project: "projects/default",- },- ],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- expect(container.textContent).toContain(- "workspace-setup-guide.self"- );-- expect(container.querySelector("[data-testid='active-action']")).toBeNull();- });-- it("does not use the default project as the setup project", async () => {- mocks.introState[databaseExploredIntroStateKey] = true;- mocks.fetchProjectList.mockResolvedValue({- projects: [- { name: "projects/default" },- { name: "projects/project-a" },- ],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "instances/instance-a" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [- {- name: "instances/instance-a/databases/db-a",- project: "projects/project-a",- },- ],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- expect(mocks.fetchDatabases).toHaveBeenCalledWith(- expect.objectContaining({- parent: "workspaces/default",- pageSize: 1,- filter: { project: "projects/project-a" },- })- );-- const actionButton = container.querySelector(- "[data-testid='secondary-action']"- ) as HTMLButtonElement | null;-- await act(async () => {- actionButton?.click();- await Promise.resolve();- });-- expect(mocks.preCreateIssue).toHaveBeenCalledWith("projects/project-a", [- "instances/instance-a/databases/db-a",- ]);- });-- it("counts workspace-owned instances as project and instance readiness", async () => {- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-sample" }],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [- { name: "instances/sample-one" },- { name: "instances/sample-two" },- ],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [- {- name: "instances/sample-one/databases/employee",- project: "projects/project-sample",- },- {- name: "instances/sample-two/databases/employee",- project: "projects/project-sample",- },- ],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- for (const key of ["hasProject", "hasInstance"]) {- expect(- container- .querySelector(`[data-testid='setup-step-${key}']`)- ?.querySelector(".lucide-circle-check-big")- ).not.toBeNull();- }- for (const key of ["hasExploredDatabase", "hasFirstQuery"]) {- expect(- container- .querySelector(`[data-testid='setup-step-${key}']`)- ?.querySelector(".lucide-circle-check-big")- ).toBeNull();- }- });-- it("counts project-owned instances as project and instance readiness", async () => {- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/app" }],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "projects/app/instances/project-sample" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [- {- name: "projects/app/instances/project-sample/databases/employee",- project: "projects/app",- },- ],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- for (const key of ["hasProject", "hasInstance"]) {- expect(- container- .querySelector(`[data-testid='setup-step-${key}']`)- ?.querySelector(".lucide-circle-check-big")- ).not.toBeNull();- }- for (const key of ["hasExploredDatabase", "hasFirstQuery"]) {- expect(- container- .querySelector(`[data-testid='setup-step-${key}']`)- ?.querySelector(".lucide-circle-check-big")- ).toBeNull();- }- });-- it("uses only the first resource page", async () => {- mocks.introState[databaseExploredIntroStateKey] = true;- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-sample" }],- nextPageToken: "project-page-2",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "instances/sample" }],- nextPageToken: "instance-page-2",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [- {- name: "instances/sample/databases/employee",- project: "projects/project-sample",- },- ],- nextPageToken: "database-page-2",- });-- await render(<WorkspaceSetupGuide />);-- expect(- container- .querySelector("[data-testid='setup-step-hasExploredDatabase']")- ?.querySelector(".lucide-circle-check-big")- ).not.toBeNull();- expect(- container.querySelector("[data-testid='active-action']")- ).toHaveAttribute(- "data-route-params",- JSON.stringify({- project: "project-sample",- instance: "sample",- database: "employee",- })- );- expect(mocks.fetchProjectList).toHaveBeenCalledTimes(1);- expect(mocks.fetchInstanceList).toHaveBeenCalledTimes(2);- expect(mocks.fetchDatabases).toHaveBeenCalledTimes(1);- expect(mocks.fetchProjectList).toHaveBeenCalledWith(- expect.objectContaining({ pageSize: 1 })- );- expect(mocks.fetchInstanceList).toHaveBeenCalledWith(- expect.objectContaining({ pageSize: 1, parent: "projects/project-sample" })- );- expect(mocks.fetchDatabases).toHaveBeenCalledWith(- expect.objectContaining({- parent: "workspaces/default",- pageSize: 1,- filter: { project: "projects/project-sample" },- })- );- });-- it.each([- "fetchProjectList",- "fetchInstanceList",- "fetchDatabases",- ] as const)("keeps the guide available when %s fails", async (key) => {- if (key === "fetchDatabases") {- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });- }- mocks[key].mockRejectedValueOnce(new Error("permission denied"));-- await render(<WorkspaceSetupGuide />);-- expect(mocks[key]).toHaveBeenCalled();- expect(container.textContent).toContain("workspace-setup-guide.self");- expect(- container.querySelector("[data-testid='setup-step-hasProject']")- ).not.toBeNull();- });-- it.each([- {- name: PROJECT_V1_ROUTE_DATABASE_DETAIL,- params: {- projectId: "project-sample",- instanceId: "sample-one",- databaseName: "employee",- },- },- {- name: INSTANCE_ROUTE_DATABASE_DETAIL,- params: {- instanceId: "sample-one",- databaseName: "employee",- },- },- {- name: SQL_EDITOR_DATABASE_MODULE,- params: {- project: "project-sample",- instance: "sample-one",- database: "employee",- },- },- ])("persists database exploration on $name", async (route) => {- mocks.currentRoute = route;- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-sample" }],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "instances/sample-one" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [- {- name: "instances/sample-one/databases/employee",- project: "projects/project-sample",- },- ],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- expect(mocks.saveIntroStateByKey).toHaveBeenCalledWith({- key: databaseExploredIntroStateKey,- newState: true,- });- });-- it("does not count the workspace database list as exploration", async () => {- mocks.currentRoute = { name: DATABASE_ROUTE_DASHBOARD };- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "instances/instance-a" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [- {- name: "instances/instance-a/databases/db-a",- project: "projects/project-a",- },- ],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- expect(mocks.saveIntroStateByKey).not.toHaveBeenCalledWith({- key: databaseExploredIntroStateKey,- newState: true,- });- expect(- container- .querySelector("[data-testid='setup-step-hasExploredDatabase']")- ?.querySelector(".lucide-circle-check-big")- ).toBeNull();- });-- it("keeps database exploration complete after it is persisted", async () => {- mocks.introState[databaseExploredIntroStateKey] = true;- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "instances/instance-a" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [- {- name: "instances/instance-a/databases/db-a",- project: "projects/project-a",- },- ],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- expect(- container- .querySelector("[data-testid='setup-step-hasExploredDatabase']")- ?.querySelector(".lucide-circle-check-big")- ).not.toBeNull();- });-- it("does not show the active guide action when already on its route", async () => {- mocks.currentRoute = { name: "workspace.instance.create" };- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- expect(container.textContent).toContain(- "workspace-setup-guide.steps.instance"- );- expect(container.querySelector("[data-testid='active-action']")).toBeNull();- expect(container.querySelector("[data-testid='dismiss-guide']")).not.toBeNull();- });-- it("highlights the next incomplete step when the current route step is done", async () => {- mocks.currentRoute = { name: "workspace.project" };- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "instances/instance-a" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- expect(- container- .querySelector("[data-testid='setup-step-hasProject']")- ?.getAttribute("class")- ).not.toContain("bg-accent/10");- expect(- container- .querySelector("[data-testid='setup-step-hasExploredDatabase']")- ?.getAttribute("class")- ).toContain("bg-accent/10");-- expect(container.querySelector("[data-testid='active-action']")).toBeNull();- });-- it("highlights the active query step on project database pages", async () => {- mocks.currentRoute = {- name: PROJECT_V1_ROUTE_DATABASE_DETAIL,- params: {- projectId: "project-a",- instanceId: "instance-a",- databaseName: "db-a",- },- };- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "projects/project-a/instances/instance-a" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [- {- name: "instances/instance-a/databases/db-a",- project: "projects/project-a",- },- ],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- expect(mocks.fetchInstanceList).toHaveBeenCalledWith(- expect.objectContaining({ pageSize: 1 })- );- expect(- container- .querySelector("[data-testid='setup-step-hasProject']")- ?.getAttribute("class")- ).not.toContain("bg-accent/10");- expect(- container- .querySelector("[data-testid='setup-step-hasInstance']")- ?.getAttribute("class")- ).not.toContain("bg-accent/10");- expect(- container- .querySelector("[data-testid='setup-step-hasFirstQuery']")- ?.getAttribute("class")- ).toContain("bg-accent/10");- expect(- container.querySelector("[data-testid='active-action']")- ).not.toBeNull();- });-- it("does not highlight the next setup step on unrelated pages", async () => {- mocks.currentRoute = { name: "workspace.home" };- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- for (const key of [- "hasProject",- "hasInstance",- "hasExploredDatabase",- "hasFirstQuery",- ]) {- expect(- container- .querySelector(`[data-testid='setup-step-${key}']`)- ?.getAttribute("class")- ).not.toContain("bg-accent/10");- }-- expect(container.querySelector("[data-testid='active-action']")).toBeNull();- });-- it("asks users to create a database when the connected instance has no databases", async () => {- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "instances/instance-a" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockImplementation(async ({ parent } = {}) => ({- databases: parent === "projects/project-a" ? [] : [],- nextPageToken: "",- }));-- await render(<WorkspaceSetupGuide />);-- expect(container.textContent).toContain(- "workspace-setup-guide.steps.database"- );- expect(container.querySelector("[data-testid='active-action']")).toBeNull();- });-- it("asks users to transfer a database when the connected instance has no project database", async () => {- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "instances/instance-a" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockImplementation(async ({ parent } = {}) => ({- databases:- parent === "instances/instance-a"- ? [{ name: "instances/instance-a/databases/db-a" }]- : [],- nextPageToken: "",- }));-- await render(<WorkspaceSetupGuide />);-- expect(container.textContent).toContain(- "workspace-setup-guide.steps.database"- );- expect(container.querySelector("[data-testid='active-action']")).toBeNull();- });-- it("opens SQL Editor as the primary action after a database is connected", async () => {- mocks.introState[databaseExploredIntroStateKey] = true;- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "instances/instance-a" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [- {- name: "instances/instance-a/databases/db-a",- project: "projects/project-a",- },- ],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- expect(container.textContent).toContain(- "workspace-setup-guide.steps.query"- );- const actionLink = container.querySelector(- "[data-testid='active-action']"- );- expect(actionLink?.getAttribute("data-route-name")).toBe(- "sql-editor.database"- );- expect(actionLink?.getAttribute("data-route-params")).toBe(- JSON.stringify({- project: "project-a",- instance: "instance-a",- database: "db-a",- })- );- expect(actionLink?.textContent).toContain(- "workspace-setup-guide.actions.query"- );- expect(actionLink?.querySelector(".lucide-square-terminal")).not.toBeNull();- expect(actionLink).toHaveAttribute("target", "_blank");- expect(actionLink).toHaveAttribute("rel", "noopener noreferrer");- expect(- container- .querySelector("[data-testid='setup-step-hasFirstQuery']")- ?.querySelector(".lucide-circle-check-big")- ).toBeNull();-- act(() => {- (actionLink as HTMLAnchorElement | null)?.click();- });- expect(mocks.saveIntroStateByKey).not.toHaveBeenCalledWith({- key: queryExecutedIntroStateKey,- newState: true,- });-- const secondaryAction = container.querySelector(- "[data-testid='secondary-action']"- );- expect(secondaryAction).not.toBeNull();- expect(secondaryAction?.getAttribute("class")).toContain(- "2xl:inline-flex"- );- expect(- secondaryAction!.compareDocumentPosition(actionLink as Node) &- Node.DOCUMENT_POSITION_FOLLOWING- ).toBe(Node.DOCUMENT_POSITION_FOLLOWING);-- act(() => {- (secondaryAction as HTMLButtonElement).click();- });- expect(mocks.preCreateIssue).toHaveBeenCalledWith("projects/project-a", [- "instances/instance-a/databases/db-a",- ]);- });-- it("completes Query data only after SQL execution finishes", async () => {- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "instances/instance-a" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [- {- name: "instances/instance-a/databases/db-a",- project: "projects/project-a",- },- ],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- const queryStep = container.querySelector(- "[data-testid='setup-step-hasFirstQuery']"- );- expect(queryStep?.querySelector(".lucide-circle-check-big")).toBeNull();-- await act(async () => {- await sqlEditorEvents.emit("query-executed", {- database: "",- project: "projects/project-a",- });- });-- expect(queryStep?.querySelector(".lucide-circle-check-big")).toBeNull();- expect(mocks.saveIntroStateByKey).not.toHaveBeenCalledWith({- key: queryExecutedIntroStateKey,- newState: true,- });-- await act(async () => {- await sqlEditorEvents.emit("query-executed", {- database: "projects/project-a/instances/instance-a/databases/db-a",- project: "projects/project-a",- });- });-- expect(mocks.saveIntroStateByKey).toHaveBeenCalledWith({- key: databaseExploredIntroStateKey,- newState: true,- });- expect(mocks.saveIntroStateByKey).toHaveBeenCalledWith({- key: queryExecutedIntroStateKey,- newState: true,- });- expect(- queryStep?.querySelector(".lucide-circle-check-big")- ).not.toBeNull();- });-- it("keeps query progress and its event target while resource scans finish", async () => {- type ProjectResponse = {- projects: { name: string }[];- nextPageToken: string;- };- let resolveFirstScan: ((value: ProjectResponse) => void) | undefined;- let resolveSecondScan: ((value: ProjectResponse) => void) | undefined;- mocks.fetchProjectList- .mockImplementationOnce(- () =>- new Promise((resolve) => {- resolveFirstScan = resolve;- })- )- .mockImplementationOnce(- () =>- new Promise((resolve) => {- resolveSecondScan = resolve;- })- );- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "instances/discovered-instance" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [- {- name: "instances/discovered-instance/databases/discovered-db",- project: "projects/discovered-project",- },- ],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);- expect(mocks.fetchProjectList).toHaveBeenCalledTimes(1);-- await act(async () => {- await sqlEditorEvents.emit("query-executed", {- database: "instances/event-instance/databases/event-db",- project: "projects/event-project",- });- });- expect(mocks.fetchProjectList).toHaveBeenCalledTimes(2);-- const assertInteractionState = () => {- for (const key of ["hasExploredDatabase", "hasFirstQuery"]) {- expect(- container- .querySelector(`[data-testid='setup-step-${key}']`)- ?.querySelector(".lucide-circle-check-big")- ).not.toBeNull();- }- expect(- container.querySelector("[data-testid='active-action']")- ).toHaveAttribute(- "data-route-params",- JSON.stringify({- project: "event-project",- instance: "event-instance",- database: "event-db",- })- );- };-- await act(async () => {- resolveFirstScan?.({- projects: [{ name: "projects/discovered-project" }],- nextPageToken: "",- });- await Promise.resolve();- await Promise.resolve();- await Promise.resolve();- await Promise.resolve();- });- assertInteractionState();-- await act(async () => {- resolveSecondScan?.({- projects: [{ name: "projects/discovered-project" }],- nextPageToken: "",- });- await Promise.resolve();- await Promise.resolve();- await Promise.resolve();- await Promise.resolve();- });- assertInteractionState();- });-- it("does not reconstruct query completion from query history", async () => {- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/app" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [- {- name: "instances/prod/databases/main",- project: "projects/app",- },- ],- nextPageToken: "",- });- mocks.searchQueryHistories.mockResolvedValue({- queryHistories: [- { database: "instances/prod/databases/main" },- ],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- expect(- container- .querySelector("[data-testid='setup-step-hasFirstQuery']")- ?.querySelector(".lucide-circle-check-big")- ).toBeNull();- });-- it("does not search query history for guide progress", async () => {- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/app" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [- {- name: "instances/prod/databases/main",- project: "projects/app",- },- ],- nextPageToken: "",- });- await render(<WorkspaceSetupGuide />);-- expect(mocks.searchQueryHistories).not.toHaveBeenCalled();- });-- it("activates the query step when users click it after visiting another step", async () => {- mocks.introState[databaseExploredIntroStateKey] = true;- mocks.currentRoute = { name: "workspace.database" };- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "instances/instance-a" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [- {- name: "instances/instance-a/databases/db-a",- project: "projects/project-a",- },- ],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- expect(- container- .querySelector("[data-testid='setup-step-hasExploredDatabase']")- ?.getAttribute("class")- ).not.toContain("bg-accent/10");- expect(- container- .querySelector("[data-testid='setup-step-hasFirstQuery']")- ?.getAttribute("class")- ).toContain("bg-accent/10");-- const queryStep = container.querySelector(- "[data-testid='setup-step-hasFirstQuery']"- );-- expect(queryStep?.tagName).toBe("BUTTON");- expect(queryStep?.getAttribute("class")).toContain("bg-accent/10");-- await act(async () => {- (queryStep as HTMLButtonElement | null)?.click();- await Promise.resolve();- });-- expect(- container- .querySelector("[data-testid='setup-step-hasFirstQuery']")- ?.getAttribute("class")- ).toContain("bg-accent/10");- expect(- container.querySelector("[data-testid='active-action']")?.textContent- ).toContain("workspace-setup-guide.actions.query");- });-- it("opens the first database change flow as a secondary action", async () => {- mocks.introState[databaseExploredIntroStateKey] = true;- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "instances/instance-a" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [- {- name: "instances/instance-a/databases/db-a",- project: "projects/project-a",- },- ],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- const changeButton = container.querySelector(- "[data-testid='secondary-action']"- ) as HTMLButtonElement | null;- expect(changeButton?.tagName).toBe("BUTTON");- expect(changeButton?.textContent).toContain(- "workspace-setup-guide.actions.change"- );- const secondaryAction = container.querySelector(- "[data-testid='secondary-action']"- );- expect(secondaryAction?.getAttribute("class")).toContain("h-9");- for (const testId of ["active-action", "dismiss-guide"]) {- const action = container.querySelector(`[data-testid='${testId}']`);- expect(action?.getAttribute("class")).toContain("h-7");- expect(action?.getAttribute("class")).toContain("2xl:h-9");- }-- await act(async () => {- changeButton?.click();- await Promise.resolve();- });-- expect(mocks.preCreateIssue).toHaveBeenCalledWith("projects/project-a", [- "instances/instance-a/databases/db-a",- ]);- });-- it("stays visible after the first query exists", async () => {- mocks.introState[databaseExploredIntroStateKey] = true;- mocks.introState[queryExecutedIntroStateKey] = true;- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "instances/instance-a" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [- {- name: "instances/instance-a/databases/db-a",- project: "projects/project-a",- },- ],- nextPageToken: "",- });- await render(<WorkspaceSetupGuide />);-- expect(container.textContent).toContain(- "workspace-setup-guide.self"- );- expect(container.textContent).toContain(- "workspace-setup-guide.steps.query"- );- expect(- container.querySelector("[data-testid='active-action']")?.textContent- ).toContain("workspace-setup-guide.actions.query");- });-- it("skips first query check before a project database exists", async () => {- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "instances/instance-a" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [],- nextPageToken: "",- });- await render(<WorkspaceSetupGuide />);-- expect(mocks.searchQueryHistories).not.toHaveBeenCalled();- expect(container.querySelector("[data-testid='active-action']")).toBeNull();- });-- it("keeps the query step disabled before a project database exists", async () => {- mocks.currentRoute = { name: "workspace.database" };- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "instances/instance-a" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- const queryStep = container.querySelector(- "[data-testid='setup-step-hasFirstQuery']"- );-- expect(queryStep?.tagName).toBe("BUTTON");- expect(queryStep).toBeDisabled();- expect(queryStep?.getAttribute("class")).not.toContain("bg-accent/10");-- await act(async () => {- (queryStep as HTMLButtonElement | null)?.click();- await Promise.resolve();- });-- expect(- container- .querySelector("[data-testid='setup-step-hasFirstQuery']")- ?.getAttribute("class")- ).not.toContain("bg-accent/10");- expect(container.querySelector("[data-testid='active-action']")).toBeNull();- });-- it("refreshes when a new instance is added to the app store", async () => {- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- expect(container.textContent).toContain(- "workspace-setup-guide.steps.instance"- );-- mocks.instancesByName = { "instances/instance-a": {} };- mocks.fetchInstanceList.mockResolvedValue({- instances: [],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- expect(container.textContent).toContain(- "workspace-setup-guide.steps.database"- );- });-- it("completes the instance step for an instance owned by the project", async () => {- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });- mocks.fetchInstanceList.mockImplementation(async (params) => ({- instances:- params?.parent === "projects/project-a"- ? [{ name: "projects/project-a/instances/sample" }]- : [],- nextPageToken: "",- }));-- await render(<WorkspaceSetupGuide />);-- expect(mocks.fetchInstanceList).toHaveBeenCalledWith(- expect.objectContaining({ parent: "projects/project-a", pageSize: 1 })- );- expect(- container- .querySelector("[data-testid='setup-step-hasInstance']")- ?.querySelector(".lucide-circle-check-big")- ).not.toBeNull();- });-- it("keeps the guide visible while progress is refreshing", async () => {- let resolveProjectList:- | ((value: { projects: unknown[]; nextPageToken: string }) => void)- | undefined;-- await render(<WorkspaceSetupGuide />);-- expect(container.textContent).toContain(- "workspace-setup-guide.self"- );-- mocks.currentRoute = { name: "workspace.instance.detail" };- mocks.instancesByName = { "instances/instance-a": {} };- mocks.fetchProjectList.mockReturnValue(- new Promise((resolve) => {- resolveProjectList = resolve;- })- );-- await render(<WorkspaceSetupGuide />);-- expect(container.textContent).toContain(- "workspace-setup-guide.self"- );- expect(container.textContent).toContain(- "workspace-setup-guide.steps.project"- );-- await act(async () => {- resolveProjectList?.({ projects: [], nextPageToken: "" });- await Promise.resolve();- });- });-- it("refreshes when a database is added to the app store", async () => {- mocks.introState[databaseExploredIntroStateKey] = true;- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "instances/instance-a" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- expect(container.querySelector("[data-testid='active-action']")).toBeNull();-- mocks.databasesByName = {- "instances/instance-a/databases/db-a": {},- };- mocks.fetchDatabases.mockResolvedValue({- databases: [- {- name: "instances/instance-a/databases/db-a",- project: "projects/project-a",- },- ],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- expect(container.textContent).toContain(- "workspace-setup-guide.actions.change"- );- });-- it("refreshes when the route changes after setup progress changes elsewhere", async () => {- mocks.introState[databaseExploredIntroStateKey] = true;- mocks.fetchProjectList.mockResolvedValue({- projects: [{ name: "projects/project-a" }],- nextPageToken: "",- });- mocks.fetchInstanceList.mockResolvedValue({- instances: [{ name: "instances/instance-a" }],- nextPageToken: "",- });- mocks.fetchDatabases.mockResolvedValue({- databases: [],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- expect(container.querySelector("[data-testid='active-action']")).toBeNull();-- mocks.currentRoute = { name: "workspace.member" };- mocks.fetchDatabases.mockResolvedValue({- databases: [- {- name: "instances/instance-a/databases/db-a",- project: "projects/project-a",- },- ],- nextPageToken: "",- });-- await render(<WorkspaceSetupGuide />);-- expect(container.textContent).toContain(- "workspace-setup-guide.actions.change"- );- });-});diff --git a/frontend/src/components/WorkspaceSetupGuide.tsx b/frontend/src/components/WorkspaceSetupGuide.tsxdeleted file mode 100644index 89afff6d86..0000000000--- a/frontend/src/components/WorkspaceSetupGuide.tsx+++ /dev/null@@ -1,636 +0,0 @@-import { CheckCircle, Circle, CircleHelp, X } from "lucide-react";-import { useEffect, useMemo, useRef, useState } from "react";-import { useTranslation } from "react-i18next";-import { createBehaviorMetric } from "@/app/analytics/behavior";-import { behaviorAnalytics } from "@/app/analytics/provider";-import { type RouteTarget, router, useCurrentRoute } from "@/app/router";-import {- DATABASE_ROUTE_DASHBOARD,- INSTANCE_ROUTE_DASHBOARD,- INSTANCE_ROUTE_DATABASE_DETAIL,- PROJECT_V1_ROUTE_DASHBOARD,- PROJECT_V1_ROUTE_DATABASE_DETAIL,- PROJECT_V1_ROUTE_DATABASES,- PROJECT_V1_ROUTE_INSTANCES,- SQL_EDITOR_DATABASE_MODULE,-} from "@/app/router/handles";-import {- getHowBytebaseWorksGuideContent,- HowBytebaseWorksSheet,-} from "@/components/HowBytebaseWorksSheet";-import { SQLEditorButton } from "@/components/SQLEditorButton";-import { Button } from "@/components/ui/button";-import { Tooltip } from "@/components/ui/tooltip";-import { useIntroStateByKey } from "@/hooks/useAppState";-import { preCreateIssue } from "@/lib/plan/issue";-import {- CREATE_INSTANCE_PRODUCT_INTRO,- CREATE_PROJECT_PRODUCT_INTRO,- PREPARE_DATABASE_PRODUCT_INTRO,- PREPARE_DATABASE_TRANSFER_TIP,- PRODUCT_INTRO_QUERY_KEY,- PRODUCT_INTRO_TIP_QUERY_KEY,- PROJECT_INSTANCE_SYNCED_PRODUCT_INTRO,-} from "@/lib/productIntro";-import { cn } from "@/lib/utils";-import { sqlEditorEvents } from "@/modules/sql-editor/model/events";-import { useAppStore } from "@/stores/app";-import { State } from "@/types/proto-es/v1/common_pb";-import { extractProjectResourceName } from "@/utils";--type SetupKeys = {- hasProject: boolean;- hasInstance: boolean;- hasExploredDatabase: boolean;- hasFirstQuery: boolean;-};--type SetupState = SetupKeys & {- projectName: string;- databaseProjectName: string;- databaseName: string;-};--type SetupStep = {- key: keyof SetupKeys;- label: string;- description: string;- link?: RouteTarget;- done: boolean;- disabled?: boolean;- matchesRoute?: (routeName: string | undefined) => boolean;-};--const initialSetupState: SetupState = {- hasProject: false,- hasInstance: false,- hasExploredDatabase: false,- hasFirstQuery: false,- projectName: "",- databaseProjectName: "",- databaseName: "",-};--const WORKSPACE_SETUP_GUIDE_DISMISSED_KEY = "workspace-setup-guide.dismissed";-const WORKSPACE_SETUP_GUIDE_DATABASE_EXPLORED_KEY =- "workspace-setup-guide.database-explored";-const WORKSPACE_SETUP_GUIDE_QUERY_EXECUTED_KEY =- "workspace-setup-guide.query-executed";-const WORKSPACE_SETUP_GUIDE_PRODUCT_MODEL_SEEN_KEY =- "workspace-setup-guide.product-model-seen";--const isRouteInside = (routeName: string | undefined, parentName: string) =>- routeName === parentName || !!routeName?.startsWith(`${parentName}.`);--const hasRouteParams = (- params: Record<string, string | string[] | undefined>,- keys: string[]-) =>- keys.every((key) => {- const value = params[key];- return typeof value === "string" && value.length > 0;- });--const isConcreteDatabaseRoute = (- name: string | undefined,- params: Record<string, string | string[] | undefined>-) => {- switch (name) {- case PROJECT_V1_ROUTE_DATABASE_DETAIL:- return hasRouteParams(params, [- "projectId",- "instanceId",- "databaseName",- ]);- case INSTANCE_ROUTE_DATABASE_DETAIL:- return hasRouteParams(params, ["instanceId", "databaseName"]);- case SQL_EDITOR_DATABASE_MODULE:- return hasRouteParams(params, ["project", "instance", "database"]);- default:- return false;- }-};--export function WorkspaceSetupGuide() {- const { i18n, t } = useTranslation();- const currentRoute = useCurrentRoute();- const dismissed = useIntroStateByKey(WORKSPACE_SETUP_GUIDE_DISMISSED_KEY);- const databaseExplored = useIntroStateByKey(- WORKSPACE_SETUP_GUIDE_DATABASE_EXPLORED_KEY- );- const queryExecuted = useIntroStateByKey(- WORKSPACE_SETUP_GUIDE_QUERY_EXECUTED_KEY- );- const productModelSeen = useIntroStateByKey(- WORKSPACE_SETUP_GUIDE_PRODUCT_MODEL_SEEN_KEY- );- const serverInfo = useAppStore((s) => s.serverInfo);- const defaultProject = serverInfo?.defaultProject ?? "";- const projectCacheSize = useAppStore(- (s) => Object.keys(s.projectsByName).length- );- const instanceCacheSize = useAppStore(- (s) => Object.keys(s.instancesByName).length- );- const databaseCacheSize = useAppStore(- (s) => Object.keys(s.databasesByName).length- );- const workspaceResourceName = useAppStore((s) => s.workspaceResourceName());- const guideEnabled = useAppStore((s) => s.workspaceSetupGuideEnabled());- const productModelAvailable = !!getHowBytebaseWorksGuideContent(- i18n.resolvedLanguage ?? "en-US"- );- const hasContextualProductIntro =- typeof currentRoute.query?.[PRODUCT_INTRO_QUERY_KEY] === "string";- const [loading, setLoading] = useState(true);- const [productModelOpen, setProductModelOpen] = useState(false);- const [selectedStepKey, setSelectedStepKey] = useState<keyof SetupKeys>();- const [setupState, setSetupState] = useState<SetupState>(initialSetupState);- const productModelAutoOpenedScopeRef = useRef<string | undefined>(undefined);- const queryTargetRef = useRef<- { projectName: string; databaseName: string } | undefined- >(undefined);-- useEffect(() => {- const off = sqlEditorEvents.on(- "query-executed",- ({ data: { database, project } }) => {- if (!database) {- return;- }-- queryTargetRef.current = {- projectName: project,- databaseName: database,- };- const store = useAppStore.getState();- if (!databaseExplored) {- store.saveIntroStateByKey({- key: WORKSPACE_SETUP_GUIDE_DATABASE_EXPLORED_KEY,- newState: true,- });- }- if (!queryExecuted) {- store.saveIntroStateByKey({- key: WORKSPACE_SETUP_GUIDE_QUERY_EXECUTED_KEY,- newState: true,- });- }- setSetupState((state) => ({- ...state,- hasExploredDatabase: true,- hasFirstQuery: true,- databaseProjectName: project,- databaseName: database,- }));- }- );- return () => {- off();- };- }, [databaseExplored, queryExecuted]);-- useEffect(() => {- if (- dismissed ||- !guideEnabled ||- databaseExplored ||- !isConcreteDatabaseRoute(currentRoute.name, currentRoute.params ?? {})- ) {- return;- }-- useAppStore.getState().saveIntroStateByKey({- key: WORKSPACE_SETUP_GUIDE_DATABASE_EXPLORED_KEY,- newState: true,- });- setSetupState((state) => ({- ...state,- hasExploredDatabase: true,- }));- }, [- currentRoute.name,- currentRoute.params,- databaseExplored,- dismissed,- guideEnabled,- ]);-- useEffect(() => {- setSelectedStepKey(undefined);- }, [currentRoute.name]);-- useEffect(() => {- if (productModelSeen) {- productModelAutoOpenedScopeRef.current = undefined;- return;- }- if (- loading ||- dismissed ||- !guideEnabled ||- !productModelAvailable ||- hasContextualProductIntro ||- !workspaceResourceName ||- productModelAutoOpenedScopeRef.current === workspaceResourceName- ) {- return;- }- productModelAutoOpenedScopeRef.current = workspaceResourceName;- setProductModelOpen(true);- }, [- dismissed,- guideEnabled,- hasContextualProductIntro,- loading,- productModelAvailable,- productModelSeen,- workspaceResourceName,- ]);-- const onSelectStep = (step: SetupStep) => {- behaviorAnalytics.captureMetric(- createBehaviorMetric("setup guide action clicked", {- properties: {- step: step.key,- },- })- );- setSelectedStepKey(step.key);- if (step.link) {- void router.push(step.link);- }- };-- useEffect(() => {- if (dismissed || !guideEnabled) {- setSetupState(initialSetupState);- setLoading(false);- return;- }-- void (async () => {- const store = useAppStore.getState();- try {- const projectResponse = await store.fetchProjectList({- pageSize: 1,- silent: true,- filter: {- excludeDefault: true,- state: State.ACTIVE,- },- });- const project = projectResponse.projects.find(- ({ name }) => !!name && name !== defaultProject- );- const [- workspaceInstanceResponse,- projectInstanceResponse,- databaseResponse,- ] = await Promise.all([- store.fetchInstanceList({- pageSize: 1,- filter: { state: State.ACTIVE },- silent: true,- }),- project- ? store.fetchInstanceList({- parent: project.name,- pageSize: 1,- filter: { state: State.ACTIVE },- silent: true,- })- : Promise.resolve({ instances: [], nextPageToken: "" }),- project && workspaceResourceName- ? store.fetchDatabases({- parent: workspaceResourceName,- pageSize: 1,- filter: { project: project.name },- silent: true,- })- : Promise.resolve(undefined),- ]);- const instance =- workspaceInstanceResponse.instances[0] ??- projectInstanceResponse.instances[0];- const database = databaseResponse?.databases.find(- ({ name, project }) => !!name && !!project- );-- const latestDatabaseExplored = store.getIntroStateByKey(- WORKSPACE_SETUP_GUIDE_DATABASE_EXPLORED_KEY- );- const latestQueryExecuted = store.getIntroStateByKey(- WORKSPACE_SETUP_GUIDE_QUERY_EXECUTED_KEY- );- const queryTarget = latestQueryExecuted- ? queryTargetRef.current- : undefined;-- setSetupState({- hasProject: !!project,- hasInstance: !!instance,- hasExploredDatabase: latestDatabaseExplored,- hasFirstQuery: latestQueryExecuted,- projectName: project?.name ?? "",- databaseProjectName:- queryTarget?.projectName ?? database?.project ?? "",- databaseName: queryTarget?.databaseName ?? database?.name ?? "",- });- } catch {- // Keep the current progress when resource discovery is unavailable.- }- setLoading(false);- })();- }, [- databaseCacheSize,- databaseExplored,- defaultProject,- dismissed,- guideEnabled,- instanceCacheSize,- projectCacheSize,- queryExecuted,- currentRoute.name,- workspaceResourceName,- ]);-- const sqlEditorDatabase = useMemo(() => {- if (!setupState.databaseName || !setupState.databaseProjectName) {- return undefined;- }- return {- name: setupState.databaseName,- project: setupState.databaseProjectName,- };- }, [setupState.databaseName, setupState.databaseProjectName]);-- const steps = useMemo<SetupStep[]>(- () => [- {- key: "hasProject",- label: t("workspace-setup-guide.steps.project"),- description: t("workspace-setup-guide.descriptions.project"),- link: setupState.hasProject- ? undefined- : {- name: PROJECT_V1_ROUTE_DASHBOARD,- query: {- [PRODUCT_INTRO_QUERY_KEY]: CREATE_PROJECT_PRODUCT_INTRO,- },- },- done: setupState.hasProject,- matchesRoute: (routeName) => routeName === PROJECT_V1_ROUTE_DASHBOARD,- },- {- key: "hasInstance",- label: t("workspace-setup-guide.steps.instance"),- description: t("workspace-setup-guide.descriptions.instance"),- link: setupState.hasInstance- ? undefined- : setupState.projectName- ? {- name: PROJECT_V1_ROUTE_INSTANCES,- params: {- projectId: extractProjectResourceName(setupState.projectName),- },- query: {- [PRODUCT_INTRO_QUERY_KEY]: CREATE_INSTANCE_PRODUCT_INTRO,- },- }- : {- name: INSTANCE_ROUTE_DASHBOARD,- query: {- [PRODUCT_INTRO_QUERY_KEY]: CREATE_INSTANCE_PRODUCT_INTRO,- },- },- done: setupState.hasInstance,- matchesRoute: (routeName) =>- isRouteInside(routeName, INSTANCE_ROUTE_DASHBOARD) ||- isRouteInside(routeName, PROJECT_V1_ROUTE_INSTANCES),- },- {- key: "hasExploredDatabase",- label: t("workspace-setup-guide.steps.database"),- description: t("workspace-setup-guide.descriptions.database"),- link: sqlEditorDatabase- ? {- name: PROJECT_V1_ROUTE_DATABASES,- params: {- projectId: extractProjectResourceName(- setupState.databaseProjectName- ),- },- query: {- [PRODUCT_INTRO_QUERY_KEY]:- PROJECT_INSTANCE_SYNCED_PRODUCT_INTRO,- },- }- : {- name: DATABASE_ROUTE_DASHBOARD,- query: {- [PRODUCT_INTRO_QUERY_KEY]: PREPARE_DATABASE_PRODUCT_INTRO,- [PRODUCT_INTRO_TIP_QUERY_KEY]: PREPARE_DATABASE_TRANSFER_TIP,- },- },- done: setupState.hasExploredDatabase,- disabled: !setupState.hasProject || !setupState.hasInstance,- matchesRoute: (routeName) =>- isRouteInside(routeName, DATABASE_ROUTE_DASHBOARD) ||- isRouteInside(routeName, PROJECT_V1_ROUTE_DATABASES) ||- routeName === INSTANCE_ROUTE_DATABASE_DETAIL,- },- {- key: "hasFirstQuery",- label: t("workspace-setup-guide.steps.query"),- description: t("workspace-setup-guide.descriptions.sql-editor"),- done: setupState.hasFirstQuery,- disabled: !setupState.hasExploredDatabase,- matchesRoute: (routeName) =>- isRouteInside(routeName, SQL_EDITOR_DATABASE_MODULE),- },- ],- [setupState, sqlEditorDatabase, t]- );-- const activeStep = steps.find((step) => !step.done) ?? steps.at(-1)!;- const selectedStep = steps.find((step) => step.key === selectedStepKey);- const routeMatchedStep = steps.find(- (step) => step.matchesRoute?.(currentRoute.name) ?? false- );- const highlightedStep =- selectedStep ?? (routeMatchedStep?.done ? activeStep : routeMatchedStep);- const actionStep =- highlightedStep && !highlightedStep.done ? highlightedStep : activeStep;-- const handleCreateFirstChange = () => {- behaviorAnalytics.captureMetric(- createBehaviorMetric("setup guide action clicked", {- properties: {- step: "createFirstChange",- },- })- );- void preCreateIssue(setupState.databaseProjectName, [- setupState.databaseName,- ]);- };-- const handleDismiss = () => {- behaviorAnalytics.captureMetric(- createBehaviorMetric("setup guide dismissed", {- properties: {- step: actionStep.key,- },- })- );- useAppStore.getState().saveIntroStateByKey({- key: WORKSPACE_SETUP_GUIDE_DISMISSED_KEY,- newState: true,- });- };-- const handleProductModelOpenChange = (open: boolean) => {- if (open) {- behaviorAnalytics.captureMetric(- createBehaviorMetric("setup guide action clicked", {- properties: {- action: "product_model_open",- source: "guide_bar",- },- })- );- }- setProductModelOpen(open);- if (!open && !productModelSeen) {- useAppStore.getState().saveIntroStateByKey({- key: WORKSPACE_SETUP_GUIDE_PRODUCT_MODEL_SEEN_KEY,- newState: true,- });- }- };-- if (dismissed || !guideEnabled || loading) {- return null;- }-- return (- <>- <div className="flex w-full shrink-0 items-center gap-x-2 border-t border-block-border bg-white px-3 py-2 shadow-[0_-2px_10px_rgba(0,0,0,0.04)] 2xl:gap-x-4 2xl:px-5 2xl:py-4">- <div className="flex min-w-0 flex-1 items-center gap-x-2 overflow-hidden 2xl:gap-x-4">- <div className="flex shrink-0 items-center gap-x-1">- <div className="shrink-0 text-sm font-semibold text-main 2xl:text-base">- {t("workspace-setup-guide.self")}- </div>- {productModelAvailable && (- <Tooltip content={t("workspace-setup-guide.product-model")}>- <Button- type="button"- appearance="secondary"- size="sm"- data-testid="open-product-model"- aria-label={t("workspace-setup-guide.product-model")}- onClick={() => handleProductModelOpenChange(true)}- >- <CircleHelp className="size-4" />- </Button>- </Tooltip>- )}- </div>- <div className="flex min-w-0 flex-1 items-center gap-x-2 overflow-x-auto pr-1 2xl:gap-x-3 2xl:pr-2">- {steps.map((step, index) => {- const isHighlighted = step.key === highlightedStep?.key;- const tooltipContent = step.disabled- ? t("workspace-setup-guide.previous-step-required")- : step.description;- const className = cn(- "inline-flex items-center gap-x-1 rounded-sm px-2 py-1 text-sm whitespace-nowrap 2xl:gap-x-2 2xl:px-3 2xl:py-2 2xl:text-base",- isHighlighted- ? "bg-accent/10 text-accent"- : step.done- ? "text-control-light"- : "text-control"- );-- return (- <div- key={step.key}- className="inline-flex items-center gap-x-2 2xl:gap-x-3"- >- <Tooltip content={tooltipContent}>- <Button- type="button"- appearance="secondary"- data-testid={`setup-step-${step.key}`}- className={cn(- className,- "h-auto justify-start py-1 font-medium 2xl:py-2"- )}- disabled={step.disabled}- onClick={() => onSelectStep(step)}- >- {step.done ? (- <CheckCircle className="size-4 text-success 2xl:size-5" />- ) : (- <Circle className="size-4 2xl:size-5" />- )}- <span>{step.label}</span>- </Button>- </Tooltip>- {index < steps.length - 1 && (- <span className="text-sm text-control-light 2xl:text-base">- ›- </span>- )}- </div>- );- })}- </div>- </div>- <div className="ml-auto flex shrink-0 items-center gap-x-2">- {actionStep.key === "hasFirstQuery" &&- setupState.databaseProjectName &&- setupState.databaseName && (- <Button- type="button"- data-testid="secondary-action"- appearance="secondary"- size="md"- className="hidden 2xl:inline-flex"- onClick={handleCreateFirstChange}- >- {t("workspace-setup-guide.actions.change")}- </Button>- )}- {actionStep.key === "hasFirstQuery" && sqlEditorDatabase && (- <SQLEditorButton- data-testid="active-action"- database={sqlEditorDatabase}- openInNewTab- size="sm"- className="2xl:h-9 2xl:gap-1.5 2xl:px-3 2xl:text-sm 2xl:leading-5"- label={t("workspace-setup-guide.actions.query")}- />- )}- <Button- type="button"- data-testid="dismiss-guide"- aria-label={t("workspace-setup-guide.dismiss")}- appearance="secondary"- size="sm"- className="text-control-light hover:text-control 2xl:h-9 2xl:gap-1.5 2xl:px-3 2xl:text-sm 2xl:leading-5"- onClick={handleDismiss}- >- <X className="size-4 2xl:size-5" />- </Button>- </div>- </div>- {productModelAvailable && (- <HowBytebaseWorksSheet- open={productModelOpen && !hasContextualProductIntro}- onOpenChange={handleProductModelOpenChange}- />- )}- </>- );-}diff --git a/frontend/src/components/header/HeaderBreadcrumb.test.tsx b/frontend/src/components/header/HeaderBreadcrumb.test.tsxindex 4b28264639..069d8e0e5e 100644--- a/frontend/src/components/header/HeaderBreadcrumb.test.tsx+++ b/frontend/src/components/header/HeaderBreadcrumb.test.tsx@@ -260,6 +260,8 @@ describe("HeaderBreadcrumb", () => {(button) => button.textContent?.includes("Recent Project"));expect(projectButton).not.toBeUndefined();+ expect(projectButton?.classList.contains("h-7")).toBe(true);+ expect(projectButton?.classList.contains("h-auto")).toBe(false);act(() => {projectButton?.click();@@ -289,6 +291,8 @@ describe("HeaderBreadcrumb", () => {container.querySelectorAll("button")).find((button) => button.textContent?.includes("Default Workspace"));expect(workspaceButton).not.toBeUndefined();+ expect(workspaceButton?.classList.contains("h-7")).toBe(true);+ expect(workspaceButton?.classList.contains("h-auto")).toBe(false);act(() => {workspaceButton?.click();diff --git a/frontend/src/components/header/HeaderBreadcrumb.tsx b/frontend/src/components/header/HeaderBreadcrumb.tsxindex ea3ac43cd1..67dbb00304 100644--- a/frontend/src/components/header/HeaderBreadcrumb.tsx+++ b/frontend/src/components/header/HeaderBreadcrumb.tsx@@ -132,7 +132,7 @@ export function WorkspaceSegment({appearance="secondary"size="sm"onClick={(event) => onSelectWorkspace(currentWorkspaceName, event)}- className="h-auto px-2 py-1 text-sm gap-x-1.5"+ className="text-sm gap-x-1.5"><Building2 className="size-4 text-control-light shrink-0" /><span className="truncate max-w-40">{workspace?.title}</span>@@ -266,7 +266,7 @@ export function ProjectSegment({appearance="secondary"size="sm"onClick={(event) => onSelectProject(currentProject, event)}- className="h-auto px-2 py-1 text-sm gap-x-1.5"+ className="text-sm gap-x-1.5"><FolderKanban className="size-4 text-control-light shrink-0" /><span className="truncate max-w-48">{currentProject.title}</span>@@ -307,7 +307,7 @@ export function ProjectSegment({type="button"appearance="secondary"size="sm"- className="h-auto px-2 py-1 text-sm gap-x-1.5 text-control-placeholder"+ className="text-sm gap-x-1.5 text-control-placeholder"/>)}diff --git a/frontend/src/modules/sql-editor/components/ResultView/ResultStatusBar.test.tsx b/frontend/src/modules/sql-editor/components/ResultView/ResultStatusBar.test.tsxindex 78f6e673b3..07b42f0a58 100644--- a/frontend/src/modules/sql-editor/components/ResultView/ResultStatusBar.test.tsx+++ b/frontend/src/modules/sql-editor/components/ResultView/ResultStatusBar.test.tsx@@ -142,6 +142,8 @@ describe("ResultStatusBar", () => {expect(statement.className).not.toContain("max-w-3xl");expect(statementText?.classList.contains("flex-1")).toBe(false);expect(copyButton.className).toContain("shrink-0");+ expect(copyButton.className).toContain("h-6");+ expect(copyButton.className).not.toContain("h-auto");});test("hides the statement copy button when the statement is empty", () => {diff --git a/frontend/src/modules/sql-editor/components/ResultView/ResultStatusBar.tsx b/frontend/src/modules/sql-editor/components/ResultView/ResultStatusBar.tsxindex e0ce7d8cd4..158b93ab81 100644--- a/frontend/src/modules/sql-editor/components/ResultView/ResultStatusBar.tsx+++ b/frontend/src/modules/sql-editor/components/ResultView/ResultStatusBar.tsx@@ -108,7 +108,7 @@ export function ResultStatusBar({content={statement}size="xs"appearance="secondary"- className="h-auto shrink-0 px-0 text-control-light hover:bg-transparent hover:text-control"+ className="shrink-0 text-control-light hover:bg-transparent hover:text-control"/>)}</div>diff --git a/frontend/src/modules/sql-editor/components/SQLEditorHomePage.test.tsx b/frontend/src/modules/sql-editor/components/SQLEditorHomePage.test.tsxindex 74d225b85a..13cb8146e4 100644--- a/frontend/src/modules/sql-editor/components/SQLEditorHomePage.test.tsx+++ b/frontend/src/modules/sql-editor/components/SQLEditorHomePage.test.tsx@@ -35,7 +35,7 @@ vi.mock("@/components/IAMRemindDialog", () => ({IAMRemindDialog: () => <div />,}));-vi.mock("@/components/WorkspaceSetupGuide", () => ({+vi.mock("@/modules/workspace-setup-guide/WorkspaceSetupGuide", () => ({WorkspaceSetupGuide: () => <div>unified-guide</div>,}));diff --git a/frontend/src/modules/sql-editor/components/SQLEditorHomePage.tsx b/frontend/src/modules/sql-editor/components/SQLEditorHomePage.tsxindex d499f4b11c..72dbda5299 100644--- a/frontend/src/modules/sql-editor/components/SQLEditorHomePage.tsx+++ b/frontend/src/modules/sql-editor/components/SQLEditorHomePage.tsx@@ -15,7 +15,6 @@ import {LAYER_BACKDROP_CLASS,LAYER_SURFACE_CLASS,} from "@/components/ui/layer";-import { WorkspaceSetupGuide } from "@/components/WorkspaceSetupGuide";import { useAppProject } from "@/hooks/useAppProject";import { applyPlanTitleToQuery } from "@/lib/plan/title";import { cn } from "@/lib/utils";@@ -37,6 +36,7 @@ import {useCurrentSQLEditorTab,useIsDisconnected,} from "@/modules/sql-editor/store/tab";+import { WorkspaceSetupGuide } from "@/modules/workspace-setup-guide/WorkspaceSetupGuide";import { useAppStore } from "@/stores/app";import { unknownProject } from "@/types";import {diff --git a/frontend/src/modules/workspace-setup-guide/WorkspaceSetupGuide.test.tsx b/frontend/src/modules/workspace-setup-guide/WorkspaceSetupGuide.test.tsxnew file mode 100644index 0000000000..e8b2669100--- /dev/null+++ b/frontend/src/modules/workspace-setup-guide/WorkspaceSetupGuide.test.tsx@@ -0,0 +1,498 @@+import { act, cleanup, fireEvent, render, screen } from "@testing-library/react";+import type { ReactNode } from "react";+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";+import type { GuideContext } from "./types";+import { WorkspaceSetupGuide } from "./WorkspaceSetupGuide";++const guideContext = (+ overrides: Partial<GuideContext> = {}+): GuideContext => ({+ hasProject: false,+ hasInstance: false,+ hasExploredDatabase: false,+ hasFirstQuery: false,+ projectName: "",+ databaseProjectName: "",+ databaseName: "",+ route: { name: "workspace.home", params: {} },+ ...overrides,+});++const mocks = vi.hoisted(() => ({+ captureMetric: vi.fn(),+ currentRoute: {+ name: "workspace.home",+ params: {},+ query: {},+ } as {+ name?: string;+ params: Record<string, string | string[] | undefined>;+ query?: Record<string, string | string[] | undefined>;+ },+ guideContext: undefined as unknown as GuideContext,+ guideEnabled: true,+ introState: {} as Record<string, boolean>,+ loading: false,+ preCreateIssue: vi.fn(),+ productModelContent: "guide content" as string | undefined,+ routerPush: vi.fn(),+ saveIntroStateByKey: vi.fn(),+ workspaceName: "workspaces/default",+}));++vi.mock("react-i18next", () => ({+ initReactI18next: { type: "3rdParty", init: () => {} },+ useTranslation: () => ({+ t: (key: string) => key,+ i18n: { resolvedLanguage: "en-US" },+ }),+}));++vi.mock("@/app/router", () => ({+ router: { push: mocks.routerPush },+ useCurrentRoute: () => mocks.currentRoute,+}));++vi.mock("@/app/analytics/provider", () => ({+ behaviorAnalytics: { captureMetric: mocks.captureMetric },+}));++vi.mock("@/components/HowBytebaseWorksSheet", () => ({+ getHowBytebaseWorksGuideContent: () => mocks.productModelContent,+ HowBytebaseWorksSheet: ({+ open,+ onOpenChange,+ }: {+ open: boolean;+ onOpenChange: (open: boolean) => void;+ }) =>+ open ? (+ <div data-testid="product-model-sheet">+ <button+ type="button"+ data-testid="close-product-model"+ onClick={() => onOpenChange(false)}+ >+ Close+ </button>+ </div>+ ) : null,+}));++vi.mock("@/components/SQLEditorButton", () => ({+ SQLEditorButton: ({+ className,+ label,+ ...props+ }: {+ className?: string;+ label?: ReactNode;+ database?: unknown;+ openInNewTab?: boolean;+ size?: string;+ "data-testid"?: string;+ }) => {+ const { database: _database, openInNewTab: _openInNewTab, size: _size, ...rest } =+ props;+ return (+ <a+ {...rest}+ className={`inline-flex h-7 gap-1 px-2 text-xs leading-4 ${className ?? ""}`}+ >+ {label}+ </a>+ );+ },+}));++vi.mock("@/hooks/useAppState", () => ({+ useIntroStateByKey: (key: string) => mocks.introState[key] ?? false,+}));++vi.mock("@/lib/plan/issue", () => ({+ preCreateIssue: mocks.preCreateIssue,+}));++vi.mock("@/stores/app", () => {+ const getState = () => ({+ workspaceResourceName: () => mocks.workspaceName,+ workspaceSetupGuideEnabled: () => mocks.guideEnabled,+ });+ const useAppStore = (selector: (state: ReturnType<typeof getState>) => unknown) =>+ selector(getState());+ useAppStore.getState = () => ({+ ...getState(),+ saveIntroStateByKey: mocks.saveIntroStateByKey,+ });+ return { useAppStore };+});++vi.mock("./useGuideContext", () => ({+ useGuideContext: () => ({+ context: mocks.guideContext,+ loading: mocks.loading,+ }),+}));++beforeEach(() => {+ vi.clearAllMocks();+ mocks.currentRoute = { name: "workspace.home", params: {}, query: {} };+ mocks.guideContext = guideContext();+ mocks.guideEnabled = true;+ mocks.introState = {};+ mocks.loading = false;+ mocks.productModelContent = "guide content";+ mocks.workspaceName = "workspaces/default";+ mocks.saveIntroStateByKey.mockImplementation(({ key, newState }) => {+ mocks.introState[key] = newState;+ });+});++afterEach(() => {+ cleanup();+ vi.useRealTimers();+});++describe("WorkspaceSetupGuide", () => {+ test("renders the approved scenario order with legacy test IDs", () => {+ render(<WorkspaceSetupGuide />);+ expect(+ screen+ .getAllByTestId(/^setup-step-/)+ .map((element) => element.getAttribute("data-testid"))+ ).toEqual([+ "setup-step-hasProject",+ "setup-step-hasInstance",+ "setup-step-hasExploredDatabase",+ "setup-step-hasFirstQuery",+ ]);+ });++ test("blocks dependency steps and preserves their tooltip", async () => {+ vi.useFakeTimers();+ render(<WorkspaceSetupGuide />);+ const exploreStep = screen.getByTestId("setup-step-hasExploredDatabase");+ expect(exploreStep).toBeDisabled();+ expect(screen.getByTestId("setup-step-hasFirstQuery")).toBeDisabled();+ fireEvent.focusIn(exploreStep.parentElement!);+ await act(async () => {+ vi.advanceTimersByTime(100);+ await Promise.resolve();+ });+ expect(+ document.getElementById("bb-react-layer-overlay")?.textContent+ ).toContain("workspace-setup-guide.previous-step-required");+ });++ test("records and dispatches a selected step action", () => {+ render(<WorkspaceSetupGuide />);+ fireEvent.click(screen.getByTestId("setup-step-hasInstance"));+ expect(mocks.captureMetric).toHaveBeenCalledWith({+ event: "setup guide action clicked",+ properties: { step: "hasInstance" },+ });+ expect(mocks.routerPush).toHaveBeenCalledWith({+ name: "workspace.instance",+ query: { intro: "create-instance" },+ });+ });++ test("renders query and change actions for the resolved query step", () => {+ mocks.guideContext = guideContext({+ hasProject: true,+ hasInstance: true,+ hasExploredDatabase: true,+ databaseProjectName: "projects/app",+ databaseName: "instances/sample/databases/employee",+ });+ render(<WorkspaceSetupGuide />);+ expect(screen.getByTestId("active-action")).toBeVisible();+ expect(screen.getByTestId("secondary-action")).toBeVisible();+ });++ test("dismisses with the active step legacy analytics key", () => {+ render(<WorkspaceSetupGuide />);+ fireEvent.click(screen.getByTestId("dismiss-guide"));+ expect(mocks.captureMetric).toHaveBeenCalledWith({+ event: "setup guide dismissed",+ properties: { step: "hasProject" },+ });+ expect(mocks.saveIntroStateByKey).toHaveBeenCalledWith({+ key: "workspace-setup-guide.dismissed",+ newState: true,+ });+ });++ test("opens the product model once for a new eligible guide", () => {+ render(<WorkspaceSetupGuide />);+ expect(screen.getByTestId("product-model-sheet")).toBeVisible();+ });++ test("does not auto-open the product model over a contextual intro", () => {+ mocks.currentRoute = {+ name: "workspace.project.database",+ params: {},+ query: { intro: "connect-database" },+ };+ render(<WorkspaceSetupGuide />);+ expect(screen.queryByTestId("product-model-sheet")).not.toBeInTheDocument();+ });++ test("does not auto-open a product model that was already seen", () => {+ mocks.introState["workspace-setup-guide.product-model-seen"] = true;+ render(<WorkspaceSetupGuide />);+ expect(screen.queryByTestId("product-model-sheet")).not.toBeInTheDocument();+ });++ test("disables the product model drawer when localized content is missing", () => {+ mocks.productModelContent = undefined;+ render(<WorkspaceSetupGuide />);+ expect(screen.queryByTestId("open-product-model")).not.toBeInTheDocument();+ expect(screen.queryByTestId("product-model-sheet")).not.toBeInTheDocument();+ });++ test("persists seen state when the product model closes", () => {+ render(<WorkspaceSetupGuide />);+ fireEvent.click(screen.getByTestId("close-product-model"));+ expect(mocks.saveIntroStateByKey).toHaveBeenCalledWith({+ key: "workspace-setup-guide.product-model-seen",+ newState: true,+ });+ });++ test("uses the shared product model label for the guide control", () => {+ render(<WorkspaceSetupGuide />);+ expect(screen.getByTestId("open-product-model")).toHaveAttribute(+ "aria-label",+ "workspace-setup-guide.product-model"+ );+ });++ test("reopens the product model from the guide control", () => {+ mocks.introState["workspace-setup-guide.product-model-seen"] = true;+ render(<WorkspaceSetupGuide />);+ fireEvent.click(screen.getByTestId("open-product-model"));+ expect(screen.getByTestId("product-model-sheet")).toBeVisible();+ expect(mocks.captureMetric).toHaveBeenCalledWith({+ event: "setup guide action clicked",+ properties: {+ action: "product_model_open",+ source: "guide_bar",+ },+ });+ });++ test("uses caller-owned responsive button sizing", () => {+ const { container } = render(<WorkspaceSetupGuide />);+ expect(container.firstElementChild).toHaveClass("py-2", "2xl:py-4");+ expect(screen.getByTestId("setup-step-hasProject")).toHaveClass(+ "text-sm",+ "2xl:text-base",+ "py-1",+ "2xl:py-2"+ );+ expect(screen.getByTestId("dismiss-guide")).toHaveClass("h-7", "2xl:h-9");+ });++ test("shows setup step descriptions in tooltips", async () => {+ vi.useFakeTimers();+ const { container } = render(<WorkspaceSetupGuide />);+ expect(container).not.toHaveTextContent(+ "workspace-setup-guide.descriptions.project"+ );+ fireEvent.focusIn(screen.getByTestId("setup-step-hasProject"));+ await act(async () => {+ vi.advanceTimersByTime(100);+ await Promise.resolve();+ });+ expect(+ document.getElementById("bb-react-layer-overlay")?.textContent+ ).toContain("workspace-setup-guide.descriptions.project");+ expect(container).not.toHaveTextContent(+ "workspace-setup-guide.descriptions.project"+ );+ });++ test("shows previous-step guidance in tooltips for disabled setup steps", async () => {+ vi.useFakeTimers();+ render(<WorkspaceSetupGuide />);+ const exploreStep = screen.getByTestId("setup-step-hasExploredDatabase");+ expect(exploreStep).toBeDisabled();+ fireEvent.focusIn(exploreStep.parentElement!);+ await act(async () => {+ vi.advanceTimersByTime(100);+ await Promise.resolve();+ });+ expect(+ document.getElementById("bb-react-layer-overlay")?.textContent+ ).toContain("workspace-setup-guide.previous-step-required");+ });++ test("can be dismissed for the current workspace and user", () => {+ const { rerender } = render(<WorkspaceSetupGuide />);+ expect(screen.getByText("workspace-setup-guide.self")).toBeVisible();+ fireEvent.click(screen.getByTestId("dismiss-guide"));+ expect(mocks.saveIntroStateByKey).toHaveBeenCalledWith({+ key: "workspace-setup-guide.dismissed",+ newState: true,+ });+ expect(mocks.captureMetric).toHaveBeenCalledWith({+ event: "setup guide dismissed",+ properties: { step: "hasProject" },+ });+ rerender(<WorkspaceSetupGuide />);+ expect(screen.queryByText("workspace-setup-guide.self")).not.toBeInTheDocument();+ });++ test("captures the selected setup guide action", () => {+ render(<WorkspaceSetupGuide />);+ fireEvent.click(screen.getByTestId("setup-step-hasInstance"));+ expect(mocks.captureMetric).toHaveBeenCalledWith({+ event: "setup guide action clicked",+ properties: { step: "hasInstance" },+ });+ });++ test("stays hidden after it is dismissed", () => {+ mocks.introState["workspace-setup-guide.dismissed"] = true;+ render(<WorkspaceSetupGuide />);+ expect(screen.queryByText("workspace-setup-guide.self")).not.toBeInTheDocument();+ });++ test("does not replay create guidance from completed steps", () => {+ mocks.guideContext = guideContext({+ hasProject: true,+ hasInstance: true,+ });+ render(<WorkspaceSetupGuide />);+ fireEvent.click(screen.getByTestId("setup-step-hasProject"));+ expect(mocks.routerPush).not.toHaveBeenCalled();+ });++ test("highlights the setup step matching the current route", () => {+ mocks.guideContext = guideContext({+ route: { name: "workspace.instance", params: {} },+ });+ mocks.currentRoute = { name: "workspace.instance", params: {}, query: {} };+ render(<WorkspaceSetupGuide />);+ expect(screen.getByTestId("setup-step-hasInstance")).toHaveClass(+ "bg-accent/10"+ );+ expect(screen.queryByTestId("active-action")).not.toBeInTheDocument();+ });++ test("does not show the active guide action when already on its route", () => {+ mocks.guideContext = guideContext({+ hasProject: true,+ projectName: "projects/app",+ route: { name: "workspace.instance.create", params: {} },+ });+ mocks.currentRoute = {+ name: "workspace.instance.create",+ params: {},+ query: {},+ };+ render(<WorkspaceSetupGuide />);+ expect(screen.queryByTestId("active-action")).not.toBeInTheDocument();+ expect(screen.getByTestId("dismiss-guide")).toBeVisible();+ });++ test("highlights the next incomplete step when the current route step is done", () => {+ mocks.guideContext = guideContext({+ hasProject: true,+ hasInstance: true,+ projectName: "projects/app",+ route: { name: "workspace.project", params: {} },+ });+ mocks.currentRoute = { name: "workspace.project", params: {}, query: {} };+ render(<WorkspaceSetupGuide />);+ expect(screen.getByTestId("setup-step-hasProject")).not.toHaveClass(+ "bg-accent/10"+ );+ expect(screen.getByTestId("setup-step-hasExploredDatabase")).toHaveClass(+ "bg-accent/10"+ );+ expect(screen.queryByTestId("active-action")).not.toBeInTheDocument();+ });++ test("does not highlight the next setup step on unrelated pages", () => {+ mocks.guideContext = guideContext({ hasProject: true });+ render(<WorkspaceSetupGuide />);+ for (const key of [+ "hasProject",+ "hasInstance",+ "hasExploredDatabase",+ "hasFirstQuery",+ ]) {+ expect(screen.getByTestId(`setup-step-${key}`)).not.toHaveClass(+ "bg-accent/10"+ );+ }+ expect(screen.queryByTestId("active-action")).not.toBeInTheDocument();+ });++ test("activates the query step when users click it after visiting another step", () => {+ mocks.guideContext = guideContext({+ hasProject: true,+ hasInstance: true,+ hasExploredDatabase: true,+ projectName: "projects/app",+ databaseProjectName: "projects/app",+ databaseName: "instances/sample/databases/employee",+ route: { name: "workspace.database", params: {} },+ });+ mocks.currentRoute = { name: "workspace.database", params: {}, query: {} };+ render(<WorkspaceSetupGuide />);+ fireEvent.click(screen.getByTestId("setup-step-hasInstance"));+ fireEvent.click(screen.getByTestId("setup-step-hasFirstQuery"));+ expect(screen.getByTestId("setup-step-hasFirstQuery")).toHaveClass(+ "bg-accent/10"+ );+ expect(screen.getByTestId("active-action")).toHaveTextContent(+ "workspace-setup-guide.actions.query"+ );+ });++ test("opens the first database change flow as a secondary action", () => {+ mocks.guideContext = guideContext({+ hasProject: true,+ hasInstance: true,+ hasExploredDatabase: true,+ databaseProjectName: "projects/app",+ databaseName: "instances/sample/databases/employee",+ });+ render(<WorkspaceSetupGuide />);+ const changeButton = screen.getByTestId("secondary-action");+ expect(changeButton).toHaveTextContent(+ "workspace-setup-guide.actions.change"+ );+ expect(changeButton).toHaveClass("h-9");+ expect(screen.getByTestId("active-action")).toHaveClass("h-7", "2xl:h-9");+ expect(screen.getByTestId("dismiss-guide")).toHaveClass("h-7", "2xl:h-9");+ fireEvent.click(changeButton);+ expect(mocks.captureMetric).toHaveBeenCalledWith({+ event: "setup guide action clicked",+ properties: { step: "createFirstChange" },+ });+ expect(mocks.preCreateIssue).toHaveBeenCalledWith("projects/app", [+ "instances/sample/databases/employee",+ ]);+ });++ test("stays visible after the first query exists", () => {+ mocks.guideContext = guideContext({+ hasProject: true,+ hasInstance: true,+ hasExploredDatabase: true,+ hasFirstQuery: true,+ databaseProjectName: "projects/app",+ databaseName: "instances/sample/databases/employee",+ });+ render(<WorkspaceSetupGuide />);+ expect(screen.getByText("workspace-setup-guide.self")).toBeVisible();+ expect(screen.getByText("workspace-setup-guide.steps.query")).toBeVisible();+ expect(screen.getByTestId("active-action")).toHaveTextContent(+ "workspace-setup-guide.actions.query"+ );+ });+});diff --git a/frontend/src/modules/workspace-setup-guide/WorkspaceSetupGuide.tsx b/frontend/src/modules/workspace-setup-guide/WorkspaceSetupGuide.tsxnew file mode 100644index 0000000000..ba90e5716b--- /dev/null+++ b/frontend/src/modules/workspace-setup-guide/WorkspaceSetupGuide.tsx@@ -0,0 +1,269 @@+import { CheckCircle, Circle, CircleHelp, X } from "lucide-react";+import { useEffect, useMemo, useRef, useState } from "react";+import { useTranslation } from "react-i18next";+import { createBehaviorMetric } from "@/app/analytics/behavior";+import { behaviorAnalytics } from "@/app/analytics/provider";+import { router, useCurrentRoute } from "@/app/router";+import {+ getHowBytebaseWorksGuideContent,+ HowBytebaseWorksSheet,+} from "@/components/HowBytebaseWorksSheet";+import { SQLEditorButton } from "@/components/SQLEditorButton";+import { Button } from "@/components/ui/button";+import { Tooltip } from "@/components/ui/tooltip";+import { useIntroStateByKey } from "@/hooks/useAppState";+import { preCreateIssue } from "@/lib/plan/issue";+import { PRODUCT_INTRO_QUERY_KEY } from "@/lib/productIntro";+import { cn } from "@/lib/utils";+import { useAppStore } from "@/stores/app";+import { resolveGuide } from "./resolve";+import { LEARN_BYTEBASE_BASICS_SCENARIO } from "./scenarios";+import { GUIDE_STEP_REGISTRY } from "./steps";+import type { GuideStepId, ResolvedGuideStep } from "./types";+import { useGuideContext } from "./useGuideContext";++const DISMISSED_KEY = "workspace-setup-guide.dismissed";+const PRODUCT_MODEL_SEEN_KEY = "workspace-setup-guide.product-model-seen";++export function WorkspaceSetupGuide() {+ const { i18n, t } = useTranslation();+ const currentRoute = useCurrentRoute();+ const dismissed = useIntroStateByKey(DISMISSED_KEY);+ const productModelSeen = useIntroStateByKey(PRODUCT_MODEL_SEEN_KEY);+ const guideEnabled = useAppStore((state) =>+ state.workspaceSetupGuideEnabled()+ );+ const workspaceResourceName = useAppStore((state) =>+ state.workspaceResourceName()+ );+ const { context, loading } = useGuideContext({+ enabled: guideEnabled,+ dismissed,+ route: currentRoute,+ });+ const productModelAvailable = !!getHowBytebaseWorksGuideContent(+ i18n.resolvedLanguage ?? "en-US"+ );+ const hasContextualProductIntro =+ typeof currentRoute.query?.[PRODUCT_INTRO_QUERY_KEY] === "string";+ const [productModelOpen, setProductModelOpen] = useState(false);+ const [selectedStepId, setSelectedStepId] = useState<GuideStepId>();+ const productModelAutoOpenedScopeRef = useRef<string | undefined>(undefined);+ const guide = useMemo(+ () =>+ resolveGuide({+ scenario: LEARN_BYTEBASE_BASICS_SCENARIO,+ registry: GUIDE_STEP_REGISTRY,+ context,+ selectedStepId,+ }),+ [context, selectedStepId]+ );+ const secondaryAction = guide.actionStep.actions.secondary;+ const primaryAction = guide.actionStep.actions.primary;++ useEffect(() => {+ setSelectedStepId(undefined);+ }, [currentRoute.name]);++ useEffect(() => {+ if (productModelSeen) {+ productModelAutoOpenedScopeRef.current = undefined;+ return;+ }+ if (+ loading ||+ dismissed ||+ !guideEnabled ||+ !productModelAvailable ||+ hasContextualProductIntro ||+ !workspaceResourceName ||+ productModelAutoOpenedScopeRef.current === workspaceResourceName+ ) {+ return;+ }+ productModelAutoOpenedScopeRef.current = workspaceResourceName;+ setProductModelOpen(true);+ }, [+ dismissed,+ guideEnabled,+ hasContextualProductIntro,+ loading,+ productModelAvailable,+ productModelSeen,+ workspaceResourceName,+ ]);++ const onSelectStep = (step: ResolvedGuideStep) => {+ behaviorAnalytics.captureMetric(+ createBehaviorMetric("setup guide action clicked", {+ properties: { step: step.definition.analyticsKey },+ })+ );+ setSelectedStepId(step.definition.id);+ if (step.actions.select?.type === "navigate") {+ void router.push(step.actions.select.target);+ }+ };++ const handleDismiss = () => {+ behaviorAnalytics.captureMetric(+ createBehaviorMetric("setup guide dismissed", {+ properties: {+ step: guide.actionStep.definition.analyticsKey,+ },+ })+ );+ useAppStore.getState().saveIntroStateByKey({+ key: DISMISSED_KEY,+ newState: true,+ });+ };++ const handleProductModelOpenChange = (open: boolean) => {+ if (open) {+ behaviorAnalytics.captureMetric(+ createBehaviorMetric("setup guide action clicked", {+ properties: {+ action: "product_model_open",+ source: "guide_bar",+ },+ })+ );+ }+ setProductModelOpen(open);+ if (!open && !productModelSeen) {+ useAppStore.getState().saveIntroStateByKey({+ key: PRODUCT_MODEL_SEEN_KEY,+ newState: true,+ });+ }+ };++ if (dismissed || !guideEnabled || loading) {+ return null;+ }++ return (+ <>+ <div className="flex w-full shrink-0 items-center gap-x-2 border-t border-block-border bg-background px-3 py-2 shadow-[0_-2px_10px_rgba(0,0,0,0.04)] 2xl:gap-x-4 2xl:px-5 2xl:py-4">+ <div className="flex min-w-0 flex-1 items-center gap-x-2 overflow-hidden 2xl:gap-x-4">+ <div className="flex shrink-0 items-center gap-x-1">+ <div className="shrink-0 text-sm font-semibold text-main 2xl:text-base">+ {t("workspace-setup-guide.self")}+ </div>+ {productModelAvailable && (+ <Tooltip content={t("workspace-setup-guide.product-model")}>+ <Button+ type="button"+ appearance="secondary"+ size="sm"+ data-testid="open-product-model"+ aria-label={t("workspace-setup-guide.product-model")}+ onClick={() => handleProductModelOpenChange(true)}+ >+ <CircleHelp className="size-4" />+ </Button>+ </Tooltip>+ )}+ </div>+ <div className="flex min-w-0 flex-1 items-center gap-x-2 overflow-x-auto pr-1 2xl:gap-x-3 2xl:pr-2">+ {guide.steps.map((step, index) => {+ const highlighted =+ step.definition.id === guide.highlightedStep?.definition.id;+ const tooltipContent = step.blocked+ ? t("workspace-setup-guide.previous-step-required")+ : t(step.definition.descriptionKey);+ return (+ <div+ key={step.definition.id}+ className="inline-flex items-center gap-x-2 2xl:gap-x-3"+ >+ <Tooltip content={tooltipContent}>+ <Button+ type="button"+ appearance="secondary"+ data-testid={`setup-step-${step.definition.analyticsKey}`}+ className={cn(+ "inline-flex h-auto items-center justify-start gap-x-1 rounded-sm px-2 py-1 text-sm font-medium whitespace-nowrap 2xl:gap-x-2 2xl:px-3 2xl:py-2 2xl:text-base",+ highlighted+ ? "bg-accent/10 text-accent"+ : step.done+ ? "text-control-light"+ : "text-control"+ )}+ disabled={step.blocked}+ onClick={() => onSelectStep(step)}+ >+ {step.done ? (+ <CheckCircle className="size-4 text-success 2xl:size-5" />+ ) : (+ <Circle className="size-4 2xl:size-5" />+ )}+ <span>{t(step.definition.labelKey)}</span>+ </Button>+ </Tooltip>+ {index < guide.steps.length - 1 && (+ <span className="text-sm text-control-light 2xl:text-base">+ ›+ </span>+ )}+ </div>+ );+ })}+ </div>+ </div>+ <div className="ml-auto flex shrink-0 items-center gap-x-2">+ {secondaryAction?.type === "create-change" && (+ <Button+ type="button"+ data-testid="secondary-action"+ appearance="secondary"+ size="md"+ className="hidden 2xl:inline-flex"+ onClick={() => {+ behaviorAnalytics.captureMetric(+ createBehaviorMetric("setup guide action clicked", {+ properties: { step: "createFirstChange" },+ })+ );+ void preCreateIssue(secondaryAction.project, [+ secondaryAction.database,+ ]);+ }}+ >+ {t("workspace-setup-guide.actions.change")}+ </Button>+ )}+ {primaryAction?.type === "open-sql-editor" && (+ <SQLEditorButton+ data-testid="active-action"+ database={primaryAction.database}+ openInNewTab+ size="sm"+ className="2xl:h-9 2xl:gap-1.5 2xl:px-3 2xl:text-sm 2xl:leading-5"+ label={t("workspace-setup-guide.actions.query")}+ />+ )}+ <Button+ type="button"+ data-testid="dismiss-guide"+ aria-label={t("workspace-setup-guide.dismiss")}+ appearance="secondary"+ size="sm"+ className="text-control-light hover:text-control 2xl:h-9 2xl:gap-1.5 2xl:px-3 2xl:text-sm 2xl:leading-5"+ onClick={handleDismiss}+ >+ <X className="size-4 2xl:size-5" />+ </Button>+ </div>+ </div>+ {productModelAvailable && (+ <HowBytebaseWorksSheet+ open={productModelOpen && !hasContextualProductIntro}+ onOpenChange={handleProductModelOpenChange}+ />+ )}+ </>+ );+}diff --git a/frontend/src/modules/workspace-setup-guide/resolve.test.ts b/frontend/src/modules/workspace-setup-guide/resolve.test.tsnew file mode 100644index 0000000000..e88f14f7bd--- /dev/null+++ b/frontend/src/modules/workspace-setup-guide/resolve.test.ts@@ -0,0 +1,228 @@+import { describe, expect, test } from "vitest";+import {+ resolveGuide,+ validateGuideScenario,+ validateGuideScenarios,+} from "./resolve";+import type {+ GuideContext,+ GuideScenario,+ GuideStepDefinition,+ GuideStepId,+ GuideStepRegistry,+} from "./types";++const context = (+ completed: Partial<Record<GuideStepId, boolean>> = {}+): GuideContext => ({+ hasProject: completed["create-project"] ?? false,+ hasInstance: completed["connect-instance"] ?? false,+ hasExploredDatabase: completed["explore-database"] ?? false,+ hasFirstQuery: completed["query-data"] ?? false,+ projectName: "",+ databaseProjectName: "",+ databaseName: "",+ route: { name: "workspace.home", params: {} },+});++const definition = (+ id: GuideStepId,+ isComplete: GuideStepDefinition["isComplete"]+): GuideStepDefinition => ({+ id,+ analyticsKey: (+ {+ "create-project": "hasProject",+ "connect-instance": "hasInstance",+ "explore-database": "hasExploredDatabase",+ "query-data": "hasFirstQuery",+ } as const+ )[id],+ labelKey: `label.${id}`,+ descriptionKey: `description.${id}`,+ isComplete,+ matchesRoute: (route) => route.name === `route.${id}`,+ resolveActions: () => ({}),+});++const registry: GuideStepRegistry = {+ "create-project": definition("create-project", (value) => value.hasProject),+ "connect-instance": definition(+ "connect-instance",+ (value) => value.hasInstance+ ),+ "explore-database": definition(+ "explore-database",+ (value) => value.hasExploredDatabase+ ),+ "query-data": definition("query-data", (value) => value.hasFirstQuery),+};++const scenario: GuideScenario = {+ id: "learn-bytebase-basics",+ steps: [+ { stepId: "create-project" },+ { stepId: "connect-instance" },+ {+ stepId: "explore-database",+ dependsOn: ["create-project", "connect-instance"],+ },+ { stepId: "query-data", dependsOn: ["explore-database"] },+ ],+};++describe("validateGuideScenario", () => {+ test("accepts the basics dependency graph", () => {+ expect(() => validateGuideScenario(scenario, registry)).not.toThrow();+ });++ test.each([+ [+ "empty scenario",+ { ...scenario, steps: [] },+ "must contain at least one step",+ ],+ [+ "duplicate step",+ {+ ...scenario,+ steps: [{ stepId: "create-project" }, { stepId: "create-project" }],+ },+ "duplicate step",+ ],+ [+ "unknown step",+ { ...scenario, steps: [{ stepId: "missing" as GuideStepId }] },+ "unregistered step",+ ],+ [+ "dependency outside scenario",+ {+ ...scenario,+ steps: [{ stepId: "query-data", dependsOn: ["explore-database"] }],+ },+ "dependency outside scenario",+ ],+ [+ "self dependency",+ {+ ...scenario,+ steps: [{ stepId: "create-project", dependsOn: ["create-project"] }],+ },+ "cannot depend on itself",+ ],+ [+ "forward dependency",+ {+ ...scenario,+ steps: [+ { stepId: "query-data", dependsOn: ["explore-database"] },+ { stepId: "explore-database" },+ ],+ },+ "must appear before",+ ],+ ])("rejects %s", (_name, invalid, message) => {+ expect(() =>+ validateGuideScenario(invalid as GuideScenario, registry)+ ).toThrow(message);+ });++ test("rejects cycles before reporting display order", () => {+ const invalid: GuideScenario = {+ id: "learn-bytebase-basics",+ steps: [+ { stepId: "create-project", dependsOn: ["connect-instance"] },+ { stepId: "connect-instance", dependsOn: ["create-project"] },+ ],+ };+ expect(() => validateGuideScenario(invalid, registry)).toThrow("cycle");+ });++ test("rejects duplicate scenario IDs", () => {+ expect(() =>+ validateGuideScenarios([scenario, scenario], registry)+ ).toThrow("duplicate scenario");+ });+});++describe("resolveGuide", () => {+ test("uses scenario order and dependencies to find the active step", () => {+ const resolved = resolveGuide({ scenario, registry, context: context() });+ expect(resolved.steps.map(({ definition }) => definition.id)).toEqual([+ "create-project",+ "connect-instance",+ "explore-database",+ "query-data",+ ]);+ expect(resolved.steps.map(({ blocked }) => blocked)).toEqual([+ false,+ false,+ true,+ true,+ ]);+ expect(resolved.activeStep.definition.id).toBe("create-project");+ });++ test("allows the second independent root step to become active", () => {+ const resolved = resolveGuide({+ scenario,+ registry,+ context: context({ "create-project": true }),+ });+ expect(resolved.activeStep.definition.id).toBe("connect-instance");+ });++ test("uses a valid manual selection for highlight and action", () => {+ const resolved = resolveGuide({+ scenario,+ registry,+ context: context(),+ selectedStepId: "connect-instance",+ });+ expect(resolved.highlightedStep?.definition.id).toBe("connect-instance");+ expect(resolved.actionStep.definition.id).toBe("connect-instance");+ });++ test("falls from a completed route match to the active step", () => {+ const value = context({+ "create-project": true,+ "connect-instance": true,+ "explore-database": true,+ });+ value.route = { name: "route.explore-database", params: {} };+ const resolved = resolveGuide({ scenario, registry, context: value });+ expect(resolved.highlightedStep?.definition.id).toBe("query-data");+ });++ test("does not highlight a step on unrelated routes", () => {+ const resolved = resolveGuide({ scenario, registry, context: context() });+ expect(resolved.highlightedStep).toBeUndefined();+ });++ test("ignores a selected ID that is not part of the scenario", () => {+ const resolved = resolveGuide({+ scenario,+ registry,+ context: context(),+ selectedStepId: "missing" as GuideStepId,+ });+ expect(resolved.highlightedStep).toBeUndefined();+ expect(resolved.actionStep.definition.id).toBe("create-project");+ });++ test("retains the final step after all steps complete", () => {+ const resolved = resolveGuide({+ scenario,+ registry,+ context: context({+ "create-project": true,+ "connect-instance": true,+ "explore-database": true,+ "query-data": true,+ }),+ });+ expect(resolved.activeStep.definition.id).toBe("query-data");+ expect(resolved.actionStep.definition.id).toBe("query-data");+ });+});diff --git a/frontend/src/modules/workspace-setup-guide/resolve.ts b/frontend/src/modules/workspace-setup-guide/resolve.tsnew file mode 100644index 0000000000..41cc71e75f--- /dev/null+++ b/frontend/src/modules/workspace-setup-guide/resolve.ts@@ -0,0 +1,139 @@+import type {+ GuideContext,+ GuideScenario,+ GuideStepId,+ GuideStepRegistry,+ ResolvedGuide,+} from "./types";++export const validateGuideScenario = (+ scenario: GuideScenario,+ registry: GuideStepRegistry+) => {+ if (scenario.steps.length === 0) {+ throw new Error(+ `Guide scenario ${scenario.id} must contain at least one step`+ );+ }++ const indexById = new Map<GuideStepId, number>();+ for (const [index, step] of scenario.steps.entries()) {+ if (!registry[step.stepId]) {+ throw new Error(+ `Guide scenario ${scenario.id} references unregistered step ${step.stepId}`+ );+ }+ if (indexById.has(step.stepId)) {+ throw new Error(+ `Guide scenario ${scenario.id} contains duplicate step ${step.stepId}`+ );+ }+ indexById.set(step.stepId, index);+ }++ for (const step of scenario.steps) {+ for (const dependency of step.dependsOn ?? []) {+ if (dependency === step.stepId) {+ throw new Error(`Guide step ${step.stepId} cannot depend on itself`);+ }+ if (!indexById.has(dependency)) {+ throw new Error(+ `Guide step ${step.stepId} has dependency outside scenario: ${dependency}`+ );+ }+ }+ }++ const byId = new Map(scenario.steps.map((step) => [step.stepId, step]));+ const visiting = new Set<GuideStepId>();+ const visited = new Set<GuideStepId>();+ const visit = (stepId: GuideStepId) => {+ if (visiting.has(stepId)) {+ throw new Error(+ `Guide scenario ${scenario.id} contains a dependency cycle`+ );+ }+ if (visited.has(stepId)) return;+ visiting.add(stepId);+ for (const dependency of byId.get(stepId)?.dependsOn ?? []) {+ visit(dependency);+ }+ visiting.delete(stepId);+ visited.add(stepId);+ };+ for (const step of scenario.steps) visit(step.stepId);++ for (const [index, step] of scenario.steps.entries()) {+ for (const dependency of step.dependsOn ?? []) {+ if ((indexById.get(dependency) ?? -1) >= index) {+ throw new Error(+ `Guide dependency ${dependency} must appear before ${step.stepId}`+ );+ }+ }+ }+};++export const validateGuideScenarios = (+ scenarios: readonly GuideScenario[],+ registry: GuideStepRegistry+) => {+ const ids = new Set<string>();+ for (const scenario of scenarios) {+ if (ids.has(scenario.id)) {+ throw new Error(+ `Guide registry contains duplicate scenario ${scenario.id}`+ );+ }+ ids.add(scenario.id);+ validateGuideScenario(scenario, registry);+ }+};++export const resolveGuide = ({+ scenario,+ registry,+ context,+ selectedStepId,+}: {+ scenario: GuideScenario;+ registry: GuideStepRegistry;+ context: GuideContext;+ selectedStepId?: GuideStepId;+}): ResolvedGuide => {+ const doneById = new Map(+ scenario.steps.map(({ stepId }) => [+ stepId,+ registry[stepId].isComplete(context),+ ])+ );+ const steps = scenario.steps.map((scenarioStep) => {+ const definition = registry[scenarioStep.stepId];+ const done = doneById.get(scenarioStep.stepId) ?? false;+ return {+ scenarioStep,+ definition,+ done,+ blocked:+ !done &&+ (scenarioStep.dependsOn ?? []).some(+ (dependency) => !doneById.get(dependency)+ ),+ actions: definition.resolveActions(context),+ };+ });+ const activeStep =+ steps.find((step) => !step.done && !step.blocked) ?? steps.at(-1)!;+ const selectedStep = selectedStepId+ ? steps.find((step) => step.definition.id === selectedStepId)+ : undefined;+ const routeMatchedStep = steps.find((step) =>+ step.definition.matchesRoute(context.route)+ );+ const highlightedStep =+ selectedStep ?? (routeMatchedStep?.done ? activeStep : routeMatchedStep);+ const actionStep =+ highlightedStep && !highlightedStep.done ? highlightedStep : activeStep;++ return { steps, activeStep, highlightedStep, actionStep };+};diff --git a/frontend/src/modules/workspace-setup-guide/scenarios.test.ts b/frontend/src/modules/workspace-setup-guide/scenarios.test.tsnew file mode 100644index 0000000000..0e4ea4b1fe--- /dev/null+++ b/frontend/src/modules/workspace-setup-guide/scenarios.test.ts@@ -0,0 +1,27 @@+import { describe, expect, test } from "vitest";+import { validateGuideScenario } from "./resolve";+import {+ GUIDE_SCENARIO_REGISTRY,+ LEARN_BYTEBASE_BASICS_SCENARIO,+} from "./scenarios";+import { GUIDE_STEP_REGISTRY } from "./steps";++describe("learn-bytebase-basics", () => {+ test("is the only registered scenario and has the approved graph", () => {+ expect(Object.keys(GUIDE_SCENARIO_REGISTRY)).toEqual([+ "learn-bytebase-basics",+ ]);+ expect(LEARN_BYTEBASE_BASICS_SCENARIO.steps).toEqual([+ { stepId: "create-project" },+ { stepId: "connect-instance" },+ {+ stepId: "explore-database",+ dependsOn: ["create-project", "connect-instance"],+ },+ { stepId: "query-data", dependsOn: ["explore-database"] },+ ]);+ expect(() =>+ validateGuideScenario(LEARN_BYTEBASE_BASICS_SCENARIO, GUIDE_STEP_REGISTRY)+ ).not.toThrow();+ });+});diff --git a/frontend/src/modules/workspace-setup-guide/scenarios.ts b/frontend/src/modules/workspace-setup-guide/scenarios.tsnew file mode 100644index 0000000000..03a00ec573--- /dev/null+++ b/frontend/src/modules/workspace-setup-guide/scenarios.ts@@ -0,0 +1,27 @@+import { validateGuideScenarios } from "./resolve";+import { GUIDE_STEP_REGISTRY } from "./steps";+import type { GuideScenario, GuideScenarioId } from "./types";++export const LEARN_BYTEBASE_BASICS_SCENARIO: GuideScenario = {+ id: "learn-bytebase-basics",+ steps: [+ { stepId: "create-project" },+ { stepId: "connect-instance" },+ {+ stepId: "explore-database",+ dependsOn: ["create-project", "connect-instance"],+ },+ { stepId: "query-data", dependsOn: ["explore-database"] },+ ],+};++export const GUIDE_SCENARIO_REGISTRY: Readonly<+ Record<GuideScenarioId, GuideScenario>+> = {+ "learn-bytebase-basics": LEARN_BYTEBASE_BASICS_SCENARIO,+};++validateGuideScenarios(+ Object.values(GUIDE_SCENARIO_REGISTRY),+ GUIDE_STEP_REGISTRY+);diff --git a/frontend/src/modules/workspace-setup-guide/steps.test.ts b/frontend/src/modules/workspace-setup-guide/steps.test.tsnew file mode 100644index 0000000000..9dd9d42ddf--- /dev/null+++ b/frontend/src/modules/workspace-setup-guide/steps.test.ts@@ -0,0 +1,214 @@+import { describe, expect, test } from "vitest";+import {+ DATABASE_ROUTE_DASHBOARD,+ INSTANCE_ROUTE_DASHBOARD,+ PROJECT_V1_ROUTE_DATABASES,+ PROJECT_V1_ROUTE_INSTANCES,+} from "@/app/router/handles";+import {+ CREATE_INSTANCE_PRODUCT_INTRO,+ CREATE_PROJECT_PRODUCT_INTRO,+ PREPARE_DATABASE_PRODUCT_INTRO,+ PREPARE_DATABASE_TRANSFER_TIP,+ PRODUCT_INTRO_QUERY_KEY,+ PRODUCT_INTRO_TIP_QUERY_KEY,+ PROJECT_INSTANCE_SYNCED_PRODUCT_INTRO,+} from "@/lib/productIntro";+import { GUIDE_STEP_REGISTRY } from "./steps";+import type { GuideContext } from "./types";++const createContext = (+ overrides: Partial<GuideContext> = {}+): GuideContext => ({+ hasProject: false,+ hasInstance: false,+ hasExploredDatabase: false,+ hasFirstQuery: false,+ projectName: "",+ databaseProjectName: "",+ databaseName: "",+ route: { name: "workspace.home", params: {} },+ ...overrides,+});++describe("GUIDE_STEP_REGISTRY", () => {+ test("preserves legacy analytics and translation keys", () => {+ expect(+ Object.values(GUIDE_STEP_REGISTRY).map(+ ({ id, analyticsKey, labelKey, descriptionKey }) => ({+ id,+ analyticsKey,+ labelKey,+ descriptionKey,+ })+ )+ ).toEqual([+ {+ id: "create-project",+ analyticsKey: "hasProject",+ labelKey: "workspace-setup-guide.steps.project",+ descriptionKey: "workspace-setup-guide.descriptions.project",+ },+ {+ id: "connect-instance",+ analyticsKey: "hasInstance",+ labelKey: "workspace-setup-guide.steps.instance",+ descriptionKey: "workspace-setup-guide.descriptions.instance",+ },+ {+ id: "explore-database",+ analyticsKey: "hasExploredDatabase",+ labelKey: "workspace-setup-guide.steps.database",+ descriptionKey: "workspace-setup-guide.descriptions.database",+ },+ {+ id: "query-data",+ analyticsKey: "hasFirstQuery",+ labelKey: "workspace-setup-guide.steps.query",+ descriptionKey: "workspace-setup-guide.descriptions.sql-editor",+ },+ ]);+ });++ test("routes project creation with the current product intro", () => {+ expect(+ GUIDE_STEP_REGISTRY["create-project"].resolveActions(createContext())+ ).toEqual({+ select: {+ type: "navigate",+ target: {+ name: "workspace.project",+ query: { [PRODUCT_INTRO_QUERY_KEY]: CREATE_PROJECT_PRODUCT_INTRO },+ },+ },+ });+ expect(+ GUIDE_STEP_REGISTRY["create-project"].resolveActions(+ createContext({ hasProject: true })+ )+ ).toEqual({});+ });++ test("routes instance connection through the project when available", () => {+ expect(+ GUIDE_STEP_REGISTRY["connect-instance"].resolveActions(+ createContext({ projectName: "projects/app" })+ )+ ).toEqual({+ select: {+ type: "navigate",+ target: {+ name: PROJECT_V1_ROUTE_INSTANCES,+ params: { projectId: "app" },+ query: { [PRODUCT_INTRO_QUERY_KEY]: CREATE_INSTANCE_PRODUCT_INTRO },+ },+ },+ });+ expect(+ GUIDE_STEP_REGISTRY["connect-instance"].resolveActions(createContext())+ ).toEqual({+ select: {+ type: "navigate",+ target: {+ name: INSTANCE_ROUTE_DASHBOARD,+ query: { [PRODUCT_INTRO_QUERY_KEY]: CREATE_INSTANCE_PRODUCT_INTRO },+ },+ },+ });+ });++ test("routes database preparation with transfer guidance", () => {+ expect(+ GUIDE_STEP_REGISTRY["explore-database"].resolveActions(createContext())+ ).toEqual({+ select: {+ type: "navigate",+ target: {+ name: DATABASE_ROUTE_DASHBOARD,+ query: {+ [PRODUCT_INTRO_QUERY_KEY]: PREPARE_DATABASE_PRODUCT_INTRO,+ [PRODUCT_INTRO_TIP_QUERY_KEY]: PREPARE_DATABASE_TRANSFER_TIP,+ },+ },+ },+ });+ });++ test("routes an existing project database with synced guidance", () => {+ expect(+ GUIDE_STEP_REGISTRY["explore-database"].resolveActions(+ createContext({+ databaseProjectName: "projects/app",+ databaseName: "instances/sample/databases/employee",+ })+ )+ ).toEqual({+ select: {+ type: "navigate",+ target: {+ name: PROJECT_V1_ROUTE_DATABASES,+ params: { projectId: "app" },+ query: {+ [PRODUCT_INTRO_QUERY_KEY]: PROJECT_INSTANCE_SYNCED_PRODUCT_INTRO,+ },+ },+ },+ });+ });++ test("resolves the current query and change actions together", () => {+ expect(+ GUIDE_STEP_REGISTRY["query-data"].resolveActions(+ createContext({+ databaseProjectName: "projects/app",+ databaseName: "instances/sample/databases/employee",+ })+ )+ ).toEqual({+ primary: {+ type: "open-sql-editor",+ database: {+ name: "instances/sample/databases/employee",+ project: "projects/app",+ },+ },+ secondary: {+ type: "create-change",+ project: "projects/app",+ database: "instances/sample/databases/employee",+ },+ });+ });++ test("omits query actions without a complete database target", () => {+ expect(+ GUIDE_STEP_REGISTRY["query-data"].resolveActions(createContext())+ ).toEqual({});+ });++ test.each([+ ["create-project", { hasProject: true }],+ ["connect-instance", { hasInstance: true }],+ ["explore-database", { hasExploredDatabase: true }],+ ["query-data", { hasFirstQuery: true }],+ ] as const)("evaluates completion for %s", (stepId, completed) => {+ expect(+ GUIDE_STEP_REGISTRY[stepId].isComplete(createContext(completed))+ ).toBe(true);+ expect(GUIDE_STEP_REGISTRY[stepId].isComplete(createContext())).toBe(false);+ });++ test.each([+ ["create-project", "workspace.project", true],+ ["connect-instance", "workspace.instance.detail", true],+ ["connect-instance", "workspace.project.instance", true],+ ["explore-database", "workspace.database.detail", true],+ ["explore-database", "workspace.project.database", true],+ ["query-data", "sql-editor.database", true],+ ["query-data", "workspace.home", false],+ ] as const)("matches %s against %s", (stepId, name, expected) => {+ expect(GUIDE_STEP_REGISTRY[stepId].matchesRoute({ name, params: {} })).toBe(+ expected+ );+ });+});diff --git a/frontend/src/modules/workspace-setup-guide/steps.ts b/frontend/src/modules/workspace-setup-guide/steps.tsnew file mode 100644index 0000000000..e975496af8--- /dev/null+++ b/frontend/src/modules/workspace-setup-guide/steps.ts@@ -0,0 +1,145 @@+import {+ DATABASE_ROUTE_DASHBOARD,+ INSTANCE_ROUTE_DASHBOARD,+ INSTANCE_ROUTE_DATABASE_DETAIL,+ PROJECT_V1_ROUTE_DASHBOARD,+ PROJECT_V1_ROUTE_DATABASES,+ PROJECT_V1_ROUTE_INSTANCES,+ SQL_EDITOR_DATABASE_MODULE,+} from "@/app/router/handles";+import {+ CREATE_INSTANCE_PRODUCT_INTRO,+ CREATE_PROJECT_PRODUCT_INTRO,+ PREPARE_DATABASE_PRODUCT_INTRO,+ PREPARE_DATABASE_TRANSFER_TIP,+ PRODUCT_INTRO_QUERY_KEY,+ PRODUCT_INTRO_TIP_QUERY_KEY,+ PROJECT_INSTANCE_SYNCED_PRODUCT_INTRO,+} from "@/lib/productIntro";+import { extractProjectResourceName } from "@/utils/v1/project";+import type { GuideStepRegistry } from "./types";++const isRouteInside = (name: string | undefined, parent: string) =>+ name === parent || !!name?.startsWith(`${parent}.`);++export const GUIDE_STEP_REGISTRY: GuideStepRegistry = {+ "create-project": {+ id: "create-project",+ analyticsKey: "hasProject",+ labelKey: "workspace-setup-guide.steps.project",+ descriptionKey: "workspace-setup-guide.descriptions.project",+ isComplete: (context) => context.hasProject,+ matchesRoute: (route) => route.name === PROJECT_V1_ROUTE_DASHBOARD,+ resolveActions: (context) =>+ context.hasProject+ ? {}+ : {+ select: {+ type: "navigate",+ target: {+ name: PROJECT_V1_ROUTE_DASHBOARD,+ query: {+ [PRODUCT_INTRO_QUERY_KEY]: CREATE_PROJECT_PRODUCT_INTRO,+ },+ },+ },+ },+ },+ "connect-instance": {+ id: "connect-instance",+ analyticsKey: "hasInstance",+ labelKey: "workspace-setup-guide.steps.instance",+ descriptionKey: "workspace-setup-guide.descriptions.instance",+ isComplete: (context) => context.hasInstance,+ matchesRoute: (route) =>+ isRouteInside(route.name, INSTANCE_ROUTE_DASHBOARD) ||+ isRouteInside(route.name, PROJECT_V1_ROUTE_INSTANCES),+ resolveActions: (context) => {+ if (context.hasInstance) return {};+ return {+ select: {+ type: "navigate",+ target: context.projectName+ ? {+ name: PROJECT_V1_ROUTE_INSTANCES,+ params: {+ projectId: extractProjectResourceName(context.projectName),+ },+ query: {+ [PRODUCT_INTRO_QUERY_KEY]: CREATE_INSTANCE_PRODUCT_INTRO,+ },+ }+ : {+ name: INSTANCE_ROUTE_DASHBOARD,+ query: {+ [PRODUCT_INTRO_QUERY_KEY]: CREATE_INSTANCE_PRODUCT_INTRO,+ },+ },+ },+ };+ },+ },+ "explore-database": {+ id: "explore-database",+ analyticsKey: "hasExploredDatabase",+ labelKey: "workspace-setup-guide.steps.database",+ descriptionKey: "workspace-setup-guide.descriptions.database",+ isComplete: (context) => context.hasExploredDatabase,+ matchesRoute: (route) =>+ isRouteInside(route.name, DATABASE_ROUTE_DASHBOARD) ||+ isRouteInside(route.name, PROJECT_V1_ROUTE_DATABASES) ||+ route.name === INSTANCE_ROUTE_DATABASE_DETAIL,+ resolveActions: (context) => ({+ select: {+ type: "navigate",+ target:+ context.databaseName && context.databaseProjectName+ ? {+ name: PROJECT_V1_ROUTE_DATABASES,+ params: {+ projectId: extractProjectResourceName(+ context.databaseProjectName+ ),+ },+ query: {+ [PRODUCT_INTRO_QUERY_KEY]:+ PROJECT_INSTANCE_SYNCED_PRODUCT_INTRO,+ },+ }+ : {+ name: DATABASE_ROUTE_DASHBOARD,+ query: {+ [PRODUCT_INTRO_QUERY_KEY]: PREPARE_DATABASE_PRODUCT_INTRO,+ [PRODUCT_INTRO_TIP_QUERY_KEY]: PREPARE_DATABASE_TRANSFER_TIP,+ },+ },+ },+ }),+ },+ "query-data": {+ id: "query-data",+ analyticsKey: "hasFirstQuery",+ labelKey: "workspace-setup-guide.steps.query",+ descriptionKey: "workspace-setup-guide.descriptions.sql-editor",+ isComplete: (context) => context.hasFirstQuery,+ matchesRoute: (route) =>+ isRouteInside(route.name, SQL_EDITOR_DATABASE_MODULE),+ resolveActions: (context) => {+ if (!context.databaseName || !context.databaseProjectName) return {};+ return {+ primary: {+ type: "open-sql-editor",+ database: {+ name: context.databaseName,+ project: context.databaseProjectName,+ },+ },+ secondary: {+ type: "create-change",+ project: context.databaseProjectName,+ database: context.databaseName,+ },+ };+ },+ },+};diff --git a/frontend/src/modules/workspace-setup-guide/types.ts b/frontend/src/modules/workspace-setup-guide/types.tsnew file mode 100644index 0000000000..f5ae42d2fc--- /dev/null+++ b/frontend/src/modules/workspace-setup-guide/types.ts@@ -0,0 +1,87 @@+import type { ReactRoute, RouteTarget } from "@/app/router";++export type GuideStepId =+ | "create-project"+ | "connect-instance"+ | "explore-database"+ | "query-data";++export type GuideScenarioId = "learn-bytebase-basics";++export type GuideAnalyticsKey =+ | "hasProject"+ | "hasInstance"+ | "hasExploredDatabase"+ | "hasFirstQuery";++export type GuideRoute = Pick<ReactRoute, "name" | "params">;++export type GuideContext = {+ hasProject: boolean;+ hasInstance: boolean;+ hasExploredDatabase: boolean;+ hasFirstQuery: boolean;+ projectName: string;+ databaseProjectName: string;+ databaseName: string;+ route: GuideRoute;+};++export type GuideDatabase = {+ name: string;+ project: string;+};++export type GuideAction =+ | { type: "navigate"; target: RouteTarget }+ | { type: "open-sql-editor"; database: GuideDatabase }+ | {+ type: "create-change";+ project: string;+ database: string;+ };++export type GuideStepActions = {+ select?: GuideAction;+ primary?: GuideAction;+ secondary?: GuideAction;+};++export type GuideStepDefinition = {+ id: GuideStepId;+ analyticsKey: GuideAnalyticsKey;+ labelKey: string;+ descriptionKey: string;+ isComplete: (context: GuideContext) => boolean;+ matchesRoute: (route: GuideRoute) => boolean;+ resolveActions: (context: GuideContext) => GuideStepActions;+};++export type GuideStepRegistry = Readonly<+ Record<GuideStepId, GuideStepDefinition>+>;++export type ScenarioStep = {+ stepId: GuideStepId;+ dependsOn?: readonly GuideStepId[];+};++export type GuideScenario = {+ id: GuideScenarioId;+ steps: readonly ScenarioStep[];+};++export type ResolvedGuideStep = {+ scenarioStep: ScenarioStep;+ definition: GuideStepDefinition;+ done: boolean;+ blocked: boolean;+ actions: GuideStepActions;+};++export type ResolvedGuide = {+ steps: ResolvedGuideStep[];+ activeStep: ResolvedGuideStep;+ highlightedStep: ResolvedGuideStep | undefined;+ actionStep: ResolvedGuideStep;+};diff --git a/frontend/src/modules/workspace-setup-guide/useGuideContext.test.tsx b/frontend/src/modules/workspace-setup-guide/useGuideContext.test.tsxnew file mode 100644index 0000000000..73f0f8d7ac--- /dev/null+++ b/frontend/src/modules/workspace-setup-guide/useGuideContext.test.tsx@@ -0,0 +1,631 @@+import { act, renderHook, waitFor } from "@testing-library/react";+import { beforeEach, describe, expect, test, vi } from "vitest";+import {+ DATABASE_ROUTE_DASHBOARD,+ INSTANCE_ROUTE_DATABASE_DETAIL,+ PROJECT_V1_ROUTE_DATABASE_DETAIL,+ SQL_EDITOR_DATABASE_MODULE,+} from "@/app/router/handles";+import { sqlEditorEvents } from "@/modules/sql-editor/model/events";+import { State } from "@/types/proto-es/v1/common_pb";+import type { GuideRoute } from "./types";++const mocks = vi.hoisted(() => ({+ projectsByName: {} as Record<string, unknown>,+ instancesByName: {} as Record<string, unknown>,+ databasesByName: {} as Record<string, unknown>,+ fetchProjectList: vi.fn(),+ fetchInstanceList: vi.fn(),+ fetchDatabases: vi.fn(),+ introState: {} as Record<string, boolean>,+ saveIntroStateByKey: vi.fn(),+ searchQueryHistories: vi.fn(),+ workspaceResourceName: "workspaces/default",+ defaultProject: "projects/default",+}));++vi.mock("@/hooks/useAppState", () => ({+ useIntroStateByKey: (key: string) => mocks.introState[key] ?? false,+}));++vi.mock("@/stores/app", () => {+ const state = () => ({+ serverInfo: { defaultProject: mocks.defaultProject },+ projectsByName: mocks.projectsByName,+ instancesByName: mocks.instancesByName,+ databasesByName: mocks.databasesByName,+ workspaceResourceName: () => mocks.workspaceResourceName,+ });+ const useAppStore = Object.assign(+ (selector: (value: ReturnType<typeof state>) => unknown) =>+ selector(state()),+ {+ getState: () => ({+ ...state(),+ fetchProjectList: mocks.fetchProjectList,+ fetchInstanceList: mocks.fetchInstanceList,+ fetchDatabases: mocks.fetchDatabases,+ getIntroStateByKey: (key: string) => mocks.introState[key] ?? false,+ saveIntroStateByKey: mocks.saveIntroStateByKey,+ }),+ }+ );+ return { useAppStore };+});++vi.mock("@/api", () => ({+ queryHistoryServiceClientConnect: {+ searchQueryHistories: mocks.searchQueryHistories,+ },+}));++import { useGuideContext } from "./useGuideContext";++const databaseExploredKey = "workspace-setup-guide.database-explored";+const queryExecutedKey = "workspace-setup-guide.query-executed";+const route: GuideRoute = { name: "workspace.home", params: {} };++const renderGuideContext = (+ props: {+ enabled: boolean;+ dismissed: boolean;+ route: GuideRoute;+ } = { enabled: true, dismissed: false, route }+) => renderHook((nextProps) => useGuideContext(nextProps), { initialProps: props });++describe("useGuideContext", () => {+ beforeEach(() => {+ vi.clearAllMocks();+ mocks.introState = {};+ mocks.projectsByName = {};+ mocks.instancesByName = {};+ mocks.databasesByName = {};+ mocks.defaultProject = "projects/default";+ mocks.workspaceResourceName = "workspaces/default";+ mocks.fetchProjectList.mockResolvedValue({ projects: [], nextPageToken: "" });+ mocks.fetchInstanceList.mockResolvedValue({+ instances: [],+ nextPageToken: "",+ });+ mocks.fetchDatabases.mockResolvedValue({ databases: [], nextPageToken: "" });+ mocks.saveIntroStateByKey.mockImplementation(({ key, newState }) => {+ mocks.introState[key] = newState;+ });+ });++ test("reports an empty workspace after the initial scan", async () => {+ const { result } = renderGuideContext();++ await waitFor(() => expect(result.current.loading).toBe(false));++ expect(result.current.context).toMatchObject({+ hasProject: false,+ hasInstance: false,+ hasExploredDatabase: false,+ hasFirstQuery: false,+ projectName: "",+ databaseProjectName: "",+ databaseName: "",+ });+ });++ test("recognizes project, project-owned instance, and project database", async () => {+ mocks.fetchProjectList.mockResolvedValue({+ projects: [{ name: "projects/app" }],+ nextPageToken: "",+ });+ mocks.fetchInstanceList.mockImplementation(async ({ parent } = {}) => ({+ instances:+ parent === "projects/app"+ ? [{ name: "projects/app/instances/sample" }]+ : [],+ nextPageToken: "",+ }));+ mocks.fetchDatabases.mockResolvedValue({+ databases: [+ {+ name: "projects/app/instances/sample/databases/employee",+ project: "projects/app",+ },+ ],+ nextPageToken: "",+ });+ const { result } = renderGuideContext();++ await waitFor(() => expect(result.current.loading).toBe(false));++ expect(result.current.context).toMatchObject({+ hasProject: true,+ hasInstance: true,+ projectName: "projects/app",+ databaseProjectName: "projects/app",+ databaseName: "projects/app/instances/sample/databases/employee",+ });+ });++ test("keeps the setup project when the first database belongs elsewhere", async () => {+ mocks.fetchProjectList.mockResolvedValue({+ projects: [{ name: "projects/project-a" }],+ nextPageToken: "",+ });+ mocks.fetchDatabases.mockResolvedValue({+ databases: [+ {+ name: "instances/sample/databases/employee",+ project: "projects/default",+ },+ ],+ nextPageToken: "",+ });+ const { result } = renderGuideContext();++ await waitFor(() => expect(result.current.loading).toBe(false));++ expect(result.current.context).toMatchObject({+ projectName: "projects/project-a",+ databaseProjectName: "projects/default",+ databaseName: "instances/sample/databases/employee",+ });+ });++ test("counts workspace-owned instances as project and instance readiness", async () => {+ mocks.fetchProjectList.mockResolvedValue({+ projects: [{ name: "projects/project-sample" }],+ nextPageToken: "",+ });+ mocks.fetchInstanceList.mockResolvedValue({+ instances: [{ name: "instances/sample" }],+ nextPageToken: "",+ });+ const { result } = renderGuideContext();++ await waitFor(() => expect(result.current.loading).toBe(false));++ expect(result.current.context).toMatchObject({+ hasProject: true,+ hasInstance: true,+ });+ });++ test("counts project-owned instances as project and instance readiness", async () => {+ mocks.fetchProjectList.mockResolvedValue({+ projects: [{ name: "projects/app" }],+ nextPageToken: "",+ });+ mocks.fetchInstanceList.mockImplementation(async ({ parent } = {}) => ({+ instances:+ parent === "projects/app"+ ? [{ name: "projects/app/instances/sample" }]+ : [],+ nextPageToken: "",+ }));+ const { result } = renderGuideContext();++ await waitFor(() => expect(result.current.loading).toBe(false));++ expect(result.current.context).toMatchObject({+ hasProject: true,+ hasInstance: true,+ });+ });++ test("uses only the first resource page", async () => {+ mocks.introState[databaseExploredKey] = true;+ mocks.fetchProjectList.mockResolvedValue({+ projects: [{ name: "projects/project-sample" }],+ nextPageToken: "project-page-2",+ });+ mocks.fetchInstanceList.mockResolvedValue({+ instances: [{ name: "instances/sample" }],+ nextPageToken: "instance-page-2",+ });+ mocks.fetchDatabases.mockResolvedValue({+ databases: [+ {+ name: "instances/sample/databases/employee",+ project: "projects/project-sample",+ },+ ],+ nextPageToken: "database-page-2",+ });+ const { result } = renderGuideContext();++ await waitFor(() => expect(result.current.loading).toBe(false));++ expect(result.current.context).toMatchObject({+ hasExploredDatabase: true,+ databaseName: "instances/sample/databases/employee",+ });+ expect(mocks.fetchProjectList).toHaveBeenCalledTimes(1);+ expect(mocks.fetchInstanceList).toHaveBeenCalledTimes(2);+ expect(mocks.fetchDatabases).toHaveBeenCalledTimes(1);+ expect(mocks.fetchProjectList).toHaveBeenCalledWith({+ pageSize: 1,+ silent: true,+ filter: { excludeDefault: true, state: State.ACTIVE },+ });+ expect(mocks.fetchInstanceList).toHaveBeenCalledWith({+ parent: "projects/project-sample",+ pageSize: 1,+ silent: true,+ filter: { state: State.ACTIVE },+ });+ expect(mocks.fetchDatabases).toHaveBeenCalledWith({+ parent: "workspaces/default",+ pageSize: 1,+ silent: true,+ filter: { project: "projects/project-sample" },+ });+ });++ test.each([+ {+ name: PROJECT_V1_ROUTE_DATABASE_DETAIL,+ params: {+ projectId: "project-sample",+ instanceId: "sample-one",+ databaseName: "employee",+ },+ },+ {+ name: INSTANCE_ROUTE_DATABASE_DETAIL,+ params: { instanceId: "sample-one", databaseName: "employee" },+ },+ {+ name: SQL_EDITOR_DATABASE_MODULE,+ params: {+ project: "project-sample",+ instance: "sample-one",+ database: "employee",+ },+ },+ ])("marks a concrete database route as explored: $name", async (route) => {+ renderGuideContext({ enabled: true, dismissed: false, route });++ await waitFor(() =>+ expect(mocks.saveIntroStateByKey).toHaveBeenCalledWith({+ key: databaseExploredKey,+ newState: true,+ })+ );+ });++ test.each([+ {+ name: PROJECT_V1_ROUTE_DATABASE_DETAIL,+ params: { projectId: "project-sample", instanceId: "sample-one" },+ },+ {+ name: INSTANCE_ROUTE_DATABASE_DETAIL,+ params: { instanceId: "sample-one" },+ },+ {+ name: SQL_EDITOR_DATABASE_MODULE,+ params: { project: "project-sample", instance: "sample-one" },+ },+ ])("requires every database parameter for $name", async (route) => {+ const { result } = renderGuideContext({+ enabled: true,+ dismissed: false,+ route,+ });++ await waitFor(() => expect(result.current.loading).toBe(false));++ expect(mocks.saveIntroStateByKey).not.toHaveBeenCalledWith({+ key: databaseExploredKey,+ newState: true,+ });+ expect(result.current.context.hasExploredDatabase).toBe(false);+ });++ test("does not count the workspace database list as exploration", async () => {+ const { result } = renderGuideContext({+ enabled: true,+ dismissed: false,+ route: { name: DATABASE_ROUTE_DASHBOARD, params: {} },+ });++ await waitFor(() => expect(result.current.loading).toBe(false));++ expect(mocks.saveIntroStateByKey).not.toHaveBeenCalledWith({+ key: databaseExploredKey,+ newState: true,+ });+ expect(result.current.context.hasExploredDatabase).toBe(false);+ });++ test("keeps database exploration complete after it is persisted", async () => {+ mocks.introState[databaseExploredKey] = true;+ const { result } = renderGuideContext();++ await waitFor(() => expect(result.current.loading).toBe(false));++ expect(result.current.context.hasExploredDatabase).toBe(true);+ });++ test("marks query execution and retains its exact target", async () => {+ const { result } = renderGuideContext();++ await waitFor(() => expect(result.current.loading).toBe(false));+ await act(async () => {+ await sqlEditorEvents.emit("query-executed", {+ database: "projects/app/instances/sample/databases/employee",+ project: "projects/app",+ });+ });++ expect(mocks.saveIntroStateByKey).toHaveBeenCalledWith({+ key: databaseExploredKey,+ newState: true,+ });+ expect(mocks.saveIntroStateByKey).toHaveBeenCalledWith({+ key: queryExecutedKey,+ newState: true,+ });+ expect(result.current.context).toMatchObject({+ hasExploredDatabase: true,+ hasFirstQuery: true,+ databaseProjectName: "projects/app",+ databaseName: "projects/app/instances/sample/databases/employee",+ });+ });++ test("keeps query progress and its event target while resource scans finish", async () => {+ let resolveFirstScan: ((value: { projects: unknown[]; nextPageToken: string }) => void) | undefined;+ let resolveSecondScan: ((value: { projects: unknown[]; nextPageToken: string }) => void) | undefined;+ mocks.fetchProjectList+ .mockImplementationOnce(+ () => new Promise((resolve) => { resolveFirstScan = resolve; })+ )+ .mockImplementationOnce(+ () => new Promise((resolve) => { resolveSecondScan = resolve; })+ );+ mocks.fetchInstanceList.mockResolvedValue({+ instances: [{ name: "instances/discovered-instance" }],+ nextPageToken: "",+ });+ mocks.fetchDatabases.mockResolvedValue({+ databases: [+ {+ name: "instances/discovered-instance/databases/discovered-db",+ project: "projects/discovered-project",+ },+ ],+ nextPageToken: "",+ });+ const { result } = renderGuideContext();++ await waitFor(() => expect(mocks.fetchProjectList).toHaveBeenCalledTimes(1));+ await act(async () => {+ await sqlEditorEvents.emit("query-executed", {+ database: "instances/event-instance/databases/event-db",+ project: "projects/event-project",+ });+ });+ await waitFor(() => expect(mocks.fetchProjectList).toHaveBeenCalledTimes(2));++ await act(async () => {+ resolveFirstScan?.({+ projects: [{ name: "projects/discovered-project" }],+ nextPageToken: "",+ });+ });+ await waitFor(() =>+ expect(result.current.context).toMatchObject({+ hasExploredDatabase: true,+ hasFirstQuery: true,+ databaseProjectName: "projects/event-project",+ databaseName: "instances/event-instance/databases/event-db",+ })+ );++ await act(async () => {+ resolveSecondScan?.({+ projects: [{ name: "projects/discovered-project" }],+ nextPageToken: "",+ });+ });+ await waitFor(() =>+ expect(result.current.context).toMatchObject({+ hasFirstQuery: true,+ databaseProjectName: "projects/event-project",+ databaseName: "instances/event-instance/databases/event-db",+ })+ );+ });++ test("does not reconstruct query completion from query history", async () => {+ mocks.fetchProjectList.mockResolvedValue({+ projects: [{ name: "projects/app" }],+ nextPageToken: "",+ });+ mocks.fetchDatabases.mockResolvedValue({+ databases: [+ { name: "instances/prod/databases/main", project: "projects/app" },+ ],+ nextPageToken: "",+ });+ const { result } = renderGuideContext();++ await waitFor(() => expect(result.current.loading).toBe(false));++ expect(result.current.context.hasFirstQuery).toBe(false);+ expect(mocks.searchQueryHistories).not.toHaveBeenCalled();+ });++ test("does not search query history for guide progress", async () => {+ const { result } = renderGuideContext();++ await waitFor(() => expect(result.current.loading).toBe(false));++ expect(mocks.searchQueryHistories).not.toHaveBeenCalled();+ });++ test("skips first query check before a project database exists", async () => {+ mocks.fetchProjectList.mockResolvedValue({+ projects: [{ name: "projects/project-a" }],+ nextPageToken: "",+ });+ mocks.fetchInstanceList.mockResolvedValue({+ instances: [{ name: "instances/instance-a" }],+ nextPageToken: "",+ });+ const { result } = renderGuideContext();++ await waitFor(() => expect(result.current.loading).toBe(false));++ expect(result.current.context).toMatchObject({+ databaseName: "",+ hasFirstQuery: false,+ });+ expect(mocks.searchQueryHistories).not.toHaveBeenCalled();+ });++ test("refreshes when a new instance is added to the app store", async () => {+ mocks.fetchProjectList.mockResolvedValue({+ projects: [{ name: "projects/project-a" }],+ nextPageToken: "",+ });+ const { result, rerender } = renderGuideContext();++ await waitFor(() => expect(result.current.loading).toBe(false));+ mocks.instancesByName = { "instances/instance-a": {} };+ mocks.fetchInstanceList.mockResolvedValue({+ instances: [{ name: "instances/instance-a" }],+ nextPageToken: "",+ });+ rerender({ enabled: true, dismissed: false, route });++ await waitFor(() => expect(result.current.context.hasInstance).toBe(true));+ });++ test("refreshes when a database is added to the app store", async () => {+ mocks.introState[databaseExploredKey] = true;+ mocks.fetchProjectList.mockResolvedValue({+ projects: [{ name: "projects/project-a" }],+ nextPageToken: "",+ });+ mocks.fetchInstanceList.mockResolvedValue({+ instances: [{ name: "instances/instance-a" }],+ nextPageToken: "",+ });+ const { result, rerender } = renderGuideContext();++ await waitFor(() => expect(result.current.loading).toBe(false));+ mocks.databasesByName = { "instances/instance-a/databases/db-a": {} };+ mocks.fetchDatabases.mockResolvedValue({+ databases: [+ {+ name: "instances/instance-a/databases/db-a",+ project: "projects/project-a",+ },+ ],+ nextPageToken: "",+ });+ rerender({ enabled: true, dismissed: false, route });++ await waitFor(() =>+ expect(result.current.context.databaseName).toBe(+ "instances/instance-a/databases/db-a"+ )+ );+ });++ test("refreshes when the route changes after setup progress changes elsewhere", async () => {+ mocks.introState[databaseExploredKey] = true;+ mocks.fetchProjectList.mockResolvedValue({+ projects: [{ name: "projects/project-a" }],+ nextPageToken: "",+ });+ mocks.fetchInstanceList.mockResolvedValue({+ instances: [{ name: "instances/instance-a" }],+ nextPageToken: "",+ });+ const { result, rerender } = renderGuideContext();++ await waitFor(() => expect(result.current.loading).toBe(false));+ mocks.fetchDatabases.mockResolvedValue({+ databases: [+ {+ name: "instances/instance-a/databases/db-a",+ project: "projects/project-a",+ },+ ],+ nextPageToken: "",+ });+ rerender({+ enabled: true,+ dismissed: false,+ route: { name: "workspace.member", params: {} },+ });++ await waitFor(() =>+ expect(result.current.context.databaseName).toBe(+ "instances/instance-a/databases/db-a"+ )+ );+ });++ test("keeps the guide visible while progress is refreshing", async () => {+ mocks.fetchProjectList.mockResolvedValue({+ projects: [{ name: "projects/project-a" }],+ nextPageToken: "",+ });+ const { result, rerender } = renderGuideContext();++ await waitFor(() => expect(result.current.loading).toBe(false));+ mocks.instancesByName = { "instances/instance-a": {} };+ mocks.fetchProjectList.mockReturnValue(new Promise(() => undefined));+ rerender({+ enabled: true,+ dismissed: false,+ route: { name: "workspace.instance.detail", params: {} },+ });++ await waitFor(() => expect(mocks.fetchProjectList).toHaveBeenCalledTimes(2));+ expect(result.current.loading).toBe(false);+ expect(result.current.context.hasProject).toBe(true);+ });++ test("keeps the latest facts when a resource refresh fails", async () => {+ mocks.fetchProjectList.mockResolvedValue({+ projects: [{ name: "projects/project-a" }],+ nextPageToken: "",+ });+ const { result, rerender } = renderGuideContext();++ await waitFor(() => expect(result.current.context.hasProject).toBe(true));+ mocks.instancesByName = { "instances/instance-a": {} };+ mocks.fetchProjectList.mockRejectedValueOnce(new Error("permission denied"));+ rerender({ enabled: true, dismissed: false, route });++ await waitFor(() => expect(mocks.fetchProjectList).toHaveBeenCalledTimes(2));+ expect(result.current.context.hasProject).toBe(true);+ });++ test.each([+ { enabled: false, dismissed: false },+ { enabled: true, dismissed: true },+ ])("resets facts when disabled or dismissed", async ({ enabled, dismissed }) => {+ mocks.fetchProjectList.mockResolvedValue({+ projects: [{ name: "projects/project-a" }],+ nextPageToken: "",+ });+ const { result, rerender } = renderGuideContext();++ await waitFor(() => expect(result.current.context.hasProject).toBe(true));+ rerender({ enabled, dismissed, route });++ await waitFor(() => expect(result.current.loading).toBe(false));+ expect(result.current.context).toMatchObject({+ hasProject: false,+ hasInstance: false,+ hasExploredDatabase: false,+ hasFirstQuery: false,+ projectName: "",+ databaseProjectName: "",+ databaseName: "",+ });+ });+});diff --git a/frontend/src/modules/workspace-setup-guide/useGuideContext.ts b/frontend/src/modules/workspace-setup-guide/useGuideContext.tsnew file mode 100644index 0000000000..a877c3bbb5--- /dev/null+++ b/frontend/src/modules/workspace-setup-guide/useGuideContext.ts@@ -0,0 +1,238 @@+import { useEffect, useMemo, useRef, useState } from "react";+import {+ INSTANCE_ROUTE_DATABASE_DETAIL,+ PROJECT_V1_ROUTE_DATABASE_DETAIL,+ SQL_EDITOR_DATABASE_MODULE,+} from "@/app/router/handles";+import { useIntroStateByKey } from "@/hooks/useAppState";+import { sqlEditorEvents } from "@/modules/sql-editor/model/events";+import { useAppStore } from "@/stores/app";+import { State } from "@/types/proto-es/v1/common_pb";+import type { GuideContext, GuideRoute } from "./types";++const DATABASE_EXPLORED_KEY = "workspace-setup-guide.database-explored";+const QUERY_EXECUTED_KEY = "workspace-setup-guide.query-executed";++type GuideFacts = Omit<GuideContext, "route">;++const INITIAL_FACTS: GuideFacts = {+ hasProject: false,+ hasInstance: false,+ hasExploredDatabase: false,+ hasFirstQuery: false,+ projectName: "",+ databaseProjectName: "",+ databaseName: "",+};++const hasRouteParams = (+ params: Record<string, string | string[] | undefined>,+ keys: string[]+) =>+ keys.every((key) => {+ const value = params[key];+ return typeof value === "string" && value.length > 0;+ });++const isConcreteDatabaseRoute = (+ name: string | undefined,+ params: Record<string, string | string[] | undefined>+) => {+ switch (name) {+ case PROJECT_V1_ROUTE_DATABASE_DETAIL:+ return hasRouteParams(params, [+ "projectId",+ "instanceId",+ "databaseName",+ ]);+ case INSTANCE_ROUTE_DATABASE_DETAIL:+ return hasRouteParams(params, ["instanceId", "databaseName"]);+ case SQL_EDITOR_DATABASE_MODULE:+ return hasRouteParams(params, ["project", "instance", "database"]);+ default:+ return false;+ }+};++export const useGuideContext = ({+ enabled,+ dismissed,+ route,+}: {+ enabled: boolean;+ dismissed: boolean;+ route: GuideRoute;+}): { context: GuideContext; loading: boolean } => {+ const databaseExplored = useIntroStateByKey(DATABASE_EXPLORED_KEY);+ const queryExecuted = useIntroStateByKey(QUERY_EXECUTED_KEY);+ const serverInfo = useAppStore((state) => state.serverInfo);+ const defaultProject = serverInfo?.defaultProject ?? "";+ const projectCacheSize = useAppStore(+ (state) => Object.keys(state.projectsByName).length+ );+ const instanceCacheSize = useAppStore(+ (state) => Object.keys(state.instancesByName).length+ );+ const databaseCacheSize = useAppStore(+ (state) => Object.keys(state.databasesByName).length+ );+ const workspaceResourceName = useAppStore((state) =>+ state.workspaceResourceName()+ );+ const [facts, setFacts] = useState<GuideFacts>(INITIAL_FACTS);+ const [loading, setLoading] = useState(true);+ const queryTargetRef = useRef<+ { projectName: string; databaseName: string } | undefined+ >(undefined);++ useEffect(() => {+ const off = sqlEditorEvents.on(+ "query-executed",+ ({ data: { database, project } }) => {+ if (!database) {+ return;+ }++ queryTargetRef.current = {+ projectName: project,+ databaseName: database,+ };+ const store = useAppStore.getState();+ if (!databaseExplored) {+ store.saveIntroStateByKey({+ key: DATABASE_EXPLORED_KEY,+ newState: true,+ });+ }+ if (!queryExecuted) {+ store.saveIntroStateByKey({+ key: QUERY_EXECUTED_KEY,+ newState: true,+ });+ }+ setFacts((state) => ({+ ...state,+ hasExploredDatabase: true,+ hasFirstQuery: true,+ databaseProjectName: project,+ databaseName: database,+ }));+ }+ );+ return () => {+ off();+ };+ }, [databaseExplored, queryExecuted]);++ useEffect(() => {+ if (+ dismissed ||+ !enabled ||+ databaseExplored ||+ !isConcreteDatabaseRoute(route.name, route.params ?? {})+ ) {+ return;+ }++ useAppStore.getState().saveIntroStateByKey({+ key: DATABASE_EXPLORED_KEY,+ newState: true,+ });+ setFacts((state) => ({ ...state, hasExploredDatabase: true }));+ }, [databaseExplored, dismissed, enabled, route.name, route.params]);++ useEffect(() => {+ if (dismissed || !enabled) {+ setFacts(INITIAL_FACTS);+ setLoading(false);+ return;+ }++ void (async () => {+ const store = useAppStore.getState();+ try {+ const projectResponse = await store.fetchProjectList({+ pageSize: 1,+ silent: true,+ filter: {+ excludeDefault: true,+ state: State.ACTIVE,+ },+ });+ const project = projectResponse.projects.find(+ ({ name }) => !!name && name !== defaultProject+ );+ const [+ workspaceInstanceResponse,+ projectInstanceResponse,+ databaseResponse,+ ] = await Promise.all([+ store.fetchInstanceList({+ pageSize: 1,+ filter: { state: State.ACTIVE },+ silent: true,+ }),+ project+ ? store.fetchInstanceList({+ parent: project.name,+ pageSize: 1,+ filter: { state: State.ACTIVE },+ silent: true,+ })+ : Promise.resolve({ instances: [], nextPageToken: "" }),+ project && workspaceResourceName+ ? store.fetchDatabases({+ parent: workspaceResourceName,+ pageSize: 1,+ filter: { project: project.name },+ silent: true,+ })+ : Promise.resolve(undefined),+ ]);+ const instance =+ workspaceInstanceResponse.instances[0] ??+ projectInstanceResponse.instances[0];+ const database = databaseResponse?.databases.find(+ ({ name, project }) => !!name && !!project+ );++ const latestDatabaseExplored = store.getIntroStateByKey(+ DATABASE_EXPLORED_KEY+ );+ const latestQueryExecuted =+ store.getIntroStateByKey(QUERY_EXECUTED_KEY);+ const queryTarget = latestQueryExecuted+ ? queryTargetRef.current+ : undefined;++ setFacts({+ hasProject: !!project,+ hasInstance: !!instance,+ hasExploredDatabase: latestDatabaseExplored,+ hasFirstQuery: latestQueryExecuted,+ projectName: project?.name ?? "",+ databaseProjectName:+ queryTarget?.projectName ?? database?.project ?? "",+ databaseName: queryTarget?.databaseName ?? database?.name ?? "",+ });+ } catch {+ // Keep the current progress when resource discovery is unavailable.+ }+ setLoading(false);+ })();+ }, [+ databaseCacheSize,+ databaseExplored,+ defaultProject,+ dismissed,+ enabled,+ instanceCacheSize,+ projectCacheSize,+ queryExecuted,+ route.name,+ workspaceResourceName,+ ]);++ const context = useMemo(() => ({ ...facts, route }), [facts, route]);+ return { context, loading };+};diff --git a/frontend/src/stores/app/index.test.ts b/frontend/src/stores/app/index.test.tsindex 7c50e001ae..dd412853a4 100644--- a/frontend/src/stores/app/index.test.ts+++ b/frontend/src/stores/app/index.test.ts@@ -2112,37 +2112,85 @@ describe("useAppStore", () => {expect(store.getState().appFeatures["bb.feature.hide-trial"]).toBe(false);});- test("enables the workspace setup guide only for an eligible sole IAM user", () => {+ test("enables the workspace setup guide for the sole workspace admin", () => {const store = createAppStore();- store.setState({ hasWorkspacePermission: () => true });+ store.setState({+ currentUser: user,+ serverInfo: createProto(ActuatorInfoSchema, { userCountInIam: 1 }),+ workspacePolicy: createProto(IamPolicySchema, {+ bindings: [+ createProto(BindingSchema, {+ role: "roles/workspaceAdmin",+ members: [user.name],+ }),+ ],+ }),+ });+ expect(store.getState().workspaceSetupGuideEnabled()).toBe(true);+ });- for (const [userCountInIam, expected] of [- [0, false],- [1, true],- [2, false],- ] as const) {- store.setState({- serverInfo: createProto(ActuatorInfoSchema, { userCountInIam }),- });- expect(store.getState().workspaceSetupGuideEnabled()).toBe(expected);- }+ test("keeps the workspace setup guide disabled until IAM loads", () => {+ const store = createAppStore();+ store.setState({+ currentUser: user,+ serverInfo: createProto(ActuatorInfoSchema, { userCountInIam: 1 }),+ workspacePolicy: undefined,+ });+ expect(store.getState().workspaceSetupGuideEnabled()).toBe(false);+ });- store.setState((state) => ({- appFeatures: {- ...state.appFeatures,- "bb.feature.hide-quick-start": true,- },- }));+ test("disables the workspace setup guide for a sole non-admin", () => {+ const store = createAppStore();+ store.setState({+ currentUser: user,+ serverInfo: createProto(ActuatorInfoSchema, { userCountInIam: 1 }),+ workspacePolicy: createProto(IamPolicySchema, {+ bindings: [+ createProto(BindingSchema, {+ role: "roles/workspaceMember",+ members: [user.name],+ }),+ ],+ }),+ });+ expect(store.getState().workspaceSetupGuideEnabled()).toBe(false);+ });++ test("disables the workspace setup guide after another member joins", () => {+ const store = createAppStore();+ store.setState({+ currentUser: user,+ serverInfo: createProto(ActuatorInfoSchema, { userCountInIam: 2 }),+ workspacePolicy: createProto(IamPolicySchema, {+ bindings: [+ createProto(BindingSchema, {+ role: "roles/workspaceAdmin",+ members: [user.name],+ }),+ ],+ }),+ });expect(store.getState().workspaceSetupGuideEnabled()).toBe(false);+ });- store.setState((state) => ({+ test("disables the workspace setup guide when quick start is hidden", () => {+ const store = createAppStore();+ store.setState({+ currentUser: user,appFeatures: {- ...state.appFeatures,- "bb.feature.hide-quick-start": false,+ ...store.getState().appFeatures,+ "bb.feature.hide-quick-start": true,},serverInfo: createProto(ActuatorInfoSchema, { userCountInIam: 1 }),- hasWorkspacePermission: () => false,- }));+ workspacePolicy: createProto(IamPolicySchema, {+ bindings: [+ createProto(BindingSchema, {+ role: "roles/workspaceAdmin",+ members: [user.name],+ }),+ ],+ }),+ });expect(store.getState().workspaceSetupGuideEnabled()).toBe(false);});diff --git a/frontend/src/stores/app/workspace.ts b/frontend/src/stores/app/workspace.tsindex b636def2ae..4e87c68c63 100644--- a/frontend/src/stores/app/workspace.ts+++ b/frontend/src/stores/app/workspace.ts@@ -20,6 +20,7 @@ import {workspaceSwitchChannel,} from "@/stores/workspaceSwitchChannel";import { defaultAppProfile } from "@/types/appProfile";+import { PresetRoleType } from "@/types/iam/role";import {hasFeature as checkFeature,hasInstanceFeature as checkInstanceFeature,@@ -688,12 +689,18 @@ export const createWorkspaceSlice: AppSliceCreator<WorkspaceSlice> = (enableOnboarding: () => get().userCountInIam() === 1,- workspaceSetupGuideEnabled: () =>- !get().appFeatures["bb.feature.hide-quick-start"] &&- get().userCountInIam() === 1 &&- get().hasWorkspacePermission("bb.projects.list") &&- get().hasWorkspacePermission("bb.instances.list") &&- get().hasWorkspacePermission("bb.databases.list"),+ workspaceSetupGuideEnabled: () => {+ const currentUserName = get().currentUser?.name;+ return (+ !get().appFeatures["bb.feature.hide-quick-start"] &&+ get().workspacePolicy !== undefined &&+ get().userCountInIam() === 1 &&+ !!currentUserName &&+ get()+ .getWorkspaceRolesByName(currentUserName)+ .has(PresetRoleType.WORKSPACE_ADMIN)+ );+ },fetchServerInfo: async () => {const info = await actuatorServiceClientConnect.getActuatorInfo({});