Skip to content

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

feat: setup with scenarios (#21327)

ecmadao95e348ca4c9e
diff --git a/frontend/scripts/check-react-i18n.mjs b/frontend/scripts/check-react-i18n.mjs
index 8367262864..508fe99e82 100644
--- a/frontend/scripts/check-react-i18n.mjs
+++ b/frontend/scripts/check-react-i18n.mjs
@@ -53,9 +53,17 @@ 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.",
+ // Scenario option, sample, and guide outcome keys are stored in typed
+ // definitions and translated through those definitions at render time.
+ "settings.profile.enable-sample-databases",
+ "settings.profile.setup-scenario.create-database-change.",
+ "settings.profile.setup-scenario.query-data.",
+ "settings.profile.setup-scenario.workspace-usage.",
// 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.generic.",
+ "workspace-setup-guide.scenarios.",
"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
diff --git a/frontend/src/app/analytics/behavior.test.ts b/frontend/src/app/analytics/behavior.test.ts
index a9378b5d1e..7b2f73e0c0 100644
--- a/frontend/src/app/analytics/behavior.test.ts
+++ b/frontend/src/app/analytics/behavior.test.ts
@@ -237,19 +237,23 @@ describe("behavior analytics metrics", () => {
test("creates allowlisted custom action metrics and drops unsafe properties", () => {
expect(
- createBehaviorMetric("setup guide action clicked", {
+ createBehaviorMetric("workspace setup submitted", {
routeId: "workspace.landing",
resource: "projects/demo",
properties: {
- step: "hasProject",
+ scenario: "query-data",
+ result: "finished",
+ sample_enabled: true,
},
})
).toEqual({
- event: "setup guide action clicked",
+ event: "workspace setup submitted",
properties: {
route_id: "workspace.landing",
resource: "projects/demo",
- step: "hasProject",
+ scenario: "query-data",
+ result: "finished",
+ sample_enabled: true,
},
});
});
diff --git a/frontend/src/app/analytics/behavior.ts b/frontend/src/app/analytics/behavior.ts
index 43eef50ebf..8b8d5e0ded 100644
--- a/frontend/src/app/analytics/behavior.ts
+++ b/frontend/src/app/analytics/behavior.ts
@@ -25,10 +25,8 @@ export type BehaviorMetricName =
| "instance connection test clicked"
| "instance create clicked"
| "locked feature clicked"
- | "setup guide action clicked"
- | "setup guide dismissed"
- | "workspace setup completed"
- | "workspace setup skipped"
+ | "sample instance requested"
+ | "workspace setup submitted"
| "post sync first change clicked"
| "post sync sql editor clicked";
diff --git a/frontend/src/components/HowBytebaseWorksSheet.test.tsx b/frontend/src/components/HowBytebaseWorksSheet.test.tsx
index 09e97023f5..e366ce48aa 100644
--- a/frontend/src/components/HowBytebaseWorksSheet.test.tsx
+++ b/frontend/src/components/HowBytebaseWorksSheet.test.tsx
@@ -61,7 +61,7 @@ describe("HowBytebaseWorksSheet", () => {
expect(learnMoreLink).toHaveAttribute("target", "_blank");
});
- test("captures the learn more action", async () => {
+ test("does not record guide analytics for the learn more action", async () => {
render(<HowBytebaseWorksSheet open onOpenChange={vi.fn()} />);
fireEvent.click(
@@ -69,14 +69,7 @@ describe("HowBytebaseWorksSheet", () => {
name: "Learn more about how Bytebase organizes resources",
})
);
-
- expect(mocks.captureMetric).toHaveBeenCalledWith({
- event: "setup guide action clicked",
- properties: {
- action: "product_model_learn_more",
- source: "drawer",
- },
- });
+ expect(mocks.captureMetric).not.toHaveBeenCalled();
});
test.each([
diff --git a/frontend/src/components/HowBytebaseWorksSheet.tsx b/frontend/src/components/HowBytebaseWorksSheet.tsx
index bd91669f02..b28f9aa4df 100644
--- a/frontend/src/components/HowBytebaseWorksSheet.tsx
+++ b/frontend/src/components/HowBytebaseWorksSheet.tsx
@@ -1,7 +1,5 @@
-import type { MouseEvent, ReactElement } from "react";
+import type { ReactElement } from "react";
import { useTranslation } from "react-i18next";
-import { createBehaviorMetric } from "@/app/analytics/behavior";
-import { behaviorAnalytics } from "@/app/analytics/provider";
import { MarkdownEditor } from "@/components/MarkdownEditor";
import {
Sheet,
@@ -42,27 +40,13 @@ export function HowBytebaseWorksSheet({
return null;
}
- const handleContentClick = (event: MouseEvent<HTMLElement>) => {
- if (!(event.target instanceof Element) || !event.target.closest("a")) {
- return;
- }
- behaviorAnalytics.captureMetric(
- createBehaviorMetric("setup guide action clicked", {
- properties: {
- action: "product_model_learn_more",
- source: "drawer",
- },
- })
- );
- };
-
return (
<Sheet open={open} onOpenChange={onOpenChange}>
<SheetContent width="narrow">
<SheetHeader>
<SheetTitle>{t("workspace-setup-guide.product-model")}</SheetTitle>
</SheetHeader>
- <SheetBody onClick={handleContentClick}>
+ <SheetBody>
<MarkdownEditor content={guideContent} mode="preview" />
</SheetBody>
</SheetContent>
diff --git a/frontend/src/components/header/ProfileMenuTrigger.test.tsx b/frontend/src/components/header/ProfileMenuTrigger.test.tsx
index 816a91d3de..a9916769d5 100644
--- a/frontend/src/components/header/ProfileMenuTrigger.test.tsx
+++ b/frontend/src/components/header/ProfileMenuTrigger.test.tsx
@@ -24,7 +24,11 @@ const mocks = vi.hoisted(() => ({
params: {},
query: {},
},
- resetQuickstart: vi.fn(),
+ resumeQuickstart: vi.fn(),
+ captureMetric: vi.fn(),
+ scenarioId: "query-data" as string | undefined,
+ workspaceUsage: undefined as string | undefined,
+ introState: {} as Record<string, boolean>,
hideQuickStart: false,
canReadSetupResources: true,
userCountInIam: 1,
@@ -143,17 +147,29 @@ vi.mock("@/hooks/useAppState", () => ({
logo: "",
}),
useAppFeature: () => mocks.hideQuickStart,
- useWorkspaceSetupGuideReset: () => mocks.resetQuickstart,
+ useWorkspaceSetupGuideResume: () => mocks.resumeQuickstart,
+ useIntroStateByKey: (key: string) => mocks.introState[key] ?? false,
+}));
+
+vi.mock("@/app/analytics/provider", () => ({
+ behaviorAnalytics: {
+ captureMetric: mocks.captureMetric,
+ },
+}));
+
+vi.mock("@/modules/workspace-setup-guide/selection", () => ({
+ readGuideWorkspaceUsage: () => mocks.workspaceUsage,
+ readSelectedGuideScenarioId: () => mocks.scenarioId,
}));
vi.mock("@/stores/app", () => ({
useAppStore: Object.assign(
(selector: (state: unknown) => unknown) =>
selector({
- workspaceSetupGuideEnabled: () =>
+ workspaceSetupGuideEnabled: (allowMultipleMembers = false) =>
!mocks.hideQuickStart &&
mocks.canReadSetupResources &&
- mocks.userCountInIam === 1,
+ (mocks.userCountInIam === 1 || allowMultipleMembers),
}),
{
getState: () => ({
@@ -194,6 +210,9 @@ beforeEach(async () => {
mocks.canReadSetupResources = true;
mocks.userCountInIam = 1;
mocks.isDev = false;
+ mocks.scenarioId = "query-data";
+ mocks.workspaceUsage = undefined;
+ mocks.introState = {};
mocks.currentRoute.name = "sql-editor.home";
window.open = vi.fn();
({ ProfileMenuTrigger } = await import("./ProfileMenuTrigger"));
@@ -283,7 +302,7 @@ describe("ProfileMenuTrigger", () => {
unmount();
});
- test("restores the unified guide", () => {
+ test("resumes the selected guide", () => {
const { container, render, unmount } = renderIntoContainer(
<ProfileMenuTrigger size="medium" link />
);
@@ -295,7 +314,25 @@ describe("ProfileMenuTrigger", () => {
).find((button) => button.textContent === "Getting started");
expect(gettingStartedButton).not.toBeUndefined();
act(() => gettingStartedButton?.click());
- expect(mocks.resetQuickstart).toHaveBeenCalledTimes(1);
+ expect(mocks.resumeQuickstart).toHaveBeenCalledTimes(1);
+ expect(mocks.captureMetric).not.toHaveBeenCalled();
+ unmount();
+ });
+
+ test("resumes the generic setup journey without scenario analytics", () => {
+ mocks.scenarioId = undefined;
+ const { container, render, unmount } = renderIntoContainer(
+ <ProfileMenuTrigger size="medium" link />
+ );
+
+ render();
+
+ const gettingStartedButton = Array.from(
+ container.querySelectorAll("button")
+ ).find((button) => button.textContent === "Getting started");
+ act(() => gettingStartedButton?.click());
+ expect(mocks.resumeQuickstart).toHaveBeenCalledTimes(1);
+ expect(mocks.captureMetric).not.toHaveBeenCalled();
unmount();
});
@@ -311,6 +348,46 @@ describe("ProfileMenuTrigger", () => {
unmount();
});
+ test("keeps the original admin's unfinished team guide resumable", () => {
+ mocks.userCountInIam = 2;
+ mocks.workspaceUsage = "team";
+ const { container, render, unmount } = renderIntoContainer(
+ <ProfileMenuTrigger size="medium" link />
+ );
+
+ render();
+
+ expect(container.textContent).toContain("Getting started");
+ unmount();
+ });
+
+ test("ends the multi-member exception after completion acknowledgment", () => {
+ mocks.userCountInIam = 2;
+ mocks.workspaceUsage = "team";
+ mocks.introState["workspace-setup-guide.completed.query-data"] = true;
+ const { container, render, unmount } = renderIntoContainer(
+ <ProfileMenuTrigger size="medium" link />
+ );
+
+ render();
+
+ expect(container.textContent).not.toContain("Getting started");
+ unmount();
+ });
+
+ test("does not give an invited member the local team exception", () => {
+ mocks.userCountInIam = 2;
+ mocks.workspaceUsage = undefined;
+ const { container, render, unmount } = renderIntoContainer(
+ <ProfileMenuTrigger size="medium" link />
+ );
+
+ render();
+
+ expect(container.textContent).not.toContain("Getting started");
+ unmount();
+ });
+
test("hides getting started without setup resource permissions", () => {
mocks.canReadSetupResources = false;
const { container, render, unmount } = renderIntoContainer(
diff --git a/frontend/src/components/header/ProfileMenuTrigger.tsx b/frontend/src/components/header/ProfileMenuTrigger.tsx
index aa843702c2..e348a0b541 100644
--- a/frontend/src/components/header/ProfileMenuTrigger.tsx
+++ b/frontend/src/components/header/ProfileMenuTrigger.tsx
@@ -22,11 +22,18 @@ import {
} from "@/components/ui/dropdown-menu";
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";
import {
+ useIntroStateByKey,
useOptionalCurrentUser,
useSubscription,
useWorkspace,
- useWorkspaceSetupGuideReset,
+ useWorkspaceSetupGuideResume,
} from "@/hooks/useAppState";
+import { guideCompletionAcknowledgedKey } from "@/modules/workspace-setup-guide/progress";
+import { getGuideJourney } from "@/modules/workspace-setup-guide/scenarios";
+import {
+ readGuideWorkspaceUsage,
+ readSelectedGuideScenarioId,
+} from "@/modules/workspace-setup-guide/selection";
import { useAppStore } from "@/stores/app";
import { PlanType } from "@/types/proto-es/v1/subscription_service_pb";
import { isDev } from "@/utils/util";
@@ -48,9 +55,17 @@ export function ProfileMenuTrigger({
const workspace = useWorkspace();
const route = useCurrentRoute();
const navigate = useNavigate();
- const resetWorkspaceSetupGuide = useWorkspaceSetupGuideReset();
+ const resumeWorkspaceSetupGuide = useWorkspaceSetupGuideResume();
+ const scenarioId = readSelectedGuideScenarioId();
+ const workspaceUsage = readGuideWorkspaceUsage();
+ const journey = getGuideJourney(scenarioId, workspaceUsage);
+ const completionAcknowledged = useIntroStateByKey(
+ guideCompletionAcknowledgedKey(journey.id)
+ );
+ const allowMultipleMembers =
+ workspaceUsage === "team" && !completionAcknowledged;
const workspaceSetupGuideEnabled = useAppStore((state) =>
- state.workspaceSetupGuideEnabled()
+ state.workspaceSetupGuideEnabled(allowMultipleMembers)
);
const currentPlan = subscription?.plan ?? PlanType.FREE;
const devLicenseOptions = [
@@ -224,7 +239,7 @@ export function ProfileMenuTrigger({
{workspaceSetupGuideEnabled ? (
<DropdownMenuItem
onClick={() => {
- resetWorkspaceSetupGuide();
+ resumeWorkspaceSetupGuide();
setOpen(false);
}}
>
diff --git a/frontend/src/components/instance/CreateInstanceView.test.tsx b/frontend/src/components/instance/CreateInstanceView.test.tsx
index d646f309c1..f46005a70f 100644
--- a/frontend/src/components/instance/CreateInstanceView.test.tsx
+++ b/frontend/src/components/instance/CreateInstanceView.test.tsx
@@ -12,6 +12,7 @@ const mocks = vi.hoisted(() => ({
onDismiss: vi.fn(),
onCreated: vi.fn(),
prepareSampleProjectInstance: vi.fn(),
+ captureMetric: vi.fn(),
pushNotification: vi.fn(),
isSaaSMode: false,
sampleAvailable: true,
@@ -62,6 +63,10 @@ vi.mock("@/hooks/useUnsavedChangesGuard", () => ({
useUnsavedChangesGuard: mocks.useUnsavedChangesGuard,
}));
+vi.mock("@/app/analytics/provider", () => ({
+ behaviorAnalytics: { captureMetric: mocks.captureMetric },
+}));
+
vi.mock("@/stores/app", () => ({
useAppStore: Object.assign(
<T,>(selector: (state: Record<string, unknown>) => T) =>
@@ -351,6 +356,13 @@ describe("CreateInstanceView", () => {
expect(mocks.prepareSampleProjectInstance).toHaveBeenCalledWith(
"projects/demo"
);
+ expect(mocks.captureMetric).toHaveBeenCalledWith({
+ event: "sample instance requested",
+ properties: { source: "instance_creation" },
+ });
+ expect(mocks.captureMetric.mock.invocationCallOrder[0]).toBeLessThan(
+ mocks.prepareSampleProjectInstance.mock.invocationCallOrder[0]
+ );
expect(mocks.onCreated).toHaveBeenCalledWith(instance);
act(() => {
@@ -531,6 +543,10 @@ describe("CreateInstanceView", () => {
description:
"[internal] The sample instance cannot be provisioned. Try again later.",
});
+ expect(mocks.captureMetric).toHaveBeenCalledWith({
+ event: "sample instance requested",
+ properties: { source: "instance_creation" },
+ });
act(() => {
root.unmount();
diff --git a/frontend/src/components/instance/CreateInstanceView.tsx b/frontend/src/components/instance/CreateInstanceView.tsx
index 9547141703..73195a55a5 100644
--- a/frontend/src/components/instance/CreateInstanceView.tsx
+++ b/frontend/src/components/instance/CreateInstanceView.tsx
@@ -1,5 +1,7 @@
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { useTranslation } from "react-i18next";
+import { createBehaviorMetric } from "@/app/analytics/behavior";
+import { behaviorAnalytics } from "@/app/analytics/provider";
import {
InfoPanel,
InfoPanelContent,
@@ -178,6 +180,11 @@ function CreateInstanceFormInner({
if (!parent || isPreparingSampleProjectInstance || state.isRequesting) {
return;
}
+ behaviorAnalytics.captureMetric(
+ createBehaviorMetric("sample instance requested", {
+ properties: { source: "instance_creation" },
+ })
+ );
setIsPreparingSampleProjectInstance(true);
setState((prev) => ({ ...prev, isRequesting: true }));
try {
diff --git a/frontend/src/hooks/useAppState.ts b/frontend/src/hooks/useAppState.ts
index 8c34c83bd1..7cfd662816 100644
--- a/frontend/src/hooks/useAppState.ts
+++ b/frontend/src/hooks/useAppState.ts
@@ -484,8 +484,8 @@ export function useNotify() {
return useAppStore((state) => state.notify);
}
-export function useWorkspaceSetupGuideReset() {
- return useAppStore((state) => state.resetWorkspaceSetupGuide);
+export function useWorkspaceSetupGuideResume() {
+ return useAppStore((state) => state.resumeWorkspaceSetupGuide);
}
export function useIntroStateByKey(key: string) {
diff --git a/frontend/src/lib/plan/events.test.ts b/frontend/src/lib/plan/events.test.ts
new file mode 100644
index 0000000000..f8bfcfa882
--- /dev/null
+++ b/frontend/src/lib/plan/events.test.ts
@@ -0,0 +1,23 @@
+import { describe, expect, test, vi } from "vitest";
+import { planEvents } from "./events";
+
+describe("planEvents", () => {
+ test("delivers database change issue creation", async () => {
+ const listener = vi.fn();
+ const off = planEvents.on("database-change-issue-created", listener);
+
+ await planEvents.emit("database-change-issue-created", {
+ issue: "projects/app/issues/1",
+ project: "projects/app",
+ });
+
+ expect(listener).toHaveBeenCalledWith({
+ name: "database-change-issue-created",
+ data: {
+ issue: "projects/app/issues/1",
+ project: "projects/app",
+ },
+ });
+ off();
+ });
+});
diff --git a/frontend/src/lib/plan/events.ts b/frontend/src/lib/plan/events.ts
new file mode 100644
index 0000000000..58e1322af0
--- /dev/null
+++ b/frontend/src/lib/plan/events.ts
@@ -0,0 +1,10 @@
+import Emittery from "emittery";
+
+export type PlanEvents = {
+ "database-change-issue-created": {
+ issue: string;
+ project: string;
+ };
+};
+
+export const planEvents = new Emittery<PlanEvents>();
diff --git a/frontend/src/lib/plan/workflow.test.ts b/frontend/src/lib/plan/workflow.test.ts
index 4c8df7bc45..cd74cf2473 100644
--- a/frontend/src/lib/plan/workflow.test.ts
+++ b/frontend/src/lib/plan/workflow.test.ts
@@ -10,6 +10,7 @@ import type {
Plan,
} from "@/types/proto-es/v1/plan_service_pb";
import { PlanSchema } from "@/types/proto-es/v1/plan_service_pb";
+import { planEvents } from "./events";
import {
createPlanWithDraftReview,
DraftReviewIssueCreationError,
@@ -61,6 +62,8 @@ describe("createPlanWithDraftReview", () => {
calls.push("issue");
return draftIssue;
});
+ const issueCreated = vi.fn();
+ const off = planEvents.on("database-change-issue-created", issueCreated);
const result = await createPlanWithDraftReview({
createIssue,
@@ -82,6 +85,16 @@ describe("createPlanWithDraftReview", () => {
plan: "projects/p1/plans/123",
title: "Add index",
});
+ await vi.waitFor(() =>
+ expect(issueCreated).toHaveBeenCalledWith({
+ name: "database-change-issue-created",
+ data: {
+ issue: "projects/p1/issues/456",
+ project: "projects/p1",
+ },
+ })
+ );
+ off();
});
test("reports the persisted malformed plan and never retries when draft issue creation fails", async () => {
@@ -90,6 +103,8 @@ describe("createPlanWithDraftReview", () => {
const createIssue = vi.fn(async () => {
throw failure;
});
+ const issueCreated = vi.fn();
+ const off = planEvents.on("database-change-issue-created", issueCreated);
const promise = createPlanWithDraftReview({
createIssue,
@@ -106,6 +121,8 @@ describe("createPlanWithDraftReview", () => {
} satisfies Partial<DraftReviewIssueCreationError>);
expect(createPlan).toHaveBeenCalledOnce();
expect(createIssue).toHaveBeenCalledOnce();
+ expect(issueCreated).not.toHaveBeenCalled();
+ off();
});
});
diff --git a/frontend/src/lib/plan/workflow.ts b/frontend/src/lib/plan/workflow.ts
index 18916f5e16..57dadba80a 100644
--- a/frontend/src/lib/plan/workflow.ts
+++ b/frontend/src/lib/plan/workflow.ts
@@ -16,6 +16,7 @@ import type {
Plan,
} from "@/types/proto-es/v1/plan_service_pb";
import { CreatePlanRequestSchema } from "@/types/proto-es/v1/plan_service_pb";
+import { planEvents } from "./events";
export class DraftReviewIssueCreationError extends Error {
readonly plan: Plan;
@@ -64,6 +65,12 @@ export async function createPlanWithDraftReview({
}),
})
);
+ void planEvents
+ .emit("database-change-issue-created", {
+ issue: issue.name,
+ project: parent,
+ })
+ .catch(() => undefined);
return { issue, plan: createdPlan };
} catch (error) {
throw new DraftReviewIssueCreationError(createdPlan, error);
diff --git a/frontend/src/lib/productIntro.ts b/frontend/src/lib/productIntro.ts
index 5850d6c260..6bd98292b8 100644
--- a/frontend/src/lib/productIntro.ts
+++ b/frontend/src/lib/productIntro.ts
@@ -14,6 +14,8 @@ export const PREPARE_DATABASE_TRANSFER_TIP = "transfer-databases-to-project";
export const EXTERNAL_URL_PRODUCT_INTRO = "external-url";
export const AI_ASSISTANT_PRODUCT_INTRO = "ai-assistant";
export const DOMAIN_RESTRICTION_PRODUCT_INTRO = "domain-restriction";
+export const CREATE_USER_PRODUCT_INTRO = "create-user";
+export const GRANT_ACCESS_PRODUCT_INTRO = "grant-access";
export type ProductIntroOptions = {
id: string;
diff --git a/frontend/src/locales/en-US.json b/frontend/src/locales/en-US.json
index 8026cffaed..6858cf29d0 100644
--- a/frontend/src/locales/en-US.json
+++ b/frontend/src/locales/en-US.json
@@ -839,7 +839,11 @@
"partitions": "Partitions",
"procedures": "Procedures",
"project-instance-synced-action": "Create database change",
+ "project-instance-synced-create-change-description": "Your database is ready in this project. Create a governed database change to continue.",
+ "project-instance-synced-create-change-title": "Ready to create a database change",
"project-instance-synced-description": "Your database is ready in this project. Start by querying data in SQL Editor, or create a governed database change when needed.",
+ "project-instance-synced-query-data-description": "Your database is ready in this project. Open SQL Editor to query it.",
+ "project-instance-synced-query-data-title": "Database ready to query",
"project-instance-synced-sql-editor-action": "Open SQL Editor",
"project-instance-synced-title": "Database connected",
"project-instance-syncing-description": "This may take a few seconds to a few minutes. You can refresh this page later.",
@@ -2823,6 +2827,8 @@
"display-name-placeholder": "Enter your name",
"email": "Email",
"enable-sample-databases": "Enable sample databases",
+ "enable-sample-databases-create-change": "Enable sample databases as a safe database change target",
+ "enable-sample-databases-query-data": "Enable sample databases to start querying immediately",
"password": "Password",
"password-confirm": "Password Confirm",
"password-confirm-placeholder": "Confirm new password",
@@ -2832,10 +2838,36 @@
"phone-tips": "Be sure to include the country code +1xxxxxx",
"setup-failed": "Failed to update profile.",
"setup-first-project": "Setup 1st project",
+ "setup-scenario": {
+ "continue": "Continue",
+ "create-database-change": {
+ "description": "Define a change and create a traceable issue.",
+ "title": "Create a database change"
+ },
+ "outcome-title": "What would you like to do with Bytebase?",
+ "query-data": {
+ "description": "Open SQL Editor and run a statement against a database.",
+ "title": "Query data"
+ },
+ "workspace-usage": {
+ "solo": {
+ "description": "I will use Bytebase on my own.",
+ "title": "Just me"
+ },
+ "team": {
+ "description": "I will work with other people.",
+ "title": "My team"
+ },
+ "title": "Who will use Bytebase with you?"
+ }
+ },
"setup-skip": "I'll do this later",
+ "setup-steps": {
+ "scenario": "Choose a goal",
+ "workspace": "Set up workspace"
+ },
"setup-submit": "Setup my workspace",
"setup-success": "Profile updated.",
- "setup-title": "Welcome! Set up your workspace",
"workspace-name": "Workspace name",
"workspace-name-placeholder": "Enter workspace name"
},
@@ -3576,19 +3608,31 @@
"workspace-setup-guide": {
"actions": {
"change": "Create database change",
+ "done": "Done",
"query": "Go to SQL Editor"
},
"descriptions": {
- "database": "Open a database to explore its schemas and tables, or create one when needed.",
- "instance": "Connect an instance so Bytebase can sync your databases.",
+ "add-teammate": "Invite a teammate and grant them workspace access.",
+ "create-database-change": "Define a database change and create its issue.",
+ "database": "Open a database and explore its schemas and tables.",
+ "instance": "Connect an instance so Bytebase can sync its databases.",
"project": "Create a project to organize databases and changes.",
- "sql-editor": "Query data in SQL Editor, or create a governed database change."
+ "query-data": "Open the selected database in SQL Editor and run any statement."
},
"dismiss": "Dismiss guide",
+ "generic": {
+ "completion-description": "You explored how your project, instance, and database connect.",
+ "completion-title": "Your database workspace is ready",
+ "title": "Set up Bytebase"
+ },
"getting-started": "Getting started",
"intro": {
+ "create-user-description": "Create an account for a teammate in this self-hosted workspace.",
+ "create-user-title": "Create a user",
"database-description": "Create a database in your connected instance.",
"database-title": "Create a database",
+ "grant-access-description": "Invite a teammate and assign their workspace role.",
+ "grant-access-title": "Grant workspace access",
"instance-description": "Create an instance so Bytebase can connect to your database server.",
"instance-title": "Connect the instance",
"project-description": "Create a project first. Databases can be synced into it after the instance is connected.",
@@ -3599,12 +3643,27 @@
"prepare-database-tip": "Select databases to transfer to the project.",
"previous-step-required": "You need to finish the previous step.",
"product-model": "How Bytebase works",
- "self": "Set up Bytebase",
+ "scenarios": {
+ "create-database-change": {
+ "completion-description": "Your database change now has a traceable issue in Bytebase.",
+ "completion-title": "You created your first database change",
+ "title": "Create a database change"
+ },
+ "query-data": {
+ "completion-description": "You opened SQL Editor and ran a statement against your database.",
+ "completion-title": "You ran your first statement",
+ "title": "Query Data"
+ }
+ },
+ "step-progress": "{{current}} of {{total}}",
"steps": {
- "database": "Explore databases",
+ "add-teammate": "Add teammate",
+ "create-database-change": "Create database change",
+ "database": "Explore database",
"instance": "Connect instance",
"project": "Create project",
- "query": "Query data"
- }
+ "query-data": "Query data"
+ },
+ "view-all-steps": "View all steps"
}
}
diff --git a/frontend/src/locales/es-ES.json b/frontend/src/locales/es-ES.json
index 0b774cce21..7485c2720a 100644
--- a/frontend/src/locales/es-ES.json
+++ b/frontend/src/locales/es-ES.json
@@ -839,7 +839,11 @@
"partitions": "Particiones",
"procedures": "Procedimientos",
"project-instance-synced-action": "Crear cambio de base de datos",
+ "project-instance-synced-create-change-description": "Tu base de datos está lista en este proyecto. Crea un cambio de base de datos gobernado para continuar.",
+ "project-instance-synced-create-change-title": "Base de datos lista para cambios",
"project-instance-synced-description": "Tu base de datos está lista en este proyecto. Empieza consultando datos en SQL Editor, o crea un cambio de base de datos gobernado cuando lo necesites.",
+ "project-instance-synced-query-data-description": "Tu base de datos está lista en este proyecto. Abre SQL Editor para consultarla.",
+ "project-instance-synced-query-data-title": "Base de datos lista para consultar",
"project-instance-synced-sql-editor-action": "Abrir SQL Editor",
"project-instance-synced-title": "Base de datos conectada",
"project-instance-syncing-description": "Esto puede tardar de unos segundos a unos minutos. Puedes actualizar esta página más tarde.",
@@ -2823,6 +2827,8 @@
"display-name-placeholder": "Ingrese su nombre",
"email": "Correo electrónico",
"enable-sample-databases": "Habilitar bases de datos de ejemplo",
+ "enable-sample-databases-create-change": "Habilitar bases de datos de ejemplo como destino seguro para el cambio",
+ "enable-sample-databases-query-data": "Habilitar bases de datos de ejemplo para empezar a consultar de inmediato",
"password": "Contraseña",
"password-confirm": "Confirmar contraseña",
"password-confirm-placeholder": "Confirmar nueva contraseña",
@@ -2832,10 +2838,36 @@
"phone-tips": "Asegúrese de incluir el código del país +1xxxxxx",
"setup-failed": "Error al actualizar el perfil.",
"setup-first-project": "Configurar el primer proyecto",
+ "setup-scenario": {
+ "continue": "Continuar",
+ "create-database-change": {
+ "description": "Defina un cambio y cree una incidencia rastreable.",
+ "title": "Crear un cambio de base de datos"
+ },
+ "outcome-title": "¿Qué le gustaría hacer con Bytebase?",
+ "query-data": {
+ "description": "Abra SQL Editor y ejecute una sentencia en una base de datos.",
+ "title": "Consultar datos"
+ },
+ "workspace-usage": {
+ "solo": {
+ "description": "Usaré Bytebase por mi cuenta.",
+ "title": "Solo yo"
+ },
+ "team": {
+ "description": "Trabajaré con otras personas.",
+ "title": "Mi equipo"
+ },
+ "title": "¿Quién usará Bytebase con usted?"
+ }
+ },
"setup-skip": "Lo haré después",
+ "setup-steps": {
+ "scenario": "Elegir un objetivo",
+ "workspace": "Configurar espacio de trabajo"
+ },
"setup-submit": "Configurar mi espacio de trabajo",
"setup-success": "Perfil actualizado.",
- "setup-title": "¡Bienvenido! Configure su espacio de trabajo",
"workspace-name": "Nombre del espacio de trabajo",
"workspace-name-placeholder": "Ingrese el nombre del espacio de trabajo"
},
@@ -3576,19 +3608,31 @@
"workspace-setup-guide": {
"actions": {
"change": "Crear cambio de base de datos",
+ "done": "Listo",
"query": "Ir a SQL Editor"
},
"descriptions": {
- "database": "Consulta una base de datos de tu instancia conectada, o crea o transfiere una cuando sea necesario.",
- "instance": "Conecta una instancia para que Bytebase pueda sincronizar tus bases de datos.",
+ "add-teammate": "Invite a un compañero y concédale acceso al espacio de trabajo.",
+ "create-database-change": "Define un cambio de base de datos y crea su incidencia.",
+ "database": "Abre una base de datos y explora sus esquemas y tablas.",
+ "instance": "Conecta una instancia para que Bytebase pueda sincronizar sus bases de datos.",
"project": "Crea un proyecto para organizar bases de datos y cambios.",
- "sql-editor": "Consulta datos en SQL Editor o crea un cambio de base de datos gobernado."
+ "query-data": "Abre la base de datos seleccionada en SQL Editor y ejecuta cualquier sentencia."
},
"dismiss": "Cerrar guía",
+ "generic": {
+ "completion-description": "Exploraste cómo se conectan tu proyecto, instancia y base de datos.",
+ "completion-title": "Tu espacio de trabajo de bases de datos está listo",
+ "title": "Configurar Bytebase"
+ },
"getting-started": "Primeros pasos",
"intro": {
+ "create-user-description": "Cree una cuenta para un compañero en este espacio de trabajo autohospedado.",
+ "create-user-title": "Crear un usuario",
"database-description": "Crea una base de datos en tu instancia conectada.",
"database-title": "Crear base de datos",
+ "grant-access-description": "Invite a un compañero y asígnele un rol en el espacio de trabajo.",
+ "grant-access-title": "Conceder acceso al espacio de trabajo",
"instance-description": "Crea una instancia para que Bytebase pueda conectarse a tu servidor de base de datos.",
"instance-title": "Conectar la instancia",
"project-description": "Crea primero un proyecto. Las bases de datos se pueden sincronizar en él después de conectar la instancia.",
@@ -3599,12 +3643,27 @@
"prepare-database-tip": "Selecciona las bases de datos para transferirlas al proyecto.",
"previous-step-required": "Debes terminar el paso anterior.",
"product-model": "Cómo funciona Bytebase",
- "self": "Configurar Bytebase",
+ "scenarios": {
+ "create-database-change": {
+ "completion-description": "Tu cambio de base de datos ya tiene una incidencia rastreable en Bytebase.",
+ "completion-title": "Creaste tu primer cambio de base de datos",
+ "title": "Crear un cambio de base de datos"
+ },
+ "query-data": {
+ "completion-description": "Abriste SQL Editor y ejecutaste una sentencia en tu base de datos.",
+ "completion-title": "Ejecutaste tu primera sentencia",
+ "title": "Consultar datos"
+ }
+ },
+ "step-progress": "{{current}} de {{total}}",
"steps": {
- "database": "Explorar bases de datos",
+ "add-teammate": "Añadir compañero",
+ "create-database-change": "Crear cambio de base de datos",
+ "database": "Explorar base de datos",
"instance": "Conectar instancia",
"project": "Crear proyecto",
- "query": "Consultar datos"
- }
+ "query-data": "Consultar datos"
+ },
+ "view-all-steps": "Ver todos los pasos"
}
}
diff --git a/frontend/src/locales/ja-JP.json b/frontend/src/locales/ja-JP.json
index 6185fabc8c..894f6f15cf 100644
--- a/frontend/src/locales/ja-JP.json
+++ b/frontend/src/locales/ja-JP.json
@@ -839,7 +839,11 @@
"partitions": "パーティション",
"procedures": "ストアドプロシージャ",
"project-instance-synced-action": "データベース変更を作成",
+ "project-instance-synced-create-change-description": "このプロジェクトでデータベースを利用できます。管理されたデータベース変更を作成して続行してください。",
+ "project-instance-synced-create-change-title": "データベース変更の準備ができました",
"project-instance-synced-description": "このプロジェクトでデータベースを利用できるようになりました。まず SQL Editor でデータをクエリし、必要に応じて管理されたデータベース変更を作成できます。",
+ "project-instance-synced-query-data-description": "このプロジェクトでデータベースを利用できます。SQL Editor を開いてクエリしてください。",
+ "project-instance-synced-query-data-title": "データベースをクエリする準備ができました",
"project-instance-synced-sql-editor-action": "SQL Editor を開く",
"project-instance-synced-title": "データベースが接続されました",
"project-instance-syncing-description": "数秒から数分かかる場合があります。後でこのページを更新してください。",
@@ -2823,6 +2827,8 @@
"display-name-placeholder": "名前を入力してください",
"email": "メールアドレス",
"enable-sample-databases": "サンプルデータベースを有効にする",
+ "enable-sample-databases-create-change": "安全な変更対象としてサンプルデータベースを有効にする",
+ "enable-sample-databases-query-data": "すぐにクエリを試せるようサンプルデータベースを有効にする",
"password": "パスワード",
"password-confirm": "パスワードの確認",
"password-confirm-placeholder": "新しいパスワードを確認します",
@@ -2832,10 +2838,36 @@
"phone-tips": "国コードを必ず含めてください +81xxxxxx",
"setup-failed": "プロフィールの更新に失敗しました。",
"setup-first-project": "最初のプロジェクトを設定",
+ "setup-scenario": {
+ "continue": "続行",
+ "create-database-change": {
+ "description": "変更を定義し、追跡可能なイシューを作成します。",
+ "title": "データベース変更を作成"
+ },
+ "outcome-title": "Bytebase で何をしたいですか?",
+ "query-data": {
+ "description": "SQL Editor を開き、データベースでステートメントを実行します。",
+ "title": "データをクエリ"
+ },
+ "workspace-usage": {
+ "solo": {
+ "description": "自分だけで Bytebase を使用します。",
+ "title": "自分だけ"
+ },
+ "team": {
+ "description": "他のメンバーと一緒に使用します。",
+ "title": "チームで使用"
+ },
+ "title": "Bytebase を誰と使用しますか?"
+ }
+ },
"setup-skip": "後で設定する",
+ "setup-steps": {
+ "scenario": "目標を選択",
+ "workspace": "ワークスペースを設定"
+ },
"setup-submit": "ワークスペースをセットアップ",
"setup-success": "プロフィールが更新されました。",
- "setup-title": "ようこそ!ワークスペースを設定してください",
"workspace-name": "ワークスペース名",
"workspace-name-placeholder": "ワークスペース名を入力"
},
@@ -3576,19 +3608,31 @@
"workspace-setup-guide": {
"actions": {
"change": "データベース変更を作成",
+ "done": "完了",
"query": "SQL Editor に移動"
},
"descriptions": {
- "database": "接続したインスタンスのデータベースを確認し、必要に応じて作成または転送します。",
- "instance": "インスタンスを接続して、Bytebase がデータベースを同期できるようにします。",
+ "add-teammate": "チームメンバーを招待し、ワークスペースへのアクセスを付与します。",
+ "create-database-change": "データベース変更を定義し、そのイシューを作成します。",
+ "database": "データベースを開き、スキーマとテーブルを確認します。",
+ "instance": "Bytebase がデータベースを同期できるようにインスタンスを接続します。",
"project": "データベースと変更を整理するプロジェクトを作成します。",
- "sql-editor": "SQL Editor でデータをクエリするか、ガバナンス付きデータベース変更を作成します。"
+ "query-data": "選択したデータベースを SQL Editor で開き、任意のステートメントを実行します。"
},
"dismiss": "ガイドを閉じる",
+ "generic": {
+ "completion-description": "プロジェクト、インスタンス、データベースのつながりを確認しました。",
+ "completion-title": "データベースワークスペースの準備ができました",
+ "title": "Bytebase をセットアップ"
+ },
"getting-started": "はじめに",
"intro": {
+ "create-user-description": "このセルフホスト型ワークスペースにチームメンバーのアカウントを作成します。",
+ "create-user-title": "ユーザーを作成",
"database-description": "接続済みインスタンスにデータベースを作成します。",
"database-title": "データベースを作成",
+ "grant-access-description": "チームメンバーを招待し、ワークスペースロールを割り当てます。",
+ "grant-access-title": "ワークスペースアクセスを付与",
"instance-description": "Bytebase がデータベースサーバーに接続できるようにインスタンスを作成します。",
"instance-title": "インスタンスを接続",
"project-description": "まずプロジェクトを作成します。インスタンス接続後、データベースをそのプロジェクトに同期できます。",
@@ -3599,12 +3643,27 @@
"prepare-database-tip": "プロジェクトに転送するデータベースを選択します。",
"previous-step-required": "前のステップを先に完了する必要があります。",
"product-model": "Bytebase の仕組み",
- "self": "Bytebase をセットアップ",
+ "scenarios": {
+ "create-database-change": {
+ "completion-description": "データベース変更が Bytebase の追跡可能なイシューになりました。",
+ "completion-title": "最初のデータベース変更を作成しました",
+ "title": "データベース変更を作成"
+ },
+ "query-data": {
+ "completion-description": "SQL Editor を開き、データベースでステートメントを実行しました。",
+ "completion-title": "最初のステートメントを実行しました",
+ "title": "データをクエリ"
+ }
+ },
+ "step-progress": "{{total}} 件中 {{current}} 件目",
"steps": {
- "database": "データベースを探索",
+ "add-teammate": "メンバーを追加",
+ "create-database-change": "データベース変更を作成",
+ "database": "データベースを確認",
"instance": "インスタンスを接続",
"project": "プロジェクトを作成",
- "query": "データをクエリ"
- }
+ "query-data": "データをクエリ"
+ },
+ "view-all-steps": "すべてのステップを表示"
}
}
diff --git a/frontend/src/locales/vi-VN.json b/frontend/src/locales/vi-VN.json
index bd0c288d6f..ae4ec00d5e 100644
--- a/frontend/src/locales/vi-VN.json
+++ b/frontend/src/locales/vi-VN.json
@@ -839,7 +839,11 @@
"partitions": "Phân vùng",
"procedures": "Thủ tục",
"project-instance-synced-action": "Tạo thay đổi cơ sở dữ liệu",
+ "project-instance-synced-create-change-description": "Cơ sở dữ liệu của bạn đã sẵn sàng trong dự án này. Hãy tạo một thay đổi cơ sở dữ liệu được quản trị để tiếp tục.",
+ "project-instance-synced-create-change-title": "Cơ sở dữ liệu đã sẵn sàng để thay đổi",
"project-instance-synced-description": "Cơ sở dữ liệu của bạn đã sẵn sàng trong dự án này. Hãy bắt đầu bằng cách truy vấn dữ liệu trong SQL Editor, hoặc tạo thay đổi cơ sở dữ liệu được quản trị khi cần.",
+ "project-instance-synced-query-data-description": "Cơ sở dữ liệu của bạn đã sẵn sàng trong dự án này. Hãy mở SQL Editor để truy vấn.",
+ "project-instance-synced-query-data-title": "Cơ sở dữ liệu đã sẵn sàng để truy vấn",
"project-instance-synced-sql-editor-action": "Mở SQL Editor",
"project-instance-synced-title": "Đã kết nối cơ sở dữ liệu",
"project-instance-syncing-description": "Quá trình này có thể mất vài giây đến vài phút. Bạn có thể làm mới trang này sau.",
@@ -2823,6 +2827,8 @@
"display-name-placeholder": "Nhập tên của bạn",
"email": "Email",
"enable-sample-databases": "Bật cơ sở dữ liệu mẫu",
+ "enable-sample-databases-create-change": "Bật cơ sở dữ liệu mẫu làm đích thay đổi an toàn",
+ "enable-sample-databases-query-data": "Bật cơ sở dữ liệu mẫu để bắt đầu truy vấn ngay",
"password": "Mật khẩu",
"password-confirm": "Xác nhận mật khẩu",
"password-confirm-placeholder": "Xác nhận mật khẩu mới",
@@ -2832,10 +2838,36 @@
"phone-tips": "Nhớ bao gồm mã quốc gia +1xxxxxx",
"setup-failed": "Cập nhật hồ sơ thất bại.",
"setup-first-project": "Thiết lập dự án đầu tiên",
+ "setup-scenario": {
+ "continue": "Tiếp tục",
+ "create-database-change": {
+ "description": "Xác định thay đổi và tạo issue có thể theo dõi.",
+ "title": "Tạo thay đổi cơ sở dữ liệu"
+ },
+ "outcome-title": "Bạn muốn làm gì với Bytebase?",
+ "query-data": {
+ "description": "Mở SQL Editor và chạy một câu lệnh trên cơ sở dữ liệu.",
+ "title": "Truy vấn dữ liệu"
+ },
+ "workspace-usage": {
+ "solo": {
+ "description": "Tôi sẽ tự sử dụng Bytebase.",
+ "title": "Chỉ mình tôi"
+ },
+ "team": {
+ "description": "Tôi sẽ làm việc cùng những người khác.",
+ "title": "Nhóm của tôi"
+ },
+ "title": "Ai sẽ sử dụng Bytebase cùng bạn?"
+ }
+ },
"setup-skip": "Để sau",
+ "setup-steps": {
+ "scenario": "Chọn mục tiêu",
+ "workspace": "Thiết lập không gian làm việc"
+ },
"setup-submit": "Thiết lập không gian làm việc của tôi",
"setup-success": "Hồ sơ đã được cập nhật.",
- "setup-title": "Chào mừng! Thiết lập không gian làm việc của bạn",
"workspace-name": "Tên không gian làm việc",
"workspace-name-placeholder": "Nhập tên không gian làm việc"
},
@@ -3576,19 +3608,31 @@
"workspace-setup-guide": {
"actions": {
"change": "Tạo thay đổi cơ sở dữ liệu",
+ "done": "Xong",
"query": "Đi tới SQL Editor"
},
"descriptions": {
- "database": "Xem cơ sở dữ liệu từ instance đã kết nối, hoặc tạo hay chuyển một cơ sở dữ liệu khi cần.",
- "instance": "Kết nối instance để Bytebase có thể đồng bộ cơ sở dữ liệu của bạn.",
- "project": "Tạo dự án để quản lý cơ sở dữ liệu và thay đổi.",
- "sql-editor": "Truy vấn dữ liệu trong SQL Editor hoặc tạo thay đổi cơ sở dữ liệu được quản trị."
+ "add-teammate": "Mời một thành viên và cấp quyền truy cập không gian làm việc.",
+ "create-database-change": "Xác định thay đổi cơ sở dữ liệu và tạo issue cho thay đổi đó.",
+ "database": "Mở một cơ sở dữ liệu và khám phá schema cùng các bảng của cơ sở dữ liệu đó.",
+ "instance": "Kết nối một instance để Bytebase có thể đồng bộ các cơ sở dữ liệu.",
+ "project": "Tạo một dự án để tổ chức cơ sở dữ liệu và các thay đổi.",
+ "query-data": "Mở cơ sở dữ liệu đã chọn trong SQL Editor và chạy bất kỳ câu lệnh nào."
},
"dismiss": "Đóng hướng dẫn",
+ "generic": {
+ "completion-description": "Bạn đã khám phá cách dự án, instance và cơ sở dữ liệu kết nối với nhau.",
+ "completion-title": "Không gian làm việc cơ sở dữ liệu của bạn đã sẵn sàng",
+ "title": "Thiết lập Bytebase"
+ },
"getting-started": "Bắt đầu",
"intro": {
+ "create-user-description": "Tạo tài khoản cho một thành viên trong không gian làm việc tự lưu trữ này.",
+ "create-user-title": "Tạo người dùng",
"database-description": "Tạo cơ sở dữ liệu trong instance đã kết nối.",
"database-title": "Tạo cơ sở dữ liệu",
+ "grant-access-description": "Mời một thành viên và gán vai trò không gian làm việc cho họ.",
+ "grant-access-title": "Cấp quyền truy cập không gian làm việc",
"instance-description": "Tạo instance để Bytebase có thể kết nối tới máy chủ cơ sở dữ liệu của bạn.",
"instance-title": "Kết nối instance",
"project-description": "Tạo một dự án trước. Cơ sở dữ liệu có thể được đồng bộ vào dự án đó sau khi instance được kết nối.",
@@ -3599,12 +3643,27 @@
"prepare-database-tip": "Chọn cơ sở dữ liệu để chuyển vào dự án.",
"previous-step-required": "Bạn cần hoàn thành bước trước đó.",
"product-model": "Cách Bytebase hoạt động",
- "self": "Thiết lập Bytebase",
+ "scenarios": {
+ "create-database-change": {
+ "completion-description": "Thay đổi cơ sở dữ liệu của bạn hiện có một issue có thể theo dõi trong Bytebase.",
+ "completion-title": "Bạn đã tạo thay đổi cơ sở dữ liệu đầu tiên",
+ "title": "Tạo thay đổi cơ sở dữ liệu"
+ },
+ "query-data": {
+ "completion-description": "Bạn đã mở SQL Editor và chạy một câu lệnh trên cơ sở dữ liệu.",
+ "completion-title": "Bạn đã chạy câu lệnh đầu tiên",
+ "title": "Truy vấn dữ liệu"
+ }
+ },
+ "step-progress": "{{current}} / {{total}}",
"steps": {
+ "add-teammate": "Thêm thành viên",
+ "create-database-change": "Tạo thay đổi cơ sở dữ liệu",
"database": "Khám phá cơ sở dữ liệu",
"instance": "Kết nối instance",
"project": "Tạo dự án",
- "query": "Truy vấn dữ liệu"
- }
+ "query-data": "Truy vấn dữ liệu"
+ },
+ "view-all-steps": "Xem tất cả các bước"
}
}
diff --git a/frontend/src/locales/zh-CN.json b/frontend/src/locales/zh-CN.json
index 4e86bcae9f..60d3a462a9 100644
--- a/frontend/src/locales/zh-CN.json
+++ b/frontend/src/locales/zh-CN.json
@@ -839,7 +839,11 @@
"partitions": "分区",
"procedures": "存储过程",
"project-instance-synced-action": "创建数据库变更",
+ "project-instance-synced-create-change-description": "你的数据库已在此项目中就绪。请创建受管数据库变更以继续。",
+ "project-instance-synced-create-change-title": "数据库已可进行变更",
"project-instance-synced-description": "你的数据库已在此项目中就绪。可以先在 SQL Editor 中查询数据,也可以在需要时创建受管数据库变更。",
+ "project-instance-synced-query-data-description": "你的数据库已在此项目中就绪。请打开 SQL Editor 进行查询。",
+ "project-instance-synced-query-data-title": "数据库已可查询",
"project-instance-synced-sql-editor-action": "打开 SQL Editor",
"project-instance-synced-title": "数据库已连接",
"project-instance-syncing-description": "这可能需要几秒到几分钟。你可以稍后刷新此页面。",
@@ -2823,6 +2827,8 @@
"display-name-placeholder": "输入您的姓名",
"email": "邮箱",
"enable-sample-databases": "启用示例数据库",
+ "enable-sample-databases-create-change": "启用示例数据库作为安全的变更目标",
+ "enable-sample-databases-query-data": "启用示例数据库以立即开始查询",
"password": "密码",
"password-confirm": "确认密码",
"password-confirm-placeholder": "确认新密码",
@@ -2832,10 +2838,36 @@
"phone-tips": "请包含国家代码前缀 +86xxxxxx",
"setup-failed": "更新个人资料失败。",
"setup-first-project": "设置第一个项目",
+ "setup-scenario": {
+ "continue": "继续",
+ "create-database-change": {
+ "description": "定义变更并创建可追踪的工单。",
+ "title": "创建数据库变更"
+ },
+ "outcome-title": "您想使用 Bytebase 做什么?",
+ "query-data": {
+ "description": "打开 SQL Editor 并对数据库运行一条语句。",
+ "title": "查询数据"
+ },
+ "workspace-usage": {
+ "solo": {
+ "description": "我会独自使用 Bytebase。",
+ "title": "仅我自己"
+ },
+ "team": {
+ "description": "我会和其他成员一起使用。",
+ "title": "我的团队"
+ },
+ "title": "谁会和您一起使用 Bytebase?"
+ }
+ },
"setup-skip": "稍后再说",
+ "setup-steps": {
+ "scenario": "选择目标",
+ "workspace": "设置工作空间"
+ },
"setup-submit": "设置我的工作空间",
"setup-success": "个人资料已更新。",
- "setup-title": "欢迎!设置您的工作空间",
"workspace-name": "工作空间名称",
"workspace-name-placeholder": "输入工作空间名称"
},
@@ -3576,19 +3608,31 @@
"workspace-setup-guide": {
"actions": {
"change": "创建数据库变更",
+ "done": "完成",
"query": "前往 SQL Editor"
},
"descriptions": {
- "database": "查看已连接实例中的数据库;如有需要,可创建或转移数据库。",
- "instance": "连接实例,让 Bytebase 可以同步你的数据库。",
- "project": "创建项目来管理数据库和变更。",
- "sql-editor": "在 SQL Editor 中查询数据,或创建受管数据库变更。"
+ "add-teammate": "邀请团队成员并授予工作空间访问权限。",
+ "create-database-change": "定义数据库变更并创建对应工单。",
+ "database": "打开数据库,浏览其中的 schema 和表。",
+ "instance": "连接实例,以便 Bytebase 同步其中的数据库。",
+ "project": "创建项目来组织数据库和变更。",
+ "query-data": "在 SQL Editor 中打开所选数据库并运行任意语句。"
},
"dismiss": "关闭指南",
+ "generic": {
+ "completion-description": "你已了解项目、实例和数据库之间的连接关系。",
+ "completion-title": "你的数据库工作空间已准备就绪",
+ "title": "设置 Bytebase"
+ },
"getting-started": "入门指南",
"intro": {
+ "create-user-description": "在此自托管工作空间中为团队成员创建账户。",
+ "create-user-title": "创建用户",
"database-description": "在已连接的实例中创建数据库。",
"database-title": "创建数据库",
+ "grant-access-description": "邀请团队成员并分配工作空间角色。",
+ "grant-access-title": "授予工作空间访问权限",
"instance-description": "创建实例,让 Bytebase 可以连接到你的数据库服务器。",
"instance-title": "连接实例",
"project-description": "先创建一个项目。实例连接后,数据库可以同步到该项目中。",
@@ -3599,12 +3643,27 @@
"prepare-database-tip": "选择数据库并转移到项目。",
"previous-step-required": "你需要先完成上一步。",
"product-model": "Bytebase 的运作方式",
- "self": "设置 Bytebase",
+ "scenarios": {
+ "create-database-change": {
+ "completion-description": "你的数据库变更现在已在 Bytebase 中创建为可追踪工单。",
+ "completion-title": "你已创建第一个数据库变更",
+ "title": "创建数据库变更"
+ },
+ "query-data": {
+ "completion-description": "你已打开 SQL Editor 并对数据库运行了一条语句。",
+ "completion-title": "你已运行第一条语句",
+ "title": "查询数据"
+ }
+ },
+ "step-progress": "第 {{current}} 步,共 {{total}} 步",
"steps": {
+ "add-teammate": "添加团队成员",
+ "create-database-change": "创建数据库变更",
"database": "浏览数据库",
"instance": "连接实例",
"project": "创建项目",
- "query": "查询数据"
- }
+ "query-data": "查询数据"
+ },
+ "view-all-steps": "查看所有步骤"
}
}
diff --git a/frontend/src/modules/workspace-setup-guide/WorkspaceSetupGuide.test.tsx b/frontend/src/modules/workspace-setup-guide/WorkspaceSetupGuide.test.tsx
index e8b2669100..b800e6dd11 100644
--- a/frontend/src/modules/workspace-setup-guide/WorkspaceSetupGuide.test.tsx
+++ b/frontend/src/modules/workspace-setup-guide/WorkspaceSetupGuide.test.tsx
@@ -1,7 +1,21 @@
-import { act, cleanup, fireEvent, render, screen } from "@testing-library/react";
+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 {
+ GUIDE_PROGRESS_KEYS,
+ guideCompletionAcknowledgedKey,
+} from "./progress";
+import type {
+ GuideContext,
+ GuideScenarioId,
+ GuideWorkspaceUsage,
+} from "./types";
import { WorkspaceSetupGuide } from "./WorkspaceSetupGuide";
const guideContext = (
@@ -10,8 +24,13 @@ const guideContext = (
hasProject: false,
hasInstance: false,
hasExploredDatabase: false,
- hasFirstQuery: false,
+ hasRunStatement: false,
+ hasCreatedChangeIssue: false,
+ isSaaS: false,
+ hasOtherHumanUser: false,
+ hasOtherWorkspaceMember: false,
projectName: "",
+ instanceName: "",
databaseProjectName: "",
databaseName: "",
route: { name: "workspace.home", params: {} },
@@ -20,30 +39,39 @@ const guideContext = (
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>;
- },
+ currentRoute: { name: "workspace.home", params: {}, query: {} },
guideContext: undefined as unknown as GuideContext,
guideEnabled: true,
+ guideUserCount: 1,
introState: {} as Record<string, boolean>,
+ isSaaS: false,
loading: false,
preCreateIssue: vi.fn(),
productModelContent: "guide content" as string | undefined,
routerPush: vi.fn(),
saveIntroStateByKey: vi.fn(),
- workspaceName: "workspaces/default",
+ scenarioId: undefined as GuideScenarioId | undefined,
+ workspaceUsage: undefined as GuideWorkspaceUsage | undefined,
}));
+const resizeObserverCallbacks: ResizeObserverCallback[] = [];
+
+globalThis.ResizeObserver = class ResizeObserver {
+ constructor(callback: ResizeObserverCallback) {
+ resizeObserverCallbacks.push(callback);
+ }
+ observe() {}
+ unobserve() {}
+ disconnect() {}
+} as typeof ResizeObserver;
+
vi.mock("react-i18next", () => ({
- initReactI18next: { type: "3rdParty", init: () => {} },
+ initReactI18next: { type: "3rdParty", init: () => undefined },
useTranslation: () => ({
- t: (key: string) => key,
+ t: (key: string, options?: Record<string, unknown>) =>
+ key === "workspace-setup-guide.step-progress"
+ ? `${options?.current} of ${options?.total}`
+ : key,
i18n: { resolvedLanguage: "en-US" },
}),
}));
@@ -59,74 +87,52 @@ vi.mock("@/app/analytics/provider", () => ({
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,
+ HowBytebaseWorksSheet: ({ open }: { open: boolean }) =>
+ open ? <div data-testid="product-model-sheet" /> : null,
}));
vi.mock("@/components/SQLEditorButton", () => ({
SQLEditorButton: ({
- className,
label,
- ...props
+ "data-testid": testId,
}: {
- 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>
- );
- },
+ }) => <button data-testid={testId ?? "sql-editor-action"}>{label}</button>,
}));
vi.mock("@/hooks/useAppState", () => ({
useIntroStateByKey: (key: string) => mocks.introState[key] ?? false,
}));
-vi.mock("@/lib/plan/issue", () => ({
- preCreateIssue: mocks.preCreateIssue,
-}));
+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,
+ const state = () => ({
+ isSaaSMode: () => mocks.isSaaS,
+ workspaceSetupGuideEnabled: (allowMultipleMembers = false) =>
+ mocks.guideEnabled &&
+ (mocks.guideUserCount === 1 || allowMultipleMembers),
});
+ const useAppStore = Object.assign(
+ (selector: (value: ReturnType<typeof state>) => unknown) =>
+ selector(state()),
+ {
+ getState: () => ({
+ ...state(),
+ saveIntroStateByKey: mocks.saveIntroStateByKey,
+ getIntroStateByKey: (key: string) => mocks.introState[key] ?? false,
+ }),
+ }
+ );
return { useAppStore };
});
+vi.mock("./selection", () => ({
+ readGuideWorkspaceUsage: () => mocks.workspaceUsage,
+ readSelectedGuideScenarioId: () => mocks.scenarioId,
+}));
+
vi.mock("./useGuideContext", () => ({
useGuideContext: () => ({
context: mocks.guideContext,
@@ -136,363 +142,421 @@ vi.mock("./useGuideContext", () => ({
beforeEach(() => {
vi.clearAllMocks();
+ resizeObserverCallbacks.length = 0;
mocks.currentRoute = { name: "workspace.home", params: {}, query: {} };
mocks.guideContext = guideContext();
mocks.guideEnabled = true;
+ mocks.guideUserCount = 1;
mocks.introState = {};
+ mocks.isSaaS = false;
mocks.loading = false;
mocks.productModelContent = "guide content";
- mocks.workspaceName = "workspaces/default";
+ mocks.scenarioId = undefined;
+ mocks.workspaceUsage = undefined;
mocks.saveIntroStateByKey.mockImplementation(({ key, newState }) => {
mocks.introState[key] = newState;
});
});
-afterEach(() => {
- cleanup();
- vi.useRealTimers();
-});
+afterEach(cleanup);
describe("WorkspaceSetupGuide", () => {
- test("renders the approved scenario order with legacy test IDs", () => {
+ test("uses the same guide title for generic and scenario journeys", () => {
+ const first = render(<WorkspaceSetupGuide />);
+ expect(
+ screen.getByText("workspace-setup-guide.getting-started")
+ ).toBeVisible();
+ first.unmount();
+
+ mocks.scenarioId = "create-database-change";
+ render(<WorkspaceSetupGuide />);
+
+ expect(
+ screen.getByText("workspace-setup-guide.getting-started")
+ ).toBeVisible();
+ expect(
+ screen.queryByText(
+ "workspace-setup-guide.scenarios.create-database-change.title"
+ )
+ ).not.toBeInTheDocument();
+ });
+
+ test("renders generic resource setup when no scenario was selected", () => {
render(<WorkspaceSetupGuide />);
+
expect(
- screen
- .getAllByTestId(/^setup-step-/)
- .map((element) => element.getAttribute("data-testid"))
+ screen.getAllByTestId(/^setup-step-/).map((node) => node.dataset.testid)
).toEqual([
- "setup-step-hasProject",
- "setup-step-hasInstance",
- "setup-step-hasExploredDatabase",
- "setup-step-hasFirstQuery",
+ "setup-step-create-project",
+ "setup-step-connect-instance",
+ "setup-step-explore-database",
]);
+ expect(screen.queryByTestId("product-model-sheet")).not.toBeInTheDocument();
+ expect(screen.getByTestId("open-product-model")).toBeVisible();
});
- 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();
+ test("keeps Query Data prerequisites visible when they are complete", () => {
+ mocks.scenarioId = "query-data";
+ mocks.guideContext = guideContext({
+ hasProject: true,
+ hasInstance: true,
+ hasExploredDatabase: true,
+ databaseProjectName: "projects/app",
+ databaseName: "instances/sample/databases/employee",
});
+
+ render(<WorkspaceSetupGuide />);
+
expect(
- document.getElementById("bb-react-layer-overlay")?.textContent
- ).toContain("workspace-setup-guide.previous-step-required");
+ screen.getAllByTestId(/^setup-step-/).map((node) => node.dataset.testid)
+ ).toEqual([
+ "setup-step-create-project",
+ "setup-step-connect-instance",
+ "setup-step-explore-database",
+ "setup-step-query-data",
+ ]);
+ expect(screen.getByTestId("active-action")).toHaveTextContent(
+ "workspace-setup-guide.actions.query"
+ );
+ expect(screen.getByTestId("open-product-model")).toBeVisible();
});
- test("records and dispatches a selected step action", () => {
+ test("shows the full Query Data chain when setup has no resources", () => {
+ mocks.scenarioId = "query-data";
+
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" },
- });
+
+ expect(screen.getByTestId("setup-step-create-project")).toBeEnabled();
+ expect(screen.getByTestId("setup-step-connect-instance")).toBeDisabled();
+ expect(screen.getByTestId("setup-step-explore-database")).toBeDisabled();
+ expect(screen.getByTestId("setup-step-query-data")).toBeDisabled();
});
- test("renders query and change actions for the resolved query step", () => {
+ test("appends Add teammate after the selected outcome for team usage", () => {
+ mocks.scenarioId = "query-data";
+ mocks.workspaceUsage = "team";
mocks.guideContext = guideContext({
hasProject: true,
hasInstance: true,
hasExploredDatabase: true,
+ hasRunStatement: true,
databaseProjectName: "projects/app",
databaseName: "instances/sample/databases/employee",
});
+
render(<WorkspaceSetupGuide />);
- expect(screen.getByTestId("active-action")).toBeVisible();
- expect(screen.getByTestId("secondary-action")).toBeVisible();
+
+ expect(
+ screen.getAllByTestId(/^setup-step-/).map((node) => node.dataset.testid)
+ ).toEqual([
+ "setup-step-create-project",
+ "setup-step-connect-instance",
+ "setup-step-explore-database",
+ "setup-step-query-data",
+ "setup-step-add-teammate",
+ ]);
+ expect(screen.getByTestId("setup-step-add-teammate")).toBeEnabled();
});
- 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("keeps a completed multi-member team journey until Done", () => {
+ mocks.scenarioId = "query-data";
+ mocks.workspaceUsage = "team";
+ mocks.guideUserCount = 2;
+ mocks.guideContext = guideContext({
+ hasProject: true,
+ hasInstance: true,
+ hasExploredDatabase: true,
+ hasRunStatement: true,
+ hasOtherHumanUser: true,
+ hasOtherWorkspaceMember: true,
+ databaseProjectName: "projects/app",
+ databaseName: "instances/sample/databases/employee",
});
- });
- test("opens the product model once for a new eligible guide", () => {
+ const first = render(<WorkspaceSetupGuide />);
+ expect(screen.getByTestId("complete-guide")).toBeVisible();
+ fireEvent.click(screen.getByTestId("complete-guide"));
+ first.unmount();
+
render(<WorkspaceSetupGuide />);
- expect(screen.getByTestId("product-model-sheet")).toBeVisible();
+ expect(screen.queryByTestId("complete-guide")).not.toBeInTheDocument();
});
- test("does not auto-open the product model over a contextual intro", () => {
- mocks.currentRoute = {
- name: "workspace.project.database",
- params: {},
- query: { intro: "connect-database" },
- };
+ test.each([false, true])(
+ "keeps the self-host teammate action fixed when a user exists: %s",
+ (hasOtherHumanUser) => {
+ mocks.workspaceUsage = "team";
+ mocks.guideContext = guideContext({
+ hasProject: true,
+ hasInstance: true,
+ hasExploredDatabase: true,
+ hasOtherHumanUser,
+ databaseProjectName: "projects/app",
+ databaseName: "instances/sample/databases/employee",
+ });
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;
+ fireEvent.click(screen.getByTestId("setup-step-add-teammate"));
+
+ expect(mocks.routerPush).toHaveBeenCalledWith({
+ name: "workspace.users",
+ query: { intro: "create-user" },
+ });
+ }
+ );
+
+ test("uses the fixed SaaS grant-access teammate action", () => {
+ mocks.isSaaS = true;
+ mocks.workspaceUsage = "team";
+ mocks.guideContext = guideContext({
+ hasProject: true,
+ hasInstance: true,
+ hasExploredDatabase: true,
+ isSaaS: true,
+ databaseProjectName: "projects/app",
+ databaseName: "instances/sample/databases/employee",
+ });
render(<WorkspaceSetupGuide />);
- expect(screen.queryByTestId("product-model-sheet")).not.toBeInTheDocument();
+
+ fireEvent.click(screen.getByTestId("setup-step-add-teammate"));
+
+ expect(mocks.routerPush).toHaveBeenCalledWith({
+ name: "workspace.members",
+ query: { intro: "grant-access" },
+ });
});
- test("disables the product model drawer when localized content is missing", () => {
- mocks.productModelContent = undefined;
+ test("starts a database change for the discovered database", () => {
+ mocks.scenarioId = "create-database-change";
+ mocks.guideContext = guideContext({
+ hasProject: true,
+ hasInstance: true,
+ hasExploredDatabase: true,
+ databaseProjectName: "projects/app",
+ databaseName: "instances/sample/databases/employee",
+ });
+
render(<WorkspaceSetupGuide />);
- expect(screen.queryByTestId("open-product-model")).not.toBeInTheDocument();
- expect(screen.queryByTestId("product-model-sheet")).not.toBeInTheDocument();
+ fireEvent.click(screen.getByTestId("setup-step-create-database-change"));
+
+ expect(mocks.preCreateIssue).toHaveBeenCalledWith("projects/app", [
+ "instances/sample/databases/employee",
+ ]);
});
- 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("keeps a completed step selected after its navigation finishes", () => {
+ mocks.scenarioId = "create-database-change";
+ mocks.guideContext = guideContext({
+ hasProject: true,
+ hasInstance: true,
+ hasExploredDatabase: true,
+ databaseProjectName: "projects/app",
+ databaseName: "instances/sample/databases/employee",
+ route: { name: "workspace.project.database", params: {} },
});
- });
+ const { rerender } = render(<WorkspaceSetupGuide />);
- 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"
+ fireEvent.click(screen.getByTestId("setup-step-create-project"));
+ mocks.guideContext = {
+ ...mocks.guideContext,
+ route: { name: "workspace.project.database", params: {} },
+ };
+ rerender(<WorkspaceSetupGuide />);
+
+ mocks.currentRoute = {
+ name: "workspace.project",
+ params: {},
+ query: { intro: "create-project" },
+ };
+ mocks.guideContext = {
+ ...mocks.guideContext,
+ route: { name: "workspace.project", params: {} },
+ };
+ rerender(<WorkspaceSetupGuide />);
+
+ expect(screen.getByTestId("setup-step-create-project")).toHaveClass(
+ "bg-accent/10"
);
+ expect(
+ screen.getByTestId("setup-step-create-database-change")
+ ).not.toHaveClass("bg-accent/10");
});
- test("reopens the product model from the guide control", () => {
- mocks.introState["workspace-setup-guide.product-model-seen"] = true;
+ test.each<GuideScenarioId | undefined>([
+ undefined,
+ "query-data",
+ "create-database-change",
+ ])("opens optional product help for the %s guide", (scenarioId) => {
+ mocks.scenarioId = scenarioId;
render(<WorkspaceSetupGuide />);
- fireEvent.click(screen.getByTestId("open-product-model"));
+
+ const productModelButton = screen.getByTestId("open-product-model");
+ expect(productModelButton).toBeVisible();
+ expect(
+ screen.getByText("workspace-setup-guide.getting-started").parentElement
+ ).toContainElement(productModelButton);
+ fireEvent.click(productModelButton);
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",
+ test("uses medium density below the 2xl breakpoint", () => {
+ render(<WorkspaceSetupGuide />);
+
+ const title = screen.getByText("workspace-setup-guide.getting-started");
+ const guideBar = title.parentElement?.parentElement?.parentElement;
+ expect(guideBar).toHaveClass("px-4", "py-3", "2xl:px-5", "2xl:py-4");
+
+ const firstStep = screen.getByTestId("setup-step-create-project");
+ expect(firstStep).toHaveClass(
+ "px-2.5",
+ "py-1.5",
+ "2xl:px-3",
"2xl:py-2"
);
- expect(screen.getByTestId("dismiss-guide")).toHaveClass("h-7", "2xl:h-9");
+ expect(firstStep).toHaveClass("text-sm", "2xl:text-base");
});
- 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();
+ test("uses the compact step navigator only when the step list overflows", async () => {
+ mocks.scenarioId = "query-data";
+ mocks.workspaceUsage = "team";
+ render(<WorkspaceSetupGuide />);
+
+ const viewport = screen.getByTestId("guide-step-viewport");
+ const measurement = screen.getByTestId("guide-step-measurement");
+ Object.defineProperty(viewport, "clientWidth", {
+ configurable: true,
+ value: 500,
+ });
+ Object.defineProperty(measurement, "scrollWidth", {
+ configurable: true,
+ value: 400,
});
- 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();
+ act(() => {
+ for (const callback of resizeObserverCallbacks) {
+ callback([], {} as ResizeObserver);
+ }
});
+ expect(screen.getByTestId("guide-step-list")).toBeVisible();
expect(
- document.getElementById("bb-react-layer-overlay")?.textContent
- ).toContain("workspace-setup-guide.previous-step-required");
- });
+ screen.queryByTestId("compact-step-navigator")
+ ).not.toBeInTheDocument();
- 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,
+ Object.defineProperty(measurement, "scrollWidth", {
+ configurable: true,
+ value: 900,
});
- expect(mocks.captureMetric).toHaveBeenCalledWith({
- event: "setup guide dismissed",
- properties: { step: "hasProject" },
+ act(() => {
+ for (const callback of resizeObserverCallbacks) {
+ callback([], {} as ResizeObserver);
+ }
});
- 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" },
- });
+ expect(screen.getByTestId("compact-step-navigator")).toBeVisible();
+ expect(screen.queryByTestId("guide-step-list")).not.toBeInTheDocument();
+ expect(screen.getByText("1 of 5")).toBeVisible();
+ expect(screen.getByTestId("compact-active-step")).toHaveTextContent(
+ "workspace-setup-guide.steps.project"
+ );
+
+ fireEvent.click(screen.getByTestId("open-step-list"));
+ expect(await screen.findAllByRole("menuitem")).toHaveLength(5);
});
- test("stays hidden after it is dismissed", () => {
- mocks.introState["workspace-setup-guide.dismissed"] = true;
+ test("routes generic actions without recording guide analytics", () => {
render(<WorkspaceSetupGuide />);
- expect(screen.queryByText("workspace-setup-guide.self")).not.toBeInTheDocument();
+ fireEvent.click(screen.getByTestId("setup-step-create-project"));
+
+ expect(mocks.routerPush).toHaveBeenCalled();
+ expect(mocks.captureMetric).not.toHaveBeenCalled();
});
- test("does not replay create guidance from completed steps", () => {
+ test("dismisses the selected guide without recording analytics", () => {
+ mocks.scenarioId = "create-database-change";
mocks.guideContext = guideContext({
hasProject: true,
hasInstance: true,
+ hasExploredDatabase: 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();
- });
+ fireEvent.click(screen.getByTestId("dismiss-guide"));
- 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: {} },
+ expect(mocks.saveIntroStateByKey).toHaveBeenCalledWith({
+ key: GUIDE_PROGRESS_KEYS.dismissed,
+ newState: true,
});
- mocks.currentRoute = {
- name: "workspace.instance.create",
- params: {},
- query: {},
- };
- render(<WorkspaceSetupGuide />);
- expect(screen.queryByTestId("active-action")).not.toBeInTheDocument();
- expect(screen.getByTestId("dismiss-guide")).toBeVisible();
+ expect(mocks.captureMetric).not.toHaveBeenCalled();
});
- test("highlights the next incomplete step when the current route step is done", () => {
+ test("shows generic completion with both next actions", () => {
mocks.guideContext = guideContext({
hasProject: true,
hasInstance: true,
- projectName: "projects/app",
- route: { name: "workspace.project", params: {} },
+ hasExploredDatabase: true,
+ databaseProjectName: "projects/app",
+ databaseName: "instances/sample/databases/employee",
});
- 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();
+
+ expect(
+ screen.getByText("workspace-setup-guide.generic.completion-title")
+ ).toBeVisible();
+ expect(screen.getByText("workspace-setup-guide.actions.change")).toBeVisible();
+ expect(screen.getByText("workspace-setup-guide.actions.query")).toBeVisible();
+ fireEvent.click(screen.getByTestId("complete-guide"));
+ expect(mocks.saveIntroStateByKey).toHaveBeenCalledWith({
+ key: guideCompletionAcknowledgedKey("workspace-setup"),
+ newState: true,
+ });
});
- test("activates the query step when users click it after visiting another step", () => {
+ test("Query completion offers a database change", () => {
+ mocks.scenarioId = "query-data";
mocks.guideContext = guideContext({
hasProject: true,
hasInstance: true,
hasExploredDatabase: true,
- projectName: "projects/app",
+ hasRunStatement: true,
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"
- );
+
+ expect(screen.getByText("workspace-setup-guide.actions.change")).toBeVisible();
+ expect(screen.queryByText("workspace-setup-guide.actions.query")).not.toBeInTheDocument();
});
- test("opens the first database change flow as a secondary action", () => {
+ test("change completion offers SQL Editor", () => {
+ mocks.scenarioId = "create-database-change";
mocks.guideContext = guideContext({
hasProject: true,
hasInstance: true,
hasExploredDatabase: true,
+ hasCreatedChangeIssue: 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",
- ]);
+
+ expect(screen.getByText("workspace-setup-guide.actions.query")).toBeVisible();
+ expect(screen.queryByText("workspace-setup-guide.actions.change")).not.toBeInTheDocument();
});
- test("stays visible after the first query exists", () => {
+ test("does not record scenario guide lifecycle analytics", () => {
+ mocks.scenarioId = "create-database-change";
mocks.guideContext = guideContext({
hasProject: true,
hasInstance: true,
hasExploredDatabase: true,
- hasFirstQuery: true,
- databaseProjectName: "projects/app",
- databaseName: "instances/sample/databases/employee",
+ hasCreatedChangeIssue: true,
});
+
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"
- );
+
+ expect(mocks.captureMetric).not.toHaveBeenCalled();
});
});
diff --git a/frontend/src/modules/workspace-setup-guide/WorkspaceSetupGuide.tsx b/frontend/src/modules/workspace-setup-guide/WorkspaceSetupGuide.tsx
index ba90e5716b..52bb34ae01 100644
--- a/frontend/src/modules/workspace-setup-guide/WorkspaceSetupGuide.tsx
+++ b/frontend/src/modules/workspace-setup-guide/WorkspaceSetupGuide.tsx
@@ -1,8 +1,6 @@
-import { CheckCircle, Circle, CircleHelp, X } from "lucide-react";
-import { useEffect, useMemo, useRef, useState } from "react";
+import { CheckCircle, Circle, CircleHelp, ListChecks, X } from "lucide-react";
+import { useLayoutEffect, 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,
@@ -10,147 +8,140 @@ import {
} from "@/components/HowBytebaseWorksSheet";
import { SQLEditorButton } from "@/components/SQLEditorButton";
import { Button } from "@/components/ui/button";
-import { Tooltip } from "@/components/ui/tooltip";
+import {
+ DropdownMenu,
+ DropdownMenuContent,
+ DropdownMenuItem,
+ DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { BlockTooltip, 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 {
+ GUIDE_PROGRESS_KEYS,
+ guideCompletionAcknowledgedKey,
+} from "./progress";
import { resolveGuide } from "./resolve";
-import { LEARN_BYTEBASE_BASICS_SCENARIO } from "./scenarios";
+import { getGuideJourney } from "./scenarios";
+import {
+ readGuideWorkspaceUsage,
+ readSelectedGuideScenarioId,
+} from "./selection";
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 scenarioId = readSelectedGuideScenarioId();
+ const workspaceUsage = readGuideWorkspaceUsage();
+ const isSaaS = useAppStore((state) => state.isSaaSMode());
+ const journey = useMemo(
+ () => getGuideJourney(scenarioId, workspaceUsage, isSaaS),
+ [isSaaS, scenarioId, workspaceUsage]
+ );
+ const dismissed = useIntroStateByKey(GUIDE_PROGRESS_KEYS.dismissed);
+ const completionAcknowledged = useIntroStateByKey(
+ guideCompletionAcknowledgedKey(journey.id)
+ );
+ const allowMultipleMembers =
+ workspaceUsage === "team" && !completionAcknowledged;
const guideEnabled = useAppStore((state) =>
- state.workspaceSetupGuideEnabled()
+ state.workspaceSetupGuideEnabled(allowMultipleMembers)
);
- const workspaceResourceName = useAppStore((state) =>
- state.workspaceResourceName()
+ const productModelAvailable = !!getHowBytebaseWorksGuideContent(
+ i18n.resolvedLanguage ?? "en-US"
);
const { context, loading } = useGuideContext({
enabled: guideEnabled,
dismissed,
route: currentRoute,
+ scenarioId,
+ workspaceUsage,
});
- 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 [stepsOverflow, setStepsOverflow] = useState(false);
+ const stepViewportRef = useRef<HTMLDivElement>(null);
+ const stepMeasurementRef = useRef<HTMLDivElement>(null);
const guide = useMemo(
() =>
resolveGuide({
- scenario: LEARN_BYTEBASE_BASICS_SCENARIO,
+ journey,
registry: GUIDE_STEP_REGISTRY,
context,
selectedStepId,
}),
- [context, selectedStepId]
+ [context, journey, selectedStepId]
);
- const secondaryAction = guide.actionStep.actions.secondary;
- const primaryAction = guide.actionStep.actions.primary;
+ const primaryAction = guide.actionStep?.actions.primary;
+ const compactStep =
+ guide.highlightedStep ?? guide.actionStep ?? guide.steps[0];
+ const compactStepIndex = compactStep
+ ? guide.steps.findIndex(
+ (step) => step.definition.id === compactStep.definition.id
+ )
+ : -1;
- useEffect(() => {
- setSelectedStepId(undefined);
- }, [currentRoute.name]);
-
- useEffect(() => {
- if (productModelSeen) {
- productModelAutoOpenedScopeRef.current = undefined;
- return;
- }
- if (
- loading ||
- dismissed ||
- !guideEnabled ||
- !productModelAvailable ||
- hasContextualProductIntro ||
- !workspaceResourceName ||
- productModelAutoOpenedScopeRef.current === workspaceResourceName
- ) {
+ useLayoutEffect(() => {
+ if (guide.complete) {
+ setStepsOverflow(false);
return;
}
- productModelAutoOpenedScopeRef.current = workspaceResourceName;
- setProductModelOpen(true);
- }, [
- dismissed,
- guideEnabled,
- hasContextualProductIntro,
- loading,
- productModelAvailable,
- productModelSeen,
- workspaceResourceName,
- ]);
+ const viewport = stepViewportRef.current;
+ const measurement = stepMeasurementRef.current;
+ if (!viewport || !measurement) return;
+ const updateOverflow = () => {
+ setStepsOverflow(measurement.scrollWidth > viewport.clientWidth);
+ };
+ const observer = new ResizeObserver(updateOverflow);
+ observer.observe(viewport);
+ observer.observe(measurement);
+ updateOverflow();
+ return () => observer.disconnect();
+ }, [guide.complete, guide.steps, i18n.resolvedLanguage]);
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 action = step.actions.select;
+ if (action?.type === "navigate") void router.push(action.target);
+ if (action?.type === "create-change") {
+ void preCreateIssue(action.project, [action.database]);
}
};
const handleDismiss = () => {
- behaviorAnalytics.captureMetric(
- createBehaviorMetric("setup guide dismissed", {
- properties: {
- step: guide.actionStep.definition.analyticsKey,
- },
- })
- );
useAppStore.getState().saveIntroStateByKey({
- key: DISMISSED_KEY,
+ key: GUIDE_PROGRESS_KEYS.dismissed,
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) {
+ if (
+ dismissed ||
+ !guideEnabled ||
+ loading ||
+ (guide.complete && completionAcknowledged)
+ ) {
return null;
}
+ const hasDatabaseTarget =
+ !!context.databaseName && !!context.databaseProjectName;
+
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 w-full shrink-0 items-center gap-x-2 border-t border-block-border bg-background px-4 py-3 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")}
+ {t("workspace-setup-guide.getting-started")}
</div>
{productModelAvailable && (
<Tooltip content={t("workspace-setup-guide.product-model")}>
@@ -160,88 +151,247 @@ export function WorkspaceSetupGuide() {
size="sm"
data-testid="open-product-model"
aria-label={t("workspace-setup-guide.product-model")}
- onClick={() => handleProductModelOpenChange(true)}
+ onClick={() => setProductModelOpen(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}>
+ {guide.complete ? (
+ <div className="min-w-0 flex-1">
+ <div className="text-sm font-medium text-main">
+ {t(journey.completionTitleKey)}
+ </div>
+ <div className="truncate text-sm text-control-light">
+ {t(journey.completionDescriptionKey)}
+ </div>
+ </div>
+ ) : (
+ <div
+ ref={stepViewportRef}
+ data-testid="guide-step-viewport"
+ className="relative min-w-0 flex-1 overflow-hidden pr-1 2xl:pr-2"
+ >
+ <div
+ ref={stepMeasurementRef}
+ data-testid="guide-step-measurement"
+ aria-hidden
+ className="pointer-events-none invisible absolute left-0 top-0 flex w-max items-center gap-x-2 2xl:gap-x-3"
+ >
+ {guide.steps.map((step, index) => (
+ <div
+ key={step.definition.id}
+ className="inline-flex items-center gap-x-2 2xl:gap-x-3"
+ >
<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)}
+ tabIndex={-1}
+ className="inline-flex h-auto items-center justify-start gap-x-1 rounded-sm px-2.5 py-1.5 text-sm font-medium whitespace-nowrap 2xl:gap-x-2 2xl:px-3 2xl:py-2 2xl:text-base"
>
{step.done ? (
- <CheckCircle className="size-4 text-success 2xl:size-5" />
+ <CheckCircle className="size-4 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>
- )}
+ {index < guide.steps.length - 1 && (
+ <span className="text-sm 2xl:text-base">&rsaquo;</span>
+ )}
+ </div>
+ ))}
+ </div>
+
+ {stepsOverflow && compactStep ? (
+ <div
+ data-testid="compact-step-navigator"
+ className="flex min-w-0 items-center gap-x-2"
+ >
+ <span className="shrink-0 text-xs text-control-light 2xl:text-sm">
+ {t("workspace-setup-guide.step-progress", {
+ current: compactStepIndex + 1,
+ total: guide.steps.length,
+ })}
+ </span>
+ <BlockTooltip
+ content={
+ compactStep.blocked
+ ? t("workspace-setup-guide.previous-step-required")
+ : t(compactStep.definition.descriptionKey)
+ }
+ >
+ <Button
+ type="button"
+ appearance="secondary"
+ data-testid="compact-active-step"
+ className="inline-flex h-auto w-full min-w-0 items-center justify-start gap-x-1 rounded-sm bg-accent/10 px-2.5 py-1.5 text-sm font-medium text-accent 2xl:gap-x-2 2xl:px-3 2xl:py-2 2xl:text-base"
+ disabled={compactStep.blocked}
+ onClick={() => onSelectStep(compactStep)}
+ >
+ {compactStep.done ? (
+ <CheckCircle className="size-4 shrink-0 text-success 2xl:size-5" />
+ ) : (
+ <Circle className="size-4 shrink-0 2xl:size-5" />
+ )}
+ <span className="truncate">
+ {t(compactStep.definition.labelKey)}
+ </span>
+ </Button>
+ </BlockTooltip>
+ <DropdownMenu>
+ <DropdownMenuTrigger
+ render={
+ <Button
+ type="button"
+ appearance="secondary"
+ size="sm"
+ data-testid="open-step-list"
+ aria-label={t("workspace-setup-guide.view-all-steps")}
+ title={t("workspace-setup-guide.view-all-steps")}
+ >
+ <ListChecks className="size-4" />
+ </Button>
+ }
+ />
+ <DropdownMenuContent align="end" className="w-64">
+ {guide.steps.map((step) => {
+ const highlighted =
+ step.definition.id === compactStep.definition.id;
+ return (
+ <DropdownMenuItem
+ key={step.definition.id}
+ className={cn(
+ "gap-x-2",
+ highlighted && "bg-control-bg"
+ )}
+ disabled={step.blocked}
+ onClick={() => onSelectStep(step)}
+ >
+ {step.done ? (
+ <CheckCircle className="size-4 shrink-0 text-success" />
+ ) : (
+ <Circle className="size-4 shrink-0" />
+ )}
+ <span className="truncate">
+ {t(step.definition.labelKey)}
+ </span>
+ </DropdownMenuItem>
+ );
+ })}
+ </DropdownMenuContent>
+ </DropdownMenu>
</div>
- );
- })}
- </div>
+ ) : (
+ <div
+ data-testid="guide-step-list"
+ className="flex w-max items-center gap-x-2 2xl:gap-x-3"
+ >
+ {guide.steps.map((step, index) => {
+ const highlighted =
+ step.definition.id ===
+ guide.highlightedStep?.definition.id;
+ return (
+ <div
+ key={step.definition.id}
+ className="inline-flex items-center gap-x-2 2xl:gap-x-3"
+ >
+ <Tooltip
+ content={
+ step.blocked
+ ? t(
+ "workspace-setup-guide.previous-step-required"
+ )
+ : t(step.definition.descriptionKey)
+ }
+ >
+ <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.5 py-1.5 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>
+
<div className="ml-auto flex shrink-0 items-center gap-x-2">
- {secondaryAction?.type === "create-change" && (
+ {guide.complete &&
+ hasDatabaseTarget &&
+ journey.completionActions.includes("create-change") && (
+ <Button
+ type="button"
+ appearance="secondary"
+ onClick={() => {
+ void preCreateIssue(context.databaseProjectName, [
+ context.databaseName,
+ ]);
+ }}
+ >
+ {t("workspace-setup-guide.actions.change")}
+ </Button>
+ )}
+ {guide.complete &&
+ hasDatabaseTarget &&
+ journey.completionActions.includes("open-sql-editor") && (
+ <SQLEditorButton
+ database={{
+ name: context.databaseName,
+ project: context.databaseProjectName,
+ }}
+ openInNewTab
+ size="sm"
+ label={t("workspace-setup-guide.actions.query")}
+ />
+ )}
+ {guide.complete && (
<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,
- ]);
- }}
+ data-testid="complete-guide"
+ onClick={() =>
+ useAppStore.getState().saveIntroStateByKey({
+ key: guideCompletionAcknowledgedKey(journey.id),
+ newState: true,
+ })
+ }
>
- {t("workspace-setup-guide.actions.change")}
+ {t("workspace-setup-guide.actions.done")}
</Button>
)}
- {primaryAction?.type === "open-sql-editor" && (
+ {!guide.complete && 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")}
/>
)}
@@ -251,7 +401,7 @@ export function WorkspaceSetupGuide() {
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"
+ className="text-control-light hover:text-control 2xl:h-9"
onClick={handleDismiss}
>
<X className="size-4 2xl:size-5" />
@@ -261,7 +411,7 @@ export function WorkspaceSetupGuide() {
{productModelAvailable && (
<HowBytebaseWorksSheet
open={productModelOpen && !hasContextualProductIntro}
- onOpenChange={handleProductModelOpenChange}
+ onOpenChange={setProductModelOpen}
/>
)}
</>
diff --git a/frontend/src/modules/workspace-setup-guide/progress.test.ts b/frontend/src/modules/workspace-setup-guide/progress.test.ts
new file mode 100644
index 0000000000..3aa7e823a9
--- /dev/null
+++ b/frontend/src/modules/workspace-setup-guide/progress.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, test } from "vitest";
+import {
+ GUIDE_PROGRESS_KEYS,
+ guideCompletionAcknowledgedKey,
+} from "./progress";
+
+describe("workspace setup guide progress keys", () => {
+ test("keeps interaction evidence under the guide namespace", () => {
+ expect(GUIDE_PROGRESS_KEYS).toEqual({
+ databaseExplored: "workspace-setup-guide.database-explored",
+ statementRun: "workspace-setup-guide.statement-run",
+ changeIssueCreated: "workspace-setup-guide.change-issue-created",
+ teammateAdded: "workspace-setup-guide.teammate-added",
+ dismissed: "workspace-setup-guide.dismissed",
+ });
+ });
+
+ test("scopes completion acknowledgement by journey", () => {
+ expect(guideCompletionAcknowledgedKey("query-data")).toBe(
+ "workspace-setup-guide.completed.query-data"
+ );
+ expect(guideCompletionAcknowledgedKey("workspace-setup")).toBe(
+ "workspace-setup-guide.completed.workspace-setup"
+ );
+ });
+});
diff --git a/frontend/src/modules/workspace-setup-guide/progress.ts b/frontend/src/modules/workspace-setup-guide/progress.ts
new file mode 100644
index 0000000000..8f29e3624f
--- /dev/null
+++ b/frontend/src/modules/workspace-setup-guide/progress.ts
@@ -0,0 +1,12 @@
+import type { GuideJourneyId } from "./types";
+
+export const GUIDE_PROGRESS_KEYS = {
+ databaseExplored: "workspace-setup-guide.database-explored",
+ statementRun: "workspace-setup-guide.statement-run",
+ changeIssueCreated: "workspace-setup-guide.change-issue-created",
+ teammateAdded: "workspace-setup-guide.teammate-added",
+ dismissed: "workspace-setup-guide.dismissed",
+} as const;
+
+export const guideCompletionAcknowledgedKey = (id: GuideJourneyId) =>
+ `workspace-setup-guide.completed.${id}`;
diff --git a/frontend/src/modules/workspace-setup-guide/resolve.test.ts b/frontend/src/modules/workspace-setup-guide/resolve.test.ts
index e88f14f7bd..f3a43948ff 100644
--- a/frontend/src/modules/workspace-setup-guide/resolve.test.ts
+++ b/frontend/src/modules/workspace-setup-guide/resolve.test.ts
@@ -1,228 +1,230 @@
import { describe, expect, test } from "vitest";
import {
resolveGuide,
- validateGuideScenario,
- validateGuideScenarios,
+ validateGuideJourney,
+ validateGuideJourneys,
} from "./resolve";
import type {
GuideContext,
- GuideScenario,
+ GuideJourney,
GuideStepDefinition,
GuideStepId,
GuideStepRegistry,
} from "./types";
-const context = (
- completed: Partial<Record<GuideStepId, boolean>> = {}
+const STEP_IDS: GuideStepId[] = [
+ "create-project",
+ "connect-instance",
+ "explore-database",
+ "query-data",
+ "create-database-change",
+ "create-user",
+ "grant-access",
+];
+
+const createContext = (
+ overrides: Partial<GuideContext> = {}
): GuideContext => ({
- hasProject: completed["create-project"] ?? false,
- hasInstance: completed["connect-instance"] ?? false,
- hasExploredDatabase: completed["explore-database"] ?? false,
- hasFirstQuery: completed["query-data"] ?? false,
+ hasProject: false,
+ hasInstance: false,
+ hasExploredDatabase: false,
+ hasRunStatement: false,
+ hasCreatedChangeIssue: false,
+ isSaaS: false,
+ hasOtherHumanUser: false,
+ hasOtherWorkspaceMember: false,
projectName: "",
+ instanceName: "",
databaseProjectName: "",
databaseName: "",
route: { name: "workspace.home", params: {} },
+ ...overrides,
});
-const definition = (
- id: GuideStepId,
- isComplete: GuideStepDefinition["isComplete"]
-): GuideStepDefinition => ({
+const completionById: Record<GuideStepId, keyof GuideContext> = {
+ "create-project": "hasProject",
+ "connect-instance": "hasInstance",
+ "explore-database": "hasExploredDatabase",
+ "query-data": "hasRunStatement",
+ "create-database-change": "hasCreatedChangeIssue",
+ "create-user": "hasOtherWorkspaceMember",
+ "grant-access": "hasOtherWorkspaceMember",
+};
+
+const definition = (id: GuideStepId): GuideStepDefinition => ({
id,
- analyticsKey: (
- {
- "create-project": "hasProject",
- "connect-instance": "hasInstance",
- "explore-database": "hasExploredDatabase",
- "query-data": "hasFirstQuery",
- } as const
- )[id],
+ analyticsKey:
+ id === "create-user" || id === "grant-access" ? "add-teammate" : id,
labelKey: `label.${id}`,
descriptionKey: `description.${id}`,
- isComplete,
+ isComplete: (context) => Boolean(context[completionById[id]]),
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 registry = Object.fromEntries(
+ STEP_IDS.map((id) => [id, definition(id)])
+) as GuideStepRegistry;
-const scenario: GuideScenario = {
- id: "learn-bytebase-basics",
+const generic: GuideJourney = {
+ id: "workspace-setup",
+ completionTitleKey: "completion.generic.title",
+ completionDescriptionKey: "completion.generic.description",
+ completionActions: ["open-sql-editor", "create-change"],
steps: [
{ stepId: "create-project" },
- { stepId: "connect-instance" },
+ { stepId: "connect-instance", dependsOn: ["create-project"] },
+ { stepId: "explore-database", dependsOn: ["connect-instance"] },
+ ],
+};
+
+const queryData: GuideJourney = {
+ id: "query-data",
+ scenarioId: "query-data",
+ completionTitleKey: "completion.query.title",
+ completionDescriptionKey: "completion.query.description",
+ completionActions: ["create-change"],
+ steps: [
+ { stepId: "create-project", kind: "prerequisite" },
+ {
+ stepId: "connect-instance",
+ kind: "prerequisite",
+ dependsOn: ["create-project"],
+ },
{
stepId: "explore-database",
- dependsOn: ["create-project", "connect-instance"],
+ kind: "prerequisite",
+ dependsOn: ["connect-instance"],
},
{ stepId: "query-data", dependsOn: ["explore-database"] },
],
};
-describe("validateGuideScenario", () => {
- test("accepts the basics dependency graph", () => {
- expect(() => validateGuideScenario(scenario, registry)).not.toThrow();
+describe("validateGuideJourney", () => {
+ test("accepts selected and generic graphs", () => {
+ expect(() => validateGuideJourney(generic, registry)).not.toThrow();
+ expect(() => validateGuideJourney(queryData, registry)).not.toThrow();
});
test.each([
+ ["empty", { ...generic, steps: [] }, "at least one step"],
[
- "empty scenario",
- { ...scenario, steps: [] },
- "must contain at least one step",
- ],
- [
- "duplicate step",
+ "duplicate",
{
- ...scenario,
+ ...generic,
steps: [{ stepId: "create-project" }, { stepId: "create-project" }],
},
"duplicate step",
],
[
- "unknown step",
- { ...scenario, steps: [{ stepId: "missing" as GuideStepId }] },
+ "unknown",
+ { ...generic, steps: [{ stepId: "missing" as GuideStepId }] },
"unregistered step",
],
[
- "dependency outside scenario",
+ "external dependency",
{
- ...scenario,
- steps: [{ stepId: "query-data", dependsOn: ["explore-database"] }],
+ ...generic,
+ steps: [{ stepId: "create-project", dependsOn: ["connect-instance"] }],
},
- "dependency outside scenario",
+ "dependency outside journey",
],
[
"self dependency",
{
- ...scenario,
+ ...generic,
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) => {
+ ])("rejects an %s graph", (_name, journey, message) => {
expect(() =>
- validateGuideScenario(invalid as GuideScenario, registry)
+ validateGuideJourney(journey as GuideJourney, 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");
+ test("rejects duplicate journey ids", () => {
+ expect(() => validateGuideJourneys([generic, generic], registry)).toThrow(
+ "duplicate journey"
+ );
});
});
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([
+ test("uses generic setup order and dependencies", () => {
+ const guide = resolveGuide({
+ journey: generic,
+ registry,
+ context: createContext(),
+ });
+ expect(guide.steps.map((step) => step.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");
+ expect(guide.activeStep?.definition.id).toBe("create-project");
});
- test("allows the second independent root step to become active", () => {
- const resolved = resolveGuide({
- scenario,
+ test("keeps satisfied prerequisites visible", () => {
+ const guide = resolveGuide({
+ journey: queryData,
registry,
- context: context({ "create-project": true }),
+ context: createContext({
+ hasProject: true,
+ hasInstance: true,
+ hasExploredDatabase: true,
+ }),
});
- expect(resolved.activeStep.definition.id).toBe("connect-instance");
+ expect(guide.steps.map((step) => step.definition.id)).toEqual([
+ "create-project",
+ "connect-instance",
+ "explore-database",
+ "query-data",
+ ]);
+ expect(guide.steps.slice(0, 3).every((step) => step.done)).toBe(true);
+ expect(guide.activeStep?.definition.id).toBe("query-data");
});
- test("uses a valid manual selection for highlight and action", () => {
- const resolved = resolveGuide({
- scenario,
+ test("shows the full chain and blocks on missing prerequisites", () => {
+ const guide = resolveGuide({
+ journey: queryData,
registry,
- context: context(),
- selectedStepId: "connect-instance",
+ context: createContext(),
});
- 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();
+ expect(guide.steps.map((step) => step.definition.id)).toEqual([
+ "create-project",
+ "connect-instance",
+ "explore-database",
+ "query-data",
+ ]);
+ expect(guide.steps[1].blocked).toBe(true);
+ expect(guide.steps[3].blocked).toBe(true);
});
- test("ignores a selected ID that is not part of the scenario", () => {
- const resolved = resolveGuide({
- scenario,
+ test("allows a completed visible prerequisite to stay selected", () => {
+ const guide = resolveGuide({
+ journey: queryData,
registry,
- context: context(),
- selectedStepId: "missing" as GuideStepId,
+ context: createContext({ hasProject: true }),
+ selectedStepId: "create-project",
});
- expect(resolved.highlightedStep).toBeUndefined();
- expect(resolved.actionStep.definition.id).toBe("create-project");
+ expect(guide.highlightedStep?.definition.id).toBe("create-project");
+ expect(guide.actionStep?.definition.id).toBe("connect-instance");
});
- test("retains the final step after all steps complete", () => {
- const resolved = resolveGuide({
- scenario,
+ test("returns completion without an active action", () => {
+ const guide = resolveGuide({
+ journey: queryData,
registry,
- context: context({
- "create-project": true,
- "connect-instance": true,
- "explore-database": true,
- "query-data": true,
+ context: createContext({
+ hasProject: true,
+ hasInstance: true,
+ hasExploredDatabase: true,
+ hasRunStatement: true,
}),
});
- expect(resolved.activeStep.definition.id).toBe("query-data");
- expect(resolved.actionStep.definition.id).toBe("query-data");
+ expect(guide.complete).toBe(true);
+ expect(guide.activeStep).toBeUndefined();
+ expect(guide.actionStep).toBeUndefined();
});
});
diff --git a/frontend/src/modules/workspace-setup-guide/resolve.ts b/frontend/src/modules/workspace-setup-guide/resolve.ts
index 41cc71e75f..18c51e157a 100644
--- a/frontend/src/modules/workspace-setup-guide/resolve.ts
+++ b/frontend/src/modules/workspace-setup-guide/resolve.ts
@@ -1,56 +1,56 @@
import type {
GuideContext,
- GuideScenario,
+ GuideJourney,
GuideStepId,
GuideStepRegistry,
ResolvedGuide,
} from "./types";
-export const validateGuideScenario = (
- scenario: GuideScenario,
+export const validateGuideJourney = (
+ journey: GuideJourney,
registry: GuideStepRegistry
) => {
- if (scenario.steps.length === 0) {
+ if (journey.steps.length === 0) {
throw new Error(
- `Guide scenario ${scenario.id} must contain at least one step`
+ `Guide journey ${journey.id} must contain at least one step`
);
}
const indexById = new Map<GuideStepId, number>();
- for (const [index, step] of scenario.steps.entries()) {
+ for (const [index, step] of journey.steps.entries()) {
if (!registry[step.stepId]) {
throw new Error(
- `Guide scenario ${scenario.id} references unregistered step ${step.stepId}`
+ `Guide journey ${journey.id} references unregistered step ${step.stepId}`
);
}
if (indexById.has(step.stepId)) {
throw new Error(
- `Guide scenario ${scenario.id} contains duplicate step ${step.stepId}`
+ `Guide journey ${journey.id} contains duplicate step ${step.stepId}`
);
}
indexById.set(step.stepId, index);
}
- for (const step of scenario.steps) {
+ for (const step of journey.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}`
+ `Guide step ${step.stepId} has dependency outside journey: ${dependency}`
);
}
}
}
- const byId = new Map(scenario.steps.map((step) => [step.stepId, step]));
+ const byId = new Map(journey.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`
+ `Guide journey ${journey.id} contains a dependency cycle`
);
}
if (visited.has(stepId)) return;
@@ -61,9 +61,9 @@ export const validateGuideScenario = (
visiting.delete(stepId);
visited.add(stepId);
};
- for (const step of scenario.steps) visit(step.stepId);
+ for (const step of journey.steps) visit(step.stepId);
- for (const [index, step] of scenario.steps.entries()) {
+ for (const [index, step] of journey.steps.entries()) {
for (const dependency of step.dependsOn ?? []) {
if ((indexById.get(dependency) ?? -1) >= index) {
throw new Error(
@@ -74,66 +74,82 @@ export const validateGuideScenario = (
}
};
-export const validateGuideScenarios = (
- scenarios: readonly GuideScenario[],
+export const validateGuideJourneys = (
+ journeys: readonly GuideJourney[],
registry: GuideStepRegistry
) => {
const ids = new Set<string>();
- for (const scenario of scenarios) {
- if (ids.has(scenario.id)) {
+ for (const journey of journeys) {
+ if (ids.has(journey.id)) {
throw new Error(
- `Guide registry contains duplicate scenario ${scenario.id}`
+ `Guide registry contains duplicate journey ${journey.id}`
);
}
- ids.add(scenario.id);
- validateGuideScenario(scenario, registry);
+ ids.add(journey.id);
+ validateGuideJourney(journey, registry);
}
};
export const resolveGuide = ({
- scenario,
+ journey,
registry,
context,
selectedStepId,
}: {
- scenario: GuideScenario;
+ journey: GuideJourney;
registry: GuideStepRegistry;
context: GuideContext;
selectedStepId?: GuideStepId;
}): ResolvedGuide => {
const doneById = new Map(
- scenario.steps.map(({ stepId }) => [
+ journey.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;
+ const allSteps = journey.steps.map((journeyStep) => {
+ const definition = registry[journeyStep.stepId];
+ const done = doneById.get(journeyStep.stepId) ?? false;
return {
- scenarioStep,
+ journeyStep,
definition,
done,
blocked:
!done &&
- (scenarioStep.dependsOn ?? []).some(
+ (journeyStep.dependsOn ?? []).some(
(dependency) => !doneById.get(dependency)
),
actions: definition.resolveActions(context),
};
});
- const activeStep =
- steps.find((step) => !step.done && !step.blocked) ?? steps.at(-1)!;
+ const complete = journey.steps.every(
+ ({ stepId }) => doneById.get(stepId) === true
+ );
+ const steps = allSteps;
+ const activeStep = complete
+ ? undefined
+ : steps.find((step) => !step.done && !step.blocked);
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;
+ const highlightedStep = complete
+ ? undefined
+ : (selectedStep ??
+ (routeMatchedStep?.done ? activeStep : routeMatchedStep));
+ const actionStep = complete
+ ? undefined
+ : highlightedStep && !highlightedStep.done
+ ? highlightedStep
+ : activeStep;
- return { steps, activeStep, highlightedStep, actionStep };
+ return {
+ steps,
+ complete,
+ 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
index 0e4ea4b1fe..310d79aad8 100644
--- a/frontend/src/modules/workspace-setup-guide/scenarios.test.ts
+++ b/frontend/src/modules/workspace-setup-guide/scenarios.test.ts
@@ -1,27 +1,137 @@
import { describe, expect, test } from "vitest";
-import { validateGuideScenario } from "./resolve";
+import { validateGuideJourney } from "./resolve";
import {
+ CREATE_DATABASE_CHANGE_SCENARIO,
GUIDE_SCENARIO_REGISTRY,
- LEARN_BYTEBASE_BASICS_SCENARIO,
+ getGuideJourney,
+ QUERY_DATA_SCENARIO,
+ WORKSPACE_SETUP_JOURNEY,
} from "./scenarios";
import { GUIDE_STEP_REGISTRY } from "./steps";
-describe("learn-bytebase-basics", () => {
- test("is the only registered scenario and has the approved graph", () => {
+describe("workspace setup guide journeys", () => {
+ test("registers only the two customer scenarios", () => {
expect(Object.keys(GUIDE_SCENARIO_REGISTRY)).toEqual([
- "learn-bytebase-basics",
+ "query-data",
+ "create-database-change",
]);
- expect(LEARN_BYTEBASE_BASICS_SCENARIO.steps).toEqual([
- { stepId: "create-project" },
- { stepId: "connect-instance" },
+ });
+
+ test("uses an unassigned generic journey when no scenario was selected", () => {
+ expect(getGuideJourney(undefined)).toBe(WORKSPACE_SETUP_JOURNEY);
+ expect(WORKSPACE_SETUP_JOURNEY.scenarioId).toBeUndefined();
+ expect(WORKSPACE_SETUP_JOURNEY).toMatchObject({
+ id: "workspace-setup",
+ steps: [
+ { stepId: "create-project" },
+ { stepId: "connect-instance", dependsOn: ["create-project"] },
+ { stepId: "explore-database", dependsOn: ["connect-instance"] },
+ ],
+ });
+ });
+
+ test("uses workspace setup as visible Query Data prerequisites", () => {
+ expect(QUERY_DATA_SCENARIO.steps).toEqual([
+ { stepId: "create-project", kind: "prerequisite" },
+ {
+ stepId: "connect-instance",
+ kind: "prerequisite",
+ dependsOn: ["create-project"],
+ },
{
stepId: "explore-database",
- dependsOn: ["create-project", "connect-instance"],
+ kind: "prerequisite",
+ dependsOn: ["connect-instance"],
},
{ stepId: "query-data", dependsOn: ["explore-database"] },
]);
+ });
+
+ test("uses workspace setup as visible database-change prerequisites", () => {
+ expect(CREATE_DATABASE_CHANGE_SCENARIO.steps).toEqual([
+ { stepId: "create-project", kind: "prerequisite" },
+ {
+ stepId: "connect-instance",
+ kind: "prerequisite",
+ dependsOn: ["create-project"],
+ },
+ {
+ stepId: "explore-database",
+ kind: "prerequisite",
+ dependsOn: ["connect-instance"],
+ },
+ {
+ stepId: "create-database-change",
+ dependsOn: ["explore-database"],
+ },
+ ]);
+ });
+
+ test.each([
+ [undefined, ["create-project", "connect-instance", "explore-database"]],
+ [
+ "query-data" as const,
+ ["create-project", "connect-instance", "explore-database", "query-data"],
+ ],
+ [
+ "create-database-change" as const,
+ [
+ "create-project",
+ "connect-instance",
+ "explore-database",
+ "create-database-change",
+ ],
+ ],
+ ])(
+ "appends the team modifier after the %s journey",
+ (scenarioId, baseSteps) => {
+ const journey = getGuideJourney(scenarioId, "team", false);
+
+ expect(journey.steps.map(({ stepId }) => stepId)).toEqual([
+ ...baseSteps,
+ "create-user",
+ ]);
+ expect(journey.steps.at(-1)).toEqual({
+ stepId: "create-user",
+ kind: "modifier",
+ dependsOn: [baseSteps.at(-1)],
+ });
+ }
+ );
+
+ test("uses a fixed grant-access step for SaaS team journeys", () => {
+ const journey = getGuideJourney("query-data", "team", true);
+
+ expect(journey.steps.at(-1)).toEqual({
+ stepId: "grant-access",
+ kind: "modifier",
+ dependsOn: ["query-data"],
+ });
+ });
+
+ test.each([undefined, "solo" as const])(
+ "does not append the team modifier for workspace usage %s",
+ (workspaceUsage) => {
+ expect(
+ getGuideJourney("query-data", workspaceUsage).steps.map(
+ ({ stepId }) => stepId
+ )
+ ).toEqual([
+ "create-project",
+ "connect-instance",
+ "explore-database",
+ "query-data",
+ ]);
+ }
+ );
+
+ test.each([
+ WORKSPACE_SETUP_JOURNEY,
+ QUERY_DATA_SCENARIO,
+ CREATE_DATABASE_CHANGE_SCENARIO,
+ ])("validates $id", (journey) => {
expect(() =>
- validateGuideScenario(LEARN_BYTEBASE_BASICS_SCENARIO, GUIDE_STEP_REGISTRY)
+ validateGuideJourney(journey, 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
index 03a00ec573..4f3c6569c1 100644
--- a/frontend/src/modules/workspace-setup-guide/scenarios.ts
+++ b/frontend/src/modules/workspace-setup-guide/scenarios.ts
@@ -1,27 +1,93 @@
-import { validateGuideScenarios } from "./resolve";
+import { validateGuideJourneys } from "./resolve";
import { GUIDE_STEP_REGISTRY } from "./steps";
-import type { GuideScenario, GuideScenarioId } from "./types";
+import type {
+ GuideJourney,
+ GuideScenarioId,
+ GuideWorkspaceUsage,
+} from "./types";
-export const LEARN_BYTEBASE_BASICS_SCENARIO: GuideScenario = {
- id: "learn-bytebase-basics",
+export const WORKSPACE_SETUP_JOURNEY: GuideJourney = {
+ id: "workspace-setup",
+ completionTitleKey: "workspace-setup-guide.generic.completion-title",
+ completionDescriptionKey:
+ "workspace-setup-guide.generic.completion-description",
+ completionActions: ["open-sql-editor", "create-change"],
steps: [
{ stepId: "create-project" },
- { stepId: "connect-instance" },
+ { stepId: "connect-instance", dependsOn: ["create-project"] },
+ { stepId: "explore-database", dependsOn: ["connect-instance"] },
+ ],
+};
+
+const SCENARIO_PREREQUISITES = WORKSPACE_SETUP_JOURNEY.steps.map((step) => ({
+ ...step,
+ kind: "prerequisite" as const,
+}));
+
+export const QUERY_DATA_SCENARIO: GuideJourney = {
+ id: "query-data",
+ scenarioId: "query-data",
+ completionTitleKey:
+ "workspace-setup-guide.scenarios.query-data.completion-title",
+ completionDescriptionKey:
+ "workspace-setup-guide.scenarios.query-data.completion-description",
+ completionActions: ["create-change"],
+ steps: [
+ ...SCENARIO_PREREQUISITES,
+ { stepId: "query-data", dependsOn: ["explore-database"] },
+ ],
+};
+
+export const CREATE_DATABASE_CHANGE_SCENARIO: GuideJourney = {
+ id: "create-database-change",
+ scenarioId: "create-database-change",
+ completionTitleKey:
+ "workspace-setup-guide.scenarios.create-database-change.completion-title",
+ completionDescriptionKey:
+ "workspace-setup-guide.scenarios.create-database-change.completion-description",
+ completionActions: ["open-sql-editor"],
+ steps: [
+ ...SCENARIO_PREREQUISITES,
{
- stepId: "explore-database",
- dependsOn: ["create-project", "connect-instance"],
+ stepId: "create-database-change",
+ dependsOn: ["explore-database"],
},
- { stepId: "query-data", dependsOn: ["explore-database"] },
],
};
export const GUIDE_SCENARIO_REGISTRY: Readonly<
- Record<GuideScenarioId, GuideScenario>
+ Record<GuideScenarioId, GuideJourney>
> = {
- "learn-bytebase-basics": LEARN_BYTEBASE_BASICS_SCENARIO,
+ "query-data": QUERY_DATA_SCENARIO,
+ "create-database-change": CREATE_DATABASE_CHANGE_SCENARIO,
+};
+
+export const getGuideJourney = (
+ scenarioId: GuideScenarioId | undefined,
+ workspaceUsage?: GuideWorkspaceUsage,
+ isSaaS = false
+): GuideJourney => {
+ const journey = scenarioId
+ ? GUIDE_SCENARIO_REGISTRY[scenarioId]
+ : WORKSPACE_SETUP_JOURNEY;
+ if (workspaceUsage !== "team") return journey;
+
+ const previousStep = journey.steps.at(-1);
+ if (!previousStep) return journey;
+ return {
+ ...journey,
+ steps: [
+ ...journey.steps,
+ {
+ stepId: isSaaS ? "grant-access" : "create-user",
+ kind: "modifier",
+ dependsOn: [previousStep.stepId],
+ },
+ ],
+ };
};
-validateGuideScenarios(
- Object.values(GUIDE_SCENARIO_REGISTRY),
+validateGuideJourneys(
+ [WORKSPACE_SETUP_JOURNEY, ...Object.values(GUIDE_SCENARIO_REGISTRY)],
GUIDE_STEP_REGISTRY
);
diff --git a/frontend/src/modules/workspace-setup-guide/selection.test.ts b/frontend/src/modules/workspace-setup-guide/selection.test.ts
new file mode 100644
index 0000000000..e9ef53891f
--- /dev/null
+++ b/frontend/src/modules/workspace-setup-guide/selection.test.ts
@@ -0,0 +1,161 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import {
+ storageKeyWorkspaceSetupGuideScenario,
+ storageKeyWorkspaceSetupGuideWorkspaceUsage,
+} from "@/utils/storage-keys";
+import {
+ clearGuideWorkspaceUsage,
+ clearSelectedGuideScenarioId,
+ isGuideScenarioId,
+ isGuideWorkspaceUsage,
+ readGuideWorkspaceUsage,
+ readSelectedGuideScenarioId,
+ saveGuideWorkspaceUsage,
+ saveSelectedGuideScenarioId,
+} from "./selection";
+
+const mocks = vi.hoisted(() => ({
+ state: {
+ currentUser: {
+ email: "[email protected]",
+ workspace: "workspaces/ws1",
+ },
+ serverInfo: {
+ workspace: "workspaces/ws1",
+ },
+ },
+}));
+
+vi.mock("@/stores/app", () => ({
+ useAppStore: {
+ getState: () => mocks.state,
+ },
+}));
+
+const storageKey = (workspace = mocks.state.currentUser.workspace) =>
+ storageKeyWorkspaceSetupGuideScenario(
+ workspace,
+ mocks.state.currentUser.email
+ );
+
+const seedStoredValue = (value: unknown) => {
+ if (value === undefined) {
+ localStorage.removeItem(storageKey());
+ return;
+ }
+ localStorage.setItem(storageKey(), JSON.stringify(value));
+};
+
+const workspaceUsageStorageKey = (
+ workspace = mocks.state.currentUser.workspace
+) =>
+ storageKeyWorkspaceSetupGuideWorkspaceUsage(
+ workspace,
+ mocks.state.currentUser.email
+ );
+
+const seedWorkspaceUsage = (value: unknown) => {
+ if (value === undefined) {
+ localStorage.removeItem(workspaceUsageStorageKey());
+ return;
+ }
+ localStorage.setItem(workspaceUsageStorageKey(), JSON.stringify(value));
+};
+
+describe("workspace setup guide scenario selection", () => {
+ beforeEach(() => {
+ localStorage.clear();
+ mocks.state.currentUser.workspace = "workspaces/ws1";
+ });
+
+ afterEach(() => {
+ vi.restoreAllMocks();
+ });
+
+ test("accepts only registered phase-one scenario ids", () => {
+ expect(isGuideScenarioId("query-data")).toBe(true);
+ expect(isGuideScenarioId("create-database-change")).toBe(true);
+ expect(isGuideScenarioId("learn-bytebase-basics")).toBe(false);
+ expect(isGuideScenarioId("protect-sensitive-data")).toBe(false);
+ expect(isGuideScenarioId(undefined)).toBe(false);
+ });
+
+ test.each([undefined, null, "", "unknown", "learn-bytebase-basics", 42])(
+ "returns no scenario for %j",
+ (value) => {
+ seedStoredValue(value);
+
+ expect(readSelectedGuideScenarioId()).toBeUndefined();
+ }
+ );
+
+ test("falls back to basics when stored JSON is malformed", () => {
+ localStorage.setItem(storageKey(), "{");
+
+ expect(readSelectedGuideScenarioId()).toBeUndefined();
+ });
+
+ test("stores an explicit valid selection", () => {
+ expect(saveSelectedGuideScenarioId("create-database-change")).toBe(true);
+ expect(JSON.parse(localStorage.getItem(storageKey()) ?? "null")).toBe(
+ "create-database-change"
+ );
+ });
+
+ test("clears a previous selection", () => {
+ expect(saveSelectedGuideScenarioId("query-data")).toBe(true);
+
+ expect(clearSelectedGuideScenarioId()).toBe(true);
+ expect(readSelectedGuideScenarioId()).toBeUndefined();
+ });
+
+ test("isolates selections by workspace", () => {
+ expect(saveSelectedGuideScenarioId("query-data")).toBe(true);
+
+ mocks.state.currentUser.workspace = "workspaces/ws2";
+
+ expect(readSelectedGuideScenarioId()).toBeUndefined();
+ expect(localStorage.getItem(storageKey("workspaces/ws1"))).not.toBeNull();
+ });
+
+ test("does not throw when localStorage rejects a write", () => {
+ vi.spyOn(Storage.prototype, "setItem").mockImplementation(() => {
+ throw new DOMException("quota");
+ });
+
+ expect(saveSelectedGuideScenarioId("query-data")).toBe(false);
+ });
+});
+
+describe("workspace setup guide workspace usage", () => {
+ beforeEach(() => {
+ localStorage.clear();
+ mocks.state.currentUser.workspace = "workspaces/ws1";
+ });
+
+ test("accepts only registered workspace usage values", () => {
+ expect(isGuideWorkspaceUsage("team")).toBe(true);
+ expect(isGuideWorkspaceUsage("solo")).toBe(true);
+ expect(isGuideWorkspaceUsage("unknown")).toBe(false);
+ expect(isGuideWorkspaceUsage(undefined)).toBe(false);
+ });
+
+ test.each([undefined, null, "", "unknown", 42])(
+ "returns no workspace usage for %j",
+ (value) => {
+ seedWorkspaceUsage(value);
+ expect(readGuideWorkspaceUsage()).toBeUndefined();
+ }
+ );
+
+ test.each(["team", "solo"] as const)("stores %s workspace usage", (value) => {
+ expect(saveGuideWorkspaceUsage(value)).toBe(true);
+ expect(readGuideWorkspaceUsage()).toBe(value);
+ });
+
+ test("clears a previous workspace usage", () => {
+ expect(saveGuideWorkspaceUsage("team")).toBe(true);
+ expect(clearGuideWorkspaceUsage()).toBe(true);
+ expect(readGuideWorkspaceUsage()).toBeUndefined();
+ });
+});
diff --git a/frontend/src/modules/workspace-setup-guide/selection.ts b/frontend/src/modules/workspace-setup-guide/selection.ts
new file mode 100644
index 0000000000..8f066b2e8b
--- /dev/null
+++ b/frontend/src/modules/workspace-setup-guide/selection.ts
@@ -0,0 +1,95 @@
+import { useAppStore } from "@/stores/app";
+import {
+ getCurrentUserEmail,
+ getWorkspaceResourceScope,
+ readJson,
+ writeJson,
+} from "@/stores/app/utils";
+import {
+ storageKeyWorkspaceSetupGuideScenario,
+ storageKeyWorkspaceSetupGuideWorkspaceUsage,
+} from "@/utils/storage-keys";
+import type { GuideScenarioId, GuideWorkspaceUsage } from "./types";
+
+export const isGuideScenarioId = (value: unknown): value is GuideScenarioId =>
+ value === "query-data" || value === "create-database-change";
+
+export const isGuideWorkspaceUsage = (
+ value: unknown
+): value is GuideWorkspaceUsage => value === "team" || value === "solo";
+
+const selectionStorageKey = () => {
+ const get = useAppStore.getState;
+ const email = getCurrentUserEmail(get);
+ const scope = getWorkspaceResourceScope(get);
+ if (!email || !scope) return undefined;
+ return storageKeyWorkspaceSetupGuideScenario(scope, email);
+};
+
+const workspaceUsageStorageKey = () => {
+ const get = useAppStore.getState;
+ const email = getCurrentUserEmail(get);
+ const scope = getWorkspaceResourceScope(get);
+ if (!email || !scope) return undefined;
+ return storageKeyWorkspaceSetupGuideWorkspaceUsage(scope, email);
+};
+
+export const readSelectedGuideScenarioId = (): GuideScenarioId | undefined => {
+ const key = selectionStorageKey();
+ if (!key) return undefined;
+ const value = readJson<unknown>(key, undefined);
+ return isGuideScenarioId(value) ? value : undefined;
+};
+
+export const saveSelectedGuideScenarioId = (id: GuideScenarioId): boolean => {
+ const key = selectionStorageKey();
+ if (!key) return false;
+ try {
+ writeJson(key, id);
+ return true;
+ } catch {
+ return false;
+ }
+};
+
+export const clearSelectedGuideScenarioId = (): boolean => {
+ const key = selectionStorageKey();
+ if (!key) return false;
+ try {
+ localStorage.removeItem(key);
+ return true;
+ } catch {
+ return false;
+ }
+};
+
+export const readGuideWorkspaceUsage = (): GuideWorkspaceUsage | undefined => {
+ const key = workspaceUsageStorageKey();
+ if (!key) return undefined;
+ const value = readJson<unknown>(key, undefined);
+ return isGuideWorkspaceUsage(value) ? value : undefined;
+};
+
+export const saveGuideWorkspaceUsage = (
+ value: GuideWorkspaceUsage
+): boolean => {
+ const key = workspaceUsageStorageKey();
+ if (!key) return false;
+ try {
+ writeJson(key, value);
+ return true;
+ } catch {
+ return false;
+ }
+};
+
+export const clearGuideWorkspaceUsage = (): boolean => {
+ const key = workspaceUsageStorageKey();
+ if (!key) return false;
+ try {
+ localStorage.removeItem(key);
+ return true;
+ } catch {
+ return false;
+ }
+};
diff --git a/frontend/src/modules/workspace-setup-guide/steps.test.ts b/frontend/src/modules/workspace-setup-guide/steps.test.ts
index 9dd9d42ddf..ef1710bc14 100644
--- a/frontend/src/modules/workspace-setup-guide/steps.test.ts
+++ b/frontend/src/modules/workspace-setup-guide/steps.test.ts
@@ -1,21 +1,22 @@
import { describe, expect, test } from "vitest";
import {
- DATABASE_ROUTE_DASHBOARD,
- INSTANCE_ROUTE_DASHBOARD,
+ PROJECT_V1_ROUTE_DASHBOARD,
PROJECT_V1_ROUTE_DATABASES,
PROJECT_V1_ROUTE_INSTANCES,
+ PROJECT_V1_ROUTE_PLAN_DETAIL,
+ WORKSPACE_ROUTE_MEMBERS,
+ WORKSPACE_ROUTE_USERS,
} from "@/app/router/handles";
import {
CREATE_INSTANCE_PRODUCT_INTRO,
CREATE_PROJECT_PRODUCT_INTRO,
- PREPARE_DATABASE_PRODUCT_INTRO,
- PREPARE_DATABASE_TRANSFER_TIP,
+ CREATE_USER_PRODUCT_INTRO,
+ GRANT_ACCESS_PRODUCT_INTRO,
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";
+import type { GuideContext, GuideStepId } from "./types";
const createContext = (
overrides: Partial<GuideContext> = {}
@@ -23,8 +24,13 @@ const createContext = (
hasProject: false,
hasInstance: false,
hasExploredDatabase: false,
- hasFirstQuery: false,
+ hasRunStatement: false,
+ hasCreatedChangeIssue: false,
+ isSaaS: false,
+ hasOtherHumanUser: false,
+ hasOtherWorkspaceMember: false,
projectName: "",
+ instanceName: "",
databaseProjectName: "",
databaseName: "",
route: { name: "workspace.home", params: {} },
@@ -32,116 +38,119 @@ const createContext = (
});
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("contains only reusable resource and customer-action definitions", () => {
+ expect(Object.keys(GUIDE_STEP_REGISTRY)).toEqual([
+ "create-project",
+ "connect-instance",
+ "explore-database",
+ "query-data",
+ "create-database-change",
+ "create-user",
+ "grant-access",
]);
});
- 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 },
- },
+ test.each([
+ ["create-project", { hasProject: true }],
+ ["connect-instance", { hasInstance: true }],
+ [
+ "explore-database",
+ {
+ hasExploredDatabase: true,
+ databaseProjectName: "projects/app",
+ databaseName: "instances/sample/databases/employee",
},
- });
+ ],
+ ["query-data", { hasRunStatement: true }],
+ ["create-database-change", { hasCreatedChangeIssue: true }],
+ ["create-user", { hasOtherWorkspaceMember: true }],
+ ["grant-access", { hasOtherWorkspaceMember: true }],
+ ] as const)("uses observable evidence for %s", (stepId, completed) => {
expect(
- GUIDE_STEP_REGISTRY["create-project"].resolveActions(
- createContext({ hasProject: true })
- )
- ).toEqual({});
+ GUIDE_STEP_REGISTRY[stepId].isComplete(createContext(completed))
+ ).toBe(true);
});
- test("routes instance connection through the project when available", () => {
+ test("keeps database exploration incomplete without a concrete target", () => {
expect(
- GUIDE_STEP_REGISTRY["connect-instance"].resolveActions(
- createContext({ projectName: "projects/app" })
+ GUIDE_STEP_REGISTRY["explore-database"].isComplete(
+ createContext({ hasExploredDatabase: true })
)
- ).toEqual({
- select: {
- type: "navigate",
- target: {
- name: PROJECT_V1_ROUTE_INSTANCES,
- params: { projectId: "app" },
- query: { [PRODUCT_INTRO_QUERY_KEY]: CREATE_INSTANCE_PRODUCT_INTRO },
+ ).toBe(false);
+ });
+
+ test.each([createContext(), createContext({ projectName: "projects/app" })])(
+ "always opens the workspace project list with the create highlight",
+ (context) => {
+ expect(
+ GUIDE_STEP_REGISTRY["create-project"].resolveActions(context)
+ ).toEqual({
+ select: {
+ type: "navigate",
+ target: {
+ name: PROJECT_V1_ROUTE_DASHBOARD,
+ query: {
+ [PRODUCT_INTRO_QUERY_KEY]: CREATE_PROJECT_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.each([
+ createContext({ projectName: "projects/app" }),
+ createContext({
+ projectName: "projects/app",
+ instanceName: "instances/prod",
+ }),
+ ])(
+ "always opens the project instance list with the create highlight",
+ (context) => {
+ expect(
+ GUIDE_STEP_REGISTRY["connect-instance"].resolveActions(context)
+ ).toEqual({
+ select: {
+ type: "navigate",
+ target: {
+ name: PROJECT_V1_ROUTE_INSTANCES,
+ params: { projectId: "app" },
+ query: {
+ [PRODUCT_INTRO_QUERY_KEY]: CREATE_INSTANCE_PRODUCT_INTRO,
+ },
+ },
},
- },
- });
- });
+ });
+ }
+ );
- test("routes database preparation with transfer guidance", () => {
+ test("keeps the connect action fixed while its project dependency is blocked", () => {
expect(
- GUIDE_STEP_REGISTRY["explore-database"].resolveActions(createContext())
+ GUIDE_STEP_REGISTRY["connect-instance"].resolveActions(createContext())
).toEqual({
select: {
type: "navigate",
target: {
- name: DATABASE_ROUTE_DASHBOARD,
+ name: PROJECT_V1_ROUTE_INSTANCES,
+ params: { projectId: "" },
query: {
- [PRODUCT_INTRO_QUERY_KEY]: PREPARE_DATABASE_PRODUCT_INTRO,
- [PRODUCT_INTRO_TIP_QUERY_KEY]: PREPARE_DATABASE_TRANSFER_TIP,
+ [PRODUCT_INTRO_QUERY_KEY]: CREATE_INSTANCE_PRODUCT_INTRO,
},
},
},
});
});
- test("routes an existing project database with synced guidance", () => {
+ test.each([
+ createContext({ projectName: "projects/app" }),
+ createContext({
+ projectName: "projects/app",
+ databaseProjectName: "projects/other",
+ databaseName: "instances/sample/databases/employee",
+ }),
+ ])("always opens the project database page with its highlight", (context) => {
expect(
- GUIDE_STEP_REGISTRY["explore-database"].resolveActions(
- createContext({
- databaseProjectName: "projects/app",
- databaseName: "instances/sample/databases/employee",
- })
- )
+ GUIDE_STEP_REGISTRY["explore-database"].resolveActions(context)
).toEqual({
select: {
type: "navigate",
@@ -156,59 +165,102 @@ describe("GUIDE_STEP_REGISTRY", () => {
});
});
- 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",
+ test.each([false, true])(
+ "always queries the discovered database when completion is %s",
+ (hasRunStatement) => {
+ expect(
+ GUIDE_STEP_REGISTRY["query-data"].resolveActions(
+ createContext({
+ hasRunStatement,
+ databaseName: "instances/sample/databases/employee",
+ databaseProjectName: "projects/app",
+ })
+ )
+ ).toEqual({
+ primary: {
+ type: "open-sql-editor",
+ database: {
+ name: "instances/sample/databases/employee",
+ project: "projects/app",
+ },
+ },
+ });
+ }
+ );
+
+ test.each([false, true])(
+ "always starts a database change when completion is %s",
+ (hasCreatedChangeIssue) => {
+ expect(
+ GUIDE_STEP_REGISTRY["create-database-change"].resolveActions(
+ createContext({
+ hasCreatedChangeIssue,
+ databaseName: "instances/sample/databases/employee",
+ databaseProjectName: "projects/app",
+ })
+ )
+ ).toEqual({
+ select: {
+ type: "create-change",
project: "projects/app",
+ database: "instances/sample/databases/employee",
},
- },
- 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([createContext(), createContext({ isSaaS: true })])(
+ "always opens Users for the self-host teammate step",
+ (context) => {
+ expect(
+ GUIDE_STEP_REGISTRY["create-user"].resolveActions(context)
+ ).toEqual({
+ select: {
+ type: "navigate",
+ target: {
+ name: WORKSPACE_ROUTE_USERS,
+ query: {
+ [PRODUCT_INTRO_QUERY_KEY]: CREATE_USER_PRODUCT_INTRO,
+ },
+ },
+ },
+ });
+ }
+ );
- 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([createContext(), createContext({ hasOtherHumanUser: true })])(
+ "always opens Members for the SaaS teammate step",
+ (context) => {
+ expect(
+ GUIDE_STEP_REGISTRY["grant-access"].resolveActions(context)
+ ).toEqual({
+ select: {
+ type: "navigate",
+ target: {
+ name: WORKSPACE_ROUTE_MEMBERS,
+ query: {
+ [PRODUCT_INTRO_QUERY_KEY]: GRANT_ACCESS_PRODUCT_INTRO,
+ },
+ },
+ },
+ });
+ }
+ );
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],
+ ["create-project", PROJECT_V1_ROUTE_DASHBOARD, true],
+ ["connect-instance", PROJECT_V1_ROUTE_INSTANCES, true],
+ ["explore-database", "workspace.project.database.detail", 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
- );
+ ["create-database-change", PROJECT_V1_ROUTE_PLAN_DETAIL, true],
+ ["create-user", WORKSPACE_ROUTE_USERS, true],
+ ["grant-access", WORKSPACE_ROUTE_MEMBERS, true],
+ ] as const)("matches %s on %s", (stepId, name, expected) => {
+ expect(
+ GUIDE_STEP_REGISTRY[stepId as GuideStepId].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
index e975496af8..b29d9057b9 100644
--- a/frontend/src/modules/workspace-setup-guide/steps.ts
+++ b/frontend/src/modules/workspace-setup-guide/steps.ts
@@ -1,145 +1,175 @@
import {
- DATABASE_ROUTE_DASHBOARD,
- INSTANCE_ROUTE_DASHBOARD,
- INSTANCE_ROUTE_DATABASE_DETAIL,
PROJECT_V1_ROUTE_DASHBOARD,
PROJECT_V1_ROUTE_DATABASES,
PROJECT_V1_ROUTE_INSTANCES,
+ PROJECT_V1_ROUTE_PLAN_DETAIL,
SQL_EDITOR_DATABASE_MODULE,
+ WORKSPACE_ROUTE_MEMBERS,
+ WORKSPACE_ROUTE_USERS,
} from "@/app/router/handles";
import {
CREATE_INSTANCE_PRODUCT_INTRO,
CREATE_PROJECT_PRODUCT_INTRO,
- PREPARE_DATABASE_PRODUCT_INTRO,
- PREPARE_DATABASE_TRANSFER_TIP,
+ CREATE_USER_PRODUCT_INTRO,
+ GRANT_ACCESS_PRODUCT_INTRO,
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";
+import type {
+ GuideContext,
+ GuideStepActions,
+ GuideStepRegistry,
+} from "./types";
const isRouteInside = (name: string | undefined, parent: string) =>
name === parent || !!name?.startsWith(`${parent}.`);
+const connectInstanceActions = (context: GuideContext): GuideStepActions => {
+ return {
+ select: {
+ type: "navigate",
+ target: {
+ name: PROJECT_V1_ROUTE_INSTANCES,
+ params: {
+ projectId: extractProjectResourceName(context.projectName),
+ },
+ query: {
+ [PRODUCT_INTRO_QUERY_KEY]: CREATE_INSTANCE_PRODUCT_INTRO,
+ },
+ },
+ },
+ };
+};
+
+const databaseActions = (context: GuideContext): GuideStepActions => ({
+ select: {
+ type: "navigate",
+ target: {
+ name: PROJECT_V1_ROUTE_DATABASES,
+ params: {
+ projectId: extractProjectResourceName(context.projectName),
+ },
+ query: {
+ [PRODUCT_INTRO_QUERY_KEY]: PROJECT_INSTANCE_SYNCED_PRODUCT_INTRO,
+ },
+ },
+ },
+});
+
export const GUIDE_STEP_REGISTRY: GuideStepRegistry = {
"create-project": {
id: "create-project",
- analyticsKey: "hasProject",
+ analyticsKey: "create-project",
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,
- },
- },
- },
+ resolveActions: () => ({
+ 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",
+ analyticsKey: "connect-instance",
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,
- },
- },
- },
- };
- },
+ resolveActions: connectInstanceActions,
},
"explore-database": {
id: "explore-database",
- analyticsKey: "hasExploredDatabase",
+ analyticsKey: "explore-database",
labelKey: "workspace-setup-guide.steps.database",
descriptionKey: "workspace-setup-guide.descriptions.database",
- isComplete: (context) => context.hasExploredDatabase,
+ isComplete: (context) =>
+ context.hasExploredDatabase &&
+ !!context.databaseProjectName &&
+ !!context.databaseName,
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,
- },
- },
- },
- }),
+ isRouteInside(route.name, PROJECT_V1_ROUTE_DATABASES),
+ resolveActions: databaseActions,
},
"query-data": {
id: "query-data",
- analyticsKey: "hasFirstQuery",
- labelKey: "workspace-setup-guide.steps.query",
- descriptionKey: "workspace-setup-guide.descriptions.sql-editor",
- isComplete: (context) => context.hasFirstQuery,
+ analyticsKey: "query-data",
+ labelKey: "workspace-setup-guide.steps.query-data",
+ descriptionKey: "workspace-setup-guide.descriptions.query-data",
+ isComplete: (context) => context.hasRunStatement,
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,
+ resolveActions: (context) => ({
+ primary: {
+ type: "open-sql-editor",
+ database: {
+ name: context.databaseName,
+ project: context.databaseProjectName,
+ },
+ },
+ }),
+ },
+ "create-database-change": {
+ id: "create-database-change",
+ analyticsKey: "create-database-change",
+ labelKey: "workspace-setup-guide.steps.create-database-change",
+ descriptionKey: "workspace-setup-guide.descriptions.create-database-change",
+ isComplete: (context) => context.hasCreatedChangeIssue,
+ matchesRoute: (route) =>
+ isRouteInside(route.name, PROJECT_V1_ROUTE_PLAN_DETAIL),
+ resolveActions: (context) => ({
+ select: {
+ type: "create-change",
+ project: context.databaseProjectName,
+ database: context.databaseName,
+ },
+ }),
+ },
+ "create-user": {
+ id: "create-user",
+ analyticsKey: "add-teammate",
+ labelKey: "workspace-setup-guide.steps.add-teammate",
+ descriptionKey: "workspace-setup-guide.descriptions.add-teammate",
+ isComplete: (context) => context.hasOtherWorkspaceMember,
+ matchesRoute: (route) => isRouteInside(route.name, WORKSPACE_ROUTE_USERS),
+ resolveActions: () => ({
+ select: {
+ type: "navigate",
+ target: {
+ name: WORKSPACE_ROUTE_USERS,
+ query: {
+ [PRODUCT_INTRO_QUERY_KEY]: CREATE_USER_PRODUCT_INTRO,
},
},
- secondary: {
- type: "create-change",
- project: context.databaseProjectName,
- database: context.databaseName,
+ },
+ }),
+ },
+ "grant-access": {
+ id: "grant-access",
+ analyticsKey: "add-teammate",
+ labelKey: "workspace-setup-guide.steps.add-teammate",
+ descriptionKey: "workspace-setup-guide.descriptions.add-teammate",
+ isComplete: (context) => context.hasOtherWorkspaceMember,
+ matchesRoute: (route) => isRouteInside(route.name, WORKSPACE_ROUTE_MEMBERS),
+ resolveActions: () => ({
+ select: {
+ type: "navigate",
+ target: {
+ name: WORKSPACE_ROUTE_MEMBERS,
+ query: {
+ [PRODUCT_INTRO_QUERY_KEY]: GRANT_ACCESS_PRODUCT_INTRO,
+ },
},
- };
- },
+ },
+ }),
},
};
diff --git a/frontend/src/modules/workspace-setup-guide/types.ts b/frontend/src/modules/workspace-setup-guide/types.ts
index f5ae42d2fc..80a043586c 100644
--- a/frontend/src/modules/workspace-setup-guide/types.ts
+++ b/frontend/src/modules/workspace-setup-guide/types.ts
@@ -4,15 +4,20 @@ export type GuideStepId =
| "create-project"
| "connect-instance"
| "explore-database"
- | "query-data";
+ | "query-data"
+ | "create-database-change"
+ | "create-user"
+ | "grant-access";
-export type GuideScenarioId = "learn-bytebase-basics";
+export type GuideScenarioId = "query-data" | "create-database-change";
+
+export type GuideWorkspaceUsage = "team" | "solo";
+
+export type GuideJourneyId = "workspace-setup" | GuideScenarioId;
export type GuideAnalyticsKey =
- | "hasProject"
- | "hasInstance"
- | "hasExploredDatabase"
- | "hasFirstQuery";
+ | Exclude<GuideStepId, "create-user" | "grant-access">
+ | "add-teammate";
export type GuideRoute = Pick<ReactRoute, "name" | "params">;
@@ -20,8 +25,13 @@ export type GuideContext = {
hasProject: boolean;
hasInstance: boolean;
hasExploredDatabase: boolean;
- hasFirstQuery: boolean;
+ hasRunStatement: boolean;
+ hasCreatedChangeIssue: boolean;
+ isSaaS: boolean;
+ hasOtherHumanUser: boolean;
+ hasOtherWorkspaceMember: boolean;
projectName: string;
+ instanceName: string;
databaseProjectName: string;
databaseName: string;
route: GuideRoute;
@@ -61,18 +71,25 @@ export type GuideStepRegistry = Readonly<
Record<GuideStepId, GuideStepDefinition>
>;
-export type ScenarioStep = {
+export type GuideJourneyStep = {
stepId: GuideStepId;
+ kind?: "prerequisite" | "learning" | "modifier";
dependsOn?: readonly GuideStepId[];
};
-export type GuideScenario = {
- id: GuideScenarioId;
- steps: readonly ScenarioStep[];
+export type GuideCompletionActionId = "open-sql-editor" | "create-change";
+
+export type GuideJourney = {
+ id: GuideJourneyId;
+ scenarioId?: GuideScenarioId;
+ completionTitleKey: string;
+ completionDescriptionKey: string;
+ completionActions: readonly GuideCompletionActionId[];
+ steps: readonly GuideJourneyStep[];
};
export type ResolvedGuideStep = {
- scenarioStep: ScenarioStep;
+ journeyStep: GuideJourneyStep;
definition: GuideStepDefinition;
done: boolean;
blocked: boolean;
@@ -81,7 +98,8 @@ export type ResolvedGuideStep = {
export type ResolvedGuide = {
steps: ResolvedGuideStep[];
- activeStep: ResolvedGuideStep;
+ complete: boolean;
+ activeStep: ResolvedGuideStep | undefined;
highlightedStep: ResolvedGuideStep | undefined;
- actionStep: ResolvedGuideStep;
+ actionStep: ResolvedGuideStep | undefined;
};
diff --git a/frontend/src/modules/workspace-setup-guide/useGuideContext.test.tsx b/frontend/src/modules/workspace-setup-guide/useGuideContext.test.tsx
index 73f0f8d7ac..f135c147cb 100644
--- a/frontend/src/modules/workspace-setup-guide/useGuideContext.test.tsx
+++ b/frontend/src/modules/workspace-setup-guide/useGuideContext.test.tsx
@@ -1,27 +1,47 @@
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_DATABASES,
PROJECT_V1_ROUTE_DATABASE_DETAIL,
SQL_EDITOR_DATABASE_MODULE,
} from "@/app/router/handles";
+import { planEvents } from "@/lib/plan/events";
import { sqlEditorEvents } from "@/modules/sql-editor/model/events";
-import { State } from "@/types/proto-es/v1/common_pb";
-import type { GuideRoute } from "./types";
+import { GUIDE_PROGRESS_KEYS } from "./progress";
+import type {
+ GuideRoute,
+ GuideScenarioId,
+ GuideWorkspaceUsage,
+} from "./types";
const mocks = vi.hoisted(() => ({
projectsByName: {} as Record<string, unknown>,
instancesByName: {} as Record<string, unknown>,
databasesByName: {} as Record<string, unknown>,
+ usersByName: {} as Record<string, unknown>,
fetchProjectList: vi.fn(),
fetchInstanceList: vi.fn(),
fetchDatabases: vi.fn(),
+ listUsers: vi.fn(),
introState: {} as Record<string, boolean>,
saveIntroStateByKey: vi.fn(),
- searchQueryHistories: vi.fn(),
+ captureMetric: vi.fn(),
workspaceResourceName: "workspaces/default",
defaultProject: "projects/default",
+ currentUserName: "users/[email protected]",
+ isSaaS: false,
+ workspacePolicy: {
+ bindings: [
+ {
+ role: "roles/workspaceAdmin",
+ members: ["users/[email protected]"],
+ },
+ ],
+ },
+}));
+
+vi.mock("@/app/analytics/provider", () => ({
+ behaviorAnalytics: { captureMetric: mocks.captureMetric },
}));
vi.mock("@/hooks/useAppState", () => ({
@@ -34,7 +54,11 @@ vi.mock("@/stores/app", () => {
projectsByName: mocks.projectsByName,
instancesByName: mocks.instancesByName,
databasesByName: mocks.databasesByName,
+ usersByName: mocks.usersByName,
workspaceResourceName: () => mocks.workspaceResourceName,
+ currentUserName: mocks.currentUserName,
+ workspacePolicy: mocks.workspacePolicy,
+ isSaaSMode: () => mocks.isSaaS,
});
const useAppStore = Object.assign(
(selector: (value: ReturnType<typeof state>) => unknown) =>
@@ -45,6 +69,7 @@ vi.mock("@/stores/app", () => {
fetchProjectList: mocks.fetchProjectList,
fetchInstanceList: mocks.fetchInstanceList,
fetchDatabases: mocks.fetchDatabases,
+ listUsers: mocks.listUsers,
getIntroStateByKey: (key: string) => mocks.introState[key] ?? false,
saveIntroStateByKey: mocks.saveIntroStateByKey,
}),
@@ -53,25 +78,26 @@ vi.mock("@/stores/app", () => {
return { useAppStore };
});
-vi.mock("@/api", () => ({
- queryHistoryServiceClientConnect: {
- searchQueryHistories: mocks.searchQueryHistories,
- },
-}));
-
-import { useGuideContext } from "./useGuideContext";
+import {
+ hasOtherHumanWorkspaceMember,
+ 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 home: 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 });
+ scenarioId?: GuideScenarioId;
+ workspaceUsage?: GuideWorkspaceUsage;
+ } = {
+ enabled: true,
+ dismissed: false,
+ route: home,
+ }
+) => renderHook((value) => useGuideContext(value), { initialProps: props });
describe("useGuideContext", () => {
beforeEach(() => {
@@ -80,51 +106,42 @@ describe("useGuideContext", () => {
mocks.projectsByName = {};
mocks.instancesByName = {};
mocks.databasesByName = {};
- mocks.defaultProject = "projects/default";
- mocks.workspaceResourceName = "workspaces/default";
+ mocks.usersByName = {};
mocks.fetchProjectList.mockResolvedValue({ projects: [], nextPageToken: "" });
mocks.fetchInstanceList.mockResolvedValue({
instances: [],
nextPageToken: "",
});
mocks.fetchDatabases.mockResolvedValue({ databases: [], nextPageToken: "" });
+ mocks.listUsers.mockResolvedValue({ users: [], nextPageToken: "" });
+ mocks.currentUserName = "users/[email protected]";
+ mocks.isSaaS = false;
+ mocks.workspacePolicy = {
+ bindings: [
+ {
+ role: "roles/workspaceAdmin",
+ members: ["users/[email protected]"],
+ },
+ ],
+ };
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 () => {
+ test("separates discovered resources from learning evidence", async () => {
mocks.fetchProjectList.mockResolvedValue({
projects: [{ name: "projects/app" }],
nextPageToken: "",
});
- mocks.fetchInstanceList.mockImplementation(async ({ parent } = {}) => ({
- instances:
- parent === "projects/app"
- ? [{ name: "projects/app/instances/sample" }]
- : [],
+ mocks.fetchInstanceList.mockResolvedValue({
+ instances: [{ name: "instances/sample" }],
nextPageToken: "",
- }));
+ });
mocks.fetchDatabases.mockResolvedValue({
databases: [
{
- name: "projects/app/instances/sample/databases/employee",
+ name: "instances/sample/databases/employee",
project: "projects/app",
},
],
@@ -137,495 +154,326 @@ describe("useGuideContext", () => {
expect(result.current.context).toMatchObject({
hasProject: true,
hasInstance: true,
+ hasExploredDatabase: false,
+ hasCreatedChangeIssue: false,
projectName: "projects/app",
- databaseProjectName: "projects/app",
- databaseName: "projects/app/instances/sample/databases/employee",
+ instanceName: "instances/sample",
+ databaseName: "instances/sample/databases/employee",
});
+ expect(mocks.captureMetric).not.toHaveBeenCalled();
});
- 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));
+ test.each([
+ ])("accepts another explicit human principal: %s", (member) => {
+ expect(
+ hasOtherHumanWorkspaceMember(
+ { bindings: [{ role: "roles/workspaceMember", members: [member] }] },
+ )
+ ).toBe(true);
+ });
- expect(result.current.context).toMatchObject({
- projectName: "projects/project-a",
- databaseProjectName: "projects/default",
- databaseName: "instances/sample/databases/employee",
- });
+ test.each([
+ "allUsers",
+ "user:allUsers",
+ "users/allUsers",
+ "serviceAccount:[email protected]",
+ "workloadIdentity:[email protected]",
+ ])("rejects a non-teammate principal: %s", (member) => {
+ expect(
+ hasOtherHumanWorkspaceMember(
+ { bindings: [{ role: "roles/workspaceMember", members: [member] }] },
+ )
+ ).toBe(false);
});
- test("counts workspace-owned instances as project and instance readiness", async () => {
- mocks.fetchProjectList.mockResolvedValue({
- projects: [{ name: "projects/project-sample" }],
+ test("lists active users only for a self-host team journey", async () => {
+ mocks.listUsers.mockResolvedValue({
+ users: [
+ { name: "users/[email protected]" },
+ { name: "users/[email protected]" },
+ ],
nextPageToken: "",
});
- mocks.fetchInstanceList.mockResolvedValue({
- instances: [{ name: "instances/sample" }],
- nextPageToken: "",
+ const { result } = renderGuideContext({
+ enabled: true,
+ dismissed: false,
+ route: home,
+ scenarioId: "query-data",
+ workspaceUsage: "team",
});
- const { result } = renderGuideContext();
await waitFor(() => expect(result.current.loading).toBe(false));
+ expect(mocks.listUsers).toHaveBeenCalledWith({
+ pageSize: 100,
+ filter: { state: 1 },
+ });
expect(result.current.context).toMatchObject({
- hasProject: true,
- hasInstance: true,
+ isSaaS: false,
+ hasOtherHumanUser: true,
+ hasOtherWorkspaceMember: false,
});
});
- test("counts project-owned instances as project and instance readiness", async () => {
- mocks.fetchProjectList.mockResolvedValue({
- projects: [{ name: "projects/app" }],
- nextPageToken: "",
+ test.each([
+ { isSaaS: true, workspaceUsage: "team" as const },
+ { isSaaS: false, workspaceUsage: "solo" as const },
+ { isSaaS: false, workspaceUsage: undefined },
+ ])("does not list users outside a self-host team journey: %j", async (input) => {
+ mocks.isSaaS = input.isSaaS;
+ const { result } = renderGuideContext({
+ enabled: true,
+ dismissed: false,
+ route: home,
+ workspaceUsage: input.workspaceUsage,
});
- 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,
- });
+ expect(mocks.listUsers).not.toHaveBeenCalled();
});
- 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: [
+ test("uses workspace IAM as teammate completion authority", async () => {
+ mocks.workspacePolicy = {
+ bindings: [
{
- name: "instances/sample/databases/employee",
- project: "projects/project-sample",
+ role: "roles/workspaceMember",
+ members: ["user:[email protected]"],
},
],
- nextPageToken: "database-page-2",
+ };
+ const { result } = renderGuideContext({
+ enabled: true,
+ dismissed: false,
+ route: home,
+ workspaceUsage: "team",
});
- 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" },
+ expect(result.current.context.hasOtherWorkspaceMember).toBe(true);
+ expect(mocks.saveIntroStateByKey).toHaveBeenCalledWith({
+ key: GUIDE_PROGRESS_KEYS.teammateAdded,
+ newState: true,
});
+ expect(mocks.captureMetric).not.toHaveBeenCalled();
});
test.each([
{
- name: PROJECT_V1_ROUTE_DATABASE_DETAIL,
- params: {
- projectId: "project-sample",
- instanceId: "sample-one",
- databaseName: "employee",
+ route: {
+ name: PROJECT_V1_ROUTE_DATABASE_DETAIL,
+ params: {
+ projectId: "app",
+ instanceId: "sample",
+ 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",
+ route: {
+ name: SQL_EDITOR_DATABASE_MODULE,
+ params: { project: "app", instance: "sample", database: "employee" },
},
},
- ])("marks a concrete database route as explored: $name", async (route) => {
- renderGuideContext({ enabled: true, dismissed: false, route });
+ ])("records concrete database route evidence", async ({ route }) => {
+ renderGuideContext({
+ enabled: true,
+ dismissed: false,
+ route,
+ });
await waitFor(() =>
expect(mocks.saveIntroStateByKey).toHaveBeenCalledWith({
- key: databaseExploredKey,
+ key: GUIDE_PROGRESS_KEYS.databaseExplored,
newState: true,
})
);
+ expect(mocks.captureMetric).not.toHaveBeenCalled();
});
- 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) => {
+ test("records a populated project database page as exploration", async () => {
+ mocks.fetchProjectList.mockResolvedValue({
+ projects: [{ name: "projects/app" }],
+ nextPageToken: "",
+ });
+ mocks.fetchInstanceList.mockResolvedValue({
+ instances: [{ name: "instances/sample" }],
+ nextPageToken: "",
+ });
+ mocks.fetchDatabases.mockResolvedValue({
+ databases: [
+ {
+ name: "instances/sample/databases/employee",
+ project: "projects/app",
+ },
+ ],
+ nextPageToken: "",
+ });
const { result } = renderGuideContext({
enabled: true,
dismissed: false,
- route,
+ route: {
+ name: PROJECT_V1_ROUTE_DATABASES,
+ params: { projectId: "app" },
+ },
});
- await waitFor(() => expect(result.current.loading).toBe(false));
-
- expect(mocks.saveIntroStateByKey).not.toHaveBeenCalledWith({
- key: databaseExploredKey,
+ await waitFor(() =>
+ expect(result.current.context.hasExploredDatabase).toBe(true)
+ );
+ expect(mocks.saveIntroStateByKey).toHaveBeenCalledWith({
+ key: GUIDE_PROGRESS_KEYS.databaseExplored,
newState: true,
});
- expect(result.current.context.hasExploredDatabase).toBe(false);
});
- test("does not count the workspace database list as exploration", async () => {
+ test("does not record an empty project database page as exploration", async () => {
const { result } = renderGuideContext({
enabled: true,
dismissed: false,
- route: { name: DATABASE_ROUTE_DASHBOARD, params: {} },
+ route: {
+ name: PROJECT_V1_ROUTE_DATABASES,
+ params: { projectId: "app" },
+ },
});
await waitFor(() => expect(result.current.loading).toBe(false));
-
+ expect(result.current.context.hasExploredDatabase).toBe(false);
expect(mocks.saveIntroStateByKey).not.toHaveBeenCalledWith({
- key: databaseExploredKey,
+ key: GUIDE_PROGRESS_KEYS.databaseExplored,
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();
-
+ test("completes Query Data after any statement execution", async () => {
+ const { result } = renderGuideContext({
+ enabled: true,
+ dismissed: false,
+ route: home,
+ scenarioId: "query-data",
+ });
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",
+ database: "instances/sample/databases/employee",
project: "projects/app",
});
});
expect(mocks.saveIntroStateByKey).toHaveBeenCalledWith({
- key: databaseExploredKey,
- newState: true,
- });
- expect(mocks.saveIntroStateByKey).toHaveBeenCalledWith({
- key: queryExecutedKey,
+ key: GUIDE_PROGRESS_KEYS.statementRun,
newState: true,
});
expect(result.current.context).toMatchObject({
- hasExploredDatabase: true,
- hasFirstQuery: true,
+ hasRunStatement: true,
databaseProjectName: "projects/app",
- databaseName: "projects/app/instances/sample/databases/employee",
+ databaseName: "instances/sample/databases/employee",
});
+ expect(mocks.captureMetric).not.toHaveBeenCalled();
});
- 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: "",
- });
+ test("records a newly created database-change issue", async () => {
+ const { result } = renderGuideContext({
+ enabled: true,
+ dismissed: false,
+ route: home,
+ scenarioId: "create-database-change",
});
- await waitFor(() =>
- expect(result.current.context).toMatchObject({
- hasExploredDatabase: true,
- hasFirstQuery: true,
- databaseProjectName: "projects/event-project",
- databaseName: "instances/event-instance/databases/event-db",
- })
- );
+ await waitFor(() => expect(result.current.loading).toBe(false));
await act(async () => {
- resolveSecondScan?.({
- projects: [{ name: "projects/discovered-project" }],
- nextPageToken: "",
+ await planEvents.emit("database-change-issue-created", {
+ issue: "projects/app/issues/1",
+ project: "projects/app",
});
});
- 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.saveIntroStateByKey).toHaveBeenCalledWith({
+ key: GUIDE_PROGRESS_KEYS.changeIssueCreated,
+ newState: true,
});
- expect(mocks.searchQueryHistories).not.toHaveBeenCalled();
+ expect(result.current.context.hasCreatedChangeIssue).toBe(true);
+ expect(mocks.captureMetric).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 });
+ test.each([undefined, "query-data" as const])(
+ "does not record a change issue for scenario %s",
+ async (scenarioId) => {
+ renderGuideContext({
+ enabled: true,
+ dismissed: false,
+ route: home,
+ scenarioId,
+ });
- await waitFor(() =>
- expect(result.current.context.databaseName).toBe(
- "instances/instance-a/databases/db-a"
- )
- );
- });
+ await act(async () => {
+ await planEvents.emit("database-change-issue-created", {
+ issue: "projects/app/issues/1",
+ project: "projects/app",
+ });
+ });
- 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();
+ expect(mocks.saveIntroStateByKey).not.toHaveBeenCalledWith({
+ key: GUIDE_PROGRESS_KEYS.changeIssueCreated,
+ newState: true,
+ });
+ }
+ );
- 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({
+ test("keeps self-host user evidence false when listing users fails", async () => {
+ mocks.listUsers.mockRejectedValue(new Error("unavailable"));
+ const { result } = renderGuideContext({
enabled: true,
dismissed: false,
- route: { name: "workspace.member", params: {} },
+ route: home,
+ workspaceUsage: "team",
});
- await waitFor(() =>
- expect(result.current.context.databaseName).toBe(
- "instances/instance-a/databases/db-a"
- )
- );
+ await waitFor(() => expect(result.current.loading).toBe(false));
+ expect(result.current.context.hasOtherHumanUser).toBe(false);
});
- test("keeps the guide visible while progress is refreshing", async () => {
- mocks.fetchProjectList.mockResolvedValue({
- projects: [{ name: "projects/project-a" }],
- nextPageToken: "",
- });
- const { result, rerender } = renderGuideContext();
-
+ test("ignores statement events without a database", async () => {
+ const { result } = 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: "",
+ await act(async () => {
+ await sqlEditorEvents.emit("query-executed", {
+ database: "",
+ project: "projects/app",
+ });
});
- 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);
+ expect(result.current.context.hasRunStatement).toBe(false);
});
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();
+ ])(
+ "does not record while disabled or dismissed: $enabled/$dismissed",
+ async (state) => {
+ renderGuideContext({
+ ...state,
+ route: home,
+ scenarioId: "query-data",
+ });
- await waitFor(() => expect(result.current.context.hasProject).toBe(true));
- rerender({ enabled, dismissed, route });
+ await act(async () => {
+ await sqlEditorEvents.emit("query-executed", {
+ database: "instances/sample/databases/employee",
+ project: "projects/app",
+ });
+ });
- await waitFor(() => expect(result.current.loading).toBe(false));
- expect(result.current.context).toMatchObject({
- hasProject: false,
- hasInstance: false,
- hasExploredDatabase: false,
- hasFirstQuery: false,
- projectName: "",
- databaseProjectName: "",
- databaseName: "",
- });
- });
+ expect(mocks.saveIntroStateByKey).not.toHaveBeenCalled();
+ }
+ );
});
diff --git a/frontend/src/modules/workspace-setup-guide/useGuideContext.ts b/frontend/src/modules/workspace-setup-guide/useGuideContext.ts
index a877c3bbb5..0bcd9f3ac9 100644
--- a/frontend/src/modules/workspace-setup-guide/useGuideContext.ts
+++ b/frontend/src/modules/workspace-setup-guide/useGuideContext.ts
@@ -2,29 +2,66 @@ import { useEffect, useMemo, useRef, useState } from "react";
import {
INSTANCE_ROUTE_DATABASE_DETAIL,
PROJECT_V1_ROUTE_DATABASE_DETAIL,
+ PROJECT_V1_ROUTE_DATABASES,
SQL_EDITOR_DATABASE_MODULE,
} from "@/app/router/handles";
import { useIntroStateByKey } from "@/hooks/useAppState";
+import { planEvents } from "@/lib/plan/events";
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";
+import { convertMemberToFullname } from "@/utils/v1/iam";
+import { extractProjectResourceName } from "@/utils/v1/project";
+import { GUIDE_PROGRESS_KEYS } from "./progress";
+import type {
+ GuideContext,
+ GuideRoute,
+ GuideScenarioId,
+ GuideWorkspaceUsage,
+} 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">;
+type GuideFacts = Omit<
+ GuideContext,
+ "route" | "isSaaS" | "hasOtherWorkspaceMember"
+>;
const INITIAL_FACTS: GuideFacts = {
hasProject: false,
hasInstance: false,
hasExploredDatabase: false,
- hasFirstQuery: false,
+ hasRunStatement: false,
+ hasCreatedChangeIssue: false,
+ hasOtherHumanUser: false,
projectName: "",
+ instanceName: "",
databaseProjectName: "",
databaseName: "",
};
+export const hasOtherHumanWorkspaceMember = (
+ policy:
+ | {
+ bindings: readonly {
+ members: readonly string[];
+ role?: string;
+ }[];
+ }
+ | undefined,
+ currentUserName: string
+) => {
+ if (!currentUserName) return false;
+ return (policy?.bindings ?? []).some((binding) =>
+ binding.members.some((member) => {
+ const name = convertMemberToFullname(member);
+ return (
+ name.startsWith("users/") &&
+ name !== "users/allUsers" &&
+ name !== currentUserName
+ );
+ })
+ );
+};
+
const hasRouteParams = (
params: Record<string, string | string[] | undefined>,
keys: string[]
@@ -54,17 +91,36 @@ const isConcreteDatabaseRoute = (
}
};
+const isPopulatedProjectDatabaseRoute = (
+ name: string | undefined,
+ params: Record<string, string | string[] | undefined>,
+ databaseProjectName: string,
+ databaseName: string
+) =>
+ name === PROJECT_V1_ROUTE_DATABASES &&
+ !!databaseName &&
+ params.projectId === extractProjectResourceName(databaseProjectName);
+
export const useGuideContext = ({
enabled,
dismissed,
route,
+ scenarioId,
+ workspaceUsage,
}: {
enabled: boolean;
dismissed: boolean;
route: GuideRoute;
+ scenarioId?: GuideScenarioId;
+ workspaceUsage?: GuideWorkspaceUsage;
}): { context: GuideContext; loading: boolean } => {
- const databaseExplored = useIntroStateByKey(DATABASE_EXPLORED_KEY);
- const queryExecuted = useIntroStateByKey(QUERY_EXECUTED_KEY);
+ const databaseExplored = useIntroStateByKey(
+ GUIDE_PROGRESS_KEYS.databaseExplored
+ );
+ const statementRun = useIntroStateByKey(GUIDE_PROGRESS_KEYS.statementRun);
+ const changeIssueCreated = useIntroStateByKey(
+ GUIDE_PROGRESS_KEYS.changeIssueCreated
+ );
const serverInfo = useAppStore((state) => state.serverInfo);
const defaultProject = serverInfo?.defaultProject ?? "";
const projectCacheSize = useAppStore(
@@ -76,70 +132,100 @@ export const useGuideContext = ({
const databaseCacheSize = useAppStore(
(state) => Object.keys(state.databasesByName).length
);
+ const userCacheSize = useAppStore(
+ (state) => Object.keys(state.usersByName).length
+ );
const workspaceResourceName = useAppStore((state) =>
state.workspaceResourceName()
);
+ const currentUserName = useAppStore((state) => state.currentUserName ?? "");
+ const workspacePolicy = useAppStore((state) => state.workspacePolicy);
+ const isSaaS = useAppStore((state) => state.isSaaSMode());
+ const hasOtherWorkspaceMember = hasOtherHumanWorkspaceMember(
+ workspacePolicy,
+ currentUserName
+ );
const [facts, setFacts] = useState<GuideFacts>(INITIAL_FACTS);
const [loading, setLoading] = useState(true);
- const queryTargetRef = useRef<
+ const eventTargetRef = useRef<
{ projectName: string; databaseName: string } | undefined
>(undefined);
+ const record = (key: string) => {
+ const store = useAppStore.getState();
+ if (store.getIntroStateByKey(key)) return;
+ store.saveIntroStateByKey({ key, newState: true });
+ };
+
+ useEffect(() => {
+ if (
+ !enabled ||
+ dismissed ||
+ workspaceUsage !== "team" ||
+ !hasOtherWorkspaceMember
+ ) {
+ return;
+ }
+ record(GUIDE_PROGRESS_KEYS.teammateAdded);
+ }, [dismissed, enabled, hasOtherWorkspaceMember, workspaceUsage]);
useEffect(() => {
- const off = sqlEditorEvents.on(
+ if (!enabled || dismissed) return;
+ const offStatement = sqlEditorEvents.on(
"query-executed",
({ data: { database, project } }) => {
- if (!database) {
- return;
- }
-
- queryTargetRef.current = {
+ if (!database) return;
+ eventTargetRef.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,
- });
- }
+ record(GUIDE_PROGRESS_KEYS.statementRun);
setFacts((state) => ({
...state,
- hasExploredDatabase: true,
- hasFirstQuery: true,
+ hasRunStatement: true,
databaseProjectName: project,
databaseName: database,
}));
}
);
+ const offChangeIssue =
+ scenarioId === "create-database-change"
+ ? planEvents.on("database-change-issue-created", () => {
+ record(GUIDE_PROGRESS_KEYS.changeIssueCreated);
+ setFacts((state) => ({
+ ...state,
+ hasCreatedChangeIssue: true,
+ }));
+ })
+ : () => undefined;
return () => {
- off();
+ offStatement();
+ offChangeIssue();
};
- }, [databaseExplored, queryExecuted]);
+ }, [dismissed, enabled, scenarioId]);
useEffect(() => {
+ if (!enabled || dismissed) return;
+ const params = route.params ?? {};
if (
- dismissed ||
- !enabled ||
- databaseExplored ||
- !isConcreteDatabaseRoute(route.name, route.params ?? {})
+ isConcreteDatabaseRoute(route.name, params) ||
+ isPopulatedProjectDatabaseRoute(
+ route.name,
+ params,
+ facts.databaseProjectName,
+ facts.databaseName
+ )
) {
- return;
+ record(GUIDE_PROGRESS_KEYS.databaseExplored);
+ setFacts((state) => ({ ...state, hasExploredDatabase: true }));
}
-
- useAppStore.getState().saveIntroStateByKey({
- key: DATABASE_EXPLORED_KEY,
- newState: true,
- });
- setFacts((state) => ({ ...state, hasExploredDatabase: true }));
- }, [databaseExplored, dismissed, enabled, route.name, route.params]);
+ }, [
+ dismissed,
+ enabled,
+ facts.databaseName,
+ facts.databaseProjectName,
+ route.name,
+ route.params,
+ ]);
useEffect(() => {
if (dismissed || !enabled) {
@@ -154,85 +240,98 @@ export const useGuideContext = ({
const projectResponse = await store.fetchProjectList({
pageSize: 1,
silent: true,
- filter: {
- excludeDefault: true,
- state: State.ACTIVE,
- },
+ 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 [workspaceInstances, projectInstances, databases, users] =
+ 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),
+ workspaceUsage === "team" && !isSaaS
+ ? store
+ .listUsers({
+ pageSize: 100,
+ filter: { state: State.ACTIVE },
+ })
+ .catch(() => ({ users: [], nextPageToken: "" }))
+ : Promise.resolve({ users: [], nextPageToken: "" }),
+ ]);
const instance =
- workspaceInstanceResponse.instances[0] ??
- projectInstanceResponse.instances[0];
- const database = databaseResponse?.databases.find(
+ workspaceInstances.instances[0] ?? projectInstances.instances[0];
+ const database = databases?.databases.find(
({ name, project }) => !!name && !!project
);
+ const eventTarget = eventTargetRef.current;
- const latestDatabaseExplored = store.getIntroStateByKey(
- DATABASE_EXPLORED_KEY
- );
- const latestQueryExecuted =
- store.getIntroStateByKey(QUERY_EXECUTED_KEY);
- const queryTarget = latestQueryExecuted
- ? queryTargetRef.current
- : undefined;
-
- setFacts({
+ setFacts((state) => ({
+ ...state,
hasProject: !!project,
hasInstance: !!instance,
- hasExploredDatabase: latestDatabaseExplored,
- hasFirstQuery: latestQueryExecuted,
+ hasExploredDatabase: databaseExplored || state.hasExploredDatabase,
+ hasRunStatement: statementRun || state.hasRunStatement,
+ hasCreatedChangeIssue:
+ changeIssueCreated || state.hasCreatedChangeIssue,
+ hasOtherHumanUser: users.users.some(
+ ({ name }) => !!name && name !== currentUserName
+ ),
projectName: project?.name ?? "",
+ instanceName: instance?.name ?? "",
databaseProjectName:
- queryTarget?.projectName ?? database?.project ?? "",
- databaseName: queryTarget?.databaseName ?? database?.name ?? "",
- });
+ eventTarget?.projectName ?? database?.project ?? "",
+ databaseName: eventTarget?.databaseName ?? database?.name ?? "",
+ }));
} catch {
- // Keep the current progress when resource discovery is unavailable.
+ setFacts((state) => ({
+ ...state,
+ hasExploredDatabase: databaseExplored || state.hasExploredDatabase,
+ hasRunStatement: statementRun || state.hasRunStatement,
+ hasCreatedChangeIssue:
+ changeIssueCreated || state.hasCreatedChangeIssue,
+ }));
}
setLoading(false);
})();
}, [
+ changeIssueCreated,
databaseCacheSize,
databaseExplored,
defaultProject,
dismissed,
enabled,
instanceCacheSize,
+ isSaaS,
projectCacheSize,
- queryExecuted,
- route.name,
+ statementRun,
+ currentUserName,
+ userCacheSize,
+ workspaceUsage,
workspaceResourceName,
]);
- const context = useMemo(() => ({ ...facts, route }), [facts, route]);
+ const context = useMemo(
+ () => ({ ...facts, isSaaS, hasOtherWorkspaceMember, route }),
+ [facts, hasOtherWorkspaceMember, isSaaS, route]
+ );
return { context, loading };
};
diff --git a/frontend/src/routes/auth/WorkspaceSetupPage.test.tsx b/frontend/src/routes/auth/WorkspaceSetupPage.test.tsx
index c738823508..21db565b31 100644
--- a/frontend/src/routes/auth/WorkspaceSetupPage.test.tsx
+++ b/frontend/src/routes/auth/WorkspaceSetupPage.test.tsx
@@ -42,6 +42,10 @@ const mocks = vi.hoisted(() => ({
setRecentProject: vi.fn(),
routerReplace: vi.fn(),
captureMetric: vi.fn(),
+ clearGuideWorkspaceUsage: vi.fn(),
+ clearSelectedGuideScenarioId: vi.fn(),
+ saveGuideWorkspaceUsage: vi.fn(),
+ saveSelectedGuideScenarioId: vi.fn(),
pushNotification: vi.fn(),
hasWorkspacePermissionV2: vi.fn(() => false),
canCreateProject: true,
@@ -56,6 +60,17 @@ vi.mock("@/app/analytics/provider", () => ({
},
}));
+vi.mock("@/modules/workspace-setup-guide/selection", () => ({
+ clearGuideWorkspaceUsage: mocks.clearGuideWorkspaceUsage,
+ clearSelectedGuideScenarioId: mocks.clearSelectedGuideScenarioId,
+ isGuideWorkspaceUsage: (value: unknown) =>
+ value === "team" || value === "solo",
+ isGuideScenarioId: (value: unknown) =>
+ value === "query-data" || value === "create-database-change",
+ saveGuideWorkspaceUsage: mocks.saveGuideWorkspaceUsage,
+ saveSelectedGuideScenarioId: mocks.saveSelectedGuideScenarioId,
+}));
+
vi.mock("@/hooks/useAppState", () => ({
useCurrentUser: () => mocks.currentUser,
useWorkspace: () => mocks.workspace,
@@ -149,7 +164,7 @@ vi.mock("@/utils", () => ({
}));
vi.mock("@/components/UserAvatar", () => ({
- UserAvatar: () => null,
+ UserAvatar: () => <div data-testid="user-avatar" />,
}));
vi.mock("react-i18next", () => ({
@@ -158,10 +173,38 @@ vi.mock("react-i18next", () => ({
t: (key: string) =>
(
({
- "settings.profile.setup-title": "Welcome! Set up your workspace",
+ "common.back": "Back",
+ "settings.profile.setup-scenario.outcome-title":
+ "What would you like to do with Bytebase?",
+ "settings.profile.setup-scenario.create-database-change.title":
+ "Create a database change",
+ "settings.profile.setup-scenario.create-database-change.description":
+ "Define a change and create its issue.",
+ "settings.profile.setup-scenario.query-data.title":
+ "Query data",
+ "settings.profile.setup-scenario.query-data.description":
+ "Open SQL Editor and run a statement.",
+ "settings.profile.setup-scenario.workspace-usage.title":
+ "Who will use Bytebase with you?",
+ "settings.profile.setup-scenario.workspace-usage.team.title":
+ "My team",
+ "settings.profile.setup-scenario.workspace-usage.team.description":
+ "I will work with other people.",
+ "settings.profile.setup-scenario.workspace-usage.solo.title":
+ "Just me",
+ "settings.profile.setup-scenario.workspace-usage.solo.description":
+ "I will use Bytebase on my own.",
+ "settings.profile.setup-scenario.continue": "Continue",
+ "settings.profile.setup-steps.scenario": "Choose a goal",
+ "settings.profile.setup-steps.workspace": "Set up workspace",
"settings.profile.setup-first-project": "Setup 1st project",
+ "settings.profile.setup-skip": "I'll do this later",
"settings.profile.enable-sample-databases":
"Enable sample databases",
+ "settings.profile.enable-sample-databases-query-data":
+ "Enable sample databases to start querying immediately",
+ "settings.profile.enable-sample-databases-create-change":
+ "Enable sample databases as a safe change target",
"settings.profile.setup-submit": "Setup my workspace",
"instance.prepare-sample-instance-failed":
"Failed to prepare Sample Project Instance.",
@@ -192,6 +235,17 @@ const renderIntoContainer = (element: ReactElement) => {
};
};
+const renderWorkspaceForm = () => {
+ const page = renderIntoContainer(<WorkspaceSetupPage />);
+ page.render();
+ const continueWithoutSelection = [
+ ...page.container.querySelectorAll("button"),
+ ].find((button) => button.textContent === "Continue");
+ if (!continueWithoutSelection) throw new Error("Continue not found");
+ act(() => fireEvent.click(continueWithoutSelection));
+ return page;
+};
+
beforeEach(async () => {
vi.clearAllMocks();
mocks.canUpdateWorkspace = true;
@@ -218,6 +272,306 @@ beforeEach(async () => {
});
describe("WorkspaceSetupPage", () => {
+ test("uses the shared step indicator for both setup steps", async () => {
+ const page = renderIntoContainer(<WorkspaceSetupPage />);
+ page.render();
+
+ const initialIndicator = page.container.querySelector(
+ "[data-slot='step-indicator']"
+ );
+ expect(initialIndicator).not.toBeNull();
+ expect(
+ [...initialIndicator!.querySelectorAll("li span")].map(
+ (label) => label.textContent
+ )
+ ).toEqual(["Choose a goal", "Set up workspace"]);
+ expect(initialIndicator!.querySelector("svg")).toBeNull();
+
+ const queryOption = [...page.container.querySelectorAll("label")].find(
+ (label) => label.textContent?.includes("Query data")
+ )!;
+ await act(async () => {
+ fireEvent.click(queryOption);
+ await Promise.resolve();
+ });
+ const continueButton = [...page.container.querySelectorAll("button")].find(
+ (button) => button.textContent === "Continue"
+ )!;
+ await act(async () => {
+ fireEvent.click(continueButton);
+ await Promise.resolve();
+ });
+
+ const workspaceIndicator = page.container.querySelector(
+ "[data-slot='step-indicator']"
+ );
+ expect(workspaceIndicator).not.toBeNull();
+ expect(workspaceIndicator!.querySelector("svg")).not.toBeNull();
+ page.unmount();
+ });
+
+ test("uses stable wizard footer actions for workspace setup", () => {
+ const page = renderWorkspaceForm();
+ const buttons = [...page.container.querySelectorAll("button")];
+ const back = buttons.find((button) => button.textContent === "Back")!;
+ const skip = buttons.find(
+ (button) => button.textContent === "I'll do this later"
+ )!;
+ const submit = buttons.find(
+ (button) => button.textContent === "Setup my workspace"
+ )!;
+ const footer = back.parentElement!;
+
+ expect(footer.className).toContain("justify-between");
+ expect(footer.className).toContain("gap-x-2");
+ expect(footer.firstElementChild).toBe(back);
+ expect(footer.lastElementChild).toContainElement(skip);
+ expect(footer.lastElementChild).toContainElement(submit);
+ expect(footer.lastElementChild?.textContent).toBe(
+ "I'll do this laterSetup my workspace"
+ );
+ expect(footer.querySelector(".w-full")).toBeNull();
+ page.unmount();
+ });
+
+ test("starts with two unanswered questionnaire groups", () => {
+ const page = renderIntoContainer(<WorkspaceSetupPage />);
+
+ page.render();
+
+ expect(page.container.textContent).toContain(
+ "What would you like to do with Bytebase?"
+ );
+ expect(page.container.querySelectorAll("[role='radio']")).toHaveLength(4);
+ expect(page.container.textContent).toContain("Create a database change");
+ expect(page.container.textContent).toContain("Who will use Bytebase with you?");
+ expect(page.container.textContent).toContain("My team");
+ expect(page.container.textContent).toContain("Just me");
+ expect(page.container.textContent).not.toContain("Learn Bytebase Basics");
+ expect(page.container.textContent).not.toContain("Setup 1st project");
+ expect(page.container.textContent).not.toContain("Skip");
+
+ page.unmount();
+ });
+
+ test("persists Create a database change when the questionnaire continues", async () => {
+ const page = renderIntoContainer(<WorkspaceSetupPage />);
+ page.render();
+ const changeOption = [...page.container.querySelectorAll("label")].find(
+ (label) => label.textContent?.includes("Create a database change")
+ )!;
+
+ await act(async () => {
+ fireEvent.click(changeOption);
+ await Promise.resolve();
+ });
+ const continueButton = [...page.container.querySelectorAll("button")].find(
+ (button) => button.textContent === "Continue"
+ )!;
+ await act(async () => {
+ fireEvent.click(continueButton);
+ await Promise.resolve();
+ });
+ expect(page.container.textContent).toContain(
+ "Enable sample databases as a safe change target"
+ );
+ expect(mocks.saveSelectedGuideScenarioId).toHaveBeenCalledWith(
+ "create-database-change"
+ );
+ expect(mocks.captureMetric).not.toHaveBeenCalled();
+ page.unmount();
+ });
+
+ test("persists both answers without recording before setup ends", async () => {
+ const page = renderIntoContainer(<WorkspaceSetupPage />);
+ page.render();
+ const labels = [...page.container.querySelectorAll("label")];
+
+ await act(async () => {
+ fireEvent.click(
+ labels.find((label) => label.textContent?.includes("Query data"))!
+ );
+ fireEvent.click(
+ labels.find((label) => label.textContent?.includes("My team"))!
+ );
+ await Promise.resolve();
+ });
+ const continueButton = [...page.container.querySelectorAll("button")].find(
+ (button) => button.textContent === "Continue"
+ )!;
+ await act(async () => {
+ fireEvent.click(continueButton);
+ await Promise.resolve();
+ });
+
+ expect(mocks.saveSelectedGuideScenarioId).toHaveBeenCalledWith(
+ "query-data"
+ );
+ expect(mocks.saveGuideWorkspaceUsage).toHaveBeenCalledWith("team");
+ expect(mocks.captureMetric).not.toHaveBeenCalled();
+ page.unmount();
+ });
+
+ test("persists Query Data before optional workspace setup", async () => {
+ const page = renderIntoContainer(<WorkspaceSetupPage />);
+ page.render();
+ const queryOption = [...page.container.querySelectorAll("label")].find(
+ (label) => label.textContent?.includes("Query data")
+ )!;
+
+ await act(async () => {
+ fireEvent.click(queryOption);
+ await Promise.resolve();
+ });
+ const continueButton = [...page.container.querySelectorAll("button")].find(
+ (button) => button.textContent === "Continue"
+ )!;
+ await act(async () => {
+ fireEvent.click(continueButton);
+ await Promise.resolve();
+ });
+ expect(mocks.saveSelectedGuideScenarioId).toHaveBeenCalledWith(
+ "query-data"
+ );
+ expect(page.container.textContent).toContain(
+ "Enable sample databases to start querying immediately"
+ );
+
+ const submit = [...page.container.querySelectorAll("button")].find(
+ (button) => button.textContent?.includes("Setup my workspace")
+ )!;
+ await act(async () => {
+ fireEvent.click(submit);
+ await Promise.resolve();
+ await Promise.resolve();
+ });
+
+ expect(mocks.saveSelectedGuideScenarioId).toHaveBeenCalledWith(
+ "query-data"
+ );
+ expect(mocks.captureMetric).toHaveBeenCalledWith({
+ event: "workspace setup submitted",
+ properties: {
+ scenario: "query-data",
+ result: "finished",
+ sample_enabled: true,
+ },
+ });
+ page.unmount();
+ });
+
+ test("preserves an explicit selection when optional setup fails", async () => {
+ mocks.updateUser.mockRejectedValueOnce(new Error("update failed"));
+ const page = renderIntoContainer(<WorkspaceSetupPage />);
+ page.render();
+ const changeOption = [...page.container.querySelectorAll("label")].find(
+ (label) => label.textContent?.includes("Create a database change")
+ )!;
+ await act(async () => {
+ fireEvent.click(changeOption);
+ await Promise.resolve();
+ });
+ const continueButton = [...page.container.querySelectorAll("button")].find(
+ (button) => button.textContent === "Continue"
+ )!;
+ await act(async () => {
+ fireEvent.click(continueButton);
+ await Promise.resolve();
+ });
+ const submit = [...page.container.querySelectorAll("button")].find(
+ (button) => button.textContent?.includes("Setup my workspace")
+ )!;
+
+ await act(async () => {
+ fireEvent.click(submit);
+ await Promise.resolve();
+ await Promise.resolve();
+ });
+
+ expect(mocks.saveSelectedGuideScenarioId).toHaveBeenCalledWith(
+ "create-database-change"
+ );
+ expect(mocks.captureMetric).not.toHaveBeenCalled();
+ page.unmount();
+ });
+
+ test("preserves the selected scenario when workspace setup is skipped", async () => {
+ const page = renderIntoContainer(<WorkspaceSetupPage />);
+ page.render();
+ const queryOption = [...page.container.querySelectorAll("label")].find(
+ (label) => label.textContent?.includes("Query data")
+ )!;
+
+ await act(async () => {
+ fireEvent.click(queryOption);
+ await Promise.resolve();
+ });
+ const continueButton = [...page.container.querySelectorAll("button")].find(
+ (button) => button.textContent === "Continue"
+ )!;
+ await act(async () => {
+ fireEvent.click(continueButton);
+ await Promise.resolve();
+ });
+ const skipSetupButton = [...page.container.querySelectorAll("button")].find(
+ (button) => button.textContent === "I'll do this later"
+ )!;
+ await act(async () => {
+ fireEvent.click(skipSetupButton);
+ await Promise.resolve();
+ });
+
+ expect(mocks.saveSelectedGuideScenarioId).toHaveBeenCalledWith(
+ "query-data"
+ );
+ expect(mocks.captureMetric).toHaveBeenCalledWith({
+ event: "workspace setup submitted",
+ properties: {
+ scenario: "query-data",
+ result: "skipped",
+ sample_enabled: false,
+ },
+ });
+ expect(mocks.routerReplace).toHaveBeenCalled();
+ page.unmount();
+ });
+
+ test("continuing without a scenario keeps scenario storage empty", async () => {
+ const page = renderIntoContainer(<WorkspaceSetupPage />);
+ page.render();
+ const continueButton = [...page.container.querySelectorAll("button")].find(
+ (button) => button.textContent === "Continue"
+ )!;
+
+ await act(async () => {
+ fireEvent.click(continueButton);
+ await Promise.resolve();
+ });
+ const submit = [...page.container.querySelectorAll("button")].find(
+ (button) => button.textContent?.includes("Setup my workspace")
+ )!;
+ await act(async () => {
+ fireEvent.click(submit);
+ await Promise.resolve();
+ await Promise.resolve();
+ });
+
+ expect(mocks.clearSelectedGuideScenarioId).toHaveBeenCalledOnce();
+ expect(mocks.clearGuideWorkspaceUsage).toHaveBeenCalledOnce();
+ expect(mocks.saveSelectedGuideScenarioId).not.toHaveBeenCalled();
+ expect(mocks.saveGuideWorkspaceUsage).not.toHaveBeenCalled();
+ expect(mocks.captureMetric).toHaveBeenCalledTimes(2);
+ expect(mocks.captureMetric).toHaveBeenCalledWith({
+ event: "workspace setup submitted",
+ properties: {
+ scenario: "unselected",
+ result: "finished",
+ sample_enabled: true,
+ },
+ });
+ page.unmount();
+ });
+
test("uses the shared product intro query key after creating a project", () => {
const source = readFileSync(join(componentDir, "WorkspaceSetupPage.tsx"), {
encoding: "utf8",
@@ -233,13 +587,15 @@ describe("WorkspaceSetupPage", () => {
});
test("shows workspace name when the sole member can update the workspace", () => {
- const page = renderIntoContainer(<WorkspaceSetupPage />);
-
- page.render();
+ const page = renderWorkspaceForm();
- expect(page.container.textContent).toContain(
+ expect(page.container.textContent).not.toContain(
"Welcome! Set up your workspace"
);
+ expect(page.container.querySelector("[data-testid='user-avatar']")).toBeNull();
+ const heading = page.container.querySelector("h1");
+ expect(heading).toHaveTextContent("Set up workspace");
+ expect(heading).toHaveClass("sr-only");
expect(page.container.textContent).toContain(
"settings.profile.workspace-name"
);
@@ -273,9 +629,7 @@ describe("WorkspaceSetupPage", () => {
},
],
} as IamPolicy;
- const page = renderIntoContainer(<WorkspaceSetupPage />);
-
- page.render();
+ const page = renderWorkspaceForm();
expect(page.container.textContent).not.toContain(
"settings.profile.workspace-name"
@@ -285,9 +639,7 @@ describe("WorkspaceSetupPage", () => {
});
test("can optionally create a project and continue to its databases page", async () => {
- const page = renderIntoContainer(<WorkspaceSetupPage />);
-
- page.render();
+ const page = renderWorkspaceForm();
expect(page.container.textContent).toContain("Setup 1st project");
expect(page.container.textContent).not.toContain(
@@ -343,6 +695,21 @@ describe("WorkspaceSetupPage", () => {
expect(mocks.createProject.mock.invocationCallOrder[0]).toBeLessThan(
mocks.prepareSampleProjectInstance.mock.invocationCallOrder[0]
);
+ expect(mocks.captureMetric).toHaveBeenCalledWith({
+ event: "sample instance requested",
+ properties: { source: "workspace_setup" },
+ });
+ const sampleMetricCall = mocks.captureMetric.mock.calls.find(
+ ([metric]) => metric.event === "sample instance requested"
+ );
+ expect(sampleMetricCall).toBeDefined();
+ expect(sampleMetricCall![0]).toEqual({
+ event: "sample instance requested",
+ properties: { source: "workspace_setup" },
+ });
+ expect(mocks.captureMetric.mock.invocationCallOrder[0]).toBeLessThan(
+ mocks.prepareSampleProjectInstance.mock.invocationCallOrder[0]
+ );
expect(mocks.routerReplace).toHaveBeenCalledWith({
name: "workspace.project.database",
params: { projectId: "new-project" },
@@ -356,9 +723,7 @@ describe("WorkspaceSetupPage", () => {
});
test("allows setup without creating a project when its title is cleared", async () => {
- const page = renderIntoContainer(<WorkspaceSetupPage />);
-
- page.render();
+ const page = renderWorkspaceForm();
const projectNameInput = page.container.querySelector(
"[data-testid='profile-project-title']"
@@ -389,6 +754,18 @@ describe("WorkspaceSetupPage", () => {
expect(mocks.createProject).not.toHaveBeenCalled();
expect(mocks.prepareSampleProjectInstance).not.toHaveBeenCalled();
+ expect(mocks.captureMetric).not.toHaveBeenCalledWith({
+ event: "sample instance requested",
+ properties: expect.anything(),
+ });
+ expect(mocks.captureMetric).toHaveBeenCalledWith({
+ event: "workspace setup submitted",
+ properties: {
+ scenario: "unselected",
+ result: "finished",
+ sample_enabled: false,
+ },
+ });
expect(mocks.setRecentProject).not.toHaveBeenCalled();
expect(mocks.routerReplace).toHaveBeenCalledWith({
name: "workspace.project",
@@ -399,9 +776,7 @@ describe("WorkspaceSetupPage", () => {
});
test("requires a project ID while the project title is present", async () => {
- const page = renderIntoContainer(<WorkspaceSetupPage />);
-
- page.render();
+ const page = renderWorkspaceForm();
const projectResourceIdInput = page.container.querySelector(
"[data-testid='project-resource-id']"
@@ -420,9 +795,7 @@ describe("WorkspaceSetupPage", () => {
});
test("does not prepare sample databases when the user opts out", async () => {
- const page = renderIntoContainer(<WorkspaceSetupPage />);
-
- page.render();
+ const page = renderWorkspaceForm();
const sampleCheckbox = page.container.querySelector(
"[data-testid='enable-sample-databases']"
@@ -448,6 +821,14 @@ describe("WorkspaceSetupPage", () => {
params: { projectId: "new-project" },
query: { intro: "connect-database" },
});
+ expect(mocks.captureMetric).toHaveBeenCalledWith({
+ event: "workspace setup submitted",
+ properties: {
+ scenario: "unselected",
+ result: "finished",
+ sample_enabled: false,
+ },
+ });
page.unmount();
});
@@ -456,9 +837,7 @@ describe("WorkspaceSetupPage", () => {
mocks.prepareSampleProjectInstance.mockRejectedValue(
new Error("sample target unavailable")
);
- const page = renderIntoContainer(<WorkspaceSetupPage />);
-
- page.render();
+ const page = renderWorkspaceForm();
const submit = Array.from(page.container.querySelectorAll("button")).find(
(button) => button.textContent?.includes("Setup my workspace")
@@ -480,15 +859,21 @@ describe("WorkspaceSetupPage", () => {
params: { projectId: "new-project" },
query: { intro: "connect-database" },
});
+ expect(mocks.captureMetric).toHaveBeenCalledWith({
+ event: "workspace setup submitted",
+ properties: {
+ scenario: "unselected",
+ result: "finished",
+ sample_enabled: true,
+ },
+ });
page.unmount();
});
test("hides sample database setup when the target is unavailable", () => {
mocks.sampleAvailable = false;
- const page = renderIntoContainer(<WorkspaceSetupPage />);
-
- page.render();
+ const page = renderWorkspaceForm();
expect(
page.container.querySelector(
@@ -501,9 +886,7 @@ describe("WorkspaceSetupPage", () => {
test("hides sample database setup when the workspace already provisioned a sample", () => {
mocks.sampleInstances = [{ instance: "instances/sample" }];
- const page = renderIntoContainer(<WorkspaceSetupPage />);
-
- page.render();
+ const page = renderWorkspaceForm();
expect(
page.container.querySelector(
@@ -515,12 +898,10 @@ describe("WorkspaceSetupPage", () => {
});
test("skips workspace setup to the projects page with create project highlighted", async () => {
- const page = renderIntoContainer(<WorkspaceSetupPage />);
-
- page.render();
+ const page = renderWorkspaceForm();
const skip = Array.from(page.container.querySelectorAll("button")).find(
- (button) => button.textContent?.includes("settings.profile.setup-skip")
+ (button) => button.textContent === "I'll do this later"
) as HTMLButtonElement;
await act(async () => {
skip.click();
@@ -533,8 +914,12 @@ describe("WorkspaceSetupPage", () => {
query: { intro: "create-project" },
});
expect(mocks.captureMetric).toHaveBeenCalledWith({
- event: "workspace setup skipped",
- properties: { deployment: "self-host" },
+ event: "workspace setup submitted",
+ properties: {
+ scenario: "unselected",
+ result: "skipped",
+ sample_enabled: false,
+ },
});
page.unmount();
@@ -545,11 +930,9 @@ describe("WorkspaceSetupPage", () => {
{ isSaaSMode: true, deployment: "cloud" },
])(
"records a completed setup for the $deployment deployment",
- async ({ isSaaSMode, deployment }) => {
+ async ({ isSaaSMode }) => {
mocks.isSaaSMode = isSaaSMode;
- const page = renderIntoContainer(<WorkspaceSetupPage />);
-
- page.render();
+ const page = renderWorkspaceForm();
const submit = Array.from(
page.container.querySelectorAll("button")
@@ -563,12 +946,11 @@ describe("WorkspaceSetupPage", () => {
});
expect(mocks.captureMetric).toHaveBeenCalledWith({
- event: "workspace setup completed",
+ event: "workspace setup submitted",
properties: {
- deployment,
- project_created: true,
- sample_requested: true,
- sample_succeeded: true,
+ scenario: "unselected",
+ result: "finished",
+ sample_enabled: true,
},
});
diff --git a/frontend/src/routes/auth/WorkspaceSetupPage.tsx b/frontend/src/routes/auth/WorkspaceSetupPage.tsx
index a78d9d6d03..bc8c240a03 100644
--- a/frontend/src/routes/auth/WorkspaceSetupPage.tsx
+++ b/frontend/src/routes/auth/WorkspaceSetupPage.tsx
@@ -10,11 +10,11 @@ import {
PROJECT_V1_ROUTE_DATABASES,
} from "@/app/router/handles";
import { ResourceIdField } from "@/components/ResourceIdField";
-import { UserAvatar } from "@/components/UserAvatar";
import { Button } from "@/components/ui/button";
import { Checkbox } from "@/components/ui/checkbox";
import { FormField } from "@/components/ui/form";
import { Input } from "@/components/ui/input";
+import { StepIndicator } from "@/components/ui/step-indicator";
import {
useCreateProject,
useCurrentUser,
@@ -28,6 +28,16 @@ import {
PROJECT_INSTANCE_SYNCED_PRODUCT_INTRO,
} from "@/lib/productIntro";
import { cn } from "@/lib/utils";
+import {
+ clearGuideWorkspaceUsage,
+ clearSelectedGuideScenarioId,
+ saveGuideWorkspaceUsage,
+ saveSelectedGuideScenarioId,
+} from "@/modules/workspace-setup-guide/selection";
+import type {
+ GuideScenarioId,
+ GuideWorkspaceUsage,
+} from "@/modules/workspace-setup-guide/types";
import { pushNotification } from "@/stores";
import { useAppStore } from "@/stores/app";
import { projectNamePrefix } from "@/stores/modules/v1/common";
@@ -39,6 +49,7 @@ import {
extractProjectResourceName,
} from "@/utils";
import { extractGrpcErrorMessage } from "@/utils/connect";
+import { WorkspaceSetupQuestionnaireStep } from "./WorkspaceSetupQuestionnaireStep";
export function WorkspaceSetupPage() {
const { t } = useTranslation();
@@ -55,9 +66,6 @@ export function WorkspaceSetupPage() {
(state) => (state.serverInfo?.sample?.instances.length ?? 0) > 0
);
const canPrepareSample = sampleAvailable && !sampleProvisioned;
- const deployment = useAppStore((state) =>
- state.isSaaSMode() ? "cloud" : "self-host"
- );
const { createProject, setRecentProject } = useCreateProject();
const workspace = useWorkspace();
const workspacePolicy = useAppStore((state) => state.workspacePolicy);
@@ -72,6 +80,12 @@ export function WorkspaceSetupPage() {
(count, b) => count + b.members.length,
0
) === 1;
+ const [setupStep, setSetupStep] = useState<"scenario" | "workspace">(
+ "scenario"
+ );
+ const [selectedScenarioId, setSelectedScenarioId] =
+ useState<GuideScenarioId>();
+ const [workspaceUsage, setWorkspaceUsage] = useState<GuideWorkspaceUsage>();
// `currentUser` loads asynchronously (unknownUser with an empty email until
// then), so seed the name field once the real user is known rather than
@@ -149,7 +163,6 @@ export function WorkspaceSetupPage() {
}
let createdProjectName = "";
let sampleInstanceName = "";
- let sampleSucceeded = false;
if (shouldCreateProject) {
const createdProject = await createProject(
projectTitle.trim(),
@@ -158,12 +171,16 @@ export function WorkspaceSetupPage() {
setRecentProject(createdProject.name);
createdProjectName = createdProject.name;
if (sampleRequested && createdProject.name) {
+ behaviorAnalytics.captureMetric(
+ createBehaviorMetric("sample instance requested", {
+ properties: { source: "workspace_setup" },
+ })
+ );
try {
const sampleInstance = await prepareSampleProjectInstance(
createdProject.name
);
sampleInstanceName = sampleInstance.name;
- sampleSucceeded = true;
} catch (error) {
pushNotification({
module: "bytebase",
@@ -180,12 +197,11 @@ export function WorkspaceSetupPage() {
title: t("settings.profile.setup-success"),
});
behaviorAnalytics.captureMetric(
- createBehaviorMetric("workspace setup completed", {
+ createBehaviorMetric("workspace setup submitted", {
properties: {
- deployment,
- project_created: !!createdProjectName,
- sample_requested: sampleRequested,
- sample_succeeded: sampleSucceeded,
+ scenario: selectedScenarioId ?? "unselected",
+ result: "finished",
+ sample_enabled: sampleRequested,
},
})
);
@@ -230,30 +246,68 @@ export function WorkspaceSetupPage() {
const handleSkip = () => {
behaviorAnalytics.captureMetric(
- createBehaviorMetric("workspace setup skipped", {
- properties: { deployment },
+ createBehaviorMetric("workspace setup submitted", {
+ properties: {
+ scenario: selectedScenarioId ?? "unselected",
+ result: "skipped",
+ sample_enabled: false,
+ },
})
);
goToDashboard();
};
- const displayName = name.trim() || currentUser?.email || "?";
+ const setupSteps = [
+ {
+ key: "scenario",
+ title: t("settings.profile.setup-steps.scenario"),
+ },
+ {
+ key: "workspace",
+ title: t("settings.profile.setup-steps.workspace"),
+ },
+ ];
+
+ if (setupStep === "scenario") {
+ return (
+ <div className="flex min-h-screen items-center justify-center px-4">
+ <div className="flex w-full max-w-lg flex-col gap-y-6">
+ <StepIndicator steps={setupSteps} currentKey={setupStep} />
+ <WorkspaceSetupQuestionnaireStep
+ scenarioValue={selectedScenarioId}
+ workspaceUsageValue={workspaceUsage}
+ onScenarioChange={setSelectedScenarioId}
+ onWorkspaceUsageChange={setWorkspaceUsage}
+ onContinue={() => {
+ if (selectedScenarioId) {
+ saveSelectedGuideScenarioId(selectedScenarioId);
+ } else {
+ clearSelectedGuideScenarioId();
+ }
+ if (workspaceUsage) {
+ saveGuideWorkspaceUsage(workspaceUsage);
+ } else {
+ clearGuideWorkspaceUsage();
+ }
+ setSetupStep("workspace");
+ }}
+ />
+ </div>
+ </div>
+ );
+ }
return (
<div className="flex flex-col items-center justify-center min-h-screen px-4">
<div className="w-full max-w-lg mx-4 flex flex-col items-center gap-y-6">
- <UserAvatar
- title={displayName}
- colorSeed={currentUser?.email}
- size="md"
- className="size-16! text-2xl!"
+ <StepIndicator
+ className="w-full"
+ steps={setupSteps}
+ currentKey={setupStep}
/>
-
- <div className="text-center">
- <h1 className="text-xl font-semibold">
- {t("settings.profile.setup-title")}
- </h1>
- </div>
+ <h1 className="sr-only">
+ {t("settings.profile.setup-steps.workspace")}
+ </h1>
<div className="w-full flex flex-col gap-y-4">
<FormField title={t("settings.profile.display-name")}>
@@ -325,28 +379,34 @@ export function WorkspaceSetupPage() {
"cursor-not-allowed text-control-placeholder"
)}
>
- {t("settings.profile.enable-sample-databases")}
+ {t(
+ selectedScenarioId === "query-data"
+ ? "settings.profile.enable-sample-databases-query-data"
+ : selectedScenarioId === "create-database-change"
+ ? "settings.profile.enable-sample-databases-create-change"
+ : "settings.profile.enable-sample-databases"
+ )}
</label>
</div>
)}
</FormField>
)}
- <div className="flex flex-col gap-y-2 mt-2">
- <Button
- onClick={() => void handleSave()}
- disabled={!canSave}
- className="w-full"
- >
- {t("settings.profile.setup-submit")}
- </Button>
+ <div className="mt-2 flex items-center justify-between gap-x-2 border-t border-block-border pt-4">
<Button
appearance="secondary"
- onClick={handleSkip}
- className="w-full"
+ onClick={() => setSetupStep("scenario")}
>
- {t("settings.profile.setup-skip")}
+ {t("common.back")}
</Button>
+ <div className="flex flex-col items-end gap-y-2 sm:flex-row sm:items-center sm:gap-x-2 sm:gap-y-0">
+ <Button appearance="secondary" onClick={handleSkip}>
+ {t("settings.profile.setup-skip")}
+ </Button>
+ <Button onClick={() => void handleSave()} disabled={!canSave}>
+ {t("settings.profile.setup-submit")}
+ </Button>
+ </div>
</div>
</div>
</div>
diff --git a/frontend/src/routes/auth/WorkspaceSetupQuestionnaireStep.test.tsx b/frontend/src/routes/auth/WorkspaceSetupQuestionnaireStep.test.tsx
new file mode 100644
index 0000000000..350dd638c9
--- /dev/null
+++ b/frontend/src/routes/auth/WorkspaceSetupQuestionnaireStep.test.tsx
@@ -0,0 +1,143 @@
+import { fireEvent } from "@testing-library/react";
+import type { ReactElement } from "react";
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import enUS from "@/locales/en-US.json";
+import type {
+ GuideScenarioId,
+ GuideWorkspaceUsage,
+} from "@/modules/workspace-setup-guide/types";
+import { WorkspaceSetupQuestionnaireStep } from "./WorkspaceSetupQuestionnaireStep";
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT =
+ true;
+
+vi.mock("react-i18next", () => ({
+ initReactI18next: { type: "3rdParty", init: () => undefined },
+ useTranslation: () => ({
+ t: (key: string) =>
+ (
+ {
+ "settings.profile.setup-scenario.outcome-title":
+ "What would you like to do with Bytebase?",
+ "settings.profile.setup-scenario.create-database-change.title":
+ "Create a database change",
+ "settings.profile.setup-scenario.create-database-change.description":
+ "Define a change and create its issue.",
+ "settings.profile.setup-scenario.query-data.title": "Query data",
+ "settings.profile.setup-scenario.query-data.description":
+ "Open SQL Editor and run a statement.",
+ "settings.profile.setup-scenario.workspace-usage.title":
+ "Who will use Bytebase with you?",
+ "settings.profile.setup-scenario.workspace-usage.team.title":
+ "My team",
+ "settings.profile.setup-scenario.workspace-usage.team.description":
+ "I will work with other people.",
+ "settings.profile.setup-scenario.workspace-usage.solo.title":
+ "Just me",
+ "settings.profile.setup-scenario.workspace-usage.solo.description":
+ "I will use Bytebase on my own.",
+ "settings.profile.setup-scenario.continue": "Continue",
+ } as Record<string, string>
+ )[key] ?? key,
+ }),
+}));
+
+const renderIntoContainer = (element: ReactElement) => {
+ const container = document.createElement("div");
+ const root = createRoot(container);
+ act(() => root.render(element));
+ return {
+ container,
+ unmount: () => act(() => root.unmount()),
+ };
+};
+
+const renderQuestionnaire = (
+ props: Partial<{
+ scenarioValue: GuideScenarioId;
+ workspaceUsageValue: GuideWorkspaceUsage;
+ onScenarioChange: (value: GuideScenarioId) => void;
+ onWorkspaceUsageChange: (value: GuideWorkspaceUsage) => void;
+ onContinue: () => void;
+ }> = {}
+) =>
+ renderIntoContainer(
+ <WorkspaceSetupQuestionnaireStep
+ scenarioValue={props.scenarioValue}
+ workspaceUsageValue={props.workspaceUsageValue}
+ onScenarioChange={props.onScenarioChange ?? vi.fn()}
+ onWorkspaceUsageChange={props.onWorkspaceUsageChange ?? vi.fn()}
+ onContinue={props.onContinue ?? vi.fn()}
+ />
+ );
+
+describe("WorkspaceSetupQuestionnaireStep", () => {
+ beforeEach(() => vi.clearAllMocks());
+
+ test("uses a goal question that names Bytebase", () => {
+ expect(
+ enUS.settings.profile["setup-scenario"]["outcome-title"]
+ ).toBe("What would you like to do with Bytebase?");
+ });
+
+ test("starts with both questions unanswered and allows Continue", () => {
+ const page = renderQuestionnaire();
+ const radios = [...page.container.querySelectorAll("[role='radio']")];
+ const buttons = [...page.container.querySelectorAll("button")];
+
+ expect(radios).toHaveLength(4);
+ expect(radios.every((radio) => radio.getAttribute("aria-checked") === "false"))
+ .toBe(true);
+ expect(buttons).toHaveLength(1);
+ expect(buttons[0]).toHaveTextContent("Continue");
+ expect(buttons[0]).toBeEnabled();
+ expect(page.container.textContent).not.toContain("Skip");
+ expect(page.container.querySelector("h1")).toHaveTextContent(
+ "What would you like to do with Bytebase?"
+ );
+ expect(page.container.textContent).not.toContain(
+ "Tell us about your setup"
+ );
+ expect(page.container.textContent).not.toContain(
+ "We will tailor your getting-started guide."
+ );
+ page.unmount();
+ });
+
+ test("reports each answer independently", () => {
+ const onScenarioChange = vi.fn();
+ const onWorkspaceUsageChange = vi.fn();
+ const page = renderQuestionnaire({
+ onScenarioChange,
+ onWorkspaceUsageChange,
+ });
+ const labels = [...page.container.querySelectorAll("label")];
+
+ act(() =>
+ fireEvent.click(
+ labels.find((label) => label.textContent?.includes("Query data"))!
+ )
+ );
+ act(() =>
+ fireEvent.click(
+ labels.find((label) => label.textContent?.includes("My team"))!
+ )
+ );
+
+ expect(onScenarioChange).toHaveBeenCalledWith("query-data");
+ expect(onWorkspaceUsageChange).toHaveBeenCalledWith("team");
+ page.unmount();
+ });
+
+ test("continues without requiring either answer", () => {
+ const onContinue = vi.fn();
+ const page = renderQuestionnaire({ onContinue });
+
+ act(() => fireEvent.click(page.container.querySelector("button")!));
+
+ expect(onContinue).toHaveBeenCalledOnce();
+ page.unmount();
+ });
+});
diff --git a/frontend/src/routes/auth/WorkspaceSetupQuestionnaireStep.tsx b/frontend/src/routes/auth/WorkspaceSetupQuestionnaireStep.tsx
new file mode 100644
index 0000000000..8154169961
--- /dev/null
+++ b/frontend/src/routes/auth/WorkspaceSetupQuestionnaireStep.tsx
@@ -0,0 +1,147 @@
+import { useTranslation } from "react-i18next";
+import { Button } from "@/components/ui/button";
+import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";
+import { cn } from "@/lib/utils";
+import {
+ isGuideScenarioId,
+ isGuideWorkspaceUsage,
+} from "@/modules/workspace-setup-guide/selection";
+import type {
+ GuideScenarioId,
+ GuideWorkspaceUsage,
+} from "@/modules/workspace-setup-guide/types";
+
+type WorkspaceSetupQuestionnaireStepProps = {
+ scenarioValue?: GuideScenarioId;
+ workspaceUsageValue?: GuideWorkspaceUsage;
+ onScenarioChange: (value: GuideScenarioId) => void;
+ onWorkspaceUsageChange: (value: GuideWorkspaceUsage) => void;
+ onContinue: () => void;
+};
+
+const SCENARIO_OPTIONS: Array<{
+ id: GuideScenarioId;
+ titleKey: string;
+ descriptionKey: string;
+}> = [
+ {
+ id: "create-database-change",
+ titleKey: "settings.profile.setup-scenario.create-database-change.title",
+ descriptionKey:
+ "settings.profile.setup-scenario.create-database-change.description",
+ },
+ {
+ id: "query-data",
+ titleKey: "settings.profile.setup-scenario.query-data.title",
+ descriptionKey: "settings.profile.setup-scenario.query-data.description",
+ },
+];
+
+const WORKSPACE_USAGE_OPTIONS: Array<{
+ id: GuideWorkspaceUsage;
+ titleKey: string;
+ descriptionKey: string;
+}> = [
+ {
+ id: "team",
+ titleKey: "settings.profile.setup-scenario.workspace-usage.team.title",
+ descriptionKey:
+ "settings.profile.setup-scenario.workspace-usage.team.description",
+ },
+ {
+ id: "solo",
+ titleKey: "settings.profile.setup-scenario.workspace-usage.solo.title",
+ descriptionKey:
+ "settings.profile.setup-scenario.workspace-usage.solo.description",
+ },
+];
+
+const optionClassName = (selected: boolean) =>
+ cn(
+ "items-start rounded-sm border px-4 py-3",
+ selected
+ ? "border-accent bg-accent/5"
+ : "border-control-border hover:bg-control-bg"
+ );
+
+export function WorkspaceSetupQuestionnaireStep({
+ scenarioValue,
+ workspaceUsageValue,
+ onScenarioChange,
+ onWorkspaceUsageChange,
+ onContinue,
+}: WorkspaceSetupQuestionnaireStepProps) {
+ const { t } = useTranslation();
+
+ return (
+ <div className="flex w-full max-w-lg flex-col gap-y-6">
+ <div className="flex flex-col gap-y-3">
+ <h1 className="font-medium text-main">
+ {t("settings.profile.setup-scenario.outcome-title")}
+ </h1>
+ <RadioGroup
+ aria-label={t("settings.profile.setup-scenario.outcome-title")}
+ value={scenarioValue ?? ""}
+ onValueChange={(nextValue) => {
+ if (isGuideScenarioId(nextValue)) onScenarioChange(nextValue);
+ }}
+ className="flex-col items-stretch gap-y-2"
+ >
+ {SCENARIO_OPTIONS.map((option) => (
+ <RadioGroupItem
+ key={option.id}
+ value={option.id}
+ className={optionClassName(scenarioValue === option.id)}
+ radioClassName="mt-0.5"
+ contentClassName="min-w-0"
+ >
+ <div className="font-medium text-main">{t(option.titleKey)}</div>
+ <div className="mt-1 text-sm text-control-light">
+ {t(option.descriptionKey)}
+ </div>
+ </RadioGroupItem>
+ ))}
+ </RadioGroup>
+ </div>
+
+ <div className="flex flex-col gap-y-3">
+ <h2 className="font-medium text-main">
+ {t("settings.profile.setup-scenario.workspace-usage.title")}
+ </h2>
+ <RadioGroup
+ aria-label={t(
+ "settings.profile.setup-scenario.workspace-usage.title"
+ )}
+ value={workspaceUsageValue ?? ""}
+ onValueChange={(nextValue) => {
+ if (isGuideWorkspaceUsage(nextValue)) {
+ onWorkspaceUsageChange(nextValue);
+ }
+ }}
+ className="flex-col items-stretch gap-y-2"
+ >
+ {WORKSPACE_USAGE_OPTIONS.map((option) => (
+ <RadioGroupItem
+ key={option.id}
+ value={option.id}
+ className={optionClassName(workspaceUsageValue === option.id)}
+ radioClassName="mt-0.5"
+ contentClassName="min-w-0"
+ >
+ <div className="font-medium text-main">{t(option.titleKey)}</div>
+ <div className="mt-1 text-sm text-control-light">
+ {t(option.descriptionKey)}
+ </div>
+ </RadioGroupItem>
+ ))}
+ </RadioGroup>
+ </div>
+
+ <div className="flex items-center justify-end gap-x-2 border-t border-block-border pt-4">
+ <Button onClick={onContinue}>
+ {t("settings.profile.setup-scenario.continue")}
+ </Button>
+ </div>
+ </div>
+ );
+}
diff --git a/frontend/src/routes/project/ProjectDatabasesPage.test.tsx b/frontend/src/routes/project/ProjectDatabasesPage.test.tsx
index bac408aa95..af172efa07 100644
--- a/frontend/src/routes/project/ProjectDatabasesPage.test.tsx
+++ b/frontend/src/routes/project/ProjectDatabasesPage.test.tsx
@@ -17,6 +17,10 @@ const mocks = vi.hoisted(() => ({
batchUpdateDatabases: vi.fn(),
useProductIntro: vi.fn(),
captureMetric: vi.fn(),
+ scenarioId: undefined as
+ | "query-data"
+ | "create-database-change"
+ | undefined,
removeDatabaseMetadataCache: vi.fn(),
fetchInstance: vi.fn(),
fetchInstanceList: vi.fn(async (_params?: { parent?: string }) => ({
@@ -83,6 +87,10 @@ vi.mock("@/app/analytics/provider", () => ({
},
}));
+vi.mock("@/modules/workspace-setup-guide/selection", () => ({
+ readSelectedGuideScenarioId: () => mocks.scenarioId,
+}));
+
vi.mock("@/components/AdvancedSearch", () => ({
AdvancedSearch: ({
scopeOptions,
@@ -282,6 +290,7 @@ beforeEach(async () => {
mocks.instancesByName = {};
mocks.routerCurrentName = "workspace.project.database";
mocks.routerCurrentQuery = {};
+ mocks.scenarioId = undefined;
mocks.batchUpdateDatabases.mockResolvedValue(undefined);
mocks.workspacePermissions = new Set([
"bb.instances.create",
@@ -743,6 +752,107 @@ describe("ProjectDatabasesPage", () => {
});
});
+ test("only offers a database change for the change scenario", async () => {
+ mocks.scenarioId = "create-database-change";
+ mocks.routerCurrentQuery = { intro: "project-instance-synced" };
+ mocks.visibleDatabases = [
+ {
+ name: "projects/demo/instances/prod/databases/app",
+ project: "projects/demo",
+ },
+ ];
+ const container = document.createElement("div");
+ const root = createRoot(container);
+
+ await act(async () => {
+ root.render(<ProjectDatabasesPage projectId="demo" />);
+ });
+
+ expect(container.textContent).toContain(
+ "db.project-instance-synced-create-change-title"
+ );
+ expect(container.textContent).toContain(
+ "db.project-instance-synced-create-change-description"
+ );
+ expect(container.textContent).toContain(
+ "db.project-instance-synced-action"
+ );
+ expect(container.textContent).not.toContain(
+ "db.project-instance-synced-sql-editor-action"
+ );
+ expect(mocks.useProductIntro).toHaveBeenCalledWith({
+ id: "project-instance-synced",
+ title: "db.project-instance-synced-create-change-title",
+ description: "db.project-instance-synced-create-change-description",
+ disabled: false,
+ });
+
+ const changeButton = Array.from(container.querySelectorAll("button")).find(
+ (button) =>
+ button.textContent?.includes("db.project-instance-synced-action")
+ ) as HTMLButtonElement;
+ expect(changeButton.className).toContain("bg-accent");
+
+ await act(async () => {
+ changeButton.click();
+ });
+ expect(preCreateIssue).toHaveBeenCalledWith("projects/demo", [
+ "projects/demo/instances/prod/databases/app",
+ ]);
+
+ act(() => {
+ root.unmount();
+ });
+ });
+
+ test("only offers SQL Editor for the query scenario", async () => {
+ mocks.scenarioId = "query-data";
+ mocks.routerCurrentQuery = { intro: "project-instance-synced" };
+ mocks.visibleDatabases = [
+ {
+ name: "projects/demo/instances/prod/databases/app",
+ project: "projects/demo",
+ },
+ ];
+ const container = document.createElement("div");
+ const root = createRoot(container);
+
+ await act(async () => {
+ root.render(<ProjectDatabasesPage projectId="demo" />);
+ });
+
+ expect(container.textContent).toContain(
+ "db.project-instance-synced-query-data-title"
+ );
+ expect(container.textContent).toContain(
+ "db.project-instance-synced-query-data-description"
+ );
+ expect(container.textContent).toContain(
+ "db.project-instance-synced-sql-editor-action"
+ );
+ expect(container.textContent).not.toContain(
+ "db.project-instance-synced-action"
+ );
+ expect(mocks.useProductIntro).toHaveBeenCalledWith({
+ id: "project-instance-synced",
+ title: "db.project-instance-synced-query-data-title",
+ description: "db.project-instance-synced-query-data-description",
+ disabled: false,
+ });
+
+ const sqlEditorButton = Array.from(container.querySelectorAll("a")).find(
+ (link) =>
+ link.textContent?.includes(
+ "db.project-instance-synced-sql-editor-action"
+ )
+ ) as HTMLAnchorElement;
+ expect(sqlEditorButton.className).toContain("bg-accent");
+
+ act(() => {
+ root.unmount();
+ });
+ });
+
test("shows database next actions when requested by the setup guide", async () => {
mocks.routerCurrentQuery = { intro: "project-instance-synced" };
mocks.visibleDatabases = [
@@ -775,6 +885,34 @@ describe("ProjectDatabasesPage", () => {
});
});
+ test("keeps database next actions after the product intro is dismissed", async () => {
+ mocks.routerCurrentQuery = { intro: "project-instance-synced" };
+ mocks.visibleDatabases = [
+ {
+ name: "projects/demo/instances/prod/databases/app",
+ project: "projects/demo",
+ },
+ ];
+ const container = document.createElement("div");
+ const root = createRoot(container);
+
+ await act(async () => {
+ root.render(<ProjectDatabasesPage projectId="demo" />);
+ });
+ expect(container.querySelector("[role='alert']")).not.toBe(null);
+
+ mocks.routerCurrentQuery = {};
+ await act(async () => {
+ root.render(<ProjectDatabasesPage projectId="demo" />);
+ });
+
+ expect(container.querySelector("[role='alert']")).not.toBe(null);
+
+ act(() => {
+ root.unmount();
+ });
+ });
+
test("hides post-sync guidance when the workspace has multiple instances", async () => {
mocks.routerCurrentQuery = { syncingInstance: "prod" };
mocks.fetchInstanceList.mockResolvedValueOnce({
diff --git a/frontend/src/routes/project/ProjectDatabasesPage.tsx b/frontend/src/routes/project/ProjectDatabasesPage.tsx
index b5d95a1811..80fff6257e 100644
--- a/frontend/src/routes/project/ProjectDatabasesPage.tsx
+++ b/frontend/src/routes/project/ProjectDatabasesPage.tsx
@@ -51,6 +51,7 @@ import {
useProductIntro,
} from "@/lib/productIntro";
import { normalizeInstanceName } from "@/lib/resourceName";
+import { readSelectedGuideScenarioId } from "@/modules/workspace-setup-guide/selection";
import { pushNotification } from "@/stores";
import { useAppStore } from "@/stores/app";
import {
@@ -536,11 +537,44 @@ export function ProjectDatabasesPage({ projectId }: { projectId: string }) {
const hasVisibleDatabase = visibleDatabases.length > 0;
const showSyncingInstanceHint =
!!syncingInstanceId && !hasVisibleDatabase && !syncingRefreshExhausted;
+ const databaseNextActionRequested =
+ (availableInstanceCount === 1 && !!syncingInstanceId) ||
+ currentRoute.query[PRODUCT_INTRO_QUERY_KEY] ===
+ PROJECT_INSTANCE_SYNCED_PRODUCT_INTRO;
+ const [databaseNextActionProject, setDatabaseNextActionProject] = useState<
+ string | undefined
+ >(() => (databaseNextActionRequested ? projectName : undefined));
+ useEffect(() => {
+ if (databaseNextActionRequested) {
+ setDatabaseNextActionProject(projectName);
+ }
+ }, [databaseNextActionRequested, projectName]);
const showDatabaseNextAction =
- hasVisibleDatabase &&
- ((availableInstanceCount === 1 && !!syncingInstanceId) ||
- currentRoute.query[PRODUCT_INTRO_QUERY_KEY] ===
- PROJECT_INSTANCE_SYNCED_PRODUCT_INTRO);
+ hasVisibleDatabase && databaseNextActionProject === projectName;
+ const selectedGuideScenarioId = readSelectedGuideScenarioId();
+ const databaseNextAction =
+ selectedGuideScenarioId === "create-database-change"
+ ? {
+ title: t("db.project-instance-synced-create-change-title"),
+ description: t(
+ "db.project-instance-synced-create-change-description"
+ ),
+ showCreateChange: true,
+ showSqlEditor: false,
+ }
+ : selectedGuideScenarioId === "query-data"
+ ? {
+ title: t("db.project-instance-synced-query-data-title"),
+ description: t("db.project-instance-synced-query-data-description"),
+ showCreateChange: false,
+ showSqlEditor: true,
+ }
+ : {
+ title: t("db.project-instance-synced-title"),
+ description: t("db.project-instance-synced-description"),
+ showCreateChange: true,
+ showSqlEditor: true,
+ };
const checkingAvailableInstance =
!hasVisibleDatabase &&
!showSyncingInstanceHint &&
@@ -589,8 +623,8 @@ export function ProjectDatabasesPage({ projectId }: { projectId: string }) {
});
useProductIntro({
id: PROJECT_INSTANCE_SYNCED_PRODUCT_INTRO,
- title: t("db.project-instance-synced-title"),
- description: t("db.project-instance-synced-description"),
+ title: databaseNextAction.title,
+ description: databaseNextAction.description,
disabled: !showDatabaseNextAction,
});
@@ -702,38 +736,46 @@ export function ProjectDatabasesPage({ projectId }: { projectId: string }) {
<Alert
variant="info"
data-product-intro-target={PROJECT_INSTANCE_SYNCED_PRODUCT_INTRO}
- title={t("db.project-instance-synced-title")}
+ title={databaseNextAction.title}
description={
<div className="flex flex-col gap-y-3">
- <span>{t("db.project-instance-synced-description")}</span>
+ <span>{databaseNextAction.description}</span>
<div className="ml-auto flex flex-wrap items-center gap-x-2 gap-y-2">
- <PermissionGuard
- permissions={PERMISSIONS_FOR_DATABASE_CREATE_ISSUE}
- project={project}
- >
- <Button
- size="sm"
- appearance="outline"
- onClick={handleCreateFirstChange}
- >
- {t("db.project-instance-synced-action")}
- </Button>
- </PermissionGuard>
- <PermissionGuard
- permissions={["bb.sql.select"]}
- project={project}
- >
- <span
- className="inline-flex"
- onClickCapture={handleOpenFirstDatabaseInSQLEditor}
+ {databaseNextAction.showCreateChange && (
+ <PermissionGuard
+ permissions={PERMISSIONS_FOR_DATABASE_CREATE_ISSUE}
+ project={project}
>
- <SQLEditorButton
+ <Button
size="sm"
- database={visibleDatabases[0]}
- label={t("db.project-instance-synced-sql-editor-action")}
- />
- </span>
- </PermissionGuard>
+ appearance={
+ databaseNextAction.showSqlEditor ? "outline" : undefined
+ }
+ onClick={handleCreateFirstChange}
+ >
+ {t("db.project-instance-synced-action")}
+ </Button>
+ </PermissionGuard>
+ )}
+ {databaseNextAction.showSqlEditor && (
+ <PermissionGuard
+ permissions={["bb.sql.select"]}
+ project={project}
+ >
+ <span
+ className="inline-flex"
+ onClickCapture={handleOpenFirstDatabaseInSQLEditor}
+ >
+ <SQLEditorButton
+ size="sm"
+ database={visibleDatabases[0]}
+ label={t(
+ "db.project-instance-synced-sql-editor-action"
+ )}
+ />
+ </span>
+ </PermissionGuard>
+ )}
</div>
</div>
}
diff --git a/frontend/src/routes/workspace/MembersPage.test.tsx b/frontend/src/routes/workspace/MembersPage.test.tsx
index d715ca7605..3e632a91f9 100644
--- a/frontend/src/routes/workspace/MembersPage.test.tsx
+++ b/frontend/src/routes/workspace/MembersPage.test.tsx
@@ -12,11 +12,13 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
).IS_REACT_ACT_ENVIRONMENT = true;
const {
+ mockUseProductIntro,
mockPushNotification,
mockUpdateProjectIamPolicy,
maximumRoleExpirationSeconds,
maximumRequestExpirationSeconds,
} = vi.hoisted(() => ({
+ mockUseProductIntro: vi.fn(),
mockPushNotification: vi.fn(),
mockUpdateProjectIamPolicy: vi.fn(),
maximumRoleExpirationSeconds: { value: undefined as number | undefined },
@@ -117,10 +119,16 @@ vi.mock("@/components/ui/button", () => ({
onClick,
variant: _variant,
size: _size,
+ ...props
}: ButtonHTMLAttributes<HTMLButtonElement> & {
size?: string;
variant?: string;
- }) => createElement("button", { disabled, onClick }, children),
+ }) => createElement("button", { ...props, disabled, onClick }, children),
+}));
+
+vi.mock("@/lib/productIntro", () => ({
+ GRANT_ACCESS_PRODUCT_INTRO: "grant-access",
+ useProductIntro: mockUseProductIntro,
}));
vi.mock("@/components/ui/checkbox", () => ({
@@ -379,6 +387,13 @@ async function renderPage(): Promise<void> {
});
}
+async function renderWorkspacePage(): Promise<void> {
+ await act(async () => {
+ root.render(createElement(MembersPage));
+ await Promise.resolve();
+ });
+}
+
async function flush(): Promise<void> {
await act(async () => {
await Promise.resolve();
@@ -538,3 +553,29 @@ describe("MembersPage project role grant drawer", () => {
expect(mockUpdateProjectIamPolicy).not.toHaveBeenCalled();
});
});
+
+describe("MembersPage onboarding intro", () => {
+ it("binds Grant Access only on the editable workspace page", async () => {
+ await renderWorkspacePage();
+
+ expect(mockUseProductIntro).toHaveBeenCalledWith({
+ id: "grant-access",
+ title: "workspace-setup-guide.intro.grant-access-title",
+ description: "workspace-setup-guide.intro.grant-access-description",
+ disabled: false,
+ });
+ const grantButton = [...container.querySelectorAll("button")].find(
+ (button) => button.textContent === "settings.members.grant-access"
+ );
+ expect(grantButton).toHaveAttribute(
+ "data-product-intro-target",
+ "grant-access"
+ );
+
+ mockUseProductIntro.mockClear();
+ await renderPage();
+ expect(mockUseProductIntro).toHaveBeenCalledWith(
+ expect.objectContaining({ id: "grant-access", disabled: true })
+ );
+ });
+});
diff --git a/frontend/src/routes/workspace/MembersPage.tsx b/frontend/src/routes/workspace/MembersPage.tsx
index 54b82c8214..511d23ce44 100644
--- a/frontend/src/routes/workspace/MembersPage.tsx
+++ b/frontend/src/routes/workspace/MembersPage.tsx
@@ -74,6 +74,10 @@ import {
getMemberBindings,
groupProjectRoleBindings,
} from "@/lib/memberBindings";
+import {
+ GRANT_ACCESS_PRODUCT_INTRO,
+ useProductIntro,
+} from "@/lib/productIntro";
import {
getRoleEnvironmentLimitationKind,
roleHasDatabaseLimitation,
@@ -2102,6 +2106,13 @@ export function MembersPage({ projectId }: { projectId?: string }) {
hasProjectPermissionV2(project, "bb.projects.setIamPolicy")
: hasWorkspacePermissionV2("bb.workspaces.setIamPolicy");
+ useProductIntro({
+ id: GRANT_ACCESS_PRODUCT_INTRO,
+ title: t("workspace-setup-guide.intro.grant-access-title"),
+ description: t("workspace-setup-guide.intro.grant-access-description"),
+ disabled: !!projectName || !canSetIamPolicy,
+ });
+
// Whether the current user already holds every PROJECT_OWNER permission
// (workspace- or project-scoped). hasProjectPermissionV2 falls back to
// workspace permissions, so a single check covers both contexts. Mirrors the
@@ -2277,13 +2288,14 @@ export function MembersPage({ projectId }: { projectId?: string }) {
</Button>
)}
<Button
+ data-product-intro-target={GRANT_ACCESS_PRODUCT_INTRO}
disabled={disabled || !canSetIamPolicy}
onClick={() => {
setEditingMember(undefined);
setShowEditMemberDrawer(true);
}}
>
- <Plus className="h-4 w-4 mr-1" />
+ <Plus />
{t("settings.members.grant-access")}
</Button>
</div>
diff --git a/frontend/src/routes/workspace/UsersPage.test.tsx b/frontend/src/routes/workspace/UsersPage.test.tsx
new file mode 100644
index 0000000000..9d8e018ffc
--- /dev/null
+++ b/frontend/src/routes/workspace/UsersPage.test.tsx
@@ -0,0 +1,19 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, test } from "vitest";
+
+const componentDir = dirname(fileURLToPath(import.meta.url));
+
+describe("UsersPage onboarding intro", () => {
+ test("binds the shared Create User intro to the existing create button", () => {
+ const source = readFileSync(join(componentDir, "UsersPage.tsx"), "utf8");
+
+ expect(source).toContain("useProductIntro({");
+ expect(source).toContain("id: CREATE_USER_PRODUCT_INTRO");
+ expect(source).toContain("disabled: !canCreateUser");
+ expect(source).toContain(
+ "data-product-intro-target={CREATE_USER_PRODUCT_INTRO}"
+ );
+ });
+});
diff --git a/frontend/src/routes/workspace/UsersPage.tsx b/frontend/src/routes/workspace/UsersPage.tsx
index 5b4c074ab9..cd1e0e6a18 100644
--- a/frontend/src/routes/workspace/UsersPage.tsx
+++ b/frontend/src/routes/workspace/UsersPage.tsx
@@ -26,6 +26,7 @@ import {
} from "@/components/WorkspacePageLayout";
import { useCurrentUser } from "@/hooks/useAppState";
import { PagedTableFooter, usePagedData } from "@/hooks/usePagedData";
+import { CREATE_USER_PRODUCT_INTRO, useProductIntro } from "@/lib/productIntro";
import { pushNotification } from "@/stores";
import { useAppStore } from "@/stores/app";
import { getUserFullNameByType } from "@/stores/modules/v1/common";
@@ -332,6 +333,14 @@ export function UsersPage() {
s.hasInstanceFeature(PlanFeature.FEATURE_DIRECTORY_SYNC)
);
const canAccessSettings = hasWorkspacePermissionV2("bb.settings.get");
+ const canCreateUser = hasWorkspacePermissionV2("bb.users.create");
+
+ useProductIntro({
+ id: CREATE_USER_PRODUCT_INTRO,
+ title: t("workspace-setup-guide.intro.create-user-title"),
+ description: t("workspace-setup-guide.intro.create-user-description"),
+ disabled: !canCreateUser,
+ });
const [userSearchText, setUserSearchText] = useState("");
const [showInactiveUsers, setShowInactiveUsers] = useState(false);
@@ -435,10 +444,11 @@ export function UsersPage() {
{t("settings.members.entra-sync.self")}
</Button>
<Button
- disabled={!hasWorkspacePermissionV2("bb.users.create")}
+ data-product-intro-target={CREATE_USER_PRODUCT_INTRO}
+ disabled={!canCreateUser}
onClick={() => setShowCreateUserDrawer(true)}
>
- <Plus className="h-4 w-4 mr-1" />
+ <Plus />
{t("common.create")}
</Button>
</div>
diff --git a/frontend/src/stores/app/index.test.ts b/frontend/src/stores/app/index.test.ts
index dd412853a4..2aa3333679 100644
--- a/frontend/src/stores/app/index.test.ts
+++ b/frontend/src/stores/app/index.test.ts
@@ -2156,7 +2156,7 @@ describe("useAppStore", () => {
expect(store.getState().workspaceSetupGuideEnabled()).toBe(false);
});
- test("disables the workspace setup guide after another member joins", () => {
+ test("allows the original admin to finish an explicit team guide", () => {
const store = createAppStore();
store.setState({
currentUser: user,
@@ -2171,6 +2171,25 @@ describe("useAppStore", () => {
}),
});
expect(store.getState().workspaceSetupGuideEnabled()).toBe(false);
+ expect(store.getState().workspaceSetupGuideEnabled(true)).toBe(true);
+ });
+
+ test("does not allow the multi-member exception for a non-admin", () => {
+ const store = createAppStore();
+ store.setState({
+ currentUser: user,
+ serverInfo: createProto(ActuatorInfoSchema, { userCountInIam: 2 }),
+ workspacePolicy: createProto(IamPolicySchema, {
+ bindings: [
+ createProto(BindingSchema, {
+ role: "roles/workspaceMember",
+ members: [user.name, "users/[email protected]"],
+ }),
+ ],
+ }),
+ });
+
+ expect(store.getState().workspaceSetupGuideEnabled(true)).toBe(false);
});
test("disables the workspace setup guide when quick start is hidden", () => {
@@ -2652,7 +2671,7 @@ describe("useAppStore", () => {
key: "workspace-setup-guide.dismissed",
newState: true,
});
- store.getState().resetWorkspaceSetupGuide();
+ store.getState().resumeWorkspaceSetupGuide();
expect(
JSON.parse(
@@ -2671,7 +2690,7 @@ describe("useAppStore", () => {
).toEqual({ "workspace-setup-guide.dismissed": false });
});
- test("resets all workspace setup guide progress", () => {
+ test("resumes the setup guide without clearing progress", () => {
const store = createAppStore();
store.setState({ currentUser: user });
@@ -2684,18 +2703,26 @@ describe("useAppStore", () => {
newState: true,
});
store.getState().saveIntroStateByKey({
- key: "workspace-setup-guide.query-executed",
+ key: "workspace-setup-guide.statement-run",
newState: true,
});
store.getState().saveIntroStateByKey({
key: "workspace-setup-guide.product-model-seen",
newState: true,
});
+ store.getState().saveIntroStateByKey({
+ key: "workspace-setup-guide.completed.query-data",
+ newState: true,
+ });
+ store.getState().saveIntroStateByKey({
+ key: "workspace-setup-guide.started.query-data",
+ newState: true,
+ });
store
.getState()
.saveIntroStateByKey({ key: "unrelated.intro", newState: true });
- store.getState().resetWorkspaceSetupGuide();
+ store.getState().resumeWorkspaceSetupGuide();
expect(
store.getState().getIntroStateByKey("workspace-setup-guide.dismissed")
@@ -2704,17 +2731,25 @@ describe("useAppStore", () => {
store
.getState()
.getIntroStateByKey("workspace-setup-guide.database-explored")
- ).toBe(false);
+ ).toBe(true);
+ expect(
+ store.getState().getIntroStateByKey("workspace-setup-guide.statement-run")
+ ).toBe(true);
expect(
store
.getState()
- .getIntroStateByKey("workspace-setup-guide.query-executed")
- ).toBe(false);
+ .getIntroStateByKey("workspace-setup-guide.product-model-seen")
+ ).toBe(true);
expect(
store
.getState()
- .getIntroStateByKey("workspace-setup-guide.product-model-seen")
+ .getIntroStateByKey("workspace-setup-guide.completed.query-data")
).toBe(false);
+ expect(
+ store
+ .getState()
+ .getIntroStateByKey("workspace-setup-guide.started.query-data")
+ ).toBe(true);
expect(store.getState().getIntroStateByKey("unrelated.intro")).toBe(true);
});
diff --git a/frontend/src/stores/app/preferences.ts b/frontend/src/stores/app/preferences.ts
index 22755e4d14..fe804a204a 100644
--- a/frontend/src/stores/app/preferences.ts
+++ b/frontend/src/stores/app/preferences.ts
@@ -60,17 +60,15 @@ export const createPreferencesSlice: AppSliceCreator<PreferencesSlice> = (
);
},
- resetWorkspaceSetupGuide: () => {
+ resumeWorkspaceSetupGuide: () => {
const email = getCurrentUserEmail(get);
if (!email) return;
const key = storageKeyIntroState(getWorkspaceResourceScope(get), email);
const previous = readJson<Record<string, boolean>>(key, {});
- const next: Record<string, boolean> = {
- ...previous,
- "workspace-setup-guide.dismissed": false,
- };
- for (const introStateKey of Object.keys(next)) {
- if (introStateKey.startsWith("workspace-setup-guide.")) {
+ const next: Record<string, boolean> = { ...previous };
+ next["workspace-setup-guide.dismissed"] = false;
+ for (const introStateKey of Object.keys(previous)) {
+ if (introStateKey.startsWith("workspace-setup-guide.completed.")) {
next[introStateKey] = false;
}
}
diff --git a/frontend/src/stores/app/types.ts b/frontend/src/stores/app/types.ts
index 57c28431a8..d38bbbf376 100644
--- a/frontend/src/stores/app/types.ts
+++ b/frontend/src/stores/app/types.ts
@@ -312,7 +312,7 @@ export type WorkspaceSlice = {
userCountInIam: () => number;
activeVcsUserCount: () => number;
enableOnboarding: () => boolean;
- workspaceSetupGuideEnabled: () => boolean;
+ workspaceSetupGuideEnabled: (allowMultipleMembers?: boolean) => boolean;
// Always returns a profile (never undefined), mirroring the Pinia
// `workspaceProfile` getter so consumers read fields without null checks.
getWorkspaceProfile: () => WorkspaceProfileSetting;
@@ -955,7 +955,7 @@ export type PreferencesSlice = {
setRecentProject: (name: string) => void;
recordRecentVisit: (path: string, workspaceName?: string) => void;
removeRecentVisit: (path: string) => void;
- resetWorkspaceSetupGuide: () => void;
+ resumeWorkspaceSetupGuide: () => void;
getIntroStateByKey: (key: string) => boolean;
saveIntroStateByKey: (params: { key: string; newState: boolean }) => void;
};
diff --git a/frontend/src/stores/app/workspace.ts b/frontend/src/stores/app/workspace.ts
index 4e87c68c63..a75d5fbc63 100644
--- a/frontend/src/stores/app/workspace.ts
+++ b/frontend/src/stores/app/workspace.ts
@@ -689,12 +689,12 @@ export const createWorkspaceSlice: AppSliceCreator<WorkspaceSlice> = (
enableOnboarding: () => get().userCountInIam() === 1,
- workspaceSetupGuideEnabled: () => {
+ workspaceSetupGuideEnabled: (allowMultipleMembers = false) => {
const currentUserName = get().currentUser?.name;
return (
!get().appFeatures["bb.feature.hide-quick-start"] &&
get().workspacePolicy !== undefined &&
- get().userCountInIam() === 1 &&
+ (get().userCountInIam() === 1 || allowMultipleMembers) &&
!!currentUserName &&
get()
.getWorkspaceRolesByName(currentUserName)
diff --git a/frontend/src/utils/storage-keys.ts b/frontend/src/utils/storage-keys.ts
index 5aedb8fa0c..ba20f1268b 100644
--- a/frontend/src/utils/storage-keys.ts
+++ b/frontend/src/utils/storage-keys.ts
@@ -61,6 +61,14 @@ export const storageKeyCollapseState = (email: string) =>
// outlive the server data associated with a workspace id.
export const storageKeyIntroState = (scope: string, email: string) =>
withScope("bb.intro-state", scope, email);
+export const storageKeyWorkspaceSetupGuideScenario = (
+ scope: string,
+ email: string
+) => withScope("bb.workspace-setup-guide.scenario", scope, email);
+export const storageKeyWorkspaceSetupGuideWorkspaceUsage = (
+ scope: string,
+ email: string
+) => withScope("bb.workspace-setup-guide.workspace-usage", scope, email);
// Workspace-scoped: value keys embed project resource names.
export const storageKeyIamRemind = (scope: string, email: string) =>
withScope("bb.iam-remind", scope, email);