Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

refactor: compose workspace setup guide from reusable scenarios (#21303)

ecmadao8ddb9d00e0fa
diff --git a/docs/agents/frontend-ux.md b/docs/agents/frontend-ux.md
index 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 icon
independently. A layout owner MAY use standard breakpoint-prefixed classes to
apply 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.mjs
The 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 temporary
legacy exception by file, rule, token, and occurrence count.
diff --git a/frontend/scripts/check-react-i18n.mjs b/frontend/scripts/check-react-i18n.mjs
index 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.mjs
index 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.mjs
index 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" />
<Button
className={cn(
"h-8",
diff --git a/frontend/scripts/ui-guideline-legacy-debt.json b/frontend/scripts/ui-guideline-legacy-debt.json
index 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.tsx
index 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 the
diff --git a/frontend/src/components/BannersWrapper.test.tsx b/frontend/src/components/BannersWrapper.test.tsx
index 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.tsx
index 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.tsx
deleted file mode 100644
index 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.tsx
deleted file mode 100644
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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">
+ &rsaquo;
+ </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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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({});